feat(native-chat): Codex sessions write their subagents into the host status store

src/main/codex/codex-background-command-tracker.ts

@@ -1,15 +1,20 @@
 import type { AgentSessionBackgroundTask } from '../../shared/agent-session-wire'
 import type { CodexBackgroundTaskEvent } from './codex-background-task-frames'
-import { codexCommandOutlivesTurn } from './codex-command-lifecycle'
 import { readRecord, readString } from './codex-item-field-readers'
 import { readCodexThreadItem } from './codex-structured-item-translation'
 import { MAX_CODEX_ITEM_STREAM_METADATA_BYTES } from './codex-item-stream-retention'
+import type { CodexAbandonedCommand } from './codex-prompt-registry'
 
 const MAX_SETTLED_COMMANDS = 128
 const MAX_DESCRIPTION_CHARS = 512
 
 type Command = { threadId: string; task: AgentSessionBackgroundTask; bytes: number }
 
+/** A command process starting, or ending: it exited, its thread closed, or the session ended. */
+export type CodexBackgroundCommandChange =
+  | { type: 'started'; threadId: string; task: AgentSessionBackgroundTask }
+  | { type: 'ended'; threadId: string; taskId: string }
+
 /** The label's reserved share of the description. Reserved, not merely capped:
  *  a label free to spend the whole budget clips away the command it qualifies,
  *  leaving a command row naming an agent and no command — the failure this
@@ -65,35 +70,37 @@ export class CodexBackgroundCommandTracker {
     )
   }
 
-  observe(event: CodexBackgroundTaskEvent): void {
+  observe(event: CodexBackgroundTaskEvent): CodexBackgroundCommandChange | null {
     const parsed = this.parse(event)
     if (!parsed || this.settled.has(parsed.key)) {
-      return
+      return null
     }
     const { key, command, completed } = parsed
-    const existing = this.commands.get(key)
     if (completed) {
-      if (existing) {
-        this.liveBytes -= existing.bytes
-        this.commands.delete(key)
-      }
-      const bytes = Buffer.byteLength(key, 'utf8') + 256
-      if (this.liveBytes + bytes <= this.maxMetadataBytes) {
-        this.settled.set(key, bytes)
-        this.settledBytes += bytes
-      }
-      this.trimSettled()
-      return
+      return this.end(key)
     }
-    if (existing) {
-      return
+    if (this.commands.has(key)) {
+      return null
     }
     if (this.liveBytes + command.bytes > this.maxMetadataBytes) {
       throw new Error('Codex command metadata was not admitted before observation')
     }
     this.commands.set(key, command)
     this.liveBytes += command.bytes
     this.trimSettled()
+    return { type: 'started', threadId: command.threadId, task: command.task }
+  }
+
+  /** The thread closed: Codex stops its processes first, so none of them can report an exit. */
+  endThread(threadId: string): CodexBackgroundCommandChange[] {
+    return [...this.commands]
+      .filter(([, command]) => command.threadId === threadId)
+      .flatMap(([key]) => this.end(key) ?? [])
+  }
+
+  /** Its approval went unanswered until its turn ended, so its process never started. */
+  endUnapproved(command: CodexAbandonedCommand): CodexBackgroundCommandChange | null {
+    return this.end(JSON.stringify([command.threadId, command.itemId]))
   }
 
   tasks(
@@ -113,11 +120,45 @@ export class CodexBackgroundCommandTracker {
       })
   }
 
