fix(lineage): Codex stop correction reads the child rollout for exact depth; a recorded agent path never claims a differently-pathed spawn

Review threads on #480: (1) reparenting to a parent the registry never
placed kept the inferred depth; the same SubagentStop names the child's own
rollout in agent_transcript_path, so exact parent and depth are read from it
first, with the parent-rollout basename as the fallback. (2) with an exact
agent path from the rollout, pending spawns recorded with a different path
are excluded; only matching or pathless (response missed) calls remain
eligible.

Author: ScriptedAlchemy

docs/audits/2026-09-03-host-lineage-matrix.md

@@ -314,7 +314,7 @@ gives shell commands the agent runs `CURSOR_CONVERSATION_ID`/`CURSOR_REQUEST_ID`
 | Host | Answer | How |
 | --- | --- | --- |
 | Claude | Yes, with the parent inferred | `SubagentStart` names the child (`agent_id`). The parent is not in the payload; it is the agent whose `Agent`/`Task` `PreToolUse` is open when `SubagentStart` fires (root when none is open) — re-verified live at depth 1 and 2 in all three runs, including two spawns issued in one message (the host serialises them: each `SubagentStart` fires before the next `Agent` `PreToolUse` opens). The host then confirms the link on the parent's `Agent` `PostToolUse` (`tool_response.agentId` = the child, `status` `async_launched` or `completed`). `Stop`/`SubagentStop` list the children still running **in the background** in `background_tasks[]` (empty when every child ran in the foreground). |
-| Codex | Yes | `SubagentStart` names the child thread and its rollout (`transcript_path`); the rollout's `session_meta` head records `source.subagent.thread_spawn.{parent_thread_id, depth, agent_path}` (§10), so the parent is read, not inferred. The `collaborationspawn_agent` call is matched to the child by `agent_path` (= the call's `PostToolUse` `tool_response.task_name`, rows 16/27). With the rollout unreadable, the parent is inferred from the newest unclaimed spawn call and corrected at `SubagentStop` by the parent rollout in `transcript_path`. MCP calls carry `parent_thread_id` directly. |
+| Codex | Yes | `SubagentStart` names the child thread and its rollout (`transcript_path`); the rollout's `session_meta` head records `source.subagent.thread_spawn.{parent_thread_id, depth, agent_path}` (§10), so the parent is read, not inferred. The `collaborationspawn_agent` call is matched to the child by `agent_path` (= the call's `PostToolUse` `tool_response.task_name`, rows 16/27). With the rollout unreadable, the parent is inferred from the newest unclaimed spawn call and corrected at `SubagentStop` — from the child's own rollout (`agent_transcript_path`) when readable by then, else from the parent rollout in `transcript_path`. MCP calls carry `parent_thread_id` directly. |
 | Cursor | Yes for the spawn, weakly for the child's traffic | `subagentStart` carries `parent_conversation_id`, `subagent_id`/`tool_call_id`, `is_parallel_worker`. The child's own `conversation_id` is not in that payload, so the first event with an unseen conversation id after a `subagentStart` is bound to it (unambiguous when children start sequentially; ambiguous for parallel workers). |
 
 **Can a plugin running under a subagent know its parent/root?**
@@ -481,4 +481,6 @@ places the thread with `resolution: 'transcript'`; the MCP `_meta` lineage
 (§3) and the hook-side lineage therefore agree by construction. What stays
 host-side: the payload itself still carries no `parent_thread_id`, so a hook
 that cannot read `CODEX_HOME/sessions` (or a rollout not yet flushed) falls
-back to spawn-ordering inference and is corrected at `SubagentStop`.
+back to spawn-ordering inference and is corrected at `SubagentStop` (from the
+child's own rollout when readable by then, else from the parent rollout's
+basename).

docs/entry-conventions.md

@@ -444,8 +444,10 @@ claimed, by parent and by the `agent_path` its `PostToolUse`
 `tool_response.task_name` carried, so `subagent.toolCallId` is exact even for
 same-parent siblings. Only when the rollout is unreadable does Codex fall back
 to the Claude rule (`resolution: 'registry'`), and a parent inferred that way
-is corrected at `SubagentStop`, where `transcript_path` is the parent's
-rollout (`rollout-<timestamp>-<thread id>.jsonl`); descendants move with it.
+is corrected at `SubagentStop` — from the child's own rollout
+(`agent_transcript_path`, exact parent and depth) when it is readable by then,
+else from the parent rollout in `transcript_path`
+(`rollout-<timestamp>-<thread id>.jsonl`); descendants move with it.
 Cursor names a child only on the parent's `subagentStart` (`subagent_id` =
 the parent's `Task` call id); the child's own hooks carry a fresh
 `conversation_id` and nothing that points back, so the registry binds by

