@bli-cockpit/cli 0.2.133 → 0.2.137

package/dist/commands/docs-notion.js

@@ -0,0 +1,90 @@
+/**
+ * `cockpit docs link` and `cockpit docs sync-status` — the Notion half of the
+ * document library (BLI-10430). A sibling of `docs.ts` rather than more of it:
+ * that file is the five library verbs, and this one is the two-way sync's.
+ *
+ * `link <id|slug> <notion-url|page-id>` → `PUT /api/docs/documents/[id]/notion-link`
+ * `link <id|slug> --clear`             → `DELETE` on the same door
+ * `sync-status [<id|slug>]`            → `GET /api/docs/notion-sync`
+ *
+ * The door folds any Notion URL or id to the page id the importer stores, and
+ * refuses by name: `invalid_notion_page`, `notion_page_already_linked`,
+ * `document_not_writable`. A link means the page is the truth: the next sync
+ * pulls it over the Tower copy and keeps the copy as a version
+ * (`docs/architecture/docs.md`, "Two-way sync with Notion").
+ */
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+import { resolveDocId } from "./docs.js";
+const TAG = "[docs cli]";
+const READ_DEADLINE_MS = 30_000;
+const WRITE_DEADLINE_MS = 60_000;
+/**
+ * `sync-status [<id|slug>]` → `GET /api/docs/notion-sync[?document_id=]`. Tower's
+ * half of the answer only (synced / tower_changed / never_synced); the door
+ * never claims anything about Notion it has not read.
+ */
+export async function syncStatusDocs(command, door) {
+    let path = "/api/docs/notion-sync";
+    if (command.docRef) {
+        const resolved = await resolveDocId(door, command.docRef);
+        if (resolved.status === "list_failed")
+            return failAgentDoor(door, TAG, resolved.reason, resolved.detail);
+        if (resolved.status === "not_found") {
+            return failAgentDoor(door, TAG, "document_not_found_or_unreadable", `That document does not exist, or you cannot read it: ${command.docRef}`);
+        }
+        path = `${path}?document_id=${encodeURIComponent(resolved.id)}`;
+    }
+    const answer = await askAgentDoor(door, { path, method: "GET", label: "docs sync-status", timeoutMs: READ_DEADLINE_MS });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, counts: body.counts, documents: body.documents ?? [] });
+    const documents = body.documents ?? [];
+    for (const doc of documents) {
+        writeLine(door.io.stdout, `${doc.id}  ${doc.state.padEnd(13)}  ${(doc.notion_synced_at ?? "never").padEnd(25)}  ${doc.slug ?? "(no slug)"}  ${doc.title}`);
+    }
+    const byState = body.counts?.by_state ?? {};
+    writeLine(door.io.stdout, "");
+    writeLine(door.io.stdout, `${body.counts?.linked ?? documents.length} linked: ${Object.entries(byState)
+        .map(([state, count]) => `${count} ${state}`)
+        .join(", ")}. A Notion edit shows up at the next pull, not here.`);
+    return 0;
+}
+export async function linkDoc(command, door) {
+    const ref = command.docRef ?? "";
+    const resolved = await resolveDocId(door, ref);
+    if (resolved.status === "list_failed")
+        return failAgentDoor(door, TAG, resolved.reason, resolved.detail);
+    if (resolved.status === "not_found") {
+        return failAgentDoor(door, TAG, "document_not_found_or_unreadable", `That document does not exist, or you cannot write to it: ${ref}`);
+    }
+    const path = `/api/docs/documents/${encodeURIComponent(resolved.id)}/notion-link`;
+    const answer = command.clearLink
+        ? await askAgentDoor(door, { path, method: "DELETE", label: "docs link", timeoutMs: WRITE_DEADLINE_MS })
+        : await askAgentDoor(door, {
+            path,
+            method: "PUT",
+            label: "docs link",
+            timeoutMs: WRITE_DEADLINE_MS,
+            body: { notion_page: command.notionPage ?? "" },
+        });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const result = answer.body;
+    const document = result.document ?? {};
+    writeLine(door.io.stderr, `${TAG} link ${JSON.stringify({ document_id: document["id"] ?? resolved.id, outcome: result.outcome ?? null })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, outcome: result.outcome, document });
+    const title = String(document["title"] ?? "");
+    const page = document["notion_page_id"];
+    const sentence = {
+        linked: `Linked ${title} to Notion page ${String(page)}. The next sync pulls the page over this copy and keeps the copy as a version.`,
+        already_linked: `${title} was already linked to Notion page ${String(page)}. Nothing changed.`,
+        unlinked: `Unlinked ${title} from Notion. It is a Tower-only document now.`,
+        already_unlinked: `${title} was not linked to Notion. Nothing changed.`,
+    };
+    writeLine(door.io.stdout, sentence[result.outcome ?? ""] ?? `Done: ${title}.`);
+    return 0;
+}

package/dist/commands/docs.js

@@ -29,6 +29,7 @@
  */
 import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor, } from "./agent-door.js";
 import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
+import { linkDoc, syncStatusDocs } from "./docs-notion.js";
 import { readNoteFile } from "./notes-file.js";
 const TAG = "[docs cli]";
 const READ_DEADLINE_MS = 30_000;
@@ -47,6 +48,10 @@ export async function runDocs(command, io) {
             return createDoc(command, door);
         case "update":
             return updateDoc(command, door);
+        case "link":
+            return linkDoc(command, door);
+        case "sync-status":
+            return syncStatusDocs(command, door);
     }
 }
 /** `--parent`, `--query`, `--limit` as the door's own query parameters (BLI-3737). */
@@ -112,7 +117,7 @@ async function treeDocs(door) {
     return 0;
 }
 /** Finds a document id by exact id or exact slug against the flat list. Never fuzzy. */
-async function resolveDocId(door, ref) {
+export async function resolveDocId(door, ref) {
     const answer = await askAgentDoor(door, {
         path: "/api/docs/documents",
         method: "GET",

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

@@ -7,8 +7,8 @@
  * added both without stretching either existing family's own doc comment.
  */
 import { optionalNonEmpty, optionalPositiveInteger, optionalUrl, parseNamedArgs, } from "./local-arg-values.js";
-const DOCS_ACTIONS = new Set(["list", "tree", "read", "create", "update"]);
-const DOCS_ACTIONS_NEEDING_A_DOC = new Set(["read", "update"]);
+const DOCS_ACTIONS = new Set(["list", "tree", "read", "create", "update", "link", "sync-status"]);
+const DOCS_ACTIONS_NEEDING_A_DOC = new Set(["read", "update", "link"]);
 export function parseDocsArgs(args) {
     const values = parseNamedArgs(args, {
         allowedFlags: [
@@ -23,20 +23,46 @@ export function parseDocsArgs(args) {
             "--body-stdin",
             "--query",
             "--limit",
+            "--clear",
             "--json",
         ],
         valueFlags: ["--home", "--dashboard-url", "--title", "--parent", "--visibility", "--file", "--query", "--limit"],
     });
     const { action, rest } = parseDocsAction(values.positionals);
-    const docRef = parseDocsDocumentReference(action, rest);
+    const link = parseDocsLink(action, rest, values.booleans.has("--clear"));
+    const docRef = parseDocsDocumentReference(action, link.rest);
     const { visibility, clearParent, parentId, allowEmpty, title, query, limit } = parseDocsFlags(action, values);
-    return buildDocsCommand(values, action, docRef, visibility, clearParent, parentId, allowEmpty, title, query, limit);
+    return buildDocsCommand(values, action, docRef, visibility, clearParent, parentId, allowEmpty, title, query, limit, link);
+}
+/**
+ * BLI-10430: `docs link <id|slug> <notion-url|page-id>` ties a document to a
+ * Notion page; `docs link <id|slug> --clear` unties it. Exactly one of the two:
+ * a link with neither says nothing, and one with both says two things.
+ */
+function parseDocsLink(action, rest, clear) {
+    if (action !== "link") {
+        if (clear)
+            throw new Error("--clear belongs to `cockpit docs link`.");
+        return { rest };
+    }
+    // No document at all: the document-reference check says so, first.
+    if (rest.length === 0)
+        return { rest };
+    const notionPage = optionalNonEmpty(rest[1]);
+    if (clear && notionPage)
+        throw new Error("docs link takes a Notion page OR --clear, not both.");
+    if (!clear && !notionPage) {
+        throw new Error("docs link needs a Notion page URL or id after the document, or --clear to unlink it.");
+    }
+    if (rest.length > 2)
+        throw new Error(`docs link takes a document and a Notion page, not ${rest.length} arguments.`);
+    return { rest: rest.slice(0, 1), ...(notionPage ? { notionPage } : {}), ...(clear ? { clearLink: true } : {}) };
 }
 function parseDocsAction(positionals) {
     const first = positionals[0];
     const action = (first === undefined ? "list" : first);
     if (!DOCS_ACTIONS.has(action)) {
-        throw new Error(`Unknown docs command: ${first}. Try list, tree, read, create, or update.`);
+        throw new Error(`Unknown docs command: ${first}. Try list, tree, read, create, update, link, or sync-status.`);
     }
     return { action, rest: positionals.slice(first === undefined ? 0 : 1) };
 }
@@ -49,6 +75,12 @@ function parseDocsDocumentReference(action, rest) {
             throw new Error(`docs ${action} takes one document reference, not ${rest.length}.`);
         return docRef;
     }
+    // BLI-10430: `sync-status` reports the whole linked library, or one document.
+    if (action === "sync-status") {
+        if (rest.length > 1)
+            throw new Error(`docs sync-status takes at most one document reference, not ${rest.length}.`);
+        return optionalNonEmpty(rest[0]);
+    }
     if (rest.length > 0)
         throw new Error(`docs ${action} does not take "${rest[0]}".`);
     return undefined;
@@ -92,7 +124,7 @@ function parseDocsFlags(action, values) {
     }
     return { visibility, clearParent, parentId, allowEmpty, title, query, limit };
 }
-function buildDocsCommand(values, action, docRef, visibility, clearParent, parentId, allowEmpty, title, query, limit) {
+function buildDocsCommand(values, action, docRef, visibility, clearParent, parentId, allowEmpty, title, query, limit, link) {
     return {
         kind: "docs",
         action,
@@ -108,6 +140,8 @@ function buildDocsCommand(values, action, docRef, visibility, clearParent, paren
         bodyStdin: values.booleans.has("--body-stdin"),
         ...(query ? { query } : {}),
         ...(limit === undefined ? {} : { limit }),
+        ...(link.notionPage ? { notionPage: link.notionPage } : {}),
+        ...(link.clearLink ? { clearLink: true } : {}),
         json: values.booleans.has("--json"),
     };
 }

package/dist/commands/local-args.js

@@ -16,6 +16,7 @@
  * verbatim, no logic change.
  */
 import { parseRootsArgs } from "./roots.js";
+import { SURFACE_ALIASES } from "./local-help.js";
 import { parseAgentRulesArgs, parseAnalyzeArgs, parseAutostartArgs, parseBackfillArgs, parseCleanArgs, parseDoctorArgs, parseInstallArgs, parseLoginArgs, parseMemoryArgs, parseLogoutArgs, parseOnboardArgs, parseReleaseArgs, parseServeArgs, parseSessionsArgs, parseStartArgs, parseStatusArgs, parseSyncArgs, parseUpdateArgs, } from "./local-args-collector.js";
 import { parseBriefArgs, parseCorrectArgs, parseDocsArgs, parseIssueArgs, parseJarvisArgs, parseMailArgs, parseCalArgs, parseModelArgs, parseMsgArgs, parseNotesArgs, parseOpsArgs, parseProjectArgs, parseModelsArgs, parseScoutArgs, parseSearchArgs, parseSettingsArgs, parseSlackArgs, parseTeamArgs, parseWorkbookArgs, parseUsageArgs, parseCareersArgs, } from "./local-args-tower.js";
 // `normalizeUrl` has always been part of this module's surface — `local.ts` and
@@ -29,6 +30,11 @@ export { normalizeUrl } from "./local-arg-values.js";
 export { DOCTOR_SETUP_ALIASES, } from "./local-command-shapes.js";
 export { SCOUT_MIN_PREFIX_LENGTH, SLACK_WORKSPACE_KEYS, WORKBOOK_MIN_WIDTH, ISSUE_STATES, } from "./local-args-tower.js";
 export function parseLocalArgs(argv) {
+    // BLI-10431: a Tower page name (`work`, `calendar`, ...) is the same parser
+    // as the noun that serves the page — a second spelling, never a second door.
+    const aliasTarget = argv[0] ? SURFACE_ALIASES.get(argv[0]) : undefined;
+    if (aliasTarget)
+        return parseLocalArgs([aliasTarget, ...argv.slice(1)]);
     const command = argv[0];
     switch (command) {
         case "roots": return parseRootsArgs(argv.slice(1));

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

@@ -31,7 +31,7 @@ export const TOWER_COMMAND_HELP = [
             "list [--role <slug>] [--min-score <n>] [--since <date>] [--stage <screened|invited|submitted|graded|booking_sent|passed_on|archived>] — the board, newest first, with the two thresholds in force.",
             "send-takehome <id> (also `invite <id>`): sends that role's take-home from the configured mailbox, whatever the screening scored. The same act as Tower's Send take-home button, and only a row still at `screened`.",
             "decide <id> --decision <passed_on|archived|reopen> — your own call on a row; `reopen` puts it back to `screened`.",
-            "grade <id> [--now]: puts one submission back in the take-home grader's queue. The grader runs on Railway every 15 minutes; --now says so rather than pretending the run happened here.",
+            "grade <id> [--now]: puts one submission back in the take-home grader's queue. The grader runs on Railway every 5 minutes; --now says so rather than pretending the run happened here.",
             "resume <id> [--out <path>] [--force]: the candidate's resume, the same file the drawer's Open resume button shows. Bare, it prints a signed link that dies in 60 seconds; --out downloads the file to that path and refuses to overwrite one already there unless you pass --force.",
             "takehome show <role> — the subject, body, link and the reviewer's rubric for that role.",
             "takehome set <role> [--subject <s>] [--body-file <path>] [--link <url>] [--pass-score <0-10>] — the body comes from a FILE and must keep {first_name} and {link}.",
@@ -42,7 +42,7 @@ export const TOWER_COMMAND_HELP = [
     [
         "docs",
         [
-            "Usage: cockpit docs [list|tree|read <id|slug>|create|update <id>] [flags]",
+            "Usage: cockpit docs [list|tree|read <id|slug>|create|update <id>|link <id|slug> <notion-page>|sync-status [<id|slug>]] [flags]",
             "",
             "The Tower document library, typed. Bare `cockpit docs` lists every document you may read.",
             "list [--parent <id>|root] [--query <text>] [--limit <n>] — every document you may see: id, visibility, body size, slug, title. Metadata only — a list never carries a body, so it stays cheap enough for an agent to call (--json was 604 KB for 155 documents before BLI-3737, and is now a few tens of KB).",
@@ -54,6 +54,8 @@ export const TOWER_COMMAND_HELP = [
             "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] [--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.",
+            "link <id|slug> <notion-url|page-id> — ties the document to a Notion page so the two-way sync moves it both ways. The page is the truth from then on: the next sync pulls it over this copy and keeps the copy as a version. `link <id|slug> --clear` unties it. Refusals: invalid_notion_page, notion_page_already_linked, document_not_writable.",
+            "sync-status [<id|slug>] — every linked document's Notion sync state, or one's: synced (the body is what both sides last agreed on), tower_changed (edited here since; the next write-back pushes it), never_synced (linked, no baseline yet). Tower's half only: a Notion edit shows up at the next pull, not here. Metadata only, never a body.",
             "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-commands.js

@@ -17,7 +17,7 @@
  * something breaks, so it is a user-visible contract like any other.
  */
 import { DEFAULT_DASHBOARD_URL } from "../local-state.js";
-import { localCommandHelp } from "./local-help.js";
+import { localCommandHelp, SURFACE_ALIASES } from "./local-help.js";
 import { TOWER_COMMAND_HELP } from "./local-help-commands-tower.js";
 export function localSubcommandHelp(command) {
     const helpByCommand = new Map([
@@ -662,5 +662,18 @@ export function localSubcommandHelp(command) {
             ],
         ],
     ]);
+    // BLI-10431: a Tower page name answers with its own usage line first, then
+    // the manual of the noun it routes to, so `cockpit work --help` names every
+    // Work verb instead of `Unknown command: work`.
+    const aliasTarget = SURFACE_ALIASES.get(command);
+    if (aliasTarget) {
+        return [
+            `Usage: cockpit ${command} [same verbs and flags as cockpit ${aliasTarget}]`,
+            `\`cockpit ${command}\` is the Tower page's name for \`cockpit ${aliasTarget}\`; both spellings run the same command.`,
+            ...(command === "work" ? ["Projects the issues are filed under: `cockpit project list`."] : []),
+            "",
+            ...(helpByCommand.get(aliasTarget) ?? [localCommandHelp()]),
+        ].join("\n");
+    }
     return (helpByCommand.get(command) ?? [localCommandHelp()]).join("\n");
 }

