@namzu/sdk 57.1.0 → 58.0.0

package/src/tools/builtins/bash.ts

@@ -1,3 +1,4 @@
+import { rm } from 'node:fs/promises'
 import { z } from 'zod'
 import { isReadOnlyCommandLine } from '../../authorization/readonly-commands.js'
 import { SANDBOX_KILL_GRACE_MS } from '../../constants/sandbox/index.js'
@@ -24,8 +25,15 @@ import { defineTool } from '../defineTool.js'
 import { scrubInheritedEnv, withheldEnvNoticeText } from '../env-scrub.js'
 import { createHostOutputDecoder } from '../host-output.js'
 import { looksBinary, windowText } from '../text-window.js'
+import {
+	bashWorkingDirectoryForExecution,
+	newCwdFile,
+	recordDirectory,
+	withCwdCapture,
+} from './bash-cwd.js'
 import { judgeExit } from './exit-semantics.js'
 import { jsonStringEscapes } from './json-string-hint.js'
+import { leadingLongSleep, longSleepRefusal } from './sleep-guard.js'
 
 // Namzu owns its own bash timeout knob — `NAMZU_BASH_TIMEOUT_MS` — and
 // reads no consumer's env name. A consumer that wants one knob aliases
@@ -526,7 +534,7 @@ export const SANDBOX_ESCAPE_NOT_APPROVED =
 	'dangerously_disable_sandbox was not approved for this call, so the command did not run. Leaving the sandbox needs the user to confirm it each time, and this turn either cannot ask or does not allow it. Run the command inside the sandbox, or tell the user what it needs and let them run it.'
 
 const BASH_DESCRIPTION =
