@namzu/sdk 53.1.0 → 53.2.0

package/src/manager/agent/lifecycle.ts

@@ -23,6 +23,11 @@ import type {
 	AgentLifecycleEvent,
 	AgentLifecycleListener,
 } from '../../types/agent/lifecycle-event.js'
+import type {
+	RestoreChildOptions,
+	RestoreChildRefusal,
+	RestoreChildResult,
+} from '../../types/agent/manager.js'
 import type {
 	AgentManagerConfig,
 	AgentTask,
@@ -53,7 +58,12 @@ import { type Logger, resolveLogger } from '../../utils/logger.js'
 import { requireOpenProject } from '../project/lifecycle.js'
 import { type TopicManagerDependency, resolveTopicManager } from '../topic/dependency.js'
 import type { TopicManager } from '../topic/lifecycle.js'
-import { registerChildSessionLog, writeChildSessionMeta } from './child-session.js'
+import {
+	childSessionEnded,
+	readChildSessionMeta,
+	registerChildSessionLog,
+	writeChildSessionMeta,
+} from './child-session.js'
 
 /**
  * Dependencies threaded into {@link AgentManager}. Phase 6 promoted the
@@ -155,6 +165,7 @@ interface ChildSpawnRecord {
 		readonly toolCallId: string
 		readonly agentType: string
 		readonly description: string
+		readonly continuation?: NonNullable<ChildSessionMeta['continuation']>
 	}
 	/** Removes the child's log from the process-local lookup. */
 	releaseLog?: () => void
@@ -1236,6 +1247,7 @@ export class AgentManager {
 			description: placement.description,
 			status: 'running',
 			createdAt: placement.createdAt,
+			...(placement.continuation ? { continuation: placement.continuation } : {}),
 		}
 	}
 
@@ -1296,6 +1308,14 @@ export class AgentManager {
 			toolCallId: spawnToolCallId(taskId),
 			agentType: options.agentId,
 			description: describeSpawn(options),
+			...(options.continuationProfile
+				? {
+						continuation: {
+							workspace: options.workspace?.mode === 'isolated' ? 'isolated' : 'shared',
+							profile: { ...options.continuationProfile },
+						},
+					}
+				: {}),
 		}
 		await writeChildSessionMeta(spawnRecord.placement.metaPath, this.childMeta(spawnRecord))
 		return DiskSessionLog.at(paths, {
@@ -1796,6 +1816,166 @@ export class AgentManager {
 		})
 	}
 
