@bli-cockpit/cli 0.2.50 → 0.2.52

package/dist/commands/clean.js

@@ -0,0 +1,191 @@
+/**
+ * `cockpit clean` — what this machine is holding, why, and what goes.
+ *
+ * BLI-3619. The tick prunes on its own once a day; this is the door a person
+ * opens when a laptop is full now. It prints the same buckets the retention
+ * rule reasons in, one line each with its reason, and only then deletes:
+ *
+ *   committed, past the 48 h retry window   goes
+ *   committed, still inside the window      kept — unless the cap needs it
+ *   uncommitted                             kept, always, and named
+ *   the ledger cannot say                   kept, always, and named apart
+ *
+ * `--dry-run` stops after the printing. `--all-committed` drops the retry
+ * window — every committed spare goes now — and is also the only thing that
+ * removes a `manual-study-evidence-vault-*` directory, and then only when every
+ * object inside it is committed. Nothing here can delete evidence the upload
+ * ledger did not vouch for; that line is in `disk-retention.ts` and this
+ * command has no way to cross it.
+ */
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { writeLine } from "./cli-io.js";
+import { planFromDisk, runStagingPrune } from "../disk-prune.js";
+import { MANUAL_VAULT_PREFIX, readDiskFootprint, } from "../disk-usage.js";
+import { readRawEvidenceCursor } from "../cursors/raw-evidence-cursor.js";
+import { getCollectorRuntimePaths, } from "../local-state.js";
+import { rotateCollectorLogsBestEffort } from "../log-rotation.js";
+export async function runClean(command, io) {
+    const paths = getCollectorRuntimePaths(command.homeDir);
+    const now = new Date();
+    const env = io.env ?? process.env;
+    const footprint = await readDiskFootprint(paths, now);
+    const plan = await planFromDisk(paths, env, { allCommitted: command.allCommitted }, now);
+    const vaults = command.allCommitted
+        ? await vaultsSafeToRemove(paths, footprint.vaults)
+        : [];
+    if (!command.json) {
+        for (const line of cleanLines(footprint, plan, vaults, command)) {
+            writeLine(io.stdout, line);
+        }
+    }
+    if (command.dryRun) {
+        if (command.json)
+            writeLine(io.stdout, cleanJson(footprint, plan, vaults, null));
+        return 0;
+    }
+    const pruned = await runStagingPrune(paths, {
+        env,
+        now,
+        force: true,
+        allCommitted: command.allCommitted,
+    });
+    // The two smaller footprints go with it: a rotation pass sweeps the archives
+    // outside the keep window, and each removed vault is named on its own line.
+    await rotateCollectorLogsBestEffort(paths);
+    const removedVaults = await removeVaults(paths.state_dir, vaults, io);
+    if (command.json) {
+        writeLine(io.stdout, cleanJson(footprint, plan, vaults, pruned));
+        return pruned.status === "fail" ? 1 : 0;
+    }
+    writeLine(io.stdout, `Freed ${mb(pruned.deleted_bytes)} MB across ${pruned.deleted_files} file(s) and ${pruned.removed_packs} pack(s)${removedVaults > 0 ? `, plus ${removedVaults} evidence vault(s)` : ""}.`);
+    if (pruned.cap_blocked_by_uncommitted) {
+        writeLine(io.stdout, `Still ${mb(pruned.bytes_after)} MB over a ${mb(pruned.cap_bytes)} MB cap, held by ${pruned.cap_blocked_count} object(s) the upload ledger cannot vouch for. Run \`cockpit sync\` to try delivering them; nothing here will delete them.`);
+    }
+    return pruned.status === "fail" ? 1 : 0;
+}
+/** The bucket table a person reads before anything is deleted. */
+export function cleanLines(footprint, plan, vaults, command) {
+    const staging = footprint.staging;
+    const lines = [
+        command.dryRun ? "Tower clean (dry run)" : "Tower clean",
+        `  staging          ${mb(staging.total_bytes)} MB across ${staging.pack_count} pack(s), ${staging.object_count} file(s)`,
+        `  going            ${mb(plan.deleted_bytes + plan.empty_pack_manifest_bytes)} MB, ${plan.delete.length} file(s) — ${command.allCommitted
+            ? "every committed copy (--all-committed)"
+            : `committed and past the ${Math.round(plan.retention_ms / 3_600_000)} h retry window`}`,
+        `  kept in window   ${mb(plan.kept_in_window.bytes)} MB, ${plan.kept_in_window.count} file(s) — committed, still inside the retry window`,
+        `  kept uncommitted ${mb(plan.kept_uncommitted.bytes)} MB, ${plan.kept_uncommitted.count} file(s) — never delivered; retention will never delete these`,
+        `  kept unknown     ${mb(plan.kept_unknown.bytes)} MB, ${plan.kept_unknown.count} file(s) — the upload ledger no longer reaches back this far and cannot say`,
+        `  rotated logs     ${mb(footprint.logs.total_bytes)} MB (${footprint.logs.archive_count} archive(s))`,
+        `  spool            ${mb(footprint.spool_bytes)} MB`,
+    ];
+    for (const vault of footprint.vaults) {
+        const removable = vaults.some((entry) => entry.name === vault.name);
+        lines.push(`  ${vault.name} ${mb(vault.byte_size)} MB, ${vault.file_count} file(s) — ${removable
+            ? "every object inside is committed; --all-committed removes it"
+            : "a one-off you made by hand; nothing here removes it"}`);
+    }
+    if (plan.cap_blocked_by_uncommitted) {
+        lines.push(`  over cap         ${mb(plan.bytes_after)} MB against a ${mb(plan.cap_bytes)} MB cap, held by ${plan.cap_blocked_count} object(s) no ledger vouches for (staging_cap_blocked_by_uncommitted)`);
+    }
+    return lines;
+}
+function cleanJson(footprint, plan, vaults, pruned) {
+    return JSON.stringify({
+        staging: {
+            pack_count: footprint.staging.pack_count,
+            object_count: footprint.staging.object_count,
+            total_bytes: footprint.staging.total_bytes,
+            committed_bytes: footprint.staging.committed_bytes,
+            uncommitted_bytes: footprint.staging.uncommitted_bytes,
+            unknown_bytes: footprint.staging.unknown_bytes,
+            oldest_uncommitted_at: footprint.staging.oldest_uncommitted_at,
+        },
+        rotated_log_bytes: footprint.logs.total_bytes,
+        spool_bytes: footprint.spool_bytes,
+        vaults: footprint.vaults,
+        plan: {
+            delete_count: plan.delete.length,
+            delete_bytes: plan.deleted_bytes + plan.empty_pack_manifest_bytes,
+            kept_in_window: plan.kept_in_window,
+            kept_uncommitted: plan.kept_uncommitted,
+            kept_unknown: plan.kept_unknown,
+            cap_bytes: plan.cap_bytes,
+            cap_blocked_by_uncommitted: plan.cap_blocked_by_uncommitted,
+        },
+        removable_vaults: vaults.map((vault) => vault.name),
+        pruned,
+    }, null, 2);
+}
+/**
+ * A hand-made evidence vault may only go when EVERY object inside it is
+ * committed. The vault is not a pack — it has no manifest — so each file is
+ * hashed and looked up. That is why it is on the explicit `--all-committed`
+ * door and never on the tick.
+ */
+async function vaultsSafeToRemove(paths, vaults) {
+    if (vaults.length === 0)
+        return [];
+    const cursor = await readRawEvidenceCursor(paths);
+    const committed = new Set(Object.keys(cursor.objects));
+    const safe = [];
+    for (const vault of vaults) {
+        const dir = path.join(paths.state_dir, vault.name);
+        if (await everyFileCommitted(dir, committed))
+            safe.push(vault);
+    }
+    return safe;
+}
+async function everyFileCommitted(dir, committed) {
+    const stack = [dir];
+    let sawFile = false;
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (!current)
+            continue;
+        const entries = await fs
+            .readdir(current, { withFileTypes: true })
+            .catch(() => []);
+        for (const entry of entries) {
+            const full = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(full);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            sawFile = true;
+            const bytes = await fs.readFile(full).catch(() => null);
+            if (!bytes)
+                return false;
+            const digest = crypto.createHash("sha256").update(bytes).digest("hex");
+            if (!committed.has(digest))
+                return false;
+        }
+    }
+    return sawFile;
+}
+async function removeVaults(stateDir, vaults, io) {
+    let removed = 0;
+    for (const vault of vaults) {
+        if (!vault.name.startsWith(MANUAL_VAULT_PREFIX))
+            continue;
+        const done = await fs
+            .rm(path.join(stateDir, vault.name), { recursive: true, force: true })
+            .then(() => true, () => false);
+        if (!done)
+            continue;
+        removed += 1;
+        writeLine(io.stderr, `[collector prune] removed an evidence vault ${JSON.stringify({
+            reason: "vault_all_committed",
+            vault: vault.name,
+            byte_size: vault.byte_size,
+            file_count: vault.file_count,
+        })}`);
+    }
+    return removed;
+}
+function mb(bytes) {
+    return (bytes / (1024 * 1024)).toFixed(1);
+}

