@bli-cockpit/cli 0.2.119 → 0.2.121

package/dist/commands/onboard-setup.js

@@ -57,6 +57,13 @@ export async function pairForOnboarding(command, input, installEvents, io) {
         repoRoot: input.primaryRoot,
         branch: command.branch,
     });
+    if (await reuseInstalledOnboardSession(command, input, installedStatus, installEvents, io)) {
+        return null;
+    }
+    await logOutMismatchedOnboardSession(command, installedStatus, io);
+    return await pairOnboardDevice(command, input, installEvents, io);
+}
+async function reuseInstalledOnboardSession(command, input, installedStatus, installEvents, io) {
     const installedSession = await readOnboardSessionReuseCandidate(command.homeDir);
     const canReuseInstalledSession = canReuseOnboardSession(installedSession, input.claimedOwnerEmail, command.dashboardUrl);
     if (installedStatus.session_state === "valid" && canReuseInstalledSession) {
@@ -65,14 +72,19 @@ export async function pairForOnboarding(command, input, installEvents, io) {
         if (!command.json) {
             writeLine(io.stdout, "2/5 Existing valid device session found; pairing skipped.");
         }
-        return null;
+        return true;
     }
+    return false;
+}
+async function logOutMismatchedOnboardSession(command, installedStatus, io) {
     if (installedStatus.session_state === "valid") {
         await logoutLocalCollector({ homeDir: command.homeDir });
         if (!command.json) {
             writeLine(io.stdout, "2/5 Existing valid device session does not match requested owner or dashboard; pairing again.");
         }
     }
+}
+async function pairOnboardDevice(command, input, installEvents, io) {
     // BLI-3731: one sign-in first. The link both signs the browser in and
     // finishes the pairing, so nobody reads a second email. Every other arm
     // below is the fallback, and it runs unchanged when this one cannot finish.
@@ -89,6 +101,9 @@ export async function pairForOnboarding(command, input, installEvents, io) {
             return linked;
         }
     }
+    return await pairOnboardDeviceWithAuthFallback(command, input, installEvents, io);
+}
+async function pairOnboardDeviceWithAuthFallback(command, input, installEvents, io) {
     const authResult = await requestPairingAccessTokenDetailed({
         dashboardUrl: command.dashboardUrl,
         email: input.claimedOwnerEmail,

package/dist/commands/ops-sections.js

@@ -0,0 +1,89 @@
+import { asRecord, callTower } from "./tower-command.js";
+import { writeLine } from "./cli-io.js";
+export function turnAggregateSection(payload) {
+    const section = payload.turns ?? null;
+    return { section, reason: section ? "ok" : "turns_section_absent" };
+}
+export async function readToolRouterBoard(io, tower) {
+    const result = await callTower(tower, { path: "/api/ops/tool-router", label: "ops-tool-router" });
+    if (!result.ok) {
+        writeLine(io.stderr, `[ops cli] tool router not read ${JSON.stringify({ reason: result.reason, http_status: result.httpStatus ?? null })}`);
+        return { board: null, reason: result.reason };
+    }
+    const board = asRecord(result.body).board ?? null;
+    return { board, reason: board ? "ok" : "tool_router_section_absent" };
+}
+export function turnAggregateLine(section) {
+    return `TURNS  ${section.turns ?? 0} turns / ${section.windowDays ?? 30}d · wall p50 ${section.wallTimeMs?.p50 ?? "n/a"}ms · p95 ${section.wallTimeMs?.p95 ?? "n/a"}ms · ${section.completion ?? "unknown"}`;
+}
+export function toolRouterLine(board) {
+    const rate = board.agreementRate === null || board.agreementRate === undefined
+        ? "n/a"
+        : `${(board.agreementRate * 100).toFixed(1)}%`;
+    return `TOOL ROUTER  ${board.turnsRouted ?? 0} routed · agreement ${rate} · p50 ${board.p50LatencyMs ?? "n/a"}ms${board.capped ? " · capped" : ""}${board.readError ? ` · ${board.readError}` : ""}`;
+}
+/**
+ * The adoption gauge, read through its own door.
+ *
+ * Never fails the board: a `cockpit ops --memory` whose memory half is
+ * unreadable still prints the pipelines, the fleet and the coverage, and says
+ * in one line which half is missing and why. The status board's exit code is
+ * about collection health, and adoption is not that.
+ */
+export async function readMemoryUsage(command, io, tower) {
+    const params = new URLSearchParams();
+    if (command.memoryDays !== undefined)
+        params.set("days", String(command.memoryDays));
+    const query = params.toString();
+    const result = await callTower(tower, {
+        path: `/api/ops/memory-usage${query ? `?${query}` : ""}`,
+        label: "ops-memory-usage",
+    });
+    if (!result.ok) {
+        writeLine(io.stderr, `[ops cli] memory usage not read ${JSON.stringify({
+            reason: result.reason,
+            http_status: result.httpStatus ?? null,
+        })}`);
+        return { section: null, hooks: null, experience: null, reason: result.reason };
+    }
+    const body = asRecord(result.body);
+    // BLI-3788: the hook counts ride the same answer, and their absence is a
+    // fact about the SERVER's version rather than about this fleet — an older
+    // dashboard sends no `hooks` key, and printing nothing is right there.
+    if (!body.memory)
+        return {
+            section: null,
+            hooks: body.hooks ?? null,
+            experience: body.experience ?? null,
+            reason: "memory_section_absent",
+        };
+    return {
+        section: body.memory,
+        hooks: body.hooks ?? null,
+        experience: body.experience ?? null,
+        reason: "ok",
+    };
+}
+/**
+ * The per-model board, read through its own door (BLI-3912).
+ *
+ * Same posture as the adoption gauge next door: it never fails the status
+ * board, and when it cannot be read the reason is printed where the section
+ * would have been. The LINES come from the server, so a terminal and the
+ * dashboard cannot disagree about what a model cost today.
+ */
+export async function readModelBoardLines(io, tower) {
+    const result = await callTower(tower, { path: "/api/ops/models", label: "ops-models" });
+    if (!result.ok) {
+        writeLine(io.stderr, `[ops cli] model board not read ${JSON.stringify({
+            reason: result.reason,
+            http_status: result.httpStatus ?? null,
+        })}`);
+        return { lines: [], board: null, reason: result.reason };
+    }
+    const body = asRecord(result.body);
+    if (!body.lines || body.lines.length === 0) {
+        return { lines: [], board: body.board ?? null, reason: "models_section_absent" };
+    }
+    return { lines: body.lines, board: body.board ?? null, reason: "ok" };
+}

package/dist/commands/ops.js

@@ -35,6 +35,7 @@
 import { colorEnabled, dim, writeLine } from "./cli-io.js";
 import { renderOpsStatus } from "./ops-render.js";
 import { renderMemoryHooks, renderMemoryUsage, } from "./ops-render-memory.js";
+import { readMemoryUsage, readModelBoardLines, readToolRouterBoard, toolRouterLine, turnAggregateLine, turnAggregateSection, } from "./ops-sections.js";
 import { asRecord, callTower, openTower, writeCommandFailure } from "./tower-command.js";
 /**
  * A whole compile, plus a little. `maxDuration` on `/api/ops/recompile` is 800
@@ -51,16 +52,7 @@ export async function runOps(command, io) {
         : runOpsRecompile(command, io, tower);
 }
 async function runOpsStatus(command, io, tower) {
-    const params = new URLSearchParams();
-    if (command.job)
-        params.set("job", command.job);
-    if (command.skips)
-        params.set("skips", "1");
-    const query = params.toString();
-    const result = await callTower(tower, {
-        path: `/api/ops/status${query ? `?${query}` : ""}`,
-        label: "ops-status",
-    });
+    const result = await readOpsStatus(command, tower);
     if (!result.ok) {
         writeLine(io.stderr, `[ops cli] status not read ${JSON.stringify({
             reason: result.reason,
@@ -82,72 +74,122 @@ async function runOpsStatus(command, io, tower) {
     // different question from "is the pipeline healthy", and a card shelf that
     // could not be read is not a collection outage.
     const models = command.models ? await readModelBoardLines(io, tower) : null;
+    const turns = command.turns ? turnAggregateSection(payload) : null;
+    const toolRouter = command.toolRouter ? await readToolRouterBoard(io, tower) : null;
+    const unhealthy = rows.filter(isUnhealthyPipeline);
+    writeOpsStatusOutput(command, io, payload, memory, models, turns, toolRouter);
+    writeOpsStatusReadLog(command, io, payload, rows, unhealthy, memory, models, turns, toolRouter);
+    return unhealthy.length > 0 ? 1 : 0;
+}
+async function readOpsStatus(command, tower) {
+    const params = new URLSearchParams();
+    if (command.job)
+        params.set("job", command.job);
+    if (command.skips)
+        params.set("skips", "1");
+    // The turn aggregates ride on the same status read (BLI-10136): one round
+    // trip, one board, never a second read of the same door for one section.
+    if (command.turns)
+        params.set("turns", "1");
+    const query = params.toString();
+    return callTower(tower, {
+        path: `/api/ops/status${query ? `?${query}` : ""}`,
+        label: "ops-status",
+    });
+}
+function isUnhealthyPipeline(row) {
     // BLI-3723: `failing` joins the list. An older CLI that has never heard of it
     // simply does not count it — which is why the server keeps the sentence in
     // `detail`, so an un-upgraded terminal still PRINTS the outage even when it
     // exits 0 over it.
-    const unhealthy = rows.filter((row) => row.verdict === "stale" ||
+    return (row.verdict === "stale" ||
         row.verdict === "never_produced" ||
         row.verdict === "unreadable" ||
         row.verdict === "failing" ||
         // BLI-3762: a job that ran and wrote less than it owed is not healthy.
         row.verdict === "degraded");
+}
+function writeOpsStatusOutput(command, io, payload, memory, models, turns, toolRouter) {
     if (command.json) {
-        writeLine(io.stdout, JSON.stringify({
-            ...payload,
-            ...(memory
-                ? { memory: memory.section, hooks: memory.hooks, experience: memory.experience }
-                : {}),
-            ...(models ? { models: models.board, modelsReason: models.reason } : {}),
-        }));
+        writeJsonOpsStatus(io, payload, memory, models, turns, toolRouter);
+        return;
     }
-    else {
-        const styled = colorEnabled(io);
-        for (const line of renderOpsStatus(payload, (text) => dim(text, styled), {
-            alwaysShowBuckets: command.coverage === true,
-        })) {
+    writeHumanOpsStatus(command, io, payload, memory, models, turns, toolRouter);
+}
+function writeJsonOpsStatus(io, payload, memory, models, turns, toolRouter) {
+    writeLine(io.stdout, JSON.stringify({
+        ...payload,
+        ...(memory
+            ? { memory: memory.section, hooks: memory.hooks, experience: memory.experience }
+            : {}),
+        ...(models ? { models: models.board, modelsReason: models.reason } : {}),
+        ...(turns ? { turns: turns.section, turnsReason: turns.reason } : {}),
+        ...(toolRouter ? { toolRouter: toolRouter.board, toolRouterReason: toolRouter.reason } : {}),
+    }));
+}
+function writeHumanOpsStatus(command, io, payload, memory, models, turns, toolRouter) {
+    const styled = colorEnabled(io);
+    for (const line of renderOpsStatus(payload, (text) => dim(text, styled), {
+        alwaysShowBuckets: command.coverage === true,
+    })) {
+        writeLine(io.stdout, line);
+    }
+    if (memory?.section) {
+        for (const line of renderMemoryUsage(memory.section, (text) => dim(text, styled))) {
             writeLine(io.stdout, line);
         }
-        if (memory?.section) {
-            for (const line of renderMemoryUsage(memory.section, (text) => dim(text, styled))) {
-                writeLine(io.stdout, line);
-            }
+    }
+    // BLI-3788. Printed whenever the door sent it, including when the usage
+    // half could not be read: "are the recalls arriving" and "is anybody
+    // saving" are two questions, and one being unreadable does not silence
+    // the other.
+    if (memory?.hooks) {
+        for (const line of renderMemoryHooks(memory.hooks, (text) => dim(text, styled))) {
+            writeLine(io.stdout, line);
         }
-        // BLI-3788. Printed whenever the door sent it, including when the usage
-        // half could not be read: "are the recalls arriving" and "is anybody
-        // saving" are two questions, and one being unreadable does not silence
-        // the other.
-        if (memory?.hooks) {
-            for (const line of renderMemoryHooks(memory.hooks, (text) => dim(text, styled))) {
+    }
+    if (memory?.experience) {
+        writeLine(io.stdout, `\nEXPERIENCE  ${memory.experience.summary}`);
+        for (const line of memory.experience.lines)
+            writeLine(io.stdout, `  ${line}`);
+    }
+    if (models) {
+        writeLine(io.stdout, "");
+        if (models.lines.length > 0) {
+            for (const line of models.lines)
                 writeLine(io.stdout, line);
-            }
-        }
-        if (memory?.experience) {
-            writeLine(io.stdout, `\nEXPERIENCE  ${memory.experience.summary}`);
-            for (const line of memory.experience.lines)
-                writeLine(io.stdout, `  ${line}`);
-        }
-        if (models) {
-            writeLine(io.stdout, "");
-            if (models.lines.length > 0) {
-                for (const line of models.lines)
-                    writeLine(io.stdout, line);
-            }
-            else {
-                // Never a silent gap where a section was asked for.
-                writeLine(io.stdout, `MODELS  not read (${models.reason})`);
-            }
         }
-        if (memory && !memory.section) {
-            // Never a silent gap where a section was asked for: the reason the gauge
-            // could not be read is printed where the gauge would have been.
-            writeLine(io.stdout, "");
-            writeLine(io.stdout, `MEMORY  not read (${memory.reason})`);
+        else {
+            // Never a silent gap where a section was asked for.
+            writeLine(io.stdout, `MODELS  not read (${models.reason})`);
         }
     }
+    if (turns) {
+        writeLine(io.stdout, "");
+        writeLine(io.stdout, turns.section ? turnAggregateLine(turns.section) : `TURNS  not read (${turns.reason})`);
+    }
+    if (toolRouter) {
+        writeLine(io.stdout, "");
+        writeLine(io.stdout, toolRouter.board
+            ? toolRouterLine(toolRouter.board)
+            : `TOOL ROUTER  not read (${toolRouter.reason})`);
+    }
+    if (memory && !memory.section) {
+        // Never a silent gap where a section was asked for: the reason the gauge
+        // could not be read is printed where the gauge would have been.
+        writeLine(io.stdout, "");
+        writeLine(io.stdout, `MEMORY  not read (${memory.reason})`);
+    }
+}
+function writeOpsStatusReadLog(command, io, payload, rows, unhealthy, memory, models, turns, toolRouter) {
     // Both branches log — an all-green board that says nothing cannot answer
     // "did anybody look today?".
     writeLine(io.stderr, `[ops cli] status read ${JSON.stringify({
+        ...createOpsStatusReadLog(command, payload, rows, unhealthy, memory, models, turns, toolRouter),
+    })}`);
+}
+function createOpsStatusReadLog(command, payload, rows, unhealthy, memory, models, turns, toolRouter) {
+    return {
         job: command.job ?? "all",
         pipelines: rows.length,
         unhealthy: unhealthy.length,
@@ -187,63 +229,13 @@ async function runOpsStatus(command, io, tower) {
         models_reason: models?.reason ?? null,
         models_counted: models?.board?.rows?.length ?? null,
         models_cost_today_usd: models?.board?.total_cost_today_usd ?? null,
-    })}`);
-    return unhealthy.length > 0 ? 1 : 0;
-}
-/**
- * The adoption gauge, read through its own door.
- *
- * Never fails the board: a `cockpit ops --memory` whose memory half is
- * unreadable still prints the pipelines, the fleet and the coverage, and says
- * in one line which half is missing and why. The status board's exit code is
- * about collection health, and adoption is not that.
- */
-async function readMemoryUsage(command, io, tower) {
-    const params = new URLSearchParams();
-    if (command.memoryDays !== undefined)
-        params.set("days", String(command.memoryDays));
-    const query = params.toString();
-    const result = await callTower(tower, {
-        path: `/api/ops/memory-usage${query ? `?${query}` : ""}`,
-        label: "ops-memory-usage",
-    });
-    if (!result.ok) {
-        writeLine(io.stderr, `[ops cli] memory usage not read ${JSON.stringify({
-            reason: result.reason,
-            http_status: result.httpStatus ?? null,
-        })}`);
-        return { section: null, hooks: null, experience: null, reason: result.reason };
-    }
-    const body = asRecord(result.body);
-    // BLI-3788: the hook counts ride the same answer, and their absence is a
-    // fact about the SERVER's version rather than about this fleet — an older
-    // dashboard sends no `hooks` key, and printing nothing is right there.
-    if (!body.memory)
-        return { section: null, hooks: body.hooks ?? null, experience: body.experience ?? null, reason: "memory_section_absent" };
-    return { section: body.memory, hooks: body.hooks ?? null, experience: body.experience ?? null, reason: "ok" };
-}
-/**
- * The per-model board, read through its own door (BLI-3912).
- *
- * Same posture as the adoption gauge next door: it never fails the status
- * board, and when it cannot be read the reason is printed where the section
- * would have been. The LINES come from the server, so a terminal and the
- * dashboard cannot disagree about what a model cost today.
- */
-async function readModelBoardLines(io, tower) {
-    const result = await callTower(tower, { path: "/api/ops/models", label: "ops-models" });
-    if (!result.ok) {
-        writeLine(io.stderr, `[ops cli] model board not read ${JSON.stringify({
-            reason: result.reason,
-            http_status: result.httpStatus ?? null,
-        })}`);
-        return { lines: [], board: null, reason: result.reason };
-    }
-    const body = asRecord(result.body);
-    if (!body.lines || body.lines.length === 0) {
-        return { lines: [], board: body.board ?? null, reason: "models_section_absent" };
-    }
-    return { lines: body.lines, board: body.board ?? null, reason: "ok" };
+        turns_asked: Boolean(command.turns),
+        turns_reason: turns?.reason ?? null,
+        turns_count: turns?.section?.turns ?? null,
+        tool_router_asked: Boolean(command.toolRouter),
+        tool_router_reason: toolRouter?.reason ?? null,
+        tool_router_turns: toolRouter?.board?.turnsRouted ?? null,
+    };
 }
 async function runOpsRecompile(command, io, tower) {
     const person = command.person ?? "";
@@ -278,11 +270,23 @@ async function runOpsRecompile(command, io, tower) {
         })}`);
         return writeCommandFailure(io, command.json, failure);
     }
-    const body = asRecord(result.body);
+    return writeOpsRecompileResult(command, io, asRecord(result.body), person);
+}
+function writeOpsRecompileResult(command, io, body, person) {
     const status = typeof body["status"] === "string" ? body["status"] : "compiled";
     const displayName = typeof body["displayName"] === "string" ? body["displayName"] : person;
     const pageId = typeof body["pageId"] === "string" ? body["pageId"] : null;
     const isNowLive = body["isNowLive"] === true;
+    writeRecompileOutput(command, io, body, status, displayName, pageId, isNowLive);
+    writeLine(io.stderr, `[ops cli] recompile done ${JSON.stringify({
+        status,
+        page_id: pageId,
+        is_now_live: status === "compiled" ? isNowLive : null,
+        dry_run: command.dryRun === true,
+    })}`);
+    return 0;
+}
+function writeRecompileOutput(command, io, body, status, displayName, pageId, isNowLive) {
     if (command.json) {
         writeLine(io.stdout, JSON.stringify(body));
     }
@@ -301,11 +305,4 @@ async function runOpsRecompile(command, io, tower) {
             : "It is NOT the page being served: a scheduled compile is stamped for a later delivery window, " +
                 "so that one still wins. Nothing was lost — this is a new version alongside it.");
     }
-    writeLine(io.stderr, `[ops cli] recompile done ${JSON.stringify({
-        status,
-        page_id: pageId,
-        is_now_live: status === "compiled" ? isNowLive : null,
-        dry_run: command.dryRun === true,
-    })}`);
-    return 0;
 }

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

package/dist/commands/scout.js

@@ -25,9 +25,20 @@ export async function runScout(command, io) {
     const session = await loadPairedSession("scout", command.homeDir);
     const dashboardUrl = command.dashboardUrl ?? session.dashboard_url;
     const log = (line) => writeLine(io.stderr, line);
+    const read = await readScoutBoard(command, io, session, dashboardUrl, log);
+    if (!read.ok) {
+        writeFailure(command, io, read);
+        return 1;
+    }
+    if (command.action === "board") {
+        return writeScoutBoard(command, io, read.body);
+    }
+    return runScoutAction(command, command.action, io, read.body, session, dashboardUrl, log);
+}
+async function readScoutBoard(command, io, session, dashboardUrl, log) {
     // The board is read first even for an action: the id prefix is resolved
     // against it locally, and a refused action still leaves a readable board.
-    const read = await towerJsonRequest({
+    return towerJsonRequest({
         dashboardUrl,
         path: command.days ? `/api/cockpit/scout?days=${command.days}` : "/api/cockpit/scout",
         method: "GET",
@@ -37,53 +48,41 @@ export async function runScout(command, io) {
         timeoutMs: READ_DEADLINE_MS,
         log,
     });
-    if (!read.ok) {
-        writeFailure(command, io, read);
-        return 1;
-    }
-    const payload = read.body;
+}
+function writeScoutBoard(command, io, payload) {
     const board = payload.board ?? {};
-    const lines = payload.lines ?? {};
-    if (command.action === "board") {
-        if (command.json) {
-            writeLine(io.stdout, JSON.stringify({ ok: true, audience: payload.audience ?? null, windowDays: payload.windowDays ?? board.windowDays ?? null, board, lines }));
-        }
-        else {
-            for (const line of renderScoutBoard(payload, colorEnabled(io)))
-                writeLine(io.stdout, line);
-        }
-        writeLine(io.stderr, `[scout cli] board read ${JSON.stringify({
+    if (command.json) {
+        writeLine(io.stdout, JSON.stringify({
+            ok: true,
             audience: payload.audience ?? null,
-            window_days: payload.windowDays ?? board.windowDays ?? null,
-            experiments: board.experiments?.length ?? 0,
-            settled: board.settled?.length ?? 0,
-            signals: board.signals?.length ?? 0,
-            truncated: truncationLines(board).length > 0,
-        })}`);
-        return 0;
+            windowDays: payload.windowDays ?? board.windowDays ?? null,
+            board,
+            lines: payload.lines ?? {},
+        }));
     }
+    else {
+        for (const line of renderScoutBoard(payload, colorEnabled(io)))
+            writeLine(io.stdout, line);
+    }
+    writeLine(io.stderr, `[scout cli] board read ${JSON.stringify({
+        audience: payload.audience ?? null,
+        window_days: payload.windowDays ?? board.windowDays ?? null,
+        experiments: board.experiments?.length ?? 0,
+        settled: board.settled?.length ?? 0,
+        signals: board.signals?.length ?? 0,
+        truncated: truncationLines(board).length > 0,
+    })}`);
+    return 0;
+}
+async function runScoutAction(command, action, io, payload, session, dashboardUrl, log) {
+    const board = payload.board ?? {};
+    const lines = payload.lines ?? {};
     const ref = command.experimentRef ?? "";
     const resolution = resolveExperimentRef(board, ref);
     if (resolution.status !== "ok") {
-        const sentence = refusalSentence(resolution, ref);
-        writeLine(io.stderr, `[scout cli] action refused ${JSON.stringify({
-            reason: resolution.status,
-            action: command.action,
-            // The typed reference is a person's own input; only its shape is logged.
-            ref_length: ref.length,
-            candidates: resolution.status === "ambiguous_prefix" ? resolution.candidates.length : 0,
-        })}`);
-        if (command.json) {
-            writeLine(io.stdout, JSON.stringify({ ok: false, error: resolution.status, detail: sentence }));
-        }
-        else {
-            writeLine(io.stderr, sentence);
-            for (const line of renderScoutBoard(payload, colorEnabled(io)))
-                writeLine(io.stdout, line);
-        }
-        return 1;
+        return writeScoutRefusal(command, action, io, payload, ref, resolution);
     }
-    const serverAction = command.action === "undo" ? "undo_dismiss" : command.action;
+    const serverAction = action === "undo" ? "undo_dismiss" : action;
     const applied = await towerJsonRequest({
         dashboardUrl,
         path: "/api/cockpit/scout",
@@ -96,32 +95,7 @@ export async function runScout(command, io) {
         log,
     });
     if (!applied.ok) {
-        writeLine(io.stderr, `[scout cli] action failed ${JSON.stringify({
-            reason: applied.reason,
-            action: serverAction,
-            http_status: applied.httpStatus ?? null,
-        })}`);
-        if (command.json) {
-            writeLine(io.stdout, JSON.stringify({
-                ok: false,
-                error: applied.reason,
-                detail: failureDetail(applied),
-                httpStatus: applied.httpStatus ?? null,
-                board,
-                lines,
-            }));
-            return 1;
-        }
-        // The server's own refusal first, then one line saying which gate it was —
-        // and the board underneath, because being refused an action never costs a
-        // person the read they already had.
-        writeLine(io.stderr, `Tower refused that action: ${failureDetail(applied)}`);
-        if (applied.httpStatus === 403) {
-            writeLine(io.stderr, "Deciding a Scout card is a super_admin action; reading the board is not.");
-        }
-        for (const line of renderScoutBoard(payload, colorEnabled(io)))
-            writeLine(io.stdout, line);
-        return 1;
+        return writeScoutActionFailure(command, io, payload, board, lines, serverAction, applied);
     }
     const card = resolution.card;
     writeLine(io.stderr, `[scout cli] action applied ${JSON.stringify({ action: serverAction, http_status: applied.httpStatus })}`);
@@ -129,10 +103,58 @@ export async function runScout(command, io) {
         writeLine(io.stdout, JSON.stringify({ ok: true, action: serverAction, experiment: applied.body?.experiment ?? null }));
     }
     else {
-        writeLine(io.stdout, `${pastTense(command.action)} ${shortId(resolution.id)} · ${card.claimSummary ?? card.title ?? "that card"}`);
+        writeLine(io.stdout, `${pastTense(action)} ${shortId(resolution.id)} · ${card.claimSummary ?? card.title ?? "that card"}`);
     }
     return 0;
 }
+function writeScoutRefusal(command, action, io, payload, ref, resolution) {
+    const sentence = refusalSentence(resolution, ref);
+    writeLine(io.stderr, `[scout cli] action refused ${JSON.stringify({
+        reason: resolution.status,
+        action,
+        // The typed reference is a person's own input; only its shape is logged.
+        ref_length: ref.length,
+        candidates: resolution.status === "ambiguous_prefix" ? resolution.candidates.length : 0,
+    })}`);
+    if (command.json) {
+        writeLine(io.stdout, JSON.stringify({ ok: false, error: resolution.status, detail: sentence }));
+    }
+    else {
+        writeLine(io.stderr, sentence);
+        for (const line of renderScoutBoard(payload, colorEnabled(io)))
+            writeLine(io.stdout, line);
+    }
+    return 1;
+}
+function writeScoutActionFailure(command, io, payload, board, lines, serverAction, applied) {
+    writeLine(io.stderr, `[scout cli] action failed ${JSON.stringify({
+        reason: applied.reason,
+        action: serverAction,
+        http_status: applied.httpStatus ?? null,
+    })}`);
+    if (command.json) {
+        writeLine(io.stdout, JSON.stringify({
+            ok: false,
+            error: applied.reason,
+            detail: failureDetail(applied),
+            httpStatus: applied.httpStatus ?? null,
+            board,
+            lines,
+        }));
+        return 1;
+    }
+    // The server's own refusal first, then one line saying which gate it was —
+    // and the board underneath, because being refused an action never costs a
+    // person the read they already had.
+    writeLine(io.stderr, `Tower refused that action: ${failureDetail(applied)}`);
+    if (applied.httpStatus === 403) {
+        writeLine(io.stderr, "Deciding a Scout card is a super_admin action; reading the board is not.");
+    }
+    for (const line of renderScoutBoard(payload, colorEnabled(io))) {
+        writeLine(io.stdout, line);
+    }
+    return 1;
+}
 // ----------------------------------------------------------------- small parts
 function writeFailure(command, io, failure) {
     const detail = failureDetail(failure);