@sleepy_panda_srl/portulan 0.3.0 → 0.4.1

package/cli/advisory.mjs

@@ -1,31 +1,37 @@
 #!/usr/bin/env node
-// The restart advisory — one line, once, where the agent is, and the same figure for the human.
+// Restart comparison with explicit horizon and resume expense; unknown recovery cost stays conditional.
 //
-//   node cli/advisory.mjs tool [<figures>]      a PostToolUse hook: the line, as additionalContext, once, mid-stretch
-//   node cli/advisory.mjs prompt [<figures>]    a UserPromptSubmit hook: the same line, at the next prompt, if not said yet
-//   node cli/advisory.mjs status [<figures>]    a status-line command: the figure and the request count, on every refresh
-//   node cli/advisory.mjs stop [<figures>]      a Stop hook, where a workspace declares it: the same line as a block, once
-//
-//   <figures>  --read <m> --write-5m <m> --write-1h <m>, all three or none, and --horizon <n>: a workspace's
-//              `spend`, as `./compile.mjs` writes it; undeclared, the general multipliers and horizon.
-//
-// Exit 0 on every path: a 2 would erase the person's prompt at `UserPromptSubmit` and hold every turn's end at
-// `Stop`. What it cannot read or use, it passes over and names on stderr.
-//
-// The line rides a tool result or a prompt: a non-blocking `Stop` hook's output never reaches the model, and a
-// headless run's one prompt comes before any request. The transcript is written asynchronously, so the line may
-// come one request late, never early.
+// node cli/advisory.mjs tool|prompt|status|stop [--read m --write-5m m --write-1h m] [--horizon n] [--resume-tokens cost]
+// Undeclared prices/horizon use general figures; unknown resume cost permits conditional reports only.
+// Tool/prompt output reaches the agent; a declared Stop holds only with explicit profitable estimates.
+// Retain the first crossing in a delayed batch; Stop uses the latest estimate. Hook failures exit 0.
+// Unusable figures are named on stderr.
 
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
+import { createHash } from "node:crypto";
 
-import { HORIZON, LedgerError, SPEND_FIGURES, figureOf, foldFigures, overflowingWrite, readLine, sessionFigures } from "./ledger.mjs";
+import { HORIZON, INPUT_USAGE_MASK, inputUnusable, usageOf, contextOf, LedgerError, SPEND_FIGURES, figureOf, foldFigures, foldCanonical, overflowingWrite, readLine, readTranscript, restartSaving, sessionFigures } from "./ledger.mjs";
 
 const grouped = (n) => String(n).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
-
-const STATE_VERSION = 2;
+const savingWords = (n) => grouped(Number(n.toPrecision(6)));
+
+const STATE_VERSION = 8;
+const SEEN_BYTES = 1024;
+const emptySeen = () => Buffer.alloc(SEEN_BYTES).toString("hex");
+// Membership selects exact replay; collisions never establish identity.
+function membership(bits, id, remember = false) {
+    const hash = createHash("sha256").update(id).digest();
+    let hit = true;
+    for (const at of [0, 4, 8]) {
+        const bit = hash.readUInt32LE(at) % (SEEN_BYTES * 8), mask = 1 << (bit & 7);
+        hit = Boolean(bits[bit >> 3] & mask) && hit;
+        if (remember) bits[bit >> 3] |= mask;
+    }
+    return hit;
+}
 
 const CHUNK = 1 << 16;
 
@@ -97,18 +103,64 @@ function restore(file, transcriptPath, stat) {
     }
     if (kept === null || typeof kept !== "object" || kept.v !== STATE_VERSION || kept.transcript !== transcriptPath) return null;
     if (kept.ino !== stat.ino || !isCount(kept.offset) || kept.offset > stat.size || typeof kept.tail !== "string" || !wellFormed(kept.figures)) return null;
