acuvo-code 0.6.1 → 0.6.3

package/bin/acuvo.mjs

@@ -61,7 +61,7 @@ import { detectRepo, findToken, fetchIssue, branchNameFor, issueToTask, createBr
 // `formatSummary`'s job, and importing it here is how the second copy came back.
 import { describeChanges, shortenRoot, toJson } from '../lib/report.mjs';
 import { renderImage } from '../lib/terminal-graphics.mjs';
-import { saveSession, listSessions, resumeMessages, loadSession } from '../lib/session.mjs';
+import { saveSession, listSessions, resumeMessages, loadSession, newSessionId, findCrashedSession, crashOfferLines, markSessionClosed } from '../lib/session.mjs';
 import { recordRun, parseAuditLog } from '../lib/audit.mjs';
 import { runBestOf, formatBestOf } from '../lib/best-of.mjs';
 import { escalate, formatEscalation, outOfRoad } from '../lib/escalate.mjs';
@@ -1612,6 +1612,84 @@ ${formatBoard(listed)}
     process.on('exit', () => { try { if (claimed?.lease) releaseAll([claimed.lease]); } catch { /* exiting anyway */ } });
   }
 
+  /**
+   * ── ⭐⭐⭐ "IF MY LAPTOP CRASHES, THE CHAT HISTORY IS GONE" ─────────────────
+   *
+   * ⚠️ IT WAS. MEASURED 2026-08-22: a run killed with SIGKILL after two
+   * completed rounds and two files written left `.acuvo/sessions/` NON-EXISTENT.
+   * `saveSession` only ever ran after the loop, so the run you most want back
+   * was the only kind that left nothing behind. The checkpoint wiring in
+   * `oneTurn` fixed the WRITE half; this is the READ half, and without it the
+   * recovery only exists for someone who already knows to type `--continue` —
+   * which is not the person who just lost their work.
+   *
+   * ⚠️⚠️ IT MUST NEVER FIRE FOR A RUN THAT IS STILL GOING. Seven terminals in
+   * one workspace is the documented normal case for this tool, and each one
+   * holds an open live record. `findCrashedSession` refuses any record whose pid
+   * still answers — see its header for the other two conditions.
+   *
+   * ⭐ ACCEPTING IT REUSES `--resume` WHOLE. The offer sets an id and the
+   * existing block below does the rest, so the restored conversation, the sticky
+   * routing key and the budget subtraction are the same code on both doors. A
+   * second copy of that block is how one of the two would end up without the
+   * budget guard.
+   *
+   * ⚠️ THE PROMPT IS TTY-ONLY. A CI job, a `| jq` pipeline or a cron entry must
+   * never block on a question nobody is there to answer — those get the lines
+   * and the command, and carry on with the fresh run they asked for.
+   */
+  let crashOfferId = null;
+  /**
+   * ⚠️ `opts.bestOf < 2` FOR THE SAME REASON `--best-of` REFUSES `--resume`
+   * outright: it forks the task into independent attempts and keeps one, so
+   * accepting a restored conversation here would silently discard the history
+   * the user had just said yes to. Offering something we would then throw away
+   * is worse than not offering.
+   */
+  if (!resumeRequested && !opts.parallel && opts.issue === null && !opts.dryRun && life.save && opts.bestOf < 2) {
+    let found = { ok: false };
+    try { found = findCrashedSession(root); } catch { /* a recovery hint may never break a run */ }
+    if (found.ok && found.crashed) {
+      const say = (t) => (opts.json ? process.stderr : process.stdout).write(t);
+      say(`${crashOfferLines(found.crashed).join('\n')}\n`);
+      const askable = process.stdin.isTTY === true && process.stdout.isTTY === true && !opts.json;
+      if (askable) {
+        const rl = createInterface({ input: process.stdin, output: process.stderr, terminal: true });
+        const answer = await new Promise((r) => rl.question('    continue that conversation instead of starting fresh? [Y/n] ', (l) => { rl.close(); r(l); }));
+        /**
+         * ⚠️ ENTER MEANS YES HERE, WHICH IS THE OPPOSITE OF `--task-audio`'s
+         * default, and the difference is deliberate: that prompt guards an
+         * ACTION taken on a possibly mis-heard instruction, so silence must
+         * cancel. This one guards CONTEXT the user already paid for, and
+         * nothing is executed by restoring it — the expensive mistake is
+         * throwing the conversation away, not keeping it.
+         */
+        if (!/^\s*n(o)?\s*$/i.test(answer)) crashOfferId = found.crashed.id;
+        else say('    starting fresh. That run stays on disk — `acuvo --sessions` lists it.\n');
+      }
+      /**
+       * ⚠️⚠️ ANSWERED IS ANSWERED — INCLUDING "I ONLY PRINTED IT". The marker
+       * lives in the record, so without this line the same warning fires on
+       * every subsequent run in this workspace, for ever, and a warning that
+       * fires when nothing is wrong is one people learn to read past. That would
+       * cost the real one.
+       *
+       * ⚠️ NOT ON ACCEPT, AND THE ORDER IS THE REASON. `resumeMessages` reads
+       * `closedCleanly` to tell the model "that run was KILLED mid-round, its
+       * last round may be missing but its work may be on disk". Closing the
+       * record here would erase that sentence a few lines before it is written.
+       * The resume block below marks it once it has been read.
+       *
+       * ⭐ NOTHING IS DELETED EITHER WAY. The record stays listable, replayable
+       * and `--resume <id>`-able; it just stops volunteering — exactly what the
+       * decline message above promises.
+       */
+      if (!crashOfferId) {
+        try { markSessionClosed(root, found.crashed.id); } catch { /* the offer already did its job */ }
+      }
+    }
+  }
+
   let priorMessages = null;
   /**
    * ── ⭐⭐⭐ ONE STICKY KEY FOR THIS WHOLE CONVERSATION, ACROSS PROCESSES ────
@@ -1629,7 +1707,7 @@ ${formatBoard(listed)}
    * the conversation being resumed had already paid to build.
    */
   let stickyKey = `acuvo-${randomUUID()}`;
