@bli-cockpit/cli 0.2.170 → 0.2.174

package/dist/commands/logs.js

@@ -0,0 +1,84 @@
+/**
+ * `cockpit logs <source>` — a token-cheap digest of Tower's own logs (BLI-12833).
+ *
+ * Read-only and local: the source's own CLI or files are read on THIS machine,
+ * masked into templates, counted and classified by `@bli-cockpit/telemetry-core/log-digest`,
+ * and printed in about 2 KB with real bugs (`our_bug`, `unknown`) first. Nothing
+ * is uploaded and no Tower door is called (the stored half, `logs-stored.ts`,
+ * is the one exception: a project name reads what Tower's cron stored). The MCP server's `logs_digest` tool
+ * calls the same `digestSource`, so the two print the same thing.
+ *
+ * A source that cannot be read is a NAMED refusal (`vercel_cli_missing`,
+ * `railway_not_logged_in`, ...): one line on stderr, `{ ok: false, error,
+ * detail }` on stdout under `--json`, exit 1. Never a stack trace.
+ */
+import { readFile } from "node:fs/promises";
+import { ClassTable, LOCAL_ACCESS_REFUSALS, digestSource } from "@bli-cockpit/telemetry-core/log-digest";
+import { getCollectorRuntimePaths } from "../local-state-paths.js";
+import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
+import { runStoredLogs, storedProject } from "./logs-stored.js";
+const TAG = "[logs cli]";
+const MAX_STDIN_CHARS = 64 * 1024 * 1024;
+function refuse(io, json, reason, detail) {
+    writeLine(io.stderr, `${TAG} refused ${JSON.stringify({ reason })}`);
+    if (json)
+        writeLine(io.stdout, JSON.stringify({ ok: false, error: reason, detail }));
+    else
+        writeLine(io.stderr, detail);
+    return 1;
+}
+export async function runLogs(command, io, deps = {}) {
+    // BLI-12855: a project name (or --stored, or --list) reads the digests Tower's cron stored, not a local log.
+    const stored = storedProject(command);
+    if (command.list || stored)
+        return runStoredLogs(command, io, { project: stored ?? "tower" });
+    const paths = getCollectorRuntimePaths(command.homeDir);
+    let table;
+    if (command.tableFile) {
+        try {
+            table = ClassTable.fromJson(await readFile(command.tableFile, "utf8"));
+        }
+        catch (error) {
+            return refuse(io, command.json, "table_unreadable", `--table ${command.tableFile} is not a readable class table: ${error instanceof Error ? error.message.slice(0, 160) : "unknown error"}`);
+        }
+    }
+    let stdinText;
+    const stdinIsTerminal = command.source === "-" && isInteractiveStdin(io);
+    if (command.source === "-" && !stdinIsTerminal) {
+        try {
+            stdinText = await readPipedText(io.stdin, { maxChars: MAX_STDIN_CHARS, overflowMessage: "logs - reads at most 64 MB of piped lines." });
+        }
+        catch (error) {
+            return refuse(io, command.json, "stdin_too_large", error instanceof Error ? error.message : "stdin could not be read");
+        }
+    }
+    const outcome = await digestSource({
+        source: command.source,
+        since: command.since,
+        raw: command.raw,
+        rawLimit: command.rawLimit,
+        table,
+        allLevels: command.allLevels,
+    }, {
+        stateDir: paths.state_dir,
+        stdinText,
+        stdinIsTerminal,
+        run: deps.run,
+        nowMs: deps.nowMs,
+        log: (message, fields) => writeLine(io.stderr, `${message} ${JSON.stringify(fields)}`),
+    });
+    if (!outcome.ok && LOCAL_ACCESS_REFUSALS.has(outcome.reason) && (command.source === "dashboard" || command.source === "railway") && !command.raw) {
+        // No local access to the platform: say so, then answer from what the cron stored (a refusal of its own if this machine is not paired).
+        writeLine(io.stderr, `${TAG} local source unreadable, reading the stored digest ${JSON.stringify({ reason: outcome.reason })}`);
+        return runStoredLogs(command, io, {
+            project: "tower",
+            fallbackReason: outcome.reason,
+            // The person asked for a local read: if the stored digest is out of reach too, the local refusal is the answer.
+            onNotPaired: () => refuse(io, command.json, outcome.reason, `${outcome.detail} This machine is not paired with Tower (cockpit login), so the stored digest could not be read either.`),
+        });
+    }
+    if (!outcome.ok)
+        return refuse(io, command.json, outcome.reason, outcome.detail);
+    writeLine(io.stdout, command.json ? JSON.stringify(outcome) : outcome.text);
+    return 0;
+}

package/dist/commands/public-root.js

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

package/dist/commands/sync-followups-staging.js

@@ -1,6 +1,7 @@
 import { redactedSyncErrorDetail, reportInstallEventsBestEffort, } from "./install-receipts.js";
 import { getCollectorRuntimePaths } from "../local-state.js";
-import { runStagingPrune } from "../disk-prune.js";
+import { runStagingPrune, terminalReclaimDetail } from "../disk-prune.js";
+import { runGateFollowUp } from "../staging-gate-receipt.js";
 import { runEvidenceReconcile, } from "../evidence-reconcile-client.js";
 import { runEvidenceRedelivery, } from "../evidence-redelivery.js";
 /** How many reconcile batches (of up to 500 hashes each) one sync tick may spend. */
@@ -67,6 +68,11 @@ export async function runStagingPruneAfterSync(command, io, dashboardUrl, option
     if (result.reason !== "nothing_to_prune") {
         events.push(stagingPruneEvent(result));
     }
+    // BLI-12832: bound the two disposable caches, then say what the staging gate
+    // is doing, once per change. Neither can fail the tick.
+    const gateEvent = await runGateFollowUp(getCollectorRuntimePaths(command.homeDir), io.env, options.now ?? new Date());
+    if (gateEvent)
+        events.push(gateEvent);
     if (events.length === 0)
         return;
     await reportInstallEventsBestEffort({
@@ -179,6 +185,7 @@ function stagingPruneEvent(result) {
         result.failed_deletions > 0
             ? `failed_deletions ${result.failed_deletions}`
             : null,
+        terminalReclaimDetail(result),
     ]
         .filter((part) => Boolean(part))
         .join("; ");

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/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)" },