+    if (typeof kept.comparison !== "string" || typeof kept.seen !== "string" || kept.seen.length !== SEEN_BYTES * 2 || !/^[0-9a-f]+$/.test(kept.seen)) return null;
+    if (typeof kept.freshUnsafe !== "boolean" || typeof kept.latestUnsafe !== "boolean" || ![kept.freshId, kept.latestId, kept.crossingId].every(id => id === null || typeof id === "string")) return null;
+    if (![kept.freshInput, kept.latestInput, kept.crossingInput].every(v => v === null || (Array.isArray(v) && v.length === 5 && v.every(isCount)))) return null;
+    if (!Array.isArray(kept.recentInputs) || kept.recentInputs.length > 16 || !kept.recentInputs.every(v => Array.isArray(v) && v.length === 3 && typeof v[0] === "string" && Array.isArray(v[1]) && v[1].length === 5 && v[1].every(isCount) && (isCount(v[2]) && (v[2] & INPUT_USAGE_MASK) === v[2]))) return null;
+    if (kept.crossing !== null && (!wellFormed(kept.crossing) || kept.crossing.pending || kept.crossing.compactions !== kept.figures.compactions || kept.crossing.fresh !== kept.figures.fresh || kept.crossing.requests > kept.figures.requests || kept.crossing.recent.length !== 0)) return null;
+    const seen = Buffer.from(kept.seen, "hex");
+    if ([...kept.figures.recent, kept.freshId, kept.latestId, kept.crossingId].some(id => id !== null && !membership(seen, id))) return null;
     return kept;
 }
 
