acuvo-code 0.6.2 → 0.6.4

package/ENTERPRISE.md

@@ -188,7 +188,7 @@ copy, but it *is* a place a process starts, and this is a list of those. Six and
 are the numbers to quote. Counting is the first thing a reviewer does.
 
 ⚠️ **This said "18 shipped files", then "41", then "90", then "101", then "108", and every
-one went stale in turn.** The package ships **120 files — 118 in `lib/`, 2 in
+one went stale in turn.** The package ships **121 files — 119 in `lib/`, 2 in
 `bin/` — about 78511 lines**, with **238 test files** beside them (counted 2026-08-22).
 
 ⭐ **AND THE 108 WENT STALE IN THE MOST INSTRUCTIVE WAY POSSIBLE: THREE OF THE FILES IT
@@ -892,7 +892,7 @@ For completeness, the properties none of them offers:
   (`lib/media.mjs`), and generates imagery with no configuration and no account
   (`lib/imagegen.mjs`) — critiqued before it is accepted, and reported as unreviewed when
   no critic is available.
-- ⭐ **Zero dependencies.** The entire auditable surface is 120 files and 78511 lines,
+- ⭐ **Zero dependencies.** The entire auditable surface is 121 files and 79376 lines,
   and there is no `node_modules` behind it. (Counted 2026-08-22 from
   `lib/*.mjs` + `bin/*.mjs`; `test/docs-truth.test.mjs` fails the build if this number
   drifts, which is why it went 18 → 41 → 46 → 52 → 53 → 57 → 60 → 61 → 62 → 65 → 66 → 69 → 70 → 71 → 72 → 73 → 80 → 84 → 90 → 100 → 101 → 102 → 103 → 107 → 108 → 111 as modules landed (111 = the three that were WRITTEN and imported by nothing — `python.mjs`, `cache-floor.mjs`, `plan-coherence.mjs`; 108 = `warm-provider.mjs`, which keeps a session on the upstream that holds its prompt cache; 107 = `login.mjs`, the command that stores an Acuvo credential — until it existed, `writeAccount` was called by nothing and every user fell through to BYOK). ⚠️ Two of those three landed on this count while remaining UNREACHABLE, which is the sharpest illustration this document has that a file count is a claim about bytes, never about capability. ⭐ A

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';
@@ -1489,6 +1489,28 @@ ${formatBoard(listed)}
    * chat loop owns the invitation, and neither should own both.
    */
   const { openingScreen } = await import('../lib/banner.mjs');
+  /**
+   * ── ⭐⭐⭐ ASK THE TERMINAL, DO NOT ASSUME IT ────────────────────────────────
+   *
+   * The half-block mark is only correct if this terminal renders ▀ ▄ █ at ONE
+   * cell. They are East-Asian-Ambiguous, so that is a property of the font and
+   * the emulator, not of the character — and where they come out double-width
+   * the mark TEARS: the padding spaces stay narrow while the blocks do not, so
+   * every row shifts by a different amount and the right-hand column is pushed
+   * off the screen.
+   *
+   * ⚠️ THIS IS THE FOURTH ATTEMPT AT THIS SCREEN AND THE FIRST THAT MEASURES.
+   * The previous three reasoned from byte sequences that were correct on my
+   * machine and wrong on Roman's, which is the only machine that counts.
+   * `measureCellWidth` prints the glyph and asks the terminal where the cursor
+   * landed — not an inference about fonts, the terminal describing itself.
+   * Unknown falls back to the ASCII mark: a plainer logo on a capable terminal
+   * costs a little beauty, torn blocks on an incapable one cost a first
+   * impression.
+   */
+  const { measureCellWidth, bannerStyle } = await import('../lib/glyph-width.mjs');
+  const cellWidth = await measureCellWidth({ input: process.stdin, output: process.stdout });
+  const bannerLook = bannerStyle({ cellWidth, env: process.env });
   /**
    * ── ⭐⭐ THE BRAND NAME, NOT THE VENDOR'S ────────────────────────────────────
    *
@@ -1518,6 +1540,14 @@ ${formatBoard(listed)}
      * site.
      */
     paint: createPainter(colourEnabled()),
+    style: bannerLook,
+    /**
+     * ⚠️ THE REAL WIDTH, NOT A CONSTANT. The banner used to build to a fixed
+     * 80 columns and never ask, so in any narrower terminal — a split pane, a
+     * side panel — every row wrapped. `columns` is undefined off a TTY, which
+     * the banner reads as "assume 80": right for a pipe, wrong for nothing.
+     */
+    columns: process.stdout.columns ?? null,
   });
   if (opts.json) process.stderr.write(banner);
   else process.stdout.write(banner);
