@bli-cockpit/cli 0.2.59 → 0.2.61

package/README.md

@@ -65,7 +65,7 @@ normal user, on both macOS and Windows.
 | Command | What it does | Why it exists / why this name |
 |---|---|---|
 | `cockpit onboard` | The named setup subset: signs you in (email code), registers this machine, starts capture, uploads once, completes all-history Codex and Claude backfill for saved approved roots, installs the 15-min background sync, and only then prints proof you're live. | You are boarding the crew. `do-everything` calls this flow when setup is missing; rerunning it directly is safe. Partial or failed backfill blocks readiness with an exact retry reason. |
-| `cockpit do-everything` / `cockpit fix` | Converges a Mac or Windows PC from blank or already-onboarded state: latest CLI, signed-in device token, saved roots, autostart, historical backfill, raw-evidence GC, and fresh sync. Interactive first runs prompt for email OTP and collection roots; headless/`--json` runs explain and exit instead of blocking. `--dry-run` previews without writing. | Edward can post one line and every intern machine should end green. `fix` is the alias people guess. |
+| `cockpit do-everything` / `cockpit fix` / `cockpit doctor` | Converges a Mac or Windows PC from blank or already-onboarded state: latest CLI, signed-in device token, saved roots, autostart, historical backfill, raw-evidence GC, and fresh sync. Interactive first runs prompt for email OTP and collection roots; headless/`--json` runs explain and exit instead of blocking. `--dry-run` previews without writing. | Edward can post one line and every intern machine should end green. `fix` is the alias people guess; `doctor` is the alias the ops board, the setup receipt and the heartbeat all tell you to run, and it is the same command (it checks each row, then fixes it). |
 | `cockpit status` | Prints install / sign-in / capture / upload health in one screen. | The "is it working?" command. Run it whenever you're unsure. |
 | `cockpit backfill --all` | Uploads your HISTORICAL Codex + Claude sessions (from before Cockpit existed on this machine). Discovery defaults to depth 3 and 50 repos; raise `--max-depth` or `--max-repos` when the returned retry command says a cap was reached. | One-time catch-up so your past work counts too. "Backfill" = fill in the back-catalog. |
 | `cockpit sync` | Captures and uploads once, right now. This is what the background agent runs every 15 min — you almost never type it yourself. | Named for what it does: synchronize local session files up to the dashboard. |

package/dist/commands/docs.js

@@ -235,6 +235,11 @@ async function updateDoc(command, door) {
             ...(bodyMarkdown !== undefined ? { body_markdown: bodyMarkdown } : {}),
             ...(command.visibility !== undefined ? { visibility: command.visibility } : {}),
             ...(command.clearParent ? { parent_id: null } : command.parentId ? { parent_id: command.parentId } : {}),
+            // BLI-3759: only ever sent when the operator asked for it. Without the
+            // key, a body that would empty a document holding text comes back as the
+            // door's own `refused_empty_body` (409), which `failAgentDoor` prints
+            // verbatim — the CLI never rephrases it and never retries with the flag.
+            ...(command.allowEmpty ? { allow_empty: true } : {}),
         },
     });
     if (!answer.ok)

package/dist/commands/jarvis-answer-envelope.js

@@ -39,6 +39,7 @@ export const JARVIS_ANSWER_ENVELOPE_KEYS = [
     "turn_id",
     "thread_id",
     "trace_thread_id",
+    "proposal_id",
     "degraded",
     "degraded_reasons",
 ];
@@ -74,6 +75,7 @@ export function buildJarvisAnswerEnvelope(input) {
         turn_id: turnId,
         thread_id: input.thread ?? null,
         trace_thread_id: input.traceThread ?? null,
+        proposal_id: input.proposalId ?? null,
         degraded: reasons.length > 0,
         degraded_reasons: reasons,
     };

package/dist/commands/jarvis-render.js

