feat(g6): tighten protocol-router to identity-only contracts

Wish #175 retire-session-names-id-only Group 6.

- findSpawnTemplate(worker) — drops recipientId param; matches templates on
  (worker.team, worker.role) only. Returns null when worker is null or
  missing team/role; caller surfaces "unknown agent" rather than guessing.
- cleanupDeadWorkers(agentId) — collapses to a single registry.get(id) +
  isPaneAlive check. Role/team fuzz removed; caller resolves at the CLI
  boundary.
- resolveResumeSessionId(worker, template) — requires non-null worker with
  a canonical id. Drops the dir:\${recipientId} fallback for null workers
  (master persistence still works via the dir:<name> id-shape on the
  worker row itself).
- ensureWorkerAlive bails early when worker is null after live-fuzzy
  match misses; lockedSpawnWorker only cleans up the worker.id it owns.
- Tests: replace the master-aware-fallback fixture set with identity-only
  contracts (dir:<name> id on a worker row, null-worker rejection,
  non-claude provider, regression guard for live worker.id) plus a new
  G6 contract test that recipient-name without a worker no longer
  triggers an auto-spawn.

Validation: bun test src/lib/protocol-router.test.ts
src/lib/protocol-router-spawn.test.ts → 10 pass / 51 skip / 0 fail
(existing describe.skip pending #175 G3 fixture migration).

Author: namastex888

src/lib/protocol-router.test.ts

@@ -844,31 +844,13 @@ describe.skip('pg — TODO retire-session-names #175: rewrite fixtures for UUID
   });
 
   // ---------------------------------------------------------------------------
-  // Master-aware resume (Group 1, master-aware-spawn wish):
-  // resolveResumeSessionId must probe `dir:<recipientId>` when worker == null.
+  // resolveResumeSessionId — identity-only contract (wish #175 G6)
+  // Caller resolves name → id at the CLI boundary; this helper requires a
+  // non-null worker with a canonical id. The pre-G6 `dir:<recipientId>`
+  // fallback for null workers is removed.
   // ---------------------------------------------------------------------------
 
