@namzu/sdk 45.1.0 → 48.0.0

package/dist/runtime/query/prepare-turn.js

@@ -1,6 +1,8 @@
+import { isDeepStrictEqual } from 'node:util';
 import { drainQueuedMessages } from '../../agents/handle.js';
 import { repairToolMessageHistory, toolHistoryRepairChanged, } from '../../compaction/dangling.js';
-import { readFoldedHistory } from '../../manager/session/turn-recorder.js';
+import { assertSessionLogAttribution } from '../../manager/session/attribution.js';
+import { readEverRecordedMessages, readFoldedHistory, } from '../../manager/session/turn-recorder.js';
 import { resolveModelPricing } from '../../pricing/index.js';
 import { isCallerAbortError } from '../../provider/errors.js';
 import { withProviderFallback, } from '../../provider/fallback.js';
@@ -21,7 +23,8 @@ import { TurnContextFactory } from './context.js';
 import { EventTranslator } from './events.js';
 import { isCompactionMessage } from './iteration/phases/compaction.js';
 import { isWorkingMemoryMessage } from './iteration/phases/working-memory.js';
-import { awaitProjectInstructionCallback, collapseProjectInstructionSnapshots, replaceProjectInstructionSnapshot, } from './project-instructions.js';
+import { PreludeSessionLease } from './prelude-lease.js';
+import { awaitProjectInstructionCallback, collapseProjectInstructionSnapshots, isProjectInstructionMessage, replaceProjectInstructionSnapshot, } from './project-instructions.js';
 import { resolveMaxRequestRichContentBytes } from './request-rich-content.js';
 import { resolveSandboxTeardownTimeoutMs } from './sandbox-lifecycle.js';
 import { resolveSessionStorage } from './session-storage.js';
@@ -255,171 +258,186 @@ export async function prepareTurn(params) {
         ...(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,
-        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 = [
-        { provider: params.provider },
-        ...(params.fallbackProviders ?? []),
-    ];
-    assertCostIsAttributable(chain, params.pricing);
-    assertBudgetIsMeasurable(params);
-    const withRecovery = (provider) => {
-        const withIdleBound = withStreamIdleTimeout(provider, {
-            idleTimeoutMs: streamIdleTimeoutMs,
-            log,
+    // 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.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,
         });
-        const metered = withTokenBudget(withIdleBound, budget);
-        return params.retry === false
-            ? metered
-            : withProviderRetry(metered, {
-                config: params.retry,
+        // 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 = [
+            { provider: params.provider },
+            ...(params.fallbackProviders ?? []),
+        ];
+        assertCostIsAttributable(chain, params.pricing);
+        assertBudgetIsMeasurable(params);
+        const withRecovery = (provider) => {
+            const withIdleBound = withStreamIdleTimeout(provider, {
+                idleTimeoutMs: streamIdleTimeoutMs,
                 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: { 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);
-        },
-    });
-    // 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();
-    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) => {
-            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 = params.topicStateStore
-        ? await drainQueuedMessages(params.topicStateStore, params.topicId, params.tenantId).catch((err) => {
-            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({
-        ...(params.lease ? { lease: params.lease } : {}),
-        session: {
-            cwd: ctx.cwd,
-            ...(params.origin ? { origin: params.origin } : {}),
-            ...(params.forkedFrom ? { forkedFrom: params.forkedFrom } : {}),
-        },
-    });
-    try {
+            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: { 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);
+            },
+        });
+        // 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();
+        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) => {
+                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 = params.topicStateStore
+            ? await drainQueuedMessages(params.topicStateStore, params.topicId, params.tenantId).catch((err) => {
+                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.
@@ -428,7 +446,9 @@ export async function prepareTurn(params) {
         const history = 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 = queuedForThisRun.length > 0 ? [...queuedForThisRun, ...input] : input;
         let resolvedInitialMessages;
         let attachmentResolutionCancelled = false;
@@ -457,8 +477,16 @@ export async function prepareTurn(params) {
             const preparationSignal = params.signal ?? new AbortController().signal;
             let snapshot;
             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,
                 }));
                 // The callback promise can settle, remove its listener, and queue this
@@ -640,7 +668,11 @@ export async function prepareTurn(params) {
         };
     }
     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;
     }
 }
@@ -650,7 +682,10 @@ export async function prepareTurn(params) {
  */
 async function savedBudgetReference(params, turnId, storage, selected) {
     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
@@ -699,28 +734,192 @@ function projectRecordedHistory(history, ids) {
     return projected;
 }
 /**
- * `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 withoutRecordedPrefix(messages, history) {
-    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;
+function sameMessageContent(a, b) {
+    const { id: _a, timestamp: _ta, ...restA } = a;
+    const { id: _b, timestamp: _tb, ...restB } = b;
+    return isDeepStrictEqual(JSON.parse(JSON.stringify(restA)), JSON.parse(JSON.stringify(restB)));
+}
+/** A `stale_cached_history` refusal: which way "the log disagrees" this is. */
+function staleCachedHistoryError(kind, message) {
+    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) {
+    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);
+}
+function reconcileNoIdAgainstFold(caller, pool, 
+// 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) {
+    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], pool[i])) {
+                fullPrefix = false;
+                break;
+            }
+        }
+        if (fullPrefix)
+            return 'trimmed';
+        if (pool.length > 0 && sameMessageContent(caller[0], pool[0])) {
+            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, history, log, continuationMode) {
+    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();
+    const noIdIndices = [];
+    const noIdMessages = [];
+    for (let index = 0; index < messages.length; index++) {
+        const message = messages[index];
+        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]);
     }
-    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));
 }
 /**
  * A new turn named by the host must not reuse the id of a turn the session