+	/**
+	 * Make a child saved by an earlier process continuable again.
+	 *
+	 * Reads the child's meta document and log from the project layout under the
+	 * invoking parent, checks they describe a settled, shared-workspace child of
+	 * this very parent session, then re-creates the in-memory session and edge
+	 * and the retained conversation that {@link provisionContinuation} requires.
+	 * It runs nothing; the caller continues the child with `sendMessage` and
+	 * `resumeSessionId`, so the invoking turn's authority, limits and review
+	 * channel apply exactly as for a child that finished in this process.
+	 */
+	async restoreChildConversation(
+		options: RestoreChildOptions,
+		context: AgentTaskContext,
+	): Promise<RestoreChildResult> {
+		const refuse = (reason: RestoreChildRefusal): RestoreChildResult => ({
+			status: 'refused',
+			reason,
+		})
+		const id = options.childSessionId
+		const retained = this.childConversations.get(id)
+		if (retained?.activeSubSessionId) return refuse('running')
+		const paths =
+			context.childStorage?.kind === 'disk' ? context.childStorage.paths : this.deps.paths
+		if (!paths) return refuse('no-layout')
+		const store = this.deps.sessionStore
+		if (store.supportsInvocationSummaries !== true || store.supportsOwnerVersionCas !== true)
+			return refuse('not-resumable')
+		const ancestry = await store.getAncestry(context.sessionId, context.tenantId)
+		const parentLocator: SessionLocator = {
+			sessionId: context.sessionId,
+			ancestors: ancestry.slice(0, -1),
+		}
+		let meta: ChildSessionMeta | null
+		try {
+			meta = await readChildSessionMeta(paths.subagentMeta(parentLocator, id))
+		} catch {
+			return refuse('not-saved')
+		}
+		if (!meta) return refuse('not-saved')
+		if (meta.sessionId !== id || meta.parentSessionId !== context.sessionId)
+			return refuse('foreign')
+		const continuation = meta.continuation
+		if (!continuation || continuation.workspace !== 'shared') return refuse('not-resumable')
+		const agentId = options.agentFor(continuation.profile)
+		if (agentId === undefined || !this.registry.has(agentId)) return refuse('not-resumable')
+		const log = retained?.log ?? DiskSessionLog.at(paths, { sessionId: id, ancestors: ancestry })
+		// The child's own log wins over its meta document: a child that never
+		// recorded the end of a turn died mid-turn, and what it did is unknown.
+		const ended = await childSessionEnded(log)
+		if (!ended) return refuse('unsettled')
+		if (ended.status === 'cancelled' || meta.status === 'cancelled') return refuse('stopped')
+		// A log written under another project or topic cannot be continued here:
+		// the child's turn would refuse to open it.
+		const started = await log.head()
+		if (started === null) return refuse('unsettled')
+		for await (const { record } of log.read({ mode: 'tolerant' })) {
+			if (record.type !== 'session_started') continue
+			if (record.projectId !== context.projectId || record.topicId !== context.topicId)
+				return refuse('foreign')
+			break
+		}
+		const placement = {
+			paths,
+			metaPath: paths.subagentMeta(parentLocator, id),
+			createdAt: meta.createdAt,
+			toolCallId: meta.toolCallId,
+			agentType: meta.agentType,
+			description: meta.description,
+			continuation,
+		}
+		const restored: RestoreChildResult = {
+			status: 'restored',
+			childSessionId: id,
+			agentId,
+			profile: continuation.profile,
+			description: meta.description,
+		}
+		if (retained) return restored
+		if (this.childConversations.size >= RETAINED_CHILD_CONVERSATION_CAP) {
+			const oldest = [...this.childConversations].find(([, value]) => !value.activeSubSessionId)
+			if (!oldest) return refuse('full')
+			this.childConversations.delete(oldest[0])
+		}
+		const childActor: ActorRef = {
+			kind: 'agent',
+			agentId,
+			tenantId: context.tenantId,
+			parentActor: context.parentActor,
+		}
+		let child = await store.getSession(id, context.tenantId)
+		let createdChild = false
+		let edge: Awaited<ReturnType<typeof store.createSubSession>> | undefined
+		let createdEdge = false
+		try {
+			if (child) {
+				// A store that outlived the process still holds the child and its edge.
+				if (
+					child.status === 'active' ||
+					child.status === 'archived' ||
+					child.status === 'locked' ||
+					child.projectId !== context.projectId ||
+					child.topicId !== context.topicId ||
+					child.currentActor?.kind !== 'agent' ||
+					child.currentActor.agentId !== agentId
+				)
+					return refuse('running')
+			} else {
+				child = await store.createSession(
+					{ id, topicId: context.topicId, projectId: context.projectId, currentActor: childActor },
+					context.tenantId,
+				)
+				createdChild = true
+			}
+			edge = (await store.getChildren(context.sessionId, context.tenantId)).find(
+				(candidate) => candidate.childSessionId === id,
+			)
+			if (!edge) {
+				edge = await store.createSubSession(
+					{
+						parentSessionId: context.sessionId,
+						childSessionId: id,
+						kind: 'agent_spawn',
+						spawnedBy: context.parentActor,
+						failureMode: 'delegate',
+						completionMode: 'summary_ref',
+					},
+					context.tenantId,
+				)
+				createdEdge = true
+			}
+		} catch (error) {
+			if (edge && createdEdge)
+				await store.deleteSubSession(edge.id, context.tenantId).catch(() => undefined)
+			if (child && createdChild)
+				await store.deleteSession(id, context.tenantId).catch(() => undefined)
+			throw error
+		}
+		this.childConversations.set(id, {
+			definition: this.registry.getOrThrow(agentId),
+			origin: {
+				subSessionId: edge.id,
+				childSessionId: id,
+				tenantId: context.tenantId,
+				parentSessionId: context.sessionId,
+				parentTurnId: meta.parentTurnId,
+				rootSessionId: meta.rootSessionId,
+				ancestry,
+				childDepth: meta.depth,
+				childOwnerVersion: child.ownerVersion,
+				placement,
+			},
+			topicId: context.topicId,
+			projectId: context.projectId,
+			cwd: resolve(options.workingDirectory),
+			log,
+		})
+		return restored
+	}
+
 	private releaseChildConversation(record: ChildSpawnRecord): void {
 		const conversation = this.childConversations.get(record.childSessionId)
 		if (conversation?.activeSubSessionId !== record.subSessionId) return

package/src/public-runtime.ts

@@ -1275,7 +1275,7 @@ export { compactNow, compactRegion } from './compaction/manual.js'
 // A host persisting manual compaction has to recognise the system message on
 // resume. Export the identity predicate rather than making every host copy the
 // marker string and eventually disagree with the writer.
-export { isCompactionMessage } from './compaction/summary.js'
+export { COMPACTION_RECOVERY_NOTE, isCompactionMessage } from './compaction/summary.js'
 export {
 	DEFAULT_SALIENCE_CONFIG,
 	DEFAULT_SALIENCE_WEIGHTS,
@@ -1639,6 +1639,7 @@ export {
 	createSessionEvidenceSource,
 	createSessionTextEvidenceSource,
 } from './store/evidence/disk.js'
+export { SessionEvidenceOffsetError } from './store/evidence/source-text.js'
 export {
 	classifyEvidenceSource,
 	EVIDENCE_RECORD_GUIDANCE,

package/src/runtime/query/executor.ts

@@ -17,6 +17,7 @@ import { sandboxShellSpawn, withoutBashStartup } from '../../tools/command-shell
 import { isAlwaysDestructive } from '../../tools/defineTool.js'
 import { createFileReadTracker } from '../../tools/file-read-tracker.js'
 import { pathOutsideRoots, toolRoots } from '../../tools/paths.js'
+import { resolveRetainedOutput } from '../../tools/retained-output.js'
 import type { ToolManager } from '../../toolsets/manager.js'
 import type { ToolSourceRef } from '../../toolsets/types.js'
 import type { ToolResultGuardrailSpec } from '../../types/guardrail/index.js'
@@ -81,6 +82,7 @@ import { ToolCallBudget, assertMaxToolCalls } from './tool-call-budget.js'
 import {
 	DEFAULT_MAX_TOOL_OUTPUT_CHARS,
 	DEFAULT_MAX_TOOL_OUTPUT_CHARS_PER_MESSAGE,
+	type RetainedOutputRoutes,
 	type ToolOutputBudgetResult,
 	applyToolOutputBudget,
 	describeDroppedContent,
@@ -635,6 +637,17 @@ export function deniedToolOutput(toolName: string, reason: string): string {
 }
 
 export class ToolExecutor {
+	/** The recovery routes this turn actually has, so a pointer never names a missing tool. */
+	private recoveryRoutes(): RetainedOutputRoutes {
+		const tools = this.config.tools
+		return {
+			read: tools.get('read') !== undefined,
+			conversation:
+				tools.get('search_conversation') !== undefined &&
+				tools.get('read_conversation') !== undefined,
+		}
+	}
+
 	private outputDirectory(): string | undefined {
 		return typeof this.config.toolOutputDir === 'function'
 			? this.config.toolOutputDir()
@@ -1079,7 +1092,11 @@ export class ToolExecutor {
 		) {
 			const value = input[tool.pathArgument]
 			if (typeof value === 'string') {
-				const outside = await pathOutsideRoots(toolRoots(this.config), value)
+				// This session's own retained output is not "outside": it is where the
+				// result that was cut told the model to look.
+				const retained =
+					tool.name === 'read' && (await resolveRetainedOutput(this.outputDirectory(), value))
+				const outside = retained ? undefined : await pathOutsideRoots(toolRoots(this.config), value)
 				if (outside !== undefined) outsidePaths = [outside]
 			}
 		}
@@ -1526,6 +1543,7 @@ export class ToolExecutor {
 			{
 				maxChars,
 				spillDir: this.outputDirectory(),
+				recoveryRoutes: this.recoveryRoutes(),
 				onError: (message) =>
 					this.log.warn('Failed to retain a tool output replaced for the message budget', {
 						[NAMZU.TURN_ID]: this.config.turnId,
@@ -1806,6 +1824,7 @@ export class ToolExecutor {
 			maxChars: this.config.maxToolOutputChars ?? DEFAULT_MAX_TOOL_OUTPUT_CHARS,
 			retainedPreviewChars: this.config.retainedToolPreviewChars,
 			spillDir: this.outputDirectory(),
+			recoveryRoutes: this.recoveryRoutes(),
 			onError: (message) =>
 				this.log.warn('Failed to spill oversized nested tool output', {
 					[NAMZU.TURN_ID]: this.config.turnId,
@@ -1901,6 +1920,9 @@ export class ToolExecutor {
 			...(this.config.additionalDirectories?.length
 				? { additionalDirectories: this.config.additionalDirectories }
 				: {}),
+			...(this.outputDirectory()
+				? { retainedOutputDirectory: this.outputDirectory() as string }
+				: {}),
 			abortSignal: this.config.abortSignal,
 			env: this.config.env,
 			log: (level, message) => this.log[level](message),
@@ -2287,6 +2309,7 @@ export class ToolExecutor {
 			maxChars: maxToolOutputChars,
 			retainedPreviewChars: this.config.retainedToolPreviewChars,
 			spillDir: this.outputDirectory(),
+			recoveryRoutes: this.recoveryRoutes(),
 			onError: (message) =>
 				this.log.warn('Failed to retain original tool output', {
 					[NAMZU.TURN_ID]: this.config.turnId,
@@ -3177,6 +3200,7 @@ export class ToolExecutor {
 						spillDir: this.outputDirectory()
 							? join(this.outputDirectory() as string, 'content')
 							: undefined,
+						recoveryRoutes: this.recoveryRoutes(),
 						onError: (message) =>
 							this.log.warn('Failed to spill oversized model tool content', {
 								[NAMZU.TURN_ID]: this.config.turnId,

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

@@ -13,7 +13,11 @@ import type { ContextReducer, ContextReduction } from '../../../../compaction/re
 import { createSlidingWindowReducer } from '../../../../compaction/reducer.js'
 import { findRetainedIndices } from '../../../../compaction/retention.js'
 import { serializeState } from '../../../../compaction/serializer.js'
-import { buildCompactionMessage, isCompactionMessage } from '../../../../compaction/summary.js'
+import {
+	COMPACTION_RECOVERY_NOTE,
+	buildCompactionMessage,
+	isCompactionMessage,
+} from '../../../../compaction/summary.js'
 import { estimateMessagesTokens } from '../../../../compaction/token-estimate.js'
 import { buildVerifiedSummaryWithBoundedProvider } from '../../../../compaction/verifier.js'
 import type { CompactionConfig } from '../../../../config/runtime.js'
@@ -999,7 +1003,14 @@ async function runCompactionCheckInner(
 		compactedContent = serializeState(manager.getState())
 	}
 
-	const compactionMessage = buildCompactionMessage(compactedContent)
+	// The pointer is only worth a line when both tools it names are mounted.
+	const mounted = new Set(ctx.tools?.listNames?.() ?? [])
+	const compactionMessage = buildCompactionMessage(
+		compactedContent,
+		mounted.has('search_conversation') && mounted.has('read_conversation')
+			? COMPACTION_RECOVERY_NOTE
+			: undefined,
+	)
 
 	// Drop a replaceable PRIOR `[COMPACTED CONTEXT]` summary from this turn's
 	// leading floor — `serializeState` is cumulative, so the new summary

package/src/runtime/query/tool-output-budget.ts

@@ -42,6 +42,58 @@ export const MESSAGE_BUDGET_PREVIEW_CHARS = 2_000
  */
 export const SPILL_MARKER = 'The full output was written to:'
 
+/**
+ * The recovery routes a host has mounted for a retained output. A pointer
+ * names only a tool that exists, so the same sentence is true wherever it is
+ * read: in the result, in the cleared placeholder that keeps it, and in a
+ * summary that quotes it.
+ */
+export interface RetainedOutputRoutes {
+	/** The `read` tool is mounted and may open this session's own retained files. */
+	readonly read?: boolean
+	/** `search_conversation` and `read_conversation` are both mounted. */
+	readonly conversation?: boolean
+}
+
+/** Opening of the sentence that follows the spill line; how a pointer is recognised. */
+export const RETAINED_OUTPUT_NOTE = 'This path identifies retained output, not the original input.'
+
+const REPLAY_WARNING =
+	'A fresh observation of the original input cannot recover its earlier contents. If recovery is unavailable, report the missing detail; do not replay the original action.'
+
+/**
+ * The one sentence that says how to get at a retained output. Without routes
+ * (an embedder that told the budget nothing) it keeps the neutral wording.
+ */
+export function describeRetainedOutputRecovery(routes?: RetainedOutputRoutes): string {
+	const read = routes?.read === true
+	const conversation = routes?.conversation === true
+	const how = [
+		read ? 'To read more of it, open this file with the read tool (offset and limit).' : '',
+		conversation
+			? read
+				? 'For anything else from earlier in this conversation, call search_conversation with a phrase from it, then read_conversation with the seq and part it returns.'
+				: 'To read more of it, call search_conversation with a phrase from it, then read_conversation with the seq and part it returns. The path is not a workspace file, so read and grep cannot open it.'
+			: '',
+	].filter(Boolean)
+	if (how.length === 0)
+		return `${RETAINED_OUTPUT_NOTE} Use the host-authorized retained-output recovery tools when available; the path does not grant filesystem access. ${REPLAY_WARNING}`
+	return [RETAINED_OUTPUT_NOTE, ...how, REPLAY_WARNING].join(' ')
+}
+
+/**
+ * The spill line and the recovery sentence under it, when `text` carries them.
+ * Whatever shortens a result keeps this pair, so the route survives.
+ */
+export function retainedOutputPointer(text: string): string | undefined {
+	// A tool may end its lines with \r\n or a bare \r; the pointer is one line either way.
+	const lines = text.split(/\r\n|\r|\n/)
+	const at = lines.findIndex((line) => line.startsWith(SPILL_MARKER))
+	if (at < 0) return undefined
+	const next = lines[at + 1]
+	return next?.startsWith(RETAINED_OUTPUT_NOTE) ? `${lines[at]}\n${next}` : (lines[at] as string)
+}
+
 /**
  * Share of the budget spent on the head. The rest goes to the tail.
  *
@@ -91,7 +143,7 @@ function boundedPreview(
 		'',
 	].join('\n')
 	const compactMiddle = '\n[... omitted ...]\n'
-	const spillLine = recovery.split('\n').find((line) => line.startsWith(SPILL_MARKER))
+	const spillLine = recovery.split(/\r\n|\r|\n/).find((line) => line.startsWith(SPILL_MARKER))
 	const compactRecovery = spillLine ? `${compactMiddle}${spillLine}\n` : compactMiddle
 	const middle =
 		detailedMiddle.length < maxChars
@@ -182,6 +234,8 @@ export interface ApplyToolOutputBudgetOptions {
 	 * middle-elided instead — degraded, but never unbounded.
 	 */
 	readonly spillDir?: string | undefined
+	/** Which recovery routes the host has mounted; see {@link describeRetainedOutputRecovery}. */
+	readonly recoveryRoutes?: RetainedOutputRoutes
 	readonly onError?: (message: string) => void
 }
 
@@ -189,8 +243,9 @@ export interface ApplyToolOutputBudgetOptions {
  * Bound a tool result to the model-visible budget.
  *
  * Retention keeps the original while bounding its model-visible preview.
- * The host owns the recovery route and its permissions; a spill path is not
- * proof that workspace read/grep tools can access it. Middle-elision is the
+ * The recovery sentence names only the routes the host says are mounted
+ * ({@link RetainedOutputRoutes}); a spill path alone is not proof that a
+ * workspace tool can open it. Middle-elision is the
  * fallback for a turn with no directory to write to.
  *
  * The preview keeps head AND tail because the two ends carry different
@@ -224,10 +279,9 @@ export function applyToolOutputBudget(opts: ApplyToolOutputBudgetOptions): ToolO
 
 	const spillPath = retained?.path
 	const recovery = spillPath
-		? [
-				`${SPILL_MARKER} ${spillPath}`,
-				'This path identifies retained output, not the original input. Use the host-authorized retained-output recovery tools when available; the path does not grant filesystem access. A fresh observation of the original input cannot recover its earlier contents. If recovery is unavailable, report the missing detail; do not replay the original action.',
-			].join('\n')
+		? [`${SPILL_MARKER} ${spillPath}`, describeRetainedOutputRecovery(opts.recoveryRoutes)].join(
+				'\n',
+			)
 		: 'The full output was not retained. Use a saved artifact or a read-only observation; do not repeat a state-changing action to recover its output.'
 	const requestedPreview = opts.retainedPreviewChars
 	// Separate the spill threshold from the cost of carrying its preview on every
@@ -358,11 +412,10 @@ export interface MessageBudgetReplacement {
 export interface FitResultsToMessageBudgetOptions {
 	readonly maxChars: number
 	readonly spillDir?: string | undefined
+	readonly recoveryRoutes?: RetainedOutputRoutes
 	readonly onError?: (message: string) => void
 }
 
-const SPILL_LINE = new RegExp(`^${SPILL_MARKER} .+$`, 'm')
-
 /**
  * Hold one assistant message's combined tool results under a cap.
  *
@@ -409,7 +462,7 @@ function previewForMessageBudget(
 	item: MessageBudgetItem,
 	opts: FitResultsToMessageBudgetOptions,
 ): MessageBudgetReplacement {
-	const spilledAt = SPILL_LINE.exec(item.output)?.[0]
+	const spilledAt = retainedOutputPointer(item.output)
 	if (spilledAt !== undefined) {
 		const output = [
 			safeHead(item.output, MESSAGE_BUDGET_PREVIEW_CHARS / 2),
@@ -420,7 +473,7 @@ function previewForMessageBudget(
 		return {
 			output,
 			originalLength: item.output.length,
-			spillPath: spilledAt.slice(SPILL_MARKER.length + 1),
+			spillPath: (spilledAt.split('\n')[0] as string).slice(SPILL_MARKER.length + 1),
 		}
 	}
 	const budgeted = applyToolOutputBudget({
@@ -430,6 +483,7 @@ function previewForMessageBudget(
 		output: item.output,
 		maxChars: MESSAGE_BUDGET_PREVIEW_CHARS,
 		spillDir: opts.spillDir,
+		...(opts.recoveryRoutes ? { recoveryRoutes: opts.recoveryRoutes } : {}),
 		...(opts.onError ? { onError: opts.onError } : {}),
 	})
 	return {

package/src/scheduler/local.ts

@@ -1,7 +1,11 @@
 import { GENAI } from '../constants/telemetry/index.js'
 import { taskFailed } from '../tools/coordinator/outcome.js'
 import type { AgentInput } from '../types/agent/base.js'
-import type { AgentManagerContract } from '../types/agent/manager.js'
+import type {
+	AgentManagerContract,
+	RestoreChildOptions,
+	RestoreChildResult,
+} from '../types/agent/manager.js'
 import type {
 	CreateTaskOptions,
 	SiblingFailurePolicy,
@@ -113,6 +117,9 @@ export class LocalTaskScheduler implements TaskScheduler {
 			{
 				agentId: options.agentId,
 				...(options.resumeSessionId ? { resumeSessionId: options.resumeSessionId } : {}),
+				...(options.continuationProfile
+					? { continuationProfile: options.continuationProfile }
+					: {}),
 				beforeStart: options.beforeStart,
 				...(options.workspace ? { workspace: options.workspace } : {}),
 				...(options.planId ? { planId: options.planId } : {}),
@@ -363,6 +370,12 @@ export class LocalTaskScheduler implements TaskScheduler {
 		await this.agentManager.continueTask(taskId, message)
 	}
 
+	async restoreChild(options: RestoreChildOptions): Promise<RestoreChildResult> {
+		if (!this.agentManager.restoreChildConversation)
+			return { status: 'refused', reason: 'no-layout' }
+		return this.agentManager.restoreChildConversation(options, this.taskContext)
+	}
+
 	cancelTask(taskId: TaskId, cause?: CancelCause): void {
 		this.agentManager.cancel(taskId, cause)
 	}

package/src/store/evidence/disk.ts

@@ -110,8 +110,9 @@ export interface EvidenceAnchor {
  * session log, or one turn of it. Closed by default (no active turn in scope);
  * snapshot mode also reads a session whose turn is running, without assuming
  * its writer is dead. The host owns authorization and the log's directory.
- * Changes to the log invalidate addresses; record and chunk digests detect
- * changed bytes. This is not a hostile filesystem sandbox.
+ * An address names a record by offset, length and digest and survives appends
+ * to the log; a replaced or rewritten log is refused and record and chunk
+ * digests detect changed bytes. This is not a hostile filesystem sandbox.
  */
 export function createSessionTextEvidenceSource(
 	options: SessionEvidenceSourceOptions,
@@ -261,9 +262,18 @@ function createSource(
 			if (!state.closed && consistency === 'closed') {
 				throw new Error('Evidence scope has an active turn; it is not closed.')
 			}
+			// The anchored prefix is verified here and again after the action. It is not
+			// part of the seal: the anchor moves with every record the writer appends, so
+			// binding it would void an address the moment the search call that returned
+			// it is itself recorded.
 			const anchorKey = anchor ? await verifyAnchor(handle, anchor) : undefined
+			// A session log only grows. An address names one record by offset, length and
+			// digest, and a read verifies all three against the bytes, so what must
+			// bind a seal is the file's identity, never its size or times: those change
+			// with every append and would void every address and cursor handed out a
+			// moment earlier, including one a search just returned.
 			const sourceKey = digest(
-				`session-v1:${consistency}:${mode}:${scopeKey}:${anchorKey ?? stamp(before)}`,
+				`session-v1:${consistency}:${mode}:${scopeKey}:${fileIdentity(before)}`,
 			)
 			const seal = evidenceSeal(state.first, sourceKey)
 			const value = await action(handle, size, seal, sourceKey, budget, !state.closed)
@@ -552,6 +562,21 @@ function createSource(
 	})
 }
 
+/**
+ * What names the log file across appends: device and inode, plus the creation
+ * time where the filesystem reports no inode (zero), so a replaced file still
+ * changes the identity there.
+ */
+function fileIdentity(stats: {
+	dev: number | bigint
+	ino: number | bigint
+	birthtimeMs: number
+}): string {
+	return Number(stats.ino) === 0
+		? `${stats.dev}:0:${stats.birthtimeMs}`
+		: `${stats.dev}:${stats.ino}`
+}
+
 /** The anchor record must still hold the bytes the writer vouched for. */
 async function verifyAnchor(handle: FileHandle, anchor: EvidenceAnchor): Promise<string> {
 	const bytes = await readBytes(handle, anchor.offset, anchor.length, {

package/src/store/evidence/source-text.ts

@@ -235,6 +235,28 @@ async function sourceText(
 	}
 }
 
+/**
+ * @experimental A read named a byte offset the retained text cannot start at.
+ * `inside_character` means the offset falls inside a multi-byte character (the
+ * character starts up to three bytes earlier); `past_end` means it lies beyond
+ * the text. Every other read failure (integrity, ownership, a changed source)
+ * is a plain `Error`, so a caller can recover from a bad position without
+ * treating a refusal as one.
+ */
+export class SessionEvidenceOffsetError extends Error {
+	constructor(
+		readonly code: 'inside_character' | 'past_end',
+		message: string,
+		/** Bytes of the retained text. */
+		readonly totalBytes: number,
+		/** Bytes this failed read was charged. */
+		readonly scannedBytes: number,
+	) {
+		super(message)
+		this.name = 'SessionEvidenceOffsetError'
+	}
+}
+
 export async function readTextPage(
 	source: TextSource,
 	scope: SessionEvidenceScope,
@@ -242,13 +264,27 @@ export async function readTextPage(
 	budget: EvidenceBudget,
 ): Promise<SessionTextEvidenceReadResult> {
 	const entry = source.entry
-	if (offset > source.bytes) throw new Error('Offset exceeds retained text.')
+	if (offset > source.bytes)
+		throw new SessionEvidenceOffsetError(
+			'past_end',
+			'Offset exceeds retained text.',
+			source.bytes,
+			budget.bytes,
+		)
 	const chunk = entry.spill
 		? Math.min(Math.floor(offset / EVIDENCE_CHUNK_BYTES), source.chunks - 1)
 		: 0
 	const window = await source.window(chunk)
-	if (offset < window.offset) throw new Error('Offset splits a UTF-8 character.')
+	const splits = () =>
+		new SessionEvidenceOffsetError(
+			'inside_character',
+			'Offset splits a UTF-8 character.',
+			source.bytes,
+			budget.bytes,
+		)
+	if (offset < window.offset) throw splits()
 	const bytes = window.bytes.subarray(offset - window.offset)
+	if (bytes.length && ((bytes[0] ?? 0) & 0xc0) === 0x80) throw splits()
 	let text = decode(utf8Page(bytes, 24_000))
 	if (text.length > 6000) {
 		let end = 6000

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

@@ -5,6 +5,7 @@ import type { ToolContext } from '../../types/tool/index.js'
 import type { ToolFacts } from '../../types/tool/presentation.js'
 import { defineTool } from '../defineTool.js'
 import { resolveWithinAnyReal, toolRoots } from '../paths.js'
+import { resolveRetainedOutput } from '../retained-output.js'
 import { looksBinary } from '../text-window.js'
 import { fingerprintContent } from './content-fingerprint.js'
 import { type RenderedRead, renderCappedRead } from './read-render.js'
@@ -71,8 +72,12 @@ export const ReadFileTool = defineTool({
 	},
 
 	async execute(input, context) {
+		// This session's own retained tool output lives on the host, outside the
+		// roots and outside any sandbox. It is read here, as a plain window of text,
+		// because the result that named it told the model to.
+		const retained = await resolveRetainedOutput(context.retainedOutputDirectory, input.path)
 		// Sandbox-aware: route through sandbox.readFile() when available
-		if (context.sandbox) {
+		if (context.sandbox && retained === undefined) {
 			const buffer = await context.sandbox.readFile(input.path)
 			const binaryGuidance = describeStructuredBinaryRead(input.path, buffer)
 			if (binaryGuidance) {
@@ -112,7 +117,7 @@ export const ReadFileTool = defineTool({
 			}
 		}
 
-		const filePath = await resolveWithinAnyReal(toolRoots(context), input.path)
+		const filePath = retained ?? (await resolveWithinAnyReal(toolRoots(context), input.path))
 		// Refused on the size alone, before the file is in memory, when no window
 		// was named: the cap exists so a huge file is never loaded to be refused.
 		if (input.readRange === undefined && input.limit === undefined) {