@bli-cockpit/cli 0.2.93 → 0.2.95

package/dist/commands/sync.js

@@ -1,20 +1,44 @@
+/**
+ * `cockpit sync` — the tick. Every fifteen minutes on a fleet machine, and by
+ * hand whenever somebody types it.
+ *
+ * Read `runSync` below as the table of contents. It is the tick's steps, in
+ * order, and every part of this command lives in exactly one of them:
+ *
+ *   rotate the scheduler's own logs   ../log-rotation.ts
+ *   say the tick started              reportTickStarted, below
+ *   collect behind both locks         sync-receipt.ts
+ *   check in with the heartbeat door  sync-heartbeat.ts
+ *   say how the tick went             reportTickOutcome / reportTickThrew
+ *   converge the rest of the machine  sync-followups.ts
+ *
+ * The supporting modules each own one thing those steps share:
+ *
+ *   sync-types.ts      the shapes each step hands the next
+ *   sync-roots.ts      which approved roots this tick may collect
+ *   sync-heartbeat.ts  the check-in itself, and the backlog it carries
+ *   sync-receipt.ts    the two locks, and the receipt the run earns
+ *   sync-run.ts        the runbook under the lock: dedup, discover, sync
+ *   sync-report.ts     the three shapes a finished run is reported in
+ *
+ * Both arms below do the same things in the same order, because a tick that
+ * THREW is still a tick a machine survived and the fleet has to be able to tell
+ * that from silence (BLI-3551). The one difference is the staging prune, which
+ * the throwing arm has never run.
+ *
+ * Split out of commands/local.ts (BLI-3578), then into the siblings above
+ * (BLI-3982). The scan and upload engine underneath is `./session-sync.ts`;
+ * what a run reports is `./collection-report.ts`. A new sibling must also join
+ * `scripts/build-public-cli.mjs` `runtimeFiles`, or the repo tests stay green
+ * while the packed CLI breaks.
+ */
 import { runMemoryExperienceAfterSync } from "./memory-log.js";
-import { writeLine } from "./cli-io.js";
-import { attributedSyncRunStatus, cursorStatusLine, displayTicketId, rawEvidenceSyncLine, shortSha, worktreeSyncRow, writeAgentSessionSummary, } from "./collection-report.js";
-import { collectionRootConsentAliases } from "./collection-roots.js";
-import { discoverCommandWorktrees } from "./local-discovery.js";
-import { sendCollectorHeartbeatBestEffort, readHeartbeatStagingFacts, } from "./heartbeat.js";
-import { classifySyncFailureRecords, classifySyncHealthError, redactedSyncErrorDetail, reportInstallEventsBestEffort, } from "./install-receipts.js";
-import { runAttributedWorktreeSync, } from "./session-sync.js";
+import { classifySyncHealthError, redactedSyncErrorDetail, reportInstallEventsBestEffort, } from "./install-receipts.js";
+import { sendSyncHeartbeat } from "./sync-heartbeat.js";
+import { runSyncWithHealthReceipt } from "./sync-receipt.js";
 import { runAutostartSelfHealAfterSync, runMemoryInstallAfterSync, runScheduledSelfUpdateAfterSync, runStagingPruneAfterSync, } from "./sync-followups.js";
-import { describeError } from "../health-detail.js";
-import { inspectBackfillLock } from "../backfill-lock.js";
 import { rotateCollectorLogsBestEffort } from "../log-rotation.js";
 import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths, readLocalCollectorConfig, } from "../local-state.js";
