@ctrl-spc/cs 0.5.0 → 0.7.0

package/dist/panel3/run.js

@@ -0,0 +1,1988 @@
+/**
+ * ═══ AGENT PANEL v3: the poll loop that answers a card. ═══
+ *
+ * THIS FILE BELONGS TO AGENT PANEL v3. Nothing outside `src/panel3/` may import
+ * it, WITH ONE NAMED EXCEPTION: `cli-v2/src/daemon.ts` imports `startPanel` from
+ * here and nothing else, which is how `cs start` runs the panel. It is written
+ * down in `conventions.md` and checked by `panel3-isolation.contract.test.mjs`;
+ * `startPanel`'s own comment at the foot of this file carries the reasoning.
+ *
+ * ---------------------------------------------------------------------------
+ * WHAT THIS IS. `cs3 say` puts a card and a user turn on the record and returns,
+ * because ux.md requires the acknowledgement never to wait for a spawn. This is
+ * the other half: the loop that notices the turn, leases it, writes a run row,
+ * starts a real agent, and puts what that agent said back on the card.
+ *
+ * ---------------------------------------------------------------------------
+ * ═══ THE DAEMON DOES NOT DECIDE WHAT IS TAKEABLE. THE DATABASE DOES. ═══
+ *
+ * Everything about exclusion lives in `panel3_take_turns()`: the lease, the
+ * "no live level 1 on this card" rule, and the skip-locked that keeps two
+ * daemons polling the same millisecond from both getting one card. There is no
+ * read-then-decide-then-write anywhere in this file, because that shape has a
+ * window between the read and the write and the window is exactly what a second
+ * daemon finds. This file honours what it was handed and nothing else.
+ *
+ * ---------------------------------------------------------------------------
+ * ═══ THE RUN ROW IS WRITTEN BEFORE THE SPAWN, OR THERE IS NO SPAWN. ═══
+ *
+ * plan.md's global constraint 8. A process with no row is a process nothing can
+ * find after a restart: it cannot be shown, cannot be recovered and cannot be
+ * ended, so the card would say working forever with an agent nobody can name.
+ *
+ * IT IS THE TAKE THAT WRITES IT, in the same statement that leases the turns,
+ * which is why this file has no ordering to be careful about: it cannot reach a
+ * spawn without a row, because it cannot reach a spawn without a take. The
+ * earlier version wrote the row here, two round trips after the lease, and both
+ * ends of that gap were holes — a daemon killed inside it stranded the card
+ * forever, and a turn arriving inside it could put a second agent on the same
+ * card. See 20260821140000.
+ *
+ * ---------------------------------------------------------------------------
+ * ═══ THE DAEMON WRITES THE AGENT TURN FROM WHAT THE PROCESS SAID. ═══
+ *
+ * The harness is one-shot: a prompt goes in, text comes out, it exits. That
+ * final text IS the answer, so this writes it as the card's `role='agent'` turn.
+ *
+ * ═══ AND IT IS THE SAME PATH AT EVERY LEVEL, WHICH IS ux.md's RULE, NOT A
+ *     CONVENIENCE. ═══ "Whoever did the work writes the answer. The level 2
+ * agent writes it, straight into the card. It does not hand a summary up to
+ * level 1 to be re-written." A dispatched agent's text goes onto the card
+ * through the same `panel3_answer` its dispatcher's did, so there is nowhere in
+ * this file for one agent's words to pass through another's. The coordinator has
+ * usually ended long before.
+ *
+ * ═══ AND A WORKER'S WORDS DO NOT REACH THE CARD AT ALL, WHICH IS THE SAME RULE
+ *     ONE LEVEL DOWN. ═══ "Each worker writes what it found into the record, and
+ * the level 2 agent reads them back." Three workers writing their own turns
+ * would be three answers to one request, before the one that covers them all
+ * arrives. `panel3_answer` puts a level 3 run's last words in its report instead,
+ * from the level on the row — decided there rather than here, because two owners
+ * for "does this reach the person" is one owner too many.
+ *
+ * ---------------------------------------------------------------------------
+ * ═══ A QUESTION MOVING, AND EVERYBODY YOU SENT FINISHING, ARE BOTH TAKEABLE
+ *     WORK, AND THEY COME THROUGH THE SAME POLL. ═══
+ *
+ * ux.md: "Nothing new is built for this. The daemon already leases takeable work
+ * and spawns. What changes is the definition of takeable." So there is a second
+ * take beside `panel3_take_turns` and nothing else in this file changes shape:
+ * `panel3_take_rearms` hands back runs to start again, for either of the two
+ * reasons ux.md's table gives, and they are started, held and settled by the
+ * functions that already do those things.
+ *
+ * THE SECOND REASON IS THE ONE NOTHING ELSE COULD FIRE. An agent that split its
+ * work dispatched and ended, because it is forbidden to wait; by the time its
+ * workers finish there is no process anywhere holding what they found. Starting
+ * it again is what makes "it reads them back and writes the answer" a mechanism
+ * rather than a sentence.
+ *
+ * IT IS THE SAME MECHANISM AS RECOVERY, POINTED AT A DIFFERENT FACT. A run whose
+ * process died is started again as itself because the machine failed; a run that
+ * asked, or one whose workers are done, is started again as itself because the
+ * thing it was waiting on exists now. Same row, same id, same brief, its report
+ * carried — and the only difference is one paragraph at the top of the prompt.
+ *
+ * ---------------------------------------------------------------------------
+ * ═══ A DISPATCH IS A SPAWN THE DAEMON DOES ON BEHALF OF AN AGENT. ═══
+ *
+ * The tools server runs inside this process and `dispatch` is served from it,
+ * but the spawning is here: writing the row before the process, recording the
+ * pid, waiting for the answer, giving up when the process is gone, and being
+ * held open long enough for `--once` to be honest are all things this file
+ * already does once, and a second copy of them behind a tool would be a second
+ * owner of a child's whole life.
+ *
+ * WHAT IT DOES NOT DO IS WAIT. The tool call returns as soon as the process
+ * exists, and the child's answer settles here, long after the agent that asked
+ * for it has ended. That is ux.md's "level 1 never blocks waiting for it", and it
+ * is why a dispatched run's promise goes into `inFlight` rather than being
+ * awaited by its caller.
+ *
+ * ---------------------------------------------------------------------------
+ * ═══ A CARD MUST NOT SIT LIVE FOREVER. ═══
+ *
+ * If this daemon is killed mid-run its process dies with it, and the run row is
+ * left saying `running` with an end that never comes. `recoverStranded` is what
+ * closes that: on every poll it looks at the runs THIS machine owns and asks the
+ * operating system whether their processes are still there. A level 1 run's
+ * turns are handed back, so they are takeable again; a dispatched run holds no
+ * turns and is STARTED AGAIN AS ITSELF, with the brief it was sent and the
+ * report it wrote. Either way the user's message is answered late rather than
+ * lost.
+ *
+ * It is careful in three directions, and each is a way the sweep can lie: it
+ * never reaps a run this process holds, never reaps a run too young to have
+ * recorded a pid (which is another daemon's live work), and never believes a pid
+ * that predates this machine's boot (which is somebody else's process wearing a
+ * reused number).
+ *
+ * ═══ AND IT CAN ONLY EVER REACH THIS MACHINE'S RUNS, WHICH IS WHY A PERSON HAS
+ *     THE OTHER MOVE. ═══
+ *
+ * A machine that is never coming back sweeps nothing, so its dispatched runs sit
+ * `running` forever. `panel3_hand_back` is the person's answer, pressed from the
+ * panel on a card nothing is listening for, and `takeHandedBack` is this
+ * daemon's half of it: the one read that looks past this machine's own id, so
+ * work another machine was holding is carried on from its brief and its report
+ * instead of being started over. The sweep is not loosened to do it, and which
+ * of the three cares above apply to that read is argued where it is written.
+ */
+// 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 { out, returned, signedInClient } from './client.js';
+import { answerPrompt, escalationPrompt, levelOnePrompt, readBackPrompt, resumePrompt, retryPrompt, } from './prompt.js';
+import { attachmentLine, loadAttachments, loadOutputNames, outputOf } from './show.js';
+import { forgetSecrets, redactSecrets } from './secrets.js';
+import { sayListening, stopListening } from './presence.js';
+import { checkoutForCodebase, hasCheckoutForCodebase } from './checkout.js';
+import { harness, startAgent } from './spawn.js';
+import { startToolsServer } from './tools.js';
+import { getMachineIdentity, scratchDir } from '../config.js';
+import { listCodebases } from '../codebases.js';
+import { processIsAlive } from '../win-shell.js';
+import { hostname, uptime } from 'node:os';
+const USAGE = 'usage: cs3 run [--once]';
+/** How long between takes. Short, because it is the whole delay between a user
+ *  sending and a card showing an agent on it, and the take is one small indexed
+ *  read against the user's own rows. */
+const POLL_INTERVAL_MS = 2_000;
+/**
+ * How long a run with no pid recorded is given before it counts as gone.
+ *
+ * ═══ IT EXISTS BECAUSE `mine` IS ONLY THIS PROCESS'S MEMORY. ═══ The take
+ * writes the run row and the pid lands a moment later, so between the two the
+ * row is indistinguishable from one whose daemon died — to this daemon. To a
+ * SECOND daemon on the same machine it is worse than indistinguishable: the run
+ * is not in its `mine` set at all, so without this it would hand back the turns
+ * of a run that started seconds ago and mark it failed while the agent was
+ * genuinely working. That configuration is not hypothetical; it is what the
+ * lease is proved with.
+ *
+ * Thirty seconds is far longer than the one round trip it has to cover and far
+ * shorter than any run, so it costs a genuinely dead run one extra poll cycle at
+ * most.
+ *
+ * ═══ AND `panel3_resume` HOLDS THE SAME NUMBER, SO IT IS EXPORTED AND CHECKED.
+ * ═══ The claim refuses to hand the same run out twice inside this window, which
+ * is this rule from the other side: a run that has just been claimed has no
+ * process yet and everything else has to leave it alone long enough for one to
+ * exist. Two comments saying they agree is not a check, and the two are in
+ * different languages in different files — so the contract test reads the
+ * interval out of the function definition and compares it to this. Disagreement
+ * either reaps a resume a second after it started, or makes a dead run wait out
+ * two windows.
+ */
+export const PID_GRACE_MS = 30_000;
+/**
+ * How many processes may be started for one run, counting the first.
+ *
+ * ═══ IT IS NOT A NEW NUMBER, AND THAT IS THE REASON FOR IT. ═══
+ * `orchestrator.ts:1107` `MAX_ATTEMPTS = 3` and `orchestrator.ts:4421`
+ * `MAX_REPLY_ATTEMPTS = 3` are the same bound, with the reason already written
+ * down at `orchestrator.ts:1102-1105`: three attempts is enough to ride out a
+ * genuinely transient failure and short enough that a deterministic one stops
+ * costing the user minutes of spawn time, and it is not configurable, because a
+ * knob here would mostly serve to hide a bug behind a bigger number. A fourth
+ * number invented here would be a dialect.
+ *
+ * ═══ AND THE BOUND ITSELF IS NOT THIS CONSTANT. ═══ `panel3_resume` counts the
+ * attempt and refuses past three IN THE SAME STATEMENT, because a bound whose
+ * counter can silently miss an attempt is not a bound
+ * (`20260806120000:1096-1099`). This is the number the daemon says out loud, and
+ * a contract test reads the literal back out of the function definition and
+ * compares the two, exactly as `PID_GRACE_MS` is compared against that
+ * function's 30 seconds.
+ */
+export const MAX_ATTEMPTS = 3;
+/** The level the daemon puts on a card of its own accord. Anything deeper exists
+ *  because an agent asked for it, and its level comes off the row
+ *  `panel3_dispatch` wrote rather than from anything here. */
+const LEVEL = 1;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * ═══ NOTHING IN THIS FILE STAMPS A COLUMN FROM THIS MACHINE'S CLOCK ANY MORE,
+ *     AND THAT IS A RULE RATHER THAN A TIDY-UP. ═══
+ *
+ * `started_at`, `ended_at` and `resumed_at` are all written by the database's own
+ * `now()`, in the statements that end or claim a run, and `panel3_owed_read_back`
+ * COMPARES a parent's end with its children's. A second clock writing any of them
+ * makes that comparison meaningless in a way nothing reports: skew one way hides
+ * the child that genuinely finished last and loses the read-back, with every row
+ * individually plausible. `failRun` was the last place that did it and now calls
+ * `panel3_end_run`.
+ *
+ * ═══ THE TWO CLOCKS STILL MEET IN ONE PLACE, AND IT IS DELIBERATE. ═══
+ * `recoverStranded` reads `started_at`, which the database stamped, and measures
+ * it against `Date.now()` for the pid grace window and against this machine's
+ * boot time for the reused-pid check. It has no choice: liveness is a local fact
+ * and the boot time is only knowable here. Both directions of skew are real:
+ *
+ *   THE DATABASE AHEAD OF LOCAL BY MORE THAN THE GRACE WINDOW makes every
+ *   pid-null run look younger than it is, forever, so nothing is ever reaped —
+ *   which is the permanent strand the recovery exists to prevent.
+ *
+ *   THE DATABASE BEHIND LOCAL BY MORE THAN THIS MACHINE'S UPTIME makes a run
+ *   that started moments ago look older than the boot, so a live agent is
+ *   declared gone and its turns are handed to a second one.
+ *
+ * Considered rather than missed, and left as it is: both machines run NTP — here
+ * they are the same machine, since the local stack is a container on it — so the
+ * skew is milliseconds against a thirty-second window and an uptime measured in
+ * days. A product where the two could drift that far would have to stamp both
+ * clocks and compare like with like.
+ */
+/* ═══ THE NAME A PERSON TYPED, WHICH IS THE ONLY NAME THEY KNOW. ═══ `cs start`
+   is the command in the product's copy everywhere else, and this is the one
+   prefix on the one stream a person actually reads. */
+const said = (what) => console.error(`cs start: ${what}`);
+/**
+ * The taken rows, grouped by card, each card's turns still in send order.
+ *
+ * ═══ THE GROUPING IS WHY THE TAKE RETURNS ROWS AND NOT ONE BODY. ═══ ux.md:
+ * "A turn takes every unaddressed input on that card, oldest first, and hands
+ * them all over. Not the newest. Not one chosen as 'the request'." There is
+ * nowhere in this function for the product to choose between them, which is the
+ * property that matters: v2 chose, and the message it did not choose was filed
+ * as background and never acted on.
+ */
+function byCard(taken) {
+    const cards = new Map();
+    for (const row of taken) {
+        const existing = cards.get(row.card_id);
+        if (existing)
+            existing.push(row);
+        else
+            cards.set(row.card_id, [row]);
+    }
+    return cards;
+}
+/**
+ * ═══ WHAT THIS CARD HAS ALREADY PRODUCED, NAMED AS IT READS NOW. ═══
+ *
+ * A card's receipts are level 1's report: every turn is answered by a fresh
+ * agent that remembers nothing, and what it most needs from the last one is what
+ * that one made. So they are read here and handed over in the prompt, exactly as
+ * a dispatched run's report is, rather than being left behind a tool call — see
+ * `levelOnePrompt` for the measured failure this closes.
+ *
+ * THE NAME IS RESOLVED, NOT READ OFF THE RECEIPT, through the one function
+ * `cs3 show` uses for it. `label` is written when the thing is made and the
+ * coordinator may rename the thing on the next turn; printing the label then
+ * hands the agent the name of a different, real object. One owner for that,
+ * because two would eventually disagree about which name a card is showing.
+ */
+async function receiptsFor(client, cardId) {
+    const outputs = await returned(client
+        .from('panel3_outputs')
+        .select('id, card_id, run_id, kind, ref_id, label, created_at')
+        .eq('card_id', cardId)
+        .order('created_at'), 'read', `what card ${cardId} has produced`);
+    const names = await loadOutputNames(client, outputs);
+    return outputs.map((o) => `${o.kind.padEnd(10)}  ${outputOf(o, names)}   id ${o.ref_id}`);
+}
+/**
+ * ═══ WHAT THE PERSON ATTACHED TO THIS CARD, FORMATTED THE ONE WAY THE PRODUCT
+ *     NAMES AN ATTACHMENT. ═══
+ *
+ * The product applies the attachment (plan-work-items.md constraint 5): level 1
+ * is handed it here rather than asked to go and find it, exactly as `produced`
+ * is handed over rather than left behind `list_work_items`. Most cards have
+ * none, since Task 2 offers attaching only when a card is started, so this is
+ * usually an empty list, and `levelOnePrompt` says nothing about attachments at
+ * all when it is.
+ */
+// Exported so a test can prove the wiring itself: that this reads the CALLER's
+// own card through `loadAttachments` rather than a copy, the same reason
+// `dispatch`'s equivalent read is proven in panel3-tools.contract.test.mjs
+// instead of only the formatter it feeds.
+export async function attachmentsFor(client, cardId) {
+    return (await loadAttachments(client, cardId)).map(attachmentLine);
+}
+/**
+ * What level 1 is sent, and also what is written to `panel3_runs.brief`: the
+ * column's own question is "what was this agent asked", answered with the exact
+ * text it was asked with rather than with a description of it.
+ *
+ * THE WORDS THEMSELVES ARE IN `prompt.ts`, which is where the rules that govern
+ * them are written down. This is only the join: the take hands over rows, the
+ * record says what the card has made, and a prompt is about a title, some
+ * messages and that list.
+ */
+// Exported for the same reason as `attachmentsFor` above: the wiring test
+// calls this with what that function actually returned, so what a coordinator
+// is told is proven to come from the card's own attachment rows rather than
+// only from `levelOnePrompt`'s own formatting tests in panel3-prompt.
+export const briefFor = (title, turns, produced, attachments, codebases = null) => levelOnePrompt(title, turns.map((t) => t.body), produced, attachments, codebases?.map((codebase) => ({
+    id: codebase.id,
+    name: codebase.name,
+    identity: codebase.gitRemoteUrl,
+    located: hasCheckoutForCodebase(codebase),
+})) ?? null);
+// ---------------------------------------------------------------------------
+// WRITES. Every one goes through the shared guard in `client.ts`, which returns
+// the rows or throws. `.select()` on each is what makes that possible: a
+// Supabase write with no select returns neither data nor an error, and the guard
+// refuses that shape rather than reading it as success.
+/**
+ * ═══ WHAT IS RUNNING A RUN, AND — AT LEVEL 1 — WHAT IT WAS SENT. ═══
+ *
+ * The run row already exists in both paths: the take wrote it for level 1 and
+ * `panel3_dispatch` wrote it for a dispatched agent, which is what makes
+ * constraint 8 unconditional rather than an ordering this file has to be careful
+ * about. So this is never the row's creation, only the facts that could not be
+ * known before the process existed.
+ *
+ * THE BRIEF IS PASSED ONLY WHERE IT IS STILL A PLACEHOLDER. The take cannot know
+ * what an agent will be sent, so level 1's row carries a placeholder until here;
+ * a dispatch knows the brief before the row exists and writes it there. Passing
+ * it again would be rewriting a brief that ux.md fixes at dispatch.
+ *
+ * A failure here is NOT fatal. The agent is already running and killing it over
+ * a bookkeeping write would cost the user the work. What is lost is precision:
+ * the run has no pid, so once this daemon is gone recovery treats it as dead —
+ * which errs towards answering again rather than stranding.
+ */
+async function recordProcess(client, runId, pid, brief) {
+    await returned(client
+        .from('panel3_runs')
+        .update({ pid, ...(brief === undefined ? {} : { brief }) })
+        .eq('id', runId)
+        .select('id'), 'record what is running', `run ${runId}`);
+}
+/**
+ * ═══ A RUN GIVEN UP ON: ENDED, ITS TURNS HANDED BACK, ITS CARD IN HAND. ═══
+ *
+ * One statement, in `panel3_give_up`, for the reason 20260821170000 gives at
+ * length: as two round trips there was an instant in which the turns were
+ * takeable and the run still read `running`, and an answer landing in that
+ * instant was accepted onto a card another daemon was already free to take.
+ *
+ * Returns the number of turns handed back, or NULL when the run was no longer
+ * running — which is this function losing cleanly to a `panel3_answer` that got
+ * there first. It is a fact about the record rather than a failure, so it does
+ * not go through `returned()`, exactly as the answer's own null does not.
+ */
+async function giveUp(client, runId, reason) {
+    const { data, error } = await client
+        .rpc('panel3_give_up', { p_run_id: runId, p_reason: reason });
+    if (error)
+        throw new Error(`could not give up run ${runId}: ${error.message}`);
+    /* THE RUN IS OVER, so whatever it read is dropped. Every ending does this —
+       here, `failRun` and `writeAnswer` — because a daemon stays up for days and
+       has no business holding Tuesday's secret. */
+    forgetSecrets(runId);
+    return data;
+}
+/**
+ * ═══ THE ANSWER, THE END OF THE RUN AND THE STATE OF THE CARD ARE ONE
+ *     STATEMENT. ═══
+ *
+ * They are one event, and writing them as three round trips left a window where
+ * the answer was on the card while the run still read running: recovery then
+ * handed the turns back and a second agent answered the same question beside an
+ * answer that was already there. `panel3_answer` is where that window used to be.
+ * It also decides whether the card is DONE, which it is only when nothing else
+ * on it is still live — a coordinator that dispatched and answered must not
+ * settle a card whose work is still going. See 20260823090000.
+ *
+ * ═══ AND IT IS SHARED BY EVERY LEVEL ON PURPOSE. ═══ ux.md's "whoever did the
+ * work writes the answer" is only structurally true if there is exactly one way
+ * for text to reach a card. A second path for dispatched runs is where a
+ * summarising hop would eventually be added.
+ *
+ * ═══ THIS IS THE ONE v3 WRITE THAT DOES NOT GO THROUGH `returned()`. ═══ The
+ * shared guard treats "no error and no data" as a result it does not understand,
+ * which is right everywhere else and wrong here: a null from `panel3_answer` is a
+ * FACT about the record — the run was no longer running, so nothing was written
+ * — and it has its own sentence below. A failure is still a failure and still
+ * throws.
+ *
+ * The run's text is on the card as a turn and is deliberately NOT copied into
+ * `report` as well: one fact, one place. `report` carries the reason on the
+ * failure paths, where there is no turn and it is the only record.
+ *
+ * ═══ AND A RUN WITH NOTHING TO SAY PASSES NULL, WHICH IS NOT THE SAME AS
+ *     SAYING NOTHING. ═══ ux.md's "outbound follows the work": a run started
+ * again only to settle a question from somebody it sent did no work for the
+ * person, and its words went to that agent through the answer. It is still
+ * ended here, and the card is still settled by the same statement, because such
+ * a run can be the last thing live on it — but no turn is written, exactly as
+ * none is written for a run that stopped to ask.
+ */
+async function writeAnswer(client, runId, cardId, text) {
+    /* ═══ THE SECOND OF THE TWO CHOKEPOINTS THE CREDENTIAL RULE RESTS ON. ═══
+       This is the ONE path an agent's own words take to a hosted row — a turn on
+       the card at levels 1 and 2, and a level 3's `panel3_runs.report`, which
+       `panel3_answer` writes instead. Tool arguments are the other, redacted in
+       `buildServer`. Identity for a run that read no credential, so every existing
+       exact-string assertion is byte-identical. */
+    const { data: turnId, error } = await client
+        .rpc('panel3_answer', { p_run_id: runId, p_body: text === null ? null : redactSecrets(runId, text) });
+    if (error) {
+        /* Thrown, not settled as failed. The run stays `running` with a process
+           that has now exited, so recovery reaps it: at level 1 the turns are
+           answered again, so the user gets an answer late instead of a card marked
+           failed for a database hiccup. The caller prints the reason. */
+        throw new Error(`could not write the answer to card ${cardId}: ${error.message}`);
+    }
+    /* ═══ INCLUDING WHEN THE RUN STOPPED TO ASK AND WILL BE STARTED AGAIN. ═══
+       That reads like a mistake and is not: the process is gone, and the one that
+       takes its place is a fresh process with a fresh context which reads the
+       credential again through `get_credential`. What it is handed to start from —
+       its own report, and the card — went through this same substitution, so there
+       is nothing left for a stale entry to protect. */
+    forgetSecrets(runId);
+    if (turnId === null) {
+        /* NO TURN WAS WRITTEN, and there are FOUR reasons, which mean different
+           things and must not be printed as one line.
+    
+           IT STOPPED TO ASK. Its last words were the question, which is already on
+           the card, and its end has just been stamped by the same statement that
+           refused the turn. Nothing is wrong and nothing is lost.
+    
+           IT HAD NOTHING TO SAY TO THE PERSON. A run started only to settle a
+           question from somebody it sent is asked for exactly this, and it is the
+           daemon that asked.
+    
+           IT IS A WORKER, and its words went into its report for whoever sent it.
+           ux.md: one request is one answer, written by the level that owns the card.
+    
+           OR IT WAS NO LONGER RUNNING — recovery had given up on it and, at level 1,
+           its turns belong to another run now. Writing anyway would put a second
+           answer on the card. The process's work is lost, which is the honest cost
+           of having been declared dead.
+    
+           ═══ AND THE STATE IS READ FIRST, WHICH IS THE FIX FOR A LINE THAT USED TO
+           LIE. ═══ The last of the four was reachable with a null body — a re-armed
+           run given up on while its process was still going — and it printed the
+           second one's sentence, "answered a question, so it wrote nothing here",
+           about a run that had been declared dead and written nothing anywhere. So
+           the state gates the two honest sentences rather than sitting under them.
+           It decides nothing except which sentence is true: whichever of the four
+           happened has already happened, in one statement, before this line runs. */
+        const run = await runNow(client, runId);
+        if (run.state === 'asked') {
+            out(`asked    card ${cardId}  run ${runId}  stopped on a question, so it wrote no answer`);
+        }
+        else if (run.state !== 'finished') {
+            said(`run ${runId} was ${run.state}, so its answer was not written to card ${cardId}`);
+        }
+        else if (text === null) {
+            out(`settled  card ${cardId}  run ${runId}  answered a question, so it wrote nothing here`);
+        }
+        else if (run.level === 3) {
+            out(`reported run ${runId}  ${text.length} characters, to whoever sent it`);
+        }
+        else {
+            /* FINISHED, WITH SOMETHING TO SAY, AND NO TURN. It had already answered
+               once, which is the one shape left, and it is said rather than assumed
+               away. */
+            said(`run ${runId} had already ended, so its answer was not written to card ${cardId}`);
+        }
+        return;
+    }
+    out(`answered card ${cardId}  run ${runId}  ${text?.length ?? 0} characters`);
+}
+/** What the record says a run is now, and at what level. Read only to say the
+ *  right sentence about something that has already happened; nothing branches on
+ *  it that could have gone the other way. */
+async function runNow(client, runId) {
+    const runs = await returned(client.from('panel3_runs').select('state, level').eq('id', runId), 'read', `the state of run ${runId}`);
+    return runs[0] ?? { state: 'no longer on the record', level: null };
+}
+/**
+ * A run whose process failed, ended with the reason ON ITS OWN COLUMN, and its
+ * turns left exactly where they are.
+ *
+ * ═══ NEVER INTO `report`, WHICH IS THE RUN'S OWN WORDS. ═══ `report` is what a
+ * respawn is handed, and this build starts settled runs again — an answered
+ * question does exactly that — so a reason written there would destroy the state
+ * the next attempt was going to resume from, and `cs3 show` would print the
+ * daemon's sentence under a heading that says the run wrote it. One owner per
+ * column: the run writes `report`, whoever ended it writes `failed_because`.
+ *
+ * ═══ AND IT IS A STATEMENT RATHER THAN AN UPDATE, BECAUSE `ended_at` IS
+ *     COMPARED AGAINST OTHER ROWS' ENDS. ═══
+ *
+ * This wrote the stamp from THIS MACHINE'S clock, because a PostgREST update has
+ * nowhere to ask for the server's time. Everything else that ends a run —
+ * `panel3_answer`, `panel3_give_up` — uses the database's `now()`, and
+ * `panel3_owed_read_back` measures a parent's end against its children's. So the
+ * two stamps met, and skew between them loses a read-back SILENTLY: a machine
+ * clock running ahead writes a parent's end later than the child that genuinely
+ * outlived it, the comparison finds nobody who finished after it, and the
+ * synthesis never happens with every row individually plausible.
+ *
+ * The header of this file already argues that v3 must not compare two clocks.
+ * This was the one place left that did.
+ */
+async function failRun(client, runId, reason) {
+    /* ═══ ONLY A RUN THAT HAS NOT ALREADY ENDED, AND THAT GUARD IS IN THE
+       STATEMENT. ═══ Unguarded, this wrote over a run that had been started again
+       in the meantime — which is not hypothetical now that an answered question
+       restarts a settled row — and marked a live agent failed. False is a fact the
+       caller reports, not a failure. */
+    const { data, error } = await client
+        .rpc('panel3_end_run', { p_run_id: runId, p_reason: reason });
+    if (error)
+        throw new Error(`could not end run ${runId}: ${error.message}`);
+    forgetSecrets(runId);
+    return data === true;
+}
+/**
+ * What the card is doing, written by the daemon.
+ *
+ * ═══ EXCEPT ON A CARD THE USER STOPPED, WHICH NOTHING HERE MAY OVERWRITE. ═══
+ * ux.md: the user's Stop is absolute. Its own effect is the reason this guard is
+ * needed rather than a precaution. `panel3_stop_card` ends the runs, this daemon
+ * kills their processes, and the level 1 agent then exits badly, which is the
+ * one path in this file that writes a card `failed`. Without the predicate the
+ * user presses Stop and the card reads Failed a second later, about a failure
+ * that never happened.
+ *
+ * Every other card write already carries the guard in SQL: `panel3_answer` and
+ * `panel3_give_up` both refuse a run that is not live, and a stopped run is not.
+ */
+async function setCardState(client, cardId, state) {
+    await returned(client
+        .from('panel3_cards')
+        .update({ state })
+        .eq('id', cardId)
+        .neq('state', 'stopped')
+        .select('id'), 'set the state of', `card ${cardId}`);
+}
+// ---------------------------------------------------------------------------
+/**
+ * One card, from the turns the take handed over to the answer on its thread.
+ *
+ * ═══ THERE IS NOTHING TO UNDO HERE, AND THAT IS THE POINT. ═══ The take wrote
+ * the run row in the same statement that leased the turns, so this function is
+ * never in the position of holding a lease it cannot honour: whatever it fails
+ * at, the row exists, `cs3 show` can see it, and recovery can reach it. The
+ * earlier version wrote the row two round trips later and had to hand the turns
+ * back on failure — which covered a thrown error and not a kill, and a kill in
+ * that window stranded the card forever.
+ *
+ * ═══ AND WHAT HAPPENS WHEN THE PROCESS IS OVER IS `settle`'s, NOT THIS
+ *     FUNCTION'S. ═══ It used to be written out again here, and the two copies
+ * were already the same thing said twice: the agent's words onto the card
+ * through `writeAnswer`, or the run ended with its reason. recovery Slice 3 gave
+ * that moment a second job, starting a process that died badly all over again,
+ * and a second copy of THAT is two features owning one respawn, which is the
+ * failure recovery-1/ux.md names in as many words. So there is one owner, and
+ * the level is what tells it how a run of this shape ends.
+ */
+async function answerCard(client, tools, machineId, cardId, turns) {
+    const runId = turns[0].run_id;
+    /* BEFORE THE SPAWN, AND ITS FAILURE IS THE SPAWN'S FAILURE. The receipts are
+       part of what the agent is sent, so a read that fails must not be papered
+       over with an empty list: that reads as a card that has made nothing, which
+       is how an agent creates a second epic beside the one it cannot see. The
+       attachments read carries the same rule: a failed read here must not read
+       as "nothing is attached", which is a different card than the one that was
+       actually sent. */
+    const brief = briefFor(turns[0].card_title, turns, await receiptsFor(client, cardId), await attachmentsFor(client, cardId), await codebasesForRun(client, runId));
+    /* ═══ THE RUN ID IS ON THE URL, AND THAT IS THE WHOLE OF WHAT THE AGENT IS
+       TOLD ABOUT ITS OWN STANDING. ═══ The tools server reads the level off the
+       run row this id names, so the daemon does not tell the child what it may do
+       and the child has nothing to claim. `LEVEL` below decides argv only — which
+       of the harness's own tools the process gets — and the two can never disagree
+       about the record, because only one of them consults it. */
+    /* AN EMPTY DIRECTORY OF THE USER'S OWN, because level 1 has no code tool to
+       use a real one with, and the daemon's inherited cwd under a launchd login
+       item is the filesystem root. */
+    const started = startAgent(brief, LEVEL, tools.urlFor(runId), scratchDir());
+    out(`run      ${runId}  level ${LEVEL}  ${started.pid ? `pid ${started.pid}` : 'no process'}`);
+    try {
+        await recordProcess(client, runId, started.pid, brief);
+    }
+    catch (error) {
+        // Said, not fatal. See `recordProcess` for what this costs and why the
+        // agent is not killed over it.
+        said(`${error instanceof Error ? error.message : String(error)} (the run is still going)`);
+    }
+    return settle(client, tools, machineId, LEVEL, runId, cardId, started);
+}
+/**
+ * WHICH PROJECT A RUN'S CARD IS FILED UNDER, or null when the card has none.
+ *
+ * ═══ ASKED OF THE RECORD AT EVERY SPAWN, RATHER THAN CARRIED. ═══ The card is
+ * the durable object and its project can change between one dispatch and the
+ * next; a value threaded through the daemon would be the state of the card when
+ * the daemon last looked. It is one indexed read on the path that is about to
+ * start a whole agent.
+ *
+ * ═══ AND A FAILED READ IS NOT "NO PROJECT". ═══ `returned` throws, which the
+ * caller turns into a dispatch that did not happen. Returning null here would
+ * quietly send the agent to the machine-wide fallback checkout, which is another
+ * project's code.
+ */
+async function projectOfRun(client, runId) {
+    const rows = await returned(client.from('panel3_runs').select('card:panel3_cards(project_id)').eq('id', runId), 'read', 'which project this run belongs to');
+    return rows[0]?.card?.project_id ?? null;
+}
+async function codebasesForRun(client, runId) {
+    const projectId = await projectOfRun(client, runId);
+    return projectId ? listCodebases(client, projectId) : null;
+}
+async function codebaseOfRun(client, runId) {
+    const rows = await returned(client
+        .from('panel3_runs')
+        .select('codebase_id, card:panel3_cards(project_id)')
+        .eq('id', runId), 'read', `which codebase run ${runId} belongs to`);
+    const row = rows[0];
+    if (!row?.codebase_id || !row.card?.project_id) {
+        throw new Error('This code work does not name a registered project codebase.');
+    }
+    const codebase = (await listCodebases(client, row.card.project_id))
+        .find((candidate) => candidate.id === row.codebase_id);
+    if (!codebase) {
+        throw new Error('The selected codebase is no longer registered on this project.');
+    }
+    return codebase;
+}
+/**
+ * ═══ ONE AGENT, STARTED UNDER ANOTHER THAT IS STILL RUNNING. ═══
+ *
+ * Called from the `dispatch` tool, and it returns as soon as the process exists.
+ * The promise it hands back settles long afterwards, and the caller puts it
+ * where the daemon can wait on it rather than awaiting it itself: an agent that
+ * waited for the work it started would hold its own run open for the length of
+ * it, which is the thing ux.md forbids in as many words.
+ *
+ * ═══ THE ORDER IS THE WHOLE CORRECTNESS ARGUMENT. ═══ The working copy is
+ * resolved FIRST, before anything is written, so a machine that has none refuses
+ * the dispatch rather than leaving a run row no process ever corresponded to.
+ * Then the row, then the process, then the pid — constraint 8, in the only order
+ * that satisfies it.
+ */
+async function startChild(client, tools, machineId, parentRunId, brief, codebase) {
+    const { data, error } = await client.rpc('panel3_dispatch', {
+        p_parent_run_id: parentRunId,
+        p_brief: brief,
+        p_machine_id: machineId,
+        p_codebase_id: codebase.id,
+        p_codebase_label: codebase.name,
+    });
+    if (error)
+        throw new Error(`could not start an agent under run ${parentRunId}: ${error.message}`);
+    const row = data?.[0];
+    if (!row) {
+        /* NOTHING WAS WRITTEN AND NOTHING IS RUNNING, and the two reasons are said
+           together because the caller cannot tell them apart from here and both mean
+           the same thing to it. */
+        throw new Error(`NO AGENT WAS STARTED and nothing was written: run ${parentRunId} has ended, or it is already `
+            + 'as deep as anything may be sent from.');
+    }
+    if (row.run_level !== 2 && row.run_level !== 3) {
+        /* UNREACHABLE, AND STILL SETTLED. `panel3_dispatch` writes `parent.level + 1`
+           from a parent it has just checked is below 3, so there is no level here
+           this cannot spawn. If that ever stops being true, the row exists and
+           nothing will ever start for it, and leaving it `running` would make a
+           recovery sweep wait out the pid grace window to conclude what is already
+           known. */
+        const why = `run ${row.run_id} was written at level ${row.run_level}, which cannot be spawned`;
+        await giveUp(client, row.run_id, why);
+        throw new Error(why);
+    }
+    const level = row.run_level;
+    let cwd;
+    try {
+        cwd = checkoutForCodebase(codebase, hostname());
+    }
+    catch (error) {
+        const why = error instanceof Error ? error.message : String(error);
+        await giveUp(client, row.run_id, why);
+        throw new Error(`NO AGENT IS RUNNING: ${why}`);
+    }
+    const started = startAgent(brief, level, tools.urlFor(row.run_id), cwd);
+    if (started.pid === null) {
+        /* THERE IS A ROW AND THERE IS NO PROCESS, which is the one shape the record
+           must never be left in quietly. The answer is already settled — nothing ran
+           — so the reason is read off it, the run is ended with that reason on it,
+           and the tool call fails saying no agent was started. */
+        const answer = await started.answered;
+        const reason = answer.ok ? 'the process ended before it could be identified' : answer.reason;
+        await giveUp(client, row.run_id, reason);
+        throw new Error(`NO AGENT IS RUNNING: ${reason}`);
+    }
+    out(`dispatch run ${row.run_id}  level ${level}  under ${parentRunId}  pid ${started.pid}`);
+    try {
+        await recordProcess(client, row.run_id, started.pid);
+    }
+    catch (error) {
+        // Said, not fatal, exactly as at level 1: the agent is running and killing
+        // it over a bookkeeping write would cost the user the work.
+        said(`${error instanceof Error ? error.message : String(error)} (the run is still going)`);
+    }
+    return {
+        runId: row.run_id,
+        settled: settle(client, tools, machineId, level, row.run_id, row.run_card_id, started),
+    };
+}
+/**
+ * HOW MANY PROCESSES HAVE BEEN STARTED FOR THIS RUN, counting the first.
+ *
+ * ═══ IT SUPPLIES THE NUMBER IN THE SENTENCE, NOT THE BOUND. ═══ The bound is
+ * `panel3_resume`'s own predicate, counted and tested in the statement that
+ * grants the attempt, so a read here that is a moment out of date cannot grant
+ * an attempt the record refuses. The worst it can do is decline one the record
+ * would have allowed, which is a run that fails a spawn early rather than a
+ * fourth process nobody bounded.
+ *
+ * A row that is not there is not "one attempt". It is a run this daemon can
+ * neither retry nor fail, because there is nothing left to write to, and saying
+ * so is the caller's business rather than this function's to paper over.
+ */
+async function attemptsSoFar(client, runId) {
+    const rows = await returned(client.from('panel3_runs').select('attempts').eq('id', runId), 'read', `how many times a process has been started for run ${runId}`);
+    const row = rows[0];
+    if (!row)
+        throw new Error(`run ${runId} is not there, so nothing can be recorded about it`);
+    return row.attempts;
+}
+/**
+ * ═══ ONE RUN, ENDED WITH ITS REASON, THE WAY A RUN OF ITS LEVEL ENDS. ═══
+ *
+ * There are two endings and the difference is not a preference, it is what the
+ * run is holding.
+ *
+ * A DISPATCHED RUN HOLDS NO LEASED TURNS. `panel3_give_up` hands nothing back
+ * and puts the card in `failed`, because nothing on that card will pick this
+ * piece of work up again unless a question outstanding somewhere else on it says
+ * work is genuinely coming back.
+ *
+ * A LEVEL 1 RUN HOLDS THE PERSON'S MESSAGE. Giving up hands it back for the next
+ * `panel3_take_turns` to lease to A BRAND NEW RUN, which is recovery's whole
+ * point when the MACHINE is gone and is the wrong ending everywhere else: a new
+ * run is a new `attempts`, so the bound below would never be spent, a harness
+ * that fails every time would be started again forever, and a coordinator that
+ * had already dispatched workers would dispatch them a second time. So level 1
+ * ends through `panel3_end_run`, which hands no turns back, and the card says
+ * failed.
+ *
+ * ═══ AND THE FORK LIVES HERE AND NOWHERE ELSE. ═══ FIVE places end a run this
+ * way: the settle, and the two failures after the claim in each of `resumeRun`
+ * and `startRearmed`. A copy of this rule in each is five places for it to
+ * drift, and it drifted the first time it could: those two functions hold the
+ * same pair of endings and only one pair was looked at.
+ *
+ * ALL FIVE CAN SEE LEVEL 1. `resumeRun` serving the retry is what opened its
+ * two. `startRearmed`'s were always reachable, because a re-arm has always
+ * served level 1, and were always ending one the way a dispatched run ends. The
+ * bound is what made that matter: a handed-back message is leased to a NEW run,
+ * whose attempts start again at one.
+ *
+ * ═══ AND THE GIVE-UPS THAT ARE NOT HERE ARE NOT OVERSIGHTS. ═══ `startChild`'s
+ * two end a dispatched run by construction, since a dispatch writes its parent's
+ * level plus one and there is no parent below level 1. The bad-level branches in
+ * `resumeRun` and `startRearmed` hold a level that is by definition none of the
+ * three, so there is no fork to make. And `recoverStranded` gives a level 1 run
+ * up ON PURPOSE, handing its message back, which is the whole of how another
+ * machine takes over a run whose machine is gone.
+ *
+ * Returns whether THIS call is what ended it. False is a fact about the record,
+ * not a failure: the run had already ended, and the caller says so.
+ */
+async function endRun(client, level, runId, cardId, why) {
+    if (level !== 1)
+        return (await giveUp(client, runId, why)) !== null;
+    /* ═══ THE RUN FIRST, AND THE CARD ONLY IF THIS RUN WAS STILL THE CARD'S TO
+       FAIL. ═══
+       The card used to be written first, and the argument for that was a daemon
+       killed between the two: it left a card reading `failed` beside a run that
+       still read running with a dead process, which the record's own forbidden
+       state check reports and recovery corrects. THE PREEMPTION MAKES THAT ORDER A
+       LIE THAT NOTHING CORRECTS. A coordinator the person's next message replaced
+       is `stopped`, its process is killed by this same daemon, and it arrives here
+       having failed: writing the card `failed` then marks the card that a FRESH
+       coordinator is working on, about a run nobody is waiting for.
+       `panel3_end_run` is what knows the difference, because it refuses a run that
+       has already ended, so its answer is what the card write waits for.
+       WHAT THE ORDER COSTS is a daemon killed between the two, which leaves the
+       run `failed` and the card still reading `working` with nothing on it. The
+       product raises that as a forbidden state on the card itself, and the
+       person's next message takes the card again. That is a smaller and louder
+       wrong than a card marked failed under an agent that is working. */
+    const ended = await failRun(client, runId, why);
+    if (ended)
+        await setCardState(client, cardId, 'failed');
+    return ended;
+}
+/**
+ * ═══ THE END OF ONE RUN'S PROCESS, WHICHEVER SPAWN STARTED IT. ═══
+ *
+ * One owner for what happens when an agent's process exits, because there are
+ * four ways one comes to exist, being a card taken, a `dispatch`, a resume of a
+ * run whose process was found gone, and a re-arm, and they end identically. A
+ * second copy would be a second answer to "what does a dead agent mean", and the
+ * first thing to drift would be whether the card is told.
+ *
+ * ═══ `speaksToTheCard` IS THE ONE THING THAT DIFFERS ON THE WAY IN, AND IT IS
+ *     ux.md's RULE RATHER THAN A SETTING. ═══ "Outbound follows the work." A run
+ * started again only to settle a question from somebody it sent did no work for
+ * the person: its words went to that agent, through the answer, and putting them
+ * on the card as well is a voice in a conversation the person did not ask to
+ * follow. It is still ended, and the card is still settled, because it can be
+ * the last thing live on it.
+ *
+ * ═══ AND `level` IS THE ONE THING THAT DIFFERS ON THE WAY OUT, WHICH IS
+ *     `endRun`'s. ═══ It is above, with the whole argument: a dispatched run
+ * holds no leased turns and a level 1 run holds the person's message, so they
+ * cannot end the same way. What `answerCard` always did is what level 1 still
+ * does, and the only thing that has moved is where it is written.
+ */
+function settle(client, tools, machineId, level, runId, cardId, started, speaksToTheCard = true) {
+    return started.answered.then(async (answer) => {
+        /* ═══ A RUN THAT STOPPED TO ASK DID NOT DIE, WHATEVER THE HARNESS PRINTED
+           ON ITS WAY OUT. ═══
+    
+           ux.md: asking is TERMINAL for the agent that asks. It calls the tool, is
+           told "you have stopped", and exits — and it owes the person nothing more,
+           because its last words were the question and the question is already on
+           the card. So a harness that exits having said nothing to the person has
+           done exactly what it was told to.
+    
+           `codexAnswer` reads that silence as a death (`spawn.ts`: "codex exited 0
+           without saying anything to the person"), which is the right reading of
+           every OTHER silent exit and the wrong one of this one. Claude happens to
+           emit a closing message after the tool call and Codex does not, so without
+           this the same question asked under the two harnesses ends two different
+           ways: answerable on one, and on the other retried twice and then FAILED
+           with the question still sitting open on a failed card.
+    
+           ═══ SO THE RECORD DECIDES IT, NOT THE STDOUT. ═══ Whether a run asked is a
+           column, written by `panel3_ask` in the same statement that stopped the
+           run, and it is true or false identically for both harnesses. Read only on
+           the failure path, where it is the one thing that can turn a death back
+           into an ordinary ending, and then handed to `writeAnswer` — which already
+           owns this case and already prints its sentence — rather than to a second
+           ending written here beside it. */
+        if (!answer.ok && (await runNow(client, runId)).state === 'asked') {
+            await writeAnswer(client, runId, cardId, null);
+            return;
+        }
+        if (!answer.ok) {
+            /* ═══ A PROCESS THAT STARTED AND THEN DIED BADLY IS STARTED AGAIN. ═══
+               recovery-1/ux.md, Slice 3: "the agent's harness fails on something that
+               is nobody's fault: a rate limit, a dropped connection, a provider
+               outage. The product tries again rather than failing the card."
+      
+               `started.pid` IS THE WHOLE OF THE DISTINCTION, and it is a fact rather
+               than a reading of a string. What reaches here as `{ ok: false }` is
+               never a verdict about the work. An agent that ran and concluded it
+               could not do the thing exits 0 having said so, and that is an ANSWER,
+               written to the card below. So what is left to separate is a process that
+               ran and died from one that never existed, and `Started.pid` answers it:
+               `could not start claude on this machine: ENOENT` and `claude is not
+               installed` are facts about this machine that will be identical in two
+               seconds and are fixed by a person, while `claude exited 1: API Error:
+               529 Overloaded` is what a rate limit, a dropped connection and a
+               provider outage all look like from here. plan-slice-3.md section 1.2
+               measured the alternative and rejected it: the provider's own words reach
+               this daemon as a 500 character tail of one of two streams, absent
+               entirely for a rate limit, and different again next release.
+      
+               WHAT THIS DELIBERATELY GIVES UP is that a genuinely deterministic
+               harness crash costs two extra spawns before the card fails. That is
+               bounded, and it is the price of not depending on a string.
+      
+               THE RESPAWN IS `resumeRun`, WHICH ALREADY EXISTS. ux.md: "two features
+               owning one respawn is how two respawns are born." Nothing new starts a
+               process here; the failure calls the sweep's own respawn, fenced by the
+               pid this daemon watched exit, and AWAITS it, so the daemon's one
+               `inFlight` entry covers the whole chain and `--once` waits for the last
+               attempt rather than exiting mid-retry.
+      
+               AND THE OLD RULING HERE IS AMENDED RATHER THAN DELETED. It read: "a
+               process that started and then failed is a failure of the work, not of
+               the machine: resuming it would put the same agent back on the same brief
+               to fail the same way, FOREVER." The half that survives is forever, and
+               the bound is what now provides it. */
+            const attempts = await attemptsSoFar(client, runId);
+            if (started.pid !== null && attempts < MAX_ATTEMPTS) {
+                out(`retry    run ${runId}  attempt ${attempts} of ${MAX_ATTEMPTS} died: ${answer.reason}`);
+                const again = await resumeRun(client, tools, machineId, runId, started.pid);
+                if (again)
+                    return again.settled;
+                /* ═══ THE CLAIM MATCHED NOTHING, AND THAT IS NOT ALWAYS SOMEBODY ELSE
+                   HOLDING THIS RUN, SO THE FAILURE IS STILL WRITTEN. ═══
+                   Six predicates can refuse a retry and two of them mean NOTHING HAS
+                   MOVED AT ALL. `pid is null` is the ordinary one, and not exotic:
+                   `recordProcess` is caught and carried on from at all four spawn sites
+                   precisely because that write is expected to be able to fail, and when
+                   it does, the process still ran and still died with a reason nobody
+                   else has. `attempts` reaching the bound between the read above and the
+                   claim is the other. RETURNING HERE WOULD LEAVE THE RUN `running` WITH
+                   A DEAD PROCESS AND THE CARD STILL SAYING WORKING, and the sentence a
+                   person eventually read would be the next sweep's guess about a daemon
+                   that never recorded a pid rather than the harness's own words.
+        
+                   SO IT FALLS THROUGH, AND THE ENDING IS THE ONE THIS PATH HAD BEFORE
+                   THE RETRY EXISTED. A run that ended or stopped under this daemon is
+                   refused by `panel3_end_run` and `panel3_give_up` on their own
+                   predicates, and that refusal is said below rather than recorded. A run
+                   another machine has taken over is not: neither ending is fenced by the
+                   machine or the pid, so this daemon ends it, exactly as it did before
+                   this slice. That is a property of the ending rather than of the retry,
+                   it is narrower than it was (the claim is fenced, so no second PROCESS
+                   starts), and closing it is a change to what a give-up may write. */
+                said(`run ${runId} could not be started again, so it is ending on: ${answer.reason}`);
+            }
+            /* ═══ AND WHEN THE BOUND IS SPENT THE CARD FAILS AND SAYS HOW MANY
+               ATTEMPTS IT TOOK. ═══ ux.md asks for that in as many words. It is said
+               once, here, into the `failed_because` column the panel and the terminal
+               both already read, so the count reaches a person from one place rather
+               than two. */
+            const why = attempts > 1 ? `${answer.reason} (after ${attempts} attempts)` : answer.reason;
+            const ended = await endRun(client, level, runId, cardId, why);
+            if (!ended) {
+                /* IT WAS ALREADY SETTLED, by recovery, which decided this process was
+                   gone before it said so itself, or by the person's Stop. Nothing was
+                   written here, and that is said rather than reported as a failure this
+                   daemon recorded. */
+                said(`run ${runId} had already ended, so nothing was recorded: ${why}`);
+                return;
+            }
+            out(level === 1
+                ? `failed   card ${cardId}  run ${runId}  ${why}`
+                : `failed   run ${runId}  ${why}`);
+            return;
+        }
+        /* ═══ ITS OWN WORDS, ONTO THE CARD, THROUGH THE SAME STATEMENT EVERY LEVEL
+           USES. ═══ Nothing reads them, nothing shortens them and nothing waits to
+           approve them: ux.md's "whoever did the work writes the answer". */
+        await writeAnswer(client, runId, cardId, speaksToTheCard ? answer.text : null);
+    });
+}
+/**
+ * ═══ ONE RUN, STARTED AGAIN AS ITSELF, WITH WHAT IT WAS SENT AND WHAT IT HAD
+ *     GOT AS FAR AS. ═══
+ *
+ * ux.md: "a respawned agent reads three things: its brief, its own report, and
+ * whatever is new", and all three arrive in the prompt because "an agent cannot
+ * fail to read its own input".
+ *
+ * ═══ THE SAME ROW, WHICH IS THE PART THAT MATTERS. ═══ Its children point at
+ * this id. A new row would be a run whose children belong to a dead parent, and
+ * the agent would dispatch them again — the failure ux.md names as the single
+ * most expensive one observed. Nothing is inserted here for the same reason
+ * nothing needs to be: constraint 8 is satisfied by a row that already exists.
+ *
+ * ═══ TWO CALLERS, AND `afterPid` IS THE WHOLE OF WHAT SEPARATES THEM. ═══
+ *
+ * NULL is the sweep, which INFERS that a process is gone from a pid the
+ * operating system no longer knows: `recoverStranded` and `takeHandedBack`. It
+ * behaves exactly as it always has, level 1 refused and the claim window
+ * enforced, and it does not spend an attempt, because a laptop that slept is not
+ * a provider that failed.
+ *
+ * A PID is the retry, made by the daemon that WATCHED that process exit. It may
+ * resume any level, it is fenced by the pid rather than by the window, and the
+ * claim counts the attempt and refuses past three. See 20260909090000 for why
+ * each of those three predicates is about the sweep and not about a failure this
+ * daemon saw with its own eyes.
+ *
+ * recovery-1/ux.md is why there is one function and not two: "two features
+ * owning one respawn is how two respawns are born."
+ *
+ * ═══ AND THE ORDER IS THE SAME ARGUMENT `startChild` MAKES, ON THE SWEEP'S
+ *     PATH. ═══ The working copy is resolved BEFORE the claim, so a machine that
+ * has none refuses without having taken a run it cannot start; then the claim,
+ * then the process, then the pid.
+ *
+ * ON THE RETRY'S PATH IT CANNOT BE, AND THAT IS `startRearmed`'s SITUATION
+ * EXACTLY. A level 1 run works in an empty directory of the user's own and
+ * anything deeper gets the working copy, and the level is not known until the
+ * claim returns. So the resolution happens after the claim, and a failure there
+ * ends the run with its reason rather than leaving a claimed run sitting
+ * `running` with no process. The sweep's ordering is untouched, because its
+ * argument still holds there.
+ *
+ * ═══ THE CHILDREN ARE READ AFTER THE CLAIM AND AS LATE AS POSSIBLE. ═══ They
+ * are the volatile half: one of them may finish while this function is running,
+ * and the prompt says out loud that the list is a moment old and is re-readable.
+ * Carrying them in the report instead is the thing ux.md forbids outright.
+ *
+ * Returns null when the claim matched nothing, which is a fact about the record
+ * rather than a failure: nothing was started here. On the sweep's path that
+ * means another daemon got there first. On the retry's it means the same thing
+ * said by the pid having moved, OR that this run has had its three processes and
+ * the record refuses a fourth, and the caller is the one that knows what to say
+ * about the failure it was holding.
+ */
+async function resumeRun(client, tools, machineId, runId, afterPid) {
+    /* ═══ THE SWEEP RESOLVES ITS WORKING COPY BEFORE THE CLAIM AND THE RETRY
+       CANNOT, AND `afterPid` IS THE WHOLE OF WHAT DECIDES IT. ═══ Said once, here.
+       See the header for both halves of the argument: a machine with no checkout
+       must not take a run it cannot start, and the level a retry needs the answer
+       for is not known until the claim returns. */
+    const sweptCwd = afterPid === null
+        ? checkoutForCodebase(await codebaseOfRun(client, runId), hostname())
+        : null;
+    const { data, error } = await client.rpc('panel3_resume', {
+        p_run_id: runId,
+        p_machine_id: machineId,
+        p_after_pid: afterPid,
+    });
+    if (error)
+        throw new Error(`could not start run ${runId} again: ${error.message}`);
+    const claimed = data?.[0];
+    if (!claimed)
+        return null;
+    const level = claimed.run_level === 1 ? 1 : claimed.run_level === 2 ? 2 : 3;
+    if (claimed.run_level !== level) {
+        /* UNREACHABLE, AND STILL SETTLED, exactly as in `startChild`: the level
+           column is checked at three, so there is no level here this cannot spawn.
+           The claim has already happened, so leaving it would strand the run for a
+           whole grace window before anything looked at it again. */
+        const why = `run ${runId} is at level ${claimed.run_level}, which cannot be spawned`;
+        await giveUp(client, runId, why);
+        throw new Error(why);
+    }
+    /* NON-NULL EXACTLY WHEN THE SWEEP RESOLVED ONE, which is the rule stated at
+       the assignment above. Branching on the VALUE rather than testing `afterPid`
+       a second time is what keeps the resolution and its use from being able to
+       disagree: whatever the sweep resolved is what the sweep runs in. */
+    let cwd;
+    if (sweptCwd !== null) {
+        cwd = sweptCwd;
+    }
+    else {
+        try {
+            cwd = level === 1
+                ? scratchDir()
+                : checkoutForCodebase(await codebaseOfRun(client, runId), hostname());
+        }
+        catch (error) {
+            /* ═══ THE REASON IS WRITTEN TO THE DATABASE, SO IT MAY NOT CARRY A PATH.
+               ═══ Constraint 6, and `startRearmed`'s own handling of the same two
+               calls: `workingCopy()` is already careful about this and says so;
+               `scratchDir()` is not, because it is `mkdirSync`, whose EACCES and
+               ENOTDIR messages name the directory they failed on. So the machine's own
+               error is kept for stderr and the record is told only what is true and
+               shareable. */
+            const stderrOnly = error instanceof Error ? error.message : String(error);
+            const why = level === 1
+                ? 'this machine could not make the empty directory this runs in'
+                : stderrOnly;
+            /* ═══ AND IT ENDS THE WAY A RUN OF THIS LEVEL ENDS. ═══ It was
+               `panel3_give_up` outright, which was right while only a dispatched run
+               could reach this function and is a leak now that the retry brings level
+               1 here: handing the person's message back mints a new run with its
+               attempts at one, which is the bound the retry is under, undone by the
+               one path that could not start. See `endRun`. */
+            await endRun(client, level, runId, claimed.run_card_id, why);
+            throw new Error(`NO AGENT IS RUNNING: ${level === 1 ? stderrOnly : why}`);
+        }
+    }
+    /* WHAT IT SENT OTHERS TO DO, FROM THE RECORD. Level 3 has no `dispatch`, so it
+       has no children to have: null says that, where an empty list would say it
+       chose to send nobody.
+  
+       ═══ AND LEVEL 1 HAS THEM TOO, WHICH ONLY THE RETRY CAN REACH. ═══ This read
+       used to be `level === 2`, which was correct only because nothing at level 1
+       ever got here. Left alone it would hand a coordinator a null child list, and
+       a coordinator that came back to no children dispatches its workers a second
+       time: ux.md's single most expensive failure. `startRearmed` reads it the
+       same way, for the same reason. */
+    const children = level === 3 ? null : await childrenOf(client, runId);
+    const started = startAgent(
+    /* ═══ WHY IT DIED IS WHAT DIFFERS, AND IT IS TOLD THE TRUTH ABOUT IT. ═══
+       `resumePrompt` opens by saying the machine went down, which is true of the
+       sweep and false of a retry: the daemon that watched this harness exit is
+       still running. See `retryPrompt`. */
+    afterPid === null
+        ? resumePrompt(claimed.run_brief, claimed.run_report, children)
+        : retryPrompt(claimed.run_brief, claimed.run_report, children), level, tools.urlFor(runId), cwd);
+    if (started.pid === null) {
+        /* THE CLAIM HAPPENED AND NO PROCESS DID, which is the one shape the record
+           must never be left in quietly. Same handling as a dispatch that could not
+           start: the reason is read off the settled answer and the run is ended with
+           it. */
+        const answer = await started.answered;
+        const reason = answer.ok ? 'the process ended before it could be identified' : answer.reason;
+        // The same level fork, for the same reason. See `endRun`.
+        await endRun(client, level, runId, claimed.run_card_id, reason);
+        throw new Error(`NO AGENT IS RUNNING: ${reason}`);
+    }
+    out(`resume   run ${runId}  level ${level}  pid ${started.pid}  `
+        + `${claimed.run_report === null ? 'no report to carry' : 'carrying its report'}`);
+    try {
+        await recordProcess(client, runId, started.pid);
+    }
+    catch (error) {
+        // Said, not fatal, as everywhere else: the agent is running and killing it
+        // over a bookkeeping write would cost the user the work a second time.
+        said(`${error instanceof Error ? error.message : String(error)} (the run is still going)`);
+    }
+    return { settled: settle(client, tools, machineId, level, runId, claimed.run_card_id, started) };
+}
+/**
+ * ═══ ONE RUN, STARTED AGAIN BECAUSE SOMETHING IT WAS WAITING ON EXISTS NOW. ═══
+ *
+ * The other half of `resumeRun`, and deliberately the same shape: same row, same
+ * id, same brief, the report carried, the children read live. Two facts differ,
+ * and both come off the row `panel3_take_rearms` handed over.
+ *
+ *   WHAT IS NEW. The answer to this run's own question, a question from somebody
+ *   it sent that it has to answer or pass on, or everybody it sent having
+ *   finished. `ask_id` and `mine` say which, and they are the record's word
+ *   rather than an inference here.
+ *
+ *   WHERE IT RUNS. A level 1 run is started in an empty directory of the user's
+ *   own, because level 1 has no code tool to use a real one with; anything deeper
+ *   gets the working copy. That is `answerCard` and `startChild`'s rule, and this
+ *   is the one path that can be handed either.
+ *
+ * ═══ THE CLAIM HAS ALREADY HAPPENED WHEN THIS IS CALLED, SO A FAILURE ENDS THE
+ *     RUN RATHER THAN LEAVING IT. ═══ `panel3_take_rearms` stamps the claim in the
+ * same statement that makes it — the question delivered, and the run's end
+ * cleared — which is what stops two daemons starting two processes for it and
+ * what stops one question, or one set of finished workers, spawning forever. The cost is that this cannot decline afterwards: a run claimed and not
+ * started would sit `running` with no process and its question already spent. So
+ * every failure below ends the run with its reason, which is visible on the card
+ * and in `cs3 show`, rather than quietly hoping the next poll finds it.
+ */
+async function startRearmed(client, tools, machineId, row) {
+    const level = row.run_level === 1 ? 1 : row.run_level === 2 ? 2 : 3;
+    if (row.run_level !== level) {
+        const why = `run ${row.run_id} is at level ${row.run_level}, which cannot be spawned`;
+        await giveUp(client, row.run_id, why);
+        throw new Error(why);
+    }
+    let cwd;
+    try {
+        cwd = level === 1
+            ? scratchDir()
+            : checkoutForCodebase(await codebaseOfRun(client, row.run_id), hostname());
+    }
+    catch (error) {
+        /* ═══ THE REASON IS WRITTEN TO THE DATABASE, SO IT MAY NOT CARRY A PATH.
+           ═══ Constraint 6. `workingCopy()` is already careful about this and says
+           so; `scratchDir()` is not — it is `mkdirSync`, whose EACCES and ENOTDIR
+           messages name the directory they failed on — and `failed_because` is a
+           column `cs3 show` prints. So the machine's own error is kept for stderr
+           and the record is told only what is true and shareable. */
+        const said = error instanceof Error ? error.message : String(error);
+        const why = level === 1
+            ? 'this machine could not make the empty directory this runs in'
+            : said;
+        // The level fork, which this path needs for the same reason `resumeRun`'s
+        // two do: a re-arm serves level 1, and a level 1 run holds the person's
+        // message. See `endRun`.
+        await endRun(client, level, row.run_id, row.run_card_id, why);
+        throw new Error(`NO AGENT IS RUNNING: ${level === 1 ? said : why}`);
+    }
+    /* WHAT IT SENT OTHERS TO DO AND WHAT THEY WROTE, FROM THE RECORD, AS LATE AS
+       POSSIBLE. Level 3 has no `dispatch`, so it has no children to have: null
+       says that, where an empty list would say it chose to send nobody. */
+    const children = level === 3 ? null : await childrenOf(client, row.run_id);
+    /* ═══ THREE REASONS, AND THE ROW SAYS WHICH. ═══ No question is ux.md's third
+       re-arm: everybody it sent has finished, and it is started to read them back.
+       `children` cannot be null on that path — only a run with children is ever
+       claimed for it — and the prompt takes the list rather than the maybe-list so
+       that is a fact of the signature rather than of a comment. */
+    const prompt = row.ask_id === null
+        ? readBackPrompt(row.run_brief, row.run_report, children ?? [])
+        : row.mine
+            ? answerPrompt(row.run_brief, row.run_report, children, row.question ?? '', row.answer ?? '')
+            : escalationPrompt(row.run_brief, row.run_report, children, row.ask_id, row.question ?? '');
+    const started = startAgent(prompt, level, tools.urlFor(row.run_id), cwd);
+    if (started.pid === null) {
+        const answer = await started.answered;
+        const reason = answer.ok ? 'the process ended before it could be identified' : answer.reason;
+        // The same level fork, for the same reason. See `endRun`.
+        await endRun(client, level, row.run_id, row.run_card_id, reason);
+        throw new Error(`NO AGENT IS RUNNING: ${reason}`);
+    }
+    out(`rearm    run ${row.run_id}  level ${level}  pid ${started.pid}  `
+        + `${row.ask_id === null
+            ? 'to read back everybody it sent'
+            : row.mine
+                ? 'with the answer to its own question'
+                : 'with a question it has to settle'}`);
+    try {
+        await recordProcess(client, row.run_id, started.pid);
+    }
+    catch (error) {
+        // Said, not fatal, as everywhere else: the agent is running and killing it
+        // over a bookkeeping write would cost the user the work.
+        said(`${error instanceof Error ? error.message : String(error)} (the run is still going)`);
+    }
+    /* ═══ AND IT SPEAKS TO THE CARD ONLY IF IT IS DOING THE PERSON'S WORK. ═══
+       Exactly the distinction ux.md draws: a run carrying on with its own work has
+       something to say when it finishes, and a run started only to settle somebody
+       else's question does not. A run started to read back everybody it sent is
+       the first kind and the clearest case of it — that reply IS the answer to the
+       request. See `settle`. */
+    return {
+        settled: settle(client, tools, machineId, level, row.run_id, row.run_card_id, started, row.ask_id === null || !!row.mine),
+    };
+}
+/**
+ * The runs one run dispatched, AND WHAT EACH OF THEM WROTE, in the words the
+ * prompt prints them in. The same question `list_child_runs` and
+ * `get_child_report` answer, asked here so the answer is IN the prompt rather
+ * than waiting for the agent to think of asking.
+ *
+ * ═══ THE REPORTS ARE HERE BECAUSE OF WHAT THIS IS FOR. ═══ ux.md: "the level 2
+ * agent does not hold its three workers' findings in its head while they run.
+ * Each worker writes what it found into the record, and the level 2 agent reads
+ * them back." The respawn that exists to do exactly that is fired by the record
+ * and given the record; leaving the reports behind a tool call would make the
+ * whole synthesis conditional on an agent choosing to make it, which is the
+ * difference ux.md draws between a guarantee and a hope.
+ *
+ * AND THEY ARE NOT TRUNCATED. A report is rewritten state rather than an append
+ * log, which is what keeps it bounded; cutting one here would hand the agent a
+ * half-sentence and no way to tell it was cut.
+ */
+async function childrenOf(client, runId) {
+    const children = await returned(client
+        .from('panel3_runs')
+        .select('id, level, state, activity, report, failed_because, ended_at')
+        .eq('parent_run_id', runId)
+        .order('started_at'), 'read', `what run ${runId} sent others to do`);
+    return children.flatMap((c) => [
+        [
+            c.id,
+            `L${c.level}`,
+            c.state === 'running' && !c.ended_at ? 'still going' : c.state,
+            c.activity ?? '',
+        ].join('  ').trimEnd(),
+        /* ONE OWNER PER COLUMN, PRINTED AS TWO FACTS. `report` is what the run
+           wrote and `failed_because` is why the product ended it, and running them
+           together would have an agent read the daemon's sentence as its worker's
+           finding. */
+        ...(c.failed_because === null ? [] : [`    it was ended: ${c.failed_because}`]),
+        ...(c.report === null
+            ? ['    it wrote nothing down']
+            : c.report.split('\n').map((l) => `    ${l}`)),
+    ]);
+}
+// ---------------------------------------------------------------------------
+/**
+ * ═══ THE TWO ENDS THE PERSON CAUSES, WHICH ARE THE TWO THIS DAEMON KILLS. ═══
+ *
+ * `stopped` is their Stop and `superseded` is the coordinator their next message
+ * replaced. The record keeps them apart on purpose, because a stop is read
+ * across the whole card and being replaced says nothing about anybody else's
+ * work. HERE they are one thing and only one: a process nothing will ever read
+ * from again.
+ */
+const ENDED_BY_THE_PERSON = ['stopped', 'superseded'];
+/** When this machine came up. Anything that started before it did has no process
+ *  left, whatever a pid lookup says about that number today. */
+const bootedAt = () => Date.now() - uptime() * 1000;
+/**
+ * ═══ IS THE PROCESS THIS RUN RECORDED STILL THERE. ═══
+ *
+ * `processIsAlive` is `kill(pid, 0)`, which answers "some process has this
+ * number", not "the process I started has this number". `machine_id` is derived
+ * from the hardware and survives a reboot, pids restart low, so after a restart
+ * a run's recorded pid regularly matches something unrelated and live. A run
+ * that started before this machine booted has no process left by definition,
+ * whatever the number says.
+ *
+ * ONE ANSWER FOR BOTH READERS. Recovery asks it to decide whether to reap a run,
+ * and the stop asks it to decide whether there is anything left to kill. The
+ * second is the one where a wrong yes is worst, because it signals a pid this
+ * machine no longer owns.
+ */
+function runProcessIsAlive(run, booted) {
+    if (run.pid === null)
+        return false;
+    // The attempt now running began at the resume, if there was one.
+    if (new Date(run.resumed_at ?? run.started_at).getTime() < booted)
+        return false;
+    return processIsAlive(run.pid);
+}
+/**
+ * ═══ THE USER STOPPED IT, OR THEIR NEXT MESSAGE REPLACED IT, SO THE PROCESS
+ *     STOPS. ═══
+ *
+ * ux.md: "The user's Stop is absolute, and nothing else stops work."
+ * `panel3_stop_card` is the whole of the decision, ending the runs and the card
+ * in one statement, and this is the effect.
+ *
+ * ═══ AND `superseded` IS READ OFF THE SAME QUERY, NOT SWEPT SEPARATELY. ═══ A
+ * coordinator the person's next message replaced has a process that will never
+ * be read from again, exactly like a stopped one, and that is the ONE thing the
+ * two states share here. Two sweeps would be two owners of "kill what is not
+ * coming back", and the second would be the one that fell behind. THE RECORD IS THE INTENT AND THE
+ * KILL IS THE EFFECT, in that order, so a machine that is offline when the
+ * button is pressed still honours it on the poll after it comes back.
+ *
+ * ONLY THIS MACHINE'S RUNS, for the same reason recovery only sweeps its own: a
+ * pid is a local fact, and no other machine can act on this one's.
+ *
+ * ═══ A PROCESS THAT IS ALREADY GONE IS NOT AN ERROR. ═══ It is the ordinary
+ * case, being an agent that finished in the second before the button or a
+ * daemon that was restarted since, and there is nothing to report about it.
+ *
+ * ═══ AND THE PID IS CLEARED, WHICH IS WHAT KEEPS THIS SET FROM BECOMING A
+ *     MINEFIELD. ═══ A stopped run is stopped forever, so without this its pid
+ * would be re-examined on every poll for the life of the machine, and pids are
+ * reused. Sooner or later that number belongs to something else that is alive
+ * and innocent, and this would signal it. Cleared, the row means what it says:
+ * this machine has no process for this run. It is the same `pid = null` a resume
+ * writes, for the same reason.
+ *
+ * AND ONLY WHEN THAT IS TRUE. A refused signal leaves the pid where it is, so
+ * the next poll tries again: clearing it after an EPERM would say this machine
+ * has no process for a run whose agent is still working.
+ */
+async function killStopped(client, machineId) {
+    const stopped = await returned(client
+        .from('panel3_runs')
+        .select('id, card_id, pid, started_at, resumed_at')
+        .eq('machine_id', machineId)
+        .in('state', ENDED_BY_THE_PERSON)
+        .not('pid', 'is', null), 'read', 'the runs on this machine that are not coming back');
+    if (stopped.length === 0)
+        return;
+    const booted = bootedAt();
+    for (const run of stopped) {
+        if (runProcessIsAlive(run, booted)) {
+            try {
+                process.kill(run.pid);
+                out(`stopped  run ${run.id}  card ${run.card_id}  killed pid ${run.pid}`);
+            }
+            catch (error) {
+                said(`could not stop pid ${run.pid} for run ${run.id}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            /* ═══ SIGNALLED IS NOT DEAD, SO THE PID STAYS ON THE ROW. ═══ `kill`
+               returning means the signal was delivered, not that the process acted on
+               it: an agent mid-write, or one ignoring SIGTERM, is still there and
+               still holding the working copy. Clearing the pid now would take the row
+               out of this read for good and it would never be signalled again. The
+               next poll finds it either gone, and clears it below, or still alive, and
+               signals it again. The same line covers a refused signal, where the
+               process is certainly still there. */
+            continue;
+        }
+        try {
+            await returned(client
+                .from('panel3_runs')
+                .update({ pid: null })
+                // STILL NOT COMING BACK. Nothing starts either of these states, so
+                // this cannot lose a race, and saying so in the statement is what
+                // keeps that true if something one day does.
+                .eq('id', run.id)
+                .in('state', ENDED_BY_THE_PERSON)
+                .select('id'), 'clear the process id of', `run ${run.id}`);
+        }
+        catch (error) {
+            // Said, not fatal. The kill has already happened; this is bookkeeping, and
+            // the next poll finds the row again and tries once more.
+            said(`${error instanceof Error ? error.message : String(error)} (it was stopped all the same)`);
+        }
+    }
+}
+/**
+ * ═══ A RUN WHOSE PROCESS IS GONE GOES BACK TO TAKEABLE. ═══
+ *
+ * Only this machine's runs, because liveness is a local fact: no other machine
+ * can honestly say whether this one's pid is still there, and guessing from a
+ * timestamp is how a run that is working gets declared dead.
+ *
+ * A run with NO PID RECORDED counts as gone — there is no process to be alive —
+ * but only once it is neither this process's own nor inside `PID_GRACE_MS` of
+ * starting. `mine` covers this daemon; the grace window covers a SECOND daemon
+ * on the same machine, whose `mine` set does not and cannot contain the first
+ * one's runs. Without it, starting a second daemon reaped the first daemon's
+ * live work: turns handed back and a run marked failed while its agent was
+ * genuinely running, producing a duplicate answer.
+ *
+ * ═══ AND A PID THAT PREDATES THIS BOOT IS NOT THIS RUN'S PID, which is
+ *     `runProcessIsAlive`'s rule and not this function's. ═══ What it costs here
+ * if it is ever weakened: after a restart a stranded run's pid regularly matches
+ * something unrelated and live, so the card would be skipped on every sweep,
+ * forever, which is the exact failure this function exists to make impossible.
+ *
+ * ═══ ENDING THE RUN AND HANDING ITS TURNS BACK IS ONE STATEMENT. ═══ It used to
+ * be two round trips, turns first so that a failure between them left the run
+ * still `running` for the next sweep to redo. That ordering was safe against a
+ * failure and not against an ANSWER: in the gap the turns were takeable while
+ * the run still read running, so a `panel3_answer` landing there was accepted
+ * onto a card another daemon was already free to take. `panel3_give_up` closes
+ * it, and the loser of that race is now decided by the database rather than by
+ * which write happened to be in flight.
+ *
+ * IT CANNOT UNDO AN ANSWER ANY MORE. A run that has answered is `finished` in
+ * the same statement that wrote the answer (`panel3_answer`), so it is never in
+ * this sweep's result at all. Before that, a daemon killed between the two left
+ * an answered card whose run still read running, and this function blanked
+ * `addressed_at` on turns with their answer sitting beside them.
+ *
+ * ---------------------------------------------------------------------------
+ * ═══ AND A DISPATCHED RUN IS NOT HANDED BACK. IT IS STARTED AGAIN. ═══
+ *
+ * The two kinds of run come back by different routes because their durable
+ * state lives in different places, and this is the fork between them.
+ *
+ *   A LEVEL 1 RUN'S WORK IS ITS TURNS. Handing them back is a complete recovery:
+ *   the next taker is sent the same thing, built from the same turns.
+ *
+ *   A DISPATCHED RUN HOLDS NO TURNS. What it was sent to do and how far it got
+ *   are on its own row, so ending it throws both away — and the person's request
+ *   dies with a card reading `failed`. `panel3_resume` claims the row instead and
+ *   the same agent is started again with its brief, its report and its children.
+ *
+ * ═══ WHICH IS ALSO WHY THE GRACE WINDOW READS `resumed_at`. ═══ A claim nulls
+ * the pid, so a freshly resumed run looks exactly like one whose daemon died
+ * before recording a pid. The window has to be measured from the attempt that is
+ * running now, not from the first one, or every resume would be reaped by the
+ * next sweep a second after it started.
+ */
+async function recoverStranded(client, tools, machineId, mine, hold) {
+    const live = await returned(client
+        .from('panel3_runs')
+        .select('id, card_id, parent_run_id, state, pid, started_at, resumed_at')
+        .eq('machine_id', machineId)
+        /* ═══ AND A RUN THAT STOPPED TO ASK IS SWEPT TOO, WHICH IS WHAT MAKES THE
+           RE-ARM'S OWN PREDICATE SAFE. ═══ `panel3_take_rearms` will only start a run
+           again once its last process is accounted for — `ended_at is not null` —
+           so that a settle still in flight cannot land on the attempt that
+           replaced it. The stamp arrives when the process exits; if the daemon
+           dies first, nothing else would ever write it and the branch would wait
+           forever on an answer that could never be delivered. This is where it
+           arrives instead. The two predicates are one rule and may not be changed
+           apart. */
+        .in('state', ['running', 'asked'])
+        .is('ended_at', null), 'read', "this machine's live runs");
+    const booted = bootedAt();
+    for (const run of live) {
+        if (mine.has(run.id))
+            continue;
+        // WHEN THE ATTEMPT NOW RUNNING BEGAN, which is the first one until a resume
+        // says otherwise. See the header.
+        const startedAt = new Date(run.resumed_at ?? run.started_at).getTime();
+        const rebooted = startedAt < booted;
+        // A run too young to have recorded a pid is another daemon's live work. The
+        // reused-pid check that used to sit beside this is `runProcessIsAlive`'s.
+        if (!rebooted && run.pid === null && Date.now() - startedAt < PID_GRACE_MS)
+            continue;
+        if (runProcessIsAlive(run, booted))
+            continue;
+        if (run.state === 'asked') {
+            /* ═══ ITS END IS STAMPED AND ITS TURNS ARE LEFT ALONE. ═══ This run is not
+               handed back and is not started again from here: its continuation is the
+               answer to what it asked, and `panel3_take_rearms` is what brings it back.
+               So it must NOT go through `panel3_give_up`, which would hand back the
+               turns a level 1 run took — putting the same message in front of a second
+               coordinator while the person is still being asked about the first.
+               What is missing is only the end stamp its process never got to write. */
+            const ended = await failRun(client, run.id, 'the process that asked this question was gone before it could finish');
+            out(ended
+                ? `recover  run ${run.id}  card ${run.card_id}  asked, and its process is gone: ended, `
+                    + 'and it comes back when its question is answered'
+                : `recover  run ${run.id}  had already ended, left alone`);
+            continue;
+        }
+        if (run.parent_run_id !== null) {
+            /* STARTED AGAIN AS ITSELF, AND A FAILURE IS SAID RATHER THAN THROWN. What
+               it must not do is take the sweep down mid-loop and leave every other
+               stranded run unlooked-at.
+      
+               WHAT IS LEFT BEHIND DEPENDS ON HOW FAR IT GOT, and each outcome is
+               honest. A failure BEFORE the claim — this machine has no working copy —
+               leaves the run exactly as it was, still `running` with a dead process,
+               so the next sweep tries again: right for a checkout that is missing for
+               a minute, and one line per poll for one that is missing for good. A run
+               that was CLAIMED and could not be STARTED is ended inside `resumeRun`,
+               because a claimed run with no process must not sit out a grace window
+               pretending to be alive. A failure between the two — the read of its
+               children — leaves it claimed, which costs it one window before the next
+               sweep claims it again. */
+            try {
+                const resumed = await resumeRun(client, tools, machineId, run.id, null);
+                if (resumed)
+                    hold(run.id, resumed.settled);
+                else
+                    out(`resume   run ${run.id}  already claimed or started again, left alone`);
+            }
+            catch (error) {
+                said(`could not start run ${run.id} again: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            continue;
+        }
+        const back = await giveUp(client, run.id, rebooted
+            ? 'this machine has restarted since the run started, so its process is gone'
+            : run.pid === null
+                ? 'the daemon that started this was gone before it recorded a process id'
+                : `the process running this (pid ${run.pid}) is gone and it never ended`);
+        if (back === null) {
+            /* IT ANSWERED WHILE IT WAS BEING GIVEN UP. The two functions race for one
+               run and `panel3_give_up` lost: the card is answered and complete, and
+               nothing here has touched it. Said rather than silent, because a sweep
+               that decided a run was dead and was wrong is worth seeing. */
+            out(`recover  run ${run.id}  card ${run.card_id}  answered as it was being given up, left alone`);
+            continue;
+        }
+        out(`recover  run ${run.id}  card ${run.card_id}  process gone, `
+            + `${back} turn${back === 1 ? '' : 's'} takeable again`);
+    }
+}
+/**
+ * ═══ A RUN A PERSON HANDED BACK, TAKEN UP BY WHOEVER IS LISTENING. ═══
+ *
+ * The same act as `recoverStranded`'s dispatched branch, by the other route.
+ * The sweep can only ever reach THIS machine's runs, because liveness is a local
+ * fact and no machine can honestly say whether another one's pid is still there.
+ * So a machine that is never coming back strands its dispatched runs forever:
+ * nothing sweeps them, and `panel3_take_turns` supersedes level 1 only.
+ *
+ * `panel3_hand_back` is the person's answer to that, and it decided everything.
+ * It ran under the card's own row lock, refused any run whose machine had
+ * heartbeated inside the listening window, and stamped `handed_back_at` on the
+ * dispatched ones. THIS IS ONLY THE DISCOVERY, which is the one thing that was
+ * missing: the daemon never asked whether another machine's run was available.
+ *
+ * ═══ AND SO THE READ HAS NO `machine_id` FILTER, WHICH IS THE WHOLE POINT. ═══
+ * RLS scopes it to the person's own account and nothing narrower, because the
+ * machine that stamped the offer is by definition not the machine that should
+ * serve it. `panel3_resume` has never had a machine predicate either, so the
+ * claim was always cross-machine; only the looking was not.
+ *
+ * ---------------------------------------------------------------------------
+ * ═══ WHICH OF THE SWEEP'S SAFETY CHECKS APPLY HERE, AND WHICH CANNOT. ═══
+ *
+ * The sweep refuses three things, and they are not decoration: they are what
+ * stops a machine reaping its own live work. Taken one at a time, because
+ * carrying them across without thinking and dropping them without saying are
+ * the same mistake.
+ *
+ *   `mine`, A RUN THIS DAEMON IS HOLDING RIGHT NOW: KEPT. Presence is coarser
+ *   than a pid, so a daemon that is alive but has missed the listening window,
+ *   meaning a closed lid, a paused VM or a network stall, has its runs offered
+ *   while its agents are genuinely working. When it comes back it finds its OWN
+ *   work on offer, and without this line it would claim it: `panel3_resume`
+ *   writes `pid = null` and a second process starts on the same run id and the
+ *   same working copy, while the first one's `settle` is still going to answer
+ *   the card.
+ *
+ *   ═══ AND IT NARROWS THAT CLASS RATHER THAN CLOSING IT. ═══ A THIRD machine,
+ *   listening and healthy, can claim that same live run, because the guard the
+ *   database applied is presence and presence is what was wrong. That limit is
+ *   the migration header's own and is not this function's to fix; `mine` closes
+ *   one half that IS knowable here, which is a run THIS PROCESS is holding, and
+ *   the pid check below closes the other, which is a run ANOTHER PROCESS ON THIS
+ *   MACHINE is holding.
+ *
+ *   `PID_GRACE_MS`, TOO YOUNG TO HAVE RECORDED A PID: KEPT, in its `pid is null`
+ *   half only, and it closes the same hole `mine` does one step earlier. A
+ *   FRESHLY DISPATCHED run is not in `inFlight` yet: `startChild` writes the row
+ *   through `panel3_dispatch` and the poll only calls `hold` once `startChild`
+ *   has RESOLVED, so in between the row reads `running`, `parent_run_id` is not
+ *   null, `pid` is null, and `mine` does not contain it. The tools server runs
+ *   off HTTP rather than off the poll, so a daemon stalled past the listening
+ *   window still serves a `dispatch` and still writes that row: the person
+ *   presses, the child is stamped, the stall ends, and this read would claim a
+ *   run whose own process is in the act of starting. Two agents, one run id, one
+ *   working copy, which is what `mine` is here to prevent.
+ *
+ *   ═══ AND IT COSTS THE REAL CASE NOTHING. ═══ A genuinely stranded offer is by
+ *   construction older than the fifteen seconds the banner needed before a
+ *   person could even see it, so the window never fires for one.
+ *
+ *   THE SWEEP'S OTHER HALF OF THAT LINE, `rebooted`, STAYS OUT. It is read off
+ *   this machine's uptime, and this is the one read that is not about this
+ *   machine's runs.
+ *
+ *   `runProcessIsAlive`, THE PID PLUS A BOOT-TIME REFUSAL: APPLIED TO THIS
+ *   MACHINE'S OWN OFFERED RUNS, AND TO NOBODY ELSE'S. The two halves are
+ *   genuinely different questions and were once answered as one.
+ *
+ *   ON ANOTHER MACHINE'S RUN IT WOULD BE A DEFECT. That pid belongs to a process
+ *   on a box this one cannot see, so `kill(pid, 0)` here asks about an unrelated
+ *   local process, and pids are reused: a collision would make this machine skip
+ *   a run nobody is working on, forever, which is the exact strand the feature
+ *   exists to end. What stands in for it there is the heartbeat guard already
+ *   spent inside `panel3_hand_back`, with the honest limit that migration's
+ *   header states.
+ *
+ *   ON A RUN WHOSE `machine_id` IS THIS MACHINE IT IS EXACTLY AS TRUSTWORTHY AS
+ *   IT IS IN `recoverStranded`, and TWO DAEMONS ON ONE MACHINE IS NOT
+ *   HYPOTHETICAL: 20260903140000 exists to support one per harness, and
+ *   `PID_GRACE_MS`'s own header says so. Without this check, D1 holds a live
+ *   dispatched run with its pid recorded, the machine sleeps, both presence rows
+ *   go stale, a person hands the card back, the machine wakes and D2 polls
+ *   first. The sweep leaves the run alone, correctly, because the process really
+ *   is alive. This read would then claim the very same row: `mine` is D2's and
+ *   does not hold D1's work, the grace window does not fire because the pid is
+ *   there, and `panel3_resume` matches every predicate, because `machine_id`
+ *   moves from this machine to this machine. Two agents, one run id, one working
+ *   copy, and D1's answer is accepted afterwards by a `panel3_answer` fenced by
+ *   neither machine nor pid.
+ *
+ * ---------------------------------------------------------------------------
+ * ═══ AND A FAILURE IS SAID RATHER THAN THROWN, AS IT IS IN THE SWEEP. ═══ The
+ * ordinary one is a machine with no folder for the project: `resumeRun` resolves
+ * the checkout BEFORE the claim, so such a machine never takes a run it cannot
+ * start. It says why on its own stderr and leaves the offer standing for a
+ * machine that has the codebase. That is not silence and it is not a success:
+ * the run is exactly as it was, and the card goes on saying nothing is listening,
+ * which is true until somebody who can serve it is.
+ *
+ * ═══ AND THAT HOLDS ONLY WHERE `CTRL_SPC_V3_WORKING_COPY` IS UNSET, WHICH IS
+ *     THIS TASK'S ONE REAL EXPOSURE. ═══
+ *
+ * `checkoutFor` resolves in three steps and the third is a machine-wide folder
+ * named by that variable, which applies EVEN WHEN THE CARD HAS A PROJECT. So a
+ * listening machine with it set resolves a checkout for any project at all,
+ * passes the ordering guarantee above, claims the run and starts an agent in a
+ * folder holding somebody else's code, which is the failure
+ * `panel3-checkout.contract.test.mjs`'s own header names. Before this function
+ * existed it was unreachable across machines, because nothing ever looked at
+ * another machine's run; this read is what makes it reachable, and the
+ * cross-machine walk in plan-slice-2.md section 8 is exactly the setup that sets
+ * the variable, so that walk can produce a false pass.
+ *
+ * ═══ RECORDED, NOT FIXED HERE. ═══ Reordering that resolution is `../codebases-3`'s
+ * assignment, and `checkoutFor` is shared by every spawn path with its own
+ * contract suite: changing it from this slice would widen a fifty-line read into
+ * a change to how every agent in the product finds its code.
+ *
+ * ═══ AND ONE OFFER NOBODY CAN CHECK OUT IS NOW RETRIED BY THE WHOLE FLEET. ═══
+ * Nothing clears `handed_back_at` except a claim, so every listening machine
+ * reads that run every poll and prints one line for it, forever, where
+ * `recoverStranded`'s header accepts the same cost for one machine. Two reads and
+ * a line per machine per poll is cheap and is the honest state of the record: the
+ * work really is offered and really has no taker. Silencing it would mean an
+ * expiry on the offer, which is a rule nothing has asked for and which would
+ * throw the work away on a fleet that was merely all asleep.
+ */
+export async function takeHandedBack(client, tools, machineId, mine, hold) {
+    /* ITS OWN NARROW ROW, NOT `LiveRun`. `machine_id` is read for one question
+       and one only: whether this row is THIS machine's, which is what decides
+       whether its pid means anything here. See the header. */
+    const offered = await returned(client
+        .from('panel3_runs')
+        .select('id, card_id, machine_id, pid, started_at, resumed_at')
+        .not('handed_back_at', 'is', null)
+        /* WHAT THE OFFER MEANS, RESTATED IN THE READ. `panel3_hand_back` only ever
+           stamps a dispatched run that is still going, and `panel3_resume` refuses
+           anything else. Saying it here too costs one line and means a row that
+           somehow carried a stale stamp is passed over rather than sent to a
+           function that would refuse it a round trip later. */
+        .eq('state', 'running')
+        .is('ended_at', null)
+        .not('parent_run_id', 'is', null), 'read', 'the runs a person has handed back');
+    // ONCE, OUTSIDE THE LOOP. It is a property of this machine, not of a row.
+    const booted = bootedAt();
+    for (const run of offered) {
+        if (mine.has(run.id)) {
+            /* THIS DAEMON'S OWN LIVE WORK, OFFERED WHILE IT WAS BUSY BEING QUIET. See
+               the header. Said rather than passed over in silence, because a machine
+               whose work was handed back out from under it is the one thing here worth
+               seeing in a terminal. */
+            out(`offered  run ${run.id}  card ${run.card_id}  is this daemon's own live work, left alone`);
+            continue;
+        }
+        /* ═══ AND THE OTHER DAEMON ON THIS MACHINE IS HOLDING IT. ═══ `mine` covers
+           this process and cannot cover its sibling: one machine runs one daemon per
+           harness on purpose (20260903140000), and a machine that slept has both
+           presence rows stale, so `panel3_hand_back` offers work that is still
+           genuinely running. THE PID ANSWERS THAT, AND ONLY FOR THIS MACHINE'S OWN
+           ROWS: for anybody else's it would be a question about an unrelated local
+           process. `recoverStranded` asks it the same way on the same rows and
+           correctly leaves them alone, so without this the sweep declines and the
+           very next read claims. See the header. */
+        if (run.machine_id === machineId && runProcessIsAlive(run, booted)) {
+            out(`offered  run ${run.id}  card ${run.card_id}  is still running on this machine, left alone`);
+            continue;
+        }
+        /* ═══ AND A RUN TOO YOUNG TO HAVE RECORDED A PID IS SOMEBODY'S LIVE WORK
+           TOO, INCLUDING THIS DAEMON'S OWN. ═══ `mine` cannot hold a dispatch
+           between the row `panel3_dispatch` wrote and the `hold` that follows the
+           spawn, and that gap is reachable from here: see the header. This is
+           `recoverStranded`'s own line without its `rebooted` half, which reads this
+           machine's uptime and has no meaning for another machine's run. */
+        if (run.pid === null
+            && Date.now() - new Date(run.resumed_at ?? run.started_at).getTime() < PID_GRACE_MS) {
+            out(`offered  run ${run.id}  card ${run.card_id}  is too young to have a process yet, left alone`);
+            continue;
+        }
+        try {
+            const resumed = await resumeRun(client, tools, machineId, run.id, null);
+            if (resumed)
+                hold(run.id, resumed.settled);
+            else
+                out(`resume   run ${run.id}  already claimed or started again, left alone`);
+        }
+        catch (error) {
+            said(`could not take run ${run.id}, which was handed back: `
+                + `${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+/**
+ * The poll loop: it takes what is waiting and answers it, forever. `--once`
+ * polls a single time and exits when the work it took is done, which is what
+ * makes the loop testable — two of them against one card is how the lease is
+ * proved.
+ *
+ * ═══ ONE LOOP, TWO CALLERS, AND THAT IS THE WHOLE OF recovery-1 SLICE 4. ═══
+ * `startPanel` below is `cs start`'s entry and hands in the session the
+ * installed CLI already holds. `cs3 run` is the acceptance harness's entry and
+ * signs in from the environment against its own isolated account. Neither is a
+ * copy of the other: a second poll loop would be two things leasing the same
+ * turns with two ideas of what recovery may reap.
+ *
+ * @param injected the client to poll and serve tools through, when the caller
+ * already has one. Its presence is also what says THIS PROCESS IS NOT v3's, so
+ * the signals belong to somebody else — see the handler block below.
+ */
+export async function run(args, injected) {
+    let once = false;
+    for (const arg of args) {
+        if (arg === '--once')
+            once = true;
+        else
+            throw new Error(`unknown option ${arg}. ${USAGE}`);
+    }
+    /* ═══ THE ONE v3 CLIENT THAT OUTLIVES ITS ACCESS TOKEN, SO IT IS THE ONE THAT
+       REFRESHES. ═══ This client polls for as long as the daemon runs AND is the
+       client every tool call is served through, so past the token's TTL both stop
+       working at once. See `client.ts` for why refreshing is safe here:
+       `persistSession` stays false, so the rotated token lives in this process and
+       no file on the machine is written.
+  
+       ═══ AND UNDER `cs start` THERE IS NO SIGN-IN AT ALL, WHICH IS THE POINT. ═══
+       The installed daemon's own client is handed in: it refreshes, it retries at
+       the network layer, and it is the ONLY client in that process, so the rotated
+       token has exactly one writer. Signing in again there would be the second
+       refresh loop `client.ts`'s header exists to prevent, this time inside one
+       process rather than across two. */
+    const client = injected ?? await signedInClient(true);
+    const machineId = getMachineIdentity().id;
+    /* THE NAME AND THE HARNESS, RESOLVED ONCE, AT STARTUP, RATHER THAN PER POLL.
+       Both are properties of this machine for the life of this process: the
+       hostname does not change under it, and neither does `CTRL_SPC_V3_AGENT`.
+       Resolving `harness()` here means a machine misconfigured with a name this
+       build cannot spawn (constraint 7: reported, never chosen) fails before it
+       ever says it is listening, rather than on its first poll. */
+    const machineName = hostname();
+    const machineHarness = harness();
+    /* THE RUNS THIS PROCESS IS HOLDING RIGHT NOW, so recovery cannot declare its
+       own live work dead in the moment before a pid is recorded. It covers THIS
+       daemon only, which is why `PID_GRACE_MS` exists for the other ones. Keyed by
+       run id, at every level: a dispatched agent is this daemon's to hold too, and
+       leaving it out would have recovery reap the children of its own runs. */
+    const inFlight = new Map();
+    /** One dispatched run's promise, held where the daemon can wait on it and
+     *  recovery can see it. The same bookkeeping the poll does for a level 1 run,
+     *  in the one other place a process is started. */
+    const hold = (runId, work) => {
+        inFlight.set(runId, work
+            .catch((error) => {
+            said(`run ${runId}: ${error instanceof Error ? error.message : String(error)}`);
+        })
+            .finally(() => { inFlight.delete(runId); }));
+    };
+    /* ═══ THE TOOLS BEFORE THE FIRST TAKE, OR NO TAKES AT ALL. ═══ A daemon that
+       took a card and then found it could not serve tools would spawn an agent
+       with no hands and write its confusion to the card as an answer. It is one
+       loopback listener on an ephemeral port; failing here is a daemon that never
+       started, which is the honest outcome.
+  
+       `tools` is referenced inside the callback it is being given, which is safe
+       for the plain reason that the callback can only run once a request has
+       arrived at a server that by then exists. */
+    const tools = await startToolsServer(client, async (parentRunId, brief, codebase) => {
+        const child = await startChild(client, tools, machineId, parentRunId, brief, codebase);
+        hold(child.runId, child.settled);
+        return { runId: child.runId };
+    });
+    out(`daemon   machine ${machineId}`);
+    out(`tools    ${tools.urlFor('<run-id>')}`);
+    out(once ? 'mode     one poll' : `mode     polling every ${POLL_INTERVAL_MS / 1000}s, Ctrl-C to stop`);
+    /* ═══ AND THIS MACHINE STOPS SAYING IT IS LISTENING WHEN IT GOES. ═══ ux.md
+       forbids a card reading `working` while nothing is working, and the freshness
+       window is a backstop for the machine that CANNOT say goodbye — a crash, a
+       lost network, a kill -9. A Ctrl-C can, so it does, and the panel tells the
+       truth within a poll rather than within a window.
+  
+       `once` never gets here: it returns below, and the same call is made there.
+  
+       ═══ AND NOT WHEN A CLIENT WAS HANDED IN, BECAUSE THEN THE PROCESS IS NOT
+       THIS LOOP'S TO EXIT. ═══ Under `cs start` this shares a process with the v2
+       presence heartbeat, which has a shutdown of its own that marks
+       `cliv2_agents` offline and then calls `process.exit`. Two handlers means two
+       exits, and whichever finishes its write first kills the other's mid-flight:
+       a Ctrl-C would leave the machine reading listening in one place and gone in
+       the other, which is Slice 1's card lying in the direction Slice 4 exists to
+       close. `daemon.ts` owns the signal there and does both writes before it
+       goes. */
+    if (!once && !injected) {
+        for (const signal of ['SIGINT', 'SIGTERM']) {
+            process.once(signal, () => {
+                void stopListening(client, machineId, machineHarness).finally(() => {
+                    /* The exit code a signal is supposed to produce, and the reason it is
+                       said explicitly: `process.once` REPLACES node's default handler, so
+                       without this a Ctrl-C would leave the daemon polling forever. */
+                    process.exit(signal === 'SIGINT' ? 130 : 143);
+                });
+            });
+        }
+    }
+    for (;;) {
+        /* ═══ ONE POLL FAILING IS NOT THE DAEMON FAILING. ═══ Every read and write
+           here throws on a network or database error, by design (constraint 7), and
+           until Slice 4 that threw straight out of `cs3 run` and exited the process.
+           Inside `cs start` that is no longer an honest outcome twice over: it would
+           take the v2 presence heartbeat down with it, and it would leave a stranded
+           card printing `cs start` at a person who IS running `cs start`, which is
+           the exact lie this slice exists to end. A dropped connection is a poll
+           that did not happen; the next one is two seconds away.
+    
+           `--once` still fails loudly, because the acceptance harness reads the exit
+           code and a swallowed failure there would make a broken suite look green. */
+        try {
+            /* ═══ THE FIRST THING EVERY POLL, BECAUSE IT IS WHAT MAKES THE OTHER THINGS
+               LEGIBLE. ═══ A card with an untaken turn reads the same whether a daemon
+               is two seconds away or nobody has one running; this row is the only place
+               the difference exists. It is written before the takes rather than after
+               so that a machine which is up but busy still reads as up. */
+            await sayListening(client, machineId, machineName, machineHarness);
+            /* ═══ THE USER'S STOP IS HONOURED BEFORE ANYTHING ELSE ON THE POLL. ═══ It
+               is the only thing here that a person is waiting on, and the two takes
+               below can spend the rest of the poll starting agents. Nothing else needs
+               to run first: `panel3_stop_card` has already ended the runs, so recovery
+               cannot see them and neither take can start them. */
+            await killStopped(client, machineId);
+            await recoverStranded(client, tools, machineId, new Set(inFlight.keys()), hold);
+            /* ═══ AND THEN WHAT SOMEBODY ELSE'S MACHINE WAS HOLDING, IF A PERSON HANDED
+               IT BACK. ═══ AFTER the sweep, deliberately: this machine settles its own
+               runs on local, pid-accurate evidence before it looks at anybody's, and a
+               run of its own that was offered while it was quiet is dealt with there on
+               the better evidence: resumed if its process is really gone, which spends
+               the offer, and skipped if it is not, which is what `mine` then honours
+               here. The set is rebuilt rather than reused because the sweep adds to it.
+               BEFORE both takes, for the reason the sweep is: work that already exists,
+               with a brief and a report behind it, comes before work that has not
+               started. */
+            await takeHandedBack(client, tools, machineId, new Set(inFlight.keys()), hold);
+            /* THE MACHINE ID GOES IN because the take writes the run row, and a run has
+               to say where it is running: the exclusion is cross-machine and recovery is
+               per-machine, so a row with nobody's machine on it could be neither. */
+            const taken = await returned(client.rpc('panel3_take_turns', { p_machine_id: machineId, p_agent: machineHarness }), 'take', 'turns');
+            /* ═══ THE OTHER KIND OF TAKEABLE WORK. ═══ ux.md's re-arm: an answered
+               question makes the branch that asked it takeable again, and a question
+               still walking up makes the run it reached takeable so that level gets its
+               turn. Same poll, same machine id, same holding: only the reason a run is
+               started differs, and the record decides that rather than this file.
+      
+               AFTER THE TURNS ARE TAKEN, deliberately, because the take WRITES the run
+               row it leases to. A person who answered and then typed something else has
+               both waiting, and in this order the message's level 1 is already on the
+               record, so the re-arm leaves that card's coordinator alone and comes back
+               to it on a later poll rather than putting two of them on one card. The
+               other order would decide the same question from a snapshot taken before
+               the run existed. */
+            const rearmed = await returned(client.rpc('panel3_take_rearms', { p_machine_id: machineId, p_agent: machineHarness }), 'take', 'runs that can carry on');
+            for (const row of rearmed) {
+                /* NOT AWAITED PAST THE SPAWN, exactly as a taken card is not: the work is a
+                   real agent and holding the poll open for it would put every other card
+                   behind it. A throw here is caught rather than taking the loop down,
+                   because one run that could not be started must not stop the others. */
+                try {
+                    hold(row.run_id, (await startRearmed(client, tools, machineId, row)).settled);
+                }
+                catch (error) {
+                    said(`could not start run ${row.run_id} again: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            for (const [cardId, turns] of byCard(taken)) {
+                const runId = turns[0].run_id;
+                out(`took     card ${cardId}  ${turns.length} turn${turns.length === 1 ? '' : 's'}  run ${runId}`);
+                /* NOT AWAITED HERE. A run is a real agent doing real work, and awaiting it
+                   in the poll would put every other card behind it — v2's own measured
+                   defect (env.ts, I21/I24: "a second request typed seconds after the first
+                   sat untouched until the first finished"). Nothing is needed to stop the
+                   same card being taken twice, because that is the database's job and it
+                   has already been done by the take. */
+                // The catch inside `hold` is the last resort. A run left `running` by a
+                // throw is not lost: its process has exited, so the next sweep reaps it
+                // and the turns are answered again. It is there so the reason is printed
+                // rather than becoming an unhandled rejection.
+                hold(runId, answerCard(client, tools, machineId, cardId, turns));
+            }
+            if (once) {
+                /* ═══ UNTIL NOTHING IS LEFT, NOT ONCE OVER WHAT WAS THERE. ═══ A level 1
+                   run dispatches WHILE it is being waited on, so the child appears in
+                   `inFlight` after the first wait started. Closing then would kill the
+                   tools server under an agent that had just been started, and `--once`
+                   would report a card answered while the work on it was still going. */
+                while (inFlight.size > 0)
+                    await Promise.all([...inFlight.values()]);
+                // The listener would otherwise keep this process alive after its one poll
+                // was done, which is the whole point of `--once` being testable.
+                await tools.close();
+                // This machine is not listening any more, and it knows that here rather
+                // than fifteen seconds from now. Same reason as the signal handlers above.
+                await stopListening(client, machineId, machineHarness);
+                return;
+            }
+        }
+        catch (error) {
+            if (once)
+                throw error;
+            said(`this poll did not finish: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        await sleep(POLL_INTERVAL_MS);
+    }
+}
+// ---------------------------------------------------------------------------
+/**
+ * ═══ THE ONE THING `cs start` REACHES INTO `panel3/` FOR. ═══
+ *
+ * recovery-1 Slice 4, and Lane's ruling behind it (2026-08-21): *the user
+ * experience must never require them to launch or authenticate multiple CLIs.
+ * They launch the CLI with `cs start`.* Slices 1 to 3 print `cs start` on a
+ * stranded card and, until this function existed, that command started a daemon
+ * which polled no cards at all — the sentence named the right machine and the
+ * wrong command, and no rewording could fix it.
+ *
+ * ═══ IT IS A NAMED EXCEPTION TO THE ISOLATION RULE, NOT A HOLE IN IT. ═══
+ * `conventions.md` forbids anything outside `panel3/` importing anything inside
+ * it, and `panel3-isolation.contract.test.mjs` enforces it. `cli-v2/src/daemon.ts`
+ * is listed there with exactly ONE allowed specifier, `./panel3/run.js`, which is
+ * why this is a single entry point handing back a single closure rather than
+ * three exports the daemon would have to assemble. A second specifier fails the
+ * suite, which is the point: the rule is enumerated, never weakened.
+ *
+ * ═══ THE CLIENT IS THE CALLER'S, AND THAT IS THE WHOLE OF "ONE SIGN-IN". ═══
+ * `startPresence()` hands over the client it built from the session `cs login`
+ * stored. This must never take one of its own: two clients in one process is two
+ * refresh loops on one rotating refresh token, both writing `session.json`
+ * through `getClient`'s `onAuthStateChange`, which is the hazard `client.ts`
+ * describes moved indoors.
+ *
+ * ═══ IT DOES NOT BLOCK, AND IT DOES NOT TAKE THE DAEMON DOWN. ═══ The loop
+ * never returns, so awaiting it here would hang `cs start` before it printed a
+ * line. A throw that escapes the per-poll guard inside it is the panel stopping,
+ * which is said on the one stream a person reads and leaves v2 presence
+ * heartbeating rather than killing the process around it.
+ */
+export function startPanel(client) {
+    /* Both resolved HERE as well as inside the loop, deliberately: `stop` has to
+       name the same row the loop's heartbeat writes, and it must be able to do
+       that after the loop has thrown. They are the two facts about this machine
+       that cannot change under a running process — the hardware-derived id and
+       `CTRL_SPC_V3_AGENT` — so reading them twice cannot disagree. */
+    const machineId = getMachineIdentity().id;
+    const machineHarness = harness();
+    void run([], client).catch((error) => {
+        said(`the agent panel stopped polling: ${error instanceof Error ? error.message : String(error)}`);
+    });
+    /* `stopListening` is already best-effort and swallows its own failure: a
+       process on its way out must not hang or fail, and the freshness window
+       covers every way a machine can leave without getting here. */
+    return { stop: () => stopListening(client, machineId, machineHarness) };
+}