@bli-cockpit/cli 0.2.96 → 0.2.98

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

@@ -11,6 +11,7 @@
 import { DEFAULT_AUTOSTART_INTERVAL_SECONDS } from "../autostart.js";
 import { assertNoPositionals, normalizeUrl, optionalNonEmpty, optionalPositiveInteger, optionalUrl, parseNamedArgs, workRootFlagValue, } from "./local-arg-values.js";
 import { DEFAULT_DASHBOARD_URL } from "../local-state.js";
+import { MEMORY_STORE_ACTIONS, parseMemoryStoreArgs, } from "./local-args-tower-memory.js";
 export function parseStatusArgs(args) {
     const values = parseNamedArgs(args, {
         allowedFlags: [
@@ -164,11 +165,30 @@ export function parseAgentRulesArgs(args) {
     };
 }
 /**
- * BLI-3580. `install` is the default action on purpose: this command exists to
- * be run unasked (by `do-everything` and by the sync tick), and a bare
- * `cockpit memory` should do the thing rather than print usage.
+ * BLI-3580, amended by BLI-4047.
+ *
+ * `cockpit memory` is now SIX verbs behind one noun: the two that configure
+ * this machine (`install`, `status`), the experience log (`log`), and the four
+ * that read and write the memory store itself (`search`, `save`, `update`,
+ * `forget`, parsed next door in `local-args-tower-memory.ts`).
+ *
+ * **A bare `cockpit memory` prints the verb list; it no longer installs.**
+ * BLI-3580 made `install` the default because the command is run unasked by
+ * `do-everything` and by the sync tick — but those callers build
+ * `{ kind: "memory", action: "install" }` in code (`doctor-registration.ts`,
+ * `sync-followups-memory.ts`, `onboard-completion.ts`) and never pass through
+ * this parser. The only caller the default ever served was a PERSON typing the
+ * noun to find out what it does, and what they got was an MCP server and three
+ * hooks registered on their machine. Installing stays one word away.
  */
 export function parseMemoryArgs(args) {
+    // The verb word first, always: reading it off `args[0]` rather than "the
+    // first token without a leading dash" is what keeps `cockpit memory --home
+    // /tmp/x status` from being read as the verb `/tmp/x`.
+    const first = args[0];
+    if (first !== undefined && MEMORY_STORE_ACTIONS.has(first)) {
+        return parseMemoryStoreArgs(first, args);
+    }
     const values = parseNamedArgs(args, {
         allowedFlags: ["--home", "--dashboard-url", "--dry-run", "--json", "--store", "--reason-stdin"],
         valueFlags: ["--home", "--dashboard-url", "--store"],
@@ -192,9 +212,10 @@ export function parseMemoryArgs(args) {
     if (values.positionals.length > 1) {
         throw new Error("memory accepts at most one action (install|status).");
     }
-    const action = values.positionals[0] ?? "install";
-    if (action !== "install" && action !== "status") {
-        throw new Error("memory action must be install or status.");
+    // BLI-4047: no positional means "tell me what this noun does", not "install".
+    const action = values.positionals[0] ?? "help";
+    if (action !== "install" && action !== "status" && action !== "help") {
+        throw new Error("memory action must be install, status, help, log, search, save, update, or forget.");
     }
     return {
         kind: "memory",

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

@@ -0,0 +1,151 @@
+/**
+ * `cockpit memory search|save|update|forget` — the argument table (BLI-4047).
+ *
+ * BLI Memory was the one Tower surface with no command-line door: the browser
+ * had one, the `bli-memory` MCP server had one, and a person or a script at a
+ * terminal had nothing. These four verbs are the twins of that server's four
+ * tools, over the SAME `/api/memory/*` doors.
+ *
+ * Two rules this table exists to enforce, both of them the same discipline
+ * `cockpit docs create` and `cockpit notes paste` already follow:
+ *
+ *  - **A body never travels on the command line.** `save`, `update` and
+ *    `forget --content` read their text from stdin (or `--file`, which is the
+ *    safest way to say it on Windows). An argument list is visible in `ps`,
+ *    lands in a shell history file, and is quoted wrong on the first line that
+ *    contains a newline. A QUERY is not a body — `search` takes one
+ *    positional, the same way `cockpit search` and `cockpit docs list --query`
+ *    do — but the text of a memory always is.
+ *  - **The container tag is derived, not typed.** Omit `--container` and the
+ *    tag comes from this repository, resolved by `@bli-cockpit/memory-mcp`'s
+ *    own resolver, so a memory saved from the terminal lands in the same space
+ *    the MCP server and the hooks write to. `--container` may be repeated on
+ *    `search` alone, because searching two spaces is meaningful and saving
+ *    into two is not.
+ *
+ * The verbs live in their own `kind` (`memory-store`) rather than widening
+ * `kind: "memory"`, because that command acts on THIS MACHINE (it registers an
+ * MCP server and three hooks) and these act on Tower. `memory-store.ts` runs
+ * them; `parseMemoryArgs` in `local-args-collector-status.ts` routes to here.
+ */
+import { optionalNonEmpty, optionalUrl, parseNamedArgs, workRootFlagValue, } from "./local-arg-values.js";
+export const MEMORY_STORE_ACTIONS = new Set([
+    "search",
+    "save",
+    "update",
+    "forget",
+]);
+const ALLOWED_FLAGS = [
+    "--home",
+    "--dashboard-url",
+    "--workspace",
+    "--repo",
+    "--container",
+    "--limit",
+    "--no-recent",
+    "--custom-id",
+    "--extract",
+    "--file",
+    "--content-stdin",
+    "--reason",
+    "--json",
+];
+const VALUE_FLAGS = [
+    "--home",
+    "--dashboard-url",
+    "--workspace",
+    "--repo",
+    "--container",
+    "--limit",
+    "--custom-id",
+    "--file",
+    "--reason",
+];
+export function parseMemoryStoreArgs(action, args) {
+    const values = parseNamedArgs(args, { allowedFlags: ALLOWED_FLAGS, valueFlags: VALUE_FLAGS });
+    const rest = values.positionals.slice(1);
+    const containers = values.flagValues.get("--container") ?? [];
+    if (action !== "search" && containers.length > 1) {
+        throw new Error(`memory ${action} takes at most one --container.`);
+    }
+    if (action !== "search" && (values.flags.has("--limit") || values.booleans.has("--no-recent"))) {
+        throw new Error("--limit and --no-recent only apply to memory search.");
+    }
+    if (action !== "save" && (values.flags.has("--custom-id") || values.booleans.has("--extract"))) {
+        throw new Error("--custom-id and --extract only apply to memory save.");
+    }
+    if (action !== "forget" && (values.flags.has("--reason") || values.booleans.has("--content-stdin"))) {
+        throw new Error("--reason and --content-stdin only apply to memory forget.");
+    }
+    if (values.flags.has("--file") && action !== "save" && action !== "update") {
+        throw new Error("--file only applies to memory save and memory update.");
+    }
+    const command = {
+        kind: "memory-store",
+        action,
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        workspace: optionalNonEmpty(workRootFlagValue(values)),
+        containerTags: containers
+            .map((tag) => tag.trim())
+            .filter((tag) => tag.length > 0),
+        json: values.booleans.has("--json"),
+    };
+    if (action === "search") {
+        // Every remaining positional joined, so `cockpit memory search what did we
+        // decide about pagination` needs no quotes — the same shape `cockpit
+        // search` and `cockpit cal find` already have.
+        const query = rest.join(" ").trim();
+        if (!query)
+            throw new Error("memory search needs a question, e.g. `cockpit memory search \"pagination rule\"`.");
+        return { ...command, action, query, limit: readLimit(values.flags.get("--limit")), includeRecent: !values.booleans.has("--no-recent") };
+    }
+    if (action === "save") {
+        if (rest.length > 0) {
+            throw new Error("memory save reads the memory from stdin or --file, never from the command line: `echo \"...\" | cockpit memory save`.");
+        }
+        return {
+            ...command,
+            action,
+            customId: optionalNonEmpty(values.flags.get("--custom-id")),
+            extract: values.booleans.has("--extract"),
+            filePath: optionalNonEmpty(values.flags.get("--file")),
+        };
+    }
+    if (action === "update") {
+        const memoryId = optionalNonEmpty(rest[0]);
+        if (!memoryId)
+            throw new Error("memory update needs the memory id `cockpit memory search` printed.");
+        if (rest.length > 1) {
+            throw new Error("memory update takes one id; the replacement text comes from stdin or --file, never from the command line.");
+        }
+        return { ...command, action, memoryId, filePath: optionalNonEmpty(values.flags.get("--file")) };
+    }
+    const memoryId = optionalNonEmpty(rest[0]);
+    if (rest.length > 1)
+        throw new Error("memory forget takes one id, or --content-stdin with a --container.");
+    const contentStdin = values.booleans.has("--content-stdin");
+    if (memoryId && contentStdin) {
+        throw new Error("memory forget takes an id OR --content-stdin, never both — they name different rows.");
+    }
+    if (!memoryId && !contentStdin) {
+        throw new Error("memory forget needs an id, or --content-stdin plus --container to forget by exact text.");
+    }
+    return {
+        ...command,
+        action,
+        memoryId,
+        contentStdin,
+        reason: optionalNonEmpty(values.flags.get("--reason")),
+    };
+}
+/** 1..20, the same window the MCP tool and the door both accept. */
+function readLimit(value) {
+    if (value === undefined)
+        return undefined;
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed < 1 || parsed > 20) {
+        throw new Error("--limit must be between 1 and 20.");
+    }
+    return parsed;
+}

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

@@ -0,0 +1,22 @@
+/**
+ * The `cockpit memory` family's command shapes (BLI-4047).
+ *
+ * Split out of `local-command-shapes.ts` the same way `SearchCommandShape` and
+ * the product shapes were: that file crossed the repo's 500-line band floor
+ * when the store verbs arrived, and one noun's shapes are exactly the kind of
+ * thing that reads better in its own file than as a third of a 540-line union.
+ *
+ * Three kinds, and the difference between them is the point:
+ *
+ *   `memory`        install / status / help — acts on THIS MACHINE, writing an
+ *                   MCP registration and three hooks into a home directory.
+ *   `memory-store`  search / save / update / forget — acts on TOWER, over
+ *                   `/api/memory/*`, the same doors the `bli-memory` MCP
+ *                   server and the browser call.
+ *   `memory-log`    the agent-experience opinion, part local file part Tower.
+ *
+ * They are separate kinds rather than one widening `action` union because they
+ * refuse different things, run on different credentials, and one of them can
+ * be run unasked by a scheduler while the others never are.
+ */
+export {};

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

@@ -555,15 +555,32 @@ export function localSubcommandHelp(command) {
         [
             "memory",
             [
-                "Usage: cockpit memory [install|status|log <win|loss|noise> --store <bli|supermemory|both> \"<reason>\"] [--dashboard-url <url>] [--dry-run] [--json]",
-                "",
-                "Registers BLI Memory on this machine: the `bli-memory` MCP server plus the",
+                "Usage: cockpit memory [search|save|update|forget|install|status|log] [flags]",
+                "",
+                "The STORE, over the same /api/memory/* doors the bli-memory MCP server calls:",
+                "  search \"<question>\" [--container <tag>] [--limit 1..20] [--no-recent]",
+                "      repeat --container to search more than one space; omit it for this repository's own.",
+                "  save [--container <tag>] [--custom-id <id>] [--extract] [--file <path>]",
+                "      the memory comes from stdin or --file, never from the command line:",
+                "      `echo \"Edward decided X on 2026-09-10\" | cockpit memory save`.",
+                "      --custom-id makes a repeat save update instead of duplicating;",
+                "      --extract distils atomic facts first (one model call) instead of storing as given.",
+                "  update <id> [--file <path>]   replacement text on stdin; the old row is kept as history.",
+                "  forget <id> [--reason <label>]",
+                "  forget --content-stdin --container <tag> [--reason <label>]   forget by exact text.",
+                "Refusals keep the door's own label — needs_rls_client, unknown_memory,",
+                "already_superseded, no_match — and --json prints the door's answer unchanged.",
+                "",
+                "BARE `cockpit memory` PRINTS THIS LIST AND DOES NOTHING ELSE (BLI-4047).",
+                "It used to run the installer; installing is now `cockpit memory install`.",
+                "",
+                "install/status register BLI Memory on this machine: the `bli-memory` MCP server plus the",
                 "recall/save hooks, for Claude Code (~/.claude.json, ~/.claude/settings.json)",
                 "and for Codex (~/.codex/config.toml, ~/.codex/skills/bli-memory/).",
                 "Idempotent: it merges with what is already there, never duplicates its own",
                 "entries, and reads the stored config back before reporting success.",
                 "`do-everything` runs it, and the sync tick re-runs it at most once a day.",
-                "Action defaults to `install`. See docs/runbooks/bli-memory-install.md.",
+                "See docs/runbooks/bli-memory-install.md.",
                 "log appends an opinion to ~/.codex/AGENT-EXPERIENCE.md and posts it to Tower.",
                 "Use --reason-stdin instead of a quoted reason; --json reports shipped status.",
                 "Reasons: one line, max 500 characters; no prompts, memory bodies or secrets.",

package/dist/commands/local-help.js

@@ -88,7 +88,7 @@ export function localCommandHelp(command) {
         "  cockpit serve [--port <port>] [--workspace <path>]",
         "  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|log <win|loss|noise> --store <bli|supermemory|both> \"<reason>\"] [--dashboard-url <url>] [--dry-run] [--json]",
+        "  cockpit memory [search \"<question>\"|save|update <id>|forget <id>|install|status|log <win|loss|noise> --store <bli|supermemory|both> \"<reason>\"] [--container <tag>] [--limit <n>] [--no-recent] [--custom-id <id>] [--extract] [--content-stdin] [--reason <label>] [--file <path>] [--dashboard-url <url>] [--dry-run] [--json]",
         "  cockpit clean [--dry-run] [--all-committed] [--reconcile] [--dashboard-url <url>] [--json]",
         "  cockpit docs [list|tree|read <id|slug>|create --title <t>|update <id>] [--parent <id>|root|--clear-parent] [--query <text>] [--limit <n>] [--visibility org|private] [--file <path>|--body-stdin] [--allow-empty] [--dashboard-url <url>] [--json]",
         "  cockpit msg [channels|create <name>|dm <email>|read <channel>|send <channel>|thread <id> --channel <channel>] [--private] [--members a@x,b@y] [--description <text>] [--thread <id>] [--limit <n>] [--dashboard-url <url>] [--json]",

package/dist/commands/local.js

@@ -33,6 +33,7 @@ import { runAutostart } from "./autostart-command.js";
 import { runAgentRules } from "./agent-rules-command.js";
 import { runMemoryLog } from "./memory-log.js";
 import { runMemoryInstall } from "./memory-install.js";
+import { runMemoryStore, runMemoryVerbList } from "./memory-store.js";
 import { runClean } from "./clean.js";
 import { runDocs } from "./docs.js";
 import { runMsg } from "./msg.js";
@@ -148,7 +149,14 @@ export async function runLocalCockpitCli(argv, io = defaultIo()) {
             case "memory-log":
                 return await runMemoryLog(command, io);
             case "memory":
+                // BLI-4047: a bare `cockpit memory` says what the noun does. It used
+                // to install; `install` is still one word away and every unattended
+                // caller asks for it by name in code.
+                if (command.action === "help")
+                    return runMemoryVerbList(io, command.json);
                 return await runMemoryInstall(command, io);
+            case "memory-store":
+                return await runMemoryStore(command, io);
             case "clean":
                 return await runClean(command, io);
             case "docs":

package/dist/commands/memory-store.js

@@ -0,0 +1,331 @@
+/**
+ * `cockpit memory search|save|update|forget` — BLI Memory at a terminal
+ * (BLI-4047).
+ *
+ * Memory was the one Tower surface with no command-line door. The browser had
+ * one, the `bli-memory` MCP server had four tools, and a person or a script
+ * had nothing — so a machine without an agent host could not read or write the
+ * store at all, and `cockpit memory` typed on its own registered an MCP server
+ * instead of saying what the noun does. These four verbs are the twins of that
+ * server's four tools.
+ *
+ * **The same doors, never a second store.** `POST /api/memory/{search,save,
+ * update,forget}`, with this machine's collector device token, through
+ * `agent-door.ts` — the identical route the MCP server calls in
+ * `packages/cockpit-memory-mcp/src/server.ts` and the browser calls from
+ * `lib/memory/agent-memories/`. Nothing here talks to Postgres, embeds
+ * anything, or knows what a container alias is; every ranking, redaction and
+ * lifecycle decision stays server-side where its one implementation lives.
+ *
+ * **A refusal keeps the door's own reason label.** `needs_rls_client`,
+ * `unknown_memory`, `already_forgotten`, `already_superseded`,
+ * `needs_container_tag`, `no_match`, `custom_id_conflict`, `search_timed_out`
+ * — printed verbatim by `failAgentDoor`, never rephrased here. A CLI that
+ * invents its own prose for a server's refusal is a CLI whose error messages
+ * lie one release later.
+ *
+ * **The container tag is `@bli-cockpit/memory-mcp`'s, not a second copy.**
+ * `resolveContainerTag` is imported from that package rather than
+ * reimplemented, so a memory saved by `cockpit memory save` lands in exactly
+ * the space the MCP server and the three hooks read from. The scheme is the
+ * vendor plugin's byte for byte and two implementations of it would strand
+ * memories in a space nothing asks about — see that module's header.
+ *
+ * **A body never comes from the command line.** `save`, `update` and
+ * `forget --content-stdin` read stdin (or `--file`). Same discipline as
+ * `cockpit docs create` and `cockpit notes paste`, and for the same reasons:
+ * `ps` shows an argument list, shell history keeps it, and a memory with a
+ * newline in it cannot be quoted correctly anyway.
+ */
+import { resolveContainerTag } from "@bli-cockpit/memory-mcp/dist/container-tag.js";
+import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor, } from "./agent-door.js";
+import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
+import { readNoteFile } from "./notes-file.js";
+const TAG = "[memory cli]";
+const SEARCH_DEADLINE_MS = 60_000;
+/** `--extract` is one model call, sometimes two; the door waits for it when asked to. */
+const WRITE_DEADLINE_MS = 120_000;
+/** The door's own ceiling on a memory (`saveMemoryInput`, 200k characters). */
+const BODY_MAX_CHARS = 200_000;
+/** The door's own ceiling on forget-by-text. */
+const FORGET_MAX_CHARS = 10_000;
+export async function runMemoryStore(command, io) {
+    const door = await openAgentDoor("memory", command, io);
+    switch (command.action) {
+        case "search":
+            return searchMemory(command, door);
+        case "save":
+            return saveMemory(command, door);
+        case "update":
+            return updateMemory(command, door);
+        case "forget":
+            return forgetMemory(command, door);
+    }
+}
+/**
+ * The verb list a bare `cockpit memory` prints (BLI-4047).
+ *
+ * It used to run the installer. Typing a noun to find out what it does is the
+ * single most common thing a person does with a new CLI, and this was the one
+ * command in the collector that answered that by writing five files in a home
+ * directory. Installing is still one word away, and every unattended caller
+ * asks for `install` by name in code.
+ */
+export function runMemoryVerbList(io, json) {
+    if (json) {
+        writeLine(io.stdout, JSON.stringify({
+            ok: true,
+            noun: "memory",
+            machine_verbs: ["install", "status"],
+            store_verbs: ["search", "save", "update", "forget"],
+            log_verbs: ["log"],
+        }));
+        return 0;
+    }
+    for (const line of [
+        "cockpit memory — BLI Memory: the store, and this machine's registration.",
+        "",
+        "The store (Tower, over /api/memory/*):",
+        "  cockpit memory search \"<question>\" [--container <tag>] [--limit 1..20] [--no-recent] [--json]",
+        "  cockpit memory save [--container <tag>] [--custom-id <id>] [--extract] [--file <path>] [--json]",
+        "      the memory comes from stdin, or --file; never from the command line",
+        "  cockpit memory update <id> [--file <path>] [--json]        replacement text on stdin",
+        "  cockpit memory forget <id> [--reason <label>] [--json]",
+        "  cockpit memory forget --content-stdin --container <tag> [--reason <label>] [--json]",
+        "",
+        "This machine:",
+        "  cockpit memory install [--dry-run] [--json]   register the MCP server and the three hooks",
+        "  cockpit memory status [--json]                read the stored config back",
+        "",
+        "The experience log:",
+        "  cockpit memory log <win|loss|noise> --store <bli|supermemory|both> \"<reason>\"",
+        "",
+        "Omit --container and this repository's own memory space is used — the same",
+        "space the bli-memory MCP server and its hooks read and write.",
+    ]) {
+        writeLine(io.stdout, line);
+    }
+    return 0;
+}
+/**
+ * This repository's memory space, resolved by the MCP server's own resolver.
+ * `--container` wins; `--workspace` says which directory to derive it from.
+ */
+function containerTagsFor(command) {
+    if (command.containerTags.length > 0)
+        return command.containerTags;
+    return [resolveContainerTag({ cwd: command.workspace ?? process.cwd() }).containerTag];
+}
+async function searchMemory(command, door) {
+    const containerTags = containerTagsFor(command);
+    const answer = await askAgentDoor(door, {
+        path: "/api/memory/search",
+        method: "POST",
+        label: "memory search",
+        timeoutMs: SEARCH_DEADLINE_MS,
+        body: {
+            query: command.query,
+            containerTag: containerTags,
+            ...(command.limit === undefined ? {} : { limit: command.limit }),
+            includeProfile: command.includeRecent !== false,
+        },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    const results = body.results ?? [];
+    const recent = body.recent ?? [];
+    // Counts and labels only: a memory body never enters a log line.
+    writeLine(door.io.stderr, `${TAG} searched ${JSON.stringify({
+        requested_containers: containerTags.length,
+        searched_containers: body.containerTags?.length ?? containerTags.length,
+        results: results.length,
+        recent: recent.length,
+        dropped_below_floor: body.dropped_below_floor ?? 0,
+        degraded: body.degraded ?? null,
+    })}`);
+    if (door.json)
+        return emitAgentDoor(door, answer.body);
+    if (results.length === 0) {
+        // The distinction the whole store is built on: silence is not an outage.
+        // A failure took the `!answer.ok` branch above and named itself there.
+        writeLine(door.io.stdout, "No memories matched. The record is silent on this — it does not mean the store is down.");
+    }
+    else {
+        for (const row of results) {
+            writeLine(door.io.stdout, `${similarityLabel(row)}${oneLine(row["memory"])}`);
+            writeLine(door.io.stdout, `    ${String(row["id"] ?? "")}  ${String(row["containerTag"] ?? "")}`);
+        }
+    }
+    if (recent.length > 0) {
+        writeLine(door.io.stdout, "");
+        writeLine(door.io.stdout, "Recent context:");
+        for (const row of recent)
+            writeLine(door.io.stdout, `  - ${oneLine(row["preview"] ?? row["memory"])}`);
+    }
+    if (body.degraded) {
+        writeLine(door.io.stdout, "");
+        writeLine(door.io.stdout, `This answer is thinner than usual (${body.degraded}) — one search channel did not run.`);
+    }
+    return 0;
+}
+async function saveMemory(command, door) {
+    const containerTag = containerTagsFor(command)[0];
+    const body = await readBody(command, door, BODY_MAX_CHARS, "A memory");
+    if (!body.ok)
+        return failAgentDoor(door, TAG, body.reason, body.detail);
+    if (!body.text.trim()) {
+        return failAgentDoor(door, TAG, "content_empty", "There is nothing to save. Pipe the memory in: `echo \"...\" | cockpit memory save`, or pass --file.");
+    }
+    const answer = await askAgentDoor(door, {
+        path: "/api/memory/save",
+        method: "POST",
+        label: "memory save",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: {
+            content: body.text,
+            containerTag,
+            ...(command.customId ? { customId: command.customId } : {}),
+            mode: command.extract ? "extract" : "verbatim",
+            // Same reason the MCP tool sets it: a caller that ASKED for distillation
+            // is waiting for the answer, so take the synchronous branch instead of
+            // the 202 the Stop hook wants.
+            ...(command.extract ? { wait: true } : {}),
+            sourceRef: { kind: "cli" },
+        },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const saved = answer.body;
+    writeLine(door.io.stderr, `${TAG} saved ${JSON.stringify({
+        outcome: saved["outcome"] ?? null,
+        chars: body.text.length,
+        embedded: saved["embedded"] ?? null,
+        embed_skipped_reason: saved["embedSkippedReason"] ?? null,
+        extract: saved["extract"] ?? null,
+        masked_spans: saved["maskedSpans"] ?? 0,
+    })}`);
+    if (door.json)
+        return emitAgentDoor(door, answer.body);
+    // The container the SERVER used, which is the canonical one when this
+    // repository has more than one tag on the shelf; saying the tag we sent
+    // would name a space the row is not in.
+    const landedIn = String(saved["containerTag"] ?? containerTag);
+    writeLine(door.io.stdout, `Memory ${String(saved["outcome"] ?? "created")} in ${landedIn} (id: ${String(saved["id"] ?? "—")}).`);
+    if (saved["embedded"] === false && saved["embedSkippedReason"]) {
+        writeLine(door.io.stdout, `Stored without a search vector (${String(saved["embedSkippedReason"])}): findable by keyword, not yet by meaning.`);
+    }
+    if (saved["extract"] === "fell_back_verbatim") {
+        writeLine(door.io.stdout, `Saved as written; extraction failed (${String(saved["extractFailureReason"] ?? "unknown")}).`);
+    }
+    return 0;
+}
+async function updateMemory(command, door) {
+    const body = await readBody(command, door, BODY_MAX_CHARS, "A memory");
+    if (!body.ok)
+        return failAgentDoor(door, TAG, body.reason, body.detail);
+    if (!body.text.trim()) {
+        return failAgentDoor(door, TAG, "content_empty", "An update needs replacement text on stdin or --file. To remove a memory, use `cockpit memory forget`.");
+    }
+    const answer = await askAgentDoor(door, {
+        path: "/api/memory/update",
+        method: "POST",
+        label: "memory update",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: { id: command.memoryId, content: body.text },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const updated = answer.body;
+    writeLine(door.io.stderr, `${TAG} updated ${JSON.stringify({
+        chars: body.text.length,
+        re_embedded: updated["reEmbedded"] ?? null,
+        embed_skipped_reason: updated["embedSkippedReason"] ?? null,
+    })}`);
+    if (door.json)
+        return emitAgentDoor(door, answer.body);
+    writeLine(door.io.stdout, `Updated. The new memory is ${String(updated["id"] ?? "")}, and ${String(updated["supersededId"] ?? command.memoryId ?? "")} is kept as its previous version.`);
+    return 0;
+}
+async function forgetMemory(command, door) {
+    let content;
+    if (command.contentStdin) {
+        const body = await readBody(command, door, FORGET_MAX_CHARS, "Text to forget");
+        if (!body.ok)
+            return failAgentDoor(door, TAG, body.reason, body.detail);
+        if (!body.text.trim()) {
+            return failAgentDoor(door, TAG, "needs_id_or_content", "Nothing arrived on stdin to forget.");
+        }
+        content = body.text;
+    }
+    const answer = await askAgentDoor(door, {
+        path: "/api/memory/forget",
+        method: "POST",
+        label: "memory forget",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: {
+            ...(command.memoryId ? { id: command.memoryId } : {}),
+            ...(content ? { content } : {}),
+            // Only defaulted for a text match, which is the case that would
+            // otherwise sweep every space this caller can read. An id needs none.
+            ...(content ? { containerTag: containerTagsFor(command)[0] } : {}),
+            ...(command.reason ? { reason: command.reason } : {}),
+        },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const result = answer.body;
+    writeLine(door.io.stderr, `${TAG} forgot ${JSON.stringify({ count: result.count ?? 0, by: content ? "content" : "id" })}`);
+    if (door.json)
+        return emitAgentDoor(door, answer.body);
+    // The door answers with WHAT it removed, deliberately: a bare "done" is the
+    // only shape in which "forget X" quietly removing Y goes unnoticed.
+    writeLine(door.io.stdout, result.message ?? `Forgotten (${result.count ?? 0}).`);
+    for (const row of result.forgotten ?? []) {
+        const entry = row;
+        writeLine(door.io.stdout, `  ${String(entry["id"] ?? "")}  ${oneLine(entry["textPreview"])}`);
+    }
+    return 0;
+}
+/** A body from `--file`, else stdin. An interactive terminal yields nothing rather than hanging. */
+async function readBody(command, door, maxChars, what) {
+    if (command.filePath) {
+        const read = await readNoteFile(command.filePath);
+        if (!read.ok) {
+            return { ok: false, reason: read.refusal, detail: `Could not read ${command.filePath}: ${read.detail}` };
+        }
+        return { ok: true, text: read.bytes.toString("utf8") };
+    }
+    if (isInteractiveStdin(door.io))
+        return { ok: true, text: "" };
+    try {
+        return {
+            ok: true,
+            text: await readPipedText(door.io.stdin, {
+                maxChars,
+                overflowMessage: `${what} is limited to ${maxChars} characters.`,
+            }),
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: "content_too_long",
+            detail: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/** `[87%] ` when the row was found by meaning, empty when it was a keyword hit. */
+function similarityLabel(row) {
+    const channels = row["channels"];
+    if (Array.isArray(channels) && !channels.includes("semantic"))
+        return "";
+    const similarity = Number(row["similarity"]);
+    return Number.isFinite(similarity) && similarity >= 0 && similarity <= 1
+        ? `[${Math.round(similarity * 100)}%] `
+        : "";
+}
+/** One terminal line: newlines folded, so a long memory cannot break the listing. */
+function oneLine(value) {
+    return String(value ?? "").replace(/\s+/g, " ").trim();
+}

package/dist/commands/public-root.js

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

package/dist/commands/session-sync-failures.js

@@ -13,6 +13,7 @@
  * without saying why.
  */
 import { claudeAttributionReadFailureCount, codexAttributionReadFailureCount, } from "./agent-session-report.js";
+import { isDeliveryHoldReason } from "./session-sync-hold.js";
 import { sourceScanFailureReason } from "./session-sync-scan.js";
 /**
  * The label used when a sync fails and nothing on the way there said why.
@@ -45,6 +46,15 @@ export function createSyncFailureLedger() {
  * The spooled reason is the most specific thing anyone has, so it leads, and it
  * names the worktree it belongs to — a fleet failure is usually one repo, and
  * "which one" is the first question asked.
+ *
+ * BLI-4022: `delivery_backoff_holding` is the one raw-evidence reason that does
+ * NOT come in here. An object inside its own retry window was withheld on
+ * purpose and will be offered again; filing that as a failed tick is what
+ * painted Ian's Mac mini red on eight consecutive ticks while every session it
+ * collected landed. The hold is still reported — it becomes the tick's named
+ * hold in `session-sync-hold.ts` and rides the same receipt — and a tick that
+ * ALSO failed for a real reason still fails on that reason. Nothing is
+ * silenced; only the verdict changed.
  */
 export function recordWorktreeDeliveryFailures(ledger, outcomes) {
     for (const { worktree, sync } of outcomes) {
@@ -61,12 +71,16 @@ export function recordWorktreeDeliveryFailures(ledger, outcomes) {
                 });
         }
         for (const reason of sync.raw_evidence_failure_reasons ?? []) {
+            if (isDeliveryHoldReason(reason))
+                continue;
             ledger.add({
                 label: "raw_evidence_upload_failed",
                 rendered: `raw_evidence:${reason}`,
             });
         }
         for (const reason of sync.raw_evidence_retry_reasons ?? []) {
+            if (isDeliveryHoldReason(reason))
+                continue;
             ledger.add({
                 label: "raw_evidence_retry_required",
                 rendered: `raw_evidence_retry:${reason}`,

package/dist/commands/session-sync-health.js

@@ -11,6 +11,7 @@
  */
 import { createSyncFailureLedger, recordSourceScanFailures, recordUnexplainedFailure, recordUnpostedSessionReportFailure, recordWorktreeDeliveryFailures, } from "./session-sync-failures.js";
 import { countSessionsNewThisTick, countSessionsPendingUpload, } from "./session-sync-counters.js";
+import { logDeliveryHold, summarizeDeliveryHold } from "./session-sync-hold.js";
 /**
  * Decide whether this tick failed, and record every condition that decided it.
  *
@@ -44,12 +45,20 @@ export function decideSyncHealth(options) {
     if (nothingInRoot !== null && notice) {
         announceNothingInRoot(nothingInRoot, options.collectionRootCount);
     }
+    // BLI-4022. Computed after `ok`, and never allowed to change it: a hold is
+    // what this tick withheld on purpose, not a verdict on the run. It rides an
+    // `ok` receipt as the tick's reason and a failing one beside the reasons that
+    // failed it, so the board can say what is waiting in either case.
+    const hold = summarizeDeliveryHold(outcomes);
+    if (hold && ok)
+        logDeliveryHold(hold);
     const records = ledger.sortedRecords();
     return {
         ok,
         failure_reasons: records.map((record) => record.rendered),
         failure_records: records,
         notice,
+        hold,
         sessions_outside_root: sessionsOutsideRoot,
         sessions_new_this_tick: countSessionsNewThisTick({
             sessions: options.sessions,

package/dist/commands/session-sync-hold.js

@@ -0,0 +1,90 @@
+/**
+ * What this tick is HOLDING, as opposed to what it got wrong (BLI-4022).
+ *
+ * The sibling `session-sync-failures.ts` is the one place a sync writes down
+ * that it FAILED. This is the one place it writes down that it deliberately
+ * withheld something and when it will try again — a different question with a
+ * different answer, kept in a different file so neither can quietly become the
+ * other.
+ *
+ * Deliberately writes no failure label of any kind: `sync-health-class.test.ts`
+ * reads every `session-sync*.ts` sibling and demands that only the failure
+ * ledger writes one, and this file is not it.
+ */
+import { formatDeliveryHoldNotice, } from "../delivery-hold-notice.js";
+import { DELIVERY_BACKOFF_HOLDING_REASON } from "../raw-evidence-staging.js";
+/**
+ * Is this reason a delivery hold rather than a delivery failure?
+ *
+ * Exact match against the label telemetry-core owns — the same discipline the
+ * failure classifier follows. A reason that merely CONTAINS the word "backoff"
+ * is not evidence of anything (BLI-3551's lesson, applied to the other side of
+ * the same fence).
+ */
+export function isDeliveryHoldReason(reason) {
+    return reason === DELIVERY_BACKOFF_HOLDING_REASON;
+}
+/**
+ * Fold every worktree's held objects into one hold for the tick, or null.
+ *
+ * The count is summed because a tick can sync several worktrees and each one
+ * reports its own held objects. The AGE takes the oldest across all of them and
+ * the NEXT ATTEMPT the earliest, because both are promises about the whole
+ * machine: the operator asks "how long has anything been stuck" and "when does
+ * anything move", not "which worktree".
+ *
+ * Returns null when nothing is held, so no caller can announce a hold of
+ * nothing — a status line that appears on every tick is one people stop
+ * reading.
+ */
+export function summarizeDeliveryHold(outcomes) {
+    let objectCount = 0;
+    let oldestFirstFailedAt = null;
+    let nextAttemptAt = null;
+    let lastReason = null;
+    for (const { sync } of outcomes) {
+        const held = sync.raw_evidence_delivery_held_count ?? 0;
+        if (held <= 0)
+            continue;
+        objectCount += held;
+        const first = sync.raw_evidence_held_oldest_failure_at ?? null;
+        if (first && (!oldestFirstFailedAt || first < oldestFirstFailedAt)) {
+            oldestFirstFailedAt = first;
+            // The reason travels WITH the object it belongs to. A reason taken from
+            // one worktree and an age from another would describe no object at all.
+            lastReason = sync.raw_evidence_held_last_reason ?? null;
+        }
+        const next = sync.raw_evidence_held_next_attempt_at ?? null;
+        if (next && (!nextAttemptAt || next < nextAttemptAt))
+            nextAttemptAt = next;
+    }
+    if (objectCount <= 0)
+        return null;
+    const notice = formatDeliveryHoldNotice({
+        objectCount,
+        oldestFirstFailedAt,
+        nextAttemptAt,
+        lastReason,
+    });
+    if (!notice)
+        return null;
+    return { objectCount, oldestFirstFailedAt, nextAttemptAt, lastReason, notice };
+}
+/**
+ * Say out loud, once per tick, that bytes are being withheld on purpose.
+ *
+ * `logEvidenceHeldByBackoff` already names the objects at the moment they are
+ * partitioned off the wire; this is the RUN's line, so the tick that reports
+ * itself as held also explains itself on stderr where launchd captures it.
+ * Counts, instants and reason labels only.
+ */
+export function logDeliveryHold(hold) {
+    console.error("[session-sync] raw evidence held by delivery backoff, nothing else failed", JSON.stringify({
+        reason: hold.notice,
+        object_count: hold.objectCount,
+        oldest_first_failed_at: hold.oldestFirstFailedAt,
+        next_attempt_at: hold.nextAttemptAt,
+        last_reason: hold.lastReason,
+        next_action: "nothing until the next attempt is due; run `cockpit doctor` if it is already past",
+    }));
+}

package/dist/commands/session-sync.js

@@ -25,6 +25,9 @@
  *   class-lock test reads that file (BLI-3551).
  * - `session-sync-health.ts` — the verdict, and the notice a quiet-but-working
  *   machine still emits.
+ * - `session-sync-hold.ts` — what the tick withheld ON PURPOSE and when it will
+ *   try again (BLI-4022), which is a different question from what it got wrong
+ *   and so lives in a different file from the failure ledger.
  * - `session-sync-counters.ts` — the two honest heartbeat counters beside the
  *   raw scan count: sessions new since the last tick's cursor, and sessions
  *   still pending a durable pointer (BLI-3645).
@@ -49,6 +52,7 @@ export { isLiveSyncCollectableAttributionState, liveSyncCursorEntryRequiresRetry
 export { sourceScanFailureReason, sourceScanRetryReason, } from "./session-sync-scan.js";
 export { SYNC_FAILED_WITHOUT_REASON } from "./session-sync-failures.js";
 export { nothingInRootCount } from "./session-sync-health.js";
+export { isDeliveryHoldReason, summarizeDeliveryHold, } from "./session-sync-hold.js";
 /**
  * Shared dual-source sync orchestration for single-repo and parent-folder
  * modes. Codex AND Claude Code sessions are scanned and attributed once across
@@ -126,6 +130,7 @@ export async function runAttributedWorktreeSync(options) {
         failure_reasons: health.failure_reasons,
         failure_records: health.failure_records,
         notice: health.notice,
+        hold: health.hold,
         sessions_observed: sessions.length,
         sessions_outside_root: health.sessions_outside_root,
         sessions_new_this_tick: health.sessions_new_this_tick,

package/dist/commands/sync-receipt.js

@@ -91,16 +91,25 @@ function standAsideForRunningSync(command, io, heldSince) {
  * is the receipt that separates "this machine is alive and its operator
  * works outside the approved roots" from "this machine is dead", which
  * until now looked identical from the dashboard.
+ *
+ * BLI-4022 added the second thing an `ok` tick can say: `held_backoff:…`, the
+ * objects this tick withheld on purpose and when they may be offered again.
+ * The two can never collide — `nothing_in_root` requires that NO worktree
+ * synced at all (`nothingInRootCount`), and a hold requires a worktree that
+ * did — so one field carries whichever is true, and the notice wins if that
+ * ever stops being the case, because "there was nothing to collect" is the
+ * larger fact about the tick.
  */
-function collectedReceipt(run) {
+export function collectedReceipt(run) {
+    const reason = run.notice ?? run.holdNotice;
     return {
         exitCode: run.exitCode,
         completion: {
             step: "sync_complete",
             status: "ok",
-            ...(run.notice ? { error_detail: run.notice } : {}),
+            ...(reason ? { error_detail: reason } : {}),
         },
-        heartbeat: { status: "ok", reason: run.notice, ...heartbeatCounts(run) },
+        heartbeat: { status: "ok", reason, ...heartbeatCounts(run) },
     };
 }
 /**
@@ -111,8 +120,14 @@ function collectedReceipt(run) {
  * failure rows carried a null detail and the real reason was reachable only
  * by running `cockpit status` on the machine itself (BLI-2526).
  */
-function failedReceipt(run) {
-    const reasonText = run.failureReasons.join("; ");
+export function failedReceipt(run) {
+    // BLI-4022: the hold leads on a failing tick. `error_detail` is bounded, and
+    // an operator reading a red row still has to be able to see what is merely
+    // waiting — otherwise the held objects become invisible the moment anything
+    // else goes wrong, which is the opposite of the fix.
+    const reasonText = [run.holdNotice, ...run.failureReasons]
+        .filter(Boolean)
+        .join("; ");
     // The bucket comes from the records the deciding branches wrote, not from
     // this sentence (BLI-3551). The sentence is still the detail.
     const errorCode = classifySyncFailureRecords(run.failureRecords);

package/dist/commands/sync-report.js

@@ -141,6 +141,9 @@ function syncResult(run) {
         failureReasons: run.ok ? [] : run.failure_reasons,
         failureRecords: run.ok ? [] : run.failure_records,
         notice: run.notice,
+        // BLI-4022: unlike the reasons, the hold survives a successful run — it is
+        // what the tick withheld, not why it failed.
+        holdNotice: run.hold?.notice ?? null,
         sessionsObserved: run.sessions_observed,
         sessionsOutsideRoot: run.sessions_outside_root,
         sessionsNewThisTick: run.sessions_new_this_tick,

package/dist/delivery-hold-notice.js

@@ -0,0 +1,166 @@
+/**
+ * A HOLD is not a FAILURE — and this file is the one place that spells it.
+ *
+ * BLI-4022. `delivery_backoff_holding` means "this object is inside its own
+ * retry window, so this tick did not offer it". Until now that reason went
+ * into the sync's failure ledger like any other, so a machine collecting
+ * perfectly reported `sync_failed` on every tick for as long as the backoff
+ * held: Ian's Mac mini was RED on eight consecutive ticks from
+ * 2026-09-09T00:11Z with the detail
+ * `raw_evidence_retry:delivery_backoff_holding; raw_evidence:delivery_backoff_holding`
+ * while its sessions kept landing and its heartbeat kept moving.
+ *
+ * The honesty is unchanged. A held object IS missing collection and must never
+ * read as clean (that is the rule BLI-3066 bought). What changes is the
+ * OUTCOME: a tick whose only raw-evidence complaint is held objects reports a
+ * named hold instead of a failure, and the hold carries everything an operator
+ * needs to decide whether to care — how many objects, how long the oldest has
+ * been failing, when the next attempt is due, and the object's own last reason.
+ *
+ * ## The grammar
+ *
+ * One token, because it has to survive two narrow channels: the heartbeat's
+ * `last_sync_reason` (`^[a-z0-9_:.-]+$`, 120 chars, no spaces) and the receipt's
+ * `error_detail`. Fields are positional and colon-separated:
+ *
+ *     held_backoff:<count>:<oldest_first_failed_at>:<next_attempt_at>:<last_reason>
+ *     held_backoff:3:2026-08-14T17:38Z:2026-09-09T06:11Z:chunk_10_failed_http_500
+ *
+ * Timestamps are minute precision UTC; `-` stands for a field this machine
+ * could not fill. The last reason is bounded so the whole token fits the
+ * heartbeat's 120 characters — the count and the ages are what a colour is
+ * decided from, so the reason is the field that gives way.
+ *
+ * The collector WRITES the token and the dashboard's fleet board READS it
+ * (`lib/ops/fleet-liveness-device-verdict.ts`, through this package's
+ * `./delivery-hold` export). One grammar, one file: a second copy of this
+ * string is exactly how the collector's word and the server's word drift
+ * apart, which is why `DELIVERY_BACKOFF_HOLDING` itself is aliased from
+ * telemetry-core rather than spelled twice.
+ */
+/** The token's leading word. Greppable in a receipt, a log line or a DM. */
+export const DELIVERY_HOLD_NOTICE_PREFIX = "held_backoff";
+/** The heartbeat's own ceiling for `last_sync_reason`. The token fits inside it. */
+export const DELIVERY_HOLD_NOTICE_MAX_CHARS = 120;
+/**
+ * How long a hold may last before it stops being a wait and becomes a stuck
+ * object.
+ *
+ * The backoff schedule doubles from the scheduler's own 15-minute cadence to a
+ * six-hour ceiling (`EVIDENCE_DELIVERY_BACKOFF_MAX_MS`), so an object held
+ * longer than this has already been offered at least four more times at the
+ * ceiling and been refused every time. Nothing is going to change on its own,
+ * and "next retry at T — nothing to do until then" would be a promise the
+ * machine cannot keep. 24 hours is also the board's own `SILENT_AFTER_HOURS`,
+ * so both clocks agree on when a quiet thing stops being a blip.
+ */
+export const DELIVERY_HOLD_STALE_AFTER_HOURS = 24;
+/** The most characters of an object's own reason label the token may carry. */
+const MAX_HOLD_REASON_CHARS = 64;
+/** A field this machine could not fill. Never omitted — the shape is positional. */
+const ABSENT = "-";
+/**
+ * Render the hold as the single token the heartbeat and the receipt carry.
+ *
+ * Returns null for a hold of nothing, so a caller cannot accidentally announce
+ * a hold that is not happening.
+ */
+export function formatDeliveryHoldNotice(notice) {
+    if (notice.objectCount <= 0)
+        return null;
+    const head = [
+        DELIVERY_HOLD_NOTICE_PREFIX,
+        String(Math.trunc(notice.objectCount)),
+        minuteStamp(notice.oldestFirstFailedAt),
+        minuteStamp(notice.nextAttemptAt),
+    ].join(":");
+    const budget = Math.min(MAX_HOLD_REASON_CHARS, DELIVERY_HOLD_NOTICE_MAX_CHARS - head.length - 1);
+    return `${head}:${reasonWord(notice.lastReason, budget)}`;
+}
+/**
+ * Find a hold token inside anything a receipt carries, and read it back.
+ *
+ * Deliberately a SEARCH, not a whole-string match: on a tick that also failed
+ * for a real reason the token rides beside those reasons in the same
+ * `error_detail`, and the board must still be able to say what is held.
+ */
+export function parseDeliveryHoldNotice(text) {
+    if (!text)
+        return null;
+    // The stamp shape is pinned rather than described by a character class: a
+    // class containing `:` is greedy across the field separator, and a parser
+    // that swallowed one field into the next reported an age of twenty-five
+    // years and a next attempt in 2001.
+    const stamp = String.raw `(?:-|\d{4}-\d{2}-\d{2}T\d{2}:\d{2}Z)`;
+    const match = new RegExp(`${DELIVERY_HOLD_NOTICE_PREFIX}:(\\d+):(${stamp}):(${stamp}):([a-z0-9_-]+)`, "iu").exec(text);
+    if (!match)
+        return null;
+    const objectCount = Number.parseInt(match[1], 10);
+    if (!Number.isFinite(objectCount) || objectCount <= 0)
+        return null;
+    return {
+        objectCount,
+        oldestFirstFailedAt: readStamp(match[2]),
+        nextAttemptAt: readStamp(match[3]),
+        lastReason: match[4] === ABSENT ? null : match[4],
+    };
+}
+/**
+ * How long the longest-held object has been failing, in hours.
+ *
+ * Null when the token carried no first-failure instant, which is a different
+ * fact from "zero hours" — an unknown age is never treated as a fresh hold.
+ */
+export function deliveryHoldAgeHours(notice, nowIso) {
+    if (!notice.oldestFirstFailedAt)
+        return null;
+    const from = Date.parse(notice.oldestFirstFailedAt);
+    const now = Date.parse(nowIso);
+    if (!Number.isFinite(from) || !Number.isFinite(now))
+        return null;
+    return (now - from) / 3_600_000;
+}
+/**
+ * Has this hold stopped being a wait?
+ *
+ * An age this reader could not compute counts as stale on purpose: the whole
+ * point of the amber sentence is the promise "next retry at T", and a hold
+ * whose age is unknown is one nobody can make that promise about.
+ */
+export function isDeliveryHoldStale(notice, nowIso) {
+    const hours = deliveryHoldAgeHours(notice, nowIso);
+    if (hours === null)
+        return true;
+    return hours > DELIVERY_HOLD_STALE_AFTER_HOURS;
+}
+/** `2026-09-09T06:11Z`, or `-` for an instant this machine does not have. */
+function minuteStamp(iso) {
+    if (!iso)
+        return ABSENT;
+    const parsed = Date.parse(iso);
+    if (!Number.isFinite(parsed))
+        return ABSENT;
+    return `${new Date(parsed).toISOString().slice(0, 16)}Z`;
+}
+/** The inverse: a token field back to an ISO instant, or null when absent. */
+function readStamp(field) {
+    if (field === ABSENT)
+        return null;
+    const parsed = Date.parse(field);
+    return Number.isFinite(parsed) ? new Date(parsed).toISOString() : null;
+}
+/**
+ * A reason label narrowed to what the token's charset and budget allow.
+ *
+ * Truncation is marked by dropping characters, never by an ellipsis: the
+ * heartbeat's charset has no `…`, and a token the door rejects tells nobody
+ * anything at all.
+ */
+function reasonWord(reason, budget) {
+    if (!reason || budget <= 0)
+        return ABSENT;
+    const safe = reason.replace(/[^a-z0-9_]/giu, "_").replace(/^_+|_+$/gu, "");
+    if (safe.length === 0)
+        return ABSENT;
+    return safe.slice(0, budget);
+}

package/dist/raw-evidence-staging.js

@@ -25,6 +25,10 @@ import { describeError, isMissingFileFailure } from "./health-detail.js";
  * Metadata only: content hashes, byte sizes, pack ids, pack-relative paths,
  * reason labels, timestamps. Never content, never an absolute path.
  */
+// BLI-4022. The stuck/held summary moved to its own sibling so this file
+// stays under the readability band; it is still importable from here,
+// which is the address every caller already knows.
+export { summarizeStuckEvidence, } from "./raw-evidence-stuck-summary.js";
 export const RAW_EVIDENCE_STAGING_FILENAME = "raw-evidence-staging.json";
 /**
  * Backoff schedule for an object whose delivery keeps failing.
@@ -207,33 +211,6 @@ export function evidenceSourceKey(options) {
             : "unknown";
     return `${options.kind}:${options.sessionId ?? "none"}:${source}`;
 }
-/**
- * What `cockpit status` and the health receipt need in order to be unable to
- * read green while an object has been failing for nine days.
- */
-export function summarizeStuckEvidence(state, now) {
-    const entries = Object.values(state.delivery_attempts);
-    const reasons = new Set();
-    let heldCount = 0;
-    let maxAttempts = 0;
-    let oldest = null;
-    for (const entry of entries) {
-        reasons.add(entry.last_reason);
-        if (Date.parse(entry.next_attempt_at) > now.getTime())
-            heldCount += 1;
-        maxAttempts = Math.max(maxAttempts, entry.attempts);
-        if (!oldest || entry.first_failed_at.localeCompare(oldest) < 0) {
-            oldest = entry.first_failed_at;
-        }
-    }
-    return {
-        stuck_object_count: entries.length,
-        held_object_count: heldCount,
-        max_attempts: maxAttempts,
-        oldest_first_failed_at: oldest,
-        reasons: [...reasons].sort(),
-    };
-}
 /**
  * Pack id derived from CONTENT, never from the clock.
  *

package/dist/raw-evidence-stuck-summary.js

@@ -0,0 +1,60 @@
+/**
+ * "Is anything stuck, and is anything being held right now?" — the two
+ * questions `cockpit status`, the health receipt and the fleet board ask of the
+ * delivery-attempt history, split out of `raw-evidence-staging.ts` (BLI-4022)
+ * so that file stays under the repo's readability band.
+ *
+ * The distinction this file exists to keep: an object with a live failure
+ * history is STUCK, and an object whose next attempt is still in the future is
+ * HELD. Every held object is stuck and most stuck objects are held, but the two
+ * answer different questions — "has anything been failing for nine days" versus
+ * "what did this tick withhold, and when does it try again" — and BLI-4022
+ * needed the second one, which nothing computed.
+ *
+ * Metadata only, like the rest of this family: content hashes, byte sizes,
+ * reason labels, timestamps. Never content, never an absolute path.
+ */
+/**
+ * What `cockpit status` and the health receipt need in order to be unable to
+ * read green while an object has been failing for nine days.
+ */
+export function summarizeStuckEvidence(state, now) {
+    const entries = Object.values(state.delivery_attempts);
+    const reasons = new Set();
+    let heldCount = 0;
+    let maxAttempts = 0;
+    let oldest = null;
+    // The held objects are tracked apart from the stuck ones, because a hold is
+    // judged on what is being withheld NOW and on when it may next be offered —
+    // not on every object that has ever failed here.
+    let heldOldest = null;
+    let heldNextAttemptAt = null;
+    for (const entry of entries) {
+        reasons.add(entry.last_reason);
+        if (Date.parse(entry.next_attempt_at) > now.getTime()) {
+            heldCount += 1;
+            if (!heldOldest ||
+                entry.first_failed_at.localeCompare(heldOldest.first_failed_at) < 0) {
+                heldOldest = entry;
+            }
+            if (!heldNextAttemptAt ||
+                entry.next_attempt_at.localeCompare(heldNextAttemptAt) < 0) {
+                heldNextAttemptAt = entry.next_attempt_at;
+            }
+        }
+        maxAttempts = Math.max(maxAttempts, entry.attempts);
+        if (!oldest || entry.first_failed_at.localeCompare(oldest) < 0) {
+            oldest = entry.first_failed_at;
+        }
+    }
+    return {
+        stuck_object_count: entries.length,
+        held_object_count: heldCount,
+        max_attempts: maxAttempts,
+        oldest_first_failed_at: oldest,
+        reasons: [...reasons].sort(),
+        held_oldest_first_failed_at: heldOldest?.first_failed_at ?? null,
+        held_next_attempt_at: heldNextAttemptAt,
+        held_last_reason: heldOldest?.last_reason ?? null,
+    };
+}

package/dist/upload-evidence-delivery-summary.js

@@ -101,6 +101,12 @@ export function hasRetryableEvidenceGap(facts, outcomes) {
  * backoff is missing collection right now. If it did not land here the sync
  * would read clean while a transcript sat undelivered for nine days, which is
  * the exact shape of BLI-3066.
+ *
+ * BLI-4022 did NOT change that. A hold still queues the retry and still travels
+ * to the status output; what changed is downstream, at the ledger in
+ * `commands/session-sync-failures.ts`, which no longer files it as a FAILED
+ * tick. Retryable and failed are two questions, and answering both with this
+ * one set is what painted a collecting machine red for eight ticks.
  */
 function isRetryableEvidenceSkipReason(reason) {
     if (reason === DELIVERY_BACKOFF_HOLDING_REASON)
@@ -201,5 +207,8 @@ export function summarizeRawEvidenceDelivery(built, outcomes, uploadedChunkCount
         raw_evidence_stuck_object_count: stuck.stuck_object_count,
         raw_evidence_max_delivery_attempts: stuck.max_attempts,
         raw_evidence_oldest_delivery_failure_at: stuck.oldest_first_failed_at,
+        raw_evidence_held_oldest_failure_at: stuck.held_oldest_first_failed_at,
+        raw_evidence_held_next_attempt_at: stuck.held_next_attempt_at,
+        raw_evidence_held_last_reason: stuck.held_last_reason,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.96",
+  "version": "0.2.98",
   "private": false,
   "type": "module",
   "bin": {
@@ -28,7 +28,7 @@
   },
   "dependencies": {
     "@bli-cockpit/memory-mcp": "0.1.25",
-    "@bli-cockpit/mcp": "0.1.28",
+    "@bli-cockpit/mcp": "0.1.29",
     "@bli-cockpit/telemetry-core": "0.1.42"
   }
 }