@namzu/sdk 34.2.0 → 35.0.0

package/dist/manager/agent/lifecycle.js

@@ -1,5 +1,4 @@
 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 { isTerminalAgentTaskState } from '../../types/agent/task.js';
@@ -80,274 +79,373 @@ export class AgentManager {
         const definitionForSpawn = this.registry.getOrThrow(options.agentId);
         const sharedAgent = definitionForSpawn.typedAgent;
         const agent = definitionForSpawn.createAgent?.() ?? sharedAgent.forRun?.() ?? sharedAgent;
-        const childAbortController = createChildAbortController(context.parentAbortController);
-        // The allocation is computed INSIDE the spawn lock, not here. Reading
-        // the parent's remaining budget at this point and debiting it after
-        // `provisionSpawn` put the two halves of a read-modify-write on either
-        // side of an await — so N siblings launched from one turn all read the
-        // same undebited number and each took a fraction of it. Measured: four
-        // concurrent children were handed 50 000 + 50 000 + 50 000 + 50 000
-        // from a pool of 100 000.
-        //
-        // `create_task`'s own description instructs exactly this shape ("'fan
-        // out 8 specialists' is one assistant message with 8 create_task
-        // blocks"), so the documented usage was the reproduction.
-        //
-        // Nothing pinned it because the only concurrent test built a fresh
-        // context per call — each spawn got its own tracker, which measures
-        // width and not budget.
-        // Phase 6: SubSession + child Session + WorkspaceRef triple. Happens
-        // before taskId minting so a capacity failure short-circuits cleanly
-        // with no observable state change.
-        //
-        // The allocation now travels with it, because the read and the debit
-        // have to be on the same side of every await to mean anything.
-        const { spawnRecord, allocatedTokens } = await this.provisionSpawn(options, context);
-        const taskId = generateTaskId();
-        const childParentActor = {
-            kind: 'agent',
-            agentId: context.parentAgentId,
-            tenantId: context.tenantId,
-            parentActor: context.parentActor,
-        };
-        // The union of every deny along the chain, plus this spawn's own.
-        //
-        // Without it, NZ-GATE-09's scope stopped at one level: a child denied
-        // `bash` could spawn a grandchild naming no scope, and the grandchild
-        // got bash back. A restriction that a descendant can shed by
-        // delegating is not a restriction.
-        //
-        // No containment CHECK here, deliberately. The obvious shape is to
-        // confirm with `isDescendantOfActor` that the child really sits under
-        // the actor whose scope is being inherited — but `childParentActor`
-        // is built two statements up FROM `context.parentActor`, so the
-        // answer is yes by construction and the branch could never be taken.
-        // 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.
-        //
-        // Union, not replace, and not "innermost wins": a descendant may
-        // narrow further and may never widen.
-        const inheritedDenies = context.toolDenies ?? [];
-        const ownDenies = options.toolScope?.deny ?? [];
-        const resolvedDenies = [...new Set([...inheritedDenies, ...ownDenies])];
-        const childContext = {
-            parentRunId: context.parentRunId,
-            parentAgentId: context.parentAgentId,
-            parentAbortController: context.parentAbortController,
-            depth: context.depth + 1,
-            budgetTracker: context.budgetTracker,
-            factoryOptions: context.factoryOptions,
-            tenantId: context.tenantId,
-            topicId: context.topicId,
-            sessionId: spawnRecord.childSessionId,
-            projectId: context.projectId,
-            parentActor: childParentActor,
-            ...(resolvedDenies.length > 0 ? { toolDenies: resolvedDenies } : {}),
-        };
-        const agentTask = {
-            taskId,
-            agentId: options.agentId,
-            agent,
-            childAbortController,
-            context: childContext,
-            state: 'pending',
-            budgetReservation: allocatedTokens,
-            pendingMessages: [],
-            createdAt: Date.now(),
-            runEventListener: listener,
-        };
-        this.instances.set(taskId, agentTask);
-        if (resolvedDenies.length > 0)
-            spawnRecord.resolvedToolDenies = resolvedDenies;
-        this.spawnRecords.set(taskId, spawnRecord);
-        this.emit({
-            type: 'pending',
-            taskId,
-            agentId: options.agentId,
-            parentAgentId: context.parentAgentId,
-            depth: context.depth,
-        });
-        if (listener) {
-            listener({
-                type: 'agent_pending',
-                runId: context.parentRunId,
-                taskId,
-                parentAgentId: context.parentAgentId,
-                childAgentId: options.agentId,
-                depth: context.depth,
-            });
-            const lineage = {
-                parentSessionId: spawnRecord.parentSessionId,
-                rootSessionId: spawnRecord.rootSessionId,
-                depth: spawnRecord.childDepth,
-            };
-            listener({
-                type: 'subsession_spawned',
-                runId: context.parentRunId,
-                subSessionId: spawnRecord.subSessionId,
-                parentSessionId: spawnRecord.parentSessionId,
-                spawnedBy: context.parentActor,
-                lineage,
-                schemaVersion: RUN_EVENT_SCHEMA_VERSION,
-                at: new Date(),
+        context.parentAbortController.signal.throwIfAborted();
+        // Reserve synchronously before provisioning yields. The authority is shared
+        // across managers and nested sessions, while the session lock below only
+        // serializes filesystem capacity checks.
+        const remaining = context.budget.remaining;
+        const maxAllocation = Number.isFinite(remaining)
+            ? Math.floor(remaining * this.config.maxBudgetFraction)
+            : (options.budgetAllocation?.tokenBudget ??
+                (options.configOverrides?.tokenBudget === 0
+                    ? 200_000
+                    : (options.configOverrides?.tokenBudget ?? 200_000)));
+        const allocatedTokens = Math.min(options.budgetAllocation?.tokenBudget ?? maxAllocation, maxAllocation);
+        if (!Number.isSafeInteger(allocatedTokens) || allocatedTokens <= 0) {
+            throw new NamzuError({
+                code: 'invalid_config',
+                message: `Cannot spawn "${options.agentId}": the parent has ${remaining} tokens remaining; a child allocation must be a finite positive integer.`,
             });
         }
-        this.log.info('Agent task pending', {
-            'namzu.agent.task_id': taskId,
-            'namzu.agent.definition_id': options.agentId,
-            'namzu.agent.depth': context.depth,
-        });
-        const definition = this.registry.getOrThrow(options.agentId);
-        let childConfig;
-        if (definition.configBuilder) {
-            // Call the configBuilder regardless of whether factoryOptions were
-            // supplied. BYO-provider flows (ambient cloud credentials, a custom registry)
-            // commonly omit factoryOptions because the provider resolves its own
-            // credentials; the builder still needs to run to wire provider+tools.
-            // Defaults: empty factoryOptions when omitted; configOverrides win.
-            childConfig = await definition.configBuilder({
-                ...(context.factoryOptions ?? {}),
-                tokenBudget: allocatedTokens,
-                timeoutMs: options.budgetAllocation?.timeoutMs ?? this.config.childTimeoutMs,
+        const childBudget = context.budget.reserve(allocatedTokens);
+        let spawnRecord;
+        try {
+            await childBudget.flush();
+            spawnRecord = await this.provisionSpawn(options, context);
+        }
+        catch (error) {
+            childBudget.settle(0);
+            await childBudget.flush();
+            throw error;
+        }
+        let childAbortController;
+        let agentTask;
+        try {
+            childAbortController = createChildAbortController(context.parentAbortController);
+            const taskId = generateTaskId();
+            const childParentActor = {
+                kind: 'agent',
+                agentId: context.parentAgentId,
+                tenantId: context.tenantId,
+                parentActor: context.parentActor,
+            };
+            // The union of every deny along the chain, plus this spawn's own.
+            //
+            // Without it, NZ-GATE-09's scope stopped at one level: a child denied
+            // `bash` could spawn a grandchild naming no scope, and the grandchild
+            // got bash back. A restriction that a descendant can shed by
+            // delegating is not a restriction.
+            //
+            // No containment CHECK here, deliberately. The obvious shape is to
+            // confirm with `isDescendantOfActor` that the child really sits under
+            // the actor whose scope is being inherited — but `childParentActor`
+            // is built two statements up FROM `context.parentActor`, so the
+            // answer is yes by construction and the branch could never be taken.
+            // 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.
+            //
+            // Union, not replace, and not "innermost wins": a descendant may
+            // narrow further and may never widen.
+            const inheritedDenies = context.toolDenies ?? [];
+            const ownDenies = options.toolScope?.deny ?? [];
+            const resolvedDenies = [...new Set([...inheritedDenies, ...ownDenies])];
+            const childContext = {
                 parentRunId: context.parentRunId,
+                parentAgentId: context.parentAgentId,
+                parentAbortController: context.parentAbortController,
                 depth: context.depth + 1,
-                ...options.configOverrides,
+                budget: childBudget,
+                factoryOptions: context.factoryOptions,
+                tenantId: context.tenantId,
+                topicId: context.topicId,
+                sessionId: spawnRecord.childSessionId,
+                projectId: context.projectId,
+                parentActor: childParentActor,
+                ...(resolvedDenies.length > 0 ? { toolDenies: resolvedDenies } : {}),
+            };
+            agentTask = {
+                taskId,
+                agentId: options.agentId,
+                agent,
+                childAbortController,
+                context: childContext,
+                state: 'pending',
+                pendingMessages: [],
+                createdAt: Date.now(),
+                runEventListener: listener,
+            };
+            childAbortController.signal.throwIfAborted();
+            this.instances.set(taskId, agentTask);
+            if (resolvedDenies.length > 0)
+                spawnRecord.resolvedToolDenies = resolvedDenies;
+            this.spawnRecords.set(taskId, spawnRecord);
+            this.emit({
+                type: 'pending',
+                taskId,
+                agentId: options.agentId,
+                parentAgentId: context.parentAgentId,
+                depth: context.depth,
             });
-            if (!childConfig.contextLevel && definition.contextLevel) {
-                childConfig.contextLevel = definition.contextLevel;
+            if (listener) {
+                await listener({
+                    type: 'agent_pending',
+                    runId: context.parentRunId,
+                    taskId,
+                    parentAgentId: context.parentAgentId,
+                    childAgentId: options.agentId,
+                    depth: context.depth,
+                });
+                const lineage = {
+                    parentSessionId: spawnRecord.parentSessionId,
+                    rootSessionId: spawnRecord.rootSessionId,
+                    depth: spawnRecord.childDepth,
+                };
+                await listener({
+                    type: 'subsession_spawned',
+                    runId: context.parentRunId,
+                    subSessionId: spawnRecord.subSessionId,
+                    parentSessionId: spawnRecord.parentSessionId,
+                    spawnedBy: context.parentActor,
+                    lineage,
+                    schemaVersion: RUN_EVENT_SCHEMA_VERSION,
+                    at: new Date(),
+                });
             }
-            // Propagate session-hierarchy scoping onto the child config. The
-            // configBuilder may not have been updated to emit these yet; we
-            // stamp them here so query() sees them regardless.
-            childConfig.sessionId = spawnRecord?.childSessionId ?? context.sessionId;
-            childConfig.topicId = context.topicId;
-            childConfig.projectId = context.projectId;
-            childConfig.tenantId = context.tenantId;
-            // Stamp the trace parent the same way, rather than trusting every
-            // configBuilder to forward an option it may not know about.
-            if (options.configOverrides?.parentSpan) {
-                childConfig.parentSpan = options.configOverrides.parentSpan;
+            this.log.info('Agent task pending', {
+                'namzu.agent.task_id': taskId,
+                'namzu.agent.definition_id': options.agentId,
+                'namzu.agent.depth': context.depth,
+            });
+            const definition = this.registry.getOrThrow(options.agentId);
+            let childConfig;
+            if (definition.configBuilder) {
+                // Call the configBuilder regardless of whether factoryOptions were
+                // supplied. BYO-provider flows (ambient cloud credentials, a custom registry)
+                // commonly omit factoryOptions because the provider resolves its own
+                // credentials; the builder still needs to run to wire provider+tools.
+                // Defaults: empty factoryOptions when omitted; configOverrides win.
+                childConfig = {
+                    ...(await definition.configBuilder({
+                        ...(context.factoryOptions ?? {}),
+                        tokenBudget: allocatedTokens,
+                        timeoutMs: options.budgetAllocation?.timeoutMs ?? this.config.childTimeoutMs,
+                        parentRunId: context.parentRunId,
+                        depth: context.depth + 1,
+                        ...options.configOverrides,
+                    })),
+                };
+                if (!childConfig.contextLevel && definition.contextLevel) {
+                    childConfig.contextLevel = definition.contextLevel;
+                }
+                // Propagate session-hierarchy scoping onto the child config. The
+                // configBuilder may not have been updated to emit these yet; we
+                // stamp them here so query() sees them regardless.
+                childConfig.sessionId = spawnRecord?.childSessionId ?? context.sessionId;
+                childConfig.topicId = context.topicId;
+                childConfig.projectId = context.projectId;
+                childConfig.tenantId = context.tenantId;
+                // Stamp the trace parent the same way, rather than trusting every
+                // configBuilder to forward an option it may not know about.
+                if (options.configOverrides?.parentSpan) {
+                    childConfig.parentSpan = options.configOverrides.parentSpan;
+                }
+                // Stamped for the same reason as the trace parent above: a
+                // `configBuilder` is written by whoever registered the agent and
+                // cannot be trusted to forward something it was never told about.
+                // An explicit override still wins, so a host can hand one child a
+                // different channel — or none.
+                //
+                // 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.
+                const inheritedHandler = options.configOverrides?.resumeHandler ?? context.resumeHandler;
+                if (inheritedHandler)
+                    childConfig.resumeHandler = inheritedHandler;
+                // And the environment, for the third time and the same reason.
+                //
+                // The bare-config branch below has always carried `env`; this one
+                // never did, so a delegate registered WITH a `configBuilder` — the
+                // normal way, and what every host in this repo does — silently ran
+                // with none of the environment its parent had been given. The
+                // builder is written by whoever registered the agent and cannot be
+                // expected to forward a field it was never told about, which is
+                // exactly why `parentSpan` and `resumeHandler` are stamped here too.
+                //
+                // Merged per key rather than replaced. `configOverrides` is a
+                // `Partial`, so assigning the whole map would drop every key the
+                // builder set and the caller did not restate — the override wins per
+                // key, the same direction it already wins for `model` and `effort`.
+                const inheritedEnv = mergeEnv(childConfig.env, options.configOverrides?.env);
+                if (inheritedEnv)
+                    childConfig.env = inheritedEnv;
+                // A builder may ignore a newly-added factory option. The requested root
+                // policy is an execution boundary, so stamp an explicit child override
+                // after the builder rather than silently falling back to ephemeral.
+                if (options.configOverrides?.sandbox) {
+                    childConfig.sandbox = options.configOverrides.sandbox;
+                }
+            }
+            else {
+                this.log.warn('No configBuilder, using bare config', {
+                    [GENAI.AGENT_ID]: options.agentId,
+                });
+                childConfig = {
+                    model: options.configOverrides?.model ?? 'default',
+                    tokenBudget: allocatedTokens,
+                    timeoutMs: options.budgetAllocation?.timeoutMs ?? this.config.childTimeoutMs,
+                    streamIdleTimeoutMs: options.configOverrides?.streamIdleTimeoutMs,
+                    maxRequestRichContentBytes: options.configOverrides?.maxRequestRichContentBytes,
+                    attachmentResolveTimeoutMs: options.configOverrides?.attachmentResolveTimeoutMs,
+                    temperature: options.configOverrides?.temperature,
+                    parentSpan: options.configOverrides?.parentSpan,
+                    maxIterations: options.configOverrides?.maxIterations,
+                    maxResponseTokens: options.configOverrides?.maxResponseTokens,
+                    // A delegate spawned without a configBuilder lands here, and this
+                    // list is the only thing it inherits. Omitting these meant a child
+                    // silently ran at the default depth and effort its parent had
+                    // deliberately moved off.
+                    thinking: options.configOverrides?.thinking,
+                    effort: options.configOverrides?.effort,
+                    env: options.configOverrides?.env,
+                    sandbox: options.configOverrides?.sandbox,
+                    sessionId: spawnRecord.childSessionId,
+                    topicId: context.topicId,
+                    projectId: context.projectId,
+                    tenantId: context.tenantId,
+                    parentRunId: context.parentRunId,
+                    depth: context.depth + 1,
+                    resumeHandler: options.configOverrides?.resumeHandler ?? context.resumeHandler,
+                };
             }
-            // Stamped for the same reason as the trace parent above: a
-            // `configBuilder` is written by whoever registered the agent and
-            // cannot be trusted to forward something it was never told about.
-            // An explicit override still wins, so a host can hand one child a
-            // different channel — or none.
+            // 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;
+            childConfig.depth = context.depth + 1;
+            childConfig.budget = childBudget;
+            // The reservation is the execution ceiling, regardless of a builder's
+            // defaults or configOverrides. Zero means unlimited to query(), so it
+            // must inherit the finite allocation rather than erase that ceiling.
+            if (!Number.isFinite(childConfig.tokenBudget) || childConfig.tokenBudget < 0) {
+                throw new NamzuError({
+                    code: 'invalid_config',
+                    message: `Invalid child token budget for "${options.agentId}": ${childConfig.tokenBudget}`,
+                });
+            }
+            childConfig.tokenBudget =
+                childConfig.tokenBudget === 0
+                    ? allocatedTokens
+                    : Math.min(childConfig.tokenBudget, allocatedTokens);
+            childBudget.narrow(childConfig.tokenBudget);
+            // Stamped AFTER the builder, for the fourth time and the same reason:
+            // a `configBuilder` is written by whoever registered the agent and
+            // cannot forward a field it was never told about. A scope applied
+            // before it would be silently discarded by every builder that returns
+            // a fixed config — which is most of them.
             //
-            // 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.
-            const inheritedHandler = options.configOverrides?.resumeHandler ?? context.resumeHandler;
-            if (inheritedHandler)
-                childConfig.resumeHandler = inheritedHandler;
-            // And the environment, for the third time and the same reason.
+            // OUTSIDE the branch, unlike the four stamps above, and that is the
+            // point. Written inside the `configBuilder` arm it read correctly and
+            // left the bare-config arm below ignoring `toolScope` entirely — a
+            // caller that asked for a narrower child got a wider one, silently,
+            // and in the only direction that matters. Every other field here is
+            // an inheritance, where missing it costs the child something; this
+            // one is a restriction, where missing it costs the CALLER something.
+            //
+            // 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()`
+            // does, and which is why this appends to `deniedTools` rather than
+            // synthesising an allow-list.
+            if (resolvedDenies.length > 0) {
+                childConfig.deniedTools = [
+                    ...new Set([...(childConfig.deniedTools ?? []), ...resolvedDenies]),
+                ];
+            }
+            if (options.personaOverride)
+                childConfig.persona = options.personaOverride;
+            // Outside the branch, like the scope above it and for the same reason:
+            // a `configBuilder` cannot forward a field it was never told about.
             //
-            // The bare-config branch below has always carried `env`; this one
-            // never did, so a delegate registered WITH a `configBuilder` — the
-            // normal way, and what every host in this repo does — silently ran
-            // with none of the environment its parent had been given. The
-            // builder is written by whoever registered the agent and cannot be
-            // expected to forward a field it was never told about, which is
-            // exactly why `parentSpan` and `resumeHandler` are stamped here too.
+            // Bound to the taskId rather than to the task object, so a drain after
+            // the task is gone throws where the caller is instead of returning an
+            // empty array from a closure over a corpse.
             //
-            // Merged per key rather than replaced. `configOverrides` is a
-            // `Partial`, so assigning the whole map would drop every key the
-            // builder set and the caller did not restate — the override wins per
-            // key, the same direction it already wins for `model` and `effort`.
-            const inheritedEnv = mergeEnv(childConfig.env, options.configOverrides?.env);
-            if (inheritedEnv)
-                childConfig.env = inheritedEnv;
-            // A builder may ignore a newly-added factory option. The requested root
-            // policy is an execution boundary, so stamp an explicit child override
-            // after the builder rather than silently falling back to ephemeral.
-            if (options.configOverrides?.sandbox) {
-                childConfig.sandbox = options.configOverrides.sandbox;
+            // This is the delivery point `pendingMessages` never had.
+            // `continueTask` and `queueMessage` pushed onto it and nothing in the
+            // kernel drained it — the manager interface's own docblock said "the
+            // runtime does not deliver it", and `continue_task` was unmounted from
+            // the coordinator tools because of that.
+            childConfig.inboundMessages = () => this.drainMessages(taskId);
+            childAbortController.signal.throwIfAborted();
+            await childBudget.flush();
+            childAbortController.signal.throwIfAborted();
+            this.runChild(agentTask, options, childConfig, listener).catch(async (err) => {
+                // A thrown invocation supplied no final usage receipt. Keep its
+                // reservation, including when its task handle was canceled or evicted.
+                let failure = err;
+                try {
+                    await childBudget.flush();
+                }
+                catch (writeError) {
+                    failure = writeError;
+                }
+                this.markFailed(taskId, toErrorMessage(failure));
+            });
+            return agentTask;
+        }
+        catch (err) {
+            // No child invocation has been admitted: all reserved tokens and all
+            // provisioned resources are still ours to return. A builder/listener
+            // failure must not strand a pending task the caller never received.
+            if (agentTask) {
+                await this.rollbackUnstartedSpawn(agentTask, spawnRecord, err);
             }
+            else {
+                childAbortController?.abort();
+                childBudget.settle(0);
+                await childBudget.flush();
+                await this.rollbackSpawnResources(spawnRecord);
+            }
+            throw err;
         }
-        else {
-            this.log.warn('No configBuilder, using bare config', {
-                [GENAI.AGENT_ID]: options.agentId,
-            });
-            childConfig = {
-                model: options.configOverrides?.model ?? 'default',
-                tokenBudget: allocatedTokens,
-                timeoutMs: options.budgetAllocation?.timeoutMs ?? this.config.childTimeoutMs,
-                streamIdleTimeoutMs: options.configOverrides?.streamIdleTimeoutMs,
-                maxRequestRichContentBytes: options.configOverrides?.maxRequestRichContentBytes,
-                attachmentResolveTimeoutMs: options.configOverrides?.attachmentResolveTimeoutMs,
-                temperature: options.configOverrides?.temperature,
-                parentSpan: options.configOverrides?.parentSpan,
-                maxIterations: options.configOverrides?.maxIterations,
-                maxResponseTokens: options.configOverrides?.maxResponseTokens,
-                // A delegate spawned without a configBuilder lands here, and this
-                // list is the only thing it inherits. Omitting these meant a child
-                // silently ran at the default depth and effort its parent had
-                // deliberately moved off.
-                thinking: options.configOverrides?.thinking,
-                effort: options.configOverrides?.effort,
-                env: options.configOverrides?.env,
-                sandbox: options.configOverrides?.sandbox,
-                sessionId: spawnRecord.childSessionId,
-                topicId: context.topicId,
-                projectId: context.projectId,
-                tenantId: context.tenantId,
-                parentRunId: context.parentRunId,
-                depth: context.depth + 1,
-                resumeHandler: options.configOverrides?.resumeHandler ?? context.resumeHandler,
-            };
+    }
+    async rollbackUnstartedSpawn(agentTask, spawnRecord, reason) {
+        agentTask.childAbortController.abort();
+        agentTask.context.budget.settle(0);
+        await agentTask.context.budget.flush();
+        if (!isTerminalAgentTaskState(agentTask.state)) {
+            agentTask.state = 'failed';
+            const error = toErrorMessage(reason);
+            this.emit({ type: 'failed', taskId: agentTask.taskId, error });
+            try {
+                await agentTask.runEventListener?.({
+                    type: 'agent_failed',
+                    runId: agentTask.context.parentRunId,
+                    taskId: agentTask.taskId,
+                    error,
+                });
+            }
+            catch (err) {
+                this.log.warn('Unstarted child failure notification failed', {
+                    'namzu.task.id': agentTask.taskId,
+                    'exception.message': toErrorMessage(err),
+                });
+            }
         }
-        // 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;
-        childConfig.depth = context.depth + 1;
-        // Stamped AFTER the builder, for the fourth time and the same reason:
-        // a `configBuilder` is written by whoever registered the agent and
-        // cannot forward a field it was never told about. A scope applied
-        // before it would be silently discarded by every builder that returns
-        // a fixed config — which is most of them.
-        //
-        // OUTSIDE the branch, unlike the four stamps above, and that is the
-        // point. Written inside the `configBuilder` arm it read correctly and
-        // left the bare-config arm below ignoring `toolScope` entirely — a
-        // caller that asked for a narrower child got a wider one, silently,
-        // and in the only direction that matters. Every other field here is
-        // an inheritance, where missing it costs the child something; this
-        // one is a restriction, where missing it costs the CALLER something.
-        //
-        // 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()`
-        // does, and which is why this appends to `deniedTools` rather than
-        // synthesising an allow-list.
-        if (resolvedDenies.length > 0) {
-            childConfig.deniedTools = [
-                ...new Set([...(childConfig.deniedTools ?? []), ...resolvedDenies]),
-            ];
+        this.clearEvictionTimer(agentTask.taskId);
+        this.instances.delete(agentTask.taskId);
+        this.spawnRecords.delete(agentTask.taskId);
+        this.resolveCompletionCallbacks(agentTask.taskId);
+        await this.rollbackSpawnResources(spawnRecord);
+    }
+    async rollbackSpawnResources(spawnRecord) {
+        await this.disposeChildWorkspace(spawnRecord);
+        try {
+            // The edge must be removed before its child: stores reject deletion
+            // of a session that still has a subsession reference.
+            await this.deps.sessionStore.deleteSubSession(spawnRecord.subSessionId, spawnRecord.tenantId);
+            await this.deps.sessionStore.deleteSession(spawnRecord.childSessionId, spawnRecord.tenantId);
+        }
+        catch (err) {
+            this.log.warn('Unstarted child rollback failed', {
+                'namzu.sub_session.id': spawnRecord.subSessionId,
+                'exception.message': toErrorMessage(err),
+            });
         }
-        if (options.personaOverride)
-            childConfig.persona = options.personaOverride;
-        // Outside the branch, like the scope above it and for the same reason:
-        // a `configBuilder` cannot forward a field it was never told about.
-        //
-        // Bound to the taskId rather than to the task object, so a drain after
-        // the task is gone throws where the caller is instead of returning an
-        // empty array from a closure over a corpse.
-        //
-        // This is the delivery point `pendingMessages` never had.
-        // `continueTask` and `queueMessage` pushed onto it and nothing in the
-        // kernel drained it — the manager interface's own docblock said "the
-        // runtime does not deliver it", and `continue_task` was unmounted from
-        // the coordinator tools because of that.
-        childConfig.inboundMessages = () => this.drainMessages(taskId);
-        this.runChild(agentTask, options, childConfig, listener).catch((err) => {
-            this.markFailed(taskId, toErrorMessage(err));
-        });
-        return agentTask;
     }
     cancel(taskId, cause) {
         const agentTask = this.instances.get(taskId);
@@ -494,34 +592,6 @@ export class AgentManager {
         }
     }
     async provisionSpawnUnlocked(options, context) {
-        // Read the parent's remaining budget HERE, inside the lock, so that
-        // concurrent siblings queue behind one another rather than all reading
-        // the same untouched number. The debit at the end of this method closes
-        // the pair: read and write are now on the same side of every await.
-        const maxAllocation = Math.floor(context.budgetTracker.remaining * this.config.maxBudgetFraction);
-        const allocatedTokens = Math.min(options.budgetAllocation?.tokenBudget ?? maxAllocation, maxAllocation);
-        // Budget exhaustion must not INVERT into no budget at all. Downstream,
-        // `tokenBudget: 0` means "uncapped" (`LimitChecker`: `tokenBudget > 0
-        // && total >= tokenBudget`), and `maxAllocation` floors to 0 as soon as
-        // the parent's remaining drops below `1 / maxBudgetFraction`. So the
-        // most depleted parent in the tree was the one that spawned an
-        // unlimited child. Refuse instead: a caller that wants an uncapped
-        // child can say so explicitly with its own `budgetAllocation`.
-        //
-        // Refusing before any provisioning work also preserves the property the
-        // debit's placement was chosen for: a spawn this call rejects makes no
-        // state change at all, and burns no allocation.
-        if (allocatedTokens <= 0) {
-            throw new NamzuError({
-                code: 'invalid_config',
-                message: `Cannot spawn "${options.agentId}": the parent has ${context.budgetTracker.remaining} tokens remaining, which allocates 0 to the child — and a token budget of 0 means UNLIMITED downstream.`,
-                details: {
-                    agentId: options.agentId,
-                    parentRemaining: context.budgetTracker.remaining,
-                    maxBudgetFraction: this.config.maxBudgetFraction,
-                },
-            });
-        }
         // Phase 9: deps are unconditional required. Every spawn produces a
         // SubSession + Session + WorkspaceRef triple (Convention #0: no
         // partial/legacy path).
@@ -635,6 +705,12 @@ export class AgentManager {
             }
         }
         catch (err) {
+            if (workspaceRef && subSession) {
+                await this.disposeChildWorkspace({
+                    workspaceRef,
+                    subSessionId: subSession.id,
+                });
+            }
             // Compensating rollback order is mandated by the store's
             // deny-by-default cascade policy (Convention #5): `deleteSession`
             // throws when any subsession still references it, so the subsession
@@ -651,23 +727,14 @@ export class AgentManager {
             await store.deleteSession(childSession.id, context.tenantId).catch(() => undefined);
             throw err;
         }
-        // Debited only now, with the provisioning committed. Every path that
-        // could still have thrown is behind us, so a rejected spawn leaves the
-        // parent's budget untouched — the property the debit's original
-        // placement was chosen for, kept while closing the race that placement
-        // opened.
-        context.budgetTracker.remaining -= allocatedTokens;
         return {
-            spawnRecord: {
-                subSessionId: subSession.id,
-                childSessionId: childSession.id,
-                tenantId: context.tenantId,
-                parentSessionId: options.parentSessionId,
-                rootSessionId,
-                childDepth,
-                workspaceRef,
-            },
-            allocatedTokens,
+            subSessionId: subSession.id,
+            childSessionId: childSession.id,
+            tenantId: context.tenantId,
+            parentSessionId: options.parentSessionId,
+            rootSessionId,
+            childDepth,
+            workspaceRef,
         };
     }
     async runChild(agentTask, options, childConfig, listener) {
@@ -680,6 +747,9 @@ 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.settle(result.usage?.totalTokens);
+        await agentTask.context.budget.flush();
         await this.finalizeChild(agentTask, result);
     }
     /**
@@ -795,44 +865,10 @@ export class AgentManager {
         }
         this.markCompleted(agentTask.taskId, result);
     }
-    /**
-     * Return the unspent part of a settled child's reservation.
-     *
-     * The debit at spawn reserves headroom so siblings cannot each be
-     * promised the same tokens. Nothing returned it, so a pool shrank by
-     * the full allocation on every spawn no matter what the child used: at
-     * a half-pool fraction, ten delegations left a parent with a
-     * thousandth of its budget and the next spawn was refused for a budget
-     * that had barely been spent.
-     *
-     * Idempotent — the reservation is cleared as it is returned, so a
-     * second terminal transition for the same task cannot credit twice.
-     * Spend above the reservation returns nothing rather than going
-     * negative; the child was capped at its allocation, so that case means
-     * the accounting was already wrong and inventing headroom would hide
-     * it.
-     */
-    releaseBudget(agentTask, spent) {
-        const reserved = agentTask.budgetReservation;
-        if (reserved === undefined)
-            return;
-        agentTask.budgetReservation = undefined;
-        const unused = Math.max(0, reserved - Math.max(0, spent));
-        if (unused === 0)
-            return;
-        agentTask.context.budgetTracker.remaining += unused;
-        this.log.debug('Returned unspent child budget', {
-            'namzu.task.id': agentTask.taskId,
-            'namzu.manager.reserved': reserved,
-            'namzu.manager.spent': spent,
-            'namzu.manager.returned': unused,
-        });
-    }
     markCompleted(taskId, result) {
         const agentTask = this.instances.get(taskId);
         if (!agentTask || isTerminalAgentTaskState(agentTask.state))
             return;
-        this.releaseBudget(agentTask, result.usage?.totalTokens ?? 0);
         agentTask.result = result;
         agentTask.completedAt = Date.now();
         this.updateState(taskId, 'completed');
@@ -851,15 +887,12 @@ export class AgentManager {
         const agentTask = this.instances.get(taskId);
         if (!agentTask || isTerminalAgentTaskState(agentTask.state))
             return;
-        // A child that failed still spent whatever it spent, and holding the
-        // rest of its reservation would punish the parent twice for one
-        // failure.
-        this.releaseBudget(agentTask, agentTask.result?.usage?.totalTokens ?? 0);
         agentTask.result = {
-            runId: agentTask.context.parentRunId,
+            runId: agentTask.context.budget.runId ?? agentTask.context.parentRunId,
             status: 'failed',
-            usage: { ...EMPTY_TOKEN_USAGE },
-            cost: { ...ZERO_COST },
+            usage: agentTask.context.budget.ownUsage,
+            budget: agentTask.context.budget.summary(),
+            cost: { ...ZERO_COST, unpricedTokens: agentTask.context.budget.ownTokens },
             iterations: 0,
             durationMs: Date.now() - agentTask.createdAt,
             messages: [],