-  clear(): void {
+  /** The live commands one thread launched, as the strip would publish them. */
+  threadTasks(threadId: string): AgentSessionBackgroundTask[] {
+    return [...this.commands.values()]
+      .filter((command) => command.threadId === threadId)
+      .map((command) => command.task)
+  }
+
+  /** The session ended, and every command with it. */
+  clear(): CodexBackgroundCommandChange[] {
+    const ended = [...this.commands.values()].map(
+      ({ threadId, task }): CodexBackgroundCommandChange => ({
+        type: 'ended',
+        threadId,
+        taskId: task.id
+      })
+    )
     this.commands.clear()
     this.settled.clear()
     this.liveBytes = 0
     this.settledBytes = 0
+    return ended
+  }
+
+  /** Retires the key so a replayed frame cannot start the command again. */
+  private end(key: string): CodexBackgroundCommandChange | null {
+    const existing = this.commands.get(key)
+    if (existing) {
+      this.liveBytes -= existing.bytes
+      this.commands.delete(key)
+    }
+    const bytes = Buffer.byteLength(key, 'utf8') + 256
+    if (this.liveBytes + bytes <= this.maxMetadataBytes) {
+      this.settled.set(key, bytes)
+      this.settledBytes += bytes
+    }
+    this.trimSettled()
+    return existing
+      ? { type: 'ended', threadId: existing.threadId, taskId: existing.task.id }
+      : null
   }
 
   private trimSettled(): void {
@@ -140,8 +181,10 @@ export class CodexBackgroundCommandTracker {
     if (event.method !== 'item/started' && event.method !== 'item/completed') {
       return null
     }
+    // Any command may outlive its turn; `source` says only how Codex launched it. A stdin write
+    // starts no process: it reaches one already tracked.
     const item = readCodexThreadItem(readRecord(event.params).item)
-    if (!item || !codexCommandOutlivesTurn(item)) {
+    if (item?.type !== 'commandExecution' || item.source === 'unifiedExecInteraction') {
       return null
     }
     const key = JSON.stringify([event.threadId, item.id])

src/main/codex/codex-background-task-frames.ts

@@ -7,6 +7,7 @@ import {
 import { codexChildTurnState } from './codex-subagent-executions'
 import { readRecord } from './codex-item-field-readers'
 import { readCodexThreadItem } from './codex-structured-item-translation'
+import { readCodexProviderVerdict } from './codex-structured-journal-provider-verdicts'
 import { readCodexTurnId } from './codex-structured-thread-facts'
 
 export type CodexBackgroundTaskFrame =
@@ -15,24 +16,59 @@ export type CodexBackgroundTaskFrame =
       agentThreadId: string
       label: string | null
       parentTurnId: string | null | undefined
+      /** The reporting thread, for a `started` activity: the agent that spawned the child. */
+      spawnerThreadId: string | undefined
     }
   | {
       kind: 'turn'
       threadId: string
       turnId: string
       state: NativeChatSubagentState
     }
+  | {
+      /** A child turn that ended with no `turn/completed`. No `turnId`: the one it is running. */
+      kind: 'turn-ended'
+      threadId: string
+      turnId: string | null
+      state: CodexChildTurnEnding
+    }
+
+type CodexChildTurnEnding = Extract<NativeChatSubagentState, 'failed' | 'unverifiable'>
 
 export type CodexBackgroundTaskEvent = {
   method: string
   threadId: string
   params: unknown
 }
 
+/**
+ * The two ways Codex ends a child's turn without `turn/completed`. An `error` it will not retry is
+ * that turn's own end: the verdict the transcript settles the same turn on. A closed thread ran
+ * its last turn, and Codex never said how it went. A `systemError` status is neither: Codex raises
+ * it for errors that leave the turn running too (a refused steer), and a turn one ends also
+ * carries the `error`.
+ */
+function readCodexChildTurnEnding(
+  event: CodexBackgroundTaskEvent
+): CodexBackgroundTaskFrame | null {
+  if (readCodexProviderVerdict(event.method, event.params) === 'turn-failed') {
+    const turnId = readCodexTurnId(event.params)
+    return { kind: 'turn-ended', threadId: event.threadId, turnId, state: 'failed' }
+  }
+  return event.method === 'thread/closed'
+    ? { kind: 'turn-ended', threadId: event.threadId, turnId: null, state: 'unverifiable' }
+    : null
+}
+
 export function readCodexBackgroundTaskFrame(
   event: CodexBackgroundTaskEvent,
   primaryThreadId: string
 ): CodexBackgroundTaskFrame | null {
+  // The session's own turn ends through the journal's turn boundaries, never here.
+  const ending = event.threadId === primaryThreadId ? null : readCodexChildTurnEnding(event)
+  if (ending) {
+    return ending
+  }
   if (event.method === 'turn/started' || event.method === 'turn/completed') {
     const turnId = readCodexTurnId(event.params)
     if (turnId === null) {
@@ -67,6 +103,8 @@ export function readCodexBackgroundTaskFrame(
     parentTurnId:
       activity.kind === 'started' || activity.kind === 'interacted'
         ? readCodexTurnId(event.params)
-        : undefined
+        : undefined,
+    // Only `started` names the spawner: other kinds ride whichever agent acted.
+    spawnerThreadId: activity.kind === 'started' ? event.threadId : undefined
   }
 }

src/main/codex/codex-background-task-tracker.ts

@@ -2,25 +2,50 @@ import type {
   AgentSessionBackgroundTask,
   AgentSessionBackgroundTaskState
 } from '../../shared/agent-session-wire'
+import type { AgentChildWorkEvidence } from '../../shared/agent-status-child-work-evidence'
 import {
   readCodexBackgroundTaskFrame,
   type CodexBackgroundTaskEvent
 } from './codex-background-task-frames'
 import { CodexSubagentExecutions } from './codex-subagent-executions'
 import { CodexBackgroundCommandTracker } from './codex-background-command-tracker'
+import { CodexChildWorkEvidence } from './codex-child-work-evidence'
+import type { CodexAbandonedCommand } from './codex-prompt-registry'
+import type { CodexStructuredSessionAdapterDeps } from './codex-structured-session-state'
 import { boundSubagentField } from './codex-subagent-group-body'
 
+/** Where a session's child-work evidence goes, and the host clock that stamps it. */
+export type CodexChildWorkSink = {
+  deliver: (evidence: AgentChildWorkEvidence[]) => void
+  now: () => number
+}
+
+export function codexChildWorkSink(
+  sessionId: string,
+  deps: Pick<CodexStructuredSessionAdapterDeps, 'onChildWorkEvidence' | 'now'>
+): CodexChildWorkSink {
+  return {
+    deliver: (evidence) => deps.onChildWorkEvidence?.(sessionId, evidence),
+    now: () => deps.now?.() ?? Date.now()
+  }
+}
+
 /** Projects the same child execution facts the durable roster consumes. */
 export class CodexBackgroundTaskTracker {
   private publishedFingerprint = '[]'
   private publishedState: AgentSessionBackgroundTaskState | null = null
   private readonly commands: CodexBackgroundCommandTracker
+  private readonly childWork: CodexChildWorkEvidence
 
   constructor(
     private readonly primaryThreadId: string,
-    private readonly executions = new CodexSubagentExecutions()
+    private readonly executions = new CodexSubagentExecutions(),
+    private readonly childWorkSink?: CodexChildWorkSink
   ) {
     this.commands = new CodexBackgroundCommandTracker(primaryThreadId)
+    this.childWork = new CodexChildWorkEvidence(primaryThreadId, executions, (threadId) =>
+      this.commands.threadTasks(threadId)
+    )
   }
 
   get state(): AgentSessionBackgroundTaskState | null {
@@ -32,20 +57,38 @@ export class CodexBackgroundTaskTracker {
     return this.commands.canObserve(event)
   }
 
-  observe(event: CodexBackgroundTaskEvent): boolean {
+  /** `unapproved`: commands whose approval the journal dropped with this frame's turn ending. */
+  observe(
+    event: CodexBackgroundTaskEvent,
+    unapproved: readonly CodexAbandonedCommand[] = []
+  ): boolean {
     const itemEvent = event.method === 'item/started' || event.method === 'item/completed'
-    if (itemEvent) {
-      this.commands.observe(event)
-    }
+    const command = itemEvent ? this.commands.observe(event) : null
+    const commands = [
+      ...unapproved.flatMap((abandoned) => this.commands.endUnapproved(abandoned) ?? []),
+      ...(event.method === 'thread/closed'
+        ? this.commands.endThread(event.threadId)
+        : command
+          ? [command]
+          : [])
+    ]
     const frame = readCodexBackgroundTaskFrame(event, this.primaryThreadId)
-    if (!frame) {
-      return itemEvent ? this.refresh() : false
-    }
-    if (frame.kind === 'subagent') {
-      this.executions.register(frame.agentThreadId, frame.label, frame.parentTurnId)
-    } else if (frame.threadId !== this.primaryThreadId) {
+    if (frame?.kind === 'subagent') {
+      this.executions.register(
+        frame.agentThreadId,
+        frame.label,
+        frame.parentTurnId,
+        frame.spawnerThreadId
+      )
+    } else if (frame?.kind === 'turn-ended') {
+      this.executions.endTurn(frame.threadId, frame.turnId, frame.state)
+    } else if (frame && frame.threadId !== this.primaryThreadId) {
       this.executions.observeTurn(frame.threadId, frame.turnId, frame.state)
     }
+    this.childWork.observe(event, frame, commands)
+    if (!frame) {
+      return itemEvent || commands.length > 0 ? this.refresh() : false
+    }
     // A primary-turn frame only prompts a republish: turn end reveals children,
     // it never settles them. Codex `spawn_agent` children keep reporting well
     // past their parent turn, so nothing here may sweep the roster.
@@ -54,10 +97,25 @@ export class CodexBackgroundTaskTracker {
 
   clear(): boolean {
     this.executions.clear()
-    this.commands.clear()
+    this.childWork.clear(this.commands.clear())
     return this.refresh()
   }
 
+  /** Everything the frames observed since the last drain said about the session's child work. */
+  drainChildWorkEvidence(observedAt: number): AgentChildWorkEvidence[] {
+    return this.childWork.drain(observedAt)
+  }
+
+  /** Hand the pending evidence to the host. Callers run this after the journal wrote the frame
+   *  and the parent's own row republished, so a child record never lands ahead of either. */
+  publishChildWork(): void {
+    // Drained even with no sink, so undelivered evidence never accumulates.
+    const evidence = this.drainChildWorkEvidence(this.childWorkSink?.now() ?? Date.now())
+    if (evidence.length > 0) {
+      this.childWorkSink?.deliver(evidence)
+    }
+  }
+
   private tasks(): AgentSessionBackgroundTask[] {
     const children = this.executions.workingChildren()
     const agents: AgentSessionBackgroundTask[] = children.map((child, index) => ({