@bli-cockpit/cli 0.2.58 → 0.2.60

package/dist/commands/ops-render-memory.js

@@ -0,0 +1,76 @@
+/**
+ * How the BLI Memory adoption gauge reads in a terminal (BLI-3729). Pure
+ * layout: no io, no network, no clock of its own — the sibling of
+ * `ops-render.ts`, split out to keep both under the repo's readability band
+ * (`repo-shape/file-size-ratchet.test.ts`).
+ *
+ * Same rule as the fleet and coverage sections next door: every SENTENCE was
+ * written on the server (`lib/ops/memory-usage.ts`) and is printed verbatim;
+ * this file decides column widths and order and nothing else.
+ *
+ * Both public names are re-exported from `./ops-render.js`, so a caller of that
+ * module never has to know the split happened.
+ */
+/**
+ * Is the org using BLI Memory? One row per person, one column per day, and the
+ * two agent sources counted apart from the import — an imported row is a
+ * backfill and must never be read as somebody using the thing.
+ */
+export function renderMemoryUsage(memory, dim) {
+    const lines = ["", `MEMORY  ${memory.summary ?? "(no summary)"}`];
+    if (memory.readError) {
+        lines.push(`  usage could not be read (${memory.readError}); nothing is known about whether anybody is using BLI Memory`);
+        return lines;
+    }
+    const days = memory.days ?? [];
+    const people = memory.people ?? [];
+    if (people.length === 0) {
+        lines.push(dim("  nobody on the roster has any memory activity to show"));
+        return lines;
+    }
+    const nameWidth = Math.max(6, ...people.map((person) => (person.displayName ?? "").length));
+    // `MM-DD` per column: the year is the same on every one of seven days and
+    // spending four characters on it costs the terminal a column per day.
+    const header = `  ${"person".padEnd(nameWidth)}  ` +
+        days.map((day) => day.slice(5).padStart(5)).join(" ") +
+        `  ${"mcp".padStart(5)} ${"hook".padStart(5)} ${"impt".padStart(5)}`;
+    lines.push(dim(header));
+    // Most active first, so the answer to "who is using it" is the top of the
+    // list; the unattributed bucket sinks to the bottom whatever its total,
+    // because it is not a person and its number is mostly the import.
+    const ranked = [...people].sort((left, right) => {
+        const leftOrphan = left.personId === null || left.personId === undefined ? 1 : 0;
+        const rightOrphan = right.personId === null || right.personId === undefined ? 1 : 0;
+        if (leftOrphan !== rightOrphan)
+            return leftOrphan - rightOrphan;
+        return agentSaves(right.counts) - agentSaves(left.counts);
+    });
+    for (const person of ranked) {
+        const byDay = new Map((person.days ?? []).map((entry) => [entry.day ?? "", entry]));
+        const cells = days
+            .map((day) => {
+            const entry = byDay.get(day);
+            const saved = agentSaves(entry?.counts);
+            // A zero prints as `·`, not `0`: seven zeroes in a row is the shape a
+            // reader is scanning for, and seven `0`s hide it in the noise.
+            return (saved === 0 ? "·" : String(saved)).padStart(5);
+        })
+            .join(" ");
+        const counts = person.counts ?? {};
+        const row = `  ${(person.displayName ?? "?").padEnd(nameWidth)}  ${cells}  ` +
+            `${String(counts.mcp ?? 0).padStart(5)} ${String(counts.stop_hook ?? 0).padStart(5)} ` +
+            `${String(counts.import ?? 0).padStart(5)}`;
+        lines.push(agentSaves(counts) > 0 ? row : dim(row));
+    }
+    if (memory.truncated) {
+        lines.push(dim("  this read stopped at its page cap, so every number above is a FLOOR — it can understate use and never invent it"));
+    }
+    if (memory.searches?.counted === false) {
+        lines.push(dim(`  searches are not counted (${memory.searches.reason ?? "no ledger"}): nothing in Tower records one, so this is saves only`));
+    }
+    return lines;
+}
+/** The two sources that mean a PERSON's agent used memory. Never the import. */
+function agentSaves(counts) {
+    return (counts?.mcp ?? 0) + (counts?.stop_hook ?? 0);
+}

package/dist/commands/ops-render.js

