@bli-cockpit/telemetry-core 0.1.27 → 0.1.29

package/dist/collector-heartbeat.d.ts

@@ -56,6 +56,95 @@ export declare const CollectorHeartbeatSchema: z.ZodObject<{
     last_sync_reason: z.ZodOptional<z.ZodString>;
     sessions_observed: z.ZodOptional<z.ZodNumber>;
     sessions_outside_root: z.ZodOptional<z.ZodNumber>;
+    sessions_new_this_tick: z.ZodOptional<z.ZodNumber>;
+    sessions_pending_upload: z.ZodOptional<z.ZodNumber>;
+    memory_install: z.ZodOptional<z.ZodObject<{
+        schema_version: z.ZodLiteral<"memory-install-receipt.v1">;
+        checked_at: z.ZodString;
+        claude: z.ZodObject<{
+            mcp: z.ZodEnum<{
+                unknown: "unknown";
+                ok: "ok";
+                stale: "stale";
+                missing: "missing";
+            }>;
+            hooks: z.ZodEnum<{
+                unknown: "unknown";
+                ok: "ok";
+                stale: "stale";
+                missing: "missing";
+            }>;
+        }, z.core.$strict>;
+        codex: z.ZodObject<{
+            mcp: z.ZodEnum<{
+                unknown: "unknown";
+                ok: "ok";
+                stale: "stale";
+                missing: "missing";
+            }>;
+            skill: z.ZodEnum<{
+                unknown: "unknown";
+                ok: "ok";
+                stale: "stale";
+                missing: "missing";
+            }>;
+            hooks: z.ZodEnum<{
+                unknown: "unknown";
+                ok: "ok";
+                stale: "stale";
+                missing: "missing";
+                needs_trust: "needs_trust";
+                unsupported: "unsupported";
+            }>;
+        }, z.core.$strict>;
+        reasons: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        bin_found: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    setup_receipt: z.ZodOptional<z.ZodObject<{
+        schema_version: z.ZodLiteral<"setup-receipt.v1">;
+        checked_at: z.ZodString;
+        browser: z.ZodObject<{
+            status: z.ZodEnum<{
+                unknown: "unknown";
+                failed: "failed";
+                skipped: "skipped";
+                ok: "ok";
+                stale: "stale";
+                missing: "missing";
+                needs_trust: "needs_trust";
+                unsupported: "unsupported";
+            }>;
+            reason: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        device: z.ZodObject<{
+            status: z.ZodEnum<{
+                unknown: "unknown";
+                failed: "failed";
+                skipped: "skipped";
+                ok: "ok";
+                stale: "stale";
+                missing: "missing";
+                needs_trust: "needs_trust";
+                unsupported: "unsupported";
+            }>;
+            reason: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        collector: z.ZodObject<{
+            autostart: z.ZodObject<{
+                status: z.ZodEnum<{
+                    unknown: "unknown";
+                    failed: "failed";
+                    skipped: "skipped";
+                    ok: "ok";
+                    stale: "stale";
+                    missing: "missing";
+                    needs_trust: "needs_trust";
+                    unsupported: "unsupported";
+                }>;
+                reason: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 export type CollectorHeartbeat = z.infer<typeof CollectorHeartbeatSchema>;
 /**

package/dist/collector-heartbeat.js

@@ -24,6 +24,8 @@
  */
 import { z } from "zod";
 import { IsoDateTimeSchema, Sha256Schema, VersionStringSchema } from "./common.js";
+import { MemoryInstallReceiptSchema } from "./memory-install-receipt.js";
+import { SetupReceiptSchema } from "./setup-receipt.js";
 export const COLLECTOR_HEARTBEAT_SCHEMA_VERSION = "collector-heartbeat.v1";
 /** The most roots one machine may declare. Well above any real operator. */
 export const COLLECTOR_HEARTBEAT_MAX_ROOTS = 40;
@@ -89,6 +91,45 @@ export const CollectorHeartbeatSchema = z
         .nonnegative()
         .max(1_000_000)
         .optional(),
+    /**
+     * BLI-3645. Two honest counters beside the raw scan count above, both
+     * optional so a collector too old to compute them keeps posting:
+     *
+     *   - `sessions_new_this_tick` — sessions first seen since this source's
+     *     cursor as it stood before this tick, a FLOW, not the re-scanned
+     *     STOCK `sessions_observed` is.
+     *   - `sessions_pending_upload` — sessions inside an approved root with
+     *     no durable pointer yet, i.e. the "only copy" set. A FLOOR at the
+     *     moment this tick observed it, same as every other counter here.
+     */
+    sessions_new_this_tick: z
+        .number()
+        .int()
+        .nonnegative()
+        .max(1_000_000)
+        .optional(),
+    sessions_pending_upload: z
+        .number()
+        .int()
+        .nonnegative()
+        .max(1_000_000)
+        .optional(),
+    /**
+     * BLI-3729. Is BLI Memory actually switched on for both agent hosts on
+     * this machine? Six words computed by reading the host configs BACK, not
+     * by remembering what the last install wrote. Optional so a collector too
+     * old to compute it keeps posting — an absent receipt reads as "this
+     * collector predates the receipt", never as "nothing is installed".
+     */
+    memory_install: MemoryInstallReceiptSchema.optional(),
+    /**
+     * BLI-3731. "Is this machine actually connected?" in seven read-back
+     * words — the browser sign-in, the device session, both agent hosts and
+     * the scheduler. Optional so a collector too old to compute it keeps
+     * posting, and so a tick that sends none leaves whatever the device row
+     * already holds rather than blanking it.
+     */
+    setup_receipt: SetupReceiptSchema.optional(),
 })
     .strict();
 /**

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./agent-artifacts.js";
 export * from "./collector-heartbeat.js";
+export * from "./setup-receipt.js";
 export * from "./common.js";
 export * from "./decision-event.js";
 export * from "./decision-event-id.js";
@@ -8,6 +9,7 @@ export * from "./evidence-reconcile.js";
 export * from "./evidence-upload.js";
 export * from "./ingest-dto.js";
 export * from "./local-config.js";
+export * from "./memory-install-receipt.js";
 export * from "./paths.js";
 export * from "./privacy.js";
 export * from "./risk-flags.js";

package/dist/index.js

@@ -1,5 +1,6 @@
 export * from "./agent-artifacts.js";
 export * from "./collector-heartbeat.js";
+export * from "./setup-receipt.js";
 export * from "./common.js";
 export * from "./decision-event.js";
 export * from "./decision-event-id.js";
@@ -8,6 +9,7 @@ export * from "./evidence-reconcile.js";
 export * from "./evidence-upload.js";
 export * from "./ingest-dto.js";
 export * from "./local-config.js";
+export * from "./memory-install-receipt.js";
 export * from "./paths.js";
 export * from "./privacy.js";
 export * from "./risk-flags.js";

package/dist/memory-install-receipt.d.ts

@@ -0,0 +1,120 @@
+/**
+ * THE MEMORY RECEIPT (BLI-3729) — is BLI Memory actually switched on, on this
+ * laptop, for both agent hosts?
+ *
+ * `cockpit memory install` already converged the two host configurations and
+ * already wrote a per-target `memory_install` install event. What nobody could
+ * answer was the fleet-wide question: "does Savina's machine have memory hooks
+ * at all?" The install event is a per-run receipt in an outbox; this is the
+ * per-MACHINE state, recomputed every sync tick by READING THE FILES BACK and
+ * carried on the heartbeat, so the ops board can name the machine that is
+ * missing a piece instead of somebody grepping logs.
+ *
+ * Six words, one per thing that can independently be absent:
+ *
+ *   claude.mcp      `~/.claude.json`            → the `bli-memory` MCP server
+ *   claude.hooks    `~/.claude/settings.json`   → SessionStart/UserPromptSubmit/Stop
+ *   codex.mcp       `~/.codex/config.toml`      → `[mcp_servers.bli-memory]`
+ *   codex.skill     `~/.codex/skills/bli-memory/` → the skill files
+ *   codex.hooks     `~/.codex/hooks.json`       → the same three events, USER scope
+ *
+ * `codex.hooks` is the only one with a fourth word, and it is the whole reason
+ * this receipt exists rather than a boolean: Codex requires a person to review
+ * and TRUST a non-managed command hook before it runs (`/hooks` in the CLI),
+ * and records that trust against the hook's current hash. So a Codex machine
+ * can be perfectly installed and still be running nothing. `needs_trust` is
+ * that state, said out loud, and it is what the intern checklist ticket is
+ * for. `unsupported` is the other honest word: a person who set
+ * `[features] hooks = false` has turned the mechanism off, which is a
+ * decision, not a fault.
+ *
+ * **Nothing here is a path.** A home directory names a person; this travels as
+ * six words and a timestamp, exactly like the root labels beside it.
+ */
+import { z } from "zod";
+export declare const MEMORY_INSTALL_RECEIPT_SCHEMA_VERSION = "memory-install-receipt.v1";
+/**
+ * What one piece of the installation is.
+ *
+ *   `ok`      registered, and what is stored is what we would write
+ *   `stale`   something of ours is there, but not what we would write today
+ *             (a hand edit, an older CLI's shape, a bin path that moved)
+ *   `missing` nothing of ours is there
+ *   `unknown` the file could not be read or parsed, so NEITHER of the above is
+ *             claimed — an unreadable config is not an absent one
+ */
+export declare const MemoryInstallPieceSchema: z.ZodEnum<{
+    unknown: "unknown";
+    ok: "ok";
+    stale: "stale";
+    missing: "missing";
+}>;
+export type MemoryInstallPiece = z.infer<typeof MemoryInstallPieceSchema>;
+/**
+ * `codex.hooks` carries two more words than the others.
+ *
+ * `needs_trust` — the hooks file holds our three entries and Codex has not
+ * been told to trust them yet. The hooks are INSTALLED and NOT RUNNING, which
+ * is a state no other piece here has.
+ * `unsupported` — hooks are turned off in this person's `config.toml`
+ * (`[features] hooks = false`, or the deprecated `codex_hooks = false` alias).
+ */
+export declare const MemoryInstallHooksPieceSchema: z.ZodEnum<{
+    unknown: "unknown";
+    ok: "ok";
+    stale: "stale";
+    missing: "missing";
+    needs_trust: "needs_trust";
+    unsupported: "unsupported";
+}>;
+export type MemoryInstallHooksPiece = z.infer<typeof MemoryInstallHooksPieceSchema>;
+export declare const MemoryInstallReceiptSchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<"memory-install-receipt.v1">;
+    checked_at: z.ZodString;
+    claude: z.ZodObject<{
+        mcp: z.ZodEnum<{
+            unknown: "unknown";
+            ok: "ok";
+            stale: "stale";
+            missing: "missing";
+        }>;
+        hooks: z.ZodEnum<{
+            unknown: "unknown";
+            ok: "ok";
+            stale: "stale";
+            missing: "missing";
+        }>;
+    }, z.core.$strict>;
+    codex: z.ZodObject<{
+        mcp: z.ZodEnum<{
+            unknown: "unknown";
+            ok: "ok";
+            stale: "stale";
+            missing: "missing";
+        }>;
+        skill: z.ZodEnum<{
+            unknown: "unknown";
+            ok: "ok";
+            stale: "stale";
+            missing: "missing";
+        }>;
+        hooks: z.ZodEnum<{
+            unknown: "unknown";
+            ok: "ok";
+            stale: "stale";
+            missing: "missing";
+            needs_trust: "needs_trust";
+            unsupported: "unsupported";
+        }>;
+    }, z.core.$strict>;
+    reasons: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    bin_found: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type MemoryInstallReceipt = z.infer<typeof MemoryInstallReceiptSchema>;
+/** Every piece is `ok`. The one question the board asks first. */
+export declare function memoryInstallFullyOn(receipt: MemoryInstallReceipt): boolean;
+/**
+ * The pieces that are NOT `ok`, as `host.piece=word` labels, in a fixed order
+ * so two machines' receipts read the same way. Empty when everything is on.
+ */
+export declare function memoryInstallGaps(receipt: MemoryInstallReceipt): string[];

package/dist/memory-install-receipt.js

@@ -0,0 +1,133 @@
+/**
+ * THE MEMORY RECEIPT (BLI-3729) — is BLI Memory actually switched on, on this
+ * laptop, for both agent hosts?
+ *
+ * `cockpit memory install` already converged the two host configurations and
+ * already wrote a per-target `memory_install` install event. What nobody could
+ * answer was the fleet-wide question: "does Savina's machine have memory hooks
+ * at all?" The install event is a per-run receipt in an outbox; this is the
+ * per-MACHINE state, recomputed every sync tick by READING THE FILES BACK and
+ * carried on the heartbeat, so the ops board can name the machine that is
+ * missing a piece instead of somebody grepping logs.
+ *
+ * Six words, one per thing that can independently be absent:
+ *
+ *   claude.mcp      `~/.claude.json`            → the `bli-memory` MCP server
+ *   claude.hooks    `~/.claude/settings.json`   → SessionStart/UserPromptSubmit/Stop
+ *   codex.mcp       `~/.codex/config.toml`      → `[mcp_servers.bli-memory]`
+ *   codex.skill     `~/.codex/skills/bli-memory/` → the skill files
+ *   codex.hooks     `~/.codex/hooks.json`       → the same three events, USER scope
+ *
+ * `codex.hooks` is the only one with a fourth word, and it is the whole reason
+ * this receipt exists rather than a boolean: Codex requires a person to review
+ * and TRUST a non-managed command hook before it runs (`/hooks` in the CLI),
+ * and records that trust against the hook's current hash. So a Codex machine
+ * can be perfectly installed and still be running nothing. `needs_trust` is
+ * that state, said out loud, and it is what the intern checklist ticket is
+ * for. `unsupported` is the other honest word: a person who set
+ * `[features] hooks = false` has turned the mechanism off, which is a
+ * decision, not a fault.
+ *
+ * **Nothing here is a path.** A home directory names a person; this travels as
+ * six words and a timestamp, exactly like the root labels beside it.
+ */
+import { z } from "zod";
+import { IsoDateTimeSchema } from "./common.js";
+export const MEMORY_INSTALL_RECEIPT_SCHEMA_VERSION = "memory-install-receipt.v1";
+/**
+ * What one piece of the installation is.
+ *
+ *   `ok`      registered, and what is stored is what we would write
+ *   `stale`   something of ours is there, but not what we would write today
+ *             (a hand edit, an older CLI's shape, a bin path that moved)
+ *   `missing` nothing of ours is there
+ *   `unknown` the file could not be read or parsed, so NEITHER of the above is
+ *             claimed — an unreadable config is not an absent one
+ */
+export const MemoryInstallPieceSchema = z.enum(["ok", "stale", "missing", "unknown"]);
+/**
+ * `codex.hooks` carries two more words than the others.
+ *
+ * `needs_trust` — the hooks file holds our three entries and Codex has not
+ * been told to trust them yet. The hooks are INSTALLED and NOT RUNNING, which
+ * is a state no other piece here has.
+ * `unsupported` — hooks are turned off in this person's `config.toml`
+ * (`[features] hooks = false`, or the deprecated `codex_hooks = false` alias).
+ */
+export const MemoryInstallHooksPieceSchema = z.enum([
+    "ok",
+    "needs_trust",
+    "stale",
+    "missing",
+    "unknown",
+    "unsupported",
+]);
+/**
+ * A closed reason label per piece, for the operator who asks "why `stale`?".
+ * Bounded and charset-restricted for the same reason `last_sync_reason` is:
+ * nothing content-bearing may ride in on it.
+ */
+const ReasonLabelSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .max(60)
+    .regex(/^[a-z0-9_:.-]+$/iu);
+export const MemoryInstallReceiptSchema = z
+    .object({
+    schema_version: z.literal(MEMORY_INSTALL_RECEIPT_SCHEMA_VERSION),
+    checked_at: IsoDateTimeSchema,
+    claude: z
+        .object({
+        mcp: MemoryInstallPieceSchema,
+        hooks: MemoryInstallPieceSchema,
+    })
+        .strict(),
+    codex: z
+        .object({
+        mcp: MemoryInstallPieceSchema,
+        skill: MemoryInstallPieceSchema,
+        hooks: MemoryInstallHooksPieceSchema,
+    })
+        .strict(),
+    /**
+     * One label per piece, keyed by the same names. Optional so an older
+     * collector that only computes the words still validates.
+     */
+    reasons: z.record(z.string().max(24), ReasonLabelSchema).optional(),
+    /**
+     * Whether `bli-memory-mcp` resolved on this machine at all. A machine
+     * where every piece is `missing` because the SERVER is not installed yet
+     * is a different machine from one whose configs were wiped, and the
+     * install path deliberately writes nothing in the first case
+     * (`no_bin_no_write`).
+     */
+    bin_found: z.boolean().optional(),
+})
+    .strict();
+/** Every piece is `ok`. The one question the board asks first. */
+export function memoryInstallFullyOn(receipt) {
+    return (receipt.claude.mcp === "ok" &&
+        receipt.claude.hooks === "ok" &&
+        receipt.codex.mcp === "ok" &&
+        receipt.codex.skill === "ok" &&
+        receipt.codex.hooks === "ok");
+}
+/**
+ * The pieces that are NOT `ok`, as `host.piece=word` labels, in a fixed order
+ * so two machines' receipts read the same way. Empty when everything is on.
+ */
+export function memoryInstallGaps(receipt) {
+    const gaps = [];
+    if (receipt.claude.mcp !== "ok")
+        gaps.push(`claude.mcp=${receipt.claude.mcp}`);
+    if (receipt.claude.hooks !== "ok")
+        gaps.push(`claude.hooks=${receipt.claude.hooks}`);
+    if (receipt.codex.mcp !== "ok")
+        gaps.push(`codex.mcp=${receipt.codex.mcp}`);
+    if (receipt.codex.skill !== "ok")
+        gaps.push(`codex.skill=${receipt.codex.skill}`);
+    if (receipt.codex.hooks !== "ok")
+        gaps.push(`codex.hooks=${receipt.codex.hooks}`);
+    return gaps;
+}

package/dist/setup-receipt.d.ts

@@ -0,0 +1,146 @@
+import { z } from "zod";
+import type { MemoryInstallReceipt } from "./memory-install-receipt.js";
+/**
+ * "Is this machine actually connected?" — one block, read back off the machine
+ * (BLI-3731).
+ *
+ * Installing was never the hard part. What nobody could answer was whether
+ * Savina's laptop has Codex hooks trusted, or whether Viet's autostart survived
+ * a reinstall. This is that answer, in seven words, computed where the truth
+ * is and carried to wherever a person reads it: the terminal
+ * (`cockpit status`, `cockpit doctor`), the heartbeat, the ops board and
+ * JARVIS's `readFleet`.
+ *
+ *   browser ✓ · device ✓ · claude mcp ✓ hooks ✓ · codex mcp ✓ skill ✓
+ *   hooks needs_trust · collector autostart ✓
+ *
+ * **The five middle words are BLI-3729's, not ours.** `MemoryInstallReceipt`
+ * already owns both agent hosts, it is already computed by reading the host
+ * configs back, and it already rides the heartbeat under `memory_install`.
+ * This schema carries only the three pieces that ticket had no way to see —
+ * whether a browser sign-in ever happened, whether the device session is still
+ * good, and whether the scheduler is registered — and the renderers below JOIN
+ * the two. One fact stored twice on one row is one fact that can disagree
+ * with itself.
+ *
+ * **Every word is a READ-BACK, never a memory of what we wrote** (BLI-2541:
+ * `cockpit autostart` validated a correct Windows task against the strings
+ * Cockpit had sent and rejected it on every machine for months). A piece this
+ * run did not actually inspect is `unknown`, never `missing` — "we did not
+ * look" and "it is not there" are different facts and only one of them is
+ * somebody's problem.
+ *
+ * **Metadata only.** Three words, three reason labels, one timestamp. No path
+ * — a home directory names a person — no token, no email.
+ */
+export declare const SETUP_RECEIPT_SCHEMA_VERSION = "setup-receipt.v1";
+/**
+ * What one piece of the setup can be. Deliberately small and closed: a word a
+ * person can read at a glance. The vocabulary is a superset of
+ * `MemoryInstallPiece`'s, so one renderer can print both halves.
+ */
+export declare const SetupPieceStatusSchema: z.ZodEnum<{
+    unknown: "unknown";
+    failed: "failed";
+    skipped: "skipped";
+    ok: "ok";
+    stale: "stale";
+    missing: "missing";
+    needs_trust: "needs_trust";
+    unsupported: "unsupported";
+}>;
+export type SetupPieceStatus = z.infer<typeof SetupPieceStatusSchema>;
+declare const PieceSchema: z.ZodObject<{
+    status: z.ZodEnum<{
+        unknown: "unknown";
+        failed: "failed";
+        skipped: "skipped";
+        ok: "ok";
+        stale: "stale";
+        missing: "missing";
+        needs_trust: "needs_trust";
+        unsupported: "unsupported";
+    }>;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type SetupPiece = z.infer<typeof PieceSchema>;
+export declare const SetupReceiptSchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<"setup-receipt.v1">;
+    checked_at: z.ZodString;
+    browser: z.ZodObject<{
+        status: z.ZodEnum<{
+            unknown: "unknown";
+            failed: "failed";
+            skipped: "skipped";
+            ok: "ok";
+            stale: "stale";
+            missing: "missing";
+            needs_trust: "needs_trust";
+            unsupported: "unsupported";
+        }>;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    device: z.ZodObject<{
+        status: z.ZodEnum<{
+            unknown: "unknown";
+            failed: "failed";
+            skipped: "skipped";
+            ok: "ok";
+            stale: "stale";
+            missing: "missing";
+            needs_trust: "needs_trust";
+            unsupported: "unsupported";
+        }>;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    collector: z.ZodObject<{
+        autostart: z.ZodObject<{
+            status: z.ZodEnum<{
+                unknown: "unknown";
+                failed: "failed";
+                skipped: "skipped";
+                ok: "ok";
+                stale: "stale";
+                missing: "missing";
+                needs_trust: "needs_trust";
+                unsupported: "unsupported";
+            }>;
+            reason: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type SetupReceipt = z.infer<typeof SetupReceiptSchema>;
+export interface SetupReceiptPiece {
+    key: string;
+    label: string;
+    piece: SetupPiece;
+}
+/**
+ * Every piece in the order the one-line block prints them, with BLI-3729's
+ * five memory words spliced into the middle when there is a memory receipt to
+ * splice. Without one, the memory keys are still LISTED, as `unknown` — a
+ * machine whose memory state nobody knows must not read as a machine with no
+ * memory pieces at all.
+ */
+export declare function setupReceiptPieces(receipt: SetupReceipt, memory?: MemoryInstallReceipt | null): SetupReceiptPiece[];
+/**
+ * The keys of every piece that is not `ok` — what a manager wants named, and
+ * what `readFleet` says out loud ("Savina's machine has no Codex hooks
+ * trusted"). `unknown` counts as a gap on purpose: a machine nobody can read
+ * is not a machine anybody should call fine.
+ */
+export declare function setupReceiptGaps(receipt: SetupReceipt, memory?: MemoryInstallReceipt | null): string[];
+/**
+ * The one line, exactly as a terminal prints it and as the ops board renders
+ * it. Written here, in the shared package, so the CLI and the dashboard cannot
+ * word the same machine's state two different ways.
+ *
+ * Five groups, dot-separated, in the order somebody debugs them: the two
+ * sign-ins first, then each agent host, then the scheduler. The grouping is
+ * the whole readability of the line — `hooks` reads as Claude's or Codex's
+ * only because of which side of a dot it sits on.
+ */
+export declare function setupReceiptLine(receipt: SetupReceipt, memory?: MemoryInstallReceipt | null): string;
+/** `ok` is a tick, a broken piece is a cross, and everything else says its own word. */
+export declare function setupPieceMark(status: SetupPieceStatus): string;
+export {};

package/dist/setup-receipt.js

@@ -0,0 +1,197 @@
+import { z } from "zod";
+import { IsoDateTimeSchema } from "./common.js";
+/**
+ * "Is this machine actually connected?" — one block, read back off the machine
+ * (BLI-3731).
+ *
+ * Installing was never the hard part. What nobody could answer was whether
+ * Savina's laptop has Codex hooks trusted, or whether Viet's autostart survived
+ * a reinstall. This is that answer, in seven words, computed where the truth
+ * is and carried to wherever a person reads it: the terminal
+ * (`cockpit status`, `cockpit doctor`), the heartbeat, the ops board and
+ * JARVIS's `readFleet`.
+ *
+ *   browser ✓ · device ✓ · claude mcp ✓ hooks ✓ · codex mcp ✓ skill ✓
+ *   hooks needs_trust · collector autostart ✓
+ *
+ * **The five middle words are BLI-3729's, not ours.** `MemoryInstallReceipt`
+ * already owns both agent hosts, it is already computed by reading the host
+ * configs back, and it already rides the heartbeat under `memory_install`.
+ * This schema carries only the three pieces that ticket had no way to see —
+ * whether a browser sign-in ever happened, whether the device session is still
+ * good, and whether the scheduler is registered — and the renderers below JOIN
+ * the two. One fact stored twice on one row is one fact that can disagree
+ * with itself.
+ *
+ * **Every word is a READ-BACK, never a memory of what we wrote** (BLI-2541:
+ * `cockpit autostart` validated a correct Windows task against the strings
+ * Cockpit had sent and rejected it on every machine for months). A piece this
+ * run did not actually inspect is `unknown`, never `missing` — "we did not
+ * look" and "it is not there" are different facts and only one of them is
+ * somebody's problem.
+ *
+ * **Metadata only.** Three words, three reason labels, one timestamp. No path
+ * — a home directory names a person — no token, no email.
+ */
+export const SETUP_RECEIPT_SCHEMA_VERSION = "setup-receipt.v1";
+/**
+ * What one piece of the setup can be. Deliberately small and closed: a word a
+ * person can read at a glance. The vocabulary is a superset of
+ * `MemoryInstallPiece`'s, so one renderer can print both halves.
+ */
+export const SetupPieceStatusSchema = z.enum([
+    /** Read back, correct. */
+    "ok",
+    /** Read back, nothing of ours is there. */
+    "missing",
+    /** Read back, something of ours is there but not what we would write. */
+    "stale",
+    /**
+     * Installed correctly and waiting on ONE human action. Today only Codex
+     * hooks, which the host requires a person to trust once per machine. It is
+     * its own word rather than `missing` because nothing is broken and no
+     * command fixes it.
+     */
+    "needs_trust",
+    /** The mechanism is switched off by a person's own choice. */
+    "unsupported",
+    /** Deliberately not done, and no file was touched. Carries its reason. */
+    "skipped",
+    /** Tried, and did not work. Carries its reason. */
+    "failed",
+    /**
+     * This run did not look. NEVER a substitute for `missing`: a collector too
+     * old to compute a piece, a dry run, and a probe that could not run all land
+     * here, and every one of them means "ask again", not "fix it".
+     */
+    "unknown",
+]);
+const PieceSchema = z
+    .object({
+    status: SetupPieceStatusSchema,
+    /**
+     * A reason label, never prose: `never_signed_in`, `session_expired`,
+     * `autostart_not_loaded`. Bounded and charset-restricted so nothing
+     * content-bearing can ride in on it.
+     */
+    reason: z
+        .string()
+        .trim()
+        .min(1)
+        .max(120)
+        .regex(/^[a-z0-9_:.-]+$/iu)
+        .optional(),
+})
+    .strict();
+export const SetupReceiptSchema = z
+    .object({
+    schema_version: z.literal(SETUP_RECEIPT_SCHEMA_VERSION),
+    /** When these words were read off this machine. Ages out; never trusted stale. */
+    checked_at: IsoDateTimeSchema,
+    /** Did a person ever sign a browser in for this machine? */
+    browser: PieceSchema,
+    /** Is the device session on disk still one the dashboard would honour? */
+    device: PieceSchema,
+    /** The 15-minute scheduler: launchd on macOS, Task Scheduler on Windows. */
+    collector: z.object({ autostart: PieceSchema }).strict(),
+})
+    .strict();
+/**
+ * Every piece in the order the one-line block prints them, with BLI-3729's
+ * five memory words spliced into the middle when there is a memory receipt to
+ * splice. Without one, the memory keys are still LISTED, as `unknown` — a
+ * machine whose memory state nobody knows must not read as a machine with no
+ * memory pieces at all.
+ */
+export function setupReceiptPieces(receipt, memory) {
+    const memoryPiece = (word, key) => {
+        if (!word)
+            return { status: "unknown", reason: "memory_receipt_absent" };
+        const reason = memory?.reasons?.[key];
+        return {
+            status: word,
+            ...(word !== "ok" && reason ? { reason } : {}),
+        };
+    };
+    return [
+        { key: "browser", label: "browser", piece: receipt.browser },
+        { key: "device", label: "device", piece: receipt.device },
+        {
+            key: "claude.mcp",
+            label: "claude mcp",
+            piece: memoryPiece(memory?.claude.mcp, "claude.mcp"),
+        },
+        {
+            key: "claude.hooks",
+            label: "hooks",
+            piece: memoryPiece(memory?.claude.hooks, "claude.hooks"),
+        },
+        {
+            key: "codex.mcp",
+            label: "codex mcp",
+            piece: memoryPiece(memory?.codex.mcp, "codex.mcp"),
+        },
+        {
+            key: "codex.skill",
+            label: "skill",
+            piece: memoryPiece(memory?.codex.skill, "codex.skill"),
+        },
+        {
+            key: "codex.hooks",
+            label: "hooks",
+            piece: memoryPiece(memory?.codex.hooks, "codex.hooks"),
+        },
+        {
+            key: "collector.autostart",
+            label: "collector autostart",
+            piece: receipt.collector.autostart,
+        },
+    ];
+}
+/**
+ * The keys of every piece that is not `ok` — what a manager wants named, and
+ * what `readFleet` says out loud ("Savina's machine has no Codex hooks
+ * trusted"). `unknown` counts as a gap on purpose: a machine nobody can read
+ * is not a machine anybody should call fine.
+ */
+export function setupReceiptGaps(receipt, memory) {
+    return setupReceiptPieces(receipt, memory)
+        .filter(({ piece }) => piece.status !== "ok")
+        .map(({ key }) => key);
+}
+/**
+ * The one line, exactly as a terminal prints it and as the ops board renders
+ * it. Written here, in the shared package, so the CLI and the dashboard cannot
+ * word the same machine's state two different ways.
+ *
+ * Five groups, dot-separated, in the order somebody debugs them: the two
+ * sign-ins first, then each agent host, then the scheduler. The grouping is
+ * the whole readability of the line — `hooks` reads as Claude's or Codex's
+ * only because of which side of a dot it sits on.
+ */
+export function setupReceiptLine(receipt, memory) {
+    const groups = new Map([
+        ["browser", []],
+        ["device", []],
+        ["claude", []],
+        ["codex", []],
+        ["collector", []],
+    ]);
+    for (const { key, label, piece } of setupReceiptPieces(receipt, memory)) {
+        const group = key.includes(".") ? key.split(".")[0] : key;
+        groups.get(group)?.push(`${label} ${setupPieceMark(piece.status)}`);
+    }
+    return [...groups.values()]
+        .filter((group) => group.length > 0)
+        .map((group) => group.join(" "))
+        .join(" · ");
+}
+/** `ok` is a tick, a broken piece is a cross, and everything else says its own word. */
+export function setupPieceMark(status) {
+    if (status === "ok")
+        return "✓";
+    if (status === "missing" || status === "failed" || status === "stale") {
+        return "✗";
+    }
+    return status;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/telemetry-core",
-  "version": "0.1.27",
+  "version": "0.1.29",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",