@namzu/sdk 12.1.0 → 13.0.0

package/dist/types/hitl/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/hitl/index.ts"],"names":[],"mappings":"AA0OA,MAAM,UAAU,kBAAkB,CAAC,OAA4B;IAC9D,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;QACtB,KAAK,eAAe;YACnB,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC,CAAA;QACnD,KAAK,aAAa;YACjB,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC,CAAA;QACpD,KAAK,sBAAsB;YAC1B,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAA;QAC/C,KAAK,eAAe;YACnB,2DAA2D;YAC3D,yDAAyD;YACzD,6DAA6D;YAC7D,uCAAuC;YACvC,OAAO,OAAO,CAAC,OAAO,CAAC;gBACtB,MAAM,EAAE,iBAAiB;gBACzB,iBAAiB,EAAE,EAAE;gBACrB,QAAQ,EAAE,mEAAmE;gBAC7E,UAAU,EAAE,OAAO,CAAC,QAAQ,CAAC,UAAU;aACvC,CAAC,CAAA;QACH,OAAO,CAAC,CAAC,CAAC;YACT,MAAM,WAAW,GAAU,OAAO,CAAA;YAClC,MAAM,IAAI,KAAK,CAAC,gCAAiC,WAAmC,CAAC,IAAI,EAAE,CAAC,CAAA;QAC7F,CAAC;IACF,CAAC;AACF,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/hitl/index.ts"],"names":[],"mappings":"AA4PA,MAAM,UAAU,kBAAkB,CAAC,OAA4B;IAC9D,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;QACtB,KAAK,eAAe;YACnB,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC,CAAA;QACnD,KAAK,aAAa;YACjB,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC,CAAA;QACpD,KAAK,sBAAsB;YAC1B,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAA;QAC/C,KAAK,eAAe;YACnB,2DAA2D;YAC3D,yDAAyD;YACzD,6DAA6D;YAC7D,uCAAuC;YACvC,OAAO,OAAO,CAAC,OAAO,CAAC;gBACtB,MAAM,EAAE,iBAAiB;gBACzB,iBAAiB,EAAE,EAAE;gBACrB,QAAQ,EAAE,mEAAmE;gBAC7E,UAAU,EAAE,OAAO,CAAC,QAAQ,CAAC,UAAU;aACvC,CAAC,CAAA;QACH,OAAO,CAAC,CAAC,CAAC;YACT,MAAM,WAAW,GAAU,OAAO,CAAA;YAClC,MAAM,IAAI,KAAK,CAAC,gCAAiC,WAAmC,CAAC,IAAI,EAAE,CAAC,CAAA;QAC7F,CAAC;IACF,CAAC;AACF,CAAC"}

package/dist/types/session/store.d.ts