package/dist/commands/doctor.js

@@ -9,6 +9,9 @@ import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths, LOCAL_COLLECTOR_VERSIO
 import { normalizeCollectionRoots } from "../root-normalization.js";
 import { detectSecondCockpitInstall } from "../second-install.js";
 import { runRawEvidenceLocalGc, rawEvidenceGcSummary } from "../raw-evidence-gc.js";
+import { runStagingPrune } from "../disk-prune.js";
+import { retentionOptionsFromEnv } from "../disk-retention.js";
+import { readDiskFootprint } from "../disk-usage.js";
 import { runBackfillCommand } from "./backfill.js";
 import { installMemoryIntegration, inspectMemoryIntegration, } from "./memory-install.js";
 import { createInteractiveExecRunner } from "../process-runner.js";
@@ -100,6 +103,15 @@ function doctorInvariants() {
             check: (context) => context.deps.checkGc(context),
             fix: (context, _state) => context.deps.fixGc(context),
         },
+        // BLI-3619. Runs after the GC because it answers the question the GC
+        // cannot: the GC only removes a whole pack whose every file is committed,
+        // so one undelivered file kept 20 GB alive on the reference Mac. This row
+        // reads the disk per FILE against the upload ledger and says what is on it.
+        {
+            id: "disk-bounded",
+            check: (context) => context.deps.checkDisk(context),
+            fix: (context, _state) => context.deps.fixDisk(context),
+        },
         {
             id: "sync-fresh",
             check: (context) => context.deps.checkSync(context),
@@ -126,6 +138,8 @@ function defaultDoctorDeps(hooks) {
         fixBackfill: fixBackfillState,
         checkGc: checkGcState,
         fixGc: fixGcState,
+        checkDisk: checkDiskState,
+        fixDisk: fixDiskState,
         checkSync: checkSyncState,
         fixSync: fixSyncState,
     };
@@ -449,6 +463,60 @@ async function fixGcState(context) {
     }
     return ok("gc-checked", `removed_${result.removed_dirs}`, rawEvidenceGcSummary(result));
 }
