@namzu/sdk 59.0.0 → 60.0.0

package/src/tools/builtins/glob.ts

@@ -1,13 +1,23 @@
 import { isAbsolute, join, relative, sep } from 'node:path'
 import { z } from 'zod'
 import { walkFilesLocally } from '../../sandbox/file-walk.js'
-import type { SandboxWalkFilesOptions } from '../../types/sandbox/index.js'
+import type { SandboxWalkFilesOptions, SandboxWalkSummary } from '../../types/sandbox/index.js'
 import { defineTool } from '../defineTool.js'
 import { resolveWithin, resolveWithinAny, resolveWithinAnyReal, toolRoots } from '../paths.js'
 import { relativePosix, resolveWithinPosix } from '../posix-path.js'
+import {
+	SEARCH_BUDGET_MS,
+	hostDisplayPath,
+	ignoredHint,
+	isEntryLimit,
+	isReadDenied,
+	openSearchBudget,
+	plural,
+	quoteControlPath,
+	stoppedNotice,
+} from './search-support.js'
 
 const MAX_GLOB_RESULTS = 500
-const MAX_VISITED_ENTRIES = 20_000
 
 const inputSchema = z.object({
 	pattern: z
@@ -27,7 +37,13 @@ const inputSchema = z.object({
 		.boolean()
 		.optional()
 		.describe(
-			'Include hidden files and directories in wildcard matches. Default: false. Explicit dotfile patterns still match.',
+			'Include hidden files and directories in wildcard matches. Default: true. Version-control directories are always skipped.',
+		),
+	include_ignored: z
+		.boolean()
+		.optional()
+		.describe(
+			'Also return files that .gitignore and .ignore rules exclude, such as build output and dependencies. Default: false.',
 		),
 })
 
@@ -49,16 +65,10 @@ function relativePattern(pattern: string, root: string, sandboxed: boolean): str
 	return result || '.'
 }
 
-/** Keep unusual filenames unambiguous without changing the returned path data. */
-function displayPath(path: string): string {
-	// biome-ignore lint/suspicious/noControlCharactersInRegex: quote filenames containing control bytes instead of creating fake result lines.
-	return /[\x00-\x1f\x7f]/.test(path) ? JSON.stringify(path) : path
-}
-
 export const GlobTool = defineTool({
 	name: 'glob',
 	description:
-		'Finds regular files by glob pattern in a bounded search. "*" searches one directory; use "**" explicitly for recursive discovery. Returns at most 500 paths and identifies incomplete searches. Does not follow symlinks.',
+		'Finds regular files by glob pattern in a bounded search. "*" searches one directory; use "**" explicitly for recursive discovery. Skips files that .gitignore and .ignore rules exclude unless include_ignored is set, and files the read rules of the session deny. Returns at most 500 paths and says when a result is limited or a search stopped early. Does not follow symlinks.',
 	inputSchema,
 	category: 'filesystem',
 	// Declared so a path outside the turn's roots can be reviewed before the
@@ -102,57 +112,94 @@ export const GlobTool = defineTool({
 					'This sandbox does not support bounded file discovery (Sandbox.walkFiles). Update its adapter or use an available directory-listing command inside the sandbox.',
 			}
 		}
+		const budget = openSearchBudget(context.abortSignal)
+		let summary: SandboxWalkSummary | undefined
 		const options: SandboxWalkFilesOptions = {
 			pattern,
-			signal: context.abortSignal,
+			signal: budget.signal,
 			maxEntries: MAX_GLOB_RESULTS + 1,
-			maxVisitedEntries: MAX_VISITED_ENTRIES,
-			includeHidden: input.include_hidden ?? false,
+			includeHidden: input.include_hidden ?? true,
+			respectIgnore: input.include_ignored !== true,
+			onSummary: (value) => {
+				summary = value
+			},
 		}
 		const entries = walkSandbox ? walkSandbox(root, options) : walkFilesLocally(root, options)
 		const files: string[] = []
-		let truncated = false
+		let capped = false
+		let timedOut = false
+		let legacyEntryLimit = false
 		let failure: string | undefined
 		try {
 			for await (const entry of entries) {
-				context.abortSignal?.throwIfAborted()
+				budget.signal.throwIfAborted()
 				const absolute = sandbox
 					? resolveWithinPosix(root, entry.path)
 					: resolveWithin(root, entry.path)
+				if (isReadDenied(context, absolute, sandbox?.rootDir)) continue
 				if (files.length === MAX_GLOB_RESULTS) {
-					truncated = true
+					capped = true
 					break
 				}
 				// Readers resolve relative input against the original working path,
 				// which may be a symlink. Project back through the selected alias
 				// before relativizing so added directories remain reachable.
-				const file = sandbox
-					? relativePosix(sandbox.rootDir, absolute)
-					: relative(context.workingDirectory, join(lexicalRoot, relative(root, absolute)))
-				files.push(`./${sandbox ? file : file.split(sep).join('/')}`)
+				files.push(
+					sandbox
+						? relativePosix(sandbox.rootDir, absolute)
+						: hostDisplayPath(
+								context.workingDirectory,
+								join(lexicalRoot, relative(root, absolute)),
+							),
+				)
 			}
 		} catch (error) {
 			if (context.abortSignal?.aborted) throw error
-			truncated = true
-			failure = error instanceof Error ? error.message : String(error)
+			if (budget.expired()) timedOut = true
+			else if (isEntryLimit(error)) legacyEntryLimit = true
+			else failure = error instanceof Error ? error.message : String(error)
+		} finally {
+			budget.close()
 		}
-		const notice = failure
-			? `[Search incomplete: ${failure}]`
-			: truncated
-				? `[Showing the first ${MAX_GLOB_RESULTS} matching files. Narrow the directory or pattern for the remaining results.]`
-				: undefined
+		const endState = summary as SandboxWalkSummary | undefined
+		const entryLimit = endState?.stopped === 'entry-limit' || legacyEntryLimit
+		const incomplete = timedOut || entryLimit
+		if (timedOut && files.length === 0) {
+			return {
+				success: false,
+				output: '',
+				error: `Search timed out after ${SEARCH_BUDGET_MS / 1000} seconds with no matches. Try a more specific path or pattern.`,
+			}
+		}
+		const notices = [
+			...(capped
+				? [
+						`(Showing the first ${plural(MAX_GLOB_RESULTS, 'matching file')}; more match. Narrow the pattern or path to see the rest.)`,
+					]
+				: []),
+			...(incomplete ? [stoppedNotice(timedOut ? 'time' : 'entries', endState?.visited)] : []),
+			...(failure ? [`[Search incomplete: ${failure}]`] : []),
+		]
+		const ignored = endState?.ignoredDirectories ?? 0
+		const hint = ignored > 0 ? `\n${ignoredHint(ignored)}` : ''
+		const empty = `No files found matching pattern "${input.pattern}" in ${root}${hint}`
 		return {
 			success: failure === undefined,
-			output:
-				[...files.map(displayPath), ...(notice ? [notice] : [])].join('\n') ||
-				`No files found matching pattern "${input.pattern}" in ${root}`,
-			data: { count: files.length, files, truncated, ...(sandbox ? { sandboxed: true } : {}) },
+			output: [...files.map(quoteControlPath), ...notices].join('\n') || empty,
+			data: {
+				count: files.length,
+				files,
+				truncated: capped || incomplete,
+				...(sandbox ? { sandboxed: true } : {}),
+			},
 			facts: {
 				kind: 'list',
 				pattern: input.pattern,
 				...(input.path !== undefined ? { path: input.path } : {}),
 				count: files.length,
-				truncated,
+				truncated: capped || incomplete,
+				...(capped ? { limited: true } : {}),
+				...(incomplete ? { incomplete: true } : {}),
 			},
 			...(failure ? { error: failure } : {}),
 		}

package/src/tools/builtins/grep.ts

@@ -2,7 +2,7 @@ import { stat } from 'node:fs/promises'
 import { isAbsolute, join, relative, sep } from 'node:path'
 import { z } from 'zod'
 import { walkFilesLocally } from '../../sandbox/file-walk.js'
-import type { SandboxWalkFilesOptions } from '../../types/sandbox/index.js'
+import type { SandboxWalkFilesOptions, SandboxWalkSummary } from '../../types/sandbox/index.js'
 import type { ToolContext } from '../../types/tool/index.js'
 import { subscribeToAbort } from '../../utils/abort.js'
 import { defineTool } from '../defineTool.js'
@@ -15,6 +15,17 @@ import {
 } from '../paths.js'
 import { relativePosix, resolveWithinPosix } from '../posix-path.js'
 import { readBoundedChunks, readBoundedFile } from './bounded-file-read.js'
+import {
+	MAX_FILES_SEARCHED,
+	SEARCH_BUDGET_MS,
+	hostDisplayPath,
+	ignoredHint,
+	isEntryLimit,
+	isReadDenied,
+	openSearchBudget,
+	plural,
+	stoppedNotice,
+} from './search-support.js'
 
 /** A remote read has no signal parameter; stop consuming it when the turn ends. */
 async function readWithSignal(read: () => Promise<Buffer>, signal?: AbortSignal): Promise<Buffer> {
@@ -166,6 +177,18 @@ const inputSchema = z.object({
 		.describe(
 			'Only search files of this kind, e.g. "js", "ts", "py", "rust", "go", "java", "md". Narrows what include selects.',
 		),
+	include_hidden: z
+		.boolean()
+		.optional()
+		.describe(
+			'Search hidden files and directories (names starting with a dot). Default: true. Version-control directories are always skipped.',
+		),
+	include_ignored: z
+		.boolean()
+		.optional()
+		.describe(
+			'Also search files that .gitignore and .ignore rules exclude, such as build output and dependencies. Default: false.',
+		),
 	max_results: z.coerce
 		.number()
 		.int()
@@ -176,7 +199,6 @@ const inputSchema = z.object({
 
 const MAX_FILE_SIZE = 5 * 1024 * 1024 // 5 MB — skip binaries/large files
 const BINARY_CHECK_BYTES = 512
-const MAX_VISITED_ENTRIES = 20_000
 
 function isBinaryContent(buffer: Buffer): boolean {
 	const check = buffer.subarray(0, BINARY_CHECK_BYTES)
@@ -189,7 +211,7 @@ function isBinaryContent(buffer: Buffer): boolean {
 export const GrepTool = defineTool({
 	name: 'grep',
 	description:
-		'Searches file contents using a regular expression. By default returns the paths of matching files, newest first; output_mode "content" returns matching lines with file paths, line numbers and optional context lines, and "count" returns the number of matching lines per file. Set multiline for a pattern that spans lines and type (js, py, rust, ...) to search one kind of file. In content mode, before_context and after_context override symmetric context_lines; only_matching returns matched substrings without context. Results are paged: head_limit (default 250, 0 for none) and offset. A line over 500 characters is replaced by a notice. Searches with a bounded traversal and identifies incomplete searches. Skips binary files, files over 5 MB, and symlinks. Choose the narrowest relevant directory.',
+		'Searches file contents using a regular expression. By default returns the paths of matching files, newest first; output_mode "content" returns matching lines with file paths, line numbers and optional context lines, and "count" returns the number of matching lines per file. Set multiline for a pattern that spans lines and type (js, py, rust, ...) to search one kind of file. In content mode, before_context and after_context override symmetric context_lines; only_matching returns matched substrings without context. Results are paged: head_limit (default 250, 0 for none) and offset. A line over 500 characters is replaced by a notice. Searches hidden files unless include_hidden is false. Skips files that .gitignore and .ignore rules exclude unless include_ignored is set, and files the read rules of the session deny. Says when a result is limited or a search stopped early. Skips binary files, files over 5 MB, and symlinks. Choose the narrowest relevant directory.',
 	inputSchema,
 	category: 'analysis',
 	// Declared so a path outside the turn's roots can be reviewed before the
@@ -256,14 +278,18 @@ export const GrepTool = defineTool({
 					'This sandbox does not support bounded file discovery (Sandbox.walkFiles). Update its adapter before searching file contents.',
 			}
 		}
+		const budget = openSearchBudget(context.abortSignal)
+		const signal = budget.signal
+		let walkEnd: SandboxWalkSummary | undefined
 		const options: SandboxWalkFilesOptions = {
 			pattern: filePattern,
-			signal: context.abortSignal,
-			maxEntries: MAX_VISITED_ENTRIES + 1,
-			maxVisitedEntries: MAX_VISITED_ENTRIES,
-			// Preserve existing source behavior: sandbox grep included dotfiles;
-			// node's host glob excluded wildcard dotfiles.
-			includeHidden: sandbox !== undefined,
+			signal,
+			maxEntries: MAX_FILES_SEARCHED + 1,
+			includeHidden: input.include_hidden ?? true,
+			respectIgnore: input.include_ignored !== true,
+			onSummary: (value) => {
+				walkEnd = value
+			},
 		}
 		const entries = walkSandbox ? walkSandbox(root, options) : walkFilesLocally(root, options)
 
@@ -282,24 +308,33 @@ export const GrepTool = defineTool({
 		let filesSearched = 0
 		let filesMatched = 0
 
-		let truncated = false
 		let pageHasMore = false
 		let failure: string | undefined
 		let unreadableFiles = 0
+		let timedOut = false
+		let legacyEntryLimit = false
+		let fileLimit = false
+		// A file list is ordered newest first, so the walk cannot stop at the
+		// first page: it reads a generous multiple of it, then sorts and pages.
+		// The count includes the offset, so every page the model is told to ask
+		// for can be served.
+		const filesToCollect =
+			headLimit > 0 ? offset + Math.max(headLimit * 4, 1000) : Number.POSITIVE_INFINITY
+		let enough = false
 		try {
 			for await (const entry of entries) {
-				context.abortSignal?.throwIfAborted()
+				signal?.throwIfAborted()
 				const filePath = sandbox
 					? resolveWithinPosix(root, entry.path)
 					: resolveWithin(root, entry.path)
-				if (filesSearched >= MAX_VISITED_ENTRIES) {
-					throw new Error(
-						`File search stopped after examining ${MAX_VISITED_ENTRIES} files; narrow its root or include pattern.`,
-					)
+				if (filesSearched >= MAX_FILES_SEARCHED) {
+					fileLimit = true
+					break
 				}
 				filesSearched++
 				if (fileType && !matchesType(entry.path, fileType)) continue
 				if (entry.size > MAX_FILE_SIZE) continue
+				if (isReadDenied(context, filePath, sandbox?.rootDir)) continue
 
 				let content: string
 				let contained: string | undefined
@@ -309,21 +344,21 @@ export const GrepTool = defineTool({
 							sandbox
 								? readBoundedChunks(
 										(offset, length) =>
-											sandbox.readFile(filePath, { offset, length, signal: context.abortSignal }),
+											sandbox.readFile(filePath, { offset, length, signal: signal }),
 										MAX_FILE_SIZE,
-										context.abortSignal,
+										signal,
 									)
 								: resolveWithinReal(root, filePath).then((path) => {
 										contained = path
-										return readBoundedFile(path, MAX_FILE_SIZE, context.abortSignal)
+										return readBoundedFile(path, MAX_FILE_SIZE, signal)
 									}),
-						context.abortSignal,
+						signal,
 					)
-					context.abortSignal?.throwIfAborted()
+					signal?.throwIfAborted()
 					if (buffer.length > MAX_FILE_SIZE || isBinaryContent(buffer)) continue
 					content = buffer.toString('utf-8')
 				} catch (error) {
-					if (context.abortSignal?.aborted) throw error
+					if (signal?.aborted) throw error
 					unreadableFiles++
 					continue
 				}
@@ -331,14 +366,12 @@ export const GrepTool = defineTool({
 				const lines = content.split('\n')
 				let fileMatches = 0
 				const relPath = sandbox
-					? `./${relativePosix(sandbox.rootDir, filePath)}`
-					: `./${relative(context.workingDirectory, join(lexicalRoot, relative(root, filePath)))
-							.split(sep)
-							.join('/')}`
+					? relativePosix(sandbox.rootDir, filePath)
+					: hostDisplayPath(context.workingDirectory, join(lexicalRoot, relative(root, filePath)))
 
 				if (mode === 'content' && input.only_matching) {
 					for (const fragment of matchingFragments(content, regex, multiline)) {
-						context.abortSignal?.throwIfAborted()
+						signal?.throwIfAborted()
 						if (fileMatches++ === 0) filesMatched++
 						totalMatches++
 						results.push(`${relPath}:${fragment.line}:${clipLine(fragment.text, 'matching')}`)
@@ -356,7 +389,7 @@ export const GrepTool = defineTool({
 				// Count mode reports matching lines, so a line covered twice counts once.
 				const countedLines = new Set<number>()
 				for (const [first, last] of hits) {
-					context.abortSignal?.throwIfAborted()
+					signal?.throwIfAborted()
 					if (fileMatches === 0) filesMatched++
 					fileMatches++
 					totalMatches++
@@ -397,16 +430,32 @@ export const GrepTool = defineTool({
 					})
 				}
 				if (pageHasMore) break
+				if (mode === 'files_with_matches' && matchedFiles.length >= filesToCollect) {
+					enough = true
+					break
+				}
 			}
 		} catch (error) {
-			truncated = true
-			failure = (error instanceof Error ? error.message : String(error)) || 'File search failed.'
+			// A caller's cancellation is reported with the matches already found:
+			// grep-search-scope.test.ts pins that, so a cancelled search keeps what it read.
+			if (budget.expired()) timedOut = true
+			else if (isEntryLimit(error)) legacyEntryLimit = true
+			else
+				failure = (error instanceof Error ? error.message : String(error)) || 'File search failed.'
+		} finally {
+			budget.close()
 		}
-		if (unreadableFiles > 0) {
-			truncated = true
-			failure ??= `${unreadableFiles} file(s) could not be read.`
+		const endState = walkEnd as SandboxWalkSummary | undefined
+		const entryLimit = endState?.stopped === 'entry-limit' || legacyEntryLimit
+		const stoppedEarly = timedOut || entryLimit || fileLimit
+		if (timedOut && totalMatches === 0 && failure === undefined) {
+			return {
+				success: false,
+				output: '',
+				error: `Search timed out after ${SEARCH_BUDGET_MS / 1000} seconds with no matches. Try a more specific path or pattern.`,
+			}
 		}
-		if (pageHasMore) truncated = true
+		const truncated = stoppedEarly || pageHasMore || enough || failure !== undefined
 
 		// Entries as the model will page through them.
 		let entriesOut: string[]
@@ -422,7 +471,7 @@ export const GrepTool = defineTool({
 			headLimit === 0 ? entriesOut.slice(offset) : entriesOut.slice(offset, offset + headLimit)
 		// Reported only when it did something, like a `| head`: a limit that cut
 		// nothing off is not news.
-		const moreRemain = headLimit > 0 && (pageHasMore || total - offset > headLimit)
+		const moreRemain = headLimit > 0 && (pageHasMore || enough || total - offset > headLimit)
 		const paging = [
 			...(moreRemain ? [`limit: ${headLimit}`] : []),
 			...(offset > 0 ? [`offset: ${offset}`] : []),
@@ -435,9 +484,12 @@ export const GrepTool = defineTool({
 			summary =
 				offset > 0 && total > 0
 					? 'No entries at this offset.'
-					: truncated
+					: stoppedEarly || failure !== undefined || unreadableFiles > 0
 						? `No matches found in the files searched for pattern "${input.pattern}"`
 						: `No matches found for pattern "${input.pattern}"`
+			if ((endState?.ignoredDirectories ?? 0) > 0 && offset === 0) {
+				summary = `${summary}\n${ignoredHint(endState?.ignoredDirectories ?? 0)}`
+			}
 		} else if (mode === 'files_with_matches') {
 			body = `Found ${page.length} ${page.length === 1 ? 'file' : 'files'}${paging ? ` (${paging})` : ''}\n${page.join('\n')}`
 		} else if (mode === 'count') {
@@ -447,21 +499,31 @@ export const GrepTool = defineTool({
 			body = page.join('\n')
 			summary = `Found ${totalMatches} match(es) in ${filesMatched} file(s) (${filesSearched} files searched)${offset > 0 ? ` from offset ${offset}` : ''}`
 		}
-		const notice = failure
-			? `[Search incomplete: ${failure}]`
-			: pageHasMore
-				? `[Search incomplete: the page of ${headLimit} is full, so more may follow. Pass offset to continue, or narrow the directory or include pattern.]`
-				: truncated
-					? '[Search incomplete: the search did not reach every file. Narrow the directory or include pattern for a complete search.]'
-					: undefined
+		const notices = [
+			...(moreRemain
+				? [
+						`[More results are available: pass offset: ${offset + headLimit} to continue, or narrow the path or pattern.${enough ? ` Files are ordered newest first among the first ${filesToCollect.toLocaleString('en-US')} that matched.` : ''}]`,
+					]
+				: []),
+			...(stoppedEarly
+				? [stoppedNotice(timedOut ? 'time' : entryLimit ? 'entries' : 'files', endState?.visited)]
+				: []),
+			...(unreadableFiles > 0
+				? [
+						`(${plural(unreadableFiles, 'file')} could not be read and ${unreadableFiles === 1 ? 'was' : 'were'} skipped.)`,
+					]
+				: []),
+			...(failure ? [`[Search incomplete: ${failure}]`] : []),
+		]
 		return {
 			success: failure === undefined,
-			output: [body, summary, notice].filter(Boolean).join('\n\n'),
+			output: [body, summary, ...notices].filter(Boolean).join('\n\n'),
 			data: {
 				totalMatches,
 				filesSearched,
 				filesMatched,
 				truncated,
+				...(stoppedEarly ? { incomplete: true } : {}),
 				mode,
 				...(moreRemain ? { appliedLimit: headLimit } : {}),
 				...(offset > 0 ? { appliedOffset: offset } : {}),
@@ -474,6 +536,8 @@ export const GrepTool = defineTool({
 				filesMatched,
 				filesSearched,
 				truncated,
+				...(moreRemain ? { limited: true } : {}),
+				...(stoppedEarly ? { incomplete: true } : {}),
 			},
 			...(failure ? { error: failure } : {}),
 		}

package/src/tools/builtins/job.ts

@@ -1,6 +1,11 @@
 import { z } from 'zod'
 
 import { invalidBackgroundJobIdInput } from '../../runtime/jobs/job-id.js'
+import {
+	formatLivenessAge,
+	formatLivenessLine,
+	judgeLiveness,
+} from '../../runtime/jobs/liveness.js'
 import { defineTool } from '../defineTool.js'
 
 /**
@@ -21,7 +26,7 @@ const inputSchema = z.object({
 	action: z
 		.enum(['read', 'list', 'kill'])
 		.describe(
-			'read: output since `from_offset`. list: every background job this turn started, with status. kill: stop a job and everything it forked.',
+			'read: output since `from_offset`. list: every background job this turn started, each running one with whether it is progressing, waiting or stalled, how long since its last output, and its last output line. kill: stop a job and everything it forked.',
 		),
 	id: z
 		.string()
@@ -76,18 +81,33 @@ export const JobTool = defineTool({
 		if (input.action === 'list') {
 			const all = jobs.list()
 			if (all.length === 0) return { success: true, output: 'No background jobs.' }
+			const now = Date.now()
+			const lines = all.map((job) => {
+				const label = job.kind === 'monitor' ? (job.description ?? job.command) : job.command
+				if (job.startedAt === undefined) {
+					return `${job.id}  ${job.status.padEnd(8)}  ${job.kind === 'monitor' ? `monitor · ${label}` : label}`
+				}
+				const liveness = judgeLiveness(
+					{
+						kind: job.kind === 'monitor' ? 'monitor' : 'job',
+						id: job.id,
+						label,
+						...(job.lastOutputLine !== undefined ? { where: job.lastOutputLine } : {}),
+						startedAt: job.startedAt,
+						...(job.lastOutputAt !== undefined ? { lastProgressAt: job.lastOutputAt } : {}),
+						alive: job.status === 'running' && (jobs.isAlive ? jobs.isAlive(job.id) : true),
+						finished: job.status !== 'running',
+					},
+					now,
+				)
+				// An ended job keeps its status word, which carries the exit.
+				return job.status === 'running'
+					? formatLivenessLine(liveness)
+					: `${job.id}  ${job.status.padEnd(8)}  ${label}`
+			})
 			return {
 				success: true,
-				// A monitor is named by what it watches: its command is the means,
-				// and the description is what the model wrote to tell its watches apart.
-				output: all
-					.map(
-						(job) =>
-							`${job.id}  ${job.status.padEnd(8)}  ${
-								job.kind === 'monitor' ? `monitor · ${job.description ?? job.command}` : job.command
-							}`,
-					)
-					.join('\n'),
+				output: lines.join('\n'),
 				data: { jobs: all },
 			}
 		}
@@ -116,6 +136,11 @@ export const JobTool = defineTool({
 			const read = jobs.read(input.id, {
 				...(input.from_offset === undefined ? {} : { fromOffset: input.from_offset }),
 			})
+			// A stopped job read to its end is collected: its exit notice would only
+			// repeat what this result says. A read always reaches the end of the
+			// output; what it can miss is bytes the retention cap dropped, and then
+			// the notice stays.
+			if (read.status !== 'running' && read.droppedBytes === 0) jobs.markCollected?.(input.id)
 			// The dropped count is stated, never absorbed. A job whose middle
 			// vanished quietly reads as a complete result that happens to be
 			// short, and the model concludes the build passed.
@@ -123,9 +148,14 @@ export const JobTool = defineTool({
 				read.droppedBytes > 0
 					? `[${read.droppedBytes} bytes were dropped before this point — the job produced output faster than the retention cap holds]\n`
 					: ''
+			const lastOutputAt = read.status === 'running' ? jobs.get(input.id)?.lastOutputAt : undefined
 			const status =
 				read.status === 'running'
-					? 'still running'
+					? `still running${
+							lastOutputAt === undefined
+								? '; no output yet'
+								: `; last output ${formatLivenessAge((Date.now() - lastOutputAt) / 1000)} ago`
+						}`
 					: read.error !== undefined
 						? `failed to start: ${read.error}`
 						: `${read.status}${read.exitCode === undefined ? '' : ` with code ${read.exitCode}`}`

package/src/tools/builtins/search-support.ts

@@ -0,0 +1,107 @@
+import { isAbsolute, join as joinPath, posix, relative, sep } from 'node:path'
+
+import { subscribeToAbort } from '../../utils/abort.js'
+
+/**
+ * How long grep and glob search before they return what they have. The tool
+ * deadline (15 s) cancels a call outright and discards its output; a search
+ * that ends itself a little earlier can still hand back its matches.
+ */
+export const SEARCH_BUDGET_MS = 12_000
+
+/** Matching files a search reads at most; past it the search ends with what it has. */
+export const MAX_FILES_SEARCHED = 50_000
+
+export interface SearchBudget {
+	/** Fires when the caller cancels or the budget runs out. */
+	readonly signal: AbortSignal
+	/** True only when the budget ran out, not when the caller cancelled. */
+	expired(): boolean
+	close(): void
+}
+
+/** A signal that follows `parent` and also fires when the search budget is spent. */
+export function openSearchBudget(parent?: AbortSignal, budgetMs = SEARCH_BUDGET_MS): SearchBudget {
+	const controller = new AbortController()
+	let spent = false
+	const stopWatching = parent
+		? subscribeToAbort(parent, () => controller.abort(parent.reason))
+		: undefined
+	const timer = setTimeout(() => {
+		spent = true
+		controller.abort(new Error('search budget spent'))
+	}, budgetMs)
+	return {
+		signal: controller.signal,
+		expired: () => spent && !parent?.aborted,
+		close() {
+			clearTimeout(timer)
+			stopWatching?.()
+		},
+	}
+}
+
+/**
+ * A file as the model sees it: relative to the working directory when it lies
+ * under it, otherwise absolute. Never prefixed with `./`.
+ */
+export function hostDisplayPath(workingDirectory: string, absolute: string): string {
+	const rel = relative(workingDirectory, absolute)
+	if (rel === '') return '.'
+	if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return absolute
+	return sep === '/' ? rel : rel.split(sep).join('/')
+}
+
+/** Keep unusual filenames unambiguous without changing the returned path data. */
+export function quoteControlPath(path: string): string {
+	// biome-ignore lint/suspicious/noControlCharactersInRegex: quote filenames containing control bytes instead of creating fake result lines.
+	return /[\x00-\x1f\x7f]/.test(path) ? JSON.stringify(path) : path
+}
+
+export function plural(count: number, one: string, many = `${one}s`): string {
+	return `${count.toLocaleString('en-US')} ${count === 1 ? one : many}`
+}
+
+/** The line that tells the model why a search stopped before it finished. */
+export function stoppedNotice(reason: 'time' | 'entries' | 'files', visited?: number): string {
+	const how =
+		reason === 'time'
+			? `after ${SEARCH_BUDGET_MS / 1000} seconds`
+			: reason === 'entries'
+				? `after examining ${(visited ?? 0).toLocaleString('en-US')} entries`
+				: `after reading ${MAX_FILES_SEARCHED.toLocaleString('en-US')} files`
+	return `[Search stopped early ${how}. Results may be incomplete; narrow the path or pattern, or add an ignore rule.]`
+}
+
+/** Tells the model that an empty result may hide files an ignore rule excluded. */
+export function ignoredHint(ignoredDirectories: number): string {
+	return `(${plural(ignoredDirectories, 'ignored directory', 'ignored directories')} skipped by ignore rules; pass include_ignored: true to search ${ignoredDirectories === 1 ? 'it' : 'them'}.)`
+}
+
+/** A walker written before the entry bound became a normal stop still throws this. */
+export function isEntryLimit(error: unknown): boolean {
+	return (error as { code?: unknown } | null)?.code === 'ERR_FILE_WALK_LIMIT'
+}
+
+/**
+ * Whether the session's read rules deny this file, so a search neither lists
+ * nor opens it. `path` is absolute: a host path, or, when `sandboxRoot` is
+ * given, a path inside the sandbox, which is mapped to the same place under
+ * the working directory because that is the folder the sandbox binds; a path
+ * outside that folder is denied. A host
+ * that supplies no rules (`ToolContext.readDenied` absent) denies nothing.
+ */
+export function isReadDenied(
+	context: { workingDirectory: string; readDenied?: (path: string) => boolean },
+	path: string,
+	sandboxRoot?: string,
+): boolean {
+	if (!context.readDenied) return false
+	if (sandboxRoot === undefined) return context.readDenied(path)
+	const relative = posix.relative(sandboxRoot, path)
+	// A guest path outside the bound folder has no host counterpart the rules
+	// could be checked against, so a session that has read rules does not list
+	// or open it.
+	if (relative === '..' || relative.startsWith('../') || posix.isAbsolute(relative)) return true
+	return context.readDenied(joinPath(context.workingDirectory, relative))
+}