@bli-cockpit/cli 0.2.50 → 0.2.52

package/dist/commands/memory-install.js

@@ -17,8 +17,10 @@
  *
  * - **Where the server is.** `bli-memory-mcp` ships as a DEPENDENCY of
  *   `@bli-cockpit/cli`, so the canonical lookup is the `node_modules/.bin` on
- *   the way up from this CLI's own entry point; PATH is the fallback. Nobody
- *   ever installs a second global package. See `resolveMemoryMcpBin`.
+ *   the way up from THIS MODULE's own file — realpath-ed first, because a
+ *   global `cockpit` is a symlink and walking up from the symlink finds
+ *   nothing; PATH is the fallback. Nobody ever installs a second global
+ *   package. See `resolveMemoryMcpBin`, which carries the receipt.
  * - **No server, no write.** If the bin does not resolve, not one file is
  *   opened and the outcome is `skipped bin_missing` — see `no_bin_no_write`
  *   below for why a written-but-inert registration is the worse option.
@@ -32,10 +34,12 @@
  * - **Never claim an install it did not read back** (BLI-2541). Both halves
  *   re-read and re-parse; this module only aggregates what they proved.
  */
+import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { writeLine } from "./cli-io.js";
-import { builtinMemoryInstallConfig, isUnsafeBinPath, MEMORY_MCP_BIN, parsePrintedMemoryInstallConfig, } from "./memory-install-contract.js";
+import { builtinMemoryInstallConfig, isUnsafeBinPath, MEMORY_MCP_BIN, parsePrintedMemoryInstallConfig, withResolvedBinPath, } from "./memory-install-contract.js";
 import { defaultMemoryFileIo, } from "./memory-install-files.js";
 import { installClaudeMemoryIntegration, inspectClaudeMemoryIntegration, } from "./memory-install-claude.js";
 import { installCodexMemoryIntegration, inspectCodexMemoryIntegration, } from "./memory-install-codex.js";