@@ -1612,6 +1642,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 +1737,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 +1748,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 +1774,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 +1793,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 +1984,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 +2102,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 +2255,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 +2397,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/banner.mjs

@@ -1,155 +1,255 @@
-/**
- * ── ⭐⭐⭐ WHAT YOU SEE WHEN YOU TYPE `acuvo` ────────────────────────────────
- *
- * Roman, 2026-08-22, having typed it: *"it's not opening as a typable terminal,
- * with acuvo logo top left and details up top etc, like how claude code opens.
- * have you actually designed the page?"* — and then: *"no we want OUR logo"*.
- *
- * So this is the real mark, not letters spelling the name. It is
- * `console/public/brand/acuvo-mark.png` — the angular A — resampled to
- * half-blocks at 14x14 and embedded as text.
- *
- * ── ⚠️ WHY IT IS EMBEDDED RATHER THAN DECODED AT RUNTIME ────────────────────
- *
- * This package has ZERO dependencies, deliberately, and Node cannot decode a
- * PNG without one. Converting at build time and pasting the result keeps that
- * promise and costs nothing at startup. If the mark ever changes, re-run the
- * conversion — the logo is DERIVED from the brand asset, not drawn by hand, so
- * it stays honest to it.
- *
- * ── ⚠️ THE CONSTRAINTS, WHICH ARE NOT PREFERENCES ───────────────────────────
- *
- * · **Half-block glyphs only** (▀ ▄ █). Braille and box-drawing render as tofu
- *   in cmd.exe and in many CI log viewers, and a logo that renders as question
- *   marks is worse than no logo — on the exact platform this is developed on.
- * · **No colour escapes here.** The caller owns colour and honours NO_COLOR; a
- *   module that hard-codes them emits garbage the moment output is piped.
- * · **Every line under 80 columns.** The narrowest terminal in real use is 80,
- *   and a wrapped banner does not read as dense, it reads as broken.
- *
- * ⭐ A NOTE ON DOING BETTER: `lib/terminal-graphics.mjs` can send a real PNG
- * inline on Kitty and iTerm2. It is deliberately NOT used here — Windows
- * Terminal speaks neither protocol, so the block art is what most users would
- * see anyway, and one rendering that is the same everywhere beats two that
- * disagree.
- */
-
-/**
- * The Acuvo mark, resampled from the brand PNG. Seven rows: tall enough to be
- * the mark rather than a smudge, short enough for something run forty times a
- * day rather than opened once.
- */
-const MARK = [
-  '      ▄█',
-  '     ▄███',
-  '    ▄█▀▀██',
-  '   ▄█▀  ▀██',
-  '  ▄█▀ ██ ▀██',
-  ' ▄████▀▀█████',
-  '█▀      █▀  ▀█',
-];
-
-const MARK_WIDTH = Math.max(...MARK.map((l) => l.length));
-const GUTTER = 2;
-export const MAX_BANNER_COLUMNS = 80;
-
-/** Columns left for the detail rows once the mark and gutter are placed. */
-const TEXT_COLUMNS = MAX_BANNER_COLUMNS - MARK_WIDTH - GUTTER;
-
-/**
- * Build the opening screen: mark on the left, facts on the right.
- *
- * @param {object} o
- * @param {string} o.version
- * @param {string} o.workspace   already shortened by the caller
- * @param {string} o.model
- * @param {string} o.billing     who this run will charge
- * @param {string} o.canRun      what it may execute, or that it may not
- * @param {boolean} [o.interactive] whether a prompt follows
- * @returns {string}
- */
-export function openingScreen({ version, workspace, model, billing, canRun, interactive = false, paint = null }) {
-  /**
-   * ── ⭐ THE MARK IS BRAND GREEN, AND ONLY THE MARK ────────────────────────────
-   *
-   * Roman: *"can you colour our logo green in the terminal?"* #C8E91E, sampled
-   * from the brand PNG rather than picked by eye.
-   *
-   * ⚠️ THE PAINTER IS INJECTED, NOT IMPORTED. The caller already decided whether
-   * this stream can take colour — it owns NO_COLOR, FORCE_COLOR, TERM=dumb and
-   * TTY detection. A module that reaches for colour itself will eventually
-   * disagree with that decision and write escapes into somebody's redirected
-   * file.
-   *
-   * ⚠️ AND ONLY THE LOGO. Colouring the detail rows would make the one line that
-   * must be read as a warning — `billing: YOUR OWN OpenRouter key` — compete
-   * with decoration.
-   */
-  const brand = paint?.brand ?? ((s) => s);
-  /**
-   * ── ⚠️⚠️ ELIDED, BECAUSE THE VALUES ARE NOT OURS ────────────────────────────
-   *
-   * Every value arrives at runtime: a deep monorepo path, a long model id, the
-   * shell-mode warning. The first version assumed they would be short and its
-   * own test caught it wrapping at 80 columns on ordinary inputs.
-   *
-   * ⭐ ELIDED IN THE MIDDLE, NOT THE END. The informative parts of a path are
-   * the drive and the leaf; chopping the tail leaves
-   * `C:\Users\somebody\Projects\a-`, which identifies nothing. Same for a model
-   * id, where the family is at the front and the variant at the back.
-   */
-  const room = TEXT_COLUMNS - 11;
-  const fit = (v) => {
-    const s = String(v ?? '');
-    if (s.length <= room) return s;
-    const head = Math.ceil((room - 1) / 2);
-    return `${s.slice(0, head)}…${s.slice(s.length - (room - 1 - head))}`;
-  };
-
-  const right = [
-    `ACUVO CODE${version ? `  ${version}` : ''}`,
-    '',
-    `workspace  ${fit(workspace)}`,
-    `model      ${fit(model)}`,
-    `billing    ${fit(billing)}`,
-    `can run    ${fit(canRun)}`,
-    '',
-  ];
-
-  /**
-   * ⚠️ THE TWO COLUMNS ARE ZIPPED, NOT CONCATENATED, and the row counts are
-   * allowed to differ — whichever is shorter simply runs out. Assuming they
-   * match would break the layout the first time a row is added to either side.
-   */
-  const rows = Math.max(MARK.length, right.length);
-  const lines = [''];
-  for (let i = 0; i < rows; i += 1) {
-    const text = right[i] ?? '';
-    /**
-     * ⚠️ PADDED FIRST, PAINTED SECOND — escape codes have no width, so padding a
-     * coloured string aligns the text against invisible bytes and the whole
-     * right-hand column drifts.
-     *
-     * ⚠️⚠️ AND PADDED ONLY WHEN SOMETHING FOLLOWS. On a mark-only row the
-     * padding sits INSIDE the colour, before the reset, where the `trimEnd`
-     * below cannot reach it — so the coloured banner carried trailing
-     * whitespace the plain one did not. Invisible, but it means colour changed
-     * the layout, which is exactly what the guard forbids.
-     */
-    const rawMark = MARK[i] ?? '';
-    const padded = text ? rawMark.padEnd(MARK_WIDTH + GUTTER) : rawMark;
-    const mark = MARK[i] ? brand(padded) : padded;
-    lines.push(`${mark}${text}`.trimEnd());
-  }
-  lines.push('');
-
-  /**
-   * ⚠️ ONLY WHEN A PROMPT ACTUALLY FOLLOWS. Printing "type what you want done"
-   * above a one-shot run that has already been given its task is an instruction
-   * for something the user cannot do, on the screen of a thing already working.
-   */
-  if (interactive) {
-    lines.push('  Type what you want done.   /help for commands  ·  exit to leave', '');
-  }
-  return lines.join('\n');
-}
+/**
+ * ── ⭐⭐⭐ WHAT YOU SEE WHEN YOU TYPE `acuvo` ────────────────────────────────
+ *
+ * Roman, 2026-08-22, having typed it: *"it's not opening as a typable terminal,
+ * with acuvo logo top left and details up top etc, like how claude code opens.
+ * have you actually designed the page?"* — and then: *"no we want OUR logo"*.
+ *
+ * So this is the real mark, not letters spelling the name. It is
+ * `console/public/brand/acuvo-mark.png` — the angular A — resampled to
+ * half-blocks at 14x14 and embedded as text.
+ *
+ * ── ⚠️ WHY IT IS EMBEDDED RATHER THAN DECODED AT RUNTIME ────────────────────
+ *
+ * This package has ZERO dependencies, deliberately, and Node cannot decode a
+ * PNG without one. Converting at build time and pasting the result keeps that
+ * promise and costs nothing at startup. If the mark ever changes, re-run the
+ * conversion — the logo is DERIVED from the brand asset, not drawn by hand, so
+ * it stays honest to it.
+ *
+ * ── ⚠️ THE CONSTRAINTS, WHICH ARE NOT PREFERENCES ───────────────────────────
+ *
+ * · **Half-block glyphs only** (▀ ▄ █). Braille and box-drawing render as tofu
+ *   in cmd.exe and in many CI log viewers, and a logo that renders as question
+ *   marks is worse than no logo — on the exact platform this is developed on.
+ * · **No colour escapes here.** The caller owns colour and honours NO_COLOR; a
+ *   module that hard-codes them emits garbage the moment output is piped.
+ * · **Every line under 80 columns.** The narrowest terminal in real use is 80,
+ *   and a wrapped banner does not read as dense, it reads as broken.
+ *
+ * ⭐ A NOTE ON DOING BETTER: `lib/terminal-graphics.mjs` can send a real PNG
+ * inline on Kitty and iTerm2. It is deliberately NOT used here — Windows
+ * Terminal speaks neither protocol, so the block art is what most users would
+ * see anyway, and one rendering that is the same everywhere beats two that
+ * disagree.
+ */
+
+/**
+ * The Acuvo mark, resampled from the brand PNG. Seven rows: tall enough to be
+ * the mark rather than a smudge, short enough for something run forty times a
+ * day rather than opened once.
+ */
+const MARK = [
+  '      ▄█',
+  '     ▄███',
+  '    ▄█▀▀██',
+  '   ▄█▀  ▀██',
+  '  ▄█▀ ██ ▀██',
+  ' ▄████▀▀█████',
+  '█▀      █▀  ▀█',
+];
+
+/**
+ * ── ⭐⭐⭐ THE SAME MARK, IN CHARACTERS NOTHING CAN STRETCH ─────────────────
+ *
+ * Every glyph here is ASCII, so it is width-1 by definition in every terminal,
+ * every font, every locale. No ambiguity class, nothing to measure, nothing to
+ * get wrong.
+ *
+ * ⚠️ THIS IS NOT "NO LOGO" — that distinction matters. Roman asked for OUR
+ * mark and then asked again when he got letters spelling the name. The fallback
+ * for a terminal that cannot draw half-blocks must therefore still BE the
+ * angular A, drawn a different way, rather than a wordmark standing in for it.
+ * A degraded logo is a logo; a text substitute is a missing one.
+ */
+const MARK_ASCII = [
+  '     /\\',
+  '    /  \\',
+  '   / /\\ \\',
+  '  / /  \\ \\',
+  ' / /____\\ \\',
+  '/_/      \\_\\',
+];
+
+const GUTTER = 2;
+
+/**
+ * The widest the banner may ever be when the terminal will not say how wide it
+ * is. Kept at 80 because that is the narrowest terminal in real use, so a
+ * banner built to it fits everywhere.
+ */
+export const MAX_BANNER_COLUMNS = 80;
+
+/** Below this the two-column layout stops being a layout and starts being a mess. */
+const MIN_TEXT_COLUMNS = 30;
+
+/**
+ * Build the opening screen: mark on the left, facts on the right.
+ *
+ * @param {object} o
+ * @param {string} o.version
+ * @param {string} o.workspace   already shortened by the caller
+ * @param {string} o.model
+ * @param {string} o.billing     who this run will charge
+ * @param {string} o.canRun      what it may execute, or that it may not
+ * @param {boolean} [o.interactive] whether a prompt follows
+ * @param {'blocks'|'text'} [o.style] which mark to draw — see `lib/glyph-width.mjs`
+ * @param {number} [o.columns]   the real terminal width, when it is known
+ * @returns {string}
+ */
+export function openingScreen({
+  version, workspace, model, billing, canRun,
+  interactive = false, paint = null, style = 'blocks', columns = null,
+}) {
+  const brand = paint?.brand ?? ((s) => s);
+
+  /**
+   * ── ⚠️⚠️ THE WIDTH IS THE TERMINAL'S, NOT A CONSTANT ──────────────────
+   *
+   * This used to build to a fixed 80 columns and never ask. Every line it
+   * produced was under 80 and it looked immaculate — in an 80-column terminal.
+   * In a narrower one, which is what a side panel or a split pane is, every
+   * single row wraps, and a wrapped banner does not read as dense. It reads as
+   * broken software, which is the first thing a new user sees.
+   *
+   * `- 1` because a line that exactly fills the width wraps on some terminals
+   * and not others, and the difference is not worth one column.
+   */
+  const width = Math.max(20, Math.min(MAX_BANNER_COLUMNS, (columns ?? MAX_BANNER_COLUMNS) - 1));
+
+  const mark = style === 'text' ? MARK_ASCII : MARK;
+  const markWidth = Math.max(...mark.map((l) => l.length));
+
+  /**
+   * ⭐ THREE LAYOUTS, CHOSEN BY WHAT ACTUALLY FITS — never by a platform guess.
+   * Side by side when there is room for both; mark above the facts when there
+   * is room for the mark alone; facts only when there is not. The last one is
+   * rare and it still has to be right, because a 24-column terminal is somebody
+   * on a phone over SSH and they deserve a legible screen, not a torn one.
+   */
+  const sideBySide = width >= markWidth + GUTTER + MIN_TEXT_COLUMNS;
+  const textColumns = sideBySide ? width - markWidth - GUTTER : width;
+
+  /**
+   * ⚠️ ELIDED IN THE MIDDLE, NOT THE END. The informative parts of a path are
+   * the drive and the leaf; chopping the tail leaves `C:\Users\somebody\Projects\a-`,
+   * which identifies nothing. Same for a model id, where the family is at the
+   * front and the variant at the back.
+   */
+  const room = Math.max(8, textColumns - 11);
+  const fit = (v) => {
+    const s = String(v ?? '');
+    if (s.length <= room) return s;
+    const head = Math.ceil((room - 1) / 2);
+    return `${s.slice(0, head)}…${s.slice(s.length - (room - 1 - head))}`;
+  };
+
+  const right = [
+    `ACUVO CODE${version ? `  ${version}` : ''}`,
+    '',
+    `workspace  ${fit(workspace)}`,
+    `model      ${fit(model)}`,
+    `billing    ${fit(billing)}`,
+    `can run    ${fit(canRun)}`,
+    '',
+  ];
+
+  const lines = [''];
+
+  if (sideBySide) {
+    /**
+     * ⚠️ THE TWO COLUMNS ARE ZIPPED, NOT CONCATENATED, and the row counts are
+     * allowed to differ — whichever is shorter simply runs out.
+     */
+    const rows = Math.max(mark.length, right.length);
+    for (let i = 0; i < rows; i += 1) {
+      const text = right[i] ?? '';
+      /**
+       * ⚠️ PADDED FIRST, PAINTED SECOND — escape codes have no width, so padding
+       * a coloured string aligns text against invisible bytes and the whole
+       * right-hand column drifts.
+       *
+       * ⚠️⚠️ AND PADDED ONLY WHEN SOMETHING FOLLOWS. On a mark-only row the
+       * padding sits INSIDE the colour, before the reset, where `trimEnd`
+       * cannot reach it — so the coloured banner carried trailing whitespace the
+       * plain one did not. Invisible, but it means colour changed the layout.
+       */
+      const raw = mark[i] ?? '';
+      const padded = text ? raw.padEnd(markWidth + GUTTER) : raw;
+      lines.push(`${mark[i] ? brand(padded) : padded}${text}`.trimEnd());
+    }
+  } else {
+    const roomForMark = width >= markWidth;
+    if (roomForMark) {
+      for (const row of mark) lines.push(brand(row));
+      lines.push('');
+    }
+    for (const text of right) lines.push(text.trimEnd());
+  }
+
+  lines.push('');
+
+  /**
+   * ⚠️ ONLY WHEN A PROMPT ACTUALLY FOLLOWS. Printing "type what you want done"
+   * above a one-shot run that has already been given its task is an instruction
+   * for something the user cannot do.
+   *
+   * ⭐ And it is SHORTENED rather than wrapped when the terminal is narrow. A
+   * hint that wraps onto a second line looks like an error message.
+   */
+  if (interactive) {
+    /**
+     * ⭐ SHORTENED IN STAGES, NEVER TRUNCATED. A clamp would cut "leave" to
+     * "leav", and a hint with a word chopped in half does not read as a
+     * compact hint — it reads as a rendering bug, which is precisely the
+     * impression this screen keeps making.
+     */
+    const hints = [
+      '  Type what you want done.   /help for commands  ·  exit to leave',
+      '  /help for commands  ·  exit to leave',
+      '  /help  ·  exit',
+    ];
+    lines.push(hints.find((h) => h.length <= width) ?? hints[hints.length - 1], '');
+  }
+
+  /**
+   * ⚠️⚠️ THE LAST WORD ON WIDTH, AND IT IS NOT A BELT-AND-BRACES CHECK.
+   * Everything above reasons about `.length`, which counts CODE UNITS, while a
+   * terminal counts CELLS — and the whole reason this file was rewritten is that
+   * those two disagree. This clamp is measured on the painted string with the
+   * escapes discounted, so a mark that turns out wider than advertised is
+   * truncated rather than allowed to wrap and tear the layout.
+   */
+  return lines.map((l) => clampToWidth(l, width)).join('\n');
+}
+
+/** Visible length, ignoring ANSI escapes — they occupy no cells. */
+function visibleLength(s) {
+  return String(s).replace(/\[[0-9;]*m/g, '').length;
+}
+
+/**
+ * Cut a possibly-coloured string to `width` visible cells, keeping the escapes
+ * balanced so a truncation cannot leak colour into the rest of the screen.
+ */
+function clampToWidth(s, width) {
+  if (visibleLength(s) <= width) return s;
+  let out = '';
+  let seen = 0;
+  const re = /(\[[0-9;]*m)|([\s\S])/g;
+  let m;
+  while ((m = re.exec(s)) !== null) {
+    if (m[1]) { out += m[1]; continue; }
+    if (seen >= width) break;
+    out += m[2];
+    seen += 1;
+  }
+  /**
+   * ⚠️ ONLY RE-CLOSE A STRING THAT WAS ACTUALLY COLOURED. Appending a reset
+   * unconditionally puts four bytes on the end of every truncated PLAIN line —
+   * harmless on a terminal, and garbage the moment output is piped to a file or
+   * a CI log, which is the one place this module has already been told never to
+   * write escapes.
+   */
+  return out.includes('') ? `${out}` : out;
+}

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/glyph-width.mjs

@@ -0,0 +1,169 @@
+/**
+ * ── ⭐⭐⭐ ASK THE TERMINAL HOW WIDE A GLYPH ACTUALLY IS ─────────────────────
+ *
+ * Roman, 2026-08-22, third report on the same screen: *"acuvo cli still is
+ * structured wrong, I can't even see our logo, and the words etc, like it
+ * doesn't fit."*
+ *
+ * ── ⚠️ WHY THE BANNER CAN BE CORRECT AND STILL SHATTER ──────────────────────
+ *
+ * The mark is built from half-block glyphs (▀ ▄ █, U+2580–U+2588). Unicode
+ * classifies them as **East Asian Ambiguous**, which means their width is not a
+ * property of the character — it is a property of the terminal and the font. A
+ * terminal that renders them at TWO cells turns a 14-column mark into 28
+ * columns, while the SPACES padding each row stay at one. The art does not get
+ * uniformly wider; it tears, every row by a different amount, and the right-hand
+ * column is shoved off the screen. That is exactly "I can't even see our logo,
+ * and the words don't fit", and it is invisible from any machine where the font
+ * happens to render them narrow — including mine, where the banner measures a
+ * tidy 72 columns and looks perfect.
+ *
+ * ⭐ SO STOP GUESSING AND MEASURE. Print the glyph, ask the terminal where the
+ * cursor ended up (`ESC[6n`, the DSR cursor-position report from ECMA-48), and
+ * subtract. The answer is not an inference about fonts or platforms; it is the
+ * terminal reporting its own behaviour. This is what every serious TUI does for
+ * emoji and CJK, and it is the only instrument that works from here — three
+ * previous attempts at this screen were reasoned from byte sequences and all
+ * three were wrong on the one machine that mattered.
+ *
+ * ── ⚠️ AND IT MUST FAIL SAFE, BECAUSE IT TOUCHES THE SCREEN ─────────────────
+ *
+ * The probe writes a character and reads a reply. If the terminal never answers
+ * — a dumb TERM, a pipe, a CI log, an editor's embedded console that swallows
+ * DSR — it must give up quickly, erase what it wrote, restore raw mode exactly
+ * as it found it, and return `null` for "unknown". A diagnostic that hangs the
+ * program it is diagnosing, or that leaves the terminal in raw mode after a
+ * failure, is worse than the bug.
+ */
+
+/** The DSR request: "report the cursor position". */
+const CURSOR_QUERY = '\x1b[6n';
+
+/**
+ * Parse a cursor-position report, `ESC [ row ; col R`.
+ *
+ * ⚠️ SCANS FOR THE PATTERN RATHER THAN ANCHORING AT THE START. The reply can
+ * arrive glued to whatever else the user typed — a keystroke that landed during
+ * the round trip sits in the same chunk — and an anchored match would discard a
+ * perfectly good measurement because somebody pressed a key.
+ *
+ * @param {string} buf
+ * @returns {{ row: number, col: number } | null}
+ */
+export function parseCursorReport(buf) {
+  const m = /\x1b\[(\d+);(\d+)R/.exec(String(buf ?? ''));
+  if (!m) return null;
+  const row = Number(m[1]);
+  const col = Number(m[2]);
+  if (!Number.isFinite(row) || !Number.isFinite(col) || col < 1) return null;
+  return { row, col };
+}
+
+/**
+ * Anything left over once the report is removed — the user's keystrokes.
+ *
+ * ⚠️ THEY MUST BE HANDED BACK, NOT DROPPED. A character typed while the probe
+ * was in flight belongs to the program, and eating it makes the very first
+ * keystroke of a session vanish at random.
+ *
+ * @param {string} buf
+ * @returns {string}
+ */
+export function residualInput(buf) {
+  return String(buf ?? '').replace(/\x1b\[\d+;\d+R/, '');
+}
+
+/**
+ * How many cells the terminal gives `glyph`.
+ *
+ * @param {object} o
+ * @param {string} [o.glyph]        the character to measure
+ * @param {NodeJS.ReadStream} o.input
+ * @param {NodeJS.WriteStream} o.output
+ * @param {number} [o.timeoutMs]
+ * @returns {Promise<number|null>} 1, 2, … or null when the terminal did not say
+ */
+export async function measureCellWidth({ glyph = '█', input, output, timeoutMs = 200 } = {}) {
+  if (!input?.isTTY || !output?.isTTY || typeof input.setRawMode !== 'function') return null;
+
+  const wasRaw = input.isRaw === true;
+  let done = false;
+  let buffered = '';
+
+  return new Promise((resolve) => {
+    /**
+     * ⚠️ ONE EXIT PATH, AND IT ALWAYS CLEANS UP. Every way out of this — a
+     * reply, a timeout, a stream error — goes through here, because a probe
+     * that returns early on the happy path and leaks a listener on the sad one
+     * is how a CLI ends up with a terminal stuck in raw mode after a hiccup.
+     */
+    const finish = (value) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      input.removeListener('data', onData);
+      try {
+        // Erase the probe glyph and put the cursor back at the start of the line.
+        output.write('\r\x1b[2K');
+      } catch { /* the stream went away; nothing to clean */ }
+      try {
+        if (!wasRaw) input.setRawMode(false);
+      } catch { /* likewise */ }
+      // Give any keystrokes that arrived during the probe back to the program.
+      const rest = residualInput(buffered);
+      if (rest) input.unshift?.(rest);
+      resolve(value);
+    };
+
+    const onData = (chunk) => {
+      buffered += String(chunk);
+      const report = parseCursorReport(buffered);
+      if (!report) return;
+      /**
+       * The cursor started at column 1, so the glyph consumed `col - 1` cells.
+       * Guarded because a terminal that answers nonsense should read as unknown
+       * rather than as a plausible-looking wrong number.
+       */
+      const cells = report.col - 1;
+      finish(cells >= 1 && cells <= 4 ? cells : null);
+    };
+
+    const timer = setTimeout(() => finish(null), timeoutMs);
+
+    try {
+      if (!wasRaw) input.setRawMode(true);
+      input.on('data', onData);
+      // `\r` first: measure from a known column, not from wherever we happened to be.
+      output.write(`\r${glyph}${CURSOR_QUERY}`);
+    } catch {
+      finish(null);
+    }
+  });
+}
+
+/**
+ * The decision the banner actually needs, with every override that matters.
+ *
+ * ⚠️ AN EXPLICIT SETTING OUTRANKS THE MEASUREMENT, ALWAYS. Detection is very
+ * good and will still be wrong somewhere, and when it is, the user must have a
+ * way to say so that does not require them to file a bug and wait for a
+ * release. `ACUVO_BANNER=text` (or `blocks`) is that way.
+ *
+ * ⚠️ AND UNKNOWN FALLS BACK TO **TEXT**, not to blocks. The two errors are not
+ * symmetric: choosing text on a terminal that could have drawn the mark costs a
+ * little beauty, while choosing blocks on a terminal that cannot costs the user
+ * a screen of torn garbage as their first impression of the product. This is
+ * the mistake that has now been reported three times, so the default leans away
+ * from it.
+ *
+ * @param {object} o
+ * @param {number|null} o.cellWidth  measured, or null
+ * @param {Record<string,string|undefined>} [o.env]
+ * @returns {'blocks'|'text'}
+ */
+export function bannerStyle({ cellWidth, env = {} }) {
+  const forced = String(env.ACUVO_BANNER ?? '').toLowerCase();
+  if (forced === 'text' || forced === 'ascii') return 'text';
+  if (forced === 'blocks' || forced === 'art') return 'blocks';
+  return cellWidth === 1 ? 'blocks' : 'text';
+}

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