@bli-cockpit/cli 0.2.149 → 0.2.150

package/dist/commands/agent-door.js

@@ -23,6 +23,7 @@ export async function openAgentDoor(commandName, command, io) {
         deviceToken: session.device_token,
         io,
         json: command.json,
+        homeDir: command.homeDir,
     };
 }
 export async function askAgentDoor(door, options) {
@@ -35,6 +36,8 @@ export async function askAgentDoor(door, options) {
         label: options.label,
         timeoutMs: options.timeoutMs,
         ...(options.body === undefined ? {} : { body: options.body }),
+        ...(options.warmRoute === undefined ? {} : { warmRoute: options.warmRoute }),
+        ...(door.homeDir === undefined ? {} : { homeDir: door.homeDir }),
         log: (line) => writeLine(door.io.stderr, line),
     });
     if (!result.ok) {

package/dist/commands/cal-calendars-write.js

@@ -0,0 +1,107 @@
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
+const TAG = "[cal cli]";
+const WRITE_DEADLINE_MS = 60_000;
+/** A first read of a crowded calendar can take a while. */
+const SYNC_DEADLINE_MS = 120_000;
+const URL_MAX_CHARS = 2_000;
+export async function runCalAddIcal(command, door) {
+    // The address comes from stdin and nowhere else. An interactive terminal
+    // with nothing piped in is told how, rather than left waiting on a prompt
+    // that would echo a permanent credential into the scrollback.
+    if (isInteractiveStdin(door.io)) {
+        return failAgentDoor(door, TAG, "address_required_on_stdin", 'The calendar\'s secret address is read from stdin, never from a flag. Try: printf "%s" "https://calendar.google.com/calendar/ical/…/basic.ics" | cockpit cal add-ical --name "Personal"');
+    }
+    let icalUrl;
+    try {
+        icalUrl = (await readPipedText(door.io.stdin, {
+            maxChars: URL_MAX_CHARS,
+            overflowMessage: "That is longer than any calendar address; nothing was attached.",
+        })).trim();
+    }
+    catch (error) {
+        return failAgentDoor(door, TAG, "address_unreadable", error instanceof Error ? error.message : String(error));
+    }
+    if (icalUrl === "") {
+        return failAgentDoor(door, TAG, "address_required_on_stdin", "Nothing arrived on stdin, so nothing was attached.");
+    }
+    const answer = await askAgentDoor(door, {
+        path: "/api/cal/calendars",
+        method: "POST",
+        label: "cal add-ical",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: {
+            ical_url: icalUrl,
+            name: command.name ?? null,
+            ...(command.orgVisible ? { org_visible: true } : {}),
+        },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const calendar = answer.body.calendar;
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, calendar });
+    writeLine(door.io.stdout, `Attached (${calendar?.id ?? "no id returned"}).`);
+    writeLine(door.io.stdout, `Nothing is read until a sync runs: \`cockpit cal sync ${calendar?.id ?? "<id>"}\`, or wait for the cron.`);
+    return 0;
+}
+export async function runCalShare(command, door) {
+    const orgVisible = command.orgVisible && !command.makePrivate;
+    const answer = await askAgentDoor(door, {
+        path: `/api/cal/calendars?calendar_id=${encodeURIComponent(command.subjectId ?? "")}`,
+        method: "PATCH",
+        label: "cal share",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: { org_visible: orgVisible },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const calendar = answer.body.calendar;
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, calendar });
+    writeLine(door.io.stdout, orgVisible
+        ? `"${calendar?.name ?? command.subjectId}" is now readable by everyone at BLI. Nobody but you can change it.`
+        : `"${calendar?.name ?? command.subjectId}" is private again — only you can read it.`);
+    return 0;
+}
+export async function runCalDetach(command, door) {
+    const answer = await askAgentDoor(door, {
+        path: `/api/cal/calendars?calendar_id=${encodeURIComponent(command.subjectId ?? "")}`,
+        method: "DELETE",
+        label: "cal detach",
+        timeoutMs: WRITE_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, detached: command.subjectId });
+    writeLine(door.io.stdout, `Detached ${command.subjectId}. Its stored events went with it; the calendar itself is untouched at Google.`);
+    return 0;
+}
+export async function runCalSync(command, door) {
+    const answer = await askAgentDoor(door, {
+        path: `/api/cal/calendars/${encodeURIComponent(command.subjectId ?? "")}/sync${command.full ? "?full=1" : ""}`,
+        method: "POST",
+        label: "cal sync",
+        timeoutMs: SYNC_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const run = answer.body.run;
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, run });
+    if (!run) {
+        writeLine(door.io.stdout, "Tower answered without a run. Nothing to report.");
+        return 0;
+    }
+    if (run.reason === "ok") {
+        writeLine(door.io.stdout, run.detail === "feed_unchanged"
+            ? "Nothing has changed on that calendar since the last read."
+            : `Synced: ${run.eventsAdded} new, ${run.eventsUpdated} updated, ${run.eventsDeleted} gone.`);
+        return 0;
+    }
+    // A failure names itself; the exit code says it failed.
+    writeLine(door.io.stderr, `${TAG} sync ${JSON.stringify({ reason: run.reason, detail: run.detail })}`);
+    writeLine(door.io.stdout, `That calendar did not sync: ${run.reason}${run.detail ? ` (${run.detail})` : ""}.`);
+    return 1;
+}

package/dist/commands/cal.js

@@ -21,15 +21,14 @@
  *   computed in UTC and "today" would end at 5pm in Vancouver.
  */
 import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor, } from "./agent-door.js";
