@namzu/sdk 56.0.1 → 56.2.0

package/src/runtime/query/iteration/recorded-context.ts

@@ -0,0 +1,48 @@
+import { NAMZU } from '../../../constants/telemetry/index.js'
+import type { TurnRecorder } from '../../../manager/session/turn-recorder.js'
+import {
+	type Message,
+	createTurnContextEntry,
+	isTurnContextKey,
+	turnContextEntries,
+} from '../../../types/message/index.js'
+import type { RecordedContextItem } from '../../../types/session/index.js'
+import type { Logger } from '../../../utils/logger.js'
+
+/**
+ * Append what a step asked to have recorded, after whatever the history
+ * ends with.
+ *
+ * Only at the end: an entry slipped in ahead of the operator's message would
+ * put the live array out of log order, and the recorder would then write a
+ * whole compaction record to re-base it on every turn. An item adds nothing
+ * when its text is empty or equals the last entry under its key, so a step
+ * that offers the same text on every call records it once. Returns the
+ * entries it added, so a request built before they were added can carry them
+ * at the place they will hold.
+ */
+export function appendRecordedContext(
+	recorder: Pick<TurnRecorder, 'messages' | 'pushMessage' | 'turnId'>,
+	items: readonly RecordedContextItem[] | undefined,
+	log: Pick<Logger, 'warn'>,
+	at: Date = new Date(),
+): Message[] {
+	const appended: Message[] = []
+	for (const item of items ?? []) {
+		const text = item.text.trim()
+		if (text.length === 0) continue
+		if (!isTurnContextKey(item.key)) {
+			log.warn('A step recorded context under a key that is not a name; it was skipped', {
+				[NAMZU.TURN_ID]: recorder.turnId,
+				'namzu.runtime.key': String(item.key).slice(0, 80),
+			})
+			continue
+		}
+		const earlier = turnContextEntries(recorder.messages, item.key)
+		if (earlier.at(-1) === text) continue
+		const entry = createTurnContextEntry(item.key, text, at, { later: earlier.length > 0 })
+		recorder.pushMessage(entry)
+		appended.push(entry)
+	}
+	return appended
+}

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

@@ -1,6 +1,5 @@
 import { createRuntimeContextMessage } from '../../../types/message/index.js'
 import type { Message } from '../../../types/message/index.js'
-import { isOperatorUserMessage } from '../steering.js'
 
 /**
  * Request-only context, as the model reads it: a runtime-context user
@@ -18,167 +17,40 @@ export function stepContextMessage(content: string) {
 	)
 }
 
-/**
- * Put `blocks` in front of the operator's new message when that message is
- * what the model is about to answer, so the request is the last thing it
- * reads and the longest data comes before it. Only the reminders and other
- * request-only context may follow that message: once the turn has an
- * assistant or tool message after it, the blocks stay at the end of the
- * history, where a caching driver ends its breakpoint before them, so the
- * tool loop of a long turn is not re-read at full price on every step.
- *
- * Reminders and notices that follow the operator's message stay where they
- * are: they are short, and the edge after the request is where they are read.
- */
-export function placeBeforeLatestOperatorMessage(history: Message[], blocks: readonly Message[]) {
-	if (blocks.length === 0) return
-	let at = history.length
-	for (let i = history.length - 1; i >= 0; i--) {
-		const message = history[i] as Message
-		if (isOperatorUserMessage(message)) {
-			at = i
-			break
-		}
-		// A reply or a tool result after the message: the model has moved on.
-		if (message.role === 'assistant' || message.role === 'tool') break
-	}
-	history.splice(at, 0, ...blocks)
-}
-
-interface PlacedBlock {
-	readonly text: string
-	/** The operator message this block precedes, or the history message it follows. */
-	at: { readonly before: Message } | { readonly after: Message | undefined }
-}
-
 function textOf(message: Message): string {
 	return typeof message.content === 'string' ? message.content : JSON.stringify(message.content)
 }
 