@@ -12,6 +12,7 @@
  * artifact does and does not prove — because that is exactly the moment
  * somebody is about to conclude something from it.
  */
+export { renderMemoryUsage } from "./ops-render-memory.js";
 /** The word a person reads. Short, fixed width, and never a bare colour. */
 export function verdictWord(verdict) {
     switch (verdict) {
@@ -24,6 +25,11 @@ export function verdictWord(verdict) {
         // rather than to a cron config.
         case "failing":
             return "BAD";
+        // BLI-3762. Between "on time" and "dead": the job ran, produced something,
+        // and produced LESS than it owed. A partial result that is still moving
+        // needs a different next step from either neighbour, so it gets a word.
+        case "degraded":
+            return "PART";
         case "never_produced":
             return "EMPTY";
         case "unreadable":

package/dist/commands/ops.js

@@ -25,6 +25,7 @@
  */
 import { colorEnabled, dim, writeLine } from "./cli-io.js";
 import { renderOpsStatus } from "./ops-render.js";
+import { renderMemoryUsage, } from "./ops-render-memory.js";
 import { asRecord, callTower, openTower, writeCommandFailure } from "./tower-command.js";
 /**
  * A whole compile, plus a little. `maxDuration` on `/api/ops/recompile` is 800
@@ -60,6 +61,13 @@ async function runOpsStatus(command, io, tower) {
     }
     const payload = asRecord(result.body);
     const rows = payload.pipelines ?? [];
+    // BLI-3729. A SECOND door, asked for only when `--memory` was: the adoption
+    // gauge is a different question from pipeline health and a different read,
+    // and putting it on every `cockpit ops` would make the common run slower for
+    // a number most runs do not want. Its failure is its own line and never the
+    // status board's exit code — "is the org using memory" going unread is not a
+    // pipeline outage.
+    const memory = command.memory ? await readMemoryUsage(command, io, tower) : null;
     // BLI-3723: `failing` joins the list. An older CLI that has never heard of it
     // simply does not count it — which is why the server keeps the sentence in
     // `detail`, so an un-upgraded terminal still PRINTS the outage even when it
@@ -67,15 +75,28 @@ async function runOpsStatus(command, io, tower) {
     const unhealthy = rows.filter((row) => row.verdict === "stale" ||
         row.verdict === "never_produced" ||
         row.verdict === "unreadable" ||
-        row.verdict === "failing");
+        row.verdict === "failing" ||
+        // BLI-3762: a job that ran and wrote less than it owed is not healthy.
+        row.verdict === "degraded");
     if (command.json) {
-        writeLine(io.stdout, JSON.stringify(payload));
+        writeLine(io.stdout, JSON.stringify(memory ? { ...payload, memory: memory.section } : payload));
     }
     else {
         const styled = colorEnabled(io);
         for (const line of renderOpsStatus(payload, (text) => dim(text, styled))) {
             writeLine(io.stdout, line);
         }
+        if (memory?.section) {
+            for (const line of renderMemoryUsage(memory.section, (text) => dim(text, styled))) {
+                writeLine(io.stdout, line);
+            }
+        }
+        else if (memory) {
+            // Never a silent gap where a section was asked for: the reason the gauge
+            // could not be read is printed where the gauge would have been.
+            writeLine(io.stdout, "");
+            writeLine(io.stdout, `MEMORY  not read (${memory.reason})`);
+        }
     }
     // Both branches log — an all-green board that says nothing cannot answer
     // "did anybody look today?".
@@ -91,9 +112,45 @@ async function runOpsStatus(command, io, tower) {
         fleet_devices: payload.fleet?.counts?.devices ?? null,
         fleet_red: payload.fleet?.counts?.red ?? null,
         fleet_amber: payload.fleet?.counts?.amber ?? null,
+        // BLI-3729: whether the adoption gauge was asked for, and what it said.
+        // Both branches, as everywhere else here.
+        memory_asked: Boolean(command.memory),
+        memory_reason: memory?.reason ?? null,
+        memory_agent_saves: memory?.section
+            ? (memory.section.counts?.mcp ?? 0) + (memory.section.counts?.stop_hook ?? 0)
+            : null,
     })}`);
     return unhealthy.length > 0 ? 1 : 0;
 }
+/**
+ * The adoption gauge, read through its own door.
+ *
+ * Never fails the board: a `cockpit ops --memory` whose memory half is
+ * unreadable still prints the pipelines, the fleet and the coverage, and says
+ * in one line which half is missing and why. The status board's exit code is
+ * about collection health, and adoption is not that.
+ */
+async function readMemoryUsage(command, io, tower) {
+    const params = new URLSearchParams();
+    if (command.memoryDays !== undefined)
+        params.set("days", String(command.memoryDays));
+    const query = params.toString();
+    const result = await callTower(tower, {
+        path: `/api/ops/memory-usage${query ? `?${query}` : ""}`,
+        label: "ops-memory-usage",
+    });
+    if (!result.ok) {
+        writeLine(io.stderr, `[ops cli] memory usage not read ${JSON.stringify({
+            reason: result.reason,
+            http_status: result.httpStatus ?? null,
+        })}`);
+        return { section: null, reason: result.reason };
+    }
+    const body = asRecord(result.body);
+    if (!body.memory)
+        return { section: null, reason: "memory_section_absent" };
+    return { section: body.memory, reason: "ok" };
+}
 async function runOpsRecompile(command, io, tower) {
     const person = command.person ?? "";
     if (!command.json) {

package/dist/commands/public-root.js

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

package/dist/commands/search.js

@@ -0,0 +1,122 @@
+/**
+ * `cockpit search` — one bar over five corpora, in a terminal (BLI-3728).
+ *
+ * The SAME door the browser's search bar presses: `GET /api/search`, opted
+ * into the collector device token in `route-caller-census.test.ts`. So a
+ * result a person reads in the rail is the same row, the same ranking and the
+ * same snippet an agent gets here. That is the whole point of the ticket's
+ * "agent-friendly is the definition of done" clause; nothing about search is
+ * computed on this side.
+ *
+ * WHAT THIS PRINTS THAT THE BROWSER ALSO SHOWS
+ * --------------------------------------------
+ * A corpus that could not answer gets its own line. "Messages did not answer"
+ * and "no messages matched" are different facts, and a terminal that folds
+ * them together lets a person conclude the record is silent when the search
+ * was simply broken. Same rule, same words, as the overlay.
+ *
+ * `[[` / `]]` are `ts_headline`'s markers, chosen server-side precisely
+ * BECAUSE they are inert in a terminal (`src/lib/search/snippet.ts`). Without
+ * a TTY they are stripped; with one they become reverse video, and nothing
+ * here parses HTML.
+ *
+ * A refusal keeps the door's own `reason` label verbatim (`agent-door.ts`):
+ * `needs_rls_client`, `query_too_short`, `query_too_long`, `unknown_kind`,
+ * `read_failed` — never rephrased here.
+ */
+import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor, } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+const TAG = "[search cli]";
+const READ_DEADLINE_MS = 30_000;
+/** Group headings, in the order a person reads them. Mirrors the overlay. */
+const KIND_LABELS = {
+    doc: "DOCUMENTS",
+    msg: "MESSAGES",
+    issue: "ISSUES",
+    note: "MEETING NOTES",
+    memory: "MEMORY",
+};
+const KIND_ORDER = ["doc", "msg", "issue", "note", "memory"];
+export async function runSearch(command, io) {
+    const door = await openAgentDoor("search", command, io);
+    const params = new URLSearchParams({ q: command.query });
+    if (command.kinds && command.kinds.length > 0)
+        params.set("kinds", command.kinds.join(","));
+    if (command.limit !== undefined)
+        params.set("limit", String(command.limit));
+    const answer = await askAgentDoor(door, {
+        path: `/api/search?${params.toString()}`,
+        method: "GET",
+        label: "search",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    if (door.json)
+        return emitAgentDoor(door, body);
+    return render(door, body);
+}
+function render(door, body) {
+    const hits = body.hits ?? [];
+    const failures = body.failures ?? {};
+    const colour = Boolean(door.io.stdout.isTTY);
+    if (hits.length === 0) {
+        if (Object.keys(failures).length === 0) {
+            writeLine(door.io.stdout, "Nothing matched. Every corpus answered — this is silence, not a failure.");
+        }
+        else {
+            writeLine(door.io.stdout, "Nothing matched in the corpora that answered.");
+        }
+    }
+    for (const kind of KIND_ORDER) {
+        const group = hits.filter((hit) => hit.kind === kind);
+        if (group.length === 0)
+            continue;
+        writeLine(door.io.stdout, "");
+        writeLine(door.io.stdout, KIND_LABELS[kind] ?? kind.toUpperCase());
+        for (const hit of group) {
+            writeLine(door.io.stdout, `  ${hit.title}`);
+            const snippet = paintSnippet(hit.snippet, colour);
+            if (snippet.length > 0)
+                writeLine(door.io.stdout, `    ${snippet}`);
+            const meta = [
+                hit.author,
+                hit.date ? hit.date.slice(0, 10) : null,
+                (hit.channels ?? []).join("+"),
+                `score ${hit.score}`,
+                // A memory has no address, and saying so is better than printing a
+                // blank column somebody reads as a missing link.
+                hit.href ?? "(no page — the text above is the whole record)",
+            ]
+                .filter(Boolean)
+                .join("  ·  ");
+            writeLine(door.io.stdout, `    ${meta}`);
+        }
+    }
+    // Never folded into "nothing matched". Same rule as the overlay.
+    const failed = Object.entries(failures);
+    if (failed.length > 0) {
+        writeLine(door.io.stdout, "");
+        for (const [kind, reason] of failed) {
+            writeLine(door.io.stdout, `${KIND_LABELS[kind] ?? kind.toUpperCase()} did not answer (${reason}). Nothing from there is in this list.`);
+        }
+    }
+    writeLine(door.io.stdout, "");
+    writeLine(door.io.stdout, `${hits.length} result(s) in ${body.elapsedMs ?? 0} ms.`);
+    return 0;
+}
+const REVERSE_ON = "\u001B[7m";
+const REVERSE_OFF = "\u001B[27m";
+/**
+ * `[[match]]` into reverse video, or into plain text without a TTY.
+ *
+ * A pipe gets clean text — `cockpit search x | grep` must not have to know
+ * about escape codes — and a terminal gets the highlight the browser shows.
+ */
+export function paintSnippet(snippet, colour) {
+    const collapsed = snippet.replace(/\s+/g, " ").trim();
+    if (!colour)
+        return collapsed.split("[[").join("").split("]]").join("");
+    return collapsed.split("[[").join(REVERSE_ON).split("]]").join(REVERSE_OFF);
+}

package/dist/commands/setup-receipt-lines.js

@@ -0,0 +1,71 @@
+/**
+ * What the setup receipt SAYS (BLI-3731). One line, then one fix per gap.
+ *
+ * Split from `setup-receipt.ts` for the reason the repo splits everything:
+ * computing a state and wording it are different jobs, and only one of them
+ * touches the machine. This file touches nothing.
+ *
+ * The rule for the fix lines is the one the message standard already sets — a
+ * refusal that does not say what to do next is half a message. Every gap here
+ * gets ONE command or ONE click, never a paragraph and never "see the docs".
+ */
+import { setupPieceMark, setupReceiptLine, setupReceiptPieces, } from "@bli-cockpit/telemetry-core";
+/** The one fix for each piece, by key. Present for every key the block prints. */
+const FIXES = {
+    browser: "Run `cockpit login` and open the link it prints.",
+    device: "Run `cockpit login` — this machine's session has lapsed.",
+    "claude.mcp": "Run `cockpit memory install`.",
+    "claude.hooks": "Run `cockpit memory install`.",
+    "codex.mcp": "Run `cockpit memory install`.",
+    "codex.skill": "Run `cockpit memory install`.",
+    "codex.hooks": "Run `cockpit memory install`.",
+    "collector.autostart": "Run `cockpit autostart install`.",
+};
+/** Codex hooks a person switched OFF is a decision, not a fault. */
+const UNSUPPORTED_FIX = "Switched off in your own config; nothing to do.";
+/**
+ * The one exception to "a gap gets a command": Codex hooks that are installed
+ * and waiting to be trusted are finished by a PERSON, in the Codex UI, and no
+ * command we could print would do it.
+ */
+const NEEDS_TRUST_FIX = "Open Codex and press `/hooks` to trust them (once, ~15s).";
+/**
+ * The block a terminal prints: the one line, then one fix per gap, then
+ * nothing. A fully connected machine gets one line and no advice — a receipt
+ * that keeps talking after saying yes trains people to stop reading it.
+ */
+export function setupReceiptBlock(reading, options = {}) {
+    const { receipt, memory } = reading;
+    const indent = options.indent ?? "";
+    const lines = [`${indent}${setupReceiptLine(receipt, memory)}`];
+    for (const { key, label, piece } of setupReceiptPieces(receipt, memory)) {
+        if (piece.status === "ok")
+            continue;
+        lines.push(`${indent}  ${label} ${setupPieceMark(piece.status)}${reasonSuffix(piece)} — ${fixFor(key, piece)}`);
+    }
+    if (options.showCheckedAt) {
+        lines.push(`${indent}Last read: ${receipt.checked_at}`);
+    }
+    return lines;
+}
+/** The whole receipt in one string, for a single `writeLine`. */
+export function setupReceiptText(reading, options = {}) {
+    return setupReceiptBlock(reading, options).join("\n");
+}
+function fixFor(key, piece) {
+    if (piece.status === "needs_trust")
+        return NEEDS_TRUST_FIX;
+    if (piece.status === "unsupported")
+        return UNSUPPORTED_FIX;
+    if (piece.status === "unknown") {
+        // "We did not look" is not somebody's chore. Say what would look.
+        return "Not read this run. Run `cockpit doctor` to check it.";
+    }
+    if (piece.status === "skipped") {
+        return "Skipped on purpose; nothing to do.";
+    }
+    return FIXES[key] ?? "Run `cockpit doctor`.";
+}
+function reasonSuffix(piece) {
+    return piece.reason ? ` (${piece.reason})` : "";
+}

package/dist/commands/setup-receipt.js

@@ -0,0 +1,241 @@
+/**
+ * "Is this machine actually connected?" — computed here, on the machine
+ * (BLI-3731).
+ *
+ * Seven words, every one of them READ BACK off this host rather than
+ * remembered from what we wrote. That rule is BLI-2541's, and it is the whole
+ * value of this module: `cockpit autostart` once registered a correct Windows
+ * task and then rejected it on every machine for months because it compared
+ * the readback against the strings Cockpit itself had sent.
+ *
+ * Where each word comes from:
+ *
+ *   browser              the device session on disk names a person. A device
+ *                        token exists ONLY because somebody signed a browser
+ *                        in, so the session file is the evidence — there is no
+ *                        second thing to ask.
+ *   device               that same session, still unexpired.
+ *   collector.autostart  `autostartStatus`, which asks launchd or Task
+ *                        Scheduler what it actually has registered.
+ *
+ * The five AGENT-HOST words in the printed block are NOT computed here. They
+ * are BLI-3729's `MemoryInstallReceipt`, already read back off
+ * `~/.claude.json`, `~/.claude/settings.json` and `~/.codex/config.toml`,
+ * already cached beside this one and already carried on the heartbeat as
+ * `memory_install`. This module reads that cache and hands both halves to the
+ * renderer. A second computation of the same five words would be a second
+ * place for them to be wrong.
+ *
+ * A piece this run did not inspect is `unknown`, never `missing`. The two are
+ * different facts and only one of them is somebody's problem.
+ *
+ * The SHAPE lives in `@bli-cockpit/telemetry-core` so the CLI and the
+ * dashboard word the same machine the same way; `memory-install-contract.ts`
+ * owns the target vocabulary this translates from.
+ */
+import os from "node:os";
+import { SETUP_RECEIPT_SCHEMA_VERSION, setupReceiptGaps, setupReceiptLine, } from "@bli-cockpit/telemetry-core";
+import { readHeartbeatMemoryReceipt } from "./heartbeat.js";
+import { autostartStatus } from "../autostart.js";
+import { readLocalSessionReference } from "../local-state.js";
+import { getCollectorRuntimePaths } from "../local-state-paths.js";
+import { readJsonFile, writeJsonFile } from "../local-state-files.js";
+const TAG = "[setup receipt]";
+/** Where the last computed receipt is cached, so a heartbeat need not re-probe. */
+export const SETUP_RECEIPT_CACHE_FILE = "setup-receipt.json";
+/**
+ * How stale a cached receipt may be before the heartbeat stops sending it.
+ * Seven days: these facts change about monthly, and re-probing them costs five
+ * file reads and a `--print-config` spawn that a 15-minute tick must not pay.
+ */
+export const SETUP_RECEIPT_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+export async function buildSetupReceipt(io, options = {}) {
+    const homeDir = options.homeDir ?? os.homedir();
+    const checkedAt = (options.now ?? new Date()).toISOString();
+    const probes = withDefaultProbes(io, homeDir, options);
+    const memory = await probes.memory().catch((error) => {
+        console.error(`${TAG} the memory receipt could not be read`, JSON.stringify({ reason: "memory_receipt_read_failed", error_name: errorName(error) }));
+        return null;
+    });
+    const session = await probes.session().catch((error) => {
+        console.error(`${TAG} device session could not be read`, JSON.stringify({ reason: "session_probe_failed", error_name: errorName(error) }));
+        return null;
+    });
+    const autostart = await probes.autostart().catch((error) => {
+        console.error(`${TAG} scheduler could not be read`, JSON.stringify({ reason: "autostart_probe_failed", error_name: errorName(error) }));
+        return { status: "unreadable" };
+    });
+    const receipt = {
+        schema_version: SETUP_RECEIPT_SCHEMA_VERSION,
+        checked_at: checkedAt,
+        browser: browserPiece(session),
+        device: devicePiece(session),
+        collector: { autostart: autostartPiece(autostart) },
+    };
+    const gaps = setupReceiptGaps(receipt, memory);
+    console.error(`${TAG} read back`, JSON.stringify({
+        reason: gaps.length === 0 ? "everything_connected" : "gaps_found",
+        gap_count: gaps.length,
+        gaps,
+        memory_receipt: memory ? "read" : "absent",
+    }));
+    return { receipt, memory };
+}
+function withDefaultProbes(io, homeDir, options) {
+    return {
+        memory: options.probes?.memory ??
+            (async () => (await readHeartbeatMemoryReceipt({
+                homeDir,
+                ...(options.now ? { now: options.now } : {}),
+            })).receipt),
+        session: options.probes?.session ??
+            (async () => {
+                const reference = await readLocalSessionReference(getCollectorRuntimePaths(homeDir));
+                return {
+                    state: reference.session_state,
+                    ...(reference.email ? { email: reference.email } : {}),
+                };
+            }),
+        autostart: options.probes?.autostart ??
+            (async () => {
+                // The scheduler can only be READ through a process runner; a machine
+                // whose io carries none is unknown, never "absent" (BLI-2541: never
+                // report a state you did not observe).
+                const exec = io.exec;
+                if (!exec)
+                    return { status: "unreadable", message: "runner_unavailable" };
+                const result = await autostartStatus({ homeDir, exec });
+                return {
+                    status: result.status,
+                    ...(result.message ? { message: result.message } : {}),
+                };
+            }),
+    };
+}
+/**
+ * A device token exists only because a person signed a browser in and claimed
+ * this machine, so a session that names an email IS the browser receipt. A
+ * session with no email came from the manual admin-approval path, which is a
+ * real way to pair and not a browser sign-in — it says so rather than claiming
+ * a click nobody made.
+ */
+function browserPiece(session) {
+    if (!session)
+        return { status: "unknown", reason: "session_unreadable" };
+    if (session.state !== "valid") {
+        return { status: "missing", reason: "never_signed_in" };
+    }
+    return session.email
+        ? { status: "ok", reason: "signed_in" }
+        : { status: "ok", reason: "paired_without_email" };
+}
+function devicePiece(session) {
+    if (!session)
+        return { status: "unknown", reason: "session_unreadable" };
+    if (session.state === "valid")
+        return { status: "ok", reason: "session_valid" };
+    if (session.state === "expired") {
+        return { status: "missing", reason: "session_expired" };
+    }
+    return { status: "missing", reason: `session_${session.state}` };
+}
+/**
+ * The scheduler is `ok` only when the host says it is registered AND loaded.
+ * `installed` on macOS means the plist is on disk; `loaded` means launchd has
+ * it. A plist nobody loaded runs nothing, which is exactly the failure that
+ * looks fine from the outside.
+ */
+function autostartPiece(result) {
+    if (result.status === "loaded" || result.status === "installed") {
+        return { status: "ok", reason: `autostart_${result.status}` };
+    }
+    if (result.status === "not_loaded") {
+        return { status: "missing", reason: "autostart_not_loaded" };
+    }
+    if (result.status === "absent" || result.status === "uninstalled") {
+        return { status: "missing", reason: "autostart_absent" };
+    }
+    if (result.status === "unsupported") {
+        return { status: "skipped", reason: "platform_unsupported" };
+    }
+    return { status: "unknown", reason: normalizeReason(result.status) };
+}
+/** Reason labels are `[a-z0-9_:.-]` by schema; anything else becomes one word. */
+function normalizeReason(value) {
+    const cleaned = value.trim().toLowerCase().replace(/[^a-z0-9_:.-]+/gu, "_");
+    return cleaned.slice(0, 120) || "unlabelled";
+}
+function errorName(error) {
+    return error instanceof Error ? error.name : typeof error;
+}
+// ---------------------------------------------------------------------------
+// The cache — so a 15-minute tick does not re-probe a monthly fact
+// ---------------------------------------------------------------------------
+export function setupReceiptCachePath(homeDir) {
+    const paths = getCollectorRuntimePaths(homeDir ?? os.homedir());
+    return `${paths.state_dir}/${SETUP_RECEIPT_CACHE_FILE}`;
+}
+/** Never fails a caller: a cache that could not be written names itself and moves on. */
+export async function cacheSetupReceipt(receipt, homeDir) {
+    try {
+        await writeJsonFile(setupReceiptCachePath(homeDir), receipt);
+    }
+    catch (error) {
+        console.error(`${TAG} cache not written`, JSON.stringify({ reason: "cache_write_failed", error_name: errorName(error) }));
+    }
+}
+/**
+ * The cached receipt, or null with a named reason. A receipt older than
+ * `SETUP_RECEIPT_MAX_AGE_MS` is refused rather than sent: a stale word is
+ * worse than an absent one, because absence asks and staleness answers.
+ */
+export async function readCachedSetupReceipt(homeDir, now = new Date()) {
+    let raw;
+    try {
+        raw = await readJsonFile(setupReceiptCachePath(homeDir));
+    }
+    catch {
+        // Absent on a machine that has never run the install. Not an error, and
+        // the caller logs the absence with its own reason.
+        return null;
+    }
+    const parsed = safeParseReceipt(raw);
+    if (!parsed) {
+        console.error(`${TAG} cache unusable`, JSON.stringify({ reason: "cache_not_a_receipt" }));
+        return null;
+    }
+    const age = now.getTime() - Date.parse(parsed.checked_at);
+    if (!Number.isFinite(age) || age > SETUP_RECEIPT_MAX_AGE_MS) {
+        console.error(`${TAG} cache too old to send`, JSON.stringify({ reason: "cache_stale", age_days: Math.round(age / 86_400_000) }));
+        return null;
+    }
+    return parsed;
+}
+function safeParseReceipt(raw) {
+    const record = raw;
+    if (!record || record.schema_version !== SETUP_RECEIPT_SCHEMA_VERSION)
+        return null;
+    return raw;
+}
+/** The one line, plus the one fix per gap. Rendering lives in `setup-receipt-lines.ts`. */
+export { setupReceiptLine };
+/**
+ * Read the machine, cache what it said, and hand it back. The ONE entry point
+ * for every surface that shows the receipt (`status`, `doctor`, `onboard`,
+ * `memory install`) — so the block a person reads in a terminal and the block
+ * the ops board renders are always the same reading, not two.
+ *
+ * Never throws: a receipt that could not be computed is `null` with a named
+ * reason, and the caller prints nothing rather than a wrong reassurance.
+ */
+export async function refreshSetupReceipt(io, options = {}) {
+    try {
+        const reading = await buildSetupReceipt(io, options);
+        await cacheSetupReceipt(reading.receipt, options.homeDir);
+        return reading;
+    }
+    catch (error) {
+        console.error(`${TAG} could not be computed`, JSON.stringify({ reason: "receipt_build_failed", error_name: errorName(error) }));
+        return null;
+    }
+}