feat(spawn): collapse to single UUID row — wish G3

namastex888 · claude · namastex888 · commit a57b5ecffc7b · 2026-05-04T09:41:02.000-03:00
Spawn callers now resolve the durable identity UUID via findOrCreateAgent
before writing runtime fields through register(). The bare-name shadow
path (`register({ id: workerId })`) is gone; register() asserts UUID-or-
`dir:` ids at the top so any rogue caller fails loudly with a useful
message instead of an opaque CHECK violation from migration 061.

Touched call sites:
- agents.ts:registerSpawnWorker — drops `?? ctx.workerId` fallback;
  agentIdentityId is now required.
- agents.ts launchTmuxSpawn / rollbackSpawn / launchSdkSpawn /
  launchInlineSpawn — registry.update / unregister target the UUID id,
  not the bare workerId.
- protocol-router-spawn.ts:spawnWorkerFromTemplate — resolves
  findOrCreateAgent(agentName, team, role) before register(); workerId
  lands on custom_name.
- session.ts:registerSessionInRegistry — same reshape; bare-name lives
  on custom_name.

New test (spawn-single-row.test.ts) covers:
1. register() rejects bare-name ids with the new error message.
2. register() accepts dir: master-row ids.
3. End-to-end spawn lands ONE UUID-keyed agents row (no shadow twin).
4. Repeated register() with the same identity is idempotent.

