@bli-cockpit/cli 0.2.170 → 0.2.173

package/dist/adapters/raw-evidence-collection-state.js

@@ -26,7 +26,8 @@ import { RAW_EVIDENCE_UPLOAD_MAX_FILE_BYTES } from "@bli-cockpit/telemetry-core"
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { DELIVERY_BACKOFF_BYPASS_REASON, deliveryBackoffApplies, heldSourceKeys, readRawEvidenceStagingState, resolveStagedObject, } from "../raw-evidence-staging.js";
+import { DELIVERY_BACKOFF_BYPASS_REASON, deliveryBackoffApplies, heldSourceKeys, readRawEvidenceStagingState, resolveStagedObject, terminalDeliveryReason, } from "../raw-evidence-staging.js";
+import { admitToStaging, openStagingAllowance, } from "../staging-gate.js";
 import { chmodPrivate } from "./raw-evidence-pack-store.js";
 import { GIT_DIFF_TIMEOUT_MS, MAX_GIT_DIFF_BYTES, } from "./raw-evidence-git-diff.js";
 export const DEFAULT_SINCE_MINUTES = 24 * 60;
@@ -54,6 +55,11 @@ export async function openCollection(context, options, places) {
     const byteBudget = options.byteBudget ?? RAW_EVIDENCE_DEFAULT_BYTE_BUDGET;
     const objectBudget = options.objectBudget ?? RAW_EVIDENCE_DEFAULT_OBJECT_BUDGET;
     const staging = await readRawEvidenceStagingState(options.stateDir);
+    const budget = options.budget ?? {
+        remainingBytes: byteBudget,
+        remainingObjects: objectBudget,
+    };
+    const stagingAllowance = (budget.staging ??= await openStagingAllowance(options.stateDir, options.env ?? process.env, { statfs: options.statfs }));
     return {
         context,
         filesDir: path.join(places.stagingDir, "files"),
@@ -71,14 +77,16 @@ export async function openCollection(context, options, places) {
         redacted: [],
         reused: [],
         scanned: new Map(),
-        caps: startingCaps({ byteBudget, objectBudget, budget: options.budget }),
+        caps: startingCaps({
+            byteBudget,
+            objectBudget,
+            budget: options.budget,
+            stagingCapBytes: stagingAllowance.snapshot.cap_bytes,
+        }),
         skipContentHashes: options.skipContentHashes ?? new Set(),
         priorSnapshots: options.priorSnapshots ?? new Map(),
         stubReoffers: options.stubReoffers ?? new Map(),
-        budget: options.budget ?? {
-            remainingBytes: byteBudget,
-            remainingObjects: objectBudget,
-        },
+        budget,
         index: { value: 0 },
     };
 }
@@ -118,6 +126,12 @@ function startingCaps(options) {
             observed: options.budget?.remainingObjects ?? options.objectBudget,
             applied: false,
         },
+        {
+            source: "raw_evidence",
+            cap_type: "staging_gate",
+            limit: options.stagingCapBytes,
+            applied: false,
+        },
         {
             source: "git_diff",
             cap_type: "max_bytes_per_diff",
@@ -185,6 +199,38 @@ export async function stageEvidenceBytes(collection, options) {
     collection.stagedNewCount += 1;
     return { local_path: destination, staged_in_pack: true };
 }
+/**
+ * The one door a file passes before its bytes may be copied: the per-sync
+ * budget below, then the disk (BLI-12832). A refusal from the disk hands the
+ * budget back, because nothing was staged and the next tick re-reads the source.
+ * A copy already staged costs the disk nothing and is never refused by it.
+ */
+export function admitEvidence(collection, byteLength, file) {
+    const budgetReason = admitToBudget(collection.budget, byteLength);
+    if (budgetReason)
+        return budgetReason;
+    const allowance = collection.budget.staging;
+    if (!allowance)
+        return null;
+    // BLI-12832: bytes the server refused for good are reclaimed by the prune
+    // (the refusal stays as a receipt), so copying them again would be churn.
+    if (collection.staging.staged[file.contentHash] === undefined &&
+        terminalDeliveryReason(collection.staging.delivery_attempts[file.contentHash]?.last_reason)) {
+        collection.budget.remainingObjects += 1;
+        collection.budget.remainingBytes += byteLength;
+        console.error("[staging-gate] not copying bytes the server refused for good", JSON.stringify({ reason: "delivery_terminal_refused", kind: file.kind, file_bytes: byteLength }));
+        return "delivery_terminal_refused";
+    }
+    const diskReason = admitToStaging(allowance, byteLength, {
+        alreadyStaged: collection.staging.staged[file.contentHash] !== undefined,
+        kind: file.kind,
+    });
+    if (!diskReason)
+        return null;
+    collection.budget.remainingObjects += 1;
+    collection.budget.remainingBytes += byteLength;
+    return `staging_deferred:${diskReason}`;
+}
 /**
  * Decrements the per-sync budget when a file fits, or returns a deferred-skip
  * reason when it does not. The object budget bounds request count; the byte

package/dist/adapters/raw-evidence-completeness.js

@@ -21,6 +21,12 @@ export function markCapApplied(ledger, source, capType) {
         cap.applied = true;
 }
 export function markBudgetCapApplied(ledger, reason) {
+    if (reason === "delivery_terminal_refused")
+        return;
+    if (reason.startsWith("staging_deferred:")) {
+        markCapApplied(ledger, "raw_evidence", "staging_gate");
+        return;
+    }
     markCapApplied(ledger, "raw_evidence", reason === "deferred_object_budget" ? "object_budget" : "byte_budget");
 }
 // ---------------------------------------------------------------------------

package/dist/adapters/raw-evidence-git-diff-reader.js

@@ -19,7 +19,7 @@ import { sha256 } from "./raw-evidence-keys.js";
 import { maskSecretsInGitDiff, } from "./raw-evidence-sanitize.js";
 import { markBudgetCapApplied, markCapApplied, recordScanned, } from "./raw-evidence-completeness.js";
 import { evidenceEntry } from "./raw-evidence-manifest.js";
-import { admitToBudget, stageEvidenceBytes, } from "./raw-evidence-collection-state.js";
+import { admitEvidence, stageEvidenceBytes, } from "./raw-evidence-collection-state.js";
 import { MAX_GIT_DIFF_BYTES, REPO_ROOT_MISSING_REASON, RepoRootMissingError, repoRootExists, runGitDiff, } from "./raw-evidence-git-diff.js";
 const GIT_DIFF_TARGETS = [
     { label: "unstaged", args: ["diff", "--no-ext-diff", "--"] },
@@ -130,7 +130,7 @@ async function stageOneGitDiff(collection, target) {
         });
         return;
     }
-    const deferReason = admitToBudget(collection.budget, sanitized.bytes.byteLength);
+    const deferReason = admitEvidence(collection, sanitized.bytes.byteLength, { contentHash, kind: "git_diff" });
     if (deferReason) {
         markBudgetCapApplied(collection, deferReason);
         collection.skipped.push({

package/dist/adapters/raw-evidence-image-reader.js

@@ -13,7 +13,7 @@ import { evidenceSourceKey } from "../raw-evidence-staging.js";
 import { sha256 } from "./raw-evidence-keys.js";
 import { markBudgetCapApplied, recordScanned, } from "./raw-evidence-completeness.js";
 import { evidenceEntry } from "./raw-evidence-manifest.js";
-import { admitToBudget, stageEvidenceBytes, } from "./raw-evidence-collection-state.js";
+import { admitEvidence, stageEvidenceBytes, } from "./raw-evidence-collection-state.js";
 export async function collectAgentImagesFromTranscript(collection, options) {
     const result = await collectAgentImageEvidenceFromJsonlFile({
         filePath: options.filePath,
@@ -56,7 +56,10 @@ async function collectOneAgentImageFile(collection, options) {
         });
         return;
     }
-    const deferReason = admitToBudget(collection.budget, raw.byteLength);
+    const deferReason = admitEvidence(collection, raw.byteLength, {
+        contentHash,
+        kind: options.kind,
+    });
     if (deferReason) {
         markBudgetCapApplied(collection, deferReason);
         collection.skipped.push({

package/dist/adapters/raw-evidence-transcript-file.js

@@ -20,7 +20,7 @@ import { maskSecretsInTranscript, } from "./raw-evidence-sanitize.js";
 import { markBudgetCapApplied, markCapApplied, } from "./raw-evidence-completeness.js";
 import { evidenceEntry } from "./raw-evidence-manifest.js";
 import { describeSnapshot, stubReplacementClaim, supersedeClaimFor, } from "./raw-evidence-snapshot-supersede.js";
-import { admitToBudget, stageEvidenceBytes, } from "./raw-evidence-collection-state.js";
+import { admitEvidence, stageEvidenceBytes, } from "./raw-evidence-collection-state.js";
 /**
  * Reads, secret-guards, content-addresses, budget-checks, and copies one
  * attributed transcript into the pack.
@@ -82,7 +82,7 @@ export async function collectOneEvidenceFile(collection, options) {
         });
         return true;
     }
-    const deferReason = admitToBudget(collection.budget, sanitized.bytes.byteLength);
+    const deferReason = admitEvidence(collection, sanitized.bytes.byteLength, { contentHash, kind: options.kind });
     if (deferReason) {
         markBudgetCapApplied(collection, deferReason);
         return skip(deferReason);

package/dist/commands/backfill-upload.js

@@ -7,6 +7,7 @@ import { countSessionUploadFailures, deferredEvidenceCount, durableBackfillCandi
 import { blockingScanIssues } from "./backfill-issues.js";
 import { ensureOutsideRootsWorkspace, isOutsideRootsWorkspace, } from "./backfill-outside-roots.js";
 import { writeLine } from "./backfill-output.js";
+import { stagingDeferredFiles } from "../staging-gate.js";
 import { stubClaimsForCandidates } from "./backfill-stub-reoffer.js";
 const BACKFILL_MAX_CONSECUTIVE_FAILURES = 3;
 /**
@@ -92,6 +93,17 @@ export async function uploadBackfillBatches(command, io, lock, ctx) {
             failureReason = "deferred_budget_exhausted";
             break;
         }
+        // BLI-12832: the disk gate refused a copy. Every later batch would be
+        // refused the same way, so stop here; the cursor only advanced through
+        // sessions that earned a durable pointer, and the next run starts from
+        // the same place once room returns.
+        const stagingDeferred = stagingDeferredFiles(rawEvidenceBudget.staging);
+        if (stagingDeferred > 0) {
+            blockedAt = stoppedAt("staging paused: not enough room to copy more evidence", index);
+            failureReason = "deferred_budget_exhausted";
+            console.error("[backfill] stopped, the staging gate is holding new copies", JSON.stringify({ reason: "staging_deferred", files_deferred: stagingDeferred, batch_index: index + 1 }));
+            break;
+        }
         if (consecutiveFailures >= BACKFILL_MAX_CONSECUTIVE_FAILURES) {
             blockedAt = stoppedAt("consecutive upload failures", index);
             failureReason = failedBatchReason(outcome.sync, outcome.missingDurableMain);

package/dist/commands/doctor-disk-words.js

@@ -57,6 +57,26 @@ export function footprintBuckets(footprint) {
     ];
     return buckets.filter((bucket) => bucket.bytes > 0).sort((a, b) => b.bytes - a.bytes);
 }
+/**
+ * BLI-12832: the sentence for a paused staging gate, in plain words. Every
+ * variant says the same two true things: nothing is lost (the source file is
+ * still on disk), and copying resumes by itself.
+ */
+export function stagingPausedWords(gate, holder) {
+    if (gate.reason === "low_disk") {
+        return `Tower paused copying new evidence: the disk has ${gib(gate.free_bytes ?? 0)} GB free. Nothing is lost; it resumes when space returns.`;
+    }
+    if (gate.reason === "state_over_ceiling") {
+        return `Tower paused copying new evidence: everything it keeps here is ${mib(gate.collector_bytes)} MB, over its ${mib(gate.ceiling_bytes)} MB ceiling${holder ? `, mostly ${holder.label} (${mib(holder.bytes)} MB)` : ""}. Nothing is lost; it resumes when that shrinks.`;
+    }
+    if (gate.reason === "staging_at_cap") {
+        return `Tower paused copying new evidence: its staging folder is full (${mib(gate.staging_bytes)} MB of a ${mib(gate.cap_bytes)} MB cap) with evidence the server has not accepted yet. Nothing is lost; the sources stay on disk and copying resumes once uploads succeed.`;
+    }
+    return null;
+}
+export function gib(bytes) {
+    return (bytes / (1024 * 1024 * 1024)).toFixed(1);
+}
 export function footprintTotalBytes(footprint) {
     return footprintBuckets(footprint).reduce((sum, bucket) => sum + bucket.bytes, 0);
 }

package/dist/commands/doctor-pipeline.js

@@ -5,12 +5,13 @@ import { readBackfillCompletionMarker, readBackfillCursor, } from "../cursors/ba
 import { savedDiscoveryLimitArgs } from "../discovery-limits.js";
 import { runStagingPrune } from "../disk-prune.js";
 import { retentionOptionsFromEnv } from "../disk-retention.js";
+import { readStagingGate, stagingGateLimitsFromEnv } from "../staging-gate.js";
 import { readDiskFootprint } from "../disk-usage.js";
 import { runEvidenceRedelivery } from "../evidence-redelivery.js";
 import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths } from "../local-state.js";
 import { runRawEvidenceLocalGc, rawEvidenceGcSummary } from "../raw-evidence-gc.js";
 import { runBackfillCommand } from "./backfill.js";
-import { FOOTPRINT_NEEDS_FIX_BYTES, diskRowMessage, footprintHolder, footprintTotalBytes, mib, redeliveryLine, } from "./doctor-disk-words.js";
+import { FOOTPRINT_NEEDS_FIX_BYTES, stagingPausedWords, diskRowMessage, footprintHolder, footprintTotalBytes, mib, redeliveryLine, } from "./doctor-disk-words.js";
 import { doctorRoots } from "./doctor-access.js";
 import { backfillCompletionStepState, backfillFixVerdict, jsonField, parseDoctorBackfillJson, parseDoctorSyncJson, syncFailureMessage, syncBacklogDrainingVerdict, syncStandAsideVerdict, } from "./doctor-pipeline-verdicts.js";
 import { asRecord, fail, needsFix, ok, skipped } from "./doctor-report.js";
@@ -162,34 +163,55 @@ export async function checkDiskState(context) {
     const footprint = await readDiskFootprint(getCollectorRuntimePaths(context.command.homeDir));
     const { capBytes } = retentionOptionsFromEnv(context.io.env);
     const message = diskRowMessage(footprint, capBytes);
+    const paused = await stagingPausedRow(context, footprint, message);
+    if (paused)
+        return paused;
     if (footprint.staging.total_bytes - (footprint.staging.terminal_bytes ?? 0) > capBytes) {
         return needsFix("disk-bounded", "over_staging_cap", message);
     }
-    const over = footprintOverSentence(footprint);
+    const over = footprintOverSentence(footprint, stagingGateLimitsFromEnv(context.io.env).ceilingBytes);
     if (over)
         return needsFix("disk-bounded", "footprint_over_512mb", `${over}; ${message}`);
     return ok("disk-bounded", "within_staging_cap", message);
 }
+/**
+ * BLI-12832: the row for a paused staging gate, or null when copying is open.
+ * Plain words first, then the numbers; logged either way so a green row can
+ * still say the gate was checked.
+ */
+async function stagingPausedRow(context, footprint, message) {
+    const gate = await readStagingGate(getCollectorRuntimePaths(context.command.homeDir).state_dir, context.io.env);
+    const words = stagingPausedWords(gate, footprintHolder(footprint));
+    console.error("[cockpit-doctor] staging gate", JSON.stringify({
+        reason: gate.reason ?? "open",
+        staging_bytes: gate.staging_bytes,
+        collector_bytes: gate.collector_bytes,
+        free_bytes: gate.free_bytes,
+    }));
+    if (!words || !gate.reason)
+        return null;
+    return needsFix("disk-bounded", `staging_paused_${gate.reason}`, `${words} ${message}`);
+}
 /**
  * "812.0 MB held, over the 512 MB line; most of it is sync logs (600.0 MB)",
  * or null when the footprint is under the line. Logged either way, because a
  * row that only speaks when it is red cannot say the check ran.
  */
-export function footprintOverSentence(footprint) {
+export function footprintOverSentence(footprint, ceilingBytes = FOOTPRINT_NEEDS_FIX_BYTES) {
     const total = footprintTotalBytes(footprint);
     const holder = footprintHolder(footprint);
-    const over = total > FOOTPRINT_NEEDS_FIX_BYTES;
+    const over = total > ceilingBytes;
     console.error("[cockpit-doctor] collector footprint", JSON.stringify({
         reason: over ? "footprint_over_512mb" : "footprint_within_512mb",
         total_bytes: total,
-        limit_bytes: FOOTPRINT_NEEDS_FIX_BYTES,
+        limit_bytes: ceilingBytes,
         holder: holder?.label ?? null,
         holder_bytes: holder?.bytes ?? 0,
         study_entries_not_counted: footprint.state.study_entries,
     }));
     if (!over)
         return null;
-    return `${mib(total)} MB held, over the ${mib(FOOTPRINT_NEEDS_FIX_BYTES)} MB line; most of it is ${holder?.label ?? "unknown"} (${mib(holder?.bytes ?? 0)} MB)`;
+    return `${mib(total)} MB held, over the ${mib(ceilingBytes)} MB line; most of it is ${holder?.label ?? "unknown"} (${mib(holder?.bytes ?? 0)} MB)`;
 }
 export async function fixDiskState(context) {
     const paths = getCollectorRuntimePaths(context.command.homeDir);
@@ -216,11 +238,16 @@ export async function fixDiskState(context) {
     }
     const footprint = await readDiskFootprint(paths);
     const message = diskRowMessage(footprint, pruned.cap_bytes);
-    const over = pruned.cap_blocked_by_uncommitted ? null : footprintOverSentence(footprint);
+    const over = pruned.cap_blocked_by_uncommitted
+        ? null
+        : footprintOverSentence(footprint, stagingGateLimitsFromEnv(context.io.env).ceilingBytes);
     if (over) {
         return needsFix("disk-bounded", "footprint_over_512mb", `freed ${mib(pruned.deleted_bytes)} MB; ${over}; ${message}`);
     }
     if (!pruned.cap_blocked_by_uncommitted) {
+        const stillPaused = await stagingPausedRow(context, footprint, `freed ${mib(pruned.deleted_bytes)} MB; ${message}`);
+        if (stillPaused)
+            return stillPaused;
         return ok("disk-bounded", `freed_${pruned.deleted_files}`, `freed ${mib(pruned.deleted_bytes)} MB; ${message}`);
     }
     // Unaccepted evidence still occupies the cap. Keep the disk row actionable.

package/dist/commands/local-args-tower-logs.js

@@ -0,0 +1,53 @@
+/**
+ * `cockpit logs` argument parsing (BLI-12833).
+ *
+ *   cockpit logs <source> [--since 15m|1h|2d|<iso>] [--raw <template-id>] [--limit <n>]
+ *                [--all-levels] [--table <file>] [--json]
+ *
+ * <source> is `collector`, `dashboard`, `railway`, `railway:<service>` or `-`
+ * (lines on stdin). Read-only: the digest is computed on this machine from the
+ * source's own CLI or files; nothing is sent to Tower and no dashboard is
+ * called, so there is no `--dashboard-url`.
+ */
+import { optionalNonEmpty, optionalPositiveInteger, parseNamedArgs } from "./local-arg-values.js";
+/** The source spellings, for the usage line and the refusal. `railway:<service>` takes any service name. */
+export const LOGS_SOURCES = ["collector", "dashboard", "railway", "railway:<service>", "-"];
+const SOURCE_PATTERN = /^(collector|dashboard|railway|railway:[A-Za-z0-9][A-Za-z0-9._-]{0,63}|-)$/;
+const SINCE_PATTERN = /^(\d{1,4}[smhd]|\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d{1,9})?)?(Z|[+-]\d{2}:\d{2})?)?)$/;
+export function parseLogsArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: ["--home", "--since", "--raw", "--limit", "--table", "--all-levels", "--json"],
+        valueFlags: ["--home", "--since", "--raw", "--limit", "--table"],
+    });
+    const source = values.positionals[0];
+    if (!source || !SOURCE_PATTERN.test(source)) {
+        throw new Error(`logs needs a source: ${LOGS_SOURCES.join(", ")}. Example: \`cockpit logs dashboard --since 1h\`.`);
+    }
+    if (values.positionals.length > 1)
+        throw new Error("logs takes one source; put the window in --since.");
+    const since = optionalNonEmpty(values.flags.get("--since"));
+    if (since && !SINCE_PATTERN.test(since)) {
+        throw new Error(`--since wants 15m, 1h, 2d or an ISO time like 2026-10-07T03:00Z; got ${JSON.stringify(since.slice(0, 40))}.`);
+    }
+    const raw = optionalNonEmpty(values.flags.get("--raw"));
+    if (raw && !/^[0-9a-f]{8}$/.test(raw)) {
+        throw new Error("--raw wants the 8 hex characters a digest line starts with.");
+    }
+    const rawLimit = optionalPositiveInteger(values.flags.get("--limit"), "--limit");
+    if (rawLimit !== undefined && !raw)
+        throw new Error("--limit counts the original lines --raw prints.");
+    if (values.booleans.has("--all-levels") && source !== "dashboard") {
+        throw new Error("--all-levels belongs to `cockpit logs dashboard`.");
+    }
+    return {
+        kind: "logs",
+        source,
+        ...(since ? { since } : {}),
+        ...(raw ? { raw } : {}),
+        ...(rawLimit === undefined ? {} : { rawLimit }),
+        ...(values.flags.get("--table") ? { tableFile: values.flags.get("--table") } : {}),
+        allLevels: values.booleans.has("--all-levels"),
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        json: values.booleans.has("--json"),
+    };
+}

