@namzu/sdk 48.3.0 → 49.0.0

package/src/registry/tool/screen.ts

@@ -83,7 +83,13 @@ export async function screenToolResult(
 ): Promise<ToolResult> {
 	if (!guardrails || guardrails.length === 0) return result
 
-	let current = result.output
+	// Failed tools are rendered from BOTH output and error. Screen the same
+	// text the executor would show, including an error-only failure.
+	let current = result.success
+		? result.output
+		: result.output.trim()
+			? `${result.output}\n\nError: ${result.error ?? 'Tool execution failed'}`
+			: `Error: ${result.error ?? 'Tool execution failed'}`
 	let rewritten = false
 
 	for (const [index, spec] of guardrails.entries()) {
@@ -128,5 +134,31 @@ export async function screenToolResult(
 		}
 	}
 
-	return rewritten ? { ...result, output: current } : result
+	// `content` wins over `output` on the model wire. A rewrite that leaves
+	// original content blocks in place would expose the text it just redacted.
+	// Rich blocks cannot be screened through the text-only verdict either, so
+	// a rewrite replaces the complete model-visible content with its text.
+	if (rewritten && !result.success) {
+		// Reconstruct the failure fields when the rewrite kept the normal
+		// formatting. Keeping the whole formatted text in `error` would make
+		// the executor add a second `Error:` prefix to the visible result.
+		const marker = '\n\nError: '
+		const lastMarker = current.lastIndexOf(marker)
+		const output = lastMarker >= 0 ? current.slice(0, lastMarker) : ''
+		const error =
+			lastMarker >= 0
+				? current.slice(lastMarker + marker.length)
+				: current.startsWith('Error: ')
+					? current.slice('Error: '.length)
+					: current
+		const visible = output.trim() ? `${output}\n\nError: ${error}` : `Error: ${error}`
+		return { ...result, output, error, content: visible }
+	}
+	return rewritten
+		? {
+				...result,
+				output: current,
+				content: current,
+			}
+		: result
 }

package/src/runtime/jobs/registry.ts

@@ -4,7 +4,7 @@ import { SANDBOX_KILL_GRACE_MS } from '../../constants/sandbox/index.js'
 import { killTree } from '../../process/kill-tree.js'
 import { hostShellSpawn } from '../../tools/command-shell.js'
 import { scrubInheritedEnv } from '../../tools/env-scrub.js'