-import { CollectionRootRequiredError, } from "../onboarding-roots.js";
-import { rawEvidenceDedupSummary, rawEvidenceGcSummary, runRawEvidenceLocalGc, sweepDuplicateStagedRawEvidence, } from "../raw-evidence-gc.js";
-import { normalizeCollectionRoots } from "../root-normalization.js";
-import { acquireSyncLock } from "../sync-lock.js";
 export async function runSync(command, io) {
     const paths = getCollectorRuntimePaths(command.homeDir);
     // BLI-3553, first thing in the tick: cap the scheduler's own logs. Nothing
@@ -22,38 +46,16 @@ export async function runSync(command, io) {
     // sync.log on the reference Mac. Best-effort by construction — a rotation
     // problem is its own log line, never a reason collection does not run.
     await rotateCollectorLogsBestEffort(paths);
-    const config = await readLocalCollectorConfig(paths).catch(() => null);
-    const dashboardUrl = command.dashboardUrl ?? config?.dashboard_url ?? DEFAULT_DASHBOARD_URL;
-    const minCliVersionAtStart = await reportInstallEventsBestEffort({
-        homeDir: command.homeDir,
-        dashboardUrl,
-        command: "sync",
-        events: [{ step: "sync_started", status: "ok" }],
-        json: command.json,
-        io,
-    });
+    const dashboardUrl = await tickDashboardUrl(command, paths);
+    const minCliVersionAtStart = await reportTickStarted(command, io, dashboardUrl);
     try {
         const result = await runSyncWithHealthReceipt(command, io);
         // BLI-3551: every tick checks in, including one that collected nothing.
         // This is the only writer of `last_seen_at` that does not need an envelope,
         // so it is what separates a quiet machine from a dead one.
         await sendSyncHeartbeat(command, io, dashboardUrl, result.heartbeat);
-        const minCliVersion = await reportInstallEventsBestEffort({
-            homeDir: command.homeDir,
-            dashboardUrl,
-            command: "sync",
-            events: [result.completion],
-            json: command.json,
-            io,
-        });
-        // BLI-2601: self-update runs only after collection's own outcome above is
-        // already decided and reported, win or lose. See the function doc.
-        await runScheduledSelfUpdateAfterSync(command, io, dashboardUrl, minCliVersion ?? minCliVersionAtStart);
-        await runAutostartSelfHealAfterSync(command, io, dashboardUrl);
-        // BLI-3580: BLI Memory's registration converges the same way — after
-        // collection, at most once a day, its own receipt either way.
-        await runMemoryInstallAfterSync(command, io, dashboardUrl);
-        await runMemoryExperienceAfterSync({ ...command, dashboardUrl }, io);
+        const minCliVersion = await reportTickOutcome(command, io, dashboardUrl, result.completion);
+        await convergeAfterTick(command, io, dashboardUrl, minCliVersion ?? minCliVersionAtStart);
         // BLI-3619: and the disk stops growing without bound — same daily cadence,
         // same rule that a follow-up never blocks or fails collection.
         await runStagingPruneAfterSync(command, io, dashboardUrl);
@@ -68,341 +70,76 @@ export async function runSync(command, io) {
             status: "fail",
             reason: errorCode,
         });
-        const minCliVersion = await reportInstallEventsBestEffort({
-            homeDir: command.homeDir,
-            dashboardUrl,
-            command: "sync",
-            events: [
-                {
-                    step: "sync_complete",
-                    status: "fail",
-                    error_code: errorCode,
-                    error_detail: redactedSyncErrorDetail(error),
-                },
-            ],
-            json: command.json,
-            io,
-        });
-        await runScheduledSelfUpdateAfterSync(command, io, dashboardUrl, minCliVersion ?? minCliVersionAtStart);
-        await runAutostartSelfHealAfterSync(command, io, dashboardUrl);
-        // BLI-3580: BLI Memory's registration converges the same way — after
-        // collection, at most once a day, its own receipt either way.
-        await runMemoryInstallAfterSync(command, io, dashboardUrl);
-        await runMemoryExperienceAfterSync({ ...command, dashboardUrl }, io);
+        const minCliVersion = await reportTickThrew(command, io, dashboardUrl, error, errorCode);
+        await convergeAfterTick(command, io, dashboardUrl, minCliVersion ?? minCliVersionAtStart);
         throw error;
     }
 }
+/** Where this tick reports: what the operator typed, else what it was paired to. */
+async function tickDashboardUrl(command, paths) {
+    const config = await readLocalCollectorConfig(paths).catch(() => null);
+    return command.dashboardUrl ?? config?.dashboard_url ?? DEFAULT_DASHBOARD_URL;
+}
 /**
- * The tick's check-in (BLI-3551).
+ * Say the tick started, and learn the floor while asking.
  *
- * Resolving the roots is best-effort on purpose: a machine with NO approved
- * root is exactly the machine whose silence needs explaining, so it still
- * checks in — with an empty root list, which is itself the finding.
+ * The reply carries `min_cli_version`, which is what the self-update follow-up
+ * needs; a tick that never reaches its own completion receipt still has this
+ * one to fall back on (BLI-2678).
  */