packages/agent-bundle/src/adapters/capabilities/codex-0.147.0.json

@@ -446,7 +446,7 @@
       "state": "supported",
       "evidence": [
         "2026-09-03: SubagentStart names no parent thread (#423), but names the new thread's rollout in transcript_path — as does every hook fired inside the thread; SubagentStop moves it to agent_transcript_path — and that rollout's session_meta head records source.subagent.thread_spawn.parent_thread_id, present on every thread-spawn rollout observed for cli 0.130.0 through 0.152.0 (fixtures/host-lineage/codex-0.147.0-rollouts). The registry reads it at SubagentStart, on the first hook of a thread seen mid-flight, and at SubagentStop (resolution: transcript, provenance derived); standalone hooks read it the same way. tools/call _meta.x-codex-turn-metadata carries parent_thread_id natively.",
-        "2026-09-03: with the rollout unreadable the registry falls back to claiming the newest unclaimed collaborationspawn_agent call under the same root (resolution: registry; refused when two parents have unclaimed spawns) and corrects that parent at SubagentStop from the parent rollout named in transcript_path (rollout-<timestamp>-<thread id>.jsonl). The spawn call's PostToolUse tool_response.task_name (/root/<task>/…) equals the child rollout's agent_path, so the spawning tool call is matched by path rather than by order."
+        "2026-09-03: with the rollout unreadable the registry falls back to claiming the newest unclaimed collaborationspawn_agent call under the same root (resolution: registry; refused when two parents have unclaimed spawns) and corrects that parent at SubagentStop: from the child's own rollout in agent_transcript_path (exact parent and depth) when readable, else from the parent rollout named in transcript_path (rollout-<timestamp>-<thread id>.jsonl). The spawn call's PostToolUse tool_response.task_name (/root/<task>/…) equals the child rollout's agent_path, so the spawning tool call is matched by path rather than by order."
       ]
     },
     "depth": {

packages/rsc-runtime/src/lineage/registry.ts

@@ -319,12 +319,17 @@ export const createAgentLineageRegistry = (
     const spawn = SPAWN_TOOLS[host];
     const underRoot = state.pendingSpawns.filter((call) =>
       spawn(call.toolName) && (nodeFor(call.conversation)?.root ?? call.conversation) === root);
-    // A known parent narrows the field to that parent's spawns; a known
-    // agent path names the exact call, since the spawn's tool response
-    // carried the same path.
+    // A known parent narrows the field to that parent's spawns. A known agent
+    // path names the exact call, since the spawn's tool response carried the
+    // same path; a call recorded with a *different* path belongs to another
+    // child and is never consumed, while a call whose response was missed
+    // (no path recorded) stays eligible.
     const fromParent = target === undefined ? underRoot : underRoot.filter((call) => call.conversation === target.parent);
-    const byPath = target?.agentPath === undefined ? [] : fromParent.filter((call) => call.agentPath === target.agentPath);
-    const candidates = byPath.length > 0 ? byPath : fromParent;
+    const compatible = target?.agentPath === undefined
+      ? fromParent
+      : fromParent.filter((call) => call.agentPath === undefined || call.agentPath === target.agentPath);
+    const exact = target?.agentPath === undefined ? [] : compatible.filter((call) => call.agentPath === target.agentPath);
+    const candidates = exact.length > 0 ? exact : compatible;
     if (candidates.length === 0) return { kind: 'none' };
     // Several unclaimed spawns from different parents under one root: the
     // start payload carries nothing to pick between them, so no guess.
@@ -544,14 +549,23 @@ export const createAgentLineageRegistry = (
       // A stop for a thread the registry never placed (cold registry, missed
       // start) still names the thread's rollout in `agent_transcript_path`.
       if (state.nodes[stopped] === undefined) await placeUnknownCodexThread('agent/stop', native, observedAt, keys);
-      // `transcript_path` on SubagentStop is the parent's rollout, and the
-      // rollout basename carries its thread id: a parent inferred from spawn
-      // ordering that disagrees is corrected before the node retires.
+      // A node placed by spawn ordering is checked against the host's own
+      // record before it retires: the child's rollout (`agent_transcript_path`)
+      // states parent and depth exactly; failing that, `transcript_path` is
+      // the parent's rollout and its basename carries the parent thread id
+      // (the depth then follows the parent when the registry knows it).
       const node = state.nodes[stopped];
-      const parent = codexThreadFromRolloutPath(nativeString(native, 'transcript_path'));
-      if (node !== undefined && node.placement !== 'transcript' && parent !== undefined && parent !== node.id && node.parent !== parent) {
-        const parentDepth = parent === node.root ? 0 : nodeFor(parent)?.depth;
-        await dispatch('nodeReparented', { ...(parentDepth === undefined ? {} : { depth: parentDepth + 1 }), id: stopped, parent }, keys);
+      if (node !== undefined && node.placement !== 'transcript') {
+        const own = await readCodexSpawnLineage(nativeString(native, 'agent_transcript_path'), stopped, readTranscript);
+        if (own !== undefined) {
+          await dispatch('nodeReparented', { depth: own.depth, id: stopped, parent: own.parent, placement: 'transcript' }, keys);
+        } else {
+          const parent = codexThreadFromRolloutPath(nativeString(native, 'transcript_path'));
+          if (parent !== undefined && parent !== node.id && node.parent !== parent) {
+            const parentDepth = parent === node.root ? 0 : nodeFor(parent)?.depth;
+            await dispatch('nodeReparented', { ...(parentDepth === undefined ? {} : { depth: parentDepth + 1 }), id: stopped, parent }, keys);
+          }
+        }
       }
     }
     if (state.nodes[stopped] === undefined) return;

packages/rsc-runtime/tests/lineage-codex-rollout.test.ts

@@ -312,6 +312,77 @@ describe('lineage registry places Codex threads from their own rollout (#423)',
     expect(registry.snapshot().nodes[other]?.stoppedAt).toBeUndefined();
   });
 
+  it('takes exact parent and depth from the child rollout at SubagentStop when the parent thread was never placed', async () => {
+    // Unreadable at start (inference files the nested thread directly under the
+    // root), readable by the time it stops.
+    const rollouts = new Map<string, string>();
+    const registry = createAgentLineageRegistry({ readTranscript: async (path) => rollouts.get(basename(path)) });
+    const observe = (event: string, key: string, native: Record<string, unknown>) =>
+      registry.observe({ event, host: 'codex', idempotencyKey: key, native, observedAt: '2026-09-03T00:00:00.000Z' });
+    await observe('session/start', 's', codexHook('SessionStart', undefined));
+    await observe('tool/before', 'sp', codexHook('PreToolUse', undefined, { tool_input: {}, tool_name: 'collaborationspawn_agent', tool_use_id: 'sp' }));
+    const misfiled = await observe('agent/start', 'nested', codexHook('SubagentStart', NESTED, { transcript_path: NESTED_ROLLOUT }));
+    expect(value(misfiled)).toMatchObject({ depth: 1, parent: ROOT, resolution: 'registry' });
+    await observe('tool/before', 'gc-spawn', codexHook('PreToolUse', NESTED, { tool_input: {}, tool_name: 'collaborationspawn_agent', tool_use_id: 'gc-spawn' }));
+    const grandchild = '01a00000-0000-7000-8000-00000000000c';
+    await observe('agent/start', 'gc', codexHook('SubagentStart', grandchild, { transcript_path: `/x/rollout-2026-09-03T00-00-00-${grandchild}.jsonl` }));
+
+    rollouts.set(basename(NESTED_ROLLOUT), (await readCodexRolloutHead(rolloutFixture(NESTED_ROLLOUT)))!);
+    // SUBAGENT, the real parent, was never seen by this registry: only the child's own rollout can say how deep it sits.
+    const stopped = await observe('agent/stop', 'nested-stop', codexHook('SubagentStop', NESTED, { agent_transcript_path: NESTED_ROLLOUT, stop_hook_active: false, transcript_path: SUBAGENT_ROLLOUT }));
+    expect(value(stopped)).toMatchObject({ conversation: NESTED, depth: 2, parent: SUBAGENT, resolution: 'transcript' });
+    expect(registry.snapshot().nodes[NESTED]).toMatchObject({ depth: 2, parent: SUBAGENT, placement: 'transcript' });
+    expect(registry.snapshot().nodes[grandchild]).toMatchObject({ depth: 3, parent: NESTED });
+    expect(registry.snapshot().nodes[SUBAGENT]).toBeUndefined();
+  });
+
+  it('keeps the inferred depth when only the parent basename is available and that parent is unknown', async () => {
+    const registry = createAgentLineageRegistry({ readTranscript: noRollouts });
+    const observe = (event: string, key: string, native: Record<string, unknown>) =>
+      registry.observe({ event, host: 'codex', idempotencyKey: key, native, observedAt: '2026-09-03T00:00:00.000Z' });
+    await observe('session/start', 's', codexHook('SessionStart', undefined));
+    await observe('tool/before', 'sp', codexHook('PreToolUse', undefined, { tool_input: {}, tool_name: 'collaborationspawn_agent', tool_use_id: 'sp' }));
+    await observe('agent/start', 'nested', codexHook('SubagentStart', NESTED, { transcript_path: NESTED_ROLLOUT }));
+    const stopped = await observe('agent/stop', 'nested-stop', codexHook('SubagentStop', NESTED, { agent_transcript_path: NESTED_ROLLOUT, stop_hook_active: false, transcript_path: SUBAGENT_ROLLOUT }));
+    // The parent is corrected to what the basename proves; the depth stays what inference gave, still reported as `registry`.
+    expect(value(stopped)).toMatchObject({ conversation: NESTED, depth: 1, parent: SUBAGENT, resolution: 'registry' });
+  });
+
+  it('never consumes a sibling\'s spawn call whose recorded path differs from the starting child\'s', async () => {
+    const rollouts = new Map<string, string>();
+    const registry = createAgentLineageRegistry({ readTranscript: async (path) => rollouts.get(path) });
+    const observe = (event: string, key: string, native: Record<string, unknown>) =>
+      registry.observe({ event, host: 'codex', idempotencyKey: key, native, observedAt: '2026-09-03T00:00:00.000Z' });
+    const meta = (thread: string, agentPath: string) =>
+      JSON.stringify({ payload: { id: thread, session_id: ROOT, source: { subagent: { thread_spawn: { agent_path: agentPath, depth: 1, parent_thread_id: ROOT } } } }, type: 'session_meta' });
+    const a = '01a00000-0000-7000-8000-0000000000aa';
+    const b = '01a00000-0000-7000-8000-0000000000bb';
+    rollouts.set('/r/a.jsonl', meta(a, '/root/a'));
+    rollouts.set('/r/b.jsonl', meta(b, '/root/b'));
+    await observe('session/start', 's', codexHook('SessionStart', undefined));
+    // A's spawn call was fully observed; B's spawn hooks were missed entirely.
+    await observe('tool/before', 'sa', codexHook('PreToolUse', undefined, { tool_input: { task_name: 'a' }, tool_name: 'collaborationspawn_agent', tool_use_id: 'spawn-a' }));
+    await observe('tool/after', 'sa-after', codexHook('PostToolUse', undefined, { tool_input: { task_name: 'a' }, tool_name: 'collaborationspawn_agent', tool_response: '{"task_name":"/root/a"}', tool_use_id: 'spawn-a' }));
+    const startB = await observe('agent/start', 'b', codexHook('SubagentStart', b, { transcript_path: '/r/b.jsonl' }));
+    expect(value(startB)).toMatchObject({ conversation: b, depth: 1, parent: ROOT, resolution: 'transcript' });
+    expect(value(startB).subagent?.toolCallId).toBeUndefined();
+    expect(registry.snapshot().pendingSpawns.map((call) => call.toolCallId)).toEqual(['spawn-a']);
+    const startA = await observe('agent/start', 'a', codexHook('SubagentStart', a, { transcript_path: '/r/a.jsonl' }));
+    expect(value(startA)).toMatchObject({ conversation: a, resolution: 'transcript', subagent: { toolCallId: 'spawn-a' } });
+    expect(registry.snapshot().pendingSpawns).toEqual([]);
+  });
+
+  it('still claims a spawn call whose response (and path) was missed, when it is the parent\'s only pending one', async () => {
+    const meta = JSON.stringify({ payload: { id: NESTED, session_id: ROOT, source: { subagent: { thread_spawn: { agent_path: '/root/x', depth: 1, parent_thread_id: ROOT } } } }, type: 'session_meta' });
+    const registry = createAgentLineageRegistry({ readTranscript: async () => meta });
+    const observe = (event: string, key: string, native: Record<string, unknown>) =>
+      registry.observe({ event, host: 'codex', idempotencyKey: key, native, observedAt: '2026-09-03T00:00:00.000Z' });
+    await observe('session/start', 's', codexHook('SessionStart', undefined));
+    await observe('tool/before', 'sp', codexHook('PreToolUse', undefined, { tool_input: {}, tool_name: 'collaborationspawn_agent', tool_use_id: 'pathless' }));
+    const start = await observe('agent/start', 'n', codexHook('SubagentStart', NESTED, { transcript_path: '/r/n.jsonl' }));
+    expect(value(start)).toMatchObject({ depth: 1, parent: ROOT, resolution: 'transcript', subagent: { toolCallId: 'pathless' } });
+  });
+
   it('leaves a transcript-placed node alone at SubagentStop and ignores a self-referential path', async () => {
     const registry = createAgentLineageRegistry({ readTranscript: capturedRollouts });
     const observe = (event: string, key: string, native: Record<string, unknown>) =>