Wish: retire-session-names-id-only Group 3.
Co-Authored-By: Claude Opus 4.7 &lt;noreply@anthropic.com&gt;
diff --git a/src/genie-commands/session.ts b/src/genie-commands/session.ts
@@ -126,12 +126,20 @@ async function registerSessionInRegistry(sessionName: string, windowName: string
     const sanitized = sanitizeTeamName(windowName);
     const leaderName = await resolveSessionLeaderName(windowName);
     const sanitizedLeader = sanitizeTeamName(leaderName);
+
+    // Wish retire-session-names-id-only Group 3: spawn writes ONE row.
+    // Resolve the durable identity UUID before registering runtime fields so
+    // the row's id matches `agents_id_shape_check` (migration 061). The
+    // bare-name display label (`<team>-<leader>`) lands on `custom_name`.
+    const agentIdentity = await registry.findOrCreateAgent(leaderName, sanitized, leaderName);
+
     await registry.register({
-      id: `${sanitized}-${sanitizedLeader}`,
+      id: agentIdentity.id,
       paneId,
       session: sessionName,
       team: windowName,
       role: leaderName,
+      customName: `${sanitized}-${sanitizedLeader}`,
       worktree: null,
       startedAt: now,
       state: 'working',
@@ -143,9 +151,6 @@ async function registerSessionInRegistry(sessionName: string, windowName: string
       nativeAgentId: `${sanitizedLeader}@${sanitized}`,
     });
 
-    // Executor model: create agent identity + executor for leader session
-    const agentIdentity = await registry.findOrCreateAgent(leaderName, sanitized, leaderName);
-
     let pid: number | null = null;
     try {
       const pidStr = (await tmux.executeTmux(`display -t ${shellQuote(target)} -p '#{pane_pid}'`)).trim();
diff --git a/src/lib/__tests__/spawn-single-row.test.ts b/src/lib/__tests__/spawn-single-row.test.ts
@@ -0,0 +1,126 @@
+/**
+ * Wish retire-session-names-id-only Group 3 — Spawn writes ONE row.
+ *
+ * Asserts the post-G3 invariants:
+ *   1. `register()` rejects bare-name ids loudly (UUID OR `dir:<name>` only).
+ *   2. The legitimate spawn path (`findOrCreateAgent` → `register`) lands a
+ *      single UUID-keyed agents row — no bare-name shadow twin.
+ *   3. `register()` accepts `dir:<name>` master-row ids.
+ *
+ * The bare-name shadow rejection is mirrored in migration 061's
+ * `agents_id_shape_check`; this test covers the application-level guard so
+ * the failure message is "loud throw at the call site" instead of a deep
+ * SQL CHECK violation.
+ */
+
+import { afterAll, afterEach, beforeAll, describe, expect, test } from 'bun:test';
+import { findOrCreateAgent, list, register, unregister } from '../agent-registry.js';
+import { getConnection } from '../db.js';
+import { DB_AVAILABLE, setupTestDatabase } from '../test-db.js';
+
+describe.skipIf(!DB_AVAILABLE)('spawn-single-row — wish retire-session-names-id-only G3', () => {
+  let cleanup: () => Promise<void>;
+
+  beforeAll(async () => {
+    cleanup = await setupTestDatabase();
+  });
+
+  afterAll(async () => {
+    await cleanup();
+  });
+
+  afterEach(async () => {
+    const sql = await getConnection();
+    await sql`DELETE FROM executors`;
+    await sql`DELETE FROM agents`;
+  });
+
+  function makeRuntimeAgent(id: string, customName: string, team: string) {
+    return {
+      id,
+      paneId: '%17',
+      session: team,
+      worktree: null,
+      customName,
+      role: customName,
+      team,
+      startedAt: new Date().toISOString(),
+      state: 'spawning' as const,
+      lastStateChange: new Date().toISOString(),
+      repoPath: '/tmp/test',
+      provider: 'claude' as const,
+      transport: 'tmux' as const,
+    };
+  }
+
+  test('register rejects bare-name id with a useful error', async () => {
+    const bareName = makeRuntimeAgent('engineer-4d48', 'engineer-4d48', 'genie');
+    let caught: Error | null = null;
+    try {
+      await register(bareName);
+    } catch (err) {
+      caught = err as Error;
+    }
+    expect(caught).not.toBeNull();
+    expect(caught!.message).toContain('non-UUID/non-dir agent id');
+    expect(caught!.message).toContain('findOrCreateAgent');
+  });
+
+  test('register accepts dir: master-row id', async () => {
+    const master = makeRuntimeAgent('dir:engineer', 'engineer', 'genie');
+    await register(master);
+    const sql = await getConnection();
+    const rows = await sql<{ id: string }[]>`SELECT id FROM agents WHERE id = 'dir:engineer'`;
+    expect(rows.length).toBe(1);
+    await unregister('dir:engineer');
+  });
+
+  test('full spawn path lands ONE UUID-keyed row (no bare-name shadow)', async () => {
+    // Step 1 (mirroring agents.ts:resolveSpawnIdentity → findOrCreateAgent):
+    // resolve the durable identity row keyed by (custom_name, team).
+    const identity = await findOrCreateAgent('engineer', 'genie', 'engineer');
+    expect(identity.id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i);
+
+    // Step 2 (mirroring agents.ts:registerSpawnWorker): register runtime fields
+    // under the SAME UUID. workerId carries the human-readable label only.
+    const workerId = 'engineer-4d48';
+    const runtime = makeRuntimeAgent(identity.id, workerId, 'genie');
+    await register(runtime);
+
+    // Assertion 1: exactly ONE row exists for this (custom_name, team).
+    const all = await list();
+    const matching = all.filter((a) => a.team === 'genie' && (a.customName === 'engineer' || a.id === identity.id));
+    expect(matching.length).toBe(1);
+
+    // Assertion 2: the row is UUID-keyed (no bare-name shadow twin).
+    const sql = await getConnection();
+    const shadowRows = await sql<{ id: string }[]>`
+      SELECT id FROM agents
+      WHERE id NOT LIKE 'dir:%'
+        AND id !~ '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
+    `;
+    expect(shadowRows.length).toBe(0);
+
+    // Assertion 3: runtime fields landed on the identity row (single-source).
+    const refreshed = matching[0];
+    expect(refreshed.paneId).toBe('%17');
+    expect(refreshed.state).toBe('spawning');
+    expect(refreshed.id).toBe(identity.id);
+  });
+
+  test('repeated register() against same identity is idempotent (no shadow twin)', async () => {
+    const identity = await findOrCreateAgent('reviewer', 'genie', 'reviewer');
+    const runtime1 = makeRuntimeAgent(identity.id, 'reviewer-aaaa', 'genie');
+    const runtime2 = makeRuntimeAgent(identity.id, 'reviewer-bbbb', 'genie');
+    await register(runtime1);
+    await register(runtime2); // ON CONFLICT (id) DO UPDATE merges runtime fields
+
+    const all = await list();
+    const matching = all.filter((a) => a.team === 'genie' && a.customName === 'reviewer');
+    // Single row — register's ON CONFLICT (id) DO UPDATE is the upsert.
+    // custom_name stays 'reviewer' from findOrCreateAgent (COALESCE preserves
+    // the existing non-null value).
+    expect(matching.length).toBe(1);
+    expect(matching[0].id).toBe(identity.id);
+  });
+});
diff --git a/src/lib/agent-registry.ts b/src/lib/agent-registry.ts
@@ -230,8 +230,30 @@ function buildLegacyTeamLeadEntryId(teamName: string): string {
   return `team-lead:${teamName}`;
 }
 
+/**
+ * Identity-shape gates enforced by migration 061's `agents_id_shape_check` —
+ * `agents.id` must be a UUID or the `dir:<name>` master-row prefix. Bare-name
+ * inserts get rejected at the database level and crash the spawn pipeline.
+ *
+ * This module-level constant is the application-side mirror so we can fail
+ * fast (with a useful error) BEFORE the SQL roundtrip. Wish
+ * retire-session-names-id-only Group 3 — the spawn primitive writes ONE row,
+ * keyed by the UUID identity from `findOrCreateAgent`. Bare-name shadow rows
+ * are gone.
+ */
+const REGISTER_ID_RE = /^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|dir:[A-Za-z0-9_-]+)$/i;
+
+function assertRegisterableId(id: string): void {
+  if (!REGISTER_ID_RE.test(id)) {
+    throw new Error(
+      `register: refusing to insert non-UUID/non-dir agent id ${JSON.stringify(id)}. Spawn callers must resolve the durable identity row via findOrCreateAgent first and pass that UUID — the bare-name shadow path was retired in wish retire-session-names-id-only Group 3 (migration 061 enforces the same shape at the DB).`,
+    );
+  }
+}
+
 // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: flat field mapping
 export async function register(agent: Agent): Promise<void> {
+  assertRegisterableId(agent.id);
   const sql = await getConnection();
   const now = new Date().toISOString();
 
diff --git a/src/lib/protocol-router-spawn.ts b/src/lib/protocol-router-spawn.ts
@@ -347,15 +347,22 @@ export async function spawnWorkerFromTemplate(
   const isClaude = template.provider === 'claude' || template.provider === 'claude-sdk';
   const effectiveSessionId = resumeSessionId ?? params.sessionId;
 
+  // Wish retire-session-names-id-only Group 3: spawn writes ONE row.
+  // Resolve the durable identity UUID first so register() runs against the
+  // same key the rest of the pipeline observes. The bare `workerId`
+  // (e.g. team-role-<short>) lands on `custom_name` for human-display only.
+  const autoSpawnIdentity = await registry.findOrCreateAgent(agentName, team, template.role);
+
   const workerEntry: registry.Agent = {
-    id: workerId,
+    id: autoSpawnIdentity.id,
     paneId,
     session,
     provider: template.provider,
     transport: 'tmux',
     role: template.role,
     skill: template.skill,
     team,
+    customName: workerId,
     worktree: null,
     startedAt: now,
     state: 'spawning',
diff --git a/src/term-commands/agents.ts b/src/term-commands/agents.ts
@@ -636,26 +636,27 @@ async function registerSpawnWorker(
   windowInfo?: { windowId: string; windowName: string } | null,
 ): Promise<registry.Agent> {
   const nt = ctx.validated.nativeTeam;
-  // Wish retire-session-names-id-only Group 3 (P0 spawn unblock):
-  // `agents.id` MUST be UUID-or-`dir:<name>` per migration 061's
-  // `agents_id_shape_check`. Pre-G3 spawn wrote `id: ctx.workerId` (a bare
-  // name like "engineer-4d48"), which the constraint now rejects, breaking
-  // every `genie agent spawn` on the live host.
+  // Wish retire-session-names-id-only Group 3: spawn writes ONE row.
   //
-  // Fix: route the durable identity UUID (`ctx.agentIdentityId`, set from
-  // `findOrCreateAgent` upstream) into `id`, and stash the human-readable
-  // workerId in `customName` for display/lookup. This collapses the prior
-  // dual-row pattern (UUID identity row + bare-name runtime row) into the
-  // single identity row that already exists. The `register()` ON CONFLICT
-  // (id) DO UPDATE clause then merges runtime fields (pane/session/state)
-  // into the same row instead of inserting a shadow.
+  // `agents.id` is the durable identity UUID returned by `findOrCreateAgent`
+  // (propagated as `ctx.agentIdentityId`). The bare `ctx.workerId`
+  // ("engineer-4d48") is the human-readable label that lives on
+  // `custom_name` for display/lookup — it never enters the id column.
   //
-  // Fallback to `ctx.workerId` is intentional for the rare paths that don't
-  // populate `agentIdentityId` yet — those paths land bare-name rows that
-  // 061 will reject loudly, exactly as designed (we want them surfaced and
-  // patched, not silently bypassed).
+  // The previous fallback (`ctx.agentIdentityId ?? ctx.workerId`) used to
+  // double-write the row keyed by bare-name whenever a caller forgot to
+  // resolve the identity upstream — exactly the regression engine this wish
+  // retires. Migration 061's `agents_id_shape_check` rejects those inserts
+  // at the DB; we mirror the invariant in the application so the failure
+  // mode is "loud throw at the call site that forgot the identity step"
+  // instead of "opaque CHECK violation deeper in the SQL roundtrip."
+  if (!ctx.agentIdentityId) {
+    throw new Error(
+      `registerSpawnWorker: missing agentIdentityId for workerId=${JSON.stringify(ctx.workerId)} (team=${JSON.stringify(ctx.validated.team)}). The spawn pipeline MUST call registry.findOrCreateAgent before register() — see wish retire-session-names-id-only Group 3.`,
+    );
+  }
   const workerEntry: registry.Agent = {
-    id: ctx.agentIdentityId ?? ctx.workerId,
+    id: ctx.agentIdentityId,
     paneId,
     session: ctx.validated.team,
     provider: ctx.validated.provider,
@@ -1207,7 +1208,12 @@ async function launchTmuxSpawn(ctx: SpawnCtx): Promise<string> {
   if (ctx.executorId) {
     await executorRegistry.updateExecutorState(ctx.executorId, 'running').catch(() => {});
   }
-  await registry.update(ctx.workerId, { state: 'idle' }).catch(() => {});
+  // The row was inserted with id = ctx.agentIdentityId (UUID); updates must
+  // target that same key. Falling back to ctx.workerId would no-op silently
+  // because the bare-name row no longer exists.
+  if (ctx.agentIdentityId) {
+    await registry.update(ctx.agentIdentityId, { state: 'idle' }).catch(() => {});
+  }
 
   // #1600 — emit terminal-state success event so `genie events list --type
   // worker.spawn.ok` becomes a positive signal (existing `worker.spawn` is
@@ -1496,8 +1502,10 @@ async function runSdkQuery(
  * then findDeadResumable routed it back through tmux-only resume → crash.
  */
 async function rollbackSpawn(ctx: SpawnCtx, opts: { workerRegistered: boolean }): Promise<void> {
-  if (opts.workerRegistered) {
-    await registry.unregister(ctx.workerId).catch(() => {});
+  // Unregister by the same id the row was inserted under — the UUID identity,
+  // not the bare-name workerId (which now lives only on custom_name).
+  if (opts.workerRegistered && ctx.agentIdentityId) {
+    await registry.unregister(ctx.agentIdentityId).catch(() => {});
   }
   if (ctx.executorId) {
     await executorRegistry.updateExecutorState(ctx.executorId, 'error').catch(() => {});
@@ -1544,7 +1552,10 @@ async function launchSdkSpawn(
   if (ctx.executorId) {
     await executorRegistry.updateExecutorState(ctx.executorId, 'done').catch(() => {});
   }
-  await registry.unregister(ctx.workerId);
+  // The row was inserted under the UUID identity; unregister by the same key.
+  if (ctx.agentIdentityId) {
+    await registry.unregister(ctx.agentIdentityId);
+  }
   console.log(`\nAgent "${ctx.workerId}" SDK session ended.`);
   return ctx.workerId;
 }
@@ -1608,7 +1619,9 @@ async function launchInlineSpawn(ctx: SpawnCtx): Promise<string> {
   if (ctx.agentIdentityId && ctx.executorId) {
     await executorRegistry.updateExecutorState(ctx.executorId, 'done').catch(() => {});
   }
-  await registry.unregister(ctx.workerId);
+  if (ctx.agentIdentityId) {
+    await registry.unregister(ctx.agentIdentityId);
+  }
   if (nt?.enabled && ctx.agentName) {
     await nativeTeams.clearNativeInbox(ctx.validated.team, ctx.agentName).catch(() => {});
     await nativeTeams.unregisterNativeMember(ctx.validated.team, ctx.agentName).catch(() => {});
