mixdog 0.9.87 → 0.9.89

package/src/runtime/agent/orchestrator/session/agent-loop.mjs

@@ -50,6 +50,7 @@ import {
     crossTurnDedupStub,
     ITERATION_CAP_REFUSAL_STUB,
 } from './loop/completion-guards.mjs';
+import { STOP_HOOK_SOURCE, createToolFailureStopHook } from './loop/stop-hooks.mjs';
 import { isEditProgressTool } from './loop/completion-guards.mjs';
 import { agentContextOverflowError } from './loop/context-overflow.mjs';
 import { positiveTokenInt } from './loop/env.mjs';
@@ -80,10 +81,16 @@ import {
 } from './loop/tool-helpers.mjs';
 import {
     compactToolCallsForHistory,
+    compactSettledToolCallBodies,
     restoreToolCallBodyForId,
 } from './loop/stored-tool-args.mjs';
 import { repairTranscriptBeforeProviderSend } from './loop/transcript-repair.mjs';
-import { classifyTerminationReason, INCOMPLETE_STOP_REASONS, isOutputLimitStopReason } from './loop/termination.mjs';
+import {
+    classifyTerminationReason,
+    INCOMPLETE_STOP_REASONS,
+    isOutputLimitStopReason,
+    providerContinuationSignal,
+} from './loop/termination.mjs';
 import { createSteeringLadder } from './loop/steering-ladder.mjs';
 import { runPreSendCompactPass } from './pre-send-compact.mjs';
 import { createEagerDispatcher } from './eager-dispatch.mjs';
@@ -210,14 +217,31 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
     // Reasoning/thinking deltas, tool calls, and the final answer are kept.
     const suppressMidTurnText = isAgentOwner(sessionRef);
     if (suppressMidTurnText) opts.onTextDelta = undefined;
