acuvo-code 0.6.1 → 0.6.2

package/lib/input-box.mjs

@@ -528,7 +528,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. */
@@ -475,15 +512,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 +577,7 @@ export function sanitizeMessages(messages, { maxBytes = MAX_SESSION_BYTES, maxCh
     droppedGroups,
     droppedIncomplete: pruned.dropped,
     truncated: droppedGroups > 0,
+    headTruncated,
   };
 }
 
@@ -600,9 +648,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 +710,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 +875,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 +911,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 +967,111 @@ 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 };
+}
+
+/**
+ * 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/package.json

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