-/** The operator message the model is about to answer, when there is one. */
-function pendingOperatorMessage(history: readonly Message[]): Message | undefined {
-	for (let i = history.length - 1; i >= 0; i--) {
-		const message = history[i] as Message
-		if (isOperatorUserMessage(message)) return message
-		if (message.role === 'assistant' || message.role === 'tool') return undefined
-	}
-	return undefined
-}
-
-/** A block whose own text says that a later one replaces it, under the name of what it reports. */
-export interface ReplaceableBlock {
-	readonly key: string
-	readonly message: Message
-}
-
-/** How many superseded versions of a replaceable block still go with the latest. */
-export const EARLIER_VERSIONS_KEPT = 2
-
-interface VersionedBlock extends PlacedBlock {
-	readonly message: Message
-}
-
 /**
- * Where a turn's request-only data sits, so it stays put from call to call.
- *
- * What a block says is the step's own business: a block it offers again with
- * the same text is the same block, and it keeps the place it first had; a
- * block it no longer offers is withdrawn, so corrected data never lingers.
- * A block seen for the first time goes before the operator's message when that
- * message is what the model is answering, and otherwise after the history of
- * that moment. So the requests of a turn share their opening up to the first
- * block that changed, and a caching driver keeps reading the same prefix
- * instead of re-reading the turn from the operator's message on.
+ * Put a request's own data into it: after everything the history holds, in
+ * the order offered, each distinct text once.
  *
- * A block that says of itself that a later one replaces it (the file
- * evidence) is never taken back. When its text changes, the earlier text stays
- * where it went and the new text follows the history of that moment, which is
- * how the block itself tells the model to read it; when it stops holding, a
- * short block says so. Only the latest version and the last
- * `EARLIER_VERSIONS_KEPT` before it are carried, and an earlier version whose
- * place a compaction rewrote is dropped, so the stale text stays small. Until
- * a version is dropped no request of the turn rewrites the one before it.
+ * Request-only data is what the model needs for this request alone (a note
+ * that something is unavailable, the work still running). It is re-placed on
+ * every call and always last, so the history before it never changes shape
+ * from one call to the next and a caching driver, which ends its breakpoint
+ * before the first such block, covers the whole history on every call. What
+ * the model should keep reading in later requests is recorded as turn context
+ * instead (`PrepareStepResult.recordedContext`), and the loop records what it
+ * learns about files and finished work the same way.
  *
- * One carry per turn. A position whose message has left the history (a
- * compaction rewrote it) is given up and the block follows the history.
+ * `request` is the projected history. `recorded` are entries the loop has just
+ * recorded: they join the history at the end of this call, so they go ahead
+ * of the first request-only block already in `request` (`tail` of them, at the
+ * end), which is where the next request will find them.
  */
