@namzu/sdk 62.6.1 → 62.8.0

package/dist/types/tool/presentation.d.ts

@@ -207,6 +207,12 @@ export type ToolFacts = {
     readonly reason: ToolFailureReason;
     /** What it was about: a path, or the tool's name for `unknown_tool`. */
     readonly subject?: string;
+    /**
+     * Why a refused call did not run, as one plain line the kernel wrote
+     * (a policy rule, the command guard). Absent when no reason was
+     * recorded; a host shows nothing for it rather than a guess.
+     */
+    readonly note?: string;
 };
 /** The same shapes, for what a call produced. */
 export type ToolResultView = ToolCallView;

package/dist/types/tool/presentation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"presentation.d.ts","sourceRoot":"","sources":["../../../src/types/tool/presentation.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"presentation.d.ts","sourceRoot":"","sources":["../../../src/types/tool/presentation.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namzu/sdk",
-  "version": "62.6.1",
+  "version": "62.8.0",
   "description": "Open-source AI kernel for TypeScript: runs an agent the way an operating system runs a process, with an identity and a budget, scheduled tool calls and checkpointed turns.",
   "license": "FSL-1.1-MIT",
   "engines": {

package/src/agents/QueryAgent.ts

@@ -40,6 +40,7 @@ const configRoutes = {
 	compactionSummaryRoute: 'query',
 	allowedTools: 'special',
 	toolResultGuardrails: 'query',
+	fileReadTracker: 'query',
 	deniedTools: 'special',
 	persona: 'query',
 	logger: 'special',
@@ -49,6 +50,8 @@ const configRoutes = {
 	speed: 'turn',
 	reasoning: 'turn',
 	completionAudit: 'turn',
+	maxHookRefusals: 'turn',
+	outcome: 'turn',
 	idempotencyKey: 'special',
 	projectId: 'special',
 	topicId: 'special',
@@ -75,6 +78,7 @@ const configRoutes = {
 	sandboxProvider: 'query',
 	sandboxTeardownTimeoutMs: 'query',
 	outsideRootAccess: 'query',
+	outsideRootRefusal: 'query',
 	sandboxEscape: 'query',
 	compactionConfig: 'query',
 	workingMemoryProvider: 'query',
@@ -273,6 +277,7 @@ export class QueryAgent extends AbstractAgent<QueryAgentConfig, QueryAgentResult
 			durationMs: Date.now() - startTime,
 			messages: turn.messages,
 			result: turn.result,
+			...(turn.outcome ? { outcome: turn.outcome } : {}),
 			structuredOutput: turn.structuredOutput,
 			lastError: turn.lastError,
 			toolCallCount,

package/src/agents/examples/SupervisorAgent.ts

@@ -512,6 +512,7 @@ export class SupervisorAgent extends AbstractAgent<SupervisorAgentConfig, Superv
 				durationMs: Date.now() - startTime,
 				messages: turn.messages,
 				result: turn.result,
+				...(turn.outcome ? { outcome: turn.outcome } : {}),
 				// `BaseAgentResult.structuredOutput` names "an archetype's result
 				// literal did not copy it" as a defect it was written to close.
 				// This literal still did not copy it, so the same defect was live

package/src/agents/explore.ts

@@ -27,6 +27,7 @@ export const EXPLORE_AGENT_PROMPT = [
 	'You are a read-only sub-agent dispatched to find things out: where something is defined, which files reference it, how a piece of code works, what a directory contains.',
 	'You cannot see the parent conversation — work only from the prompt you were given.',
 	'You have reading and searching tools only. You cannot edit, write or run commands, and you must not describe a change as made.',
-	'Search broadly first, then read what matters. Report file paths with line numbers, quote the relevant lines, and say plainly what you did not find.',
+	'Search broadly first, then read what matters. Report file paths with line numbers, quote the relevant lines, and say plainly what you did not find and what you did not read.',
+	'You are best at locating answers; prefer locating over auditing whole files, and say so when a task asks for more than you can cover.',
 	'End with a concise answer the parent can act on; do not ask the parent questions.',
 ].join('\n')

package/src/compaction/index.ts

@@ -79,6 +79,7 @@ export type { CompactionResult, CompactNowInput, CompactRegionInput } from './ma
 export {
 	COMPACTION_HEADER,
 	COMPACTION_RECOVERY_NOTE,
+	COMPACTION_RESUME_NOTE,
 	buildCompactionMessage,
 	isCompactionMessage,
 } from './summary.js'

package/src/compaction/model-summary.ts

@@ -13,7 +13,7 @@ import { classifyProviderError } from '../types/provider/errors.js'
 import type { LLMProvider } from '../types/provider/interface.js'
 import type { WorkingStateManager } from './manager.js'
 import { serializeState } from './serializer.js'
-import { isCompactionMessage } from './summary.js'
+import { isCompactionMessage, withoutClosingNotes } from './summary.js'
 import {
 	MAX_COMPACTION_INSTRUCTIONS_CHARS,
 	type UsageSink,
@@ -185,7 +185,7 @@ export function fitTranscript(entries: readonly string[], budget: number): strin
 /** The text of a prior summary without the restored files and skills that follow it. */
 export function summaryBodyOf(content: string): string {
 	const cut = content.indexOf('\n## Restored after compaction')
-	return (cut >= 0 ? content.slice(0, cut) : content).trim()
+	return withoutClosingNotes((cut >= 0 ? content.slice(0, cut) : content).trim())
 }
 
 /** Replaceable earlier summaries on the leading floor, oldest first. */

package/src/compaction/summary.ts

@@ -34,14 +34,42 @@ export function isCompactionMessage(content: string | null | undefined): boolean
 export const COMPACTION_RECOVERY_NOTE =
 	'Earlier output was cut from this summary. To get exact earlier text, call search_conversation, then read_conversation.'
 
+/**
+ * The closing instruction after every summary. It is written for the first
+ * request after a pass, when the model has only the summary and no memory of
+ * the steps it describes. Kept out of {@link COMPACTION_HEADER}, which prompt
+ * caching and the replace-in-place check both read byte for byte, and kept
+ * constant so the same summary always renders the same message.
+ */
+export const COMPACTION_RESUME_NOTE =
+	'Carry on from where this summary says the work stood, without asking the person to repeat it. Treat steps it marks done as done. Files may have changed or may not be shown in full, so read a file again before editing it. If it names something still running or waiting, check on that first.'
+
+/**
+ * `text` without any closing notes this module adds, however many are stacked.
+ * An earlier summary is handed to the next pass whole, and a model may repeat
+ * its ending; cutting them here keeps each message to one note.
+ */
+export function withoutClosingNotes(text: string): string {
+	let out = text.trimEnd()
+	for (;;) {
+		const next = [COMPACTION_RESUME_NOTE, COMPACTION_RECOVERY_NOTE].reduce(
+			(acc, note) => (acc.endsWith(note) ? acc.slice(0, -note.length).trimEnd() : acc),
+			out,
+		)
+		if (next === out) return out
+		out = next
+	}
+}
+
 /**
  * The summary, as the system message that replaces what it summarises.
- * `recoveryNote` is appended as its own paragraph.
+ * `recoveryNote` is appended as its own paragraph, then the resume note, which
+ * always closes the message.
  */
 export function buildCompactionMessage(body: string, recoveryNote?: string): Message {
 	return {
 		...createSystemMessage(
-			`${COMPACTION_HEADER}\n\n${body}${recoveryNote ? `\n\n${recoveryNote}` : ''}`,
+			`${COMPACTION_HEADER}\n\n${withoutClosingNotes(body)}${recoveryNote ? `\n\n${recoveryNote}` : ''}\n\n${COMPACTION_RESUME_NOTE}`,
 		),
 		source: { type: 'compaction-summary' },
 	}

package/src/config/runtime.ts

@@ -138,6 +138,21 @@ export const CompactionConfigSchema = z.object({
 	minToolResultCharsToClear: z.number().min(0).default(1_000),
 	/** Tools whose output is never cleared, by name. */
 	preserveToolResultsFrom: z.array(z.string()).optional(),
+	/**
+	 * Before the first request of a turn, clear the old, large tool results
+	 * when that saves at least `minSavedTokens` by the kernel's own estimate.
+	 * Meant for a host that knows the provider's prompt cache has expired since
+	 * the last request, when the whole prefix is paid for at full price anyway.
+	 * Off when absent. Keeps the newest `keepRecentToolResults` results, errors,
+	 * pinned (`retain`) messages and already cleared results, exactly as the
+	 * in-turn clear does, and records the originals as a `compaction_shed` event.
+	 */
+	clearStaleToolResultsAtStart: z
+		.object({
+			minSavedTokens: z.number().int().positive(),
+			keepRecentToolResults: z.number().int().min(0).optional(),
+		})
+		.optional(),
 
 	maxToolResults: z.number().int().positive().default(30),
 	maxListSize: z.number().int().positive().default(25),

package/src/execution/workflow/runtime.ts

@@ -1,6 +1,7 @@
 import { randomBytes } from 'node:crypto'
 import { cpus } from 'node:os'
 
+import type { TurnOutcome } from '../../types/session/outcome.js'
 import { encodeCodeValue } from '../code-runtime/json-value.js'
 import type { CodeFrame, CodeRuntime, HostCallResult } from '../code-runtime/types.js'
 import { WorkerCodeRuntime } from '../code-runtime/worker.js'
@@ -209,6 +210,7 @@ interface AgentRecord {
 		readonly childSessionId?: string
 	}
 	childSessionId?: string
+	outcome?: TurnOutcome
 }
 
 interface Waiter {
@@ -504,6 +506,7 @@ export class WorkflowRuntime {
 					? { interrupted: true as const }
 					: {}),
 				...(agent.childSessionId !== undefined ? { childSessionId: agent.childSessionId } : {}),
+				...(agent.outcome !== undefined ? { outcome: agent.outcome } : {}),
 			})
 			return { ok: true, value: { v: value, t: totalTokens() } }
 		}
@@ -516,6 +519,7 @@ export class WorkflowRuntime {
 			agent.tokens = count(outcome.tokens)
 			agent.toolCalls = count(outcome.toolCalls)
 			if (outcome.sessionId !== undefined) agent.childSessionId = outcome.sessionId
+			if (outcome.outcome !== undefined) agent.outcome = outcome.outcome
 			if (agent.userSkipped || outcome.state === 'skipped') {
 				return settle(agent, { state: 'done', skipped: true })
 			}

package/src/execution/workflow/types.ts

@@ -4,6 +4,8 @@
  * runtime schedules them. See `docs/sdk/workflows.md`.
  */
 
+import type { TurnOutcome } from '../../types/session/outcome.js'
+
 /** One phase declared in `meta.phases`. */
 export interface WorkflowPhaseMeta {
 	readonly title: string
@@ -55,6 +57,11 @@ export interface WorkflowAgentOutcome {
 	readonly error?: string
 	/** The id of the child session the host ran this agent in, recorded in the journal. */
 	readonly sessionId?: string
+	/**
+	 * The kernel's record of what the agent's turn changed and what checked it.
+	 * Written to the journal beside the outcome; the script never receives it.
+	 */
+	readonly outcome?: TurnOutcome
 }
 
 /**
@@ -245,6 +252,8 @@ export type WorkflowJournalRecord =
 			/** Where a cached result was first recorded. */
 			readonly resultFrom?: { readonly pass: number; readonly index: number }
 			readonly childSessionId?: string
+			/** What the agent's turn changed and what checked it; see `TurnOutcome`. */
+			readonly outcome?: TurnOutcome
 	  }
 	| { readonly type: 'log'; readonly at: number; readonly message: string }
 	| {

package/src/manager/agent/child-session.ts

@@ -1,6 +1,7 @@
 import { mkdir, readFile } from 'node:fs/promises'
 import { dirname } from 'node:path'
 import type { SessionLog, SessionRecordDraft } from '../../store/session-log/index.js'
+import { parseTurnOutcome } from '../../store/session-log/turn-outcome.js'
 import type { SessionId } from '../../types/ids/index.js'
 import { type ChildSessionMeta, ChildSessionMetaSchema } from '../../types/session/records.js'
 import { atomicWriteFile } from '../../utils/atomic-write.js'
@@ -56,6 +57,41 @@ export async function childSessionEnded(
 	return ended
 }
 
+/** `child_outcome_recorded`, as the parent's writer appends it. */
+export type ChildOutcomeRecordedDraft = Extract<
+	SessionRecordDraft,
+	{ type: 'child_outcome_recorded' }
+>
+
+/**
+ * The parent's `child_outcome_recorded` record for a child: the outcome record
+ * the child's last settled turn wrote in its own log. `null` when the child has
+ * no settled turn or that turn kept none, so a child whose outcome is unknown
+ * is never reported as having changed nothing. The parent's writer appends it
+ * just before the child's `child_session_ended`, with the same `turnId` rule.
+ */
+export async function childOutcomeRecorded(
+	childLog: SessionLog,
+): Promise<ChildOutcomeRecordedDraft | null> {
+	let written: { turnId: string; outcome: Readonly<Record<string, unknown>> } | undefined
+	let outcome: Readonly<Record<string, unknown>> | undefined
+	for await (const { record } of childLog.read({ mode: 'tolerant' })) {
+		if (record.type === 'turn_outcome_recorded') {
+			written = { turnId: record.turnId, outcome: record.outcome }
+		} else if (record.type === 'turn_completed' || record.type === 'turn_failed') {
+			// Only the turn that settled counts: an earlier turn's record does not carry over.
+			outcome = written?.turnId === record.turnId ? written.outcome : undefined
+		}
+	}
+	if (outcome === undefined || parseTurnOutcome(outcome) === undefined) return null
+	return {
+		type: 'child_outcome_recorded',
+		ignorable: true,
+		childSessionId: childLog.sessionId,
+		outcome,
+	}
+}
+
 /** A `<child-id>.meta.json` that belongs to another child or another parent. */
 export class ChildSessionMetaOwnerError extends Error {
 	override readonly name = 'ChildSessionMetaOwnerError'

package/src/manager/agent/lifecycle.ts

@@ -933,6 +933,15 @@ export class AgentManager {
 				childConfig.toolResultGuardrails = inheritedScreens
 			}
 
+			// A child of its own reader record over the family's authored ledger, so
+			// what the parent wrote is still "this session's" to a child that runs
+			// it, while what the child has read stays its own and a write by a
+			// sibling still makes its stale. See `BaseAgentConfig.fileReadTracker`.
+			const childTracker = options.configOverrides?.fileReadTracker?.forChild?.()
+			if (childTracker !== undefined) {
+				childConfig.fileReadTracker = childTracker
+			}
+
 			// Stamped after both branches, beside the screens and for the same
 			// reason: a `configBuilder` cannot forward a field it was never told
 			// about, and the bare-config branch builds its config by hand.

package/src/manager/session/turn-recorder.ts

@@ -7,6 +7,7 @@ import { NAMZU } from '../../constants/telemetry/index.js'
 import { resolveModelPricing } from '../../pricing/index.js'
 import type { SessionTokenBudget } from '../../store/budget/index.js'
 import type { SessionCheckpointStore } from '../../store/checkpoint/index.js'
+import { foldSessionLog } from '../../store/session-log/incremental.js'
 import {
 	type SessionLease,
 	type SessionLog,
@@ -24,6 +25,7 @@ import {
 	accumulateTokenUsage,
 	isTerminalStatus,
 	mergeTokenUsage,
+	promptSizeOf,
 } from '../../types/common/index.js'
 import { NamzuError } from '../../types/errors/index.js'
 import type { MessageId, SessionId, TenantId, TurnId } from '../../types/ids/index.js'
@@ -37,10 +39,12 @@ import {
 	isEphemeralEvent,
 } from '../../types/session/events.js'
 import type { ProjectId, TopicId } from '../../types/session/ids.js'
+import type { TurnOutcome } from '../../types/session/outcome.js'
 import type { SessionRecord } from '../../types/session/records.js'
 import type { StepResult } from '../../types/session/step.js'
 import type { StopReason } from '../../types/session/stop-reason.js'
 import {
+	type LiveTurnSettlement,
 	type Origin,
 	type Turn,
 	type TurnConfigSnapshot,
@@ -56,7 +60,7 @@ import {
 	accumulateUnpricedCost,
 } from '../../utils/cost.js'
 import { asCheckpointId, generateAuditEventId, generateMessageId } from '../../utils/id.js'
-import { childSessionEnded } from '../agent/child-session.js'
+import { childOutcomeRecorded, childSessionEnded } from '../agent/child-session.js'
 import { assertSessionLogAttribution } from './attribution.js'
 import { takeStreamedMessageIdentity } from './streamed-message-identity.js'
 
@@ -492,6 +496,12 @@ export class TurnRecorder {
 		this.#turn.abandonedJobIds = [...jobIds]
 	}
 
+	/** The turn's outcome record, set once as the loop ends; absent means none was kept. */
+	setOutcome(outcome: TurnOutcome | undefined): void {
+		if (outcome === undefined) delete this.#turn.outcome
+		else this.#turn.outcome = outcome
+	}
+
 	setSteps(steps: readonly StepResult[]): void {
 		this.#turn.steps = steps
 	}
@@ -527,7 +537,7 @@ export class TurnRecorder {
 	 */
 	recordTurnUsage(usage: TokenUsage, servedBy: PricingSubject): void {
 		this.accumulateUsage(usage, servedBy)
-		this.#lastPromptTokens = usage.promptTokens
+		this.#lastPromptTokens = promptSizeOf(usage)
 		this.#lastPromptMessageCount = this.#turn.messages.length
 	}
 
@@ -585,7 +595,7 @@ export class TurnRecorder {
 	}
 
 	/** The settlement a terminal record carries, from the turn as it stands. */
-	settlement(status: TurnSettlement['status']): TurnSettlement {
+	settlement(status: TurnSettlement['status']): LiveTurnSettlement {
 		const turn = this.getTurn()
 		const resultMessageId = this.#lastAssistantEntry()?.id
 		return {
@@ -600,6 +610,7 @@ export class TurnRecorder {
 			...(turn.metadata.servingProvider ? { servingProvider: turn.metadata.servingProvider } : {}),
 			abandonedTaskIds: [...(turn.abandonedTaskIds ?? [])],
 			abandonedJobIds: [...(turn.abandonedJobIds ?? [])],
+			...(turn.outcome ? { outcome: turn.outcome } : {}),
 		}
 	}
 
@@ -892,6 +903,26 @@ export class TurnRecorder {
 		return this.#enqueue(() => this.#append(draft))
 	}
 
+	/**
+	 * Append a record a reader can do without (one flagged `ignorable`), in
+	 * order with every other record. A write that is refused resolves
+	 * `undefined` instead of failing the turn: the record is only the outcome's
+	 * account, and a log that really cannot be written fails the next record on
+	 * its own.
+	 */
+	appendIgnorableRecord(
+		draft: Parameters<SessionLog['append']>[1],
+	): Promise<SessionLogEntry | undefined> {
+		this.#syncMessages()
+		return this.#enqueue(async () => {
+			try {
+				return await this.#append(draft)
+			} catch {
+				return undefined
+			}
+		})
+	}
+
 	/**
 	 * Append a live event as its record. Resolves `undefined` for an event
 	 * the log does not hold: an ephemeral one, or one bound to a turn that is
@@ -925,6 +956,20 @@ export class TurnRecorder {
 		}
 		const draft = eventDraft(event, this.#turnOpen() ? this.turnId : undefined)
 		this.#syncMessages()
+		// The outcome is a record of its own, just ahead of the one that ends the
+		// turn, never a field of the settlement.
+		if (
+			(event.type === 'turn_completed' || event.type === 'turn_failed') &&
+			event.settlement.outcome !== undefined &&
+			this.#turnOpen()
+		) {
+			await this.appendIgnorableRecord({
+				type: 'turn_outcome_recorded',
+				turnId: this.turnId,
+				ignorable: true,
+				outcome: event.settlement.outcome as unknown as Readonly<Record<string, unknown>>,
+			})
+		}
 		if (
 			event.type === 'turn_paused' ||
 			event.type === 'turn_completed' ||
@@ -981,6 +1026,16 @@ export class TurnRecorder {
 		return this.#enqueue(async () => {
 			const ended = await childSessionEnded(childLog)
 			if (!ended) return undefined
+			// The child's outcome record goes in a record of its own just ahead of
+			// the end record; it is never a field of it.
+			const outcome = await childOutcomeRecorded(childLog)
+			if (outcome) {
+				try {
+					await this.#append(turnId ? { ...outcome, turnId } : outcome)
+				} catch {
+					// Only the outcome's account; the end record below fails on its own if the log is gone.
+				}
+			}
 			return this.#append(turnId ? { ...ended, turnId } : ended)
 		})
 	}
@@ -1357,6 +1412,11 @@ export function eventDraft(
 		...payload
 	} = event as SessionEvent & Record<string, unknown>
 	const draft = JSON.parse(JSON.stringify(payload)) as Record<string, unknown>
+	// The outcome rides the live settlement only; the log keeps it in its own record.
+	if (draft.settlement !== undefined && typeof draft.settlement === 'object') {
+		const { outcome: _outcome, ...settlement } = draft.settlement as Record<string, unknown>
+		draft.settlement = settlement
+	}
 	return { ...draft, ...(turnId ? { turnId } : {}) } as Parameters<SessionLog['append']>[1]
 }
 
@@ -1382,12 +1442,29 @@ export async function readFoldedHistory(
 	log: SessionLog,
 	options: { readonly throughSeq?: number } = {},
 ): Promise<RecordedMessage[]> {
+	// Folding the whole log is advanced from the last record the previous call
+	// folded, not redone from byte 0 on every turn. A fold to a seq is a
+	// different question and is read in full.
+	if (options.throughSeq === undefined) {
+		return foldSessionLog(log, {
+			name: 'folded-history',
+			mode: 'strict',
+			create: () => new SessionMessageFold(),
+			apply: (fold, entry) => fold.apply(entry.record as SessionRecord),
+			result: (fold) => recordedMessages(log, fold),
+		})
+	}
 	const fold = new SessionMessageFold()
-	for await (const entry of log.read(
-		options.throughSeq !== undefined ? { throughSeq: options.throughSeq } : {},
-	)) {
+	for await (const entry of log.read({ throughSeq: options.throughSeq })) {
 		fold.apply(entry.record as SessionRecord)
 	}
+	return recordedMessages(log, fold)
+}
+
+async function recordedMessages(
+	log: SessionLog,
+	fold: SessionMessageFold,
+): Promise<RecordedMessage[]> {
 	const out: RecordedMessage[] = []
 	const spilled = fold.spilledSummary
 	if (spilled) {
@@ -1404,9 +1481,10 @@ export async function readFoldedHistory(
 		}
 	}
 	for (const entry of fold.entries()) {
+		// A message from a shared fold is copied: the caller owns what it gets.
 		const message = entry.spill
 			? (JSON.parse(await log.readSpill(entry.spill as SpillRef)) as Message)
-			: entry.message
+			: structuredClone(entry.message)
 		out.push({
 			message: withMessageId(message, entry.messageId),
 			...(entry.messageId ? { messageId: entry.messageId } : {}),
@@ -1429,29 +1507,36 @@ export async function readFoldedHistory(
 export async function readEverRecordedMessages(
 	log: SessionLog,
 ): Promise<ReadonlyMap<MessageId, Message>> {
-	const latest = new Map<MessageId, { readonly content: Message; readonly spill?: SpillRef }>()
-	for await (const entry of log.read()) {
-		const record = entry.record as SessionRecord
-		if (record.type === 'message') {
-			latest.set(record.messageId, {
-				content: record.content,
-				...(record.spill ? { spill: record.spill } : {}),
-			})
-		} else if (record.type === 'message_replaced') {
-			latest.set(record.targetMessageId, {
-				content: record.content,
-				...(record.spill ? { spill: record.spill } : {}),
-			})
-		}
-	}
-	const resolved = new Map<MessageId, Message>()
-	for (const [id, entry] of latest) {
-		const content = entry.spill
-			? (JSON.parse(await log.readSpill(entry.spill)) as Message)
-			: entry.content
-		resolved.set(id, withMessageId(content, id))
-	}
-	return resolved
+	return foldSessionLog(log, {
+		name: 'ever-recorded-messages',
+		mode: 'strict',
+		create: () => new Map<MessageId, { readonly content: Message; readonly spill?: SpillRef }>(),
+		apply: (latest, entry) => {
+			const record = entry.record as SessionRecord
+			if (record.type === 'message') {
+				latest.set(record.messageId, {
+					content: record.content,
+					...(record.spill ? { spill: record.spill } : {}),
+				})
+			} else if (record.type === 'message_replaced') {
+				latest.set(record.targetMessageId, {
+					content: record.content,
+					...(record.spill ? { spill: record.spill } : {}),
+				})
+			}
+		},
+		result: async (latest) => {
+			const resolved = new Map<MessageId, Message>()
+			for (const [id, entry] of latest) {
+				// Copied: the map this is read from is shared with the next call.
+				const content = entry.spill
+					? (JSON.parse(await log.readSpill(entry.spill)) as Message)
+					: structuredClone(entry.content)
+				resolved.set(id, withMessageId(content, id))
+			}
+			return resolved
+		},
+	})
 }
 
 /**

package/src/pricing/rates.source.json

@@ -219,7 +219,7 @@
 			"verified": "2026-08-10",
 			"promptIncludesCacheReads": true,
 			"reportsCacheWrites": false,
-			"note": "Vendor list prices for text models, cached-input rate included. The driver hard-codes cacheWriteTokens to zero, so no write rate is carried. Embedding models are omitted (no output rate, and a chat turn never reaches one), as are models whose cached-input rate was not published alongside the others — an unestablished rate is left out rather than approximated, which is the rule this whole file follows.",
+			"note": "Vendor list prices for text models, cached-input rate included. The driver hard-codes cacheWriteTokens to zero, so no write rate is carried. Embedding models are omitted (no output rate, and a chat turn never reaches one), as are models whose cached-input rate was not published alongside the others — an unestablished rate is left out rather than approximated, which is the rule this whole file follows. gpt-6-astra has no row on purpose: the vendor prices it by input length (read 2026-11-11 on its pricing page, $10 in / $1 cached / $50 out up to 272,000 input tokens, $20 / $2 / $75 above), this table holds one rate per model, and either single rate would be wrong for the other half of requests, so its cost reports unknown.",
 			"models": [
 				{
 					"id": "gpt-5.6-sol",

package/src/prompt/coding-agent-doctrine.ts

@@ -81,10 +81,12 @@ export const CODING_AGENT_WORKING_DOCTRINE = `## How you work
  */
 export const CODING_AGENT_DELEGATION_DOCTRINE = `### Planning and delegating
 - A task list is optional. For work of three or more distinct steps — several files, several separate stages — you may keep one: exactly one step marked in progress at a time, each marked done when it is done rather than at the end, and the list cleared away once everything is done. Do not make one for a single inspect-edit-test cycle or a two-step job; a list of one or two items tells the user nothing. Keeping a list is not progress on the task itself.
-- When the \`Agent\` tool is available, delegate independent work through it and give each delegation a short, specific description; the user watches those descriptions, not the prompts. Brief each sub-agent with four things: the objective; what is out of bounds; which tools and sources to use; and the shape of the reply you want, such as a short summary with a file path for anything long. A fresh sub-agent starts with none of your context and returns what you ask for.
+- When the \`Agent\` tool is available, do small work, or work whose target you already know, yourself: a file you can name, one search, one edit. A fresh sub-agent starts with none of your context. Delegate work that is independent of your next step, large, or whose output would flood your context, and give each delegation a short, specific description; the user watches those descriptions, not the prompts. Brief each sub-agent with four things: the objective; what is out of bounds; which tools and sources to use; and the shape of the reply you want, such as a short summary with a file path for anything long.
+- You keep the understanding. Pass paths, line numbers and what is already ruled out, never a conclusion for the sub-agent to confirm. Once delegated, do not do the work again yourself.
+- A sub-agent's report is a claim, not a fact. Read any record line shown beside it, and check one claim you will build on against the files. Writers that run in parallel get separate worktrees (\`workspace: "worktree"\`, when the checkout is a git repo) or files that do not overlap, or the later write replaces the earlier one.
 - When the \`Agent\` tool lists a \`fork\` type, use \`subagent_type: "fork"\` when a side task would fill your context with output you will not need again, such as an open-ended survey. A fork starts from this conversation under your own instructions, so its prompt is only the directive: what to do and where its scope ends, without the background. Never write or guess what a fork will find before its report arrives. A fork cannot start forks of its own.
 - When delegated agents finish, tell the user what each one found in your next message. Their results reach you and not the user, so a result you do not pass on stays unseen.
-- Delegate lookups — where something is defined, which files reference it, how a module works — with \`subagent_type: "explore"\`: it has reading and searching tools only and never interrupts the user for permission. Reserve the default sub-agent for work that changes files or runs commands.
+- Use \`subagent_type: "explore"\` to locate something small — where it is defined, which files reference it; it only reads and searches, and never interrupts the user for permission. It is not for reviewing or auditing whole files. Reserve the default sub-agent for work that changes files or runs commands.
 
 ### Answering how work is going
 - When asked how things stand while background work runs, read the note about running work on your request first if the host gives you one, and add one status read from the tool that started an item only when the note does not say enough. The answer needs no waiting or polling and leaves the work running, because stopping or restarting an item to answer would lose what it has done.
@@ -114,7 +116,7 @@ When you have understood the task, reply with the plan: what you would change, i
  * doctrine did not already name.
  */
 export const CODING_AGENT_HYPERMODE_DOCTRINE = `### Hypermode
-This session has hypermode on: treat delegation through \`Agent\` as the default for substantive work, not the exception. Before doing multi-step work yourself, ask whether an independent piece of it — a lookup, a draft, a check — could run as its own delegation, and prefer delegating it when the answer is yes. This changes only how eagerly you reach for \`Agent\` on work you would otherwise do inline; it does not mount a roster or start any delegation by itself. Agents in the same phase are launched in the same response, each with \`run_in_background: true\` when you mean to wait for them together; a phase is never started one agent at a time.`
+This session has hypermode on: treat delegation through \`Agent\` as the default for substantive work, not the exception. Before doing multi-step work yourself, ask whether an independent piece of it — a lookup, a draft, a check — could run as its own delegation, and prefer delegating it when the answer is yes. This overrides the advice above to do small work yourself: while hypermode is on, delegate an independent piece even when it is small. It changes only how eagerly you reach for \`Agent\` on work you would otherwise do inline; it does not mount a roster or start any delegation by itself. Agents in the same phase are launched in the same response, each with \`run_in_background: true\` when you mean to wait for them together; a phase is never started one agent at a time.`
 
 /**
  * @deprecated Renamed {@link CODING_AGENT_HYPERMODE_DOCTRINE}; the mode it

package/src/provider/fallback.ts

@@ -37,6 +37,7 @@ import {
 	assertHostedWebSearchSupported,
 	assertNativeStructuredOutputSupported,
 } from './capabilities.js'
+import { wasGivenUpOnEarly } from './retry.js'
 
 /**
  * One member of the chain: a constructed provider, and the model to ask it for.
@@ -468,6 +469,7 @@ export function withProviderFallback(
 				}
 
 				const classified = classifyProviderError(err, member.provider.id)
+				const overloadedCount = wasGivenUpOnEarly(err)
 				cursor = next
 				log?.warn('Provider chain: falling over', {
 					'namzu.provider.from': member.provider.id,
@@ -496,7 +498,10 @@ export function withProviderFallback(
 						...(to.model !== undefined ? { toModel: to.model } : {}),
 						code: classified.code,
 						...(classified.status !== undefined ? { status: classified.status } : {}),
-						reason: classified.message,
+						reason:
+							overloadedCount !== undefined
+								? `Left after ${overloadedCount} overloaded answers in a row: ${classified.message}`
+								: classified.message,
 						...(fragments ? { restart: true } : {}),
 					},
 				}