agent-nuvira 3.5.0 → 3.5.2

package/dist/tools/tool-loop.js

@@ -32,7 +32,7 @@ import { runBeforeToolHooks, runToolOutcomeHooks, toolHookRefusalText, } from '.
 import { stepDigest } from '../learning/step-checkpoint.js';
 // P7 — the identical-command guard's memory. The loop drops it when a WRITE is
 // applied, so a repaired project can re-run its own check (see the context below).
-import { resetTerminalFailureStreaks } from './run-terminal.js';
+import { RUN_TERMINAL_INCOMPLETE_PREFIX, resetTerminalFailureStreaks } from './run-terminal.js';
 import { createRunCommandMemo } from './command-memo.js';
 // WS6 (#28) — the declared fault seam. `faultAt` is a null check when this
 // process declared no fault (`NUVIRA_INJECT_FAULT`), so an ordinary turn is
@@ -488,6 +488,13 @@ export const MAX_THINK_CONTINUES = 3;
  * demonstrated it is not answering this step, and re-calling it is the loop that
  * killed a real turn (five consecutive empties, then the turn reported itself
  * bounded with zero tool calls).
+ *
+ * THIS IS THE HANDOFF TRIGGER, NOT THE WHOLE PATIENCE POLICY. Since P5 the caller
+ * may grant extra same-pair attempts (`emptyResponsePatienceMs`), spent as
+ * bounded waits BEFORE this threshold is honored — which is what tells a two
+ * second blink apart from a dead pair. The threshold itself is unchanged, so a
+ * caller that grants nothing, and every mock/sub-agent child, behaves exactly as
+ * before.
  */
 export const MAX_SAME_MODEL_EMPTY_RETRIES = 1;
 /**
@@ -569,6 +576,26 @@ export function isTransientGenerationFailure(message) {
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+/**
+ * Sleep that a CANCELLED turn interrupts.
+ *
+ * The blip patience below can wait ten seconds on a pair, and a 10s wait that
+ * ignores Esc is a 10s delay before the turn admits it was cancelled — the same
+ * defect `chat.ts`'s `abortableSleep` was written to fix. Sliced rather than
+ * event-driven because the loop only holds an `AbortSignal`, and at 250ms a slice
+ * the granularity is imperceptible next to the wait it is bounding.
+ */
+async function sleepUnlessAborted(ms, signal) {
+    const deadline = Date.now() + Math.max(0, ms);
+    for (;;) {
+        if (signal?.aborted)
+            return;
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            return;
+        await sleep(Math.min(250, remaining));
+    }
+}
 /**
  * Run one tool-call turn:
  * generate → execute tools → feed results back → repeat until the model
@@ -617,6 +644,12 @@ async function runToolLoopInner(opts, progress) {
     // bounds how many times the turn may move.
     let emptyRetriesOnCurrentModel = 0;
     let modelHandoffs = 0;
+    // P5 — the empty-response patience plan for the CURRENT streak, asked for once
+    // (see `emptyResponsePatienceMs`) plus how many of its delays have been spent.
+    // `undefined` = not asked yet; an empty array = asked, and the caller granted
+    // nothing. Both are reset wherever the streak resets.
+    let emptyPatienceSchedule;
+    let emptyPatienceSpent = 0;
     // P3 — the ATTEMPT budget (see MAX_HANDOFF_ATTEMPT_CREDIT): step credit
     // granted by mid-turn handoffs, so a run against several dead models cannot
     // exhaust its road before it has done any work.
@@ -1056,7 +1089,7 @@ async function runToolLoopInner(opts, progress) {
                     if (digest)
                         upsertWorkDigest(thread, digest);
                 }
-                deps.onEvent?.(`   ✂️ ${trimmedResult.trimmed} old tool result(s) trimmed to fit the ${Math.round(budgetChars / 1000)}K-char context budget.`);
+                deps.onEvent?.(`   ✂️ ${trimmedResult.trimmed} message(s) trimmed to fit the ${Math.round(budgetChars / 1000)}K-char context budget.`);
             }
         }
         // ── The route feed, re-synced before every call ────────────────────────
@@ -1240,8 +1273,14 @@ async function runToolLoopInner(opts, progress) {
         // P2 — the model just produced something usable (text, or at least one tool
         // call), so its empty-response streak is over: a later blip starts a NEW
         // streak rather than inheriting one from twenty steps ago.
-        if (toolCalls.length > 0 || !responseThinkOnly)
+        if (toolCalls.length > 0 || !responseThinkOnly) {
             emptyRetriesOnCurrentModel = 0;
+            // P5 — a usable response ends the blink, so the next streak asks for a
+            // FRESH patience plan instead of inheriting spent patience from a step
+            // twenty turns of the loop ago.
+            emptyPatienceSchedule = undefined;
+            emptyPatienceSpent = 0;
+        }
         if (toolCalls.length === 0) {
             // No tools → end turn UNLESS the content is think-only (
             // isThinkOnlyResponse: continue instead of ending).
@@ -1262,6 +1301,66 @@ async function runToolLoopInner(opts, progress) {
                 // is the exact class of defect this work exists to remove, so the two
                 // cases are named apart even though they are bounded together.
                 const emptyResponse = response.content.trim().length === 0;
+                // ── P5 — WAIT OUT A BLINK ON THE PAIR THAT ANSWERED NOTHING ──────────
+                //
+                // An empty 200 is the one unusable response that never reaches the blip
+                // policy: `chat.generateWithTransientRetry` applies the empty-response
+                // schedule only when the attempt THROWS, and a provider that answers 200
+                // with no content does not throw — it lands here. So the policy has to be
+                // reachable from the loop too, or it is inert for exactly the failure it
+                // was written for. Both traces that motivated this did precisely that:
+                // two empties in a row, the loop's single retry spent, handoff, local last
+                // resort, weak answer (trace-1791906998502-txddq4,
+                // trace-1791907393457-7seewg).
+                //
+                // The caller decides how long to stay (see `emptyResponsePatienceMs`); the
+                // loop memoizes that answer per streak so a shifting plan cannot extend the
+                // wait, sleeps each granted delay, and re-asks the SAME pair. Cancelling
+                // mid-wait is honored.
+                if (emptyResponse && !opts.signal?.aborted) {
+                    if (emptyPatienceSchedule === undefined) {
+                        try {
+                            emptyPatienceSchedule = deps.emptyResponsePatienceMs?.({
+                                emptyStreak: emptyRetriesOnCurrentModel + 1,
+                                handoffs: modelHandoffs,
+                                deliveredWorkThisTurn: progress.successfulToolCalls.length > 0,
+                            }) ?? [];
+                        }
+                        catch {
+                            // A broken patience hook must neither extend nor block a turn.
+                            emptyPatienceSchedule = [];
+                        }
+                    }
+                    if (emptyPatienceSpent < emptyPatienceSchedule.length) {
+                        const waitMs = emptyPatienceSchedule[emptyPatienceSpent++];
+                        emptyRetriesOnCurrentModel += 1;
+                        thinkContinues = 0;
+                        // Name the pair generically when the route is unknown — a wrong name
+                        // would be worse than none (see `servedRoute`).
+                        let pairLabel = 'the same model';
+                        try {
+                            const route = opts.servedRoute?.();
+                            if (route?.model && !isUnresolvedModel(route.model)) {
+                                pairLabel = `${route.providerType}/${route.model}`;
+                            }
+                        }
+                        catch {
+                            // Unknown route reads generically.
+                        }
+                        if (waitMs > 0) {
+                            deps.onEvent?.(`   👀 ${pairLabel} returned nothing — waiting ${Math.round(waitMs / 100) / 10}s ` +
+                                `before re-asking it (blip patience ${emptyPatienceSpent}/${emptyPatienceSchedule.length}).`);
+                            await sleepUnlessAborted(waitMs, opts.signal);
+                        }
+                        traceEvent({
+                            kind: 'decision',
+                            gate: 'wait',
+                            summary: `the provider returned an empty response — waiting ${waitMs}ms and re-asking the SAME pair ` +
+                                `(blip patience ${emptyPatienceSpent}/${emptyPatienceSchedule.length}) instead of handing off`,
+                        });
+                        continue;
+                    }
+                }
                 // ── P2 — MID-TURN MODEL HANDOFF ────────────────────────────────────
                 // An empty completion is a PROVIDER failure, not a state of mind, and
                 // re-asking the model that just returned nothing is what killed a real
@@ -1288,6 +1387,43 @@ async function runToolLoopInner(opts, progress) {
                     }
                     if (switched) {
                         modelHandoffs += 1;
+                        // ── CONTEXT HANDOFF NOTE (Proposal 2, reassessed) ─────────────
+                        //
+                        // The CONTEXT already travels: one `thread` is kept across the
+                        // switch, so the replacement receives the ask, every tool call and
+                        // every result. What deliberately does NOT travel is the previous
+                        // model's `reasoningContent` (replaying a stranger's chain-of-
+                        // thought is either rejected outright or anchors the new model to
+                        // the failed reading of the task) — that stays dropped.
+                        //
+                        // What was missing is the plain STATEMENT of the handoff: a model
+                        // that starts mid-thread with no note reads the transcript as its
+                        // own and re-plans from the ask, re-running finished commands and
+                        // re-reading files whose results are already in front of it. The
+                        // note names the change, tells it the context is its own, and hands
+                        // it the facts (files changed, commands with their verdicts) so it
+                        // continues instead of restarting.
+                        let servedNow;
+                        try {
+                            const route = opts.servedRoute?.();
+                            if (route?.model && !isUnresolvedModel(route.model)) {
+                                servedNow = `${route.providerType}/${route.model}`;
+                            }
+                        }
+                        catch {
+                            // An unknown route is fine — the note reads generically then.
+                        }
+                        upsertHandoffNote(thread, buildHandoffNote({
+                            route: servedNow,
+                            facts: isWorkDigestEnabled(context.configManager)
+                                ? buildWorkDigest({
+                                    successfulTools: progress.successfulToolCalls,
+                                    mutatedPaths: progress.mutatedPaths,
+                                    executedActions: progress.executedActions,
+                                })
+                                : '',
+                        }));
+                        deps.onEvent?.('   🤝 handoff note written into the thread — the replacement model starts from the work already done.');
                         // ── C5 — RE-FIT THE THREAD TO THE MODEL THAT NOW ANSWERS ──────
                         // `budgetChars` was resolved before this loop started, from the pair
                         // the turn BEGAN on — and the handoff worth catching is the one to a
@@ -1311,6 +1447,10 @@ async function runToolLoopInner(opts, progress) {
                         // The streak and the think streak belong to the model that failed.
                         emptyRetriesOnCurrentModel = 0;
                         thinkContinues = 0;
+                        // P5 — the replacement pair gets its OWN plan, not the one granted to
+                        // (and half-spent on) the model that just returned nothing.
+                        emptyPatienceSchedule = undefined;
+                        emptyPatienceSpent = 0;
                         // ── DROP THE FAILED MODEL'S PRIVATE REASONING ─────────────────
                         // Every assistant turn records `reasoningContent`, and the wire
                         // layer echoes it back on that assistant message — which is
@@ -2091,7 +2231,17 @@ async function runToolLoopInner(opts, progress) {
             // outcome reading the same as its opposite — so the refusal classifier is
             // now the authority for both the event KIND and the success verdict.
             const refusal = classifyToolRefusal(rawResult);
+            // A command that outlived its wait budget is STILL RUNNING under
+            // monitoring: it has not verified anything yet, and it has not failed
+            // either. Neither verdict may be recorded for it — `successfulToolCalls`
+            // feeds the "did you check it" gate and the honest accounting, so counting
+            // a live run as a success is how a turn claims "the tests pass" about a
+            // suite still on its first file. The command's real verdict arrives when
+            // it lands, via `run_terminal(action:'poll')` — which is a normal success
+            // or `Error:` result and is accounted for like any other.
+            const stillRunning = rawResult.startsWith(RUN_TERMINAL_INCOMPLETE_PREFIX);
             const ranOk = refusal === null &&
+                !stillRunning &&
                 !rawResult.startsWith('Error:') &&
                 (!DELIVERY_TOOL_NAMES.has(call.name) || deliveryResultSucceeded(rawResult));
             if (ranOk) {
@@ -3771,16 +3921,127 @@ export const DEFAULT_THREAD_BUDGET_CHARS = 200_000;
 const RECENT_KEEP = 6;
 /** Stub left in place of a trimmed tool result. */
 const TRIM_STUB = '[earlier tool result trimmed to fit the context budget]';
