feat(v2): draft quiet pod system action line (TASK-406)

backend/__tests__/service/agentSendFreshnessCommitFence.test.js

@@ -85,4 +85,24 @@ d('agent freshness: in-flight PostgreSQL insert', () => {
     }
   });
 
+  it('a trigger-revisioned claim line creates no send hold; ordinary peer chat still does', async () => {
+    const { emitSystemActionLine } = require('../../services/systemActionLineService');
+    await pool.query('DELETE FROM messages WHERE pod_id = $1', [String(podId)]);
+    await Cursor.deleteOne({ _id: `${agentId}:${podId}` });
+    const before = await Freshness.readStart(podId);
+    await Freshness.recordRead(agentId, podId, before, []);
+    await emitSystemActionLine({ podId: String(podId), actorUserId: String(peerId),
+      actorName: 'fence-peer', action: 'task-claimed', taskId: 'TASK-406' });
+    const { rows: [line] } = await pool.query('SELECT freshness_revision FROM messages WHERE pod_id = $1', [String(podId)]);
+    expect(Number(line.freshness_revision)).toBeGreaterThan(before.revision);
+    expect(await Freshness.unseenMessages(agentId, podId)).toBeNull();
+    const after = await Freshness.readStart(podId);
+    await Freshness.recordRead(agentId, podId, after, []);
+    expect((await Cursor.findById(`${agentId}:${podId}`).lean()).readRevision).toBe(after.revision);
+    await pool.query('INSERT INTO messages (pod_id, user_id, content) VALUES ($1, $2, $3)',
+      [String(podId), String(peerId), 'ordinary peer chat']);
+    expect(await Freshness.unseenMessages(agentId, podId)).toMatchObject({ unseenCount: 1,
+      messages: [{ content: 'ordinary peer chat' }] });
+  });
+
 });

backend/__tests__/service/agentSendFreshnessMongoCommitFence.test.js

@@ -28,6 +28,19 @@ describe('agent freshness: delayed Mongo-only write', () => {
     await Cursor.deleteMany({});
   });
 
