@ctrl-spc/cs 0.7.2 → 0.7.4

package/dist/panel3/client.js

@@ -118,6 +118,7 @@
 import { createClient } from '@supabase/supabase-js';
 import { SUPABASE_URL, SUPABASE_KEY } from '../env.js';
 import { readSession } from '../config.js';
+import { readableWriteError } from '../firewall.js';
 /**
  * How a v3 client holds its session, for the two lifetimes v3 has.
  *
@@ -202,7 +203,7 @@ export async function signedInClient(living = false) {
 export async function returned(query, verb, subject) {
     const { data, error } = await query;
     if (error)
-        throw new Error(`could not ${verb} ${subject}: ${error.message}`);
+        throw new Error(`could not ${verb} ${subject}: ${readableWriteError(error.message)}`);
     if (!data) {
         throw new Error(`could not ${verb} ${subject}: neither data nor an error came back`);
     }

package/dist/panel3/prompt.js

@@ -130,6 +130,7 @@
  * how to write it travels with `write_report`'s own description, where ux.md
  * says the how belongs.
  */
+import { FIREWALL_WRITING_RULE } from '../firewall.js';
 /**
  * ═══ WHAT EVERY LEVEL IS TOLD ABOUT THE THING IT SENDS BACK. ═══
  *
@@ -429,9 +430,12 @@ const projectCodebases = (codebases) => {
  * — which matters because the daemon writes it to `panel3_runs.brief`.
  *
  * ═══ `cardTitle` IS A NAME, NOT THE QUESTION, AND ITS LABEL SAYS SO. ═══ `say`
- * fixes it once, as the truncated first line of the FIRST message, and never
- * changes it. Labelled as what is being asked, a second turn would tell the
- * agent the current question is a stale half-sentence and then hand it the real
+ * writes it as the truncated first line of the FIRST message, and the launcher
+ * may replace it once, with `dispatch`'s `work_name`, so that it names the work
+ * rather than that sentence. Either way it names the CONVERSATION and not what
+ * is currently being asked: it is written before the first answer and nothing
+ * touches it after. Labelled as what is being asked, a second turn would tell
+ * the agent the current question is the opening line and then hand it the real
  * ones underneath — so the label names the conversation, which is all the title
  * has ever been.
  *
@@ -494,6 +498,18 @@ export function levelOnePrompt(cardTitle, messages, produced, attachments = [],
         '',
         'WHAT THIS CONVERSATION IS CALLED',
         cardTitle,
+        /* ═══ THE ONE MOMENT ANYTHING CAN NAME THE WORK. ═══ Until the owner is
+           sent, this is the truncated first line of the person's first message, and
+           sending the owner cuts the branch for the work from it and stamps that
+           branch for good. The launcher is the only thing that runs in between, and
+           it has the messages in front of it, so it is the only thing that can say
+           what the work is before both are fixed. */
+        'This is the first line of what they typed, so it names their sentence rather than the work. If',
+        'the person pointed this conversation at a work item, that item is already its name and there is',
+        'nothing to do. Otherwise pass `work_name` to `dispatch`: a few words, six at most, naming the',
+        'work itself, such as "Fix the sign-out checklist bug". The conversation is called that from',
+        'then on, and the branch the work goes on is cut from it, both as you send the owner. This is',
+        'the only moment either can be named.',
         '',
         'WHAT HAS ALREADY BEEN MADE HERE',
         'Everything this conversation has produced so far, whatever it was that made it, with the id to',