-  describe('resolveResumeSessionId (master-aware fallback)', () => {
-    /**
-     * Insert a `dir:<name>` master agent row directly. Mirrors
-     * `agent-directory.add()` but skips the `agents.yaml` round-trip so the
-     * test keeps a tight surface around the chokepoint behavior.
-     * Crucially sets `auto_resume=true` (fresh-DB default is `false` since
-     * migration 044) so the chokepoint returns `resume=true` for permanent
-     * rows that have a session UUID on file.
-     */
-    async function seedMasterDirRow(name: string, opts: { team: string; repoPath: string }): Promise<void> {
-      const { getConnection } = await import('./db.js');
-      const sql = await getConnection();
-      await sql`
-        INSERT INTO agents (id, role, custom_name, team, repo_path, started_at, auto_resume, state, metadata)
-        VALUES (
-          ${`dir:${name}`}, ${name}, ${name}, ${opts.team}, ${opts.repoPath},
-          now(), true, ${null}, ${sql.json({})}
-        )
-      `;
-    }
-
+  describe('resolveResumeSessionId (identity-only)', () => {
     function templateFor(role: string, team: string): WorkerTemplate {
       return {
         id: `${team}-${role}`,
@@ -880,53 +862,79 @@ describe.skip('pg — TODO retire-session-names #175: rewrite fixtures for UUID
       };
     }
 
-    test('master agent: dir:<name> with current_executor.claude_session_id resolves via chokepoint', async () => {
+    test('master agent (dir:<name> id): resolves via chokepoint when worker row carries the id', async () => {
+      const registry = await import('./agent-registry.js');
       const executorReg = await import('./executor-registry.js');
       const { resolveResumeSessionId } = await import('./protocol-router.js');
 
       const sessionId = 'fa1fac7b-1234-4abc-9def-000000000001';
-      await seedMasterDirRow('master-db', { team: 'team-db', repoPath: tempDir });
+      const now = new Date().toISOString();
+      // Master persistence id-shape (`dir:<name>`) is preserved. The wish #175
+      // change is that the caller must pass a worker row with this id —
+      // resolveResumeSessionId no longer fabricates `dir:${recipientId}` from
+      // a name when worker is null.
+      await registry.register({
+        id: 'dir:master-db',
+        paneId: '%51',
+        session: 'test-session',
+        provider: 'claude',
+        transport: 'tmux',
+        role: 'master-db',
+        team: 'team-db',
+        customName: 'master-db',
+        state: 'idle',
+        startedAt: now,
+        lastStateChange: now,
+        repoPath: tempDir,
+        worktree: null,
+        autoResume: true,
+      });
       await executorReg.createAndLinkExecutor('dir:master-db', 'claude', 'tmux', {
         claudeSessionId: sessionId,
         state: 'idle',
       });
 
-      const result = await resolveResumeSessionId(null, templateFor('master-db', 'team-db'), 'master-db');
+      const worker = await registry.get('dir:master-db');
+      expect(worker).toBeTruthy();
+      const result = await resolveResumeSessionId(worker!, templateFor('master-db', 'team-db'));
       expect(result).toBe(sessionId);
     });
 
-    test('master agent jsonl-fallback: no executor on row, jsonl on disk resolves via chokepoint', async () => {
+    test('null worker is rejected at the contract boundary (G6 tightened)', async () => {
       const { resolveResumeSessionId } = await import('./protocol-router.js');
-      const executorReg = await import('./executor-registry.js');
-
-      const recoveredSessionId = 'fa1fac7b-1234-4abc-9def-000000000002';
-      await seedMasterDirRow('master-jsonl', { team: 'team-jsonl', repoPath: tempDir });
-      // No executor → DB happy path misses; getResumeSessionId falls through
-      // to the JSONL scanner. Override scanner to return our recovered UUID
-      // without touching the real ~/.claude/projects/* tree.
-      executorReg._resumeJsonlScannerDeps.scanForSession = async (cwd, identity) => {
-        if (cwd === tempDir && identity?.team === 'team-jsonl' && identity?.customName === 'master-jsonl') {
-          return recoveredSessionId;
-        }
-        return null;
-      };
-
-      try {
-        const result = await resolveResumeSessionId(null, templateFor('master-jsonl', 'team-jsonl'), 'master-jsonl');
-        expect(result).toBe(recoveredSessionId);
-      } finally {
-        executorReg._resumeJsonlScannerDeps.scanForSession = null;
-      }
+      // After wish #175 G6, callers must resolve to an id before invoking this
+      // helper. Passing null violates the contract — type-system enforces this
+      // at compile time, but we guard at runtime to catch any erased-type
+      // callers from JS.
+      await expect(
+        // @ts-expect-error — passing null intentionally violates the new contract
+        resolveResumeSessionId(null, templateFor('eph', 'team-eph')),
+      ).rejects.toThrow();
     });
 
-    test('ephemeral spawn: no dir:<name> row, no worker → undefined (fresh --session-id)', async () => {
+    test('non-claude provider returns undefined regardless of worker state', async () => {
+      const registry = await import('./agent-registry.js');
       const { resolveResumeSessionId } = await import('./protocol-router.js');
 
-      const result = await resolveResumeSessionId(
-        null,
-        templateFor('ephemeral-role', 'team-eph'),
-        'unknown-ephemeral-task',
-      );
+      const now = new Date().toISOString();
+      await registry.register({
+        id: '99999999-2222-3333-4444-555555555555',
+        paneId: '%52',
+        session: 'test-session',
+        provider: 'codex',
+        transport: 'tmux',
+        role: 'codex-role',
+        team: 'team-codex',
+        state: 'idle',
+        startedAt: now,
+        lastStateChange: now,
+        repoPath: tempDir,
+        worktree: null,
+      });
+      const worker = await registry.get('99999999-2222-3333-4444-555555555555');
+      expect(worker).toBeTruthy();
+      const tpl: WorkerTemplate = { ...templateFor('codex-role', 'team-codex'), provider: 'codex' };
+      const result = await resolveResumeSessionId(worker!, tpl);
       expect(result).toBeUndefined();
     });
 
@@ -938,7 +946,7 @@ describe.skip('pg — TODO retire-session-names #175: rewrite fixtures for UUID
       const sessionId = 'fa1fac7b-1234-4abc-9def-000000000003';
       const now = new Date().toISOString();
       await registry.register({
-        id: 'live-master-worker',
+        id: '88888888-2222-3333-4444-555555555555',
         paneId: '%50',
         session: 'test-session',
         provider: 'claude',
@@ -953,15 +961,53 @@ describe.skip('pg — TODO retire-session-names #175: rewrite fixtures for UUID
         worktree: null,
         autoResume: true,
       });
-      await executorReg.createAndLinkExecutor('live-master-worker', 'claude', 'tmux', {
+      await executorReg.createAndLinkExecutor('88888888-2222-3333-4444-555555555555', 'claude', 'tmux', {
         claudeSessionId: sessionId,
         state: 'idle',
       });
 
-      const worker = await registry.get('live-master-worker');
+      const worker = await registry.get('88888888-2222-3333-4444-555555555555');
       expect(worker).toBeTruthy();
-      const result = await resolveResumeSessionId(worker!, templateFor('master-live', 'team-live'), 'master-live');
+      const result = await resolveResumeSessionId(worker!, templateFor('master-live', 'team-live'));
       expect(result).toBe(sessionId);
     });
   });
+
+  // ---------------------------------------------------------------------------
+  // findSpawnTemplate / cleanupDeadWorkers identity-only contracts (wish #175 G6)
+  // These helpers are not exported — we exercise them via send-path behavior:
+  //  - findSpawnTemplate: a recipient-as-role that only matches a template by
+  //    its `role` (no worker carrying that role) must NOT auto-spawn anymore.
+  //  - cleanupDeadWorkers: only removes the row whose id matches; sibling
+  //    dead rows with the same role survive.
+  // ---------------------------------------------------------------------------
+
+  describe('identity-only spawn/cleanup contracts (G6)', () => {
+    test('findSpawnTemplate refuses to match by recipient name when no worker exists', async () => {
+      const registry = await import('./agent-registry.js');
+      const router = await import('./protocol-router.js');
+
+      router._deps.isPaneAlive = async (paneId: string) => alivePanes.has(paneId);
+      router._deps.waitForWorkerReady = async () => true;
+      process.env.TMUX = '/tmp/tmux-test/default,123,0';
+
+      const now = new Date().toISOString();
+      // Template exists keyed by role 'engineer' / team 'g6-team'.
+      await registry.saveTemplate({
+        id: 'g6-team-engineer',
+        team: 'g6-team',
+        role: 'engineer',
+        provider: 'claude',
+        cwd: tempDir,
+        lastSpawnedAt: now,
+      });
+
+      // No worker row, no directory entry. Pre-G6 router would have matched
+      // the template by recipientId ('engineer') and spawned. Post-G6: refuses.
+      const spawnCountBefore = spawnCallCount;
+      const result = await router.sendMessage(tempDir, 'alice', 'engineer', 'hi', 'g6-team');
+      expect(spawnCallCount).toBe(spawnCountBefore);
+      expect(result.delivered).toBe(false);
+    });
+  });
 });

src/lib/protocol-router.ts

@@ -236,21 +236,19 @@ async function findLiveWorkerFuzzy(recipientId: string): Promise<registry.Agent
  * Ensure a worker is alive, auto-spawning from template if needed.
  * Handles suspended workers by resuming with --resume <session-id>.
  */
-/** Find a matching spawn template for the worker/recipient. */
-async function findSpawnTemplate(
-  worker: registry.Agent | null,
-  recipientId: string,
-): Promise<registry.WorkerTemplate | null> {
+/**
+ * Find a matching spawn template for a known worker.
+ *
+ * Identity-only match: requires a worker row carrying `(team, role)` —
+ * recipientId-as-role fuzz removed (wish #175 G6, decision row 2).
+ * Caller resolves name → id at the CLI boundary; if no worker row exists
+ * for the canonical id, return null and let the send path surface
+ * "unknown agent" rather than guessing.
+ */
+async function findSpawnTemplate(worker: registry.Agent | null): Promise<registry.WorkerTemplate | null> {
+  if (!worker || !worker.team || !worker.role) return null;
   const templates = await registry.listTemplates();
-  const candidates = [worker?.role, worker?.id, recipientId].filter((v): v is string => Boolean(v));
-  const uniqueCandidates = [...new Set(candidates)];
-  const workerTeam = worker?.team;
-  return (
-    templates.find((t) => {
-      if (workerTeam && t.team !== workerTeam) return false;
-      return uniqueCandidates.some((q) => t.id === q || t.role === q || `${t.team}:${t.role}` === q);
-    }) ?? null
-  );
+  return templates.find((t) => t.team === worker.team && t.role === worker.role) ?? null;
 }
 
 /** Attempt to spawn a worker from template inside an advisory-locked transaction. */
@@ -261,7 +259,6 @@ async function lockedSpawnWorker(
   resumeSessionId: string | undefined,
 ): Promise<{ worker: registry.Agent; respawned: boolean } | null> {
   const sql = await getConnection();
-  const workerTeam = worker?.team;
 
   const lockResult = await sql.begin(async (tx: typeof sql) => {
     await tx`SELECT pg_advisory_xact_lock(hashtext(${recipientId}))`;
@@ -270,8 +267,10 @@ async function lockedSpawnWorker(
     const postLockLive = await findLiveWorkerFuzzy(recipientId);
     if (postLockLive) return { type: 'existing' as const, worker: postLockLive };
 
-    await cleanupDeadWorkers(recipientId, workerTeam);
-    if (worker) await registry.unregister(worker.id);
+    if (worker) {
+      await cleanupDeadWorkers(worker.id);
+      await registry.unregister(worker.id);
+    }
 
     const { spawnWorkerFromTemplate } = await import('./protocol-router-spawn.js');
     const spawnResult = await spawnWorkerFromTemplate(template, resumeSessionId);
@@ -298,32 +297,28 @@ async function lockedSpawnWorker(
  * whose last executor is in a non-terminal state (spawning/running/idle/
  * working/permission/question) are mid-task — we MUST resume them with
  * their session id. Silently spawning fresh would drop the conversation
- * history. Master agents (`kind='permanent'`, `dir:<name>` rows) lose
- * their runtime worker on reboot but retain a recoverable session UUID
- * via the chokepoint; probing `dir:<recipientId>` when no live worker
- * exists keeps team-lead "hires" on the master's persistent session
- * instead of forking a fresh UUID and orphaning conversation history.
- * Ephemeral spawns have no `dir:<name>` row, so the chokepoint returns
- * `unknown_agent` and the caller proceeds with a fresh `--session-id`.
- * Gap C from trace-stale-resume (task #6) + master-aware-spawn Group 1.
+ * history. Identity-only contract (wish #175 G6): caller must supply a
+ * non-null worker with a canonical id (UUID or `dir:<name>`); the
+ * `dir:${recipientId}` fallback for null workers is removed because
+ * name-as-id resolution belongs at the CLI boundary, not here.
+ * Gap C from trace-stale-resume (task #6).
  */
 export async function resolveResumeSessionId(
-  worker: registry.Agent | null,
+  worker: registry.Agent,
   template: registry.WorkerTemplate,
-  recipientId: string,
 ): Promise<string | undefined> {
   if (template.provider !== 'claude') return undefined;
-  const agentIdToProbe = worker?.id ?? `dir:${recipientId}`;
-  const decision = await shouldResume(agentIdToProbe);
-  if (worker && (await isExecutorResumable(worker))) {
-    if (!decision.sessionId) throw new MissingResumeSessionError(worker.id, recipientId);
+  if (!worker.id) throw new Error('resolveResumeSessionId: worker.id is required');
+  const decision = await shouldResume(worker.id);
+  if (await isExecutorResumable(worker)) {
+    if (!decision.sessionId) throw new MissingResumeSessionError(worker.id);
   }
   if (!decision.sessionId) return undefined;
   // Actual resume attempt — emit the lifecycle event via the eventful
   // helper. `shouldResume` (read path) stays silent
   // (observability-signal-normalization Group 1).
   const { acquireResumeSessionForAttempt } = await import('./executor-registry.js');
-  const acquired = await acquireResumeSessionForAttempt(agentIdToProbe).catch(() => null);
+  const acquired = await acquireResumeSessionForAttempt(worker.id).catch(() => null);
   return acquired ?? decision.sessionId;
 }
 
@@ -351,10 +346,15 @@ async function ensureWorkerAlive(
   if (await isExecutorCompleted(worker)) return null;
   if (!process.env.TMUX) return null;
 
-  const template = await findSpawnTemplate(worker, recipientId);
+  // Identity-only auto-spawn (wish #175 G6): we need a worker row with
+  // (team, role) to locate a template. Directory-only fallback (no worker
+  // row) is intentionally not supported here — caller resolves at CLI.
+  if (!worker) return null;
+
+  const template = await findSpawnTemplate(worker);
   if (!template) return null;
 
-  const resumeSessionId = await resolveResumeSessionId(worker, template, recipientId);
+  const resumeSessionId = await resolveResumeSessionId(worker, template);
 
   try {
     return await lockedSpawnWorker(recipientId, worker, template, resumeSessionId);
@@ -364,18 +364,17 @@ async function ensureWorkerAlive(
 }
 
 /**
- * Remove dead worker entries matching a role/ID to prevent ghost accumulation.
- * Only removes workers whose tmux panes are no longer alive.
+ * Remove the dead worker row identified by `agentId` to prevent ghost
+ * accumulation. Only removes the row when its tmux pane is no longer alive.
+ *
+ * Identity-only contract (wish #175 G6): match by canonical id only —
+ * role/team fuzz removed. Caller resolves at the CLI boundary.
  */
-async function cleanupDeadWorkers(recipientId: string, team?: string): Promise<void> {
-  const allWorkers = await registry.list();
-  for (const w of allWorkers) {
-    if (team && w.team !== team) continue;
-    const matches = w.role === recipientId || w.id === recipientId;
-    if (!matches) continue;
-    if (await _deps.isPaneAlive(w.paneId)) continue;
-    await registry.unregister(w.id);
-  }
+async function cleanupDeadWorkers(agentId: string): Promise<void> {
+  const w = await registry.get(agentId);
+  if (!w) return;
+  if (await _deps.isPaneAlive(w.paneId)) return;
+  await registry.unregister(w.id);
 }
 
 // ============================================================================