@bli-cockpit/cli 0.2.51 → 0.2.53

package/dist/disk-retention.js

@@ -0,0 +1,157 @@
+/** How long a committed spare is kept so a retry still has local bytes. */
+export const DEFAULT_STAGING_RETENTION_MS = 48 * 60 * 60 * 1000;
+/** Ceiling on everything under `raw-evidence`, manifests included. */
+export const DEFAULT_STAGING_CAP_BYTES = 2 * 1024 * 1024 * 1024;
+/** Local knobs, read from the environment like `COCKPIT_DISABLE_GC`. */
+export const STAGING_CAP_ENV = "COCKPIT_STAGING_CAP_BYTES";
+export const STAGING_RETENTION_ENV = "COCKPIT_STAGING_RETENTION_HOURS";
+/** The two knobs, from the environment, falling back to the defaults above. */
+export function retentionOptionsFromEnv(env) {
+    const hours = Number(env[STAGING_RETENTION_ENV]);
+    const cap = Number(env[STAGING_CAP_ENV]);
+    return {
+        retentionMs: Number.isFinite(hours) && hours >= 0
+            ? hours * 60 * 60 * 1000
+            : DEFAULT_STAGING_RETENTION_MS,
+        capBytes: Number.isFinite(cap) && cap > 0 ? cap : DEFAULT_STAGING_CAP_BYTES,
+    };
+}
+export function planStagingRetention(inventory, options = {}) {
+    const retentionMs = options.retentionMs ?? DEFAULT_STAGING_RETENTION_MS;
+    const capBytes = options.capBytes ?? DEFAULT_STAGING_CAP_BYTES;
+    const plan = emptyPlan(capBytes, retentionMs, inventory.total_bytes);
+    const committedInWindow = [];
+    for (const pack of inventory.packs) {
+        for (const object of pack.objects) {
+            if (object.state !== "committed") {
+                keepUnvouched(plan, object);
+                continue;
+            }
+            if (options.allCommitted || object.age_ms >= retentionMs) {
+                pushDeletion(plan, object, "committed_past_retry_window");
+                continue;
+            }
+            committedInWindow.push(object);
+            addToBucket(plan.kept_in_window, object);
+        }
+    }
+    applyByteCap(plan, committedInWindow, capBytes, inventory);
+    markEmptyPacks(plan, inventory.packs);
+    plan.bytes_after =
+        inventory.total_bytes - plan.deleted_bytes - plan.empty_pack_manifest_bytes;
+    // Over the cap is only "blocked by uncommitted" when uncommitted bytes are
+    // what is left. Over the cap with nothing unvouched on disk is a different
+    // sentence — the remaining manifests alone exceed it — and saying the wrong
+    // one would send an operator hunting evidence that is not missing.
+    const unvouched = plan.kept_uncommitted.count + plan.kept_unknown.count;
+    plan.cap_blocked_by_uncommitted = plan.bytes_after > capBytes && unvouched > 0;
+    plan.cap_blocked_count = plan.cap_blocked_by_uncommitted ? unvouched : 0;
+    return plan;
+}
+/**
+ * The oldest committed spares go until the total fits, newest kept last. Sorted
+ * by the ledger's `committed_at` age rather than a file mtime: mtime moves when
+ * a pack is refilled, and the question here is how long ago the bytes became
+ * safe elsewhere.
+ *
+ * It does not run at all when the floor is already above the cap. That branch
+ * is not theoretical: on the reference Mac (2026-09-05) 8.0 GB of staging is
+ * evidence no ledger vouches for, against a 2 GB cap, so spending the retry
+ * window on 1,027 committed spares would have deleted a day of local retry
+ * copies and still ended over the cap. The cap takes a spare only when taking
+ * it can actually get this machine under the cap.
+ */
+function applyByteCap(plan, committedInWindow, capBytes, inventory) {
+    let projected = plan.bytes_before - plan.deleted_bytes;
+    if (projected <= capBytes)
+        return;
+    if (unremovableFloor(inventory) >= capBytes)
+        return;
+    const oldestFirst = [...committedInWindow].sort((a, b) => b.age_ms - a.age_ms);
+    for (const object of oldestFirst) {
+        if (projected <= capBytes)
+            break;
+        pushDeletion(plan, object, "cap_committed_oldest_first");
+        removeFromBucket(plan.kept_in_window, object);
+        projected -= object.byte_size;
+    }
+}
+/**
+ * Bytes no retention rule may take: every object the ledger does not vouch for,
+ * plus the `manifest.json` of each pack holding one, because that pack survives
+ * whatever else is deleted from it.
+ */
+function unremovableFloor(inventory) {
+    let floor = 0;
+    for (const pack of inventory.packs) {
+        const unvouched = pack.objects.filter((object) => object.state !== "committed");
+        if (unvouched.length === 0)
+            continue;
+        floor += pack.manifest_bytes;
+        for (const object of unvouched)
+            floor += object.byte_size;
+    }
+    return floor;
+}
+/**
+ * A pack with no payload left is deleted whole, `manifest.json` included. The
+ * manifest is pack metadata — its only job is to describe files that are no
+ * longer there — and on the reference Mac those manifests were 836 MB across
+ * 1,612 packs, so leaving them behind would keep almost a gigabyte of
+ * descriptions of nothing.
+ */
+function markEmptyPacks(plan, packs) {
+    const deleted = new Set(plan.delete.map((entry) => `${entry.pack_id}/${entry.relative_path}`));
+    for (const pack of packs) {
+        const survives = pack.objects.some((object) => !deleted.has(`${pack.pack_id}/${object.relative_path}`));
+        if (survives)
+            continue;
+        plan.empty_packs.push({
+            pack_id: pack.pack_id,
+            manifest_bytes: pack.manifest_bytes,
+        });
+        plan.empty_pack_manifest_bytes += pack.manifest_bytes;
+    }
+}
+function keepUnvouched(plan, object) {
+    const bucket = object.state === "unknown" ? plan.kept_unknown : plan.kept_uncommitted;
+    addToBucket(bucket, object);
+}
+function pushDeletion(plan, object, reason) {
+    plan.delete.push({
+        pack_id: object.pack_id,
+        relative_path: object.relative_path,
+        byte_size: object.byte_size,
+        content_hash: object.content_hash,
+        reason,
+        age_ms: object.age_ms,
+    });
+    plan.deleted_bytes += object.byte_size;
+}
+function addToBucket(bucket, object) {
+    bucket.count += 1;
+    bucket.bytes += object.byte_size;
+    bucket.oldest_age_ms = Math.max(bucket.oldest_age_ms, object.age_ms);
+}
+function removeFromBucket(bucket, object) {
+    bucket.count -= 1;
+    bucket.bytes -= object.byte_size;
+}
+function emptyPlan(capBytes, retentionMs, bytesBefore) {
+    const bucket = () => ({ count: 0, bytes: 0, oldest_age_ms: 0 });
+    return {
+        delete: [],
+        deleted_bytes: 0,
+        empty_packs: [],
+        empty_pack_manifest_bytes: 0,
+        kept_uncommitted: bucket(),
+        kept_unknown: bucket(),
+        kept_in_window: bucket(),
+        cap_bytes: capBytes,
+        retention_ms: retentionMs,
+        bytes_before: bytesBefore,
+        bytes_after: bytesBefore,
+        cap_blocked_by_uncommitted: false,
+        cap_blocked_count: 0,
+    };
+}

