@namzu/sdk 58.1.1 → 60.0.0

package/src/runtime/query/index.ts

@@ -113,6 +113,7 @@ import {
 	SandboxAcquisitionStopped,
 	createDeferredSandbox,
 } from './deferred-sandbox.js'
+import { DetachedCalls } from './detached-calls.js'
 import type { EventTranslator } from './events.js'
 import { finalizeTurn } from './finalize-turn.js'
 import { GuardCoordinator } from './guard.js'
@@ -150,6 +151,7 @@ import { acquireSandbox } from './sandbox-lifecycle.js'
 import {
 	SteeringBinding,
 	type SteeringChannel,
+	formatJobExitNotice,
 	formatMonitorEnd,
 	formatMonitorEvent,
 	isOperatorUserMessage,
@@ -808,6 +810,28 @@ export interface QueryParams {
 	 */
 	waitForInbound?: (signal: AbortSignal) => Promise<void>
 
+	/**
+	 * Answer the operator while a long tool call is still running.
+	 *
+	 * Default off. When on, and `waitForOperator` reports the operator wrote while
+	 * a batch had been running for two seconds, each call not yet finished is answered with a "still running"
+	 * placeholder so the model can read the message and reply at once. The
+	 * calls are not interrupted and not repeated: their real results reach the
+	 * model later in a message that names each call, and the turn is held open
+	 * for them like any outstanding work. The host's wake is then also consulted
+	 * during tool batches, not only when the turn would otherwise end. Ignored
+	 * under per-call review, where the batch is waiting on a person.
+	 */
+	answerWhileCallsRun?: boolean
+
+	/**
+	 * Resolve when the operator wrote, and for no other reason. It is what
+	 * `answerWhileCallsRun` listens to: a notice from a child agent or mail from
+	 * a peer also wakes `waitForInbound`, but must not hand a running call back.
+	 * Abort removes the waiter, as for `waitForInbound`.
+	 */
+	waitForOperator?: (signal: AbortSignal) => Promise<void>
+
 	/** Durable host input: normal append, flush and exact acknowledgement before inference. Requires sessionLog. */
 	durableInbound?: DurableInboundSource
 
@@ -1484,6 +1508,21 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 				)
 			: undefined
 		awaitedJobs?.attach()
+		// A tool result has handed the model this job's exit: the notice that
+		// would announce the same exit is taken back, and the host is told it was
+		// delivered so the session does not wake the model for it either.
+		const collectJob = (id: string): void => {
+			const withdrawn = jobNotices?.withdraw(id) ?? false
+			awaitedJobs?.collected(id)
+			if (!pendingJobNoticeIds.delete(id) && !withdrawn) return
+			try {
+				params.onJobNoticeDelivered?.([id])
+			} catch (error) {
+				ctx.log.warn('A background job notice observer failed', {
+					'exception.message': error instanceof Error ? error.message : String(error),
+				})
+			}
+		}
 
 		// Turn-scoped, like `toolGrants` below: what a skill loaded in this turn
 		// pre-approves ends with the turn. Shared by the executor, where the
@@ -1513,6 +1552,7 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 				...(params.backgroundJobs ? { backgroundJobs: params.backgroundJobs } : {}),
 				...(params.backgroundJobOwner ? { backgroundJobOwner: params.backgroundJobOwner } : {}),
 				...(awaitedJobs ? { onJobAwaited: (id: string) => awaitedJobs.expect(id) } : {}),
+				...(awaitedJobs ? { onJobCollected: collectJob } : {}),
 				...(awaitedJobs ? { onMonitorStarted: (id: string) => awaitedJobs.expectMonitor(id) } : {}),
 				...(params.monitorTimeoutCapMs !== undefined
 					? { monitorTimeoutCapMs: params.monitorTimeoutCapMs }
@@ -1611,13 +1651,13 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 					.catch(() => {})
 				return
 			}
-			const outcome =
-				job.status === 'killed'
-					? 'was stopped'
-					: `exited with code ${job.exitCode ?? 'unknown'}${job.signal ? ` (${job.signal})` : ''}`
-			jobNotices?.steer(
-				`Background job ${job.id} (${job.command}) ${outcome}. Read its output with the job tool if you need it.`,
-			)
+			let inlineOutput: ReturnType<NonNullable<typeof params.backgroundJobs>['read']> | undefined
+			try {
+				inlineOutput = params.backgroundJobs?.read(job.id)
+			} catch {
+				// The record is gone; the notice still stands without its output.
+			}
+			jobNotices?.steer(formatJobExitNotice(job, inlineOutput), job.id)
 			pendingJobNoticeIds.add(job.id)
 			void eventTranslator
 				.emitEvent({
@@ -1821,6 +1861,9 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 			...(monitorNotices ? { monitorNotices } : {}),
 			...(monitorNotices ? { onMonitorNoticeDelivered: acknowledgeMonitorNotices } : {}),
 			...(awaitedJobs ? { awaitedJobs } : {}),
+			...(params.answerWhileCallsRun && params.waitForOperator
+				? { detachedCalls: new DetachedCalls(params.waitForOperator) }
+				: {}),
 			checkpointMgr,
 			planManager: ctx.planManager,
 			taskGateway: taskScheduler,

package/src/runtime/query/iteration/outstanding-work.ts

@@ -5,6 +5,7 @@ import type { TaskHandle } from '../../../types/agent/scheduler.js'
 import { createRuntimeContextMessage } from '../../../types/message/index.js'
 import type { SessionEvent } from '../../../types/session/index.js'
 import { readPositiveIntEnv } from '../../../utils/env.js'
+import { formatLateResults } from '../detached-calls.js'
 import { formatJobNote, formatMonitorNote } from '../steering.js'
 import type { IterationContext } from './phases/index.js'
 
@@ -165,7 +166,8 @@ export async function* holdForOutstandingWork(
 ): AsyncGenerator<SessionEvent, boolean> {
 	const inbox = ctx.completionInbox?.holdsTurn ? ctx.completionInbox : undefined
 	const jobs = ctx.awaitedJobs?.hasPendingWork ? ctx.awaitedJobs : undefined
-	if (!inbox && !jobs) return false
+	const detached = ctx.detachedCalls?.hasWork ? ctx.detachedCalls : undefined
+	if (!inbox && !jobs && !detached) return false
 
 	// Read HERE rather than from `forceFinalize`, which was sampled at the
 	// top of the iteration: one that has since crossed the finalize point
@@ -179,7 +181,7 @@ export async function* holdForOutstandingWork(
 	// to be running. A job therefore never shortens a wait, and it never
 	// lengthens one either: where a task is outstanding too, that is how
 	// long this turn was waiting anyway.
-	let graceMs = inbox ? settleGraceMs(remainingMs) : awaitedJobGraceMs(remainingMs)
+	let graceMs = inbox || detached ? settleGraceMs(remainingMs) : awaitedJobGraceMs(remainingMs)
 	// A monitor the turn owns is held for until the monitor itself ends, which
 	// its own deadline bounds; the two-minute job ceiling would walk away from
 	// a watch with most of its time left. As with a task, this only ever
@@ -207,6 +209,7 @@ export async function* holdForOutstandingWork(
 		await Promise.race([
 			...(inbox ? [inbox.waitForArrival(graceMs, waiting.signal)] : []),
 			...(jobs ? [jobs.waitForArrival(graceMs, waiting.signal)] : []),
+			...(detached ? [detached.waitForArrival(graceMs, waiting.signal)] : []),
 			...(ctx.waitForInbound ? [ctx.waitForInbound(waiting.signal)] : []),
 			...(ctx.durableInbound?.wait ? [ctx.durableInbound.wait(waiting.signal)] : []),
 		])
@@ -228,8 +231,14 @@ export async function* holdForOutstandingWork(
 	}
 	const exited = deliverAwaitedJobExits(ctx)
 	const monitored = deliverMonitorNotices(ctx)
+	const late = ctx.detachedCalls?.take() ?? []
+	if (late.length > 0) {
+		ctx.recorder.pushMessage(createRuntimeContextMessage(formatLateResults(late), 'job-exit'))
+	}
 	const inbound = await deliverInbound()
-	if (arrived.length === 0 && !exited && !monitored && inbound === 0) return false
+	if (arrived.length === 0 && !exited && !monitored && late.length === 0 && inbound === 0) {
+		return false
+	}
 	await ctx.emitEvent({
 		type: 'iteration_completed',
 		turnId: ctx.recorder.turnId,

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

@@ -40,6 +40,7 @@ import type { TaskStore } from '../../../../types/task/index.js'
 import type { Logger } from '../../../../utils/logger.js'
 import type { AwaitedJobs } from '../../../jobs/awaited-jobs.js'
 import type { CheckpointManager } from '../../checkpoint.js'
+import type { DetachedCalls } from '../../detached-calls.js'
 import type { EmitEvent } from '../../events.js'
 import type { ToolExecutor } from '../../executor.js'
 import type { GuardCoordinator } from '../../guard.js'
@@ -171,6 +172,12 @@ export interface IterationContext {
 	 * and a turn whose model stopped calling tools settles without waiting.
 	 */
 	readonly awaitedJobs?: AwaitedJobs
+	/**
+	 * Calls answered with a placeholder because the operator wrote while they
+	 * ran. Absent means no call is ever handed back and the operator's message
+	 * waits for the batch, as it always has.
+	 */
+	readonly detachedCalls?: DetachedCalls
 	readonly checkpointMgr: CheckpointManager
 	readonly planManager: PlanManager
 

package/src/runtime/query/iteration/phases/tool-review.ts

@@ -7,10 +7,12 @@ import type {
 	ToolCallDeclined,
 	ToolCallSummary,
 } from '../../../../types/hitl/index.js'
+import { createRuntimeContextMessage } from '../../../../types/message/index.js'
 import type { ChatCompletionResponse } from '../../../../types/provider/index.js'
 import type { SessionEvent } from '../../../../types/session/index.js'
 import type { ShellDialect } from '../../../../types/tool/index.js'
 import { DECLINED_TOOL_CALL_FEEDBACK } from '../../declined.js'
+import { type BatchDetach, DETACH_AFTER_MS, formatLateResults } from '../../detached-calls.js'
 import type {
 	PreparedToolBatch,
 	ReviewedExecution,
@@ -65,6 +67,60 @@ function hookAskedReason(reason: string | undefined): string {
 		: 'a hook asked that a person approve this call'
 }
 
+/**
+ * Watch for the operator writing while this batch runs.
+ *
+ * The batch is handed back once a message has arrived and the batch has run for
+ * {@link DETACH_AFTER_MS}; a short call finishes first and nothing changes. The
+ * arrival signal is the host's `waitForOperator`, which fires for operator text
+ * only, so a host that supplies none never detaches a call and a notice from a
+ * child or a peer never does.
+ */
+function watchForOperator(
+	ctx: IterationContext,
+	startedAt: number,
+): { readonly detach: BatchDetach; stop(): void } | undefined {
+	const calls = ctx.detachedCalls
+	const wakes = calls?.waitForOperator ? [calls.waitForOperator] : []
+	if (!calls || wakes.length === 0) return undefined
+	const watching = new AbortController()
+	let timer: ReturnType<typeof setTimeout> | undefined
+	const requested = new Promise<void>((resolve) => {
+		const settled = Promise.race(
+			wakes.map((wake) => {
+				try {
+					return wake(watching.signal)
+				} catch {
+					return new Promise<void>(() => {})
+				}
+			}),
+		)
+		settled.then(
+			() => {
+				if (watching.signal.aborted) return
+				const wait = Math.max(0, startedAt + DETACH_AFTER_MS - Date.now())
+				timer = setTimeout(resolve, wait)
+			},
+			// An aborted wait is the batch ending, which is not a message.
+			() => {},
+		)
+	})
+	return {
+		detach: { requested, calls },
+		stop() {
+			watching.abort()
+			if (timer !== undefined) clearTimeout(timer)
+		},
+	}
+}
+
+/** The outcomes of calls that were handed back as still running and have since finished. */
+function takeLateResults(ctx: IterationContext) {
+	const outcomes = ctx.detachedCalls?.take()
+	if (!outcomes || outcomes.length === 0) return undefined
+	return createRuntimeContextMessage(formatLateResults(outcomes), 'job-exit')
+}
+
 export type ToolReviewDecision = 'executed' | 'rejected' | 'stop'
 
 /**
@@ -290,14 +346,21 @@ export async function* runToolReview(
 	): Promise<void> => {
 		await announceRefusals(denials)
 		const startedAt = Date.now()
-		const batch = await ctx.toolExecutor.executeBatch(
-			response,
-			withRepeatRefusals(denials),
-			undefined,
-			preparedBatch,
-			declines,
-			review,
-		)
+		const watch = watchForOperator(ctx, startedAt)
+		let batch: Awaited<ReturnType<typeof ctx.toolExecutor.executeBatch>>
+		try {
+			batch = await ctx.toolExecutor.executeBatch(
+				response,
+				withRepeatRefusals(denials),
+				undefined,
+				preparedBatch,
+				declines,
+				review,
+				watch?.detach,
+			)
+		} finally {
+			watch?.stop()
+		}
 		toolMs += Date.now() - startedAt
 		executed = batch.results
 		await announceBatch(batch.results)
@@ -369,6 +432,8 @@ export async function* runToolReview(
 			},
 		)
 		if (monitorNotice) ctx.recorder.pushMessage(monitorNotice)
+		const lateResults = takeLateResults(ctx)
+		if (lateResults) ctx.recorder.pushMessage(lateResults)
 		const credentialNotice = takeWithheldEnvNotice(ctx.recorder.messages, batch.observations)
 		if (credentialNotice) ctx.recorder.pushMessage(credentialNotice)
 		if (jobNoticeDelivered) ctx.onJobNoticeDelivered?.()

package/src/runtime/query/session-storage.ts

@@ -273,9 +273,14 @@ export function checkpointLogView(log: SessionLog): CheckpointLogView {
 	return {
 		async verifyThrough(scope, throughSeq, throughSha256) {
 			own(scope)
-			const read = await log.readAll({ mode: 'tolerant', throughSeq })
-			const entry = read.entries.at(-1)
-			return entry?.pointer.seq === throughSeq && entry.pointer.sha256 === throughSha256
+			// Stream the walk and keep only the last pointer: the chain is
+			// verified as it is read, and a long session must not be held in
+			// memory just to look at its final entry.
+			let last: { seq: number; sha256: string } | undefined
+			for await (const entry of log.read({ mode: 'tolerant', throughSeq })) {
+				last = entry.pointer
+			}
+			return last?.seq === throughSeq && last.sha256 === throughSha256
 		},
 		async writtenDocSha256(scope, checkpointId) {
 			own(scope)

package/src/runtime/query/steering.ts

@@ -64,17 +64,31 @@ export interface SteeringChannel {
 }
 
 export class SteeringBinding implements SteeringChannel {
-	private queued: string[] = []
+	private queued: { readonly text: string; readonly key?: string }[] = []
 
-	steer(text: string): void {
+	/**
+	 * `key` names what the text is about (a job id), so the text can be
+	 * taken back with {@link withdraw} while it is still undelivered.
+	 */
+	steer(text: string, key?: string): void {
 		const trimmed = text.trim()
 		if (!trimmed) return
-		this.queued.push(trimmed)
+		this.queued.push(key === undefined ? { text: trimmed } : { text: trimmed, key })
+	}
+
+	/**
+	 * Take back every undelivered text queued under `key`. Returns whether any
+	 * was queued. Text already drained has been delivered and is not touched.
+	 */
+	withdraw(key: string): boolean {
+		const before = this.queued.length
+		this.queued = this.queued.filter((entry) => entry.key !== key)
+		return this.queued.length !== before
 	}
 
 	drain(): string | undefined {
 		if (this.queued.length === 0) return undefined
-		const joined = this.queued.join('\n')
+		const joined = this.queued.map((entry) => entry.text).join('\n')
 		this.queued = []
 		return joined
 	}
@@ -84,6 +98,60 @@ export class SteeringBinding implements SteeringChannel {
 	}
 }
 
+/**
+ * The most output a job-exit notice carries inline. A job whose whole output
+ * fits is told with its result; a larger one is read with the job tool, so a
+ * noisy build cannot turn every exit into a large message.
+ */
+export const JOB_NOTICE_INLINE_OUTPUT_MAX_BYTES = 2048
+
+/**
+ * One job's exit as the text the model reads. The output is inlined only when
+ * the whole of it fits {@link JOB_NOTICE_INLINE_OUTPUT_MAX_BYTES} and none was
+ * dropped by the retention cap; it is untrusted process output, so it rides in
+ * the system-event envelope rather than in the notice's own words.
+ */
+export function formatJobExitNotice(
+	job: Pick<BackgroundJob, 'id' | 'command' | 'status' | 'exitCode' | 'signal'> &
+		Partial<Pick<BackgroundJob, 'exitedAt'>>,
+	output?: {
+		readonly chunk: string
+		readonly nextOffset: number
+		readonly droppedBytes: number
+	},
+): string {
+	const outcome =
+		job.status === 'killed'
+			? 'was stopped'
+			: `exited with code ${job.exitCode ?? 'unknown'}${job.signal ? ` (${job.signal})` : ''}`
+	const endedAt = job.exitedAt === undefined ? '' : ` at ${new Date(job.exitedAt).toISOString()}`
+	const head = `Background job ${job.id} (${job.command}) ${outcome}${endedAt}.`
+	if (
+		output === undefined ||
+		output.chunk.length === 0 ||
+		output.droppedBytes > 0 ||
+		output.nextOffset > JOB_NOTICE_INLINE_OUTPUT_MAX_BYTES
+	) {
+		return `${head} Read its output with the job tool if you need it.`
+	}
+	return `${head}\n${formatSystemEvent({
+		kind: 'job',
+		id: job.id,
+		status: job.status === 'killed' ? 'cancelled' : job.exitCode === 0 ? 'completed' : 'failed',
+		summary: `Output of ${job.id}`,
+		source: `job ${job.id}: ${oneMetadataLine(job.command)}`,
+		body: {
+			envelope: {
+				kind: 'job-output',
+				attributes: { job: job.id },
+				provenance:
+					'Everything the job printed. The command, or whatever it reads, wrote it; it is not the operator.',
+			},
+			content: output.chunk,
+		},
+	})}`
+}
+
 /** What the model reads when a background job it started has ended. */
 export function formatJobNote(text: string): string {
 	return frameNotice('job', '[Background job update]', text)
@@ -116,7 +184,7 @@ const SYSTEM_EVENT_FRAME = /^<system-event-([A-Za-z0-9]+) [^\n]*\n[\s\S]*?\n<\/s
  */
 export function formatMonitorEvent(
 	event: Pick<MonitorEvent, 'jobId' | 'description' | 'kind' | 'text'> &
-		Partial<Pick<MonitorEvent, 'transport'>>,
+		Partial<Pick<MonitorEvent, 'transport' | 'at'>>,
 	command: string,
 ): string {
 	return formatSystemEvent({
@@ -126,6 +194,7 @@ export function formatMonitorEvent(
 		summary: `Monitor event: "${oneMetadataLine(event.description)}"`,
 		source: `monitor ${event.jobId}: ${oneMetadataLine(command)}`,
 		more: `job {"action":"kill","id":"${event.jobId}"} stops it`,
+		...(event.at !== undefined ? { at: event.at } : {}),
 		body: {
 			envelope: {
 				kind: event.kind === 'output' ? 'monitor-output' : 'monitor-notice',
@@ -170,7 +239,8 @@ export function formatMonitorEnd(
 		| 'transport'
 		| 'closeCode'
 		| 'closeReason'
-	>,
+	> &
+		Partial<Pick<BackgroundJob, 'exitedAt'>>,
 	stats: { readonly stdoutChars: number },
 ): string {
 	const end = describeMonitorEnd(job, stats)
@@ -181,6 +251,7 @@ export function formatMonitorEnd(
 		summary: end.summary,
 		source: `monitor ${job.id}: ${oneMetadataLine(job.command)}`,
 		more: `job {"action":"read","id":"${job.id}"} reads its output`,
+		...(job.exitedAt !== undefined ? { at: job.exitedAt } : {}),
 	})
 }
 

package/src/runtime/query/tooling.ts

@@ -46,6 +46,7 @@ export interface ToolingBootstrapConfig {
 	backgroundJobOwner?: string
 	/** Where `wait_for_job` records wait-intent; see the executor's own field. */
 	onJobAwaited?: (id: string) => void
+	onJobCollected?: (id: string) => void
 	/** See `ToolExecutorConfig.monitorTimeoutCapMs`. */
 	monitorTimeoutCapMs?: number
 	/** See `ToolExecutorConfig.onMonitorStarted`. */
@@ -110,6 +111,7 @@ export class ToolingBootstrap {
 				...(config.backgroundJobs ? { backgroundJobs: config.backgroundJobs } : {}),
 				...(config.backgroundJobOwner ? { backgroundJobOwner: config.backgroundJobOwner } : {}),
 				...(config.onJobAwaited ? { onJobAwaited: config.onJobAwaited } : {}),
+				...(config.onJobCollected ? { onJobCollected: config.onJobCollected } : {}),
 				...(config.monitorTimeoutCapMs !== undefined
 					? { monitorTimeoutCapMs: config.monitorTimeoutCapMs }
 					: {}),

package/src/runtime/system-events.ts

@@ -102,6 +102,11 @@ export interface SystemEvent {
 	readonly more?: string
 	/** Omit for an event with nothing to show; renders as `(no output)`. */
 	readonly body?: SystemEventBody
+	/**
+	 * When it happened (epoch ms). Rendered as an `at` attribute in ISO form so
+	 * the model can tell a fresh event from one that waited in a queue.
+	 */
+	readonly at?: number
 }
 
 export interface FormatSystemEventOptions {
@@ -209,6 +214,12 @@ function renderBody(body: SystemEventBody | undefined, options: FormatSystemEven
 	)
 }
 
+function atAttribute(at: number | undefined): string {
+	if (at === undefined || !Number.isFinite(at)) return ''
+	const date = new Date(at)
+	return Number.isNaN(date.getTime()) ? '' : ` at="${date.toISOString()}"`
+}
+
 /**
  * Render one asynchronous event as provider-required user-role context.
  *
@@ -248,7 +259,7 @@ export function formatSystemEvent(
 	])
 	const closingTag = `</system-event-${nonce}>`
 	const lines = [
-		`<system-event-${nonce} kind="${escapeAttribute(event.kind)}" id="${escapeAttribute(event.id)}" status="${escapeAttribute(event.status)}">`,
+		`<system-event-${nonce} kind="${escapeAttribute(event.kind)}" id="${escapeAttribute(event.id)}" status="${escapeAttribute(event.status)}"${atAttribute(event.at)}>`,
 		SYSTEM_EVENT_HEADER,
 		nonceClosureStatement(closingTag),
 		`summary: ${summary}`,

package/src/sandbox/denial.ts

@@ -0,0 +1,79 @@
+import type { SandboxEnvironment, SandboxExecAttribution } from '../types/sandbox/index.js'
+
+/**
+ * Reading a sandboxed command's failure: did the command fail, did the
+ * sandbox refuse it, or did the launcher never get as far as running it?
+ *
+ * The model cannot tell these apart from an exit code. A denied write looks
+ * like any other failure, so it retries the same command and burns turns
+ * on something no retry can fix; a launcher that could not set up its
+ * namespaces looks like the command crashing. Both call for a different
+ * answer (ask for the escape, or report a runner fault).
+ *
+ * This is inference from stderr text, not a verdict from the kernel, and
+ * the wording says so. It only ever adds a note; the result is unchanged.
+ */
+
+/** Launcher setup failures print this prefix before any user command runs. */
+const RUNNER_PREFIX: Partial<Record<SandboxEnvironment, RegExp>> = {
+	'linux-bwrap': /^bwrap: (?!execvp )/m,
+	'linux-namespace': /^unshare: /m,
+	'macos-seatbelt': /^sandbox-exec: /m,
+}
+
+const EROFS = /Read-only file system|\bEROFS\b/i
+const PERMISSION = /Permission denied|Operation not permitted|\bEACCES\b|\bEPERM\b/i
+const ABSOLUTE_PATH = /(?:^|[\s'"`:(])(\/[^\s'"`:)]+)/g
+
+/** Only tiers that confine file writes can produce a sandbox denial. */
+const CONFINES_FILES: ReadonlySet<SandboxEnvironment> = new Set(['linux-bwrap', 'macos-seatbelt'])
+
+function within(path: string, root: string): boolean {
+	return path === root || path.startsWith(root.endsWith('/') ? root : `${root}/`)
+}
+
+function pathsIn(line: string): string[] {
+	return [...line.matchAll(ABSOLUTE_PATH)].map((m) => m[1] as string)
+}
+
+export interface AttributionInput {
+	readonly environment: SandboxEnvironment
+	readonly exitCode: number
+	readonly stderr: string
+	readonly timedOut: boolean
+	/** Paths the sandbox lets the command write: root, added directories, scratch. */
+	readonly allowedRoots: readonly string[]
+}
+
+export function attributeSandboxFailure(
+	input: AttributionInput,
+): SandboxExecAttribution | undefined {
+	if (input.exitCode === 0 || input.timedOut || input.stderr === '') return undefined
+
+	const runner = RUNNER_PREFIX[input.environment]
+	if (runner?.test(input.stderr)) {
+		const line = input.stderr.split('\n').find((l) => runner.test(l)) ?? ''
+		return {
+			kind: 'runner-failure',
+			message: `The sandbox launcher failed before the command could run (${line.trim()}). This is a runner fault, not a failure of the command; retrying the same command will not help.`,
+		}
+	}
+
+	if (!CONFINES_FILES.has(input.environment)) return undefined
+
+	for (const line of input.stderr.split('\n')) {
+		if (EROFS.test(line)) return denial()
+		if (!PERMISSION.test(line)) continue
+		const paths = pathsIn(line)
+		if (paths.some((p) => !input.allowedRoots.some((root) => within(p, root)))) return denial()
+	}
+	return undefined
+}
+
+function denial(): SandboxExecAttribution {
+	return {
+		kind: 'denial',
+		message:
+			'This looks like a sandbox denial: the command touched a path the sandbox does not allow it to write. This is inferred from the error text, not proven. Retrying the same command will fail the same way; if the action is needed, ask to run it outside the sandbox instead.',
+	}
+}

package/src/sandbox/file-walk-program.ts

@@ -1,5 +1,7 @@
+import { IGNORE_SOURCE } from './ignore-source.js'
+
 /** Stable guest code: host bundlers must never rewrite a function we serialize. */
-export const FILE_WALK_PROGRAM = String.raw`
+export const FILE_WALK_PROGRAM = `${IGNORE_SOURCE}${String.raw`
 const fs = require('node:fs/promises');
 const path = require('node:path');
 const plan = JSON.parse(process.argv[1]);
@@ -9,10 +11,17 @@ const write = async value => {
     await new Promise(resolve => process.stdout.once('drain', resolve));
   }
 };
+let stopped;
+let visitedTotal = 0;
+let ignoredDirs = 0;
 const visit = count => {
-  if (count > plan.maxVisitedEntries) {
+  visitedTotal = count;
+  if (count <= plan.maxVisitedEntries) return true;
+  if (plan.failOnLimit) {
     throw Object.assign(new Error('File search stopped after examining ' + plan.maxVisitedEntries + ' entries; narrow its root or pattern.'), {code:'ERR_FILE_WALK_LIMIT'});
   }
+  stopped = 'entry-limit';
+  return false;
 };
 const patterns = plan.patterns.map(set => set.map(part =>
   typeof part === 'object' && part !== null ? new RegExp(part.source, part.flags + 's') : part));
@@ -41,9 +50,13 @@ async function run() {
   let emitted = 0;
   const matchers = plan.expressions.map(({source, flags}) => new RegExp(source, flags + 's'));
   const maxDepth = plan.maxDepth === null ? Infinity : plan.maxDepth;
-  const open = async (absolute, relative, depth) => {
-    try { stack.push({dir: await fs.opendir(absolute), relative, depth}); }
-    catch (error) { if (!missing(error)) throw error; }
+  const ignore = plan.respectIgnore ? ignCreate({fs, path, extraFiles: []}) : null;
+  const open = async (absolute, relative, depth, layered) => {
+    try {
+      const dir = await fs.opendir(absolute);
+      if (layered && ignore) await ignore.enter(absolute);
+      stack.push({dir, relative, depth, layered});
+    } catch (error) { if (!missing(error)) throw error; }
   };
   try {
     if (plan.patterns.length === 0) return;
@@ -53,36 +66,42 @@ async function run() {
     if (canonicalRoot !== path.resolve(plan.root)) throw new Error('File walk root follows a symbolic link; use its authorized real directory');
     const rootInfo = await fs.lstat(plan.root);
     if (rootInfo.isFile()) {
-      visit(++visited);
+      if (!visit(++visited)) return;
       if (matchers.some(matcher => matcher.test(path.basename(plan.root)))) {
         await write({type:'entry', path:plan.root, size:rootInfo.size});
       }
       return;
     }
+    if (ignore) { await ignore.init(plan.root); await ignore.enter(plan.root); }
     let start = plan.root;
     for (const part of plan.prefix) {
       start = path.join(start, part);
       let info;
       try { info = await fs.lstat(start); }
       catch (error) { if (missing(error)) return; throw error; }
-      visit(++visited);
+      if (!visit(++visited)) return;
       if (!info.isDirectory()) return;
+      if (ignore) await ignore.enter(start);
     }
     if (plan.prefix.length >= maxDepth) return;
-    await open(start, plan.prefix.join('/'), plan.prefix.length);
+    await open(start, plan.prefix.join('/'), plan.prefix.length, false);
     while (stack.length) {
       const frame = stack[stack.length - 1];
       const entry = await frame.dir.read();
-      if (!entry) { stack.pop(); await frame.dir.close(); continue; }
-      visit(++visited);
+      if (!entry) { stack.pop(); if (frame.layered && ignore) ignore.leave(); await frame.dir.close(); continue; }
+      if (!visit(++visited)) return;
+      if (IGN_VCS.includes(entry.name)) continue;
       const relative = frame.relative ? frame.relative + '/' + entry.name : entry.name;
       const absolute = path.join(plan.root, relative);
       const depth = frame.depth + 1;
       if (entry.isDirectory()) {
-        if (depth < maxDepth && canDescend(relative)) await open(absolute, relative, depth);
+        if (depth >= maxDepth || !canDescend(relative)) continue;
+        if (ignore && ignore.isIgnored(absolute, true)) { ignoredDirs++; continue; }
+        await open(absolute, relative, depth, true);
         continue;
       }
       if (!entry.isFile() || !matchers.some(matcher => matcher.test(relative))) continue;
+      if (ignore && ignore.isIgnored(absolute, false)) continue;
       let info;
       try { info = await fs.lstat(absolute); }
       catch (error) { if (missing(error)) continue; throw error; }
@@ -95,7 +114,7 @@ async function run() {
   }
 }
 run().then(
-  () => write({type:'done'}),
+  () => write({type:'done', visited:visitedTotal, ignoredDirs, stopped}),
   async error => { await write({type:'error', message:error.message, code:error.code}); process.exitCode = 1; },
 );
-`
+`}`