@@ -727,6 +743,9 @@ export function workBrief(level, responsibility, boundary, workItemId, attachmen
         'not what you were halfway through. Notes written at the end of the work are notes that were',
         'never written.',
         '',
+        'ANYTHING YOU SAVE GOES THROUGH A FIREWALL',
+        FIREWALL_WRITING_RULE,
+        '',
         ...WHILE_YOU_ARE_WORKING,
         '',
         ...(level === 2

package/dist/panel3/run.js

@@ -132,6 +132,7 @@
 // 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 { readableWriteError } from '../firewall.js';
 import { answerPrompt, escalationPrompt, levelOnePrompt, ownerActivationPrompt, readBackPrompt, landingOutcomeContext, presentedArtifactAnswerContext, resumePrompt, retryPrompt, standingRules, whatWasAttached, workingRules, } from './prompt.js';
 import { ASK_CONTENT_COLUMNS, attachmentLine, gitRulesFor, loadAttachments, loadOutputNames, outputOf, recordBaseProtection, standingRulesFor, withAskContent, } from './show.js';
 import { forgetSecrets, redactSecrets } from './secrets.js';
@@ -140,12 +141,15 @@ import { designatedCoordinator } from './coordinator.js';
 import { baseBranchState, checkoutForCodebase, commitCardWork, detectBaseProtection, folderIsBranch, hasCheckoutForCodebase, mergeIntoBase, releaseBaseBranch, settleCardWorktree, worktreeForCard, worktreesOnThisMachine, } from './checkout.js';
 import { harness, startAgent } from './spawn.js';
 import { establishOwnerSession, listOwnerSessionIds, OWNER_SESSION_GRACE_MS, readOwnerSession, removeOwnerSession, validSessionUuid, writeOwnerSession, } from './session.js';
-import { startToolsServer } from './tools.js';
+import { startToolsServer, PANEL3_IMAGES_BUCKET } from './tools.js';
 import { listPanel3CodexOwnerHomeIds, removePanel3CodexOwnerHome, } from '../codex-home.js';
 import { getMachineIdentity, scratchDir } from '../config.js';
 import { listCodebases } from '../codebases.js';
 import { killTree, processIsAlive } from '../win-shell.js';
 import { hostname, uptime } from 'node:os';
+import { execFileSync } from 'node:child_process';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
 const USAGE = 'usage: 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
@@ -454,7 +458,14 @@ whereYouAre = [],
    the rules; rendering it underneath would put it below a block saying it
    wins. Already carries its own header and its own leading blank, which this
    join absorbs the same way it absorbs `whereYouAre`'s. */
-whatIsAttached = []) => {
+whatIsAttached = [], 
+/* ═══ THE PICTURES ON THIS CARD, ALREADY ON DISK (33 Slice 6). ═══ Its own
+   parameter for `whatIsAttached`'s reason: these are neither a fact about the
+   machine nor something the person attached to the card, they are files this
+   spawn has just written, and the paths are only knowable after the cwd is
+   resolved. Below the rules and beside the codebase block, because a picture
+   is a fact about where this run is rather than an instruction. */
+pictures = []) => {
     /* `whatWasAttached` begins its array with a blank, since its two other
        callers join it onto lines already above it. Here it is the first thing in
        the prompt, and a prompt that opens on an empty line is a prompt with a
@@ -467,6 +478,7 @@ whatIsAttached = []) => {
         ...(attached.length === 0 ? [] : [...attached, '']),
         ...standingRules(documents),
         ...(whereYouAre.length === 0 ? [] : ['', ...whereYouAre]),
+        ...(pictures.length === 0 ? [] : ['', ...pictures]),
     ];
     return block.length === 0 ? prompt : [...block, '', prompt].join('\n');
 };
@@ -587,7 +599,7 @@ async function writeAnswer(client, runId, cardId, text, processToken) {
            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}`);
+        throw new Error(`could not write the answer to card ${cardId}: ${readableWriteError(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
@@ -964,6 +976,96 @@ async function refreshBaseProtection(client, codebase, rules, source, base) {
         said(`could not check whether ${base} is protected: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
+/**
+ * ═══ THE PICTURES ON THIS CARD, ON DISK WHERE THE AGENT CAN READ THEM, AND THE
+ *     LINES THAT TELL IT SO (33 Slice 6). ═══
+ *
+ * ═══ WHY A FILE AND NOT A TOOL RESULT. ═══ `ToolDef['handler']` returns
+ * `Promise<string>` and `buildServer` wraps it in one text block, so a tool
+ * cannot hand back an image. But that is not the reason: `spawn.ts` already
+ * grants levels 2 and 3 the harness's own `Read`, which renders an image
+ * natively, works in both harnesses, and is how every other file reaches an agent
+ * here. A file on disk needs no new tool, no new allowlist entry, and — the part
+ * that decides it — no decision by the model to call anything.
+ *
+ * ═══ WHY THE RUN'S OWN CWD AND NOT `scratchDir()`. ═══ `workingDirectory` gives
+ * the scratch directory only to level 1 and to a level 2 owner with no codebase;
+ * every level 3 worker and every run with a codebase gets a WORKTREE. `agentArgs`
+ * passes no `--add-dir` and `--setting-sources ''` strips anything that might
+ * have supplied one, so a path outside the cwd is a path the child must ask
+ * permission to read — with nobody at the keyboard to answer. Writing into the
+ * directory the run already has needs no widening of what any worker may read.
+ *
+ * ═══ AND INSIDE `git rev-parse --git-dir`, WHICH IS THE PART THAT WAS MEASURED
+ *     RATHER THAN REASONED ABOUT. ═══ A folder in the working tree shows as `??`
+ * in `git status`, and `settleCardWorktree` commits unconditionally — so a
+ * picture left there is a picture committed onto the card's branch. And
+ * `.git/info/exclude` cannot be used: in a linked worktree `.git` is a FILE
+ * holding a `gitdir:` pointer, and `git rev-parse --git-path info/exclude`
+ * resolves to the SHARED repository's exclude file, so writing it would alter
+ * every other worktree and the person's own clone. The git dir resolves per
+ * worktree, sits inside what the agent may read, and is invisible to
+ * `git status`.
+ *
+ * For a scratch cwd, which is not a repository, the files go in the cwd itself.
+ *
+ * ═══ THE PATH IS HANDED TO A PROCESS, NEVER STORED. ═══ `spawn.ts`'s stated
+ * rule: a path passed to a process is not a path stored in a row. Nothing here
+ * writes one back.
+ *
+ * A failure to fetch one picture is NOT fatal and does not stop the others: an
+ * agent starting without a picture it was never told about is a worse outcome
+ * than one that starts and is told about the pictures that did arrive.
+ */
+// Exported for `withStandingRules`' and `briefFor`'s reason: the seam this
+// feature crosses is a real file on disk and the lines naming it, and a test
+// over the spawn sites would prove nothing about either.
+export async function picturesOnDisk(client, cardId, where, level) {
+    /* ═══ LEVEL 1 IS TOLD NOTHING, BECAUSE IT HAS NO `Read`. ═══ `builtIns` serves
+       it no code tool at all, so naming a file it cannot open would be an
+       instruction it must fail. */
+    if (level === 1)
+        return [];
+    const images = await returned(client.from('panel3_images').select('id, storage_path, caption')
+        .eq('card_id', cardId).order('created_at'), 'read', `the pictures on card ${cardId}`);
+    if (images.length === 0)
+        return [];
+    const folder = join(gitDirOf(where.cwd) ?? where.cwd, 'ctrl-spc-images');
+    await mkdir(folder, { recursive: true });
+    const lines = [];
+    for (const image of images) {
+        const file = join(folder, `${image.id}.png`);
+        const { data, error } = await client.storage.from(PANEL3_IMAGES_BUCKET).download(image.storage_path);
+        if (error || !data) {
+            out(`images   could not fetch ${image.id}: ${error?.message ?? 'no data'}`);
+            continue;
+        }
+        await writeFile(file, Buffer.from(await data.arrayBuffer()));
+        /* THE PATH, NOT AN ID. `Read` takes a path directly, so there is nothing for
+           the agent to resolve and no tool for it to remember. The caption is
+           included when there is one, because a worker's picture carries its words
+           on the row rather than in a turn the agent can read. */
+        lines.push(`Image: ${file}. Read it before you answer about it.`
+            + (image.caption === null ? '' : ` It was shown with: "${image.caption}"`));
+    }
+    if (lines.length === 0)
+        return [];
+    return ['PICTURES ON THIS CARD', ...lines];
+}
+/** The git directory for `folder`, or null when it is not a repository. Resolved
+ *  per worktree, which is the whole point: a linked worktree's git dir is its
+ *  own, and the shared repository's is not. */
+function gitDirOf(folder) {
+    try {
+        const found = execFileSync('git', ['-C', folder, 'rev-parse', '--absolute-git-dir'], {
+            encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        return found === '' ? null : found;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * ═══ WHAT THE COORDINATOR IS TOLD ABOUT EACH CODEBASE IT MAY SEND WORK TO. ═══
  *
@@ -1061,7 +1163,7 @@ async function startChild(client, tools, machineId, parentRunId, brief, codebase
         ...(parentProcessToken === undefined ? {} : { p_process_token: parentProcessToken }),
     });
     if (error)
-        throw new Error(`could not start an agent under run ${parentRunId}: ${error.message}`);
+        throw new Error(`could not start an agent under run ${parentRunId}: ${readableWriteError(error.message)}`);
     const row = data?.[0];
     if (!row) {
         /* NOTHING WAS WRITTEN AND NOTHING IS RUNNING, and the two reasons are said
@@ -1084,6 +1186,7 @@ async function startChild(client, tools, machineId, parentRunId, brief, codebase
     const level = row.run_level;
     let where;
     let prompt;
+    let pictures;
     /* READ AGAINST THE CHILD'S OWN RUN ROW, NOT THE PARENT'S. The row already
        exists (`panel3_dispatch` wrote it above) and it carries this child's
        codebase, which is what decides which codebase-scoped rules it is under. */
@@ -1094,6 +1197,10 @@ async function startChild(client, tools, machineId, parentRunId, brief, codebase
             ? await initialOwnerPrompt(client, row.run_card_id, parentRunId, brief)
             : brief;
         rules = await standingRulesFor(client, row.run_id);
+        /* Inside this site's own try, for `standingRulesFor`'s reason: a failure to
+           assemble what the agent needs ends the run the way this path already ends
+           runs, rather than starting a process that is missing it. */
+        pictures = await picturesOnDisk(client, row.run_card_id, where, level);
     }
     catch (error) {
         const why = error instanceof Error ? error.message : String(error);
@@ -1102,7 +1209,7 @@ async function startChild(client, tools, machineId, parentRunId, brief, codebase
     }
     const processToken = row.process_token ?? undefined;
     const isOwner = level === 2;
-    const started = startAgent(withStandingRules(rules, prompt, where.block), level, tools.urlFor(row.run_id, processToken), where.cwd, isOwner ? { ownerId: row.run_id } : undefined);
+    const started = startAgent(withStandingRules(rules, prompt, where.block, [], pictures), level, tools.urlFor(row.run_id, processToken), where.cwd, isOwner ? { ownerId: row.run_id } : undefined);
     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
@@ -1572,8 +1679,14 @@ async function resumeRun(client, tools, machineId, runId, afterPid) {
        is a `returned()` message naming tables and columns, which carries no local
        path and is therefore shareable. */
     let rules;
+    let pictures;
     try {
         rules = await standingRulesFor(client, runId);
+        /* ═══ WRITTEN AGAIN ON EVERY START, LIKE THE RULES. ═══ A resumed process is
+           a NEW process with a new copy of the working directory, so the files a
+           previous one was handed are not there any more, and the stored brief this
+           path replays cannot carry a path that was not known when it was written. */
+        pictures = await picturesOnDisk(client, claimed.run_card_id, where, level);
     }
     catch (error) {
         const why = error instanceof Error ? error.message : String(error);
@@ -1587,7 +1700,7 @@ async function resumeRun(client, tools, machineId, runId, afterPid) {
        still running. See `retryPrompt`. */
     withStandingRules(rules, afterPid === null
         ? resumePrompt(claimed.run_brief, claimed.run_report, children)
-        : retryPrompt(claimed.run_brief, claimed.run_report, children), where.block), level, tools.urlFor(runId), where.cwd);
+        : retryPrompt(claimed.run_brief, claimed.run_report, children), where.block, [], pictures), level, tools.urlFor(runId), where.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
@@ -1694,15 +1807,17 @@ async function startRearmed(client, tools, machineId, row) {
        same way: the re-arm's claim has already happened, so a failure here ends
        the run with its reason rather than leaving it claimed with no process. */
     let rules;
+    let pictures;
     try {
         rules = await standingRulesFor(client, row.run_id);
+        pictures = await picturesOnDisk(client, row.run_card_id, where, level);
     }
     catch (error) {
         const why = error instanceof Error ? error.message : String(error);
         await endRun(client, level, row.run_id, row.run_card_id, why);
         throw new Error(`NO AGENT IS RUNNING: ${why}`);
     }
-    const started = startAgent(withStandingRules(rules, prompt, where.block), level, tools.urlFor(row.run_id), where.cwd);
+    const started = startAgent(withStandingRules(rules, prompt, where.block, [], pictures), level, tools.urlFor(row.run_id), where.cwd);
     if (started.pid === null) {
         const answer = await started.answered;
         const reason = answer.ok ? 'the process ended before it could be identified' : answer.reason;
@@ -1950,11 +2065,17 @@ async function activateOwner(client, tools, machineId, runId, afterProcessToken
        activation does not. This block carries the PERSON's attachments; where the
        owner is working is `where.block`'s answer. */
     let attached;
+    let pictures;
     try {
         where = await ownerDirectory(client, candidate);
         rules = await standingRulesFor(client, runId);
         attached = whatWasAttached((await attachmentsFor(client, claimed.run_card_id))
             .filter((line) => !line.startsWith('codebase  ')));
+        /* ═══ THE OWNER'S OWN ACTIVATION, WHICH IS WHERE MOST PICTURES ARRIVE. ═══
+           The person sends one and this is the run that reads it. Written on every
+           activation rather than once, so an owner resumed into an existing native
+           conversation is told again about a directory a previous process wrote. */
+        pictures = await picturesOnDisk(client, claimed.run_card_id, where, 2);
     }
     catch (error) {
         const why = error instanceof Error ? error.message : String(error);
@@ -1980,7 +2101,7 @@ async function activateOwner(client, tools, machineId, runId, afterProcessToken
            are not the same event and `prompt.ts` exists to stop an agent being
            told an untrue reason for its own restart. */
         afterPid !== null, landing);
-    const started = startAgent(withStandingRules(rules, prompt, where.block, attached), 2, tools.urlFor(runId, claimed.process_token), where.cwd, { ownerId: runId, ...(resumeSessionId ? { resumeSessionId } : {}) });
+    const started = startAgent(withStandingRules(rules, prompt, where.block, attached, pictures), 2, tools.urlFor(runId, claimed.process_token), where.cwd, { ownerId: runId, ...(resumeSessionId ? { resumeSessionId } : {}) });
     if (started.pid === null) {
         const answer = await started.answered;
         const reason = answer.ok ? 'the process ended before it could be identified' : answer.reason;
@@ -1997,7 +2118,38 @@ async function activateOwner(client, tools, machineId, runId, afterProcessToken
         settled: settle(client, tools, machineId, 2, runId, claimed.run_card_id, started, true, claimed.process_token, ownerSessionLifecycle(started, runId, machineHarness, claimed.process_token, resumeSessionId)),
     };
 }
-/** The only owner rows the normal poll may try, including an explicit hand-back move. */
+/** The only owner rows the normal poll may try, including an explicit hand-back move.
+ *
+ * ═══ A CARD THAT IS OVER HAS NO ACTIVATION TO TAKE, AND THE POLL MUST KNOW
+ *     THAT WITHOUT ASKING. ═══ `panel3_take_owner_activation` already refuses
+ * every one of these, so the rows were never started; what the refusal cost was
+ * the ASKING. A finished owner stays `finished` forever and its card stays
+ * `done` forever, so each one was re-offered on every poll for the life of the
+ * account: measured here, 35 owners, ~340ms per round trip, ~12s added to a
+ * single poll. The heartbeat at the top of that poll is written once per
+ * iteration, and `isListening`'s window is 15s, so a long enough tail of
+ * finished cards pushes the gap past the window and every card on screen reads
+ * `Nothing is listening` off a daemon that is polling perfectly.
+ *
+ * The card's state is the right gate rather than the run's, because it is what
+ * says the conversation is over: a `finished` owner on a `working` card is
+ * exactly the row a person's next message re-activates, and it must still be
+ * offered. It is read here off the row the poll already has (`card:` is
+ * embedded in the candidates select), so the check costs nothing.
+ *
+ * ═══ THE GATE NAMES THE LIVE STATES, NOT THE TERMINAL ONES. ═══ There are three
+ * ways a card ends — `done`, `failed` and `stopped` (20260828140000) — and only
+ * two ways it is live. Enumerating the terminals is the spelling that rots: it
+ * was written that way first and let `stopped` straight through, because
+ * `stopped` was added to the check constraint by a later migration than the one
+ * that introduced the other three. A state this file has never heard of is far
+ * likelier to be a new ending than a new kind of alive, and the safe direction
+ * for an unknown is to keep asking rather than to go silent, which is what
+ * naming the live pair gives.
+ *
+ * A hand-back is deliberately NOT gated on it: `handed_back_at` is a person
+ * asking for the work to move, and the RPC owns whether that is still possible.
+ */
 export function ownerPollClaim(candidate) {
     if (candidate.state === 'running') {
         if (candidate.handed_back_at === null || candidate.process_token === null)
@@ -2005,6 +2157,12 @@ export function ownerPollClaim(candidate) {
         return { afterProcessToken: candidate.process_token, afterPid: null };
     }
     if (candidate.state === 'finished' || candidate.state === 'asked') {
+        /* Undefined means a caller that does not carry the card, which keeps the
+           old behaviour rather than silently refusing a row it cannot judge. */
+        if (candidate.card_state !== undefined
+            && candidate.card_state !== 'working'
+            && candidate.card_state !== 'needs-you')
+            return null;
         return { afterProcessToken: null, afterPid: null };
     }
     return null;
@@ -2130,7 +2288,7 @@ async function takeOwnerActivations(client, tools, machineId, mine, hold) {
                 || (candidate.pid === null
                     && Date.now() - new Date(candidate.resumed_at ?? candidate.started_at).getTime() < PID_GRACE_MS)))
             continue;
-        const claim = ownerPollClaim(candidate);
+        const claim = ownerPollClaim({ ...candidate, card_state: candidate.card?.state ?? null });
         if (!claim)
             continue;
         try {
@@ -2674,8 +2832,20 @@ export async function takeHandedBack(client, tools, machineId, mine, hold) {
  * 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.
+ * already has one, OR a function returning whichever client the caller is
+ * holding NOW. Its presence is also what says THIS PROCESS IS NOT v3's, so the
+ * signals belong to somebody else — see the handler block below.
+ *
+ * ═══ A FUNCTION, BECAUSE THE CALLER'S CLIENT CAN BE REPLACED UNDER THIS LOOP.
+ * ═══ Under `cs start` the injected client is v2 presence's, and presence
+ * REBUILDS it when `session.json` comes to hold a different refresh token. A
+ * value captured once at startup is then a client the database refuses and
+ * nobody watches for `SIGNED_OUT`, while this loop goes on writing
+ * `panel3_machines` every two seconds against it: 37,051 writes in one window,
+ * which was the single largest contributor to the incident this parameter was
+ * widened for. The acceptance harness still passes a plain client, which is
+ * normalised into a constant getter below, so there is one shape inside `run`
+ * and no branch anywhere near the poll.
  */
 /**
  * ═══ THE CARD IS OVER, SO ITS COPY GOES — AND THE BRANCH STAYS. ═══
@@ -2806,6 +2976,31 @@ async function reportHarnessMismatch(client, machineId, machineHarness) {
         + `this daemon is restarted with CTRL_SPC_V3_AGENT=${designation.agent}, or ${machineHarness} `
         + 'is designated in the app.');
 }
+/**
+ * ═══ THE ONE PLACE THE TWO SHAPES OF CALLER BECOME ONE SHAPE. ═══
+ *
+ * `run` is entered two ways. The acceptance harness (`panel3/cli.js run`) signs
+ * in once and holds one client for the life of a `--once` poll, so a value is
+ * the honest thing for it to pass. `cs start` hands in v2 presence's client,
+ * which presence REPLACES when `session.json` comes to hold a different refresh
+ * token, so the honest thing for it to pass is a way to ask.
+ *
+ * ═══ IT IS A FUNCTION RATHER THAN A BRANCH AT EVERY USE SITE, AND THAT IS THE
+ *     WHOLE PRODUCT RULE. ═══ The defect being closed is a client read in one
+ * place and captured in another: the poll body could be made to re-read and the
+ * shutdown write, the signal handler and the dispatch callback would still hold
+ * a client the database refuses. Collapsing both callers into one getter at the
+ * top means there is no second shape left for a use site to capture, so
+ * "everything reads the live client" is true by construction rather than by
+ * every call site remembering.
+ *
+ * Exported because that rule is what a test should hold: a client swapped after
+ * `run` was entered is the one subsequently used, which is a claim about this
+ * function and nothing else.
+ */
+export function clientReader(injected) {
+    return typeof injected === 'function' ? injected : () => injected;
+}
 export async function run(args, injected) {
     let once = false;
     for (const arg of args) {
@@ -2827,7 +3022,13 @@ export async function run(args, injected) {
        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);
+    /* ═══ NORMALISED ONCE, HERE, SO EVERYTHING BELOW READS THE SAME WAY. ═══ A
+       plain client becomes a getter that always answers with it, and a getter is
+       used as it is. Every use site inside this loop then calls `current()`, and
+       which of the two the caller passed stops being visible past this line. That
+       is the property that matters, because the failure being closed is a value
+       captured in one place and not another. */
+    const current = clientReader(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
@@ -2862,8 +3063,8 @@ export async function run(args, injected) {
        `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, processToken) => {
-        const child = await startChild(client, tools, machineId, parentRunId, brief, codebase, processToken);
+    const tools = await startToolsServer(current(), async (parentRunId, brief, codebase, processToken) => {
+        const child = await startChild(current(), tools, machineId, parentRunId, brief, codebase, processToken);
         hold(child.runId, child.settled);
         return { runId: child.runId };
     });
@@ -2890,7 +3091,7 @@ export async function run(args, injected) {
     if (!once && !injected) {
         for (const signal of ['SIGINT', 'SIGTERM']) {
             process.once(signal, () => {
-                void stopListening(client, machineId, machineHarness).finally(() => {
+                void stopListening(current(), 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. */
@@ -2917,20 +3118,20 @@ export async function run(args, injected) {
                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);
+            await sayListening(current(), 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 reconcileOwnerSessions(client, machineId, machineHarness, new Set(inFlight.keys()));
-            await recoverStranded(client, tools, machineId, new Set(inFlight.keys()), hold);
+            await killStopped(current(), machineId);
+            await reconcileOwnerSessions(current(), machineId, machineHarness, new Set(inFlight.keys()));
+            await recoverStranded(current(), tools, machineId, new Set(inFlight.keys()), hold);
             /* ═══ AND THE COPIES OF CARDS THAT ARE OVER. ═══ After recovery,
                deliberately: a run this machine is about to resume is one whose card is
                not finished, and the sweep asks the record after recovery has had its
                say about what is really still running. */
-            await sweepFinishedWorktrees(client);
+            await sweepFinishedWorktrees(current());
             /* ═══ 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
@@ -2941,10 +3142,10 @@ export async function run(args, injected) {
                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);
+            await takeHandedBack(current(), tools, machineId, new Set(inFlight.keys()), hold);
             /* Every reason a conversational owner may continue is claimed together.
                The legacy turn and re-arm takes exclude named owners in the database. */
-            await takeOwnerActivations(client, tools, machineId, new Set(inFlight.keys()), hold);
+            await takeOwnerActivations(current(), tools, machineId, new Set(inFlight.keys()), hold);
             /* ═══ AND IF THE DESIGNATION NAMES A HARNESS THIS DAEMON IS NOT, IT SAYS
                SO BEFORE TAKING NOTHING. ═══
                `panel3_take_turns` and `panel3_take_rearms` compare `p_agent` against
@@ -2962,11 +3163,11 @@ export async function run(args, injected) {
                ux.md's forbidden state — "nothing will act on it and nothing on screen
                says so" — is reached the moment they do. This is the daemon's own
                screen saying so. */
-            await reportHarnessMismatch(client, machineId, machineHarness);
+            await reportHarnessMismatch(current(), machineId, machineHarness);
             /* 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');
+            const taken = await returned(current().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
@@ -2980,14 +3181,14 @@ export async function run(args, injected) {
                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');
+            const rearmed = await returned(current().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);
+                    hold(row.run_id, (await startRearmed(current(), tools, machineId, row)).settled);
                 }
                 catch (error) {
                     said(`could not start run ${row.run_id} again: ${error instanceof Error ? error.message : String(error)}`);
@@ -3006,7 +3207,7 @@ export async function run(args, injected) {
                 // 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));
+                hold(runId, answerCard(current(), tools, machineId, cardId, turns));
             }
             if (once) {
                 /* ═══ UNTIL NOTHING IS LEFT, NOT ONCE OVER WHAT WAS THERE. ═══ A level 1
@@ -3021,7 +3222,7 @@ export async function run(args, injected) {
                 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);
+                await stopListening(current(), machineId, machineHarness);
                 return;
             }
         }
@@ -3053,11 +3254,21 @@ export async function run(args, injected) {
  * 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.
+ * `startPresence()` owns 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.
+ *
+ * ═══ AND IT IS READ RATHER THAN HANDED OVER, BECAUSE PRESENCE REPLACES IT. ═══
+ * A `SupabaseClient` is still accepted, for the harness and for any caller
+ * holding exactly one. `cs start` passes a function instead, because presence's
+ * heartbeat rebuilds its client when the account on disk changes, and the panel
+ * holding the pre-rebuild one is the largest single share of the poll storm this
+ * widening closes. `stop` reads it through the same getter for the same reason:
+ * it is the last write this process makes, minutes or days after the getter was
+ * handed over, and a goodbye written with a refused token leaves the card saying
+ * an agent is working.
  *
  * ═══ 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
@@ -3065,7 +3276,8 @@ export async function run(args, injected) {
  * 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) {
+export function startPanel(injected) {
+    const current = clientReader(injected);
     /* 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
@@ -3073,11 +3285,16 @@ export function startPanel(client) {
        `CTRL_SPC_V3_AGENT` — so reading them twice cannot disagree. */
     const machineId = getMachineIdentity().id;
     const machineHarness = harness();
-    void run([], client).catch((error) => {
+    /* THE GETTER, NOT `current()`. Passing the read itself is what keeps ONE
+       normalisation in this process: `run` calls `clientReader` on whatever it is
+       given, a getter passes through unchanged, and the loop reads the same live
+       client `stop` does. Passing `current()` here would resolve it once and hand
+       the loop the very snapshot this parameter was widened to stop producing. */
+    void run([], current).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) };
+    return { stop: () => stopListening(current(), machineId, machineHarness) };
 }