-	'Executes a command line using the execution shell disclosed in the system context and returns stdout/stderr output. Command timeout is configurable. The `command` parameter is required, so every call carries one. Long file content goes through `write`, not a heredoc, so it cannot hit the output token limit mid-stream.'
+	'Executes a command line using the execution shell disclosed in the system context and returns stdout/stderr output. The working directory persists between calls, but shell state does not. Command timeout is configurable. The `command` parameter is required, so every call carries one. Long file content goes through `write`, not a heredoc, so it cannot hit the output token limit mid-stream.'
 
 const BashToolBase = defineTool({
 	name: 'bash',
@@ -579,6 +587,7 @@ const BashToolBase = defineTool({
 	},
 
 	async execute(input, context) {
+		const startDirectory = bashWorkingDirectoryForExecution(context)
 		if (isDangerousCommand(input.command)) {
 			return {
 				success: false,
@@ -588,6 +597,15 @@ const BashToolBase = defineTool({
 			}
 		}
 
+		// Where a job registry exists to wait on, a long leading sleep only
+		// holds the turn; it is refused with the better ways to wait.
+		if (!input.run_in_background && context.backgroundJobs && !backgroundTasksDisabled()) {
+			const longSleep = leadingLongSleep(input.command)
+			if (longSleep !== null) {
+				return { success: false, output: '', error: longSleepRefusal(longSleep) }
+			}
+		}
+
 		// Asked to leave the sandbox. Honoured only on the executor's word that
 		// a reviewer confirmed THIS call (`sandboxEscapeApproved`); the input
 		// alone is the model's request, never the permission. Without a
@@ -648,7 +666,7 @@ const BashToolBase = defineTool({
 			try {
 				const job = context.backgroundJobs.start({
 					command: input.command,
-					workingDirectory: context.workingDirectory,
+					workingDirectory: startDirectory,
 				})
 				// `start` returns before the process exists, and a spawn that
 				// fails (no such shell, bad directory) reports a tick later.
@@ -799,38 +817,57 @@ const BashToolBase = defineTool({
 		let withdrawOffer: (() => void) | undefined
 		const offer = context.backgroundJobs?.registerForeground?.bind(context.backgroundJobs)
 
+		// The directory carries over between calls of a session on a POSIX host
+		// shell; the shell records where it ended, read back in `finally`.
+		const hostShell = hostCommandShell()
+		const carryDirectory =
+			context.sandbox === undefined &&
+			typeof context.sessionId === 'string' &&
+			hostShell.path !== undefined &&
+			hostShell.windows !== true
+		const cwdFile = carryDirectory ? newCwdFile() : undefined
+		let settled = false
+		const settle = async (): Promise<string | undefined> => {
+			if (cwdFile === undefined) return undefined
+			settled = true
+			return recordDirectory(context.sessionId, cwdFile, context)
+		}
+
 		try {
 			const { stdout, stderr, stdoutBytes, stderrBytes, backgroundedJobId, backgroundedBy } =
-				await execHostShell(input.command, {
-					cwd: context.workingDirectory,
-					timeout: input.timeout,
-					env: { ...inherited.env, ...context.env },
-					maxBuffer: DEFAULT_BASH_MAX_BUFFER_BYTES,
-					signal: context.abortSignal,
-					onOutput,
-					...(canMoveOnTimeout ? { onTimeout: adoptRunning } : {}),
-					...(canHandOff
-						? {
-								adopt: adoptRunning,
-								adoptOnInterrupt: true,
-								...(offer
-									? {
-											onRunning: (control: {
-												background(reason: 'user' | 'message'): boolean
-											}) => {
-												offerTimer = setTimeout(() => {
-													withdrawOffer = offer({
-														command: input.command,
-														background: (reason) => control.background(reason),
-													})
-												}, FOREGROUND_HANDOFF_AFTER_MS)
-												offerTimer.unref?.()
-											},
-										}
-									: {}),
-							}
-						: {}),
-				})
+				await execHostShell(
+					cwdFile === undefined ? input.command : withCwdCapture(input.command, cwdFile),
+					{
+						cwd: startDirectory,
+						timeout: input.timeout,
+						env: { ...inherited.env, ...context.env },
+						maxBuffer: DEFAULT_BASH_MAX_BUFFER_BYTES,
+						signal: context.abortSignal,
+						onOutput,
+						...(canMoveOnTimeout ? { onTimeout: adoptRunning } : {}),
+						...(canHandOff
+							? {
+									adopt: adoptRunning,
+									adoptOnInterrupt: true,
+									...(offer
+										? {
+												onRunning: (control: {
+													background(reason: 'user' | 'message'): boolean
+												}) => {
+													offerTimer = setTimeout(() => {
+														withdrawOffer = offer({
+															command: input.command,
+															background: (reason) => control.background(reason),
+														})
+													}, FOREGROUND_HANDOFF_AFTER_MS)
+													offerTimer.unref?.()
+												},
+											}
+										: {}),
+								}
+							: {}),
+					},
+				)
 			if (backgroundedJobId !== undefined) {
 				const timedOut = backgroundedBy === 'timeout'
 				return {
@@ -853,9 +890,10 @@ const BashToolBase = defineTool({
 					facts: { kind: 'command', command: input.command, background: true, continued: true },
 				}
 			}
+			const reset = await settle()
 			return {
 				success: true,
-				output: formatShellOutput(stdout, stderr) || '(no output)',
+				output: withResetNotice(formatShellOutput(stdout, stderr) || '(no output)', reset),
 				data: {
 					exitCode: 0,
 					...(leaveSandbox ? { sandboxed: false, sandboxEscape: true } : {}),
@@ -903,6 +941,7 @@ const BashToolBase = defineTool({
 			const judged =
 				!timedOut && exitCode !== undefined ? judgeExit(input.command, exitCode) : undefined
 			const answered = judged !== undefined && !judged.isError
+			const reset = await settle()
 			const output = [
 				formatShellOutput(failure.stdout, failure.stderr),
 				clipped.length > 0
@@ -914,7 +953,7 @@ const BashToolBase = defineTool({
 
 			return {
 				success: answered,
-				output: output || '(no output)',
+				output: withResetNotice(output || '(no output)', reset),
 				data: {
 					...(exitCode !== undefined ? { exitCode } : {}),
 					...(judged?.note ? { exitNote: judged.note } : {}),
@@ -949,6 +988,7 @@ const BashToolBase = defineTool({
 				}),
 			}
 		} finally {
+			if (cwdFile !== undefined && !settled) await rm(cwdFile, { force: true })
 			if (offerTimer !== undefined) clearTimeout(offerTimer)
 			withdrawOffer?.()
 		}
@@ -1002,6 +1042,11 @@ function formatShellOutput(stdout: string | undefined, stderr: string | undefine
 		.join('\n\n')
 }
 
+/** The result text with the directory-reset line, when there is one, on its own last line. */
+function withResetNotice(output: string, notice: string | undefined): string {
+	return notice === undefined ? output : `${output}\n${notice}`
+}
+
 /**
  * The notice text for the credential-shaped variables left out of a command's
  * environment (see {@link withheldEnvNoticeText}). It is sent as a notice after

package/src/tools/builtins/bounded-file-read.ts

@@ -0,0 +1,80 @@
+import { constants } from 'node:fs'
+import { open } from 'node:fs/promises'
+
+const CHUNK_BYTES = 64 * 1024
+
+/** A hard input ceiling, independent of output windows and allow_large. */
+export const TEXT_MAX_INPUT_BYTES = 32 * 1024 * 1024
+
+/**
+ * Read at most the limit plus one sentinel byte, even if the file grows after
+ * stat. No allocation or request is derived from an untrusted file size.
+ * The first bounded chunk can choose a stricter limit from the file signature.
+ */
+export async function readBoundedChunks(
+	read: (offset: number, length: number) => Promise<Buffer>,
+	maximum: number,
+	signal?: AbortSignal,
+	selectLimit?: (prefix: Buffer) => number,
+): Promise<Buffer> {
+	const chunks: Buffer[] = []
+	let offset = 0
+	let limit = maximum
+	for (;;) {
+		signal?.throwIfAborted()
+		const length = Math.min(CHUNK_BYTES, limit + 1 - offset)
+		const chunk = await read(offset, length)
+		signal?.throwIfAborted()
+		if (chunk.length > length)
+			throw new Error('The file backend returned more bytes than the requested bounded range.')
+		if (offset === 0 && selectLimit) limit = Math.min(maximum, selectLimit(chunk))
+		offset += chunk.length
+		if (offset > limit) throw inputTooLarge(limit)
+		chunks.push(chunk)
+		if (chunk.length < length) return Buffer.concat(chunks, offset)
+	}
+}
+
+export async function readBoundedFile(
+	path: string,
+	maximum: number,
+	signal?: AbortSignal,
+	selectLimit?: (prefix: Buffer) => number,
+): Promise<Buffer> {
+	// O_NONBLOCK prevents a substituted FIFO from blocking open before fstat.
+	signal?.throwIfAborted()
+	const file = await open(path, constants.O_RDONLY | constants.O_NONBLOCK)
+	try {
+		const info = await file.stat()
+		if (!info.isFile()) throw new Error('Read requires a regular file.')
+		if (info.size > maximum) throw inputTooLarge(maximum)
+		return await readBoundedChunks(
+			async (offset, length) => {
+				const buffer = Buffer.allocUnsafe(length)
+				let used = 0
+				while (used < length) {
+					signal?.throwIfAborted()
+					const { bytesRead } = await file.read(buffer, used, length - used, offset + used)
+					if (bytesRead === 0) break
+					used += bytesRead
+				}
+				return buffer.subarray(0, used)
+			},
+			maximum,
+			signal,
+			(prefix) => {
+				const limit = selectLimit?.(prefix) ?? maximum
+				if (info.size > limit) throw inputTooLarge(limit)
+				return limit
+			},
+		)
+	} finally {
+		await file.close()
+	}
+}
+
+function inputTooLarge(limit: number): Error {
+	return new Error(
+		`File exceeds the bounded read limit (${limit} bytes). Extract a smaller file with a shell command.`,
+	)
+}

package/src/tools/builtins/grep.ts

@@ -1,8 +1,9 @@
-import { readFile, stat } from 'node:fs/promises'
+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 { ToolContext } from '../../types/tool/index.js'
 import { subscribeToAbort } from '../../utils/abort.js'
 import { defineTool } from '../defineTool.js'
 import {
@@ -13,6 +14,7 @@ import {
 	toolRoots,
 } from '../paths.js'
 import { relativePosix, resolveWithinPosix } from '../posix-path.js'
+import { readBoundedChunks, readBoundedFile } from './bounded-file-read.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> {
@@ -57,6 +59,46 @@ export const DEFAULT_HEAD_LIMIT = 250
 /** A matching or context line longer than this is replaced by a notice, not printed. */
 export const MAX_LINE_COLUMNS = 500
 
+/** File kinds for the `type` argument: extensions (without the dot) and exact file names. */
+const FILE_TYPES: Record<string, { ext: string[]; names?: string[] }> = {
+	js: { ext: ['js', 'jsx', 'mjs', 'cjs'] },
+	ts: { ext: ['ts', 'tsx', 'mts', 'cts'] },
+	py: { ext: ['py', 'pyi'] },
+	rust: { ext: ['rs'] },
+	go: { ext: ['go'] },
+	java: { ext: ['java'] },
+	kotlin: { ext: ['kt', 'kts'] },
+	swift: { ext: ['swift'] },
+	c: { ext: ['c', 'h'] },
+	cpp: { ext: ['cc', 'cpp', 'cxx', 'hpp', 'hh', 'hxx', 'h'] },
+	cs: { ext: ['cs'] },
+	rb: { ext: ['rb', 'rake', 'gemspec'] },
+	php: { ext: ['php'] },
+	sh: { ext: ['sh', 'bash', 'zsh'] },
+	md: { ext: ['md', 'markdown', 'mdx'] },
+	json: { ext: ['json', 'jsonc'] },
+	yaml: { ext: ['yml', 'yaml'] },
+	toml: { ext: ['toml'] },
+	html: { ext: ['html', 'htm'] },
+	css: { ext: ['css', 'scss', 'sass', 'less'] },
+	sql: { ext: ['sql'] },
+	xml: { ext: ['xml'] },
+	make: { ext: ['mk', 'mak'], names: ['Makefile', 'makefile', 'GNUmakefile'] },
+	docker: { ext: [], names: ['Dockerfile'] },
+}
+FILE_TYPES.javascript = FILE_TYPES.js as { ext: string[] }
+FILE_TYPES.typescript = FILE_TYPES.ts as { ext: string[] }
+FILE_TYPES.python = FILE_TYPES.py as { ext: string[] }
+FILE_TYPES.rs = FILE_TYPES.rust as { ext: string[] }
+FILE_TYPES.markdown = FILE_TYPES.md as { ext: string[] }
+
+function matchesType(path: string, kind: { ext: string[]; names?: string[] }): boolean {
+	const name = path.slice(path.lastIndexOf('/') + 1)
+	if (kind.names?.includes(name)) return true
+	const dot = name.lastIndexOf('.')
+	return dot > 0 && kind.ext.includes(name.slice(dot + 1))
+}
+
 const inputSchema = z.object({
 	pattern: z.string().describe('Regular expression pattern to search for in file contents'),
 	path: z
@@ -74,6 +116,24 @@ const inputSchema = z.object({
 		.min(0)
 		.default(0)
 		.describe('Number of lines to show before and after each match'),
+	before_context: z.coerce
+		.number()
+		.int()
+		.min(0)
+		.optional()
+		.describe('Lines before each content match; overrides context_lines for this side.'),
+	after_context: z.coerce
+		.number()
+		.int()
+		.min(0)
+		.optional()
+		.describe('Lines after each content match; overrides context_lines for this side.'),
+	only_matching: z
+		.boolean()
+		.optional()
+		.describe(
+			'In content mode, print each matched substring instead of the whole line. Ignores context.',
+		),
 	output_mode: z
 		.enum(['files_with_matches', 'content', 'count'])
 		.default('files_with_matches')
@@ -94,6 +154,18 @@ const inputSchema = z.object({
 		.min(0)
 		.default(0)
 		.describe('Skip this many entries before applying head_limit, to page through results.'),
+	multiline: z
+		.boolean()
+		.optional()
+		.describe(
+			'Let a pattern span lines: "." also matches a newline, and "^" and "$" match at line starts and ends. Content mode prints every line a match covers.',
+		),
+	type: z
+		.string()
+		.optional()
+		.describe(
+			'Only search files of this kind, e.g. "js", "ts", "py", "rust", "go", "java", "md". Narrows what include selects.',
+		),
 	max_results: z.coerce
 		.number()
 		.int()
@@ -117,7 +189,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. 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 with a bounded traversal and identifies incomplete searches. 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
@@ -146,7 +218,18 @@ export const GrepTool = defineTool({
 
 	async execute(input, context) {
 		context.abortSignal?.throwIfAborted()
-		const flags = input.case_sensitive ? 'g' : 'gi'
+		const multiline = input.multiline === true
+		const flags = `${(input.case_sensitive ?? true) ? 'g' : 'gi'}${multiline ? 'ms' : ''}`
+		const fileType = input.type
+			? FILE_TYPES[input.type.toLowerCase().replace(/^\./, '')]
+			: undefined
+		if (input.type && !fileType) {
+			return {
+				success: false,
+				output: '',
+				error: `Unknown file type "${input.type}". Known types: ${Object.keys(FILE_TYPES).sort().join(', ')}. Use include for another pattern.`,
+			}
+		}
 		let regex: RegExp
 		try {
 			regex = new RegExp(input.pattern, flags)
@@ -189,6 +272,8 @@ export const GrepTool = defineTool({
 		// `max_results` predates `head_limit`; it keeps meaning "at most this many".
 		const headLimit = input.head_limit ?? input.max_results ?? DEFAULT_HEAD_LIMIT
 		const offset = input.offset ?? 0
+		const beforeContext = input.before_context ?? input.context_lines ?? 0
+		const afterContext = input.after_context ?? input.context_lines ?? 0
 		// Content lines in output order. Only content mode uses them as the
 		// result; the other modes build from `matchedFiles`.
 		const results: string[] = []
@@ -213,6 +298,7 @@ export const GrepTool = defineTool({
 					)
 				}
 				filesSearched++
+				if (fileType && !matchesType(entry.path, fileType)) continue
 				if (entry.size > MAX_FILE_SIZE) continue
 
 				let content: string
@@ -221,10 +307,15 @@ export const GrepTool = defineTool({
 					const buffer = await readWithSignal(
 						() =>
 							sandbox
-								? sandbox.readFile(filePath)
+								? readBoundedChunks(
+										(offset, length) =>
+											sandbox.readFile(filePath, { offset, length, signal: context.abortSignal }),
+										MAX_FILE_SIZE,
+										context.abortSignal,
+									)
 								: resolveWithinReal(root, filePath).then((path) => {
 										contained = path
-										return readFile(path, { signal: context.abortSignal })
+										return readBoundedFile(path, MAX_FILE_SIZE, context.abortSignal)
 									}),
 						context.abortSignal,
 					)
@@ -245,36 +336,47 @@ export const GrepTool = defineTool({
 							.split(sep)
 							.join('/')}`
 
-				for (let i = 0; i < lines.length; i++) {
-					context.abortSignal?.throwIfAborted()
-					const line = lines[i] ?? ''
-					regex.lastIndex = 0
-					if (!regex.test(line)) continue
+				if (mode === 'content' && input.only_matching) {
+					for (const fragment of matchingFragments(content, regex, multiline)) {
+						context.abortSignal?.throwIfAborted()
+						if (fileMatches++ === 0) filesMatched++
+						totalMatches++
+						results.push(`${relPath}:${fragment.line}:${clipLine(fragment.text, 'matching')}`)
+						if (headLimit > 0 && results.length >= offset + headLimit) {
+							pageHasMore = true
+							break
+						}
+					}
+					if (pageHasMore) break
+					continue
+				}
 
+				// Each hit is the first and last line (0-based) a match covers.
+				const hits = multiline ? multilineHits(content, regex) : lineHits(lines, regex, context)
+				// 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()
 					if (fileMatches === 0) filesMatched++
 					fileMatches++
 					totalMatches++
 					// A file list only needs to know that the file matches.
 					if (mode === 'files_with_matches') break
-					if (mode === 'count') continue
-
-					if (input.context_lines > 0) {
-						const start = Math.max(0, i - input.context_lines)
-						const end = Math.min(lines.length - 1, i + input.context_lines)
-
-						if (results.length > 0) {
-							results.push('--')
-						}
+					if (mode === 'count') {
+						for (let j = first; j <= last; j++) countedLines.add(j)
+						continue
+					}
 
-						for (let j = start; j <= end; j++) {
-							const prefix = j === i ? ':' : '-'
-							const text = lines[j] ?? ''
-							results.push(
-								`${relPath}${prefix}${j + 1}${prefix}${clipLine(text, j === i ? 'matching' : 'context')}`,
-							)
-						}
-					} else {
-						results.push(`${relPath}:${i + 1}:${clipLine(line, 'matching')}`)
+					const before = Math.max(0, first - beforeContext)
+					const after = Math.min(lines.length - 1, last + afterContext)
+					if ((beforeContext > 0 || afterContext > 0) && results.length > 0) results.push('--')
+					for (let j = before; j <= after; j++) {
+						if (headLimit > 0 && results.length >= offset + headLimit) break
+						const hit = j >= first && j <= last
+						const prefix = hit ? ':' : '-'
+						results.push(
+							`${relPath}${prefix}${j + 1}${prefix}${clipLine(lines[j] ?? '', hit ? 'matching' : 'context')}`,
+						)
 					}
 
 					// A full page ends the search: another file is not read just to
@@ -285,6 +387,7 @@ export const GrepTool = defineTool({
 						break
 					}
 				}
+				if (mode === 'count' && fileMatches > 0) fileMatches = countedLines.size
 
 				if (fileMatches > 0 && mode !== 'content') {
 					matchedFiles.push({
@@ -404,3 +507,70 @@ async function sortByNewest<T extends { relPath: string; host?: string }>(
 		.sort((a, b) => b.mtime - a.mtime || a.file.relPath.localeCompare(b.file.relPath))
 		.map((entry) => entry.file)
 }
+
+/** One hit per matching line. */
+function lineHits(
+	lines: readonly string[],
+	regex: RegExp,
+	context: ToolContext,
+): [number, number][] {
+	const hits: [number, number][] = []
+	for (let i = 0; i < lines.length; i++) {
+		context.abortSignal?.throwIfAborted()
+		regex.lastIndex = 0
+		if (regex.test(lines[i] ?? '')) hits.push([i, i])
+	}
+	return hits
+}
+
+/** One hit per match over the whole text, from the line it starts on to the line it ends on. */
+function multilineHits(content: string, regex: RegExp): [number, number][] {
+	const hits: [number, number][] = []
+	const starts = [0]
+	for (let i = content.indexOf('\n'); i !== -1; i = content.indexOf('\n', i + 1)) starts.push(i + 1)
+	const lineOf = (offset: number): number => {
+		let lo = 0
+		let hi = starts.length - 1
+		while (lo < hi) {
+			const mid = (lo + hi + 1) >> 1
+			if ((starts[mid] ?? 0) <= offset) lo = mid
+			else hi = mid - 1
+		}
+		return lo
+	}
+	regex.lastIndex = 0
+	for (let m = regex.exec(content); m !== null; m = regex.exec(content)) {
+		const text = m[0]
+		if (text.length === 0) {
+			regex.lastIndex++
+			continue
+		}
+		// A match that ends on a newline covers the lines before it, not the next one.
+		const end = m.index + text.length - (text.endsWith('\n') ? 1 : 0)
+		hits.push([lineOf(m.index), lineOf(Math.max(m.index, end))])
+	}
+	return hits
+}
+
+/** Lazy fragments: a dense file never allocates every match before paging. */
+function* matchingFragments(content: string, regex: RegExp, multiline: boolean) {
+	const subjects = multiline ? [content] : content.split('\n')
+	let line = 1
+	for (const subject of subjects) {
+		regex.lastIndex = 0
+		let previous = 0
+		for (let match = regex.exec(subject); match !== null; match = regex.exec(subject)) {
+			if (multiline) {
+				for (let i = previous; i < match.index; i++) if (subject[i] === '\n') line++
+				previous = match.index
+			}
+			if (match[0].length === 0) {
+				regex.lastIndex++
+				continue
+			}
+			// Keep a multiline substring on one output row, never forge path rows.
+			yield { line, text: match[0].replace(/\n/g, '\\n') }
+		}
+		if (!multiline) line++
+	}
+}