@namzu/sdk 43.0.0 → 44.1.0

package/dist/manager/agent/lifecycle.js

@@ -1,11 +1,12 @@
+import { rm } from 'node:fs/promises';
 import { AGENT_MANAGER_DEFAULTS } from '../../constants/agent/index.js';
 import { EMPTY_TOKEN_USAGE } from '../../constants/limits.js';
 import { GENAI } from '../../constants/telemetry/index.js';
 import { DelegationCapacityExceeded, } from '../../session/handoff/capacity.js';
+import { DiskSessionLog, InMemorySessionLog, } from '../../store/session-log/index.js';
 import { isTerminalAgentTaskState } from '../../types/agent/task.js';
 import { NamzuError } from '../../types/errors/index.js';
-import { RunCancelled } from '../../types/run/cancel-cause.js';
-import { RUN_EVENT_SCHEMA_VERSION } from '../../types/run/schema-version.js';
+import { TurnCancelled } from '../../types/session/cancel-cause.js';
 import { createChildAbortController } from '../../utils/abort.js';
 import { ZERO_COST } from '../../utils/cost.js';
 import { toErrorMessage } from '../../utils/error.js';
@@ -14,6 +15,7 @@ import { SCOPE_ATTRIBUTE } from '../../utils/log/types.js';
 import { resolveLogger } from '../../utils/logger.js';
 import { requireOpenProject } from '../project/lifecycle.js';
 import { resolveTopicManager } from '../topic/dependency.js';
+import { registerChildSessionLog, writeChildSessionMeta } from './child-session.js';
 /** Internal backpressure: the parent's unmeasured request owns its budget until its receipt. */
 class ParentBudgetRequestPending extends Error {
 }
