@namzu/sdk 45.1.0 → 48.0.0

package/src/runtime/query/prepare-turn.ts

@@ -1,10 +1,16 @@
+import { isDeepStrictEqual } from 'node:util'
 import { drainQueuedMessages } from '../../agents/handle.js'
 import {
 	type ToolHistoryRepairReport,
 	repairToolMessageHistory,
 	toolHistoryRepairChanged,
 } from '../../compaction/dangling.js'
-import { type RecordedMessage, readFoldedHistory } from '../../manager/session/turn-recorder.js'
+import { assertSessionLogAttribution } from '../../manager/session/attribution.js'
+import {
+	type RecordedMessage,
+	readEverRecordedMessages,
+	readFoldedHistory,
+} from '../../manager/session/turn-recorder.js'
 import { resolveModelPricing } from '../../pricing/index.js'
 import { isCallerAbortError } from '../../provider/errors.js'
 import {
@@ -17,6 +23,7 @@ import { withProviderRetry } from '../../provider/retry.js'
 import { withTokenBudget } from '../../provider/token-budget.js'
 import { resolveAttachments } from '../../store/attachment/index.js'
 import type { SessionTokenBudget } from '../../store/budget/index.js'
+import type { SessionLog } from '../../store/session-log/index.js'
 import { NAMZU } from '../../telemetry/attributes.js'
 import type { SerializedSpanContext } from '../../telemetry/attributes.js'
 import type { TaskScheduler } from '../../types/agent/scheduler.js'
@@ -41,9 +48,11 @@ import { EventTranslator } from './events.js'
 import type { QueryParams } from './index.js'
 import { isCompactionMessage } from './iteration/phases/compaction.js'
 import { isWorkingMemoryMessage } from './iteration/phases/working-memory.js'
+import { PreludeSessionLease } from './prelude-lease.js'
 import {
 	awaitProjectInstructionCallback,
 	collapseProjectInstructionSnapshots,
+	isProjectInstructionMessage,
 	replaceProjectInstructionSnapshot,
 } from './project-instructions.js'
 import type { PromptCache } from './prompt-cache.js'
@@ -359,187 +368,207 @@ export async function prepareTurn(params: QueryParams): Promise<PreparedTurn> {
 		...(params.tokenBudgetStore ? { tokenBudgetStore: params.tokenBudgetStore } : {}),
 		...(params.workingDirectory ? { workingDirectory: params.workingDirectory } : {}),
 	})