@@ -86,7 +86,34 @@ export interface SessionStore {
     getProject(projectId: ProjectId, tenantId: TenantId): Promise<Project | null>;
     createSession(params: CreateSessionParams, tenantId: TenantId): Promise<Session>;
     getSession(sessionId: SessionId, tenantId: TenantId): Promise<Session | null>;
-    updateSession(session: Session, tenantId: TenantId): Promise<void>;
+    /**
+     * Write a Session back, optionally only if nobody else wrote it first.
+     *
+     * **`expectedOwnerVersion` is the single-writer lock this level is supposed
+     * to own, and it did not exist.** `Session.ownerVersion` is documented as
+     * the CAS counter for handoff, but nothing enforced it: both stores
+     * overwrote unconditionally, and the handoff's own check compared a
+     * snapshot it had read several awaits earlier against itself. Two
+     * concurrent handoffs on one idle session both passed, both provisioned a
+     * worktree, and one silently erased the other.
+     *
+     * Supply it and the store compares against the version it HAS STORED —
+     * not against the payload, which is the caller's stale copy — and throws
+     * {@link StaleSessionError} rather than writing. Omit it and the behaviour
+     * is exactly what it always was, which is the compatibility promise: this
+     * parameter is optional so that widening the interface stays invisible to
+     * callers and harmless to hosts implementing their own store. A required
+     * parameter would break every implementor for a guarantee they can opt
+     * into.
+     *
+     * **In-process only, stated rather than implied.** `DiskSessionStore`
+     * writes atomically, but its read-compare-write is not a critical section,
+     * so two PROCESSES can still both pass the check. Closing that needs a
+     * lease with an expiry — not a PID registry, because a Session is durable
+     * and written from hosts where a PID is not a checkable fact. The same
+     * honesty the spawn lock already carries.
+     */
+    updateSession(session: Session, tenantId: TenantId, expectedOwnerVersion?: number): Promise<void>;
     /**
      * List every Session that belongs to the given Thread for the caller's
      * tenant, ordered by `createdAt` ascending. Returns an empty array when

package/dist/types/session/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/types/session/store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,+BAA+B,CAAA;AAC5D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAA;AAC5D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,+BAA+B,CAAA;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAA;AACrE,OAAO,KAAK,EACX,cAAc,EACd,WAAW,EACX,UAAU,EACV,cAAc,EACd,MAAM,oCAAoC,CAAA;AAC3C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAA;AACnE,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AACrE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAErF;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,mBAAmB;IACnC,QAAQ,EAAE,QAAQ,CAAA;IAClB,SAAS,EAAE,SAAS,CAAA;IACpB;;;;OAIG;IACH,YAAY,EAAE,QAAQ,GAAG,IAAI,CAAA;CAC7B;AAED;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACtC,eAAe,EAAE,SAAS,CAAA;IAC1B,cAAc,EAAE,SAAS,CAAA;IACzB,IAAI,EAAE,cAAc,CAAA;IACpB,SAAS,EAAE,QAAQ,CAAA;IACnB,WAAW,CAAC,EAAE,WAAW,CAAA;IACzB,cAAc,CAAC,EAAE,cAAc,CAAA;CAC/B;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IACnC,QAAQ,EAAE,QAAQ,CAAA;IAClB,IAAI,EAAE,MAAM,CAAA;CACZ;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC3B,OAAO,EAAE,OAAO,CAAA;IAChB,QAAQ,EAAE,SAAS,UAAU,EAAE,CAAA;IAC/B,QAAQ,EAAE,SAAS,SAAS,EAAE,CAAA;CAC9B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAG5B,aAAa,CAAC,MAAM,EAAE,mBAAmB,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAEhF,UAAU,CAAC,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAA;IAI7E,aAAa,CAAC,MAAM,EAAE,mBAAmB,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAEhF,UAAU,CAAC,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAA;IAE7E,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAElE;;;;;;;;;;;;;;;;OAgBG;IACH,YAAY,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,OAAO,EAAE,CAAC,CAAA;IAEjF;;;;;;;;;;;;;;OAcG;IACH,aAAa,CAAC,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAItE,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;IAEzF,aAAa,CAAC,YAAY,EAAE,YAAY,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAA;IAEzF,gBAAgB,CAAC,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE3E;;;;;;OAMG;IACH,gBAAgB,CAAC,YAAY,EAAE,YAAY,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAI/E;;;;OAIG;IACH,aAAa,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC,CAAA;IAE7F;;;;;;;OAOG;IACH,YAAY,CAAC,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,OAAO,EAAE,CAAC,CAAA;IAEnF;;;;;;;;;OASG;IACH,mBAAmB,CAAC,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,cAAc,EAAE,CAAC,CAAA;IAIjG;;;OAGG;IACH,WAAW,CAAC,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC,CAAA;IAErF;;;;;OAKG;IACH,WAAW,CAAC,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,SAAS,EAAE,CAAC,CAAA;IAEpF;;;OAGG;IACH,KAAK,CAAC,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAA;IAI5E;;;;;;;;;;;;;;;;OAgBG;IACH,aAAa,CACZ,OAAO,EAAE,iBAAiB,GAAG;QAAE,cAAc,EAAE,QAAQ,CAAA;KAAE,EACzD,QAAQ,EAAE,QAAQ,GAChB,OAAO,CAAC,IAAI,CAAC,CAAA;IAEhB;;;;OAIG;IACH,UAAU,CAAC,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAA;CACvF;AAED;;;GAGG;AACH,YAAY,EAAE,SAAS,EAAE,CAAA"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/types/session/store.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namzu/sdk",
-  "version": "12.1.0",
+  "version": "13.0.0",
   "description": "Open-source AI agent SDK with a built-in runtime. Nothing between you and your agents.",
   "license": "FSL-1.1-MIT",
   "type": "module",

package/src/bridge/a2a/__tests__/project-is-the-a2a-context.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'vitest'
+
+import type { WireRun } from '../../../contracts/api.js'
+import { a2aMessageToCreateRun, runToA2ATask } from '../task.js'
+
+/**
+ * A2A's `contextId` is namzu's **Project**, and this pins it.
+ *
+ * The docs of record said the opposite for a long time: `a2a-threading.md`
+ * opened with "A2A connections attach at the Thread level, not the Project
+ * level" and called that the reason the Thread layer is first-class. The code
+ * never did it. `runToA2ATask` has always bound `contextId` to `project_id`,
+ * `a2aParamsToRunRequest` has always read it back as `projectId`, and
+ * `ThreadId` appears nowhere in this bridge.
+ *
+ * That gap is why this test exists rather than a comment. The claim was load-
+ * bearing — it was the single justification for a whole hierarchy level — and
+ * it survived for months because nothing asserted the actual binding. An
+ * unasserted invariant is a belief, and beliefs are what the prose was made of.
+ */
+
+function wireRun(overrides: Partial<WireRun> = {}): WireRun {
+	return {
+		id: 'run_ctx',
+		agent_id: 'worker',
+		status: 'completed',
+		project_id: 'prj_alpha',
+		created_at: new Date('2026-08-06').toISOString(),
+		...overrides,
+	} as WireRun
+}
+
+describe('a2a contextId is the project, in both directions', () => {
+	it('maps a run onto a task whose context is its project', () => {
+		expect(runToA2ATask(wireRun()).contextId).toBe('prj_alpha')
+	})
+
+	it('reads a task context back as the project to run under', () => {
+		const request = a2aMessageToCreateRun('worker', {
+			contextId: 'prj_beta',
+			message: { role: 'user', parts: [{ kind: 'text', text: 'go' }] },
+		} as never)
+
+		expect(request.projectId).toBe('prj_beta')
+	})
+
+	it('round-trips, so a peer context names a project namzu can run under', () => {
+		// The property an interoperating peer actually depends on: the context
+		// it was handed is the context it can send back.
+		const task = runToA2ATask(wireRun({ project_id: 'prj_gamma' } as Partial<WireRun>))
+		const request = a2aMessageToCreateRun('worker', {
+			contextId: task.contextId,
+			message: { role: 'user', parts: [{ kind: 'text', text: 'again' }] },
+		} as never)
+
+		expect(request.projectId).toBe('prj_gamma')
+	})
+
+	it('leaves the context absent when a run has no project', () => {
+		// Absent rather than an empty string: a peer must be able to tell "no
+		// context" from "a context named nothing".
+		expect(
+			runToA2ATask(wireRun({ project_id: undefined } as Partial<WireRun>)).contextId,
+		).toBeUndefined()
+	})
+})

package/src/manager/agent/lifecycle.ts

@@ -641,6 +641,24 @@ export class AgentManager {
 			if (this.deps.workspaceRegistry.has(backend)) {
 				const driver = this.deps.workspaceRegistry.get(backend)
 				workspaceRef = await driver.create({ label: subSession.id })
+
+				// Write the workspace onto the record that outlives this process.
+				//
+				// The ref was kept only on the in-memory `ChildSpawnRecord`, so
+				// `SubSession.workspaceId` stayed `null` for every spawn-created
+				// child — and `ArchivalManager` resolves a workspace only when
+				// that field is set (`session/retention/archive.ts`). The one
+				// record that could have named the workspace said there was none,
+				// which is why the archival path could never act as a backstop
+				// for a leaked worktree.
+				//
+				// After `create` rather than in `createSubSession`, because the
+				// sub-session id is the workspace's label — the workspace cannot
+				// exist before the record it is named after. Inside the try, so
+				// the compensating rollback below covers it like every other
+				// mutation here.
+				subSession = { ...subSession, workspaceId: workspaceRef.id }
+				await store.updateSubSession(subSession, context.tenantId)
 			}
 		} catch (err) {
 			// Compensating rollback order is mandated by the store's
@@ -764,9 +782,9 @@ export class AgentManager {
 						)
 					}
 				} else {
-					// Non-success: mark sub-session failed and, when we own a
-					// workspace, dispose it. Dispose errors are logged but not
-					// propagated — the sub-session state is already persisted.
+					// Non-success: mark sub-session failed. Disposal is shared with
+					// the success branch below — the workspace was provisioned for
+					// this child either way, and it is this manager that owns it.
 					const subSession = await store.getSubSession(
 						spawnRecord.subSessionId,
 						spawnRecord.tenantId,
@@ -774,21 +792,25 @@ export class AgentManager {
 					if (subSession) {
 						await store.updateSubSession({ ...subSession, status: 'failed' }, spawnRecord.tenantId)
 					}
-					if (spawnRecord.workspaceRef) {
-						const backend = spawnRecord.workspaceRef.meta.backend
-						if (this.deps.workspaceRegistry.has(backend)) {
-							await this.deps.workspaceRegistry
-								.get(backend)
-								.dispose(spawnRecord.workspaceRef)
-								.catch((disposeErr) => {
-									this.log.warn('Workspace dispose failed', {
-										backend,
-										error: toErrorMessage(disposeErr),
-									})
-								})
-						}
-					}
 				}
+
+				// A child is done with its workspace however it ended.
+				//
+				// This used to live only in the branch above, so both dispose
+				// sites in this class were failure paths and a child that
+				// SUCCEEDED released nothing. `.namzu/worktrees/` then grew once
+				// per successful delegation — the more reliable the workers, the
+				// faster it filled, which is the opposite of the signal a leak
+				// usually gives.
+				//
+				// 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`
+				// 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
+				// is fixing.
+				await this.disposeChildWorkspace(spawnRecord)
 			} catch (err) {
 				this.log.error('Sub-session finalization failed', {
 					taskId: agentTask.taskId,
@@ -937,15 +959,38 @@ export class AgentManager {
 				spawnRecord.tenantId,
 			)
 		}
-		if (spawnRecord.workspaceRef) {
-			const backend = spawnRecord.workspaceRef.meta.backend
-			if (this.deps.workspaceRegistry.has(backend)) {
-				await this.deps.workspaceRegistry
-					.get(backend)
-					.dispose(spawnRecord.workspaceRef)
-					.catch(() => undefined)
-			}
-		}
+		await this.disposeChildWorkspace(spawnRecord)
+	}
+
+	/**
+	 * Release the workspace this manager provisioned for a child.
+	 *
+	 * 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
+	 * an exception on a child that already finished.
+	 *
+	 * Never throws. Disposal is cleanup, not part of the child's result: the
+	 * sub-session state is already persisted by the time this runs, and
+	 * failing here would report a delegation that worked as one that did not.
+	 * The failure is logged instead, because a worktree that could not be
+	 * removed is an operator's problem and silence is how it stays one.
+	 */
+	private async disposeChildWorkspace(spawnRecord: ChildSpawnRecord): Promise<void> {
+		if (!spawnRecord.workspaceRef) return
+		const backend = spawnRecord.workspaceRef.meta.backend
+		if (!this.deps.workspaceRegistry.has(backend)) return
+		await this.deps.workspaceRegistry
+			.get(backend)
+			.dispose(spawnRecord.workspaceRef)
+			.catch((disposeErr) => {
+				this.log.warn('Workspace dispose failed', {
+					backend,
+					workspaceId: spawnRecord.workspaceRef?.id,
+					subSessionId: spawnRecord.subSessionId,
+					error: toErrorMessage(disposeErr),
+				})
+			})
 	}
 
 	private markCanceled(taskId: TaskId): void {

package/src/public-runtime.ts

@@ -483,6 +483,12 @@ export {
 
 export {
 	AncestryCycleError,
+	// Exported with the CAS it announces. A host that opts into
+	// `expectedOwnerVersion` has to be able to tell "somebody else took this
+	// session" from any other failure, and string-matching a message is not a
+	// contract — which is the state `ThreadClosedError` and its siblings are
+	// still in, and a reason not to add a fourth.
+	StaleSessionError,
 	TenantIsolationError,
 	WorkspaceBackendError,
 } from './session/errors.js'

package/src/runtime/query/__tests__/the-other-approval-surface-names-the-agent.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from 'vitest'
+
+import type { PlanManager } from '../../../manager/plan/lifecycle.js'
+import { MockLLMProvider, registerMock } from '../../../provider/index.js'
+import { ToolRegistry } from '../../../registry/index.js'
+import type { HITLResumeDecision, PlanApprovalData } from '../../../types/hitl/index.js'
+import {
+	generateProjectId,
+	generateSessionId,
+	generateTenantId,
+	generateThreadId,
+} from '../../../utils/id.js'
+import { drainQuery } from '../index.js'
+
+/**
+ * There are TWO approval surfaces, and the fix landed on one of them.
+ *
+ * `PlanStep.agentId` was added so an approver could see WHICH agent a step goes
+ * to rather than only THAT it delegates. It reached `PlanApprovalRequest` — the
+ * shape a host sees when it installs its own handler on `PlanManager` — and the
+ * test written at the time asserted on exactly that, by constructing a
+ * `PlanManager` directly.
+ *
+ * It did not reach `PlanApprovalData`, which is what every `resumeHandler` host
+ * receives, because that type declared its own step shape and both mappers copy
+ * field by field. So the busier surface kept showing `toolName: 'create_task'`
+ * and nothing else — the precise behaviour the change was supposed to end.
+ *
+ * A live run did not catch it either: the run observes `plan_ready`, which
+ * carries whole `PlanStep`s and therefore always had `agentId`. Watching the
+ * event stream confirmed the field existed somewhere, which is not the same
+ * question as whether the approver gets it.
+ */
+
+registerMock()
+
+async function agentIdSeenByResumeHandler(): Promise<PlanApprovalData['steps']> {
+	let seen: PlanApprovalData['steps'] | undefined
+
+	await drainQuery({
+		provider: new MockLLMProvider({ responses: [{ content: 'done' }] } as never),
+		tools: new ToolRegistry(),
+		agentId: 'a',
+		agentName: 'A',
+		messages: [{ role: 'user', content: 'go' }],
+		workingDirectory: process.cwd(),
+		runConfig: { model: 'mock', tokenBudget: 100_000, timeoutMs: 30_000, maxIterations: 4 },
+		projectId: generateProjectId(),
+		sessionId: generateSessionId(),
+		threadId: generateThreadId(),
+		tenantId: generateTenantId(),
+		// The ordinary host path: a resumeHandler, not a hand-installed
+		// PlanManager handler.
+		resumeHandler: async (request: { type: string; plan?: PlanApprovalData }) => {
+			if (request.type === 'plan_approval' && request.plan) seen = request.plan.steps
+			return { action: 'approve_plan' } as HITLResumeDecision
+		},
+		onContextCreated: ({ planManager }: { planManager: PlanManager }) => {
+			planManager.startGenerating('the work')
+			planManager.addStep({
+				id: 'step_1',
+				description: 'delegated work',
+				agentId: 'shell-runner',
+				toolName: 'create_task',
+				dependsOn: [],
+				order: 1,
+			})
+			planManager.addStep({ id: 'step_2', description: 'my own work', dependsOn: [], order: 2 })
+			planManager.markReady()
+			void planManager.requestApproval()
+		},
+	} as never)
+
+	if (!seen) throw new Error('the resume handler never received a plan approval')
+	return seen
+}
+
+describe('the resumeHandler approval surface names the agent too', () => {
+	it('carries agentId through to the host', async () => {
+		const steps = await agentIdSeenByResumeHandler()
+
+		expect(steps.map((s) => s.agentId)).toEqual(['shell-runner', undefined])
+	})
+
+	it('still distinguishes the two steps by more than toolName', async () => {
+		// The defect in the shape that matters: without agentId both delegated
+		// steps reach the approver identical, and an orchestrator-owned step is
+		// told apart only by an absent toolName.
+		const steps = await agentIdSeenByResumeHandler()
+		const delegated = steps.find((s) => s.id === 'step_1')
+
+		expect(delegated?.toolName).toBe('create_task')
+		expect(delegated?.agentId).toBe('shell-runner')
+	})
+})

package/src/runtime/query/index.ts

@@ -527,6 +527,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 					id: s.id,
 					description: s.description,
 					toolName: s.toolName,
+					agentId: s.agentId,
 					dependsOn: s.dependsOn,
 					order: s.order ?? i + 1,
 				})),

package/src/runtime/query/iteration/phases/plan.ts

@@ -29,6 +29,7 @@ export async function* runPlanGate(ctx: IterationContext): AsyncGenerator<RunEve
 				id: s.id,
 				description: s.description,
 				toolName: s.toolName,
+				agentId: s.agentId,
 				dependsOn: s.dependsOn,
 				order: s.order,
 			})),

