@bli-cockpit/cli 0.2.272 → 0.2.274

package/dist/adapters/claude-attribution-memoized-reads.js

@@ -36,7 +36,7 @@ function parseMainRead(data) {
 export async function readSidecar(memo, localPath) {
     const stamp = memo ? await statSourceForMemo(localPath) : null;
     if (memo && stamp) {
-        const hit = memo.recall(localPath, stamp, ATTRIBUTION_READ_RECIPE, stamp.size, parseSidecarRead);
+        const hit = await memo.recall(localPath, stamp, ATTRIBUTION_READ_RECIPE, stamp.size, parseSidecarRead);
         if (hit)
             return hit;
     }
@@ -60,7 +60,7 @@ export async function readSidecar(memo, localPath) {
 export async function readMain(memo, filePath) {
     const stamp = memo ? await statSourceForMemo(filePath) : null;
     if (memo && stamp) {
-        const hit = memo.recall(filePath, stamp, ATTRIBUTION_READ_RECIPE, stamp.size, parseMainRead);
+        const hit = await memo.recall(filePath, stamp, ATTRIBUTION_READ_RECIPE, stamp.size, parseMainRead);
         if (hit)
             return hit;
     }

package/dist/adapters/codex-attribution-memoized-reads.js

@@ -0,0 +1,52 @@
+import { SESSION_FACTS_VERSION, SKILL_USE_VERSION } from "@bli-cockpit/telemetry-core";
+import { readCodexMetadataSignals } from "./codex-session-signals.js";
+import { statSourceForMemo } from "./transcript-read-memo.js";
+/**
+ * The read attribution does of one Codex session file, remembered by the file's stamp (BLI-23346), the sibling
+ * of Claude's `claude-attribution-memoized-reads.ts`. Before this a tick re-streamed and re-hashed every Codex
+ * session in the window (177 files, 490 MB on the reference Mac) although no byte had changed. A Codex session
+ * is one file, so what is remembered is the finished answer of the streaming pass: the metadata signals, the
+ * sha256 and size of the bytes, and the finalized facts. The stamp (size, inode, mtime and ctime in
+ * nanoseconds) is the prepare memo's, so an append, rewrite or replace is read fresh. Scoring against the
+ * worktrees and the cwd-exists check run after the read, on every tick, so a repo that appears or vanishes is
+ * seen at once. Bump SIGNALS_VERSION when `codex-session-signals.ts` changes what it extracts.
+ */
+const SIGNALS_VERSION = "codex-signals.v1";
+export const CODEX_READ_RECIPE = ["codex-reads.v1", SIGNALS_VERSION, SESSION_FACTS_VERSION, SKILL_USE_VERSION].join("|");
+const isStrings = (v) => Array.isArray(v) && v.every((s) => typeof s === "string");
+const isNum = (v) => typeof v === "number" && Number.isFinite(v);
+const isObj = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+function parseCodexRead(data) {
+    if (!isObj(data) || !isNum(data["byteSize"]) || typeof data["contentHashSha256"] !== "string")
+        return null;
+    const s = data["signals"];
+    const facts = data["facts"];
+    if (!isObj(s) || !isObj(facts))
+        return null;
+    for (const key of ["session_ids", "cwds", "workspace_roots", "branches", "commit_hashes", "repository_urls"]) {
+        if (!isStrings(s[key]))
+            return null;
+    }
+    if (!isNum(s["line_count"]) || !isNum(s["parse_error_count"]))
+        return null;
+    if (typeof facts["extractor_version"] !== "string" || facts["source"] !== "codex" || !isObj(facts["usage_by_model"]) || !isNum(facts["transcript_bytes"]))
+        return null;
+    return data;
+}
+/** The session's signals, hash, size and facts: recalled when its stamp is unchanged, else streamed (a read failure throws). */
+export async function readCodexMetadataMemoized(memo, filePath) {
+    const stamp = memo ? await statSourceForMemo(filePath) : null;
+    if (memo && stamp) {
+        const hit = await memo.recall(filePath, stamp, CODEX_READ_RECIPE, stamp.size, parseCodexRead);
+        if (hit)
+            return hit;
+    }
+    else
+        memo?.note("stamp_missing");
+    const read = await readCodexMetadataSignals(filePath);
+    if (memo && stamp) {
+        memo.note("fresh");
+        memo.remember(filePath, stamp, CODEX_READ_RECIPE, read);
+    }
+    return read;
+}

package/dist/adapters/codex-attribution.js

@@ -2,7 +2,8 @@ import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { describeError } from "../health-detail.js";
-import { extractCodexSessionSignals, readCodexMetadataSignals, } from "./codex-session-signals.js";
+import { extractCodexSessionSignals, } from "./codex-session-signals.js";
+import { readCodexMetadataMemoized } from "./codex-attribution-memoized-reads.js";
 import { sanitizeSessionId, scoreSignalsAgainstWorktrees, sessionIdFromFileName, shortHash, } from "./attribution-core.js";
 /**
  * Deterministic Codex session JSONL -> repo/worktree attribution.
@@ -41,7 +42,7 @@ export async function scanAndAttributeCodexSessions(options) {
     const files = discovery.files.slice(0, limit);
     const results = [];
     for (const file of files) {
-        results.push(await attributeOneSession(file, options.worktrees, options.collectionRoots ?? []));
+        results.push(await attributeOneSession(file, options.worktrees, options.collectionRoots ?? [], options.readMemo));
     }
     return {
         results,
@@ -164,11 +165,11 @@ function dedupePaths(values) {
     }
     return out;
 }
-async function attributeOneSession(file, worktrees, collectionRoots) {
+async function attributeOneSession(file, worktrees, collectionRoots, readMemo) {
     const base = createSessionBase(file);
     let read;
     try {
-        read = await readCodexMetadataSignals(file.file);
+        read = await readCodexMetadataMemoized(readMemo, file.file);
     }
     catch (error) {
         // One skipped session, with `file_read_failed` on its row. Logged per

package/dist/adapters/raw-evidence-image-reader.js

@@ -27,7 +27,7 @@ export async function collectAgentImagesFromTranscript(collection, options) {
     const memo = collection.budget.readMemo;
     const stamp = memo ? await statSourceForMemo(options.filePath) : null;
     const remembered = memo && stamp
-        ? memo.recall(options.filePath, stamp, IMAGE_SCAN_RECIPE, stamp.size, (data) => (data === "no_image_candidates" ? true : null))
+        ? await memo.recall(options.filePath, stamp, IMAGE_SCAN_RECIPE, stamp.size, (data) => (data === "no_image_candidates" ? true : null))
         : null;
     if (!remembered && memo && !stamp)
         memo.note("stamp_missing");

package/dist/adapters/transcript-read-memo.js

@@ -5,49 +5,77 @@
  * transcript the image step scans: on the reference Mac 33 of the 37 seconds of main-thread JavaScript went to
  * reading, parsing and hashing files whose size and mtime had not moved since the tick before. This is the
  * sibling of the prepare memo (`raw-evidence-prepare-memo.ts`) and uses ITS stamp: size plus inode, mtime and
- * ctime in nanoseconds, so an append, rewrite or replace is never mistaken for "unchanged". The entry cap, the
- * `seen_ms` ageing and the atomic write are the prepare memo's own helpers.
+ * ctime in nanoseconds, so an append, rewrite or replace is never mistaken for "unchanged". The entry cap and
+ * the 14-day forgetting are the prepare memo's own numbers.
  *
  * An entry is trusted only when the stamp AND the recipe match. The recipe names the rules that produced the
  * remembered answer, so changing a rule rebuilds the memo once. What an entry holds is decided by its caller
  * (`data`); this file never sees a byte of transcript content, and neither does the file on disk: signals,
  * hashes, sizes and counts only. A memo that is lost, corrupt or stale in the safe direction costs one slow
  * tick, never a wrong answer. The file path is hashed, so no path reaches the memo either.
+ *
+ * BLI-23346: one small file per source key under `transcript-read-memo-<name>/`, read on demand. The first
+ * layout was one JSON file; on the reference Mac that reached 18.2 MB (2,931 entries, 1.1 M timestamps), was
+ * parsed whole at open, held through both scan passes and rewritten whole whenever one transcript was fresh.
+ * Now an unchanged transcript costs one small read that is parsed and dropped, a changed one costs one small
+ * atomic write, and nothing else is touched. A hit older than a day gets its `seen_ms` rewritten (one small
+ * file), and a prune pass (at most daily, by file mtime) forgets what was not written or refreshed for 14 days
+ * and the oldest beyond the cap. Exact facts are unchanged: an entry holds the same `data` the caller always
+ * stored (request-id-ordered usage, delta-encoded timestamps), it is only filed apart.
  */
 import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
 import path from "node:path";
-import { isMissingFileFailure } from "../health-detail.js";
-import { readJsonFile, writeJsonFileAtomic } from "../local-state-files.js";
-import { PREPARE_MEMO_MAX_ENTRIES, refreshSeen, trimEntries, } from "./raw-evidence-prepare-memo.js";
+import { describeError } from "../health-detail.js";
+import { isMissingFileError, writeJsonFileAtomic } from "../local-state-files.js";
+import { FORGET_AFTER_MS, PREPARE_MEMO_MAX_ENTRIES, SEEN_REFRESH_MS, } from "./raw-evidence-prepare-memo.js";
 export { sourceStampOf, statSourceForMemo } from "./raw-evidence-prepare-memo.js";
-const MEMO_FORMAT = "transcript-read-memo.v1";
+const MEMO_FORMAT = "transcript-read-memo.v2";
 const TAG = "[transcript-reads]";
+const PRUNE_EVERY_MS = 24 * 3_600_000;
+const PRUNE_MARKER = ".pruned";
+const WRITE_CONCURRENCY = 8;
 export function transcriptReadMemoPath(stateDir, name) {
-    return path.join(stateDir, `transcript-read-memo-${name}.json`);
+    return path.join(stateDir, `transcript-read-memo-${name}`);
 }
 const keyOf = (filePath) => createHash("sha256").update(filePath).digest("hex").slice(0, 32);
+const zeroCounts = () => ({ reused: 0, fresh: 0, stamp_missing: 0, bytes_not_read: 0, unreadable: 0, refreshed: 0 });
 export async function openTranscriptReadMemo(stateDir, name) {
-    const entries = await readEntries(stateDir, name);
-    let dirty = false;
-    let counts = { reused: 0, fresh: 0, stamp_missing: 0, bytes_not_read: 0 };
-    const recalled = new Set();
+    const dir = transcriptReadMemoPath(stateDir, name);
+    const entryPath = (key) => path.join(dir, `${key}.json`);
+    /** Entries remembered this pass, written at `settle`; also answers a second pass over the same file before then. */
+    const pending = new Map();
+    let counts = zeroCounts();
+    await removeLegacySingleFile(stateDir, name);
     return {
-        recall(filePath, stamp, recipe, bytes, parse) {
+        async recall(filePath, stamp, recipe, bytes, parse) {
             const key = keyOf(filePath);
-            const entry = entries.get(key);
+            const fromPending = pending.get(key);
+            let entry = fromPending;
+            if (!entry) {
+                const loaded = await readEntry(entryPath(key));
+                if (loaded === "unreadable")
+                    counts.unreadable += 1;
+                else if (loaded)
+                    entry = loaded;
+            }
             if (!entry || entry.recipe !== recipe || entry.size !== stamp.size || entry.identity !== stamp.identity)
                 return null;
             const data = parse(entry.data);
             if (data === null)
                 return null;
-            recalled.add(key);
             counts.reused += 1;
             counts.bytes_not_read += bytes;
+            const now = Date.now();
+            if (!fromPending && now - entry.seen_ms > SEEN_REFRESH_MS) {
+                entry.seen_ms = now;
+                counts.refreshed += 1;
+                await writeJsonFileAtomic(entryPath(key), entry, { compact: true }).catch(() => undefined);
+            }
             return data;
         },
         remember(filePath, stamp, recipe, data, now = Date.now()) {
-            entries.set(keyOf(filePath), { ...stamp, recipe, data, seen_ms: now });
-            dirty = true;
+            pending.set(keyOf(filePath), { schema_version: MEMO_FORMAT, ...stamp, recipe, data, seen_ms: now });
         },
         note(outcome) {
             if (outcome === "fresh")
@@ -57,53 +85,102 @@ export async function openTranscriptReadMemo(stateDir, name) {
         },
         async settle(now = Date.now()) {
             const done = counts;
-            counts = { reused: 0, fresh: 0, stamp_missing: 0, bytes_not_read: 0 };
-            dirty = refreshSeen(entries, recalled, now) || dirty;
-            recalled.clear();
-            let written = false;
-            let reason = done.reused > 0 ? "stamp_unchanged" : done.fresh > 0 ? "no_reusable_entry" : "stamp_missing";
-            if (dirty) {
-                const before = entries.size;
-                const kept = trimEntries(entries, now, PREPARE_MEMO_MAX_ENTRIES);
-                try {
-                    await writeJsonFileAtomic(transcriptReadMemoPath(stateDir, name), { schema_version: MEMO_FORMAT, entries: Object.fromEntries(kept) }, { compact: true });
-                    dirty = false;
-                    written = true;
-                }
-                catch (error) {
-                    reason = "memo_write_failed";
-                    console.error(TAG + " memo not written; the next tick reads these files again", JSON.stringify({ memo: name, reason, entries: before, error_name: error instanceof Error ? error.name : typeof error }));
+            counts = zeroCounts();
+            const toWrite = [...pending.entries()];
+            pending.clear();
+            let written = 0;
+            let failed = 0;
+            for (let i = 0; i < toWrite.length; i += WRITE_CONCURRENCY) {
+                const outcomes = await Promise.all(toWrite.slice(i, i + WRITE_CONCURRENCY).map(([key, entry]) => writeJsonFileAtomic(entryPath(key), entry, { compact: true }).then(() => true, (error) => {
+                    if (failed === 0)
+                        console.error(TAG + " memo entry not written; that file is read again next tick", JSON.stringify({ memo: name, reason: "memo_write_failed", ...describeError(error) }));
+                    return false;
+                })));
+                for (const ok of outcomes) {
+                    if (ok)
+                        written += 1;
+                    else
+                        failed += 1;
                 }
             }
-            if (done.reused + done.fresh + done.stamp_missing === 0)
+            const pruned = await pruneIfDue(dir, name, now);
+            if (done.reused + done.fresh + done.stamp_missing === 0 && pruned === null)
                 return;
-            console.error(TAG + " tick", JSON.stringify({ memo: name, reason, reused: done.reused, read_fresh: done.fresh, stamp_missing: done.stamp_missing, bytes_not_read: done.bytes_not_read, entries: entries.size, memo_written: written }));
+            const reason = failed > 0 ? "memo_write_failed" : done.reused > 0 ? "stamp_unchanged" : done.fresh > 0 ? "no_reusable_entry" : "stamp_missing";
+            console.error(TAG + " tick", JSON.stringify({
+                memo: name,
+                reason,
+                reused: done.reused,
+                read_fresh: done.fresh,
+                stamp_missing: done.stamp_missing,
+                bytes_not_read: done.bytes_not_read,
+                entries_written: written,
+                entries_write_failed: failed,
+                entries_unreadable: done.unreadable,
+                seen_refreshed: done.refreshed,
+                ...(pruned ? { pruned_expired: pruned.expired, pruned_over_cap: pruned.overCap, kept: pruned.kept } : {}),
+            }));
         },
     };
 }
-async function readEntries(stateDir, name) {
-    const entries = new Map();
-    let raw;
+/** One entry file; null when absent; "unreadable" when it exists but is not an entry (a miss, rewritten by the next fresh read). */
+async function readEntry(file) {
+    let text;
+    try {
+        text = await fs.readFile(file, "utf8");
+    }
+    catch (error) {
+        return isMissingFileError(error) ? null : "unreadable";
+    }
+    try {
+        const e = JSON.parse(text);
+        if (e && e.schema_version === MEMO_FORMAT && typeof e.size === "number" && typeof e.identity === "string" && typeof e.recipe === "string" && typeof e.seen_ms === "number" && e.data !== undefined)
+            return e;
+    }
+    catch {
+        // A torn or foreign file is a miss; the caller counts it as unreadable.
+    }
+    return "unreadable";
+}
+/** The pre-BLI-23346 single file is dead weight (18 MB on the reference Mac): remove it once and say so. */
+async function removeLegacySingleFile(stateDir, name) {
+    const legacy = path.join(stateDir, `transcript-read-memo-${name}.json`);
     try {
-        raw = await readJsonFile(transcriptReadMemoPath(stateDir, name));
+        const { size } = await fs.stat(legacy);
+        await fs.rm(legacy, { force: true });
+        console.error(TAG + " legacy single-file memo removed", JSON.stringify({ memo: name, reason: "legacy_memo_replaced_by_entry_files", bytes: size }));
     }
     catch (error) {
-        if (!isMissingFileFailure(error))
-            console.error(TAG + " memo unreadable; every file is read once", JSON.stringify({ memo: name, reason: "read_memo_unreadable" }));
-        return entries;
+        if (!isMissingFileError(error))
+            console.error(TAG + " legacy memo not removed", JSON.stringify({ memo: name, reason: "legacy_memo_remove_failed", ...describeError(error) }));
     }
-    const stored = raw;
-    if (stored?.schema_version !== MEMO_FORMAT || !stored.entries || typeof stored.entries !== "object")
-        return entries;
-    let dropped = 0;
-    for (const [key, value] of Object.entries(stored.entries)) {
-        const e = value;
-        if (e && typeof e.size === "number" && typeof e.identity === "string" && typeof e.recipe === "string" && typeof e.seen_ms === "number" && e.data !== undefined)
-            entries.set(key, e);
-        else
-            dropped += 1;
+}
+/** At most once a day: forget entries not written or refreshed for 14 days, then the oldest beyond the cap. Null when not due or nothing to prune. */
+async function pruneIfDue(dir, name, now) {
+    const marker = path.join(dir, PRUNE_MARKER);
+    try {
+        const last = await fs.stat(marker).then((s) => s.mtimeMs, () => 0);
+        if (now - last < PRUNE_EVERY_MS)
+            return null;
+        const names = (await fs.readdir(dir)).filter((n) => n.endsWith(".json"));
+        const aged = [];
+        for (const n of names) {
+            const file = path.join(dir, n);
+            const stat = await fs.stat(file).catch(() => null);
+            if (stat)
+                aged.push({ file, mtimeMs: stat.mtimeMs });
+        }
+        const expired = aged.filter((a) => now - a.mtimeMs > FORGET_AFTER_MS);
+        const live = aged.filter((a) => now - a.mtimeMs <= FORGET_AFTER_MS).sort((a, b) => b.mtimeMs - a.mtimeMs);
+        const over = live.slice(PREPARE_MEMO_MAX_ENTRIES);
+        await Promise.all([...expired, ...over].map((a) => fs.rm(a.file, { force: true })));
+        await fs.writeFile(marker, `${new Date(now).toISOString()}\n`);
+        await fs.utimes(marker, new Date(now), new Date(now));
+        return { expired: expired.length, overCap: over.length, kept: live.length - over.length };
+    }
+    catch (error) {
+        if (!isMissingFileError(error))
+            console.error(TAG + " memo prune failed", JSON.stringify({ memo: name, reason: "memo_prune_failed", ...describeError(error) }));
+        return null;
     }
-    if (dropped > 0)
-        console.error(TAG + " memo entries dropped as malformed", JSON.stringify({ memo: name, reason: "read_memo_entries_malformed", dropped, kept: entries.size }));
-    return entries;
 }

package/dist/bookkeeping-session.js

@@ -0,0 +1,82 @@
+/**
+ * Tick-scoped bookkeeping: load each big state file once, write it at checkpoints (BLI-23346).
+ *
+ * The worktree loop of one sync tick used to read the 7 MB raw-evidence cursor and the staging state from disk,
+ * mutate them and write them back (serialise, fsync, rename) once per worktree, about 45 times a tick on the
+ * reference Mac: ~650 MB of JSON churn and ~326 MB of fsync'd writes to say "nothing changed". Inside
+ * `withBookkeepingSession` the first read of a file loads it, later reads return the SAME in-memory object, and a
+ * write only marks it dirty. Dirty files are persisted by the SAME writer the caller named (so fsync, temp file,
+ * rename and pruning are unchanged) at three points: when `CHECKPOINT_MS` has passed since the last flush, and
+ * when the session ends (also on an exception or a yielded loop, before the sync lock is released). A process
+ * killed between checkpoints loses at most that window of bookkeeping, which only means objects are re-offered
+ * next tick (the server dedups by content hash); it never loses a delivery.
+ *
+ * Outside a session every call is the plain disk read / write it always was, so a lone `cockpit sync`, backfill
+ * or doctor behaves exactly as before. Only the worktree loop opens a session, and it holds the sync lock.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import { describeError } from "./health-detail.js";
+const TAG = "[bookkeeping]";
+export const CHECKPOINT_MS = 30_000;
+const storage = new AsyncLocalStorage();
+/** The value for `key`: loaded by `load` on first use inside a session, then served from memory. Outside a session, `load()`. */
+export async function bookkeepingRead(key, load) {
+    const session = storage.getStore();
+    if (!session)
+        return load();
+    const held = session.entries.get(key);
+    if (held) {
+        session.memoryReads += 1;
+        return held.value;
+    }
+    const value = await load();
+    session.diskReads += 1;
+    // `persist` is filled in by the first write; a never-written entry is never dirty.
+    session.entries.set(key, { value, persist: async () => undefined, dirty: false });
+    return value;
+}
+/** Record `value` as the new state of `key`. Inside a session it is persisted at the next checkpoint; outside, now. */
+export async function bookkeepingWrite(key, value, persist) {
+    const session = storage.getStore();
+    if (!session)
+        return persist(value);
+    session.writesRequested += 1;
+    session.entries.set(key, { value, persist: persist, dirty: true });
+    if (Date.now() - session.lastFlushMs >= CHECKPOINT_MS)
+        await flush(session, "checkpoint");
+}
+async function flush(session, why) {
+    session.lastFlushMs = Date.now();
+    const dirty = [...session.entries.values()].filter((entry) => entry.dirty);
+    if (dirty.length === 0)
+        return;
+    session.flushes += 1;
+    for (const entry of dirty) {
+        entry.dirty = false;
+        try {
+            await entry.persist(entry.value);
+            session.filesFlushed += 1;
+        }
+        catch (error) {
+            entry.dirty = true;
+            console.error(TAG + " state not written", JSON.stringify({ reason: why === "end" ? "end_flush_failed" : "checkpoint_flush_failed", ...describeError(error) }));
+            if (why === "checkpoint")
+                throw error;
+        }
+    }
+}
+/** Run `fn` with bookkeeping held in memory; flush whatever is dirty when it settles, however it settles. */
+export async function withBookkeepingSession(fn) {
+    if (storage.getStore())
+        return fn();
+    const session = { entries: new Map(), lastFlushMs: Date.now(), diskReads: 0, memoryReads: 0, writesRequested: 0, flushes: 0, filesFlushed: 0 };
+    try {
+        return await storage.run(session, fn);
+    }
+    finally {
+        await flush(session, "end");
+        if (session.diskReads + session.memoryReads + session.writesRequested > 0) {
+            console.error(TAG + " session settled", JSON.stringify({ reason: "session_end", disk_reads: session.diskReads, memory_reads: session.memoryReads, writes_requested: session.writesRequested, flush_count: session.flushes, files_written: session.filesFlushed }));
+        }
+    }
+}

package/dist/commands/local.js

@@ -1,78 +1,11 @@
-import { runOpsCommand } from "./local-run-ops.js";
-import { runGlossary } from "./glossary.js";
-import { runSpend } from "./spend.js";
-import { runSessionsForget } from "./sessions-forget.js";
-import { runPush } from "./push.js";
 import { defaultIo, writeLine } from "./cli-io.js";
 import { isLocalHelpRequest, localCommandHelp } from "./local-help.js";
 import { beginStage, endStage } from "../crash-guard.js";
 import { reportCommandFailure, refuseArguments, stripGlobalToggles, watchWrites } from "./local-run-guards.js";
-import { reportInstallEventsBestEffort } from "./install-receipts.js";
-import { persistOnboardingRootConfig, resolveOnboardingRootsForCommand, } from "./collection-roots.js";
 import { rememberDiscoveryLimits } from "./local-discovery.js";
-import { runInstall, runRelease, runSelfUpdate, runUpdate } from "./install-update.js";
-import { runOnboard } from "./onboard.js";
-import { runLogin } from "./login.js";
-import { runLogout } from "./logout.js";
-import { runStart } from "./start.js";
-import { runSync } from "./sync.js";
-import { runDoctorAfterSync } from "./sync-doctor.js";
-import { runAnalyze } from "./analyze.js";
-import { runBackfillCommand } from "./backfill.js";
-import { runDoctor } from "./doctor.js";
-import { runStatus } from "./status.js";
-import { runSessions } from "./sessions.js";
-import { runJarvis } from "./jarvis.js";
-import { runModels } from "./models.js";
-import { runSlack } from "./slack.js";
-import { runModel, runSettings } from "./settings.js";
-import { runTeam } from "./team.js";
-import { runWorkbook } from "./workbook.js";
-import { runBrief } from "./brief.js";
-import { runBriefEdit } from "./brief-edit.js";
-import { runBriefRewrite } from "./brief-rewrite.js";
-import { runBriefDone } from "./brief-done.js";
-import { runCorrect } from "./correct.js";
-import { runNotes } from "./notes.js";
-import { runServe } from "./serve.js";
-import { runAutostart } from "./autostart-command.js";
-import { runAgentRules } from "./agent-rules-command.js";
-import { runMemoryLog } from "./memory-log.js";
-import { runMemoryInstall } from "./memory-install.js";
-import { runMemoryStore, runMemoryVerbList } from "./memory-store.js";
-import { runClean } from "./clean.js";
-import { runSourcesCheck } from "./sources-check.js";
-import { runDocs } from "./docs.js";
-import { runMsg } from "./msg.js";
-import { runIssue } from "./issue.js";
-import { runCal } from "./cal.js";
-import { runMail } from "./mail.js";
-import { runProject } from "./project.js";
-import { runMilestone } from "./milestone.js";
-import { runGithub } from "./github.js";
-import { runSearch } from "./search.js";
-import { runCareers } from "./careers.js";
-import { runRename } from "./rename-scope.js";
-import { runSetup } from "./setup.js";
-import { runUsage } from "./usage.js";
-import { runSpeed } from "./speed.js";
-import { runLogs } from "./logs.js";
-import { runApprovals, runDrills } from "./approvals.js";
-import { runManager } from "./manager.js";
-import { runImage } from "./image.js";
-import { runBrain } from "./brain.js";
-import { runHits } from "./hits.js";
-import { runIntentions } from "./intentions.js";
-import { runWho } from "./who.js";
-import { runPeople } from "./people.js";
 import { parseLocalArgs } from "./local-args.js";
-// `./local.js` is the published entry point (the public CLI root, root.ts, doctor.ts, tests): a split must not move a name off it.
+// `./local.js` is the published entry point (the public CLI root, root.ts): it keeps the help registry names and loads each command module only when that command runs (BLI-23349).
 export { rootCommandNames, localCommandHelp, SURFACE_ALIASES, unknownCommandJson, unknownCommandLine, } from "./local-help.js";
-export { buildCollectorHeartbeat, collectionRootLabel, collectionRootLabels, sendCollectorHeartbeatBestEffort, } from "./heartbeat.js";
-export { classifySyncFailureRecords, classifySyncHealthError, redactedSyncErrorDetail, reportInstallEventsBestEffort, SYNC_ERROR_DETAIL_MAX_CHARS, } from "./install-receipts.js";
-export { assertCollectionRootPersisted } from "./collection-roots.js";
-export { runSelfUpdate, SelfUpdateError, } from "./install-update.js";
-import { runRoots } from "./roots.js";
 /** Commands that act on THIS machine; the rest talk to Tower. */
 const MACHINE_COMMAND_KINDS = [
     "roots",
@@ -101,7 +34,9 @@ const MACHINE_COMMAND_KINDS = [
 function isMachineCommand(command) {
     return MACHINE_COMMAND_KINDS.includes(command.kind);
 }
-export async function runLocalCockpitCli(argv, io = { ...defaultIo(), runDoctorAfterSync }) {
+/** `sync` is the only caller of this hook; the module loads when it is first called, not at startup. */
+const lazyRunDoctorAfterSync = async (...args) => (await import("./sync-doctor.js")).runDoctorAfterSync(...args);
+export async function runLocalCockpitCli(argv, io = { ...defaultIo(), runDoctorAfterSync: lazyRunDoctorAfterSync }) {
     argv = stripGlobalToggles(argv);
     if (isLocalHelpRequest(argv)) {
         writeLine(io.stdout, localCommandHelp(argv[0]));
@@ -131,7 +66,7 @@ export async function runLocalCockpitCli(argv, io = { ...defaultIo(), runDoctorA
     try {
         // Not awaited, as it never was: a `cal` rejection bypasses the net below.
         if (command.kind === "cal")
-            return runCal(command, io);
+            return (await import("./cal.js")).runCal(command, io);
         if (isMachineCommand(command))
             return await runMachineCommand(command, io);
         return await runTowerCommand(command, io);
@@ -145,86 +80,86 @@ export async function runLocalCockpitCli(argv, io = { ...defaultIo(), runDoctorA
 }
 async function runMachineCommand(command, io) {
     switch (command.kind) {
-        case "roots": return await runRoots(command, io);
-        case "install": return await runInstall(command, io);
-        case "onboard": return await runOnboard(command, io);
-        case "update": return await runUpdate(command, io);
+        case "roots": return await (await import("./roots.js")).runRoots(command, io);
+        case "install": return await (await import("./install-update.js")).runInstall(command, io);
+        case "onboard": return await (await import("./onboard.js")).runOnboard(command, io);
+        case "update": return await (await import("./install-update.js")).runUpdate(command, io);
         case "doctor":
-            return await runDoctor(command, io, {
-                reportInstallEvents: reportInstallEventsBestEffort,
-                selfUpdate: runSelfUpdate,
+            return await (await import("./doctor.js")).runDoctor(command, io, {
+                reportInstallEvents: (await import("./install-receipts.js")).reportInstallEventsBestEffort,
+                selfUpdate: (await import("./install-update.js")).runSelfUpdate,
                 runLogin: runDoctorLogin,
                 resolveAndSaveRoots: resolveAndSaveDoctorRoots,
             });
-        case "login": return await runLogin(command, io);
-        case "logout": return await runLogout(command, io);
-        case "start": return await runStart(command, io);
-        case "sync": return await runSync(command, io);
-        case "analyze": return await runAnalyze(command, io);
-        case "backfill": return await runBackfillCommand(command, io);
-        case "status": return await runStatus(command, io);
-        case "sessions": return await runSessions(command, io);
-        case "serve": return await runServe(command, io);
-        case "autostart": return await runAutostart(command, io);
-        case "agent-rules": return await runAgentRules(command, io);
-        case "memory-log": return await runMemoryLog(command, io);
+        case "login": return await (await import("./login.js")).runLogin(command, io);
+        case "logout": return await (await import("./logout.js")).runLogout(command, io);
+        case "start": return await (await import("./start.js")).runStart(command, io);
+        case "sync": return await (await import("./sync.js")).runSync(command, io);
+        case "analyze": return await (await import("./analyze.js")).runAnalyze(command, io);
+        case "backfill": return await (await import("./backfill.js")).runBackfillCommand(command, io);
+        case "status": return await (await import("./status.js")).runStatus(command, io);
+        case "sessions": return await (await import("./sessions.js")).runSessions(command, io);
+        case "serve": return await (await import("./serve.js")).runServe(command, io);
+        case "autostart": return await (await import("./autostart-command.js")).runAutostart(command, io);
+        case "agent-rules": return await (await import("./agent-rules-command.js")).runAgentRules(command, io);
+        case "memory-log": return await (await import("./memory-log.js")).runMemoryLog(command, io);
         case "memory":
             // BLI-4047: a bare `cockpit memory` says what the noun does. It used
             // to install; `install` is still one word away and every unattended
             // caller asks for it by name in code.
             if (command.action === "help")
-                return runMemoryVerbList(io, command.json);
-            return await runMemoryInstall(command, io);
-        case "memory-store": return await runMemoryStore(command, io);
-        case "clean": return await runClean(command, io);
-        case "sources": return await runSourcesCheck(command, io);
-        case "release": return await runRelease(command, io);
+                return (await import("./memory-store.js")).runMemoryVerbList(io, command.json);
+            return await (await import("./memory-install.js")).runMemoryInstall(command, io);
+        case "memory-store": return await (await import("./memory-store.js")).runMemoryStore(command, io);
+        case "clean": return await (await import("./clean.js")).runClean(command, io);
+        case "sources": return await (await import("./sources-check.js")).runSourcesCheck(command, io);
+        case "release": return await (await import("./install-update.js")).runRelease(command, io);
     }
 }
 async function runTowerCommand(command, io) {
     switch (command.kind) {
-        case "jarvis": return await runJarvis(command, io);
-        case "model": return await runModel(command, io);
-        case "models": return await runModels(command, io);
+        case "jarvis": return await (await import("./jarvis.js")).runJarvis(command, io);
+        case "model": return await (await import("./settings.js")).runModel(command, io);
+        case "models": return await (await import("./models.js")).runModels(command, io);
         case "scout":
         case "ci":
         case "delivery":
         case "ops":
-            return await runOpsCommand(command, io);
-        case "slack": return await runSlack(command, io);
-        case "settings": return await runSettings(command, io);
-        case "team": return await runTeam(command, io);
-        case "workbook": return await runWorkbook(command, io);
+            return await (await import("./local-run-ops.js")).runOpsCommand(command, io);
+        case "slack": return await (await import("./slack.js")).runSlack(command, io);
+        case "settings": return await (await import("./settings.js")).runSettings(command, io);
+        case "team": return await (await import("./team.js")).runTeam(command, io);
+        case "workbook": return await (await import("./workbook.js")).runWorkbook(command, io);
         case "brief": return await runBriefVerb(command, io);
-        case "correct": return await runCorrect(command, io);
-        case "notes": return await runNotes(command, io);
-        case "glossary": return await runGlossary(command, io);
-        case "sessions-forget": return await runSessionsForget(command, io);
-        case "spend": return await runSpend(command, io);
-        case "push": return await runPush(command, io);
-        case "docs": return await runDocs(command, io);
-        case "msg": return await runMsg(command, io);
-        case "issue": return await runIssue(command, io);
-        case "mail": return await runMail(command, io);
-        case "project": return await runProject(command, io);
-        case "milestone": return await runMilestone(command, io);
-        case "search": return await runSearch(command, io);
-        case "github": return await runGithub(command, io);
-        case "careers": return await runCareers(command, io);
-        case "rename": return await runRename(command, io);
-        case "setup": return await runSetup(command, io);
-        case "usage": return await runUsage(command, io);
-        case "speed": return await runSpeed(command, io);
-        case "logs": return await runLogs(command, io);
-        case "brain": return await runBrain(command, io);
-        case "hits": return await runHits(command, io);
-        case "intentions": return await runIntentions(command, io);
-        case "who": return await runWho(command, io);
-        case "people": return await runPeople(command, io);
-        case "approvals": return await runApprovals(command, io);
-        case "drills": return await runDrills(command, io);
-        case "manager": return await runManager(command, io);
-        case "image": return await runImage(command, io);
+        case "correct": return await (await import("./correct.js")).runCorrect(command, io);
+        case "notes": return await (await import("./notes.js")).runNotes(command, io);
+        case "glossary": return await (await import("./glossary.js")).runGlossary(command, io);
+        case "sessions-forget": return await (await import("./sessions-forget.js")).runSessionsForget(command, io);
+        case "spend": return await (await import("./spend.js")).runSpend(command, io);
+        case "push": return await (await import("./push.js")).runPush(command, io);
+        case "docs": return await (await import("./docs.js")).runDocs(command, io);
+        case "msg": return await (await import("./msg.js")).runMsg(command, io);
+        case "issue": return await (await import("./issue.js")).runIssue(command, io);
+        case "mail": return await (await import("./mail.js")).runMail(command, io);
+        case "project": return await (await import("./project.js")).runProject(command, io);
+        case "milestone": return await (await import("./milestone.js")).runMilestone(command, io);
+        case "search": return await (await import("./search.js")).runSearch(command, io);
+        case "github": return await (await import("./github.js")).runGithub(command, io);
+        case "careers": return await (await import("./careers.js")).runCareers(command, io);
+        case "rename": return await (await import("./rename-scope.js")).runRename(command, io);
+        case "setup": return await (await import("./setup.js")).runSetup(command, io);
+        case "usage": return await (await import("./usage.js")).runUsage(command, io);
+        case "speed": return await (await import("./speed.js")).runSpeed(command, io);
+        case "logs": return await (await import("./logs.js")).runLogs(command, io);
+        case "brain": return await (await import("./brain.js")).runBrain(command, io);
+        case "hits": return await (await import("./hits.js")).runHits(command, io);
+        case "intentions": return await (await import("./intentions.js")).runIntentions(command, io);
+        case "who": return await (await import("./who.js")).runWho(command, io);
+        case "people": return await (await import("./people.js")).runPeople(command, io);
+        case "approvals": return await (await import("./approvals.js")).runApprovals(command, io);
+        case "drills": return await (await import("./approvals.js")).runDrills(command, io);
+        case "manager": return await (await import("./manager.js")).runManager(command, io);
+        case "image": return await (await import("./image.js")).runImage(command, io);
     }
 }
 /**
@@ -235,17 +170,17 @@ async function runTowerCommand(command, io) {
  */
 async function runBriefVerb(command, io) {
     if (command.action === "edit")
-        return await runBriefEdit(command, io);
+        return await (await import("./brief-edit.js")).runBriefEdit(command, io);
     if (command.action === "rewrite")
-        return await runBriefRewrite(command, io);
+        return await (await import("./brief-rewrite.js")).runBriefRewrite(command, io);
     // BLI-3605: the board's done checkbox, at a terminal.
     if (command.action === "done" || command.action === "undone") {
-        return await runBriefDone(command, io);
+        return await (await import("./brief-done.js")).runBriefDone(command, io);
     }
-    return await runBrief(command, io);
+    return await (await import("./brief.js")).runBrief(command, io);
 }
 async function runDoctorLogin(command, io) {
-    return runLogin({
+    return (await import("./login.js")).runLogin({
         kind: "login",
         homeDir: command.homeDir,
         dashboardUrl: command.dashboardUrl,
@@ -265,8 +200,9 @@ async function resolveAndSaveDoctorRoots(command, io) {
         // headless equivalent for scripted and scheduled runs.
         allowHomeRoot: command.allowHomeRoot,
     };
-    const resolution = await resolveOnboardingRootsForCommand(rootCommand, io);
-    await persistOnboardingRootConfig(rootCommand, resolution);
+    const roots = await import("./collection-roots.js");
+    const resolution = await roots.resolveOnboardingRootsForCommand(rootCommand, io);
+    await roots.persistOnboardingRootConfig(rootCommand, resolution);
     if (!command.json) {
         writeLine(io.stdout, `Saved collection roots: ${resolution.collectionRoots.join(", ")}`);
     }

package/dist/commands/memory-install-config.js

@@ -31,7 +31,7 @@ export async function resolveMemoryMcpBin(options) {
 export async function resolveMemoryConfig(command, io, platform, deps) {
     const dashboardUrl = await resolveDashboardUrl(command, deps);
     const found = await resolveMemoryMcpBin({
-        env: envWithNodeRuntimeOnPath(io.env ?? process.env),
+        env: envWithNodeRuntimeOnPath(io.env ?? process.env, undefined, platform),
         platform,
         fileExists: deps.fileExists,
         cliEntryPoint: deps.cliEntryPoint,

package/dist/commands/public-root.js

@@ -21,7 +21,7 @@ export async function runCockpitCli(argv, io) {
   }
 
   if (command === "--version" || command === "-V" || command === "version") {
-    writeLine(io?.stdout ?? process.stdout, "0.2.272");
+    writeLine(io?.stdout ?? process.stdout, "0.2.274");
     return 0;
   }
 

package/dist/commands/session-sync-scan.js

@@ -12,6 +12,7 @@ import { saveRootWorkScan } from "../root-work.js";
 import { CODEX_ATTRIBUTION_SCAN_WINDOW_SESSION_LIMIT, CODEX_ATTRIBUTION_SCAN_WINDOW_MINUTES, defaultCodexSessionDirs, scanAndAttributeCodexSessions, } from "../adapters/codex-attribution.js";
 import { scanAndAttributeClaudeSessions, } from "../adapters/claude-attribution.js";
 import { CLAUDE_CURSOR_FILENAME } from "../cursors/raw-evidence-cursor.js";
+import { isRedactionStubObjectKey } from "../cursors/raw-evidence-stub-entry.js";
 import { clearSourceRetryFailure, recordSourceRetryFailure, } from "../spool/local-spool.js";
 import { claudeAttributionReadFailureCount, codexAttributionReadFailureCount, } from "./agent-session-report.js";
 import { widenForCatchUp } from "./session-sync-outside-roots.js";
@@ -37,6 +38,7 @@ export async function scanAndAttributeBothSources(options) {
         retryPending: plan.codexRetryPending,
         retrySinceMinutes: plan.codexRetrySinceMinutes,
         outsideRootCatchUpPending: plan.outsideRootCatchUpPending,
+        stateDir: options.paths.state_dir,
     });
     // First run (D B.4 §8): without a Claude cursor yet, widen the window to 14
     // days so the first sync captures retroactive history instead of only 24h.
@@ -60,7 +62,7 @@ export async function scanAndAttributeBothSources(options) {
             source: "codex",
             attemptedAt: options.now.toISOString(),
             pendingBefore: plan.codexSourceRetryPending,
-            reason: sourceScanRetryReason("codex", codexAttribution),
+            reason: sourceScanRetryReason("codex", codexAttribution, plan.codexCursorBefore),
         });
     }
     if (plan.claudeEnabled) {
@@ -69,7 +71,7 @@ export async function scanAndAttributeBothSources(options) {
             source: "claude_code",
             attemptedAt: options.now.toISOString(),
             pendingBefore: plan.claudeSourceRetryPending,
-            reason: sourceScanRetryReason("claude_code", claudeAttribution),
+            reason: sourceScanRetryReason("claude_code", claudeAttribution, plan.claudeCursorBefore),
         });
     }
     await saveRootWorkScan(options.paths, [...codexAttribution.results, ...claudeAttribution.results], options.now);
@@ -89,28 +91,37 @@ async function scanCodexSessionsForSync(options) {
     const sinceMinutes = widenForCatchUp(options.retryPending
         ? options.retrySinceMinutes
         : CODEX_ATTRIBUTION_SCAN_WINDOW_MINUTES, options.outsideRootCatchUpPending, CODEX_ATTRIBUTION_SCAN_WINDOW_MINUTES);
-    let scan = await scanAndAttributeCodexSessions({
-        sessionsDirs: defaultCodexSessionDirs(options.homeDir),
-        worktrees: options.worktrees,
-        now: options.now,
-        sinceMinutes,
-        limit: CODEX_ATTRIBUTION_SCAN_WINDOW_SESSION_LIMIT,
-        collectionRoots: options.collectionRoots,
-    });
-    if (scan.session_limit_applied) {
-        // Re-run once, bounded by exactly what the first pass discovered, so a
-        // capped scan still returns every session it found instead of silently
-        // truncating at the window's default limit.
-        scan = await scanAndAttributeCodexSessions({
+    // BLI-23346: one memo for both passes, settled once, so an unchanged session file is never streamed again.
+    const readMemo = await openTranscriptReadMemo(options.stateDir, "codex_attribution").catch(() => undefined);
+    try {
+        let scan = await scanAndAttributeCodexSessions({
             sessionsDirs: defaultCodexSessionDirs(options.homeDir),
             worktrees: options.worktrees,
             now: options.now,
             sinceMinutes,
-            limit: scan.discovered_file_count,
+            limit: CODEX_ATTRIBUTION_SCAN_WINDOW_SESSION_LIMIT,
             collectionRoots: options.collectionRoots,
+            readMemo,
         });
+        if (scan.session_limit_applied) {
+            // Re-run once, bounded by exactly what the first pass discovered, so a
+            // capped scan still returns every session it found instead of silently
+            // truncating at the window's default limit.
+            scan = await scanAndAttributeCodexSessions({
+                sessionsDirs: defaultCodexSessionDirs(options.homeDir),
+                worktrees: options.worktrees,
+                now: options.now,
+                sinceMinutes,
+                limit: scan.discovered_file_count,
+                collectionRoots: options.collectionRoots,
+                readMemo,
+            });
+        }
+        return scan;
+    }
+    finally {
+        await readMemo?.settle();
     }
-    return scan;
 }
 /**
  * Scan and attribute Claude sessions for this sync — the Claude counterpart to
@@ -155,7 +166,7 @@ async function scanClaudeSessionsForSync(options) {
         await readMemo?.settle();
     }
 }
-export function sourceScanRetryReason(source, scan) {
+export function sourceScanRetryReason(source, scan, cursorBefore) {
     const reasons = new Set();
     const failure = sourceScanFailureReason(source, scan);
     if (failure)
@@ -164,11 +175,30 @@ export function sourceScanRetryReason(source, scan) {
     // reason to widen the next scan window, because the transcript fallback can
     // still attribute it. It is not a reason to call this sync failed — see
     // `sourceScanFailureReason`.
-    if (scan.results.some((result) => result.reason === "repo_not_on_disk")) {
+    //
+    // BLI-23346: only while that session still owes its upload. A `repo_not_on_disk` session the cursor already
+    // holds a durable pointer for owes nothing, and widening for it re-scanned 30 days every tick on the reference
+    // Mac (the widened window found the same already-delivered sessions again, which re-armed the flag).
+    const owing = scan.results.filter((result) => result.reason === "repo_not_on_disk" && sessionStillOwesUpload(source, result, cursorBefore));
+    if (owing.length > 0) {
         reasons.add("repo_not_on_disk");
     }
+    else if (cursorBefore) {
+        const delivered = scan.results.filter((result) => result.reason === "repo_not_on_disk").length;
+        if (delivered > 0)
+            console.error("[session-sync] repo_not_on_disk sessions are already delivered, no scan retry kept", JSON.stringify({ reason: "repo_not_on_disk_already_durable", source, delivered_count: delivered }));
+    }
     return reasons.size > 0 ? [...reasons].sort().join(",") : null;
 }
+function sessionStillOwesUpload(source, result, cursorBefore) {
+    if (!cursorBefore)
+        return true;
+    const sessionId = source === "codex"
+        ? result.codex_session_id
+        : result.claude_session_id;
+    const key = cursorBefore.sessions[sessionId]?.uploaded_object_key;
+    return !key || isRedactionStubObjectKey(key);
+}
 /**
  * The part of the scan outcome that is a genuine FAILURE: the session store
  * itself could not be read, so sessions that exist were not seen.

package/dist/commands/session-sync-upload.js

@@ -6,6 +6,7 @@
  * and the Claude growth damper lives here because it is the only step that can
  * see both what the cursor already made durable and what is about to be sent.
  */
+import { withBookkeepingSession } from "../bookkeeping-session.js";
 import { startLocalWorkContext, startLocalWorkContextForAttributedTarget, } from "../local-state.js";
 import { LocalUploadBlockedError, syncLocalAmbientEnvelope, } from "../upload.js";
 import { RAW_EVIDENCE_DEFAULT_BYTE_BUDGET, RAW_EVIDENCE_DEFAULT_OBJECT_BUDGET, } from "../adapters/raw-evidence.js";
@@ -41,12 +42,14 @@ export async function syncEveryTargetWorktree(options) {
     };
     // BLI-11112: a waiting backfill takes the lock at the next worktree
     // boundary; the worktrees not reached stay pending for it or the next tick.
-    const loop = await runYieldingAtBoundaries({
+    // BLI-23346: the cursor and the staging state are loaded once for the whole loop and written at checkpoints and
+    // when the loop ends (before the lock is released), not read and rewritten per worktree.
+    const loop = await withBookkeepingSession(() => runYieldingAtBoundaries({
         items: syncWorktrees,
         shouldYield: run.yieldCheck,
         describe: (outcome) => ({ status: outcome.sync.status }),
         runOne: (worktree) => syncTargetWithAllowance(options, worktree, syncWorktrees, rawEvidenceBudget, discoveredWorktreeKeys, dampedClaudePointers),
-    });
+    }));
     const outcomes = loop.results;
     const everyWorktreeUploaded = outcomes.every((outcome) => outcome.sync.status === "uploaded");
     return {

package/dist/commands/tower-mcp-install.js

@@ -26,7 +26,7 @@ import { envWithNodeRuntimeOnPath } from "../scheduled-self-update.js";
 async function resolveTowerConfig(deps) {
     const found = await resolveMcpBin({
         binName: TOWER_MCP_BIN,
-        env: envWithNodeRuntimeOnPath(deps.env),
+        env: envWithNodeRuntimeOnPath(deps.env, undefined, deps.platform),
         platform: deps.platform,
         fileExists: deps.fileExists,
         cliEntryPoint: deps.cliEntryPoint,

package/dist/cursors/raw-evidence-cursor.js

@@ -1,6 +1,7 @@
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { bookkeepingRead, bookkeepingWrite } from "../bookkeeping-session.js";
 import { describeError, isMissingFileFailure } from "../health-detail.js";
 /**
  * Durable local cursor for raw-evidence harvesting.
@@ -37,7 +38,22 @@ export function emptyRawEvidenceCursorState() {
         sessions: {},
     };
 }
+/**
+ * Inside a worktree-loop bookkeeping session the cursor is loaded once and handed out as one shared object
+ * (`bookkeeping-session.ts`, BLI-23346); anywhere else this is the plain disk read.
+ */
 export async function readRawEvidenceCursor(paths, options = {}) {
+    let key;
+    try {
+        key = rawEvidenceCursorPath(paths, options.filename);
+    }
+    catch {
+        // Paths without a cursors dir: the disk reader below reports it exactly as it always did.
+        return readRawEvidenceCursorFromDisk(paths, options);
+    }
+    return bookkeepingRead(key, () => readRawEvidenceCursorFromDisk(paths, options));
+}
+async function readRawEvidenceCursorFromDisk(paths, options) {
     try {
         const raw = JSON.parse(await fs.readFile(rawEvidenceCursorPath(paths, options.filename), "utf8"));
         return parseCursorState(raw);
@@ -59,6 +75,9 @@ export async function readRawEvidenceCursor(paths, options = {}) {
     }
 }
 export async function writeRawEvidenceCursor(paths, state, options = {}) {
+    await bookkeepingWrite(rawEvidenceCursorPath(paths, options.filename), state, (held) => writeRawEvidenceCursorToDisk(paths, held, options));
+}
+async function writeRawEvidenceCursorToDisk(paths, state, options) {
     const filePath = rawEvidenceCursorPath(paths, options.filename);
     await fs.mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 });
     const pruned = pruneCursorState(state);

package/dist/image-byte-scan.js

@@ -1,185 +1,2 @@
-/**
- * Find the embedded images of one transcript line without ever building the base64 as a JS string
- * (BLI-23317, stage D).
- *
- * `findEmbeddedImages` (telemetry-core/transcript-images.ts) is the RULE and stays the test oracle: it
- * feeds `evidenceRulesFingerprint`, so its regex and its results do not change. This module is the same
- * rule run on the line's BYTES, which is what the streamed prepare path calls:
- *
- *  - a whole-string payload: a base64 run that starts right after a `"`, starts with one of the four
- *    image starts (`iVBOR`, `/9j/`, `R0lGO`, `UklGR`), is at least 495 characters past that start
- *    (so 499 for a JPEG, 500 for the others, exactly as the regex counts) and is closed by `"` or `\"`;
- *  - a data URL: `data:image/<[a-z0-9.+-]+>;base64,` and then a run of at least 500 characters, no closing
- *    quote needed. The whole URL is the replaced range.
- *
- * A match is accepted only when the decoded bytes sniff as PNG, JPEG, GIF or WebP; either way the scan
- * resumes after the run, as `matchAll` does. All matched characters are ASCII, so a byte offset here is
- * the character offset there on ASCII text, and the replaced ranges are the same everywhere else.
- *
- * Decoding is incremental: the run is decoded in blocks of 48 Ki characters (a multiple of 4, so each
- * block decodes on its own) straight into a sha256, with the first block sniffed. At no point does a
- * string of the run, or a Buffer of the whole decoded image, exist. The one exception is a run whose
- * `=` characters are not plain trailing padding: Node's decoder rules for those are version specific,
- * so such a run takes the whole-run decode the oracle takes (never seen in real transcripts).
- *
- * `byteSize` is the length Node's `Buffer.from(run, "base64")` gives, because every block, including a
- * short last one, is decoded by that very function.
- */
-import { createHash } from "node:crypto";
-import { IMAGE_MIN_BASE64_CHARS, sniffImageMediaType, } from "@bli-cockpit/telemetry-core";
-const QUOTE = 0x22;
-const BACKSLASH = 0x5c;
-const EQUALS = 0x3d;
-/** Characters per decoded block. A multiple of 4: each block is a whole number of base64 quanta. */
-const BLOCK_CHARS = 48 * 1024;
-const BASE64 = new Uint8Array(256);
-for (const range of ["AZ", "az", "09"]) {
-    for (let code = range.charCodeAt(0); code <= range.charCodeAt(1); code += 1)
-        BASE64[code] = 1;
-}
-for (const char of "+/=")
-    BASE64[char.charCodeAt(0)] = 1;
-const DATA_URL_LOWER = new Uint8Array(256);
-for (const range of ["az", "09"]) {
-    for (let code = range.charCodeAt(0); code <= range.charCodeAt(1); code += 1)
-        DATA_URL_LOWER[code] = 1;
-}
-for (const char of ".+-")
-    DATA_URL_LOWER[char.charCodeAt(0)] = 1;
-/** The four image starts of a whole-string payload, and the data URL anchor. */
-const STARTS = ["iVBOR", "/9j/", "R0lGO", "UklGR"].map((text) => Buffer.from(text, "latin1"));
-const DATA_URL = Buffer.from("data:image/", "latin1");
-const BASE64_TAG = Buffer.from(";base64,", "latin1");
-/** Is there any chance this line holds an image? Same anchors as the string check, on bytes. */
-export function bytesMayHoldImage(line) {
-    return line.includes(DATA_URL) || STARTS.some((start) => line.includes(start));
-}
-/** The end (exclusive) of the base64-alphabet run that starts at `from`. */
-function runEnd(line, from) {
-    let at = from;
-    while (at < line.length && BASE64[line[at]] === 1)
-        at += 1;
-    return at;
-}
-/**
- * sha256, size and type of the image `line[from, to)` encodes, or null when it is not a PNG, JPEG, GIF
- * or WebP. Blocks of the run are decoded one at a time.
- */
-export function digestBase64Run(line, from, to) {
-    const length = to - from;
-    const inRun = line.subarray(from, to).indexOf(EQUALS);
-    const firstPad = inRun === -1 ? -1 : from + inRun;
-    const padCount = firstPad === -1 ? 0 : to - firstPad;
-    const plainPadding = padCount === 0
-        || (padCount <= 2 && length % 4 === 0 && onlyPaddingFrom(line, firstPad, to));
-    if (!plainPadding) {
-        const bytes = Buffer.from(line.toString("latin1", from, to), "base64");
-        const mediaType = sniffImageMediaType(bytes);
-        return mediaType ? { sha256: createHash("sha256").update(bytes).digest("hex"), mediaType, byteSize: bytes.byteLength } : null;
-    }
-    const hash = createHash("sha256");
-    let byteSize = 0;
-    let mediaType = null;
-    for (let at = from; at < to; at += BLOCK_CHARS) {
-        const block = Buffer.from(line.toString("latin1", at, Math.min(to, at + BLOCK_CHARS)), "base64");
-        if (at === from) {
-            mediaType = sniffImageMediaType(block);
-            if (!mediaType)
-                return null;
-        }
-        hash.update(block);
-        byteSize += block.byteLength;
-    }
-    return mediaType ? { sha256: hash.digest("hex"), mediaType, byteSize } : null;
-}
-/** True when everything from `firstPad` to `to` is `=` (padding at the very end of the run, nothing after it). */
-function onlyPaddingFrom(line, firstPad, to) {
-    for (let at = firstPad; at < to; at += 1)
-        if (line[at] !== EQUALS)
-            return false;
-    return true;
-}
-/** The sha256 of an image's decoded bytes, or null when `line[from, to)` does not decode to an image (used to re-check a payload before it is sent). */
-export function sha256OfBase64Run(line, from, to) {
-    return digestBase64Run(line, from, to)?.sha256 ?? null;
-}
-/**
- * The next index at or after `from` where `anchor` sits right after a `"`, or -1. `current` is the answer
- * of the last call: -2 not looked for yet, -1 none left, else still good while it is at or after `from`.
- */
-function nextQuotedStart(line, anchor, from, current) {
-    if (current === -1 || current >= from)
-        return current;
-    let at = line.indexOf(anchor, from);
-    while (at !== -1 && !(at > 0 && line[at - 1] === QUOTE))
-        at = line.indexOf(anchor, at + 1);
-    return at;
-}
-/**
- * Every embedded image in `line` (one physical line, no `\n` inside), in order, with byte offsets inside
- * the line. Equal to `findEmbeddedImages` on the decoded text in everything but the unit of the offsets.
- */
-export function scanImagesInLine(line) {
-    const found = [];
-    if (line.length < IMAGE_MIN_BASE64_CHARS - 1)
-        return found;
-    // For each whole-string start, the next quoted occurrence (-2: not looked for yet, -1: none left).
-    const nextStart = STARTS.map(() => -2);
-    let nextData = -2;
-    let position = 0;
-    while (position < line.length) {
-        let candidate = -1;
-        let kind = -1;
-        for (let index = 0; index < STARTS.length; index += 1) {
-            nextStart[index] = nextQuotedStart(line, STARTS[index], position, nextStart[index]);
-            const at = nextStart[index];
-            if (at !== -1 && (candidate === -1 || at < candidate)) {
-                candidate = at;
-                kind = index;
-            }
-        }
-        if (nextData !== -1) {
-            nextData = nextData >= position ? nextData : line.indexOf(DATA_URL, position);
-            if (nextData !== -1 && (candidate === -1 || nextData < candidate)) {
-                candidate = nextData;
-                kind = STARTS.length;
-            }
-        }
-        if (candidate === -1)
-            break;
-        if (kind < STARTS.length) {
-            const startLength = STARTS[kind].length;
-            const end = runEnd(line, candidate);
-            const closed = end < line.length && (line[end] === QUOTE || (line[end] === BACKSLASH && line[end + 1] === QUOTE));
-            if (!closed || end - candidate < startLength + (IMAGE_MIN_BASE64_CHARS - 5)) {
-                position = candidate + 1;
-                continue;
-            }
-            position = end;
-            const digest = digestBase64Run(line, candidate, end);
-            if (digest)
-                found.push({ replaceStart: candidate, replaceEnd: end, base64Start: candidate, base64End: end, ...digest });
-            continue;
-        }
-        // data:image/<type>;base64,<run of at least 500>
-        let cursor = candidate + DATA_URL.length;
-        const typeStart = cursor;
-        while (cursor < line.length && DATA_URL_LOWER[line[cursor]] === 1)
-            cursor += 1;
-        if (cursor === typeStart || line.compare(BASE64_TAG, 0, BASE64_TAG.length, cursor, cursor + BASE64_TAG.length) !== 0) {
-            position = candidate + 1;
-            continue;
-        }
-        const base64Start = cursor + BASE64_TAG.length;
-        const end = runEnd(line, base64Start);
-        if (end - base64Start < IMAGE_MIN_BASE64_CHARS) {
-            position = candidate + 1;
-            continue;
-        }
-        position = end;
-        const digest = digestBase64Run(line, base64Start, end);
-        if (digest)
-            found.push({ replaceStart: candidate, replaceEnd: end, base64Start, base64End: end, ...digest });
-    }
-    return found;
-}
+/** The byte scanner lives in telemetry-core (BLI-23349) so the memory hook shares it; this keeps the collector's import path. */
+export { bytesMayHoldImage, digestBase64Run, scanImagesInLine, sha256OfBase64Run, } from "@bli-cockpit/telemetry-core";

package/dist/raw-evidence-staging.js

@@ -2,6 +2,7 @@ import { DELIVERY_BACKOFF_HOLDING } from "@bli-cockpit/telemetry-core";
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { bookkeepingRead, bookkeepingWrite } from "./bookkeeping-session.js";
 import { describeError, isMissingFileFailure } from "./health-detail.js";
 /**
  * Durable local state for raw-evidence STAGING and DELIVERY ATTEMPTS.
@@ -67,7 +68,9 @@ export function emptyRawEvidenceStagingState() {
 export function rawEvidenceStagingStatePath(stateDir) {
     return path.join(stateDir, RAW_EVIDENCE_STAGING_FILENAME);
 }
-export async function readRawEvidenceStagingState(stateDir) {
+export const readRawEvidenceStagingState = (stateDir) => // BLI-23346: once per loop
+ bookkeepingRead(rawEvidenceStagingStatePath(stateDir), () => readStagingFromDisk(stateDir));
+async function readStagingFromDisk(stateDir) {
     try {
         const raw = JSON.parse(await fs.readFile(rawEvidenceStagingStatePath(stateDir), "utf8"));
         const state = parseStagingState(raw);
@@ -94,11 +97,12 @@ export async function readRawEvidenceStagingState(stateDir) {
  * lose every attempt count at once — which is exactly the thing that must not
  * be losable.
  */
-export async function writeRawEvidenceStagingState(stateDir, state) {
+export const writeRawEvidenceStagingState = (stateDir, state) => bookkeepingWrite(rawEvidenceStagingStatePath(stateDir), state, (held) => writeStagingToDisk(stateDir, held));
+async function writeStagingToDisk(stateDir, state) {
     const filePath = rawEvidenceStagingStatePath(stateDir);
     await fs.mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 });
     const pruned = pruneStagingState(state);
-    const serialized = `${JSON.stringify(pruned, null, 2)}\n`;
+    const serialized = `${JSON.stringify(pruned)}\n`; // compact (BLI-23346); readers accept either
     const tempPath = `${filePath}.tmp-${process.pid}-${crypto.randomUUID()}`;
     let handle = null;
     try {

package/dist/scheduled-self-update.js

@@ -7,14 +7,24 @@ export const SELF_UPDATE_THROTTLE_MARKER = ".last-self-update-check";
  * Put the running node binary's directory on PATH for scheduled npm commands.
  * Schedulers use a bare PATH; npm's shim ships beside node on both host families.
  */
-export function envWithNodeRuntimeOnPath(env, nodeExecutable = process.execPath) {
-    const nodeBinDir = path.dirname(nodeExecutable);
-    const currentPath = env["PATH"] ?? "";
-    if (currentPath.split(path.delimiter).includes(nodeBinDir))
+export function envWithNodeRuntimeOnPath(env, nodeExecutable = process.execPath, 
+/** Which platform's rules the PATH follows. Omitted: this host's own. */
+platform) {
+    const api = platform === undefined ? path : platform === "win32" ? path.win32 : path.posix;
+    // The running node's folder means nothing on a platform it is not from (an install
+    // simulated for another platform): leave that PATH exactly as the caller wrote it.
+    if (!api.isAbsolute(nodeExecutable))
+        return env;
+    const nodeBinDir = api.dirname(nodeExecutable);
+    // Windows spells the variable `Path`, and `{ ...process.env }` keeps that spelling: reading
+    // only `PATH` saw an empty PATH and left two spellings in the child's environment (BLI-23322).
+    const pathKey = api.sep === "\\" ? Object.keys(env).find((key) => key.toUpperCase() === "PATH") ?? "PATH" : "PATH";
+    const currentPath = env[pathKey] ?? "";
+    if (currentPath.split(api.delimiter).includes(nodeBinDir))
         return env;
     return {
         ...env,
-        PATH: [nodeBinDir, currentPath].filter(Boolean).join(path.delimiter),
+        [pathKey]: [nodeBinDir, currentPath].filter(Boolean).join(api.delimiter),
     };
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.272",
+  "version": "0.2.274",
   "private": false,
   "type": "module",
   "bin": {
@@ -27,9 +27,9 @@
     "test": "node dist/cli.js --help && node ../../scripts/assert-public-cli-routing.mjs && node ../../scripts/assert-public-cli-verb-help.mjs && node ../../scripts/assert-public-cli-surface-doors.mjs && node ../../scripts/assert-public-cli-runtime-files.mjs && node ../../scripts/assert-public-cli-exit-contract.mjs && node ../../scripts/assert-public-cli-no-fleet-posts.mjs && node ../../scripts/assert-public-cli-doctor-json.mjs && node ../../scripts/assert-public-package-pack.mjs --workspace=@bli-cockpit/cli"
   },
   "dependencies": {
-    "@bli-cockpit/memory-mcp": "0.1.82",
-    "@bli-cockpit/mcp": "0.1.166",
-    "@bli-cockpit/telemetry-core": "0.1.89",
+    "@bli-cockpit/memory-mcp": "0.1.83",
+    "@bli-cockpit/mcp": "0.1.167",
+    "@bli-cockpit/telemetry-core": "0.1.90",
     "unpdf": "1.8.1"
   },
   "repository": {