@bli-cockpit/cli 0.2.286 → 0.2.287

package/dist/live-founder-memo.js

@@ -0,0 +1,57 @@
+/**
+ * BLI-22640: what Tower said about this machine's person, remembered INSIDE
+ * THIS PROCESS ONLY, so one sync tick (which decides in a dozen places) asks
+ * Tower once and not a dozen times. Nothing here touches the disk: a new
+ * process always asks again, so no file a person can edit is ever a source.
+ *
+ * Definite answers live one minute (the window Tower's own lock caches its
+ * owners list for). A "could not ask" lives ten seconds: long enough that a
+ * tick whose Tower is down holds everywhere without ten timeouts in a row,
+ * short enough that a Tower that comes back is asked again.
+ *
+ * Keyed by state directory, so two homes in one test process never share.
+ * No network and no Tower client in here: the light readers
+ * (`source-opt-out.ts`, `memory-capture-choice.ts`) import it for free.
+ *
+ * A new sibling must also join `scripts/build-public-cli.mjs` `runtimeFiles`.
+ */
+const ANSWER_MS = 60_000;
+const COULD_NOT_ASK_MS = 10_000;
+const memo = new Map();
+export function rememberLiveFounderAnswer(stateDir, answer, now = Date.now()) {
+    memo.set(stateDir, { answer, at: now });
+}
+/** The answer this process got from Tower recently, or null when it must ask. */
+export function recallLiveFounderAnswer(stateDir, now = Date.now()) {
+    const known = memo.get(stateDir);
+    if (!known)
+        return null;
+    const window = known.answer.standing === "unknown" ? COULD_NOT_ASK_MS : ANSWER_MS;
+    if (now - known.at >= window) {
+        memo.delete(stateDir);
+        return null;
+    }
+    return known.answer;
+}
+/** Tests only. */
+export function forgetLiveFounderAnswers() {
+    memo.clear();
+}
+/**
+ * What every decider asks: Tower's word on this machine's person, from this
+ * process's last minute or a fresh ask. Never the saved file. `unknown` means
+ * Tower could not say, and the caller holds. The Tower client loads only on a
+ * miss, so a machine with no opt-out (it never calls this) and a tick that has
+ * already asked pay nothing.
+ */
+export async function liveStandingForDecision(paths, ask = {}) {
+    const known = recallLiveFounderAnswer(paths.state_dir);
+    if (known)
+        return known;
+    const { liveFounderStanding } = await import("./founder-standing.js");
+    return liveFounderStanding({
+        homeDir: paths.home_dir,
+        ...(ask.fetch ? { fetch: ask.fetch } : {}),
+        ...(ask.dashboardUrl ? { dashboardUrl: ask.dashboardUrl } : {}),
+    });
+}

package/dist/local-state-config.js

@@ -5,7 +5,7 @@ import { readFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { normalizeCollectionRoots } from "./root-normalization.js";
-import { configForDisk, resolveSourceSwitches } from "./source-opt-out.js";
+import { configForDisk, configOptOutLabels } from "./source-opt-out.js";
 import { ensureRuntimeDirectories, getCollectorRuntimePaths, } from "./local-state-paths.js";
 import { isMissingFileError, readJsonFile, writeJsonFile, } from "./local-state-files.js";
 const localCollectorPackage = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
@@ -68,17 +68,23 @@ export async function installLocalCollector(options = {}) {
         collect_claude_jsonl: existingConfig?.collect_claude_jsonl,
         // Same for Codex, and for `raw_evidence_upload: "disabled"` below (ticket 22557).
         collect_codex_jsonl: existingConfig?.collect_codex_jsonl,
+        // BLI-23590: a local `roots_only` request survives every rewrite too; whether it counts is Tower's call.
+        collection_scope: existingConfig?.collection_scope,
+        // BLI-23478 (three shelves): a founder's shelf choices survive every rewrite exactly as the opt-outs above
+        // do. Optional with no default, so they reach disk only when someone set them.
+        shelf_default: existingConfig?.shelf_default,
+        shelf_metrics_allow: existingConfig?.shelf_metrics_allow,
         session_file_path: paths.session_file,
         state_dir_path: paths.state_dir,
     });
     await recordRootApprovals(paths, defaultRepoPaths, options.replaceRepoRoots);
     await writeJsonFile(paths.config_file, configForDisk(config));