+/**
+ * Floor for the per-message tool-result clamp (the tail clamp). A single tool
+ * result may never exceed half the thread budget, so one oversized output cannot
+ * dominate the prompt; this floor keeps the clamp sane for a tiny budget.
+ */
+const MIN_TOOL_RESULT_CHARS = 8_000;
+/**
+ * Bounded scan window for the clamp's error-line rescue. An elided middle can be
+ * megabytes, and scanning all of it would cost more CPU than the prompt costs
+ * tokens, so only the EDGES of the middle are searched. Nothing here is
+ * unrecoverable: a clipped result is re-runnable (`run_terminal` again) or
+ * re-readable (`read_file` with offset/limit), which the notice says out loud.
+ */
+const CLAMP_SCAN_CHARS = 250_000;
+/** Cap on rescued error-looking lines, and on the chars they may add back. */
+const CLAMP_ERROR_LINES = 12;
+const CLAMP_ERROR_CHARS = 2_000;
+/**
+ * A line that looks like the REASON something failed. Deliberately broad: one
+ * extra line costs a few tokens, while dropping the only line that says WHY the
+ * build broke costs a wrong fix built on a log the model never saw.
+ */
+const ERROR_LINE_RE = /\b(?:error|errors|fail|failed|failing|failure|exception|panic|fatal|traceback|assert|assertion|expected|received|refused|denied|unhandled|cannot|unable|timeout|enoent|econnrefused)\b|\btimed out\b|\bexit(?:ed)?(?: with)?(?: code)? [1-9]\d*\b|[✗✘✕]/i;
+/** `5234567` → `5,234,567` (deterministic grouping — no locale/ICU dependence). */
+function withThousands(n) {
+    return String(Math.max(0, Math.trunc(n))).replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+}
 /** Estimated character size of one thread message (chars/4 ≈ tokens). */
 function messageChars(m) {
     return (m.content?.length ?? 0) + (m.toolCalls?.length ? JSON.stringify(m.toolCalls).length : 0);
 }