@@ -37,6 +37,19 @@ export function validatePrompt(raw) {
  * (BLI-3414) — same field names the request handler parses, mirroring the
  * JSON body's fields plus one `image` file field.
  */
+/**
+ * Whether a PROGRAM is reading this turn's answer (BLI-3755).
+ *
+ * `--json` is a script's contract, and the coding arm's approval gate assumes
+ * the code it hands back reaches a person. So a `--json` turn declares itself
+ * an agent surface and JARVIS answers with a proposal id in place of the code;
+ * `--show-approval-code` opts a script that really is driving a dispatch for a
+ * human back in, and the terminal logs that it did. An interactive turn is
+ * always a person's and never sends this.
+ */
+export function agentSurface(command) {
+    return command.json === true && command.showApprovalCode !== true;
+}
 export function buildAttachmentForm(command, prompt, attachment) {
     const form = new FormData();
     form.set("question", prompt);
@@ -47,6 +60,11 @@ export function buildAttachmentForm(command, prompt, attachment) {
         form.set("model", command.model);
     if (command.date)
         form.set("date", command.date);
+    // BLI-3755: an attached-image turn is still a turn on some surface, and the
+    // coding arm rides the same belt — dropping this here would hand a code to a
+    // program that sent a screenshot.
+    if (agentSurface(command))
+        form.set("surface", "agent");
     form.set("image", new File([attachment.bytes], attachment.fileName, { type: attachment.mimeType }));
     return form;
 }

package/dist/commands/jarvis-turn.js

@@ -12,7 +12,7 @@ import { readAttachedImage } from "./jarvis-attachment.js";
 import { rememberTurnTrace } from "./jarvis-trace.js";
 import { towerFailureDetail, towerJsonRequest, towerRequest } from "../tower-client.js";
 import { readTowerTurn, streamFailureDetail } from "../tower-stream.js";
-import { activityToTrace, ANSWER_UPDATING_LINE, buildAttachmentForm, clientTimingFields, createLiveAnswer, latencyFields, latencyLogFields, TURN_DEADLINE_MS, writeActivityLine, writeAttachmentRefusal, writeFailure, writeModelReceipt, writeRevision, writeTraceBlock, } from "./jarvis-render.js";
+import { activityToTrace, agentSurface, ANSWER_UPDATING_LINE, buildAttachmentForm, clientTimingFields, createLiveAnswer, latencyFields, latencyLogFields, TURN_DEADLINE_MS, writeActivityLine, writeAttachmentRefusal, writeFailure, writeModelReceipt, writeRevision, writeTraceBlock, } from "./jarvis-render.js";
 export async function sendOneTurn(context, prompt, io) {
     const startedAt = Date.now();
     // BLI-3414: an attached file is read and locally screened (exists,
@@ -41,6 +41,11 @@ export async function sendOneTurn(context, prompt, io) {
     // all three are named. If this number is ever large, the step that made it
     // large is on the same line.
     const preRequestMs = Date.now() - startedAt;
+    // BLI-3755: never silently. A script that asked for the code is a script
+    // that can spend a human's approval, and the one line saying so is here.
+    if (context.command.json && context.command.showApprovalCode) {
+        log("[jarvis] approval code requested by a --json caller (--show-approval-code)");
+    }
     const requested = await towerRequest({
         dashboardUrl: context.dashboardUrl,
         path: "/api/jarvis/cli",
@@ -65,6 +70,12 @@ export async function sendOneTurn(context, prompt, io) {
                 // there is nothing above to revise.
                 previousAnswer: context.previous?.answer,
                 previousQuestion: context.previous?.question,
+                // BLI-3755: who is reading this answer. A `--json` turn is a
+                // PROGRAM's, so the coding arm withholds its approval code and
+                // answers with a proposal id instead; an interactive turn is a
+                // person's and is unchanged. `--show-approval-code` opts a script
+                // back in, and says so on stderr below.
+                surface: agentSurface(context.command) ? "agent" : undefined,
             },
         log,
     });
@@ -146,6 +157,7 @@ export async function sendOneTurn(context, prompt, io) {
                 modelFallback: body.model?.fallback,
                 revised: body.revised,
                 trace,
+                proposalId: body.proposalId,
             }),
             reply: body.reply,
             thread: body.thread ?? context.command.thread,

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

@@ -31,6 +31,10 @@ export function parseJarvisArgs(args) {
             "--trace",
             "--limit",
             "--json",
+            // BLI-3755: opt a `--json` turn back into seeing the coding arm's
+            // approval code. Without it a `--json` turn is an agent surface and the
+            // code is withheld.
+            "--show-approval-code",
         ],
         valueFlags: [
             "--home",
@@ -123,6 +127,7 @@ export function parseJarvisArgs(args) {
         // callers that want the single-body shape on purpose, not a compat knob.
         stream: !values.booleans.has("--no-stream"),
         json: values.booleans.has("--json"),
+        showApprovalCode: values.booleans.has("--show-approval-code"),
     };
 }
 /**

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

@@ -17,6 +17,7 @@ export function parseDocsArgs(args) {
             "--title",
             "--parent",
             "--clear-parent",
+            "--allow-empty",
             "--visibility",
             "--file",
             "--body-stdin",
@@ -55,6 +56,14 @@ export function parseDocsArgs(args) {
     if (clearParent && action !== "update") {
         throw new Error("--clear-parent belongs to `cockpit docs update`.");
     }
+    // BLI-3759: the PATCH door refuses a body that empties a document holding
+    // text unless the caller sends `allow_empty: true` (`refused_empty_body`,
+    // 409, BLI-3757). `--allow-empty` is the terminal's way to say it, and it
+    // means nothing on the verbs that never send an existing document a new body.
+    const allowEmpty = values.booleans.has("--allow-empty");
+    if (allowEmpty && action !== "update") {
+        throw new Error("--allow-empty belongs to `cockpit docs update`.");
+    }
     const title = optionalNonEmpty(values.flags.get("--title"));
     if (action === "create" && !title) {
         throw new Error("docs create needs --title.");
@@ -80,6 +89,7 @@ export function parseDocsArgs(args) {
         title,
         ...(parentId ? { parentId } : {}),
         clearParent,
+        ...(allowEmpty ? { allowEmpty } : {}),
         visibility: visibility,
         filePath: optionalNonEmpty(values.flags.get("--file")),
         bodyStdin: values.booleans.has("--body-stdin"),

package/dist/commands/local-args.js

@@ -41,6 +41,10 @@ export function parseLocalArgs(argv) {
         // Aliasing lands once the convergence run honours --ticket. See BLI-2494.
         case "do-everything":
         case "fix":
+        // BLI-3768: `doctor` is what the ops board's RED rows, the setup receipt
+        // and the heartbeat all tell a person to run. It routes here exactly like
+        // `fix` — the check table diagnoses, then converges.
+        case "doctor":
             return parseDoctorArgs(command, argv.slice(1));
         case "install":
             return parseInstallArgs(argv.slice(1));

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

@@ -78,6 +78,16 @@ export function localSubcommandHelp(command) {
                 "Alias for `cockpit do-everything`.",
             ],
         ],
+        [
+            "doctor",
+            [
+                "Usage: cockpit doctor [same flags as cockpit do-everything]",
+                "",
+                "Alias for `cockpit do-everything`. It checks this machine row by row —",
+                "CLI version, sign-in, saved folders, background sync, backfill, disk — and",
+                "fixes each row it can. `--dry-run` prints the diagnosis and changes nothing.",
+            ],
+        ],
         [
             "login",
             [
@@ -227,7 +237,7 @@ export function localSubcommandHelp(command) {
         [
             "jarvis",
             [
-                "Usage: cockpit jarvis [question] [--prompt <question>] [--as <person>] [--date <YYYY-MM-DD>] [--thread <name>] [--model <key>] [--image <path>|--file <path>] [--no-stream] [--threads|--history [--limit <n>]] [--trace <id|last>] [--dashboard-url <url>] [--json]",
+                "Usage: cockpit jarvis [question] [--prompt <question>] [--as <person>] [--date <YYYY-MM-DD>] [--thread <name>] [--model <key>] [--image <path>|--file <path>] [--no-stream] [--threads|--history [--limit <n>]] [--trace <id|last>] [--dashboard-url <url>] [--json [--show-approval-code]]",
                 "",
                 "Chats with the same JARVIS used by Tower web chat and the BLI Slack DM.",
                 "--as selects the existing website person space; it changes who the chat is about, never who is authenticated.",
@@ -239,7 +249,8 @@ export function localSubcommandHelp(command) {
                 "Each answer prints a per-tool trace line and, only on a fallback or model mismatch, one model receipt line.",
                 "Trace lines arrive live while JARVIS works; pass --no-stream to wait for the whole answer in one piece instead.",
                 "--json writes one machine-readable response (including trace and model) to stdout; operational metadata stays on stderr. A --json run never streams fragments, whichever mode it is in.",
-                "That object carries answer, sources (the Source: lines inside it), turn_id (pass it to --trace), thread_id (pass it to --thread), degraded and degraded_reasons — the SAME shape the bli-tower MCP server's jarvis_ask tool returns, so a script and an agent read one contract. reply/thread/traceId/model/trace/latency are still there beside it and still mean what they always meant.",
+                "A --json turn is treated as an AGENT surface: if it proposes a coding task, JARVIS answers with proposal_id and NOT the eight-character approval code, because a code a program can read is a code it could approve with. The person fetches the code themself — a Tower browser tab, their Slack DM, or an interactive `cockpit jarvis` — and hands it back. Pass --show-approval-code when a script really is driving a dispatch for a person; the run says on stderr that it did.",
+                "That object carries answer, sources (the Source: lines inside it), turn_id (pass it to --trace), thread_id (pass it to --thread), proposal_id (the coding-arm proposal this turn made, or null), degraded and degraded_reasons — the SAME shape the bli-tower MCP server's jarvis_ask tool returns, so a script and an agent read one contract. reply/thread/traceId/model/trace/latency are still there beside it and still mean what they always meant.",
                 "A turn that outlives the dashboard's own ceiling is reported as turn_timed_out — an incomplete answer is never printed as a finished one.",
                 "The command uses the existing paired device identity. It cannot override the caller, team, role, or person scope.",
                 "--threads lists the terminal conversations on this account; --thread <name> --history replays one (the newest --limit <n> messages). Neither takes a question, and neither can reach anybody else's conversations.",
@@ -540,7 +551,8 @@ export function localSubcommandHelp(command) {
                 "tree — the same documents nested under their parent, for a sidebar-shaped view.",
                 "read <id|slug> — one document's title, slug, visibility, and its body. This is the ONLY verb that returns a body.",
                 "create --title \"<title>\" [--parent <id>] [--visibility org|private] [--file <path>|--body-stdin] — the body comes from --file, or stdin (`cat body.md | cockpit docs create --title \"...\"`); neither means an empty body, matching the browser's own default.",
-                "update <id|slug> [--title \"<t>\"] [--visibility org|private] [--parent <id>|--clear-parent] [--file <path>|--body-stdin] — only the fields you pass change; a `--parent` change IS a move, there is no separate move verb.",
+                "update <id|slug> [--title \"<t>\"] [--visibility org|private] [--parent <id>|--clear-parent] [--file <path>|--body-stdin] [--allow-empty] — only the fields you pass change; a `--parent` change IS a move, there is no separate move verb.",
+                "  --allow-empty clears the page on purpose. A body that would empty a document that holds text is refused (refused_empty_body) unless you say so, because far more often it is a surface that lost the content than a person who meant it.",
                 "A document body is never accepted on the command line — --file (safest on Windows) or a pipe only, same discipline as `cockpit notes paste`.",
                 "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
                 "A refusal keeps Tower's own reason label — needs_rls_client, document_not_found_or_unreadable, document_not_writable, slug_taken, circular_parent, and so on.",

package/dist/commands/local-help.js

@@ -15,6 +15,7 @@ export const rootCommandNames = new Set([
     "upgrade",
     "do-everything",
     "fix",
+    "doctor",
     "install",
     "login",
     "pair",
@@ -57,6 +58,7 @@ export function localCommandHelp(command) {
         "  cockpit upgrade [same flags as update]",
         "  cockpit do-everything [--workspace <path>] [--dashboard-url <url>] [--update-tag <tag>] [--dry-run] [--json]",
         "  cockpit fix [same flags as do-everything]",
+        "  cockpit doctor [same flags as do-everything]",
         "  cockpit install [--dashboard-url <url>] [--workspace <path>] [--allow-home-root] [--json]",
         "  cockpit login [--pair <code>] [--no-browser] [--legacy-pair] [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--no-auth] [--json]",
         "  cockpit pair [--pair <code>] [--no-browser] [--legacy-pair] [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--no-auth] [--json]",
@@ -64,7 +66,7 @@ export function localCommandHelp(command) {
         "  cockpit start [--ticket <id>|--clear-ticket] [--topic <label>] [--intent <intent>] [--phase <phase>] [--workspace <path>] [--branch <name>] [--max-depth <n>] [--max-repos <n>] [--json]",
         "  cockpit sync [--workspace <path>] [--dashboard-url <url>] [--max-depth <n>] [--max-repos <n>] [--json]",
         "  cockpit analyze [--workspace <path>] [--dashboard-url <url>] [--max-depth <n>] [--max-repos <n>] [--json]",
-        "  cockpit jarvis [question] [--prompt <question>] [--as <person>] [--date <YYYY-MM-DD>] [--thread <name>] [--model <key>] [--image <path>|--file <path>] [--no-stream] [--threads|--history [--limit <n>]] [--trace <id|last>] [--dashboard-url <url>] [--json]",
+        "  cockpit jarvis [question] [--prompt <question>] [--as <person>] [--date <YYYY-MM-DD>] [--thread <name>] [--model <key>] [--image <path>|--file <path>] [--no-stream] [--threads|--history [--limit <n>]] [--trace <id|last>] [--dashboard-url <url>] [--json [--show-approval-code]]",
         "  cockpit model [show|set <provider:model>] [--json]",
         "  cockpit scout [start|dismiss|undo <experiment-id>] [--days <n>] [--dashboard-url <url>] [--json]",
         "  cockpit ops [status [--job <id>] [--skips] [--memory] | recompile --person <email|name|id> [--dry-run]] [--dashboard-url <url>] [--json]",
@@ -84,7 +86,7 @@ export function localCommandHelp(command) {
         "  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] [--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] [--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]",
         "  cockpit issue [list|show <BLI-id>|create --title <t>|update <BLI-id>|move <BLI-id> <state>|comment <BLI-id>|history <BLI-id>] [--state <s>] [--assignee me|unassigned|<uuid>] [--project <name|id>] [--limit <n>] [--priority 0-4] [--parent <BLI-id>] [--file <path>|--body-stdin] [--dashboard-url <url>] [--json]",
         "  cockpit project [list] [--archived] [--dashboard-url <url>] [--json]",

package/dist/commands/ops-render.js

@@ -25,6 +25,11 @@ export function verdictWord(verdict) {
         // rather than to a cron config.
         case "failing":
             return "BAD";
+        // BLI-3762. Between "on time" and "dead": the job ran, produced something,
+        // and produced LESS than it owed. A partial result that is still moving
+        // needs a different next step from either neighbour, so it gets a word.
+        case "degraded":
+            return "PART";
         case "never_produced":
             return "EMPTY";
         case "unreadable":

package/dist/commands/ops.js

@@ -75,7 +75,9 @@ async function runOpsStatus(command, io, tower) {
     const unhealthy = rows.filter((row) => row.verdict === "stale" ||
         row.verdict === "never_produced" ||
         row.verdict === "unreadable" ||
-        row.verdict === "failing");
+        row.verdict === "failing" ||
+        // BLI-3762: a job that ran and wrote less than it owed is not healthy.
+        row.verdict === "degraded");
     if (command.json) {
         writeLine(io.stdout, JSON.stringify(memory ? { ...payload, memory: memory.section } : payload));
     }

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.59");
+    writeLine(io?.stdout ?? process.stdout, "0.2.61");
     return 0;
   }
 

package/dist/commands/tower-mcp-install.js

@@ -6,9 +6,11 @@
  * verb: that command already runs unasked from `do-everything` and the daily
  * sync tick (`memory-install.ts`'s own header), which is the ONLY way a
  * registration reaches every intern machine without anyone typing anything.
- * A second, un-invoked `cockpit mcp install` command would ship the feature
+ * A second, un-invoked `mcp install` verb of its own would ship the feature
  * and still leave every existing machine unregistered until someone learned
- * to type the new verb.
+ * to type it. (Deliberately not written as a `cockpit ...` invocation here:
+ * BLI-3768's census refuses any spelled-out command the router would answer
+ * `Unknown command` to, and this one is a road not taken.)
  *
  * `no_bin_no_write` applies here too, for the identical reason
  * `memory-install.ts` states it for `bli-memory-mcp`: a Claude Code entry

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.59",
+  "version": "0.2.61",
   "private": false,
   "type": "module",
   "bin": {
@@ -27,8 +27,8 @@
     "test": "node dist/cli.js --help && node ../../scripts/assert-public-cli-routing.mjs && node ../../scripts/assert-public-cli-runtime-files.mjs && node ../../scripts/assert-public-cli-no-fleet-posts.mjs && node ../../scripts/assert-public-package-pack.mjs --workspace=@bli-cockpit/cli"
   },
   "dependencies": {
-    "@bli-cockpit/memory-mcp": "0.1.7",
-    "@bli-cockpit/mcp": "0.1.3",
+    "@bli-cockpit/memory-mcp": "0.1.8",
+    "@bli-cockpit/mcp": "0.1.4",
     "@bli-cockpit/telemetry-core": "0.1.29"
   }
 }