@bli-cockpit/cli 0.2.168 → 0.2.173

package/dist/commands/sync.js

@@ -11,7 +11,7 @@
  *   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
+ *   converge the rest of the machine  sync-followups.ts, sync-heal.ts
  *
  * The supporting modules each own one thing those steps share:
  *
@@ -39,13 +39,18 @@ import { createInteractiveExecRunner } from "../process-runner.js";
 import { envWithNodeRuntimeOnPath } from "../scheduled-self-update.js";
 import { runMemoryExperienceAfterSync } from "./memory-log.js";
 import { classifySyncHealthError, redactedSyncErrorDetail, reportInstallEventsBestEffort, } from "./install-receipts.js";
+import { runMachineHealAfterSync } from "./sync-heal.js";
 import { sendSyncHeartbeat } from "./sync-heartbeat.js";
 import { runSyncWithHealthReceipt } from "./sync-receipt.js";
 import { runAutostartSelfHealAfterSync, runMemoryInstallAfterSync, runScheduledSelfUpdateAfterSync, runStagingPruneAfterSync, } from "./sync-followups.js";
 import { rotateCollectorLogsBestEffort } from "../log-rotation.js";
+import { stampSyncTick } from "../sync-tick-stamp.js";
 import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths, readLocalCollectorConfig, } from "../local-state.js";
 export async function runSync(command, io) {
     const paths = getCollectorRuntimePaths(command.homeDir);
+    // Ticket 12831: the memory prompt hook reads this stamp to tell a scheduler
+    // that stopped firing from one that is merely quiet.
+    await stampSyncTick(paths);
     // BLI-3553, first thing in the tick: cap the scheduler's own logs. Nothing
     // rotated them before, and two months of a 15-minute tick left 211 MB of
     // sync.log on the reference Mac. Best-effort by construction — a rotation
@@ -165,5 +170,8 @@ async function reportTickThrew(command, io, dashboardUrl, error, errorCode) {
 async function convergeAfterTick(command, io, dashboardUrl) {
     await runAutostartSelfHealAfterSync(command, io, dashboardUrl);
     await runMemoryInstallAfterSync(command, io, dashboardUrl);
+    // BLI-12828: the repairs `cockpit doctor` also makes (agent rules, a lapsed
+    // sign-in), so nobody has to be told to run it.
+    await runMachineHealAfterSync(command, io, dashboardUrl);
     await runMemoryExperienceAfterSync({ ...command, dashboardUrl }, io);
 }

package/dist/disk-prune.js

@@ -29,7 +29,8 @@
  */
 import fs from "node:fs/promises";
 import path from "node:path";
-import { planStagingRetention, retentionOptionsFromEnv, } from "./disk-retention.js";
+import { measureCollectorBytes, stagingGateLimitsFromEnv, } from "./staging-gate.js";
+import { TERMINAL_RECLAIM_AGE_MS, planStagingRetention, retentionOptionsFromEnv, } from "./disk-retention.js";
 import { RAW_EVIDENCE_DIR, readStagingInventory } from "./disk-usage.js";
 import { describeError } from "./health-detail.js";
 import { writeLastPruneReceipt } from "./prune-receipt.js";
@@ -62,16 +63,26 @@ export async function runStagingPrune(paths, options = {}) {
 export async function planFromDisk(paths, env, options, now) {
     const fromEnv = retentionOptionsFromEnv(env);
     const inventory = await readStagingInventory(paths, now);
+    const capBytes = options.capBytes ?? fromEnv.capBytes;
+    const limits = stagingGateLimitsFromEnv(env);
+    const collectorBytes = await measureCollectorBytes(paths.state_dir).catch(() => 0);
+    // BLI-12832: how many terminal bytes must go for the staging gate to reopen.
+    // Reclaim down to half of each limit (staging cap, state ceiling) so a
+    // typical file fits afterwards, oldest refused copy first.
+    const reserve = 0.5;
+    const terminalPressureBytes = Math.max(inventory.total_bytes - Math.floor(capBytes * reserve), collectorBytes - Math.floor(limits.ceilingBytes * reserve), 0);
     return planStagingRetention(inventory, {
         retentionMs: options.retentionMs ?? fromEnv.retentionMs,
-        capBytes: options.capBytes ?? fromEnv.capBytes,
+        capBytes,
         allCommitted: options.allCommitted,
         reclaimTerminal: options.reclaimTerminal,
+        terminalAgedMs: options.terminalAgedMs ?? TERMINAL_RECLAIM_AGE_MS,
+        terminalPressureBytes: options.terminalPressureBytes ?? terminalPressureBytes,
     });
 }
 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 tally = { files: 0, bytes: 0, packs: 0, failed: 0, hashes: [], terminalFiles: 0, terminalBytes: 0 };
     const removedPackIds = await removeEmptyPacks(root, plan, tally);
     await removeRemainingFiles(root, plan, removedPackIds, tally);
     await forgetStagedObjects(paths, tally.hashes);
@@ -83,6 +94,8 @@ async function applyPlan(paths, plan) {
         deleted_bytes: tally.bytes,
         removed_packs: tally.packs,
         failed_deletions: tally.failed,
+        terminal_reclaimed_files: tally.terminalFiles,
+        terminal_reclaimed_bytes: tally.terminalBytes,
     };
 }
 /**
@@ -126,6 +139,17 @@ async function removeRemainingFiles(root, plan, removedPackIds, tally) {
 function countRemoved(tally, entry) {
     tally.files += 1;
     tally.bytes += entry.byte_size;
+    if (entry.reason.startsWith("terminal")) {
+        tally.terminalFiles += 1;
+        tally.terminalBytes += entry.byte_size;
+        console.error("[collector prune] terminal evidence reclaimed, the refusal receipt stays in the ledger", JSON.stringify({
+            reason: entry.reason.split(":")[0],
+            terminal_reason: entry.reason.split(":").slice(1).join(":") || null,
+            byte_size: entry.byte_size,
+            age_ms: entry.age_ms,
+            content_hash_prefix: entry.content_hash?.slice(0, 16) ?? null,
+        }));
+    }
     if (entry.content_hash)
         tally.hashes.push(entry.content_hash);
 }
@@ -166,6 +190,12 @@ async function forgetStagedObjects(paths, hashes) {
         }));
     }
 }
+/** The receipt fragment for refused copies reclaimed this tick, or null. */
+export function terminalReclaimDetail(result) {
+    if (!result.terminal_reclaimed_files)
+        return null;
+    return `terminal_reclaimed ${result.terminal_reclaimed_files} (${result.terminal_reclaimed_bytes ?? 0}B)`;
+}
 function dryRunResult(plan) {
     return {
         status: "ok",
@@ -229,6 +259,8 @@ export function reportPrune(result, options = { dryRun: false }) {
         bytes_scanned: result.bytes_before,
         bytes_after: result.bytes_after,
         failed_deletions: result.failed_deletions,
+        terminal_reclaimed_files: result.terminal_reclaimed_files ?? 0,
+        terminal_reclaimed_bytes: result.terminal_reclaimed_bytes ?? 0,
     }));
     if (!result.cap_blocked_by_uncommitted)
         return;

package/dist/disk-retention.js

@@ -8,6 +8,8 @@ export const DEFAULT_STAGING_CAP_BYTES = 256 * 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";
+/** A terminal object's staged bytes are reclaimed after a week regardless. */
+export const TERMINAL_RECLAIM_AGE_MS = 7 * 24 * 60 * 60 * 1000;
 /** The two knobs, from the environment, falling back to the defaults above. */
 export function retentionOptionsFromEnv(env) {
     const hours = Number(env[STAGING_RETENTION_ENV]);
@@ -43,7 +45,10 @@ export function planStagingRetention(inventory, options = {}) {
             addToBucket(plan.kept_in_window, object);
         }
     }
-    const retainedTerminalBytes = options.reclaimTerminal ? 0 : (inventory.terminal_bytes ?? 0);
+    const terminalReclaimed = reclaimTerminalOnSchedule(plan, inventory, options);
+    const retainedTerminalBytes = options.reclaimTerminal
+        ? 0
+        : Math.max(0, (inventory.terminal_bytes ?? 0) - terminalReclaimed);
     applyByteCap(plan, committedInWindow, capBytes + retainedTerminalBytes, inventory);
     markEmptyPacks(plan, inventory.packs);
     plan.bytes_after =
@@ -57,6 +62,31 @@ export function planStagingRetention(inventory, options = {}) {
     plan.cap_blocked_count = plan.cap_blocked_by_uncommitted ? unvouched : 0;
     return plan;
 }
+/**
+ * BLI-12832: the scheduled prune's terminal reclaim. Aged objects first (a
+ * week), then oldest-first until the gate's pressure is relieved. Returns the
+ * bytes planned for deletion.
+ */
+function reclaimTerminalOnSchedule(plan, inventory, options) {
+    if (options.reclaimTerminal)
+        return 0;
+    const terminal = inventory.packs
+        .flatMap((pack) => pack.objects)
+        .filter((object) => object.state === "terminal")
+        .sort((a, b) => (b.disk_age_ms || b.age_ms) - (a.disk_age_ms || a.age_ms));
+    let freed = 0;
+    let pressure = options.terminalPressureBytes ?? 0;
+    for (const object of terminal) {
+        const age = object.disk_age_ms || object.age_ms;
+        const aged = options.terminalAgedMs !== undefined && age >= options.terminalAgedMs;
+        if (!aged && pressure <= 0)
+            break;
+        pushDeletion(plan, object, `${aged ? "terminal_aged" : "terminal_pressure"}:${object.reason}`);
+        freed += object.byte_size;
+        pressure -= object.byte_size;
+    }
+    return freed;
+}
 /**
  * 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

package/dist/sign-in-action.js

@@ -0,0 +1,7 @@
+/**
+ * The ONE sentence a person gets when only a browser can fix their sign-in
+ * (BLI-12828). Doctor's `authed` row, doctor's exit-code receipt and the sync
+ * tick's once-a-day note all say these exact words, so nobody is told two
+ * different things for the same problem.
+ */
+export const SIGN_IN_ACTION = "Run `cockpit login` and approve the sign-in in your browser.";

package/dist/staging-gate-receipt.js

@@ -0,0 +1,131 @@
+/**
+ * `staging-gate.json`: what the staging gate last decided, and whether anyone
+ * has been told (BLI-12832).
+ *
+ * The gate itself runs every tick and logs every tick on stderr. The receipt
+ * stream and `cockpit doctor` are different: a person reads them, so a pause
+ * that lasts three days must be said once when it starts and once when it ends,
+ * not 288 times. This file is the memory that makes "once" possible: the state
+ * the gate is in now, and the state the last receipt announced.
+ *
+ * One small JSON object, overwritten each tick, so it is bounded by
+ * construction. Metadata only: byte counts and reason labels.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { describeError } from "./health-detail.js";
+import { pruneStateDirCaches } from "./state-dir-prune.js";
+import { readStagingGate, } from "./staging-gate.js";
+export const STAGING_GATE_FILE = "staging-gate.json";
+export const STAGING_GATE_STEP = "staging_gate";
+export async function readStagingGateReceipt(paths) {
+    const raw = await fs
+        .readFile(path.join(paths.state_dir, STAGING_GATE_FILE), "utf8")
+        .catch(() => null);
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        if ((parsed.state !== "open" && parsed.state !== "paused") ||
+            typeof parsed.since !== "string" ||
+            typeof parsed.announced !== "string") {
+            return null;
+        }
+        return {
+            state: parsed.state,
+            reason: parsed.reason ?? null,
+            since: parsed.since,
+            evaluated_at: String(parsed.evaluated_at ?? parsed.since),
+            announced: parsed.announced,
+            staging_bytes: Number(parsed.staging_bytes) || 0,
+            collector_bytes: Number(parsed.collector_bytes) || 0,
+            free_bytes: typeof parsed.free_bytes === "number" ? parsed.free_bytes : null,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function stateKey(snapshot) {
+    return snapshot.reason ? `paused:${snapshot.reason}` : "open";
+}
+/**
+ * Reads the gate live (after the prune, so it reflects what the tick just
+ * freed), compares it with the last announced state and returns the one
+ * receipt event a CHANGE deserves, or null. Never throws.
+ */
+export async function settleStagingGate(paths, env, now, deps = {}) {
+    const snapshot = await readStagingGate(paths.state_dir, env, deps);
+    const key = stateKey(snapshot);
+    const previous = await readStagingGateReceipt(paths);
+    const announcedBefore = previous?.announced ?? "open";
+    const changed = key !== announcedBefore;
+    const sameState = previous && stateKey({ reason: previous.reason }) === key;
+    console.error(snapshot.reason
+        ? "[staging-gate] paused, new evidence is not being copied; sources stay on disk"
+        : "[staging-gate] open, new evidence may be copied", JSON.stringify({
+        reason: snapshot.reason ?? "open",
+        announced: changed ? "now" : "already",
+        staging_bytes: snapshot.staging_bytes,
+        collector_bytes: snapshot.collector_bytes,
+        free_bytes: snapshot.free_bytes,
+        floor_bytes: snapshot.floor_bytes,
+        cap_bytes: snapshot.cap_bytes,
+        ceiling_bytes: snapshot.ceiling_bytes,
+    }));
+    try {
+        const receipt = {
+            state: snapshot.reason ? "paused" : "open",
+            reason: snapshot.reason,
+            since: sameState ? previous.since : now.toISOString(),
+            evaluated_at: now.toISOString(),
+            announced: key,
+            staging_bytes: snapshot.staging_bytes,
+            collector_bytes: snapshot.collector_bytes,
+            free_bytes: snapshot.free_bytes,
+        };
+        await fs.mkdir(paths.state_dir, { recursive: true });
+        const file = path.join(paths.state_dir, STAGING_GATE_FILE);
+        const temp = `${file}.${process.pid}.tmp`;
+        await fs.writeFile(temp, `${JSON.stringify(receipt)}\n`, { mode: 0o600 });
+        await fs.rename(temp, file);
+    }
+    catch (error) {
+        console.error("[staging-gate] could not record the gate receipt", JSON.stringify({ reason: "staging_gate_receipt_write_failed", ...describeError(error) }));
+        return { snapshot, event: null };
+    }
+    return { snapshot, event: changed ? gateEvent(snapshot) : null };
+}
+/**
+ * The tick's last disk chore: bound the two disposable caches, then settle the
+ * gate. Returns the receipt event a change deserves, or null. Never throws.
+ */
+export async function runGateFollowUp(paths, env, now) {
+    try {
+        await pruneStateDirCaches(paths, now);
+        return (await settleStagingGate(paths, env, now)).event;
+    }
+    catch (error) {
+        console.error("[staging-gate] the gate follow-up threw, the tick is unaffected", JSON.stringify({ reason: "staging_gate_follow_up_threw", ...describeError(error) }));
+        return null;
+    }
+}
+/** Counts and a reason label only; no path travels in a receipt. */
+function gateEvent(snapshot) {
+    const detail = [
+        `staging ${snapshot.staging_bytes}B of ${snapshot.cap_bytes}B cap`,
+        `collector ${snapshot.collector_bytes}B of ${snapshot.ceiling_bytes}B ceiling`,
+        snapshot.free_bytes === null ? null : `free ${snapshot.free_bytes}B`,
+    ]
+        .filter((part) => Boolean(part))
+        .join("; ");
+    if (snapshot.reason) {
+        return {
+            step: STAGING_GATE_STEP,
+            status: "skipped",
+            error_code: `staging_deferred_${snapshot.reason}`,
+            error_detail: detail,
+        };
+    }
+    return { step: STAGING_GATE_STEP, status: "ok", error_detail: `resumed; ${detail}` };
+}

package/dist/staging-gate.js

@@ -0,0 +1,214 @@
+/**
+ * The write-side gate: Tower never copies new evidence onto a disk that has no
+ * room for it (BLI-12832).
+ *
+ * `disk-retention.ts` governs what the prune may DELETE, and it rightly never
+ * deletes evidence the server has not accepted. Nothing on the way IN used to
+ * look at the cap or at the volume, so when uploads failed for days every
+ * 15-minute tick copied more transcripts into staging without bound: 182 GB on
+ * one laptop (ticket 3066), 174 GB on another (ticket 2002).
+ *
+ * A staged copy duplicates a source file that is still on disk, so refusing to
+ * copy loses nothing. The deferred file is simply not collected this tick; no
+ * cursor entry is written for it, and the next tick re-reads the source when
+ * room has returned.
+ *
+ * Three reasons close the gate, most urgent first:
+ *
+ * - `low_disk`: the volume's free space is under max(5 GiB, 5% of the volume).
+ * - `state_over_ceiling`: everything the collector writes under its state dir
+ *   (staging, spool, logs, cursors, state; never the study folders
+ *   `state-dir-audit.ts` recognises) would pass the hard ceiling, 512 MiB by
+ *   default.
+ * - `staging_at_cap`: staging, committed and uncommitted alike, is at the
+ *   staging cap (256 MiB by default).
+ *
+ * One exception, on purpose: when staging is EMPTY the first file is admitted
+ * even if it alone is bigger than the cap, because a 334 MB rollout would
+ * otherwise never be collected on any machine. The ceiling and the free-space
+ * floor still bind it.
+ *
+ * Metadata only: byte counts and reason labels, never a path.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { retentionOptionsFromEnv } from "./disk-retention.js";
+import { directoryBytes } from "./disk-usage-files.js";
+import { describeError } from "./health-detail.js";
+import { classifyStateEntry } from "./state-dir-audit.js";
+/** Hard ceiling on everything the collector writes under its state dir. */
+export const DEFAULT_STATE_CEILING_BYTES = 512 * 1024 * 1024;
+export const STATE_CEILING_ENV = "COCKPIT_STATE_CEILING_BYTES";
+/** Overrides the low-disk floor (bytes); unset means max(5 GiB, 5% of volume). */
+export const MIN_FREE_ENV = "COCKPIT_MIN_FREE_BYTES";
+export const LOW_DISK_FLOOR_BYTES = 5 * 1024 * 1024 * 1024;
+export const LOW_DISK_FLOOR_FRACTION = 0.05;
+/**
+ * Each pack's `manifest.json` is staged beside the payload and its size grows
+ * with the gap ledger, so it is not known when a file is admitted. A tenth of
+ * the cap is held back for manifests: payload is admitted only up to 90% of the
+ * cap, which keeps the folder, manifests included, at or under the cap.
+ */
+export const STAGING_MANIFEST_RESERVE_FRACTION = 0.1;
+/** The reason label every skip, log line and receipt carries. */
+export const STAGING_DEFERRED = "staging_deferred";
+export function stagingGateLimitsFromEnv(env) {
+    const ceiling = Number(env[STATE_CEILING_ENV]);
+    const minFree = Number(env[MIN_FREE_ENV]);
+    return {
+        capBytes: retentionOptionsFromEnv(env).capBytes,
+        ceilingBytes: Number.isFinite(ceiling) && ceiling > 0 ? ceiling : DEFAULT_STATE_CEILING_BYTES,
+        minFreeBytes: Number.isFinite(minFree) && minFree >= 0 && env[MIN_FREE_ENV] ? minFree : null,
+    };
+}
+/**
+ * Free and total bytes of the volume holding `dir` (or its nearest existing
+ * parent: a fresh machine has no state dir yet). `null` when the platform
+ * cannot say, which is logged and never closes the gate on its own.
+ */
+export async function readVolumeSpace(dir, statfs = fs.statfs) {
+    let target = dir;
+    for (let hops = 0; hops < 64; hops += 1) {
+        try {
+            const stats = await statfs(target);
+            const bsize = Number(stats.bsize);
+            return {
+                free_bytes: Number(stats.bavail) * bsize,
+                total_bytes: Number(stats.blocks) * bsize,
+            };
+        }
+        catch (error) {
+            const parent = path.dirname(target);
+            if (parent === target) {
+                console.error("[staging-gate] free space unreadable, low-disk check skipped", JSON.stringify({ reason: "statfs_unavailable", ...describeError(error) }));
+                return null;
+            }
+            target = parent;
+        }
+    }
+    return null;
+}
+export function lowDiskFloorBytes(totalBytes, override) {
+    if (override !== null)
+        return override;
+    return Math.max(LOW_DISK_FLOOR_BYTES, Math.ceil(totalBytes * LOW_DISK_FLOOR_FRACTION));
+}
+/**
+ * Everything the collector writes under its state dir, studies excluded: the
+ * quantity the ceiling bounds. Cheap: stat-walks only what the audit table
+ * counts, never the study folders.
+ */
+export async function measureCollectorBytes(stateDir) {
+    const entries = await fs.readdir(stateDir, { withFileTypes: true }).catch(() => []);
+    let total = 0;
+    for (const entry of entries) {
+        if (classifyStateEntry(entry.name)?.class === "study")
+            continue;
+        const full = path.join(stateDir, entry.name);
+        total += entry.isDirectory()
+            ? await directoryBytes(full)
+            : await fs.stat(full).then((info) => info.size, () => 0);
+    }
+    return total;
+}
+export function decideStagingGate(facts) {
+    if (facts.free_bytes !== null &&
+        facts.floor_bytes !== null &&
+        facts.free_bytes < facts.floor_bytes) {
+        return "low_disk";
+    }
+    if (facts.collector_bytes >= facts.ceiling_bytes)
+        return "state_over_ceiling";
+    if (facts.staging_bytes >= facts.cap_bytes)
+        return "staging_at_cap";
+    return null;
+}
+/** One live read of the gate: measure, ask the volume, decide. Never throws. */
+export async function readStagingGate(stateDir, env, deps = {}) {
+    const limits = stagingGateLimitsFromEnv(env);
+    const [stagingBytes, collectorBytes, volume] = await Promise.all([
+        directoryBytes(path.join(stateDir, "raw-evidence")).catch(() => 0),
+        measureCollectorBytes(stateDir).catch(() => 0),
+        readVolumeSpace(stateDir, deps.statfs),
+    ]);
+    const facts = {
+        staging_bytes: stagingBytes,
+        collector_bytes: Math.max(collectorBytes, stagingBytes),
+        free_bytes: volume?.free_bytes ?? null,
+        total_bytes: volume?.total_bytes ?? null,
+        floor_bytes: volume ? lowDiskFloorBytes(volume.total_bytes, limits.minFreeBytes) : null,
+        cap_bytes: limits.capBytes,
+        ceiling_bytes: limits.ceilingBytes,
+    };
+    return { ...facts, reason: decideStagingGate(facts) };
+}
+/** How many files the gate has refused to copy so far this tick. */
+export function stagingDeferredFiles(allowance) {
+    if (!allowance)
+        return 0;
+    return Object.values(allowance.deferred).reduce((sum, slot) => sum + (slot?.files ?? 0), 0);
+}
+export async function openStagingAllowance(stateDir, env, deps = {}) {
+    const snapshot = await readStagingGate(stateDir, env, deps);
+    console.error("[staging-gate] evaluated", JSON.stringify({
+        reason: snapshot.reason ?? "open",
+        staging_bytes: snapshot.staging_bytes,
+        collector_bytes: snapshot.collector_bytes,
+        free_bytes: snapshot.free_bytes,
+        floor_bytes: snapshot.floor_bytes,
+        cap_bytes: snapshot.cap_bytes,
+        ceiling_bytes: snapshot.ceiling_bytes,
+    }));
+    return { snapshot, admitted_bytes: 0, deferred: {} };
+}
+/**
+ * May a file of this size be copied into staging now? Returns the reason it may
+ * not, or null after charging the allowance. A copy that already exists on disk
+ * costs nothing and must be passed as `alreadyStaged` so it is never refused.
+ */
+export function admitToStaging(allowance, byteLength, options = {}) {
+    if (options.alreadyStaged)
+        return null;
+    const { snapshot } = allowance;
+    const payloadCap = Math.floor(snapshot.cap_bytes * (1 - STAGING_MANIFEST_RESERVE_FRACTION));
+    const spent = allowance.admitted_bytes;
+    const stagedNow = snapshot.staging_bytes + spent;
+    let reason = null;
+    if (snapshot.free_bytes !== null &&
+        snapshot.floor_bytes !== null &&
+        snapshot.free_bytes - spent - byteLength < snapshot.floor_bytes) {
+        reason = "low_disk";
+    }
+    else if (snapshot.collector_bytes + spent + byteLength > snapshot.ceiling_bytes) {
+        reason = "state_over_ceiling";
+    }
+    else if (stagedNow >= snapshot.cap_bytes ||
+        (stagedNow > 0 && stagedNow + byteLength > payloadCap)) {
+        reason = "staging_at_cap";
+    }
+    if (!reason) {
+        allowance.admitted_bytes += byteLength;
+        return null;
+    }
+    const slot = (allowance.deferred[reason] ??= { files: 0, bytes: 0 });
+    slot.files += 1;
+    slot.bytes += byteLength;
+    // The first refusal of each reason per tick carries the numbers; the rest are
+    // counted in `slot` and summed by the follow-up, so a 50-session backlog is
+    // one line, not fifty.
+    if (slot.files === 1) {
+        console.error("[staging-gate] copy deferred, source stays on disk and is re-read when room returns", JSON.stringify({
+            event: STAGING_DEFERRED,
+            reason,
+            kind: options.kind ?? null,
+            file_bytes: byteLength,
+            staging_bytes: snapshot.staging_bytes,
+            collector_bytes: snapshot.collector_bytes,
+            free_bytes: snapshot.free_bytes,
+            floor_bytes: snapshot.floor_bytes,
+            cap_bytes: snapshot.cap_bytes,
+            ceiling_bytes: snapshot.ceiling_bytes,
+        }));
+    }
+    return reason;
+}

package/dist/state-dir-audit.js

@@ -34,10 +34,10 @@ export const STUDIES_DIR_SUFFIX = "-studies";
  * collector name; none does today, and the test pins that.
  */
 export const STATE_DIR_RULES = [
-    { name: "raw-evidence", match: "exact", class: "staging", bound: "staged copies go the tick the server commits them; 256 MiB cap; uncommitted evidence is never deleted, only counted" },
+    { name: "raw-evidence", match: "exact", class: "staging", bound: "staged copies go the tick the server commits them; 256 MiB cap; the staging gate stops new copies at the cap, on a low disk or over the 512 MiB ceiling; uncommitted evidence is never deleted, only counted" },
     { name: "sync.log", match: "prefix", class: "logs", bound: "rotated every tick at 10 MiB, at most 2 archives (20 MB) per stream" },
     { name: "sync.err.log", match: "prefix", class: "logs", bound: "rotated every tick at 10 MiB, at most 2 archives (20 MB) per stream" },
-    { name: "spool", match: "exact", class: "spool", bound: "upload queue; each entry is deleted once the ingest door accepts it" },
+    { name: "spool", match: "exact", class: "spool", bound: "upload queue; each entry is deleted once the ingest door accepts it; at most 20 pending uploads and 100 outbox entries (40 events each), oldest dropped first" },
     { name: "cursors", match: "exact", class: "state", bound: "raw-evidence ledger and reconcile answers capped at 5,000 rows each; backfill cursors one small file each" },
     { name: "raw-evidence-staging.json", match: "exact", class: "state", bound: "staged-object index and delivery attempts capped at 5,000 rows each" },
     { name: "work-contexts", match: "exact", class: "state", bound: "one small file per worktree ever bound with `cockpit start`; overwritten, not pruned (a few KB each)" },
@@ -45,14 +45,15 @@ export const STATE_DIR_RULES = [
     { name: "root-work-scan.json", match: "exact", class: "state", bound: "one file, overwritten by each root scan" },
     { name: "setup-receipt.json", match: "exact", class: "state", bound: "one file, overwritten" },
     { name: "memory-install-receipt.json", match: "exact", class: "state", bound: "one file, overwritten" },
+    { name: "staging-gate.json", match: "exact", class: "state", bound: "one file, overwritten every tick: the staging gate's state and what was last announced (BLI-12832)" },
     { name: "last-prune.json", match: "exact", class: "state", bound: "one file, overwritten every tick" },
     { name: "last-turn-trace.json", match: "exact", class: "state", bound: "one file, overwritten" },
     { name: "sync.lock", match: "exact", class: "state", bound: "lock file, removed when the tick ends" },
     { name: "backfill.lock", match: "exact", class: "state", bound: "lock file, removed when the backfill ends" },
     { name: ".last-", match: "prefix", class: "state", bound: "24-byte throttle markers for self-update, autostart repair and the memory install" },
-    { name: "read-cache", match: "exact", class: "state", bound: "one response file per distinct Tower read, overwritten on refresh" },
+    { name: "read-cache", match: "exact", class: "state", bound: "one response file per distinct Tower read; the tick deletes files older than 7 days and the oldest past 32 MiB (state-dir-prune.ts)" },
     { name: "memory-hook-stats.json", match: "exact", class: "state", bound: "fixed-size histograms, overwritten (BLI Memory hooks)" },
-    { name: "memory-hook-samples", match: "exact", class: "state", bound: "hourly content-free timing samples (BLI Memory hooks); not yet pruned, a few MB a week" },
+    { name: "memory-hook-samples", match: "exact", class: "state", bound: "hourly content-free timing samples (BLI Memory hooks); the tick deletes files older than 14 days (state-dir-prune.ts)" },
     { name: "memory-recall-seen", match: "exact", class: "state", bound: "one file per agent session, deleted after 7 days (BLI Memory hooks)" },
     { name: "memory-stop-anchors.json", match: "exact", class: "state", bound: "one offset per transcript, overwritten (BLI Memory hooks)" },
     { name: "memory-daemon-spawn.json", match: "exact", class: "state", bound: "one spawn stamp, overwritten (BLI Memory daemon)" },

package/dist/state-dir-prune.js

@@ -0,0 +1,84 @@
+/**
+ * Bounds the two state-dir writers that had no bound (BLI-12832 audit).
+ *
+ * `read-cache/` keeps one response file per distinct Tower read (the key folds
+ * in the request body, so every different `memory search` is its own file) and
+ * overwrote only on a repeat of the SAME read. `memory-hook-samples/` keeps
+ * hourly timing samples and was "not yet pruned". Both are disposable: a cache
+ * miss re-reads from Tower, an old timing sample is history nobody consults.
+ * Neither is evidence, so deleting from them can never lose anything.
+ *
+ * Every other state-dir entry is bounded where it is written (see the table in
+ * `state-dir-audit.ts`). Runs on every sync tick, never throws, logs counts.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { describeError } from "./health-detail.js";
+export const READ_CACHE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+export const READ_CACHE_MAX_BYTES = 32 * 1024 * 1024;
+export const HOOK_SAMPLES_MAX_AGE_MS = 14 * 24 * 60 * 60 * 1000;
+async function listFiles(dir) {
+    const out = [];
+    const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            out.push(...(await listFiles(full)));
+        }
+        else if (entry.isFile()) {
+            const info = await fs.stat(full).catch(() => null);
+            if (info)
+                out.push({ file: full, bytes: info.size, mtime_ms: info.mtimeMs });
+        }
+    }
+    return out;
+}
+async function removeAll(files) {
+    let removed = 0;
+    let bytes = 0;
+    for (const fact of files) {
+        const ok = await fs.rm(fact.file, { force: true }).then(() => true, () => false);
+        if (!ok)
+            continue;
+        removed += 1;
+        bytes += fact.bytes;
+    }
+    return { removed, bytes };
+}
+export async function pruneStateDirCaches(paths, now = new Date()) {
+    const result = {
+        read_cache_removed: 0,
+        read_cache_bytes_freed: 0,
+        hook_samples_removed: 0,
+        hook_samples_bytes_freed: 0,
+    };
+    try {
+        const cache = await listFiles(path.join(paths.state_dir, "read-cache"));
+        const fresh = cache.filter((fact) => now.getTime() - fact.mtime_ms <= READ_CACHE_MAX_AGE_MS);
+        const doomed = cache.filter((fact) => !fresh.includes(fact));
+        let kept = fresh.reduce((sum, fact) => sum + fact.bytes, 0);
+        for (const fact of [...fresh].sort((a, b) => a.mtime_ms - b.mtime_ms)) {
+            if (kept <= READ_CACHE_MAX_BYTES)
+                break;
+            doomed.push(fact);
+            kept -= fact.bytes;
+        }
+        const freed = await removeAll(doomed);
+        result.read_cache_removed = freed.removed;
+        result.read_cache_bytes_freed = freed.bytes;
+        const samples = await listFiles(path.join(paths.state_dir, "memory-hook-samples"));
+        const stale = samples.filter((fact) => now.getTime() - fact.mtime_ms > HOOK_SAMPLES_MAX_AGE_MS);
+        const sampleFreed = await removeAll(stale);
+        result.hook_samples_removed = sampleFreed.removed;
+        result.hook_samples_bytes_freed = sampleFreed.bytes;
+        console.error("[collector prune] state-dir caches bounded", JSON.stringify({
+            reason: freed.removed + sampleFreed.removed > 0 ? "caches_trimmed" : "caches_within_bounds",
+            ...result,
+            read_cache_kept_bytes: kept,
+        }));
+    }
+    catch (error) {
+        console.error("[collector prune] state-dir cache prune failed, nothing else is affected", JSON.stringify({ reason: "state_dir_cache_prune_failed", ...describeError(error) }));
+    }
+    return result;
+}