+/**
+ * Rescue the error-looking lines from the MIDDLE of a result that is about to be
+ * clamped away. The clamp keeps head + tail, and a tool's verdict usually lands
+ * in the tail — but the REASON for a failure (an assertion, a stack frame, `exit
+ * code 1`) can sit in the middle, and a model that never sees it fixes the wrong
+ * thing. Deterministic: a line filter, no LLM, no summary, no drift.
+ */
+function errorLinesFrom(middle) {
+    const regions = middle.length <= CLAMP_SCAN_CHARS * 2
+        ? [middle]
+        : [middle.slice(0, CLAMP_SCAN_CHARS), middle.slice(-CLAMP_SCAN_CHARS)];
+    const out = [];
+    let used = 0;
+    for (const region of regions) {
+        for (const raw of region.split('\n')) {
+            const line = raw.trim();
+            if (!line)
+                continue;
+            // NO length filter. A tool's output rarely ends on a newline, so the tail
+            // cut lands MID-LINE and fuses the last real line with the kept tail —
+            // MEASURED: a 38-char `AssertionError: 2 !== 3 (received 3)` arrived here
+            // as 1,036 chars, and a `> 1000` skip dropped it, i.e. the rescue silently
+            // lost exactly the line it exists to save. Long lines are kept by their
+            // first 200 chars instead (an error keyword in a minified blob is still
+            // the start of the reason).
+            if (!ERROR_LINE_RE.test(line))
+                continue;
+            const kept = line.slice(0, 200);
+            if (out.includes(kept))
+                continue;
+            if (used + kept.length > CLAMP_ERROR_CHARS)
+                return out;
+            out.push(kept);
+            used += kept.length;
+            if (out.length >= CLAMP_ERROR_LINES)
+                return out;
+        }
+    }
+    return out;
+}
+/**
+ * The notice a clamp leaves behind: it names the tool, counts the elided
+ * characters and says how to get them back. A model handed a SILENTLY partial
+ * result cannot tell whether anything is missing; one handed a QUANTIFIED cut
+ * can re-run the command or re-read the file — far cheaper than a fix built on a
+ * log it never saw.
+ */
+function clampNotice(tool, elided, errorLines) {
+    const who = tool ? `${tool}: ` : '';
+    const rescued = errorLines.length > 0 ? '; the error-looking lines from the elided middle are kept below' : '';
+    return (`\n[tool result trimmed to fit the context budget — ${who}${withThousands(elided)} chars elided ` +
+        `from the middle${rescued}. The beginning and the end are kept verbatim; re-run the command, or ` +
+        `read the file again with offset/limit, to see the rest.]\n` +
+        (errorLines.length > 0 ? `${errorLines.join('\n')}\n` : ''));
+}
+/**
+ * Clamp one oversized tool result to `cap` chars, keeping its HEAD and TAIL so
+ * the model still sees which tool ran and how its output ended, plus any
+ * error-looking lines from the elided middle. Deterministic — no summary, no
+ * model call. The result never exceeds `cap`: the head absorbs what the notice
+ * and the rescued lines do not use.
+ */
+function clampToolResult(content, cap, tool) {
+    if (content.length <= cap)
+        return content;
+    const tailLen = Math.min(1_000, Math.floor(cap / 4));
+    const tailStart = Math.max(0, content.length - tailLen);
+    const middle = content.slice(0, tailStart);
+    const errors = errorLinesFrom(middle);
+    // Sized with the LARGEST possible elided count, so the exact (smaller) notice
+    // that follows can never push the result past `cap`.
+    const headLen = Math.max(0, cap - tailLen - clampNotice(tool, middle.length, errors).length);
+    const head = content.slice(0, headLen);
+    return head + clampNotice(tool, Math.max(0, middle.length - headLen), errors) + content.slice(tailStart);
+}
 /**
  * Deterministically trim a thread to `maxChars`:
  * 1. Never touch the system prompt or the FIRST user message (the ask).
- * 2. Never touch the last `RECENT_KEEP` messages (recent context).
- * 3. Oldest-first: tool results longer than 500 chars collapse to the stub;
- *    if still over budget, remaining old tool results collapse entirely.
+ * 2. Never touch the last `RECENT_KEEP` messages (recent context) — except for
+ *    the tail clamps in steps 4–5, which run ONLY when the oldest-first passes
+ *    could not pay for the overage.
+ * 3. Oldest-first pays FIRST, and only as much as the deficit needs: tool
+ *    results longer than 500 chars collapse to the stub; if still over budget,
+ *    remaining old tool results collapse entirely; then oversized old user
+ *    messages shrink.
+ * 4. Only if the thread is STILL over does the protected tail pay: an oversized
+ *    recent tool result is clamped to head + rescued error lines + tail, and
+ *    then clamped harder, so the prompt actually fits the window it goes to.
+ *    The ORDER is what protects delivery: recent context is the model's working
+ *    memory, so it is spent only when nothing older can cover the overage.
  * Returns a NEW array (input untouched) + how many messages were trimmed.
  */
 export function trimThreadBudget(thread, maxChars = DEFAULT_THREAD_BUDGET_CHARS) {
@@ -3801,6 +4062,9 @@ export function trimThreadBudget(thread, maxChars = DEFAULT_THREAD_BUDGET_CHARS)
     }
     let over = total - maxChars;
     let trimmed = 0;