+    // Deferred mutation-body compaction: bodies left verbatim by a previous
+    // turn's push (deferBodies below) collapse to markers now — the model has
+    // already seen them on that turn's follow-up send. Failed bodies stay
+    // verbatim for retry.
+    compactSettledToolCallBodies(messages);
+    // ---- Codex turn stop hook (refs/codex core/src/session/turn.rs:372-404) --
+    // A no-tool assistant message is TERMINAL. Only a structured provider
+    // follow-up signal (end_turn=false / pause_turn), pending input, tool
+    // calls/results, or a stop hook that blocks with a continuation prompt keep
+    // sampling alive. The single hook below is structural: after an unresolved
+    // real tool failure it blocks the first terminal message ONCE, records the
+    // continuation prompt, and then stays inactive for the rest of the turn.
+    const _toolFailureStopHook = createToolFailureStopHook();
     const pushToolResultMessage = (message) => {
         messages.push(message);
+        _toolFailureStopHook.observeToolResult(message);
         try { opts.onToolResult?.(message); } catch {}
     };
     const drainSteeringIntoMessages = (stage = 'mid-turn', options = {}) => {
         if (typeof opts.drainSteering !== 'function') return false;
         let steerMsgs = [];
-        try { steerMsgs = opts.drainSteering(sessionId, options) || []; }
+        // The stage rides along so the host can scope which queues a drain may
+        // consume (mid-turn tool-batch boundary vs the terminal pending-input
+        // check that precedes the stop hooks).
+        try { steerMsgs = opts.drainSteering(sessionId, { ...options, stage }) || []; }
         catch { steerMsgs = []; }
         const mergedMessages = [];
         for (const entry of Array.isArray(steerMsgs) ? steerMsgs : []) {
@@ -288,13 +312,34 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
         const providerMetadata = resp.providerMetadata && typeof resp.providerMetadata === 'object'
             ? resp.providerMetadata
             : null;
-        if (!content && !reasoningContent && !reasoningItems && !thinkingBlocks) return false;
+        // Anthropic native server-tool turns (web search / code execution /
+        // native MCP) carry `server_tool_use` + `*_tool_result` blocks that
+        // exist ONLY in this ordered verbatim list — they cannot be rebuilt
+        // from content/thinkingBlocks/toolCalls, and dropping them breaks the
+        // resumed turn (a result block is only valid right after its call
+        // block). Attach them so Anthropic lowering replays the turn as-is.
+        // Guarded on no client tool calls: this committer only handles
+        // continuation/intermediate turns. A MIXED turn (native blocks +
+        // client tool_use) is committed by the tool-call branch below, which
+        // keeps both the compacted toolCalls and these blocks.
+        const assistantBlocks = Array.isArray(resp.assistantBlocks)
+            && resp.assistantBlocks.length
+            && !resp.toolCalls?.length
+            ? resp.assistantBlocks
+            : null;
+        // A native-only turn (server tool blocks, no flattened text) is real
+        // assistant output and must stay committable — not treated as empty.
+        if (!content && !reasoningContent && !reasoningItems && !thinkingBlocks && !assistantBlocks) return false;
         const message = attachAssistantTranscriptMetadata({
             role: 'assistant',
             content,
+            // assistantBlocks already contains the thinking blocks verbatim in
+            // stream order, so thinkingBlocks is redundant (and would be
+            // double-counted by the context estimator) when it is present.
+            ...(assistantBlocks ? { assistantBlocks } : {}),
             // Anthropic adaptive-thinking signatures must be replayed verbatim
             // before the continuation turn, just like tool-call trajectories.
-            ...(thinkingBlocks ? { thinkingBlocks } : {}),
+            ...(thinkingBlocks && !assistantBlocks ? { thinkingBlocks } : {}),
             ...(reasoningItems ? { reasoningItems } : {}),
             ...(reasoningContent ? { reasoningContent } : {}),
             ...(providerMetadata ? { providerMetadata } : {}),
@@ -334,6 +379,11 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
     let _refusalRetryUsed = false;
     let _maxOutputRecoveryCount = 0;
     const _maxOutputContentParts = [];
+    // Count of structured provider continuation signals honored this turn
+    // (endTurn === false / stopReason === 'pause_turn'). Diagnostic only; the
+    // hard iteration cap remains the sole bound on how long a provider may
+    // keep declaring "not done" inside one user turn.
+    let _providerContinuationCount = 0;
     // Claude Code parity: queued prompt/task notifications are attached after a
     // tool batch, before the continuation provider send. Normal batches drain
     // up to 'next'; a Sleep-like tool grants a 'later' flush.
@@ -760,6 +810,42 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                 });
                 continue;
             }
+            // Structured provider continuation signal. The provider declared
+            // the assistant turn unfinished, so this text is mid-turn output,
+            // not a final answer: commit it EXACTLY ONCE to history/UI (single
+            // pushIntermediateAssistantResponse → onAssistantMessageCommitted)
+            // and immediately resume sampling in the same user turn. Output
+            // limit stops keep the bounded max-output recovery ladder above and
+            // refusals keep the bounded refusal retry; both own their own
+            // continuation semantics. No lexical/progress-text heuristic.
+            const continuationSignal = !isOutputLimitStop && stopReason !== 'refusal'
+                ? providerContinuationSignal(response)
+                : null;
+            if (continuationSignal && pushIntermediateAssistantResponse(response)) {
+                if (hasContent && !suppressMidTurnText) {
+                    try { opts.onAssistantText?.(response.content); } catch { /* best-effort */ }
+                }
+                _providerContinuationCount += 1;
+                _emptyNudgeStreak = 0;
+                try {
+                    appendAgentTrace({
+                        sessionId,
+                        iteration: iterations,
+                        kind: 'provider_continuation',
+                        payload: {
+                            signal: continuationSignal,
+                            stop_reason: stopReason,
+                            count: _providerContinuationCount,
+                            content_len: typeof response.content === 'string' ? response.content.length : 0,
+                        },
+                        agent: sessionAgent || null,
+                    });
+                } catch { /* best-effort */ }
+                continue;
+            }
+            // A continuation signal with nothing committable (no text, no
+            // reasoning) falls through to the bounded empty-turn handling
+            // below: re-sending an unchanged transcript would livelock.
             if (!hasContent && !isHidden) {
                 _emptyNudgeStreak += 1;
                 if (_emptyNudgeStreak > EMPTY_NUDGE_MAX) {
@@ -774,14 +860,49 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                 if (isIncompleteStop) {
                     nudgeMsg = `[mixdog-runtime] Previous turn ended mid-synthesis (stopReason=${stopReason}) with empty content. Continue — emit your final handoff (fragments, file:line) with your synthesis so far, or call more tools to finish.`;
                 } else {
-                    // Vary the nudge per attempt — a byte-identical repeat
-                    // reinforces the empty-completion pattern it is trying to
-                    // break (the request context stays effectively constant).
                     nudgeMsg = `[mixdog-runtime] Your previous response was empty (no handoff text and no tool call) — attempt ${_emptyNudgeStreak}/${EMPTY_NUDGE_MAX}. Either emit your final handoff text now, or continue with tool calls. Do not return an empty turn.`;
                 }
                 messages.push({ role: 'user', content: nudgeMsg });
                 continue;
             }
+            // Codex `has_pending_input` (turn.rs:304-318): queued user input is
+            // folded into needs_follow_up and evaluated BEFORE the stop hooks,
+            // so real steering always wins over a synthetic continuation prompt.
+            // Commit the terminal text first (beforeAppend), then resume.
+            if (!_capFinalToolsDisabled && drainSteeringIntoMessages('terminal', {
+                maxPriority: 'next',
+                beforeAppend: () => { pushIntermediateAssistantResponse(response); },
+            })) {
+                _emptyNudgeStreak = 0;
+                continue;
+            }
+            // Codex parity (turn.rs:372-404): this no-tool message ends the turn
+            // unless a stop hook blocks it. The unresolved-tool-failure hook may
+            // block exactly once — commit the assistant text, record the
+            // structural continuation prompt, resume sampling. Skipped on the
+            // hard-cap final turn (tool use is already forbidden) and for hidden
+            // roles, whose own role rules define a text-only terminal contract.
+            if (!_capFinalToolsDisabled && !isHidden) {
+                const _hookPrompt = _toolFailureStopHook.takeContinuationPrompt();
+                if (_hookPrompt) {
+                    pushIntermediateAssistantResponse(response);
+                    messages.push({
+                        role: 'user',
+                        content: _hookPrompt,
+                        meta: { source: STOP_HOOK_SOURCE, tool: _toolFailureStopHook.lastFailedTool || null },
+                    });
+                    try {
+                        appendAgentTrace({
+                            sessionId,
+                            iteration: iterations,
+                            kind: 'steer',
+                            payload: { tag: 'tool_failure_stop_hook', tool: _toolFailureStopHook.lastFailedTool || null },
+                            agent: sessionAgent || null,
+                        });
+                    } catch { /* best-effort */ }
+                    continue;
+                }
+            }
             if (_maxOutputContentParts.length > 0) {
                 const terminalSegment = typeof response.content === 'string' ? response.content : '';
                 response = {
@@ -823,13 +944,33 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
             // response.content (the real result rides the later final-answer
             // turn). Blank it so it never accumulates as input tokens.
             content: suppressMidTurnText ? '' : (response.content || ''),
-            toolCalls: compactToolCallsForHistory(calls),
+            // deferBodies: mutation bodies (patch / old_string / ...) stay
+            // verbatim through the send that answers this batch, then the
+            // compactSettledToolCallBodies sweep below collapses them. This
+            // keeps a model that patches twice in a row from ever seeing (and
+            // copying) a compacted marker where its own last patch should be.
+            toolCalls: compactToolCallsForHistory(calls, { deferBodies: true }),
+            // MIXED Anthropic turn (native server tools + client tool_use):
+            // the ordered `server_tool_use` / `*_tool_result` blocks exist ONLY
+            // in this verbatim list and are order-bound (a result block is
+            // valid only right after its call block), so they must ride the
+            // tool-call history message too. toolCalls above stays authoritative
+            // for execution/recovery/interruption; both Anthropic lowerers
+            // prefer assistantBlocks verbatim (which already contains the
+            // text/thinking/tool_use blocks), so nothing is emitted twice and
+            // non-Anthropic providers simply ignore the field.
+            ...(Array.isArray(response.assistantBlocks) && response.assistantBlocks.length
+                ? { assistantBlocks: response.assistantBlocks }
+                : {}),
             // Anthropic adaptive thinking: prior-turn thinking blocks must be
             // returned verbatim (signature intact; empty thinking allowed) and
             // are REQUIRED back before tool_use blocks on tool-continuation
             // turns. Store them so toAnthropicMessages can build assistantBlocks
-            // = [...thinking, tool_use...]. Other providers ignore this field.
+            // = [...thinking, tool_use...]. Skipped when assistantBlocks is
+            // present: those blocks already carry the thinking verbatim, and a
+            // second copy would double-count in the context estimator.
             ...(Array.isArray(response.thinkingBlocks) && response.thinkingBlocks.length
+                && !(Array.isArray(response.assistantBlocks) && response.assistantBlocks.length)
                 ? { thinkingBlocks: response.thinkingBlocks }
                 : {}),
             ...(Array.isArray(response.reasoningItems) && response.reasoningItems.length
@@ -842,8 +983,13 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                 ? { providerMetadata: response.providerMetadata }
                 : {}),
         }, opts);
+        // Settle earlier deferred bodies before this turn's message lands:
+        // every previous call already has its result row, so successful bodies
+        // compact to markers while failed ones keep their full retry text.
+        compactSettledToolCallBodies(messages);
         messages.push(_assistantTurnMsg);
         try { opts.onAssistantMessageCommitted?.(_assistantTurnMsg); } catch {}
+        const _callsToExecute = calls;
         // Hard-cap final turn: tools are disabled but the model still emitted
         // tool calls. Do NOT execute them — push a refusal stub for each.
         if (_capFinalToolsDisabled) {
@@ -860,7 +1006,7 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
         }
         try { opts.onToolPhaseStarted?.(); } catch {}
         ({ dedupStubTotal: _dedupStubTotal, editCount: _editCount } = await processToolBatch({
-            calls, messages, tools, cwd, sessionId, sessionRef, signal, opts,
+            calls: _callsToExecute, messages, tools, cwd, sessionId, sessionRef, signal, opts,
             iterations, assistantTurnMsg: _assistantTurnMsg,
             pending: eager.pending, epoch: eager.epoch, startEagerRun: eager.startEagerRun,
             crossTurnCalls: _crossTurnCalls, crossTurnCap: _CROSS_TURN_CAP,
@@ -869,8 +1015,10 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
             pushToolResultMessage, throwIfAborted,
             repeatFailLimit: REPEAT_FAIL_LIMIT,
         }));
+        // Settle the stop hook on the batch that actually executed.
+        _toolFailureStopHook.endBatch(_callsToExecute);
         _toolBatchJustCompleted = true;
-        _lastToolBatchHadSleep = calls.some(isSleepLikeToolCall);
+        _lastToolBatchHadSleep = _callsToExecute.some(isSleepLikeToolCall);
     }
     // Classify WHY the loop ended so agent-tool can promote an empty/abnormal
     // finish to an explicit Lead-facing error instead of a silent empty
@@ -891,5 +1039,6 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
         providerStateUpdated,
         terminationReason,
         maxLoopIterations,
+        providerContinuations: _providerContinuationCount,
     };
 }

