@bli-cockpit/cli 0.2.149 → 0.2.154

package/dist/commands/local-arg-values.js

@@ -105,6 +105,15 @@ export function optionalPositiveInteger(value, flag) {
     }
     return parsed;
 }
+export function optionalNonNegativeInteger(value, flag) {
+    if (value === undefined)
+        return undefined;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 0) {
+        throw new Error(`${flag} must be a whole number of 0 or more.`);
+    }
+    return parsed;
+}
 export function optionalConfidence(value, flag) {
     if (value === undefined)
         return undefined;

package/dist/commands/local-args-collector-setup.js

@@ -142,8 +142,10 @@ export function parseDoctorArgs(alias, args) {
     return {
         kind: "doctor",
         checkOnly: values.booleans.has("--check") || values.booleans.has("--no-repair"),
-        backfillBudgetSeconds: optionalPositiveInteger(values.flags.get("--backfill-budget"), "--backfill-budget") ?? 900,
-        lockWaitSeconds: optionalPositiveInteger(values.flags.get("--lock-wait"), "--lock-wait") ?? 600,
+        // Absent stays absent (BLI-11101): `doctor-budget.ts` owns the defaults,
+        // and `--json` without either flag runs under one bounded budget.
+        backfillBudgetSeconds: optionalPositiveInteger(values.flags.get("--backfill-budget"), "--backfill-budget"),
+        lockWaitSeconds: optionalPositiveInteger(values.flags.get("--lock-wait"), "--lock-wait"),
         alias,
         homeDir: optionalNonEmpty(values.flags.get("--home")),
         repoRoot: optionalNonEmpty(workRootFlagValue(values)),

package/dist/commands/local-args-collector-work.js

@@ -8,7 +8,7 @@
  * defaults, same refusal sentences.
  */
 import { IntentSourceSchema, WorkIntentSchema, WorkPhaseSchema, } from "@bli-cockpit/telemetry-core";
-import { assertNoPositionals, optionalConfidence, optionalNonEmpty, optionalPositiveInteger, optionalSchemaValue, optionalUrl, parseNamedArgs, workRootFlagValue, } from "./local-arg-values.js";
+import { assertNoPositionals, optionalConfidence, optionalNonEmpty, optionalNonNegativeInteger, optionalPositiveInteger, optionalSchemaValue, optionalUrl, parseNamedArgs, workRootFlagValue, } from "./local-arg-values.js";
 export function parseStartArgs(args) {
     const values = parseNamedArgs(args, {
         allowedFlags: [
@@ -134,6 +134,7 @@ export function parseBackfillArgs(args) {
             "--max-files",
             "--max-depth",
             "--max-repos",
+            "--lock-wait",
             "--yes",
             "--json",
         ],
@@ -146,6 +147,7 @@ export function parseBackfillArgs(args) {
             "--max-files",
             "--max-depth",
             "--max-repos",
+            "--lock-wait",
         ],
     });
     assertNoPositionals(values.positionals, "backfill");
@@ -169,7 +171,13 @@ export function parseBackfillArgs(args) {
         maxFiles: optionalPositiveInteger(values.flags.get("--max-files"), "--max-files"),
         maxDepth: optionalPositiveInteger(values.flags.get("--max-depth"), "--max-depth"),
         maxRepos: optionalPositiveInteger(values.flags.get("--max-repos"), "--max-repos"),
+        ...lockWaitMs(values.flags.get("--lock-wait")),
         yes: values.booleans.has("--yes"),
         json: values.booleans.has("--json"),
     };
+}
+/** `--lock-wait <seconds>` (0 = try once); absent means the 10-minute default (BLI-11091). */
+function lockWaitMs(value) {
+    const seconds = optionalNonNegativeInteger(value, "--lock-wait");
+    return seconds === undefined ? {} : { syncLockWaitMs: seconds * 1000 };
 }

package/dist/commands/local-help-commands.js

@@ -95,6 +95,7 @@ export function localSubcommandHelp(command) {
                 "--check or --no-repair diagnoses without repairs. --dry-run previews repairs.",
                 "--backfill-budget defaults to 900 seconds; catch-up repeats chunks until complete, with progress every 30 seconds.",
                 "--lock-wait defaults to 600 seconds; progress prints every 30 seconds.",
+                "--json without either flag answers within 45 seconds; a repair that does not fit reads doctor_budget_spent.",
                 "--json includes steps, repairs, and needs_person. Exit 0 means nothing needs you.",
                 "Maintainers: --update-tag next keeps self-update on the prerelease candidate.",
             ],
@@ -267,7 +268,7 @@ export function localSubcommandHelp(command) {
         [
             "backfill",
             [
-                "Usage: cockpit backfill (--since-days <n>|--all) [--source codex|claude] [--dry-run] [--max-files <n>] [--max-depth <n>] [--max-repos <n>] [--yes] [--workspace <path>] [--json]",
+                "Usage: cockpit backfill (--since-days <n>|--all) [--source codex|claude] [--dry-run] [--max-files <n>] [--max-depth <n>] [--max-repos <n>] [--lock-wait <seconds>] [--yes] [--workspace <path>] [--json]",
                 "",
                 "Backfills historical Codex and Claude Code session evidence using the saved collection roots from local config when --workspace is omitted.",
                 "Omit --source to scan both sources; there is no --source all literal.",
@@ -276,6 +277,8 @@ export function localSubcommandHelp(command) {
                 "Repo discovery scans 3 folder levels and up to 50 repos by default.",
                 "Raise --max-depth or --max-repos when a partial result reports a discovery cap.",
                 "--dry-run validates the paired collector and dashboard reachability, prints the same summary tables, and writes nothing.",
+                "Sessions outside every saved root upload too, labelled outside; only an explicit opt-out withholds a session.",
+                "When the scheduled sync holds the collection lock, backfill waits up to --lock-wait seconds (default 600) and exits 1 with sync_lock_held if it never frees.",
             ],
         ],
         [

package/dist/commands/local-help.js

@@ -109,7 +109,7 @@ export function localCommandHelp(command) {
         "  cockpit correct --claim <claimId> --text \"<what is wrong>\" [--for <person>] [--version <pageId>] [--supersedes <id>] [--dashboard-url <url>] [--json]",
         "  cockpit notes [list|show <id>|shelf|shelves|folders|mkdir <path>|rmdir <path>|rename <path>|upload <paths...> [--wait]|paste|share <id>|unshare <id>|move <id>|place <id>] [--folder <path>] [--series <shelf>] [--kind <kind>] [--since <YYYY-MM-DD>] [--until <YYYY-MM-DD>] [--limit <n>] [--file <path>] [--name <n>] [--exclude \"<sentence>\"] [--to \"<shelf>\"|--clear-shelf] [--apply] [--yes] [--dashboard-url <url>] [--json]",
         "  cockpit notes [accounts [--show-webhook <account-id>]|connect --provider fellow --workspace <sub> --key-stdin [--name <n>]|webhook <account-id> --secret-stdin|detach <account-id>|sync <account-id>] [--json]   (the key and the signing secret are read from stdin, never a flag)",
-        "  cockpit backfill (--since-days <n>|--all) [--source codex|claude] [--dry-run] [--max-files <n>] [--max-depth <n>] [--max-repos <n>] [--yes] [--workspace <path>] [--json]",
+        "  cockpit backfill (--since-days <n>|--all) [--source codex|claude] [--dry-run] [--max-files <n>] [--max-depth <n>] [--max-repos <n>] [--lock-wait <seconds>] [--yes] [--workspace <path>] [--json]",
         "  cockpit status [--workspace <path>] [--max-depth <n>] [--max-repos <n>] [--json]",
         "  cockpit sessions [--source codex|claude] [--since-days <n>|--all] [--workspace <path>] [--max-depth <n>] [--max-repos <n>] [--json]",
         "  cockpit serve [--port <port>] [--workspace <path>]",

package/dist/commands/local.js

@@ -65,6 +65,20 @@ export async function runLocalCockpitCli(argv, io = defaultIo()) {
         argv = argv.filter((token) => token !== "--quiet");
         process.env.COCKPIT_QUIET = "1";
     }
+    // BLI-10746: `--fresh`/`--allow-stale` are global toggles for the
+    // stale-while-revalidate read cache, same reason and same shape as
+    // `--quiet` above — stripped here so none of the seven cached read
+    // commands' own `allowedFlags` needs to learn them, and mirrored onto
+    // env vars `read-cache.ts` reads. One `cockpit` process makes at most one
+    // cacheable request, so a process-wide toggle is exactly a per-request one.
+    if (argv.includes("--fresh")) {
+        argv = argv.filter((token) => token !== "--fresh");
+        process.env.COCKPIT_READ_FRESH = "1";
+    }
+    if (argv.includes("--allow-stale")) {
+        argv = argv.filter((token) => token !== "--allow-stale");
+        process.env.COCKPIT_READ_ALLOW_STALE = "1";
+    }
     if (isLocalHelpRequest(argv)) {
         writeLine(io.stdout, localCommandHelp(argv[0]));
         return 0;

package/dist/commands/mail.js

@@ -24,6 +24,7 @@ import { writeFile } from "node:fs/promises";
 import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor, } from "./agent-door.js";
 import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
 import { readNoteFile } from "./notes-file.js";
+import { cacheAgeLabel, readThroughCache } from "./read-cache.js";
 import { towerRequest } from "../tower-client.js";
 const TAG = "[mail cli]";
 const READ_DEADLINE_MS = 30_000;
@@ -151,17 +152,32 @@ async function inbox(command, door) {
     if (command.label)
         query.set("label", command.label);
     const suffix = query.toString();
-    const answer = await askAgentDoor(door, {
-        path: `/api/mail/inbox${suffix ? `?${suffix}` : ""}`,
-        method: "GET",
+    const inboxPath = `/api/mail/inbox${suffix ? `?${suffix}` : ""}`;
+    const answer = await readThroughCache({
+        io: door.io,
+        homeDir: door.homeDir,
+        deviceToken: door.deviceToken,
+        surface: "mail",
         label: "mail inbox",
-        timeoutMs: READ_DEADLINE_MS,
+        path: inboxPath,
+        json: door.json,
+        ask: () => askAgentDoor(door, {
+            path: inboxPath,
+            method: "GET",
+            label: "mail inbox",
+            timeoutMs: READ_DEADLINE_MS,
+            // BLI-10746: route through the resident memory daemon's warm connection.
+            warmRoute: true,
+        }),
     });
     if (!answer.ok)
         return failAgentDoor(door, TAG, answer.reason, answer.detail);
     const body = answer.body;
     if (door.json)
         return emitAgentDoor(door, { ok: true, ...body });
+    if (answer.fromCache) {
+        writeLine(door.io.stderr, `(${cacheAgeLabel(answer.ageMs ?? 0)}, refreshing in the background)`);
+    }
     const messages = body.messages ?? [];
     if (messages.length === 0) {
         writeLine(door.io.stdout, (body.accounts ?? []).length === 0 ? "No mailboxes attached yet." : "No mail matches that.");

package/dist/commands/memory-store.js

@@ -46,6 +46,7 @@ import { resolveContainerTag } from "@bli-cockpit/memory-mcp/dist/container-tag.
 import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor, } from "./agent-door.js";
 import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
 import { runMemoryConsolidation } from "./memory-consolidation.js";
+import { cacheAgeLabel, readThroughCache } from "./read-cache.js";
 import { runMemoryRequeue } from "./memory-requeue.js";
 import { readNoteFile } from "./notes-file.js";
 export { runMemoryVerbList } from "./memory-verb-list.js";
@@ -142,17 +143,30 @@ function containerTagsFor(command) {
 }
 async function searchMemory(command, door) {
     const containerTags = containerTagsFor(command);
-    const answer = await askAgentDoor(door, {
-        path: "/api/memory/search",
-        method: "POST",
+    const requestBody = {
+        query: command.query,
+        containerTag: containerTags,
+        ...(command.limit === undefined ? {} : { limit: command.limit }),
+        includeProfile: command.includeRecent !== false,
+    };
+    const answer = await readThroughCache({
+        io: door.io,
+        homeDir: door.homeDir,
+        deviceToken: door.deviceToken,
+        surface: "memory",
         label: "memory search",
-        timeoutMs: SEARCH_DEADLINE_MS,
-        body: {
-            query: command.query,
-            containerTag: containerTags,
-            ...(command.limit === undefined ? {} : { limit: command.limit }),
-            includeProfile: command.includeRecent !== false,
-        },
+        path: "/api/memory/search",
+        requestBody,
+        json: door.json,
+        ask: () => askAgentDoor(door, {
+            path: "/api/memory/search",
+            method: "POST",
+            label: "memory search",
+            timeoutMs: SEARCH_DEADLINE_MS,
+            // BLI-10746: the one POST this repo treats as a warm-routable read.
+            warmRoute: true,
+            body: requestBody,
+        }),
     });
     if (!answer.ok)
         return failAgentDoor(door, TAG, answer.reason, answer.detail);
@@ -170,6 +184,9 @@ async function searchMemory(command, door) {
     })}`);
     if (door.json)
         return emitAgentDoor(door, answer.body);
+    if (answer.fromCache) {
+        writeLine(door.io.stderr, `(${cacheAgeLabel(answer.ageMs ?? 0)}, refreshing in the background)`);
+    }
     if (results.length === 0 && body.degraded) {
         // BLI-10448: an empty answer from a search that lost a channel is NOT the
         // record being silent. `semantic_timed_out` is the store answering on

package/dist/commands/msg.js

@@ -17,6 +17,7 @@
  */
 import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor, } from "./agent-door.js";
 import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
+import { cacheAgeLabel, readThroughCache } from "./read-cache.js";
 const TAG = "[msg cli]";
 const READ_DEADLINE_MS = 30_000;
 const WRITE_DEADLINE_MS = 30_000;
@@ -39,15 +40,31 @@ export async function runMsg(command, io) {
     }
 }
 async function fetchChannels(door) {
-    const answer = await askAgentDoor(door, {
-        path: "/api/msg/channels",
-        method: "GET",
+    const answer = await readThroughCache({
+        io: door.io,
+        homeDir: door.homeDir,
+        deviceToken: door.deviceToken,
+        surface: "msg",
         label: "msg channels",
-        timeoutMs: READ_DEADLINE_MS,
+        path: "/api/msg/channels",
+        json: door.json,
+        ask: () => askAgentDoor(door, {
+            path: "/api/msg/channels",
+            method: "GET",
+            label: "msg channels",
+            timeoutMs: READ_DEADLINE_MS,
+            // BLI-10746: route through the resident memory daemon's warm connection.
+            warmRoute: true,
+        }),
     });
     if (!answer.ok)
         return { ok: false, reason: answer.reason, detail: answer.detail };
-    return { ok: true, channels: answer.body.channels ?? [] };
+    return {
+        ok: true,
+        channels: answer.body.channels ?? [],
+        fromCache: answer.fromCache,
+        ageMs: answer.ageMs,
+    };
 }
 async function listChannels(door) {
     const fetched = await fetchChannels(door);
@@ -55,6 +72,9 @@ async function listChannels(door) {
         return failAgentDoor(door, TAG, fetched.reason, fetched.detail);
     if (door.json)
         return emitAgentDoor(door, { ok: true, channels: fetched.channels });
+    if (fetched.fromCache) {
+        writeLine(door.io.stderr, `(${cacheAgeLabel(fetched.ageMs ?? 0)}, refreshing in the background)`);
+    }
     if (fetched.channels.length === 0) {
         writeLine(door.io.stdout, "No channels.");
         return 0;

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.149");
+    writeLine(io?.stdout ?? process.stdout, "0.2.154");
     return 0;
   }
 

package/dist/commands/read-cache.js

@@ -0,0 +1,115 @@
+/**
+ * STALE-WHILE-REVALIDATE FOR THE SEVEN READ COMMANDS BLI-10746 MEASURED
+ * (`work list`, `docs list`, `cal today`, `mail inbox`, `msg channels`,
+ * `settings personal`, `memory search`).
+ *
+ * Text mode: a cache hit prints INSTANTLY (its age travels with it), then a
+ * background refresh is spawned so the next call is live — never blocking
+ * this process on a network round trip it already has a recent answer for.
+ * `--json` (an agent, not a person) trusts cache only under
+ * `JSON_FRESH_BOUND_MS`, unless `--allow-stale` says otherwise; older than
+ * that runs the live request inline, same as a miss. `--fresh` skips the
+ * read entirely — both flags are process-wide (BLI-10450's `--quiet`
+ * pattern), stripped from argv and mirrored onto `COCKPIT_READ_FRESH` /
+ * `COCKPIT_READ_ALLOW_STALE` by `local.ts`, so none of these seven parsers'
+ * own `allowedFlags` needed to learn a new flag.
+ *
+ * **The background refresh is a whole second `cockpit` process, detached.**
+ * Not a lighter internal-only command: it re-runs THIS SAME argv with
+ * `--fresh` appended, `stdio: "ignore"`, unref'd. That is deliberately the
+ * simplest correct thing — it reuses every bit of behaviour the live path
+ * already has (auth, rendering, the warm route) with zero drift risk, at
+ * the cost of a process this ticket's "abundant compute" call already
+ * accepts (`docs/architecture/repo-map.md`'s standing orders). The PARENT
+ * never waits on it, so the terminal returns control the instant the cached
+ * answer is printed — a detached child is the only shape that lets a write
+ * to disk keep happening after THIS process has already exited (an
+ * unref'd but still-open socket dies with the process; a separate process
+ * does not).
+ *
+ * **Any write invalidates.** `tower-client.ts`'s `towerRequest` calls
+ * `invalidateReadCacheSurface` (from `@bli-cockpit/telemetry-core`'s
+ * `./node-read-cache`, the same module this reads and writes through) on
+ * every successful non-GET response whose path names one of the seven
+ * surfaces — coarse (the whole surface, not just the one changed row) and
+ * correct: a stale row is never possible, only one avoidable extra request.
+ */
+import { spawn } from "node:child_process";
+import { readCacheEntryPath, readCacheKey, readReadCacheEntry, writeReadCacheEntryAtomic, } from "@bli-cockpit/telemetry-core/node-read-cache";
+import { writeLine } from "./cli-io.js";
+import { getCollectorRuntimePaths } from "../local-state-paths.js";
+/** An agent's `--json` read trusts cache only this fresh, unless `--allow-stale`. */
+export const JSON_FRESH_BOUND_MS = 30_000;
+/** Never spawns a second refresh for an answer this recently written — avoids a pile-up under rapid repeated calls. */
+export const MIN_REFRESH_INTERVAL_MS = 3_000;
+/** `"cached 3s ago"` / `"cached 4m ago"` — the one phrasing every cached read command prints. */
+export function cacheAgeLabel(ageMs) {
+    const seconds = Math.max(0, Math.round(ageMs / 1000));
+    if (seconds < 60)
+        return `cached ${seconds}s ago`;
+    const minutes = Math.round(seconds / 60);
+    return `cached ${minutes}m ago`;
+}
+export async function readThroughCache(options) {
+    const log = (line) => writeLine(options.io.stderr, line);
+    const stateDir = getCollectorRuntimePaths(options.homeDir).state_dir;
+    const key = readCacheKey(options.label, options.path, options.requestBody);
+    const entryPath = readCacheEntryPath(stateDir, options.deviceToken, options.surface, key);
+    const fresh = options.io.env["COCKPIT_READ_FRESH"] === "1";
+    const allowStale = options.io.env["COCKPIT_READ_ALLOW_STALE"] === "1";
+    if (fresh) {
+        log(`[read-cache] bypassed ${JSON.stringify({ surface: options.surface, label: options.label, reason: "fresh_flag" })}`);
+    }
+    else {
+        const cached = readReadCacheEntry(entryPath);
+        if (cached) {
+            const ageMs = Date.now() - cached.storedAt;
+            const trusted = !options.json || ageMs < JSON_FRESH_BOUND_MS || allowStale;
+            if (trusted) {
+                log(`[read-cache] served ${JSON.stringify({ surface: options.surface, label: options.label, age_ms: ageMs, json: options.json })}`);
+                if (ageMs > MIN_REFRESH_INTERVAL_MS) {
+                    spawnBackgroundRefresh(options.io, log, options.spawnImpl);
+                }
+                else {
+                    log(`[read-cache] refresh skipped ${JSON.stringify({ reason: "too_recent", age_ms: ageMs })}`);
+                }
+                return { ok: true, httpStatus: cached.status, body: cached.body, fromCache: true, ageMs };
+            }
+            log(`[read-cache] too stale for --json ${JSON.stringify({ surface: options.surface, label: options.label, age_ms: ageMs })}`);
+        }
+        else {
+            log(`[read-cache] miss ${JSON.stringify({ surface: options.surface, label: options.label })}`);
+        }
+    }
+    const live = await options.ask();
+    if (live.ok) {
+        writeReadCacheEntryAtomic(entryPath, { status: live.httpStatus, body: live.body });
+        log(`[read-cache] refreshed ${JSON.stringify({ surface: options.surface, label: options.label })}`);
+    }
+    return { ...live, fromCache: false, ageMs: null };
+}
+/**
+ * Re-runs THIS process's own argv with `--fresh` appended, detached and
+ * discarded. Never awaited, never throws — a refresh that could not be
+ * spawned just means the next call finds the same cache age it would have
+ * found anyway; it is never this call's failure to report.
+ */
+export function spawnBackgroundRefresh(io, log, spawnImpl = spawn) {
+    try {
+        const args = process.argv
+            .slice(2)
+            .filter((token) => token !== "--fresh" && token !== "--allow-stale");
+        args.push("--fresh");
+        const child = spawnImpl(process.execPath, [process.argv[1] ?? "", ...args], {
+            detached: true,
+            stdio: "ignore",
+            windowsHide: true,
+            env: io.env,
+        });
+        child.unref();
+        log(`[read-cache] background refresh spawned ${JSON.stringify({ argv_len: args.length })}`);
+    }
+    catch (error) {
+        log(`[read-cache] background refresh failed to spawn ${JSON.stringify({ reason: error instanceof Error ? error.name : "unknown" })}`);
+    }
+}

package/dist/commands/settings.js

@@ -20,6 +20,7 @@
  * being written to stdout, stderr, or an argument vector.
  */
 import { isInteractiveStdin, readLine, writeLine, yesByDefault } from "./cli-io.js";
+import { cacheAgeLabel, readThroughCache } from "./read-cache.js";
 import { asList, asRecord, callTower, isForbidden, openTower, parseModelKey, readAllStdin, writeCommandFailure, } from "./tower-command.js";
 import { showOverview } from "./settings-overview.js";
 import { renderCliFloor, renderEnvBlobs, renderModelRouting, renderPersonal, renderSwitches, } from "./settings-render.js";
@@ -54,12 +55,26 @@ export async function runSettings(command, io) {
 }
 // ── personal ──────────────────────────────────────────────────────────
 async function showPersonal(command, tower, io) {
-    const result = await callTower(tower, {
-        path: "/api/settings/personal",
+    const result = await readThroughCache({
+        io,
+        homeDir: tower.homeDir,
+        deviceToken: tower.deviceToken,
+        surface: "settings",
         label: "settings personal",
+        path: "/api/settings/personal",
+        json: command.json,
+        ask: () => callTower(tower, {
+            path: "/api/settings/personal",
+            label: "settings personal",
+            // BLI-10746: route through the resident memory daemon's warm connection.
+            warmRoute: true,
+        }),
     });
     if (!result.ok)
         return writeCommandFailure(io, command.json, result);
+    if (result.fromCache && !command.json) {
+        writeLine(io.stderr, `(${cacheAgeLabel(result.ageMs ?? 0)}, refreshing in the background)`);
+    }
     return writeBody(io, command.json, result.body, () => renderPersonal(asRecord(result.body)));
 }
 async function setPersonal(command, tower, io) {

package/dist/commands/tower-command.js

@@ -33,6 +33,8 @@ export async function openTower(commandName, command, io) {
         deviceToken: session.device_token,
         fetch: io.fetch,
         log: (line) => writeLine(io.stderr, line),
+        io,
+        homeDir: command.homeDir,
     };
 }
 export async function callTower(context, options) {
@@ -45,6 +47,8 @@ export async function callTower(context, options) {
         ...(options.body === undefined ? {} : { body: options.body }),
         timeoutMs: options.timeoutMs ?? REQUEST_DEADLINE_MS,
         label: options.label,
+        ...(options.warmRoute === undefined ? {} : { warmRoute: options.warmRoute }),
+        ...(context.homeDir === undefined ? {} : { homeDir: context.homeDir }),
         log: context.log,
     });
     if (result.ok)

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

@@ -165,10 +165,14 @@ function parseObjectEntry(value) {
     const committedAt = optionalString(record["committed_at"]);
     if (!objectKey || !committedAt)
         return null;
+    const sourceKey = optionalString(record["source_key"]);
     return {
         object_key: objectKey,
         byte_size: optionalNumber(record["byte_size"]),
         committed_at: committedAt,
+        ...(sourceKey
+            ? { source_key: sourceKey, checkpoints: parseCheckpoints(record["checkpoints"]) }
+            : {}),
     };
 }
 function parseSessionEntry(value) {
@@ -193,6 +197,16 @@ function parseSessionEntry(value) {
         last_seen_at: lastSeenAt,
     };
 }
+function parseCheckpoints(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const out = {};
+    for (const [offset, hash] of Object.entries(value)) {
+        if (/^\d+$/.test(offset) && typeof hash === "string")
+            out[offset] = hash;
+    }
+    return out;
+}
 function rawEvidenceCursorPath(paths, filename = PRIMARY_CURSOR_FILENAME) {
     return path.join(paths.cursors_dir, filename);
 }

package/dist/tower-client.js

@@ -23,9 +23,11 @@
  * `responseErrorMessage`) is reused from `upload-http.ts` rather than copied —
  * the upload path and the conversation path answer to the same rules.
  */
+import { invalidateReadCacheSurface, readCacheSurfaceForPath, } from "@bli-cockpit/telemetry-core/node-read-cache";
 import { errorMessage } from "./commands/cli-io.js";
 import { getCollectorRuntimePaths, readLocalCollectorSessionFile, } from "./local-state.js";
 import { normalizeDashboardUrl, readResponseJson, responseErrorMessage, } from "./upload-http.js";
+import { isWarmRoutableRead, tryWarmTowerFetch } from "./warm-tower-fetch.js";
 const defaultLog = (line) => {
     console.error(line);
 };
@@ -77,6 +79,7 @@ export async function towerRequest(options) {
     const startedAt = Date.now();
     const url = `${normalizeDashboardUrl(options.dashboardUrl)}${options.path}`;
     const isForm = typeof FormData !== "undefined" && options.body instanceof FormData;
+    const method = options.method ?? "POST";
     const headers = {
         ...(options.headers ?? {}),
         authorization: `Bearer ${options.deviceToken}`,
@@ -85,16 +88,26 @@ export async function towerRequest(options) {
     // content-type by hand would strip it and the server would parse nothing.
     if (options.body !== undefined && !isForm)
         headers["content-type"] = "application/json";
+    const body = options.body === undefined || isForm ? undefined : JSON.stringify(options.body);
     const init = {
-        method: options.method ?? "POST",
+        method,
         headers,
         ...(options.body === undefined
             ? {}
-            : { body: (isForm ? options.body : JSON.stringify(options.body)) }),
+            : { body: (isForm ? options.body : body) }),
         ...(timeoutSignal(options.timeoutMs) ?? {}),
     };
     try {
-        const response = await options.fetch(url, init);
+        // BLI-10746: a read (GET, or the one POST read this repo has —
+        // `memory search`) skips the cold TCP+TLS connect by asking the resident
+        // memory daemon to replay it on its own warm dispatcher. `isForm` never
+        // holds for a read this repo makes, but the check is here so a future
+        // read that DOES carry a form body never gets silently mis-proxied.
+        const warmEligible = options.warmRoute === true && !isForm && isWarmRoutableRead(method, options.label);
+        const warmResponse = warmEligible
+            ? await tryWarmTowerFetch(url, { method, headers, body }, log, { homeDir: options.homeDir })
+            : null;
+        const response = warmResponse ?? (await options.fetch(url, init));
         const respondedMs = Date.now() - startedAt;
         // The success branch always decided something (BLI-10450 kept the
         // "log the success branch too" rule intact) — it is just that under
@@ -111,6 +124,21 @@ export async function towerRequest(options) {
                 elapsed_ms: respondedMs,
             })}`);
         }
+        // BLI-10746: "any write through the CLI or MCP invalidates the affected
+        // cache". A successful (2xx) write to a covered surface throws away
+        // every cached read for that surface — coarse, but a stale row is never
+        // possible this way, only one avoidable extra request.
+        if (method !== "GET" && response.ok) {
+            const surface = readCacheSurfaceForPath(options.path);
+            if (surface) {
+                const stateDir = getCollectorRuntimePaths(options.homeDir).state_dir;
+                const invalidated = invalidateReadCacheSurface(stateDir, options.deviceToken, surface);
+                log(`[tower client] read cache invalidated ${JSON.stringify({
+                    surface,
+                    ...(invalidated.ok ? { removed: invalidated.removed } : { reason: invalidated.reason }),
+                })}`);
+            }
+        }
         return { ok: true, response, startedAt, respondedMs };
     }
     catch (error) {

package/dist/upload-envelope-build.js

@@ -14,6 +14,7 @@
  *   `upload-session-reports.ts`, which builds its own provenance without a
  *   full envelope.
  */
+import { priorSnapshotsFromCursor, } from "./adapters/raw-evidence-snapshot-supersede.js";
 import { TelemetryIngestEnvelopeSchema, } from "@bli-cockpit/telemetry-core";
 import path from "node:path";
 import { getCollectorRuntimePaths, LOCAL_COLLECTOR_VERSION, readLocalCollectorConfig, readLocalCollectorSessionFile, readLocalSessionReference, readLocalWorkContextForRepo, } from "./local-state.js";
@@ -120,6 +121,10 @@ export async function buildLocalAmbientEnvelope(options = {}) {
             operatorId: session.operator_id,
             workContextId: uploadContext.work_context_id,
         }),
+        rawEvidencePriorSnapshots: priorSnapshotsFromCursor(transcriptCursorObjects(options.cursorObjects), (objectKey) => rawEvidenceObjectKeyBelongsToWorkContext(objectKey, {
+            operatorId: session.operator_id,
+            workContextId: uploadContext.work_context_id,
+        })),
         rawEvidenceByteBudget: options.rawEvidenceByteBudget,
         rawEvidenceObjectBudget: options.rawEvidenceObjectBudget,
         rawEvidenceBudget: options.rawEvidenceBudget,
@@ -188,6 +193,10 @@ function reusableContentHashes(options, context) {
         .filter(([, entry]) => rawEvidenceObjectKeyBelongsToWorkContext(entry.object_key, context))
         .map(([hash]) => hash));
 }
+/** Cursor entries that remember a transcript source (BLI-11088); the rest are ignored. */
+function transcriptCursorObjects(objects) {
+    return Object.fromEntries(Object.entries(objects ?? {}).filter((pair) => "source_key" in pair[1] && Boolean(pair[1].source_key)));
+}
 export function makeUploadWorkContext(options) {
     const provenance = makeCollectorProvenance({
         context: options.activeContext,