@bli-cockpit/cli 0.2.38 → 0.2.39

package/dist/commands/notes.js

@@ -0,0 +1,490 @@
+/**
+ * `cockpit notes` — the meeting-notes surface in the terminal (BLI-3459).
+ *
+ * The library, one note, your own shelf, putting a note in from a file or the
+ * clipboard, sharing it and taking it back, and moving it to another shelf.
+ * Everything `/meeting-notes` does in a browser, typed.
+ *
+ * This file owns terminal input and output ONLY. It holds no access rule, no
+ * naming scheme and no idea what a note may contain: every command is one call
+ * to a dashboard route, which runs the same code the page runs. In particular a
+ * paste goes through `POST /api/notes/upload` and never near the ingester
+ * directly — the route is what supplies `submittedAt` (BLI-3336), which is the
+ * whole reason a note that names no day of its own is stored as a dated context
+ * note instead of refused.
+ *
+ * Two contracts the shape enforces:
+ *
+ *  - **stdout is the answer, stderr is the commentary.** A `--json` run puts
+ *    exactly one object on stdout; progress, receipts and reasons go to stderr,
+ *    the same split the rest of the CLI keeps.
+ *  - **Sharing is a deliberate act.** `share` asks in a terminal and requires
+ *    `--yes` without one. `--json` implies `--yes`, because a machine-readable
+ *    run has nobody to ask and asking it to guess is worse than the flag it
+ *    already typed the command for.
+ */
+import { isInteractiveStdin, readLine, writeLine, yesByDefault } from "./cli-io.js";
+import { NOTE_SLOW_UPLOAD_BYTES, noteFileRefusalSentence, readNoteFile, } from "./notes-file.js";
+import { loadPairedSession, towerFailureDetail, towerRequest, } from "../tower-client.js";
+import { readResponseJson } from "../upload-http.js";
+/**
+ * The upload route's own ceiling is `maxDuration = 300` — reading a note is one
+ * model call over the whole file. The client waits slightly longer so the
+ * server's named failure wins the race whenever it manages to send one.
+ */
+const UPLOAD_DEADLINE_MS = 305_000;
+const READ_DEADLINE_MS = 60_000;
+const PASTE_MAX_CHARS = 2_000_000;
+const TAG = "[notes cli]";
+export async function runNotes(command, io) {
+    const session = await loadPairedSession("notes", command.homeDir);
+    const door = {
+        dashboardUrl: command.dashboardUrl ?? session.dashboard_url,
+        deviceToken: session.device_token,
+        io,
+        json: command.json,
+    };
+    switch (command.action) {
+        case "list":
+            return listNotes(command, door);
+        case "shelves":
+            return listShelves(command, door);
+        case "show":
+            return showNote(command, door);
+        case "shelf":
+            return showShelf(command, door);
+        case "upload":
+            return uploadNotes(command, door);
+        case "paste":
+            return pasteNote(command, door);
+        case "share":
+        case "unshare":
+            return shareNote(command, door);
+        case "move":
+            return moveNote(command, door);
+    }
+}
+function libraryQuery(command) {
+    const query = new URLSearchParams();
+    if (command.series)
+        query.set("series", command.series);
+    if (command.meetingKind)
+        query.set("kind", command.meetingKind);
+    if (command.since)
+        query.set("since", command.since);
+    if (command.until)
+        query.set("until", command.until);
+    if (command.limit !== undefined)
+        query.set("limit", String(command.limit));
+    const rendered = query.toString();
+    return rendered === "" ? "" : `?${rendered}`;
+}
+async function listNotes(command, door) {
+    const answer = await ask(door, {
+        path: `/api/notes/library${libraryQuery(command)}`,
+        method: "GET",
+        label: "notes list",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return fail(door, answer.reason, answer.detail);
+    const body = answer.body;
+    if (door.json)
+        return emit(door, body);
+    sayScope(door, body);
+    const series = body.series ?? [];
+    if (series.length === 0) {
+        writeLine(door.io.stdout, "No meeting notes matched.");
+        return 0;
+    }
+    for (const one of series) {
+        writeLine(door.io.stdout, "");
+        writeLine(door.io.stdout, `${one.heading} (${one.notes.length})`);
+        for (const note of one.notes) {
+            const who = note.participants.length > 0 ? ` — ${note.participants.join(", ")}` : "";
+            writeLine(door.io.stdout, `  ${note.meetingDate}  ${note.id}  ${note.fileName}${who}`);
+        }
+    }
+    writeLine(door.io.stdout, "");
+    writeLine(door.io.stdout, `${body.count ?? 0} note(s)${body.more ? ", and more exist beyond the limit" : ""}.`);
+    return 0;
+}
+async function listShelves(command, door) {
+    const answer = await ask(door, {
+        path: `/api/notes/library${libraryQuery(command)}`,
+        method: "GET",
+        label: "notes shelves",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return fail(door, answer.reason, answer.detail);
+    const body = answer.body;
+    const shelves = (body.series ?? []).map((one) => ({
+        shelf: one.heading,
+        notes: one.notes.length,
+        // A shelf somebody typed, rather than the one a kind implies. Only the
+        // first kind is reported: a shelf is free text and can hold any of them.
+        custom: (body.categories ?? []).includes(one.heading),
+    }));
+    if (door.json)
+        return emit(door, { scope: body.scope, shelves });
+    sayScope(door, body);
+    if (shelves.length === 0) {
+        writeLine(door.io.stdout, "No shelves yet.");
+        return 0;
+    }
+    for (const shelf of shelves) {
+        writeLine(door.io.stdout, `${String(shelf.notes).padStart(4)}  ${shelf.shelf}${shelf.custom ? "" : "  (from the meeting kind)"}`);
+    }
+    return 0;
+}
+async function showNote(command, door) {
+    const answer = await ask(door, {
+        path: `/api/notes/library/${encodeURIComponent(command.noteId ?? "")}`,
+        method: "GET",
+        label: "notes show",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return fail(door, answer.reason, answer.detail);
+    const body = answer.body;
+    if (door.json)
+        return emit(door, body);
+    const note = body.note;
+    if (!note)
+        return fail(door, "no_note_in_answer", "Tower answered without a note.");
+    sayScope(door, body);
+    writeLine(door.io.stdout, note.title);
+    writeLine(door.io.stdout, `${note.meetingDate}  ·  ${note.shelf}  ·  ${note.fileName}  ·  ${note.lineCount} lines`);
+    if (note.participants.length > 0) {
+        writeLine(door.io.stdout, `In the room: ${note.participants.join(", ")}`);
+    }
+    writeLine(door.io.stdout, note.visibility);
+    writeLine(door.io.stdout, "");
+    writeLine(door.io.stdout, note.content);
+    return 0;
+}
+async function showShelf(command, door) {
+    const query = command.limit === undefined ? "" : `?limit=${command.limit}`;
+    const answer = await ask(door, {
+        path: `/api/notes/shelf${query}`,
+        method: "GET",
+        label: "notes shelf",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return fail(door, answer.reason, answer.detail);
+    const body = answer.body;
+    if (door.json)
+        return emit(door, body);
+    sayScope(door, body);
+    const notes = body.notes ?? [];
+    if (notes.length === 0) {
+        writeLine(door.io.stdout, "You have not put any notes in yet.");
+        return 0;
+    }
+    for (const note of notes) {
+        const counts = note.countsKnown
+            ? `${note.statements} statements, ${note.openToTheTeam} open to the team, ${note.keptBack} kept back`
+            : "counts unknown on this server";
+        writeLine(door.io.stdout, `${note.meetingDate}  ${note.id}  ${note.shared ? "shared " : "yours  "}  ${note.name}`);
+        writeLine(door.io.stdout, `            ${counts}`);
+    }
+    return 0;
+}
+async function uploadNotes(command, door) {
+    const paths = command.paths ?? [];
+    const results = [];
+    let worstExit = 0;
+    for (const filePath of paths) {
+        // Read and screen locally BEFORE any network call — a refusal here never
+        // reaches the dashboard, same discipline as `cockpit jarvis --image`.
+        const read = await readNoteFile(filePath);
+        if (!read.ok) {
+            const sentence = noteFileRefusalSentence(read.refusal, filePath);
+            writeLine(door.io.stderr, `${TAG} file refused ${JSON.stringify({ reason: read.refusal, detail: read.detail })}`);
+            if (!door.json)
+                writeLine(door.io.stderr, sentence);
+            results.push({ path: filePath, ok: false, reason: read.refusal });
+            worstExit = 1;
+            continue;
+        }
+        if (read.bytes.byteLength >= NOTE_SLOW_UPLOAD_BYTES) {
+            // The route reads the whole note with one model call and may take
+            // minutes. A still cursor reads as a hang, so say what is happening.
+            writeLine(door.io.stderr, `Reading ${read.fileName} (${Math.round(read.bytes.byteLength / 1024)} KB). This can take a couple of minutes.`);
+        }
+        const form = new FormData();
+        form.set("file", new File([new Uint8Array(read.bytes)], read.fileName));
+        if (command.exclude)
+            form.set("exclusions", command.exclude);
+        const answer = await ask(door, {
+            path: "/api/notes/upload",
+            method: "POST",
+            label: "notes upload",
+            timeoutMs: UPLOAD_DEADLINE_MS,
+            body: form,
+        });
+        if (!answer.ok) {
+            writeLine(door.io.stderr, `${TAG} upload failed ${JSON.stringify({ reason: answer.reason })}`);
+            if (!door.json)
+                writeLine(door.io.stderr, `${read.fileName}: ${answer.detail}`);
+            results.push({ path: filePath, ok: false, reason: answer.reason });
+            worstExit = 1;
+            continue;
+        }
+        const body = answer.body;
+        results.push({ path: filePath, ok: body.stored === true, body });
+        if (body.stored !== true)
+            worstExit = 1;
+        if (!door.json)
+            sayUpload(door, body);
+        writeLine(door.io.stderr, `${TAG} upload answered ${JSON.stringify({
+            stored: body.stored === true,
+            note_id: body.noteId ?? null,
+            scope: body.scope ?? null,
+            byte_size: read.bytes.byteLength,
+            extension: read.extension,
+        })}`);
+    }
+    if (door.json) {
+        emit(door, { ok: worstExit === 0, uploaded: results.length, results });
+    }
+    return worstExit;
+}
+async function pasteNote(command, door) {
+    let text;
+    if (command.filePath) {
+        const read = await readNoteFile(command.filePath);
+        if (!read.ok) {
+            const sentence = noteFileRefusalSentence(read.refusal, command.filePath);
+            writeLine(door.io.stderr, `${TAG} file refused ${JSON.stringify({ reason: read.refusal, detail: read.detail })}`);
+            return fail(door, read.refusal, sentence);
+        }
+        text = read.bytes.toString("utf8");
+    }
+    else {
+        if (isInteractiveStdin(door.io)) {
+            return fail(door, "nothing_piped", "Pipe the note in (`pbpaste | cockpit notes paste` on macOS, "
+                + "`Get-Clipboard | cockpit notes paste` on Windows) or pass --file <path>.");
+        }
+        try {
+            text = await readAll(door.io.stdin);
+        }
+        catch (error) {
+            return fail(door, "paste_too_long", errorText(error));
+        }
+    }
+    if (text.trim() === "") {
+        return fail(door, "empty_paste", "There was nothing to paste. Nothing was sent.");
+    }
+    const form = new FormData();
+    form.set("text", text);
+    if (command.name)
+        form.set("name", command.name);
+    if (command.exclude)
+        form.set("exclusions", command.exclude);
+    if (text.length >= NOTE_SLOW_UPLOAD_BYTES) {
+        writeLine(door.io.stderr, `Reading ${Math.round(text.length / 1024)} KB of pasted text. This can take a couple of minutes.`);
+    }
+    const answer = await ask(door, {
+        path: "/api/notes/upload",
+        method: "POST",
+        label: "notes paste",
+        timeoutMs: UPLOAD_DEADLINE_MS,
+        body: form,
+    });
+    if (!answer.ok)
+        return fail(door, answer.reason, answer.detail);
+    const body = answer.body;
+    writeLine(door.io.stderr, `${TAG} paste answered ${JSON.stringify({
+        stored: body.stored === true,
+        note_id: body.noteId ?? null,
+        scope: body.scope ?? null,
+        chars: text.length,
+        named_by_caller: Boolean(command.name),
+    })}`);
+    if (door.json)
+        return emit(door, body, body.stored === true ? 0 : 1);
+    sayUpload(door, body);
+    return body.stored === true ? 0 : 1;
+}
+async function shareNote(command, door) {
+    const wantsToShare = command.action === "share";
+    // Only sharing asks. Taking a note back narrows who can read it, and nobody
+    // needs to be talked out of that.
+    if (wantsToShare && !command.yes) {
+        if (!isInteractiveStdin(door.io)) {
+            return fail(door, "confirmation_required", "Sharing a note lets everyone signed in read it. Pass --yes to do it without being asked.");
+        }
+        const answer = await readLine(door.io, "Share this note with everyone signed in? [Y/n] ");
+        if (!yesByDefault(answer)) {
+            writeLine(door.io.stderr, `${TAG} share declined ${JSON.stringify({ reason: "operator_said_no" })}`);
+            writeLine(door.io.stdout, "Left alone. Nothing changed.");
+            return 0;
+        }
+    }
+    const answer = await ask(door, {
+        path: "/api/notes/share",
+        method: "POST",
+        label: wantsToShare ? "notes share" : "notes unshare",
+        timeoutMs: READ_DEADLINE_MS,
+        body: { note_id: command.noteId, share: wantsToShare },
+    });
+    if (!answer.ok)
+        return fail(door, answer.reason, answer.detail);
+    const body = answer.body;
+    writeLine(door.io.stderr, `${TAG} ${wantsToShare ? "shared" : "taken back"} ${JSON.stringify({
+        note_id: command.noteId ?? null,
+        stored: body.stored === true,
+    })}`);
+    if (door.json)
+        return emit(door, body);
+    sayUpload(door, body);
+    return 0;
+}
+async function moveNote(command, door) {
+    const answer = await ask(door, {
+        path: "/api/notes/move",
+        method: "POST",
+        label: "notes move",
+        timeoutMs: READ_DEADLINE_MS,
+        // `--clear-shelf` sends the empty string, which is what the browser's own
+        // move box sends when a person empties it.
+        body: { note_id: command.noteId, category: command.clearShelf ? "" : command.to },
+    });
+    if (!answer.ok)
+        return fail(door, answer.reason, answer.detail);
+    const body = answer.body;
+    writeLine(door.io.stderr, `${TAG} move answered ${JSON.stringify({
+        note_id: command.noteId ?? null,
+        ok: body.ok === true,
+        reason: body.reason ?? null,
+        cleared: Boolean(command.clearShelf),
+    })}`);
+    if (door.json)
+        return emit(door, body, body.ok === true ? 0 : 1);
+    writeLine(door.io.stdout, body.headline ?? "Tower answered without a sentence.");
+    for (const line of body.lines ?? [])
+        writeLine(door.io.stdout, line);
+    return body.ok === true ? 0 : 1;
+}
+/**
+ * One request, and a refusal that keeps the ROUTE'S own words.
+ *
+ * `towerJsonRequest` maps a non-2xx through `responseErrorMessage`, which looks
+ * for `message` or `error` — the shape the ingest routes answer with. Every
+ * notes door answers in the browser's shape instead (`headline` plus `lines`,
+ * with a `reason` label beside them), because the same body is what the page
+ * renders. Reading it here rather than widening `responseErrorMessage` keeps one
+ * meaning per field: the sentence is written where the outcome is known, and the
+ * terminal relays it rather than inventing a second wording for the same thing.
+ */
+async function ask(door, options) {
+    const result = await towerRequest({
+        dashboardUrl: door.dashboardUrl,
+        path: options.path,
+        deviceToken: door.deviceToken,
+        fetch: door.io.fetch,
+        method: options.method,
+        label: options.label,
+        timeoutMs: options.timeoutMs,
+        ...(options.body === undefined ? {} : { body: options.body }),
+        log: (line) => writeLine(door.io.stderr, line),
+    });
+    if (!result.ok) {
+        const failure = result;
+        return {
+            ok: false,
+            reason: failure.reason,
+            detail: towerFailureDetail(failure.reason, failure.detail),
+        };
+    }
+    const body = await readResponseJson(result.response);
+    if (!result.response.ok) {
+        const status = result.response.status;
+        return {
+            ok: false,
+            reason: refusalReason(body) ?? `http_${status}`,
+            detail: refusalSentence(body) ?? `Tower answered ${status} and said nothing about why.`,
+        };
+    }
+    return { ok: true, body };
+}
+function refusalReason(body) {
+    if (!body || typeof body !== "object")
+        return null;
+    const record = body;
+    for (const key of ["reason", "error", "code"]) {
+        const value = record[key];
+        if (typeof value === "string" && value.trim() !== "")
+            return value;
+    }
+    return null;
+}
+function refusalSentence(body) {
+    if (!body || typeof body !== "object")
+        return null;
+    const record = body;
+    const headline = typeof record["headline"] === "string" ? record["headline"] : null;
+    const message = typeof record["message"] === "string" ? record["message"] : null;
+    const lines = Array.isArray(record["lines"])
+        ? record["lines"].filter((line) => typeof line === "string")
+        : [];
+    const said = [headline ?? message, ...lines].filter(Boolean);
+    return said.length > 0 ? said.join(" ") : null;
+}
+/** One machine-readable object on stdout, and nothing else on it. */
+function emit(door, body, exitCode = 0) {
+    writeLine(door.io.stdout, JSON.stringify(body));
+    return exitCode;
+}
+function fail(door, reason, detail) {
+    writeLine(door.io.stderr, `${TAG} refused ${JSON.stringify({ reason })}`);
+    if (door.json) {
+        writeLine(door.io.stdout, JSON.stringify({ ok: false, error: reason, detail }));
+    }
+    else {
+        writeLine(door.io.stderr, detail);
+    }
+    return 1;
+}
+/**
+ * The route's own words for what happened. Never rephrased here — the sentences
+ * are written where the outcome is known, and a second wording in the terminal
+ * would be a second thing to keep in step.
+ */
+function sayUpload(door, body) {
+    writeLine(door.io.stdout, body.headline ?? "Tower answered without a sentence.");
+    for (const line of body.lines ?? [])
+        writeLine(door.io.stdout, line);
+    if (body.noteId)
+        writeLine(door.io.stdout, `Note id: ${body.noteId}`);
+}
+/**
+ * Says out loud when an answer is narrower than the one a browser would give.
+ *
+ * A degraded read is still a real answer and is never withheld — but a person
+ * who cannot see their own unshared note has to be told that is why, not left
+ * to conclude it was never stored.
+ */
+function sayScope(door, body) {
+    if (!body.degradedBecause)
+        return;
+    writeLine(door.io.stderr, `${TAG} narrowed ${JSON.stringify({ scope: body.scope ?? null, reason: body.degradedBecause })}`);
+    writeLine(door.io.stderr, body.degradedNote ?? "This answer is narrower than the browser's.");
+}
+async function readAll(stream) {
+    stream.setEncoding("utf8");
+    let text = "";
+    for await (const chunk of stream) {
+        text += chunk;
+        if (text.length > PASTE_MAX_CHARS) {
+            throw new Error(`A pasted note is limited to ${PASTE_MAX_CHARS} characters. Save it to a file and use --file instead.`);
+        }
+    }
+    return text;
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}

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

package/dist/commands/scout-render.js

@@ -0,0 +1,172 @@
+/**
+ * How a Scout board reads in a terminal, and which card a typed id means.
+ *
+ * Pure functions, no io and no network: `scout.ts` fetches, this lays out. The
+ * split is BLI-3460's, taken so the layout can be asserted line for line by a
+ * test that never opens a socket.
+ *
+ * **The sentences are the page's, not this file's.** Every standing line — the
+ * watch line, the headline, the quiet reason, all three section labels —
+ * arrives in the GET payload from the dashboard's `lib/cockpit/scout-lines.ts`,
+ * the same module the browser surface renders. Nothing here words anything; a
+ * terminal that writes its own "LAST SWEEP" will eventually disagree with the
+ * page about whether the sweep ran.
+ *
+ * **A bounded read says so.** The server returns at most 8 cards and 12
+ * signals; when there are more, `truncationLines` prints how many. A quiet
+ * board and a truncated board must never look alike.
+ */
+const DIM = "\x1b[2m";
+const RESET = "\x1b[0m";
+// ------------------------------------------------------------------ rendering
+/** The whole board as terminal lines, in the page's three sections and order. */
+export function renderScoutBoard(payload) {
+    const board = payload.board ?? {};
+    const lines = payload.lines ?? {};
+    const out = [];
+    if (lines.watch)
+        out.push(lines.watch);
+    if (lines.headline)
+        out.push(lines.headline);
+    const experiments = board.experiments ?? [];
+    out.push("", lines.waitingLabel ?? "Waiting on you");
+    if (experiments.length === 0) {
+        out.push(indent(lines.quiet ?? "Nothing is waiting on a decision right now."));
+    }
+    else {
+        for (const card of experiments)
+            out.push(...renderExperiment(card));
+    }
+    const settled = board.settled ?? [];
+    if (settled.length > 0) {
+        out.push("", lines.settledLabel ?? "Already decided");
+        for (const card of settled) {
+            out.push(`  ⏺ ${shortId(card.id ?? "")} · ${card.status === "done" ? "RAN" : "DISMISSED"} · ${card.claimSummary ?? card.title ?? ""}`);
+        }
+    }
+    const signals = board.signals ?? [];
+    out.push("", lines.rawWatchLabel ?? "The raw watch");
+    if (signals.length === 0) {
+        out.push(indent(lines.rawWatchEmpty ?? "Nothing was gathered in this window."));
+    }
+    else {
+        for (const signal of signals)
+            out.push(...renderSignal(signal));
+    }
+    const truncation = truncationLines(board);
+    if (truncation.length > 0)
+        out.push("", ...truncation);
+    return out;
+}
+function renderExperiment(card) {
+    const sourceCount = card.sourceCount ?? 0;
+    const head = [
+        shortId(card.id ?? ""),
+        card.status === "started" ? "RUNNING" : "SUGGESTED",
+        sourceCount === 0
+            ? "no source signals"
+            : `${sourceCount} source signal${sourceCount === 1 ? "" : "s"}`,
+        dayStamp(card.createdAt),
+    ]
+        .filter(Boolean)
+        .join(" · ");
+    const out = [`  ⏺ ${head}`];
+    if (card.claimSummary)
+        out.push(`    ${card.claimSummary}`);
+    if (card.title)
+        out.push(dim(`    ${card.title}`));
+    for (const row of card.crossref ?? []) {
+        if (row.person)
+            out.push(dim(`    On your team · ${row.person} · ${row.observedPattern ?? ""}`));
+    }
+    if (card.expectedPayoff)
+        out.push(dim(`    Worth trying · ${card.expectedPayoff}`));
+    for (const source of card.sources ?? []) {
+        if (source.title)
+            out.push(dim(`    ${source.title} · ${source.source ?? ""} · ${source.url ?? ""}`));
+    }
+    return out;
+}
+function renderSignal(signal) {
+    const out = [`  ⏺ ${signal.title ?? "untitled"} · ${dayStamp(signal.gatheredAt)}`];
+    if (signal.synopsis)
+        out.push(dim(`    ${signal.synopsis}`));
+    const foot = [
+        signal.source,
+        signal.evidenceStrength ?? undefined,
+        signal.status === "promoted" ? "promoted" : undefined,
+        (signal.tags ?? []).slice(0, 4).join(", ") || undefined,
+        signal.url,
+    ].filter((part) => Boolean(part));
+    if (foot.length > 0)
+        out.push(dim(`    ${foot.join(" · ")}`));
+    return out;
+}
+/**
+ * One line per bounded read that did not fit. Silence here means the board on
+ * screen IS the board — which is only true because this says otherwise when it
+ * is not.
+ */
+export function truncationLines(board) {
+    const coverage = board.coverage ?? {};
+    const parts = [
+        ["waiting cards", coverage.openExperiments],
+        ["decided cards", coverage.settledExperiments],
+        ["signals", coverage.signals],
+    ];
+    const out = [];
+    for (const [label, read] of parts) {
+        if (!read?.truncated)
+            continue;
+        const returned = read.returned ?? 0;
+        out.push(typeof read.total === "number"
+            ? `Bounded read · ${label}: ${returned} of ${read.total} shown. The rest is in Tower.`
+            : `Bounded read · ${label}: ${returned} shown, and there are more. The rest is in Tower.`);
+    }
+    return out;
+}
+/**
+ * Which card a typed reference means, decided against the board that was just
+ * read — never against a guess. An exact id wins outright; otherwise a prefix
+ * must match exactly one card, and two matches are refused by name rather than
+ * silently taking the first.
+ */
+export function resolveExperimentRef(board, ref) {
+    const needle = ref.trim().toLowerCase();
+    if (!needle)
+        return { status: "no_match" };
+    const cards = [...(board.experiments ?? []), ...(board.settled ?? [])].filter((card) => typeof card.id === "string");
+    const exact = cards.find((card) => card.id.toLowerCase() === needle);
+    if (exact)
+        return { status: "ok", id: exact.id, card: exact };
+    const matches = cards.filter((card) => card.id.toLowerCase().startsWith(needle));
+    if (matches.length === 0)
+        return { status: "no_match" };
+    if (matches.length > 1) {
+        return { status: "ambiguous_prefix", candidates: matches.map((card) => shortId(card.id)) };
+    }
+    const only = matches[0];
+    return { status: "ok", id: only.id, card: only };
+}
+export function refusalSentence(resolution, ref) {
+    if (resolution.status === "no_match") {
+        return `No card on the board starts with "${ref}". Run \`cockpit scout\` to see the ids.`;
+    }
+    if (resolution.status === "ambiguous_prefix") {
+        return `${resolution.candidates.length} cards start with "${ref}" (${resolution.candidates.join(", ")}). Use more characters.`;
+    }
+    return "";
+}
+// ----------------------------------------------------------------- small parts
+export function shortId(id) {
+    return id.slice(0, 6);
+}
+function dayStamp(iso) {
+    return iso ? iso.slice(0, 10) : "";
+}
+function dim(text) {
+    return `${DIM}${text}${RESET}`;
+}
+function indent(text) {
+    return `  ${text}`;
+}