-  if (resumeRequested) {
+  if (resumeRequested || crashOfferId) {
     if (life.resume !== null && life.continueLatest) {
       die('--resume <id> and --continue both name a run to carry on, and they disagree. Pass one: --continue takes the most recent, --resume takes the id you name.', EXIT_USAGE);
     }
@@ -1640,7 +1718,10 @@ ${formatBoard(listed)}
       die('--issue starts a fresh branch and a fresh conversation, so there is nothing to resume. Drop one of --issue / --resume.', EXIT_USAGE);
     }
 
-    let id = life.resume;
+    // ⚠️ `crashOfferId` is only ever set when NEITHER flag was given (the guard
+    // above requires `!resumeRequested`), so this cannot silently outrank a
+    // `--resume <id>` the user typed.
+    let id = life.resume ?? crashOfferId;
     if (life.continueLatest) {
       const listed = listSessions(root, { limit: 50 });
       if (!listed.ok) die(listed.error, EXIT_FAILED);
@@ -1663,6 +1744,16 @@ ${formatBoard(listed)}
     // ⭐ The saved id IS the conversation, so it is the routing key too. This
     // line is what makes stickiness survive closing the terminal.
     stickyKey = `acuvo-${resumed.id ?? id}`;
+    /**
+     * ⚠️ AFTER `resumeMessages`, NEVER BEFORE — it reads the crash marker to
+     * tell the model that run was killed mid-round. Carrying the conversation
+     * forward is what closes the book on the old record: this run now owns the
+     * history, so the old one must stop announcing itself as unfinished on every
+     * future `acuvo` in this workspace.
+     */
+    if (resumed.crashed) {
+      try { markSessionClosed(root, resumed.id ?? id); } catch { /* the resume already succeeded */ }
+    }
     if (!task) task = resumed.task;
     if (!task) {
       die(`run ${resumed.id} recorded no task text, so "carry on" has nothing to carry. Say what to do next: acuvo --resume ${resumed.id} "<the next step>"`, EXIT_USAGE);
@@ -1672,6 +1763,24 @@ ${formatBoard(listed)}
     (opts.json ? process.stderr : process.stdout).write(
       `  · resuming ${resumed.id} — ${priorMessages.length} messages restored, nothing re-run${warn}\n`,
     );
+    /**
+     * ── ⚠️ SAY IT WHEN THE DISCOUNT IS GONE ──────────────────────────────────
+     *
+     * The first two messages ARE the cacheable prefix. A record whose head was
+     * clipped resumes into a prompt that differs from the original at message
+     * ZERO, so prefix caching misses on every token — measured at 60.8%
+     * byte-identical before `MAX_HEAD_CHARS` gave the head its own ceiling, i.e.
+     * the whole restored conversation re-bought at full price.
+     *
+     * ⚠️ It is silent on every ordinary resume, which is what makes it worth
+     * printing at all: this fires only on a head above 60,000 characters, and
+     * somebody seeing it needs to know the resume is honest but not cheap.
+     */
+    if (resumed.headTruncated) {
+      (opts.json ? process.stderr : process.stdout).write(
+        '    ⚠ that record\'s opening message was too large to store whole, so the prompt cache cannot hit on this resume — expect it to cost like a fresh run.\n',
+      );
+    }
 
     /**
      * ── ⚠️⚠️ A RESUMED RUN USED TO GET A WHOLE FRESH BUDGET ──────────────────
@@ -1845,6 +1954,22 @@ ${formatBoard(listed)}
       },
     });
 
+    /**
+     * ── ⭐⭐⭐ THE ID THIS TURN WILL BE SAVED UNDER, DECIDED BEFORE IT STARTS ──
+     *
+     * ⚠️ MEASURED, WHICH IS WHY IT IS HERE: a run SIGKILLed mid-round left NO
+     * `.acuvo/sessions/` directory at all — every save happened after the loop,
+     * so the run whose conversation you would most want back was the only kind
+     * that left none. The checkpoints below write the same record the end of the
+     * turn writes, under this id, marked `live` until the turn closes it.
+     *
+     * ⚠️ `--dry-run` AND `--no-session` MUST BE HONOURED HERE TOO, not only in
+     * `persistRun`. A dry run that scattered eight session files while promising
+     * to "touch nothing" is the same broken promise, arrived at from a new door.
+     */
+    const turnSessionId = newSessionId();
+    const checkpointing = life.save && !opts.dryRun && !over.quiet;
+
     let result;
     try {
       result = await runSession({
@@ -1947,6 +2072,26 @@ ${formatBoard(listed)}
       untilDone: opts.untilDone,
       // ⭐ The admin layer reaches the loop. OPEN_POLICY when no file exists.
       policy,
+      /**
+       * ── ⭐⭐⭐ THE WIRE THAT MAKES A KILLED RUN RECOVERABLE ──────────────────
+       *
+       * `runSession` calls this at every round boundary with the same shape it
+       * returns at the end, so `saveSession` is the whole implementation —
+       * there is one definition of a session record, not a live one and a final
+       * one that drift apart the first time either grows a field.
+       *
+       * ⚠️ IT SWALLOWS ITS OWN FAILURES ON PURPOSE, and this is the one place in
+       * this file that does so silently. `persistRun` announces a failed save
+       * because that is the last word on a finished run; announcing a failed
+       * CHECKPOINT would print the same line once per round for the rest of a
+       * long run, which is how people learn to read past the line that matters.
+       * The end-of-turn save hits the same disk and will say so.
+       */
+      onCheckpoint: checkpointing
+        ? (partial) => {
+            try { saveSession(root, partial, { task: turnTask, id: turnSessionId, live: true }); } catch { /* the work outranks the record */ }
+          }
+        : null,
       // ⚠️ STREAMED, NOT BUFFERED. A bounded loop that prints only at the end is
       // indistinguishable from a hang for however long it takes, and the whole
       // value of watching a fix land is watching it land.
@@ -2080,7 +2225,13 @@ ${formatBoard(listed)}
        */
       gate.dispose();
     }
-    persistRun(turnTask, result);
+    /**
+     * ⚠️ THE SAME ID THE CHECKPOINTS USED — this call is what flips
+     * `closedCleanly` to true. Passing a fresh id here would leave the live
+     * record open forever, and the next `acuvo` in this workspace would offer to
+     * recover a run that finished perfectly well.
+     */
+    persistRun(turnTask, result, turnSessionId);
     /**
      * ── ⭐ `--say` — NARRATE THE VERDICT ──────────────────────────────────────
      *
@@ -2216,11 +2367,26 @@ ${formatBoard(listed)}
    *    dry run that creates two files in the workspace has broken that promise
    *    to save a record of a run that did not happen.
    */
-  const persistRun = (turnTask, result) => {
+  /**
+   * ── ⭐⭐⭐ ONE ID PER TURN, SHARED BY THE LIVE SAVES AND THE FINAL ONE ──────
+   *
+   * ⚠️ WITHOUT THIS THE CRASH RECOVERY WOULD LITTER. `saveSession` mints a fresh
+   * id whenever it is not given one, so checkpointing each round would leave
+   * eight files for one turn and the finished record would be a ninth — and the
+   * eight orphans would all still carry `closedCleanly: false`, so every one of
+   * them would look like a crash to the startup check. Handing the same id to
+   * every write means one file per turn, exactly as before, whose only new
+   * content is a boolean that flips true when the turn ends.
+   *
+   * ⚠️ MINTED PER TURN, NOT PER PROCESS: interactive mode runs many turns and
+   * has always written one record each. Sharing one id across a conversation
+   * would collapse the whole history into a single overwritten file.
+   */
+  const persistRun = (turnTask, result, id = null) => {
     if (opts.dryRun) return;
     if (life.save) {
       try {
-        const saved = saveSession(root, result, { task: turnTask });
+        const saved = saveSession(root, result, { task: turnTask, ...(id ? { id } : {}) });
         if (!saved.ok) process.stderr.write(`  · the run was not saved: ${saved.error}\n`);
       } catch (e) {
         process.stderr.write(`  · the run was not saved: ${e?.message ?? e}\n`);

package/lib/chat.mjs

@@ -370,7 +370,7 @@ export async function runChat({
    * Pressed against the banner it read as a fifth detail row rather than as an
    * instruction addressed to the person.
    */
-  output.write('\nType what you want done. "/help" for commands, "exit" to leave.\n\n');
+  const writeInvitation = () => output.write('\nType what you want done. "/help" for commands, "exit" to leave.\n\n');
 
   let history = null;
   let turns = 0;
@@ -412,6 +412,12 @@ export async function runChat({
    * scrollback in existence runs.
    */
   writeBanner();
+  /**
+   * ⚠️ AFTER THE BANNER, AND IT WAS PRINTING BEFORE IT. The invitation is
+   * addressed to somebody who has just read the banner; printed above it, it is
+   * an instruction for a screen they have not seen yet.
+   */
+  writeInvitation();
 
   try {
     for (;;) {

package/lib/input-box.mjs

@@ -489,9 +489,34 @@ export function readBoxedLine({ input, output, history = [], onInterrupt = null,
  */
 export function pinRegion(output, { rows = 2, env = process.env } = {}) {
   const height = output?.rows ?? process.stdout?.rows ?? 0;
+  /**
+   * ── ⚠️⚠️⚠️ OFF BY DEFAULT. THREE ATTEMPTS, THREE DIFFERENT WRONG RESULTS ────
+   *
+   * Roman, across three builds: "you have to scroll down to see the prompt" —
+   * then, after the clear was fixed — "now it's just the box, everything else
+   * is gone."
+   *
+   * The write ORDER is provably correct (traced: clear, region, banner at row 1,
+   * input at the last two rows). It still renders wrong in his terminal, and a
+   * scroll region is a claim on somebody's whole screen that behaves differently
+   * in VS Code, Windows Terminal and cmd.exe. I cannot verify it in the terminal
+   * that matters from here, and shipping a fourth guess at somebody's display is
+   * worse than not having the feature.
+   *
+   * ⭐ AND THE SIMPLE VERSION GETS THE ACTUAL REQUIREMENT. Without a region the
+   * input is simply the LAST THING WRITTEN each turn, and every terminal
+   * auto-scrolls to its newest output — so it is always at the bottom of what
+   * you are looking at, always visible, with the transcript above it. That is
+   * what "stuck down the bottom" needs to mean; welding it to a physical screen
+   * row was my addition, not the requirement.
+   *
+   * ⚠️ KEPT, NOT DELETED, and still fully tested — `ACUVO_PIN=1` turns it on.
+   * The mechanism is correct and worth having once it can be verified in a real
+   * VS Code terminal rather than inferred from a byte trace.
+   */
   const enabled = Boolean(output?.isTTY)
     && height > rows + 4
-    && String(env.ACUVO_NO_PIN ?? '') !== '1'
+    && String(env.ACUVO_PIN ?? '') === '1'
     && String(env.CI ?? '').toLowerCase() !== 'true';
 
   if (!enabled) return { enabled: false, release() {}, rows: 0, bottom: 0 };
@@ -528,7 +553,26 @@ export function pinRegion(output, { rows = 2, env = process.env } = {}) {
    * screen. Both are needed and the order matters: erase the history, erase the
    * screen, then home.
    */
-  output.write(`${CSI}3J${CSI}2J${CSI}1;${bottom}r${CSI}1;1H`);
+  /**
+   * ── ⚠️⚠️ THE CANONICAL CLEAR, IN THE CANONICAL ORDER — TWICE WRONG BEFORE ──
+   *
+   * Roman, twice: *"you have to scroll down to see the prompt area."*
+   *
+   * What `clear` itself emits is `ESC[H ESC[2J ESC[3J` — HOME FIRST, then erase
+   * the screen, then erase the scrollback. I had `3J 2J` with the home last, and
+   * the order is not cosmetic: erasing scrollback while the cursor is still
+   * parked in it leaves the viewport anchored to a region that no longer exists,
+   * so the terminal keeps showing the old shell output and our banner and prompt
+   * sit below the fold.
+   *
+   * ⭐ HOME FIRST puts the viewport at the top of the buffer BEFORE anything is
+   * erased, so there is nowhere stale for it to stay.
+   *
+   * ⚠️ AND THE SCROLL REGION IS SET LAST. Setting a region while the cursor is
+   * outside it is undefined across terminals — some clamp, some ignore it. Clear
+   * completely, then declare the region, then place the cursor inside it.
+   */
+  output.write(`${CSI}H${CSI}2J${CSI}3J${CSI}1;${bottom}r${CSI}1;1H`);
 
   const release = () => {
     if (released) return;

package/lib/session.mjs

@@ -83,7 +83,7 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync,
 import { dirname } from 'node:path';
 
 import { resolveInWorkspace } from './workspace.mjs';
-import { refusedCommitPath } from './secret-paths.mjs';
+import { refusedCommitPath } from './secret-paths.mjs';
 import { ensureAcuvoDirIgnored } from './acuvo-dir.mjs';
 
 /** Scratch, alongside `plan.json`, `mcp.json` and the screenshots `see_page`
@@ -101,6 +101,43 @@ export const MAX_SESSIONS = 20;
 /** Per-message ceiling. A single `read_file` of a 200KB source file would
  *  otherwise be most of the budget on its own. */
 export const MAX_MESSAGE_CHARS = 8_000;
+/**
+ * ── ⚠️⚠️ THE HEAD GETS ITS OWN CEILING, AND THE OLD ONE WAS A CACHE BUG ─────
+ *
+ * MEASURED 2026-08-22 on a real run against a stub provider, not reasoned about:
+ *
+ *     live system message   12,118 chars
+ *     saved system message   8,117 chars   ← MAX_MESSAGE_CHARS + the truncation note
+ *
+ * `MAX_MESSAGE_CHARS` was applied to EVERY message including the system one, so
+ * a `--resume` handed the provider a prompt that diverged from the original at
+ * **character 8,121 of message zero**. Measured end to end (original round-2
+ * payload vs resumed round-1 payload): the byte-identical common prefix was
+ * **60.8%**, and prefix caching matches from the first token and stops at the
+ * first difference — so the divergence being inside message 0 means the WHOLE
+ * restored conversation was re-bought at full price. `lib/chat.mjs` puts the
+ * value of that prefix at 97.2% cached / 4.3x cheaper; this threw all of it
+ * away, silently, on the one code path whose entire justification is not paying
+ * twice for work already done.
+ *
+ * ⚠️ AND THE MONEY IS THE SMALLER HALF. The 4,118 characters that fell off the
+ * end of that system message were the SKILLS BLOCK — so a resumed model was
+ * reasoning under rules it had never been shown, which is exactly the failure
+ * `compact.mjs`'s header names ("the resumed model starts reasoning about
+ * instructions it was never given").
+ *
+ * ⭐ SO THE HEAD IS CAPPED SEPARATELY AND GENEROUSLY. It is bounded by
+ * construction anyway — the system message is a prompt this package assembles,
+ * and the first user message is `repo-map.mjs`'s output, which has its own
+ * budget. 60,000 is ~5x the largest head observed and still a quarter of
+ * MAX_SESSION_BYTES, so the file cap below stays the real bound.
+ *
+ * ⚠️ IT IS A CAP, NOT AN EXEMPTION. A head that somehow exceeds it is still
+ * truncated rather than allowed to blow the file limit — but the record then
+ * carries `headTruncated: true` so `resumeMessages` can SAY the cache will miss
+ * instead of letting someone believe they got the discount.
+ */
+export const MAX_HEAD_CHARS = 60_000;
 export const MAX_TASK_CHARS = 400;
 /** The metadata lists are for a HUMAN reading `--sessions`, so they are short
  *  by intent — the full detail is in the messages. */
@@ -399,23 +436,68 @@ const WITHHELD =
   '[withheld: this tool call touched a credential file, so its contents were not saved with the session. '
   + 'Read the file again in this run if you need it.]';
 
+/**
+ * The keys a saved message may carry, in the order this module falls back to
+ * when the source message does not state one of its own.
+ *
+ * ⚠️ `role` IS PINNED FIRST AND THE REST FOLLOW THE SOURCE — see `orderedKeys`.
+ */
+const MESSAGE_KEYS = ['role', 'content', 'name', 'tool_call_id', 'tool_calls'];
+
+/**
+ * ── ⚠️⭐ THE SAVED MESSAGE MUST SERIALISE IN THE ORDER THE LIVE ONE DID ──────
+ *
+ * MEASURED 2026-08-22, on the end-to-end crash-and-resume run this file exists
+ * for. With the head truncation fixed the restored prompt matched the original
+ * for 13,305 of 13,700 characters — and then diverged, on this:
+ *
+ *     live  : {"role":"tool","tool_call_id":"c_write_file","name":…,"content":…}
+ *     saved : {"role":"tool","content":…,"name":…,"tool_call_id":"c_write_file"}
+ *
+ * Same message, same bytes of meaning, different JSON. `turn.mjs` pushes tool
+ * replies as `{role, tool_call_id, name, content}`; this function rebuilt them
+ * as `{role, content, name, tool_call_id}` because that is the order the code
+ * happened to assign in. Nothing was lost and nothing was wrong — the payload
+ * simply stopped being byte-identical at the first tool result, which is round
+ * one of every real session.
+ *
+ * ⭐ SO THE SOURCE'S OWN KEY ORDER IS PRESERVED. Reading `Object.keys(message)`
+ * costs nothing and makes the property hold for message shapes this module has
+ * not been taught about yet, which an explicit hand-written order would not.
+ * `role` is forced first because a `tool_calls`-only object would otherwise
+ * bury it, and every consumer reads `role` first.
+ */
+function orderedKeys(message) {
+  const seen = new Set(['role']);
+  const keys = ['role'];
+  for (const k of Object.keys(message ?? {})) {
+    if (!MESSAGE_KEYS.includes(k) || seen.has(k)) continue;
+    seen.add(k);
+    keys.push(k);
+  }
+  // Anything the source did not name (or named in a shape we skipped) still has
+  // to be emitted if we produce a value for it — appended, never interleaved.
+  for (const k of MESSAGE_KEYS) if (!seen.has(k)) { seen.add(k); keys.push(k); }
+  return keys;
+}
+
 /**
  * Scrub and cap one message. Returns a NEW object — the caller's array belongs
  * to a live session that may still be in use, and mutating it here would edit
  * the conversation a running loop is about to send.
  */
 function sanitizeMessage(message, { withhold = false, maxChars = MAX_MESSAGE_CHARS } = {}) {
-  const out = { role: message?.role };
+  const value = {};
   let redactions = 0;
 
   if (typeof message?.content === 'string') {
     if (withhold) {
-      out.content = WITHHELD;
+      value.content = WITHHELD;
       redactions += 1;
     } else {
       const r = redactSecrets(message.content);
       redactions += r.redactions;
-      out.content = truncate(r.text, maxChars);
+      value.content = truncate(r.text, maxChars);
     }
   } else if (message?.content !== undefined) {
     // Non-string content (an array of parts, from a multimodal round). Keep the
@@ -423,14 +505,14 @@ function sanitizeMessage(message, { withhold = false, maxChars = MAX_MESSAGE_CHA
     // assistant message is another way to earn a 400.
     const r = redactSecrets(JSON.stringify(message.content));
     redactions += r.redactions;
-    out.content = truncate(r.text, maxChars);
+    value.content = truncate(r.text, maxChars);
   }
 
-  if (typeof message?.name === 'string') out.name = message.name;
-  if (typeof message?.tool_call_id === 'string') out.tool_call_id = message.tool_call_id;
+  if (typeof message?.name === 'string') value.name = message.name;
+  if (typeof message?.tool_call_id === 'string') value.tool_call_id = message.tool_call_id;
 
   if (Array.isArray(message?.tool_calls)) {
-    out.tool_calls = message.tool_calls.map((call) => {
+    value.tool_calls = message.tool_calls.map((call) => {
       const raw = String(call?.function?.arguments ?? '{}');
       // ⚠️ The ARGUMENTS of a write_file to `.env` contain the file body. The
       // reply is not the only place a credential lives.
@@ -450,6 +532,12 @@ function sanitizeMessage(message, { withhold = false, maxChars = MAX_MESSAGE_CHA
       };
     });
   }
+
+  const out = {};
+  for (const key of orderedKeys(message)) {
+    if (key === 'role') { out.role = message?.role; continue; }
+    if (value[key] !== undefined) out[key] = value[key];
+  }
   return { message: out, redactions };
 }
 
@@ -475,15 +563,25 @@ function isCredentialCall(call) {
  */
 export function sanitizeMessages(messages, { maxBytes = MAX_SESSION_BYTES, maxChars = MAX_MESSAGE_CHARS } = {}) {
   if (!Array.isArray(messages) || messages.length === 0) {
-    return { messages: [], redactions: 0, droppedGroups: 0, droppedIncomplete: 0, truncated: false };
+    return { messages: [], redactions: 0, droppedGroups: 0, droppedIncomplete: 0, truncated: false, headTruncated: false };
   }
   const { head, groups } = groupMessages(messages);
   const pruned = dropDanglingCalls(groups);
 
   let redactions = 0;
+  /**
+   * ⭐ THE HEAD IS THE CACHEABLE PREFIX, so it is capped at MAX_HEAD_CHARS and
+   * not at the per-message ceiling — see MAX_HEAD_CHARS for the measurement that
+   * forced this apart. `headTruncated` is reported rather than hidden: a resume
+   * whose first message was clipped cannot hit the prompt cache, and the person
+   * paying for it is entitled to know that before the bill.
+   */
+  let headTruncated = false;
+  const headCap = Math.max(maxChars, MAX_HEAD_CHARS);
   const cleanHead = head.map((m) => {
-    const s = sanitizeMessage(m, { maxChars });
+    const s = sanitizeMessage(m, { maxChars: headCap });
     redactions += s.redactions;
+    if (typeof m?.content === 'string' && m.content.length > headCap) headTruncated = true;
     return s.message;
   });
   const cleanGroups = pruned.groups.map((group) => {
@@ -530,6 +628,7 @@ export function sanitizeMessages(messages, { maxBytes = MAX_SESSION_BYTES, maxCh
     droppedGroups,
     droppedIncomplete: pruned.dropped,
     truncated: droppedGroups > 0,
+    headTruncated,
   };
 }
 
@@ -600,9 +699,30 @@ function extractActivity(executed) {
  * A failed session is saved and listable; it is simply not RESUMABLE, and the
  * record says so rather than leaving the caller to infer it.
  *
+ * ── ⭐⭐⭐ `meta.live` — THE HALF THAT SURVIVES A LAPTOP DYING ────────────────
+ *
+ * MEASURED 2026-08-22 before this existed: a run was SIGKILLed mid-round after
+ * two completed rounds and two files written, and `.acuvo/sessions/` **did not
+ * exist at all**. Not empty — absent. The checkpoint journal survived (it is
+ * appended per write), so the FILES could be put back and the CONVERSATION that
+ * produced them was gone. Every save happened at the end of a turn, so the one
+ * run you would most want to carry on — the one that died — was the only kind
+ * that left nothing to carry on from.
+ *
+ * ⭐ A live save is the same record, written early and rewritten as the run
+ * goes. `closedCleanly: false` is the crash marker; the final save at the end of
+ * the turn passes the SAME id and flips it true. So there is exactly one file
+ * per turn, exactly as before, and the only new state on disk is one boolean.
+ *
+ * ⚠️ `pid` IS RECORDED BECAUSE "NOT CLOSED" AND "STILL RUNNING" LOOK IDENTICAL
+ * ON DISK. Seven terminals in one workspace is the documented normal case here;
+ * offering to resume a conversation another live process is in the middle of
+ * would be worse than never offering at all. `findCrashedSession` refuses any
+ * record whose pid still answers.
+ *
  * @param {string} root
  * @param {any} outcome the SessionOutcome from turn.mjs
- * @param {{ task?: string, id?: string, now?: Date, keep?: number }} [meta]
+ * @param {{ task?: string, id?: string, now?: Date, keep?: number, live?: boolean, pid?: number }} [meta]
  * @returns {SessionSaved | SessionRefused}
  */
 export function saveSession(root, outcome, meta = {}) {
@@ -641,9 +761,23 @@ export function saveSession(root, outcome, meta = {}) {
     // and it is the difference between a listable record and a resumable one.
     resumable: clean.messages.length > 0,
     truncated: clean.truncated,
+    /**
+     * ⚠️ A CLIPPED HEAD MEANS THE PROMPT CACHE CANNOT HIT ON RESUME — see
+     * MAX_HEAD_CHARS. Recorded so `resumeMessages` states it instead of leaving
+     * someone to discover it on the invoice.
+     */
+    headTruncated: clean.headTruncated === true,
     droppedGroups: clean.droppedGroups,
     droppedIncomplete: clean.droppedIncomplete,
     redactions: clean.redactions,
+    /**
+     * ⚠️ FALSE MEANS "THIS PROCESS NEVER GOT TO THE END", NOT "IT FAILED". A run
+     * that stopped at the round cap closed cleanly; a run whose laptop shut is
+     * the one this flag is for. Absent (an older record) is read as TRUE, so
+     * upgrading never manufactures a crash offer for a run that finished fine.
+     */
+    closedCleanly: meta.live !== true,
+    pid: typeof meta.pid === 'number' ? meta.pid : process.pid,
     messages: clean.messages,
   };
 
@@ -792,6 +926,17 @@ export function resumeMessages(root, id) {
   if (s.files.length > 0) {
     bits.push(`Files it touched: ${s.files.slice(0, 12).map((f) => f.path).join(', ')}${s.files.length > 12 ? `, +${s.files.length - 12} more` : ''}.`);
   }
+  if (s.closedCleanly === false) {
+    /**
+     * ⚠️ SAY THAT IT DIED, because the model's own transcript gives it no way to
+     * tell. A record closed at the round cap and a record whose process was
+     * killed look identical from the inside — and the difference matters: the
+     * killed one may have started a tool call whose EFFECT landed while its
+     * result never did, so "check the disk before redoing anything" is advice
+     * only this branch can honestly give.
+     */
+    bits.push('⚠️ That run was killed mid-round (the process never reached the end), so its final round may be missing from this history even though its work may already be on disk.');
+  }
   if (s.droppedIncomplete > 0) {
     bits.push('Its last round was incomplete and has been discarded, so the final tool call it started never finished.');
   }
@@ -817,6 +962,16 @@ export function resumeMessages(root, id) {
     messages: [...s.messages, { role: 'user', content: note }],
     note,
     rootChanged,
+    /**
+     * ⭐ WHETHER THE DISCOUNT SURVIVED. The first two messages ARE the cacheable
+     * prefix, so a record whose head was clipped resumes into a prompt that
+     * differs from the original at message zero and cannot hit the cache at all
+     * — see MAX_HEAD_CHARS for the 60.8% this was measured at before the head
+     * got its own ceiling. Reported so the CLI can say so out loud; silence here
+     * is how a 4.3x price difference goes unnoticed.
+     */
+    headTruncated: s.headTruncated === true,
+    crashed: s.closedCleanly === false,
     replayed: false,
   };
 }
@@ -863,12 +1018,147 @@ export function listSessions(root, { limit = 10 } = {}) {
       commands: s.commands.length,
       stoppedBecause: s.stoppedBecause,
       resumable: s.resumable === true,
+      // ⚠️ ABSENT READS AS CLEAN. Records written before this field existed are
+      // finished runs, and inventing a crash for them would greet every upgrade
+      // with an offer to recover something that never broke.
+      closedCleanly: s.closedCleanly !== false,
+      pid: typeof s.pid === 'number' ? s.pid : null,
       summary: summarizeSession(s),
     });
   }
   return { ok: true, sessions, unreadable };
 }
 
+/**
+ * ── ⭐⭐⭐ "MY LAPTOP CRASHED. WHERE DID MY CONVERSATION GO?" ────────────────
+ *
+ * The one question this module existed to answer and could not. `listSessions`
+ * shows you everything and makes you pick; `--continue` takes the newest and
+ * asks nothing. Neither of them tells you, unprompted, that the run you were in
+ * the middle of never finished — and a recovery you have to already know about
+ * is a recovery for the person who does not need it.
+ *
+ * ⚠️ THREE THINGS MUST ALL BE TRUE, and each one has a case behind it:
+ *
+ *   · `closedCleanly === false` — it really did die mid-run. A run that stopped
+ *     at the round cap is FINISHED; offering to rescue it would train people to
+ *     dismiss this prompt, which is how the real one gets dismissed too.
+ *   · `resumable` — there is a conversation to restore. A record with no
+ *     messages can be listed and cannot be continued, and offering it would be
+ *     a promise the next step breaks.
+ *   · the pid does not answer — nobody is running it RIGHT NOW. Seven terminals
+ *     in one workspace is the documented normal case for this tool, and every
+ *     one of them holds an open live record. Without this check, opening a
+ *     second terminal would offer to "recover" the session the first one is
+ *     still working in.
+ *
+ * ⚠️ AND IT NEVER THROWS. It runs on the startup path of every ordinary run, so
+ * a corrupt file or an unreadable directory must cost the offer and nothing
+ * else.
+ *
+ * @param {string} root
+ * @param {{ limit?: number, selfPid?: number, isAlive?: (pid: number) => boolean }} [opts]
+ * @returns {{ ok: true, crashed: null | { id: string, savedAt: string, task: string, roundsUsed: number, files: number, pid: number | null, summary: string } } | SessionRefused}
+ */
+export function findCrashedSession(root, { limit = 5, selfPid = process.pid, isAlive = pidIsAlive } = {}) {
+  let listed;
+  try { listed = listSessions(root, { limit }); } catch (e) { return { ok: false, error: err(e) }; }
+  if (!listed.ok) return listed;
+
+  for (const s of listed.sessions) {
+    if (s.closedCleanly) continue;
+    if (!s.resumable) continue;
+    /**
+     * ⚠️ OUR OWN PID IS "ALIVE" TRIVIALLY, so it is excluded explicitly rather
+     * than relied on. A process that re-enters this function after writing its
+     * own live record would otherwise skip it for the right reason by accident,
+     * and an accident is not a guard.
+     */
+    if (s.pid !== null && (s.pid === selfPid || isAlive(s.pid))) continue;
+    return {
+      ok: true,
+      crashed: {
+        id: s.id, savedAt: s.savedAt, task: s.task, roundsUsed: s.roundsUsed,
+        files: s.files, pid: s.pid, summary: s.summary,
+      },
+    };
+  }
+  return { ok: true, crashed: null };
+}
+
+/**
+ * ── ⭐⭐ CLOSE THE BOOK ON A CRASHED RECORD ONCE IT HAS BEEN DEALT WITH ──────
+ *
+ * ⚠️ WITHOUT THIS THE OFFER IS IMMORTAL, and that is not a small defect — it is
+ * the one that makes the whole feature useless. The crash marker lives in the
+ * record, so a session recovered on Monday still says "I never finished" on
+ * Tuesday, Wednesday and every run after that. A warning that fires when nothing
+ * is wrong teaches people to dismiss it without reading, and then the real one
+ * gets dismissed too.
+ *
+ * ⭐ IT IS CALLED ON BOTH ANSWERS — accepted and declined. Accepting carries the
+ * conversation into a NEW record, so the old one is history. Declining is a
+ * decision, and re-asking somebody who already said no is how a prompt becomes
+ * noise. Neither answer deletes anything: the record stays listable, replayable
+ * and `--resume <id>`-able, it simply stops volunteering.
+ *
+ * ⚠️ IT NEVER THROWS AND IT NEVER PARTIALLY WRITES. Same temp-then-rename as
+ * `saveSession`, and an unreadable or unparseable file is reported, not raised —
+ * this runs on the startup path of an ordinary run.
+ *
+ * @param {string} root
+ * @param {string} id
+ * @returns {{ ok: true, id: string, changed: boolean } | SessionRefused}
+ */
+export function markSessionClosed(root, id) {
+  const loaded = loadSession(root, id);
+  if (!loaded.ok) return loaded;
+  if (loaded.session.closedCleanly !== false) return { ok: true, id: loaded.session.id, changed: false };
+
+  const f = resolveSessionFile(root, `${String(id).replace(/\.json$/, '')}.json`);
+  if (!f.ok) return f;
+  const written = writeRecord(f, { ...loaded.session, closedCleanly: true });
+  if (!written.ok) return written;
+  return { ok: true, id: loaded.session.id, changed: true };
+}
+
+/**
+ * Does this pid still answer?
+ *
+ * ⚠️ `EPERM` MEANS ALIVE, NOT DEAD, and reading it the other way is the
+ * dangerous direction: a pid owned by another user exists, and treating it as
+ * gone is how we offer to resume a conversation somebody else is having. Only
+ * `ESRCH` — no such process — is an answer of "no".
+ */
+export function pidIsAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e?.code !== 'ESRCH';
+  }
+}
+
+/**
+ * ⭐ THE EXACT SENTENCE A PERSON SEES AFTER THEIR LAPTOP DIED, exported so the
+ * test asserts what they read rather than a paraphrase of it — the rule
+ * `interrupt.mjs` set for FIRST_PRESS_NOTICE, for the same reason: the promise
+ * this line makes has to stay wired to the code that keeps it.
+ *
+ * ⚠️ IT NAMES THE COMMAND. "A previous run did not finish" with no next step is
+ * a notification, not a recovery, and the person reading it has just lost work.
+ */
+export function crashOfferLines(crashed, { command = 'acuvo --continue' } = {}) {
+  const when = String(crashed?.savedAt ?? '').slice(0, 16).replace('T', ' ');
+  const task = String(crashed?.task ?? '').replace(/\s+/g, ' ').trim();
+  return [
+    `  ⚠ a run in this workspace never finished — it stopped mid-round at ${when} (UTC).`,
+    `    ${crashed?.roundsUsed ?? 0} round${crashed?.roundsUsed === 1 ? '' : 's'} and ${crashed?.files ?? 0} file change${crashed?.files === 1 ? '' : 's'} were recorded: ${task.length > 64 ? `${task.slice(0, 63)}…` : task}`,
+    `    Its conversation was saved. Carry on from it with:  ${command}`,
+  ];
+}
+
 /**
  * One line, and it has to earn its width: the id (which is what you type to
  * resume), when, how far it got, what it produced, and why it stopped. The task

package/lib/turn.mjs

@@ -2349,6 +2349,20 @@ export async function runSession({
    * default is `OPEN_POLICY`, so a run with no policy file is unchanged.
    */
   policy = OPEN_POLICY,
+  /**
+   * ── ⭐⭐ CALLED AT EVERY ROUND BOUNDARY WITH THE RUN SO FAR ────────────────
+   *
+   * `null` (the default) is one falsy check per round and the behaviour this
+   * function has always had. `bin/acuvo.mjs` passes `saveSession`, which is what
+   * makes a killed run recoverable — see the call site inside the loop for the
+   * measurement that forced it.
+   *
+   * ⚠️ IT RECEIVES THE SAME SHAPE THIS FUNCTION RETURNS, deliberately, so the
+   * caller has one consumer and not two. A checkpoint that needed its own
+   * translation layer would be a second definition of the outcome, and the two
+   * would drift the first time either grew a field.
+   */
+  onCheckpoint = null,
 }) {
   const continuing = Array.isArray(priorMessages) && priorMessages.length > 0;
   /**
@@ -3047,6 +3061,52 @@ export async function runSession({
     }
     onEvent({ type: 'round-start', round, of: maxRounds });
 
+    /**
+     * ── ⭐⭐⭐ THE TRANSCRIPT REACHES DISK *DURING* THE RUN, NOT AFTER IT ─────
+     *
+     * ⚠️ MEASURED 2026-08-22, which is the only reason this exists: a run was
+     * SIGKILLed here, mid-round, after two completed rounds and two files
+     * written — and `.acuvo/sessions/` did not exist at all afterwards. Every
+     * save in this package happened after the loop, so the run a person most
+     * wants back (the one that died) was the only one that left nothing.
+     *
+     * ⭐ THE TOP OF THE ROUND IS THE RIGHT SEAM, and it is ONE call site. Here,
+     * `messages` holds everything through round N-1 and nothing partial: the
+     * assistant reply for this round has not arrived, so there is no dangling
+     * `tool_calls` group for the session's side-effect guard to have to drop.
+     * Hooking the three `rounds.push` sites instead would be three copies of the
+     * same decision — the shape that has cost this repo five separate bugs.
+     *
+     * ⚠️ WHAT IT COSTS ON A CRASH IS THE ROUND IN FLIGHT, and that is honest:
+     * the killed round's tool call may have LANDED while its result never did,
+     * which is precisely what `resumeMessages` now says out loud.
+     *
+     * ⚠️ AND IT CAN NEVER TAKE THE RUN DOWN. A bookkeeping write that throws
+     * would kill the work it exists to protect — the same rule `audit.mjs` and
+     * `checkpoint.mjs` already state. The caller is handed the SAME shape
+     * `saveSession` consumes at the end of the run, so there is one definition
+     * of "what a session record contains" rather than two.
+     */
+    if (onCheckpoint) {
+      try {
+        onCheckpoint({
+          ok: true,
+          stage: 'running',
+          model: config.model,
+          messages,
+          executed,
+          rounds,
+          roundsUsed: rounds.length,
+          maxRounds,
+          stoppedBecause: 'in-progress',
+          // ⭐ The same aggregator the finished outcome uses — a resumed run's
+          // budget subtraction reads `usage.cost`, and a checkpoint that
+          // reported nothing would hand a crashed run a fresh full ceiling.
+          usage: aggregateUsage(rounds, prefixReadings),
+        });
+      } catch { /* a record must never cost the work it records */ }
+    }
+
     /**
      * ── ⭐ THE COUNTDOWN, INJECTED HERE AND NOWHERE ELSE ────────────────────
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acuvo-code",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "Acuvo Code — the terminal client for the Acuvo capability registry. Zero dependencies, by design.",
   "type": "module",
   "bin": {