@bli-cockpit/cli 0.2.222 → 0.2.236

package/dist/commands/doctor-pipeline.js

@@ -5,7 +5,7 @@ import { retentionOptionsFromEnv } from "../disk-retention.js";
 import { readStagingGate, stagingGateLimitsFromEnv } from "../staging-gate.js";
 import { readDiskFootprint } from "../disk-usage.js";
 import { runEvidenceRedelivery } from "../evidence-redelivery.js";
-import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths } from "../local-state.js";
+import { isDefaultDashboardUrl, getCollectorRuntimePaths } from "../local-state.js";
 import { runRawEvidenceLocalGc, rawEvidenceGcSummary } from "../raw-evidence-gc.js";
 import { FOOTPRINT_NEEDS_FIX_BYTES, stagingPausedWords, diskRowMessage, footprintHolder, footprintTotalBytes, mib, redeliveryLine, } from "./doctor-disk-words.js";
 import { doctorRoots } from "./doctor-access.js";
@@ -185,7 +185,7 @@ async function runSyncRepair(context) {
         const args = ["sync", "--json", "--workspace", repoRoot, ...discoveryArgs];
         if (context.command.homeDir)
             args.push("--home", context.command.homeDir);
-        if (context.command.dashboardUrl !== DEFAULT_DASHBOARD_URL) {
+        if (!isDefaultDashboardUrl(context.command.dashboardUrl)) {
             args.push("--dashboard-url", context.command.dashboardUrl);
         }
         // One line every 30 s while doctor's own sync runs; the exec has nothing

package/dist/commands/doctor-report.js

@@ -174,6 +174,7 @@ export function doctorNeedsPerson(rows, receipt) {
         "usage-telemetry": "cockpit doctor",
         "memory-registered": "cockpit doctor",
         "agent-rules": "cockpit doctor",
+        "agent-plugins": "cockpit doctor",
         "mcp-answers": "cockpit doctor",
         "memory-daemon": "cockpit doctor",
         "backfill-complete": "cockpit doctor",

package/dist/commands/doctor-update.js

@@ -1,5 +1,5 @@
 import { isSemverBelow } from "../scheduled-self-update.js";
-import { DEFAULT_DASHBOARD_URL, LOCAL_COLLECTOR_VERSION } from "../local-state.js";
+import { isDefaultDashboardUrl, LOCAL_COLLECTOR_VERSION } from "../local-state.js";
 import { createInteractiveExecRunner } from "../process-runner.js";
 import { asRecord, fail, needsFix, ok } from "./doctor-report.js";
 /**
@@ -89,7 +89,7 @@ export function reexecDoctor(command, io) {
         args.push("--max-repos", String(command.maxRepos));
     for (const root of command.collectionRoots ?? (command.repoRoot ? [command.repoRoot] : []))
         args.push("--workspace", root);
-    if (command.dashboardUrl !== DEFAULT_DASHBOARD_URL) {
+    if (!isDefaultDashboardUrl(command.dashboardUrl)) {
         args.push("--dashboard-url", command.dashboardUrl);
     }
     if (command.updateTag)

package/dist/commands/doctor.js

@@ -10,6 +10,7 @@ import { gateRow, readCollectionGate } from "./doctor-collection-lock.js";
 import { checkMcpAnswersState, fixMcpAnswersState } from "./doctor-mcp.js";
 import { budgetSpentRow, doctorRunDeadline, DOCTOR_JSON_BUDGET_SECONDS } from "./doctor-budget.js";
 import { checkMemoryDaemonState } from "./doctor-memory-daemon.js";
+import { checkAgentPluginsState, fixAgentPluginsState } from "./doctor-agent-plugins.js";
 import { checkDoctorAgentRules, fixDoctorAgentRules, checkAutostartState, checkMemoryState, fixAutostartState, fixMemoryState, } from "./doctor-registration.js";
 import { dryRunPreview, isInteractiveDoctorFix, maybeReportDoctorEvents, writeDoctorOutput, doctorNeedsPerson, finalizeDoctorRepairs, } from "./doctor-report.js";
 import { buildSetupReceipt, refreshSetupReceipt } from "./setup-receipt.js";
@@ -189,6 +190,9 @@ function doctorInvariants() {
         },
         { id: "usage-telemetry", check: context => context.deps.checkUsageTelemetry(context), fix: context => context.deps.fixUsageTelemetry(context) },
         { id: "agent-rules", check: (context) => context.deps.checkAgentRules(context), fix: (context) => context.deps.fixAgentRules(context) },
+        // BLI-18200. Right after the rules row: same family, what the two agent
+        // hosts carry. The check reads the hosts' files; only the fix starts their CLIs.
+        { id: "agent-plugins", check: (context) => context.deps.checkAgentPlugins(context), fix: (context) => context.deps.fixAgentPlugins(context) },
         // BLI-3804. Right after the registration row, because it asks the second
         // half of the same question: `memory-registered` proves the entry exists
         // and names a bin, this one proves the server behind it starts, speaks the
@@ -240,6 +244,8 @@ function defaultDoctorDeps(hooks) {
         onReceipt: hooks.onReceipt,
         checkAgentRules: checkDoctorAgentRules,
         fixAgentRules: fixDoctorAgentRules,
+        checkAgentPlugins: (context) => checkAgentPluginsState(context),
+        fixAgentPlugins: (context) => fixAgentPluginsState(context),
         latestCliVersion: latestCliVersionFromNpm,
         selfUpdate: hooks.selfUpdate,
         reexecDoctor: reexecDoctor,

package/dist/commands/drills-render.js

@@ -0,0 +1,63 @@
+/** Plain-words rendering of the drills doors for the terminal (BLI-19259). No system nouns, no dashes used as punctuation. */
+const indent = (text, prefix = "    ") => text.split("\n").map((line) => `${prefix}${line}`);
+export function drillLines(current) {
+    const lines = [`${current.framing.bossName}: ${current.framing.roundLine}${current.redrillDay ? ` (back after ${current.redrillDay} day${current.redrillDay === 1 ? "" : "s"})` : ""}`, "", current.scenario.title, current.scenario.context, ""];
+    lines.push(`The ${current.scenario.artifactKind}:`, ...indent(current.scenario.artifact));
+    if (current.scenario.logExcerpt)
+        lines.push("", "What it printed, up to the moment before it broke:", ...indent(current.scenario.logExcerpt));
+    lines.push("", current.scenario.question);
+    if (current.scenario.reconstructed)
+        lines.push("(Rebuilt from the incident write-up, so the details are close, not word for word.)");
+    return lines;
+}
+const minutes = (value) => (value === null ? "none yet" : value >= 120 ? `${(value / 60).toFixed(1)} hours` : `${Math.round(value)} minutes`);
+export function overviewLines(body) {
+    const lines = [];
+    if (body.current)
+        lines.push("You have a drill open. Answer it before you see the cause:", "", ...drillLines(body.current), "", "Answer with: echo \"what you think\" | cockpit drills answer --confidence <1-5>", "");
+    else if (body.queue.redrillsDue > 0)
+        lines.push(`${body.queue.redrillsDue} drill${body.queue.redrillsDue === 1 ? "" : "s"} you were sure about ${body.queue.redrillsDue === 1 ? "is" : "are"} due for another look. Run: cockpit drills start`, "");
+    else if (body.queue.newLeft > 0)
+        lines.push(`${body.queue.newLeft} new drill${body.queue.newLeft === 1 ? "" : "s"} waiting. Run: cockpit drills start`, "");
+    else
+        lines.push("You are all caught up. Nothing new is waiting.", "");
+    lines.push(`Theme: ${body.theme.label}${body.theme.chosen ? "" : " (the default; change it with `cockpit drills theme set <theme>`)"}`, "");
+    if (body.bosses.length > 0) {
+        lines.push("Bosses");
+        for (const boss of body.bosses)
+            lines.push(`  ${boss.bossName}: ${boss.progressLine}`);
+        lines.push("");
+    }
+    const { stats } = body;
+    lines.push(`You have answered ${stats.answered} and passed ${stats.passed}. ${stats.confidentMisses} wrong answer${stats.confidentMisses === 1 ? "" : "s"} you were sure about.`);
+    lines.push(stats.firstRunGreenStreak.known ? `PRs green on the first CI run, in a row: at least ${stats.firstRunGreenStreak.value}.` : (stats.firstRunGreenStreak.note ?? ""));
+    if (stats.recovery.known && stats.recovery.value)
+        lines.push(`Recovering from a hit: last ${minutes(stats.recovery.value.lastMinutes)}, your best ${minutes(stats.recovery.value.bestMinutes)}.`);
+    if (stats.teamBeaten.known && stats.teamBeaten.value)
+        lines.push(`Across the team, ${stats.teamBeaten.value.fightsBeaten} boss fight${stats.teamBeaten.value.fightsBeaten === 1 ? "" : "s"} won, ${stats.teamBeaten.value.patternsBeaten} pattern${stats.teamBeaten.value.patternsBeaten === 1 ? "" : "s"} beaten at least once.`);
+    if (body.history.length > 0) {
+        lines.push("", "Recently");
+        for (const item of body.history.slice(0, 5))
+            lines.push(`  ${item.verdict === "pass" ? "passed" : item.verdict === "miss" ? "missed" : "unmarked"}  ${item.title}  (sure: ${item.confidence} of 5${item.hypercorrection ? ", comes back" : ""})`);
+    }
+    for (const note of body.notes)
+        lines.push("", note);
+    return lines.filter((line, index, all) => !(line === "" && all[index - 1] === ""));
+}
+export function reviewLines(body) {
+    const lines = [body.headline];
+    const section = (title, items) => {
+        if (items.length > 0)
+            lines.push("", title, ...items.map((item) => `  ${item}`));
+    };
+    if (body.hits.known && body.hits.value)
+        section("Your hits this week", body.hits.value.length === 0 ? ["None."] : body.hits.value.map((hit) => `A ${hit.weight} one: ${hit.patternLabel.toLowerCase()}${hit.recoveredMinutes === null ? "" : `, back to green in ${minutes(hit.recoveredMinutes)}`}.`));
+    section("Wins", body.wins);
+    section("Highs", body.highs);
+    section("Lows", body.lows);
+    section("Where you have stopped improving", body.plateaus);
+    section("What to practise", body.practise.map((item) => `${item.patternLabel}: ${item.why}`));
+    for (const note of body.notes)
+        lines.push("", note);
+    return lines;
+}

package/dist/commands/drills.js

@@ -0,0 +1,152 @@
+import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor } from "./agent-door.js";
+import { drillLines, overviewLines, reviewLines } from "./drills-render.js";
+import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
+const TAG = "[drills cli]";
+const READ_DEADLINE_MS = 30_000;
+const WRITE_DEADLINE_MS = 55_000;
+const ANSWER_MAX_CHARS = 4_000;
+export async function runDrills(command, io) {
+    let door;
+    try {
+        door = await openAgentDoor("drills", command, io);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : "this machine is not paired with Tower";
+        writeLine(io.stderr, `${TAG} refused ${JSON.stringify({ reason: "not_paired" })}`);
+        if (command.json)
+            writeLine(io.stdout, JSON.stringify({ ok: false, error: "not_paired", detail }));
+        else
+            writeLine(io.stderr, detail);
+        return 1;
+    }
+    switch (command.action) {
+        case "list": return list(door);
+        case "start": return start(door);
+        case "answer": return answer(command, door);
+        case "theme": return themeShow(door);
+        case "theme-set": return themeSet(command, door);
+        case "review": return review(door);
+    }
+}
+async function list(door) {
+    const response = await askAgentDoor(door, { path: "/api/drills", method: "GET", label: "drills list", timeoutMs: READ_DEADLINE_MS });
+    if (!response.ok)
+        return failAgentDoor(door, TAG, response.reason, response.detail);
+    const body = response.body;
+    writeLine(door.io.stderr, `${TAG} list answered ${JSON.stringify({ open: body.current !== null, bosses: body.bosses.length, history: body.history.length, new_left: body.queue.newLeft })}`);
+    if (door.json)
+        return emitAgentDoor(door, response.body);
+    for (const line of overviewLines(body))
+        writeLine(door.io.stdout, line);
+    return 0;
+}
+async function start(door) {
+    const response = await askAgentDoor(door, { path: "/api/drills/start", method: "POST", label: "drills start", timeoutMs: READ_DEADLINE_MS, body: {} });
+    if (!response.ok)
+        return failAgentDoor(door, TAG, response.reason, response.detail);
+    const body = response.body;
+    writeLine(door.io.stderr, `${TAG} start answered ${JSON.stringify({ started: body.started, reason: body.reason })}`);
+    if (door.json)
+        return emitAgentDoor(door, response.body);
+    if (!body.started || !body.current) {
+        writeLine(door.io.stdout, body.message ?? "Nothing new is waiting for you right now.");
+        return 0;
+    }
+    for (const line of drillLines(body.current))
+        writeLine(door.io.stdout, line);
+    writeLine(door.io.stdout, "");
+    writeLine(door.io.stdout, "Answer first, then see the cause:  echo \"what you think\" | cockpit drills answer --confidence <1-5>");
+    return 0;
+}
+async function openAttemptId(door) {
+    const response = await askAgentDoor(door, { path: "/api/drills", method: "GET", label: "drills list", timeoutMs: READ_DEADLINE_MS });
+    if (!response.ok)
+        return { ok: false, reason: response.reason, detail: response.detail };
+    const current = response.body.current;
+    if (!current)
+        return { ok: false, reason: "no_open_drill", detail: "No drill is open. Run `cockpit drills start` first." };
+    return { ok: true, id: current.attemptId };
+}
+async function answer(command, door) {
+    let text = command.text;
+    if (!text) {
+        if (isInteractiveStdin(door.io))
+            return failAgentDoor(door, TAG, "nothing_piped", "Pipe your answer in, e.g. `echo \"it will stop at 1,000 rows\" | cockpit drills answer --confidence 4`, or use --text. Nothing was sent.");
+        try {
+            text = (await readPipedText(door.io.stdin, { maxChars: ANSWER_MAX_CHARS, overflowMessage: `Keep your answer under ${ANSWER_MAX_CHARS} characters.` })).trim();
+        }
+        catch (error) {
+            return failAgentDoor(door, TAG, "answer_too_long", error instanceof Error ? error.message : String(error));
+        }
+    }
+    let id = command.attemptId;
+    if (!id) {
+        const open = await openAttemptId(door);
+        if (!open.ok)
+            return failAgentDoor(door, TAG, open.reason, open.detail);
+        id = open.id;
+    }
+    const response = await askAgentDoor(door, { path: "/api/drills/answer", method: "POST", label: "drills answer", timeoutMs: WRITE_DEADLINE_MS, body: { attemptId: id, answer: text, confidence: command.confidence } });
+    if (!response.ok)
+        return failAgentDoor(door, TAG, response.reason, response.detail);
+    const body = response.body;
+    writeLine(door.io.stderr, `${TAG} answered ${JSON.stringify({ verdict: body.verdict, hypercorrection: body.hypercorrection, redrills: body.redrills.length, new_win: body.newWin })}`);
+    if (door.json)
+        return emitAgentDoor(door, response.body);
+    const out = door.io.stdout;
+    writeLine(out, body.message);
+    writeLine(out, "");
+    writeLine(out, "The real cause:");
+    writeLine(out, `  ${body.reveal.realCause}`);
+    writeLine(out, "The guard that would have caught it:");
+    writeLine(out, `  ${body.reveal.guard}`);
+    if (body.reveal.aftermath)
+        writeLine(out, `What it cost: ${body.reveal.aftermath}`);
+    if (body.redrills.length > 0)
+        writeLine(out, `It comes back in ${body.redrills.map((plan) => plan.day).join(", ")} days.`);
+    return 0;
+}
+async function themeShow(door) {
+    const response = await askAgentDoor(door, { path: "/api/drills/theme", method: "GET", label: "drills theme", timeoutMs: READ_DEADLINE_MS });
+    if (!response.ok)
+        return failAgentDoor(door, TAG, response.reason, response.detail);
+    const body = response.body;
+    writeLine(door.io.stderr, `${TAG} theme answered ${JSON.stringify({ key: body.theme.key, chosen: body.theme.chosen, ready: body.ready })}`);
+    if (door.json)
+        return emitAgentDoor(door, response.body);
+    writeLine(door.io.stdout, `Your theme: ${body.theme.label}${body.theme.chosen ? "" : " (the default)"}`);
+    writeLine(door.io.stdout, "Choices:");
+    for (const choice of body.themes)
+        writeLine(door.io.stdout, `  ${choice.key}: ${choice.blurb}${choice.key === body.suggestedTheme && !body.theme.chosen ? "  (suggested)" : ""}`);
+    writeLine(door.io.stdout, "Or use your own words. Change it with: cockpit drills theme set <theme> [--play <what you play>] [--watch <what you watch>] [--train <what you train>]");
+    return 0;
+}
+async function themeSet(command, door) {
+    const response = await askAgentDoor(door, {
+        path: "/api/drills/theme",
+        method: "POST",
+        label: "drills theme set",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: { theme: command.theme, ...(command.play ? { play: command.play } : {}), ...(command.watch ? { watch: command.watch } : {}), ...(command.train ? { train: command.train } : {}) },
+    });
+    if (!response.ok)
+        return failAgentDoor(door, TAG, response.reason, response.detail);
+    const body = response.body;
+    writeLine(door.io.stderr, `${TAG} theme saved ${JSON.stringify({ key: body.theme.key, closed: body.theme.closed, preparing: body.preparing ?? false })}`);
+    if (door.json)
+        return emitAgentDoor(door, response.body);
+    writeLine(door.io.stdout, body.message ?? "Theme saved.");
+    return 0;
+}
+async function review(door) {
+    const response = await askAgentDoor(door, { path: "/api/drills/review", method: "GET", label: "drills review", timeoutMs: READ_DEADLINE_MS });
+    if (!response.ok)
+        return failAgentDoor(door, TAG, response.reason, response.detail);
+    const body = response.body;
+    writeLine(door.io.stderr, `${TAG} review answered ${JSON.stringify({ practise: body.practise.length, plateaus: body.plateaus.length })}`);
+    if (door.json)
+        return emitAgentDoor(door, response.body);
+    for (const line of reviewLines(body))
+        writeLine(door.io.stdout, line);
+    return 0;
+}

package/dist/commands/hits.js

@@ -0,0 +1,83 @@
+import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+const TAG = "[hits cli]";
+const READ_DEADLINE_MS = 55_000;
+/** The door's own query for a read: only what the person asked for, so the door's defaults stay the door's. */
+export function hitsReadQuery(command) {
+    const query = new URLSearchParams();
+    if (command.who)
+        query.set("who", command.who);
+    if (command.person)
+        query.set("person", command.person);
+    if (command.project)
+        query.set("project", command.project);
+    if (command.days !== undefined)
+        query.set("days", String(command.days));
+    if (command.top !== undefined)
+        query.set("top", String(command.top));
+    if (command.learning)
+        query.set("learning", "1");
+    if (command.patterns)
+        query.set("view", "patterns");
+    return query.toString();
+}
+export async function runHits(command, io) {
+    let door;
+    try {
+        door = await openAgentDoor("hits", command, io);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : "this machine is not paired with Tower";
+        writeLine(io.stderr, `${TAG} refused ${JSON.stringify({ reason: "not_paired" })}`);
+        if (command.json)
+            writeLine(io.stdout, JSON.stringify({ ok: false, error: "not_paired", detail }));
+        else
+            writeLine(io.stderr, detail);
+        return 1;
+    }
+    if (command.action === "approve") {
+        const answer = await askAgentDoor(door, { path: "/api/hits/patterns/approve", method: "POST", label: "hits approve", timeoutMs: READ_DEADLINE_MS,
+            body: { scope: command.scope, ...(command.version !== undefined ? { version: command.version } : {}) } });
+        if (!answer.ok)
+            return failAgentDoor(door, TAG, answer.reason, answer.detail);
+        const body = answer.body;
+        writeLine(io.stderr, `${TAG} approve answered ${JSON.stringify({ reason: body.reason, approved: body.approved ?? 0, version: body.version ?? null })}`);
+        if (command.json)
+            return emitAgentDoor(door, body, body.ok ? 0 : 1);
+        writeLine(io.stdout, body.text);
+        return body.ok ? 0 : 1;
+    }
+    if (command.action === "timeline") {
+        const path = command.weeks !== undefined ? `/api/hits/timeline?weeks=${command.weeks}` : "/api/hits/timeline";
+        const answer = await askAgentDoor(door, { path, method: "GET", label: "hits timeline", timeoutMs: READ_DEADLINE_MS });
+        if (!answer.ok)
+            return failAgentDoor(door, TAG, answer.reason, answer.detail);
+        const body = answer.body;
+        writeLine(io.stderr, `${TAG} timeline read ${JSON.stringify({ weeks: body.weeks.length, hits: body.coverage.hits, labels: body.coverage.labels, end: body.coverage.end })}`);
+        if (command.json)
+            return emitAgentDoor(door, body);
+        writeLine(io.stdout, body.text);
+        return 0;
+    }
+    if (command.action === "coach") {
+        const answer = await askAgentDoor(door, { path: "/api/hits/coach", method: "GET", label: "hits coach", timeoutMs: READ_DEADLINE_MS });
+        if (!answer.ok)
+            return failAgentDoor(door, TAG, answer.reason, answer.detail);
+        const body = answer.body;
+        writeLine(io.stderr, `${TAG} coach read ${JSON.stringify({ alerts: body.alerts.length, rows: body.coverage.rows, pages: body.coverage.pages, end: body.coverage.end })}`);
+        if (command.json)
+            return emitAgentDoor(door, body);
+        writeLine(io.stdout, body.text);
+        return 0;
+    }
+    const asked = hitsReadQuery(command);
+    const answer = await askAgentDoor(door, { path: asked ? `/api/hits?${asked}` : "/api/hits", method: "GET", label: "hits read", timeoutMs: READ_DEADLINE_MS });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    writeLine(io.stderr, `${TAG} read answered ${JSON.stringify({ who: body.who, hits: body.totals.hits, rows: body.coverage.rows, pages: body.coverage.pages, end: body.coverage.end })}`);
+    if (command.json)
+        return emitAgentDoor(door, body);
+    writeLine(io.stdout, body.text);
+    return 0;
+}

package/dist/commands/intentions.js

@@ -0,0 +1,49 @@
+import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+const TAG = "[intentions cli]";
+const DEADLINE_MS = 55_000;
+export async function runIntentions(command, io) {
+    let door;
+    try {
+        door = await openAgentDoor("intentions", command, io);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : "this machine is not paired with Tower";
+        writeLine(io.stderr, `${TAG} refused ${JSON.stringify({ reason: "not_paired" })}`);
+        if (command.json)
+            writeLine(io.stdout, JSON.stringify({ ok: false, error: "not_paired", detail }));
+        else
+            writeLine(io.stderr, detail);
+        return 1;
+    }
+    let request;
+    if (command.action === "list") {
+        const query = new URLSearchParams();
+        if (command.status)
+            query.set("status", command.status);
+        if (command.project)
+            query.set("project", command.project);
+        if (command.limit !== undefined)
+            query.set("limit", String(command.limit));
+        const asked = query.toString();
+        request = { path: asked ? `/api/intentions?${asked}` : "/api/intentions", method: "GET", label: "intentions list" };
+    }
+    else if (command.action === "show") {
+        request = { path: `/api/intentions/${encodeURIComponent(command.id)}`, method: "GET", label: "intentions show" };
+    }
+    else {
+        request = {
+            path: `/api/intentions/${encodeURIComponent(command.id)}`, method: "POST", label: `intentions ${command.action}`,
+            body: { action: command.action, ...(command.evidence ? { evidence: command.evidence } : {}), ...(command.by ? { by: command.by } : {}) },
+        };
+    }
+    const answer = await askAgentDoor(door, { ...request, timeoutMs: DEADLINE_MS });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    writeLine(io.stderr, `${TAG} ${command.action} answered ${JSON.stringify({ rows: body.intentions?.length ?? 1, ...(body.coverage ? { requested: body.coverage.requested, returned: body.coverage.returned, unique: body.coverage.unique, end: body.coverage.end } : {}) })}`);
+    if (command.json)
+        return emitAgentDoor(door, body);
+    writeLine(io.stdout, body.text ?? "");
+    return 0;
+}

package/dist/commands/local-args-docs-export.js

@@ -0,0 +1,23 @@
+/**
+ * `cockpit docs export` flag parsing (ticket 20694), split out of `local-args-tower-docs-msg.ts`,
+ * which sits at the file-size ratchet.
+ */
+import { optionalNonEmpty } from "./local-arg-values.js";
+const DOCS_EXPORT_FORMATS = ["md", "pdf", "docx", "txt"];
+/** Ticket 20694: `--format`/`--out` mean something on `export` alone, and an unknown format is refused by name. */
+export function parseDocsExportFlags(action, values) {
+    const format = optionalNonEmpty(values.flags.get("--format"))?.toLowerCase();
+    const outPath = optionalNonEmpty(values.flags.get("--out"));
+    if (action !== "export") {
+        if (format)
+            throw new Error("--format belongs to `cockpit docs export`.");
+        if (outPath)
+            throw new Error("--out belongs to `cockpit docs export`.");
+        return {};
+    }
+    const chosen = format === "markdown" ? "md" : format === "word" ? "docx" : format === "text" ? "txt" : (format ?? "md");
+    if (!DOCS_EXPORT_FORMATS.includes(chosen)) {
+        throw new Error(`docs export --format must be one of ${DOCS_EXPORT_FORMATS.join(", ")} (Word is docx), not "${format}".`);
+    }
+    return { exportFormat: chosen, ...(outPath ? { outPath } : {}) };
+}

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

@@ -301,6 +301,14 @@ export function parseTeamArgs(args) {
         }
         return { kind: "team", action: `github-login-${operation}`, personRef, githubLogin, ...common };
     }
+    if (verb === "timezone") {
+        const [operation, personRef, zone, ...extra] = rest;
+        if (!["set", "list"].includes(operation ?? "") || extra.length ||
+            (operation === "list" ? personRef !== undefined : !personRef || !zone)) {
+            throw new Error("team timezone takes set <person> <iana-zone> (or the word unknown), or list.");
+        }
+        return { kind: "team", action: operation === "set" ? "timezone-set" : "timezone-list", ...(personRef ? { personRef } : {}), ...(zone ? { zone } : {}), ...common };
+    }
     if (verb === "device") {
         return parseTeamDeviceArgs(rest, values.flags, common);
     }

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

@@ -0,0 +1,90 @@
+/**
+ * `cockpit brain ladder` argument parsing (BLI-19250): Edward's call ladder.
+ *
+ *   cockpit brain ladder show [--json]
+ *   cockpit brain ladder promote <class> [--anyway] [--note <text>] [--json]
+ *   cockpit brain ladder demote <class> [--note <text>] [--json]
+ *   cockpit brain ladder predict "<question>" [--context <text>] [--asker <label>] [--source-kind <k>] [--source-ref <ref>] [--json]
+ *   cockpit brain ladder answer "<what he answered>" (--prediction <uuid> | --source-kind <k> --source-ref <ref>) [--json]
+ *
+ * The class names are checked by the door against the closed list (`lib/edward-predictor/classes.ts`), not copied here.
+ */
+import { optionalNonEmpty, optionalUrl, parseNamedArgs } from "./local-arg-values.js";
+const VERBS = ["show", "promote", "demote", "predict", "answer"];
+const SOURCE_KIND = /^[a-z][a-z0-9_]{0,31}$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export function parseBrainLadderArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: ["--home", "--dashboard-url", "--json", "--anyway", "--note", "--context", "--asker", "--source-kind", "--source-ref", "--prediction"],
+        valueFlags: ["--home", "--dashboard-url", "--note", "--context", "--asker", "--source-kind", "--source-ref", "--prediction"],
+    });
+    const [ladderWord, verb, ...rest] = values.positionals;
+    if (ladderWord !== "ladder" || !VERBS.includes(verb ?? "")) {
+        throw new Error(`brain ladder takes one verb: ${VERBS.join(", ")}. Example: \`cockpit brain ladder show\`.`);
+    }
+    const shape = { verb: verb };
+    const flag = (name) => optionalNonEmpty(values.flags.get(name))?.trim();
+    const note = flag("--note");
+    if (note && note.length > 300)
+        throw new Error("--note is at most 300 characters.");
+    const sourceKind = flag("--source-kind");
+    if (sourceKind && !SOURCE_KIND.test(sourceKind))
+        throw new Error("--source-kind wants a lowercase label like approval_card.");
+    const prediction = flag("--prediction");
+    if (prediction && !UUID.test(prediction))
+        throw new Error("--prediction wants a prediction id (a UUID).");
+    const only = (allowed) => {
+        for (const name of ["--anyway", "--note", "--context", "--asker", "--source-kind", "--source-ref", "--prediction"]) {
+            const given = values.booleans.has(name) || values.flags.has(name);
+            if (given && !allowed.includes(name))
+                throw new Error(`${name} does not belong to brain ladder ${shape.verb}.`);
+        }
+    };
+    switch (shape.verb) {
+        case "show":
+            if (rest.length)
+                throw new Error("brain ladder show takes no arguments.");
+            only([]);
+            break;
+        case "promote":
+        case "demote":
+            if (rest.length !== 1)
+                throw new Error(`brain ladder ${shape.verb} takes one class name. Example: \`cockpit brain ladder ${shape.verb} merge\`.`);
+            only(shape.verb === "promote" ? ["--anyway", "--note"] : ["--note"]);
+            shape.className = rest[0];
+            if (values.booleans.has("--anyway"))
+                shape.anyway = true;
+            if (note)
+                shape.note = note;
+            break;
+        case "predict":
+            if (rest.length !== 1)
+                throw new Error('brain ladder predict takes the question in quotes. Example: `cockpit brain ladder predict "Merge #1820 now?"`.');
+            only(["--context", "--asker", "--source-kind", "--source-ref"]);
+            shape.text = rest[0];
+            if (flag("--context"))
+                shape.context = flag("--context");
+            if (flag("--asker"))
+                shape.asker = flag("--asker");
+            if (sourceKind)
+                shape.sourceKind = sourceKind;
+            if (flag("--source-ref"))
+                shape.sourceRef = flag("--source-ref");
+            break;
+        case "answer":
+            if (rest.length !== 1)
+                throw new Error('brain ladder answer takes what he answered, in quotes. Example: `cockpit brain ladder answer "Yes, merge it" --prediction <id>`.');
+            only(["--prediction", "--source-kind", "--source-ref"]);
+            shape.text = rest[0];
+            if (prediction)
+                shape.predictionId = prediction;
+            if (sourceKind)
+                shape.sourceKind = sourceKind;
+            if (flag("--source-ref"))
+                shape.sourceRef = flag("--source-ref");
+            if (!shape.predictionId && !(shape.sourceKind && shape.sourceRef))
+                throw new Error("brain ladder answer needs --prediction <id>, or --source-kind and --source-ref.");
+            break;
+    }
+    return { ladder: shape, dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")), homeDir: flag("--home"), json: values.booleans.has("--json") };
+}

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

