@ctrl-spc/cs 0.6.0 → 0.7.0

package/dist/panel3/answer.js

@@ -0,0 +1,166 @@
+/**
+ * ═══ AGENT PANEL v3: `cs3 answer`, the person settling a question. ═══
+ *
+ * THIS FILE BELONGS TO AGENT PANEL v3. Nothing outside `src/panel3/` may
+ * import it.
+ *
+ * ---------------------------------------------------------------------------
+ * ═══ IT IS `cs3 say`'s SIBLING, AND IT IS A SEPARATE COMMAND ON PURPOSE. ═══
+ *
+ * Both are the person putting something on the record and returning, with no
+ * spawn to wait for. They differ in what the record does with it, and that
+ * difference is exactly why they are not one command: a message is new work, and
+ * an answer is the thing one particular piece of stopped work was waiting for.
+ * `cs3 say --card <id> "the answer"` would put the words on the card as a fresh
+ * message, leave the question open, and leave the run that asked it stopped
+ * forever — which is the fenced-off answer ux.md spends a section on, arrived at
+ * by the shortest route.
+ *
+ * ---------------------------------------------------------------------------
+ * ═══ THE CARD LEAVES needs-you IN THE SAME STATEMENT. ═══
+ *
+ * ux.md: "Every user input changes the screen immediately... a card still
+ * sitting in needs-you after the user answered it gets answered twice." So this
+ * command writes nothing itself: `panel3_answer_ask` settles the question and puts
+ * the card back in hand together, and there is no instant between them for a
+ * screen to be wrong in.
+ *
+ * ═══ EXCEPT WHEN THE QUESTION BELONGS TO WORK THE USER STOPPED, AND THEN THIS
+ *     COMMAND SAYS SO. ═══ The same statement declines to put such a card in
+ * hand, because nobody will be started for the answer. What this command may not
+ * do is go on printing the sentence that is usually true: "in hand again" and
+ * "whoever was waiting on this is started again with it" would be the product
+ * announcing an effect it did not have, which is the same failure as a tool
+ * reporting success for work it did not do. So the card's state is read back and
+ * the outcome is what the record says, not what usually happens.
+ *
+ * ---------------------------------------------------------------------------
+ * ═══ AND IT DOES NOT SPAWN, WHICH IS THE WHOLE DESIGN RATHER THAN A GAP. ═══
+ *
+ * The agent that asked is gone: asking is terminal, and nothing is sitting there
+ * to be woken. What starts it again is the daemon's own poll, one round trip
+ * later, reading the same row this command wrote — so the answer is durable
+ * whether or not a machine is up, and this command is honest about the wait
+ * rather than pretending to have started something.
+ */
+// The runtime import comes FIRST, deliberately: `tsc` elides a type-only import
+// and takes the leading comment with it, so a file whose first statement is
+// `import type` loses its v3 header in the published `dist/`.
+import { at, out, returned, signedInClient } from './client.js';
+import { ASK_CONTENT_COLUMNS, withAskContent } from './show.js';
+const USAGE = 'usage: cs3 answer <question-id> "<text>"';
+/**
+ * The two arguments, and a second bare word refused rather than joined: `cs3
+ * answer <id> yes it is` is an answer the shell already split, and gluing it back
+ * together would be this command guessing at what the person typed. The same rule
+ * `cs3 say` applies, for the same reason.
+ */
+function parseArgs(args) {
+    const words = args.filter((a) => !a.startsWith('--'));
+    const flag = args.find((a) => a.startsWith('--'));
+    if (flag)
+        throw new Error(`unknown option ${flag}. ${USAGE}`);
+    if (words.length < 2)
+        throw new Error(`answer what, and with what? ${USAGE}`);
+    if (words.length > 2) {
+        throw new Error(`quote the answer as one argument, got ${words.length - 1}. ${USAGE}`);
+    }
+    if (words[1].trim() === '')
+        throw new Error(`the answer is empty. ${USAGE}`);
+    return { askId: words[0], answer: words[1] };
+}
+/**
+ * ═══ A REFUSAL SAYS WHICH REFUSAL IT IS, WHICH TAKES A SECOND READ. ═══
+ *
+ * `panel3_answer_ask` returns null for three different facts — already answered,
+ * not the person's to answer yet, no such question — because a caller inside the
+ * product cannot act on the difference. A person can: one of them means look at
+ * the card, one means wait, and one means the id is wrong. So this reads the row
+ * afterwards, purely to say which, and nothing about the record has changed in
+ * between that could make the sentence untrue.
+ *
+ * ═══ AND THE WAITING ONE IS ONLY SAID WHEN IT IS TRUE. ═══ It used to say the
+ * question "may yet be settled without troubling you" whatever the record said —
+ * including for a question `cs3 show` had already called stalled, because the
+ * agent it went to had ended without dealing with it. Two surfaces, opposite
+ * claims, and the one the person can act on was the one that was wrong. Those
+ * are now answerable, so the only refusal left here is the honest one: it has
+ * not been tried yet.
+ */
+async function whyNot(client, askId) {
+    const asks = await withAskContent(client, await returned(client
+        .from('panel3_asks')
+        .select(`id, card_id, answered_at, pending_run_id, delivered_at, ${ASK_CONTENT_COLUMNS}`)
+        .eq('id', askId), 'read', `question ${askId}`));
+    const ask = asks[0];
+    if (!ask) {
+        return `there is no question with id ${askId}. \`cs3 show\` lists the cards and the questions on them.`;
+    }
+    if (ask.answered_at) {
+        return (`that question was already answered ${at(ask.answered_at)}, with:\n  ${ask.answer ?? '(nothing)'}\n`
+            + 'Answering it again would rewrite a decision the work has already been started on. Send a '
+            + `message instead: cs3 say --card ${ask.card_id} "<text>"`);
+    }
+    return ('that question has not reached you: it is with the work it came from, which has not had its go '
+        + 'at it yet and may settle it without troubling you. `cs3 show` says who has it, and it becomes '
+        + 'yours to answer if they end without dealing with it.');
+}
+export async function answer(args) {
+    const { askId, answer: text } = parseArgs(args);
+    const client = await signedInClient();
+    /* ═══ STILL FREE TEXT, AND IT NEEDS NO CASE FOR THE SHAPE OF THE QUESTION.
+       ═══ questions-2/ux.md puts changing this command out of scope, and no
+       branch is needed to keep that promise: no selection and the text as the
+       note is the product's own "answered in their own words", which
+       `app.canonical_decision_answer` returns verbatim whatever mode the question
+       was asked in. So a shortlisted question answered from a terminal records
+       what was typed, exactly as it always did, and the panel reads it as an own
+       answer rather than as a choice nobody made. */
+    const { data: cardId, error } = await client
+        .rpc('panel3_answer_ask', { p_ask_id: askId, p_selected_options: [], p_answer_note: text });
+    if (error)
+        throw new Error(`could not answer question ${askId}: ${error.message}`);
+    if (cardId === null) {
+        /* NOTHING WAS WRITTEN, and this exits non-zero saying why. A command whose
+           whole job is settling something must never look like it settled it. */
+        throw new Error(await whyNot(client, askId));
+    }
+    /* WHAT THE RECORD DID, READ BACK, rather than what it usually does. One read,
+       and it is the card's own state: `panel3_answer_ask` puts a card in hand
+       exactly when somebody can be started for the answer, so the state is the
+       answer to "did anything start" without a second return value to keep in
+       step with it. */
+    const cards = await returned(client.from('panel3_cards').select('state').eq('id', cardId), 'read', `card ${cardId}`);
+    for (const said of answeredLines(askId, cardId, cards[0]?.state ?? null))
+        out(said);
+}
+/**
+ * What the command says once the answer is on the record, from the state the
+ * card is actually in.
+ *
+ * `working` is the ordinary outcome and the only one where anybody is started.
+ * Anything else means the card was not put back in hand, which today is a card
+ * the user stopped: the answer is kept, and nothing is waiting for it. A null
+ * state is a card that vanished between the write and the read, and it is said
+ * plainly rather than dressed as either outcome.
+ */
+export function answeredLines(askId, cardId, state) {
+    if (state === 'working') {
+        return [
+            `answered  ${askId}`,
+            `card      ${cardId}   in hand again`,
+            '',
+            '  Whoever was waiting on this is started again with it, wherever they had got to.',
+            `  cs3 show ${cardId}`,
+        ];
+    }
+    return [
+        `answered  ${askId}`,
+        `card      ${cardId}   ${state === null ? 'no longer on the record' : `still ${state}`}`,
+        '',
+        '  NOBODY IS BEING STARTED FOR THIS. The answer is on the record and nothing is waiting for',
+        '  it, because the work that asked was stopped. Send a message if you want this card picked',
+        '  up again:',
+        `  cs3 say --card ${cardId} "<text>"`,
+    ];
+}