-import { awaitWithAbort } from '../../utils/await-with-abort.js'
+import { subscribeToAbort } from '../../utils/abort.js'
 
 /**
  * Work that outlives a tool call, owned by whoever started it.
@@ -246,6 +246,8 @@ export class BackgroundJobRegistry {
 			buffer: '',
 			produced: 0,
 			exit: new Promise<void>((resolve) => {
+				let spawned = child.pid !== undefined
+				let failedToSpawn = false
 				const finalize = (code: number | null, signal: NodeJS.Signals | null): void => {
 					entry.record = {
 						...entry.record,
@@ -260,6 +262,15 @@ export class BackgroundJobRegistry {
 					resolve()
 					this.announceExit(entry.record)
 				}
+				child.once('spawn', () => {
+					spawned = true
+				})
+				child.on('error', () => {
+					// A failed spawn emits both `error` and `close`. Waiting for
+					// `close` also covers errors on an already-running process
+					// (such as a failed kill) without announcing a false exit.
+					if (!spawned) failedToSpawn = true
+				})
 				child.once('close', (code, signal) => {
 					// The job is the process GROUP, not the shell. A command that
 					// backgrounds its real work (`server &`) exits the shell at
@@ -270,21 +281,17 @@ export class BackgroundJobRegistry {
 					// job whose shell has ended stays running while its group is
 					// alive, and ends — with the shell's exit code — when the
 					// group is empty.
+					const exitCode = failedToSpawn ? null : code
 					if (entry.record.status !== 'killed' && groupAlive(child.pid)) {
 						const poll = setInterval(() => {
 							if (groupAlive(child.pid)) return
 							clearInterval(poll)
-							finalize(code, signal)
+							finalize(exitCode, signal)
 						}, GROUP_POLL_MS)
 						poll.unref()
 						return
 					}
-					finalize(code, signal)
-				})
-				child.once('error', () => {
-					entry.record = { ...entry.record, status: 'exited', exitedAt: Date.now() }
-					resolve()
-					this.announceExit(entry.record)
+					finalize(exitCode, signal)
 				})
 			}),
 		}
@@ -336,13 +343,30 @@ export class BackgroundJobRegistry {
 		const entry = this.jobs.get(id)
 		if (!entry) throw new UnknownBackgroundJobError({ id })
 		if (entry.record.status !== 'running') return Promise.resolve(entry.record)
-		// `entry` is the same object the `finalize` closure in `start()`
-		// mutates in place, so reading `entry.record` after `exit` settles
-		// sees the final status — the same trick `kill()` already relies on.
-		return awaitWithAbort(
-			entry.exit.then(() => entry.record),
-			opts.signal,
-		)
+		if (!opts.signal) {
+			// Keep the original promise path for callers without cancellation.
+			return entry.exit.then(() => entry.record)
+		}
+		const signal = opts.signal
+		if (signal.aborted) return Promise.reject(signal.reason)
+
+		// A Promise.race against entry.exit leaves a continuation on that
+		// never-ending promise after cancellation. An exit listener can instead
+		// be removed as soon as this particular wait is abandoned.
+		return new Promise<BackgroundJob>((resolve, reject) => {
+			let disposeAbort = () => {}
+			const unsubscribe = this.onExit((job) => {
+				if (job.id !== id) return
+				unsubscribe()
+				disposeAbort()
+				resolve(job)
+			})
+			disposeAbort = subscribeToAbort(signal, () => {
+				unsubscribe()
+				disposeAbort()
+				reject(signal.reason)
+			})
+		})
 	}
 
 	/**

package/src/runtime/query/index.ts

@@ -264,6 +264,12 @@ export interface QueryParams {
 	 * finishes.
 	 */
 	backgroundJobOwner?: string
