@namzu/sdk 32.0.0 → 33.1.0

package/src/runtime/query/resume-pending.ts

@@ -1,8 +1,11 @@
+import { isDeepStrictEqual } from 'node:util'
+
 import type { RunPersistence } from '../../manager/run/persistence.js'
 import type {
 	CheckpointId,
 	HITLResumeDecision,
 	IterationCheckpoint,
+	ToolCallSummary,
 } from '../../types/hitl/index.js'
 import type { AssistantMessage, Message, ToolCall } from '../../types/message/index.js'
 import type { ChatCompletionResponse } from '../../types/provider/index.js'
@@ -38,6 +41,10 @@ export interface PendingResumePlan {
 	readonly response: ChatCompletionResponse
 	/** Per-call refusals derived from the decision. */
 	readonly denials: ToolCallDenials
+	/** Exact projections and gate decisions persisted with a tool review. */
+	readonly reviewedCalls?: readonly ToolCallSummary[]
+	/** Calls whose raw input the human replaced in the durable decision. */
+	readonly modifiedCallIds?: ReadonlySet<string>
 	/**
 	 * Answers to deliver to tools that parked on a question, keyed by the
 	 * asking call's id. Present only on a question resume.
@@ -117,6 +124,8 @@ export function planPendingResume(
 		assistant,
 		response: synthesizeResponse(assistant),
 		denials,
+		reviewedCalls: pending.request.toolCalls,
+		modifiedCallIds: modifiedCallIds(decision),
 	}
 }
 
@@ -246,13 +255,86 @@ export async function applyPendingResume(
 	executor: ToolExecutor,
 	prior?: PriorToolResults,
 ): Promise<void> {
+	const denials = new Map(plan.denials)
+	const reviewedById = new Map(plan.reviewedCalls?.map((call) => [call.id, call]))
+
+	// A gate denial belongs to the run, not to the process that first evaluated
+	// it. Restore it before preparation so denied calls do not even reach a
+	// pre-tool hook after restart.
+	for (const call of plan.reviewedCalls ?? []) {
+		if (call.authorization?.decision !== 'deny' || denials.has(call.id)) continue
+		denials.set(
+			call.id,
+			`Blocked by the authorization gate: ${call.authorization.reason ?? 'the persisted operator policy denied this call'}`,
+		)
+	}
+
+	const callsToPrepare = (plan.response.message.toolCalls ?? []).filter(
+		(call) => !prior?.has(call.id) && !denials.has(call.id),
+	)
+	const responseToPrepare: ChatCompletionResponse = {
+		...plan.response,
+		message: { ...plan.response.message, toolCalls: callsToPrepare },
+	}
+	const preparedBatch = await executor.prepareBatchForReview(responseToPrepare)
+
+	for (const call of preparedBatch.reviewCalls) {
+		const reviewed = reviewedById.get(call.id)
+		const wasModified = plan.modifiedCallIds?.has(call.id) === true
+		if (reviewed && !wasModified) {
+			const unchanged = reviewed.name === call.name && isDeepStrictEqual(reviewed.input, call.input)
+			if (!unchanged) {
+				const reason =
+					'The tool input changed after its durable review; the earlier approval cannot be reused.'
+				denials.set(call.id, reason)
+				await runMgr.recordAudit({
+					what: { action: 'tool_call', tool: call.name },
+					outcome: 'refused',
+					reason,
+				})
+				continue
+			}
+		}
+
+		const current = executor.evaluatePreparedAuthorization(call.name, call.input)
+		let reason: string | undefined
+		if (current?.decision === 'deny') {
+			reason = `Blocked by the authorization gate after resume: ${current.reason}`
+		} else if (current?.decision === 'review' && (wasModified || !reviewed)) {
+			reason = wasModified
+				? `Blocked by the authorization gate after resume: the modified prepared value requires a new explicit approval. ${current.reason}`
+				: `Blocked by the authorization gate after resume: this recovered call requires operator review. ${current.reason}`
+		} else if (!current && reviewed && reviewed.authorization === undefined) {
+			reason =
+				'The durable review predates bound authorization metadata; review this call again before execution.'
+		}
+
+		if (reason) {
+			denials.set(call.id, reason)
+			await runMgr.recordAudit({
+				what: { action: 'tool_call', tool: call.name },
+				outcome: 'refused',
+				reason,
+			})
+		}
+	}
+
 	runMgr.pushMessage(plan.assistant)
-	const batch = await executor.executeBatch(plan.response, plan.denials, prior)
+	const batch = await executor.executeBatch(plan.response, denials, prior, preparedBatch)
 	for (const msg of batch.messages) {
 		runMgr.pushMessage(msg)
 	}
 }
 
+function modifiedCallIds(decision: HITLResumeDecision): ReadonlySet<string> {
+	if (decision.action !== 'modify_tools') return new Set()
+	return new Set(
+		decision.modifications
+			.filter((modification) => modification.action === 'modify')
+			.map((modification) => modification.toolCallId),
+	)
+}
+
 /**
  * Results the run already produced for calls in `toolCalls`.
  *

package/src/runtime/query/tool-output-budget.ts

@@ -37,6 +37,57 @@ export const SPILL_MARKER = 'The full output was written to:'
  */
 const HEAD_SHARE = 0.75
 
+function safeHead(text: string, maxChars: number): string {
+	let end = Math.min(text.length, Math.max(0, maxChars))
+	if (end > 0) {
+		const last = text.charCodeAt(end - 1)
+		if (last >= 0xd800 && last <= 0xdbff) end--
+	}
+	return text.slice(0, end)
+}
+
+function safeTail(text: string, maxChars: number): string {
+	let start = Math.max(0, text.length - Math.max(0, maxChars))
+	if (start < text.length) {
+		const first = text.charCodeAt(start)
+		if (first >= 0xdc00 && first <= 0xdfff) start++
+	}
+	return text.slice(start)
+}
+
+/**
+ * Fit a recoverable head+tail preview inside the actual model-visible cap.
+ *
+ * The old implementation allocated the entire cap to source text and then
+ * appended its diagnostic and recovery instructions. A configured 1,000
+ * character cap therefore emitted 1,200–1,300 characters; at very small
+ * limits the explanation could be several times larger than the limit.
+ */
+function boundedPreview(
+	output: string,
+	maxChars: number,
+	toolName: string,
+	recovery: string,
+): string {
+	const detailedMiddle = [
+		'',
+		`[... characters omitted — "${toolName}" returned ${output.length.toLocaleString()} characters, over the ${maxChars.toLocaleString()}-character budget ...]`,
+		recovery,
+		'',
+	].join('\n')
+	const compactMiddle = '\n[... omitted ...]\n'
+	const middle = detailedMiddle.length < maxChars ? detailedMiddle : compactMiddle
+
+	// A host may deliberately set a tiny positive cap. At that point no
+	// truthful recovery sentence fits; the hard bound still wins.
+	if (middle.length >= maxChars) return safeHead(middle, maxChars)
+
+	const sourceChars = maxChars - middle.length
+	const headChars = Math.max(1, Math.floor(sourceChars * HEAD_SHARE))
+	const tailChars = Math.max(0, sourceChars - headChars)
+	return `${safeHead(output, headChars)}${middle}${safeTail(output, tailChars)}`
+}
+
 export interface ToolOutputBudgetResult {
 	/** What the model sees. */
 	readonly output: string
@@ -127,15 +178,6 @@ export function applyToolOutputBudget(opts: ApplyToolOutputBudgetOptions): ToolO
 		return { output, originalLength, truncated: false }
 	}
 
-	// Both slices are derived from `maxChars` so the preview honours the
-	// budget it is enforcing. `slice(-0)` returns the WHOLE string, so the
-	// zero-tail case must be branched, not computed.
-	const headChars = Math.max(1, Math.floor(maxChars * HEAD_SHARE))
-	const tailChars = Math.max(0, maxChars - headChars)
-	const head = output.slice(0, headChars)
-	const tail = tailChars > 0 ? output.slice(-tailChars) : ''
-	const omitted = originalLength - head.length - tail.length
-
 	const spillPath = opts.spillDir
 		? spill(opts.spillDir, opts.toolUseId, output, opts.onError)
 		: undefined
@@ -148,14 +190,7 @@ export function applyToolOutputBudget(opts: ApplyToolOutputBudgetOptions): ToolO
 		: 'The full output was not retained. Re-run with a narrower query, a line range, or a filter.'
 
 	return {
-		output: [
-			head,
-			'',
-			`[... ${omitted.toLocaleString()} characters omitted — "${opts.toolName}" returned ${originalLength.toLocaleString()} characters, over the ${maxChars.toLocaleString()}-character budget ...]`,
-			recovery,
-			'',
-			tail,
-		].join('\n'),
+		output: boundedPreview(output, maxChars, opts.toolName, recovery),
 		originalLength,
 		truncated: true,
 		...(spillPath ? { spillPath } : {}),

package/src/runtime/query/tooling.ts

@@ -1,8 +1,10 @@
+import type { AuthorizationGate } from '../../authorization/gate.js'
 import type { PluginLifecycleManager } from '../../plugin/lifecycle.js'
 import type { ActivityStore } from '../../store/activity/memory.js'
 import type { RunId } from '../../types/ids/index.js'
 import type { InvocationState } from '../../types/invocation/index.js'
 import type { PermissionMode } from '../../types/permission/index.js'
+import type { AuditEventInput } from '../../types/run/audit.js'
 import type { RunEvent } from '../../types/run/index.js'
 import type {
 	RequestToolPause,
@@ -41,6 +43,10 @@ export interface ToolingBootstrapConfig {
 	maxToolContentBytes?: number
 	toolOutputDir?: string
 	repairToolCall?: RepairToolCall
+	/** Operator authorization shared with the direct-call review path. */
+	authorizationGate?: AuthorizationGate
+	/** Durable refusal recorder for nested authorization decisions. */
+	recordAudit?: (input: AuditEventInput) => Promise<unknown>
 	/** Builds the durable-pause seam for one tool call; see ToolContext.requestPause. */
 	toolPause?: (toolUseId: string) => RequestToolPause
 }
@@ -81,6 +87,10 @@ export class ToolingBootstrap {
 					: {}),
 				...(config.toolOutputDir !== undefined ? { toolOutputDir: config.toolOutputDir } : {}),
 				...(config.repairToolCall !== undefined ? { repairToolCall: config.repairToolCall } : {}),
+				...(config.authorizationGate !== undefined
+					? { authorizationGate: config.authorizationGate }
+					: {}),
+				...(config.recordAudit !== undefined ? { recordAudit: config.recordAudit } : {}),
 				...(config.toolPause !== undefined ? { toolPause: config.toolPause } : {}),
 			},
 			activityStore,

package/src/sandbox/provider/local.ts

@@ -38,6 +38,7 @@ import type {
 	SandboxProvider,
 	SandboxStatus,
 } from '../../types/sandbox/index.js'
+import { subscribeToAbort } from '../../utils/abort.js'
 import { generateSandboxId } from '../../utils/id.js'
 import type { Logger } from '../../utils/logger.js'
 import {
@@ -72,6 +73,8 @@ function assertInsideSandbox(sandboxRoot: string, targetPath: string): string {
 const LINUX_UNSHARE_FLAGS = ['--mount', '--pid', '--fork', '--map-root-user', '--net']
 
 const SPAWN_PROBE_SENTINEL = 'namzu-sandbox-spawn-probe'
+const BWRAP_INFO_FD = 3
+const BWRAP_BLOCK_FD = 4
 
 interface SpawnProbeObservation {
 	readonly error?: unknown
@@ -117,6 +120,48 @@ function probeSandboxSpawn(command: string, wrapperArgs: readonly string[]): boo
 	return acceptsSandboxSpawnProbe(observation)
 }
 
+function readBwrapChildPid(value: string): number | undefined {
+	try {
+		const record = JSON.parse(value) as { readonly 'child-pid'?: unknown }
+		const pid = record['child-pid']
+		return typeof pid === 'number' && Number.isSafeInteger(pid) && pid > 0 ? pid : undefined
+	} catch {
+		return undefined
+	}
+}
+
+/** The bwrap tier is usable only if its child can be addressed after startup. */
+function probeBwrapSpawn(command: string, wrapperArgs: readonly string[]): boolean {
+	const observation = spawnSync(
+		command,
+		[
+			...wrapperArgs,
+			'--info-fd',
+			String(BWRAP_INFO_FD),
+			'--block-fd',
+			String(BWRAP_BLOCK_FD),
+			'--',
+			process.execPath,
+			'-e',
+			`process.stdout.write(${JSON.stringify(SPAWN_PROBE_SENTINEL)})`,
+		],
+		{
+			encoding: 'utf8',
+			timeout: 5_000,
+			// `/dev/null` proves the option is accepted and lets the synchronous
+			// probe proceed. Production supplies a live pipe and releases it only
+			// after the info record establishes ownership of the inner namespace.
+			stdio: ['ignore', 'pipe', 'pipe', 'pipe', 'ignore'],
+		},
+	)
+	const status = observation.output?.[BWRAP_INFO_FD]
+	return (
+		acceptsSandboxSpawnProbe(observation) &&
+		typeof status === 'string' &&
+		readBwrapChildPid(status) !== undefined
+	)
+}
+
 const TRUSTED_WRAPPER_CANDIDATES = {
 	bwrap: ['/usr/bin/bwrap', '/bin/bwrap', '/usr/sbin/bwrap'],
 	unshare: ['/usr/bin/unshare', '/bin/unshare', '/usr/sbin/unshare'],
@@ -275,7 +320,7 @@ function detectEnvironment(): DetectedEnvironment {
 		// hosts that mediate namespace helpers and can claim a tier production
 		// cannot actually drive.
 		const bwrap = resolveTrustedWrapper('bwrap')
-		if (bwrap !== undefined && probeSandboxSpawn(bwrap, buildBwrapArgs(tmpdir()))) {
+		if (bwrap !== undefined && probeBwrapSpawn(bwrap, buildBwrapArgs(tmpdir()))) {
 			return { environment: 'linux-bwrap', wrapperCommand: bwrap }
 		}
 
@@ -522,6 +567,27 @@ function buildSafeEnv(
 	return env
 }
 
+/**
+ * Reach bwrap's PID-namespace reaper as well as its outer host wrapper.
+ *
+ * `--new-session` deliberately moves the inner reaper out of the outer
+ * detached process group. `--die-with-parent` normally bridges that boundary,
+ * but there is a startup interval before the inner reaper has armed its parent
+ * death signal. `--info-fd` gives us the host pid once it exists. Address both
+ * its eventual process group and the pid itself: before `setsid` only the pid
+ * is valid; afterwards the negative pid reaches the complete inner session.
+ */
+function killBwrapChild(pid: number | undefined, signal: NodeJS.Signals): void {
+	if (pid === undefined || process.platform === 'win32') return
+	for (const target of [-pid, pid]) {
+		try {
+			process.kill(target, signal)
+		} catch {
+			// The other address may be the valid one, or the namespace is gone.
+		}
+	}
+}
+
 // ---------------------------------------------------------------------------
 // LocalSandbox
 // ---------------------------------------------------------------------------
@@ -577,7 +643,10 @@ class LocalSandbox implements Sandbox {
 
 		const cwd = opts?.cwd ? assertInsideSandbox(this.rootDir, opts.cwd) : this.rootDir
 
-		const { spawnCommand, spawnArgs } = this.buildSpawnArgs(command, args)
+		const { spawnCommand, spawnArgs, bwrapInfoFd, bwrapBlockFd } = this.buildSpawnArgs(
+			command,
+			args,
+		)
 
 		this.log.debug('Executing command', {
 			'namzu.sandbox.command': command,
@@ -586,23 +655,27 @@ class LocalSandbox implements Sandbox {
 			'namzu.execution.environment': this.environment,
 		})
 
-		// The caller's cancellation and this call's own deadline both have to
-		// reach `spawn`, and `spawn` takes exactly one signal.
-		//
-		// Only the deadline used to. `SandboxExecOptions.signal` is declared,
-		// documented, and exported, and every backend dropped it — so a Stop
-		// abandoned the *wait* and left the sandboxed process running, which is
-		// verbatim the failure the option's own docstring says it exists to
-		// prevent. `AbortSignal.any` is what makes both reach the child: it
-		// aborts as soon as either does, and — unlike an `addEventListener`
-		// bridge — it does not retain a listener on the caller's long-lived
-		// signal after this call settles.
+		// The caller's cancellation and this call's own deadline are separate
+		// causes. `spawn({ signal })` cannot own either one here: Node sends that
+		// signal only to the direct wrapper pid and removes its abort listener on
+		// `exit`, while this promise must wait for `close` so inherited stdout and
+		// stderr have drained. A wrapper can therefore exit before a descendant;
+		// an abort in that interval would reach nobody and the descendant would
+		// keep both pipes — and this call — alive.
 		const ac = new AbortController()
 		const timeoutId = setTimeout(() => ac.abort(), timeout)
-		const spawnSignal = opts?.signal ? AbortSignal.any([ac.signal, opts.signal]) : ac.signal
 
 		try {
-			const result = await this.spawnProcess(spawnCommand, spawnArgs, cwd, env, ac, spawnSignal)
+			const result = await this.spawnProcess(
+				spawnCommand,
+				spawnArgs,
+				cwd,
+				env,
+				ac.signal,
+				opts?.signal,
+				bwrapInfoFd,
+				bwrapBlockFd,
+			)
 			return { ...result, durationMs: Date.now() - startTime }
 		} finally {
 			clearTimeout(timeoutId)
@@ -685,8 +758,13 @@ class LocalSandbox implements Sandbox {
 	private buildSpawnArgs(
 		command: string,
 		args: string[],
-	): { spawnCommand: string; spawnArgs: string[] } {
-		return buildLimitedSpawn({
+	): {
+		spawnCommand: string
+		spawnArgs: string[]
+		bwrapInfoFd?: number
+		bwrapBlockFd?: number
+	} {
+		const built = buildLimitedSpawn({
 			environment: this.environment,
 			...(this.wrapperCommand !== undefined ? { wrapperCommand: this.wrapperCommand } : {}),
 			command,
@@ -697,24 +775,40 @@ class LocalSandbox implements Sandbox {
 				: {}),
 			...(this.config.maxProcesses !== undefined ? { maxProcesses: this.config.maxProcesses } : {}),
 		})
+		if (this.environment !== 'linux-bwrap') return built
+
+		const separator = built.spawnArgs.indexOf('--')
+		if (separator < 0) throw new Error('bwrap invocation has no command separator')
+		return {
+			spawnCommand: built.spawnCommand,
+			spawnArgs: [
+				...built.spawnArgs.slice(0, separator),
+				'--info-fd',
+				String(BWRAP_INFO_FD),
+				'--block-fd',
+				String(BWRAP_BLOCK_FD),
+				...built.spawnArgs.slice(separator),
+			],
+			bwrapInfoFd: BWRAP_INFO_FD,
+			bwrapBlockFd: BWRAP_BLOCK_FD,
+		}
 	}
 
 	/**
-	 * @param ac      this call's own deadline — still the thing that decides
-	 *                whether a termination is reported as `timedOut`.
-	 * @param signal  what actually reaches `spawn`: the deadline, merged with
-	 *                the caller's cancellation when one was passed. Two
-	 *                parameters because they answer different questions —
-	 *                "should this process die" and "did it die because it ran
-	 *                too long" — and a cancelled run did not time out.
+	 * The two signals stay distinct so the first accepted cause is latched.
+	 * Reading `deadline.aborted` later would let a deadline that fired while a
+	 * caller cancellation was draining retroactively turn that cancellation
+	 * into a timeout.
 	 */
 	private spawnProcess(
 		command: string,
 		args: string[],
 		cwd: string,
 		env: Record<string, string>,
-		ac: AbortController,
-		signal: AbortSignal = ac.signal,
+		deadlineSignal: AbortSignal,
+		callerSignal?: AbortSignal,
+		bwrapInfoFd?: number,
+		bwrapBlockFd?: number,
 	): Promise<Omit<SandboxExecResult, 'durationMs'>> {
 		return new Promise((resolvePromise, rejectPromise) => {
 			let child: ReturnType<typeof spawn>
@@ -722,8 +816,10 @@ class LocalSandbox implements Sandbox {
 				child = spawn(command, args, {
 					cwd,
 					env,
-					stdio: ['pipe', 'pipe', 'pipe'],
-					signal,
+					stdio:
+						bwrapInfoFd === undefined
+							? ['pipe', 'pipe', 'pipe']
+							: ['pipe', 'pipe', 'pipe', 'pipe', 'pipe'],
 					// Leader of its own process group (POSIX only — Windows has
 					// nothing to opt into here), not a member of this Node
 					// process's. That is what lets `killTree` below reach `cmd`
@@ -738,30 +834,92 @@ class LocalSandbox implements Sandbox {
 
 			const stdout = new CappedStream(SANDBOX_MAX_OUTPUT_BYTES)
 			const stderr = new CappedStream(SANDBOX_MAX_OUTPUT_BYTES)
-			let timedOut = false
+			let cancellation: 'caller' | 'deadline' | undefined
+			let bwrapChildPid: number | undefined
+			let terminationSignal: NodeJS.Signals | undefined
+			let settled = false
+			let escalation: ReturnType<typeof setTimeout> | undefined
+			const disposeAbortListeners: Array<() => void> = []
+
+			const finishSubscriptions = () => {
+				for (const dispose of disposeAbortListeners.splice(0)) dispose()
+			}
+			const terminate = (signal: NodeJS.Signals) => {
+				terminationSignal = signal
+				// Before bwrap publishes its inner reaper, killing only the outer
+				// wrapper can strand startup between fork() and PR_SET_PDEATHSIG. Its
+				// block fd guarantees the authored command is not admitted meanwhile;
+				// retain the wrapper until the addressable inner pid arrives.
+				if (bwrapBlockFd !== undefined && bwrapChildPid === undefined) return
+				killTree(child, signal)
+				killBwrapChild(bwrapChildPid, signal)
+			}
+			const cancel = (origin: 'caller' | 'deadline') => {
+				if (settled || cancellation !== undefined) return
+				cancellation = origin
+				// Own the group while its leader is still ours. Deferring this to
+				// Node's AbortError loses the wrapper-exit/stdio-close interval.
+				terminate('SIGTERM')
+				escalation = setTimeout(() => {
+					escalation = undefined
+					terminate('SIGKILL')
+				}, SANDBOX_KILL_GRACE_MS)
+				// A command that honoured SIGTERM must not leave the host alive just
+				// to deliver a no-op escalation. If shared stdio closes first, the
+				// close handler forces any remaining group before releasing its pid.
+				escalation.unref?.()
+			}
 
 			child.stdout?.on('data', (chunk: Buffer) => stdout.push(chunk))
 			child.stderr?.on('data', (chunk: Buffer) => stderr.push(chunk))
-
-			child.on('error', (err: NodeJS.ErrnoException) => {
-				if (err.code === 'ABORT_ERR' || signal.aborted) {
-					// `timedOut` means the DEADLINE fired. A caller-cancelled
-					// run is aborted but not late, and reporting it as a
-					// timeout would tell the model to retry with a longer
-					// budget for something a human just stopped.
-					timedOut = ac.signal.aborted
-					// `spawn`'s own `signal` handling already reached `child.pid`
-					// — the outermost wrapper — but that was never the process
-					// this call exists to stop. Reach the whole tree, then give
-					// it a grace period before forcing it.
-					killTree(child, 'SIGTERM')
-					setTimeout(() => killTree(child, 'SIGKILL'), SANDBOX_KILL_GRACE_MS)
-					return
+			const bwrapInfo = bwrapInfoFd === undefined ? undefined : child.stdio[bwrapInfoFd]
+			const bwrapBlock = bwrapBlockFd === undefined ? undefined : child.stdio[bwrapBlockFd]
+			let bwrapInfoBuffer = ''
+			bwrapInfo?.on('data', (chunk: Buffer) => {
+				if (bwrapChildPid !== undefined) return
+				bwrapInfoBuffer += chunk.toString('utf8')
+				// `--info-fd` writes one JSON document, often pretty-printed across
+				// several lines and potentially split across stream chunks. Parse the
+				// whole accumulated document whenever more arrives.
+				const observed = readBwrapChildPid(bwrapInfoBuffer)
+				if (observed === undefined) return
+				bwrapChildPid = observed
+				// Cancellation may have won before bwrap published the inner reaper.
+				// Nothing authored has been admitted yet, so there is no graceful
+				// shutdown to preserve: kill startup atomically before it can cross the
+				// gate. Otherwise one byte admits the command now that it has an owner.
+				if (terminationSignal !== undefined) {
+					if (escalation !== undefined) {
+						clearTimeout(escalation)
+						escalation = undefined
+					}
+					terminate('SIGKILL')
+				} else if (bwrapBlock !== undefined && bwrapBlock !== null && 'end' in bwrapBlock) {
+					bwrapBlock.end(Buffer.from([1]))
 				}
+			})
+
+			child.once('error', (err: NodeJS.ErrnoException) => {
+				if (settled) return
+				settled = true
+				finishSubscriptions()
+				if (escalation !== undefined) clearTimeout(escalation)
 				rejectPromise(err)
 			})
 
-			child.on('close', (code, signal) => {
+			child.once('close', (code, signal) => {
+				if (settled) return
+				settled = true
+				finishSubscriptions()
+				if (escalation !== undefined) {
+					clearTimeout(escalation)
+					escalation = undefined
+					// `close` proves the wrapper and shared pipes are gone, not that a
+					// descendant which closed its copies has stopped. Force the old group
+					// now: retaining its numeric pid for a later timer risks pid reuse.
+					terminate('SIGKILL')
+				}
+				const timedOut = cancellation === 'deadline'
 				resolvePromise({
 					exitCode: code ?? (timedOut ? 124 : 1),
 					stdout: stdout.text,
@@ -776,6 +934,16 @@ class LocalSandbox implements Sandbox {
 					stderrTruncated: stderr.truncated,
 				})
 			})
+
+			// Register only after every terminal handler exists, then re-check.
+			// JavaScript cannot interleave an abort callback inside this synchronous
+			// block, and the check closes the already-aborted admission edge.
+			disposeAbortListeners.push(subscribeToAbort(deadlineSignal, () => cancel('deadline')))
+			if (callerSignal !== undefined) {
+				disposeAbortListeners.push(subscribeToAbort(callerSignal, () => cancel('caller')))
+			}
+			if (deadlineSignal.aborted) cancel('deadline')
+			else if (callerSignal?.aborted) cancel('caller')
 		})
 	}
 }

package/src/scheduler/delegating.ts

@@ -4,6 +4,7 @@ import type { CreateTaskOptions, TaskHandle, TaskScheduler } from '../types/agen
 import type { AgentTaskState } from '../types/agent/task.js'
 import type { RunExecutionStatus } from '../types/common/index.js'
 import type { TaskId } from '../types/ids/index.js'
+import { type CancelCause, RunCancelled } from '../types/run/cancel-cause.js'
 import { asRunId, generateTaskId } from '../utils/id.js'
 
 /**
@@ -248,16 +249,16 @@ export class DelegatingTaskScheduler implements TaskScheduler {
 		await entry.delegate.continue(message)
 	}
 
-	cancelTask(taskId: TaskId): void {
+	cancelTask(taskId: TaskId, cause?: CancelCause): void {
 		const entry = this.tasks.get(taskId)
 		if (!entry) {
-			this.config.local?.cancelTask(taskId)
+			this.config.local?.cancelTask(taskId, cause)
 			return
 		}
 		if (!entry.delegate.capabilities.cancel) {
 			throw new DelegateCapabilityError({ id: entry.delegate.id, capability: 'cancel' })
 		}
-		controllerAbort(entry)
+		controllerAbort(entry, cause)
 	}
 
 	getTask(taskId: TaskId): TaskHandle | undefined {
@@ -292,6 +293,6 @@ export class DelegatingTaskScheduler implements TaskScheduler {
  * race that: a delegate that completed a microsecond before the abort would
  * be recorded as cancelled while its answer sat unread.
  */
-function controllerAbort(entry: Entry): void {
-	entry.controller.abort()
+function controllerAbort(entry: Entry, cause?: CancelCause): void {
+	entry.controller.abort(cause ? new RunCancelled(cause) : undefined)
 }

package/src/scheduler/local.ts

@@ -11,6 +11,7 @@ import type {
 import type { AgentTaskContext } from '../types/agent/task.js'
 import type { TaskId } from '../types/ids/index.js'
 import { createUserMessage } from '../types/message/index.js'
+import type { CancelCause } from '../types/run/cancel-cause.js'
 import type { RunEventListener } from '../types/run/events.js'
 import { toErrorMessage } from '../utils/error.js'
 import { SCOPE_ATTRIBUTE } from '../utils/log/types.js'
@@ -244,8 +245,8 @@ export class LocalTaskScheduler implements TaskScheduler {
 		await this.agentManager.continueTask(taskId, message)
 	}
 
-	cancelTask(taskId: TaskId): void {
-		this.agentManager.cancel(taskId)
+	cancelTask(taskId: TaskId, cause?: CancelCause): void {
+		this.agentManager.cancel(taskId, cause)
 	}
 
 	getTask(taskId: TaskId): TaskHandle | undefined {