@ctrl-spc/cs 0.6.0 → 0.7.1

package/dist/panel3/show.js

@@ -0,0 +1,997 @@
+/**
+ * ═══ AGENT PANEL v3: `cs3 show`, the whole record in a terminal. ═══
+ *
+ * THIS FILE BELONGS TO AGENT PANEL v3. Nothing outside `src/panel3/` may
+ * import it.
+ *
+ * ---------------------------------------------------------------------------
+ * WHY THIS IS THE FIRST THING BUILT, BEFORE ANYTHING IT SHOWS EXISTS.
+ *
+ * v3 has no UI at all. Every later task is proved through this command, so if a
+ * fact cannot be seen here it cannot be said to work. That is also why the
+ * output is written for a person deciding whether the design holds, not for a
+ * parser: no ids without the thing they name, no counts without the rows.
+ *
+ * ---------------------------------------------------------------------------
+ * ═══ AN EMPTY RECORD AND A FAILED READ MUST NEVER LOOK ALIKE. ═══
+ *
+ * A read that comes back empty prints "No cards.". A read that FAILS throws, so
+ * `cs3` prints the reason on stderr and exits non-zero. `returned()` in
+ * `client.ts` is the one place that distinction is made, for every v3 command,
+ * and it also rejects the shape that would otherwise slip through: no error and
+ * no data, which is not "nothing is there" but "the client returned something
+ * this code does not understand".
+ *
+ * ---------------------------------------------------------------------------
+ * WHAT "LIVE" MEANS HERE, AND WHAT IT DOES NOT.
+ *
+ * Live is what the record says: state `running` and no end stamped. This
+ * command does not go looking for the process, and it must not pretend to —
+ * turning a run whose process is gone back into takeable work is Task 4's
+ * recovery, and a guess here would be a second, quieter answer to the same
+ * question.
+ */
+// The runtime import comes FIRST, deliberately: `tsc` elides a type-only import
+// and takes the leading comment with it, so a file whose first statement is
+// `import type` loses its v3 header in the published `dist/`.
+import { at, out, returned, signedInClient } from './client.js';
+import { coordination, elsewhereMismatch, listeningFleet, } from './presence.js';
+import { designatedCoordinator } from './coordinator.js';
+import { listCodebaseLocations, listCodebases } from '../codebases.js';
+/** The columns of `panel3_asks` that carry content, plus the reference that says
+ *  whether they are the ones to read. */
+export const ASK_CONTENT_COLUMNS = 'decision_id, question, answer, category, context, answer_mode, options, selected_options, '
+    + 'answer_note';
+/**
+ * The same rows, with a decision-backed question's words filled in from its
+ * decision.
+ *
+ * ONE EXTRA READ, AND ONLY WHEN THERE IS SOMETHING TO READ. `decision_id` is by
+ * value with no foreign key (conventions.md), so PostgREST cannot embed it and
+ * this is the join. A batch of escalations makes no second request at all.
+ *
+ * ═══ AND A DECISION THE PERSON CANNOT SEE IS LEFT EMPTY RATHER THAN INVENTED.
+ *     ═══ The read goes through their own RLS, exactly as every other v3 read
+ * does, so a row that comes back without its decision keeps the nulls the ask
+ * row really holds instead of being given a placeholder that would read as the
+ * question.
+ */
+export async function withAskContent(client, asks) {
+    const ids = [...new Set(asks.map((a) => a.decision_id).filter((id) => !!id))];
+    if (ids.length === 0)
+        return asks;
+    const decisions = await read(client.from('decisions')
+        .select('id, question, answer, category, context, answer_mode, options, selected_options, '
+        + 'answer_note, related_artifact_id, related_artifact_revision')
+        .in('id', ids), 'decisions');
+    /* THE CONTENT ONLY. The decision's own `id` is dropped here rather than
+       spread and overwritten: the ask row's id is what every caller answers,
+       shows and re-arms by, and merging the wrong one is the kind of mistake that
+       reads correctly right up until somebody uses it. */
+    const byId = new Map(decisions.map(({ id, ...content }) => [id, content]));
+    return asks.map((ask) => {
+        const content = ask.decision_id === null ? undefined : byId.get(ask.decision_id);
+        return content === undefined ? ask : { ...ask, ...content };
+    });
+}
+// ---------------------------------------------------------------------------
+// READS. Each one either returns rows or says why it could not, through the one
+// guard in `client.ts` that every v3 command shares.
+const read = (query, what) => returned(query, 'read', what);
+const CARD_COLUMNS = 'id, project_id, title, state, created_at, archived_at';
+const TURN_COLUMNS = 'id, card_id, role, body, created_at, addressed_at, run_id';
+const RUN_COLUMNS = 'id, card_id, codebase_id, parent_run_id, level, state, brief, report, failed_because, activity, machine_id, '
+    + 'pid, started_at, resumed_at, read_back_at, ended_at';
+const ASK_COLUMNS = `id, card_id, run_id, pending_run_id, answered_at, delivered_at, created_at, ${ASK_CONTENT_COLUMNS}`;
+const OUTPUT_COLUMNS = 'id, card_id, run_id, kind, ref_id, label, created_at';
+const ATTACHMENT_COLUMNS = 'id, card_id, kind, ref_id, label, created_at';
+function groupByCard(list) {
+    const out = new Map();
+    for (const row of list) {
+        const existing = out.get(row.card_id);
+        if (existing)
+            existing.push(row);
+        else
+            out.set(row.card_id, [row]);
+    }
+    return out;
+}
+/**
+ * The four child tables for the given cards, in the order each is read on
+ * screen. One loader for both views, so the list and the detail can never
+ * disagree about what is on a card.
+ */
+async function loadChildren(client, cardIds) {
+    const child = (table, columns, order) => read(client.from(table).select(columns).in('card_id', cardIds).order(order), table);
+    const [turns, runs, asks, outputs] = await Promise.all([
+        child('panel3_turns', TURN_COLUMNS, 'created_at'),
+        child('panel3_runs', RUN_COLUMNS, 'started_at'),
+        child('panel3_asks', ASK_COLUMNS, 'created_at'),
+        child('panel3_outputs', OUTPUT_COLUMNS, 'created_at'),
+    ]);
+    return {
+        turns: groupByCard(turns),
+        runs: groupByCard(runs),
+        // A question with the person keeps its words in its decision, so they are
+        // read before anything renders one. See `withAskContent`.
+        asks: groupByCard(await withAskContent(client, asks)),
+        outputs: groupByCard(outputs),
+    };
+}
+/**
+ * Project names for the cards that have one, read from the shared product table
+ * through the signed-in user's RLS — which AGENTS.md allows and this panel
+ * exists to surface. A project the user cannot see, or one that has been
+ * deleted, is simply absent from the map and is rendered as unknown rather than
+ * as none: they are different facts.
+ */
+async function loadProjectNames(client, cards) {
+    const ids = [...new Set(cards.map((c) => c.project_id).filter((id) => !!id))];
+    if (ids.length === 0)
+        return new Map();
+    const projects = await read(client.from('projects').select('id, name').in('id', ids), 'projects');
+    return new Map(projects.map((p) => [p.id, p.name]));
+}
+/**
+ * ═══ A RECEIPT POINTS AT AN OBJECT, SO WHAT IS PRINTED IS THE OBJECT'S NAME
+ *     NOW, NOT THE NAME IT WAS GIVEN. ═══
+ *
+ * ux.md: what a run made is recorded "as a receipt pointing at an object, never
+ * as prose describing one". `panel3_outputs.label` is that prose. It is written
+ * once, when the thing is made, and the coordinator may rename the thing on the
+ * very next turn. Printing the label then makes the only screen v3 has say the
+ * card produced something that does not exist under that name.
+ *
+ * IT IS NOT A HYPOTHETICAL AND IT IS NOT COSMETIC. One measured run created a
+ * work item, renamed it, and left a receipt reading "Onboarding checklist
+ * forgets itself on sign-out", which is the name of a DIFFERENT, real item that
+ * was already in progress. The card claimed a duplicate that had never been
+ * made.
+ *
+ * THE LABEL IS STILL WORTH KEEPING, for the two cases the ref cannot answer:
+ * `record_output` takes a kind this map does not know (a commit), and an object
+ * that has since been deleted has no name left to read. The second is said out
+ * loud rather than papered over with the old label, because a receipt pointing
+ * at nothing is exactly the sort of broken record this command exists to expose.
+ */
+const NAMED_BY = {
+    epic: { table: 'epics', column: 'name' },
+    sprint: { table: 'sprints', column: 'name' },
+    work_item: { table: 'tasks', column: 'name' },
+    artifact: { table: 'artifacts', column: 'title' },
+};
+/** Keyed by kind and id together, because two product tables answering to the
+ *  same id is a thing this map must not quietly resolve. */
+export async function loadOutputNames(client, outputs) {
+    const found = new Map();
+    await Promise.all(Object.entries(NAMED_BY).map(async ([kind, source]) => {
+        const ids = [...new Set(outputs.filter((o) => o.kind === kind).map((o) => o.ref_id))];
+        if (ids.length === 0)
+            return;
+        const rows = await read(client.from(source.table).select(`id, ${source.column}`).in('id', ids), source.table);
+        // A row that is there but unnamed is FOUND, not missing: an artifact may
+        // carry a null title, and calling that gone would be the louder lie.
+        for (const row of rows)
+            found.set(`${kind}:${row.id}`, row[source.column] ?? '(untitled)');
+    }));
+    return found;
+}
+/**
+ * ═══ WHAT WAS ATTACHED TO ONE CARD. ═══
+ *
+ * One card at a time, unlike `loadChildren`'s batch of every card on the list
+ * view: `cs3 show` prints attachments only in the single-card view (the plan's
+ * own line: the list view already says one thing per card, and this is
+ * per-item detail), and level 1's prompt and a dispatched brief are both about
+ * one card's work, never many at once. A batched loader with exactly one
+ * caller would be the speculative structure the engineering guide forbids.
+ */
+export async function loadAttachments(client, cardId) {
+    return read(client.from('panel3_attachments').select(ATTACHMENT_COLUMNS).eq('card_id', cardId)
+        .order('created_at'), 'panel3_attachments');
+}
+/**
+ * ═══ ONE LINE, EVERYWHERE AN ATTACHMENT IS NAMED. ═══
+ *
+ * `cs3 show`'s ATTACHMENTS section, level 1's prompt and a dispatched brief all
+ * name the same fact about the same row, and ux.md's own warning about the
+ * outbound rules applies here too: two copies of "how an attachment reads"
+ * would drift, silently, in whichever caller nobody re-read. So there is one
+ * function and every caller uses it, formatted plainly enough to read in a
+ * terminal and in a prompt alike.
+ */
+export const attachmentLine = (a) => `${a.kind}  ${a.label}   id ${a.ref_id}`;
+/**
+ * ═══ THE WHOLE ATTACHMENTS SECTION, EXACTLY AS `cs3 show` PRINTS IT, OR
+ *     NOTHING AT ALL. ═══
+ *
+ * Every other section on a card prints its own header and a "none" line at
+ * zero, because zero is still an answer to "how many runs does this card
+ * have". Whether a card has anything attached is a different question: most
+ * never will, since Task 2 offers attaching only when a card is started, and a
+ * header over nothing on every card in the record would be noise on every one
+ * of them for a fact that is usually absent rather than usually zero.
+ *
+ * PURE AND EXPORTED for the same reason `nothingWillActOn` is: the "prints
+ * nothing when there is nothing" rule is a fact about this function's return
+ * value, and a test asserting it should not need a live client or a running
+ * `cs3 show` to see it.
+ */
+export function attachmentsSection(attachments) {
+    if (attachments.length === 0)
+        return [];
+    return [`ATTACHMENTS  ${attachments.length}`, ...attachments.map((a) => `  ${attachmentLine(a)}`)];
+}
+async function codebaseSection(client, card, attachments, runs) {
+    const selected = attachments.filter((attachment) => attachment.kind === 'codebase');
+    if (selected.length === 0)
+        return [];
+    const codebases = card.project_id ? await listCodebases(client, card.project_id) : [];
+    const locations = await listCodebaseLocations(client, codebases.map((codebase) => codebase.gitRemoteUrl));
+    const machineIds = [...new Set(runs.filter((run) => run.codebase_id).map((run) => run.machine_id))];
+    const machines = machineIds.length === 0
+        ? []
+        : await read(client.from('panel3_machines').select('machine_id, name').in('machine_id', machineIds), 'machines that worked on these codebases');
+    const duplicateNames = new Set(codebases
+        .filter((codebase, index, all) => all.some((other, otherIndex) => (index !== otherIndex && other.name === codebase.name)))
+        .map((codebase) => codebase.name));
+    return [
+        `CODEBASES  ${selected.length}`,
+        ...selected.map((attachment) => {
+            const codebase = codebases.find((candidate) => candidate.id === attachment.ref_id);
+            if (!codebase)
+                return `  ${attachment.label}  no longer registered on this project`;
+            const name = duplicateNames.has(codebase.name)
+                ? `${codebase.name} (${codebase.gitRemoteUrl})`
+                : codebase.name;
+            const runMachineIds = [...new Set(runs.filter((run) => run.codebase_id === codebase.id).map((run) => run.machine_id))];
+            if (runMachineIds.length === 0)
+                return `  ${name}`;
+            const availability = runMachineIds.map((machineId) => {
+                const machineName = machines.find((machine) => machine.machine_id === machineId)?.name ?? machineId;
+                const located = locations.some((location) => (location.machineId === machineId && location.gitRemoteUrl === codebase.gitRemoteUrl));
+                return `${located ? 'located on' : 'NOT LOCATED on'} ${machineName}`;
+            });
+            return `  ${name}  ${availability.join('  ·  ')}`;
+        }),
+    ];
+}
+// ---------------------------------------------------------------------------
+// WHAT THE RECORD MEANS.
+const isLive = (run) => run.state === 'running' && !run.ended_at;
+/** The states a run is over in, whichever way it got there. `asked` is not one:
+ *  that run is coming back. */
+const ENDED = ['finished', 'failed'];
+const isOpen = (ask) => !ask.answered_at;
+const isUntaken = (turn) => turn.role === 'user' && !turn.addressed_at;
+/** Waiting on the PERSON: it has run out of levels above it, so nothing else
+ *  will settle it. This is what the needs-you state means, and it is read off
+ *  the same row the re-arm reads. */
+const isForYou = (ask) => !ask.answered_at && !ask.pending_run_id;
+/**
+ * ═══ SOMEBODY STILL HAS TO BE STARTED FOR THIS. ═══
+ *
+ * Unanswered, or answered and not yet carried back to the run that asked. Both
+ * are work that is coming back, which is why neither may let a card read `done`
+ * — and why `panel3_answer` carries this same predicate. A question is finished
+ * with only once it has been both answered and delivered.
+ */
+const isOutstanding = (ask) => !ask.answered_at || !ask.delivered_at;
+/**
+ * ═══ A QUESTION THAT BELONGS TO WORK THE USER STOPPED. ═══
+ *
+ * `panel3_ask_was_stopped` restated, and the duplication is `isOwedAReadBack`'s:
+ * the rule lives in SQL, where the re-arm, both settlers and `panel3_answer_ask`
+ * share it, and this is the screen's copy over rows it has already read. The
+ * contract suite asks both about the same rows, because the last copy of a rule
+ * that was left behind said an agent was about to be started that never was.
+ *
+ * WHAT IT CHANGES HERE IS ONE SENTENCE, AND THE SENTENCE MATTERS: a stalled
+ * question normally has a move, and this is the one case where it has none.
+ * Printing `cs3 answer` at somebody whose answer would start nothing sends them
+ * to type a command that cannot do what it says.
+ */
+const askWasStopped = (ask, runs) => {
+    const asker = runs.find((r) => r.id === ask.run_id);
+    if (!asker?.ended_at)
+        return false;
+    /* THE RUN THAT NEEDS THE ANSWER WAS REPLACED, so nothing will ever be started
+       for it. Keyed on that run alone, exactly as the SQL is: being superseded
+       says nothing about anybody else's question. */
+    if (asker.state === 'superseded')
+        return true;
+    return runs.some((s) => s.state === 'stopped' && s.ended_at && s.ended_at >= asker.ended_at);
+};
+/**
+ * ═══ A QUESTION HANDED TO AN AGENT THAT ENDED WITHOUT TOUCHING IT. ═══
+ *
+ * The one way the walk up can stop. A run is started once for a question it was
+ * handed — `delivered_at` is what makes that once rather than forever — so an
+ * agent that exits without answering it or passing it on leaves it where it is,
+ * with nothing that will ever pick it up again.
+ *
+ * IT IS FOUND BY THE SAME THREE FACTS THE RE-ARM USES, in the other direction:
+ * open, delivered, and the run it went to is not live. While that run IS live it
+ * is being dealt with, and before it was delivered the daemon will deal with it.
+ */
+const isStalled = (ask, runs) => isOpen(ask) && !!ask.pending_run_id && !!ask.delivered_at
+    && !runs.some((r) => r.id === ask.pending_run_id && isLive(r));
+/**
+ * ═══ A RUN THAT IS ABOUT TO BE STARTED AGAIN TO READ ITS WORKERS BACK. ═══
+ *
+ * ux.md's third re-arm, seen from the screen. It matters here for one reason:
+ * between the last worker ending and the next poll, a card can have nothing live
+ * on it, no turn waiting and no question outstanding, and still have an answer
+ * coming. Without this, the sentence below would call that card stranded — which
+ * is the forbidden state announced about a card that is perfectly healthy, and
+ * the one lie this function exists to prevent.
+ *
+ * ═══ IT IS `panel3_owed_read_back` RESTATED, AND THE DUPLICATION IS THE SAME ONE
+ *     `isOutstanding` ALREADY CARRIES. ═══ The rule lives in SQL, where the take
+ * and the two settlers share it; this is the screen's copy of it, over rows it
+ * has already read. Its cost is that the two can drift, and the contract suite
+ * pins the SQL side, which is the one anything depends on. Reading it back per
+ * card would be a round trip per run for a sentence that is usually not printed.
+ *
+ * ═══ AND THEY DID DRIFT, WHICH IS WHY THIS IS NOW EXPORTED AND TESTED. ═══ The
+ * SQL learned about Stop and this did not, so on a stopped card the screen
+ * announced that a run was "waiting to be started again" that nothing would ever
+ * start, and suppressed the two notes that would have said the card was going
+ * nowhere. A comment saying the two agree is not a check.
+ */
+export const isOwedAReadBack = (run, runs, asks) => {
+    /* ENDED, HOWEVER IT ENDED. A failed parent's workers carry on after it —
+       nothing cascades — so it is owed its read-back too, and leaving it out here
+       would have the screen call a card healthy that the database is about to
+       start work on. */
+    if (run.level <= 1 || !ENDED.includes(run.state) || !run.ended_at)
+        return false;
+    const sent = runs.filter((r) => r.parent_run_id === run.id);
+    if (sent.length === 0)
+        return false;
+    // A failed worker is done; a worker with a question outstanding is coming back.
+    const stillToCome = (child) => !child.ended_at || asks.some((a) => a.run_id === child.id && isOutstanding(a));
+    if (sent.some(stillToCome))
+        return false;
+    /* ═══ AND IT ENDED BEFORE THE USER STOPPED THIS CARD, SO IT BELONGS TO THE
+       WORK THEY STOPPED. ═══ `panel3_owed_read_back`'s own clause: nothing that had
+       ended when the stop landed is started again by it, whether the stop reached
+       its workers or something else on the card. Without this the screen says an
+       agent is about to be started to read back work the person killed. */
+    if (runs.some((s) => s.state === 'stopped' && s.ended_at && run.ended_at
+        && s.ended_at > run.ended_at))
+        return false;
+    /* ═══ AND IT HAS NOT ALREADY BEEN STARTED WITH THEM. ═══ Never started with
+       them at all is owed — which is the case a comparison against the run's own
+       end could not see, and the one that settled a card on a parent's
+       pre-dispatch text. Somebody finishing since is owed again. */
+    if (run.read_back_at === null)
+        return true;
+    return sent.some((child) => !!child.ended_at && child.ended_at > run.read_back_at);
+};
+/**
+ * ═══ THE QUESTIONS THAT NEED THE PERSON, WHATEVER ELSE IS TRUE OF THE CARD. ═══
+ *
+ * Split out of `nothingWillActOn` because it is the one part of that function
+ * that does not depend on a machine being up: a question whose agent has ended,
+ * and a question asked by work the user stopped, are both waiting on the person
+ * and stay waiting whether or not a daemon is polling. Everything else there is
+ * about what a machine would have done by now.
+ */
+function notesAboutQuestions(asks, runs) {
+    const notes = [];
+    for (const ask of asks.filter((a) => isStalled(a, runs))) {
+        /* ═══ UNLESS ANSWERING IT WOULD DO NOTHING. ═══ A question asked by work the
+           user stopped is never delivered again, so `cs3 answer` settles the row and
+           starts nobody. Naming the command anyway would be this screen sending
+           somebody to type something that cannot do what it says, which is the same
+           failure as the command itself claiming an effect it did not have. */
+        if (askWasStopped(ask, runs)) {
+            notes.push(`question ${ask.id} was asked by work you stopped: answering it starts nothing, and `
+                + `nothing is waiting for it. Send a message instead: cs3 say --card ${ask.card_id} `
+                + '"<text>".');
+            continue;
+        }
+        /* ═══ AND THE MOVE IS NAMED, BECAUSE THERE IS ONE. ═══ A stalled question is
+           the one case where the person may answer something that was never put to
+           them: it went somewhere, that somewhere is gone, and nobody else is going
+           to. Saying only that nothing will act on it would leave them reading a
+           dead end that is not one. */
+        notes.push(`question ${ask.id} went to an agent that has ended without answering it or passing it on: `
+            + `nothing will act on it until you do, with cs3 answer ${ask.id} "<text>".`);
+    }
+    return notes;
+}
+/**
+ * ═══ THE `'elsewhere'` SENTENCE, NAMING WHICH HALF OF THE DESIGNATION IS
+ *     ACTUALLY WRONG. ═══
+ *
+ * `elsewhereMismatch` (`presence.ts`) is the same comparison this sentence is
+ * built from, restated for the screen. "A machine is listening but it is not
+ * the one designated" is wrong and confusing when the designated MACHINE is
+ * exactly the one listening and only the harness differs — the point of this
+ * task — so each of the four shapes gets its own wording rather than one
+ * sentence covering all of them.
+ */
+function elsewhereSentence(designation, fleet) {
+    const mismatch = elsewhereMismatch(designation, fleet);
+    if (mismatch === 'harness') {
+        return `the designated machine (${designation.machineId}) is listening, but running a `
+            + `different harness than ${designation.agent}, which is what is designated: nothing will `
+            + `act on this until it runs ${designation.agent}, or a different machine or harness is `
+            + 'designated to coordinate.';
+    }
+    if (mismatch === 'machine') {
+        return `${designation.agent} is listening, but on a different machine than ${designation.machineId}, `
+            + 'which is what is designated: nothing will act on this until the designated machine runs '
+            + 'it, or a different machine or harness is designated to coordinate.';
+    }
+    if (mismatch === 'split') {
+        /* ═══ TWO ROWS SUPPLY ONE HALF EACH, SO THE SENTENCE NAMES BOTH. ═══ Review
+           finding on this task: the fall-through used to print the generic "not
+           the one designated" line here, which is the LEAST specific of the four
+           sentences in exactly the case the product knows the MOST — the
+           designated machine's OWN row (running the wrong harness) and the
+           designated harness's OWN row (running on the wrong machine) are both
+           right there in `fleet`. */
+        const wrongHarness = fleet.find((m) => m.machine_id === designation.machineId);
+        const wrongMachine = fleet.find((m) => m.harness === designation.agent);
+        return `the designated machine (${designation.machineId}) is listening, but running `
+            + `${wrongHarness?.harness} instead of ${designation.agent}, while ${designation.agent} is `
+            + `listening on a different machine (${wrongMachine?.machine_id}): nothing will act on this `
+            + `until ${designation.machineId} runs ${designation.agent}, or a different machine or `
+            + 'harness is designated to coordinate.';
+    }
+    return 'a machine is listening, but it is not the one designated to coordinate: nothing will '
+        + 'act on this until the designated machine is back, or a different one is designated to '
+        + 'coordinate.';
+}
+/**
+ * ═══ ANYTHING THAT WILL NEVER BE ACTED ON, SAID PLAINLY. ═══
+ *
+ * ux.md's forbidden state: "No input may ever be in a state where nothing will
+ * act on it and nothing on screen says so." This command is the only screen v3
+ * has, so this function is that guarantee, and it is deliberately the ONLY
+ * place the judgement is made — the card list and the card detail both call it,
+ * so a card cannot look stranded in one view and healthy in the other.
+ *
+ * AN OPEN ASK IS NOT STRANDED. It is waiting for the user, which is a state the
+ * user can see and settle, and calling it abandoned would be the same lie in
+ * the other direction. The asks section shows it as open.
+ *
+ * It reads the record and nothing else. Whether a machine is online is a fact
+ * this command cannot establish honestly today: nothing writes a run yet, so
+ * "waiting for a machine" would be a sentence with no writer behind it. The
+ * task that spawns runs owns that distinction.
+ */
+export function nothingWillActOn(card, turns, runs, asks, 
+/* ═══ WHETHER THE MACHINE AND HARNESS THAT WOULD ACT ON THIS CARD ARE
+   LISTENING. ═══ Every other sentence below is about rows, and rows cannot say
+   this: a card with an untaken turn is identical whether the pair that would
+   take it is two seconds away or nobody has one running. ux.md draws exactly
+   that line ("it must not say working, because nothing is working... the
+   distinction that matters is whether anything CAN pick it up"), so the one
+   fact the record does not hold is passed in — as `presence.ts`'s
+   `coordination()` gives it, not a plain boolean, because plan-coordinator
+   Task 4 split "anything is listening" into three cases a person needs told
+   apart: `'here'` (in hand, say nothing), `'elsewhere'` (a pair is designated
+   and it is not the one listening, though something else is), and `'nobody'`
+   (nothing at all is). */
+status, 
+/* ═══ AND, ONLY FOR `'elsewhere'`, WHAT WAS DESIGNATED AND WHO ELSE IS
+   LISTENING. ═══ plan-coordinator-shared Task 2: the designation now names a
+   machine AND a harness, so "not the one designated" can be wrong in two
+   different ways, and the sentence below has to say which one when only one
+   of the two differs — `elsewhereMismatch` in `presence.ts` is the same
+   comparison, restated for the screen. Neither argument is read when `status`
+   is `'here'` or `'nobody'`. */
+designation, fleet) {
+    const live = runs.filter(isLive);
+    const outstanding = asks.filter(isOutstanding);
+    const untaken = turns.filter(isUntaken);
+    const stalled = asks.filter((a) => isStalled(a, runs));
+    /* WORK THAT IS COMING BACK, EXACTLY AS AN OUTSTANDING QUESTION IS. The card
+       has nothing live on it and an answer is still on its way, so neither
+       sentence below may be printed about it. */
+    const reading = runs.filter((r) => isOwedAReadBack(r, runs, asks));
+    const notes = [];
+    /* ═══ THE CARD IS NOT IN HAND, WHICH OUTRANKS EVERY SENTENCE BELOW. ═══ The
+       two notes that follow read the card's rows and say nothing is acting on it;
+       both assume the machine that would act exists to have acted. With it not
+       listening, the fuller and simpler truth is the only one printed, because two
+       notes about one card read as two problems and the second would send
+       somebody looking at their turns for a fault that is not there.
+  
+       It is said about a `working` card alone. `done` has nothing left to pick up,
+       `needs-you` is waiting on the person rather than on a machine, and `failed`
+       already says what happened. */
+    if (status !== 'here' && card.state === 'working') {
+        return [
+            status === 'nobody'
+                ? 'no machine is running `cs3 run`, so nothing can pick this up: it is waiting for a '
+                    + 'machine, not being worked on. Start the CLI on a machine and it is taken from where '
+                    + 'it is.'
+                /* ═══ `'elsewhere'`, WHICH USED TO READ AS `'nobody'` AND CLAIMED NO
+                   MACHINE WAS ON WHEN THE PERSON COULD SEE ONE WAS. ═══ Task 4's own
+                   drift: a designated machine that has gone quiet is not the same fact
+                   as no machine at all, and the sentence has to say which one is true.
+                   ═══ AND, SINCE plan-coordinator-shared Task 2, WHICH HALF OF THE PAIR
+                   IS WRONG. ═══ "a machine is listening but it is not the one
+                   designated" is accurate and confusing the moment the designated
+                   MACHINE is exactly the one listening and only the harness differs, so
+                   the three shapes `elsewhereMismatch` can return each get their own
+                   sentence. `status === 'elsewhere'` only happens with a real
+                   designation (see `coordination`), so `designation` is never null
+                   here. */
+                : elsewhereSentence(designation, fleet),
+            ...notesAboutQuestions(asks, runs),
+        ];
+    }
+    if (card.state !== 'done' && untaken.length > 0 && live.length === 0
+        && outstanding.length === 0 && reading.length === 0) {
+        /* NOT WHEN THE CARD SAYS `done`, because that is a worse fact about the same
+           rows and it has its own sentence below. Two notes about one turn would
+           read as two problems. */
+        notes.push(`${count(untaken.length, 'user turn')} nobody has taken, and no run is live: `
+            + 'nothing is acting on this card.');
+    }
+    if (untaken.length === 0 && live.length === 0 && outstanding.length === 0 && reading.length === 0
+        && card.state === 'working') {
+        notes.push('the card says working, but no run is live, no turn is waiting to be taken and no question '
+            + 'is outstanding: nothing is working on it.');
+    }
+    if (card.state === 'needs-you' && asks.filter(isForYou).length === 0) {
+        notes.push('the card says needs-you, but no question is waiting on you: there is nothing for you to '
+            + 'answer.');
+    }
+    notes.push(...notesAboutQuestions(asks, runs));
+    if (card.state === 'done' && untaken.length > 0) {
+        /* ═══ SETTLED OVER SOMETHING THE PERSON SENT AFTERWARDS. ═══ `panel3_answer`
+           marks a card `done` on nothing live, nothing outstanding and nobody owed a
+           read-back — and NOT on the turns. A message typed while the run was
+           finishing is therefore unaddressed under a card that says the work is
+           over, which is exactly ux.md's forbidden state: what they sent is real,
+           durable and takeable, and the screen says the opposite.
+           IT IS A WINDOW AND NOT A DEAD END, so the sentence says which: the next
+           poll takes the turn and the card goes back to working. Naming it only
+           when it has lasted would mean the screen is honest except in the moment
+           somebody is most likely to be looking at it. */
+        notes.push(`the card says done while ${count(untaken.length, 'user turn')} `
+            + `${untaken.length === 1 ? 'is' : 'are'} still waiting to be taken: what you sent last has `
+            + 'not been answered, whatever the state says.');
+    }
+    /* AND `stopped` IS ONE OF THEM, because it is the newest way for the two to
+       disagree and the hardest to notice: a stop that missed a run leaves a live
+       agent under a card that says it was ended, and nothing else corrects a
+       stopped card. */
+    if ((card.state === 'done' || card.state === 'failed' || card.state === 'stopped')
+        && live.length > 0) {
+        notes.push(`the card says ${card.state} while ${count(live.length, 'run')} `
+            + `${live.length === 1 ? 'is' : 'are'} still live: the card and its runs disagree.`);
+    }
+    if (card.state === 'done' && reading.length > 0) {
+        /* THE SAME DISAGREEMENT ONE STEP EARLIER. `panel3_answer` refuses to settle a
+           card while somebody on it is owed a read-back, so this can only be printed
+           if the screen's copy of that rule and the database's have drifted — which
+           is exactly the drift worth being told about, since the answer the person
+           is about to get would land on a card they have stopped reading. */
+        notes.push(`the card says done while ${count(reading.length, 'run')} `
+            + `${reading.length === 1 ? 'has' : 'have'} still to read back what its workers found.`);
+    }
+    return notes;
+}
+// ---------------------------------------------------------------------------
+// RENDERING. Plain text, aligned, and every id printed in full so it can be
+// pasted straight back into `cs3 show`. `out` and `at` come from `client.ts`,
+// so two commands cannot print the same instant two different ways.
+const count = (n, noun) => `${n} ${noun}${n === 1 ? '' : 's'}`;
+/** A body of text under a heading, indented, with its blank lines kept. */
+function block(text, indent) {
+    for (const line of text.split('\n'))
+        out(`${indent}${line}`);
+}
+function summarise(turns, runs, asks, outputs) {
+    const live = runs.filter(isLive).length;
+    const open = asks.filter(isOpen).length;
+    return [
+        count(turns.length, 'turn'),
+        `${count(runs.length, 'run')}${live ? ` (${live} live)` : ''}`,
+        `${count(asks.length, 'ask')}${open ? ` (${open} open)` : ''}`,
+        count(outputs.length, 'output'),
+    ].join(', ');
+}
+export function outputOf(output, names) {
+    const label = output.label ?? '(no label)';
+    if (!(output.kind in NAMED_BY))
+        return label;
+    return names.get(`${output.kind}:${output.ref_id}`)
+        ?? `${label}   NO LONGER ON THE RECORD, or no longer yours to see`;
+}
+function projectOf(card, names) {
+    if (!card.project_id)
+        return 'no project yet';
+    return `${names.get(card.project_id) ?? 'unknown project'} (${card.project_id})`;
+}
+/**
+ * ═══ `working` IS A CLAIM ABOUT A MACHINE, SO IT IS NOT PRINTED WITHOUT ONE.
+ * ═══
+ *
+ * ux.md: "If no machine is running the CLI, the input is still accepted and
+ * durable... But it must not say working, because nothing is working. It says it
+ * is waiting for a machine."
+ *
+ * DERIVED HERE RATHER THAN STORED, which is what Task 1's migration already
+ * committed to in writing: "NOT ENUMERATED, DELIBERATELY: waiting for a machine
+ * ... it is DERIVED, not stored ... storing it would make it a second fact that
+ * drifts from the row that actually governs takeability". So the column keeps
+ * saying `working` and the screen says what that means right now.
+ */
+export const displayState = (card, status) => card.state === 'working' && status !== 'here' ? 'waiting' : card.state;
+/**
+ * ═══ WHICH MACHINE AND HARNESS COORDINATE, AND WHO ELSE IS LISTENING, EACH
+ *     WITH ITS OWN HARNESS. ═══
+ *
+ * PURE AND EXPORTED, matching `attachmentsSection`: the fact is checkable
+ * without a database, and it is said once here rather than assembled twice at
+ * the two render sites that need it — `showAllCards`'s own MACHINES paragraph
+ * and `showCard`'s per-card summary — so the two can never print a different
+ * answer to "which machine and harness coordinate" than each other.
+ *
+ * `designation === null` is said out loud rather than left silent, matching
+ * the migration's own comment: unset is a state, not an absence. A fleet row
+ * is marked COORDINATOR only when BOTH halves match — a listening row that
+ * shares only the machine id or only the harness with the designation is not
+ * the coordinator, it is exactly the `elsewhere` case `nothingWillActOn` names.
+ */
+export function machinesSection(designation, fleet) {
+    const lines = [
+        `coordinator  ${designation ? `${designation.machineId}  ${designation.agent}` : 'none designated, any machine may coordinate'}`,
+        fleet.length === 0
+            ? 'listening    none, so nothing can be picked up until a machine runs `cs3 run`'
+            : `listening    ${count(fleet.length, 'machine')}`,
+    ];
+    for (const m of fleet) {
+        const isCoordinator = designation !== null
+            && m.machine_id === designation.machineId && m.harness === designation.agent;
+        lines.push(`  ${m.machine_id}  ${m.name}  ${m.harness}${isCoordinator ? '  COORDINATOR' : ''}`);
+    }
+    return lines;
+}
+function renderNotes(notes) {
+    if (notes.length === 0)
+        return;
+    out();
+    out('NOTHING WILL ACT ON THIS');
+    for (const note of notes)
+        out(`  ${note}`);
+}
+// ---------------------------------------------------------------------------
+// THE THREE VIEWS.
+async function showAllCards(client) {
+    const cards = await read(client
+        .from('panel3_cards')
+        .select(CARD_COLUMNS)
+        .order('created_at', { ascending: false }), 'panel3_cards');
+    // The empty record, stated. Silence here would be indistinguishable from a
+    // command that did nothing at all, which is the confusion this whole file is
+    // built to avoid.
+    if (cards.length === 0) {
+        out('No cards.');
+        return;
+    }
+    const [children, names, designation, fleet] = await Promise.all([
+        loadChildren(client, cards.map((c) => c.id)),
+        loadProjectNames(client, cards),
+        designatedCoordinator(client),
+        listeningFleet(client),
+    ]);
+    const status = coordination(designation, fleet);
+    /* ═══ THE ANSWER TO "CAN ANYTHING PICK ANY OF THIS UP", ABOVE THE LIST THAT
+       DEPENDS ON IT. ═══ Every `waiting` below is this line's consequence, and a
+       reader who does not see it here would be left working out from a card why
+       the whole board is idle. */
+    out('MACHINES');
+    for (const line of machinesSection(designation, fleet))
+        out(`  ${line}`);
+    out();
+    out(`CARDS  ${cards.length}, newest first`);
+    for (const card of cards) {
+        const turns = children.turns.get(card.id) ?? [];
+        const runs = children.runs.get(card.id) ?? [];
+        const asks = children.asks.get(card.id) ?? [];
+        const outputs = children.outputs.get(card.id) ?? [];
+        out();
+        out(`  ${displayState(card, status).padEnd(10)}${card.title}`);
+        out(`    card     ${card.id}`);
+        out(`    project  ${projectOf(card, names)}`);
+        out(`    created  ${at(card.created_at)}${card.archived_at ? '   ARCHIVED' : ''}`);
+        out(`    ${summarise(turns, runs, asks, outputs)}`);
+        for (const note of nothingWillActOn(card, turns, runs, asks, status, designation, fleet)) {
+            out(`    ! ${note}`);
+        }
+    }
+    out();
+    out('  cs3 show <card-id> for one card in full.');
+}
+async function showCard(client, card) {
+    const [children, names, designation, fleet, attachments] = await Promise.all([
+        loadChildren(client, [card.id]),
+        loadProjectNames(client, [card]),
+        designatedCoordinator(client),
+        listeningFleet(client),
+        loadAttachments(client, card.id),
+    ]);
+    const status = coordination(designation, fleet);
+    const turns = children.turns.get(card.id) ?? [];
+    const runs = children.runs.get(card.id) ?? [];
+    const asks = children.asks.get(card.id) ?? [];
+    const outputs = children.outputs.get(card.id) ?? [];
+    /* ═══ EVERY READ FINISHES BEFORE THE FIRST LINE IS PRINTED. ═══ Resolved down
+       beside the outputs it names, this read threw after `CARD`, `TURNS` and the
+       turns themselves were already on stdout, leaving half a card above a reason
+       on stderr. In the one command whose whole job is telling the truth about the
+       record, a torn render is the worst place for it: the part that printed looks
+       like the whole answer. So it joins the load block, and rendering starts only
+       once nothing is left that can fail. */
+    const outputNames = await loadOutputNames(client, outputs);
+    const codebaseLines = await codebaseSection(client, card, attachments, runs);
+    out(`CARD  ${card.id}`);
+    out(`  title    ${card.title}`);
+    /* THE STATE THE PERSON IS OWED, which is not always the one stored: see
+       `displayState`. The stored word is still printed beside it, because this is
+       the command that exposes the record rather than dressing it. */
+    out(`  state    ${displayState(card, status)}${displayState(card, status) === card.state ? '' : ` (the row says ${card.state})`}`);
+    for (const line of machinesSection(designation, fleet))
+        out(`  ${line}`);
+    out(`  project  ${projectOf(card, names)}`);
+    for (const line of codebaseLines)
+        out(`  ${line}`);
+    out(`  created  ${at(card.created_at)}`);
+    if (card.archived_at)
+        out(`  archived ${at(card.archived_at)}`);
+    out();
+    out(`TURNS  ${turns.length}, in send order`);
+    if (turns.length === 0)
+        out('  none');
+    turns.forEach((turn, i) => {
+        /* ═══ ONLY A USER TURN IS EVER WAITING TO BE ADDRESSED. ═══ `addressed_at`
+           is the column the take reads, and the take only ever looks at the user's
+           words; an agent turn IS the answer, so printing NOT ADDRESSED beside one
+           said that the product's own reply was waiting for somebody. It appeared
+           the moment Task 4 wrote the first agent turn, on a card that was complete
+           and correct, which is exactly the kind of false alarm this command exists
+           not to raise. */
+        const addressed = turn.role !== 'user'
+            ? ''
+            : `  ${turn.addressed_at ? `addressed ${at(turn.addressed_at)}` : 'NOT ADDRESSED'}`;
+        /* WHICH LEVEL ANSWERED, read off the runs already loaded for this card
+           rather than fetched again. ux.md sends the answer back from whoever did
+           the work, so this line is where a reader sees that a code question came
+           back from level 2 and a question about the record came back from level 1.
+           A turn naming no run says so by saying nothing. */
+        const wrote = runs.find(run => run.id === turn.run_id);
+        const level = wrote ? `  L${wrote.level}` : '';
+        out(`  ${String(i + 1).padStart(2)}  ${turn.role.padEnd(5)}${level.padEnd(4)}  ${at(turn.created_at)}${addressed}`);
+        block(turn.body, '        ');
+    });
+    out();
+    out(`RUNS  ${runs.length}, nested under the run that dispatched them`);
+    if (runs.length === 0)
+        out('  none');
+    /* WHO IS ABOUT TO BE STARTED AGAIN TO READ ITS WORKERS BACK, worked out once
+       and handed over: the tree renderer has the runs and not the asks, and the
+       rule needs both. */
+    renderRunTree(runs, new Set(runs.filter((r) => isOwedAReadBack(r, runs, asks)).map((r) => r.id)));
+    out();
+    out(`ASKS  ${asks.length}`);
+    if (asks.length === 0)
+        out('  none');
+    for (const ask of asks) {
+        /* ═══ WHOSE TURN IT IS, WHICH IS THE WHOLE OF HOW A QUESTION WALKS. ═══ The
+           same row says who needs the answer and who has to give it, and the second
+           one moves up a level at a time until it runs out, which is the person. */
+        out(`  ${(isOpen(ask) ? 'OPEN' : 'answered').padEnd(8)}  ${ask.id}`);
+        out(`    asked   ${at(ask.created_at)} by ${ask.run_id ?? 'a run no longer on the record'}`);
+        out(`    with    ${isOpen(ask)
+            ? (ask.pending_run_id ?? 'YOU')
+            : 'nobody, it is answered'}`);
+        out('    Q');
+        /* NULL ONLY WHEN THE DECISION IT IS COULD NOT BE READ, which `withAskContent`
+           leaves empty rather than filling in. Said as what it is: the row is there
+           and its words are not, which is a different fact from a blank question. */
+        block(ask.question ?? '(this question could not be read)', '      ');
+        if (ask.answered_at) {
+            out(`    A  ${at(ask.answered_at)}`);
+            block(ask.answer ?? '(answered with nothing)', '      ');
+        }
+        else {
+            out('    A  not answered yet');
+        }
+        /* ═══ THE RE-ARM, ON THE ROW THAT GOVERNS IT. ═══ ux.md: the indicator and
+           the takeability are one fact. Undelivered says a run is still to be
+           started for this — for the answer, or to consider the question — which is
+           exactly what stops the card reading done. */
+        out(`    carried ${ask.delivered_at
+            ? `${at(ask.delivered_at)}, so somebody has been started for it`
+            : 'not yet: a run is still to be started for this'}`);
+    }
+    out();
+    out(`OUTPUTS  ${outputs.length}`);
+    if (outputs.length === 0)
+        out('  none');
+    for (const output of outputs) {
+        out(`  ${output.kind}  ${outputOf(output, outputNames)}`);
+        out(`    ref  ${output.ref_id}`);
+        out(`    by   ${output.run_id ?? 'a run no longer on the record'} at ${at(output.created_at)}`);
+    }
+    const attachmentLines = attachmentsSection(attachments);
+    if (attachmentLines.length > 0) {
+        out();
+        for (const line of attachmentLines)
+            out(line);
+    }
+    renderNotes(nothingWillActOn(card, turns, runs, asks, status, designation, fleet));
+    if (runs.length > 0) {
+        out();
+        out('  cs3 show <run-id> for a run\'s brief and report.');
+    }
+}
+/**
+ * The run tree, indented by dispatch rather than by level, because the question
+ * a reader has is who sent this agent, and the level is printed on the row.
+ *
+ * A run whose parent is not on this card is printed at the root WITH THAT SAID,
+ * rather than silently dropped: an orphan is exactly the kind of broken record
+ * this command exists to expose.
+ *
+ * ═══ AND SO IS A PARENT CYCLE, WHICH USED TO PRINT NOTHING AT ALL. ═══
+ *
+ * Two runs pointing at each other are neither roots nor anybody's rendered
+ * child, so the first version of this walked from the roots and left them out
+ * of the tree entirely: a `RUNS 3` header over two rows. The schema permits it
+ * — Task 1's migration has no self-reference or cycle check — and in the one
+ * command whose whole job is exposing a broken record, silently printing fewer
+ * rows than the count is the same failure as an empty array standing in for a
+ * failed read.
+ *
+ * So EVERY RUN IS RENDERED, and reachability is a fact about the record rather
+ * than a filter on the output: what the roots reach is printed first, then
+ * whatever is left over, at the root, saying why it is there. The `rendered`
+ * set is also what stops the cycle recursing forever.
+ */
+function renderRunTree(runs, readingBack) {
+    const onCard = new Set(runs.map((r) => r.id));
+    const children = new Map();
+    const roots = [];
+    for (const run of runs) {
+        if (run.parent_run_id && onCard.has(run.parent_run_id)) {
+            const siblings = children.get(run.parent_run_id);
+            if (siblings)
+                siblings.push(run);
+            else
+                children.set(run.parent_run_id, [run]);
+        }
+        else {
+            roots.push(run);
+        }
+    }
+    const rendered = new Set();
+    /** `unreached` is true for the leftover pass: no chain of parents on this card
+     *  gets from a root to this run, so the row says so instead of looking like an
+     *  ordinary root. */
+    const render = (run, depth, unreached) => {
+        rendered.add(run.id);
+        const pad = '  '.repeat(depth + 1);
+        const liveness = isLive(run) ? 'LIVE' : run.state;
+        out(`${pad}L${run.level}  ${liveness}  ${run.id}`);
+        if (run.codebase_id)
+            out(`${pad}    codebase ${run.codebase_id}`);
+        out(`${pad}    machine ${run.machine_id}${run.pid ? `  pid ${run.pid}` : ''}`);
+        out(`${pad}    started ${at(run.started_at)}`
+            + (run.ended_at ? `  ended ${at(run.ended_at)}` : '  not ended'));
+        /* ═══ STARTED AGAIN AS ITSELF, WHICH IS NOT VISIBLE ANYWHERE ELSE. ═══ Same
+           row, same id, same brief, so without this line a run that came back looks
+           exactly like one that ran once for a long time — and the difference is the
+           whole of whether the work survived.
+           WHY IT CAME BACK IS NOT SAID HERE, because the record does not hold it and
+           there are now three reasons: its machine went down, its question was
+           answered, or somebody it sent needs a decision. The asks below say which,
+           and inventing a reason on this line was measured saying "after its process
+           was found gone" under a run whose process had exited perfectly. */
+        if (run.resumed_at)
+            out(`${pad}    resumed ${at(run.resumed_at)}  started again as itself`);
+        /* ═══ WHAT IT SAID IT WAS DOING, AND ONLY WHILE IT COULD STILL BE DOING IT.
+           ═══ `activity` is a live line, so printing the last one under a run that
+           ended half an hour ago would read as something still in progress. On an
+           ended run the record's own answer is its state and its report. */
+        if (isLive(run) && run.activity)
+            out(`${pad}    doing   ${run.activity}`);
+        /* ═══ WHY THE PRODUCT ENDED IT, WHICH IS NOT THE RUN'S OWN WORDS. ═══ It
+           lives in its own column precisely so it cannot overwrite the report a
+           respawn is handed, and it is printed here because a run reading `failed`
+           with no reason anywhere is the record refusing to say what happened. */
+        if (run.failed_because)
+            out(`${pad}    failed  ${run.failed_because}`);
+        /* ═══ ENDED, AND STILL COMING BACK. ═══ Between the last worker finishing
+           and the next poll this run reads `finished` with nothing live anywhere on
+           the card, and an answer is on its way. Without this line the only honest
+           reading of that screen is that the work stopped. */
+        if (readingBack.has(run.id)) {
+            out(`${pad}    waiting to be started again, to read back what the ${count((children.get(run.id) ?? []).length, 'agent')} it sent found`);
+        }
+        if (!run.parent_run_id)
+            out(`${pad}    parent  none, dispatched by the daemon`);
+        else if (!onCard.has(run.parent_run_id)) {
+            out(`${pad}    parent  ${run.parent_run_id}, WHICH IS NOT ON THIS CARD`);
+        }
+        else if (unreached) {
+            out(`${pad}    parent  ${run.parent_run_id}, IN A CYCLE: no chain of parents reaches a root`);
+        }
+        for (const child of children.get(run.id) ?? []) {
+            if (rendered.has(child.id)) {
+                out(`${pad}  ${child.id} ALREADY SHOWN ABOVE: the parent chain loops back to it`);
+            }
+            else
+                render(child, depth + 1, unreached);
+        }
+    };
+    // What the roots reach, first, which is the tree as it is meant to be.
+    for (const root of roots)
+        render(root, 0, false);
+    // Then everything the roots could not reach, at the root, said out loud.
+    for (const run of runs)
+        if (!rendered.has(run.id))
+            render(run, 0, true);
+}
+/** A named run, which is the only place a brief and a report are printed in
+ *  full: putting them in the card view would bury the shape of the tree under
+ *  the text of every prompt. */
+async function showRun(client, run) {
+    const cards = await read(client.from('panel3_cards').select(CARD_COLUMNS).eq('id', run.card_id), 'panel3_cards');
+    const card = cards[0];
+    out(`RUN  ${run.id}`);
+    out(`  card     ${run.card_id}${card ? `  ${card.title}` : '  (card not readable)'}`);
+    out(`  level    ${run.level}`);
+    out(`  state    ${run.state}${isLive(run) ? '  (live)' : ''}`);
+    out(`  parent   ${run.parent_run_id ?? 'none, dispatched by the daemon'}`);
+    out(`  machine  ${run.machine_id}${run.pid ? `  pid ${run.pid}` : '  no pid recorded'}`);
+    out(`  started  ${at(run.started_at)}`);
+    if (run.resumed_at)
+        out(`  resumed  ${at(run.resumed_at)}  started again as itself`);
+    out(`  ended    ${run.ended_at ? at(run.ended_at) : 'not ended'}`);
+    if (isLive(run) && run.activity)
+        out(`  doing    ${run.activity}`);
+    if (run.failed_because)
+        out(`  failed   ${run.failed_because}`);
+    out();
+    out('BRIEF  what it was sent to do, written once at dispatch');
+    block(run.brief, '  ');
+    out();
+    out('REPORT  what it knows now, rewritten by the run');
+    // Null and empty are different facts about a run and are said differently.
+    if (run.report === null)
+        out('  nothing reported yet');
+    else if (run.report.trim() === '')
+        out('  reported an empty report');
+    else
+        block(run.report, '  ');
+}
+// ---------------------------------------------------------------------------
+/**
+ * `cs3 show` with no id lists every card. With an id it shows that card in
+ * full, or that run with its brief and report — one argument, resolved against
+ * the record, because a `--run` flag would make the caller say which kind of id
+ * they are holding when the record already knows.
+ */
+export async function show(id) {
+    const client = await signedInClient();
+    if (!id)
+        return showAllCards(client);
+    const cards = await read(client.from('panel3_cards').select(CARD_COLUMNS).eq('id', id), 'panel3_cards');
+    if (cards[0])
+        return showCard(client, cards[0]);
+    const runs = await read(client.from('panel3_runs').select(RUN_COLUMNS).eq('id', id), 'panel3_runs');
+    if (runs[0])
+        return showRun(client, runs[0]);
+    throw new Error(`no card and no run with id ${id}`);
+}