+	/**
+	 * Called with job ids only when their exit notices enter model context:
+	 * a tool result or a recorded job-exit message. An exit event alone does not
+	 * mean the model saw it. A host can carry unacknowledged exits to its next turn.
+	 */
+	onJobNoticeDelivered?: (jobIds: readonly string[]) => void
 
 	/**
 	 * What else goes in this turn's prompt.
@@ -1319,6 +1325,20 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 		// subscription that fills it below, because the wait-intent recorder needs
 		// to ask whether its text has been read yet.
 		const jobNotices = params.backgroundJobs ? new SteeringBinding() : undefined
+		const pendingJobNoticeIds = new Set<string>()
+		const acknowledgeJobNotices = () => {
+			if (pendingJobNoticeIds.size === 0) return
+			const ids = [...pendingJobNoticeIds]
+			pendingJobNoticeIds.clear()
+			try {
+				params.onJobNoticeDelivered?.(ids)
+			} catch (error) {
+				// A host observer cannot retract model-visible context or fail the turn.
+				ctx.log.warn('A background job notice observer failed', {
+					'exception.message': error instanceof Error ? error.message : String(error),
+				})
+			}
+		}
 		// Jobs the model told `wait_for_job` it is waiting on, which is the only
 		// thing that can hold this turn open for a job. Built only where there is a
 		// registry, so a host with no background mode carries no recorder and the
@@ -1425,6 +1445,7 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 			jobNotices?.steer(
 				`Background job ${job.id} (${job.command}) ${outcome}. Read its output with the job tool if you need it.`,
 			)
+			pendingJobNoticeIds.add(job.id)
 			void eventTranslator
 				.emitEvent({
 					type: 'background_job_exited',
@@ -1567,6 +1588,7 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 				: {}),
 			tools: toolManager,
 			allowedTools: effectiveAllowedTools,
+			showDeferredToolContext: params.contextLevel !== 'minimal',
 			recorder: ctx.recorder,
 			toolExecutor,
 			guard,
@@ -1582,6 +1604,7 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 			promptContributions,
 			...(params.steering ? { steering: params.steering } : {}),
 			...(jobNotices ? { jobNotices } : {}),
+			...(jobNotices ? { onJobNoticeDelivered: acknowledgeJobNotices } : {}),
 			...(awaitedJobs ? { awaitedJobs } : {}),
 			checkpointMgr,
 			planManager: ctx.planManager,
@@ -1807,7 +1830,7 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 					if (annotations.length > 0) {
 						promptContributions.replace({
 							id: 'hooks:user_prompt_submit',
-							placement: 'dynamic',
+							placement: 'context',
 							render: () => `Context from the operator's hooks:\n\n${annotations.join('\n\n')}`,
 						})
 					}

package/src/runtime/query/iteration/index.ts

@@ -3,7 +3,9 @@ import {
 	extractFromAssistantMessage,
 	extractFromUserMessage,
 } from '../../../compaction/extractor.js'
+import { estimateMessageTokens } from '../../../compaction/token-estimate.js'
 import { AUTO_CONTINUATION_USER_MESSAGE } from '../../../constants/continuation.js'
+import { CHARS_PER_TOKEN } from '../../../constants/limits.js'
 import {
 	DEFAULT_STRUCTURED_OUTPUT_RETRIES,
 	STRUCTURED_OUTPUT_REPROMPT,
@@ -548,13 +550,37 @@ export class IterationOrchestrator {
 					// Shape this step before calling the model. `stopWhen` decides
 					// whether to keep going; this decides HOW. No-op when the host
 					// supplied no hook.
+					// Render request-only contributions once before preparation. Their
+					// estimated cost reduces every stage's headroom, and the same text
+					// reaches the provider even if a stage changes external state.
+					const contextSections =
+						this.ctx.promptContributions?.render('context', { iteration: iterationNum }) ?? []
+					const deferredMcpHints =
+						this.ctx.showDeferredToolContext !== false
+							? this.ctx.tools.snapshotUntrustedDeferredContext()
+							: undefined
+					const pricedContextText = [
+						...contextSections,
+						...(deferredMcpHints?.all ? [deferredMcpHints.all] : []),
+					].join('\n\n')
+					const shaping: StepShaping = {
+						...this.stepShaping(),
+						requestContextTokens: pricedContextText
+							? estimateMessageTokens(stepContextMessage(pricedContextText)) +
+								Math.ceil(
+									((deferredMcpHints?.maxRenderedChars ?? 0) -
+										(deferredMcpHints?.all.length ?? 0)) /
+										CHARS_PER_TOKEN,
+								)
+							: 0,
+					}
 					const contextModelBeforePreparation = this.ctx.contextModel ?? model
-					const step = await prepareStep(this.stepShaping(), iterationNum)
+					const step = await prepareStep(shaping, iterationNum)
 					// Preparation inference belongs to the turn, not the main-model step.
 					usageBefore = { ...recorder.tokenUsage }
 					costBefore = { ...recorder.costInfo }
 					stepModel = step.model ?? model
-					await selectContextModel(this.stepShaping(), stepModel)
+					await selectContextModel(shaping, stepModel)
 					// Preserve post-compaction preparation/recall semantics. A changed
 					// model needs a second check against its own window; never replay
 					// host preparation effects merely to rebuild its request guidance.
@@ -563,6 +589,11 @@ export class IterationOrchestrator {
 					yield* this.ctx.drainPending()
 
 					const stepAllowedTools = step.allowedTools ?? this.ctx.allowedTools
+					const deferredMcpContext = deferredMcpHints?.forNames(stepAllowedTools) ?? ''
+					const contextText = [
+						...contextSections,
+						...(deferredMcpContext ? [deferredMcpContext] : []),
+					].join('\n\n')
 					const llmTools = this.ctx.tools
 						.toLLMTools(stepAllowedTools)
 						.filter(
@@ -643,11 +674,6 @@ export class IterationOrchestrator {
 					// (compaction preserves it there) and leaves the request's
 					// system run here.
 					const workingMemory = splitWorkingMemoryForRequest(baseMessages)
-					const contextSections =
-						this.ctx.promptContributions?.render('context', {
-							iteration: iterationNum,
-						}) ?? []
-
 					const stepPreamble = [step.system, stepSkills, policyNotice, ...turnSections]
 						.filter(Boolean)
 						.join('\n\n')
@@ -655,15 +681,14 @@ export class IterationOrchestrator {
 						? [...workingMemory.history, createSystemMessage(stepPreamble)]
 						: [...workingMemory.history]
 					if (workingMemory.context) requestHistory.push(workingMemory.context)
-					if (contextSections.length > 0)
-						requestHistory.push(stepContextMessage(contextSections.join('\n\n')))
+					if (contextText) requestHistory.push(stepContextMessage(contextText))
 					if (step.context) requestHistory.push(stepContextMessage(step.context))
 					const messages = projectRequestRichContent(
 						this.projectObservations(requestHistory),
 						this.ctx.turnConfig.maxRequestRichContentBytes ??
 							DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES,
 					)
-					appendWorkContext(this.stepShaping(), messages, iterationNum, step)
+					appendWorkContext(shaping, messages, iterationNum, step)
 					if (closingDirective) messages.push(closingDirective)
 					await this.reportUnsupportedToolResults(messages)
 					yield* this.ctx.drainPending()

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

@@ -260,6 +260,7 @@ export function deliverAwaitedJobExits(ctx: IterationContext): boolean {
 		'namzu.runtime.jobs': delivered.exits.map((job) => job.id),
 	})
 	ctx.recorder.pushMessage(createRuntimeContextMessage(formatJobNote(delivered.text), 'job-exit'))
+	ctx.onJobNoticeDelivered?.()
 	return true
 }
 
@@ -383,4 +384,5 @@ export function deliverArrivedJobExits(ctx: IterationContext): void {
 		'namzu.runtime.jobs': delivered.exits.map((job) => job.id),
 	})
 	ctx.recorder.pushMessage(createRuntimeContextMessage(formatJobNote(delivered.text), 'job-exit'))
+	ctx.onJobNoticeDelivered?.()
 }

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

@@ -98,6 +98,8 @@ export interface IterationContext {
 	readonly structuredOutput?: StructuredOutputConfig
 	readonly tools: ToolManager
 	readonly allowedTools?: string[]
+	/** The minimal context level omits tool discovery from both system and request context. */
+	readonly showDeferredToolContext?: boolean
 	readonly recorder: TurnRecorder
 	readonly toolExecutor: ToolExecutor
 	readonly guard: GuardCoordinator