package/dist/commands/local-args-tower.js

@@ -38,5 +38,6 @@ export { parseModelsArgs } from "./local-args-tower-models.js";
 export { parseMailArgs } from "./local-args-tower-mail.js";
 export { parseCalArgs } from "./local-args-tower-cal.js";
 export { parseUsageArgs } from "./local-args-tower-usage.js";
+export { parseLogsArgs } from "./local-args-tower-logs.js";
 export { parseCareersArgs } from './local-args-tower-careers.js';
 export { parseRenameArgs } from './local-args-tower-rename.js';

package/dist/commands/local-args.js

@@ -18,7 +18,7 @@
 import { parseRootsArgs } from "./roots.js";
 import { SURFACE_ALIASES } from "./local-help.js";
 import { parseAgentRulesArgs, parseAnalyzeArgs, parseAutostartArgs, parseBackfillArgs, parseCleanArgs, parseDoctorArgs, parseInstallArgs, parseLoginArgs, parseMemoryArgs, parseLogoutArgs, parseOnboardArgs, parseReleaseArgs, parseServeArgs, parseSessionsArgs, parseSourcesArgs, parseStartArgs, parseStatusArgs, parseSyncArgs, parseUpdateArgs, } from "./local-args-collector.js";
-import { parseBriefArgs, parseCorrectArgs, parseDocsArgs, parseIssueArgs, parseJarvisArgs, parseMailArgs, parseCalArgs, parseModelArgs, parseMsgArgs, parseNotesArgs, parseOpsArgs, parseProjectArgs, parseModelsArgs, parseScoutArgs, parseGithubArgs, parseSearchArgs, parseSettingsArgs, parseSlackArgs, parseTeamArgs, parseWorkbookArgs, parseUsageArgs, parseCareersArgs, parseRenameArgs, } from "./local-args-tower.js";
+import { parseBriefArgs, parseCorrectArgs, parseDocsArgs, parseIssueArgs, parseJarvisArgs, parseMailArgs, parseCalArgs, parseModelArgs, parseMsgArgs, parseNotesArgs, parseOpsArgs, parseProjectArgs, parseModelsArgs, parseScoutArgs, parseGithubArgs, parseSearchArgs, parseSettingsArgs, parseSlackArgs, parseTeamArgs, parseWorkbookArgs, parseUsageArgs, parseLogsArgs, parseCareersArgs, parseRenameArgs, } from "./local-args-tower.js";
 // `normalizeUrl` has always been part of this module's surface — `local.ts` and
 // `local-auth.ts` import it from here — so it stays exported from this address
 // even though it now lives next door. The same goes for the four names the