package/src/session/__tests__/integration/a-successful-delegation-disposes-its-workspace.test.ts

@@ -0,0 +1,270 @@
+/**
+ * A worktree provisioned for a delegated child outlived the child that used it.
+ *
+ * `finalizeChild` had two dispose sites and both were failure paths — the
+ * non-success branch, and the rollback in `failSubSession`. The success branch
+ * disposed nothing, so `.namzu/worktrees/` grew once per successful delegation:
+ * the more reliable the workers, the faster it filled.
+ *
+ * The backstop could not fire either. `ArchivalManager` resolves a workspace
+ * only when `SubSession.workspaceId` is set, and for a spawn-created
+ * sub-session that field was written `null` and never updated —
+ * `provisionSpawn` kept the ref on the in-memory `ChildSpawnRecord` and nowhere
+ * else. So the one record that could have named the leaked worktree said there
+ * was none.
+ *
+ * Both halves are pinned here, and the failure path is re-asserted alongside
+ * them: a test that only counted disposals would pass on the old code by
+ * reading the failure branch's disposal and calling it the success branch's.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { EMPTY_TOKEN_USAGE } from '../../../constants/limits.js'
+import { AgentManager } from '../../../manager/agent/lifecycle.js'
+import { ThreadManager } from '../../../manager/thread/lifecycle.js'
+import { AgentRegistry } from '../../../registry/agent/definitions.js'
+import { InMemorySessionStore } from '../../../store/session/memory.js'
+import { InMemoryThreadStore } from '../../../store/thread/memory.js'
+import type {
+	AgentCapabilities,
+	AgentInput,
+	BaseAgentConfig,
+	BaseAgentResult,
+} from '../../../types/agent/base.js'
+import type { Agent } from '../../../types/agent/core.js'
+import type { AgentDefinition } from '../../../types/agent/factory.js'
+import type { AgentTaskContext, SendMessageOptions } from '../../../types/agent/task.js'
+import type { RunId, TenantId, UserId, WorkspaceId } from '../../../types/ids/index.js'
+import { createAssistantMessage } from '../../../types/message/index.js'
+import type { ActorRef } from '../../../types/session/actor.js'
+import type { SummaryId } from '../../../types/session/ids.js'
+import type { WorkspaceRef } from '../../../types/workspace/ref.js'
+import { ZERO_COST } from '../../../utils/cost.js'
+import { DefaultCapacityValidator } from '../../handoff/capacity.js'
+import { SessionSummaryMaterializer } from '../../summary/materialize.js'
+import type {
+	BranchWorkspaceParams,
+	CreateWorkspaceParams,
+	WorkspaceBackendDriver,
+	WorkspaceInspection,
+} from '../../workspace/driver.js'
+import { WorkspaceBackendRegistry } from '../../workspace/registry.js'
+
+const tenant = 'tnt_alpha' as TenantId
+
+const capabilities: AgentCapabilities = {
+	supportsTools: false,
+	supportsStreaming: false,
+	supportsConcurrency: false,
+	supportsSubAgents: false,
+}
+
+/** A child that settles the way `outcome` says, so both branches are reachable. */
+function buildAgent(
+	id: string,
+	outcome: 'completed' | 'failed',
+): Agent<BaseAgentConfig, BaseAgentResult> {
+	return {
+		type: 'reactive',
+		metadata: {
+			type: 'reactive',
+			id,
+			name: id,
+			version: '1.0.0',
+			category: 'test',
+			description: id,
+			capabilities,
+		},
+		run: async (_input: AgentInput, _config: BaseAgentConfig): Promise<BaseAgentResult> => ({
+			runId: 'run_child' as RunId,
+			status: outcome,
+			usage: { ...EMPTY_TOKEN_USAGE },
+			cost: { ...ZERO_COST },
+			iterations: 1,
+			durationMs: 1,
+			messages: [createAssistantMessage('child did the work')],
+			result: 'child did the work',
+		}),
+		cancel: async () => undefined,
+		getCapabilities: () => capabilities,
+	}
+}
+
+function buildDefinition(agent: Agent<BaseAgentConfig, BaseAgentResult>): AgentDefinition {
+	return {
+		info: {
+			id: agent.metadata.id,
+			name: agent.metadata.name,
+			version: agent.metadata.version,
+			category: agent.metadata.category,
+			description: agent.metadata.description,
+			tools: [],
+			defaults: { model: 'test', tokenBudget: 1_000 },
+		},
+		typedAgent: agent,
+	}
+}
+
+/** Provisions successfully and records every ref it is asked to dispose. */
+class RecordingWorkspaceDriver implements WorkspaceBackendDriver {
+	readonly kind = 'git-worktree' as const
+	readonly created: WorkspaceRef[] = []
+	readonly disposed: WorkspaceId[] = []
+	private counter = 0
+
+	async create(params: CreateWorkspaceParams): Promise<WorkspaceRef> {
+		const ref: WorkspaceRef = {
+			id: `wsp_test_${++this.counter}` as WorkspaceId,
+			meta: {
+				backend: 'git-worktree',
+				repoRoot: '/tmp/repo',
+				branch: `namzu/${params.label ?? 'unlabelled'}`,
+				worktreePath: `/tmp/repo/.namzu/worktrees/${params.label ?? 'unlabelled'}`,
+			},
+			createdAt: new Date(),
+		}
+		this.created.push(ref)
+		return ref
+	}
+
+	async branch(_source: WorkspaceRef, _params: BranchWorkspaceParams): Promise<WorkspaceRef> {
+		throw new Error('unused in this test')
+	}
+
+	async dispose(ref: WorkspaceRef): Promise<void> {
+		this.disposed.push(ref.id)
+	}
+
+	async inspect(_ref: WorkspaceRef): Promise<WorkspaceInspection> {
+		throw new Error('unused in this test')
+	}
+}
+
+/**
+ * Stands up a Project → Thread → parent Session and an AgentManager wired to a
+ * recording workspace driver. `outcome` decides how the delegated child ends;
+ * `registerBackend: false` leaves the registry empty, which is the supported
+ * lazy-provisioning configuration rather than an error (pattern doc §7.1).
+ */
+async function harness(
+	outcome: 'completed' | 'failed',
+	{ registerBackend = true }: { registerBackend?: boolean } = {},
+) {
+	const store = new InMemorySessionStore()
+	const threadStore = new InMemoryThreadStore()
+	const project = await store.createProject({ tenantId: tenant, name: 'workspace-project' }, tenant)
+	const thread = await threadStore.createThread(
+		{ projectId: project.id, title: 'workspace-topic' },
+		tenant,
+	)
+
+	const userActor: ActorRef = { kind: 'user', userId: 'usr_root' as UserId, tenantId: tenant }
+
+	const parentSession = await store.createSession(
+		{ threadId: thread.id, projectId: project.id, currentActor: userActor },
+		tenant,
+	)
+	await store.updateSession({ ...parentSession, status: 'active' }, tenant)
+
+	let summaryCounter = 0
+	const materializer = new SessionSummaryMaterializer({
+		store,
+		generateSummaryId: () => `sum_test_${++summaryCounter}` as SummaryId,
+	})
+
+	const registry = new AgentRegistry()
+	registry.register(buildDefinition(buildAgent('worker', outcome)))
+
+	const workspaceRegistry = new WorkspaceBackendRegistry()
+	const driver = new RecordingWorkspaceDriver()
+	if (registerBackend) workspaceRegistry.register(driver)
+
+	const manager = new AgentManager(registry, undefined, {
+		sessionStore: store,
+		summaryMaterializer: materializer,
+		workspaceRegistry,
+		capacity: new DefaultCapacityValidator(store),
+		threadManager: new ThreadManager({ threadStore, sessionStore: store }),
+	})
+
+	const taskContext: AgentTaskContext = {
+		parentRunId: 'run_parent' as RunId,
+		parentAgentId: 'supervisor',
+		parentAbortController: new AbortController(),
+		depth: 0,
+		budgetTracker: { total: 100_000, remaining: 100_000 },
+		tenantId: tenant,
+		threadId: thread.id,
+		sessionId: parentSession.id,
+		projectId: project.id,
+		parentActor: userActor,
+	}
+
+	const options: SendMessageOptions = {
+		agentId: 'worker',
+		input: { messages: [], workingDirectory: '/tmp' },
+		parentSessionId: parentSession.id,
+		tenantId: tenant,
+		projectId: project.id,
+		parentActor: userActor,
+		workspaceBackend: 'git-worktree',
+	}
+
+	return { store, manager, driver, parentSession, options, taskContext }
+}
+
+describe('a delegated child does not outlive its workspace', () => {
+	it('disposes the workspace when the child SUCCEEDS', async () => {
+		const { manager, driver, options, taskContext } = await harness('completed')
+
+		const task = await manager.sendMessage(options, taskContext)
+		await manager.waitForCompletion(task.taskId)
+
+		expect(manager.getState(task.taskId)).toBe('completed')
+		expect(driver.created).toHaveLength(1)
+		// The assertion the leak fails: one workspace made, the same one released.
+		expect(driver.disposed).toEqual([driver.created[0]?.id])
+	})
+
+	it('still disposes the workspace when the child FAILS', async () => {
+		const { manager, driver, options, taskContext } = await harness('failed')
+
+		const task = await manager.sendMessage(options, taskContext)
+		await manager.waitForCompletion(task.taskId)
+
+		expect(driver.created).toHaveLength(1)
+		expect(driver.disposed).toEqual([driver.created[0]?.id])
+	})
+
+	it('records the workspace on the sub-session, so archival can find it', async () => {
+		const { store, manager, driver, parentSession, options, taskContext } =
+			await harness('completed')
+
+		const task = await manager.sendMessage(options, taskContext)
+		await manager.waitForCompletion(task.taskId)
+
+		const [subSession] = await store.getChildren(parentSession.id, tenant)
+		expect(subSession).toBeDefined()
+		// Was `null` on every spawn-created sub-session, which is what made
+		// `ArchivalManager`'s `sub.workspaceId &&` guard unreachable here.
+		expect(subSession?.workspaceId).toBe(driver.created[0]?.id)
+	})
+
+	it('leaves workspaceId null when no backend is registered', async () => {
+		// Lazy provisioning stays legal (pattern doc §7.1): an unregistered
+		// backend is not an error, and the record must not claim a workspace
+		// that was never made.
+		const { store, manager, driver, parentSession, options, taskContext } = await harness(
+			'completed',
+			{ registerBackend: false },
+		)
+
+		const task = await manager.sendMessage(options, taskContext)
+		await manager.waitForCompletion(task.taskId)
+
+		expect(manager.getState(task.taskId)).toBe('completed')
+		expect(driver.created).toHaveLength(0)
+		const [subSession] = await store.getChildren(parentSession.id, tenant)
+		expect(subSession?.workspaceId).toBeNull()
+	})
+})