-    const switches = resolveSourceSwitches(config);
-    if (!switches.claude) {
-        console.error("[install] claude session upload stays off", JSON.stringify({ reason: switches.claudeReason }));
-    }
-    if (!switches.codex) {
-        console.error("[install] codex session upload stays off", JSON.stringify({ reason: switches.codexReason }));
+    // Install decides nothing about what leaves the machine, so it asks Tower
+    // nothing: it names the opt-outs the config carries, and every run that
+    // collects asks Tower live whether they are obeyed (BLI-22640).
+    const carried = configOptOutLabels(config);
+    if (carried.length > 0) {
+        console.error("[install] config carries session-upload opt-outs; each run decides on Tower's live answer whether they hold", JSON.stringify({ reason: "opt_out_carried", labels: carried }));
     }
     return {
         config,

package/dist/memory-capture-choice.js

@@ -0,0 +1,73 @@
+import { optOutVerdict, MEMORY_CAPTURE_CHOICE_FILE_NAME, parseMemoryCaptureChoice, renderMemoryCaptureChoice, } from "@bli-cockpit/telemetry-core";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { liveStandingForDecision } from "./live-founder-memo.js";
+/**
+ * BLI-22640. This machine's BLI Memory choice: the collector's half of
+ * `memory-capture-contract.ts` (telemetry-core), which says why it is a file
+ * in the state directory and not a key in `config.json`.
+ *
+ * Only a person's own act writes it: `cockpit memory on|off|install|uninstall`,
+ * `cockpit doctor --no-memory`, or their answer to the one-time question in an
+ * interactive `doctor` / `onboard`. The unattended paths (the sync tick,
+ * doctor's repairs, onboard's closing install) only READ it.
+ *
+ * A new sibling must also join `scripts/build-public-cli.mjs` `runtimeFiles`.
+ */
+export const MEMORY_CAPTURE_CHOICE_FILE = MEMORY_CAPTURE_CHOICE_FILE_NAME;
+function choicePath(paths) {
+    return path.join(paths.state_dir, MEMORY_CAPTURE_CHOICE_FILE);
+}
+export async function readMemoryCaptureChoice(paths) {
+    let raw;
+    try {
+        raw = await fs.readFile(choicePath(paths), "utf8");
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return { state: "unchosen" };
+        // A file we cannot read is somebody's choice we cannot see: off, named.
+        console.error("[memory-capture] choice file unreadable; treating BLI Memory as off", JSON.stringify({ reason: "choice_unreadable", error_code: code ?? "unknown" }));
+        return { state: "off", choice: null, reason: "choice_unreadable" };
+    }
+    const reading = parseMemoryCaptureChoice(raw);
+    if (reading.state === "off" && reading.reason === "choice_unreadable") {
+        console.error("[memory-capture] choice file does not parse; treating BLI Memory as off", JSON.stringify({ reason: "choice_unreadable", byte_size: raw.length }));
+    }
+    return reading;
+}
+export async function readEffectiveMemoryCapture(paths, ask = {}) {
+    const reading = await readMemoryCaptureChoice(paths);
+    if (reading.state !== "off") {
+        return { reading, off: false, ignored: false, held: false, standing: "unknown", verdict: null };
+    }
+    const answer = await liveStandingForDecision(paths, ask);
+    const verdict = optOutVerdict(answer.standing);
+    if (!verdict.obeyed) {
+        console.error("[memory-capture] off ignored; only a founder's off is obeyed", JSON.stringify({ reason: verdict.reason, file_reason: reading.reason, via: reading.choice?.via ?? null }));
+    }
+    else if (verdict.held) {
+        console.error("[memory-capture] off held; Tower could not say whether this person is a founder, so BLI Memory sends nothing this run", JSON.stringify({ reason: verdict.reason, detail: answer.standing === "unknown" ? answer.reason : null, via: reading.choice?.via ?? null }));
+    }
+    return { reading, off: verdict.obeyed, ignored: !verdict.obeyed, held: verdict.held, standing: answer.standing, verdict: verdict.reason };
+}
+export async function isMemoryCaptureOff(paths, ask = {}) {
+    return (await readEffectiveMemoryCapture(paths, ask)).off;
+}
+/**
+ * Records the person's choice. Throws when it cannot be written: a caller that
+ * told a person "BLI Memory is off" over a file that did not land would be
+ * lying about the one thing this switch exists for.
+ */
+export async function writeMemoryCaptureChoice(paths, memoryCapture, via, now = new Date()) {
+    await fs.mkdir(paths.state_dir, { recursive: true, mode: 0o700 });
+    await fs.writeFile(choicePath(paths), renderMemoryCaptureChoice({ memory_capture: memoryCapture, chosen_at: now.toISOString(), via }), { encoding: "utf8", mode: 0o600 });
+    const stored = parseMemoryCaptureChoice(await fs.readFile(choicePath(paths), "utf8"));
+    const expected = memoryCapture ? "on" : "off";
+    if (stored.state !== expected) {
+        console.error("[memory-capture] choice did not read back", JSON.stringify({ reason: "read_back_mismatch", expected, stored: stored.state }));
+        throw new Error("memory_capture_read_back_mismatch");
+    }
+    console.error("[memory-capture] choice recorded", JSON.stringify({ reason: memoryCapture ? "memory_on" : "explicit_opt_out", via }));
+}

package/dist/root-work.js

@@ -1,6 +1,8 @@
 /** Local directory evidence and explicit root approvals. Full paths stay here. */
+import { realpathSync } from "node:fs";
 import path from "node:path";
 import { z } from "zod";
+import { ROOT_APPROVALS_FILENAME } from "@bli-cockpit/telemetry-core";
 import { readJsonFile, writeJsonFile, isMissingFileError } from "./local-state-files.js";
 import { containsPath, normalizeCollectionRoots } from "./root-normalization.js";
 const DirectorySchema = z.object({ directory: z.string(), count: z.number().int().nonnegative() });
@@ -69,22 +71,68 @@ export async function readRootWorkScan(paths) {
         throw error;
     }
 }
-const ApprovalsSchema = z.object({ approved_at: z.string(), roots: z.array(z.string()) });
-export async function readRootApprovals(paths) {
+// BLI-23478 (three shelves): `labels` maps a folder to the shelf its sessions and memories go to. Read by the shared
+// resolver (`@bli-cockpit/memory-mcp` `shelf-routing.ts`); an older CLI's parse strips the key it does not know.
+const ApprovalsSchema = z.object({
+    approved_at: z.string(),
+    roots: z.array(z.string()),
+    // Any string is kept as read (a hand-edited `safe` must not break the approvals); the resolver treats a value
+    // other than `team` or `drawer` as the drawer.
+    labels: z.record(z.string(), z.string()).default({}),
+});
+const approvalsFile = (paths) => path.join(paths.config_dir, ROOT_APPROVALS_FILENAME);
+async function readApprovalsFile(paths) {
     try {
-        return ApprovalsSchema.parse(await readJsonFile(path.join(paths.config_dir, "root-approvals.json"))).roots;
+        return ApprovalsSchema.parse(await readJsonFile(approvalsFile(paths)));
     }
     catch (error) {
         if (isMissingFileError(error))
-            return [];
+            return null;
         throw error;
     }
 }
+export async function readRootApprovals(paths) {
+    return (await readApprovalsFile(paths))?.roots ?? [];
+}
+/** BLI-23478: the folder labels on this laptop. Full paths; they never leave the machine. */
+export async function readRootLabels(paths) {
+    return (await readApprovalsFile(paths))?.labels ?? {};
+}
 export async function recordRootApprovals(paths, roots, replace = false) {
-    const previous = replace ? [] : await readRootApprovals(paths);
+    const existing = await readApprovalsFile(paths);
+    const previous = replace ? [] : existing?.roots ?? [];
     const approved = normalizeCollectionRoots([...previous, ...roots]);
-    await writeJsonFile(path.join(paths.config_dir, "root-approvals.json"), { approved_at: new Date().toISOString(), roots: approved });
-    console.error("[roots] approval recorded", JSON.stringify({ roots: approved.length, replaced: replace }));
+    // Labels survive every rewrite of the approvals, including a replace: only `cockpit roots label` changes them.
+    const labels = existing?.labels ?? {};
+    await writeJsonFile(approvalsFile(paths), {
+        approved_at: new Date().toISOString(),
+        roots: approved,
+        ...(Object.keys(labels).length > 0 ? { labels } : {}),
+    });
+    console.error("[roots] approval recorded", JSON.stringify({ roots: approved.length, replaced: replace, labels: Object.keys(labels).length }));
+}
+/**
+ * BLI-23478: label one folder `team` or `drawer`. The folder is stored normalized (the same spelling the approvals
+ * use) so the resolver compares like with like on both platforms. Returns the label count after the write.
+ */
+export async function recordRootLabel(paths, root, label) {
+    const existing = await readApprovalsFile(paths);
+    if (!root.trim())
+        throw new Error("Choose a folder to label.");
+    // The case the filesystem stores (case-insensitive APFS keeps whatever was typed otherwise).
+    let normalized = path.resolve(root);
+    try {
+        normalized = realpathSync.native(normalized);
+    }
+    catch { /* not on disk: keep the typed spelling */ }
+    const labels = { ...(existing?.labels ?? {}), [normalized]: label };
+    await writeJsonFile(approvalsFile(paths), {
+        approved_at: existing?.approved_at ?? new Date().toISOString(),
+        roots: existing?.roots ?? [],
+        labels,
+    });
+    console.error("[roots] label recorded", JSON.stringify({ reason: "root_label_recorded", shelf: label, labels: Object.keys(labels).length }));
+    return Object.keys(labels).length;
 }
 export function rootsAddCommand(directory, platform = process.platform, homeDir) {
     // Native Windows command is for PowerShell; POSIX quoting is for zsh/bash.

package/dist/shelf-decision.js

@@ -0,0 +1,52 @@
+/**
+ * The collector's one shelf decision per run (BLI-23478, Jeetesh's review of PR 2819).
+ *
+ * "Is this laptop's person a founder?" is Tower's LIVE answer (`@bli-cockpit/memory-mcp` `founder-check.ts`),
+ * never the saved heartbeat file a teammate could edit. Four outcomes:
+ *
+ *   - `inactive`     no labels and no `shelf_default` on this laptop (every teammate's): nothing is asked, nothing
+ *                    changes, no extra request on the sync path.
+ *   - `founder`      Tower says founder: the labels apply.
+ *   - `not_founder`  Tower says not a founder: the labels are IGNORED, the laptop collects exactly as a teammate's
+ *                    does (`shelf_labels_ignored_not_owner`).
+ *   - `hold`         Tower could not be asked: the run sends nothing and keeps nothing in the drawer, and the next
+ *                    run asks again (`owner_check_unavailable`).
+ *
+ * Logs: labels only (`safeLog`).
+ */
+import { safeLog } from "@bli-cockpit/telemetry-core";
+import { askTowerFounder, OWNER_CHECK_UNAVAILABLE } from "@bli-cockpit/memory-mcp/dist/founder-check.js";
+import { loadShelfRules } from "@bli-cockpit/memory-mcp/dist/shelf-routing.js";
+import { getCollectorRuntimePaths, readLocalCollectorConfig, readLocalCollectorSessionFile } from "./local-state.js";
+export { OWNER_CHECK_UNAVAILABLE };
+/**
+ * Tower's live answer alone, for the verbs that act on the founder question whatever the labels say (`cockpit roots
+ * label … drawer`, `cockpit shelf default drawer`, the doctor row, the usage-telemetry opt-out, the memory verbs).
+ */
+export async function askFounderLive(options) {
+    const paths = getCollectorRuntimePaths(options.homeDir);
+    const [session, config] = await Promise.all([
+        readLocalCollectorSessionFile(paths).catch(() => null),
+        options.dashboardUrl ? Promise.resolve(null) : readLocalCollectorConfig(paths).catch(() => null),
+    ]);
+    return askTowerFounder({
+        dashboardUrl: options.dashboardUrl ?? session?.dashboard_url ?? config?.dashboard_url ?? null,
+        deviceToken: session?.device_token ?? null,
+        fetchImpl: options.fetchImpl,
+        caller: "collector",
+    });
+}
+export async function decideShelfMode(options) {
+    const rules = options.rules ?? loadShelfRules(options.homeDir ? { homeDir: options.homeDir } : {});
+    if (!rules.active)
+        return { mode: "inactive", rules, reason: "routing_inactive" };
+    const answer = await askFounderLive(options);
+    if (answer.standing === "founder")
+        return { mode: "founder", rules, reason: answer.reason };
+    if (answer.standing === "not_founder") {
+        safeLog("shelf", "shelf_labels_ignored_not_owner", {});
+        return { mode: "not_founder", rules, reason: "shelf_labels_ignored_not_owner" };
+    }
+    safeLog("shelf", "shelf_held", { detail: answer.reason });
+    return { mode: "hold", rules, reason: OWNER_CHECK_UNAVAILABLE };
+}

package/dist/shelf-headers.js

@@ -0,0 +1,15 @@
+/**
+ * BLI-23478 (three shelves, design 9.1 item 11): the three headers on every device-token request the collector
+ * makes. The collector only ever sends team-shelf content (a drawer session never leaves the laptop; its bare
+ * numbers are team-shelf data), so the set is constant: `x-tower-shelf: team`, `x-tower-caller: collector` and this
+ * CLI's release. On a teammate's laptop Tower ignores them; on a founder's, Tower's lock requires them once founder
+ * routing is on, and refuses any request from an older CLI that does not send them.
+ *
+ * `LOCAL_COLLECTOR_VERSION` is the `@bli-cockpit/cli` release in the published CLI: its `dist/` reads the CLI
+ * package's own manifest (`local-state-config.ts`).
+ */
+import { shelfRequestHeaders } from "@bli-cockpit/telemetry-core";
+import { LOCAL_COLLECTOR_VERSION } from "./local-state-config.js";
+export function collectorShelfHeaders() {
+    return shelfRequestHeaders({ caller: "collector", cliVersion: LOCAL_COLLECTOR_VERSION });
+}

package/dist/shelf-reports.js

@@ -0,0 +1,167 @@
+/**
+ * The numbers-only bare record for every drawer session (BLI-23478, three-shelves design 3.2 and 9.1 item 10).
+ *
+ * A drawer session's words never leave the laptop. What Tower gets instead is one strict `shelf.v1` record per
+ * session, under a random `report_id`: how long, how many turns, how many tokens, how big. No session id, folder,
+ * branch, commit, tool or model (the last two only if the founder allowed them with `cockpit shelf metrics`).
+ *
+ * Two rules keep the sums honest:
+ *
+ *   - **One record per session, once it has settled.** A session is reported after its transcript has been quiet
+ *     for {@link SHELF_REPORT_SETTLE_MS}; Tower's insert ignores a repeated `report_id`, so a record sent half-way
+ *     through a session would freeze its numbers there. A session resumed after it was reported is not re-counted
+ *     (stated residual).
+ *   - **The `report_id` is kept in a local cursor** (`<state dir>/shelf-reports.json`), keyed by a local-only
+ *     session key, so a retry after a failed POST sends the SAME id and Tower counts it once.
+ *
+ * The POST goes to `/api/ambient/ingest` as its own `shelf-reports.v1` envelope with the collector's three shelf
+ * headers. The header says `team` because the numbers are team-shelf data; Tower's lock refuses a founder's request
+ * whose header says anything else.
+ *
+ * Logs: counts and labels only (`safeLog`).
+ */
+import crypto from "node:crypto";
+import path from "node:path";
+import { errorNameOnly, projectShelfMetrics, safeLog, SHELF_REPORTS_ENVELOPE_VERSION, SHELF_REPORTS_MAX_PER_REQUEST, } from "@bli-cockpit/telemetry-core";
+import { readJsonFile, writeJsonFileAtomic } from "./local-state-files.js";
+import { collectorShelfHeaders } from "./shelf-headers.js";
+const TAG = "shelf";
+export const SHELF_REPORT_CURSOR_FILENAME = "shelf-reports.json";
+export const SHELF_REPORT_SETTLE_MS = 6 * 60 * 60 * 1000;
+/** A cursor entry is forgotten this long after it was sent; by then the session is far outside every scan window. */
+const CURSOR_RETENTION_MS = 120 * 24 * 60 * 60 * 1000;
+function cursorFile(paths) {
+    return path.join(paths.state_dir, SHELF_REPORT_CURSOR_FILENAME);
+}
+async function readCursor(paths) {
+    const value = (await readJsonFile(cursorFile(paths)).catch(() => null));
+    if (value?.schema_version !== "shelf-report-cursor.v1" || !value.sessions || typeof value.sessions !== "object") {
+        return { schema_version: "shelf-report-cursor.v1", sessions: {} };
+    }
+    return { schema_version: "shelf-report-cursor.v1", sessions: value.sessions };
+}
+/** How many drawer sessions this laptop has recorded, for `cockpit shelf status`. */
+export async function countShelvedSessions(paths) {
+    const cursor = await readCursor(paths);
+    const firstSeen = Object.values(cursor.sessions).map((entry) => entry.first_seen_at).sort();
+    return { sessions: firstSeen.length, oldest: firstSeen[0] ?? null };
+}
+/** Send what is owed. Never throws; every branch logs one line with counts. */
+export async function reportShelvedSessions(options) {
+    const now = options.now ?? new Date();
+    const outcome = { shelved: options.shelved.length, sent: 0, already_sent: 0, unsettled: 0, not_counted: 0, failed: 0, refused: 0, reason: "nothing_owed" };
+    if (options.shelved.length === 0)
+        return outcome;
+    const cursor = await readCursor(options.paths);
+    const owed = [];
+    for (const session of options.shelved) {
+        const entry = cursor.sessions[session.key] ??= {
+            report_id: crypto.randomUUID(),
+            sent_at: null,
+            first_seen_at: now.toISOString(),
+        };
+        if (entry.sent_at) {
+            outcome.already_sent += 1;
+            continue;
+        }
+        if (entry.refused_reason) {
+            outcome.refused += 1;
+            continue;
+        }
+        if (!session.facts) {
+            outcome.not_counted += 1;
+            continue;
+        }
+        if (now.getTime() - session.recencyMs < SHELF_REPORT_SETTLE_MS) {
+            outcome.unsettled += 1;
+            continue;
+        }
+        try {
+            owed.push({ key: session.key, report: { report_id: entry.report_id, shelf: "drawer", metrics: projectShelfMetrics(session.facts, options.allow ?? []) } });
+        }
+        catch (error) {
+            outcome.not_counted += 1;
+            safeLog(TAG, "shelf_report_projection_failed", { error_name: errorNameOnly(error) });
+        }
+    }
+    if (owed.length > 0) {
+        if (!options.dashboardUrl || !options.deviceToken) {
+            outcome.failed = owed.length;
+            outcome.reason = "not_signed_in";
+        }
+        else {
+            await sendOwed(owed, cursor, outcome, { ...options, dashboardUrl: options.dashboardUrl, deviceToken: options.deviceToken, now });
+        }
+    }
+    else if (outcome.unsettled > 0) {
+        outcome.reason = "waiting_to_settle";
+    }
+    else {
+        outcome.reason = "nothing_owed";
+    }
+    pruneCursor(cursor, now);
+    try {
+        await writeJsonFileAtomic(cursorFile(options.paths), cursor);
+    }
+    catch (error) {
+        // The ids stay in memory only; the next tick makes new ones for anything not yet sent, and Tower has none of
+        // those yet, so nothing is double-counted. Said out loud because the cursor is what makes retries idempotent.
+        safeLog(TAG, "shelf_report_cursor_not_written", { error_name: errorNameOnly(error) });
+    }
+    safeLog(TAG, outcome.failed > 0 ? "shelf_reports_owed" : outcome.sent > 0 ? "shelf_reports_sent" : outcome.reason, { ...outcome, reason: undefined });
+    return outcome;
+}
+async function sendOwed(owed, cursor, outcome, options) {
+    for (let start = 0; start < owed.length; start += SHELF_REPORTS_MAX_PER_REQUEST) {
+        const chunk = owed.slice(start, start + SHELF_REPORTS_MAX_PER_REQUEST);
+        let status = 0;
+        let serverReason = null;
+        try {
+            const response = await options.fetchImpl(`${options.dashboardUrl}/api/ambient/ingest`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${options.deviceToken}`,
+                    "Content-Type": "application/json",
+                    ...collectorShelfHeaders(),
+                },
+                body: JSON.stringify({
+                    envelope_version: SHELF_REPORTS_ENVELOPE_VERSION,
+                    generated_at: options.now.toISOString(),
+                    shelf_reports: chunk.map((item) => item.report),
+                }),
+                signal: AbortSignal.timeout(30_000),
+            });
+            status = response.status;
+            const body = (await response.json().catch(() => null));
+            serverReason = typeof body?.reason === "string" && /^[a-z0-9_:-]{1,80}$/u.test(body.reason) ? body.reason : null;
+        }
+        catch (error) {
+            safeLog(TAG, "shelf_reports_transport_failed", { reports: chunk.length, error_name: errorNameOnly(error) });
+        }
+        if (status >= 200 && status < 300) {
+            for (const item of chunk)
+                cursor.sessions[item.key].sent_at = options.now.toISOString();
+            outcome.sent += chunk.length;
+            outcome.reason = "shelf_reports_sent";
+            continue;
+        }
+        // Only an owner's laptop sends bare records; a refusal that says so is final for these ids.
+        if (status === 403 && serverReason === "shelf_reports_owner_only") {
+            for (const item of chunk)
+                cursor.sessions[item.key].refused_reason = serverReason;
+            outcome.refused += chunk.length;
+            outcome.reason = serverReason;
+            continue;
+        }
+        outcome.failed += chunk.length;
+        outcome.reason = serverReason ?? (status === 0 ? "shelf_reports_transport_failed" : `shelf_reports_http_${status}`);
+        safeLog(TAG, "shelf_reports_refused", { reports: chunk.length, http_status: status, server_reason: serverReason });
+    }
+}
+function pruneCursor(cursor, now) {
+    for (const [key, entry] of Object.entries(cursor.sessions)) {
+        const sent = entry.sent_at ? Date.parse(entry.sent_at) : NaN;
+        if (Number.isFinite(sent) && now.getTime() - sent > CURSOR_RETENTION_MS)
+            delete cursor.sessions[key];
+    }
+}

package/dist/shelf-state.js

@@ -0,0 +1,112 @@
+/**
+ * What the heartbeat learns about Tower's founder lock, kept on the laptop (BLI-23478, three-shelves design 9.1
+ * item 12), and the heartbeat's own shelf rule for roots.
+ *
+ * The heartbeat answer carries `{ shelf_enforced, min_cli_version, is_owner, founder_routing_enabled }` (and
+ * `cli_too_old` for an owner on an old CLI). This module writes it to `<state dir>/shelf-state.json`, where the
+ * memory hooks, the Memory MCP server and `cockpit doctor` read it without a network call. Only the heartbeat
+ * writes it; an answer without the fields (a Tower that predates the lock) leaves the last file as it was.
+ *
+ * Logs: labels only (`safeLog`).
+ */
+import path from "node:path";
+import os from "node:os";
+import { errorNameOnly, safeLog, SHELF_STATE_FILENAME, SHELF_STATE_SCHEMA_VERSION, ShelfStateFileSchema, } from "@bli-cockpit/telemetry-core";
+import { readShelfState, resolveShelfWith } from "@bli-cockpit/memory-mcp/dist/shelf-routing.js";
+import { normalizeMachinePath } from "@bli-cockpit/memory-mcp/dist/recorded-outside-roots.js";
+import { getCollectorRuntimePaths } from "./local-state-paths.js";
+import { decideShelfMode, OWNER_CHECK_UNAVAILABLE } from "./shelf-decision.js";
+import { writeJsonFileAtomic } from "./local-state-files.js";
+const TAG = "shelf";
+function bool(value) {
+    return typeof value === "boolean" ? value : null;
+}
+/** Store the lock state from one heartbeat answer. Never throws. */
+export async function recordShelfState(homeDir, reply, now = new Date()) {
+    if (!reply || typeof reply["shelf_enforced"] !== "boolean") {
+        safeLog(TAG, "shelf_state_not_in_answer", {});
+        return null;
+    }
+    // A null means Tower could not read its own state this time (heartbeat `shelf_state_unreadable`). It never
+    // overwrites a known answer: one blip must not turn a founder's laptop back into a teammate's (fail closed).
+    const previous = readShelfState(homeDir ?? os.homedir());
+    const isOwner = bool(reply["is_owner"]) ?? previous?.is_owner ?? null;
+    const routing = bool(reply["founder_routing_enabled"]) ?? previous?.founder_routing_enabled ?? null;
+    if (bool(reply["is_owner"]) === null || bool(reply["founder_routing_enabled"]) === null) {
+        safeLog(TAG, "shelf_state_partly_unknown", { kept_is_owner: isOwner, kept_routing: routing });
+    }
+    const parsed = ShelfStateFileSchema.safeParse({
+        schema_version: SHELF_STATE_SCHEMA_VERSION,
+        checked_at: now.toISOString(),
+        shelf_enforced: reply["shelf_enforced"],
+        is_owner: isOwner,
+        founder_routing_enabled: routing,
+        min_cli_version: typeof reply["min_cli_version"] === "string" ? reply["min_cli_version"].slice(0, 40) : null,
+        cli_too_old: reply["cli_too_old"] === true,
+    });
+    if (!parsed.success) {
+        safeLog(TAG, "shelf_state_answer_unreadable", { field: parsed.error.issues[0]?.path.join(".") ?? null });
+        return null;
+    }
+    try {
+        await writeJsonFileAtomic(path.join(getCollectorRuntimePaths(homeDir).state_dir, SHELF_STATE_FILENAME), parsed.data);
+    }
+    catch (error) {
+        safeLog(TAG, "shelf_state_not_written", { error_name: errorNameOnly(error) });
+        return null;
+    }
+    const state = parsed.data;
+    const changed = previous?.is_owner !== state.is_owner ||
+        previous?.founder_routing_enabled !== state.founder_routing_enabled ||
+        previous?.cli_too_old !== state.cli_too_old;
+    safeLog(TAG, changed ? "shelf_state_changed" : "shelf_state_recorded", {
+        is_owner: state.is_owner,
+        founder_routing_enabled: state.founder_routing_enabled,
+        shelf_enforced: state.shelf_enforced,
+        cli_too_old: state.cli_too_old,
+    });
+    return state;
+}
+/**
+ * The approved roots that may travel as labels, and how many stay home as a bare count (drawer-labelled). Asks
+ * Tower live on a laptop with labels (`shelf-decision.ts`): a non-founder's labels are ignored and every root
+ * travels as today; with no answer the drawer roots stay hidden this tick (fail closed; the heartbeat still goes).
+ */
+export async function teamRootsForHeartbeat(roots, homeDir, fetchImpl) {
+    const decision = await decideShelfMode({ ...(homeDir ? { homeDir } : {}), fetchImpl });
+    const rules = decision.rules;
+    if (decision.mode === "inactive" || decision.mode === "not_founder")
+        return { team: [...roots], shelved: 0 };
+    const team = rules.failed ? [] : roots.filter((root) => resolveShelfWith(rules, root).shelf === "team");
+    // Distinct folders: a drawer label on a folder that is also an approved root is one folder, counted once.
+    const offTeam = new Set([
+        ...roots.filter((root) => !team.includes(root)).map((root) => normalizeMachinePath(root, rules.platform)),
+        ...rules.folders.filter((folder) => folder.labelled && folder.shelf !== "team").map((folder) => folder.root),
+    ]);
+    const shelved = offTeam.size;
+    safeLog(TAG, "heartbeat_roots_split", { team_roots: team.length, shelved_roots: shelved });
+    return { team, shelved };
+}
+export { readShelfState };
+/**
+ * BLI-23478: `cockpit memory search|save|update|forget` carry text an agent wrote, from a folder the CLI cannot
+ * prove, exactly like the Memory MCP. On a laptop with shelf settings Tower is asked LIVE (never the saved copy):
+ * a founder's laptop refuses locally by the same name as the MCP, and no answer refuses too
+ * (`owner_check_unavailable`). A laptop with no shelf settings asks nothing; Tower's lock refuses a founder's
+ * `collector` caller on a memory door anyway.
+ */
+export const FOUNDER_MCP_DISABLED = "founder_mcp_disabled_until_host_workspace";
+export const FOUNDER_TEXT_VERBS = new Set(["search", "save", "update", "forget"]);
+export const FOUNDER_MEMORY_VERB_DETAIL = "On a founder's laptop this memory command is off until it can prove which folder it runs in. Nothing was sent. " +
+    "The automatic memory hooks still save and recall from team folders.";
+export async function founderMemoryVerbRefusal(homeDir, fetchImpl) {
+    const decision = await decideShelfMode({ ...(homeDir ? { homeDir } : {}), fetchImpl });
+    const refusal = decision.mode === "founder"
+        ? { reason: FOUNDER_MCP_DISABLED, detail: FOUNDER_MEMORY_VERB_DETAIL }
+        : decision.mode === "hold"
+            ? { reason: OWNER_CHECK_UNAVAILABLE, detail: "Tower could not be asked whether this is a founder's laptop, so nothing was sent. Try again shortly." }
+            : null;
+    if (refusal)
+        safeLog(TAG, "memory_verb_refused", { refused: refusal.reason });
+    return refusal;
+}