-async function sendSyncHeartbeat(command, io, dashboardUrl, facts) {
-    const roots = await resolveSyncCollectionRoots(command).catch(() => []);
-    // BLI-3797: the backlog figure rides the same check-in as the root labels, so
-    // `cockpit ops` learns about undelivered evidence on the SAME tick that proves
-    // the machine is alive. Best-effort: nulls omit the fields rather than
-    // reporting a zero nobody measured.
-    const staging = await readHeartbeatStagingFacts({
+async function reportTickStarted(command, io, dashboardUrl) {
+    return reportInstallEventsBestEffort({
         homeDir: command.homeDir,
-    }).catch(() => ({ bytes: null, reason: null }));
-    await sendCollectorHeartbeatBestEffort({
+        dashboardUrl,
+        command: "sync",
+        events: [{ step: "sync_started", status: "ok" }],
+        json: command.json,
+        io,
+    });
+}
+/** Post the receipt the run earned, whatever it says. */
+async function reportTickOutcome(command, io, dashboardUrl, completion) {
+    return reportInstallEventsBestEffort({
         homeDir: command.homeDir,
         dashboardUrl,
-        roots,
-        facts: {
-            ...facts,
-            stagingUncommittedBytes: staging.bytes,
-            stagingUncommittedReason: staging.reason,
-        },
+        command: "sync",
+        events: [completion],
+        json: command.json,
         io,
-    }).catch((error) => {
-        // The sender already swallows everything it knows about; this is the net
-        // for anything it does not, because a heartbeat must never fail a sync.
-        console.error("[heartbeat] the check-in threw and was dropped", JSON.stringify({ reason: "heartbeat_threw", ...describeError(error) }));
-        return false;
     });
 }
-async function runSyncWithHealthReceipt(command, io) {
-    const backfillLock = await inspectBackfillLock(getCollectorRuntimePaths(command.homeDir));
-    if (backfillLock.held) {
-        if (command.json) {
-            writeLine(io.stdout, JSON.stringify({
-                status: "live_sync_paused_during_backfill",
-                reason: "live sync paused during backfill",
-                held_since: backfillLock.held_since,
-                collection_complete: false,
-                upload_state: "not_uploaded",
-                retryable: true,
-            }, null, 2));
-        }
-        else {
-            writeLine(io.stdout, "Pausing normal sync while it catches up on old sessions.");
-        }
-        return {
-            exitCode: 0,
-            completion: {
-                step: "sync_complete",
-                status: "skipped",
-                error_code: "live_sync_paused_during_backfill",
-            },
-            heartbeat: {
-                status: "skipped",
-                reason: "live_sync_paused_during_backfill",
-            },
-        };
-    }
-    // Single-flight: a launchd timer and a manual sync must not interleave the
-    // cursor read-modify-write. A blocked invocation exits cleanly (B.4 §7).
-    const lock = await acquireSyncLock(getCollectorRuntimePaths(command.homeDir));
-    if (!lock.acquired) {
-        if (command.json) {
-            writeLine(io.stdout, JSON.stringify({
-                status: "sync_already_running",
-                reason: "another sync owns the collection lock",
-                held_since: lock.held_since,
-                collection_complete: false,
-                upload_state: "not_uploaded",
-                retryable: true,
-            }, null, 2));
-        }
-        else {
-            writeLine(io.stdout, "Tower sync already running; skipping this run.");
-        }
-        return {
-            exitCode: 0,
-            completion: {
-                step: "sync_complete",
-                status: "skipped",
-                error_code: "sync_already_running",
-            },
-            heartbeat: { status: "skipped", reason: "sync_already_running" },
-        };
-    }
-    try {
-        const { exitCode, failureReasons, failureRecords, notice, sessionsObserved, sessionsOutsideRoot, sessionsNewThisTick, sessionsPendingUpload, } = await runSyncLocked(command, io);
-        const counts = {
-            sessionsObserved,
-            sessionsOutsideRoot,
-            sessionsNewThisTick,
-            sessionsPendingUpload,
-        };
-        if (exitCode === 0) {
-            // BLI-3551: an `ok` tick can still have something to say. `nothing_in_root`
-            // is the receipt that separates "this machine is alive and its operator
-            // works outside the approved roots" from "this machine is dead", which
-            // until now looked identical from the dashboard.
-            return {
-                exitCode,
-                completion: {
-                    step: "sync_complete",
-                    status: "ok",
-                    ...(notice ? { error_detail: notice } : {}),
-                },
-                heartbeat: { status: "ok", reason: notice, ...counts },
-            };
-        }
-        // A sync that fails by exit code says exactly as much as one that throws.
-        // It used to say `sync_failed` and nothing else, so 100% of recorded
-        // failure rows carried a null detail and the real reason was reachable only
-        // by running `cockpit status` on the machine itself (BLI-2526).
-        const reasonText = failureReasons.join("; ");
-        // The bucket comes from the records the deciding branches wrote, not from
-        // this sentence (BLI-3551). The sentence is still the detail.
-        const errorCode = classifySyncFailureRecords(failureRecords);
-        return {
-            exitCode,
-            completion: {
+/**
+ * Post a receipt for a tick that threw before it could earn one.
+ *
+ * The bucket is the classifier's, the detail is the redacted error: a receipt
+ * that can only say "failed" is one nobody can act on (BLI-2526).
+ */
+async function reportTickThrew(command, io, dashboardUrl, error, errorCode) {
+    return reportInstallEventsBestEffort({
+        homeDir: command.homeDir,
+        dashboardUrl,
+        command: "sync",
+        events: [
+            {
                 step: "sync_complete",
                 status: "fail",
                 error_code: errorCode,
-                error_detail: redactedSyncErrorDetail(reasonText),
+                error_detail: redactedSyncErrorDetail(error),
             },
-            heartbeat: { status: "fail", reason: errorCode, ...counts },
-        };
-    }
-    finally {
-        await lock.handle.release();
-    }
-}
-/**
- * Turn a finished run into an exit code and the reasons behind it.
- *
- * One place, so a future return path cannot reintroduce a code with no reason.
- * The reasons come from the run itself — the code that decided `ok` is false is
- * the only code that knows why.
- */
-function syncResult(run) {
-    return {
-        exitCode: run.ok ? 0 : 1,
-        failureReasons: run.ok ? [] : run.failure_reasons,
-        failureRecords: run.ok ? [] : run.failure_records,
-        notice: run.notice,
-        sessionsObserved: run.sessions_observed,
-        sessionsOutsideRoot: run.sessions_outside_root,
-        sessionsNewThisTick: run.sessions_new_this_tick,
-        sessionsPendingUpload: run.sessions_pending_upload,
-    };
+        ],
+        json: command.json,
+        io,
+    });
 }
 /**
- * The sync runbook: resolve which roots to collect, dedup staged packs before
- * touching anything else, discover worktrees, sync them, then report — one of
- * three shapes depending on how many worktrees came back. The three shapes
- * share nothing but `dedup`, so each gets its own step function below rather
- * than one branchy body.
+ * Everything the tick converges after its own outcome is already decided and
+ * reported, win or lose (BLI-2601): the CLI floor, the scheduler, and BLI
+ * Memory's registration — each at most once a day, each with its own receipt,
+ * and none of them able to block or fail collection (BLI-3580).
  */
-async function runSyncLocked(command, io) {
-    const collectionRoots = await resolveSyncCollectionRoots(command);
-    // Before anything is collected: collapse byte-identical staged packs. It runs
-    // first, unconditionally and unthrottled, because a machine that already
-    // holds 559 copies of one rollout needs the disk back before it stages
-    // anything else (BLI-3066). Safe by construction — a duplicate is identical
-    // by content hash to the survivor.
-    const dedup = await sweepDuplicateStagedRawEvidence(getCollectorRuntimePaths(command.homeDir), io.env);
-    if (!dedup.skipped && dedup.removed_dirs > 0) {
-        writeLine(io.stdout, rawEvidenceDedupSummary(dedup));
-    }
-    const worktrees = await discoverCommandWorktrees(collectionRoots, {
-        maxDepth: command.maxDepth,
-        maxRepos: command.maxRepos,
-        homeDir: command.homeDir,
-        allowEmpty: true,
-    }, io);
-    const run = await runAttributedWorktreeSync({
-        homeDir: command.homeDir,
-        dashboardUrl: command.dashboardUrl,
-        collectionRoots,
-        startContexts: false,
-        worktrees,
-        fetchImpl: io.fetch,
-    });
-    if (run.outcomes.length > 1) {
-        return reportMultiRepoSync(command, io, run, dedup);
-    }
-    // Zero worktrees is a legitimate steady state, not a failure: an approved
-    // root can hold no git repos, and sessions upload independently of
-    // worktrees (session-first, BLI-2581). This used to throw "Sync produced no
-    // result", which painted ~90 false-red sync_failed receipts per day on one
-    // fleet machine with a single empty root and taught people to ignore
-    // sync_failed (BLI-2722). A genuinely broken run still fails via run.ok.
-    if (run.outcomes.length === 0) {
-        return reportNoWorktreeSync(command, io, run, dedup);
-    }
-    return reportSingleRepoSync(command, io, run, dedup);
-}
-async function reportMultiRepoSync(command, io, run, dedup) {
-    const rows = run.outcomes.map((outcome) => worktreeSyncRow(outcome, run));
-    const collectionRunStatus = attributedSyncRunStatus(run);
-    const gc = run.ok ? await runSyncRawEvidenceGc(command, io) : null;
-    if (command.json) {
-        writeLine(io.stdout, JSON.stringify({
-            mode: "multi_repo",
-            status: collectionRunStatus,
-            collection_complete: run.ok,
-            results: run.outcomes.map((outcome) => outcome.sync),
-            repos: rows,
-            codex_sessions: run.summary,
-            raw_evidence_gc: gc,
-            raw_evidence_dedup: dedup,
-        }, null, 2));
-        return syncResult(run);
-    }
-    writeLine(run.ok ? io.stdout : io.stderr, `Tower parent sync ${collectionRunStatus} ${run.outcomes.filter((outcome) => outcome.sync.status === "uploaded").length}/${run.outcomes.length} worktree(s).`);
-    for (const outcome of run.outcomes) {
-        const { worktree, sync } = outcome;
-        const uploaded = sync.status === "uploaded";
-        const failureSuffix = sync.status === "spooled" ? ` reason:${sync.failure_reason}` : "";
-        writeLine(uploaded ? io.stdout : io.stderr, `- ${worktree.repo_label}/${worktree.worktree_label} (${worktree.branch}) head:${shortSha(sync.head_sha ?? worktree.head_sha)} ${sync.status} objects:${sync.raw_evidence_uploaded_object_count} chunks:${sync.raw_evidence_uploaded_chunk_count} reused:${sync.raw_evidence_reused_count} failed:${sync.raw_evidence_failed_count} cursor:${sync.cursor_tracked_object_count}${failureSuffix}`);
-    }
-    writeAgentSessionSummary(io, run.summary);
-    if (gc && !gc.skipped)
-        writeLine(io.stdout, rawEvidenceGcSummary(gc));
-    return syncResult(run);
-}
-async function reportNoWorktreeSync(command, io, run, dedup) {
-    const collectionRunStatus = attributedSyncRunStatus(run);
-    const gc = run.ok ? await runSyncRawEvidenceGc(command, io) : null;
-    if (command.json) {
-        writeLine(io.stdout, JSON.stringify({
-            mode: "no_worktrees",
-            status: collectionRunStatus,
-            collection_complete: run.ok,
-            ...(run.notice ? { notice: run.notice } : {}),
-            codex_sessions: run.summary,
-            raw_evidence_gc: gc,
-            raw_evidence_dedup: dedup,
-        }, null, 2));
-        return syncResult(run);
-    }
-    writeLine(run.ok ? io.stdout : io.stderr, `Tower sync ${collectionRunStatus}: no git worktrees under this root; session scan ran.`);
-    if (run.notice) {
-        // Says out loud what the receipt now says to the dashboard: the sessions
-        // this machine ran were all outside the folders it is allowed to look at.
-        writeLine(io.stdout, `Every session seen this run was outside your approved folders (${run.notice}). Nothing was collected, and nothing is broken.`);
-    }
-    writeAgentSessionSummary(io, run.summary);
-    if (gc && !gc.skipped)
-        writeLine(io.stdout, rawEvidenceGcSummary(gc));
-    return syncResult(run);
-}
-async function reportSingleRepoSync(command, io, run, dedup) {
-    const result = run.outcomes[0]?.sync;
-    if (!result) {
-        throw new Error("Sync produced no result for the repo worktree.");
-    }
-    const collectionRunStatus = attributedSyncRunStatus(run);
-    const gc = run.ok ? await runSyncRawEvidenceGc(command, io) : null;
-    if (command.json) {
-        writeLine(io.stdout, JSON.stringify({
-            ...result,
-            status: collectionRunStatus,
-            collection_complete: run.ok,
-            codex_sessions: run.summary,
-            raw_evidence_gc: gc,
-            raw_evidence_dedup: dedup,
-        }, null, 2));
-        return syncResult(run);
-    }
-    if (run.ok) {
-        writeLine(io.stdout, "Tower uploaded this session.");
-        writeLine(io.stdout, `Ticket: ${displayTicketId(result.ticket_id)}`);
-        writeLine(io.stdout, `Context: ${result.work_context_id}`);
-        writeLine(io.stdout, `Head: ${shortSha(result.head_sha)}`);
-        writeLine(io.stdout, `Things recorded: ${result.event_count}`);
-        writeLine(io.stdout, `Risk flags: ${result.risk_flag_count}`);
-        writeLine(io.stdout, `Raw evidence files: ${result.raw_evidence_file_count}`);
-        writeLine(io.stdout, rawEvidenceSyncLine(result));
-        writeAgentSessionSummary(io, run.summary);
-        writeLine(io.stdout, cursorStatusLine(result));
-        if (gc && !gc.skipped)
-            writeLine(io.stdout, rawEvidenceGcSummary(gc));
-        return syncResult(run);
-    }
-    if (result.status === "uploaded") {
-        writeLine(io.stderr, "Tower uploaded, but some sessions did not make it. Run `cockpit sync` again.");
-        writeAgentSessionSummary(io, run.summary);
-        return syncResult(run);
-    }
-    writeLine(io.stderr, "Tower could not upload. It saved a note to retry and will try again on the next sync.");
-    writeLine(io.stderr, `Ticket: ${displayTicketId(result.ticket_id)}`);
-    writeLine(io.stderr, `Failure: ${result.failure_reason}`);
-    writeLine(io.stderr, `Retry: ${result.retry_command}`);
-    return syncResult(run);
-}
-async function resolveSyncCollectionRoots(command) {
-    const explicitRoots = normalizeCollectionRoots(command.repoRoot ? [command.repoRoot] : []);
-    if (explicitRoots.length > 0) {
-        return collectionRootConsentAliases(explicitRoots);
-    }
-    const config = await readLocalCollectorConfig(getCollectorRuntimePaths(command.homeDir)).catch(() => null);
-    const savedRoots = normalizeCollectionRoots(config?.default_repo_paths ?? []);
-    if (savedRoots.length > 0) {
-        return collectionRootConsentAliases(savedRoots);
-    }
-    throw new CollectionRootRequiredError(`no explicit or saved collection root is available.`);
-}
-async function runSyncRawEvidenceGc(command, io) {
-    return runRawEvidenceLocalGc(getCollectorRuntimePaths(command.homeDir), io.env);
+async function convergeAfterTick(command, io, dashboardUrl, minCliVersion) {
+    await runScheduledSelfUpdateAfterSync(command, io, dashboardUrl, minCliVersion);
+    await runAutostartSelfHealAfterSync(command, io, dashboardUrl);
+    await runMemoryInstallAfterSync(command, io, dashboardUrl);
+    await runMemoryExperienceAfterSync({ ...command, dashboardUrl }, io);
 }

package/dist/disk-usage-classify.js

@@ -0,0 +1,109 @@
+/**
+ * The three-state question, asked once per staged file: committed, uncommitted,
+ * or unknown — and the reason label that says which record answered.
+ *
+ * The order of the answers is the whole safety property. This machine's commit
+ * ledger wins first; a server answer an earlier `cockpit clean --reconcile`
+ * recorded wins next, because the server was actually asked; and only when
+ * neither can speak does the object fall to `unknown` with the reason its
+ * silence has. Everything downstream — what may be deleted, what is offered
+ * again, what an operator reads — is this label.
+ */
+import path from "node:path";
+import { hashUnnamedFile } from "./disk-usage-files.js";
+export 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,
+        staged_on_disk_at: options.stagedOnDiskAt,
+        disk_age_ms: ageMs(options.stagedOnDiskAt, options.now),
+    };
+    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;
+}
+/** How old a recorded moment is, with an unreadable one worth nothing. */
+function ageMs(at, now) {
+    if (!at)
+        return 0;
+    const parsed = Date.parse(at);
+    return Number.isFinite(parsed) ? Math.max(0, now.getTime() - parsed) : 0;
+}

package/dist/disk-usage-facts.js

@@ -0,0 +1,4 @@
+/** 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-";