+    // A single result may never exceed half the budget, whatever the passes below
+    // do (see MIN_TOOL_RESULT_CHARS).
+    const perMessageCap = Math.max(MIN_TOOL_RESULT_CHARS, Math.floor(maxChars / 2));
     // Pass 1: collapse long OLD tool results to the stub (keep the first 500
     // chars so the model retains the gist of what it did).
     for (const i of eligible) {
@@ -3848,6 +4112,66 @@ export function trimThreadBudget(thread, maxChars = DEFAULT_THREAD_BUDGET_CHARS)
             trimmed++;
         }
     }
+    // ── Pass 4 — only NOW does the PROTECTED TAIL pay ─────────────────────────
+    // Nothing older could cover the deficit, so an oversized RECENT tool result
+    // must be clamped — otherwise the prompt goes out verbatim and either the
+    // provider rejects it or the model silently loses its middle.
+    //
+    // MEASURED (trace-1791879575576-x731yp): step 4 ran a 24s test command; its
+    // result landed in the tail, the oldest-first passes could not reach it, and
+    // step 5 — handed to `local/qwen2.5:0.5b` (32K window) — recorded 5,292,237
+    // context chars (~1.18M tokens), carried into the dashboard and cost ledger
+    // as REAL input. Running this pass here (rather than before the oldest-first
+    // passes) is deliberate: recent context is the model's working memory, so it
+    // is spent only when older output cannot pay for the overage.
+    // A tool message carries only the call ID, so the notice's tool name comes
+    // from the assistant message that made the call. Built lazily: a turn whose
+    // thread fits never walks the thread for names it will not print.
+    const toolNameById = new Map();
+    const toolNameOf = (m) => {
+        if (!m.toolCallId)
+            return undefined;
+        if (toolNameById.size === 0) {
+            for (const t of thread) {
+                for (const call of t.toolCalls ?? []) {
+                    if (call?.id)
+                        toolNameById.set(call.id, call.name);
+                }
+            }
+        }
+        return toolNameById.get(m.toolCallId);
+    };
+    if (over > 0) {
+        for (let i = Math.max(0, out.length - RECENT_KEEP); i < out.length && over > 0; i++) {
+            const m = out[i];
+            if (m.role !== 'tool' || m.content.length <= perMessageCap)
+                continue;
+            const clamped = clampToolResult(m.content, perMessageCap, toolNameOf(m));
+            if (clamped.length >= m.content.length)
+                continue;
+            out[i] = { ...m, content: clamped };
+            over -= m.content.length - clamped.length;
+            trimmed++;
+        }
+    }
+    // Pass 5: STILL over — the protected tail holds the bulk even after the clamp
+    // above; clamp its tool results harder rather than ship a prompt the model's
+    // window cannot hold. Only TOOL results in the tail are touched — the user's
+    // ask and the latest assistant turn stay.
+    if (over > 0) {
+        const tailFloor = Math.max(500, Math.floor(perMessageCap / 4));
+        for (let i = Math.max(0, out.length - RECENT_KEEP); i < out.length && over > 0; i++) {
+            const m = out[i];
+            if (m.role !== 'tool')
+                continue;
+            const clamped = clampToolResult(m.content, tailFloor, toolNameOf(m));
+            if (clamped.length >= m.content.length)
+                continue;
+            out[i] = { ...m, content: clamped };
+            over -= m.content.length - clamped.length;
+            trimmed++;
+        }
+    }
     return { thread: out, trimmed };
 }
 // ─── Within-turn work digest (the memory a trimmed thread keeps) ────────────
