@namzu/sdk 59.0.0 → 60.1.0

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; },
 );
-`
+`}`

package/src/sandbox/file-walk.ts

@@ -1,4 +1,4 @@
-import { isAbsolute, posix } from 'node:path'
+import { isAbsolute, join, posix } from 'node:path'
 import braceExpansion from 'brace-expansion'
 import { GLOBSTAR, Minimatch } from 'minimatch'
 import type {
@@ -6,9 +6,14 @@ import type {
 	SandboxExecResult,
 	SandboxFileEntry,
 	SandboxWalkFilesOptions,
+	SandboxWalkSummary,
 } from '../types/sandbox/index.js'
 import { subscribeToAbort } from '../utils/abort.js'
 import { FILE_WALK_PROGRAM } from './file-walk-program.js'
+import { VCS_NAMES, createIgnoreStack } from './ignore-matcher.js'
+
+/** Entries a walk examines before it stops with what it has: a safety valve, not a budget. */
+export const DEFAULT_MAX_VISITED_ENTRIES = 500_000
 
 interface WalkPlan {
 	root: string
@@ -18,6 +23,8 @@ interface WalkPlan {
 	maxEntries: number
 	maxVisitedEntries: number
 	includeHidden: boolean
+	respectIgnore: boolean
+	failOnLimit: boolean
 	patterns: (string | { source: string; flags: string } | null)[][]
 }
 
@@ -103,8 +110,13 @@ function planWalk(root: string, options: SandboxWalkFilesOptions): WalkPlan {
 		expressions,
 		maxDepth: Number.isFinite(maxDepth) ? maxDepth : null,
 		maxEntries: positiveInteger(options.maxEntries, 'maxEntries'),
-		maxVisitedEntries: positiveInteger(options.maxVisitedEntries ?? 20_000, 'maxVisitedEntries'),
+		maxVisitedEntries: positiveInteger(
+			options.maxVisitedEntries ?? DEFAULT_MAX_VISITED_ENTRIES,
+			'maxVisitedEntries',
+		),
 		includeHidden: options.includeHidden ?? false,
+		respectIgnore: options.respectIgnore ?? true,
+		failOnLimit: options.failOnLimit ?? false,
 		patterns: sets.map((set) =>
 			set.map((segment) =>
 				segment === GLOBSTAR
@@ -151,13 +163,25 @@ function directoryMatcher(plan: WalkPlan): (relative: string) => boolean {
 async function* executeWalk(
 	plan: WalkPlan,
 	signal?: AbortSignal,
+	onSummary?: (summary: SandboxWalkSummary) => void,
 ): AsyncGenerator<SandboxFileEntry> {
 	const fs = await import('node:fs/promises')
 	const path = await import('node:path')
 	const { EventEmitter } = await import('node:events')
-	const open: { dir: import('node:fs').Dir; relative: string; depth: number }[] = []
+	const open: {
+		dir: import('node:fs').Dir
+		relative: string
+		depth: number
+		/** Whether leaving this directory also drops its ignore layer. */
+		layered: boolean
+	}[] = []
 	let visited = 0
 	let emitted = 0
+	let ignoredDirectories = 0
+	let stopped: SandboxWalkSummary['stopped']
+	const ignore = plan.respectIgnore
+		? createIgnoreStack({ fs, path, extraFiles: globalIgnoreFiles() })
+		: undefined
 	const matchers = plan.expressions.map(({ source, flags }) => new RegExp(source, `${flags}s`))
 	const canDescend = directoryMatcher(plan)
 	const maxDepth = plan.maxDepth ?? Number.POSITIVE_INFINITY
@@ -204,9 +228,11 @@ async function* executeWalk(
 			dispose?.()
 		}
 	}
+	/** False once the safety valve trips; the walk then ends with what it has. */
 	const noteVisit = () => {
 		visited += 1
-		if (visited > plan.maxVisitedEntries) {
+		if (visited <= 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.`,
@@ -214,6 +240,8 @@ async function* executeWalk(
 				{ code: 'ERR_FILE_WALK_LIMIT' },
 			)
 		}