-export class TurnContextCarry {
-	private placed = new Map<string, PlacedBlock>()
-	private readonly versions = new Map<string, VersionedBlock[]>()
-
-	/**
-	 * Put `blocks` and the `replaceable` ones into `request`, the projected copy
-	 * of `history` (same length and order). `end` is the last message of the
-	 * turn's own history. `retractions` says, per replaceable key, what to
-	 * write when an earlier block of that key no longer holds.
-	 */
-	place(
-		request: Message[],
-		history: readonly Message[],
-		end: Message | undefined,
-		blocks: readonly Message[],
-		replaceable: readonly ReplaceableBlock[] = [],
-		retractions: Readonly<Record<string, Message>> = {},
-	): void {
-		const index = (message: Message | undefined) =>
-			message ? history.lastIndexOf(message) : history.length - 1
-		const operator = pendingOperatorMessage(history)
-		const positionOf = (slot: PlacedBlock) =>
-			'before' in slot.at ? index(slot.at.before) : index(slot.at.after) + 1
-		const anchorOf = (slot: PlacedBlock) => ('before' in slot.at ? slot.at.before : slot.at.after)
-		const next = new Map<string, PlacedBlock>()
-		const inserts: { at: number; message: Message }[] = []
-		for (const message of blocks) {
-			const text = textOf(message)
-			if (next.has(text)) continue
-			let slot: PlacedBlock | undefined = this.placed.get(text)
-			if (slot) {
-				const anchor = anchorOf(slot)
-				if (anchor && index(anchor) < 0) slot = { text, at: { after: end } }
-			} else {
-				slot = { text, at: operator ? { before: operator } : { after: end } }
-			}
-			next.set(text, slot)
-			inserts.push({ at: positionOf(slot), message })
-		}
-		this.placed = next
-
-		const offered = new Map(replaceable.map((block) => [block.key, block.message]))
-		for (const key of new Set([...this.versions.keys(), ...offered.keys()])) {
-			const held = this.versions.get(key) ?? []
-			const wanted = offered.get(key) ?? retractions[key]
-			const last = held.at(-1)
-			if (wanted !== undefined && (last === undefined || last.text !== textOf(wanted)))
-				held.push({
-					text: textOf(wanted),
-					message: wanted,
-					// The first version goes where the other blocks go; a later one
-					// follows the history, after the one it replaces.
-					at: last === undefined && operator ? { before: operator } : { after: end },
-				})
-			// An earlier version whose place a compaction rewrote is given up: the
-			// request is rewritten at that point anyway, and stacking stale copies
-			// at the end would only add bulk. The latest version is never given up.
-			const kept = held.filter((version, i) => {
-				if (i === held.length - 1) return true
-				const anchor = anchorOf(version)
-				return !anchor || index(anchor) >= 0
-			})
-			// Only the latest and a few earlier versions are carried, so a long turn
-			// does not grow by a full copy per change.
-			kept.splice(0, Math.max(0, kept.length - (EARLIER_VERSIONS_KEPT + 1)))
-			this.versions.set(key, kept)
-			for (const version of kept) {
-				const anchor = anchorOf(version)
-				if (anchor && index(anchor) < 0) version.at = { after: end }
-				inserts.push({ at: positionOf(version), message: version.message })
-			}
-		}
-
-		// Back to front, so an earlier position is not shifted by a later one;
-		// blocks at one position keep the order they were offered in.
-		const order = inserts.map((entry, position) => ({ ...entry, position }))
-		order.sort((a, b) => b.at - a.at || b.position - a.position)
-		for (const entry of order) request.splice(entry.at, 0, entry.message)
+export function placeRequestContext(
+	request: Message[],
+	recorded: readonly Message[],
+	tail: number,
+	blocks: readonly Message[],
+): void {
+	if (recorded.length > 0) request.splice(request.length - tail, 0, ...recorded)
+	const seen = new Set<string>()
+	for (const message of blocks) {
+		const text = textOf(message)
+		if (seen.has(text)) continue
+		seen.add(text)
+		request.push(message)
 	}
 }

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

@@ -1,30 +1,30 @@
 import { resolveContextWindow } from '../../../compaction/context-window.js'
-import { estimateMessageTokens } from '../../../compaction/token-estimate.js'
+import { estimateMessageTokens, estimateTextTokens } from '../../../compaction/token-estimate.js'
 import { NAMZU } from '../../../constants/telemetry/index.js'
 import { renderSkillsSection } from '../../../persona/assembler.js'
+import { recordedOwnedTaskIds } from '../../../scheduler/completion-inbox.js'
 import { PreparationContextError } from '../../../turn/preparation-context-error.js'
 import {
 	type Message,
 	type UserMessage,
 	createSystemMessage,
+	turnContextEntries,
 } from '../../../types/message/index.js'
 import type { ToolChoice } from '../../../types/provider/chat.js'
 import type {
 	PrepareStepContext,
 	PrepareStepResult,
+	RecordedContextItem,
 	StepResult,
 	StepVeto,
 } from '../../../types/session/index.js'
 import type { Skill } from '../../../types/skills/index.js'
 import { toErrorMessage } from '../../../utils/error.js'
 import { createCallbackInference } from '../callback-inference.js'
+import { recordFileEvidence } from '../file-evidence-context.js'
 import { measureContext } from './phases/compaction.js'
 import type { IterationContext } from './phases/index.js'
-import {
-	type ReplaceableBlock,
-	placeBeforeLatestOperatorMessage,
-	stepContextMessage,
-} from './step-context.js'
+import { stepContextMessage } from './step-context.js'
 
 /**
  * How the next request is shaped: admission, preparation, and the context
@@ -48,57 +48,68 @@ export interface StepShaping {
 
 export { stepContextMessage }
 
-/** Derived after request projection; never accumulates in canonical history or replaces operator intent. */
-export function appendWorkContext(
-	shaping: StepShaping,
-	messages: Message[],
-	stepNumber: number,
-	prepared: PrepareStepResult,
-): void {
-	// Per-turn data goes in front of the operator's new message while that is
-	// what the model is answering, like the other blocks of request-only data.
-	placeBeforeLatestOperatorMessage(
-		messages,
-		workContextBlocks(shaping, messages, stepNumber, prepared).map((block) => block.message),
-	)
-}
-
-/** What the two work-context blocks report; each tells the model a later one replaces it. */
+/** The names the two kinds of recorded work context are filed under. */
 export const OWNED_WORK_KEY = 'owned-work'
 export const FILE_EVIDENCE_KEY = 'file-evidence'
 
+/** What the work context says for one request. */
+export interface WorkContext {
+	/** Facts that do not change once true, to be kept in the conversation. */
+	readonly recorded: RecordedContextItem[]
+	/** Facts about now, shown with this request only. */
+	readonly requestOnly: Message[]
+}
+
 /**
- * The work-context blocks for a request whose projected messages are
- * `messages`, each under the name of what it reports.
+ * The work context for a request whose projected messages are `messages`.
+ *
+ * Two kinds of fact, each where it belongs. What holds until something
+ * changes it, or never changes, is recorded: the file entries that are new or
+ * changed since the last record (with the paths whose entry no longer holds),
+ * and each owned task once it has finished. What is true only now, the tasks
+ * still running, goes with this request alone. Each text is admitted whole or
+ * not at all, within the room the request has left.
  */
-export function workContextBlocks(
+export function workContext(
 	shaping: StepShaping,
 	messages: readonly Message[],
 	stepNumber: number,
 	prepared: PrepareStepResult,
-): ReplaceableBlock[] {
+): WorkContext {
 	const { ctx } = shaping
+	const held = (key: string) => turnContextEntries(ctx.recorder.messages, key)
+	const inbox = ctx.completionInbox
 
-	const contributions = (
-		[
-			[OWNED_WORK_KEY, ctx.completionInbox?.describeOwnedWork()],
-			[FILE_EVIDENCE_KEY, ctx.toolExecutor.describeFileEvidence(messages)],
-		] as [string, string | undefined][]
-	).filter((entry): entry is [string, string] => Boolean(entry[1]))
-	if (contributions.length === 0) return []
-	const placed: ReplaceableBlock[] = []
+	const contributions: { content: string | undefined; key?: string }[] = [
+		{ content: inbox?.describeRunningWork() },
+		{
+			content: inbox?.describeSettledWork(recordedOwnedTaskIds(held(OWNED_WORK_KEY))),
+			key: OWNED_WORK_KEY,
+		},
+		{
+			content: recordFileEvidence(
+				ctx.toolExecutor.fileEvidenceEntries(messages),
+				held(FILE_EVIDENCE_KEY),
+			),
+			key: FILE_EVIDENCE_KEY,
+		},
+	]
+	const present = contributions.filter((entry) => Boolean(entry.content))
+	const work: WorkContext = { recorded: [], requestOnly: [] }
+	if (present.length === 0) return work
 	let room = stepContext(shaping, stepNumber, prepared).contextBudget?.remainingTokens ?? 0
 	// Leave room for the actual task; admit whole contributions, never dangling partial references.
-	if (room < 1_500) return []
-	for (const [key, content] of contributions) {
+	if (room < 1_500) return work
+	for (const { content, key } of present) {
 		if (!content || content.length > 8_000) continue
 		const message = stepContextMessage(content)
 		const tokens = estimateMessageTokens(message)
 		if (tokens > Math.min(2_000, room - 1_000)) continue
-		placed.push({ key, message })
+		if (key) work.recorded.push({ key, text: content })
+		else work.requestOnly.push(message)
 		room -= tokens
 	}
-	return placed
+	return work
 }
 
 export function stepContext(
@@ -122,7 +133,8 @@ export function stepContext(
 	const preamble = [prepared.system, skills].filter(Boolean).join('\n\n')
 	const preparedTokens =
 		(preamble ? estimateMessageTokens(createSystemMessage(preamble)) : 0) +
-		(prepared.context ? estimateMessageTokens(stepContextMessage(prepared.context)) : 0)
+		(prepared.context ? estimateMessageTokens(stepContextMessage(prepared.context)) : 0) +
+		(prepared.recordedContext ?? []).reduce((sum, item) => sum + estimateTextTokens(item.text), 0)
 	const responseReserve = Math.min(
 		prepared.maxResponseTokens ?? ctx.turnConfig.maxResponseTokens ?? Math.floor(window.tokens / 4),
 		Math.floor(window.tokens / 4),
@@ -180,6 +192,7 @@ export async function prepareStep(
 	model?: string
 	system?: string
 	context?: string
+	recordedContext?: readonly RecordedContextItem[]
 	skills?: readonly Skill[]
 	temperature?: number
 	maxResponseTokens?: number
@@ -206,7 +219,16 @@ export async function prepareStep(
 				...stepContext(shaping, stepNumber, result),
 				generateText: inference.generateText,
 			})
-			if (decided) result = { ...result, ...decided }
+			if (decided) {
+				// Recorded context adds up across stages: each stage files its own
+				// keys, and one stage must not erase what an earlier one recorded.
+				const recorded = [...(result.recordedContext ?? []), ...(decided.recordedContext ?? [])]
+				result = {
+					...result,
+					...decided,
+					...(recorded.length > 0 ? { recordedContext: recorded } : {}),
+				}
+			}
 			await selectContextModel(shaping, result.model ?? ctx.turnConfig.model)
 		} catch (err) {
 			// Skipped, and the rest still run: one broken concern must
@@ -242,6 +264,7 @@ export async function prepareStep(
 		model?: string
 		system?: string
 		context?: string
+		recordedContext?: readonly RecordedContextItem[]
 		skills?: readonly Skill[]
 		temperature?: number
 		maxResponseTokens?: number
@@ -279,6 +302,7 @@ export async function prepareStep(
 	if (result.model !== undefined) prepared.model = result.model
 	if (result.system !== undefined) prepared.system = result.system
 	if (result.context !== undefined) prepared.context = result.context
+	if (result.recordedContext !== undefined) prepared.recordedContext = result.recordedContext
 	if (result.skills !== undefined) prepared.skills = result.skills
 	if (result.temperature !== undefined) prepared.temperature = result.temperature
 	if (result.maxResponseTokens !== undefined) {

package/src/scheduler/completion-inbox.ts

@@ -31,10 +31,11 @@ const UNOWNED_BUFFER_LIMIT = 32
  * once.
  *
  * Unrelated to {@link UNOWNED_BUFFER_LIMIT} — that one bounds a memory leak;
- * this one bounds a request payload. `describeOwnedWork`'s output is admitted
- * into the request through `appendWorkContext`'s 8,000-character / ~2,000-token
- * gate (`runtime/query/iteration/index.ts`), and 16 tasks' worth of scheduler
- * state fits that with room to spare, including the overflow note below.
+ * this one bounds a request payload. What the inbox describes is admitted
+ * into the request through the work-context gate of 8,000 characters and
+ * about 2,000 tokens (`runtime/query/iteration/step-shaping.ts`), and 16
+ * tasks' worth of scheduler state fits that with room to spare, including the
+ * overflow note below.
  *
  * Running tasks fill these slots first — see {@link CompletionInbox.runningOwned}
  * — so a task still going is never bumped out by launch count alone the way a
@@ -43,6 +44,31 @@ const UNOWNED_BUFFER_LIMIT = 32
  */
 const OWNED_WORK_DISPLAY_LIMIT = 16
 
+/** What the model is told about owned work, wherever it is shown. */
+const OWNED_WORK_GUIDANCE =
+	'Each task gives its id (taskId), its state, how its turn ended (turnStatus), why it stopped (stopReason), and whether its result has reached this conversation (resultDelivery: delivered-to-history, or not-delivered). Result delivery is not proof that you answered the original request. Answer the latest operator message and complete the requested synthesis of available results unless the operator cancelled or changed that request. Reuse delivered results when sufficient; do not relaunch completed work. If a delivered result is no longer visible, retrieve it by task ID. A terminal state with a non-end_turn stop reason is not successful task completion. Do not repeat a synthesis already given.'
+
+/**
+ * The ids of the tasks that earlier recorded entries name, read from the
+ * entries' text, so what is recorded is known from the conversation alone.
+ */
+export function recordedOwnedTaskIds(entries: readonly string[]): Set<string> {
+	const ids = new Set<string>()
+	for (const entry of entries) {
+		for (const line of entry.split('\n')) {
+			if (!line.startsWith('{')) continue
+			try {
+				const parsed = JSON.parse(line) as { tasks?: { taskId?: unknown }[] }
+				for (const task of Array.isArray(parsed.tasks) ? parsed.tasks : [])
+					if (typeof task?.taskId === 'string') ids.add(task.taskId)
+			} catch {
+				// a line of the entry that is not the task list
+			}
+		}
+	}
+	return ids
+}
+
 export interface CompletionInboxOptions {
 	/** See {@link CompletionInbox.holdsTurnOpen}. Default `true`. */
 	readonly holdsTurnOpen?: boolean
@@ -451,6 +477,10 @@ export class CompletionInbox {
 	 * model once — but a RUNNING task that does not fit is: the preamble
 	 * says exactly how many, so the model never mistakes the cap for the
 	 * task having ended.
+	 *
+	 * @deprecated The query loop reads {@link describeRunningWork} for the
+	 * request and {@link describeSettledWork} for what it records. This single
+	 * snapshot is kept for hosts that read it themselves.
 	 */
 	describeOwnedWork(): string | undefined {
 		if (this.ours.size === 0) return
@@ -460,26 +490,63 @@ export class CompletionInbox {
 		const settled = [...this.settledOwned].reverse()
 		const shownSettled = settled.slice(0, OWNED_WORK_DISPLAY_LIMIT - shownRunning.length)
 		const ids = [...shownRunning, ...shownSettled]
-		const tasks = ids.map((taskId) => {
-			let handle = this.unheard.get(taskId)
-			try {
-				handle = this.gateway?.getTask(taskId) ?? handle
-			} catch {
-				// A broken observation must not block execution or invent a task state.
-			}
-			return {
-				taskId,
-				state: handle?.state ?? 'unknown',
-				...(handle?.result?.status ? { turnStatus: handle.result.status } : {}),
-				...(handle?.result?.stopReason ? { stopReason: handle.result.stopReason } : {}),
-				resultDelivery: this.claimed.has(taskId) ? 'delivered-to-history' : 'not-delivered',
-			}
-		})
+		const tasks = ids.map((taskId) => this.observe(taskId))
 		const overflow =
 			stillRunningNotShown > 0
 				? ` ${shownRunning.length} running tasks are shown below, and ${stillRunningNotShown} more still running.`
 				: ''
-		return `Owned delegated work (current scheduler observations; a later block with this heading replaces this one).${overflow} Result delivery is not proof that you answered the original request. Answer the latest operator message and complete the requested synthesis of available results unless the operator cancelled or changed that request. Reuse delivered results when sufficient; do not relaunch completed work. If a delivered result is no longer visible, retrieve it by task ID. A terminal state with a non-end_turn stop reason is not successful task completion. Do not repeat a synthesis already given.\n${JSON.stringify({ tasks, omitted: this.ours.size - ids.length })}`
+		return `Owned delegated work (current scheduler observations).${overflow} ${OWNED_WORK_GUIDANCE}\n${JSON.stringify({ tasks, omitted: this.ours.size - ids.length })}`
+	}
+
+	/**
+	 * The tasks this turn launched that are still going, for the request that
+	 * is about to be sent and for no other: running state changes, so it is
+	 * never recorded. Most recently launched first; a task that does not fit
+	 * is counted, so the model never mistakes the cap for the task having
+	 * ended. Undefined when nothing is running.
+	 */
+	describeRunningWork(): string | undefined {
+		if (this.runningOwned.size === 0) return
+		const running = [...this.runningOwned].reverse()
+		const shown = running.slice(0, OWNED_WORK_DISPLAY_LIMIT)
+		const notShown = running.length - shown.length
+		const overflow =
+			notShown > 0 ? ` ${shown.length} running tasks are shown below, and ${notShown} more.` : ''
+		return `Owned delegated work still running (current scheduler observations).${overflow} ${OWNED_WORK_GUIDANCE}\n${JSON.stringify({ tasks: shown.map((taskId) => this.observe(taskId)) })}`
+	}
+
+	/**
+	 * The tasks this turn launched that have reached a terminal state and are
+	 * not yet in `recorded` (the ids earlier entries name), oldest first, as
+	 * text to record. A terminal state does not change, so an entry is never
+	 * out of date and is written once per task. Tasks that settled and fell
+	 * out of the bounded list before they were recorded are counted. Undefined
+	 * when no task has newly settled.
+	 */
+	describeSettledWork(recorded: ReadonlySet<string>): string | undefined {
+		const fresh = this.settledOwned.filter((taskId) => !recorded.has(taskId))
+		if (fresh.length === 0) return
+		const accounted = new Set<string>([...this.runningOwned, ...fresh])
+		for (const taskId of recorded) if (this.ours.has(taskId as TaskId)) accounted.add(taskId)
+		const omitted = this.ours.size - accounted.size
+		const tasks = fresh.map((taskId) => this.observe(taskId))
+		return `Owned delegated work that has finished (as observed when this entry was written; a finished task does not change).${omitted > 0 ? ` ${omitted} more finished tasks are not listed.` : ''} ${OWNED_WORK_GUIDANCE}\n${JSON.stringify({ tasks })}`
+	}
+
+	private observe(taskId: TaskId) {
+		let handle = this.unheard.get(taskId)
+		try {
+			handle = this.gateway?.getTask(taskId) ?? handle
+		} catch {
+			// A broken observation must not block execution or invent a task state.
+		}
+		return {
+			taskId,
+			state: handle?.state ?? 'unknown',
+			...(handle?.result?.status ? { turnStatus: handle.result.status } : {}),
+			...(handle?.result?.stopReason ? { stopReason: handle.result.stopReason } : {}),
+			resultDelivery: this.claimed.has(taskId) ? 'delivered-to-history' : 'not-delivered',
+		}
 	}
 
 	/**

package/src/store/session-index/fts.ts

@@ -55,6 +55,11 @@ function shedTexts(messages: unknown): ShedText[] {
 		const message = plainObject(value)
 		if (!message || typeof message.role !== 'string' || !ROLES.has(message.role)) continue
 		const role = message.role
+		// A recorded context entry is the host's own earlier look at the
+		// repository, memory or evidence; indexing it would let a search find
+		// its own earlier answer as if it were something said in the session.
+		const source = plainObject(message.source)
+		if (source?.type === 'runtime-context' && source.kind === 'turn-context') continue
 		const tool = metadata[index]
 		if (typeof message.content === 'string') {
 			const summary =

package/src/test-support/file-evidence-held.ts

@@ -0,0 +1,27 @@
+import { type Message, turnContextEntries } from '../types/message/index.js'
+
+/**
+ * The file entries a request's history holds, as the model reads them: the
+ * recorded file-evidence entries replayed in order, an entry for a path
+ * replacing the earlier one and a path under "No longer holds" dropped.
+ * Undefined when none holds.
+ */
+export function heldFileEvidence(messages: readonly Message[] | undefined): unknown[] | undefined {
+	const held = new Map<string, unknown>()
+	for (const entry of turnContextEntries(messages ?? [], 'file-evidence')) {
+		for (const line of entry.split('\n')) {
+			if (line.startsWith('No longer holds: ')) {
+				for (const path of JSON.parse(line.slice('No longer holds: '.length)) as string[])
+					held.delete(path)
+			} else if (line.startsWith('[')) {
+				for (const item of JSON.parse(line) as { path: string }[]) held.set(item.path, item)
+			}
+		}
+	}
+	return held.size > 0 ? [...held.values()] : undefined
+}
+
+/** The recorded file-evidence entries of a history, oldest first. */
+export function fileEvidenceEntries(messages: readonly Message[] | undefined): readonly string[] {
+	return turnContextEntries(messages ?? [], 'file-evidence')
+}

package/src/test-support/request-only.ts

@@ -0,0 +1,19 @@
+import type { Message } from '../types/message/index.js'
+
+/** True for a block that rides one request only (a runtime-context message of kind `step-context`). */
+export function isRequestOnly(message: Message): boolean {
+	return (
+		message.role === 'user' &&
+		message.source?.type === 'runtime-context' &&
+		message.source.kind === 'step-context'
+	)
+}
+
+/**
+ * The part of a request that is history: every message but the request-only
+ * blocks. Each request begins with the history of the one before it, whatever
+ * the request-only blocks say.
+ */
+export function historyOf(messages: readonly Message[]): Message[] {
+	return messages.filter((message) => !isRequestOnly(message))
+}

package/src/tools/builtins/content-fingerprint.ts

@@ -33,3 +33,23 @@ export function staleFileError(path: string, operation: 'edit' | 'write' = 'edit
 export function unreadFileError(path: string, operation: 'edit' | 'write' = 'edit'): string {
 	return `${path} has not been read yet. Read it first, then redo the ${operation}. Nothing was written.`
 }
+
+/**
+ * Whether the file at `key` has moved on disk since the session read it.
+ *
+ * The read side of the same comparison `edit` and `write` make when they run,
+ * for asking before a reviewer is: `current` is the body now on disk. False
+ * when the host keeps no ledger, never read the path (a different refusal, and
+ * a read earlier in the same batch may still satisfy it), or cannot fingerprint.
+ */
+export function movedSinceRead(
+	tracker:
+		| { hasRead(key: string): boolean; fingerprint?(key: string): string | undefined }
+		| undefined,
+	key: string,
+	current: string,
+): boolean {
+	if (!tracker || !tracker.hasRead(key)) return false
+	const seen = tracker.fingerprint?.(key)
+	return seen !== undefined && seen !== fingerprintContent(current)
+}