@ctrl-spc/cs 0.6.0 → 0.7.1

package/dist/panel3/spawn.js

@@ -0,0 +1,565 @@
+/**
+ * ═══ AGENT PANEL v3: running one headless agent and reading what it said. ═══
+ *
+ * THIS FILE BELONGS TO AGENT PANEL v3. Nothing outside `src/panel3/` may
+ * import it.
+ *
+ * ---------------------------------------------------------------------------
+ * ═══ WHY v3 HAS ITS OWN SPAWN INSTEAD OF CALLING v1's. ═══
+ *
+ * `orchestrator.ts` already spawns headless agents, and reusing it was the first
+ * thing considered. It cannot be reused: `spawnAgent` takes a `WorkerMcpServer`,
+ * builds an inline MCP config for v1's tools server, seeds a per-run `CODEX_HOME`
+ * for the same server, resolves a checkout from a v1 todo row, and
+ * reports its outcome in v1's own vocabulary. Every one of those is v1's panel,
+ * and conventions.md names `orchestrator.ts` in the column v3 may not use — the
+ * rule that keeps v1 deletable.
+ *
+ * ═══ SO WHAT IS BORROWED IS THE PART THAT BELONGS TO NO GENERATION. ═══
+ * `agentPath`, `windowsSafeSpawn` and `scratchDir` are process primitives about
+ * running a child on this operating system, and re-deriving them here would
+ * re-derive their bugs: `win-shell.ts` alone holds three Windows rules that each
+ * shipped as a defect when a second call site missed one.
+ *
+ * ---------------------------------------------------------------------------
+ * ═══ NOTHING HERE STOPS AN AGENT. THERE IS NO CLOCK. ═══
+ *
+ * ux.md, in the mechanical column: "The user's Stop is absolute, and nothing
+ * else stops work. No clock, no silence timeout."
+ *
+ * This file held a ten-minute wall clock that killed the process and reported it
+ * as a failure. It was never a finding, never a ruling and never an exclusion in
+ * the plan, and it capped precisely the case the three-level design exists for:
+ * an epic that runs for hours. A worker eleven minutes into a build was killed
+ * mid-edit, the run was marked failed, and the person was told the work failed
+ * when nothing had gone wrong with it.
+ *
+ * ═══ AND REMOVING IT LOSES NOTHING, BECAUSE LIVENESS ALREADY HAS AN OWNER. ═══
+ * `recoverStranded` in `run.ts` asks the operating system whether each of this
+ * machine's runs still has a process, with a pid-null grace window and a
+ * pre-boot check, and ends or starts again the ones that do not. That is what a
+ * wedged process is caught by, and it is caught by being GONE rather than by
+ * being slow. A clock cannot tell the two apart, which is the whole reason
+ * ux.md rules it out.
+ *
+ * ---------------------------------------------------------------------------
+ * ═══ THE PROMPT GOES ON STDIN, ON EVERY PLATFORM. ═══
+ *
+ * `claude -p` with no prompt argument reads it from stdin. v1 only does that on
+ * Windows, where a command line cannot carry a newline at all; the reason it is
+ * unconditional here is the simpler one — the prompt is prose written by a user
+ * and it has no business on a command line on any platform. It keeps every
+ * quoting question, and the injection risk that comes with them, out of this
+ * file entirely.
+ *
+ * ---------------------------------------------------------------------------
+ * ═══ THE HARNESS'S OWN TOOLS ARE PART OF THE GRANT, AND THIS FILE DECIDES
+ *     WHICH LEVELS GET THEM. ═══
+ *
+ * `tools.ts` serves the product's tools and deliberately serves no code tool at
+ * any level, because reading and editing code is something the harness already
+ * does far better than a re-implementation would. That leaves one question the
+ * tools server cannot answer: WHO IS ALLOWED TO USE THE HARNESS'S OWN.
+ *
+ * ux.md answers it in the mechanical column — "level 1 is never granted a code
+ * tool, so it cannot become the thing that does the work" — and `--tools` is
+ * where that becomes true of a real process. It names which of the harness's
+ * BUILT-IN tools exist at all, and `--tools ''` is none of them: a level 1 child
+ * starts with an empty built-in list and the product's tools beside it, so its
+ * tool list obeys the same absence-not-refusal rule the tools server does.
+ *
+ * ═══ `--allowedTools` ALONE WAS TRIED FIRST, AND IT IS NOT THE GUARANTEE. ═══
+ * v1's own comment says naming `mcp__ctrl-spc__*` and nothing else "silently
+ * removed everything else — Bash, WebFetch, Read, Write, Edit", and measured
+ * against claude 2.1.227 that is not what happens: the `init` event still listed
+ * `Read`, `Write`, `Edit`, `Bash` and `Task`, and a level 1 child asked to read a
+ * file did not say it had no way to; it said it needed permission to. That is a
+ * REFUSAL, and a refusal is the thing ux.md rules out — an agent that can see the
+ * tool spends its turn asking for it, and the level rule survives only as long as
+ * nobody approves. The two flags do different jobs and both are needed:
+ * **`--tools` decides what exists, `--allowedTools` decides what runs without
+ * somebody at a keyboard.**
+ *
+ * `--setting-sources ''` is the third piece and without it the others are
+ * theatre: the developer's own settings would otherwise load, bringing their
+ * personal allow list and hooks with them, and level 1's posture would depend on
+ * whose laptop it was running on.
+ *
+ * `--strict-mcp-config` was already here before there was a tools server, and it
+ * matters more now: without it the child inherits whatever MCP servers this
+ * machine happens to have registered, which on a developer's machine is v1 and
+ * v2's own tools server. A v3 run reaching v2's tools by accident is the
+ * coupling conventions.md exists to prevent, arrived at through a config file
+ * rather than an import.
+ *
+ * ---------------------------------------------------------------------------
+ * ═══ THE WORKING COPY IS A MACHINE-LOCAL FACT, AND IT IS THE `cwd`. ═══
+ *
+ * A level 2 agent reads and changes code, so it needs a real checkout. Nothing
+ * in v3 resolves one, and constraint 6 rules out the obvious place to put the
+ * answer: no absolute filesystem path may reach the database, so it cannot live
+ * on the card, on the run, or in the brief the run row stores.
+ *
+ * SO IT IS NEVER WRITTEN DOWN ANYWHERE THE PRODUCT CAN SEE. It is named by one
+ * environment variable on the machine running the daemon, read at the moment of
+ * a dispatch, and handed to the child as its `cwd`. The child works in it; the
+ * record says only that a run happened. That is the whole mechanism, and it is
+ * the smallest thing that is honest: a path passed to a process is not a path
+ * stored in a row.
+ *
+ * WHAT IT DOES NOT COVER, and each is a later slice's to answer: one machine has
+ * one working copy, not one per project or per codebase; parallel agents share
+ * it rather than getting a copy each, so two of them editing the same file is a
+ * collision nothing here prevents; and nothing branches, stashes or cleans it.
+ *
+ * ---------------------------------------------------------------------------
+ * WHAT THIS STILL DELIBERATELY DOES NOT DO.
+ *
+ * No codex, and no stream parsing. `prompt.ts` owns what an agent is told;
+ * this file's job is that a process at a given level starts in the right place
+ * with exactly the authority that level has.
+ */
+import { spawn as spawnChild } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { agentPath } from '../agents.js';
+import { ensureCodexRunHome, ensurePanel3CodexOwnerHome, removeCodexRunHome, } from '../codex-home.js';
+import { windowsSafeSpawn } from '../win-shell.js';
+const AGENT_VAR = 'CTRL_SPC_V3_AGENT';
+/**
+ * The harness named on this machine, or the reason the name is not one.
+ *
+ * ═══ AN UNKNOWN NAME THROWS RATHER THAN FALLING BACK TO CLAUDE. ═══ Constraint
+ * 7: a failure stays a failure. Somebody who sets this to `claude-code` or
+ * `gpt` has said which harness they want, and quietly running the other one
+ * would produce a whole session of results attributed to a binary that never
+ * ran. `startAgent` turns this into "no agent was started", which is true.
+ */
+export function harness(env = process.env) {
+    const named = (env[AGENT_VAR] ?? '').trim().toLowerCase();
+    if (named === '' || named === 'claude')
+        return 'claude';
+    if (named === 'codex')
+        return 'codex';
+    throw new Error(`${AGENT_VAR} names "${named}", which is not a harness this build can spawn. `
+        + 'It is `claude` or `codex`, or unset for claude.');
+}
+/** The MCP server name the child sees, so its tools are `mcp__ctrl-spc__…`.
+ *  Paired with `--strict-mcp-config` it is the only server that exists in that
+ *  process, so there is nothing for the name to collide with. */
+const SERVER = 'ctrl-spc';
+/** ═══ THE HARNESS'S CODE TOOLS, FOR THE LEVELS THAT DO THE WORK. ═══
+ *
+ *  Read, search, edit, run. `Task` is deliberately NOT here: it spawns a
+ *  subagent inside the harness, which is a dispatch the record never sees and a
+ *  fourth level ux.md does not have. Depth stops at three, and it stops in the
+ *  tools rather than in a sentence asking an agent not to. Codex's own
+ *  subagent tool gets the same closing, in `codex-home.ts`'s per-run
+ *  `[agents] enabled = false` — a reader of either file finds the other. */
+const CODE_TOOLS = ['Read', 'Glob', 'Grep', 'Edit', 'Write', 'Bash'];
+/** Which of the harness's built-ins EXIST for this level. Empty at level 1: not
+ *  denied, not present. */
+const builtIns = (level) => (level === 1 ? '' : CODE_TOOLS.join(','));
+/** What runs without a human approving it: the product's tools, and the code
+ *  tools at the levels that have any. */
+const allowedTools = (level) => [`mcp__${SERVER}__*`, ...(level === 1 ? [] : CODE_TOOLS)].join(',');
+/**
+ * The child's whole argument list, for one level, pointed at one run's tools.
+ *
+ * SEPARATE FROM THE SPAWN so that what a level is granted can be printed and
+ * checked without starting a process — which is how the allowlist is proved,
+ * and how it stays provable after this task.
+ */
+export function agentArgs(level, toolsUrl, agent = harness(), platform = process.platform, ownerSession) {
+    if (agent === 'codex')
+        return codexArgs(level, toolsUrl, platform, ownerSession);
+    const session = ownerSession
+        ? ownerSession.resumeSessionId
+            ? ['--resume', ownerSession.resumeSessionId]
+            : ['--session-id', ownerSession.freshSessionId ?? randomUUID()]
+        : [];
+    return [
+        // `-p` with the prompt on stdin. See the header.
+        '-p',
+        '--mcp-config',
+        JSON.stringify({ mcpServers: { [SERVER]: { type: 'http', url: toolsUrl } } }),
+        '--strict-mcp-config',
+        '--setting-sources', '',
+        '--tools', builtIns(level),
+        '--allowedTools', allowedTools(level),
+        ...session,
+        /* STATED WHERE THERE IS SOMETHING TO STATE. `acceptEdits` grants file edits
+           to a headless process with nobody at a prompt to approve them, and it is
+           passed only to the levels that have a file tool to use it with: at level 1
+           it would describe an authority over a tool that is not there. */
+        ...(level === 1 ? [] : ['--permission-mode', 'acceptEdits']),
+    ];
+}
+/**
+ * ═══ THE SAME GRANT, SAID THE ONLY WAY CODEX OFFERS. ═══
+ *
+ * The claude argv above says four things: these tools exist, these run without
+ * anybody approving them, this one MCP server and no other, and none of the
+ * user's own settings. On macOS, three of those move into a per-run
+ * `$CODEX_HOME`. The current Windows Desktop runtime accepts the same isolation
+ * through `--ignore-user-config` and `-c`, while retaining its installed
+ * credential and sandbox state. Both paths are pinned below.
+ *
+ * ═══ THE ONE THING THAT CANNOT BE SAID, STATED RATHER THAN GLOSSED. ═══
+ * `--tools ''` gives a claude level 1 NO code tool at all — not denied, not
+ * present. Codex has no such switch: its shell is built in, `tools.shell` is not
+ * a configuration field (measured against codex-cli 0.147.0-alpha.6.5: "unknown
+ * configuration field `tools.shell`"), and there is no allow list. The closest
+ * honest thing is a READ-ONLY sandbox, which is what level 1 gets: it cannot
+ * change the machine it runs on, and it runs in the empty scratch directory the
+ * caller hands it. It can still read. That is a floor of the harness, it is
+ * recorded in status.md as one, and it changes nothing about the product's own
+ * tools — those come from the run row through the URL, identically for both.
+ *
+ * `--ephemeral` keeps the session transcript, which holds absolute local paths,
+ * off the disk entirely. `--ignore-rules` is the settings half of claude's
+ * `--setting-sources ''` for the execpolicy files that live outside the home.
+ * `--json` makes the answer an `agent_message` item read out of the stream
+ * rather than whatever prose happened to reach stdout (see `codexAnswer`).
+ */
+function codexArgs(level, toolsUrl, platform, ownerSession) {
+    const resume = ownerSession?.resumeSessionId;
+    return [
+        'exec',
+        ...(resume ? ['resume', resume, '-'] : []),
+        // The prompt arrives on stdin, exactly as it does for claude: `codex exec`
+        // reads it from there when no prompt argument is given.
+        '--json',
+        // The level 1 scratch directory is not a repository, and neither need a
+        // working copy be.
+        '--skip-git-repo-check',
+        ...(ownerSession ? [] : ['--ephemeral']),
+        '--ignore-rules',
+        /* The current Windows Desktop runtime can define the run's one MCP server
+           on argv. Keeping the machine's real CODEX_HOME lets its installed sandbox
+           helpers and credential work, while this flag keeps every user setting,
+           connector and MCP server out of the run. Other platforms retain the
+           proven per-run home below. */
+        ...(platform === 'win32' ? [
+            '--ignore-user-config',
+            '-c', 'model="gpt-5.5"',
+            '-c', 'features.apps=false',
+            '-c', 'features.multi_agent=false',
+            '-c', `mcp_servers.${SERVER}.url=${JSON.stringify(toolsUrl)}`,
+            '-c', `mcp_servers.${SERVER}.default_tools_approval_mode="approve"`,
+            '-c', 'windows.sandbox="unelevated"',
+            '-c', 'windows.sandbox_private_desktop=false',
+        ] : []),
+        /* THE POSTURE, STATED. `workspace-write` is codex's `acceptEdits`: file
+           edits without a human at a prompt, and deliberately not
+           `danger-full-access`. Level 1 has no file tool to use it with, so it gets
+           the read-only sandbox instead — see the block comment above for what that
+           does and does not buy. */
+        ...(resume
+            ? ['-c', `sandbox_mode=${JSON.stringify(level === 1 ? 'read-only' : 'workspace-write')}`]
+            : ['-s', level === 1 ? 'read-only' : 'workspace-write']),
+        /* The write sandbox sandboxes the NETWORK too, and an agent handed a
+           credential that can then reach nothing is a dead end. Only where there is
+           a write sandbox to say it about. */
+        ...(level === 1 ? [] : ['-c', 'sandbox_workspace_write.network_access=true']),
+    ];
+}
+/** ═══ ONE RUN, ONE DIRECTORY. ═══ `codex-home.ts` keys a home by the request
+ *  it is working, because two runs sharing one directory is a race that ends
+ *  with a live run's credential deleted from under it. v3's tools URL ends in
+ *  the run id, which is exactly that key, and `codexRunHomePath` sanitises
+ *  whatever it is handed before it becomes a directory name. */
+function runKey(toolsUrl) {
+    const last = toolsUrl.split('/').pop();
+    return last && last !== '' ? last : null;
+}
+/**
+ * ═══ WHAT A CODEX RUN SAID, OUT OF THE STREAM RATHER THAN OFF STDOUT. ═══
+ *
+ * A claude answer under `-p` IS stdout. Codex's stdout under `--json` is its
+ * protocol: thread ids, tool calls with their arguments, reasoning items. Handed
+ * to a person as an answer it would be gibberish, and written to `panel3_turns`
+ * it would be gibberish carrying absolute local paths, so the answer is the text
+ * of the last completed `agent_message` and nothing else.
+ *
+ * ═══ A FAILED TURN BEATS A MESSAGE, EVEN THOUGH THE PROCESS EXITED 0. ═══ Codex
+ * can emit an `agent_message` and then a `turn.failed` and still exit cleanly.
+ * The exit code sees success, the message looks like an answer, and the card
+ * would read as answered by a turn the harness itself says did not finish. That
+ * is the forbidden state ux.md is about, so the failure wins wherever both are
+ * present.
+ */
+export function codexAnswer(stdout) {
+    let text = null;
+    let failure = null;
+    for (const line of stdout.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed[0] !== '{')
+            continue;
+        let event;
+        try {
+            event = JSON.parse(trimmed);
+        }
+        catch {
+            // Not protocol. Codex prints nothing else on stdout under `--json`, and a
+            // line that is not JSON is not an answer either way.
+            continue;
+        }
+        if (event.type === 'item.completed' && event.item?.type === 'agent_message') {
+            if (typeof event.item.text === 'string')
+                text = event.item.text;
+        }
+        else if (event.type === 'turn.failed') {
+            const named = event.error?.message ?? event.message;
+            failure = typeof named === 'string' ? named : '';
+        }
+    }
+    if (failure !== null) {
+        return { ok: false, reason: `codex could not finish the turn${failure ? `: ${failure}` : ''}` };
+    }
+    if (text === null || text.trim() === '') {
+        return { ok: false, reason: 'codex exited 0 without saying anything to the person' };
+    }
+    return { ok: true, text: text.trim() };
+}
+/** Enough for any answer a person reads, and a ceiling so a runaway process
+ *  cannot exhaust this daemon's memory. */
+const MAX_OUTPUT_CHARS = 1_000_000;
+/**
+ * ═══ WHY A PROCESS DID NOT START, WITHOUT SAYING WHERE THE BINARY IS. ═══
+ *
+ * Constraint 6: no absolute filesystem path reaches the database. Both ways a
+ * spawn can fail hand back a message that carries one — node's own spawn error
+ * reads `spawn /Users/…/claude ENOENT`, and an EACCES from the synchronous throw
+ * names the file too — and both of these become a run's `failed_because`, which
+ * `cs3 show` prints and a coordinator can repeat to the person.
+ *
+ * `workingCopy()` above already makes this argument for the checkout and the
+ * fix is the same one: the CODE is what a person acts on, it is not a path, and
+ * the machine's own sentence is left for whoever is reading stderr on that
+ * machine. Nothing is softened — it is still a failure, still says no agent
+ * started, and still says what the operating system called it.
+ */
+const couldNotStart = (err, agent) => {
+    const code = err.code;
+    return `could not start ${agent} on this machine`
+        + (typeof code === 'string' ? `: ${code}` : '');
+};
+/** The last of a stream, for an error message that has to stay readable. */
+function tail(text, chars = 500) {
+    const trimmed = text.trim();
+    if (trimmed === '')
+        return '';
+    return trimmed.length <= chars ? `: ${trimmed}` : `: ...${trimmed.slice(-chars)}`;
+}
+/**
+ * Start one agent on this machine, at one level, connected to one run's tools,
+ * in one directory.
+ *
+ * ═══ THE DIRECTORY IS THE CALLER'S TO CHOOSE, AND IT IS RESOLVED BEFORE THE
+ * RUN ROW EXISTS. ═══ Level 1 is given an empty scratch directory because it has
+ * no code tool to use one with; a dispatched agent is given the working copy.
+ * The caller resolves it first so that a machine with no working copy fails
+ * BEFORE anything is written, rather than leaving a run row for a process that
+ * was never started.
+ *
+ * ═══ THE LEVEL IS PASSED TO THE HARNESS AND NEVER TO THE AGENT. ═══ It decides
+ * argv and nothing else. What the agent may call it learns by being handed a
+ * tool list, and the tools server derives that list from the run id in
+ * `toolsUrl` rather than from anything said here — so the two halves of the
+ * grant cannot drift, because only one of them is ever told a number.
+ *
+ * ═══ IT STARTS SYNCHRONOUSLY AND HANDS BACK THE PID SEPARATELY. ═══ A single
+ * `Promise<Answer>` would hide the pid until the process had already finished,
+ * and by then recording it is pointless: the pid exists to answer "is this run's
+ * process still alive" after the daemon that started it has been killed. So the
+ * caller gets the pid immediately, writes it, and then waits.
+ */
+export function startAgent(prompt, level, toolsUrl, cwd, ownerSession) {
+    const failed = (reason) => ({
+        pid: null,
+        session: Promise.resolve(null),
+        answered: Promise.resolve({ ok: false, reason }),
+    });
+    let agent;
+    try {
+        agent = harness();
+    }
+    catch (err) {
+        // A machine configured for a harness this build has never heard of. See
+        // `harness()`: running the other one instead is the lie, not the failure.
+        return failed(err.message);
+    }
+    const launchedOwnerSession = ownerSession && !ownerSession.resumeSessionId
+        ? { ...ownerSession, freshSessionId: randomUUID() }
+        : ownerSession;
+    const ARGS = agentArgs(level, toolsUrl, agent, process.platform, launchedOwnerSession);
+    const bin = agentPath(agent);
+    if (!bin) {
+        return failed(`${agent} is not installed on this machine`);
+    }
+    /* macOS uses the proven per-run home. Windows keeps its installed home so the
+       Desktop runtime's ACL-bound sandbox helpers remain valid; `codexArgs`
+       isolates its configuration and grants this run's one server on argv. */
+    const windowsCodex = agent === 'codex' && process.platform === 'win32';
+    const home = agent === 'codex' && !windowsCodex
+        ? ownerSession
+            ? ensurePanel3CodexOwnerHome({ url: toolsUrl }, ownerSession.ownerId)
+            // `false`: v3 closes codex's own subagent tool, the same depth-stops-at-
+            // three rule `CODE_TOOLS` enforces for claude below. v2's callers never
+            // pass this and keep today's behaviour; see `codex-home.ts`.
+            : ensureCodexRunHome({ url: toolsUrl }, null, runKey(toolsUrl), false)
+        : null;
+    if (agent === 'codex' && !windowsCodex && !home) {
+        return failed('codex is not signed in on this machine, so a run cannot be given this product\'s tools '
+            + 'and nothing else. Sign codex in on the machine running this, and start it again.');
+    }
+    const { args, shell } = windowsSafeSpawn(bin, ARGS);
+    let child;
+    try {
+        child = spawnChild(bin, args, {
+            // The repo-wide invariant for ANY child process (MEMORY: "Windows silence
+            // decision"). A user must never see a console flash.
+            windowsHide: true,
+            shell,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            // NEVER the daemon's inherited cwd, which under a launchd login item is
+            // the filesystem root. The caller says where, and both answers are
+            // deliberate: an empty scratch directory, or the working copy.
+            cwd,
+            /* THE PARENT'S ENVIRONMENT, PLUS THE HOME. Codex needs PATH and HOME to
+               run at all, and `$CODEX_HOME` is the only place its MCP server can be
+               said. Claude is spawned with the environment untouched, exactly as
+               before. */
+            ...(home ? { env: { ...process.env, CODEX_HOME: home } } : {}),
+        });
+    }
+    catch (err) {
+        // NOT `err.message`, which names the binary's absolute path. See
+        // `couldNotStart`.
+        if (home && !ownerSession)
+            removeCodexRunHome(home);
+        return failed(couldNotStart(err, agent));
+    }
+    let resolveSession;
+    let sessionSettled = false;
+    const session = new Promise((resolve) => { resolveSession = resolve; });
+    const observeSession = (value) => {
+        if (sessionSettled)
+            return;
+        sessionSettled = true;
+        resolveSession(value);
+    };
+    if (!ownerSession)
+        observeSession(null);
+    else if (agent === 'claude') {
+        observeSession(launchedOwnerSession?.resumeSessionId ?? launchedOwnerSession?.freshSessionId ?? null);
+    }
+    const answered = new Promise((resolve) => {
+        let stdout = '';
+        let stderr = '';
+        let truncated = false;
+        let settled = false;
+        const collect = (into, chunk) => {
+            if (into.length >= MAX_OUTPUT_CHARS) {
+                truncated = true;
+                return into;
+            }
+            return into + chunk;
+        };
+        /* ═══ ONE ANSWER, WHICHEVER OF THE TWO EVENTS ARRIVES. ═══ `error` and
+           `close` can both fire for one child, and the second must not overwrite
+           what the first said. There is no timer to clear: see the header — nothing
+           in this file stops an agent, and the process runs until it exits or the
+           user stops it. */
+        const finish = (answer) => {
+            if (settled)
+                return;
+            settled = true;
+            /* THE CREDENTIAL COPY GOES WHEN THE RUN DOES. `codex-home.ts` calls this
+               the primary reclaim and the startup sweep the backstop; a home left
+               behind holds a copy of the user's codex credential. */
+            if (home && !ownerSession)
+                removeCodexRunHome(home);
+            if (!sessionSettled)
+                observeSession(null);
+            resolve(answer);
+        };
+        child.stdout?.on('data', (d) => {
+            stdout = collect(stdout, String(d));
+            if (ownerSession && agent === 'codex' && !sessionSettled) {
+                for (const line of stdout.split('\n')) {
+                    try {
+                        const event = JSON.parse(line);
+                        if (event.type === 'thread.started' && typeof event.thread_id === 'string') {
+                            const id = event.thread_id;
+                            if (/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(id)) {
+                                observeSession(id);
+                                break;
+                            }
+                        }
+                    }
+                    catch {
+                        // The final answer parser owns protocol validity. This observer only finds one event.
+                    }
+                }
+            }
+        });
+        child.stderr?.on('data', (d) => { stderr = collect(stderr, String(d)); });
+        /* ENOENT and friends. The process never ran, and that is what is reported —
+           WITHOUT the message, which is where node puts the binary's absolute path.
+           The same failure as the throw above, arriving asynchronously. */
+        child.on('error', (err) => {
+            finish({ ok: false, reason: couldNotStart(err, agent) });
+        });
+        child.on('close', (code, signal) => {
+            /* ═══ THREE OUTCOMES, AND ONLY ONE OF THEM IS AN ANSWER. ═══ A non-zero
+               exit and an exit of zero that said nothing are both failures, and
+               neither may be returned as an empty answer: the daemon would write a
+               blank agent turn and the card would read as answered. That is the
+               forbidden state ux.md is about, reached by treating silence as
+               success. */
+            if (signal !== null) {
+                /* ═══ A SIGNALLED PROCESS HAS NO EXIT CODE, AND SAYING IT "EXITED NULL"
+                   IS NOT TRUE. ═══ `code` is null exactly when a signal ended the
+                   process, and this daemon is the only thing that signals one: the
+                   person's Stop (`killStopped`) and the person's correction
+                   (`redirectedProcess`). Both reach here, both are printed, and the
+                   second one can reach `failed_because` and a person's card if the
+                   respawn behind it is refused. Naming the signal is the whole fix. */
+                finish({ ok: false, reason: `${agent} was ended by ${signal}${tail(stderr) || tail(stdout)}` });
+            }
+            else if (code !== 0) {
+                /* STDOUT WHEN STDERR IS EMPTY, because `claude -p` prints its own
+                   failure on stdout and exits non-zero having written nothing to
+                   stderr. Reporting only "exited 1" would throw away the one sentence
+                   that says what went wrong. */
+                finish({ ok: false, reason: `${agent} exited ${code}${tail(stderr) || tail(stdout)}` });
+            }
+            else if (stdout.trim() === '') {
+                finish({ ok: false, reason: `${agent} exited 0 and said nothing${tail(stderr)}` });
+            }
+            else if (agent === 'codex') {
+                /* The stream, not the buffer. See `codexAnswer`: stdout here is
+                   protocol, and a failed turn that exited 0 is still a failure. */
+                finish(codexAnswer(stdout));
+            }
+            else {
+                const text = stdout.trim();
+                finish({
+                    ok: true,
+                    text: truncated ? `${text}\n\n[cut off at ${MAX_OUTPUT_CHARS} characters]` : text,
+                });
+            }
+        });
+        /* THE PROMPT, AND THEN END OF INPUT, because `claude -p` reads stdin to the
+           end before it starts, and `codex exec` reads it from there whenever no
+           prompt argument is given. The error handler is not swallowing a failure: a
+           child that exits before reading gives EPIPE here, and the outcome of that
+           child is reported by `close` above with its real exit code. Without the
+           handler the EPIPE is an unhandled stream error and takes the daemon down
+           with it. */
+        child.stdin?.on('error', () => { });
+        child.stdin?.end(prompt);
+    });
+    return { pid: child.pid ?? null, session, answered };
+}