@@ -141,6 +143,8 @@ export interface IterationContext {
 	readonly onSteeringDelivered?: (text: string) => void
 	/** Exit notices for the turn's background jobs, drained into the next tool result. */
 	readonly jobNotices?: SteeringChannel
+	/** Acknowledge exit notices only after their text enters model context. */
+	readonly onJobNoticeDelivered?: () => void
 	/**
 	 * Background jobs the model said it is waiting on, which is the only kind
 	 * the loop holds a finishing run open for.

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

@@ -186,6 +186,7 @@ export async function* runToolReview(
 		// block must be answered by a `tool_result` with the same id, so a
 		// user message wedged between them is rejected by the provider. Same
 		// delivery a denial already uses, without the refusal.
+		let jobNoticeDelivered = false
 		for (const msg of attachRepeatNotice(
 			attachNotice(
 				attachSteering(batch.messages, ctx.steering, ctx.onSteeringDelivered),
@@ -194,12 +195,16 @@ export async function* runToolReview(
 				// The exits that text accounts for have now been read, so the
 				// record of them stops being pending work. Left standing, it
 				// buys the model a turn the next time any job queues a notice.
-				() => ctx.awaitedJobs?.noticesDelivered(),
+				() => {
+					ctx.awaitedJobs?.noticesDelivered()
+					jobNoticeDelivered = true
+				},
 			),
 			notices,
 		)) {
 			ctx.recorder.pushMessage(msg)
 		}
+		if (jobNoticeDelivered) ctx.onJobNoticeDelivered?.()
 		// The complete tool-result batch is already in history before host policy
 		// may react, so a replacement cannot split provider-required adjacency.
 		// Commit each accepted observation before entering the next one. A single

package/src/runtime/query/iteration/step-shaping.ts

@@ -38,6 +38,8 @@ export interface StepShaping {
 	readonly ctx: IterationContext
 	readonly latestUserMessage: () => UserMessage | undefined
 	readonly steps: () => readonly StepResult[]
+	/** Request-only contributions already rendered for this model step. */
+	readonly requestContextTokens?: number
 }
 
 export { stepContextMessage }