package/src/runtime/agent/orchestrator/session/eager-dispatch.mjs

@@ -7,7 +7,7 @@
 // serial batch loop.
 import { normalizeToolEnvelope } from './tool-envelope.mjs';
 import { isInvalidToolArgsMarker } from '../providers/openai-compat-stream.mjs';
-import { _intraTurnSig, _isReadTool, _isScopedCacheableTool, _stripMcpPrefix } from './loop/tool-classify.mjs';
+import { _intraTurnSig, _isMutationTool, _isReadTool, _isScopedCacheableTool, _isShellTool, _stripMcpPrefix } from './loop/tool-classify.mjs';
 import { tryReadCached, tryScopedToolCached } from './read-dedup.mjs';
 import { preDispatchDenyForSession } from './loop/pre-dispatch-deny.mjs';
 import { executeTool } from './loop/tool-exec.mjs';
@@ -40,6 +40,18 @@ export function createEagerDispatcher({
         // resets at the turn boundary without leaking across getIterations().
         const _eagerInFlightSigs = new Map();
         const epoch = { mutation: 0 };
+        // Patch→shell ordering insurance: a shell call that appears AFTER an
+        // apply_patch in the same assistant turn must not eager-start before
+        // that patch has executed (serial body runs both in call order).
+        // Reads are already safe via the mutationEpoch re-execution gate;
+        // only shell's side effects would consume pre-patch file state.
+        let _streamSawMutation = false;
+        const _hasEarlierMutation = (calls, index) => {
+            for (let k = 0; k < index; k += 1) {
+                if (_isMutationTool(calls[k]?.name)) return true;
+            }
+            return false;
+        };
         const startEagerTool = (call) => {
             if (!call?.id || pending.has(call.id) || !isParallelDispatchable(call.name)) return null;
             // Never eager-execute a call whose arguments failed to parse
@@ -163,6 +175,9 @@ export function createEagerDispatcher({
                 // later calls keep starting in parallel past it.
                 if (!call?.id || !isParallelDispatchable(call.name)) continue;
                 if (dupSet && dupSet.has(call.id)) continue;
+                // Patch→shell insurance: leave a shell that follows an
+                // apply_patch to the serial body so it runs after the patch.
+                if (_isShellTool(call.name) && _hasEarlierMutation(calls, j)) continue;
                 // A null return here is NOT a state barrier. It means a
                 // non-barrier stub — intra-turn in-flight dup, repeat-failure /
                 // cross-turn dedup, pre-dispatch-deny, invalid-args, or a cache
@@ -173,7 +188,9 @@ export function createEagerDispatcher({
             }
         };
         const onToolCall = (call) => {
+            if (_isMutationTool(call?.name)) { _streamSawMutation = true; return; }
             if (!isParallelDispatchable(call?.name)) return;
+            if (_streamSawMutation && _isShellTool(call.name)) return;
             startEagerTool(call);
         };
     return { pending, epoch, startEagerTool, startEagerRun, onToolCall };

package/src/runtime/agent/orchestrator/session/lifecycle-scan.mjs

@@ -1,66 +1,82 @@
 /**
- * Cheap, bounded top-level-only scan for the `closed`/`generation`
- * lifecycle fields in a serialized session JSON document — a substitute
- * for JSON.parse on the session-store save-guard hot path.
+ * Authoritative top-level lifecycle read (`id` / `closed` / `generation`) for
+ * a serialized session JSON document.
  *
- * Why not JSON.parse: `generation` is a top-level field on every persisted
- * session (added by _ensureLifecycleFields on first save), so a raw
- * substring pre-check (`raw.includes('"generation"')`) is true for nearly
- * every guarded write — paying full-parse-and-allocate cost (building the
- * entire messages array, unescaping every string) on the hot path even
- * though only two scalar fields are ever consulted.
+ * ONE verdict, no fallbacks. Every caller of this module makes a destructive
+ * or ownership-deciding choice (drop a save, delete a file, close a session,
+ * deliver cross-process input), so the module answers with exactly two
+ * outcomes:
  *
- * Why not a regex-only check: a stored message body can itself contain the
- * literal text `{"closed":true}` (a tool result, a pasted JSON blob, an
- * assistant-authored snippet) inside `messages[i].content`. A substring or
- * naively-anchored regex cannot tell that occurrence apart from the real
- * top-level lifecycle field, so it is spoofable. This scanner walks the raw
- * text as a real (bracket-depth + string-escape aware) tokenizer, but only
- * *interprets* key/value pairs at depth 1 (directly inside the root
- * object); every nested object/array/string value — including the entire
- * `messages` array — is skipped by depth counting alone, never allocated
- * or parsed. That keeps it both spoof-proof (nested `"closed"` can never be
- * mistaken for the top-level one) and cheap (no JS object/array/string
- * allocation for content we don't care about).
+ *   • a lifecycle record — the document is a single, complete, well-formed
+ *     JSON object whose top-level lifecycle fields are unambiguous;
+ *   • LIFECYCLE_SCAN_CONFLICT — "unreadable": ANY doubt at all.
  *
- * Returns `{ closed, generation }` (either key absent if the field wasn't
- * present at depth 1) or `null` if `raw` is not a well-formed top-level
- * JSON object (caller should treat that the same as a parse failure).
+ * There is deliberately no third "couldn't tell, parse it yourself" state.
+ * The previous incarnation was a hand-rolled depth-1 tokenizer that returned
+ * `null` for everything it did not positively confirm and let each caller
+ * fall back to `JSON.parse` — which silently resolves duplicate keys
+ * LAST-WINS, so a record like `{"id":"mine",…,"id":"other"}` (or a malformed
+ * separator the scanner refused) was accepted as this session's own state by
+ * the very code paths the scanner existed to protect. The fallback WAS the
+ * vulnerability. It is gone.
  *
- * Scope contract: this is not a general JSON validator. `raw` is always our
- * own JSON.stringify output (or truncated/concatenated fragments thereof
- * from partial writes) — never hand-authored or third-party JSON. It is
- * only responsible for detecting the failure modes a writer like ours can
- * actually produce: mid-write truncation, nested-field spoofing, mismatched
- * brackets, and trailing garbage from a botched/partial write. It does NOT
- * validate separator-level well-formedness (missing/trailing commas,
- * missing colons beyond the one check above, etc.) since JSON.stringify
- * cannot emit those — a well-formed prefix is assumed between structural
- * checks. Anything the scanner doesn't positively confirm returns `null`,
- * and the caller falls back to `JSON.parse` for the definitive answer.
+ * Strategy (simplification over more parser patches):
+ *   1. strict full `JSON.parse` — the only validator. It rejects truncation,
+ *      missing/trailing commas, missing colons, trailing garbage after the
+ *      root object, and any non-object root, with no bespoke grammar of ours
+ *      to get subtly wrong;
+ *   2. an explicit top-level duplicate-key walk, because `JSON.parse` alone
+ *      is last-wins and cannot report that a key appeared twice. ANY repeated
+ *      top-level key is a conflict — not just the lifecycle three: consumers
+ *      of this record RESERIALIZE it (the tombstone/detach barriers rewrite
+ *      the whole document) and ACT on other top-level fields (`status`,
+ *      `updatedAt`, `owner`, `messages` drive sweep maturity, blank-scratch
+ *      reaping and transcript reads), so a last-wins `status`/`updatedAt`
+ *      would silently decide a delete or a rewrite. The walk runs on a
+ *      document ALREADY proven well-formed by step 1, so it only counts
+ *      depth-1 keys (skipping nested objects/arrays/strings by bracket
+ *      depth) and never has to double as a validator;
+ *   3. type validation of the three lifecycle fields. Our writer only ever
+ *      emits a non-empty string `id`, a boolean `closed` and a numeric
+ *      `generation`; anything else present under those names is not a record
+ *      we can speak for → unreadable.
+ *
+ * Duplicate detection is type- and order-independent by construction: the
+ * walk counts key OCCURRENCES before any value is interpreted, so
+ * `{"id":7,"id":"sess_a"}` (non-string first) and `{"closed":false,
+ * "closed":true}` conflict exactly like the string-first case.
+ *
+ * NESTED duplicates stay compatible on purpose: a duplicate key inside
+ * `messages[i].content` (a pasted JSON blob, a tool result) is message DATA.
+ * It is skipped by bracket depth, is never an ownership or action input, and
+ * the whole nested value is reserialized verbatim by JSON.stringify from the
+ * parsed document — the last-wins resolution there cannot move a lifecycle,
+ * sweep or delete decision.
+ *
+ * The parsed document is returned alongside the lifecycle fields (`doc`) so
+ * consumers that need the whole record (the sweep reads owner/status/
+ * timestamps/messages) reuse THIS parse instead of parsing again — a second
+ * parse would be both slower and a second, divergent authority.
  */
 
-function isWs(ch) {
-    return ch === ' ' || ch === '\t' || ch === '\n' || ch === '\r';
+// Single authoritative rejection marker: ambiguous OR malformed OR
+// wrong-typed. Frozen and deliberately carrying no `id`/`closed`/`generation`
+// so a lenient consumer that forgets the check still reads nothing usable.
+export const LIFECYCLE_SCAN_CONFLICT = Object.freeze({ conflict: 'unreadable' });
+
+/** True for the rejection marker (and for anything that isn't a record). */
+export function isLifecycleUnreadable(result) {
+    return !result || typeof result !== 'object' || result.conflict !== undefined;
 }
 
-// True iff raw[i..] is nothing but whitespace to EOF. Enforces the "single
-// complete root JSON object" contract: trailing garbage after the root `}`
-// (e.g. a concatenated second document, or corruption) must not be silently
-// accepted as if `raw` were exactly one well-formed object.
-function isTrailingWhitespaceOnly(raw, i) {
-    const len = raw.length;
-    while (i < len) {
-        if (!isWs(raw[i])) return false;
-        i++;
-    }
-    return true;
+function isWs(ch) {
+    return ch === ' ' || ch === '\t' || ch === '\n' || ch === '\r';
 }
 
 // Advances past a JSON string literal starting at raw[i] === '"'.
-// Escape handling only needs to skip exactly one char after each `\` —
-// even for `\u0041`-style escapes, the trailing hex digits can never be
-// `"` or `\`, so a naive 2-char skip never misses the real closing quote.
+// Escape handling only needs to skip exactly one char after each `\` — even
+// for `\u0041`-style escapes the trailing hex digits can never be `"` or `\`,
+// so a naive 2-char skip never misses the real closing quote.
 function skipString(raw, i) {
     const len = raw.length;
     i++; // opening quote
@@ -73,11 +89,8 @@ function skipString(raw, i) {
     return i;
 }
 
-// Advances past one JSON value (string/object/array/number/true/false/null)
-// starting at raw[i]. Objects/arrays are skipped via universal bracket-depth
-// counting (any `{`/`[` opens, any `}`/`]` closes) with string-awareness so
-// braces inside string content never perturb the count — never descends
-// into the structure to interpret its keys.
+// Advances past one JSON value. Objects/arrays are skipped by string-aware
+// bracket-depth counting — never descended into, never allocated.
 function skipValue(raw, i) {
     const len = raw.length;
     const c = raw[i];
@@ -99,79 +112,96 @@ function skipValue(raw, i) {
     return i;
 }
 
-export function scanTopLevelLifecycle(raw) {
+/**
+ * True when EVERY depth-1 key occurs exactly once.
+ *
+ * PRECONDITION: `raw` already parsed cleanly as a JSON object (see
+ * readTopLevelLifecycleRecord). That is what lets this be a counter rather
+ * than a validator: separator/grammar correctness was already decided by
+ * JSON.parse. Returns false on ANY repeated top-level key, or when the walk
+ * cannot complete (which cannot happen for a well-formed document — treated
+ * as unreadable rather than assumed unique).
+ */
+function hasUniqueTopLevelKeys(raw) {
+    // A Set (not an object) so a document key named `constructor`/`__proto__`
+    // is counted as data, never as an inherited property.
+    const seen = new Set();
     const len = raw.length;
     let i = 0;
     while (i < len && isWs(raw[i])) i++;
-    if (raw[i] !== '{') return null;
+    if (raw[i] !== '{') return false;
     i++;
-    const result = {};
-    let found = 0;
     while (i < len) {
         while (i < len && isWs(raw[i])) i++;
-        if (i >= len) return null;
-        if (raw[i] === '}') {
-            i++;
-            return isTrailingWhitespaceOnly(raw, i) ? result : null;
-        }
+        if (i >= len) return false;
+        if (raw[i] === '}') return true;
         if (raw[i] === ',') { i++; continue; }
-        if (raw[i] !== '"') return null;
+        if (raw[i] !== '"') return false;
         const keyStart = i;
         i = skipString(raw, i);
         let key;
-        try { key = JSON.parse(raw.slice(keyStart, i)); } catch { return null; }
+        try { key = JSON.parse(raw.slice(keyStart, i)); } catch { return false; }
         while (i < len && isWs(raw[i])) i++;
-        if (raw[i] !== ':') return null;
+        if (raw[i] !== ':') return false;
         i++;
         while (i < len && isWs(raw[i])) i++;
-        if (i >= len) return null;
-        if (key === 'closed' || key === 'generation') {
-            const valStart = i;
-            i = skipValue(raw, i);
-            try { result[key] = JSON.parse(raw.slice(valStart, i)); } catch { return null; }
-            found++;
-            // Both lifecycle fields resolved. We no longer need to interpret
-            // further keys, but we MUST still confirm the root object is not
-            // truncated (e.g. a session file cut off mid-write as
-            // `{"closed":true,"generation":1,"messages":[`) before trusting
-            // `result` — otherwise a truncated-but-field-bearing prefix would
-            // be treated as well-formed. Finish with a cheap depth-only walk
-            // (no key/value JSON.parse) to the matching close of the root
-            // object; only return `result` once that close is actually
-            // reached before EOF.
-            if (found === 2) {
-                // Track exact bracket types (not just depth) so a mismatched
-                // pair anywhere — including the root itself, e.g. malformed
-                // `{"closed":true,"generation":1]` closing the root object
-                // with `]` instead of `}` — is rejected rather than silently
-                // accepted because *a* bracket happened to bring the count to
-                // zero. `stack[0]` is always '}' (the root object we opened
-                // at function entry); the walk must consume exactly that to
-                // finish, and any closer that doesn't match the innermost
-                // opener is a structural error.
-                const stack = ['}'];
-                while (i < len) {
-                    const ch = raw[i];
-                    if (ch === '"') { i = skipString(raw, i); continue; }
-                    if (ch === '{') { stack.push('}'); i++; continue; }
-                    if (ch === '[') { stack.push(']'); i++; continue; }
-                    if (ch === '}' || ch === ']') {
-                        if (stack.pop() !== ch) return null; // mismatched bracket pair
-                        i++;
-                        if (stack.length === 0) {
-                            // Root object closed with '}' — only trust it if
-                            // nothing but whitespace follows to EOF.
-                            return isTrailingWhitespaceOnly(raw, i) ? result : null;
-                        }
-                        continue;
-                    }
-                    i++;
-                }
-                return null; // ran off the end (or hit EOF) before the root object closed: truncated
-            }
-        } else {
-            i = skipValue(raw, i);
-        }
+        if (i >= len) return false;
+        // Recorded BEFORE the value is looked at, so a duplicate is detected
+        // regardless of the value types or which copy comes first.
+        if (seen.has(key)) return false;
+        seen.add(key);
+        i = skipValue(raw, i);
+    }
+    return false;
+}
+
+/**
+ * Read `raw` as a session record.
+ * Returns LIFECYCLE_SCAN_CONFLICT (unreadable) or
+ * `{ doc, id, closed, generation }` where each lifecycle field is `undefined`
+ * when the document simply does not carry it (legacy records predate them).
+ */
+export function readTopLevelLifecycleRecord(raw) {
+    if (typeof raw !== 'string') return LIFECYCLE_SCAN_CONFLICT;
+    let doc;
+    // Strict and complete: trailing bytes, truncation, missing/trailing
+    // commas and every other separator fault are rejected here.
+    try { doc = JSON.parse(raw); } catch { return LIFECYCLE_SCAN_CONFLICT; }
+    if (!doc || typeof doc !== 'object' || Array.isArray(doc)) return LIFECYCLE_SCAN_CONFLICT;
+    // JSON.parse is last-wins for duplicate keys; this is where that is caught
+    // — for EVERY top-level key, since consumers reserialize and act on the
+    // whole record, not only on the lifecycle three.
+    if (!hasUniqueTopLevelKeys(raw)) return LIFECYCLE_SCAN_CONFLICT;
+    const has = (key) => Object.prototype.hasOwnProperty.call(doc, key);
+    const record = { doc, id: undefined, closed: undefined, generation: undefined };
+    if (has('id')) {
+        // Identity we cannot positively confirm is worse than no identity: a
+        // consumer must not read an empty/non-string id as "probably ours".
+        if (typeof doc.id !== 'string' || !doc.id) return LIFECYCLE_SCAN_CONFLICT;
+        record.id = doc.id;
     }
-    return null; // ran off the end without a closing '}': malformed/truncated
+    if (has('closed')) {
+        if (typeof doc.closed !== 'boolean') return LIFECYCLE_SCAN_CONFLICT;
+        record.closed = doc.closed;
+    }
+    if (has('generation')) {
+        if (typeof doc.generation !== 'number' || !Number.isFinite(doc.generation)) return LIFECYCLE_SCAN_CONFLICT;
+        record.generation = doc.generation;
+    }
+    return record;
+}
+
+/**
+ * Lifecycle fields only (no parsed document) for callers that consult nothing
+ * else. Same two outcomes: the fields present at top level, or
+ * LIFECYCLE_SCAN_CONFLICT.
+ */
+export function scanTopLevelLifecycle(raw) {
+    const record = readTopLevelLifecycleRecord(raw);
+    if (isLifecycleUnreadable(record)) return LIFECYCLE_SCAN_CONFLICT;
+    const out = {};
+    if (record.id !== undefined) out.id = record.id;
+    if (record.closed !== undefined) out.closed = record.closed;
+    if (record.generation !== undefined) out.generation = record.generation;
+    return out;
 }