@@ -9,16 +9,26 @@
  */
 import { LOG_PROJECT_PATTERN } from "@bli-cockpit/telemetry-core/log-digest";
 import { optionalNonEmpty, optionalUrl, parseNamedArgs } from "./local-arg-values.js";
+import { parseBrainLadderArgs } from "./local-args-tower-brain-ladder.js";
 /** The statuses the queue's door accepts for `--show`; the migration's CHECK constraint is the other copy. */
 export const BRAIN_SHOW_STATUSES = ["open", "running", "needs_human", "fixed", "not_actionable", "cleared"];
 export function parseBrainArgs(args) {
+    // BLI-19250: `brain ladder ...` is Edward's call ladder; it has its own verbs and flags.
+    // The census spells these `brain ladder-show` (one action word), so that spelling is accepted beside `brain ladder show`.
+    const first = args.find((arg) => !arg.startsWith("--"));
+    if (first === "ladder" || /^ladder-[a-z]+$/.test(first ?? "")) {
+        const hyphen = first !== "ladder";
+        const split = hyphen ? args.flatMap((arg) => (arg === first ? ["ladder", first.slice("ladder-".length)] : [arg])) : args;
+        const parsed = parseBrainLadderArgs(split);
+        return { kind: "brain", action: `ladder-${parsed.ladder.verb}`, ladder: parsed.ladder, dashboardUrl: parsed.dashboardUrl, homeDir: parsed.homeDir, json: parsed.json };
+    }
     const values = parseNamedArgs(args, {
         allowedFlags: ["--project", "--show", "--home", "--dashboard-url", "--json", "--all-needs-human", "--reason"],
         valueFlags: ["--project", "--show", "--home", "--dashboard-url", "--reason"],
     });
     const action = values.positionals[0];
     if ((action !== "status" && action !== "retry") || (action === "status" && values.positionals.length > 1)) {
-        throw new Error("brain takes one verb: `status` or `retry`. Example: `cockpit brain status` or `cockpit brain status --project pearl-portal`.");
+        throw new Error("brain takes one verb: `status`, `retry` or `ladder`. Example: `cockpit brain status` or `cockpit brain status --project pearl-portal`.");
     }
     const project = optionalNonEmpty(values.flags.get("--project"));
     if (project && !LOG_PROJECT_PATTERN.test(project))

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

@@ -7,13 +7,14 @@
  * 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", "delete", "link", "sync-status"]);
+import { parseDocsExportFlags } from "./local-args-docs-export.js";
+const DOCS_ACTIONS = new Set(["list", "tree", "read", "create", "update", "delete", "link", "sync-status", "export"]);
 // BLI-10450: `read` moved to its own branch in `parseDocsDocumentReference` —
 // it takes SEVERAL references now, so it no longer shares the "exactly one"
 // rule `update`/`link` still enforce. BLI‑10555: `delete` takes several too
 // (the same door, called once per ref), so it joined `read`'s branch rather
 // than this set.
-const DOCS_ACTIONS_NEEDING_A_DOC = new Set(["update", "link"]);
+const DOCS_ACTIONS_NEEDING_A_DOC = new Set(["update", "link", "export"]);
 export function parseDocsArgs(args) {
     const values = parseNamedArgs(args, {
         allowedFlags: [
@@ -33,6 +34,8 @@ export function parseDocsArgs(args) {
             "--bodies",
             "--section",
             "--offset",
+            "--format",
+            "--out",
             "--json",
         ],
         valueFlags: [
@@ -46,6 +49,8 @@ export function parseDocsArgs(args) {
             "--limit",
             "--section",
             "--offset",
+            "--format",
+            "--out",
         ],
     });
     const { action, rest } = parseDocsAction(values.positionals);
@@ -111,7 +116,7 @@ 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, update, delete, link, or sync-status.`);
+        throw new Error(`Unknown docs command: ${first}. Try list, tree, read, create, update, delete, link, sync-status, or export.`);
     }
     return { action, rest: positionals.slice(first === undefined ? 0 : 1) };
 }
@@ -234,6 +239,7 @@ function buildDocsCommand(values, action, docRef, docRefs, visibility, clearPare
         ...(offset === undefined ? {} : { offset }),
         ...(link.notionPage ? { notionPage: link.notionPage } : {}),
         ...(link.clearLink ? { clearLink: true } : {}),
+        ...parseDocsExportFlags(action, values),
         json: values.booleans.has("--json"),
     };
 }