@@ -108,7 +110,13 @@ export function stepContext(
 			windowTokens: window.tokens,
 			remainingTokens: Math.max(
 				0,
-				Math.floor(window.tokens - measureContext(ctx).tokens - preparedTokens - responseReserve),
+				Math.floor(
+					window.tokens -
+						measureContext(ctx).tokens -
+						(shaping.requestContextTokens ?? 0) -
+						preparedTokens -
+						responseReserve,
+				),
 			),
 		},
 		steps: steps(),

package/src/store/index.ts

@@ -36,6 +36,7 @@ export {
 	slugifyMemoryName,
 } from './memory/naming.js'
 export type { MemoryContentRejection } from './memory/naming.js'
+export { MemoryRevisionConflictError } from './memory/revision.js'
 
 // Was that answer any good — recorded per message, durably, with
 // compare-and-set. Every consumer used to invent its own side table for the

package/src/store/memory/disk.ts

@@ -3,14 +3,15 @@ import { dirname, join, resolve } from 'node:path'
 import { NamzuError } from '../../types/errors/index.js'
 import type { MemoryId } from '../../types/ids/index.js'
 import type {
+	ConditionalMemoryStore,
 	CreateMemoryParams,
 	MemoryContent,
 	MemoryIndexEntry,
 	MemoryRecord,
 	MemorySearchParams,
 	MemorySearchResult,
-	MemoryStore,
 	UpdateMemoryParams,
+	VersionedMemoryRecord,
 } from '../../types/memory/index.js'
 import { assertMemoryStatus, isMemoryType } from '../../types/memory/index.js'
 import { generateMemoryId, isEntityId } from '../../utils/id.js'
@@ -18,7 +19,7 @@ import { SCOPE_ATTRIBUTE } from '../../utils/log/types.js'
 import { type Logger, resolveLogger } from '../../utils/logger.js'
 import { DiskRecordStore } from '../kv/record-store.js'
 import { SCHEMA_VERSION_KEY, defineSchema } from '../schema.js'
