@ctrl-spc/cs 0.6.0 → 0.7.1

package/dist/codex-home.js

@@ -0,0 +1,562 @@
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync, } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { configDir } from './config.js';
+/**
+ * 18c SLICE 8 — A CODEX WORKER IS ISOLATED LIKE A CLAUDE WORKER.
+ *
+ * THE GAP THIS CLOSES, measured on this Mac rather than reasoned about. A codex
+ * worker was spawned with `['exec', '--skip-git-repo-check']` and nothing else,
+ * so it inherited the developer's ENTIRE agent configuration. Asked to list the
+ * tools it could call, a plain `codex exec` on this machine answered with
+ * `mcp__supabase_main__execute_sql`, `mcp__postman__*`, `mcp__filesystem__*`,
+ * `mcp__memory__*`, `mcp__netlify__*`, `mcp__node_repl__*`, `mcp__moflo__*` and
+ * `mcp__super_harness__*` — eight servers this product never granted, one of
+ * them holding a live service-role token for the very database the product
+ * writes to. Asked whether it had been given an instruction file from outside
+ * the working directory, it quoted `~/.codex/AGENTS.md` back verbatim.
+ *
+ * That is the same hole `--strict-mcp-config` and `--setting-sources ''` close
+ * for claude, and "nothing was created" cannot be said honestly about a run
+ * configured by something the product never granted.
+ *
+ * ═══ WHY A SEEDED HOME, AND NOT ANY OF THE FOUR THINGS TRIED BEFORE ═══
+ *
+ * Codex offered no argv for an inline MCP config in the Mac runtime this module
+ * serves (codex-cli 0.147.0-alpha.6.5), and four mechanisms were measured as
+ * failing there. None of them is retried here:
+ *
+ *   * `-c mcp_servers."ctrl-spc".url=...` — `-c` cannot CREATE or override an
+ *     MCP server in this build. Re-measured for this slice with
+ *     `--ignore-user-config -c 'mcp_servers.ctrl-spc={url=...}'`: the run
+ *     completed and answered the tool-list question with `[]`. The override is
+ *     accepted on the command line and produces no server.
+ *   * `--ignore-user-config` — drops this product's own `[mcp_servers.ctrl-spc]`
+ *     along with the user's, leaving zero ctrl-spc tools.
+ *   * a per-run `CODEX_HOME` holding ONLY a one-server config.toml — hangs,
+ *     because codex will not start against a home with none of its own state.
+ *   * a `-c` override plus a `--mcp-config` file (Slice 5's Windows walk) — hung
+ *     twice, and testing wiring no user has is not a test.
+ *
+ * The newer Windows Desktop runtime now supports creating the server through
+ * `-c`. Panel v3 uses that platform-specific route in `panel3/spawn.ts`, keeping
+ * the installed home because Windows sandbox setup is bound to its ACL state.
+ *
+ * THE THIRD ONE WAS ALMOST RIGHT, AND ITS DIAGNOSIS NAMED THE FIX. "Codex will
+ * not start against a home with none of its own state" is a statement about what
+ * the home is MISSING, not about per-run homes being impossible. The one piece
+ * of state codex cannot manufacture is the credential: `codex exec --help` says
+ * of `--ignore-user-config` that "auth still uses `CODEX_HOME`", which is the
+ * binary telling us where it insists on reading auth from. Everything else in
+ * that directory — the model cache, the session store, the sqlite state files,
+ * its own `.system` skills — codex creates for itself on first run.
+ *
+ * So the home is SEEDED with exactly one file copied from the user's own
+ * (`auth.json`) and one file this product writes (`config.toml`). Measured on
+ * this Mac: the run completes, it does not hang, and the tool list comes back as
+ * this product's tools and NOTHING else. The `~/.codex/AGENTS.md` that a plain
+ * run quoted verbatim is not seen, and none of the user's personal skills under
+ * `~/.codex/skills` is present — only the `.system` skills codex installs into
+ * any home for itself.
+ *
+ * ═══ THE ONE THING THIS DOES NOT COVER, STATED RATHER THAN GLOSSED ═══
+ *
+ * `~/.agents/skills` is a SECOND skill root, resolved from the user's HOME
+ * rather than from `$CODEX_HOME`, and nothing reaches it: not the per-run home,
+ * not `--ignore-user-config`, and not `[features] skill_search = false` (all
+ * three measured). An isolated run is therefore still handed a CATALOG naming
+ * the skills there — on this Mac, `ctrl-spc` (this product's own) and
+ * `impeccable`.
+ *
+ * WHY THAT IS RECORDED AND NOT PAPERED OVER. It is a list of names and paths
+ * rather than injected content: the run is not given those files' contents, is
+ * not instructed by them, and reads one only if it chooses to. The isolation
+ * that Story 6 asks for — the tool surface, the instruction file, the permission
+ * posture — holds, and the acceptance run confirmed all three. But "the tool
+ * surface is exactly this product's" and "nothing of the user's is visible" are
+ * different claims, and only the first is true. The honest fix is a `HOME`
+ * override, which is not taken because `HOME` is where codex also finds its
+ * credential, its cache and the user's shell environment, and breaking those to
+ * hide two skill names would trade a real capability for a cosmetic one.
+ *
+ * ═══ THE SECOND THING THE HOME BUYS, WHICH IS WORTH AS MUCH ═══
+ *
+ * A per-run home means a per-run `config.toml`, and a per-run `config.toml`
+ * means the server URL is OURS TO WRITE. That is the per-run channel codex was
+ * said not to have: `todo_id` goes on the URL exactly as `workerMcpConfig` puts
+ * it there for claude, so a codex tool call names its own request instead of the
+ * machine's oldest live worker. Measured with two codex runs started at the same
+ * second against one server: the ALPHA run's tool call arrived carrying
+ * `todo_id=RUN-ALPHA` and the BETA run's carried `todo_id=RUN-BETA`. That is the
+ * precise limitation `machineRunTodoId` documents as unfixable and hands to this
+ * slice.
+ *
+ * ═══ WHY NOT ONE SHARED ISOLATED HOME ═══
+ *
+ * Because the URL in it is per-run. Two concurrent runs sharing one home would
+ * race on the same `config.toml` and one would read the other's request id,
+ * which is the bug this is fixing wearing a different hat.
+ *
+ * ═══ WHAT A LEFTOVER HOME ACTUALLY COSTS, MEASURED ═══
+ *
+ * An earlier version of this comment called a leftover home "inert (two small
+ * files plus codex's own cache)". **That was measurably wrong**, and gate A
+ * caught it. After ONE real run the directory is 32 MB and contains, besides the
+ * credential copy, `sessions/**\/rollout-*.jsonl` — codex's full session
+ * transcript, which holds the entire conversation and absolute local paths.
+ *
+ * Two things follow, and both are done rather than noted. `--ephemeral` is on
+ * the argv (`codex exec --help`: "Run without persisting session files to
+ * disk"), measured to leave zero rollout files while the answer is still
+ * captured, so the transcript is never written in the first place. And the sweep
+ * cannot be the only thing standing between a crash and a stranded credential,
+ * so `sweepStrandedCodexHomes` runs at daemon startup beside the rest of the
+ * crash recovery.
+ */
+/** The file naming the process that built a home and is responsible for it.
+ *  Read by the startup sweep to decide whether the home still has an owner. */
+const OWNER_FILE = 'ctrl-spc-owner.json';
+/** The parent of every per-run home. Homes under it are swept individually, and
+ *  only when their owning process is gone — see `sweepStrandedCodexHomes`. */
+export function codexHomesRoot() {
+    return join(configDir(), 'codex-homes');
+}
+/** Persistent isolated homes belong only to panel3 conversation owners. They
+ * are separate from `codexHomesRoot()` so the per-process PID sweep can keep
+ * its existing contract without deleting a resumable owner conversation. */
+export function panel3CodexOwnerHomesRoot() {
+    return join(configDir(), 'panel3-codex-owner-homes');
+}
+export function panel3CodexOwnerHomePath(ownerRunId) {
+    const key = ownerRunId.replace(/[^a-zA-Z0-9-]/g, '_');
+    return join(panel3CodexOwnerHomesRoot(), key);
+}
+/** Where this run's throwaway codex home lives. Inside the product's own config
+ *  dir, beside `scratch/`, so it is the user's own directory and it is obvious
+ *  what wrote it. Keyed by request so two concurrent runs never share one. */
+export function codexRunHomePath(runTodoId) {
+    /* THE KEY IS SANITISED, NOT TRUSTED. A request id is a uuid today and nothing
+       in the type says so, and this string becomes a DIRECTORY NAME that a
+       credential is copied into. Anything outside the safe set becomes `_`, and
+       the dot is then handled separately: allowing `.` keeps a uuid readable but
+       would let `..` through as a whole path segment, which `join` would resolve
+       into a parent. A leading dot cannot survive, so `..` cannot either.
+  
+       A RUN WITH NO REQUEST STILL GETS ITS OWN HOME, and this used to be a lie.
+       The key was the constant `'no-request'`, so every concurrent run without a
+       request shared ONE directory — precisely the race the paragraph above cites
+       as the reason for keying by request at all, reintroduced by the fallback
+       (gate A). There is nothing stable to key on in that case, so a random
+       suffix is the honest answer: uniqueness is what the key is for, and
+       readability is worth nothing for a directory that has no request to be read
+       against. */
+    const key = runTodoId
+        ? runTodoId.replace(/[^a-zA-Z0-9._-]/g, '_').replace(/^\.+/, '_')
+        : `no-request-${randomUUID()}`;
+    return join(codexHomesRoot(), key);
+}
+/** The user's own codex home, resolved exactly as codex resolves it. */
+export function userCodexHome() {
+    return process.env.CODEX_HOME || join(homedir(), '.codex');
+}
+/** The URL a run's `config.toml` points at, however the caller said it. */
+function mcpUrl(server, runTodoId) {
+    return 'url' in server ? server.url : codexWorkerMcpUrl(server, runTodoId);
+}
+/**
+ * The `config.toml` this product hands a codex worker. ONE server, named exactly
+ * as the tools and the guidance name it, and nothing else.
+ *
+ * `default_tools_approval_mode = "approve"` is not optional and is not a
+ * loosening. Without it headless `codex exec` CANCELS every MCP tool call
+ * client-side, with a zero-second duration and nothing in any server log
+ * (.bugs/20260808-codex-mcp-tools-cancelled). `ensureCodexMcpApproval` in mcp.ts
+ * exists to keep putting this key back into the USER's config after every
+ * `codex mcp add` destroys it; here the file is ours and never rewritten, so the
+ * key simply stays.
+ *
+ * `features.apps = false` is the last of the inherited surface, and it is not
+ * config-file state — it comes from the signed-in ChatGPT account. Measured: a
+ * seeded home WITHOUT this line still listed `mcp__codex_apps__github_*`,
+ * `mcp__codex_apps__codex_document_control_*` and the rest, so a worker could
+ * open pull requests on the user's GitHub through an account connector the
+ * product never granted. WITH it, the tool list is this product's tools and
+ * nothing else. It is disabled rather than allow-listed because codex offers no
+ * per-server allow list; `false` is the only knob, and an allow list is what
+ * `--strict-mcp-config` + `--allowedTools` amount to for claude.
+ */
+export function codexRunConfigToml(server, runTodoId, runtimePlatform = process.platform, 
+/* ═══ CODEX'S OWN SUBAGENT TOOL, WHICH v3 CLOSES AND v2 DOES NOT. ═══
+ *
+ * v3 enforces "depth stops at three" in the TOOL SURFACE, never in a prompt.
+ * Claude's half of that is `CODE_TOOLS` excluding `Task` in
+ * `panel3/spawn.ts`. Codex's own subagent tool was left open, and a level 2
+ * codex worker reached for it instead of this product's `dispatch` tool;
+ * no level 3 run was ever started through the record.
+ *
+ * Codex 0.148 made `multi_agent` the stable feature switch and changed
+ * `[agents]` into a role table. The old `[agents] enabled = false` now makes
+ * the current Desktop runtime reject the whole config before a run starts.
+ * `features.multi_agent = false` is therefore the surface-level absence rule
+ * on the current runtime, matching the documented configuration contract.
+ *
+ * v2's claude workers are deliberately still granted `Task` (see
+ * `orchestrator.ts`), so this is an EXPLICIT argument rather than a change to
+ * what v2 gets: the default keeps today's behaviour (subagents allowed), and
+ * only v3's `startAgent` passes it off. Never inferred from `server`'s shape:
+ * v2 and v3 both pass `{ url }` here, so the shape cannot tell them apart.
+ */
+subagentsEnabled = true, persistentPanelOwner = false) {
+    const lines = [
+        '# Written by CTRL+SPC for ONE codex run. Not the user\'s config; never read',
+        '# by anything but the worker this was written for.',
+        /* The Windows Desktop bundle can lag the account's server-selected default
+           model. When that default requires a newer client, every headless worker
+           exits before its first action. Pin the current broadly-supported model
+           only for that bundled runtime; other platforms keep Codex's own model
+           selection. */
+        ...(runtimePlatform === 'win32' ? ['model = "gpt-5.5"', ''] : []),
+        ...(persistentPanelOwner ? [
+            'sandbox_mode = "workspace-write"',
+            '',
+            '[sandbox_workspace_write]',
+            'network_access = true',
+            '',
+        ] : []),
+        '[features]',
+        /* The account's own connectors, which no config.toml grants and no argv
+           removes. See the block comment above. */
+        'apps = false',
+        ...(!subagentsEnabled ? ['multi_agent = false'] : []),
+        '',
+    ];
+    /* Native Windows must name its sandbox implementation. Without this block,
+       codex silently resolves a requested workspace-write run as read-only and
+       refuses every network command. `unelevated` is the documented fallback for
+       a headless process: `elevated` opens a UAC consent dialog that a daemon has
+       nobody present to approve. This block is Windows-only. macOS keeps its
+       existing Seatbelt configuration exactly. */
+    if (runtimePlatform === 'win32') {
+        lines.push('[windows]', 'sandbox = "unelevated"', 
+        /* 0.148 defaults both Windows sandboxes onto a private desktop. A
+           daemon-spawned headless worker has no desktop handshake to complete,
+           so its command runner waits on the pipe until the turn fails. The
+           documented compatibility mode keeps the same sandbox boundaries and
+           runs the command on Winsta0\\Default instead. */
+        'sandbox_private_desktop = false', '');
+    }
+    /* No server means the tools server is not running, and the worker then runs
+       with NO ctrl-spc tools rather than with whatever the user's config happens
+       to hold — the same honest-absence rule `headlessAgentArgs` already applies
+       to claude's `--mcp-config`. Writing no `[mcp_servers]` block at all is what
+       makes that true: the home has no other source of servers. */
+    if (server) {
+        const url = mcpUrl(server, runTodoId);
+        lines.push('[mcp_servers.ctrl-spc]', `url = ${JSON.stringify(url)}`, 
+        /* See the block comment above: without this every tool call is cancelled
+           client-side before it leaves the worker. */
+        'default_tools_approval_mode = "approve"', '');
+    }
+    return lines.join('\n');
+}
+/**
+ * The URL a codex worker reaches this server on. Deliberately the SAME shape
+ * `workerMcpUrl` builds for claude — token, then `todo_id` when there is a
+ * request — because the server reads the query string the same way for both and
+ * two spellings of one URL is how they drift apart.
+ *
+ * Kept here rather than imported from orchestrator.ts to avoid a cycle; the pair
+ * is pinned identical by a test rather than by hope.
+ */
+export function codexWorkerMcpUrl(server, runTodoId) {
+    const query = runTodoId
+        ? `token=${server.token}&todo_id=${encodeURIComponent(runTodoId)}`
+        : `token=${server.token}`;
+    return `http://127.0.0.1:${server.port}/mcp?${query}`;
+}
+/**
+ * Build this run's isolated codex home and return its path, or null when it
+ * cannot be built.
+ *
+ * NULL IS A REAL ANSWER AND THE CALLER MUST HONOUR IT. The one thing that can
+ * fail is the credential copy: no `auth.json` in the user's home means the user
+ * has never signed codex in, and a home without it is the case that HANGS. So a
+ * missing credential returns null and the caller runs codex the old way — an
+ * un-isolated run that works beats a hung one that looks safe, and a run that
+ * hangs is indistinguishable from a slow one for thirty minutes.
+ *
+ * IT IS BUILT FROM EMPTY EVERY RUN, not merely overwritten. The URL carries the
+ * request id and the token can rotate, so a stale `config.toml` would point a
+ * worker at the wrong request or a dead port. Overwriting the two files was not
+ * enough: a RETRY of the same request resolves the same key, so the previous
+ * attempt's session state, sqlite files and caches were inherited by the run
+ * meant to be a fresh start (gate A). The directory is removed first, so "this
+ * run's home" means what it says. The expensive parts are codex's own and it
+ * recreates them; the two files this writes are under a kilobyte.
+ */
+export function ensureCodexRunHome(server, runTodoId, 
+/* ═══ 18d SLICE 4 — THE DIRECTORY KEY, WHEN IT MUST DIFFER FROM THE REQUEST.
+   ═══
+
+   The home was keyed by request id alone, which is right while one request
+   means one run. A HANDOFF breaks that: the continuation carries the SAME
+   request id, so it resolved to the same directory as the run it is replacing
+   — and this function starts by `rmSync`-ing the directory. Two ways to lose:
+   the continuation deletes the outgoing run's home from under it, or the
+   outgoing run's `removeCodexRunHome` deletes the continuation's.
+
+   The caller passes a per-DISPATCH key, so two runs of one request never share
+   a directory. `runTodoId` still goes into the config's MCP url unchanged,
+   because that is the request the worker is genuinely working. */
+homeKey = runTodoId, 
+/* ═══ THE SUBAGENT SWITCH, DEFAULTED TO v2's BEHAVIOUR. ═══ Passed straight
+   through to `codexRunConfigToml` (see its comment for the measurement
+   table). Defaults `true` so v2's callers, which never pass this, are
+   byte-identical to before; only v3's `startAgent` passes `false`. */
+subagentsEnabled = true, runtimePlatform = process.platform) {
+    const source = join(userCodexHome(), 'auth.json');
+    /* No credential, no isolated home. See the block comment above: this is the
+       exact shape that hangs, and hanging is worse than inheriting. */
+    if (!existsSync(source))
+        return null;
+    const home = codexRunHomePath(homeKey);
+    try {
+        /* FROM EMPTY. See above: a retry of the same request would otherwise start
+           inside the failed attempt's leftovers. */
+        rmSync(home, { recursive: true, force: true });
+        /* 0o700 UNCONDITIONALLY. The files inside are written 0600, but `auth.json`
+           arrives through `copyFileSync`, which PRESERVES THE SOURCE MODE — so the
+           credential copy is only as private as the original happened to be. The
+           directory being owner-only is what makes that irrelevant, and it is set
+           explicitly rather than left to the umask (gate A: the homes were 0755).
+           `mode` is ignored by `mkdirSync` when the directory already exists, which
+           is why the `chmodSync` below is not redundant. */
+        mkdirSync(home, { recursive: true, mode: 0o700 });
+        chmodSync(home, 0o700);
+        /* COPIED, NOT SYMLINKED. Codex rewrites `auth.json` when it refreshes a
+           token, and a symlink would make a throwaway home's refresh land in the
+           user's real one — a per-run directory that writes back into `~/.codex` is
+           not isolated in the direction that matters. */
+        copyFileSync(source, join(home, 'auth.json'));
+        writeFileSync(join(home, 'config.toml'), codexRunConfigToml(server, runTodoId, runtimePlatform, subagentsEnabled), { mode: 0o600 });
+        /* WHO OWNS THIS HOME, so the startup sweep can tell a stranded directory
+           from one a LIVE run is using. Written FIRST-ish and always, because the
+           sweep treats an ownerless home as strandable: the only way to produce one
+           is a crash between the `mkdirSync` above and this line, which is a couple
+           of syscalls with no child spawned yet, so there is nothing live to lose.
+           Two processes share this root (the terminal daemon and the companion) and
+           neither can see the other's children, so the pid is the only thing that
+           crosses the gap. See `sweepStrandedCodexHomes`. */
+        writeFileSync(join(home, OWNER_FILE), JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() }), { mode: 0o600 });
+        return home;
+    }
+    catch {
+        /* Same reasoning as the missing credential: an isolated home we cannot write
+           is not a reason to fail the user's run. */
+        return null;
+    }
+}
+/**
+ * Create or refresh the isolated home for one durable panel3 Level 2 owner.
+ * Unlike `ensureCodexRunHome`, this never removes the directory: Codex's native
+ * session files inside it are the state a later activation resumes. Only the
+ * credential copy and current sealed MCP configuration are refreshed.
+ */
+export function ensurePanel3CodexOwnerHome(server, ownerRunId, runtimePlatform = process.platform) {
+    const source = join(userCodexHome(), 'auth.json');
+    if (!existsSync(source))
+        return null;
+    const home = panel3CodexOwnerHomePath(ownerRunId);
+    try {
+        mkdirSync(home, { recursive: true, mode: 0o700 });
+        chmodSync(home, 0o700);
+        copyFileSync(source, join(home, 'auth.json'));
+        writeFileSync(join(home, 'config.toml'), codexRunConfigToml(server, null, runtimePlatform, false, true), { mode: 0o600 });
+        return home;
+    }
+    catch {
+        return null;
+    }
+}
+/** Product-owned persistent state only. Windows owners use the installed Codex
+ * home, so this path is normally absent there and removal remains harmless. */
+export function removePanel3CodexOwnerHome(ownerRunId) {
+    try {
+        rmSync(panel3CodexOwnerHomePath(ownerRunId), { recursive: true, force: true });
+    }
+    catch {
+        // Reconciliation retries. Cleanup must never turn a completed turn into a failure.
+    }
+}
+/** Valid directory names only; callers reconcile each id against the signed-in
+ * owner row before retaining it. */
+export function listPanel3CodexOwnerHomeIds() {
+    try {
+        return readdirSync(panel3CodexOwnerHomesRoot(), { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Delete a run's home once the run is over.
+ *
+ * IT TAKES THE PATH, NOT THE REQUEST ID, and that is load-bearing rather than
+ * stylistic. `codexRunHomePath(null)` now mints a RANDOM key so that concurrent
+ * requestless runs cannot share a directory, so recomputing the path here would
+ * delete a directory that never existed and leave the real one behind forever.
+ * The caller holds the path `ensureCodexRunHome` returned; it passes that.
+ *
+ * IT IS NOT MERE TIDINESS, and the comment here used to say it was. A leftover
+ * home is 32 MB after one run and holds the credential copy plus (before
+ * `--ephemeral`) the full session transcript with absolute local paths. This is
+ * the primary reclaim; `sweepStrandedCodexHomes` is the backstop for the paths
+ * that never reach it.
+ *
+ * Best-effort in the sense that it never throws: a run that has already produced
+ * the user's answer must not fail because a directory would not delete.
+ */
+export function removeCodexRunHome(home) {
+    try {
+        rmSync(home, { recursive: true, force: true });
+    }
+    catch {
+        /* Never allowed to affect a run that has already ended. The startup sweep is
+           what catches whatever this could not remove. */
+    }
+}
+/**
+ * Remove per-run codex homes whose OWNING PROCESS IS GONE.
+ *
+ * WHY A STARTUP SWEEP EXISTS AT ALL (gate A, blocker 3). The per-run sweep runs
+ * when a run ends, and there are ways a run does not end: SIGKILL, a panic, an
+ * OS restart, launchd restarting a crashed daemon, and `daemon.ts`'s own
+ * shutdown, which calls `process.exit(0)` without awaiting in-flight spawns.
+ * Every one strands a directory holding a copy of the user's credential, and
+ * nothing else in the product would ever look at it again.
+ *
+ * ═══ WHY IT IS NOT WHOLESALE, WHICH IS WHAT IT USED TO BE ═══
+ *
+ * The first version deleted the whole root, borrowing `recoverStrandedWorkers`'s
+ * argument: "if this daemon is starting, nothing it started is still running".
+ * **That argument does not transfer, and the re-review proved the harm.** That
+ * function is scoped by `machine_id` to rows this daemon owns on a SERVER; this
+ * is an unscoped `rmSync` of a SHARED LOCAL directory. TWO INDEPENDENT PROCESSES
+ * call `startPresence()`: the terminal daemon (`cs start` → `runDaemon`) and the
+ * companion (`cs open`, again after browser sign-in). The companion has a port
+ * guard; the daemon has NO cross-process guard at all. Both resolve the same
+ * `configDir()`, so `cs start` while the companion is mid-run — or launchd
+ * restarting a crashed daemon while the companion survives — deleted a LIVE
+ * worker's `$CODEX_HOME` underneath it. That is precisely the harm the `settle`
+ * fix removed, reintroduced at a new trigger.
+ *
+ * ═══ WHY THE OWNER PID, AND NOT AGE ═══
+ *
+ * Age was the obvious candidate and it is NOT SAFE AT ANY THRESHOLD I could
+ * defend, which was measured rather than assumed. During a live 40-second codex
+ * run, sampled every five seconds: the home directory's own mtime went stale
+ * almost immediately (codex writes to files INSIDE it, which does not touch the
+ * parent's mtime), and the newest mtime ANYWHERE IN THE TREE still reached ~29
+ * seconds while the run was plainly alive, because codex holds sqlite handles
+ * open without flushing. Mtime measures "when codex last flushed", not "is this
+ * run alive". A thinking agent mid-tool-call is silent BY DESIGN here — the
+ * elapsed-time kill was retired for exactly that reason (user ruling
+ * 2026-08-06, "no agent that is actively working should ever be killed
+ * automatically") — so any age threshold is a bet against a long tool call.
+ *
+ * The owner pid asks the real question instead. `processIsAlive` is the same
+ * check `reapDeadWorkers` already trusts to decide a worker really died, and it
+ * treats EPERM as alive, so a home owned by the OTHER process (a different uid,
+ * or simply not ours to signal) is correctly read as still owned.
+ *
+ * A RECYCLED PID CAN ONLY MAKE THIS TOO CAUTIOUS, NEVER TOO EAGER. If a dead
+ * owner's pid has been reused by something unrelated, the home is kept and
+ * reclaimed on a later start; the failure direction is a leftover directory, not
+ * a deleted live one. That is the right way round for a directory holding a
+ * credential in use.
+ *
+ * A HOME WITH NO OWNER FILE IS SWEPT, and there are TWO independent reasons that
+ * is safe rather than one. Within a build, an unstamped home can only come from
+ * a crash between `mkdirSync` and the owner stamp, which is a window of two
+ * syscalls with no child spawned yet, so there is nothing live to protect.
+ * Across builds, the usual worry would be a home written by an OLDER version
+ * that did not stamp — and there is no such version: this module was created on
+ * the branch that also introduced the stamp, and has never been merged or
+ * released, so no build exists anywhere that can produce a live unstamped home.
+ *
+ * Best-effort and never throws: a daemon must start even if a directory will
+ * not delete. A home that survives is retried on the next start, and the run
+ * that reuses its key rebuilds it from empty anyway.
+ */
+export function sweepStrandedCodexHomes(
+/** Injected so a test can drive the liveness decision without real processes.
+ *  Defaults to the same check `reapDeadWorkers` uses. */
+isAlive = defaultProcessIsAlive) {
+    let entries;
+    try {
+        entries = readdirSync(codexHomesRoot());
+    }
+    catch {
+        /* No root yet (the common case on a first start), or unreadable. Nothing to
+           do either way, and startup must not be blocked. */
+        return;
+    }
+    for (const entry of entries) {
+        const home = join(codexHomesRoot(), entry);
+        try {
+            if (codexRunHomeHasLiveOwner(home, isAlive))
+                continue;
+            rmSync(home, { recursive: true, force: true });
+        }
+        catch {
+            /* One home that will not delete must not stop the others, and must not
+               stop the daemon starting. Retried next start. */
+        }
+    }
+}
+/**
+ * Does this home still belong to a running process? Anything unreadable or
+ * unparseable counts as ownerless — see the sweep's comment on the two-syscall
+ * window that is the only way to produce one.
+ *
+ * `pid > 0` IS LOAD-BEARING, NOT A PLAUSIBILITY CHECK, and it was written as one
+ * before the gate pointed this out. `process.kill(0, 0)` does not ask "is pid 0
+ * alive": POSIX reads pid 0 as THE CALLER'S OWN PROCESS GROUP, and `kill(-N, 0)`
+ * targets process GROUP N. Both SUCCEED — measured on this machine — so without
+ * this a home stamped `{"pid":0}` would read as owned forever and could never be
+ * reclaimed. The guard keeps a corrupt or truncated stamp from reaching `kill`
+ * with a value that means something entirely different from "this process".
+ *
+ * `Number.isInteger` is belt-and-braces by comparison and is kept as such: node
+ * throws `ERR_INVALID_ARG_TYPE` on `1.5` and `NaN`, which `defaultProcessIsAlive`
+ * already turns into "dead" via its non-EPERM catch. It is here so the intent is
+ * stated at the point of the decision rather than resting on the catch, and a
+ * mutation removing it survives the suite for that reason.
+ */
+function codexRunHomeHasLiveOwner(home, isAlive) {
+    let pid;
+    try {
+        pid = JSON.parse(readFileSync(join(home, OWNER_FILE), 'utf8')).pid;
+    }
+    catch {
+        return false;
+    }
+    return typeof pid === 'number' && Number.isInteger(pid) && pid > 0 && isAlive(pid);
+}
+/** `process.kill(pid, 0)` signals nothing and only tests for existence. EPERM
+ *  means it exists and belongs to someone else, which still answers "alive" —
+ *  so only ESRCH ("no such process") is death. Duplicated from
+ *  `orchestrator.processIsAlive` rather than imported, because orchestrator.ts
+ *  imports THIS module and the cycle would be the only thing gained. */
+function defaultProcessIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}

package/dist/companion.js

@@ -6,7 +6,7 @@ import { companionToken, getMachineIdentity, readSession, clearSession, readCode
 import { getClient, signIn, NotLoggedIn } from './supabase.js';
 import { startPresence, stopPresence } from './presence.js';
 import { detectAgents } from './agents.js';
-import { toolsServerStatus, agentRegStatus, badgeReason } from './mcp.js';
+import { agentToolsBadgeState } from './mcp.js';
 import { loadProjects, saveMapping } from './projects.js';
 import { listCodebases, addCodebase, reportLocated, removeCodebase, NotHostedRemoteError } from './codebases.js';
 import { hostedRemoteIdentity } from './git-remote.js';
@@ -156,18 +156,15 @@ function str(value) {
 }
 /** The passive "Agent tools" badge state for the companion (feature 05). Phase 3
  *  gives it an honest lifecycle — connecting / connected / couldn't-connect — on
- *  top of the signed-out and no-agent off-states. The branching itself lives in
- *  the pure `badgeReason` (mcp.ts) so it's unit-testable; this only gathers the
- *  live signals: whether we're signed in, which supported agents are installed,
- *  whether the tools server is up, and each agent's registration status. */
+ *  top of the signed-out and no-agent off-states. The branching lives in
+ *  `agentToolsBadgeState` (mcp.ts, unit-testable): the pure `badgeReason` over
+ *  this process's live signals, plus — when THIS process doesn't own the tools
+ *  port (bug 20260730 split-brain) — a cached /health probe and the on-disk
+ *  agent registrations, so a healthy server owned by another cs process never
+ *  reads as "failed". This only gathers signed-in + installed agents. */
 function agentToolsState(signedIn) {
     const installed = detectAgents().filter((a) => a === 'claude' || a === 'codex');
-    return badgeReason({
-        signedIn,
-        installed,
-        serverRunning: toolsServerStatus().running,
-        status: agentRegStatus(),
-    });
+    return agentToolsBadgeState({ signedIn, installed });
 }
 async function handle(req, res, token) {
     if (!allowedHost(req.headers.host)) {
@@ -221,7 +218,7 @@ async function handleApi(req, res, path, query) {
             machineName: machine.name,
             platform: process.platform,
             version: VERSION,
-            agentTools: agentToolsState(email !== null),
+            agentTools: await agentToolsState(email !== null),
         });
         return;
     }

package/dist/config.js

@@ -10,6 +10,29 @@ export function configDir() {
 function filePath(name) {
     return join(configDir(), name);
 }
+/**
+ * 18b SLICE 2 — WHERE A RUN THAT NEEDS NO REPOSITORY STARTS.
+ *
+ * NEVER THE FILESYSTEM ROOT, and never `$HOME`. Passing no cwd to `spawn` means
+ * "inherit the parent's", and the parent is a launchd login item whose cwd is
+ * `/` — so a write-capable agent answering "what is on this project's board"
+ * started at the root of the user's disk. Nothing in that run needs a directory
+ * at all, which is exactly why it should be given one that contains nothing.
+ *
+ * An empty directory inside the config dir is the cheapest honest answer: it
+ * exists (so `spawn` cannot fail on chdir), it is the user's own, it is empty
+ * (so a stray relative write lands somewhere inert and visible rather than in a
+ * real tree), and it needs no cleanup between runs.
+ *
+ * ponytail: one shared directory, not one per run. Per-run temp dirs would need
+ * a lifecycle nothing here has; if two concurrent no-checkout runs ever need to
+ * be isolated from each other, mkdtemp per run is the upgrade.
+ */
+export function scratchDir() {
+    const path = join(configDir(), 'scratch');
+    mkdirSync(path, { recursive: true });
+    return path;
+}
 function writeJson(name, value) {
     mkdirSync(configDir(), { recursive: true });
     const path = filePath(name);