@openparachute/agent 0.1.0 → 0.1.2

package/src/secrets/secrets.test.ts

@@ -11,6 +11,7 @@ import {
   getSecret,
   getSecretById,
   listAssignments,
+  listInjectableSecretsForGroup,
   listSecrets,
   putSecret,
   removeAssignment,
@@ -108,17 +109,21 @@ describe('secrets store', () => {
     expect(env.get('B')).toBe('scoped-B');
   });
 
-  it('mode=selective injects nothing without explicit assignments', () => {
+  it('mode=selective hides unassigned globals, but scoped secrets are auto-seeded into the owner', () => {
     const db = initTestDb();
     runMigrations(db);
     _setMasterKeyForTest(crypto.randomBytes(32));
     seedAgentGroup(db, 'g1', 'selective');
 
-    putSecret('GLOBAL', 'value');
-    putSecret('SCOPED', 'value', { agent_group_id: 'g1' });
+    // Unassigned global → invisible under selective mode.
+    putSecret('GLOBAL', 'global-v');
+    // Scoped secret → putSecret auto-seeds the (id, g1) assignment row, so
+    // the resolver injects it even under selective mode (paraclaw#127).
+    putSecret('SCOPED', 'scoped-v', { agent_group_id: 'g1' });
 
     const env = resolveInjectableSecrets('g1');
-    expect(env.size).toBe(0);
+    expect([...env.keys()]).toEqual(['SCOPED']);
+    expect(env.get('SCOPED')).toBe('scoped-v');
   });
 
   it('unknown agent_group_id resolves as no-secrets (selective default)', () => {
@@ -127,6 +132,112 @@ describe('secrets store', () => {
   });
 });
 
+describe('putSecret auto-seeds the owner assignment for scoped creates (paraclaw#127)', () => {
+  /**
+   * The default `agent_groups.secret_mode` is `selective` (migration 023).
+   * Before the auto-seed, calling `putSecret(name, value, { agent_group_id })`
+   * inserted a `secrets` row but never the matching `secret_assignments` row,
+   * leaving the secret silently invisible to `resolveInjectableSecrets` —
+   * the row predicate `(s.agent_group_id = g.id OR s.agent_group_id IS NULL)`
+   * matches but the gate `(g.secret_mode='all' OR a.secret_id IS NOT NULL)`
+   * rejects. UI layers had a follow-up `setSecretAssignments` that papered
+   * over this on edits, but the create-side `CredentialForm` "free" mode
+   * called only `putSecret` — so the standard "+ New secret" flow produced
+   * orphan rows.
+   *
+   * Fix: `putSecret` writes the (id, owning_group) assignment row in the
+   * same transaction on INSERT. UPDATE/rotate leaves the assignment set
+   * alone (operator may have deliberately revoked).
+   */
+
+  it('scoped create writes a matching secret_assignments row', () => {
+    const db = initTestDb();
+    runMigrations(db);
+    _setMasterKeyForTest(crypto.randomBytes(32));
+    seedAgentGroup(db, 'A', 'selective');
+
+    const id = putSecret('TOKEN', 'v', { agent_group_id: 'A' });
+
+    expect(listAssignments(id)).toEqual(['A']);
+  });
+
+  it('scoped create in selective mode is visible via resolveInjectableSecrets without an explicit assign call', () => {
+    const db = initTestDb();
+    runMigrations(db);
+    _setMasterKeyForTest(crypto.randomBytes(32));
+    seedAgentGroup(db, 'A', 'selective');
+
+    putSecret('TOKEN', 'scoped-v', { agent_group_id: 'A' });
+
+    expect(resolveInjectableSecrets('A').get('TOKEN')).toBe('scoped-v');
+  });
+
+  it('scoped create in selective mode is visible via listInjectableSecretsForGroup, tagged scope=scoped', () => {
+    const db = initTestDb();
+    runMigrations(db);
+    _setMasterKeyForTest(crypto.randomBytes(32));
+    seedAgentGroup(db, 'A', 'selective');
+
+    putSecret('TOKEN', 'scoped-v', { agent_group_id: 'A' });
+
+    const rows = listInjectableSecretsForGroup('A');
+    expect(rows).toHaveLength(1);
+    expect(rows[0].name).toBe('TOKEN');
+    expect(rows[0].scope).toBe('scoped');
+  });
+
+  it('global create does NOT write any secret_assignments row', () => {
+    const db = initTestDb();
+    runMigrations(db);
+    _setMasterKeyForTest(crypto.randomBytes(32));
+
+    const id = putSecret('GLOBAL_TOKEN', 'v');
+
+    expect(listAssignments(id)).toEqual([]);
+    const total = db.prepare<{ n: number }>(`SELECT COUNT(*) AS n FROM secret_assignments`).get();
+    expect(total?.n).toBe(0);
+  });
+
+  it('rotate (UPDATE path) does NOT touch the assignment set', () => {
+    // Operator may have deliberately revoked the auto-seeded assignment —
+    // a rotate must not re-seed it. The auto-seed is INSERT-only.
+    const db = initTestDb();
+    runMigrations(db);
+    _setMasterKeyForTest(crypto.randomBytes(32));
+    seedAgentGroup(db, 'A', 'selective');
+
+    const id = putSecret('TOKEN', 'v1', { agent_group_id: 'A' });
+    expect(listAssignments(id)).toEqual(['A']);
+
+    // Operator revokes.
+    removeAssignment(id, 'A');
+    expect(listAssignments(id)).toEqual([]);
+
+    // Rotate plaintext — assignment set stays empty.
+    const id2 = putSecret('TOKEN', 'v2', { agent_group_id: 'A' });
+    expect(id2).toBe(id);
+    expect(listAssignments(id)).toEqual([]);
+  });
+
+  it('two scoped creates with different owners each seed their own row', () => {
+    const db = initTestDb();
+    runMigrations(db);
+    _setMasterKeyForTest(crypto.randomBytes(32));
+    seedAgentGroup(db, 'A', 'selective');
+    seedAgentGroup(db, 'B', 'selective');
+
+    const aId = putSecret('TOKEN', 'va', { agent_group_id: 'A' });
+    const bId = putSecret('TOKEN', 'vb', { agent_group_id: 'B' });
+
+    expect(aId).not.toBe(bId);
+    expect(listAssignments(aId)).toEqual(['A']);
+    expect(listAssignments(bId)).toEqual(['B']);
+    // Each scoped create is visible only in its own group, never across.
+    expect(resolveInjectableSecrets('A').get('TOKEN')).toBe('va');
+    expect(resolveInjectableSecrets('B').get('TOKEN')).toBe('vb');
+  });
+});
+
 describe('secret assignments (selective mode)', () => {
   it('round-trips: assignment to A injects into A, not B', () => {
     const db = initTestDb();
@@ -352,3 +463,189 @@ describe('getSecretById', () => {
     expect(getSecretById('does-not-exist')).toBeUndefined();
   });
 });
+
+describe('listInjectableSecretsForGroup', () => {
+  it('tags scoped, assigned, and global rows correctly', () => {
+    const db = initTestDb();
+    runMigrations(db);
+    _setMasterKeyForTest(crypto.randomBytes(32));
+    seedAgentGroup(db, 'A', 'all');
+
+    // Three inclusion paths:
+    //   SCOPED   — owned by group A
+    //   ASSIGNED — global, with explicit assignment row → A
+    //   GLOBAL   — global, included only because A is mode='all'
+    const scopedId = putSecret('SCOPED_TOKEN', 'v', { agent_group_id: 'A' });
+    const assignedId = putSecret('ASSIGNED_TOKEN', 'v');
+    addAssignment(assignedId, 'A');
+    const globalId = putSecret('GLOBAL_TOKEN', 'v');
+
+    const rows = listInjectableSecretsForGroup('A');
+    const byName = new Map(rows.map((r) => [r.name, r]));
+
+    expect(byName.get('SCOPED_TOKEN')?.scope).toBe('scoped');
+    expect(byName.get('SCOPED_TOKEN')?.id).toBe(scopedId);
+    expect(byName.get('ASSIGNED_TOKEN')?.scope).toBe('assigned');
+    expect(byName.get('ASSIGNED_TOKEN')?.id).toBe(assignedId);
+    expect(byName.get('GLOBAL_TOKEN')?.scope).toBe('global');
+    expect(byName.get('GLOBAL_TOKEN')?.id).toBe(globalId);
+  });
+
+  it('selective mode hides globals that have no assignment row', () => {
+    const db = initTestDb();
+    runMigrations(db);
+    _setMasterKeyForTest(crypto.randomBytes(32));
+    seedAgentGroup(db, 'A', 'selective');
+
+    putSecret('UNREACHABLE_GLOBAL', 'v');
+    const assignedId = putSecret('ASSIGNED', 'v');
+    addAssignment(assignedId, 'A');
+
+    const rows = listInjectableSecretsForGroup('A');
+    expect(rows.map((r) => r.name).sort()).toEqual(['ASSIGNED']);
+    expect(rows[0].scope).toBe('assigned');
+  });
+
+  it('assignment row + mode=all → assigned wins (more specific wins)', () => {
+    const db = initTestDb();
+    runMigrations(db);
+    _setMasterKeyForTest(crypto.randomBytes(32));
+    seedAgentGroup(db, 'A', 'all');
+
+    const id = putSecret('SHARED', 'v');
+    addAssignment(id, 'A');
+
+    const rows = listInjectableSecretsForGroup('A');
+    expect(rows).toHaveLength(1);
+    expect(rows[0].scope).toBe('assigned');
+  });
+
+  it('on name collision, scoped row wins and reports scope=scoped', () => {
+    const db = initTestDb();
+    runMigrations(db);
+    _setMasterKeyForTest(crypto.randomBytes(32));
+    seedAgentGroup(db, 'A', 'all');
+
+    putSecret('TOKEN', 'global-v');
+    putSecret('TOKEN', 'scoped-v', { agent_group_id: 'A' });
+
+    const rows = listInjectableSecretsForGroup('A');
+    expect(rows).toHaveLength(1);
+    expect(rows[0].name).toBe('TOKEN');
+    expect(rows[0].scope).toBe('scoped');
+  });
+
+  it('returns an empty list for an unknown agent group', () => {
+    putSecret('GLOBAL', 'v');
+    expect(listInjectableSecretsForGroup('does-not-exist')).toEqual([]);
+  });
+
+  it('never carries the encrypted value', () => {
+    const db = initTestDb();
+    runMigrations(db);
+    _setMasterKeyForTest(crypto.randomBytes(32));
+    seedAgentGroup(db, 'A', 'all');
+    putSecret('K', 'super-secret');
+    const rows = listInjectableSecretsForGroup('A');
+    expect(rows[0]).not.toHaveProperty('value_encrypted');
+  });
+});
+
+describe('resolveInjectableSecrets ↔ listInjectableSecretsForGroup lockstep (paraclaw#129)', () => {
+  /**
+   * Mechanical guard against drift between the two SQL-identical functions in
+   * src/secrets/index.ts. Both walk identical row predicates + gate clauses;
+   * any future SQL edit must touch both. Today the invariant is preserved by
+   * careful reading + a load-bearing doc-comment. This block tests it.
+   *
+   * For each fixture, calls both functions and asserts:
+   *   - same set of names (the row gate matches)
+   *   - per-name plaintext from resolveInjectableSecrets matches the value
+   *     getSecret returns when scoped to the same group (the dedup-by-name
+   *     `ORDER BY s.agent_group_id IS NULL` scoped-wins ordering matches)
+   *
+   * If a future SQL change makes one function accept a row the other rejects,
+   * the name-set assertion fails. If the ORDER BY drifts so dedup picks the
+   * wrong row on collision, the per-name plaintext assertion fails.
+   */
+  function expectLockstep(agentGroupId: string, expectedNames: string[]): void {
+    const resolved = resolveInjectableSecrets(agentGroupId);
+    const listed = listInjectableSecretsForGroup(agentGroupId);
+
+    const sortedExpected = expectedNames.slice().sort();
+    expect([...resolved.keys()].sort()).toEqual(sortedExpected);
+    expect(listed.map((r) => r.name).sort()).toEqual(sortedExpected);
+
+    for (const view of listed) {
+      expect(resolved.get(view.name)).toBe(getSecret(view.name, agentGroupId));
+    }
+  }
+
+  it('rich mix: scoped+all + global+assigned + global+mode=all + name collision', () => {
+    const db = initTestDb();
+    runMigrations(db);
+    _setMasterKeyForTest(crypto.randomBytes(32));
+    seedAgentGroup(db, 'A', 'all');
+
+    putSecret('SCOPED_ONLY', 'sv', { agent_group_id: 'A' });
+    const assignedId = putSecret('GLOBAL_ASSIGNED', 'gv-assigned');
+    addAssignment(assignedId, 'A');
+    putSecret('GLOBAL_MODE_ALL', 'gv-mode-all');
+    putSecret('TOKEN', 'global-token');
+    putSecret('TOKEN', 'scoped-token', { agent_group_id: 'A' });
+
+    expectLockstep('A', ['SCOPED_ONLY', 'GLOBAL_ASSIGNED', 'GLOBAL_MODE_ALL', 'TOKEN']);
+
+    // Spot-check the collision picked the scoped row in BOTH views.
+    expect(resolveInjectableSecrets('A').get('TOKEN')).toBe('scoped-token');
+    expect(listInjectableSecretsForGroup('A').find((r) => r.name === 'TOKEN')?.scope).toBe('scoped');
+  });
+
+  it('mode=selective: mixed reachable + unreachable globals + scoped-with-assignment', () => {
+    const db = initTestDb();
+    runMigrations(db);
+    _setMasterKeyForTest(crypto.randomBytes(32));
+    seedAgentGroup(db, 'B', 'selective');
+
+    putSecret('UNREACHABLE_GLOBAL', 'gv'); // mode=selective + no assignment → excluded
+    const reachableId = putSecret('REACHABLE', 'gv2');
+    addAssignment(reachableId, 'B');
+    const scopedAssignedId = putSecret('SCOPED_AND_ASSIGNED', 'sv', { agent_group_id: 'B' });
+    addAssignment(scopedAssignedId, 'B');
+
+    expectLockstep('B', ['REACHABLE', 'SCOPED_AND_ASSIGNED']);
+  });
+
+  it('orphaned-scoped (selective + scoped + no assignment): both exclude', () => {
+    // The "structurally unreachable via putSecret" config — selective mode +
+    // scoped secret + no assignment row. paraclaw#127 closed the create path
+    // (putSecret auto-seeds the matching assignment), so to exercise the
+    // shared gate `(g.secret_mode='all' OR a.secret_id IS NOT NULL)` we
+    // construct the orphan directly. If a future SQL change makes one of the
+    // two functions accept it, this catches the drift.
+    const db = initTestDb();
+    runMigrations(db);
+    _setMasterKeyForTest(crypto.randomBytes(32));
+    seedAgentGroup(db, 'C', 'selective');
+
+    db.prepare(
+      `INSERT INTO secrets (id, name, value_encrypted, kind, agent_group_id, created_at, updated_at)
+         VALUES ('orphan-id', 'ORPHAN', 'ct', 'generic', 'C', datetime('now'), datetime('now'))`,
+    ).run();
+
+    expectLockstep('C', []);
+  });
+
+  it('unknown agent_group_id: both return empty (selective default)', () => {
+    putSecret('GLOBAL', 'v');
+    expectLockstep('does-not-exist', []);
+  });
+
+  it('empty secret store + mode=all: both return empty', () => {
+    const db = initTestDb();
+    runMigrations(db);
+    _setMasterKeyForTest(crypto.randomBytes(32));
+    seedAgentGroup(db, 'D', 'all');
+    expectLockstep('D', []);
+  });
+});

package/src/session-manager.attachments.test.ts

@@ -0,0 +1,171 @@
+/**
+ * Regression coverage for paraclaw#96 — silent file clobber on mutated
+ * replays. After paraclaw#92 / #95 made duplicate-dispatch
+ * (sender-approval replay etc.) a warm path, the attachment-extraction
+ * step in writeSessionMessage must run only AFTER the row commits, or a
+ * mutated replay rewrites the on-disk file under the original
+ * messages_in.id while the DB row stays unchanged.
+ *
+ * Real session DBs (no execSync mock) — file-clobber-class hazards are
+ * easy to fake green with mocked filesystem state.
+ */
+import fs from 'fs';
+import path from 'path';
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+
+import { openDb } from './db/connection.js';
+import { initTestDb, closeDb, runMigrations, createAgentGroup } from './db/index.js';
+import { initSessionFolder, inboundDbPath, sessionDir, writeSessionMessage } from './session-manager.js';
+
+vi.mock('./config.js', async () => {
+  const actual = await vi.importActual('./config.js');
+  return { ...actual, DATA_DIR: '/tmp/paraclaw-test-attachments' };
+});
+
+const TEST_DIR = '/tmp/paraclaw-test-attachments';
+const AG = 'ag-1';
+const SESS = 'sess-attachments';
+
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
+function readRowContent(): string {
+  const db = openDb(inboundDbPath(AG, SESS));
+  const row = db.prepare('SELECT content FROM messages_in WHERE id = ?').get('msg-1') as { content: string };
+  db.close();
+  return row.content;
+}
+
+function inboxFilePath(filename: string): string {
+  return path.join(sessionDir(AG, SESS), 'inbox', 'msg-1', filename);
+}
+
+function makeMessageWithAttachment(dataB64: string) {
+  return {
+    id: 'msg-1',
+    kind: 'chat',
+    timestamp: nowIso(),
+    platformId: 'chan-1',
+    channelType: 'discord',
+    threadId: null as string | null,
+    content: JSON.stringify({
+      text: 'see attachment',
+      attachments: [{ name: 'photo.jpg', type: 'image', size: 9, data: dataB64 }],
+    }),
+  };
+}
+
+const ORIGINAL_BYTES = Buffer.from('first-pic');
+const MUTATED_BYTES = Buffer.from('CLOBBERED');
+
+beforeEach(() => {
+  if (fs.existsSync(TEST_DIR)) fs.rmSync(TEST_DIR, { recursive: true });
+  fs.mkdirSync(TEST_DIR, { recursive: true });
+
+  const db = initTestDb();
+  runMigrations(db);
+
+  createAgentGroup({
+    id: AG,
+    name: 'Test Agent',
+    folder: 'test-agent',
+    agent_provider: null,
+    created_at: nowIso(),
+  });
+  // Fresh-start a session manually — we don't need a messaging group for
+  // these tests, just the session folder + DBs.
+  const sessRow = {
+    id: SESS,
+    agent_group_id: AG,
+    messaging_group_id: null,
+    thread_id: null,
+    agent_provider: null,
+    status: 'active' as const,
+    container_status: 'stopped' as const,
+    last_active: null,
+    created_at: nowIso(),
+  };
+  db.prepare(
+    `INSERT INTO sessions (id, agent_group_id, messaging_group_id, thread_id, agent_provider,
+       status, container_status, last_active, created_at)
+     VALUES (@id, @agent_group_id, @messaging_group_id, @thread_id, @agent_provider,
+       @status, @container_status, @last_active, @created_at)`,
+  ).run(sessRow);
+  initSessionFolder(AG, SESS);
+});
+
+afterEach(() => {
+  closeDb();
+  if (fs.existsSync(TEST_DIR)) fs.rmSync(TEST_DIR, { recursive: true });
+});
+
+describe('writeSessionMessage — attachment extraction order (paraclaw#96)', () => {
+  it('fresh insert with attachment: row content has localPath, file written to inbox', () => {
+    writeSessionMessage(AG, SESS, makeMessageWithAttachment(ORIGINAL_BYTES.toString('base64')));
+
+    const parsed = JSON.parse(readRowContent());
+    expect(parsed.attachments).toHaveLength(1);
+    expect(parsed.attachments[0].localPath).toBe('inbox/msg-1/photo.jpg');
+    expect(parsed.attachments[0].data).toBeUndefined();
+
+    const onDisk = fs.readFileSync(inboxFilePath('photo.jpg'));
+    expect(onDisk.equals(ORIGINAL_BYTES)).toBe(true);
+  });
+
+  it('fresh insert without attachments: row content unchanged, no inbox dir created', () => {
+    writeSessionMessage(AG, SESS, {
+      id: 'msg-1',
+      kind: 'chat',
+      timestamp: nowIso(),
+      content: JSON.stringify({ text: 'no attachments here' }),
+    });
+
+    expect(JSON.parse(readRowContent()).text).toBe('no attachments here');
+    expect(fs.existsSync(path.join(sessionDir(AG, SESS), 'inbox'))).toBe(false);
+  });
+
+  it('duplicate dispatch with identical bytes: silently absorbed, file untouched', () => {
+    const msg = makeMessageWithAttachment(ORIGINAL_BYTES.toString('base64'));
+
+    writeSessionMessage(AG, SESS, msg);
+    const firstMtime = fs.statSync(inboxFilePath('photo.jpg')).mtimeMs;
+
+    // Sleep just enough to make a re-write detectable in mtime resolution.
+    const wait = Date.now() + 20;
+    while (Date.now() < wait) {
+      /* spin */
+    }
+
+    writeSessionMessage(AG, SESS, msg);
+
+    // File was NOT re-written — mtime unchanged.
+    expect(fs.statSync(inboxFilePath('photo.jpg')).mtimeMs).toBe(firstMtime);
+    expect(fs.readFileSync(inboxFilePath('photo.jpg')).equals(ORIGINAL_BYTES)).toBe(true);
+  });
+
+  it('duplicate dispatch with MUTATED bytes (replay hazard): on-disk file preserved byte-for-byte', () => {
+    // The exact failure shape paraclaw#96 calls out: a replay that re-uses
+    // the same messages_in.id but carries different attachment bytes. Pre-fix,
+    // the second call's extractAttachmentFiles ran before the dup-check and
+    // would have overwritten photo.jpg with MUTATED_BYTES while the DB row
+    // still pointed at the original commit.
+    writeSessionMessage(AG, SESS, makeMessageWithAttachment(ORIGINAL_BYTES.toString('base64')));
+    const rowAfterFirst = readRowContent();
+
+    writeSessionMessage(AG, SESS, makeMessageWithAttachment(MUTATED_BYTES.toString('base64')));
+
+    // 1. On-disk file is byte-for-byte the original — NO clobber.
+    const onDisk = fs.readFileSync(inboxFilePath('photo.jpg'));
+    expect(onDisk.equals(ORIGINAL_BYTES)).toBe(true);
+    expect(onDisk.equals(MUTATED_BYTES)).toBe(false);
+
+    // 2. Only the original row exists; the replay didn't slip a new row in.
+    const db = openDb(inboundDbPath(AG, SESS));
+    const rows = db.prepare('SELECT id, content FROM messages_in').all() as Array<{ id: string; content: string }>;
+    db.close();
+    expect(rows).toHaveLength(1);
+    expect(rows[0].content).toBe(rowAfterFirst);
+  });
+});

package/src/session-manager.dup-skip.test.ts

@@ -0,0 +1,173 @@
+/**
+ * Integration coverage for paraclaw#97 — writeSessionMessage's dup-skip
+ * side effects beyond the SQL-layer assertions in #95.
+ *
+ * After paraclaw#92 / #95, ON CONFLICT(id) DO NOTHING absorbs the second
+ * INSERT, and writeSessionMessage gates two side effects on inserted=true:
+ *   1. session.last_active is NOT bumped on the dup
+ *   2. extractAttachmentFiles never runs (paraclaw#96 / #120)
+ *   3. A debug log fires so drops are observable
+ *
+ * The session-manager.attachments.test.ts file already covers #2 with
+ * sequential pairs. This file adds the integration-level invariants the
+ * issue calls out as still untested at the writeSessionMessage layer:
+ * last_active discipline, debug log shape, and dup-skip behavior under
+ * realistic dispatcher pressure (Promise.all'd same-id calls).
+ *
+ * Real session DBs + real fs — last_active and file invariants are the
+ * kind that mocks can fake green.
+ */
+import fs from 'fs';
+import path from 'path';
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+
+import { openDb } from './db/connection.js';
+import { initTestDb, closeDb, runMigrations, createAgentGroup, getSession } from './db/index.js';
+import { log } from './log.js';
+import { initSessionFolder, inboundDbPath, sessionDir, writeSessionMessage } from './session-manager.js';
+
+vi.mock('./config.js', async () => {
+  const actual = await vi.importActual('./config.js');
+  return { ...actual, DATA_DIR: '/tmp/paraclaw-test-dup-skip' };
+});
+
+const TEST_DIR = '/tmp/paraclaw-test-dup-skip';
+const AG = 'ag-1';
+const SESS = 'sess-dup';
+
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
+function rowsInMessagesIn(): Array<{ id: string }> {
+  const db = openDb(inboundDbPath(AG, SESS));
+  const rows = db.prepare('SELECT id FROM messages_in').all() as Array<{ id: string }>;
+  db.close();
+  return rows;
+}
+
+function makeMessage(id: string) {
+  return {
+    id,
+    kind: 'chat',
+    timestamp: nowIso(),
+    platformId: 'chan-1',
+    channelType: 'discord',
+    threadId: null as string | null,
+    content: JSON.stringify({
+      text: 'hello',
+      attachments: [{ name: 'doc.bin', type: 'file', size: 4, data: Buffer.from('aaaa').toString('base64') }],
+    }),
+  };
+}
+
+beforeEach(() => {
+  if (fs.existsSync(TEST_DIR)) fs.rmSync(TEST_DIR, { recursive: true });
+  fs.mkdirSync(TEST_DIR, { recursive: true });
+
+  const db = initTestDb();
+  runMigrations(db);
+
+  createAgentGroup({
+    id: AG,
+    name: 'Test Agent',
+    folder: 'test-agent',
+    agent_provider: null,
+    created_at: nowIso(),
+  });
+  db.prepare(
+    `INSERT INTO sessions (id, agent_group_id, messaging_group_id, thread_id, agent_provider,
+       status, container_status, last_active, created_at)
+     VALUES (@id, @agent_group_id, @messaging_group_id, @thread_id, @agent_provider,
+       @status, @container_status, @last_active, @created_at)`,
+  ).run({
+    id: SESS,
+    agent_group_id: AG,
+    messaging_group_id: null,
+    thread_id: null,
+    agent_provider: null,
+    status: 'active' as const,
+    container_status: 'stopped' as const,
+    last_active: null,
+    created_at: nowIso(),
+  });
+  initSessionFolder(AG, SESS);
+});
+
+afterEach(() => {
+  closeDb();
+  if (fs.existsSync(TEST_DIR)) fs.rmSync(TEST_DIR, { recursive: true });
+  vi.restoreAllMocks();
+});
+
+describe('writeSessionMessage — dup-skip side effects (paraclaw#97)', () => {
+  it('does NOT bump session.last_active on a duplicate dispatch', async () => {
+    writeSessionMessage(AG, SESS, makeMessage('msg-1'));
+
+    const firstActive = getSession(SESS)!.last_active;
+    expect(firstActive).not.toBeNull();
+
+    // Sleep enough for any new ISO timestamp to differ from the first.
+    await new Promise((r) => setTimeout(r, 25));
+
+    writeSessionMessage(AG, SESS, makeMessage('msg-1'));
+
+    const secondActive = getSession(SESS)!.last_active;
+    expect(secondActive).toBe(firstActive);
+
+    expect(rowsInMessagesIn()).toHaveLength(1);
+  });
+
+  it('emits a debug log on dup-skip with the expected payload', () => {
+    const debugSpy = vi.spyOn(log, 'debug');
+
+    writeSessionMessage(AG, SESS, makeMessage('msg-2'));
+    writeSessionMessage(AG, SESS, makeMessage('msg-2'));
+
+    const dupCalls = debugSpy.mock.calls.filter(
+      ([msg]) => typeof msg === 'string' && msg.includes('messages_in id already present'),
+    );
+    expect(dupCalls).toHaveLength(1);
+
+    const [, fields] = dupCalls[0]!;
+    expect(fields).toMatchObject({
+      agentGroupId: AG,
+      sessionId: SESS,
+      messageId: 'msg-2',
+    });
+  });
+
+  it('absorbs N near-concurrent same-id dispatches: one row, one file, no spurious sibling files', async () => {
+    // Promise.all-style dispatcher pressure. better-sqlite3 is synchronous so
+    // these serialize on the event loop, but the test shape captures what a
+    // future async refactor would have to preserve: same-id calls collapse
+    // to a single row + a single attachment file regardless of fan-in.
+    const calls = Array.from({ length: 6 }, () => writeSessionMessage(AG, SESS, makeMessage('msg-burst')));
+    await Promise.all(calls);
+
+    expect(rowsInMessagesIn()).toHaveLength(1);
+
+    const inboxDir = path.join(sessionDir(AG, SESS), 'inbox', 'msg-burst');
+    expect(fs.existsSync(inboxDir)).toBe(true);
+    const files = fs.readdirSync(inboxDir);
+    expect(files).toEqual(['doc.bin']);
+  });
+
+  it('different ids in the same burst all land — dup-skip is keyed on id, not on burst', async () => {
+    // Sanity check that the dup-skip absorption is NOT overly broad — distinct
+    // messages_in.id values still get their own rows + their own inbox dirs.
+    await Promise.all([
+      writeSessionMessage(AG, SESS, makeMessage('msg-a')),
+      writeSessionMessage(AG, SESS, makeMessage('msg-b')),
+      writeSessionMessage(AG, SESS, makeMessage('msg-c')),
+    ]);
+
+    const ids = rowsInMessagesIn()
+      .map((r) => r.id)
+      .sort();
+    expect(ids).toEqual(['msg-a', 'msg-b', 'msg-c']);
+
+    expect(fs.readdirSync(path.join(sessionDir(AG, SESS), 'inbox')).sort()).toEqual(['msg-a', 'msg-b', 'msg-c']);
+  });
+});