+/**
+ * BLI-3619: what Cockpit is holding on this machine, in one line.
+ *
+ * Green means the staging tree fits under the cap. Over the cap is `needs_fix`
+ * and the fix is the same prune the tick runs, forced past its daily throttle;
+ * if it is still over afterwards, the message names the one command that goes
+ * further. Every number here is metadata — byte counts and file counts, never
+ * a path.
+ */
+async function checkDiskState(context) {
+    const footprint = await readDiskFootprint(getCollectorRuntimePaths(context.command.homeDir));
+    const { capBytes } = retentionOptionsFromEnv(context.io.env);
+    const message = diskRowMessage(footprint, capBytes);
+    return footprint.staging.total_bytes > capBytes
+        ? needsFix("disk-bounded", "over_staging_cap", message)
+        : ok("disk-bounded", "within_staging_cap", message);
+}
+async function fixDiskState(context) {
+    const paths = getCollectorRuntimePaths(context.command.homeDir);
+    const pruned = await runStagingPrune(paths, {
+        env: context.io.env,
+        force: true,
+    });
+    if (pruned.status === "fail") {
+        return fail("disk-bounded", pruned.reason, "the prune could not run; nothing was deleted");
+    }
+    if (pruned.status === "skipped") {
+        return skipped("disk-bounded", pruned.reason, "cleanup is switched off");
+    }
+    const footprint = await readDiskFootprint(paths);
+    const message = diskRowMessage(footprint, pruned.cap_bytes);
+    if (!pruned.cap_blocked_by_uncommitted) {
+        return ok("disk-bounded", `freed_${pruned.deleted_files}`, `freed ${mib(pruned.deleted_bytes)} MB; ${message}`);
+    }
+    // Deliberately still `ok`: staging over the cap because evidence has not been
+    // accepted yet is the collector working, not a machine to repair. The row
+    // names the blockage and the one command that goes further.
+    return ok("disk-bounded", "staging_cap_blocked_by_uncommitted", `freed ${mib(pruned.deleted_bytes)} MB; ${message}; ${pruned.cap_blocked_count} object(s) the upload ledger cannot vouch for are holding the rest — run \`cockpit sync\` to deliver them, or \`cockpit clean --all-committed\` to drop every accepted copy now`);
+}
+function diskRowMessage(footprint, capBytes) {
+    const staging = footprint.staging;
+    const parts = [
+        `staging ${mib(staging.total_bytes)} MB (${mib(staging.committed_bytes)} committed / ${mib(staging.uncommitted_bytes)} uncommitted / ${mib(staging.unknown_bytes)} unknown) against a ${mib(capBytes)} MB cap`,
+        `logs ${mib(footprint.logs.total_bytes)} MB`,
+        `spool ${mib(footprint.spool_bytes)} MB`,
+    ];
+    for (const vault of footprint.vaults) {
+        parts.push(`${vault.name} ${mib(vault.byte_size)} MB (a one-off; \`cockpit clean --all-committed\` removes it only if every file in it is accepted)`);
+    }
+    return parts.join("; ");
+}
+function mib(bytes) {
+    return (bytes / (1024 * 1024)).toFixed(1);
+}
 async function checkSyncState(context) {
     const roots = await doctorRoots(context);
     if (roots.length === 0) {

package/dist/commands/jarvis.js

@@ -102,7 +102,10 @@ export async function runJarvis(command, io) {
     const promptStartedAt = Date.now();
     const oneShotPrompt = await resolveOneShotPrompt(command, io);
     if (oneShotPrompt !== null) {
-        return sendOneTurn({
+        // A one-shot turn has nothing above it — this process printed no earlier
+        // answer — so it sends no previous answer and nothing is ever revised. The
+        // `sent_previous_answer: false` field on the answered line says so.
+        const turn = await sendOneTurn({
             command,
             dashboardUrl,
             deviceToken: session.device_token,
@@ -114,27 +117,38 @@ export async function runJarvis(command, io) {
                 promptMs: command.prompt ? null : Date.now() - promptStartedAt,
             },
         }, oneShotPrompt, io);
+        return turn.exitCode;
     }
     if (command.json) {
         throw new Error("cockpit jarvis --json needs --prompt, positional text, or piped stdin.");
     }
     writeLine(io.stdout, "JARVIS terminal chat. Type /exit to leave.");
+    // BLI-3567: the answer this session last printed, and the question it
+    // answered. It is what a correction typed on the next line can rewrite —
+    // kept here rather than read back off the ledger, for the same reason the
+    // browsers send their own bubble: what has to be revised is what is on the
+    // person's screen. A failed turn deliberately does not replace it; a "that
+    // did not go through" line is not an answer.
+    let previous = null;
     while (true) {
         const prompt = (await readLine(io, "you> ")).trim();
         if (!prompt)
             continue;
         if (prompt === "/exit" || prompt === "/quit")
             return 0;
-        const exitCode = await sendOneTurn({
+        const turn = await sendOneTurn({
             command,
             dashboardUrl,
             deviceToken: session.device_token,
             // The typing wait belongs to the person, not to the turn, so no prompt
             // span is reported for an interactive turn.
             boot: { bootMs, sessionMs, promptMs: null },
+            previous,
         }, prompt, io);
-        if (exitCode !== 0)
-            return exitCode;
+        if (turn.exitCode !== 0)
+            return turn.exitCode;
+        if (turn.reply)
+            previous = { answer: turn.reply, question: prompt };
     }
 }
 /**
@@ -242,7 +256,7 @@ async function sendOneTurn(context, prompt, io) {
         const read = await readAttachedImage(context.command.imagePath);
         if (!read.ok) {
             writeAttachmentRefusal(context.command, io, read.refusal, context.command.imagePath);
-            return 1;
+            return { exitCode: 1, reply: null };
         }
         attachment = read;
     }
@@ -277,12 +291,18 @@ async function sendOneTurn(context, prompt, io) {
                 // BLI-3484: which day's page this turn is about. Sent verbatim — the
                 // dashboard decides what counts as a date and whose day it is.
                 date: context.command.date,
+                // BLI-3567: the answer this session last printed, so a correction can
+                // rewrite the paragraph it contradicts. Absent on a one-shot turn and
+                // on the first turn of a session, which is how the dashboard knows
+                // there is nothing above to revise.
+                previousAnswer: context.previous?.answer,
+                previousQuestion: context.previous?.question,
             },
         log,
     });
     if (!requested.ok) {
         writeFailure(context.command, io, requested.reason, towerFailureDetail(requested.reason, requested.detail));
-        return 1;
+        return { exitCode: 1, reply: null };
     }
     // Live trace lines go to a person as they land, never to a `--json`
     // consumer: that contract is exactly one object on stdout, so the events are
@@ -302,6 +322,17 @@ async function sendOneTurn(context, prompt, io) {
                 liveTraceLines += 1;
         },
         onToken: (event) => live.token(event),
+        // BLI-3567: the paragraph being rewritten says so while it happens. The
+        // terminal cannot mark the paragraph itself — it printed it turns ago — so
+        // the pending state is one dim line, in the same words the browsers use.
+        onRevision: (event) => {
+            if (context.command.json)
+                return;
+            if (event.revision?.status !== "pending")
+                return;
+            live.interrupt();
+            writeLine(io.stdout, dim(`  ${ANSWER_UPDATING_LINE}`, colorEnabled(io)));
+        },
         onNote: (reason, detail) => {
             log(`[jarvis cli] stream note ${JSON.stringify({
                 reason,
@@ -312,7 +343,7 @@ async function sendOneTurn(context, prompt, io) {
     if (!turn.ok) {
         live.abandon();
         writeFailure(context.command, io, turn.reason, streamFailureDetail(turn.reason, turn.detail));
-        return 1;
+        return { exitCode: 1, reply: null };
     }
     const body = turn.final;
     const httpStatus = typeof turn.final.httpStatus === "number" ? turn.final.httpStatus : requested.response.status;
@@ -320,7 +351,7 @@ async function sendOneTurn(context, prompt, io) {
         live.abandon();
         const reason = body.error ?? body.reply ?? `http_${httpStatus}`;
         writeFailure(context.command, io, "turn_failed", reason);
-        return 1;
+        return { exitCode: 1, reply: null };
     }
     // A streaming server may leave the settled trace out of the final event
     // because it already sent every step live; the activity we collected is that
@@ -366,6 +397,10 @@ async function sendOneTurn(context, prompt, io) {
         // through `writeReply`, which is byte-for-byte what this command printed
         // before, BLI-3570's dim link line included.
         live.settle(body.reply, subject, body.revised === true);
+        // BLI-3567: what the correction did to the answer above, printed under
+        // this turn's reply because that is the only place a terminal has.
+        if (body.revision)
+            writeRevision(context.command, io, body.revision);
         // Only when nothing was drawn live — otherwise every tool would print twice.
         if (liveTraceLines === 0)
             writeTraceBlock(io, trace);
@@ -389,6 +424,13 @@ async function sendOneTurn(context, prompt, io) {
         // dashboard means the answer landed all at once.
         streamed_chars: turn.draft.length,
         revised: body.revised === true,
+        // BLI-3567: whether this turn was told there was an answer above it, and
+        // what the correction did to it. `sent_previous_answer: false` is a
+        // one-shot turn; a status with no revision at all is a dashboard that
+        // predates the step.
+        sent_previous_answer: Boolean(context.previous),
+        revision: body.revision?.status ?? null,
+        revision_reason: body.revision?.reason ?? null,
         // BLI-3582: `elapsed_ms` above is the whole wait as this side felt it;
         // these three say which part of it was the dashboard's prep, which was
         // the model's first token, and how long the socket stayed silent before
@@ -406,7 +448,7 @@ async function sendOneTurn(context, prompt, io) {
             timing: turn.timing,
         }),
     })}`);
-    return 0;
+    return { exitCode: 0, reply: body.reply };
 }
 /**
  * The terminal's own spans as log fields (BLI-3591).
@@ -528,6 +570,56 @@ function createLiveAnswer(command, io) {
  * not exist.
  */
 const ANSWER_REVISED_LINE = "revised: I checked that against its sources and changed what they did not back up";
+/**
+ * The three lines a correction's rewrite prints (BLI-3567).
+ *
+ * The browsers replace the paragraph where it stands. A terminal cannot —
+ * stdout is a river — so it says the same three things in sequence instead:
+ * that a rewrite is under way, what the paragraph now says, and that the
+ * printed one above it did not change. The last of those is the honest half:
+ * without it a person would have two versions on screen and no idea which one
+ * JARVIS believes.
+ *
+ * `ANSWER_UPDATING_LINE` is the terminal's copy of the browsers'
+ * `ANSWER_UPDATING_LABEL` (`apps/dashboard/src/lib/webchat/tool-trace.ts`),
+ * word for word. This package cannot import from the dashboard, so it is
+ * written out here rather than shared through a dependency that does not exist
+ * — the same arrangement `ANSWER_REVISED_LINE` above already has.
+ */
+const ANSWER_UPDATING_LINE = "(updating...)";
+const ANSWER_CORRECTED_LINE = "revised after your correction";
+const ANSWER_CORRECTED_NOTE_LINE = "The paragraph printed above is unchanged — a terminal cannot rewrite what it already " +
+    "printed. This is what it says now.";
+const ANSWER_REWRITE_UNVERIFIED_LINE = "Your correction is recorded. I could not verify a rewrite of that paragraph against its " +
+    "sources, so it stays as it was.";
+/**
+ * Print what a correction did to the answer above, once the turn has settled.
+ *
+ * `--json` prints nothing: that contract is exactly one object on stdout, and
+ * the revision rides it as a field. Every branch either prints or is a
+ * deliberate no-op with a stderr line behind it in `sendOneTurn`.
+ */
+function writeRevision(command, io, revision) {
+    if (command.json)
+        return;
+    const styled = colorEnabled(io);
+    if (revision.status === "unverified") {
+        writeLine(io.stdout, "");
+        writeLine(io.stdout, dim(`  — ${ANSWER_REWRITE_UNVERIFIED_LINE}`, styled));
+        return;
+    }
+    if (revision.status !== "revised")
+        return;
+    const paragraphs = Array.isArray(revision.paragraphs) ? revision.paragraphs : [];
+    const written = paragraphs.filter((one) => typeof one === "object" && one !== null && typeof one.text === "string");
+    if (written.length === 0)
+        return;
+    writeLine(io.stdout, "");
+    writeLine(io.stdout, dim(`  — ${ANSWER_CORRECTED_LINE} —`, styled));
+    for (const paragraph of written)
+        writeLine(io.stdout, paragraph.text);
+    writeLine(io.stdout, dim(`  ${ANSWER_CORRECTED_NOTE_LINE}`, styled));
+}
 /**
  * The multipart body `/api/jarvis/cli` reads when a file is attached
  * (BLI-3414) — same field names the request handler parses, mirroring the

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

@@ -596,6 +596,27 @@ export function parseMemoryArgs(args) {
         json: values.booleans.has("--json"),
     };
 }
+/**
+ * BLI-3619. Deliberately takes no positional: `clean` is one verb, and the two
+ * flags say how far it goes. A path is never accepted — the only directory this
+ * command may touch is the collector's own state directory.
+ */
+export function parseCleanArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: ["--home", "--dry-run", "--all-committed", "--json"],
+        valueFlags: ["--home"],
+    });
+    if (values.positionals.length > 0) {
+        throw new Error("clean takes no arguments; use --dry-run or --all-committed.");
+    }
+    return {
+        kind: "clean",
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dryRun: values.booleans.has("--dry-run"),
+        allCommitted: values.booleans.has("--all-committed"),
+        json: values.booleans.has("--json"),
+    };
+}
 function parseAgentRulesHost(value) {
     const host = value?.trim().toLowerCase() || "all";
     if (host === "codex" || host === "claude" || host === "all")

package/dist/commands/local-args.js

@@ -1,4 +1,4 @@
-import { parseAgentRulesArgs, parseAnalyzeArgs, parseAutostartArgs, parseBackfillArgs, parseDoctorArgs, parseInstallArgs, parseLoginArgs, parseMemoryArgs, parseLogoutArgs, parseOnboardArgs, parseReleaseArgs, parseServeArgs, parseSessionsArgs, parseStartArgs, parseStatusArgs, parseSyncArgs, parseUpdateArgs, } from "./local-args-collector.js";
+import { parseAgentRulesArgs, parseAnalyzeArgs, parseAutostartArgs, parseBackfillArgs, parseCleanArgs, parseDoctorArgs, parseInstallArgs, parseLoginArgs, parseMemoryArgs, parseLogoutArgs, parseOnboardArgs, parseReleaseArgs, parseServeArgs, parseSessionsArgs, parseStartArgs, parseStatusArgs, parseSyncArgs, parseUpdateArgs, } from "./local-args-collector.js";
 import { parseBriefArgs, parseCorrectArgs, parseJarvisArgs, parseModelArgs, parseNotesArgs, parseOpsArgs, parseScoutArgs, parseSettingsArgs, parseSlackArgs, parseTeamArgs, parseWorkbookArgs, } 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
@@ -82,6 +82,8 @@ export function parseLocalArgs(argv) {
             return parseAgentRulesArgs(argv.slice(1));
         case "memory":
             return parseMemoryArgs(argv.slice(1));
+        case "clean":
+            return parseCleanArgs(argv.slice(1));
         case "release":
             return parseReleaseArgs(argv.slice(1));
         default:

package/dist/commands/local-help.js

@@ -39,6 +39,7 @@ export const rootCommandNames = new Set([
     "autostart",
     "agent-rules",
     "memory",
+    "clean",
     "release",
 ]);
 export function localCommandHelp(command) {
@@ -76,6 +77,7 @@ export function localCommandHelp(command) {
         "  cockpit autostart [install|uninstall|status] [--workspace <path>] [--dashboard-url <url>] [--interval-seconds <n>] [--json]",
         "  cockpit agent-rules [install|uninstall|status] [--host codex|claude|all] [--workspace <path>] [--json]",
         "  cockpit memory [install|status] [--dashboard-url <url>] [--dry-run] [--json]",
+        "  cockpit clean [--dry-run] [--all-committed] [--json]",
         "  cockpit release [--dry-run] [--skip-checks] [--no-floor] [--tag <tag>] [--access <public|restricted>] [--otp <code>]",
         "",
         `Default dashboard: ${DEFAULT_DASHBOARD_URL}. Omit --dashboard-url for normal production use; pass it only for staging/custom dashboards or to force a different pairing.`,
@@ -546,6 +548,22 @@ function localSubcommandHelp(command) {
                 "Action defaults to `install`. See docs/runbooks/bli-memory-install.md.",
             ],
         ],
+        [
+            "clean",
+            [
+                "Usage: cockpit clean [--dry-run] [--all-committed] [--json]",
+                "",
+                "Reclaims this machine's disk. Prints what it would delete and why, per bucket,",
+                "then deletes: staged evidence Tower has already accepted goes after a 48-hour",
+                "retry window, and anything the upload ledger has NOT vouched for is kept,",
+                "counted and named — retention never deletes undelivered evidence.",
+                "--dry-run stops after the printing. --all-committed drops the retry window,",
+                "so every already-accepted copy goes now, and is the only thing that removes a",
+                "manual-study-evidence-vault folder (and only when every file in it is accepted).",
+                "The scheduled sync does the same prune once a day; this is the door for a",
+                "laptop that is full right now.",
+            ],
+        ],
         [
             "release",
             [

package/dist/commands/local.js

@@ -31,6 +31,7 @@ import { runServe } from "./serve.js";
 import { runAutostart } from "./autostart-command.js";
 import { runAgentRules } from "./agent-rules-command.js";
 import { runMemoryInstall } from "./memory-install.js";
+import { runClean } from "./clean.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
@@ -128,6 +129,8 @@ export async function runLocalCockpitCli(argv, io = defaultIo()) {
                 return await runAgentRules(command, io);
             case "memory":
                 return await runMemoryInstall(command, io);
+            case "clean":
+                return await runClean(command, io);
             case "release":
                 return await runRelease(command, io);
         }

package/dist/commands/memory-install-contract.js

@@ -42,6 +42,13 @@
  * env = { COCKPIT_DASHBOARD_URL = "https://…" }
  * ```
  *
+ * **The printed `command` is a bare name and is never written as-is.** The bin
+ * cannot know where it was installed, and it lives nested inside
+ * `@bli-cockpit/cli`'s `node_modules` rather than on PATH — so
+ * `withResolvedBinPath` re-points every command at the absolute path this
+ * machine resolved before anything is written. Skipping that step registered
+ * three hooks that answered `command not found` on every turn.
+ *
  * Nothing here touches the filesystem. The halves that do are
  * `memory-install-claude.ts` and `memory-install-codex.ts`.
  */
@@ -207,6 +214,54 @@ export function parsePrintedMemoryInstallConfig(stdout) {
         permissions_allow: allow ?? [...MEMORY_AUTO_APPROVE_TOOLS],
     };
 }
+/**
+ * Put THIS machine's resolved bin path into a config the bin printed.
+ *
+ * The printed contract says `command: "bli-memory-mcp"` — a bare name, because
+ * the bin has no idea where it was installed. `bli-memory-mcp` is a DEPENDENCY
+ * of `@bli-cockpit/cli`, nested inside its `node_modules`, and therefore **not
+ * on anybody's PATH**: a host handed the bare name answers `command not found`
+ * on every SessionStart, every prompt and every Stop. The installer is the only
+ * thing that knows the absolute path, so path qualification happens here and
+ * the printed strings are never written verbatim (BLI-3580; found by running
+ * the registered hook command in a simulated global install, not by reading
+ * the code).
+ *
+ * What the printed config still owns: which hook EVENTS exist, their
+ * subcommands, their timeouts, the server id and the allow-list. What this
+ * function owns: where the program is, and the per-platform launch shape.
+ *
+ * Returns null when a printed hook command cannot be understood well enough to
+ * re-point — the caller then falls back to the built-in template, which is
+ * always path-qualified. Guessing at a command we cannot parse would write a
+ * hook that runs something else.
+ */
+export function withResolvedBinPath(config, options) {
+    const quoted = shellQuoteBinPath(options.binPath);
+    const hooks = [];
+    for (const hook of config.hooks) {
+        const tail = hookSubcommandTail(hook.command);
+        if (!tail)
+            return null;
+        hooks.push({ ...hook, command: `${quoted} ${tail}` });
+    }
+    const entry = memoryMcpServerEntry(options);
+    return {
+        ...config,
+        // The bin's own env wins nothing and loses nothing: it prints `{}`, and the
+        // dashboard URL is a machine fact the installer holds.
+        mcp_server: { ...entry, env: { ...config.mcp_server.env, ...entry.env } },
+        hooks,
+    };
+}
+/**
+ * `…/bli-memory-mcp hook prompt` → `hook prompt`. The subcommand is the part we
+ * keep; everything before it is a path that may be wrong for this machine.
+ */
+function hookSubcommandTail(command) {
+    const match = /(^|\s)(hook\s+\S+.*)$/u.exec(command.trim());
+    return match?.[2]?.trim() ?? null;
+}
 function normalizeStringArray(value) {
     if (value === undefined)
         return [];