package/dist/commands/local-help.js

@@ -10,6 +10,26 @@
 import { DEFAULT_DASHBOARD_URL } from "../local-state.js";
 import { SEARCH_KINDS } from "./local-args-tower-search.js";
 import { localSubcommandHelp } from "./local-help-commands.js";
+/**
+ * The Tower PAGE names a person reads in the rail, each routed to the CLI noun
+ * that already serves that page (BLI-10431).
+ *
+ * The rail says WORK, CALENDAR, MESSAGES and MEETING NOTES; the MCP server
+ * says `work_list_issues`; the CLI spelled the same doors `issue`, `cal`,
+ * `msg` and `notes`. `cockpit work --help` answered `Unknown command: work` on
+ * 0.2.133 while every Work verb existed one word away. An alias here is a
+ * second spelling of the same parser, never a second parser: `cockpit work
+ * list` IS `cockpit issue list`, byte for byte.
+ *
+ * `surface-doors.test.ts` reads the rail and the MCP tool names and fails when
+ * a page or a tool family has no spelling here or in `rootCommandNames`.
+ */
+export const SURFACE_ALIASES = new Map([
+    ["work", "issue"],
+    ["calendar", "cal"],
+    ["messages", "msg"],
+    ["meeting-notes", "notes"],
+]);
 export const rootCommandNames = new Set([
     "roots",
     "onboard",
@@ -55,6 +75,7 @@ export const rootCommandNames = new Set([
     "release",
     "careers",
     "usage",
+    ...SURFACE_ALIASES.keys(),
 ]);
 /** Public names omit compatibility spellings while the router keeps accepting them. */
 export const publicCommandNames = new Set([...rootCommandNames].filter((name) => name !== "do-everything" && name !== "fix"));
@@ -108,11 +129,66 @@ export function localCommandHelp(command) {
         "  cockpit usage sessions [--task <BLI-NNNN> | --subject <name>] [--repo <label>] [--since <window>] [--json]",
         "  cockpit usage sessions --session <id> [--from-window <n>] [--json]",
         "  --by-topic groups work types; --by-subject groups open subjects from session summaries.",
+        "  cockpit work [same verbs and flags as cockpit issue]   (the Work page; projects: `cockpit project list`)",
+        "  cockpit calendar [same verbs and flags as cockpit cal]",
+        "  cockpit messages [same verbs and flags as cockpit msg]",
+        "  cockpit meeting-notes [same verbs and flags as cockpit notes]",
         "  cockpit usage people [--by-repo | --by-topic | --by-subject | --by-task] [--min-confidence high|medium|low] [--person <email|me>] [--all] [--detail] [--since <n>d|<n>h|<iso>] [--until <iso>] [--include-automated] [--dashboard-url <url>] [--json]",
         "",
         `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.`,
     ].join("\n");
 }
+/**
+ * What an unknown first word answers (BLI-10431). The closest registered name
+ * within two edits, or none. A person who mistyped `work` as `wrok` wants one line
+ * naming `cockpit work`, not only a sixty-line wall to search by eye.
+ */
+export function suggestCommand(word) {
+    const typed = word.toLowerCase();
+    let best = null;
+    for (const name of publicCommandNames) {
+        const distance = editDistance(typed, name);
+        if (distance > 2 || distance >= name.length)
+            continue;
+        if (!best || distance < best.distance)
+            best = { name, distance };
+    }
+    return best?.name ?? null;
+}
+/** The first line of an unknown-command refusal, with its suggestion if any. */
+export function unknownCommandLine(word) {
+    const suggestion = suggestCommand(word);
+    return suggestion
+        ? `Unknown command: ${word}. Did you mean \`cockpit ${suggestion}\`?`
+        : `Unknown command: ${word}`;
+}
+/**
+ * The one JSON object `--json` promises, for an argv that never reached a
+ * command. Same shape as a Tower refusal (`ok`, `error`, `detail`), so an agent
+ * reads a refused parse and a refused door the same way.
+ */
+export function unknownCommandJson(word) {
+    return JSON.stringify({
+        ok: false,
+        error: "unknown_command",
+        command: word,
+        did_you_mean: suggestCommand(word),
+        detail: `There is no cockpit command named ${word}. Run \`cockpit --help\` for every command.`,
+    });
+}
+function editDistance(a, b) {
+    const row = Array.from({ length: b.length + 1 }, (_, index) => index);
+    for (let i = 1; i <= a.length; i += 1) {
+        let diagonal = row[0];
+        row[0] = i;
+        for (let j = 1; j <= b.length; j += 1) {
+            const above = row[j];
+            row[j] = Math.min(row[j] + 1, row[j - 1] + 1, diagonal + (a[i - 1] === b[j - 1] ? 0 : 1));
+            diagonal = above;
+        }
+    }
+    return row[b.length];
+}
 /**
  * `cockpit <command> --help`, and since BLI-3833 `cockpit <command> <verb>
  * --help` too — QA tick 21 found `cockpit cal create --help` printing the whole

package/dist/commands/local.js

@@ -50,7 +50,7 @@ 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
 // all import from here. Splitting the file must not move a name off it.
-export { rootCommandNames, localCommandHelp } from "./local-help.js";
+export { rootCommandNames, localCommandHelp, SURFACE_ALIASES, unknownCommandJson, unknownCommandLine, } from "./local-help.js";
 export { buildCollectorHeartbeat, collectionRootLabel, collectionRootLabels, sendCollectorHeartbeatBestEffort, } from "./heartbeat.js";
 export { classifySyncFailureRecords, classifySyncHealthError, redactedSyncErrorDetail, reportInstallEventsBestEffort, SYNC_ERROR_DETAIL_MAX_CHARS, } from "./install-receipts.js";
 export { assertCollectionRootPersisted } from "./collection-roots.js";
@@ -66,6 +66,18 @@ export async function runLocalCockpitCli(argv, io = defaultIo()) {
         command = parseLocalArgs(argv);
     }
     catch (error) {
+        // BLI-10431: under --json a refused parse still owes stdout one object.
+        // It used to write nothing there, so `cockpit usage sessions --json`
+        // without a filter read to an agent as an empty answer, not a refusal.
+        if (argv.includes("--json")) {
+            writeLine(io.stdout, JSON.stringify({
+                ok: false,
+                error: "invalid_arguments",
+                command: argv[0] ?? "",
+                detail: errorMessage(error),
+            }));
+        }
+        console.error("[cockpit-cli] arguments refused", JSON.stringify({ reason: "invalid_arguments", command: argv[0] ?? "", json: argv.includes("--json") }));
         writeLine(io.stderr, errorMessage(error));
         writeLine(io.stderr, "");
         // A refused `cockpit cal create --meet` used to print its one correct
@@ -85,6 +97,13 @@ export async function runLocalCockpitCli(argv, io = defaultIo()) {
     // BLI-4110: the outermost stage name, so a crash that escapes every catch
     // below still says which subcommand was running.
     beginStage(`command:${command.kind}`);
+    // BLI-10431: `--json` promises one object on stdout even when the command
+    // throws. Watching whether stdout was written lets the net below add the
+    // refusal object only when the command had not already answered.
+    const wantsJson = "json" in command && command.json === true;
+    const stdoutWatch = wantsJson ? watchWrites(io.stdout) : undefined;
+    if (stdoutWatch)
+        io = { ...io, stdout: stdoutWatch.stream };
     try {
         switch (command.kind) {
             case "roots": return await runRoots(command, io);
@@ -206,6 +225,14 @@ export async function runLocalCockpitCli(argv, io = defaultIo()) {
             command: command.kind,
             ...describeError(error),
         }));
+        if (stdoutWatch && !stdoutWatch.written()) {
+            writeLine(io.stdout, JSON.stringify({
+                ok: false,
+                error: "command_failed",
+                command: command.kind,
+                detail: errorMessage(error),
+            }));
+        }
         writeLine(io.stderr, errorMessage(error));
         return 1;
     }
@@ -239,4 +266,25 @@ async function resolveAndSaveDoctorRoots(command, io) {
     if (!command.json) {
         writeLine(io.stdout, `Saved collection roots: ${resolution.collectionRoots.join(", ")}`);
     }
+}
+/**
+ * The same stream, with a flag that flips on the first write. A Proxy rather
+ * than a copied object so `isTTY`, `columns` and every listener method still
+ * reach the real stream.
+ */
+function watchWrites(stream) {
+    let wrote = false;
+    const watched = new Proxy(stream, {
+        get(target, property) {
+            if (property === "write") {
+                return (...args) => {
+                    wrote = true;
+                    return target.write.apply(target, args);
+                };
+            }
+            const value = Reflect.get(target, property, target);
+            return typeof value === "function" ? value.bind(target) : value;
+        },
+    });
+    return { stream: watched, written: () => wrote };
 }

package/dist/commands/public-root.js

@@ -1,4 +1,10 @@
-import { localCommandHelp, runLocalCockpitCli, rootCommandNames } from "./local.js";
+import {
+  localCommandHelp,
+  runLocalCockpitCli,
+  rootCommandNames,
+  unknownCommandJson,
+  unknownCommandLine,
+} from "./local.js";
 
 export async function runCockpitCli(argv, io) {
   const command = argv[0];
@@ -15,7 +21,7 @@ export async function runCockpitCli(argv, io) {
   }
 
   if (command === "--version" || command === "-V" || command === "version") {
-    writeLine(io?.stdout ?? process.stdout, "0.2.133");
+    writeLine(io?.stdout ?? process.stdout, "0.2.137");
     return 0;
   }
 
@@ -23,7 +29,12 @@ export async function runCockpitCli(argv, io) {
     return runLocalCockpitCli(argv, io);
   }
 
-  writeLine(io?.stderr ?? process.stderr, `Unknown command: ${command}`);
+  // BLI-10431: mirrors commands/root.ts. `--json` owes stdout one object,
+  // and the refusal names the closest real command.
+  if (argv.includes("--json")) {
+    writeLine(io?.stdout ?? process.stdout, unknownCommandJson(command));
+  }
+  writeLine(io?.stderr ?? process.stderr, unknownCommandLine(command));
   writeLine(io?.stderr ?? process.stderr, "");
   writeLine(io?.stderr ?? process.stderr, cockpitHelp());
   return 1;
@@ -45,7 +56,7 @@ function cockpitHelp() {
     "Agent setup: `cockpit doctor` installs and verifies AGENTS.md/CLAUDE.md rules.",
     "Dashboard URL is optional for normal production use; pass `--dashboard-url` only for staging/custom dashboards or forced re-pairing.",
     "Manual collector path: `install`, `login`, `start [--ticket <id>] [--topic <label>] [--intent <intent>] [--phase <phase>]`, `sync`, `status`, `agent-rules`.",
-    "Maintainer release path: merge to main, publish to `next` with `cockpit release`, canary Windows plus Apple Silicon, then deliberately promote that exact version to `latest`.",
+    "Maintainer release path: merge to main, then run `cockpit release --dry-run` and `cockpit release --tag latest` from a clean main checkout; a latest publish raises the fleet floor.",
   ].join("\n");
 }
 

package/dist/tower-client.js

@@ -122,11 +122,17 @@ export async function towerJsonRequest(options) {
     }
     return { ok: true, httpStatus: result.response.status, body };
 }