package/dist/panel3/checkout.js

@@ -0,0 +1,29 @@
+/**
+ * ═══ AGENT PANEL v3: THE EXACT CODEBASE A RUN WORKS IN. ═══
+ *
+ * A run names one registered codebase. The cloud keeps its path-free identity;
+ * this machine keeps the folder in `codebase-paths.json`. Nothing falls back to
+ * a project folder or a machine-wide working copy, because either could put an
+ * agent in a different repository while the record names this one.
+ */
+import { statSync } from 'node:fs';
+import { readCodebasePaths } from '../config.js';
+function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export function hasCheckoutForCodebase(codebase) {
+    const located = readCodebasePaths()[codebase.gitRemoteUrl];
+    return Boolean(located && isDirectory(located));
+}
+/** Resolve one registered codebase to this machine's local folder. */
+export function checkoutForCodebase(codebase, machineName) {
+    const located = readCodebasePaths()[codebase.gitRemoteUrl];
+    if (located && hasCheckoutForCodebase(codebase))
+        return located;
+    throw new Error(`Open the companion on ${machineName} and locate ${codebase.name} before sending code work there.`);
+}

package/dist/panel3/cli.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+/**
+ * ═══ AGENT PANEL v3: the `cs3` bin. ═══
+ *
+ * THIS FILE BELONGS TO AGENT PANEL v3. Nothing outside `src/panel3/` may
+ * import it.
+ *
+ * A SEPARATE BIN RATHER THAN A SUBCOMMAND OF `cs`, deliberately: v3 never
+ * touches v1's command router, so retiring either generation is deleting a
+ * directory and a line of `bin`, not unpicking a switch statement two
+ * generations share.
+ *
+ * ═══ AND SINCE recovery-1 SLICE 4, `run` IS NOT SOMETHING A PERSON TYPES. ═══
+ * Lane's ruling (2026-08-21): a person launches one CLI, `cs start`, and signs
+ * into it once. `cs start` now runs the panel's poll loop through `startPanel`,
+ * so that is the only launch the product ever names, and `cs3 run` is off the
+ * help text above.
+ *
+ * ═══ IT IS STILL HERE, AND IT IS NOT A SECOND OWNER OF THE LOOP. ═══ There is
+ * one `run()` in `run.ts` with two callers. This one signs in from
+ * `CTRL_SPC_V3_EMAIL` / `CTRL_SPC_V3_PASSWORD`, which is what lets
+ * `test/panel3-acceptance.mjs` and the three walk scripts stand a daemon up
+ * against their own isolated account and their own working copy without touching
+ * the installed CLI's `session.json` or its presence. Deleting it would mean
+ * rebuilding that isolation inside `cs start`, which is a launch path the tests
+ * would then own. DO NOT PUT IT BACK IN THE HELP TEXT.
+ *
+ * ═══ A FAILURE EXITS NON-ZERO AND SAYS WHY, ALWAYS. ═══ Every read in `show`
+ * and every write in `say` either returns its rows or throws, and this is the
+ * only handler. Nothing here converts a failure into an empty result, because a
+ * command whose whole job is observation is worthless the first time silence can
+ * mean either "nothing is there" or "the read failed", and a `say` that exited
+ * zero without writing would be an acknowledgement of nothing.
+ */
+import { answer } from './answer.js';
+import { run } from './run.js';
+import { say } from './say.js';
+import { show } from './show.js';
+const HELP = `cs3 — CTRL+SPC agent panel v3
+
+  cs3 say "<text>"              Start a card and put your message on it
+  cs3 say --project <p> "<text>"  Start it filed under that project (id or name)
+  cs3 say --card <id> "<text>"  Add a message to a card you already have
+  cs3 answer <id> "<text>"      Answer a question a card is waiting on you for
+  cs3 show                      Every card
+  cs3 show <id>                 One card in full, or one run with its brief and report
+  cs3 help                      Show this help
+
+This machine answers cards when \`cs start\` is running. These commands are the
+terminal's view of the same record.
+
+Acts as CTRL_SPC_V3_EMAIL / CTRL_SPC_V3_PASSWORD, against the hosted project
+by default. Point it at a local stack with:
+  CTRL_SPC_SUPABASE_URL=http://127.0.0.1:54321
+  CTRL_SPC_SUPABASE_KEY=<the local publishable key from \`supabase status\`>
+`;
+async function main() {
+    const command = process.argv[2];
+    switch (command) {
+        case 'say':
+            return say(process.argv.slice(3));
+        case 'answer':
+            return answer(process.argv.slice(3));
+        case 'run':
+            return run(process.argv.slice(3));
+        case 'show':
+            return show(process.argv[3]);
+        case undefined:
+        case 'help':
+        case '--help':
+        case '-h':
+            console.log(HELP);
+            return;
+        default:
+            console.error(`Unknown command: ${command}\n`);
+            console.log(HELP);
+            process.exitCode = 1;
+    }
+}
+main().catch((err) => {
+    console.error(`cs3: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+});

package/dist/panel3/client.js

@@ -0,0 +1,181 @@
+/**
+ * ═══ AGENT PANEL v3: what every v3 command talks to the record through. ═══
+ *
+ * THIS FILE BELONGS TO AGENT PANEL v3. Nothing outside `src/panel3/` may
+ * import it.
+ *
+ * ---------------------------------------------------------------------------
+ * WHY THE ERROR GUARD AND THE TWO PRINTERS LIVE HERE TOO.
+ *
+ * They were written twice, once in `show.ts` and once in `say.ts`, and a
+ * slightly different copy of something that already exists is a defect in this
+ * project rather than a delivery. The guard is the one that matters: it is where
+ * constraint 7 is actually enforced, and two copies of it means two places a
+ * later command could soften into returning null on failure. One owner, called
+ * by both, and every command added after this one inherits it rather than
+ * copying it a third time.
+ *
+ * ---------------------------------------------------------------------------
+ * WHY IT SIGNS IN EVERY TIME INSTEAD OF READING THE STORED SESSION.
+ *
+ * The installed CLI keeps one `session.json` on this machine and its long-lived
+ * daemon holds the access token that file names. A second process that reads it
+ * and lets the client refresh writes a ROTATED token back over the same file,
+ * and the daemon's token stops working. So v3 takes a fresh session of its own,
+ * in memory, and never touches the file: `persistSession: false`, and no v3
+ * client has any storage to write a rotated token into.
+ *
+ * ═══ THAT IS NOW TRUE OF THE COMMANDS AND NOT OF THE PANEL, AND THE DIFFERENCE
+ *     IS THE WORD "PROCESS". ═══ recovery-1 Slice 4: `cs start` runs the poll
+ * loop itself, and it hands `run()` THE CLIENT IT ALREADY HAS. Read the hazard
+ * above again with that in mind — it is about a SECOND PROCESS refreshing
+ * against a file the first one is relying on. Inside one process there is one
+ * client, `getClient()`'s, with one refresh loop and one update-only
+ * `onAuthStateChange` writer, so a rotation is the daemon rotating its own
+ * token. `signedInClient` must never be called from that path, because taking a
+ * session of its own there is what would recreate the race indoors.
+ *
+ * So this function now serves `show`, `say`, `answer`, and `cs3 run` as the
+ * acceptance harness's isolated entry — every one of them a process that is NOT
+ * the installed daemon, which is exactly the set the paragraph above describes.
+ *
+ * ---------------------------------------------------------------------------
+ * ═══ AND THE DAEMON'S CLIENT REFRESHES, WHILE A ONE-SHOT COMMAND'S DOES NOT.
+ *     ═══
+ *
+ * `autoRefreshToken` was off for every v3 client, which is right for `show`,
+ * `say` and `answer` — each signs in, does one thing and exits, long inside the
+ * access token's lifetime — and WRONG for `cs3 run`, which holds one client for
+ * as long as the daemon lives and hands that same client to every tool call an
+ * agent makes. Past the token's TTL every poll and every in-flight tool call
+ * would start failing, and the card would sit working with a daemon that could
+ * no longer read or write anything.
+ *
+ * ═══ THIS IS CLI v1's RECORDED ROOT CAUSE, AND IT WAS ON ITS WAY BACK IN. ═══
+ * MEMORY, "CLI v1 unreliability root cause": `autoRefreshToken: false` plus a
+ * long-lived connection plus swallowed 401s is why v1's presence went stale and
+ * nobody could say why. v3 does not swallow anything — `returned()` throws — so
+ * it would have failed loudly rather than silently, but it would still have
+ * failed, and no proof run here has ever been long enough to reach it.
+ *
+ * ═══ THE REASON THE FLAG WAS OFF STILL HOLDS, WHICH IS WHY ONLY THE FLAG
+ *     CHANGES. ═══ What must never happen is a v3 process writing a rotated
+ * token over the installed CLI's `session.json`. That is prevented by
+ * `persistSession: false`, not by this flag: with no persistence the client has
+ * no storage, so a refresh replaces a token held in memory by THIS process and
+ * touches no file on the machine. The two flags answer different questions —
+ * one is where a session is kept, the other is whether it is kept alive — and
+ * only the second was ever wrong here.
+ *
+ * ---------------------------------------------------------------------------
+ * ═══ THE CREDENTIALS COME FROM THE ENVIRONMENT, WITH NO DEFAULT. ═══
+ *
+ * They had one, the seeded local pair, on the grounds that `supabase/seed.sql`
+ * already commits it. THE TWO PLACES ARE NOT THE SAME. This package is
+ * published (`"files": ["dist"]`, `"access": "public"`), and `dist/` is
+ * committed, so a literal password here is one `npm publish` away from the
+ * public registry — a harm about DISTRIBUTION that the loopback guard below,
+ * which is about where a request is SENT, does nothing to prevent. So there is
+ * no fallback: unset means refuse, and say where to get them.
+ *
+ * ---------------------------------------------------------------------------
+ * ═══ THE LOOPBACK-ONLY GUARD IS GONE, AND THIS IS THE EDIT IT ASKED FOR. ═══
+ *
+ * It read: "this build runs against the local stack alone and its migrations
+ * are not pushed until Lane says so", and it refused any host that was not
+ * loopback so an unset `CTRL_SPC_SUPABASE_URL` could not silently aim a v3
+ * command at production. It ended by naming its own removal: "the task that
+ * first points v3 at a hosted project removes it, deliberately and in one
+ * edit."
+ *
+ * That day is 2026-08-19. The 28 `panel3_` migrations are applied to the hosted
+ * project and recorded in its ledger, so the tables the guard was protecting
+ * the absence of now exist. Keeping it would mean v3 could never be run against
+ * the database it was just given.
+ *
+ * WHAT REPLACED IT IS NOT NOTHING. The two things the guard was standing in for
+ * are still enforced, and by the mechanisms that actually answer them:
+ *
+ *   - A v3 process must never write a rotated token over the installed CLI's
+ *     `session.json`. That is `persistSession: false`, below, and always was.
+ *   - A password must never ship in this package. That is the refusal a few
+ *     lines down: the credentials come from the environment with no fallback,
+ *     because `dist/` is committed and published.
+ *
+ * What is left is that `CTRL_SPC_SUPABASE_URL` decides where a command goes,
+ * which is the same rule every other surface in this repository lives by.
+ */
+import { createClient } from '@supabase/supabase-js';
+import { SUPABASE_URL, SUPABASE_KEY } from '../env.js';
+/**
+ * How a v3 client holds its session, for the two lifetimes v3 has.
+ *
+ * Exported so the rule can be checked without signing in, exactly as
+ * `agentArgs` and `toolNamesForLevel` are: a flag nobody can print is a flag
+ * nobody can check, and this one is invisible until a run outlives a token.
+ */
+export const sessionOptions = (living) => ({
+    /* NEVER TRUE, AT EITHER LIFETIME. It is what keeps a v3 process from writing a
+       rotated token over the installed CLI's `session.json`. */
+    persistSession: false,
+    /* THE DAEMON'S CLIENT ONLY. See the header: a one-shot command exits inside
+       the token's lifetime, and the daemon does not. */
+    autoRefreshToken: living,
+});
+/**
+ * @param living whether this client outlives its access token. The daemon's
+ * does; every one-shot command's does not.
+ */
+export async function signedInClient(living = false) {
+    const email = process.env.CTRL_SPC_V3_EMAIL;
+    const password = process.env.CTRL_SPC_V3_PASSWORD;
+    if (!email || !password) {
+        throw new Error('set CTRL_SPC_V3_EMAIL and CTRL_SPC_V3_PASSWORD to the account this command '
+            + `should act as at ${SUPABASE_URL}`);
+    }
+    const client = createClient(SUPABASE_URL, SUPABASE_KEY, { auth: sessionOptions(living) });
+    const { data, error } = await client.auth.signInWithPassword({ email, password });
+    // Truthfully, and naming both halves of what was attempted: a wrong password
+    // and a stack that is not running are different problems with the same
+    // symptom at the call site, and the message has to tell them apart.
+    if (error) {
+        throw new Error(`could not sign in as ${email} at ${SUPABASE_URL}: ${error.message}`);
+    }
+    if (!data.session) {
+        throw new Error(`sign-in as ${email} at ${SUPABASE_URL} returned no session`);
+    }
+    return client;
+}
+// ---------------------------------------------------------------------------
+// ═══ WHAT A QUERY GAVE BACK, OR WHY IT COULD NOT. ═══
+//
+// The one place a v3 command turns a Supabase result into a value, and it either
+// returns the data or throws. Constraint 7 lives here: NOTHING converts a
+// failure into an empty array, a null or a success, because a `show` that
+// printed "No cards." on a failed read and a `say` that exited zero without
+// writing are the same lie told by two commands.
+//
+// The second guard is the one that is easy to leave out. No error AND no data is
+// not "nothing is there" — it is a result this code does not understand, and
+// passing it on as an empty value is how a failure becomes a silent success.
+//
+// The caller passes the VERB and the SUBJECT rather than a finished sentence, so
+// one shared guard still says `could not read panel3_turns` and `could not create
+// the card` rather than collapsing every failure into the same vague line.
+export async function returned(query, verb, subject) {
+    const { data, error } = await query;
+    if (error)
+        throw new Error(`could not ${verb} ${subject}: ${error.message}`);
+    if (!data) {
+        throw new Error(`could not ${verb} ${subject}: neither data nor an error came back`);
+    }
+    return data;
+}
+// ---------------------------------------------------------------------------
+// PRINTING. Shared for the plainer reason: two copies of `at()` is two ways the
+// same instant could come to be printed differently in two commands.
+/** One line to stdout. */
+export const out = (line = '') => console.log(line);
+/** UTC, to the second. A local time would read differently on two machines
+ *  comparing the same run. */
+export const at = (iso) => `${new Date(iso).toISOString().slice(0, 19).replace('T', ' ')}Z`;

package/dist/panel3/coordinator.js

@@ -0,0 +1,18 @@
+import { returned } from './client.js';
+/**
+ * Read the designation. `cliv2_orchestrator_preference` carries `unique
+ * (user_id)`, so RLS alone (`auth.uid() = user_id`) can never return more than
+ * one row for the signed-in caller, and this is never an ambiguous read.
+ *
+ * ═══ A FAILED READ THROWS RATHER THAN RETURNING NULL. ═══ Constraint 4. A
+ * read that failed is not "nothing is designated" — that reading would let a
+ * transient error silently reopen the exact race the migration's shared lease
+ * closes, and would tell a person nobody is designated when the truth is
+ * unknown. `returned()` already throws on an error or an unreadable result;
+ * this function adds nothing on top of it.
+ */
+export async function designatedCoordinator(client) {
+    const rows = await returned(client.from('cliv2_orchestrator_preference').select('machine_id, agent'), 'read', 'which machine and harness are designated to coordinate');
+    const row = rows[0];
+    return row ? { machineId: row.machine_id, agent: row.agent } : null;
+}

package/dist/panel3/presence.js

@@ -0,0 +1,162 @@
+import { returned } from './client.js';
+/** How old a row may be and still read as listening.
+ *
+ *  THE DAEMON REFRESHES IT ON EVERY POLL, so this is several polls' grace rather
+ *  than one: a poll that spent a second on a slow query, or a machine whose
+ *  clock is a little out, must not flip every card on screen to "waiting for a
+ *  machine" and back. It is the same ratio v2 uses (`CLIV2_ONLINE_MS` is three
+ *  heartbeats), at the shorter cadence a card deserves. */
+export const LISTENING_WINDOW_MS = 15_000;
+/** Is this machine still listening?
+ *
+ *  THE ONE PREDICATE, shared by `cs3 show` and the panel, so the two screens
+ *  cannot disagree about whether anything can pick a card up.
+ *
+ *  ═══ IT TAKES THE ROW, NOT A TIMESTAMP, BECAUSE FRESHNESS IS NO LONGER THE
+ *      WHOLE ANSWER. ═══ Since 20260907090000 a daemon that exits cleanly stamps
+ *  `stopped_at` and KEEPS its row, so a row can be two seconds old and still
+ *  belong to a machine that has gone. Filtering `stopped_at is null` in each
+ *  query instead would put the rule in as many places as there are reads, and
+ *  the panel needs one read that returns stopped rows TOO, in order to name a
+ *  machine that is not listening. One rule, one spelling. */
+export function isListening(machine, now = Date.now()) {
+    // A daemon that said goodbye is not listening, however fresh its last
+    // heartbeat was. Checked first, because it is the one case the window cannot
+    // see and the whole reason the column exists.
+    if (machine.stopped_at !== null)
+        return false;
+    const seen = new Date(machine.last_seen_at).getTime();
+    // An unparseable timestamp is not a machine that is listening. Returning true
+    // here would be the expensive lie ux.md names, told about a row we cannot read.
+    if (Number.isNaN(seen))
+        return false;
+    return now - seen < LISTENING_WINDOW_MS;
+}
+/**
+ * Say this machine is listening, or refresh what it already said.
+ *
+ * ═══ IT THROWS RATHER THAN SHRUGGING. ═══ Constraint 7. A heartbeat that failed
+ * quietly is a daemon that is polling while every card on screen says nothing
+ * will pick it up, which is the same lie in the other direction, and the caller
+ * decides what to do about it rather than never hearing.
+ *
+ * ═══ `name` AND `harness` ARE THE CALLER'S TO SAY, NEVER THIS FILE'S TO WORK
+ *     OUT. ═══ `name` is `os.hostname()`, a label for the person reading the
+ * title bar and never an identifier (`machine_id` stays part of the key).
+ * `harness` is `harness()` from `spawn.ts`, REPORTED rather than chosen: the
+ * columns are `not null` with no default (20260902090000) precisely so a
+ * heartbeat that cannot say which harness it runs fails loudly instead of
+ * guessing.
+ *
+ * ═══ THE CONFLICT TARGET IS `(user_id, machine_id, harness)`, NOT
+ *     `(user_id, machine_id)`. ═══ 20260903140000: one machine running two
+ * harnesses is two daemons, and a key that could not tell them apart had them
+ * overwrite the same row every poll, flipping a card between working and
+ * waiting for no reason a person watching could see. Two daemons for the same
+ * machine and the same harness — a restart racing its own predecessor — still
+ * collapse onto one row, which is the one collision this key is still meant
+ * to prevent.
+ */
+export async function sayListening(client, machineId, name, harness) {
+    /* ═══ THE ERROR IS CHECKED DIRECTLY, RATHER THAN THROUGH `returned`. ═══ That
+       helper also refuses a null body, which is right for every read in v3 and
+       wrong for exactly this write: a write with no `select()` comes back 204 with
+       no content, so `returned` called a successful heartbeat a failure and the
+       daemon printed one every two seconds while the row it had just written sat
+       there. A write that says nothing is a write that worked. */
+    const { error } = await client
+        .from('panel3_machines')
+        /* `user_id` is left to the column default (`auth.uid()`), which is what the
+           RLS check compares against: a caller that named its own owner could only
+           ever name itself, so sending one buys nothing and invites a mismatch. */
+        .upsert({
+        machine_id: machineId,
+        name,
+        harness,
+        last_seen_at: new Date().toISOString(),
+        /* ═══ AND A HEARTBEAT CLEARS `stopped_at`, WHICH IS WHAT MAKES A RESTART
+           WORK AT ALL. ═══ The row survives a clean exit now (20260907090000),
+           so a daemon coming back would otherwise upsert onto a row still
+           stamped as gone and stay invisible for as long as it ran. Sent on
+           EVERY poll rather than only the first: nothing here knows which poll
+           is the first, and a daemon that is polling is listening whatever it
+           last did. */
+        stopped_at: null,
+    }, { onConflict: 'user_id,machine_id,harness' });
+    if (error)
+        throw new Error(`could not say this machine is listening: ${error.message}`);
+}
+/**
+ * Stop saying it, because this daemon is going away.
+ *
+ * ═══ IT MARKS THE ROW; IT DOES NOT DELETE IT. ═══ 20260907090000: `name` lives
+ * on this row and nowhere else, and recovery Slice 1's card has to NAME the
+ * machine whose work has been left behind. Deleting took that name away on the
+ * one path a person actually walks, Ctrl-C. Stamping `stopped_at` is the same
+ * single write at the same moment and reads as not-listening on the very next
+ * poll, so nothing about how fast a clean stop becomes true on screen changed.
+ * An update matching no row is a no-op, which is exactly right for a daemon
+ * that never got as far as writing one.
+ *
+ * ═══ SCOPED TO THIS DAEMON'S OWN ROW, BY MACHINE AND HARNESS. ═══ 20260903140000:
+ * a machine can run two daemons at once, one per harness, each its own row. A
+ * stop by `machine_id` alone would mark BOTH rows the moment either daemon
+ * exited, telling every card that nothing on that machine is listening while
+ * the sibling harness is still polling, which is exactly the lie this table
+ * exists to end, produced from the other side by exiting too thoroughly.
+ *
+ * Best-effort by design: a process that is exiting must not hang or fail on the
+ * way out, and the freshness window is what covers every way a machine can leave
+ * without getting here.
+ */
+export async function stopListening(client, machineId, harness) {
+    try {
+        await client
+            .from('panel3_machines')
+            .update({ stopped_at: new Date().toISOString() })
+            .eq('machine_id', machineId)
+            .eq('harness', harness);
+    }
+    catch {
+        // The window covers it. See the header.
+    }
+}
+/** This account's machines that are listening right now, with what a screen
+ *  needs to show a fleet rather than a count: the name and harness beside the
+ *  id. Filtered through the one `isListening` predicate, so nothing here can
+ *  disagree with `coordination` below about which rows count.
+ *
+ *  ═══ THE ID-ONLY READ (`listeningMachines`) IS GONE, DELIBERATELY. ═══ `show.ts`
+ *  was its only caller, wanting an id list and a length check, and Task 4 gave
+ *  it both a coordinator to name and a harness to print beside each machine —
+ *  which only this row shape carries. A second near-identical select earning
+ *  its keep on a length check alone, once the one caller that wanted only that
+ *  is gone, is the duplicate this project's guide says to remove rather than
+ *  leave standing beside its replacement. */
+export async function listeningFleet(client) {
+    const rows = await returned(client.from('panel3_machines').select('machine_id, name, harness, last_seen_at, stopped_at'), 'read', 'which machines are listening');
+    return rows.filter((r) => isListening(r));
+}
+export function coordination(designation, fleet) {
+    if (designation === null)
+        return fleet.length > 0 ? 'here' : 'nobody';
+    if (fleet.some((m) => m.machine_id === designation.machineId && m.harness === designation.agent)) {
+        return 'here';
+    }
+    return fleet.length > 0 ? 'elsewhere' : 'nobody';
+}
+export function elsewhereMismatch(designation, fleet) {
+    const machineListening = fleet.some((m) => m.machine_id === designation.machineId);
+    const harnessListening = fleet.some((m) => m.harness === designation.agent);
+    /* ═══ BOTH HALVES PRESENT MEANS TWO ROWS, NOT ONE, BECAUSE ONE ROW SUPPLYING
+       BOTH IS `coordination()`'s OWN `'here'`. ═══ So this is never a weaker
+       answer than `'harness'` or `'machine'` alone — it is a strictly more
+       specific one, and it is checked first. */
+    if (machineListening && harnessListening)
+        return 'split';
+    if (machineListening)
+        return 'harness';
+    if (harnessListening)
+        return 'machine';
+    return 'neither';
+}