-function advance(kept, transcriptPath, size) {
+const comparisonKey = ({ declared, horizon, resume }) => JSON.stringify([declared?.read ?? null, declared?.write?.["5m"] ?? null, declared?.write?.["1h"] ?? null, horizon, resume]);
+const inputOf = r => [r.uncached, r.written1h, r.written5m, r.writtenUnknown, r.read];
+const validity = () => ({ freshUnsafe: false, latestUnsafe: false, freshId: null, latestId: null, crossingId: null, freshInput: null, latestInput: null, crossingInput: null });
+const reset = (kept) => Object.assign(kept, { offset: 0, tail: "", seen: emptySeen(), figures: sessionFigures(), crossing: null, recentInputs: [], ...validity() });
+function rememberInput(state, r) {
+    if (r.id === null) return;
+    state.recentInputs = [...state.recentInputs.filter(v => v[0] !== r.id), [r.id, inputOf(r), r.usageMissing & INPUT_USAGE_MASK]].filter(v => state.figures.recent.includes(v[0])).slice(-16);
+}
+
+function replayValidity(kept, transcriptPath, spend) {
+    const transcript = readTranscript(transcriptPath, { end: kept.offset });
+    const state = { figures: sessionFigures(), crossing: null, recentInputs: [], ...validity() }, seen = Buffer.alloc(SEEN_BYTES);
+    for (const r of transcript.requests) {
+        if (r.id !== null) membership(seen, r.id, true);
+        if (r.sidechain) continue;
+        if (r.compacted) Object.assign(state, { crossing: null, ...validity() });
+        const fresh = state.figures.fresh === null || state.figures.pending || r.compacted;
+        foldCanonical(state.figures, r);
+        rememberInput(state, r);
+        const unsafe = inputUnusable(r);
+        if (fresh) { state.freshUnsafe = unsafe; state.freshId = r.id; state.freshInput = inputOf(r); }
+        state.latestUnsafe = unsafe; state.latestId = r.id; state.latestInput = inputOf(r);
+        if (state.freshUnsafe && !isCount(state.figures.fresh)) state.figures.fresh = 0;
+        if (state.latestUnsafe && !isCount(state.figures.last)) state.figures.last = 0;
+        if (state.freshUnsafe || state.latestUnsafe || state.crossing !== null) continue;
+        try {
+            const figure = figureOf(state.figures, spend);
+            if (figure !== null && figure.saving >= 0) { state.crossing = { ...state.figures, recent: [] }; state.crossingId = r.id; state.crossingInput = inputOf(r); }
+        } catch (error) { if (!(error instanceof LedgerError)) throw error; }
+    }
+    state.figures.compactions = transcript.figures.compactions;
+    state.figures.pending = transcript.figures.pending;
+    if (state.figures.pending) Object.assign(state, { crossing: null, ...validity() });
+    else if (state.crossing) state.crossing.compactions = state.figures.compactions;
+    Object.assign(kept, state, { seen: seen.toString("hex") });
+}
+
+function advance(kept, transcriptPath, size, spend) {
     if (size === kept.offset) return false;
     const fd = fs.openSync(transcriptPath, "r");
     try {
         if (kept.offset > 0 && tailBefore(fd, kept.offset) !== kept.tail) {
-            Object.assign(kept, { offset: 0, tail: "", figures: sessionFigures() });
+            reset(kept);
         }
+        const seen = Buffer.from(kept.seen, "hex");
         const start = kept.offset;
         let position = kept.offset;
+        let replay = false;
         // Joined once the newline lands: joining at every chunk would copy a long line once per chunk it spans.
         let waiting = [];
         while (position < size) {
@@ -125,12 +177,48 @@ function advance(kept, transcriptPath, size) {
             const complete = waiting.length === 0 ? bytes.subarray(0, end) : Buffer.concat([...waiting, bytes.subarray(0, end)]);
             for (const line of complete.toString("utf8").split("\n")) {
                 const read = readLine(line);
-                if (read !== null && !read.malformed) foldFigures(kept.figures, read);
+                if (read === null || read.malformed) continue;
+                const { requests, compactions } = kept.figures;
+                const fresh = kept.figures.fresh === null || kept.figures.pending;
+                const r = read.request;
+                if (r && !r.synthetic) {
+                    const repeated = r.id !== null && membership(seen, r.id, true);
+                    if (repeated && !kept.figures.recent.includes(r.id)) replay = true;
+                    if (!r.sidechain || repeated) {
+                        const input = inputOf(r);
+                        const tracked = [[kept.freshId, kept.freshInput], [kept.latestId, kept.latestInput], [kept.crossingId, kept.crossingInput]];
+                        const recent = kept.recentInputs.find(v => v[0] === r.id);
+                        if (inputUnusable(r) || (recent && (JSON.stringify(recent[1]) !== JSON.stringify(input) || recent[2] !== (r.usageMissing & INPUT_USAGE_MASK))) || (r.id !== null && tracked.some(([id, before]) => id === r.id && (JSON.stringify(before) !== JSON.stringify(input) || kept.freshUnsafe || kept.latestUnsafe)))) replay = true;
+                    }
+                }
+                foldFigures(kept.figures, read);
+                if (compactions !== kept.figures.compactions) Object.assign(kept, { crossing: null, ...validity() });
+                if (r && !r.synthetic && !r.sidechain) {
+                    rememberInput(kept, r);
+                    const unsafe = inputUnusable(r);
+                    if (requests !== kept.figures.requests) {
+                        if (fresh) { kept.freshUnsafe = unsafe; kept.freshId = r.id; kept.freshInput = inputOf(r); }
+                        kept.latestUnsafe = unsafe; kept.latestId = r.id; kept.latestInput = inputOf(r);
+                    } else if (r.id !== null && (r.usageUnsafe & 1)) {
+                        if (r.id === kept.freshId) kept.freshUnsafe = true;
+                        if (r.id === kept.latestId) kept.latestUnsafe = true;
+                    }
+                }
+                if (kept.freshUnsafe || kept.latestUnsafe) continue;
+                if (requests === kept.figures.requests || kept.crossing !== null) continue;
+                try {
+                    const figure = figureOf(kept.figures, spend);
+                    if (figure !== null && figure.saving >= 0) { kept.crossing = { ...kept.figures, recent: [] }; kept.crossingId = r.id; kept.crossingInput = inputOf(r); }
+                } catch (error) {
+                    if (!(error instanceof LedgerError)) throw error;
+                }
             }
             waiting = end + 1 < got ? [bytes.subarray(end + 1)] : [];
             kept.offset = position - (got - end - 1);
         }
         if (kept.offset !== start) kept.tail = tailBefore(fd, kept.offset);
+        kept.seen = seen.toString("hex");
+        if (replay) replayValidity(kept, transcriptPath, spend);
         return kept.offset !== start;
     } finally {
         fs.closeSync(fd);
@@ -165,19 +253,25 @@ function locate(payload, dir) {
     if (!stat.isFile()) return { why: "the transcript could not be read — it is not a file" };
     const sessionId = sessionOf(payload);
     const file = sessionId === null ? null : stateFile(sessionId, dir);
-    const kept = (file === null ? null : restore(file, transcriptPath, stat)) ?? { v: STATE_VERSION, transcript: transcriptPath, ino: stat.ino, offset: 0, tail: "", figures: sessionFigures() };
+    const kept = (file === null ? null : restore(file, transcriptPath, stat)) ?? { v: STATE_VERSION, transcript: transcriptPath, ino: stat.ino, offset: 0, tail: "", seen: emptySeen(), figures: sessionFigures(), comparison: "", crossing: null, recentInputs: [], ...validity() };
     return { transcriptPath, sessionId, stat, file, kept };
 }
 
 function refresh(found, warn, spend) {
     try {
-        if (advance(found.kept, found.transcriptPath, found.stat.size) && found.file !== null) keep(found.file, found.kept, warn);
+        const key = comparisonKey(spend);
+        const changed = found.kept.comparison !== key;
+        if (changed) { reset(found.kept); found.kept.comparison = key; }
+        if ((advance(found.kept, found.transcriptPath, found.stat.size, spend) || changed) && found.file !== null) keep(found.file, found.kept, warn);
     } catch (error) {
         return { why: `the transcript could not be read — ${error.code ?? error.message}` };
     }
     let figure;
+    if (found.kept.freshUnsafe) return { why: "fresh context usage has invalid or missing counters; comparison unavailable (compaction or completed missing fields required)" };
+    if (found.kept.latestUnsafe) return { why: "latest context usage has invalid or missing counters; comparison unavailable (valid next request or completed missing fields required)" };
     try {
         figure = figureOf(found.kept.figures, spend);
+        if (figure !== null) figure.crossing = found.kept.crossing === null ? null : figureOf(found.kept.crossing, spend);
     } catch (error) {
         if (!(error instanceof LedgerError)) throw error;
         return { why: error.message };
@@ -188,35 +282,40 @@ function refresh(found, warn, spend) {
         : { why: "no request is recorded yet", after: "the first recorded request" };
 }
 
-const FINISH = { PostToolUse: "finish the current step, then ", UserPromptSubmit: "finish what this prompt asks, then ", Stop: "" };
-
 export function adviceLine(figure, event = "UserPromptSubmit") {
     const m = figure.multipliers;
-    const assumed =
-        m.source === "declared"
-            ? "multipliers declared"
-            : `multipliers undeclared, so the general read multiplier and the ${m.recorded ? `${m.lifetime === "1h" ? "one-hour" : "five-minute"} writes the host recorded` : "five-minute write the records did not state"}`;
-    return (
-        `Portulan restart advisory: after ${grouped(figure.requests)} requests, each re-reading it, this session's context, ${grouped(figure.context)} tokens, has reached its restart threshold of ` +
-        `${grouped(figure.threshold)} = fresh context ${grouped(figure.fresh)} × (1 + write ${m.write}× / (${figure.horizon} more requests × read ${m.read}×)); ${assumed}. ` +
-        `Continuing costs more in re-reads than restarting: ${FINISH[event]}write the handoff and end the session. Said once.`
-    );
+    const horizon = `${figure.horizon} remaining (${figure.horizonDeclared ? "declared" : "default"})`;
+    const resume = figure.resume == null ? "resume cost unknown; threshold is a lower bound" : `resume ${grouped(figure.resume)} input equivalents`;
+    const comparison = figure.saving < 0 ? "Latest estimate does not favor restarting."
+        : figure.resume != null && figure.horizonDeclared
+        ? `Estimated savings ${savingWords(figure.saving)} input equivalents; consider a handoff and restart if these estimates still fit the task.`
+        : "Restart only if remaining work and recovery cost make it cheaper; finish bounded work when that costs less.";
+    const first = figure.crossing;
+    const history = first && first.requests !== figure.requests
+        ? ` First crossing: request ${grouped(first.requests)}, context ${grouped(first.context)} / threshold ${grouped(first.threshold)} (fresh ${grouped(first.fresh)}, read ${first.multipliers.read}×, write ${first.multipliers.write}×, ${first.multipliers.recorded ? "recorded" : "assumed"} ${first.multipliers.lifetime}).`
+        : "";
+    return `Portulan restart advisory: after ${grouped(figure.requests)} requests, context ${grouped(figure.context)} tokens, threshold ${grouped(figure.threshold)}; ${horizon}, read ${m.read}×, write ${m.write}× (${m.source}); ${resume}.${history} ${comparison} Said once.`;
 }
 
 export function statusLine(figure) {
     const m = figure.multipliers;
-    const multiplied = `${m.source === "declared" ? "multipliers declared" : "multipliers undeclared"}: read ${m.read}×, write ${m.write}×`;
-    const requests = `${grouped(figure.requests)} request${figure.requests === 1 ? "" : "s"}`;
-    return figure.context >= figure.threshold
-        ? `${requests} · context ${compact(figure.context)} has reached its ${compact(figure.threshold)} restart threshold: write the handoff and restart · ${multiplied}`
-        : `${requests} · context ${compact(figure.context)} of a ${compact(figure.threshold)} restart threshold · ${multiplied}`;
+    return `${grouped(figure.requests)} requests · context ${compact(figure.context)} / restart ${compact(figure.threshold)} · ${figure.horizon} remaining (${figure.horizonDeclared ? "declared" : "default"}) · ` +
+        `${figure.resume == null ? "resume cost unknown: lower bound" : `resume ${grouped(figure.resume)} input-equivalent tokens; estimated saving ${savingWords(figure.saving)}`} · ` +
+        `multipliers ${m.source}: read ${m.read}×, write ${m.write}×`;
 }
 
-function once(event, payload, { dir = os.tmpdir(), warn = () => {}, declared = null, horizon = HORIZON } = {}) {
+export function advisoryOutput(figure, event) {
+    const line = adviceLine(figure, event);
+    return event === "Stop"
+        ? JSON.stringify({ decision: "block", reason: line })
+        : JSON.stringify({ hookSpecificOutput: { hookEventName: event, additionalContext: line } });
+}
+
+function once(event, payload, { dir = os.tmpdir(), warn = () => {}, declared = null, horizon = null, resume = null } = {}) {
     // Claude Code 2.1.281: a subagent's tool call carries its own `agent_id` and the main session's transcript,
     // and a subagent told to end its session would end nothing.
     if (typeof payload?.agent_id === "string" && payload.agent_id !== "") return null;
-    // A host can give a block's retry a new session id, where the held-once record would hold it again.
+    // Without the host's retry marker, rotated session ids can repeat the hold.
     if (event === "Stop" && payload?.stop_hook_active === true) return null;
     const sessionId = sessionOf(payload);
     if (sessionId === null) {
@@ -231,12 +330,13 @@ function once(event, payload, { dir = os.tmpdir(), warn = () => {}, declared = n
     const record = event === "Stop" ? heldFile : toldFile;
     // Nothing written since the figures were kept, so nothing compacted: the record at the kept count answers without a read.
     if (found.stat.size === found.kept.offset && fs.existsSync(record(sessionId, found.kept.figures.compactions, dir))) return null;
-    const figure = refresh(found, warn, { declared, horizon });
+    const figure = refresh(found, warn, { declared, horizon, resume });
     if (figure.why !== undefined) {
         warn(figure.why);
         return null;
     }
-    if (figure.context < figure.threshold) return null;
+    if (figure.crossing === null) return null;
+    if (event === "Stop" && (!figure.horizonDeclared || figure.resume === null || !(figure.saving > 0))) return null;
     const mark = (file) => fs.writeFileSync(file, `${figure.context} ${figure.threshold}\n`, { flag: "wx", mode: 0o600 });
     try {
         mark(record(sessionId, figure.compactions, dir));
@@ -250,13 +350,13 @@ function once(event, payload, { dir = os.tmpdir(), warn = () => {}, declared = n
         }
         return null;
     }
-    if (event !== "Stop") return JSON.stringify({ hookSpecificOutput: { hookEventName: event, additionalContext: adviceLine(figure, event) } });
+    if (event !== "Stop") return advisoryOutput(figure, event);
     try {
         mark(toldFile(sessionId, figure.compactions, dir));
     } catch (error) {
         if (error.code !== "EEXIST") warn(`the told-once record could not be written — ${error.code ?? error.message}; the line may come once more after the block`);
     }
-    return JSON.stringify({ decision: "block", reason: adviceLine(figure, event) });
+    return advisoryOutput(figure, event);
 }
 
 export const onTool = (payload, options) => once("PostToolUse", payload, options);
@@ -266,13 +366,24 @@ export const onPrompt = (payload, options) => once("UserPromptSubmit", payload,
 export const onStop = (payload, options) => once("Stop", payload, options);
 
 /** The status line, its context the host's own last-call counts where sent: current where the transcript may lag a request. */
-export function onStatus(payload, { dir = os.tmpdir(), warn = () => {}, declared = null, horizon = HORIZON } = {}) {
+export function onStatus(payload, { dir = os.tmpdir(), warn = () => {}, declared = null, horizon = null, resume = null } = {}) {
     const found = locate(payload, dir);
-    const figure = found.why === undefined ? refresh(found, warn, { declared, horizon }) : found;
+    const figure = found.why === undefined ? refresh(found, warn, { declared, horizon, resume }) : found;
     if (figure.why !== undefined) return figure.after !== undefined ? `restart threshold: after ${figure.after}` : `restart threshold: not known, because ${figure.why}`;
     const usage = payload?.context_window?.current_usage;
-    const counts = usage !== null && typeof usage === "object" ? ["input_tokens", "cache_creation_input_tokens", "cache_read_input_tokens"].map((k) => usage[k]) : [];
-    if (counts.length === 3 && counts.every((n) => Number.isSafeInteger(n) && n >= 0)) figure.context = counts.reduce((a, b) => a + b, 0);
+    if (usage !== undefined && usage !== null) {
+        if (typeof usage !== "object" || Array.isArray(usage)) return "restart threshold: not known, because the current input has missing or invalid counters";
+        const current = usageOf(usage), context = contextOf(current);
+        if (!Number.isSafeInteger(context)) return "restart threshold: not known, because the current input sum is unsafe";
+        if (inputUnusable(current)) return "restart threshold: not known, because the current input has missing or invalid counters";
+        try {
+            figure.saving = restartSaving({ fresh: figure.fresh, context, horizon: figure.horizon, read: figure.multipliers.read, write: figure.multipliers.write, resume: figure.resume ?? 0 });
+        } catch (error) {
+            if (error instanceof LedgerError) return "restart threshold: not known, because the estimated saving overflows";
+            throw error;
+        }
+        figure.context = context;
+    }
     return statusLine(figure);
 }
 
@@ -284,7 +395,7 @@ function readPayload() {
     }
 }
 
-const SPEND_FLAGS = { "--read": "read", "--write-5m": "write", "--write-1h": "write", "--horizon": "requests" };
+const SPEND_FLAGS = { "--read": "read", "--write-5m": "write", "--write-1h": "write", "--horizon": "requests", "--resume-tokens": "resume" };
 
 const MULTIPLIER_FLAGS = ["--read", "--write-5m", "--write-1h"];
 
@@ -294,7 +405,7 @@ const DECIMAL = /^[0-9]+(\.[0-9]+)?(e[+-]?[0-9]+)?$/;
 /** The figures after the mode, `{ declared, horizon, fault }`, each null where absent; a partial multiplier set is undeclared whole. */
 export function spendFlags(args) {
     const values = new Map();
-    const faults = { multipliers: [], horizon: [], other: [] };
+    const faults = { multipliers: [], horizon: [], resume: [], other: [] };
     const shown = (s) => (typeof s === "string" && /^[-+.a-zA-Z0-9]+$/.test(s) ? s : JSON.stringify(s));
     for (let i = 0; i < args.length; i += 2) {
         const [flag, raw] = [args[i], args[i + 1]];
@@ -302,7 +413,7 @@ export function spendFlags(args) {
             faults.other.push(`${shown(flag)} is no flag it takes`);
             continue;
         }
-        const part = flag === "--horizon" ? faults.horizon : faults.multipliers;
+        const part = flag === "--horizon" ? faults.horizon : flag === "--resume-tokens" ? faults.resume : faults.multipliers;
         const range = SPEND_FIGURES[SPEND_FLAGS[flag]];
         const value = typeof raw === "string" && DECIMAL.test(raw) ? Number(raw) : Number.NaN;
         if (values.has(flag)) part.push(`${flag} is given twice`);
@@ -319,10 +430,12 @@ export function spendFlags(args) {
     const said = [];
     if (faults.multipliers.length) said.push(`${faults.multipliers.join(", ")}, so the multipliers are undeclared`);
     if (faults.horizon.length) said.push(`${faults.horizon.join(", ")}, so the horizon is undeclared, and ${HORIZON} requests`);
+    if (faults.resume.length) said.push(`${faults.resume.join(", ")}, so resume cost is unknown`);
     if (faults.other.length) said.push(`${faults.other.join(", ")}, so ${faults.other.length === 1 ? "it is" : "each is"} passed over with the value after it`);
     return {
         declared: missing.length === 0 && !faults.multipliers.length ? { read: values.get("--read"), write: { "5m": values.get("--write-5m"), "1h": values.get("--write-1h") } } : null,
         horizon: values.has("--horizon") && !faults.horizon.length ? values.get("--horizon") : null,
+        resume: values.has("--resume-tokens") && !faults.resume.length ? values.get("--resume-tokens") : null,
         fault: said.length ? said.join("; ") : null,
     };
 }
@@ -334,7 +447,8 @@ export function main(argv = process.argv.slice(2), { stdout = process.stdout, st
     try {
         const figures = spendFlags(argv.slice(1));
         if (figures.fault !== null) warn(`the figures after ${mode} are not all usable — ${figures.fault}`);
-        const priced = { dir, warn, declared: figures.declared, horizon: figures.horizon ?? HORIZON };
+        if (mode === "stop" && figures.fault !== null) return 0;
+        const priced = { dir, warn, declared: figures.declared, horizon: figures.horizon, resume: figures.resume };
         if (mode === "prompt" || mode === "tool" || mode === "stop") {
             const out = { tool: onTool, prompt: onPrompt, stop: onStop }[mode](input, priced);
             if (out !== null) stdout.write(`${out}\n`);

package/cli/cache-risk.mjs

@@ -0,0 +1,69 @@
+// Potential cache risks from project files; host activation is not inferred.
+import fs from "node:fs";
+import path from "node:path";
+import { readOwnedText } from "./compile.mjs";
+
+const object = v => v !== null && typeof v === "object" && !Array.isArray(v);
+const strings = v => Array.isArray(v) && v.every(s => typeof s === "string");
+const scope = "Project files only; full MCP schema, trust, live activation, user/managed/CLI overrides, broader model/MCP policies and untested selectors (including experimental-beta disabling) are unassessed.";
+
+export function cacheRiskLines(root) {
+    const lines = [`Assessed selectors: project model/ANTHROPIC_MODEL (opusplan and conditional Haiku), ENABLE_TOOL_SEARCH=false and ToolSearch denial; ${scope}`];
+    const read = label => {
+        const file = path.join(root, label);
+        try { fs.lstatSync(file); }
+        catch (error) {
+            if (error.code === "ENOENT") return {};
+            lines.push(`${label}: unassessed — project source is unreadable.`); return {};
+        }
+        try {
+            const value = JSON.parse(readOwnedText(file, root));
+            if (!object(value)) throw Error();
+            return value;
+        } catch { lines.push(`${label}: unassessed — project source is unreadable, malformed, nonregular or outside its tree.`); return {}; }
+    };
+    const settings = label => {
+        const value = read(label);
+        if ((value.model !== undefined && typeof value.model !== "string") ||
+            (value.env !== undefined && (!object(value.env) || ["ANTHROPIC_MODEL", "ENABLE_TOOL_SEARCH"].some(k => value.env[k] !== undefined && typeof value.env[k] !== "string"))) ||
+            (value.permissions !== undefined && (!object(value.permissions) || (value.permissions.deny !== undefined && !strings(value.permissions.deny)))) ||
+            ["enabledMcpjsonServers", "disabledMcpjsonServers"].some(k => value[k] !== undefined && !strings(value[k])) ||
+            (value.enableAllProjectMcpServers !== undefined && typeof value.enableAllProjectMcpServers !== "boolean")) {
+            lines.push(`${label}: unassessed — relevant project settings have invalid shapes.`); return {};
+        }
+        return value;
+    };
+    const shared = settings(".claude/settings.json"), local = settings(".claude/settings.local.json");
+    const env = { ...shared.env, ...local.env };
+    const model = env.ANTHROPIC_MODEL || (local.model ?? shared.model);
+    const source = env.ANTHROPIC_MODEL ? "project ANTHROPIC_MODEL" : "project model";
+    if (typeof model === "string" && /^opusplan(?:\[1m\])?$/i.test(model)) {
+        lines.push(`plan-mode model switching configured via ${source}: Opus planning and Sonnet execution can rebuild the model-specific cache at the boundary.`);
+    } else if (typeof model === "string" && /^(?:haiku(?:\[1m\])?|claude-haiku-[a-z0-9.-]+)$/i.test(model)) {
+        lines.push(`plan-mode model upgrade possible via ${source} for a Haiku selection: a permitted Sonnet upgrade can rebuild the model-specific cache. Provider and allowlist behavior is unresolved.`);
+    } else if (model === "") lines.push("project model selection is empty: resolved default and plan-mode behavior are unassessed.");
+    const mcp = read(".mcp.json");
+    const candidates = [];
+    if (mcp.mcpServers !== undefined && !object(mcp.mcpServers)) lines.push(".mcp.json: unassessed — project MCP definitions have an invalid shape.");
+    else for (const [name, server] of Object.entries(mcp.mcpServers ?? {})) {
+        const stdio = object(server) && (server.type === undefined || server.type === "stdio") && typeof server.command === "string" && server.command.trim() !== "";
+        let remote = false;
+        if (object(server) && ["http", "sse", "ws"].includes(server.type) && typeof server.url === "string") {
+            try { remote = (server.type === "ws" ? ["ws:", "wss:"] : ["http:", "https:"]).includes(new URL(server.url).protocol); } catch { /* Invalid endpoint is never printed. */ }
+        }
+        if (!/^[a-zA-Z0-9_-]+$/.test(name) || (!stdio && !remote) || server.disabled !== undefined ||
+            (server.args !== undefined && !strings(server.args)) || (server.env !== undefined && (!object(server.env) || !Object.values(server.env).every(v => typeof v === "string")))) {
+            lines.push(".mcp.json: unassessed — a project MCP definition is unsupported or invalid.");
+        } else candidates.push(name);
+    }
+    const rejected = new Set([...(shared.disabledMcpjsonServers ?? []), ...(local.disabledMcpjsonServers ?? [])]);
+    const approved = new Set([...(shared.enabledMcpjsonServers ?? []), ...(local.enabledMcpjsonServers ?? [])]);
+    const all = local.enableAllProjectMcpServers ?? shared.enableAllProjectMcpServers ?? false;
+    const eligible = candidates.filter(name => !rejected.has(name));
+    const denial = [...(shared.permissions?.deny ?? []), ...(local.permissions?.deny ?? [])].includes("ToolSearch");
+    if (eligible.length && (env.ENABLE_TOOL_SEARCH === "false" || denial)) {
+        const known = eligible.filter(name => all || approved.has(name)).length;
+        lines.push(`tool search disabled by ${denial ? "project ToolSearch denial" : "project ENABLE_TOOL_SEARCH=false"}: ${eligible.length} eligible project MCP candidate(s), ${known} with project-file approval; upfront tool definitions can enlarge or change the cache prefix.`);
+    }
+    return lines;
+}

package/cli/comments.mjs

@@ -764,12 +764,15 @@ export function historyOf(comments) {
     return comments.filter((comment) => kinds.has(comment)).map((comment) => ({ ...comment, kinds: [...kinds.get(comment)] }));
 }
 
-function trackedFiles(root) {
+function trackedFiles(root, timeout, env, noFsmonitor) {
     try {
-        const out = execFileSync("git", ["ls-files", "--cached", "--others", "--exclude-standard", "-z"], {
+        const out = execFileSync("git", [...(noFsmonitor ? ["-c", "core.fsmonitor=false"] : []), "ls-files", "--cached", "--others", "--exclude-standard", "-z"], {
             cwd: root,
             encoding: "utf8",
             maxBuffer: 256 * 1024 * 1024,
+            timeout,
+            env,
+            killSignal: "SIGKILL",
             stdio: ["ignore", "pipe", "pipe"],
         });
         return [...new Set(out.split("\0").filter(Boolean))].sort();
@@ -799,8 +802,8 @@ function readSource(root, file, linked) {
 }
 
 /** Every file the tree holds in a language this reads, with its comments and the ones recording history. */
-export function scan(root, { exclude = [] } = {}) {
-    const files = trackedFiles(root);
+export function scan(root, { exclude = [], timeout, env, noFsmonitor = false } = {}) {
+    const files = trackedFiles(root, timeout, env, noFsmonitor);
     const unused = exclude.filter((prefix) => !files.some((file) => file.startsWith(prefix)));
     if (unused.length) throw new CommentsError(`--exclude ${unused.join(", ")} names no file in the tree: remove it`);
     const read = [];
@@ -822,7 +825,7 @@ export function scan(root, { exclude = [] } = {}) {
 const sum = (items, pick) => items.reduce((total, item) => total + pick(item), 0);
 const figure = (n) => n.toLocaleString("en-US");
 
-export const historyCount = (root) => sum(scan(root), (entry) => entry.history.length);
+export const historyCount = (root, options) => sum(scan(root, options), (entry) => entry.history.length);
 
 function directoryTable(read) {
     const directories = new Map();