acuvo-code 0.6.2 → 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 };

package/lib/session.mjs

@@ -436,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
@@ -460,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.
@@ -487,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 };
 }
 
@@ -1035,6 +1086,42 @@ export function findCrashedSession(root, { limit = 5, selfPid = process.pid, isA
   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?
  *

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.2",
+  "version": "0.6.3",
   "description": "Acuvo Code — the terminal client for the Acuvo capability registry. Zero dependencies, by design.",
   "type": "module",
   "bin": {