-	const savedBudget = await savedBudgetReference(params, turnId, storage, selectedResumeState)
-	const budget = await resolveQueryBudget(params, turnId, storage.tokenBudget, savedBudget)
-	const log = TurnContextFactory.buildLogger({
-		agentName: params.agentName,
-		turnConfig,
+	// The preflight refuses an already foreign log before opening a budget or
+	// draining queued topic messages. Repeat after claiming the writer lease:
+	// another process may have opened a log that was empty at preflight time.
+	await assertSessionLogAttribution(storage.log, params)
+	const preludeLease = await PreludeSessionLease.acquire(
+		storage.log,
+		params.sessionId,
 		turnId,
-		...(params.parentSessionId ? { parentSessionId: params.parentSessionId } : {}),
-		sessionId: params.sessionId,
-		topicId: params.topicId,
-		projectId: params.projectId,
-		tenantId: params.tenantId,
-	})
-
-	// Every model call in the turn — the loop's turns, the forced-final
-	// summary, advisory and compaction side calls — goes through this one
-	// wrapped provider, so the retry policy cannot be bypassed by a code
-	// path that happens to hold the raw driver.
-	// The logger is passed on purpose: `withProviderRetry` guards every one
-	// of its warns behind `options.log`, and this is its only production
-	// call site — so without it the "failed, retrying" and "failed, giving
-	// up" lines were dead code and a backoff left no trace anywhere.
-	//
-	// With a chain declared, the same sentence holds two levels out. The idle
-	// watchdog is applied to each raw member, retry wraps that, and fallback
-	// wraps the members: `fallback(retry(idle(m0)), retry(idle(m1)), …)`. The
-	// idle layer cannot sit outside retry, because its timer would then count a
-	// legitimate backoff as provider silence. This order is not a
-	// preference. Assembled the other way round — which is what a host gets if
-	// it wraps its own chain and hands the result in, because this function
-	// would then wrap THAT in retry — an exhausted chain gets restarted from
-	// the head by the outer loop and a throttle on the last member is counted
-	// by two budgets. Building it here is what makes the order unspellable
-	// wrong.
-	const chain: readonly ProviderChainMember[] = [
-		{ provider: params.provider },
-		...(params.fallbackProviders ?? []),
-	]
-	assertCostIsAttributable(chain, params.pricing)
-	assertBudgetIsMeasurable(params)
-	const withRecovery = (provider: LLMProvider): LLMProvider => {
-		const withIdleBound = withStreamIdleTimeout(provider, {
-			idleTimeoutMs: streamIdleTimeoutMs,
-			log,
-		})
-		const metered = withTokenBudget(withIdleBound, budget)
-		return params.retry === false
-			? metered
-			: withProviderRetry(metered, {
-					config: params.retry,
-					log,
-					canRetry: () => budget.remaining > 0,
-				})
-	}
-	// Who is serving right now, for the turn RECORD rather than for the request.
-	//
-	// It starts at the head and moves only when the chain does, which is the
-	// whole of the truth because the cursor never rewinds. The turn cannot read
-	// this off `resilientProvider`: that wrapper reports the head's `id` on
-	// purpose, so asking it produces the declaration back — the defect this
-	// record exists to fix.
-	const serving: { current: ServingMember } = {
-		current: { index: 0, providerId: params.provider.id },
-	}
-	const resilientProvider = withProviderFallback(
-		chain.map((member) => ({
-			...member,
-			provider: withRecovery(member.provider),
-		})),
-		{
-			log,
-			canFallback: () => budget.remaining > 0,
-			onSwap: (to) => {
-				serving.current = to
-				// `ctx` is declared below and is initialized before anything can
-				// call the provider: this fires from inside a `chatStream`, and
-				// the first one is issued by the loop that `ctx` is built for.
-				ctx.recorder.setServingProvider(to.providerId)
-			},
-		},
+		params.lease,
 	)
+	let releaseOwnedLease = () => preludeLease.release()
+	try {
+		await preludeLease.assertCurrent()
+		await assertSessionLogAttribution(storage.log, params)
+		const savedBudget = await savedBudgetReference(params, turnId, storage, selectedResumeState)
+		const budget = await resolveQueryBudget(params, turnId, storage.tokenBudget, savedBudget)
+		const log = TurnContextFactory.buildLogger({
+			agentName: params.agentName,
+			turnConfig,
+			turnId,
+			...(params.parentSessionId ? { parentSessionId: params.parentSessionId } : {}),
+			sessionId: params.sessionId,
+			topicId: params.topicId,
+			projectId: params.projectId,
+			tenantId: params.tenantId,
+		})
 
-	// Asked ONCE, here, before the loop exists. Both readers are synchronous
-	// and hot, so this can never move inside the iteration — and a driver
-	// that rejects, or one that hangs until the turn is cancelled, must not
-	// take down a run the table could have served perfectly well. That is
-	// why the failure path is a swallow with a log rather than a throw: the
-	// window is an optimisation over a working default, not a prerequisite.
-	const providerContextWindow = await resolveProviderContextWindow(
-		resilientProvider,
-		turnConfig.model,
-		params.signal,
-		turnConfig.timeoutMs,
-		log,
-	)
-	const modelContextWindows = new Map<string, number | undefined>()
-	if (turnConfig.model) modelContextWindows.set(turnConfig.model, providerContextWindow)
-
-	// The mode this conversation was left in, when the turn config names none.
-	// Read once, before the loop exists, for the same reason the context
-	// window is: the executor's resolver is synchronous and hot.
-	//
-	// A store that throws is not a turn failure — the turn falls back to the
-	// config's answer, which is exactly what it did before this existed.
-	const topicState = params.topicStateStore
-		? await params.topicStateStore
-				.getState(params.topicId, params.tenantId)
-				.catch((err: unknown) => {
-					log.debug('Could not read the topic state; using the turn config', {
-						'namzu.topic.id': params.topicId,
-						'namzu.error.message': toErrorMessage(err),
-					})
-					return null
-				})
-		: null
-
-	// Whatever a host left for "the next turn", taken and cleared in one
-	// compare-and-set write. Prepended to the messages this turn starts from,
-	// so it is in the FIRST request rather than arriving a turn late.
-	//
-	// Cleared as it is read: a queue read and cleared separately re-delivers
-	// on a crash between the two, and "start with this" arriving twice is a
-	// different instruction from the one that was left.
-	const queuedForThisRun: readonly Message[] = params.topicStateStore
-		? await drainQueuedMessages(params.topicStateStore, params.topicId, params.tenantId).catch(
-				(err: unknown) => {
-					log.debug('Could not drain the topic queue; starting without it', {
-						'namzu.topic.id': params.topicId,
-						'namzu.error.message': toErrorMessage(err),
+		// Every model call in the turn — the loop's turns, the forced-final
+		// summary, advisory and compaction side calls — goes through this one
+		// wrapped provider, so the retry policy cannot be bypassed by a code
+		// path that happens to hold the raw driver.
+		// The logger is passed on purpose: `withProviderRetry` guards every one
+		// of its warns behind `options.log`, and this is its only production
+		// call site — so without it the "failed, retrying" and "failed, giving
+		// up" lines were dead code and a backoff left no trace anywhere.
+		//
+		// With a chain declared, the same sentence holds two levels out. The idle
+		// watchdog is applied to each raw member, retry wraps that, and fallback
+		// wraps the members: `fallback(retry(idle(m0)), retry(idle(m1)), …)`. The
+		// idle layer cannot sit outside retry, because its timer would then count a
+		// legitimate backoff as provider silence. This order is not a
+		// preference. Assembled the other way round — which is what a host gets if
+		// it wraps its own chain and hands the result in, because this function
+		// would then wrap THAT in retry — an exhausted chain gets restarted from
+		// the head by the outer loop and a throttle on the last member is counted
+		// by two budgets. Building it here is what makes the order unspellable
+		// wrong.
+		const chain: readonly ProviderChainMember[] = [
+			{ provider: params.provider },
+			...(params.fallbackProviders ?? []),
+		]
+		assertCostIsAttributable(chain, params.pricing)
+		assertBudgetIsMeasurable(params)
+		const withRecovery = (provider: LLMProvider): LLMProvider => {
+			const withIdleBound = withStreamIdleTimeout(provider, {
+				idleTimeoutMs: streamIdleTimeoutMs,
+				log,
+			})
+			const metered = withTokenBudget(withIdleBound, budget)
+			return params.retry === false
+				? metered
+				: withProviderRetry(metered, {
+						config: params.retry,
+						log,
+						canRetry: () => budget.remaining > 0,
 					})
-					return []
+		}
+		// Who is serving right now, for the turn RECORD rather than for the request.
+		//
+		// It starts at the head and moves only when the chain does, which is the
+		// whole of the truth because the cursor never rewinds. The turn cannot read
+		// this off `resilientProvider`: that wrapper reports the head's `id` on
+		// purpose, so asking it produces the declaration back — the defect this
+		// record exists to fix.
+		const serving: { current: ServingMember } = {
+			current: { index: 0, providerId: params.provider.id },
+		}
+		const resilientProvider = withProviderFallback(
+			chain.map((member) => ({
+				...member,
+				provider: withRecovery(member.provider),
+			})),
+			{
+				log,
+				canFallback: () => budget.remaining > 0,
+				onSwap: (to) => {
+					serving.current = to
+					// `ctx` is declared below and is initialized before anything can
+					// call the provider: this fires from inside a `chatStream`, and
+					// the first one is issued by the loop that `ctx` is built for.
+					ctx.recorder.setServingProvider(to.providerId)
 				},
-			)
-		: []
-
-	// One effective list, used everywhere the turn is seeded from. Three
-	// branches below push from it, and computing it at each would be three
-	// places to forget the queue.
-	//
-	// Stored attachments are resolved HERE, once, before the messages reach
-	// the turn record. Resolving later — at the provider boundary — would put
-	// refs in the durable transcript and in every checkpoint, and a turn
-	// resumed against a store that had since forgotten a ref would fail
-	// replaying its own history rather than at the moment somebody asked for
-	// the bytes. Every failure refuses: a message that silently lost its
-	// image is a model answering about a picture it never saw.
-	const ctx = TurnContextFactory.build({
-		budget,
-		...(topicState ? { topicPermissionMode: topicState.permissionMode } : {}),
-		...(params.permissionModeRef ? { permissionModeRef: params.permissionModeRef } : {}),
-		agentId: params.agentId,
-		agentName: params.agentName,
-		turnConfig,
-		provider: resilientProvider,
-		workingDirectory: params.workingDirectory,
-		pricing: params.pricing,
-		enableActivityTracking: params.enableActivityTracking,
-		signal: params.signal,
-		sessionId: params.sessionId,
-		topicId: params.topicId,
-		projectId: params.projectId,
-		tenantId: params.tenantId,
-		storage,
-		turnId,
-		...(params.parentSessionId ? { parentSessionId: params.parentSessionId } : {}),
-		...(params.parentTurnId ? { parentTurnId: params.parentTurnId } : {}),
-		...(params.depth !== undefined ? { depth: params.depth } : {}),
-		log,
-	})
+			},
+		)
 
-	// The writer lease, and `session_started` on an empty log. Everything
-	// from here to the end of the turn holds the lease, so a failure before
-	// the turn body owns it releases it.
-	await ctx.recorder.open({
-		...(params.lease ? { lease: params.lease } : {}),
-		session: {
-			cwd: ctx.cwd,
-			...(params.origin ? { origin: params.origin } : {}),
-			...(params.forkedFrom ? { forkedFrom: params.forkedFrom } : {}),
-		},
-	})
-	try {
+		// Asked ONCE, here, before the loop exists. Both readers are synchronous
+		// and hot, so this can never move inside the iteration — and a driver
+		// that rejects, or one that hangs until the turn is cancelled, must not
+		// take down a run the table could have served perfectly well. That is
+		// why the failure path is a swallow with a log rather than a throw: the
+		// window is an optimisation over a working default, not a prerequisite.
+		const providerContextWindow = await resolveProviderContextWindow(
+			resilientProvider,
+			turnConfig.model,
+			params.signal,
+			turnConfig.timeoutMs,
+			log,
+		)
+		const modelContextWindows = new Map<string, number | undefined>()
+		if (turnConfig.model) modelContextWindows.set(turnConfig.model, providerContextWindow)
+
+		// The mode this conversation was left in, when the turn config names none.
+		// Read once, before the loop exists, for the same reason the context
+		// window is: the executor's resolver is synchronous and hot.
+		//
+		// A store that throws is not a turn failure — the turn falls back to the
+		// config's answer, which is exactly what it did before this existed.
+		const topicState = params.topicStateStore
+			? await params.topicStateStore
+					.getState(params.topicId, params.tenantId)
+					.catch((err: unknown) => {
+						log.debug('Could not read the topic state; using the turn config', {
+							'namzu.topic.id': params.topicId,
+							'namzu.error.message': toErrorMessage(err),
+						})
+						return null
+					})
+			: null
+
+		// Whatever a host left for "the next turn", taken and cleared in one
+		// compare-and-set write. Prepended to the messages this turn starts from,
+		// so it is in the FIRST request rather than arriving a turn late.
+		//
+		// Cleared as it is read: a queue read and cleared separately re-delivers
+		// on a crash between the two, and "start with this" arriving twice is a
+		// different instruction from the one that was left.
+		await preludeLease.assertCurrent()
+		const queuedForThisRun: readonly Message[] = params.topicStateStore
+			? await drainQueuedMessages(params.topicStateStore, params.topicId, params.tenantId).catch(
+					(err: unknown) => {
+						log.debug('Could not drain the topic queue; starting without it', {
+							'namzu.topic.id': params.topicId,
+							'namzu.error.message': toErrorMessage(err),
+						})
+						return []
+					},
+				)
+			: []
+
+		// One effective list, used everywhere the turn is seeded from. Three
+		// branches below push from it, and computing it at each would be three
+		// places to forget the queue.
+		//
+		// Stored attachments are resolved HERE, once, before the messages reach
+		// the turn record. Resolving later — at the provider boundary — would put
+		// refs in the durable transcript and in every checkpoint, and a turn
+		// resumed against a store that had since forgotten a ref would fail
+		// replaying its own history rather than at the moment somebody asked for
+		// the bytes. Every failure refuses: a message that silently lost its
+		// image is a model answering about a picture it never saw.
+		const ctx = TurnContextFactory.build({
+			budget,
+			...(topicState ? { topicPermissionMode: topicState.permissionMode } : {}),
+			...(params.permissionModeRef ? { permissionModeRef: params.permissionModeRef } : {}),
+			agentId: params.agentId,
+			agentName: params.agentName,
+			turnConfig,
+			provider: resilientProvider,
+			workingDirectory: params.workingDirectory,
+			pricing: params.pricing,
+			enableActivityTracking: params.enableActivityTracking,
+			signal: params.signal,
+			sessionId: params.sessionId,
+			topicId: params.topicId,
+			projectId: params.projectId,
+			tenantId: params.tenantId,
+			storage,
+			turnId,
+			...(params.parentSessionId ? { parentSessionId: params.parentSessionId } : {}),
+			...(params.parentTurnId ? { parentTurnId: params.parentTurnId } : {}),
+			...(params.depth !== undefined ? { depth: params.depth } : {}),
+			log,
+		})
+
+		// The writer lease, and `session_started` on an empty log. Everything
+		// from here to the end of the turn holds the lease, so a failure before
+		// the turn body owns it releases it.
+		await ctx.recorder.open({
+			lease: await preludeLease.transfer(),
+			ownLease: preludeLease.ownsLease,
+			session: {
+				cwd: ctx.cwd,
+				...(params.origin ? { origin: params.origin } : {}),
+				...(params.forkedFrom ? { forkedFrom: params.forkedFrom } : {}),
+			},
+		})
+		releaseOwnedLease = async () => {
+			await preludeLease.stop()
+			await ctx.recorder.release()
+		}
+		await preludeLease.stop()
 		await assertTurnMayStart(params, turnId, storage, ctx)
 		// The session log is the conversation's source of truth. A new turn starts
 		// from its folded history, and `params.messages` is what this turn adds.
@@ -548,7 +577,14 @@ export async function prepareTurn(params: QueryParams): Promise<PreparedTurn> {
 		const history: RecordedMessage[] = params.resumeFromCheckpoint
 			? []
 			: await readFoldedHistory(storage.log)
-		const input = withoutRecordedPrefix(params.messages, history)
+		const input = params.resumeFromCheckpoint
+			? []
+			: await reconcileCallerMessages(
+					params.messages,
+					history,
+					storage.log,
+					params.continuationMode === true,
+				)
 		const seeded: Message[] = queuedForThisRun.length > 0 ? [...queuedForThisRun, ...input] : input
 		let resolvedInitialMessages: Message[]
 		let attachmentResolutionCancelled = false
@@ -577,9 +613,17 @@ export async function prepareTurn(params: QueryParams): Promise<PreparedTurn> {
 			const preparationSignal = params.signal ?? new AbortController().signal
 			let snapshot: UserMessage | null | undefined
 			try {
+				// `ProjectInstructionCallbackContext.messages` promises "the
+				// messages accepted before this callback starts" — the durable
+				// history this turn folds from the log, not only what THIS turn
+				// itself is contributing. Without the fold's own project-instruction
+				// snapshot (from an earlier turn of the SAME session) in view, a
+				// host that discovers a nested scope from a tool call could never
+				// re-derive which files to re-read on the next turn, once the
+				// message that named them was reconciled away as already durable.
 				const prepared = await awaitProjectInstructionCallback(preparationSignal, () =>
 					params.projectInstructionContext?.prepareInitialSnapshot?.({
-						messages: [...resolvedInitialMessages],
+						messages: [...history.map((entry) => entry.message), ...resolvedInitialMessages],
 						signal: preparationSignal,
 					}),
 				)
@@ -778,7 +822,10 @@ export async function prepareTurn(params: QueryParams): Promise<PreparedTurn> {
 			taskScheduler,
 		}
 	} catch (error) {
-		await ctx.recorder.release()
+		// Once open succeeds, the recorder normally releases this lease at the
+		// end of the turn. Preparation failures, including an open refusal,
+		// still belong to this prelude. A caller-supplied lease stays theirs.
+		if (preludeLease.ownsLease) await releaseOwnedLease().catch(() => undefined)
 		throw error
 	}
 }
@@ -794,7 +841,10 @@ async function savedBudgetReference(
 	selected: SelectedResumeState | undefined,
 ): Promise<SavedBudgetReference | undefined> {
 	if (selected?.budgetBinding) {
-		return { binding: selected.budgetBinding, accountId: selected.budgetBinding.accountId }
+		return {
+			binding: selected.budgetBinding,
+			accountId: selected.budgetBinding.accountId,
+		}
 	}
 	// A selected state carries only a durable binding. An account held in
 	// memory is named by the checkpoint document alone, and a resume must
@@ -844,29 +894,258 @@ function projectRecordedHistory(
 }
 
 /**
- * `messages` without the leading run of messages the session log already
- * holds, compared by value. A host that passes only the new input is
- * unaffected; one that passes the whole conversation adds only its tail.
+ * Deep-equal ignoring `id` and `timestamp`: two copies of one message may
+ * disagree only on which record named it, and `timestamp` is bookkeeping
+ * about when it was authored, not part of what it says — `createUserMessage`
+ * and its siblings always stamp `Date.now()`, but the field is optional on
+ * `BaseMessage`, and a host that reconstructs history itself (the
+ * documented stateless `exec --json` stdin contract never requires it) has
+ * no way to recover the original value and must not be read as having
+ * edited a message merely for omitting one. Each side is round-tripped
+ * through JSON first — "canonical" — so an `undefined`-valued own property
+ * (a field a driver or the recorder set explicitly, as opposed to one never
+ * mentioned) does not read as a difference: `isDeepStrictEqual` alone treats
+ * `{ x: undefined }` and `{}` as unequal, and the durable record went
+ * through the same round trip when it was written.
+ */
+function sameMessageContent(a: Message, b: Message): boolean {
+	const { id: _a, timestamp: _ta, ...restA } = a
+	const { id: _b, timestamp: _tb, ...restB } = b
+	return isDeepStrictEqual(
+		JSON.parse(JSON.stringify(restA)) as unknown,
+		JSON.parse(JSON.stringify(restB)) as unknown,
+	)
+}
+
+/** A `stale_cached_history` refusal: which way "the log disagrees" this is. */
+function staleCachedHistoryError(
+	kind: 'edited' | 'foreign' | 'unaligned',
+	message: Message,
+): NamzuError {
+	const id = message.id
+	const guidance =
+		'pass only new messages (with no id), or re-read history from the session instead of reusing a cached copy.'
+	const text =
+		kind === 'edited'
+			? `A cached message carries id ${id}, but its content no longer matches what this session's log recorded under that id. A message read from history must not be edited before it is sent back: ${guidance}`
+			: kind === 'foreign'
+				? `A cached message carries id ${id}, which this session's log never recorded. A host must not mint its own id for a message: pass only messages this session's log gave an id (unedited), or new messages with no id.`
+				: `A cached message with no id starts the same as this session's log, but the two diverge further in — this looks like an attempted full resend of the conversation, of a fold this log does not actually hold (edited, reordered, or from elsewhere). Nothing here can tell which of the cache's later messages, if any, are genuinely new: ${guidance}`
+	return new NamzuError({
+		code: 'stale_cached_history',
+		message: text,
+		details: {
+			kind,
+			role: message.role,
+			...(id === undefined ? {} : { messageId: id }),
+		},
+	})
+}
+
+/**
+ * A kind `query()` reconstructs itself every turn rather than trusting a
+ * caller's cached copy of it: the per-turn static/dynamic system prompt
+ * (`pushSystemMessages`, pushed `transient: true` and so never durably
+ * recorded at all — see `manager/session/turn-recorder.ts`), and a
+ * project-instruction snapshot (durably recorded, but `Turn.messages` keeps
+ * only the LATEST one per `collapseProjectInstructionSnapshots`, while the
+ * log keeps every turn's own). A compaction summary and a working-memory
+ * note are deliberately NOT here: those two are conversation STATE the
+ * kernel cannot re-derive, not prompt scaffolding it rebuilds.
+ *
+ * Comparing either kind positionally is meaningless — the caller's copy and
+ * the log's own history disagree on how many of them exist by construction,
+ * never because anything is stale — so both are dropped before the no-id
+ * alignment below ever sees them, on both the caller's side and the fold's.
+ */
+function isKernelDerivedMessage(message: Message): boolean {
+	if (isProjectInstructionMessage(message)) return true
+	if (message.role !== 'system') return false
+	const content = typeof message.content === 'string' ? message.content : null
+	return !isCompactionMessage(content) && !isWorkingMemoryMessage(content)
+}
+
+/**
+ * How a caller's no-id messages (`caller`, in order) relate to what remains
+ * of the log's own fold (`pool`, in order), once ids already claimed and the
+ * kernel-rebuilt kinds are set aside from both — never by searching for SOME
+ * aligned position, which cannot tell "the caller is echoing an old value"
+ * from "the caller wrote something new that happens to match" without a
+ * false positive or a false negative somewhere (an interrupted turn's own
+ * trailing no-id prompt, resent verbatim as the host's only next message,
+ * looks identical to a coincidental repeat of it as genuinely new content;
+ * a `k`-suffix search that tried to tell them apart swallowed the latter).
+ *
+ * There is exactly one shape this recognizes as "my cache, trimmed to a
+ * prefix of the fold": `caller`'s OWN first `pool.length` messages equal
+ * `pool` exactly, in order — the caller resent everything the fold
+ * currently holds. Then, and only then, that matched prefix is durable and
+ * dropped; what follows (if anything) is new. `caller` must be LONGER than
+ * `pool` for this UNLESS the call also has an id-carrying message
+ * elsewhere (`hasId`): only then can a length exactly matching the pool —
+ * "everything, nothing new yet" — be trusted, because something else in
+ * the same call already anchors it as part of a larger, structured resend.
+ * A caller with no id anywhere gets the strict inequality: its no-id
+ * segment IS its whole request, so an exact length match cannot be told
+ * apart from one message that happens to repeat the fold's own last value.
+ *
+ * Anything else is never matched by value, on purpose — a caller with no
+ * more messages than the fold has left, or one whose cache diverges from
+ * the fold's very first message, is `'new'`: every message it sent is kept,
+ * none dropped. This gives up detecting "a trimmed cache" without an id
+ * (session-log.md documents why: a host must send either everything or only
+ * new messages to reconcile by value at all) in exchange for never again
+ * confusing an echo with new content in either direction.
+ *
+ * The one case still refused rather than guessed at: `caller` is longer
+ * than `pool` and its first message matches `pool`'s first, but the two
+ * diverge somewhere after that — a cache that looks like an attempted full
+ * resend of a KNOWN fold, just not the fold this session's log actually
+ * holds. `'unaligned'` names that, rather than the alternative — duplicating
+ * or dropping content nobody can prove is redundant.
  */
-function withoutRecordedPrefix(
+type NoIdReconciliation =
+	/** `caller`'s first `pool.length` messages ARE `pool`: drop that prefix. */
+	| 'trimmed'
+	/** Fails the turn: an attempted full resend of a fold this log does not hold. */
+	| 'unaligned'
+	/** No value matching at all: every one of `caller`'s messages is kept. */
+	| 'new'
+
+function reconcileNoIdAgainstFold(
+	caller: readonly Message[],
+	pool: readonly Message[],
+	// A wholly no-id caller (this call's `messages` carries no id anywhere)
+	// gets the strict `>`: its no-id segment IS its entire request, so a
+	// length exactly matching the pool is indistinguishable from "one
+	// message that happens to repeat the fold's own last value" (an
+	// interrupted turn's own trailing prompt, resent as a caller's ONLY
+	// next message — round-3's own probe1/probe3) — favoring "new" there
+	// is the whole point of this rule. A caller that ALSO sent at least one
+	// id-carrying message this same call is not that: its no-id segment is
+	// part of a larger, structured resend the id path already anchors, so
+	// an EXACT length match is trusted as "everything, nothing new" (`>=`)
+	// — the shape a wholesale history replacement (a compaction, or the
+	// provider-rejected-image repair, which records this way for the same
+	// reason: `TurnRecorder.replaceMessages`) produces on its very next
+	// turn, before any new message has been added at all.
+	hasId: boolean,
+): NoIdReconciliation {
+	if (hasId ? caller.length >= pool.length : caller.length > pool.length) {
+		let fullPrefix = true
+		for (let i = 0; i < pool.length; i++) {
+			if (!sameMessageContent(caller[i] as Message, pool[i] as Message)) {
+				fullPrefix = false
+				break
+			}
+		}
+		if (fullPrefix) return 'trimmed'
+		if (pool.length > 0 && sameMessageContent(caller[0] as Message, pool[0] as Message)) {
+			return 'unaligned'
+		}
+	}
+	return 'new'
+}
+
+/**
+ * `messages` reconciled against this session's log, by id where a message
+ * carries one, and otherwise by the anchored, whole-cache rule
+ * {@link reconcileNoIdAgainstFold} implements — never by walking the two
+ * positionally message by message, and never by searching for some aligned
+ * position, either of which reads a genuine echo of old content and a
+ * coincidentally-identical new message as the same shape.
+ *
+ * A message carrying an id already durable under it (matching content) is
+ * dropped — the fold supplies it, from wherever compaction has since put
+ * it, even from before a compaction summarized it away, since the log
+ * remembers every id it ever gave out. One whose id the log never recorded,
+ * or whose content no longer matches what the log recorded under it, is
+ * refused outright (`stale_cached_history`, `'foreign'` / `'edited'`).
+ *
+ * A message with no id, once the kernel-derived kinds above are set aside
+ * from both sides, joins its OWN sequence of no-id messages (in their
+ * original relative order), reconciled against the fold's own remaining
+ * pool: every fold entry EXCEPT one whose id an id-carrying caller message
+ * already claimed above (so nothing is offered to both mechanisms) and a
+ * no-id one (a compaction summary, or a record predating per-message ids).
+ * A caller using no ids at all thus reconciles exactly as
+ * {@link reconcileNoIdAgainstFold} describes, against the whole fold,
+ * nothing claimed. A caller that CAN only ever id some roles — a protocol
+ * adapter (AG-UI) that mints an id for an assistant/tool message it
+ * produced but never for one its own client authored — still reconciles
+ * its no-id messages correctly, against whatever the id path left
+ * unclaimed, rather than an empty pool that would read every one of them
+ * as new (which is harmless here — "new" is always a safe answer — but
+ * would duplicate needlessly).
+ *
+ * See {@link reconcileNoIdAgainstFold} for exactly which shape is recognized
+ * as "my cache, trimmed to a prefix of the fold" (dropped), which is
+ * refused as `stale_cached_history` (`'unaligned'`) as an attempted resend
+ * of a fold this log does not hold, and — deliberately, the rest — which is
+ * never matched by value at all and so always kept as new.
+ */
+async function reconcileCallerMessages(
 	messages: readonly Message[],
 	history: readonly RecordedMessage[],
-): Message[] {
-	const recorded = history.filter((entry) => entry.message.role !== 'system')
-	let matched = 0
-	let r = 0
-	for (const message of messages) {
-		if (message.role === 'system') {
-			matched++
-			continue
+	log: SessionLog,
+	continuationMode: boolean,
+): Promise<Message[]> {
+	const hasId = messages.some((message) => message.id !== undefined)
+	const recordedById = hasId ? await readEverRecordedMessages(log) : undefined
+	// Ids a caller message already claimed by direct lookup above: a fold
+	// entry that gave one of THESE out must not also be offered to the no-id
+	// alignment below, or a message that already reconciled by id could be
+	// matched a second time by value. A caller need not be all-or-nothing
+	// about ids for this to matter — a protocol adapter (AG-UI) that can
+	// only ever attach an id to an assistant/tool message it itself minted,
+	// never to a message its OWN client authored, sends exactly this mix.
+	const claimedIds = new Set<MessageId>()
+
+	const noIdIndices: number[] = []
+	const noIdMessages: Message[] = []
+	for (let index = 0; index < messages.length; index++) {
+		const message = messages[index] as Message
+		const id = message.id
+		if (id !== undefined) {
+			const recorded = recordedById?.get(id)
+			if (recorded === undefined) throw staleCachedHistoryError('foreign', message)
+			if (!sameMessageContent(recorded, message)) throw staleCachedHistoryError('edited', message)
+			claimedIds.add(id)
+			continue // already durable: the fold supplies it
 		}
-		const next = recorded[r]
-		if (!next || JSON.stringify(next.message) !== JSON.stringify(message)) break
-		r++
-		matched++
+		// Outside `continuationMode`, the kernel rebuilds the system floor and
+		// collapses every project-instruction snapshot but the latest
+		// (`pushSystemMessages`, `collapseProjectInstructionSnapshots`
+		// downstream of this function) regardless of what a caller sent, so a
+		// no-id message of either kind is dropped here rather than offered to
+		// the alignment below, where the fold's OWN asymmetric copies of them
+		// (one durable record per turn that had one, never collapsed) would
+		// corrupt it. `continuationMode` turns that rebuilding OFF — the
+		// caller's array IS the request, verbatim — so there is no "the
+		// kernel discards this anyway" to lean on; a message of either kind
+		// is ordinary content there; unforced-through, it would just report
+		// a passthrough-only conversation as no-id forever - a genuinely new
+		// no-id system message (a `continuationMode` caller's own) has to
+		// reconcile like anything else, not vanish.
+		if (!continuationMode && isKernelDerivedMessage(message)) continue
+		noIdIndices.push(index)
+		noIdMessages.push(message)
+	}
+
+	const pool = history
+		.filter((entry) => entry.messageId === undefined || !claimedIds.has(entry.messageId))
+		.map((entry) => entry.message)
+		.filter((message) => continuationMode || !isKernelDerivedMessage(message))
+
+	const reconciliation = reconcileNoIdAgainstFold(noIdMessages, pool, hasId)
+	if (reconciliation === 'unaligned') {
+		throw staleCachedHistoryError('unaligned', noIdMessages[0] as Message)
 	}
-	if (r === 0) return [...messages]
-	return messages.slice(matched)
+	const keptNoIdIndices =
+		reconciliation === 'trimmed' ? noIdIndices.slice(pool.length) : noIdIndices
+
+	const newIndices = new Set(keptNoIdIndices)
+	return messages.filter((_message, index) => newIndices.has(index))
 }
 
 /**