-import { InMemoryMemoryIndex, searchMemoryEntries } from './index.js'
+import { InMemoryMemoryIndex, searchMemoryEntries, selectMemorySearchCandidates } from './index.js'
 import {
 	MemoryNameConflictError,
 	assertOptionalMemoryFields,
@@ -31,6 +32,7 @@ import {
 	acquireMemoryOperationLock,
 	validateMemoryLockTimeout,
 } from './operation-lock.js'
+import { MemoryRevisionConflictError, assertMemoryRevision, memoryRevision } from './revision.js'
 
 /**
  * This store's on-disk format, versioned as a unit — which is how a
@@ -181,7 +183,7 @@ export interface DiskMemoryStoreConfig {
 	lockTimeoutMs?: number
 }
 
-export class DiskMemoryStore implements MemoryStore {
+export class DiskMemoryStore implements ConditionalMemoryStore {
 	private readonly baseDir: string
 	private readonly log: Logger
 	private readonly lockTimeoutMs: number
@@ -355,18 +357,54 @@ export class DiskMemoryStore implements MemoryStore {
 		})
 	}
 
+	async getVersionedRecord(id: MemoryId): Promise<VersionedMemoryRecord | undefined> {
+		return this.withAuthoritativeIndex(async (location) => {
+			assertStorageMemoryId(id, (reason) => invalidContent(id, reason, { field: 'id' }))
+			const entry = this.index.getEntry(id)
+			if (!entry) return undefined
+			const record = structuredClone({ entry, content: await this.readContent(location, id) })
+			return { ...record, revision: memoryRevision(record) }
+		})
+	}
+
 	async update(id: MemoryId, updates: UpdateMemoryParams): Promise<MemoryIndexEntry | undefined> {
+		return this.updateInternal(id, updates)
+	}
+
+	async updateIfRevision(
+		id: MemoryId,
+		updates: UpdateMemoryParams,
+		expectedRevision: string,
+	): Promise<MemoryIndexEntry> {
+		const updated = await this.updateInternal(id, updates, expectedRevision)
+		if (!updated) throw new MemoryRevisionConflictError(id)
+		return updated
+	}
+
+	private async updateInternal(
+		id: MemoryId,
+		updates: UpdateMemoryParams,
+		expectedRevision?: string,
+	): Promise<MemoryIndexEntry | undefined> {
 		if (updates.status !== undefined) assertMemoryStatus(updates.status)
 		assertOptionalMemoryFields(updates)
 		return this.withAuthoritativeIndex(async (location) => {
 			assertStorageMemoryId(id, (reason) => invalidContent(id, reason, { field: 'id' }))
 			const existing = this.index.getEntry(id)
+			const existingContent = existing ? await this.readContent(location, id) : undefined
+			if (expectedRevision !== undefined) {
+				assertMemoryRevision(
+					id,
+					existing && existingContent ? { entry: existing, content: existingContent } : undefined,
+					expectedRevision,
+				)
+			}
 			if (!existing) return undefined
 			if (updates.name !== undefined) {
 				const holder = nameHolder(this.index.allEntries(), updates.name, id)
 				if (holder) throw new MemoryNameConflictError(updates.name, holder.id)
 			}
-			const existingContent = await this.readContent(location, id)
+			if (!existingContent) invalidContent(id, 'the indexed content record is missing')
 			const updated: MemoryIndexEntry = withOptionalFields(
 				{
 					...existing,
@@ -403,9 +441,27 @@ export class DiskMemoryStore implements MemoryStore {
 	}
 
 	async delete(id: MemoryId): Promise<boolean> {
+		return this.deleteInternal(id)
+	}
+
+	async deleteIfRevision(id: MemoryId, expectedRevision: string): Promise<void> {
+		const deleted = await this.deleteInternal(id, expectedRevision)
+		if (!deleted) throw new MemoryRevisionConflictError(id)
+	}
+
+	private async deleteInternal(id: MemoryId, expectedRevision?: string): Promise<boolean> {
 		return this.withAuthoritativeIndex(async (location) => {
 			assertStorageMemoryId(id, (reason) => invalidContent(id, reason, { field: 'id' }))
-			if (!this.index.getEntry(id)) return false
+			const entry = this.index.getEntry(id)
+			if (expectedRevision !== undefined) {
+				const content = entry ? await this.readContent(location, id) : undefined
+				assertMemoryRevision(
+					id,
+					entry && content ? { entry, content } : undefined,
+					expectedRevision,
+				)
+			}
+			if (!entry) return false
 
 			try {
 				await unlink(this.contentPath(location, id))
@@ -432,12 +488,31 @@ export class DiskMemoryStore implements MemoryStore {
 				query: undefined,
 				limit: undefined,
 				requiredIdentifiers: undefined,
+				maxScanned: undefined,
+				scanOffset: undefined,
 			})
+			const selection = selectMemorySearchCandidates(candidates.entries, params)
 			const contents = new Map<MemoryId, string>()
-			for (const entry of candidates.entries) {
+			for (const entry of selection.entries) {
 				contents.set(entry.id, (await this.readContent(location, entry.id)).content)
 			}
-			return searchMemoryEntries(candidates.entries, params, (id) => contents.get(id) ?? '')
+			const matched = searchMemoryEntries(
+				selection.entries,
+				{ ...params, maxScanned: undefined, scanOffset: undefined },
+				(id) => contents.get(id) ?? '',
+			)
+			return {
+				...matched,
+				...(params.maxScanned !== undefined || params.scanOffset !== undefined
+					? {
+							truncated: selection.truncated,
+							scannedCount: selection.scannedCount,
+							...(selection.nextScanOffset !== undefined
+								? { nextScanOffset: selection.nextScanOffset }
+								: {}),
+						}
+					: {}),
+			}
 		})
 	}
 

package/src/store/memory/index.ts

@@ -26,6 +26,56 @@ export function matchesMemoryIdentifier(text: string, identifiers: ReadonlySet<s
 	return false
 }
 
+interface MemoryScanSelection {
+	readonly entries: readonly MemoryIndexEntry[]
+	readonly truncated: boolean
+	readonly scannedCount: number
+	readonly nextScanOffset?: number
+}
+
+/** Select a bounded, resumable snapshot of indexed candidates before reading any bodies. */
+export function selectMemorySearchCandidates(
+	entries: readonly MemoryIndexEntry[],
+	params: MemorySearchParams,
+): MemoryScanSelection {
+	if (
+		params.maxScanned !== undefined &&
+		(!Number.isSafeInteger(params.maxScanned) || params.maxScanned < 1)
+	) {
+		throw new RangeError('maxScanned must be a positive safe integer')
+	}
+	if (
+		params.scanOffset !== undefined &&
+		(!Number.isSafeInteger(params.scanOffset) || params.scanOffset < 0)
+	) {
+		throw new RangeError('scanOffset must be a nonnegative safe integer')
+	}
+	const query = terms(params.query ?? '')
+	if (params.query?.trim() && query.size === 0)
+		return { entries: [], truncated: false, scannedCount: 0 }
+	const bodySearch =
+		query.size > 0 ||
+		Boolean(params.requiredIdentifiers?.length) ||
+		params.maxScanned !== undefined ||
+		params.scanOffset !== undefined
+	if (!bodySearch) return { entries, truncated: false, scannedCount: 0 }
+	const ordered = [...entries].sort(
+		(a, b) => b.updatedAt - a.updatedAt || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0),
+	)
+	const start = params.scanOffset ?? 0
+	const selected = ordered.slice(
+		start,
+		params.maxScanned === undefined ? undefined : start + params.maxScanned,
+	)
+	const next = start + selected.length
+	return {
+		entries: selected,
+		truncated: next < ordered.length,
+		scannedCount: selected.length,
+		...(next < ordered.length ? { nextScanOffset: next } : {}),
+	}
+}
+
 /** Shared lexical ranking; a caller-owned index can omit body content. */
 export function searchMemoryEntries(
 	entries: readonly MemoryIndexEntry[],
@@ -36,13 +86,13 @@ export function searchMemoryEntries(
 	const identifiers = new Set(
 		params.requiredIdentifiers?.map((id) => id.normalize('NFKC').toLowerCase()),
 	)
-	if (params.query?.trim() && query.size === 0) return { entries: [], totalCount: 0 }
-	const ranked = entries
-		.filter(
-			(entry) =>
-				(!params.status || entry.status === params.status) &&
-				(!params.tags?.length || params.tags.every((tag) => entry.tags.includes(tag))),
-		)
+	const candidates = entries.filter(
+		(entry) =>
+			(!params.status || entry.status === params.status) &&
+			(!params.tags?.length || params.tags.every((tag) => entry.tags.includes(tag))),
+	)
+	const selection = selectMemorySearchCandidates(candidates, params)
+	const ranked = selection.entries
 		.filter(
 			(entry) =>
 				!identifiers.size ||
@@ -79,6 +129,15 @@ export function searchMemoryEntries(
 	return {
 		entries: ranked.slice(0, params.limit ?? ranked.length).map(({ entry }) => entry),
 		totalCount: ranked.length,
+		...(params.maxScanned !== undefined || params.scanOffset !== undefined
+			? {
+					truncated: selection.truncated,
+					scannedCount: selection.scannedCount,
+					...(selection.nextScanOffset !== undefined
+						? { nextScanOffset: selection.nextScanOffset }
+						: {}),
+				}
+			: {}),
 	}
 }