@bli-cockpit/cli 0.2.52 → 0.2.53

package/dist/commands/sync-followups.js

@@ -19,7 +19,10 @@ import { runSelfUpdate, SelfUpdateError } from "./install-update.js";
 import { getCollectorRuntimePaths, LOCAL_COLLECTOR_VERSION, } from "../local-state.js";
 import { runAutostartSelfHeal, } from "../autostart-self-heal.js";
 import { runStagingPrune } from "../disk-prune.js";
+import { runEvidenceReconcile, } from "../evidence-reconcile-client.js";
 import { envWithNodeRuntimeOnPath, runScheduledSelfUpdate, } from "../scheduled-self-update.js";
+/** How many reconcile batches (of up to 500 hashes each) one sync tick may spend. */
+const RECONCILE_BATCHES_PER_TICK = 1;
 /**
  * BLI-2721: after the tick's collection and self-update are done and
  * reported, repair a broken/legacy autostart registration in place (Windows
@@ -197,8 +200,23 @@ function memoryInstallEvent(outcome) {
  * The rule itself is `disk-retention.ts`: only objects the upload ledger
  * vouches for are ever deleted, and anything undelivered is counted, aged and
  * named instead.
+ *
+ * BLI-3619's second half runs FIRST, every tick, bounded to
+ * `RECONCILE_BATCHES_PER_TICK` (one batch of up to 500 hashes): the local
+ * ledger's own memory is capped, so a laptop that keeps accumulating
+ * `unknown` state needs SOMETHING asking the server on a schedule, not only
+ * when a person happens to type `cockpit clean --reconcile`. One batch a tick
+ * is not throttled to once a day like the prune below — an `unknown` backlog
+ * drains at up to 500 hashes/15 min, and the ordinary case (nothing unknown)
+ * costs one cheap local read and no network call at all, so it never competes
+ * with collection for the tick's time. A reconcile failure never blocks the
+ * prune that follows it.
  */
 export async function runStagingPruneAfterSync(command, io, dashboardUrl, options = {}) {
+    const events = [];
+    const reconciled = await runReconcileFollowUp(command, io, dashboardUrl, options);
+    if (reconciled)
+        events.push(reconcileEvent(reconciled));
     let result;
     try {
         result = await runStagingPrune(getCollectorRuntimePaths(command.homeDir), {
@@ -217,17 +235,36 @@ export async function runStagingPruneAfterSync(command, io, dashboardUrl, option
     }
     // The daily throttle is the steady state — reporting it would post a receipt
     // on 95 of every 96 ticks for no new information.
-    if (result.reason === "throttled_recent_run")
+    if (result.reason !== "throttled_recent_run") {
+        events.push(stagingPruneEvent(result));
+    }
+    if (events.length === 0)
         return;
     await reportInstallEventsBestEffort({
         homeDir: command.homeDir,
         dashboardUrl,
         command: "sync",
-        events: [stagingPruneEvent(result)],
+        events,
         json: command.json,
         io,
     });
 }
+/**
+ * Never throws (`runEvidenceReconcile` already never does); returns `null`
+ * for the boring, common case — nothing this tick was `unknown` — so that
+ * case costs no receipt either, the same rule the prune's own daily throttle
+ * follows above.
+ */
+async function runReconcileFollowUp(command, io, dashboardUrl, options) {
+    const result = await runEvidenceReconcile({
+        homeDir: command.homeDir,
+        dashboardUrl,
+        maxBatches: RECONCILE_BATCHES_PER_TICK,
+        fetch: io.fetch,
+        ...(options.now ? { now: options.now } : {}),
+    });
+    return result.reason === "nothing_unknown" ? null : result;
+}
 function prunedNothing() {
     return {
         status: "skipped",
@@ -276,6 +313,14 @@ function stagingPruneEvent(result) {
     }
     return { step: "staging_prune", status: "ok", error_detail: detail };
 }
+/** Counts only; no hash and no pack id travels in a receipt. */
+function reconcileEvent(result) {
+    const detail = `asked ${result.asked} hash(es) across ${result.batches}/${result.total_batches} batch(es); committed ${result.committed}, not_committed ${result.not_committed}, unknown_to_server ${result.unknown_to_server}, failed_batches ${result.failed_batches}`;
+    if (result.status === "fail") {
+        return { step: "evidence_reconcile", status: "fail", error_code: result.reason, error_detail: detail };
+    }
+    return { step: "evidence_reconcile", status: "ok", error_detail: detail };
+}
 /**
  * BLI-2601: the fleet keeps itself current on npm `latest` without anyone
  * re-running `npm i -g @bli-cockpit/cli` by hand after day 0. This always

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

@@ -0,0 +1,132 @@
+/**
+ * The server's own answer, kept durably on this machine.
+ *
+ * BLI-3619. `cursors/raw-evidence.json` `objects` answers "did this content
+ * hash commit?" but is capped at 5,000 rows and prunes the oldest, so a pack
+ * staged before its own memory begins reads `unknown` — the ledger cannot say,
+ * not that it says no. `cockpit clean --reconcile` asks the dashboard once per
+ * hash and this file is where that answer lives afterward, so the same
+ * question is never asked twice for the same hash and a `--dry-run` run can
+ * read a reconciled state from an earlier `--reconcile` run without spending
+ * another round trip.
+ *
+ * Keyed on `content_hash_sha256`, same as the commit ledger and for the same
+ * reason: `pack_id` is a local directory name the server has never seen.
+ *
+ * Metadata only: hashes, a verdict label, and two timestamps. Never a path,
+ * never a byte of content.
+ */
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { describeError, isMissingFileFailure } from "../health-detail.js";
+export const RECONCILE_CURSOR_FILENAME = "raw-evidence-reconcile.json";
+// Same order of magnitude as the commit ledger's own cap (D4): entries are
+// small, and the question this file answers is bounded by how many hashes a
+// laptop can hold `unknown` at once, which the byte cap already keeps small.
+const MAX_TRACKED_RESULTS = 5_000;
+export function emptyReconcileCursorState() {
+    return {
+        schema_version: "cockpit-raw-evidence-reconcile-cursor.v1",
+        updated_at: null,
+        results: {},
+    };
+}
+export async function readReconcileCursor(paths) {
+    try {
+        const raw = JSON.parse(await fs.readFile(reconcileCursorPath(paths), "utf8"));
+        return parseReconcileCursorState(raw);
+    }
+    catch (error) {
+        if (!isMissingFileFailure(error)) {
+            console.error("[collector reconcile] reconcile cursor unreadable, starting from empty", JSON.stringify({
+                reason: "reconcile_cursor_unreadable",
+                ...describeError(error),
+            }));
+        }
+        return emptyReconcileCursorState();
+    }
+}
+export async function writeReconcileCursor(paths, state) {
+    const filePath = reconcileCursorPath(paths);
+    await fs.mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    const pruned = pruneReconcileState(state);
+    const serialized = `${JSON.stringify(pruned, null, 2)}\n`;
+    const tempPath = `${filePath}.tmp-${process.pid}-${crypto.randomUUID()}`;
+    let handle = null;
+    try {
+        handle = await fs.open(tempPath, "w", 0o600);
+        await handle.writeFile(serialized);
+        await handle.sync();
+    }
+    finally {
+        await handle?.close();
+    }
+    try {
+        await fs.rename(tempPath, filePath);
+    }
+    catch (error) {
+        await fs.rm(tempPath, { force: true }).catch(() => undefined);
+        throw error;
+    }
+    if (process.platform !== "win32") {
+        await fs.chmod(filePath, 0o600).catch(() => undefined);
+    }
+}
+export function recordReconcileResult(state, contentHash, entry) {
+    state.results[contentHash] = entry;
+}
+function pruneReconcileState(state) {
+    const entries = Object.entries(state.results);
+    if (entries.length <= MAX_TRACKED_RESULTS)
+        return state;
+    entries.sort((a, b) => b[1].checked_at.localeCompare(a[1].checked_at));
+    return {
+        ...state,
+        results: Object.fromEntries(entries.slice(0, MAX_TRACKED_RESULTS)),
+    };
+}
+function reconcileCursorPath(paths) {
+    return path.join(paths.cursors_dir, RECONCILE_CURSOR_FILENAME);
+}
+function parseReconcileCursorState(value) {
+    if (!value || typeof value !== "object")
+        return emptyReconcileCursorState();
+    const record = value;
+    const results = {};
+    const rawResults = record["results"];
+    if (rawResults && typeof rawResults === "object") {
+        for (const [hash, entry] of Object.entries(rawResults)) {
+            const parsed = parseReconcileEntry(entry);
+            if (parsed)
+                results[hash] = parsed;
+        }
+    }
+    return {
+        schema_version: "cockpit-raw-evidence-reconcile-cursor.v1",
+        updated_at: optionalString(record["updated_at"]),
+        results,
+    };
+}
+function parseReconcileEntry(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const record = value;
+    const verdict = record["verdict"];
+    const checkedAt = optionalString(record["checked_at"]);
+    if (!checkedAt)
+        return null;
+    if (verdict !== "committed" &&
+        verdict !== "not_committed" &&
+        verdict !== "unknown_to_server") {
+        return null;
+    }
+    return {
+        verdict,
+        checked_at: checkedAt,
+        server_committed_at: optionalString(record["server_committed_at"]),
+    };
+}
+function optionalString(value) {
+    return typeof value === "string" && value.trim() ? value : null;
+}

package/dist/disk-usage.js

@@ -28,6 +28,14 @@
  *                          7.93 GB of "I forgot" must not read as 7.93 GB of
  *                          "it never landed".
  *
+ * BLI-3619's second half: `cockpit clean --reconcile` asks the dashboard's own
+ * upload ledger about a hash this laptop can no longer classify and writes the
+ * answer into `cursors/raw-evidence-reconcile.json` — read here, alongside the
+ * commit ledger, before an object is allowed to fall back to `unknown`. A
+ * server-confirmed `committed` object counts as `committed`; `not_committed` /
+ * `unknown_to_server` count as `uncommitted`, never `unknown` — the server
+ * spoke, so "the ledger cannot say" is no longer true of that hash.
+ *
  * Content hashes come from each pack's own `manifest.json`, which already
  * records `relative_path` + `content_hash_sha256` + `byte_size` for every file
  * it staged. That is why a daily inventory does not re-read 20 GB. A physical
@@ -42,6 +50,7 @@ import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { readRawEvidenceCursor } from "./cursors/raw-evidence-cursor.js";
+import { readReconcileCursor, } from "./cursors/raw-evidence-reconcile-cursor.js";
 import { describeError } from "./health-detail.js";
 import { rotatedLogFootprint } from "./log-rotation.js";
 import { readRawEvidenceStagingState } from "./raw-evidence-staging.js";
@@ -67,6 +76,7 @@ export async function readDiskFootprint(paths, now = new Date()) {
 export async function readStagingInventory(paths, now = new Date()) {
     const root = path.join(paths.state_dir, RAW_EVIDENCE_DIR);
     const ledger = await readCommitLedger(paths);
+    const reconciled = await readReconcileLedger(paths);
     const stagedAt = await readStagedAtIndex(paths);
     const entries = await fs
         .readdir(root, { withFileTypes: true })
@@ -86,6 +96,7 @@ export async function readStagingInventory(paths, now = new Date()) {
             continue;
         const pack = await readPack(dir, entry.name, {
             ledger,
+            reconciled,
             stagedAt,
             now,
             budget,
@@ -121,6 +132,15 @@ async function readStagedAtIndex(paths) {
     }
     return index;
 }
+/**
+ * The reconcile cursor as a lookup map. Read alongside the commit ledger so an
+ * object the server confirmed committed classifies exactly like one this
+ * machine's own ledger still remembers.
+ */
+async function readReconcileLedger(paths) {
+    const cursor = await readReconcileCursor(paths);
+    return new Map(Object.entries(cursor.results));
+}
 async function readPack(dir, packId, options) {
     const manifest = await readManifestIndex(dir);
     const pack = {
@@ -158,6 +178,12 @@ async function classifyObject(dir, packId, relative, size, manifest, options) {
             age_ms: ageMs(committedAt, options.now),
         };
     }
+    if (hash) {
+        const reconciled = options.reconciled.get(hash);
+        if (reconciled) {
+            return classifyFromReconcileAnswer(base, hash, reconciled, options.now);
+        }
+    }
     const unknownReason = unknownStateReason(hash, manifest, stagedAt, options);
     return {
         ...base,
@@ -168,6 +194,35 @@ async function classifyObject(dir, packId, relative, size, manifest, options) {
         age_ms: ageMs(stagedAt, options.now),
     };
 }
+/**
+ * The server's own answer for this hash, already on disk from an earlier
+ * `cockpit clean --reconcile` run. This takes priority over
+ * `unknownStateReason`'s guesswork about the LOCAL ledger's memory, because
+ * the server was actually asked and actually answered.
+ */
+function classifyFromReconcileAnswer(base, hash, reconciled, now) {
+    if (reconciled.verdict === "committed") {
+        const decidedAt = reconciled.server_committed_at ?? reconciled.checked_at;
+        return {
+            ...base,
+            content_hash: hash,
+            state: "committed",
+            reason: "reconciled_committed",
+            decided_at: decidedAt,
+            age_ms: ageMs(decidedAt, now),
+        };
+    }
+    return {
+        ...base,
+        content_hash: hash,
+        state: "uncommitted",
+        reason: reconciled.verdict === "not_committed"
+            ? "reconciled_not_committed"
+            : "reconciled_unknown_to_server",
+        decided_at: reconciled.checked_at,
+        age_ms: ageMs(reconciled.checked_at, now),
+    };
+}
 /**
  * Why the ledger's silence about this object is NOT the same as a "no".
  *

package/dist/evidence-reconcile-client.js

@@ -0,0 +1,224 @@
+/**
+ * Asks `POST /api/ambient/evidence/reconcile` about every hash this laptop
+ * can no longer classify on its own, then writes the answer into
+ * `cursors/raw-evidence-reconcile.json` so `disk-usage.ts` reads it back on
+ * every run after this one.
+ *
+ * BLI-3619. Three properties, same as the prune it feeds:
+ *
+ * - **Never deletes.** This module only asks and records; `disk-prune.ts`
+ *   decides what goes, unchanged.
+ * - **A server failure never blocks the prune.** A batch that cannot be asked
+ *   leaves its hashes exactly as unresolved as they were — still `unknown`
+ *   locally — and the run says `reconcile_unavailable: <reason>` rather than
+ *   throwing. The ordinary retention prune runs whether this succeeded,
+ *   partly succeeded, or could not run at all.
+ * - **Bounded.** `maxBatches` lets a caller (the daily sync fold) ask only one
+ *   batch of up to 500 hashes per tick rather than draining years of
+ *   accumulated `unknown` state in one request storm; `cockpit clean
+ *   --reconcile` itself asks every batch there is.
+ */
+import { EVIDENCE_RECONCILE_MAX_BATCH, EVIDENCE_RECONCILE_SCHEMA_VERSION, EvidenceReconcileResponseSchema, } from "@bli-cockpit/telemetry-core";
+import { describeError } from "./health-detail.js";
+import { getCollectorRuntimePaths, readLocalCollectorSessionFile } from "./local-state.js";
+import { readReconcileCursor, recordReconcileResult, writeReconcileCursor, } from "./cursors/raw-evidence-reconcile-cursor.js";
+import { readStagingInventory } from "./disk-usage.js";
+const RECONCILE_BATCH_TIMEOUT_MS = 15_000;
+/** The prune the sync tick and `cockpit clean --reconcile` both call. Never throws. */
+export async function runEvidenceReconcile(options) {
+    const paths = getCollectorRuntimePaths(options.homeDir);
+    const now = options.now ?? new Date();
+    const doFetch = options.fetch ?? fetch;
+    try {
+        const inventory = options.inventory ?? (await readStagingInventory(paths, now));
+        const hashes = uniqueUnknownHashes(inventory);
+        if (hashes.length === 0) {
+            // No stderr line here on purpose: the sync tick calls this every 15
+            // minutes and the steady state is "nothing unknown" — logging that
+            // every tick forever is exactly the receipt-on-95-of-96-ticks spam the
+            // daily prune throttle exists to avoid. `cockpit clean --reconcile`
+            // still tells a person this on stdout (`reconcileLines` in clean.ts).
+            return emptyResult("nothing_unknown");
+        }
+        const session = await readLocalCollectorSessionFile(paths).catch(() => null);
+        if (!session ||
+            session.session_state !== "valid" ||
+            typeof session.device_token !== "string" ||
+            !session.device_token) {
+            const result = {
+                ...emptyResult("no_device_session"),
+                total_batches: chunk(hashes, EVIDENCE_RECONCILE_MAX_BATCH).length,
+            };
+            reportReconcile(result);
+            return result;
+        }
+        const batches = chunk(hashes, EVIDENCE_RECONCILE_MAX_BATCH);
+        const bounded = options.maxBatches != null ? batches.slice(0, options.maxBatches) : batches;
+        const cursor = await readReconcileCursor(paths);
+        let committed = 0;
+        let notCommitted = 0;
+        let unknownToServer = 0;
+        let failedBatches = 0;
+        let firstFailureReason = null;
+        let askedThisRun = 0;
+        for (const batch of bounded) {
+            const outcome = await sendReconcileBatch({
+                dashboardUrl: options.dashboardUrl,
+                deviceToken: session.device_token,
+                hashes: batch,
+                fetchImpl: doFetch,
+            });
+            if (!outcome.ok) {
+                failedBatches += 1;
+                firstFailureReason ??= outcome.reason;
+                continue;
+            }
+            askedThisRun += batch.length;
+            for (const item of outcome.results) {
+                recordReconcileResult(cursor, item.content_hash_sha256, {
+                    verdict: item.verdict,
+                    checked_at: now.toISOString(),
+                    server_committed_at: item.verdict === "committed" ? item.committed_at : null,
+                });
+                if (item.verdict === "committed")
+                    committed += 1;
+                else if (item.verdict === "not_committed")
+                    notCommitted += 1;
+                else
+                    unknownToServer += 1;
+            }
+        }
+        if (askedThisRun > 0) {
+            cursor.updated_at = now.toISOString();
+            await writeReconcileCursor(paths, cursor).catch((error) => {
+                // The prune's own forgetStagedObjects follows the same rule: the
+                // answer is not lost (the server has it), but a reader of THIS
+                // machine will ask again next run rather than silently drift.
+                console.error("[collector reconcile] reconcile cursor not written after answers landed", JSON.stringify({
+                    reason: "reconcile_cursor_write_failed",
+                    answered_count: askedThisRun,
+                    ...describeError(error),
+                }));
+            });
+        }
+        const result = {
+            status: askedThisRun > 0 ? "ok" : "fail",
+            reason: reconcileReason({
+                askedThisRun,
+                failedBatches,
+                firstFailureReason,
+                boundedShortOfAvailable: bounded.length < batches.length,
+            }),
+            asked: askedThisRun,
+            committed,
+            not_committed: notCommitted,
+            unknown_to_server: unknownToServer,
+            batches: bounded.length,
+            failed_batches: failedBatches,
+            total_batches: batches.length,
+        };
+        reportReconcile(result);
+        return result;
+    }
+    catch (error) {
+        const result = {
+            ...emptyResult(`reconcile_unavailable: ${describeError(error).error_name}`),
+            status: "fail",
+        };
+        console.error("[collector reconcile] the reconcile pass threw; nothing was answered or deleted", JSON.stringify({ reason: "reconcile_threw", ...describeError(error) }));
+        return result;
+    }
+}
+function reconcileReason(input) {
+    if (input.askedThisRun === 0) {
+        return `reconcile_unavailable: ${input.firstFailureReason ?? "unknown"}`;
+    }
+    if (input.failedBatches > 0)
+        return "reconciled_partial";
+    if (input.boundedShortOfAvailable)
+        return "reconciled_bounded";
+    return "reconciled";
+}
+/** Every `unknown`-state object's hash, deduplicated — the question is per hash. */
+function uniqueUnknownHashes(inventory) {
+    const hashes = new Set();
+    for (const pack of inventory.packs) {
+        for (const object of pack.objects) {
+            if (object.state === "unknown" && object.content_hash) {
+                hashes.add(object.content_hash);
+            }
+        }
+    }
+    return [...hashes];
+}
+function chunk(items, size) {
+    const batches = [];
+    for (let index = 0; index < items.length; index += size) {
+        batches.push(items.slice(index, index + size));
+    }
+    return batches;
+}
+async function sendReconcileBatch(options) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), RECONCILE_BATCH_TIMEOUT_MS);
+    try {
+        const response = await options.fetchImpl(`${options.dashboardUrl}/api/ambient/evidence/reconcile`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${options.deviceToken}`,
+            },
+            body: JSON.stringify({
+                schema_version: EVIDENCE_RECONCILE_SCHEMA_VERSION,
+                items: options.hashes.map((hash) => ({ content_hash_sha256: hash })),
+            }),
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            return { ok: false, reason: `http_${response.status}`, results: [] };
+        }
+        const body = await response.json().catch(() => null);
+        const parsed = EvidenceReconcileResponseSchema.safeParse(body);
+        if (!parsed.success) {
+            return { ok: false, reason: "invalid_response", results: [] };
+        }
+        return { ok: true, reason: "ok", results: parsed.data.results };
+    }
+    catch (error) {
+        return { ok: false, reason: describeError(error).error_name, results: [] };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function emptyResult(reason) {
+    return {
+        status: "skipped",
+        reason,
+        asked: 0,
+        committed: 0,
+        not_committed: 0,
+        unknown_to_server: 0,
+        batches: 0,
+        failed_batches: 0,
+        total_batches: 0,
+    };
+}
+/**
+ * The receipt, on stderr, exactly the shape the ticket names:
+ * `{asked, committed, not_committed, unknown_to_server, batches, failed_batches}`,
+ * plus `total_batches` so a bounded (daily-fold) run says the bound it hit.
+ * Metadata only — hashes and pack ids never travel in this line.
+ */
+function reportReconcile(result) {
+    console.error("[collector reconcile]", JSON.stringify({
+        reason: result.reason,
+        asked: result.asked,
+        committed: result.committed,
+        not_committed: result.not_committed,
+        unknown_to_server: result.unknown_to_server,
+        batches: result.batches,
+        total_batches: result.total_batches,
+        failed_batches: result.failed_batches,
+    }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.52",
+  "version": "0.2.53",
   "private": false,
   "type": "module",
   "bin": {
@@ -27,7 +27,7 @@
     "test": "node dist/cli.js --help && node ../../scripts/assert-public-cli-routing.mjs && node ../../scripts/assert-public-cli-runtime-files.mjs && node ../../scripts/assert-public-cli-no-fleet-posts.mjs && node ../../scripts/assert-public-package-pack.mjs --workspace=@bli-cockpit/cli"
   },
   "dependencies": {
-    "@bli-cockpit/memory-mcp": "0.1.1",
-    "@bli-cockpit/telemetry-core": "0.1.26"
+    "@bli-cockpit/memory-mcp": "0.1.2",
+    "@bli-cockpit/telemetry-core": "0.1.27"
   }
 }