+const UNREACHABLE_PREFIX = "Tower could not be reached (";
 /** One plain sentence per reason, so no caller has to invent its own wording. */
 export function towerFailureDetail(reason, detail) {
     switch (reason) {
         case "gateway_unreachable":
-            return `Tower could not be reached (${detail}).`;
+            // Idempotent (BLI-10431): `towerRequest` already words its failure with
+            // this function, and seven callers word it again, which printed
+            // "Tower could not be reached (Tower could not be reached (fetch failed).)."
+            if (detail.startsWith(UNREACHABLE_PREFIX))
+                return detail;
+            return `${UNREACHABLE_PREFIX}${detail}).`;
         case "turn_timed_out":
             return "Tower did not finish in time, so the answer is incomplete. Ask again.";
         case "http_error":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.133",
+  "version": "0.2.137",
   "private": false,
   "type": "module",
   "bin": {
@@ -24,11 +24,11 @@
     "pretypecheck": "node ../../scripts/build-workspace-dep.mjs @bli-cockpit/cli",
     "typecheck": "node -e \"await import('./dist/commands/public-root.js')\"",
     "pretest": "node ../../scripts/build-workspace-dep.mjs @bli-cockpit/cli",
-    "test": "node dist/cli.js --help && node ../../scripts/assert-public-cli-routing.mjs && node ../../scripts/assert-public-cli-verb-help.mjs && node ../../scripts/assert-public-cli-runtime-files.mjs && node ../../scripts/assert-public-cli-exit-contract.mjs && node ../../scripts/assert-public-cli-no-fleet-posts.mjs && node ../../scripts/assert-public-package-pack.mjs --workspace=@bli-cockpit/cli"
+    "test": "node dist/cli.js --help && node ../../scripts/assert-public-cli-routing.mjs && node ../../scripts/assert-public-cli-verb-help.mjs && node ../../scripts/assert-public-cli-surface-doors.mjs && node ../../scripts/assert-public-cli-runtime-files.mjs && node ../../scripts/assert-public-cli-exit-contract.mjs && node ../../scripts/assert-public-cli-no-fleet-posts.mjs && node ../../scripts/assert-public-package-pack.mjs --workspace=@bli-cockpit/cli"
   },
   "dependencies": {
     "@bli-cockpit/memory-mcp": "0.1.35",
-    "@bli-cockpit/mcp": "0.1.59",
+    "@bli-cockpit/mcp": "0.1.63",
     "@bli-cockpit/telemetry-core": "0.1.48"
   }
 }