@@ -90,7 +92,7 @@ export class AgentManager {
             state: 'pending',
             pendingMessages: [],
             createdAt: Date.now(),
-            runEventListener: listener,
+            sessionEventListener: listener,
         };
         this.instances.set(task.taskId, task);
         const onAbort = () => {
@@ -122,7 +124,8 @@ export class AgentManager {
         try {
             await listener?.({
                 type: 'agent_pending',
-                runId: context.parentRunId,
+                sessionId: context.parentSessionId,
+                turnId: context.parentTurnId,
                 taskId: task.taskId,
                 parentAgentId: context.parentAgentId,
                 childAgentId: options.agentId,
@@ -207,8 +210,11 @@ export class AgentManager {
             return;
         task.childAbortController.abort(reason);
         const error = toErrorMessage(reason);
+        // The child never got a session, so its result names the parent turn
+        // that asked for it.
         task.result = {
-            runId: entry.context.parentRunId,
+            sessionId: entry.context.parentSessionId,
+            turnId: entry.context.parentTurnId,
             status: 'failed',
             usage: { ...EMPTY_TOKEN_USAGE },
             cost: { ...ZERO_COST },
@@ -220,9 +226,10 @@ export class AgentManager {
         task.state = 'failed';
         task.completedAt = Date.now();
         this.emit({ type: 'failed', taskId: task.taskId, error });
-        this.emitRunEvent(task, {
+        this.emitSessionEvent(task, {
             type: 'agent_failed',
-            runId: entry.context.parentRunId,
+            sessionId: entry.context.parentSessionId,
+            turnId: entry.context.parentTurnId,
             taskId: task.taskId,
             error,
         });
@@ -241,8 +248,8 @@ export class AgentManager {
         // A shell this task has to itself, not the registry's shared instance.
         //
         // `resolve` returns one `typedAgent` per registered id, and an instance
-        // refuses a second concurrent `run` because it holds per-run state. So
-        // a fan-out naming the same `agent_id` four times drove four runs at one
+        // refuses a second concurrent `run` because it holds per-turn state. So
+        // a fan-out naming the same `agent_id` four times drove four turns at one
         // shell: one worked and three died with `ConcurrentInvocationError` —
         // while `create_task`'s own description tells the model that this
         // fan-out is the thing to do. Observed live on 12.0.1, four launches,
@@ -258,7 +265,7 @@ export class AgentManager {
         // the agent. The shell was the only shared thing left.
         const definitionForSpawn = this.registry.getOrThrow(options.agentId);
         const sharedAgent = definitionForSpawn.typedAgent;
-        const agent = definitionForSpawn.createAgent?.() ?? sharedAgent.forRun?.() ?? sharedAgent;
+        const agent = definitionForSpawn.createAgent?.() ?? sharedAgent.forTurn?.() ?? sharedAgent;
         context.parentAbortController.signal.throwIfAborted();
         // Reserve synchronously before provisioning yields. The authority is shared
         // across managers and nested sessions, while the session lock below only
@@ -334,7 +341,7 @@ export class AgentManager {
             // A check that cannot fail reads as a safeguard and is not one. The
             // predicate is exported for the callers that do face an actor they
             // did not construct: an audit walking a subtree, a host asking
-            // whether one run's actor is contained by another's.
+            // whether one turn's actor is contained by another's.
             //
             // Union, not replace, and not "innermost wins": a descendant may
             // narrow further and may never widen.
@@ -342,7 +349,8 @@ export class AgentManager {
             const ownDenies = options.toolScope?.deny ?? [];
             const resolvedDenies = [...new Set([...inheritedDenies, ...ownDenies])];
             const childContext = {
-                parentRunId: context.parentRunId,
+                parentSessionId: context.parentSessionId,
+                parentTurnId: context.parentTurnId,
                 parentAgentId: context.parentAgentId,
                 parentAbortController: context.parentAbortController,
                 depth: context.depth + 1,
@@ -354,6 +362,7 @@ export class AgentManager {
                 projectId: context.projectId,
                 parentActor: childParentActor,
                 ...(resolvedDenies.length > 0 ? { toolDenies: resolvedDenies } : {}),
+                ...(context.childStorage ? { childStorage: context.childStorage } : {}),
             };
             agentTask = Object.assign(queuedTask ?? {}, {
                 taskId,
@@ -364,7 +373,7 @@ export class AgentManager {
                 state: 'pending',
                 pendingMessages: queuedTask?.pendingMessages ?? [],
                 createdAt: queuedTask?.createdAt ?? Date.now(),
-                runEventListener: listener,
+                sessionEventListener: listener,
             });
             childAbortController.signal.throwIfAborted();
             this.instances.set(taskId, agentTask);
@@ -383,7 +392,8 @@ export class AgentManager {
                 if (!queuedTask)
                     await listener({
                         type: 'agent_pending',
-                        runId: context.parentRunId,
+                        sessionId: context.parentSessionId,
+                        turnId: context.parentTurnId,
                         taskId,
                         parentAgentId: context.parentAgentId,
                         childAgentId: options.agentId,
@@ -398,14 +408,25 @@ export class AgentManager {
                     depth: spawnRecord.childDepth,
                 };
                 await listener({
-                    type: 'subsession_spawned',
-                    runId: context.parentRunId,
-                    subSessionId: spawnRecord.subSessionId,
-                    parentSessionId: spawnRecord.parentSessionId,
-                    spawnedBy: context.parentActor,
+                    type: 'child_session_spawned',
+                    sessionId: spawnRecord.parentSessionId,
+                    turnId: spawnRecord.parentTurnId,
+                    childSessionId: spawnRecord.childSessionId,
+                    toolCallId: spawnToolCallId(taskId),
+                    kind: 'agent_spawn',
+                    description: describeSpawn(options),
+                    path: childLogPath(spawnRecord.childSessionId),
+                    ...(options.workflow
+                        ? {
+                            batch: {
+                                batchId: options.workflow,
+                                name: options.workflow,
+                                ...(options.phase ? { phase: options.phase } : {}),
+                            },
+                        }
+                        : {}),
+                    budgetAccountId: childBudget.accountId,
                     lineage,
-                    schemaVersion: RUN_EVENT_SCHEMA_VERSION,
-                    at: new Date(),
                 });
             }
             this.log.info('Agent task pending', {
@@ -426,7 +447,9 @@ export class AgentManager {
                         ...(context.factoryOptions ?? {}),
                         tokenBudget: allocatedTokens,
                         timeoutMs: options.budgetAllocation?.timeoutMs ?? this.config.childTimeoutMs,
-                        parentRunId: context.parentRunId,
+                        sessionId: spawnRecord.childSessionId,
+                        parentSessionId: spawnRecord.parentSessionId,
+                        parentTurnId: spawnRecord.parentTurnId,
                         depth: context.depth + 1,
                         ...options.configOverrides,
                     })),
@@ -454,7 +477,7 @@ export class AgentManager {
                 //
                 // Without this every delegated child fell through to
                 // `autoApproveHandler`, so a host's "ask before acting" gate
-                // covered the top-level run and nothing it delegated.
+                // covered the top-level turn and nothing it delegated.
                 const inheritedHandler = options.configOverrides?.resumeHandler ?? context.resumeHandler;
                 if (inheritedHandler)
                     childConfig.resumeHandler = inheritedHandler;
@@ -509,17 +532,18 @@ export class AgentManager {
                     topicId: context.topicId,
                     projectId: context.projectId,
                     tenantId: context.tenantId,
-                    parentRunId: context.parentRunId,
+                    parentSessionId: spawnRecord.parentSessionId,
+                    parentTurnId: spawnRecord.parentTurnId,
                     depth: context.depth + 1,
                     resumeHandler: options.configOverrides?.resumeHandler ?? context.resumeHandler,
                 };
             }
-            // The screens in force for the parent run, stamped onto the child
+            // The screens in force for the parent session, stamped onto the child
             // the way the trace parent and the review handler are — and after
             // both branches, because the bare-config branch builds its whole
             // config by hand and would otherwise omit this one field.
             //
-            // A child run builds its own executor, which installs
+            // A child session builds its own executor, which installs
             // `DEFAULT_TOOL_RESULT_GUARDRAILS` when nothing said otherwise — so
             // without this a parent that turned the screens off, or exempted a
             // tool it knows, had that decision revert the moment it delegated,
@@ -537,8 +561,9 @@ export class AgentManager {
             // Lineage is assigned by the spawning manager, not proposed by the
             // child definition. A fixed configBuilder can ignore its inputs and
             // configOverrides is caller-authored; neither may turn a child back
-            // into depth zero or attach it to a different parent run.
-            childConfig.parentRunId = context.parentRunId;
+            // into depth zero or attach it to a different parent session.
+            childConfig.parentSessionId = spawnRecord.parentSessionId;
+            childConfig.parentTurnId = spawnRecord.parentTurnId;
             childConfig.depth = context.depth + 1;
             childConfig.budget = childBudget;
             // The reservation is the execution ceiling, regardless of a builder's
@@ -574,7 +599,7 @@ export class AgentManager {
             // Narrowing only: the deny list is SUBTRACTED from whatever the child
             // would otherwise have. `allowedTools` absent means "every registered
             // tool", so a deny with no existing allow-list has to be resolved
-            // against the registry at the run rather than here — which `query()`
+            // against the registry at the turn rather than here — which `query()`
             // does, and which is why this appends to `deniedTools` rather than
             // synthesising an allow-list.
             if (resolvedDenies.length > 0) {
@@ -584,6 +609,26 @@ export class AgentManager {
             }
             if (options.personaOverride)
                 childConfig.persona = options.personaOverride;
+            // Where the child session lives, stamped after the builder for the
+            // same reason as everything above: a `configBuilder` cannot forward
+            // a field it was never told about.
+            //
+            // A parent held in memory gives its child a fresh in-memory log (a
+            // log is one session's, never shared), and its checkpoint store
+            // when it named one, so the child writes nothing under
+            // `NAMZU_HOME`. Otherwise, with a layout known, the child's log goes
+            // under its parent (`<parent>/subagents/<child-id>.jsonl`) with its
+            // meta document beside it. A child config that names a session log
+            // or paths of its own chose where it goes, and keeps it.
+            const childLog = await this.placeChildSession(spawnRecord, childConfig, context, options, taskId);
+            if (childLog) {
+                await this.startChildSessionLog(childLog, spawnRecord, context, options, taskId, {
+                    id: agent.metadata.id,
+                    name: agent.metadata.name,
+                });
+                childConfig.sessionLog = childLog;
+                spawnRecord.releaseLog = registerChildSessionLog(childLog);
+            }
             // Outside the branch, like the scope above it and for the same reason:
             // a `configBuilder` cannot forward a field it was never told about.
             //
@@ -613,6 +658,8 @@ export class AgentManager {
                 catch (writeError) {
                     failure = writeError;
                 }
+                // The child's turn is over either way; its parent hears so first.
+                await this.settleChildSession(runningTask, spawnRecord, runningTask.state === 'canceled' ? 'cancelled' : 'failed');
                 // Cancellation may already have published a terminal handle. Its
                 // invocation has only NOW stopped; release the persisted edge here.
                 if (!this.instances.has(taskId) || isTerminalAgentTaskState(runningTask.state)) {
@@ -624,7 +671,7 @@ export class AgentManager {
                 .finally(() => {
                 this.executingTasks.delete(taskId);
                 if (!this.instances.has(taskId))
-                    this.spawnRecords.delete(taskId);
+                    this.dropSpawnRecord(taskId);
                 this.pumpAdmissions(options.parentSessionId);
             })
                 .catch((error) => this.log.warn('Child cleanup failed', {
@@ -658,9 +705,10 @@ export class AgentManager {
             const error = toErrorMessage(reason);
             this.emit({ type: 'failed', taskId: agentTask.taskId, error });
             try {
-                await agentTask.runEventListener?.({
+                await agentTask.sessionEventListener?.({
                     type: 'agent_failed',
-                    runId: agentTask.context.parentRunId,
+                    sessionId: agentTask.context.parentSessionId,
+                    turnId: agentTask.context.parentTurnId,
                     taskId: agentTask.taskId,
                     error,
                 });
@@ -675,7 +723,8 @@ export class AgentManager {
         this.clearEvictionTimer(agentTask.taskId);
         if (retainHandle) {
             agentTask.result ??= {
-                runId: agentTask.context.parentRunId,
+                sessionId: agentTask.context.parentSessionId,
+                turnId: agentTask.context.parentTurnId,
                 status: 'failed',
                 usage: { ...EMPTY_TOKEN_USAGE },
                 cost: { ...ZERO_COST },
@@ -689,11 +738,20 @@ export class AgentManager {
         }
         else
             this.instances.delete(agentTask.taskId);
-        this.spawnRecords.delete(agentTask.taskId);
+        this.dropSpawnRecord(agentTask.taskId);
         this.resolveCompletionCallbacks(agentTask.taskId);
         await this.rollbackSpawnResources(spawnRecord);
     }
     async rollbackSpawnResources(spawnRecord) {
+        spawnRecord.releaseLog?.();
+        // A child that never started leaves no meta document naming it: the
+        // session it describes is being deleted below.
+        if (spawnRecord.placement) {
+            await rm(spawnRecord.placement.metaPath, { force: true }).catch((err) => this.log.warn('Unstarted child meta removal failed', {
+                'namzu.store.path': spawnRecord.placement?.metaPath,
+                'exception.message': toErrorMessage(err),
+            }));
+        }
         await this.disposeChildWorkspace(spawnRecord);
         try {
             // The edge must be removed before its child: stores reject deletion
@@ -708,6 +766,125 @@ export class AgentManager {
             });
         }
     }
+    /** Forget a spawn record, and take its child's log out of the process-local lookup. */
+    dropSpawnRecord(taskId) {
+        this.spawnRecords.get(taskId)?.releaseLog?.();
+        this.spawnRecords.delete(taskId);
+    }
+    /** The parent session's place in the tree: its ancestors, root first. */
+    parentLocator(spawnRecord) {
+        return {
+            sessionId: spawnRecord.parentSessionId,
+            ancestors: spawnRecord.ancestry.slice(0, -1),
+        };
+    }
+    /** The meta document for a placed child, as it stands at spawn. */
+    childMeta(spawnRecord) {
+        const placement = spawnRecord.placement;
+        if (!placement)
+            throw new Error('A child session placed by no layout has no meta document');
+        return {
+            v: 1,
+            kind: 'child-session',
+            sessionId: spawnRecord.childSessionId,
+            parentSessionId: spawnRecord.parentSessionId,
+            parentTurnId: spawnRecord.parentTurnId,
+            rootSessionId: spawnRecord.rootSessionId,
+            depth: spawnRecord.childDepth,
+            toolCallId: placement.toolCallId,
+            agentType: placement.agentType,
+            description: placement.description,
+            status: 'running',
+            createdAt: placement.createdAt,
+        };
+    }
+    /**
+     * Decide where a child session's log lives, and write its meta document
+     * when this manager places it.
+     *
+     * - A config that names a `sessionLog` keeps it; one that names `paths`
+     *   gets its log in that layout, under its parent.
+     * - A parent held in memory gives a fresh `InMemorySessionLog`, plus its
+     *   checkpoint store when it named one.
+     * - Otherwise, with {@link AgentManagerDeps.paths} known, the log goes to
+     *   `<parent-session-dir>/subagents/<child-id>.jsonl`, nested under every
+     *   ancestor, with `<child-id>.meta.json` beside it.
+     *
+     * Returns the log the child should append to, or `undefined` to leave
+     * the child's config as it is.
+     */
+    async placeChildSession(spawnRecord, childConfig, context, options, taskId) {
+        if (childConfig.sessionLog !== undefined)
+            return undefined;
+        const inherited = context.childStorage;
+        if (inherited?.kind === 'memory' && childConfig.paths === undefined) {
+            if (inherited.checkpointStore && childConfig.checkpointStore === undefined) {
+                childConfig.checkpointStore = inherited.checkpointStore;
+            }
+            return new InMemorySessionLog({ sessionId: spawnRecord.childSessionId });
+        }
+        // The parent's own layout first: a child's log nests under its
+        // parent's session directory, so it must be the parent's layout.
+        const paths = childConfig.paths ??
+            (inherited?.kind === 'disk' ? inherited.paths : undefined) ??
+            this.deps.paths;
+        if (!paths)
+            return undefined;
+        childConfig.paths = paths;
+        const parent = this.parentLocator(spawnRecord);
+        spawnRecord.placement = {
+            paths,
+            metaPath: paths.subagentMeta(parent, spawnRecord.childSessionId),
+            createdAt: new Date().toISOString(),
+            toolCallId: spawnToolCallId(taskId),
+            agentType: options.agentId,
+            description: describeSpawn(options),
+        };
+        await writeChildSessionMeta(spawnRecord.placement.metaPath, this.childMeta(spawnRecord));
+        return DiskSessionLog.at(paths, {
+            sessionId: spawnRecord.childSessionId,
+            ancestors: spawnRecord.ancestry,
+        });
+    }
+    /**
+     * Open a child session placed by this manager with its `session_started`,
+     * naming where it sits in the tree (`parent`: the spawning session, turn
+     * and tool call, the root session, the depth, and the kind of spawn).
+     *
+     * Written here, before the child sessions, because only the manager knows all
+     * of it: a child's config carries its parent session and turn but not the
+     * tool call or the root. The child's own turn then finds the log started
+     * and appends after it. A log that already has records is left alone.
+     */
+    async startChildSessionLog(log, spawnRecord, context, options, taskId, agent) {
+        const lease = await log.claim({ holder: `namzu:agent-manager:${taskId}`, ttlMs: 30_000 });
+        if (lease === null) {
+            throw new Error(`Child session ${spawnRecord.childSessionId} is already leased`);
+        }
+        try {
+            if ((await log.head()) !== null)
+                return;
+            await log.append(lease, {
+                type: 'session_started',
+                projectId: context.projectId,
+                tenantId: spawnRecord.tenantId,
+                topicId: context.topicId,
+                cwd: options.input.workingDirectory ?? process.cwd(),
+                agent: { id: agent.id, name: agent.name, type: options.agentId },
+                parent: {
+                    sessionId: spawnRecord.parentSessionId,
+                    turnId: spawnRecord.parentTurnId,
+                    toolCallId: spawnToolCallId(taskId),
+                    rootSessionId: spawnRecord.rootSessionId,
+                    depth: spawnRecord.childDepth,
+                    kind: 'agent_spawn',
+                },
+            });
+        }
+        finally {
+            await log.release(lease);
+        }
+    }
     cancel(taskId, cause) {
         if (this.cancelingTasks.has(taskId))
             return;
@@ -716,23 +893,23 @@ export class AgentManager {
             return;
         // Was the bare string `'canceled'`, which `abortReasonText` suppresses
         // by name — its docblock cites this exact call site — so the child's
-        // run saw a cancellation with no attributable origin at all.
+        // turn saw a cancellation with no attributable origin at all.
         // Abort listeners run synchronously. A pending task's parent observer
         // must not reenter this method and replace an explicit user's cause.
         this.cancelingTasks.add(taskId);
         try {
-            agentTask.childAbortController.abort(cause ? new RunCancelled(cause) : undefined);
+            agentTask.childAbortController.abort(cause ? new TurnCancelled(cause) : undefined);
             this.markCanceled(taskId, cause);
         }
         finally {
             this.cancelingTasks.delete(taskId);
         }
     }
-    cancelAll(parentRunId, cause = 'parent') {
+    cancelAll(parentSessionId, cause = 'parent') {
         // `'parent'` by default, because this call site IS a parent
         // abandoning its children. `AbstractAgent.cancel` takes no default
         // for the opposite reason: its caller could be anyone.
-        for (const agentTask of this.listByParent(parentRunId)) {
+        for (const agentTask of this.listByParent(parentSessionId)) {
             this.cancel(agentTask.taskId, cause);
         }
     }
@@ -785,8 +962,8 @@ export class AgentManager {
     getSpawnRecord(taskId) {
         return this.spawnRecords.get(taskId);
     }
-    listByParent(parentRunId) {
-        return Array.from(this.instances.values()).filter((t) => t.context.parentRunId === parentRunId);
+    listByParent(parentSessionId) {
+        return Array.from(this.instances.values()).filter((t) => t.context.parentSessionId === parentSessionId);
     }
     listActive() {
         return Array.from(this.instances.values()).filter((t) => !isTerminalAgentTaskState(t.state));
@@ -811,7 +988,7 @@ export class AgentManager {
                 this.clearEvictionTimer(taskId);
                 this.instances.delete(taskId);
                 if (!this.executingTasks.has(taskId))
-                    this.spawnRecords.delete(taskId);
+                    this.dropSpawnRecord(taskId);
             }
         }
     }
@@ -828,7 +1005,8 @@ export class AgentManager {
             this.clearEvictionTimer(taskId);
         }
         // Every live child, not the children of one parent. This used to call
-        // `cancelAll('' as RunId)`, and `cancelAll` filters by parent run —
+        // `cancelAll` with an invented empty parent id, and `cancelAll` filters
+        // by parent —
         // no task has an empty parent, so it matched nothing and the lines
         // below then dropped every reference to work that was still running.
         for (const taskId of [...this.instances.keys()]) {
@@ -837,7 +1015,7 @@ export class AgentManager {
         this.instances.clear();
         for (const taskId of this.spawnRecords.keys())
             if (!this.executingTasks.has(taskId))
-                this.spawnRecords.delete(taskId);
+                this.dropSpawnRecord(taskId);
         this.listeners.length = 0;
     }
     /**
@@ -1004,7 +1182,7 @@ export class AgentManager {
             // deny-by-default cascade policy (Convention #5): `deleteSession`
             // throws when any subsession still references it, so the subsession
             // record must be removed first. No failed-subsession audit row is
-            // kept — the `subsession_spawned` run event never fired (we aborted
+            // kept — the `child_session_spawned` event never fired (we aborted
             // before `buildSpawnRecord`), so no observer is expecting one, and
             // leaving a `status: 'failed'` breadcrumb would be a dangling
             // record with no corresponding emission. The original `err` is the
@@ -1021,7 +1199,9 @@ export class AgentManager {
             childSessionId: childSession.id,
             tenantId: context.tenantId,
             parentSessionId: options.parentSessionId,
+            parentTurnId: context.parentTurnId,
             rootSessionId,
+            ancestry: parentAncestry,
             childDepth,
             workspaceRef,
         };
@@ -1036,16 +1216,18 @@ export class AgentManager {
         const spawnRecord = this.spawnRecords.get(agentTask.taskId);
         const childListener = this.wrapChildListener(listener, spawnRecord);
         const result = await agentTask.agent.run(input, childConfig, childListener);
-        agentTask.context.budget.bindRun(result.runId);
+        agentTask.context.budget.bindTurn(result.sessionId, result.turnId);
         agentTask.context.budget.settle(result.usage?.totalTokens);
         await agentTask.context.budget.flush();
         await this.finalizeChild(agentTask, result);
     }
     /**
-     * Wraps the parent listener so every event emitted from the child's run
-     * carries the session-hierarchy `lineage` + `schemaVersion: 2` stamp.
-     * Replaces the old `Object.assign({sourceAgentId, parentTaskId}, event)`
-     * loose-cast pattern entirely — the types now encode the linkage.
+     * Wraps the parent listener so every event relayed from the child session
+     * carries its `lineage`. The child's own `seq` is dropped: it is a
+     * position in the CHILD's log, and a parent listener keeping a reconnect
+     * cursor per session must not read it as one in the parent's. Replaces the
+     * old `Object.assign({sourceAgentId, parentTaskId}, event)` loose-cast
+     * pattern entirely — the types now encode the linkage.
      */
     wrapChildListener(listener, spawnRecord) {
         if (!listener)
@@ -1058,12 +1240,8 @@ export class AgentManager {
             depth: spawnRecord.childDepth,
         };
         return async (event) => {
-            const stamped = {
-                ...event,
-                lineage,
-                schemaVersion: RUN_EVENT_SCHEMA_VERSION,
-            };
-            await listener(stamped);
+            const { seq: _childSeq, ...relayed } = event;
+            await listener({ ...relayed, lineage });
         };
     }
     async finalizeChild(agentTask, result) {
@@ -1111,7 +1289,7 @@ export class AgentManager {
                 //
                 // It runs after the summary is sealed and the sub-session flipped
                 // to `idle`, so nothing the terminalization path reads is gone
-                // before it reads it. It also runs BEFORE the `subsession_idled`
+                // before it reads it. It also runs BEFORE the `child_session_idled`
                 // emission below: a listener cannot reach into the workspace from
                 // that event. Stated rather than hedged — no consumer does today,
                 // and holding a worktree open for a hypothetical one is what this
@@ -1125,34 +1303,59 @@ export class AgentManager {
                 });
             }
         }
-        // Emit subsession_idled event on success before marking the task
-        // completed — consumers expect the ordering `run_completed (child) →
-        // subsession_idled → run_completed (parent)` per §10.5.
-        if (spawnRecord && agentTask.runEventListener && result.status === 'completed') {
-            const lineage = {
-                parentSessionId: spawnRecord.parentSessionId,
-                rootSessionId: spawnRecord.rootSessionId,
-                depth: spawnRecord.childDepth,
-            };
+        if (spawnRecord)
+            await this.settleChildSession(agentTask, spawnRecord, result.status);
+        this.markCompleted(agentTask.taskId, result);
+    }
+    /**
+     * The child's turn is over: its meta document records how, and the
+     * parent hears `child_session_idled`, before the task is marked settled —
+     * consumers expect `turn_completed (child) → child_session_idled →
+     * turn_completed (parent)`.
+     *
+     * Idled on every outcome, not only success: the event says the child's
+     * turn ended and nothing is queued, which a failure is too. It is the
+     * parent writer's cue to append `child_session_ended`, read from the
+     * child's own terminal record (`childSessionEnded`).
+     */
+    async settleChildSession(agentTask, spawnRecord, status) {
+        if (spawnRecord.placement) {
             try {
-                await agentTask.runEventListener({
-                    type: 'subsession_idled',
-                    runId: agentTask.context.parentRunId,
-                    subSessionId: spawnRecord.subSessionId,
-                    parentSessionId: spawnRecord.parentSessionId,
-                    lineage,
-                    schemaVersion: RUN_EVENT_SCHEMA_VERSION,
-                    at: new Date(),
+                await writeChildSessionMeta(spawnRecord.placement.paths.subagentMeta(this.parentLocator(spawnRecord), spawnRecord.childSessionId), {
+                    ...this.childMeta(spawnRecord),
+                    status,
+                    endedAt: new Date().toISOString(),
                 });
             }
             catch (err) {
-                this.log.error('subsession_idled emission error', {
+                this.log.warn('Child session meta update failed', {
                     'namzu.task.id': agentTask.taskId,
                     'exception.message': toErrorMessage(err),
                 });
             }
         }
-        this.markCompleted(agentTask.taskId, result);
+        const listener = agentTask.sessionEventListener;
+        if (!listener)
+            return;
+        try {
+            await listener({
+                type: 'child_session_idled',
+                sessionId: spawnRecord.parentSessionId,
+                turnId: spawnRecord.parentTurnId,
+                childSessionId: spawnRecord.childSessionId,
+                lineage: {
+                    parentSessionId: spawnRecord.parentSessionId,
+                    rootSessionId: spawnRecord.rootSessionId,
+                    depth: spawnRecord.childDepth,
+                },
+            });
+        }
+        catch (err) {
+            this.log.error('child_session_idled emission error', {
+                'namzu.task.id': agentTask.taskId,
+                'exception.message': toErrorMessage(err),
+            });
+        }
     }
     markCompleted(taskId, result) {
         const agentTask = this.instances.get(taskId);
@@ -1162,9 +1365,10 @@ export class AgentManager {
         agentTask.completedAt = Date.now();
         this.updateState(taskId, 'completed');
         this.emit({ type: 'completed', taskId, result });
-        this.emitRunEvent(agentTask, {
+        this.emitSessionEvent(agentTask, {
             type: 'agent_completed',
-            runId: agentTask.context.parentRunId,
+            sessionId: agentTask.context.parentSessionId,
+            turnId: agentTask.context.parentTurnId,
             taskId,
             result,
         });
@@ -1176,8 +1380,12 @@ export class AgentManager {
         const agentTask = this.instances.get(taskId);
         if (!agentTask || isTerminalAgentTaskState(agentTask.state))
             return;
+        // The child's own turn when its budget was bound to one; the parent
+        // turn that asked for it otherwise.
+        const bound = agentTask.context.budget.turn;
         agentTask.result = {
-            runId: agentTask.context.budget.runId ?? agentTask.context.parentRunId,
+            sessionId: bound?.sessionId ?? agentTask.context.parentSessionId,
+            turnId: bound?.turnId ?? agentTask.context.parentTurnId,
             status: 'failed',
             usage: agentTask.context.budget.ownUsage,
             budget: agentTask.context.budget.summary(),
@@ -1190,9 +1398,10 @@ export class AgentManager {
         agentTask.completedAt = Date.now();
         this.updateState(taskId, 'failed');
         this.emit({ type: 'failed', taskId, error });
-        this.emitRunEvent(agentTask, {
+        this.emitSessionEvent(agentTask, {
             type: 'agent_failed',
-            runId: agentTask.context.parentRunId,
+            sessionId: agentTask.context.parentSessionId,
+            turnId: agentTask.context.parentTurnId,
             taskId,
             error,
         });
@@ -1226,7 +1435,7 @@ export class AgentManager {
      *
      * Called on every terminal path, success included. `has(backend)` before
      * `get(backend)` because the registry is deny-by-default and throws on an
-     * unknown kind — a driver deregistered mid-run must not turn cleanup into
+     * unknown kind — a driver deregistered mid-turn must not turn cleanup into
      * an exception on a child that already finished.
      *
      * Never throws. Disposal is cleanup, not part of the child's result: the
@@ -1260,9 +1469,10 @@ export class AgentManager {
         agentTask.completedAt = Date.now();
         this.updateState(taskId, 'canceled');
         this.emit({ type: 'canceled', taskId });
-        this.emitRunEvent(agentTask, {
+        this.emitSessionEvent(agentTask, {
             type: 'agent_canceled',
-            runId: agentTask.context.parentRunId,
+            sessionId: agentTask.context.parentSessionId,
+            turnId: agentTask.context.parentTurnId,
             taskId,
             ...(cause ? { cancelCause: cause } : {}),
         });
@@ -1293,7 +1503,7 @@ export class AgentManager {
         const timer = setTimeout(() => {
             this.instances.delete(taskId);
             if (!this.executingTasks.has(taskId))
-                this.spawnRecords.delete(taskId);
+                this.dropSpawnRecord(taskId);
             this.evictionTimers.delete(taskId);
             this.log.info('Agent task evicted', { 'namzu.agent.task_id': taskId });
         }, this.config.evictionMs);
@@ -1327,11 +1537,12 @@ export class AgentManager {
             }
         }
     }
-    emitRunEvent(agentTask, event) {
-        if (!agentTask.runEventListener)
+    emitSessionEvent(agentTask, event) {
+        const listener = agentTask.sessionEventListener;
+        if (!listener)
             return;
         const reportFailure = (error) => {
-            this.log.error('RunEvent emission error', {
+            this.log.error('SessionEvent emission error', {
                 'namzu.event.type': event.type,
                 'exception.message': toErrorMessage(error),
             });
@@ -1339,13 +1550,46 @@ export class AgentManager {
         try {
             // Terminal observation must not delay completion or leak a rejected
             // listener promise into the host as an unhandled rejection.
-            void Promise.resolve(agentTask.runEventListener(event)).catch(reportFailure);
+            void Promise.resolve(listener(event)).catch(reportFailure);
         }
         catch (error) {
             reportFailure(error);
         }
     }
 }
+/**
+ * The id `child_session_spawned` and the meta document name as the call that
+ * spawned the child.
+ *
+ * The provider's tool-call id does not reach this manager: neither
+ * `CreateTaskOptions` nor `SendMessageOptions` carries it. Until it does, the
+ * spawn's task id stands in, which is unique per spawn and is the id every
+ * `agent_*` event for this child already carries.
+ */
+function spawnToolCallId(taskId) {
+    return taskId;
+}
+/** Longest spawn description kept on the record. */
+const SPAWN_DESCRIPTION_MAX_CHARS = 200;
+/**
+ * One line saying what the child was asked to do: the first line of the last
+ * user message it was handed, or its agent id when there is none.
+ */
+function describeSpawn(options) {
+    for (let i = options.input.messages.length - 1; i >= 0; i--) {
+        const message = options.input.messages[i];
+        if (message?.role !== 'user' || typeof message.content !== 'string')
+            continue;
+        const line = message.content.trim().split('\n', 1)[0]?.trim() ?? '';
+        if (line.length > 0)
+            return line.slice(0, SPAWN_DESCRIPTION_MAX_CHARS);
+    }
+    return options.agentId;
+}
+/** The child's log, relative to the parent's session directory. */
+function childLogPath(childSessionId) {
+    return `subagents/${childSessionId}.jsonl`;
+}
 /**
  * The display grouping a host supplied at spawn, in the shape `agent_pending`
  * carries it.