@@ -3895,6 +4219,51 @@ export function buildWorkDigest(input) {
         return '';
     return `${WORK_DIGEST_MARKER}\n${lines.join('\n')}`;
 }
+/** Marker prefix identifying the loop's mid-turn HANDOFF note. */
+export const HANDOFF_NOTE_MARKER = '[handoff — the model serving this turn changed]';
+/**
+ * The note a mid-turn model switch leaves in the thread.
+ *
+ * It says three things the TRANSCRIPT cannot say by itself: that the pair
+ * answering this step is not the pair that answered the previous ones, that the
+ * context above is genuinely this model's to use (nothing was restarted), and
+ * which work is already DONE (files changed, commands and their verdicts) — so
+ * the replacement continues instead of re-deriving a plan from the ask. It also
+ * states the rule that costs real steps when broken: do not re-run finished
+ * commands or restate the work in more words.
+ *
+ * Deterministic and LLM-free, like the digest it borrows its facts from — a
+ * handoff must not spend a model call to describe itself.
+ */
+export function buildHandoffNote(input) {
+    const served = input.route
+        ? ` This step is served by ${input.route}.`
+        : ' This step is served by a different model.';
+    const facts = (input.facts ?? '').trim();
+    return (`${HANDOFF_NOTE_MARKER}${served}\n` +
+        'The pair that had been answering returned nothing usable, so the turn was handed to you mid-flight —\n' +
+        'everything above is YOUR context: the ask, every tool call and every result. Nothing was restarted.\n' +
+        (facts ? `${facts}\n` : '') +
+        'Continue from the work that is already done. Do not re-run finished commands, re-read files whose results\n' +
+        'are above, or restate the work in more words.');
+}
+/**
+ * Insert or refresh the single handoff note. Idempotent — a turn may hand off
+ * more than once (a second pair can also answer with nothing), and stacking a
+ * note per handoff would fill the thread with the same information. Kept with
+ * the run's framing (right after the leading system prompt) so it is a `system`
+ * message: the thread-budget passes never trim one, and it therefore survives
+ * every compaction between the handoff and the answer.
+ */
+export function upsertHandoffNote(thread, note) {
+    const existing = thread.findIndex((m) => m.content.startsWith(HANDOFF_NOTE_MARKER));
+    if (existing !== -1) {
+        thread[existing] = { ...thread[existing], content: note };
+        return;
+    }
+    const insertAt = thread.length > 0 && thread[0].role === 'system' ? 1 : 0;
+    thread.splice(insertAt, 0, { role: 'system', content: note });
+}
 /**
  * Insert or refresh the single work-digest message. Idempotent: a digest already
  * in the thread is UPDATED in place, never stacked, so repeated compaction in a