+  it('ignores claim lines for sends and cursor advancement but still holds ordinary peer chat', async () => {
+    await Message.collection.insertOne({ podId, userId: peerId, content: 'peer claimed TASK-406',
+      messageType: 'system', payload: { kind: 'system-action' }, createdAt: new Date(), freshnessCommittedAt: new Date(), freshnessPending: false });
+    expect(await Freshness.unseenMessages(agentId, podId)).toBeNull();
+    const start = await Freshness.readStart(podId);
+    await Freshness.recordRead(agentId, podId, start, []);
+    expect(await Cursor.findById(`${agentId}:${podId}`).lean()).not.toBeNull();
+    await Message.collection.insertOne({ podId, userId: peerId, content: 'ordinary peer chat',
+      messageType: 'text', createdAt: new Date(), freshnessPending: true });
+    const hold = await Freshness.unseenMessages(agentId, podId);
+    expect(hold).toMatchObject({ unseenCount: 1, messages: [{ content: 'ordinary peer chat' }] });
+  });
+
   it('holds an insert whose createdAt predates a successful read but whose save finishes later', async () => {
     const peerMessage = new Message({
       podId,

backend/__tests__/service/tasks.claim-lease.test.js

@@ -22,10 +22,14 @@ jest.mock('../../services/taskEventService', () => {
   const actual = jest.requireActual('../../services/taskEventService');
   return { ...actual, notifyPodAgents: jest.fn().mockResolvedValue(undefined) };
 });
+jest.mock('../../services/systemActionLineService', () => ({
+  emitSystemActionLine: jest.fn().mockResolvedValue(undefined),
+}));
 
 const express = require('express');
 const request = require('supertest');
 const { notifyPodAgents } = require('../../services/taskEventService');
+const { emitSystemActionLine } = require('../../services/systemActionLineService');
 const Pod = require('../../models/Pod');
 const Task = require('../../models/Task');
 const User = require('../../models/User');
@@ -62,6 +66,7 @@ describe('POST /api/v1/tasks/:podId/:taskId/claim — lease semantics (ADR-018 D
 
   beforeEach(async () => {
     await clearMongoDb();
+    emitSystemActionLine.mockClear();
     owner = await User.create({
       username: `lease-owner-${Date.now()}`,
       email: `lease-owner-${Date.now()}@test.com`,
@@ -81,7 +86,7 @@ describe('POST /api/v1/tasks/:podId/:taskId/claim — lease semantics (ADR-018 D
       verified: true,
       isBot: true,
       botType: 'agent',
-      botMetadata: { agentName: 'claim-audit-agent', instanceId: 'default' },
+      botMetadata: { agentName: 'claim-audit-agent', instanceId: 'default', displayName: 'Audit Agent' },
       agentRuntimeTokens: [{
         tokenHash: hash(AGENT_TOKEN),
         label: 'task-claim-audit',
@@ -134,6 +139,11 @@ describe('POST /api/v1/tasks/:podId/:taskId/claim — lease semantics (ADR-018 D
         authorId: agent._id.toString(),
       }),
     ]));
+    expect(emitSystemActionLine).toHaveBeenCalledWith(expect.objectContaining({
+      actorName: 'Audit Agent',
+      actorUsername: 'claim-audit-agent',
+      actorIsBot: true,
+    }));
   });
 
   test('a fresh claim stamps a lease ~30 minutes out', async () => {
@@ -145,6 +155,16 @@ describe('POST /api/v1/tasks/:podId/:taskId/claim — lease semantics (ADR-018 D
     const expires = new Date(res.body.task.claimExpiresAt).getTime();
     expect(expires).toBeGreaterThanOrEqual(before + LEASE_MS - 5000);
     expect(expires).toBeLessThanOrEqual(Date.now() + LEASE_MS + 5000);
+    expect(emitSystemActionLine).toHaveBeenCalledWith({
+      podId: pod._id.toString(),
+      actorUserId: owner._id.toString(),
+      actorName: owner.username,
+      actorUsername: owner.username,
+      actorAvatarUrl: null,
+      actorIsBot: false,
+      action: 'task-claimed',
+      taskId: 'T-1',
+    });
   });
 
   test('a live lease refuses a rival, naming the holder and when the lease frees', async () => {
@@ -164,6 +184,7 @@ describe('POST /api/v1/tasks/:podId/:taskId/claim — lease semantics (ADR-018 D
     const renewed = await claim(ownerToken);
     expect(renewed.status).toBe(200);
     expect(new Date(renewed.body.task.claimExpiresAt).getTime()).toBeGreaterThan(firstExpiry);
+    expect(emitSystemActionLine).toHaveBeenCalledTimes(1);
   });
 
   test('a lapsed lease is claimable by a peer — dead claimants never hold work forever', async () => {
@@ -176,6 +197,7 @@ describe('POST /api/v1/tasks/:podId/:taskId/claim — lease semantics (ADR-018 D
     const res = await claim(rivalToken);
     expect(res.status).toBe(200);
     expect(res.body.task.claimedBy).toBe(rival._id.toString());
+    expect(emitSystemActionLine).toHaveBeenCalledTimes(1);
   });
 
   test('a RECENT legacy claim (no lease field) is still protected', async () => {

backend/__tests__/unit/models/pg/message.systemActions.test.js

@@ -0,0 +1,15 @@
+jest.mock('../../../../config/db-pg', () => ({ pool: { query: jest.fn() } }));
+const { pool } = require('../../../../config/db-pg');
+const Message = require('../../../../models/pg/Message');
+beforeEach(() => { pool.query.mockReset(); pool.query.mockResolvedValue({ rows: [] }); });
+test('activity exclusion is an SQL predicate before LIMIT', async () => {
+  await Message.findByPodId('pod-1', 1, null, null, { excludeSystemActions: true });
+  const [sql, params] = pool.query.mock.calls[0];
+  expect(sql).toContain("NOT (m.message_type = 'system' AND COALESCE(m.payload->>'kind', '') = 'system-action')");
+  expect(sql.indexOf("= 'system-action'")).toBeLessThan(sql.indexOf('LIMIT'));
+  expect(params).toEqual(['pod-1', 1]);
+});
+test('ordinary pod history still includes system action rows', async () => {
+  await Message.findByPodId('pod-1', 1);
+  expect(pool.query.mock.calls[0][0]).not.toContain("= 'system-action'");
+});

backend/__tests__/unit/services/activityService.agentMessages.test.js

@@ -1,3 +1,5 @@
+jest.mock('../../../models/Message', () => ({ find: jest.fn() }));
+
 jest.mock('../../../models/pg/Message', () => ({ findByPodId: jest.fn() }));
 
 const PGMessage = require('../../../models/pg/Message');
@@ -29,3 +31,16 @@ describe('ActivityService.getMessageActivities', () => {
     })]);
   });
 });
+
+const MongoMessage = require('../../../models/Message');
+test('Activity excludes system action rows before its PG and Mongo fetch limits', async () => {
+  PGMessage.findByPodId.mockResolvedValue([]);
+  const lean = jest.fn().mockResolvedValue([]);
+  const populate = jest.fn().mockReturnValue({ lean });
+  const limit = jest.fn().mockReturnValue({ populate });
+  MongoMessage.find.mockReturnValue({ sort: () => ({ limit }) });
+  await ActivityService.getMessageActivities(['pod-1'], new Map(), { limit: 1 });
+  expect(PGMessage.findByPodId).toHaveBeenCalledWith('pod-1', 1, null, null, { excludeSystemActions: true });
+  expect(MongoMessage.find).toHaveBeenCalledWith({ podId: { $in: ['pod-1'] }, $nor: [{ messageType: 'system', 'payload.kind': 'system-action' }] });
+  expect(limit).toHaveBeenCalledWith(1);
+});

backend/__tests__/unit/services/agentSendFreshness.test.js

@@ -39,6 +39,7 @@ describe('agent send-time freshness', () => {
     expect(hold.message).toContain('continueAnyway:true');
     expect(Message.countDocuments).toHaveBeenCalledWith({
       podId: 'pod-id',
+      $nor: [{ messageType: 'system', 'payload.kind': 'system-action' }],
       $and: [
         { $or: [{ userId: { $ne: 'agent-id' } }, { authorKind: 'kernel' }] },
         { $or: [
@@ -129,4 +130,18 @@ describe('agent send-time freshness', () => {
     expect(pool.query.mock.calls[0][1]).toEqual(['pod-id', 4, 6, 'agent-id', [5, 6]]);
     expect(Cursor.updateOne).toHaveBeenCalledTimes(1);
   });
+
+  it('excludes system actions from both PostgreSQL send holds and omitted-read checks', async () => {
+  jest.clearAllMocks();
+  process.env.PG_HOST = 'configured';
+  pool.query.mockResolvedValue({ rows: [] });
+  await Freshness.unseenMessages('agent-id', 'pod-id');
+  await Freshness.recordRead('agent-id', 'pod-id', { at: new Date(), revision: 10 }, []);
+  expect(pool.query.mock.calls).toHaveLength(2);
+  for (const [sql] of pool.query.mock.calls) {
+    expect(sql).toContain("NOT (m.message_type = 'system' AND COALESCE(m.payload->>'kind', '') = 'system-action')");
+    expect(sql.indexOf("= 'system-action'")).toBeLessThan(sql.indexOf('LIMIT'));
+  }
+});
+
 });

backend/__tests__/unit/services/systemActionLineService.test.js

@@ -0,0 +1,65 @@
+const mockQuery = jest.fn();
+const mockEmit = jest.fn();
+const mockTo = jest.fn(() => ({ emit: mockEmit }));
+
+jest.mock('../../../config/db-pg', () => ({
+  pool: { query: (...args) => mockQuery(...args) },
+}));
+jest.mock('../../../config/socket', () => ({
+  getIO: () => ({ to: mockTo }),
+}));
+
+const { emitSystemActionLine } = require('../../../services/systemActionLineService');
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  mockQuery.mockResolvedValue({ rows: [{ id: 42, created_at: '2026-10-23T20:00:00.000Z' }] });
+});
+
+it('persists one structured system row and broadcasts the same line without a wake or pod touch', async () => {
+  await emitSystemActionLine({
+    podId: 'pod-1', actorUserId: 'user-1', actorName: 'Forge',
+    actorUsername: 'forge-agent', actorAvatarUrl: '/avatars/forge.png', actorIsBot: true,
+    action: 'task-claimed', taskId: 'TASK-406',
+  });
+
+  expect(mockQuery).toHaveBeenCalledTimes(1);
+  const [sql, params] = mockQuery.mock.calls[0];
+  expect(sql).toContain("'system'");
+  expect(sql).not.toMatch(/UPDATE pods|attention|AgentEvent/i);
+  expect(params.slice(0, 3)).toEqual(['pod-1', 'user-1', 'Forge claimed TASK-406']);
+  expect(JSON.parse(params[3])).toEqual({
+    kind: 'system-action', action: 'task-claimed', actorName: 'Forge', taskId: 'TASK-406',
+  });
+  expect(mockTo).toHaveBeenCalledWith('pod_pod-1');
+  expect(mockEmit).toHaveBeenCalledWith('newMessage', expect.objectContaining({
+    id: '42', messageType: 'system', pod_id: 'pod-1',
+    payload: expect.objectContaining({ action: 'task-claimed', taskId: 'TASK-406' }),
+    user: expect.objectContaining({ username: 'forge-agent', profile_picture: '/avatars/forge.png', isBot: true }),
+  }));
+});
+
+it('executes the INSERT and reads the table-generated identity, timestamp and JSON payload back', async () => {
+  const { newDb } = require('pg-mem');
+  const db = newDb();
+  db.public.none(`CREATE TABLE messages (
+    id SERIAL PRIMARY KEY, pod_id TEXT NOT NULL, user_id TEXT NOT NULL,
+    content TEXT NOT NULL, message_type TEXT NOT NULL, payload JSONB,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+  )`);
+  const { Pool } = db.adapters.createPg();
+  const pool = new Pool();
+  mockQuery.mockImplementation((sql, params) => pool.query(sql, params));
+  try {
+    await emitSystemActionLine({ podId: 'pod-1', actorUserId: 'user-1', actorName: 'Persisted Forge', action: 'task-claimed', taskId: 'TASK-406' });
+    const { rows: [row] } = await pool.query('SELECT * FROM messages');
+    expect(row.id).toBe(1);
+    expect(row.created_at).toBeInstanceOf(Date);
+    expect(row.message_type).toBe('system');
+    expect(row.payload).toEqual({ kind: 'system-action', action: 'task-claimed', actorName: 'Persisted Forge', taskId: 'TASK-406' });
+    expect(mockEmit).toHaveBeenCalledWith('newMessage', expect.objectContaining({ id: String(row.id), created_at: row.created_at, payload: row.payload }));
+  } finally {
+    mockQuery.mockReset();
+    await pool.end();
+  }
+});

backend/controllers/podController.ts

@@ -273,6 +273,7 @@ exports.getAllPods = async (req: any, res: any) => {
           FROM messages m
           LEFT JOIN users u ON u._id = m.user_id
           WHERE m.pod_id = ANY($1::text[])
+            AND NOT (m.message_type = 'system' AND COALESCE(m.payload->>'kind', '') = 'system-action')
           ORDER BY m.pod_id, m.created_at DESC
         `;
         const result = await pool.query(sql, [podIds]);

backend/models/pg/Message.ts

@@ -245,6 +245,7 @@ class Message {
     // derivation in create()). This is what makes agent-side thread reads
     // cheaper than paging the whole pod (TASK-052's cue depends on it).
     threadRootId: string | null = null,
+    options: { excludeSystemActions?: boolean } = {},
   ): Promise<FormattedMessage[]> {
     // Defense-in-depth clamp at the data layer: callers should pass a bounded
     // limit, but a stray unbounded value must never turn into a million-row
@@ -270,6 +271,9 @@ class Message {
         WHERE m.pod_id = $1
       `;
       const queryParams: unknown[] = [podId];
+      if (options.excludeSystemActions) {
+        query += " AND NOT (m.message_type = 'system' AND COALESCE(m.payload->>'kind', '') = 'system-action')";
+      }
       if (before) {
         query += ' AND m.created_at < $2';
         queryParams.push(before);

backend/routes/tasksApi.ts

@@ -22,6 +22,10 @@ const AgentSendFreshness = require('../services/agentSendFreshness');
 // eslint-disable-next-line global-require
 const { emitTaskUpdated, notifyPodAgents } = require('../services/taskEventService');
 // eslint-disable-next-line global-require
+const { emitSystemActionLine } = require('../services/systemActionLineService');
+// eslint-disable-next-line global-require
+const { resolveAgentDisplayLabel } = require('../services/agentIdentityService');
+// eslint-disable-next-line global-require
 const { recordTaskAttention, resolveTaskAttention } = require('../services/attentionItemService');
 // eslint-disable-next-line global-require
 const { parseAssignee, toSingleLineTitle } = require('../utils/taskFieldNormalization');
@@ -78,11 +82,11 @@ interface AuthReq {
   // `username` is here because the sweep can write it into `lapsedFrom`
   // (provenance falls back through holder.label = assignee || username ||
   // claimedBy), so the restore path must be able to match on it.
-  user?: { id?: string; _id?: unknown; isBot?: boolean; username?: string; botMetadata?: { instanceId?: string; agentName?: string } };
+  user?: { id?: string; _id?: unknown; isBot?: boolean; username?: string; profilePicture?: string; botMetadata?: { displayName?: string; instanceId?: string; agentName?: string } };
   // Same reason as `user.username` above: `agentRuntimeAuth` puts the bot's
   // User row here, and its username is what the sweep writes into
   // `lapsedFrom` for an agent holder.
-  agentUser?: { _id?: unknown; username?: string };
+  agentUser?: { _id?: unknown; username?: string; profilePicture?: string; isBot?: boolean; botMetadata?: { displayName?: string; instanceId?: string; agentName?: string } };
   params?: Record<string, string>;
   query?: Record<string, string>;
   body?: Record<string, unknown>;
@@ -690,6 +694,22 @@ router.post('/:podId/:taskId/claim', rateLimit({
       && (preClaim.claimedBy === claimedBy || preClaim.lapsedFrom === claimedBy);
     if (!isSameHolderContinuation) {
       notifyAgents(req, podId, task, 'updated', preClaim);
+      const actorUser = req.agentUser || req.user;
+      const actorName = actorUser?.isBot
+        ? resolveAgentDisplayLabel(actorUser, author)
+        : actorUser?.username || author;
+      // The claim CAS has committed. This quiet timeline projection is
+      // best-effort and never changes the claim's HTTP result.
+      void emitSystemActionLine({
+        podId: String(podId),
+        actorUserId: String(userId),
+        actorName,
+        actorUsername: actorUser?.username || author,
+        actorAvatarUrl: actorUser?.profilePicture || null,
+        actorIsBot: !!actorUser?.isBot,
+        action: 'task-claimed',
+        taskId: String(task.taskId || taskId),
+      }).catch((error: Error) => console.warn('[tasks] system action line failed:', error.message));
     }
     return res.json({ task });
   } catch (err) {

backend/services/activityService.ts

@@ -368,7 +368,10 @@ class ActivityService {
       // recap still commonly-bot-only because the working pods still never
       // made the fetch window).
       const { rows } = await pool.query(
-        'SELECT pod_id, MAX(created_at) AS latest FROM messages WHERE pod_id = ANY($1::text[]) GROUP BY pod_id ORDER BY latest DESC',
+        `SELECT pod_id, MAX(created_at) AS latest FROM messages
+         WHERE pod_id = ANY($1::text[])
+           AND NOT (message_type = 'system' AND COALESCE(payload->>'kind', '') = 'system-action')
+         GROUP BY pod_id ORDER BY latest DESC`,
         [ids],
       );
       const ranked = rows.map((r) => String(r.pod_id));
@@ -716,7 +719,13 @@ class ActivityService {
           // the vacuum. (Verified live: findByPodId(oid) -> 0 rows,
           // findByPodId(String(oid)) -> rows.)
           const podMessagesList = await Promise.all(
-            podIds.slice(0, 12).map((podId) => (PGMessage as { findByPodId(id: unknown, limit: number): Promise<unknown[]> }).findByPodId(String(podId), limit)),
+            podIds.slice(0, 12).map((podId) => (PGMessage as {
+              findByPodId(
+                id: unknown, count: number, cursor: string | null, thread: string | null,
+                queryOptions: { excludeSystemActions: boolean },
+              ): Promise<unknown[]>;
+            })
+              .findByPodId(String(podId), limit, before || null, null, { excludeSystemActions: true })),
           );
           messages = podMessagesList.flat() as Array<Record<string, unknown>>;
         } catch (e) {
@@ -725,7 +734,10 @@ class ActivityService {
       }
 
       if (messages.length === 0 && Message) {
-        const query: Record<string, unknown> = { podId: { $in: podIds } };
+        const query: Record<string, unknown> = {
+          podId: { $in: podIds },
+          $nor: [{ messageType: 'system', 'payload.kind': 'system-action' }],
+        };
         if (before) {
           query.createdAt = { $lt: new Date(before) };
         }