@@ -140,6 +144,7 @@ async function resolveMemoryConfig(command, io, platform, deps) {
         platform,
         fileExists: deps.fileExists,
         cliEntryPoint: deps.cliEntryPoint,
+        realpath: deps.realpath,
     });
     if (!found) {
         return {
@@ -172,10 +177,35 @@ async function resolveMemoryConfig(command, io, platform, deps) {
     }
     const printed = await printedMemoryConfig(io, found.path);
     if (printed) {
+        // The bin prints a BARE command name — it cannot know where it was
+        // installed, and it is nested inside the CLI's node_modules rather than on
+        // PATH. Path-qualifying it here is what makes the registration runnable at
+        // all; see `withResolvedBinPath`.
+        const qualified = withResolvedBinPath(printed, {
+            binPath: found.path,
+            platform,
+            dashboardUrl,
+        });
+        if (qualified) {
+            return {
+                config: qualified,
+                source: "bin",
+                binTarget: { target: "bin", status: "already", reason: "bin_printed_config" },
+                bin_source: found.source,
+            };
+        }
+        // A printed hook command this installer cannot re-point. The template is
+        // always path-qualified, so it is the safe answer — and the reason says
+        // which of the two fallbacks happened.
         return {
-            config: printed,
-            source: "bin",
-            binTarget: { target: "bin", status: "already", reason: "bin_printed_config" },
+            config: builtinMemoryInstallConfig({ binPath: found.path, platform, dashboardUrl }),
+            source: "template",
+            binTarget: {
+                target: "bin",
+                status: "already",
+                reason: "bin_printed_config_unqualifiable",
+                detail: "the bin printed a hook command this installer could not re-point at the resolved path; the built-in shape was used",
+            },
             bin_source: found.source,
         };
     }
@@ -222,12 +252,11 @@ async function printedMemoryConfig(io, binPath) {
  *
  * **1. Beside the CLI that is running.** `bli-memory-mcp` ships as a DEPENDENCY
  * of `@bli-cockpit/cli`, so installing the CLI installs the server, and npm
- * links its bin into a `node_modules/.bin` on the path from this entry point up
- * to the install root — `…/@bli-cockpit/cli/node_modules/.bin` when it is
- * nested, `…/lib/node_modules/.bin` when npm hoists it. Walking up from
- * `process.argv[1]` finds it either way, and it is the ONLY lookup that cannot
- * find somebody else's `bli-memory-mcp`. Nobody ever runs `npm i -g` for a
- * second package.
+ * links its bin into a `node_modules/.bin` on the path from this package up to
+ * the install root — `…/@bli-cockpit/cli/node_modules/.bin` when it is nested,
+ * `…/lib/node_modules/.bin` when npm hoists it. It is the ONLY lookup that
+ * cannot find somebody else's `bli-memory-mcp`. Nobody ever runs `npm i -g` for
+ * a second package.
  *
  * **2. PATH, as a fallback**, for a linked checkout or a hand-installed server.
  * Done in this process rather than through `which`/`where`: it spawns nothing,
@@ -236,6 +265,26 @@ async function printedMemoryConfig(io, binPath) {
  * standard layouts, which is why the caller passes a PATH that already includes
  * it (`envWithNodeRuntimeOnPath`) — the launchd tick's PATH is otherwise
  * `/usr/bin:/bin:/usr/sbin:/sbin` and would find nothing.
+ *
+ * **What step 1 got wrong on the first real machine** (BLI-3580, CLI 0.2.50):
+ * it walked up from `process.argv[1]`, resolved with `path.resolve` and no
+ * symlink following. For a global install `argv[1]` is the SHIM — on Edward's
+ * Mac `/opt/homebrew/bin/cockpit`, a symlink into
+ * `/opt/homebrew/lib/node_modules/@bli-cockpit/cli/dist/cli.js`. The walk
+ * therefore started in `/opt/homebrew/bin`, went up through `/opt` to `/`, and
+ * never came within reach of the nested `.bin` that was sitting right there.
+ * Every machine reported `skipped bin_missing` with the server installed.
+ *
+ * Two changes, both in `besideAnchors` / `resolveBesideCli`:
+ *
+ *  - The anchor is **this module's own file** first (`import.meta.url`), which
+ *    is inside the installed package by construction and is never a shim. The
+ *    entry point (injected, or `argv[1]`) stays as a second anchor for a build
+ *    layout where this module has been bundled somewhere else.
+ *  - Every anchor is **realpath-ed** before the walk, so a symlinked entry
+ *    lands in the real tree. A path that will not resolve is used as given —
+ *    the same bounded silence `container-tag.ts` uses, because a path that
+ *    cannot be realpath-ed still identifies a directory well enough to look in.
  */
 export async function resolveMemoryMcpBin(options) {
     const exists = options.fileExists ?? defaultFileExists;
@@ -245,28 +294,66 @@ export async function resolveMemoryMcpBin(options) {
     const onPath = await resolveOnPath(options, exists);
     return onPath ? { path: onPath, source: "path" } : null;
 }
-async function resolveBesideCli(options, exists) {
+/**
+ * Where to start walking, in order of trustworthiness. This module's own
+ * location first: it is inside the installed package and cannot be a shim.
+ */
+function besideAnchors(options) {
+    const anchors = [];
+    const own = currentModulePath();
+    if (own)
+        anchors.push(own);
     const entry = options.cliEntryPoint ?? process.argv[1];
-    if (!entry)
+    if (entry)
+        anchors.push(entry);
+    return anchors;
+}
+function currentModulePath() {
+    try {
+        return fileURLToPath(import.meta.url);
+    }
+    catch {
+        // A bundler that dropped `import.meta` support. The entry-point anchor
+        // still covers it, so this is a narrowing rather than a failure.
         return null;
+    }
+}
+async function resolveBesideCli(options, exists) {
     const platformPath = options.platform === "win32" ? path.win32 : path.posix;
     const extensions = binExtensions(options.platform);
-    let directory = platformPath.dirname(platformPath.resolve(entry));
-    // Bounded walk: deep enough for `…/node_modules/@scope/pkg/dist/cli.js` plus
-    // a hoisted root above it, and it stops at the filesystem root anyway.
-    for (let depth = 0; depth < 12; depth += 1) {
-        for (const extension of extensions) {
-            const candidate = platformPath.join(directory, "node_modules", ".bin", `${MEMORY_MCP_BIN}${extension}`);
-            if (await exists(candidate))
-                return candidate;
+    const realpath = options.realpath ?? defaultRealpath;
+    for (const anchor of besideAnchors(options)) {
+        let directory = platformPath.dirname(realpath(platformPath.resolve(anchor)));
+        // Bounded walk: deep enough for `…/node_modules/@scope/pkg/dist/cli.js`
+        // plus a hoisted root above it, and it stops at the filesystem root anyway.
+        for (let depth = 0; depth < 12; depth += 1) {
+            for (const extension of extensions) {
+                const candidate = platformPath.join(directory, "node_modules", ".bin", `${MEMORY_MCP_BIN}${extension}`);
+                if (await exists(candidate))
+                    return candidate;
+            }
+            const parent = platformPath.dirname(directory);
+            if (parent === directory)
+                break;
+            directory = parent;
         }
-        const parent = platformPath.dirname(directory);
-        if (parent === directory)
-            break;
-        directory = parent;
     }
     return null;
 }
+/**
+ * `realpathSync.native` follows the symlink npm writes for a global bin. A
+ * path that does not resolve — a Windows path being reasoned about from a Mac
+ * in a test, a directory that has since moved — comes back unchanged rather
+ * than throwing, because the walk above can still look inside it.
+ */
+function defaultRealpath(value) {
+    try {
+        return fs.realpathSync.native(value);
+    }
+    catch {
+        return value;
+    }
+}
 async function resolveOnPath(options, exists) {
     // The TARGET platform's path rules, not the running one's. On a real machine
     // they are the same; asking for them explicitly is what lets the Windows

package/dist/commands/public-root.js

@@ -15,7 +15,7 @@ export async function runCockpitCli(argv, io) {
   }
 
   if (command === "--version" || command === "-V" || command === "version") {
-    writeLine(io?.stdout ?? process.stdout, "0.2.50");
+    writeLine(io?.stdout ?? process.stdout, "0.2.52");
     return 0;
   }
 

package/dist/commands/sync-followups.js

@@ -1,8 +1,8 @@
 /**
  * What the sync tick does AFTER collection's own outcome is decided and
  * reported: keep this machine's CLI current on npm `latest` (BLI-2601), put a
- * broken scheduler registration back (BLI-2721), and keep BLI Memory
- * registered with both agent hosts (BLI-3580).
+ * broken scheduler registration back (BLI-2721), keep BLI Memory registered
+ * with both agent hosts (BLI-3580), and stop the laptop filling up (BLI-3619).
  *
  * Split out of commands/sync.ts (BLI-3578), moved verbatim. They belong
  * together because they share one rule, and it is the reason both are called
@@ -18,6 +18,7 @@ import { redactedSyncErrorDetail, reportInstallEventsBestEffort, } from "./insta
 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 { envWithNodeRuntimeOnPath, runScheduledSelfUpdate, } from "../scheduled-self-update.js";
 /**
  * BLI-2721: after the tick's collection and self-update are done and
@@ -183,6 +184,98 @@ function memoryInstallEvent(outcome) {
     }
     return { step: "memory_install", status: "ok", error_detail: detail };
 }
+/**
+ * BLI-3619: staged raw evidence Tower has already accepted stops living on the
+ * laptop forever.
+ *
+ * Same shape as the memory install above and for the same reasons: it runs only
+ * once collection's own outcome is decided and reported, at most once a day, it
+ * cannot throw, and its outcome is its own named receipt rather than a sync
+ * failure. A machine that cannot prune is a machine short of disk, and that
+ * must never also be a machine that stops collecting.
+ *
+ * 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.
+ */
+export async function runStagingPruneAfterSync(command, io, dashboardUrl, options = {}) {
+    let result;
+    try {
+        result = await runStagingPrune(getCollectorRuntimePaths(command.homeDir), {
+            env: io.env,
+            ...(options.now ? { now: options.now } : {}),
+        });
+    }
+    catch (error) {
+        // runStagingPrune already catches everything it can reach; this is the
+        // last-resort net so a prune crash truly cannot touch the sync result.
+        result = { ...prunedNothing(), reason: "prune_threw", status: "fail" };
+        console.error("[collector prune] the prune follow-up threw", JSON.stringify({
+            reason: "prune_followup_threw",
+            detail: redactedSyncErrorDetail(error),
+        }));
+    }
+    // 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")
+        return;
+    await reportInstallEventsBestEffort({
+        homeDir: command.homeDir,
+        dashboardUrl,
+        command: "sync",
+        events: [stagingPruneEvent(result)],
+        json: command.json,
+        io,
+    });
+}
+function prunedNothing() {
+    return {
+        status: "skipped",
+        reason: "prune_threw",
+        deleted_files: 0,
+        deleted_bytes: 0,
+        removed_packs: 0,
+        kept_uncommitted: 0,
+        kept_uncommitted_bytes: 0,
+        oldest_uncommitted_age_ms: 0,
+        kept_unknown: 0,
+        kept_unknown_bytes: 0,
+        kept_in_window: 0,
+        cap_bytes: 0,
+        bytes_before: 0,
+        bytes_after: 0,
+        cap_blocked_by_uncommitted: false,
+        cap_blocked_count: 0,
+        failed_deletions: 0,
+    };
+}
+/** Counts and byte totals only; no pack id and no path travels in a receipt. */
+function stagingPruneEvent(result) {
+    const detail = [
+        `freed ${result.deleted_bytes}B in ${result.deleted_files} file(s)`,
+        `held ${result.kept_uncommitted_bytes}B uncommitted`,
+        result.cap_blocked_by_uncommitted
+            ? `staging_cap_blocked_by_uncommitted ${result.cap_blocked_count}`
+            : null,
+        result.failed_deletions > 0
+            ? `failed_deletions ${result.failed_deletions}`
+            : null,
+    ]
+        .filter((part) => Boolean(part))
+        .join("; ");
+    if (result.status === "fail") {
+        return {
+            step: "staging_prune",
+            status: "fail",
+            error_code: result.reason,
+            error_detail: detail,
+        };
+    }
+    if (result.status === "skipped") {
+        return { step: "staging_prune", status: "skipped", error_code: result.reason };
+    }
+    return { step: "staging_prune", 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/commands/sync.js

@@ -5,7 +5,7 @@ import { discoverCommandWorktrees } from "./local-discovery.js";
 import { sendCollectorHeartbeatBestEffort, } from "./heartbeat.js";
 import { classifySyncFailureRecords, classifySyncHealthError, redactedSyncErrorDetail, reportInstallEventsBestEffort, } from "./install-receipts.js";
 import { runAttributedWorktreeSync, } from "./session-sync.js";
-import { runAutostartSelfHealAfterSync, runMemoryInstallAfterSync, runScheduledSelfUpdateAfterSync, } from "./sync-followups.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";
@@ -52,6 +52,9 @@ export async function runSync(command, io) {
         // 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);
+        // 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);
         return result.exitCode;
     }
     catch (error) {

package/dist/disk-prune.js

@@ -0,0 +1,246 @@
+/**
+ * Carrying out the retention plan, and saying what it did.
+ *
+ * BLI-3619. The decision is `disk-retention.ts` and the reading is
+ * `disk-usage.ts`; this file is the only one that removes a staged byte. Three
+ * properties it must keep:
+ *
+ * - **It never fails the tick.** Every path is caught. A prune that cannot run
+ *   is a log line, never a reason collection did not happen — the same rule the
+ *   log rotation and the two self-heal follow-ups already live under.
+ * - **It never deletes what the ledger did not vouch for.** The plan decides
+ *   that; this file does not second-guess it, and re-reads nothing.
+ * - **It says so on both branches.** `[collector prune]` fires on the boring
+ *   run too, because "0 deleted, 2.1 GB held, all committed" is the only
+ *   evidence that the drain is still running at all (the BLI-2528 lesson: what
+ *   only speaks on failure cannot answer "did anything work today?").
+ *
+ * Throttled to once a day by a marker file, the same idiom the raw-evidence GC,
+ * the scheduled self-update and the BLI Memory install use. Walking a pack tree
+ * is cheap; doing it every fifteen minutes for a decision that changes on the
+ * scale of hours is not.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { planStagingRetention, retentionOptionsFromEnv, } from "./disk-retention.js";
+import { RAW_EVIDENCE_DIR, readStagingInventory } from "./disk-usage.js";
+import { describeError } from "./health-detail.js";
+import { readRawEvidenceStagingState, writeRawEvidenceStagingState, } from "./raw-evidence-staging.js";
+export const STAGING_PRUNE_THROTTLE_MARKER = ".last-staging-prune";
+export const STAGING_PRUNE_MIN_INTERVAL_MS = 24 * 60 * 60 * 1000;
+/**
+ * The prune the sync tick runs and `cockpit clean` / `cockpit doctor` reuse.
+ * Never throws.
+ */
+export async function runStagingPrune(paths, options = {}) {
+    const env = options.env ?? process.env;
+    const now = options.now ?? new Date();
+    if (env["COCKPIT_DISABLE_GC"] === "1") {
+        return skippedResult("disabled");
+    }
+    if (!options.force && (await prunedRecently(paths, now))) {
+        return skippedResult("throttled_recent_run");
+    }
+    try {
+        if (!options.dryRun && !options.force)
+            await markPruned(paths, now);
+        const plan = await planFromDisk(paths, env, options, now);
+        const result = options.dryRun
+            ? dryRunResult(plan)
+            : await applyPlan(paths, plan);
+        reportPrune(result, { dryRun: Boolean(options.dryRun) });
+        return result;
+    }
+    catch (error) {
+        console.error("[collector prune] the prune could not run; nothing was deleted", JSON.stringify({ reason: "prune_threw", ...describeError(error) }));
+        return { ...skippedResult("prune_threw"), status: "fail" };
+    }
+}
+export async function planFromDisk(paths, env, options, now) {
+    const fromEnv = retentionOptionsFromEnv(env);
+    const inventory = await readStagingInventory(paths, now);
+    return planStagingRetention(inventory, {
+        retentionMs: options.retentionMs ?? fromEnv.retentionMs,
+        capBytes: options.capBytes ?? fromEnv.capBytes,
+        allCommitted: options.allCommitted,
+    });
+}
+async function applyPlan(paths, plan) {
+    const root = path.join(paths.state_dir, RAW_EVIDENCE_DIR);
+    const tally = { files: 0, bytes: 0, packs: 0, failed: 0, hashes: [] };
+    const removedPackIds = await removeEmptyPacks(root, plan, tally);
+    await removeRemainingFiles(root, plan, removedPackIds, tally);
+    await forgetStagedObjects(paths, tally.hashes);
+    return {
+        ...dryRunResult(plan),
+        status: "ok",
+        reason: tally.files > 0 ? "pruned" : "nothing_eligible",
+        deleted_files: tally.files,
+        deleted_bytes: tally.bytes,
+        removed_packs: tally.packs,
+        failed_deletions: tally.failed,
+    };
+}
+/**
+ * A pack whose every payload file is going is removed whole, in one call, so
+ * `manifest.json` goes with it rather than surviving as a description of files
+ * that are not there.
+ */
+async function removeEmptyPacks(root, plan, tally) {
+    const removed = new Set();
+    for (const pack of plan.empty_packs) {
+        const gone = await rmQuietly(path.join(root, pack.pack_id), true);
+        if (!gone) {
+            tally.failed += 1;
+            continue;
+        }
+        removed.add(pack.pack_id);
+        tally.packs += 1;
+        tally.bytes += pack.manifest_bytes;
+    }
+    return removed;
+}
+async function removeRemainingFiles(root, plan, removedPackIds, tally) {
+    const emptyPackIds = new Set(plan.empty_packs.map((pack) => pack.pack_id));
+    for (const entry of plan.delete) {
+        if (emptyPackIds.has(entry.pack_id)) {
+            // The pack removal above already took these bytes — or failed, in which
+            // case the file is still on disk and must be counted as such.
+            if (!removedPackIds.has(entry.pack_id))
+                tally.failed += 1;
+            else
+                countRemoved(tally, entry);
+            continue;
+        }
+        const file = path.join(root, entry.pack_id, ...entry.relative_path.split("/").filter(Boolean));
+        if (await rmQuietly(file, false))
+            countRemoved(tally, entry);
+        else
+            tally.failed += 1;
+    }
+}
+function countRemoved(tally, entry) {
+    tally.files += 1;
+    tally.bytes += entry.byte_size;
+    if (entry.content_hash)
+        tally.hashes.push(entry.content_hash);
+}
+async function rmQuietly(target, recursive) {
+    return fs.rm(target, { recursive, force: true }).then(() => true, () => false);
+}
+/**
+ * The staged-object index points at bytes that are no longer there. Left alone
+ * it self-heals — `resolveStagedObject` stats the file and drops the entry —
+ * but the index is capped at 5,000 rows, so stale entries evict live ones and
+ * a real staged copy stops being found. One atomic write clears them together.
+ */
+async function forgetStagedObjects(paths, hashes) {
+    if (hashes.length === 0)
+        return;
+    try {
+        const staging = await readRawEvidenceStagingState(paths.state_dir);
+        let removed = 0;
+        for (const hash of hashes) {
+            if (staging.staged[hash]) {
+                delete staging.staged[hash];
+                removed += 1;
+            }
+        }
+        if (removed === 0)
+            return;
+        staging.updated_at = new Date().toISOString();
+        await writeRawEvidenceStagingState(paths.state_dir, staging);
+    }
+    catch (error) {
+        // Not fatal and not silent: the bytes are gone either way, and the index
+        // heals on the next read. What must not happen is nobody knowing the index
+        // is carrying rows for files that no longer exist.
+        console.error("[collector prune] staged index not updated after the prune", JSON.stringify({
+            reason: "staged_index_write_failed",
+            forgotten_count: hashes.length,
+            ...describeError(error),
+        }));
+    }
+}
+function dryRunResult(plan) {
+    return {
+        status: "ok",
+        reason: plan.delete.length > 0 ? "would_prune" : "nothing_eligible",
+        deleted_files: plan.delete.length,
+        deleted_bytes: plan.deleted_bytes + plan.empty_pack_manifest_bytes,
+        removed_packs: plan.empty_packs.length,
+        kept_uncommitted: plan.kept_uncommitted.count,
+        kept_uncommitted_bytes: plan.kept_uncommitted.bytes,
+        oldest_uncommitted_age_ms: plan.kept_uncommitted.oldest_age_ms,
+        kept_unknown: plan.kept_unknown.count,
+        kept_unknown_bytes: plan.kept_unknown.bytes,
+        kept_in_window: plan.kept_in_window.count,
+        cap_bytes: plan.cap_bytes,
+        bytes_before: plan.bytes_before,
+        bytes_after: plan.bytes_after,
+        cap_blocked_by_uncommitted: plan.cap_blocked_by_uncommitted,
+        cap_blocked_count: plan.cap_blocked_count,
+        failed_deletions: 0,
+    };
+}
+function skippedResult(reason) {
+    return {
+        status: "skipped",
+        reason,
+        deleted_files: 0,
+        deleted_bytes: 0,
+        removed_packs: 0,
+        kept_uncommitted: 0,
+        kept_uncommitted_bytes: 0,
+        oldest_uncommitted_age_ms: 0,
+        kept_unknown: 0,
+        kept_unknown_bytes: 0,
+        kept_in_window: 0,
+        cap_bytes: 0,
+        bytes_before: 0,
+        bytes_after: 0,
+        cap_blocked_by_uncommitted: false,
+        cap_blocked_count: 0,
+        failed_deletions: 0,
+    };
+}
+/**
+ * The receipt, on stderr, which launchd captures to `sync.err.log`. Counts,
+ * byte totals and reason labels only — never a pack id, never a path.
+ */
+export function reportPrune(result, options = { dryRun: false }) {
+    console.error(options.dryRun ? "[collector prune] dry run" : "[collector prune] swept", JSON.stringify({
+        reason: result.reason,
+        deleted_files: result.deleted_files,
+        deleted_bytes: result.deleted_bytes,
+        removed_packs: result.removed_packs,
+        kept_uncommitted: result.kept_uncommitted,
+        staging_uncommitted_bytes: result.kept_uncommitted_bytes,
+        oldest_uncommitted_age_ms: result.oldest_uncommitted_age_ms,
+        kept_unknown: result.kept_unknown,
+        kept_in_window: result.kept_in_window,
+        cap_bytes: result.cap_bytes,
+        bytes_after: result.bytes_after,
+        failed_deletions: result.failed_deletions,
+    }));
+    if (!result.cap_blocked_by_uncommitted)
+        return;
+    console.error("[collector prune] still over the cap and nothing committed is left to take", JSON.stringify({
+        reason: "staging_cap_blocked_by_uncommitted",
+        blocked_object_count: result.cap_blocked_count,
+        staging_uncommitted_bytes: result.kept_uncommitted_bytes,
+        unknown_bytes: result.kept_unknown_bytes,
+        cap_bytes: result.cap_bytes,
+        bytes_after: result.bytes_after,
+    }));
+}
+async function prunedRecently(paths, now) {
+    const marker = path.join(paths.state_dir, STAGING_PRUNE_THROTTLE_MARKER);
+    const info = await fs.stat(marker).catch(() => null);
+    return Boolean(info && now.getTime() - info.mtimeMs < STAGING_PRUNE_MIN_INTERVAL_MS);
+}
+async function markPruned(paths, now) {
+    const marker = path.join(paths.state_dir, STAGING_PRUNE_THROTTLE_MARKER);
+    await fs.mkdir(paths.state_dir, { recursive: true }).catch(() => undefined);
+    await fs.writeFile(marker, now.toISOString()).catch(() => undefined);
+}