+		stopped = 'entry-limit'
+		return false
 	}
 	try {
 		check()
@@ -231,11 +259,14 @@ async function* executeWalk(
 		const rootInfo = await wait(fs.lstat(plan.root))
 		check()
 		if (rootInfo.isFile()) {
-			noteVisit()
+			if (!noteVisit()) return
 			if (matchers.some((matcher) => matcher.test(path.basename(plan.root))))
 				yield { path: plan.root, size: rootInfo.size }
 			return
 		}
+		// An explicit root is never itself ignored: only what is below it is tested.
+		await ignore?.init(plan.root)
+		await ignore?.enter(plan.root)
 		let start = plan.root
 		// Never follow a static-prefix symlink to speed up a pattern: traversal
 		// and its optimized starting point must have the same link policy.
@@ -249,22 +280,29 @@ async function* executeWalk(
 				if (missing(error)) return
 				throw error
 			}
-			noteVisit()
+			if (!noteVisit()) return
 			if (!info.isDirectory()) return
+			await ignore?.enter(start)
 		}
 		if (plan.prefix.length >= maxDepth) return
-		const openDirectory = async (absolute: string, relative: string, depth: number) => {
+		const openDirectory = async (
+			absolute: string,
+			relative: string,
+			depth: number,
+			layered: boolean,
+		) => {
 			check()
 			try {
 				const dir = await wait(fs.opendir(absolute), (late) => {
 					void close(late).catch(() => {})
 				})
-				open.push({ dir, relative, depth })
+				if (layered) await ignore?.enter(absolute)
+				open.push({ dir, relative, depth, layered })
 			} catch (error) {
 				if (!missing(error)) throw error
 			}
 		}
-		await openDirectory(start, plan.prefix.join('/'), plan.prefix.length)
+		await openDirectory(start, plan.prefix.join('/'), plan.prefix.length, false)
 		while (open.length > 0) {
 			check()
 			const frame = open[open.length - 1] as (typeof open)[number]
@@ -272,18 +310,26 @@ async function* executeWalk(
 			check()
 			if (!entry) {
 				open.pop()
+				if (frame.layered) ignore?.leave()
 				await close(frame.dir)
 				continue
 			}
-			noteVisit()
+			if (!noteVisit()) return
+			if (VCS_NAMES.has(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 openDirectory(absolute, relative, depth)
+				if (depth >= maxDepth || !canDescend(relative)) continue
+				if (ignore?.isIgnored(absolute, true)) {
+					ignoredDirectories += 1
+					continue
+				}
+				await openDirectory(absolute, relative, depth, true)
 				continue
 			}
 			if (!entry.isFile() || !matchers.some((matcher) => matcher.test(relative))) continue
+			if (ignore?.isIgnored(absolute, false)) continue
 			let info: import('node:fs').Stats
 			try {
 				info = await wait(fs.lstat(absolute))
@@ -303,16 +349,24 @@ async function* executeWalk(
 				void close(dir).catch(() => {})
 			} else await close(dir)
 		}
+		onSummary?.({ visited, ignoredDirectories, ...(stopped ? { stopped } : {}) })
 	}
 }
 
+/** Global exclude files, lowest precedence. Only the host has them. */
+function globalIgnoreFiles(): string[] {
+	const home = process.env.HOME ?? process.env.USERPROFILE
+	const base = process.env.XDG_CONFIG_HOME || (home ? join(home, '.config') : undefined)
+	return base ? [join(base, 'git', 'ignore')] : []
+}
+
 /** Internal host path; the caller first resolves its authorized filesystem root. */
 export async function* walkFilesLocally(
 	rootPath: string,
 	options: SandboxWalkFilesOptions,
 ): AsyncGenerator<SandboxFileEntry> {
 	options.signal?.throwIfAborted()
-	yield* executeWalk(planWalk(rootPath, options), options.signal)
+	yield* executeWalk(planWalk(rootPath, options), options.signal, options.onSummary)
 }
 
 /** The existing sandbox execution seam; no separate worker protocol is needed. */
@@ -346,6 +400,7 @@ export async function* walkFilesViaExec(
 	let terminal = false
 	let received = 0
 	let failure: unknown
+	const outcome: { summary?: SandboxWalkSummary } = {}
 	const reject = (error: unknown) => {
 		failure ??= error instanceof Error ? error : new Error(String(error))
 		controller.abort(error)
@@ -358,6 +413,13 @@ export async function* walkFilesViaExec(
 		const record = value as Record<string, unknown>
 		if (record.type === 'done') {
 			terminal = true
+			const count = (value: unknown) =>
+				typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : 0
+			outcome.summary = {
+				visited: count(record.visited),
+				ignoredDirectories: count(record.ignoredDirs),
+				...(record.stopped === 'entry-limit' ? { stopped: 'entry-limit' as const } : {}),
+			}
 			return
 		}
 		if (record.type === 'error' && typeof record.message === 'string') {
@@ -462,6 +524,7 @@ export async function* walkFilesViaExec(
 		}
 	} finally {
 		dispose?.()
+		if (outcome.summary) options.onSummary?.(outcome.summary)
 		if (!settled) controller.abort(new Error('File walk consumer stopped'))
 		await pending
 		// A rejected cancellation can mean remote work is still alive. Preserve

package/src/sandbox/ignore-matcher.ts

@@ -0,0 +1,46 @@
+import { IGNORE_SOURCE } from './ignore-source.js'
+
+/** One compiled ignore rule. */
+export interface IgnoreRule {
+	readonly negate: boolean
+	readonly dirOnly: boolean
+	readonly re: RegExp
+}
+
+/** Layered ignore rules for one depth-first walk; see `ignore-source.ts`. */
+export interface IgnoreStack {
+	/** Find the enclosing repository and load the layers above the walk root. */
+	init(root: string): Promise<void>
+	/** Load a directory's rule files; call before reading it. */
+	enter(directory: string): Promise<void>
+	/** Drop the layer of the directory most recently entered. */
+	leave(): void
+	isIgnored(absolute: string, isDirectory: boolean): boolean
+}
+
+export interface IgnoreDeps {
+	readonly fs: unknown
+	readonly path: unknown
+	/** Global exclude files, lowest precedence. The guest has none. */
+	readonly extraFiles?: readonly string[]
+}
+
+interface IgnoreModule {
+	parse(text: string): IgnoreRule[]
+	decide(rules: readonly IgnoreRule[], relative: string, isDirectory: boolean): 0 | 1 | 2
+	create(deps: IgnoreDeps): IgnoreStack
+	vcs: readonly string[]
+}
+
+// The same text is embedded in the guest program, so both walks share it.
+const module_ = new Function(
+	`${IGNORE_SOURCE}\nreturn { parse: ignParse, decide: ignDecide, create: ignCreate, vcs: IGN_VCS }`,
+)() as IgnoreModule
+
+/** Parse the text of one ignore file into rules; a line it cannot read is dropped. */
+export const parseIgnoreRules = module_.parse
+/** 0: no rule matches, 1: ignored, 2: re-included. The last matching rule wins. */
+export const decideIgnore = module_.decide
+export const createIgnoreStack = module_.create
+/** Version-control directories that no walk ever descends into. */
+export const VCS_NAMES: ReadonlySet<string> = new Set(module_.vcs)