+import { runCalAddIcal, runCalDetach, runCalShare, runCalSync } from "./cal-calendars-write.js";
 import { runCalDelete } from "./cal-delete.js";
 import { runCalSyncStatus } from "./cal-sync-status.js";
-import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
+import { writeLine } from "./cli-io.js";
+import { cacheAgeLabel, readThroughCache } from "./read-cache.js";
 const TAG = "[cal cli]";
 const READ_DEADLINE_MS = 30_000;
 const WRITE_DEADLINE_MS = 60_000;
-/** A first read of a crowded calendar can take a while. */
-const SYNC_DEADLINE_MS = 120_000;
-const URL_MAX_CHARS = 2_000;
 export async function runCal(command, io) {
     const door = await openAgentDoor("cal", command, io);
     switch (command.action) {
@@ -42,15 +41,15 @@ export async function runCal(command, io) {
         case "calendars":
             return listCalendars(door);
         case "add-ical":
-            return addIcal(command, door);
+            return runCalAddIcal(command, door);
         case "create":
             return create(command, door);
         case "share":
-            return share(command, door);
+            return runCalShare(command, door);
         case "detach":
-            return detach(command, door);
+            return runCalDetach(command, door);
         case "sync":
-            return sync(command, door);
+            return runCalSync(command, door);
         case "sync-status":
             return runCalSyncStatus(command, door);
         case "delete":
@@ -92,17 +91,37 @@ async function window(command, door) {
     // `--from`/`--to` beat a named window, on any of the three verbs: somebody
     // who named two dates meant them.
     const path = command.from && command.to ? "events" : command.action;
-    const answer = await askAgentDoor(door, {
-        path: `/api/cal/${path}?${windowQuery(command).toString()}`,
+    const apiPath = `/api/cal/${path}?${windowQuery(command).toString()}`;
+    // BLI-10746: `cal today` is the one read this ticket measured; the warm
+    // route and the cache both apply to it (and only it).
+    const cached = command.action === "today";
+    const ask = () => askAgentDoor(door, {
+        path: apiPath,
         method: "GET",
         label: `cal ${command.action}`,
         timeoutMs: READ_DEADLINE_MS,
+        warmRoute: cached,
     });
+    const answer = cached
+        ? await readThroughCache({
+            io: door.io,
+            homeDir: door.homeDir,
+            deviceToken: door.deviceToken,
+            surface: "cal",
+            label: "cal today",
+            path: apiPath,
+            json: door.json,
+            ask,
+        })
+        : { ...(await ask()), fromCache: false, ageMs: null };
     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 zone = body.window?.time_zone ?? localTimeZone();
     const events = body.events ?? [];
     if (events.length === 0) {
@@ -246,46 +265,6 @@ async function listCalendars(door) {
     writeLine(door.io.stdout, `${calendars.length} calendar(s). ids: ${calendars.map((calendar) => calendar.id).join(", ")}`);
     return 0;
 }
-async function addIcal(command, door) {
-    // The address comes from stdin and nowhere else. An interactive terminal
-    // with nothing piped in is told how, rather than left waiting on a prompt
-    // that would echo a permanent credential into the scrollback.
-    if (isInteractiveStdin(door.io)) {
-        return failAgentDoor(door, TAG, "address_required_on_stdin", 'The calendar\'s secret address is read from stdin, never from a flag. Try: printf "%s" "https://calendar.google.com/calendar/ical/…/basic.ics" | cockpit cal add-ical --name "Personal"');
-    }
-    let icalUrl;
-    try {
-        icalUrl = (await readPipedText(door.io.stdin, {
-            maxChars: URL_MAX_CHARS,
-            overflowMessage: "That is longer than any calendar address; nothing was attached.",
-        })).trim();
-    }
-    catch (error) {
-        return failAgentDoor(door, TAG, "address_unreadable", error instanceof Error ? error.message : String(error));
-    }
-    if (icalUrl === "") {
-        return failAgentDoor(door, TAG, "address_required_on_stdin", "Nothing arrived on stdin, so nothing was attached.");
-    }
-    const answer = await askAgentDoor(door, {
-        path: "/api/cal/calendars",
-        method: "POST",
-        label: "cal add-ical",
-        timeoutMs: WRITE_DEADLINE_MS,
-        body: {
-            ical_url: icalUrl,
-            name: command.name ?? null,
-            ...(command.orgVisible ? { org_visible: true } : {}),
-        },
-    });
-    if (!answer.ok)
-        return failAgentDoor(door, TAG, answer.reason, answer.detail);
-    const calendar = answer.body.calendar;
-    if (door.json)
-        return emitAgentDoor(door, { ok: true, calendar });
-    writeLine(door.io.stdout, `Attached (${calendar?.id ?? "no id returned"}).`);
-    writeLine(door.io.stdout, `Nothing is read until a sync runs: \`cockpit cal sync ${calendar?.id ?? "<id>"}\`, or wait for the cron.`);
-    return 0;
-}
 async function create(command, door) {
     const answer = await askAgentDoor(door, {
         path: "/api/cal/events",
@@ -328,64 +307,4 @@ async function create(command, door) {
         writeLine(door.io.stdout, `Invitations went to ${command.attendees.join(", ")} from Google.`);
     }
     return 0;
-}
-async function share(command, door) {
-    const orgVisible = command.orgVisible && !command.makePrivate;
-    const answer = await askAgentDoor(door, {
-        path: `/api/cal/calendars?calendar_id=${encodeURIComponent(command.subjectId ?? "")}`,
-        method: "PATCH",
-        label: "cal share",
-        timeoutMs: WRITE_DEADLINE_MS,
-        body: { org_visible: orgVisible },
-    });
-    if (!answer.ok)
-        return failAgentDoor(door, TAG, answer.reason, answer.detail);
-    const calendar = answer.body.calendar;
-    if (door.json)
-        return emitAgentDoor(door, { ok: true, calendar });
-    writeLine(door.io.stdout, orgVisible
-        ? `"${calendar?.name ?? command.subjectId}" is now readable by everyone at BLI. Nobody but you can change it.`
-        : `"${calendar?.name ?? command.subjectId}" is private again — only you can read it.`);
-    return 0;
-}
-async function detach(command, door) {
-    const answer = await askAgentDoor(door, {
-        path: `/api/cal/calendars?calendar_id=${encodeURIComponent(command.subjectId ?? "")}`,
-        method: "DELETE",
-        label: "cal detach",
-        timeoutMs: WRITE_DEADLINE_MS,
-    });
-    if (!answer.ok)
-        return failAgentDoor(door, TAG, answer.reason, answer.detail);
-    if (door.json)
-        return emitAgentDoor(door, { ok: true, detached: command.subjectId });
-    writeLine(door.io.stdout, `Detached ${command.subjectId}. Its stored events went with it; the calendar itself is untouched at Google.`);
-    return 0;
-}
-async function sync(command, door) {
-    const answer = await askAgentDoor(door, {
-        path: `/api/cal/calendars/${encodeURIComponent(command.subjectId ?? "")}/sync${command.full ? "?full=1" : ""}`,
-        method: "POST",
-        label: "cal sync",
-        timeoutMs: SYNC_DEADLINE_MS,
-    });
-    if (!answer.ok)
-        return failAgentDoor(door, TAG, answer.reason, answer.detail);
-    const run = answer.body.run;
-    if (door.json)
-        return emitAgentDoor(door, { ok: true, run });
-    if (!run) {
-        writeLine(door.io.stdout, "Tower answered without a run. Nothing to report.");
-        return 0;
-    }
-    if (run.reason === "ok") {
-        writeLine(door.io.stdout, run.detail === "feed_unchanged"
-            ? "Nothing has changed on that calendar since the last read."
-            : `Synced: ${run.eventsAdded} new, ${run.eventsUpdated} updated, ${run.eventsDeleted} gone.`);
-        return 0;
-    }
-    // A failure names itself; the exit code says it failed.
-    writeLine(door.io.stderr, `${TAG} sync ${JSON.stringify({ reason: run.reason, detail: run.detail })}`);
-    writeLine(door.io.stdout, `That calendar did not sync: ${run.reason}${run.detail ? ` (${run.detail})` : ""}.`);
-    return 1;
 }

package/dist/commands/docs.js

@@ -32,6 +32,7 @@ import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
 import { readDoc } from "./docs-read.js";
 import { linkDoc, syncStatusDocs } from "./docs-notion.js";
 import { readNoteFile } from "./notes-file.js";
+import { cacheAgeLabel, readThroughCache } from "./read-cache.js";
 const TAG = "[docs cli]";
 const READ_DEADLINE_MS = 30_000;
 const WRITE_DEADLINE_MS = 60_000;
@@ -74,17 +75,32 @@ export function docsListPath(command) {
     return search.length > 0 ? `/api/docs/documents?${search}` : "/api/docs/documents";
 }
 async function listDocs(command, door) {
-    const answer = await askAgentDoor(door, {
-        path: docsListPath(command),
-        method: "GET",
+    const listPath = docsListPath(command);
+    const answer = await readThroughCache({
+        io: door.io,
+        homeDir: door.homeDir,
+        deviceToken: door.deviceToken,
+        surface: "docs",
         label: "docs list",
-        timeoutMs: READ_DEADLINE_MS,
+        path: listPath,
+        json: door.json,
+        ask: () => askAgentDoor(door, {
+            path: listPath,
+            method: "GET",
+            label: "docs list",
+            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 documents = (answer.body.documents ?? []);
     if (door.json)
         return emitAgentDoor(door, { ok: true, documents });
+    if (answer.fromCache) {
+        writeLine(door.io.stderr, `(${cacheAgeLabel(answer.ageMs ?? 0)}, refreshing in the background)`);
+    }
     if (documents.length === 0) {
         writeLine(door.io.stdout, command.query ? `No document matches "${command.query}".` : "No documents.");
         return 0;

package/dist/commands/issue-directory.js

@@ -22,6 +22,13 @@ async function fetchTeamDirectory(door) {
         method: "GET",
         label: "issue assignee directory",
         timeoutMs: TEAM_DIRECTORY_TIMEOUT_MS,
+        // BLI-10746: this runs IN PARALLEL with `work list`'s own issues fetch
+        // (BLI-10579) — measured live, an un-warmed directory call was the
+        // reason `work list`'s end-to-end time did not show the daemon's own
+        // ~300ms handshake saving (its own fetch dropped from 749ms cold to
+        // ~420-500ms warm; the command's total didn't, because this parallel
+        // call was still paying a cold connection every time).
+        warmRoute: true,
     });
     if (!answer.ok)
         return { ok: false, people: [], reason: answer.reason };

package/dist/commands/issue.js

@@ -28,6 +28,7 @@
 import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor, } from "./agent-door.js";
 import { writeLine } from "./cli-io.js";
 import { assigneeLabel, beginAssigneeDirectoryFetch, finishAssigneeDirectory, withAssigneeIdentity } from "./issue-directory.js";
+import { cacheAgeLabel, readThroughCache } from "./read-cache.js";
 import { showIssue } from "./issue-show.js";
 import { READ_DEADLINE_MS, TAG, resolveProjectId, sizeForEstimate, withSizeLabel, } from "./issue-contracts.js";
 import { commentIssue, createIssue, moveIssue, updateIssue } from "./issue-write.js";
@@ -111,11 +112,26 @@ async function listIssues(command, door) {
     // instead of waiting for that answer first (measured ~580ms of the ~580ms
     // `work list` p50 was exactly this serial second call).
     const directoryFetch = beginAssigneeDirectoryFetch(door);
-    const answer = await askAgentDoor(door, {
-        path: `/api/work/issues${suffix ? `?${suffix}` : ""}`,
-        method: "GET",
+    const listPath = `/api/work/issues${suffix ? `?${suffix}` : ""}`;
+    const answer = await readThroughCache({
+        io: door.io,
+        homeDir: door.homeDir,
+        deviceToken: door.deviceToken,
+        surface: "work",
         label: "issue list",
-        timeoutMs: READ_DEADLINE_MS,
+        path: listPath,
+        json: door.json,
+        ask: () => askAgentDoor(door, {
+            path: listPath,
+            method: "GET",
+            label: "issue list",
+            timeoutMs: READ_DEADLINE_MS,
+            // BLI-10746: `work list` was the slowest of the six reads measured
+            // from Vietnam (1,682 ms p50) — route it through the resident memory
+            // daemon's warm connection so this command skips a fresh TCP+TLS
+            // handshake.
+            warmRoute: true,
+        }),
     });
     if (!answer.ok) {
         // Not awaited for its own sake — `finishAssigneeDirectory` always awaits
@@ -123,6 +139,9 @@ async function listIssues(command, door) {
         await finishAssigneeDirectory(door, directoryFetch, []);
         return failAgentDoor(door, TAG, answer.reason, answer.detail);
     }
+    if (answer.fromCache && !door.json) {
+        writeLine(door.io.stderr, `(${cacheAgeLabel(answer.ageMs ?? 0)}, refreshing in the background)`);
+    }
     const body = answer.body;
     const issues = body.issues ?? [];
     // BLI-10447: the gaps go to stderr in both modes, so `--json` stdout stays one object.

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.150");
     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/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/warm-tower-fetch.js

@@ -0,0 +1,83 @@
+/**
+ * A CLI READ, ROUTED THROUGH THE RESIDENT MEMORY DAEMON'S WARM CONNECTION
+ * (BLI-10746).
+ *
+ * Every `cockpit` process today opens its own TCP+TLS connection to Tower —
+ * measured from Vietnam, about 420 ms of the ~1,700 ms `work list` takes is
+ * exactly that setup, paid fresh on every single command. `@bli-cockpit/
+ * memory-mcp`'s resident daemon already holds one connection open across
+ * turns for recall (BLI-10741); this module is "reuse that for every other
+ * read too" — a GET (or the one POST read this repo has, `memory search`)
+ * asks the daemon to replay it on its own dispatcher instead of opening a new
+ * socket.
+ *
+ * **Fallback is the whole safety argument.** A daemon that is absent, wedged,
+ * refuses, times out, or answers something this cannot parse means exactly
+ * one thing here: go the way this command always went. `isWarmRoutableRead`
+ * decides which requests are even eligible — writes NEVER take this path, so
+ * there is no daemon-retry-of-a-write hazard to reason about.
+ *
+ * **Auth never changes hands.** The caller's own `authorization` header
+ * travels inside `init.headers` exactly as `towerRequest` already built it;
+ * the daemon forwards it unread (see `@bli-cockpit/memory-mcp`'s
+ * `daemon/http-proxy.ts`). This module never reads the device token either.
+ */
+import os from "node:os";
+import { memoryDaemonEndpoint } from "@bli-cockpit/telemetry-core";
+import { askMemoryDaemonHttp, } from "@bli-cockpit/telemetry-core/node-daemon-http-client";
+/**
+ * The only POST this repo treats as a read for warm-routing purposes
+ * (`cockpit memory search`, `POST /api/memory/search`). Every other read is a
+ * GET; a caller names itself with the same `label` it already logs under.
+ */
+const WARM_ROUTABLE_POST_LABELS = new Set(["memory search"]);
+/** GET is always eligible; a small named allowlist covers the one read that is not. */
+export function isWarmRoutableRead(method, label) {
+    return method === "GET" || WARM_ROUTABLE_POST_LABELS.has(label);
+}
+/** The whole local-socket-plus-daemon's-own-fetch budget. Comfortably under any `READ_DEADLINE_MS` a command sets. */
+export const WARM_FETCH_DEADLINE_MS = 10_000;
+/**
+ * Tries the daemon; returns `null` on ANY reason it could not, so the caller
+ * falls back to a direct request. Never throws.
+ */
+export async function tryWarmTowerFetch(url, init, log, deps = {}) {
+    const endpoint = memoryDaemonEndpoint({
+        homeDir: deps.homeDir ?? os.homedir(),
+        ...(deps.platform ? { platform: deps.platform } : {}),
+        username: deps.username ?? safeUsername(),
+    });
+    if (endpoint.kind === "unix" && endpoint.addressTooLong) {
+        log(`[tower client] warm route skipped ${JSON.stringify({ reason: "socket_path_too_long" })}`);
+        return null;
+    }
+    const result = await askMemoryDaemonHttp({
+        address: endpoint.address,
+        deadlineMs: deps.deadlineMs ?? WARM_FETCH_DEADLINE_MS,
+        ...(deps.connectImpl ? { connectImpl: deps.connectImpl } : {}),
+        ...(deps.now ? { now: deps.now } : {}),
+        request: {
+            method: init.method,
+            url,
+            headers: init.headers,
+            ...(init.body === undefined ? {} : { body: init.body }),
+        },
+    });
+    if (!result.ok) {
+        log(`[tower client] warm route missed ${JSON.stringify({ reason: result.reason, elapsed_ms: result.elapsedMs })}`);
+        return null;
+    }
+    log(`[tower client] warm route used ${JSON.stringify({ elapsed_ms: result.elapsedMs })}`);
+    return new Response(result.answer.body, {
+        status: result.answer.status,
+        headers: result.answer.headers,
+    });
+}
+function safeUsername() {
+    try {
+        return os.userInfo().username;
+    }
+    catch {
+        return undefined;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.149",
+  "version": "0.2.150",
   "private": false,
   "type": "module",
   "bin": {
@@ -27,8 +27,8 @@
     "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-package-pack.mjs --workspace=@bli-cockpit/cli"
   },
   "dependencies": {
-    "@bli-cockpit/memory-mcp": "0.1.38",
-    "@bli-cockpit/mcp": "0.1.72",
-    "@bli-cockpit/telemetry-core": "0.1.50"
+    "@bli-cockpit/memory-mcp": "0.1.39",
+    "@bli-cockpit/mcp": "0.1.73",
+    "@bli-cockpit/telemetry-core": "0.1.51"
   }
 }