@@ -133,6 +133,8 @@ export function parseLocalArgs(argv) {
             return parseRenameArgs(argv.slice(1));
         case "usage":
             return parseUsageArgs(argv.slice(1));
+        case "logs":
+            return parseLogsArgs(argv.slice(1));
         default:
             throw new Error(`Unknown local command: ${command ?? ""}`);
     }

package/dist/commands/local-command-shapes-logs.js

@@ -0,0 +1,6 @@
+/**
+ * `cockpit logs` command shape (BLI-12833), beside `local-command-shapes.ts` for
+ * the same reason `local-command-shapes-github.ts` is: that file sits at the
+ * readability ceiling.
+ */
+export {};

package/dist/commands/local-help-commands-tower-ops.js

@@ -10,6 +10,32 @@
  * something breaks, so it is a user-visible contract like any other.
  */
 export const TOWER_OPS_COMMAND_HELP = [
+    [
+        "logs",
+        [
+            "Usage: cockpit logs <collector|dashboard|railway|railway:<service>|-> [--since 15m|1h|2d|<iso>] [--raw <template-id> [--limit <n>]] [--all-levels] [--table <file>] [--json]",
+            "",
+            "A token-cheap digest of Tower's own logs, read on THIS machine (nothing is uploaded). Variable parts of",
+            "each line are masked into a template, equal templates are counted, routine runs become counts, and every",
+            "template is classified: our_bug and unknown first, then capacity, config_drift, rate_pushback, hiccup,",
+            "and one COUNTED line for dead_source and benign (counted, never alerted). About 2 KB.",
+            "  collector           this machine's sync.log, sync.err.log and their rotated archives (hook logs go to sync.err.log).",
+            "                      These logs have no per-line time, so the window is approximate (the digest says so).",
+            "  dashboard           Vercel runtime logs of bli-cockpit-dashboard (team bli-inc) through the `vercel` CLI.",
+            "                      Reads what Vercel marks error, warning or fatal plus every 5xx; --all-levels reads everything (slow).",
+            "  railway             every service of the bli-cockpit-inference project through the `railway` CLI;",
+            "  railway:<service>   one service (ladder, runner, linear-sync, ...). Project and environment are always passed",
+            "                      explicitly: this repo's `railway link` points at the runner service.",
+            "  -                   lines on stdin: plain text, `journalctl -o json`, `railway logs --json` or `vercel logs --json`.",
+            "--raw <template-id>   the original lines behind one template id from a digest (redacted, newest last; --limit n, default 20).",
+            "--table <file>        a class table JSON (same shape as the packaged one) to try a new pattern before committing it.",
+            "A source that cannot be read is a named refusal, never a stack trace: vercel_cli_missing, vercel_not_logged_in,",
+            "railway_cli_missing, railway_not_logged_in, railway_service_unknown, collector_logs_missing, stdin_is_terminal, ...",
+            "--json writes one object to stdout: { ok, kind, source, window, lines, templates[], routine, notes, text, measure };",
+            "a refusal is { ok: false, error, detail } and exits 1. Run list and teaching: docs/runbooks/tower-logs.md.",
+            "The bli-tower MCP server has the twin: logs_digest.",
+        ],
+    ],
     [
         "github",
         [

package/dist/commands/local-help.js

@@ -78,6 +78,7 @@ export const rootCommandNames = new Set([
     "careers",
     "rename",
     "usage",
+    "logs",
     ...SURFACE_ALIASES.keys(),
 ]);
 /** Public names omit compatibility spellings while the router keeps accepting them. */
@@ -132,6 +133,7 @@ export function localCommandHelp(command) {
         "  cockpit release [--dry-run] [--skip-checks] [--no-floor] [--tag <tag>] [--access <public|restricted>] [--otp <code>]",
         "  cockpit careers [list|show <id>|rescreen <id>|send-takehome <id>|decide <id> --decision <passed_on|archived|reopen>|followup <id> [--record-sent-at <iso>]|interview <id> <--at <iso>|--clear>|grade <id> [--now]|resume <id> [--out <path>]|takehome show <role>|takehome set <role> --body-file <path>|settings show|settings set --enabled <true|false> --followup-enabled <true|false> --followup-after-days <n> --takehome-window-hours <n>] [--role <slug>] [--min-score <n>] [--since <date>] [--stage <s>] [--force] [--json]",
         "  cockpit rename [list|resolve <id> --scope <page|everywhere|undo>] [--dashboard-url <url>] [--json]",
+        "  cockpit logs <collector|dashboard|railway|railway:<service>|-> [--since 15m|1h|2d|<iso>] [--raw <template-id> [--limit <n>]] [--all-levels] [--table <file>] [--json]",
         "  cockpit usage sessions [--task <BLI-NNNN> | --subject <name>] [--repo <label>] [--since <window>] [--json]",
         "  cockpit usage sessions --session <id> [--from-window <n>] [--json]",
         "  --by-topic groups work types; --by-subject groups open subjects from session summaries.",

package/dist/commands/local.js

@@ -49,6 +49,7 @@ import { runSearch } from "./search.js";
 import { runCareers } from "./careers.js";
 import { runRename } from "./rename-scope.js";
 import { runUsage } from "./usage.js";
+import { runLogs } from "./logs.js";
 import { parseLocalArgs } from "./local-args.js";
 // `./local.js` is the published entry point for this command surface: the
 // public CLI's generated root, commands/root.ts, doctor.ts and the test suite
@@ -242,6 +243,8 @@ export async function runLocalCockpitCli(argv, io = defaultIo()) {
                 return await runRename(command, io);
             case "usage":
                 return await runUsage(command, io);
+            case "logs":
+                return await runLogs(command, io);
         }
     }
     catch (error) {

package/dist/commands/logs.js

@@ -0,0 +1,68 @@
+/**
+ * `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 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, digestSource } from "@bli-cockpit/telemetry-core/log-digest";
+import { getCollectorRuntimePaths } from "../local-state-paths.js";
+import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.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 = {}) {
+    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)
+        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.173");
     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)" },

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;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.170",
+  "version": "0.2.173",
   "private": false,
   "type": "module",
   "bin": {
@@ -27,9 +27,9 @@
     "test": "node dist/cli.js --help && node ../../scripts/assert-public-cli-routing.mjs && node ../../scripts/assert-public-cli-verb-help.mjs && node ../../scripts/assert-public-cli-surface-doors.mjs && node ../../scripts/assert-public-cli-runtime-files.mjs && node ../../scripts/assert-public-cli-exit-contract.mjs && node ../../scripts/assert-public-cli-no-fleet-posts.mjs && node ../../scripts/assert-public-cli-doctor-json.mjs && node ../../scripts/assert-public-package-pack.mjs --workspace=@bli-cockpit/cli"
   },
   "dependencies": {
-    "@bli-cockpit/memory-mcp": "0.1.46",
-    "@bli-cockpit/mcp": "0.1.87",
-    "@bli-cockpit/telemetry-core": "0.1.58"
+    "@bli-cockpit/memory-mcp": "0.1.47",
+    "@bli-cockpit/mcp": "0.1.89",
+    "@bli-cockpit/telemetry-core": "0.1.59"
   },
   "repository": {
     "type": "git",