package/dist/disk-usage.js

@@ -0,0 +1,392 @@
+/**
+ * What this laptop is actually holding, and which of it the upload ledger can
+ * vouch for.
+ *
+ * BLI-3619. Measured on the reference Mac 2026-09-05, not estimated:
+ * `~/.local/state/bli-cockpit/raw-evidence` held 1,612 pack directories,
+ * 5,776 payload files and 18.76 GB, plus 836 MB of `manifest.json` beside them
+ * — 20 GB of staging on a machine whose whole job is to upload it and move on.
+ * The collector staged raw evidence, uploaded it, committed it, and then kept
+ * the local copy forever.
+ *
+ * Nothing here deletes anything. This module answers ONE question per file —
+ * "does a ledger on this machine say these bytes are durable remotely?" — and
+ * the answer has three values, not two, because the honest third one is what
+ * the same probe turned up:
+ *
+ *   committed              the content hash is in `cursors/raw-evidence.json`
+ *                          `objects`, so it is durable remotely and the local
+ *                          copy is a spare.
+ *   uncommitted            the hash is absent AND the ledger's own memory
+ *                          reaches back past this object, so the ledger CAN
+ *                          speak about it and says no. Never deleted.
+ *   unknown                the ledger cannot answer: its `objects` map is
+ *                          capped at 5,000 rows and prunes the oldest, so on
+ *                          the reference Mac it only reached back to
+ *                          2026-08-28 while 518 packs (7.93 GB) predate that.
+ *                          Also never deleted — but counted apart, because
+ *                          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
+ * file its own manifest does not name is hashed instead, under a byte budget
+ * (3 such files, 37 MB, on the reference Mac); past the budget it stays
+ * `unknown` with a reason rather than being guessed at.
+ *
+ * Metadata only: pack ids, pack-relative paths, byte counts, hashes, reason
+ * labels. Never a person's absolute path and never a byte of content.
+ */
+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";
+/** Bytes this inventory may spend hashing files no manifest names. */
+export const UNNAMED_FILE_HASH_BUDGET_BYTES = 256 * 1024 * 1024;
+/** Directory name of the staged raw-evidence tree under the state directory. */
+export const RAW_EVIDENCE_DIR = "raw-evidence";
+/** One-off evidence vaults a person made by hand; named, never auto-deleted. */
+export const MANUAL_VAULT_PREFIX = "manual-study-evidence-vault-";
+/**
+ * Everything on this machine Cockpit put there, in one read. Used by the sync
+ * tick's prune, by `cockpit clean` and by `cockpit doctor`'s disk row, so all
+ * three quote the same numbers rather than three near-misses.
+ */
+export async function readDiskFootprint(paths, now = new Date()) {
+    return {
+        staging: await readStagingInventory(paths, now),
+        logs: await rotatedLogFootprint(paths),
+        spool_bytes: await directoryBytes(paths.spool_dir),
+        vaults: await readManualVaults(paths),
+    };
+}
+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 })
+        .catch(() => []);
+    const inventory = emptyStagingInventory();
+    const budget = { remaining: UNNAMED_FILE_HASH_BUDGET_BYTES };
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const dir = path.join(root, entry.name);
+        if (entry.name.startsWith(".staging-")) {
+            inventory.orphan_staging_dirs += 1;
+            inventory.orphan_staging_bytes += await directoryBytes(dir);
+            continue;
+        }
+        if (!entry.name.startsWith("work-"))
+            continue;
+        const pack = await readPack(dir, entry.name, {
+            ledger,
+            reconciled,
+            stagedAt,
+            now,
+            budget,
+        });
+        inventory.packs.push(pack);
+        accumulatePack(inventory, pack);
+    }
+    return inventory;
+}
+/**
+ * The commit record, read from the one place that writes it: the raw-evidence
+ * cursor's `objects` map (`upload.ts` → `markObjectCommitted`, only ever for an
+ * outcome that was not `upload_failed`).
+ */
+async function readCommitLedger(paths) {
+    const cursor = await readRawEvidenceCursor(paths);
+    const committed = new Map();
+    let oldest = null;
+    for (const [hash, entry] of Object.entries(cursor.objects)) {
+        committed.set(hash, entry.committed_at);
+        if (!oldest || entry.committed_at.localeCompare(oldest) < 0) {
+            oldest = entry.committed_at;
+        }
+    }
+    return { committed, reachesBackTo: oldest };
+}
+/** `pack_id/relative_path` → when this machine staged those bytes. */
+async function readStagedAtIndex(paths) {
+    const staging = await readRawEvidenceStagingState(paths.state_dir);
+    const index = new Map();
+    for (const entry of Object.values(staging.staged)) {
+        index.set(`${entry.pack_id}/${entry.relative_path}`, entry.staged_at);
+    }
+    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 = {
+        pack_id: packId,
+        objects: [],
+        manifest_bytes: 0,
+        manifest_present: manifest !== null,
+    };
+    for (const relative of await listPackFiles(dir)) {
+        const size = await fs
+            .stat(path.join(dir, relative))
+            .then((info) => (info.isFile() ? info.size : 0))
+            .catch(() => 0);
+        if (relative === "manifest.json") {
+            pack.manifest_bytes += size;
+            continue;
+        }
+        pack.objects.push(await classifyObject(dir, packId, relative, size, manifest, options));
+    }
+    return pack;
+}
+async function classifyObject(dir, packId, relative, size, manifest, options) {
+    const hash = manifest?.get(relative) ??
+        (await hashUnnamedFile(path.join(dir, relative), size, options.budget));
+    const stagedAt = options.stagedAt.get(`${packId}/${relative}`) ?? null;
+    const committedAt = hash ? options.ledger.committed.get(hash) : undefined;
+    const base = { pack_id: packId, relative_path: relative, byte_size: size };
+    if (committedAt) {
+        return {
+            ...base,
+            content_hash: hash ?? null,
+            state: "committed",
+            reason: "committed_in_ledger",
+            decided_at: committedAt,
+            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,
+        content_hash: hash ?? null,
+        state: unknownReason ? "unknown" : "uncommitted",
+        reason: unknownReason ?? "absent_from_ledger",
+        decided_at: stagedAt,
+        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".
+ *
+ * The `objects` map is capped at 5,000 rows and drops the oldest, so anything
+ * staged before the oldest row it still holds is outside its memory. Saying
+ * "uncommitted" there would be a claim the ledger never made.
+ */
+function unknownStateReason(hash, manifest, stagedAt, options) {
+    if (!manifest)
+        return "manifest_unreadable";
+    if (!hash)
+        return "no_manifest_row";
+    const reachesBackTo = options.ledger.reachesBackTo;
+    if (!reachesBackTo)
+        return "ledger_empty";
+    if (stagedAt && stagedAt.localeCompare(reachesBackTo) < 0) {
+        return "ledger_evicted";
+    }
+    if (!stagedAt)
+        return "ledger_evicted";
+    return null;
+}
+/**
+ * A file its own manifest does not name gets hashed — but only while the run's
+ * byte budget lasts. Past it the object stays `unknown` and says which budget
+ * ran out, because reading 20 GB to answer a housekeeping question is how the
+ * old GC earned its once-a-day throttle.
+ */
+async function hashUnnamedFile(file, size, budget) {
+    if (size > budget.remaining)
+        return null;
+    const bytes = await fs.readFile(file).catch(() => null);
+    if (!bytes)
+        return null;
+    budget.remaining -= bytes.byteLength;
+    return crypto.createHash("sha256").update(bytes).digest("hex");
+}
+async function readManifestIndex(dir) {
+    const raw = await fs
+        .readFile(path.join(dir, "manifest.json"), "utf8")
+        .catch(() => null);
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        const index = new Map();
+        for (const file of parsed.files ?? []) {
+            if (typeof file.relative_path === "string" &&
+                typeof file.content_hash_sha256 === "string" &&
+                file.content_hash_sha256.length === 64) {
+                index.set(file.relative_path, file.content_hash_sha256);
+            }
+        }
+        return index;
+    }
+    catch (error) {
+        // Named, not swallowed: an unreadable manifest turns every file in the
+        // pack into `unknown`, which is the difference between a pack that gets
+        // pruned and one that is kept forever (BLI-3238's rule, BLI-3619's cost).
+        console.error("[collector disk] pack manifest unreadable, its files cannot be classified", JSON.stringify({
+            reason: "manifest_unreadable",
+            pack_id: path.basename(dir),
+            ...describeError(error),
+        }));
+        return null;
+    }
+}
+async function listPackFiles(dir) {
+    const files = [];
+    const stack = [{ dir, prefix: "" }];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (!current)
+            continue;
+        const entries = await fs
+            .readdir(current.dir, { withFileTypes: true })
+            .catch(() => []);
+        for (const entry of entries) {
+            const relative = current.prefix
+                ? `${current.prefix}/${entry.name}`
+                : entry.name;
+            if (entry.isDirectory()) {
+                stack.push({ dir: path.join(current.dir, entry.name), prefix: relative });
+            }
+            else if (entry.isFile()) {
+                files.push(relative);
+            }
+        }
+    }
+    return files;
+}
+async function readManualVaults(paths) {
+    const entries = await fs
+        .readdir(paths.state_dir, { withFileTypes: true })
+        .catch(() => []);
+    const vaults = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory() || !entry.name.startsWith(MANUAL_VAULT_PREFIX)) {
+            continue;
+        }
+        const dir = path.join(paths.state_dir, entry.name);
+        vaults.push({
+            name: entry.name,
+            byte_size: await directoryBytes(dir),
+            file_count: (await listPackFiles(dir)).length,
+        });
+    }
+    return vaults;
+}
+export async function directoryBytes(dir) {
+    let total = 0;
+    for (const relative of await listPackFiles(dir)) {
+        const info = await fs.stat(path.join(dir, relative)).catch(() => null);
+        total += info?.isFile() ? info.size : 0;
+    }
+    return total;
+}
+function accumulatePack(inventory, pack) {
+    inventory.pack_count += 1;
+    inventory.manifest_bytes += pack.manifest_bytes;
+    inventory.total_bytes += pack.manifest_bytes;
+    for (const object of pack.objects) {
+        inventory.object_count += 1;
+        inventory.total_bytes += object.byte_size;
+        if (object.state === "committed") {
+            inventory.committed_count += 1;
+            inventory.committed_bytes += object.byte_size;
+            continue;
+        }
+        if (object.state === "unknown") {
+            inventory.unknown_count += 1;
+            inventory.unknown_bytes += object.byte_size;
+            continue;
+        }
+        inventory.uncommitted_count += 1;
+        inventory.uncommitted_bytes += object.byte_size;
+        if (object.decided_at &&
+            (!inventory.oldest_uncommitted_at ||
+                object.decided_at.localeCompare(inventory.oldest_uncommitted_at) < 0)) {
+            inventory.oldest_uncommitted_at = object.decided_at;
+        }
+    }
+}
+function emptyStagingInventory() {
+    return {
+        pack_count: 0,
+        object_count: 0,
+        total_bytes: 0,
+        committed_count: 0,
+        committed_bytes: 0,
+        uncommitted_count: 0,
+        uncommitted_bytes: 0,
+        oldest_uncommitted_at: null,
+        unknown_count: 0,
+        unknown_bytes: 0,
+        manifest_bytes: 0,
+        orphan_staging_dirs: 0,
+        orphan_staging_bytes: 0,
+        packs: [],
+    };
+}
+function ageMs(at, now) {
+    if (!at)
+        return 0;
+    const parsed = Date.parse(at);
+    return Number.isFinite(parsed) ? Math.max(0, now.getTime() - parsed) : 0;
+}