tumwater 0.2.0 → 0.4.0

package/dist/src/pi-extension/bounded-output.js

@@ -1,6 +1,6 @@
 /**
  * Bundled pi extension: bounds oversized tool results so a single read or command cannot
- * flood the tick's context window (PLANS.md "Bound tool output head+tail with a tumwater
+ * flood the run's context window (PLANS.md "Bound tool output head+tail with a tumwater
  * pi extension"). Loaded on every pi run via `-e <this file>` from src/pi/pi-args.ts.
  *
  * All bounding logic lives in pure, filesystem-free exported functions — `boundText`,
@@ -12,14 +12,16 @@
  * harness root and writes the file.
  *
  * Limits are constants on purpose (opinionated defaults over configuration). The read
- * limit (~12k chars ≈ 300 lines) mirrors the prompt's CONTEXT_BUDGET_RULE; the bash limit
+ * limit (~12k chars ≈ 300 lines) backs the prompt's contextBudgetRule, which asks for ranged
+ * reads past ~150 lines, the share a 64k window's scaled limit holds; the bash limit
  * is looser because test logs and build output legitimately need more tail. Both were tuned on
  * the 128k local fallback, so a model that declares a smaller window gets them scaled down in
  * proportion (`outputLimits`): a 12k-char result is twice the share of a 64k window.
  */
 import { windowScale } from "./context-window.js";
 import { writeFullOutput } from "./full-output.js";
-/** Char budget for a `read` tool result (~300 lines, matching CONTEXT_BUDGET_RULE). */
+/** Char budget for a `read` tool result (~300 lines; contextBudgetRule asks for ranges past
+ * ~150). */
 export const READ_LIMIT_CHARS = 12_000;
 /** Char budget for a `bash` tool result — looser, so test/build tails survive. */
 export const BASH_LIMIT_CHARS = 16_000;

package/dist/src/pi-extension/context-budget.js

@@ -12,8 +12,8 @@
  * the note is the stop-reading backstop for a run whose remaining results were not reclaimable. (On
  * a window under 128k context-shake crosses earlier, under pi's compaction line — see its
  * `shakeLimits` — while these notes keep their percentages.) The
- * failure mode the numbers exist for is the fallback's local model (Qwen3.8-27B): its longest ticks
- * peaked at 96–110k tokens (coverage, steward, telemetry, plan; 2026-09-29..10-01) while the
+ * failure mode the numbers exist for is the fallback's local model (Qwen3.8-27B): its longest runs
+ * peaked at 96–110k tokens (coverage, steward, selfcheck, plan; 2026-09-29..10-01) while the
  * prompt's reading budget could only say "your window is finite". On a large-window model the
  * thresholds are rarely reached, so the extension costs nothing there.
  *

package/dist/src/pi-extension/context-shake.js

@@ -11,7 +11,7 @@
  * old tool results with recoverable references and keep the recent window intact. pi 1.0.0 can
  * do the same from an extension — a `turn_end` handler appends persisted `context_edit` entries
  * (pi docs, extensions.md "Events and concurrency"; session-format.md "ContextEditEntry"). On a
- * large-window primary (1M) the 70% line sits far above the largest team tick, so the
+ * large-window primary (1M) the 70% line sits far above the largest team run, so the
  * extension plans nothing and costs nothing there.
  *
  * The selection logic is a pure, exported function (`shakePlan`) so every rule is unit-testable

package/dist/src/pi-extension/context-window.js

@@ -1,4 +1,3 @@
-// vocabulary: plain
 /**
  * The model's declared context window, as the bundled pi extensions read it: the one home of the
  * window arithmetic bounded-output, context-shake and strip-thinking share.

package/dist/src/pi-extension/full-output.js

@@ -14,7 +14,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { toolOutputDir } from "../paths.js";
-import { walkUp, writeTextAtomic } from "../files/files.js";
+import { isDirectory, walkUp, writeTextAtomic } from "../files/files.js";
 /** Walk up from `startDir` looking for a `.tumwater/` directory — the harness root. Worktrees
  * under it (`.tumwater/worktrees/<role>`, merger, gate alike) reach it three levels up
  * (`../../..`, the repo checkout that owns `.tumwater/`); a harness root carries it directly.
@@ -22,14 +22,7 @@ import { walkUp, writeTextAtomic } from "../files/files.js";
  * terminates without walking to the filesystem root; returns null when no ancestor within
  * that bound has one, so such a run writes nothing. Exported for tests. */
 export function findTumwaterRoot(startDir = process.cwd()) {
-    return walkUp(startDir, 63, (dir) => {
-        try {
-            return fs.statSync(path.join(dir, ".tumwater")).isDirectory() ? dir : null;
-        }
-        catch {
-            return null; // Not here — keep walking up.
-        }
-    });
+    return walkUp(startDir, 63, (dir) => (isDirectory(path.join(dir, ".tumwater")) ? dir : null));
 }
 /** Persist a full tool output under the harness's gitignored `.tumwater/` area and return
  * its path, or null when there is no harness root (or the write fails). Files are named
@@ -41,7 +34,7 @@ export function findTumwaterRoot(startDir = process.cwd()) {
  * orchestrator's retention passes prune this directory with the team's
  * sessionRetentionDays window (paths.ts's toolOutputDir, the single home of this path that
  * this module shares instead of re-joining it), so a pointer to a full output stays readable
- * while its tick is recent and never accumulates forever. */
+ * while its run is recent and never accumulates forever. */
 export function writeFullOutput(text, toolCallId, startDir = process.cwd()) {
     const root = findTumwaterRoot(startDir);
     if (!root)

package/dist/src/pi-extension/strip-thinking.js

@@ -1,4 +1,3 @@
-// vocabulary: plain
 /**
  * Bundled pi extension: on a model with a small context window, send none of the model's earlier
  * thinking back to it. Loaded on every pi run via `-e <this file>` from src/pi/pi-args.ts.

package/dist/src/pi-extension/trim-system-prompt.js

@@ -1,4 +1,3 @@
-// vocabulary: plain
 /**
  * Bundled pi extension: send pi's system prompt without its `docs` section, on every model.
  * Loaded on every pi run via `-e <this file>` from src/pi/pi-args.ts.
@@ -6,15 +5,15 @@
  * Why: pi 1.2.0's default system prompt carries a `<docs>` section — the install paths of pi's own
  * README, docs and examples, to read "only when the user asks about pi itself". A tumwater run
  * never does, and the section is ~1,400 characters (~350 tokens) that every request re-sends,
- * alongside tumwater's own run prompt, which is the compact one on every model too (prompt.ts
- * CompactPrompt). Until 2026-10-18 both applied only at a declared window of at most 128k; they
+ * alongside tumwater's own run prompt, which is compact on every model too (prompt.ts). Until
+ * 2026-10-18 both applied only at a declared window of at most 128k; they
  * now apply everywhere to cut token spend (a 2026-10-18 audit of the team's 1M-window runs). pi
  * offers no option to leave the section out short of replacing the whole prompt, so the
  * `before_agent_start` handler returns the rendered prompt with that one section cut — the
  * preamble, tool list, tool rules and working directory are pi's own text.
  *
  * The cut is a pure exported function so it is unit-testable without pi; the default export is
- * the thin adapter over pi's `before_agent_start` event and `ctx.model`.
+ * the thin adapter over pi's `before_agent_start` event.
  */
 /** pi's docs section as rendered, with the blank lines that separate it from the section before
  * it. pi wraps each named section in a tag of the same name. */

package/dist/src/pi-extension/write-guard.js

@@ -0,0 +1,37 @@
+/**
+ * Bundled pi extension: refuse an `edit` or `write` that would land under the team root but
+ * outside the run's own worktree, and name the path inside the worktree to use instead. Loaded on
+ * every pi run via `-e <this file>` from src/pi/pi-args.ts.
+ *
+ * The rule lives in src/agent/write-guard.ts, shared with claude's hook. This file is the thin
+ * adapter over pi's `tool_call` event, which blocks a call when a handler returns
+ * `{ block: true, reason }` (pi docs, extensions.md "Events and concurrency"); the model gets the
+ * reason as the tool's error. A nested call from a codemode script goes through the same event.
+ * pi blocks the tool when a handler throws, so an unexpected failure here lets the write through
+ * rather than stopping every edit of the run: runner-run.ts's stray-write warning still sees it.
+ */
+import { strayWriteRefusal } from "../agent/write-guard.js";
+/** The file-writing tools pi ships, by the name a `tool_call` event carries. Both take `path`. */
+const WRITE_TOOLS = new Set(["edit", "write"]);
+/** The refusal for one `tool_call` event, or undefined to let it run. Exported for tests. */
+export function guardToolCall(event, cwd) {
+    if (typeof event.toolName !== "string" || !WRITE_TOOLS.has(event.toolName))
+        return undefined;
+    const input = event.input;
+    if (typeof input !== "object" || input === null)
+        return undefined;
+    const target = input.path;
+    if (typeof target !== "string" || target === "")
+        return undefined;
+    try {
+        const reason = strayWriteRefusal(target, cwd);
+        return reason === null ? undefined : { block: true, reason };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The pi extension entry point. */
+export default function writeGuard(pi) {
+    pi.on("tool_call", (event, ctx) => guardToolCall(event, typeof ctx?.cwd === "string" ? ctx.cwd : process.cwd()));
+}

package/dist/src/process/launch-services.js

@@ -1,4 +1,3 @@
-// vocabulary: plain
 /** launchservicesd's Mach-port budget on macOS: the running team's warning, driven by a watch
  * stepped from the orchestrator's poll. The daemon keeps a port for every process that ever
  * checked in with LaunchServices and never releases it, and the kernel kills it near
@@ -47,7 +46,7 @@ export function nextLaunchServicesWarning(lastWarned, ports) {
  * is already leaking says so right away — and logs a harness warning per
  * nextLaunchServicesWarning. The sample runs in the background: a poll never waits on `top`.
  * In memory only: a restarted team warns again on its first sample if the count is still high,
- * the right default for a condition only a reboot clears. cli/cli-run.ts builds one for a daemon
+ * the right default for a condition only a reboot clears. cli/cli-start.ts builds one for a daemon
  * `tumwater run` only — a `--once` round and in-process tests run without it. */
 export class LaunchServicesWatch {
     root;

package/dist/src/process/node-bin.js

@@ -0,0 +1,16 @@
+/** Choosing which node binary a supervised child or self-reexec spawns, shared by the
+ * supervisor (spawnSupervised, src/process/supervisor.ts) and the dashboard reload
+ * (reexecSelf, src/redeploy/self-reload.ts). Both embed `process.execPath`, which is the
+ * running process's resolved, versioned node path — a Homebrew upgrade under the running team
+ * deletes the old keg while the team stays up, so `execPath` names a file that no longer
+ * exists (BUGS.md 2026-10-21). The fix is the same trick build-stage's `compileStaged` uses
+ * for tsc (BUGS-FIXED.md, the 2026-09-29 `tsc exited ENOENT` cluster): PATH resolves a live
+ * node at spawn time, so fall back to the bare `node` when the recorded binary is gone.
+ * Nothing spawns until a child is created, so this cheap existence check is the whole fix. */
+import fs from "node:fs";
+/** The node binary to pass `spawn` for a harness child: the running process's own `execPath`
+ * while it still exists, else the bare `node` resolved through PATH. An explicit path makes
+ * the deleted-keg branch testable without touching this process. */
+export function liveNodeBin(execPath = process.execPath) {
+    return fs.existsSync(execPath) ? execPath : "node";
+}

package/dist/src/process/process-group.js

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import { releaseChildHandles, signalTree, withoutLaunchServicesCheckIn } from "./process.js";
+import { captureCappedOutput, releaseChildHandles, signalTree, withoutLaunchServicesCheckIn } from "./process.js";
 import { errCode } from "../errno.js";
 /** The detached process-group runner: runScriptGroup starts a command in its own process
  * group — exactly like pi — and settles exactly once, bounding a timed-out tree at its
@@ -122,22 +122,12 @@ export function runScriptGroup(cmd, args, opts) {
             env: withoutLaunchServicesCheckIn(process.env),
         });
         let settled = false;
-        let stdout = "";
-        let stderr = "";
-        let stdoutSize = 0;
-        let stderrSize = 0;
-        child.stdout?.on("data", (chunk) => {
-            if (stdoutSize < opts.maxBuffer) {
-                stdoutSize += chunk.length;
-                stdout += chunk;
-            }
-        });
-        child.stderr?.on("data", (chunk) => {
-            if (stderrSize < opts.maxBuffer) {
-                stderrSize += chunk.length;
-                stderr += chunk;
-            }
-        });
+        // Captured output is capped at maxBuffer per stream (further chunks are dropped —
+        // classification reads the tail, so a chatty script can neither wedge the check nor balloon
+        // memory). The overflow is deliberately ignored here: truncated output still classifies.
+        // `captured` is read at settle time (its fields accumulate as data arrives), never
+        // destructured up front.
+        const captured = captureCappedOutput(child, opts.maxBuffer);
         const deadline = armGroupDeadline(child, {
             startedAt: spawnedAt,
             timeoutMs: opts.timeoutMs,
@@ -158,7 +148,7 @@ export function runScriptGroup(cmd, args, opts) {
             const run = { spawnedAt, settledAt: Date.now(), timeoutMs: opts.timeoutMs };
             if (timedOut)
                 run.deadlineLateMs = deadline.lateMs();
-            resolve({ ...result, timedOut, stdout, stderr, run });
+            resolve({ ...result, timedOut, stdout: captured.stdout, stderr: captured.stderr, run });
         }
         child.on("error", (err) => {
             // Before the deadline this is the spawn failing (npm missing from PATH). After it, it can

package/dist/src/process/process.js

@@ -24,7 +24,7 @@ export function execFileAsync(file, args, options = {}) {
  * added after the abort event never fires, so `addEventListener` alone would leave the caller
  * waiting on a shutdown that has come and gone. A missing signal (no shutdown wiring)
  * registers nothing. Shared by spawnSupervised (supervisor.ts), runPi's child spawn
- * (src/agent/run-agent.ts), sleepInterruptible (tick-timing.ts), and abortOnShutdown
+ * (src/agent/run-agent.ts), sleepInterruptible (run-timing.ts), and abortOnShutdown
  * (merge-pipeline.ts).
  *
  * Returns a disposer that detaches `fn`. A `{ once: true }` listener detaches itself when the
@@ -69,7 +69,7 @@ export function pidAlive(pid) {
  * escalating to SIGKILL after 10 s if any of it is still alive. The child is spawned detached
  * (its own process group leader — runPi does this for pi), so a negative PID reaches every
  * tool-call grandchild — which a single-PID kill leaves orphaned to launchd — while the
- * harness's own group is never in the blast radius. Shared by the tick-timeout,
+ * harness's own group is never in the blast radius. Shared by the run-timeout,
  * quiet-watchdog, and harness-shutdown kills, and by the sweep every run gets once pi exits
  * (runPi's 'exit' handler), when the group holds only what pi's tool calls backgrounded.
  *
@@ -121,6 +121,45 @@ export function releaseChildHandles(child) {
     child.stderr?.destroy();
     child.unref();
 }
+/** Collect a detached child's stdout/stderr, keeping each stream while it stays within
+ * `maxBuffer` BYTES and reporting the stream that passes the ceiling via `onOverflow` (called at
+ * most once per stream, on the first overflowing chunk). The shared acquisition the three
+ * bounded detached-child probes (execGitBounded, runScriptGroup, boundedProbe) all hand-declared
+ * before: git fails loudly and kills the child on overflow, the script runner keeps a truncated
+ * tail for classification, the doctor probe aborts and reads "could not check" — the policy stays
+ * in the caller, the byte counting here. The chunk arrives as
+ * a Buffer from a raw stdio pipe, or as a String once the caller setEncoding'd the stream; both
+ * are counted by BYTE length (Buffer.byteLength / Buffer.length), exactly what execFile's
+ * maxBuffer ceiling limits. Call BEFORE the child can emit: receivers are attached here. */
+export function captureCappedOutput(child, maxBuffer, onOverflow) {
+    const captured = { stdout: "", stderr: "", stdoutOverflow: false, stderrOverflow: false };
+    const capture = (stream) => {
+        let bytes = 0;
+        child[stream]?.on("data", (chunk) => {
+            bytes += typeof chunk === "string" ? Buffer.byteLength(chunk) : chunk.length;
+            if (bytes <= maxBuffer) {
+                captured[stream] += chunk;
+                return;
+            }
+            // Past the ceiling: drop this and every later chunk, and call onOverflow once per stream
+            // (further overflowing chunks are ignored).
+            if (stream === "stdout") {
+                if (captured.stdoutOverflow)
+                    return;
+                captured.stdoutOverflow = true;
+            }
+            else {
+                if (captured.stderrOverflow)
+                    return;
+                captured.stderrOverflow = true;
+            }
+            onOverflow?.(stream);
+        });
+    };
+    capture("stdout");
+    capture("stderr");
+    return captured;
+}
 // ── Child environments ───────────────────────────────────────────────────────────────────
 /** The child-environment policy every spawn that hands a child the harness's environment shares:
  * start from `process.env` and apply `overrides` on top. The explicit spawn sites

package/dist/src/process/run-marker.js

@@ -10,6 +10,7 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { plural } from "../text/phrases.js";
 import { execFileAsync, withoutLaunchServicesCheckIn } from "./process.js";
 /** Every lookup normally finishes in well under a second; a wedged one must not hang
  * its caller — the same ceiling process-table.ts's probe lookups carry. */
@@ -45,7 +46,7 @@ export function runMarkerEnv(base, marker) {
  * given, is prepended to PATH — run-agent passes the notes shim dir (notesShimDir) so every
  * run finds the `tumwater-notes` command first (plans/notes-command.md "Reaching it from a
  * run"). */
-export function agentBaseEnv(marker, base = process.env, binDir) {
+export function backendBaseEnv(marker, base = process.env, binDir) {
     const env = runMarkerEnv(withoutLaunchServicesCheckIn(base), marker);
     if (binDir) {
         const prev = env.PATH;
@@ -53,20 +54,28 @@ export function agentBaseEnv(marker, base = process.env, binDir) {
     }
     return env;
 }
-/** The environment variable that names a run's notebook file, exported to authoring runs as
+/** The environment variable that names a run's notes file, exported to authoring runs as
  * the path the bundled `tumwater-notes` command reads and writes (notes-cli.ts). */
 const NOTES_PATH_VAR = "TUMWATER_NOTES_PATH";
-/** `base` plus this run's notebook as NOTES_PATH_VAR when `notesPath` is set — the agent
+/** `base` plus this run's notes as NOTES_PATH_VAR when `notesPath` is set — the agent
  * adapter's run spec carries one only for authoring runs, so every other run leaves the
  * variable untouched (and an inherited value survives). Kept out of runMarkerEnv so the two
- * environment concerns — cross-group attribution and the notebook — stay separate; shared here
- * beside agentBaseEnv because all three adapters (pi, claude, opencode) build their run
+ * environment concerns — cross-group attribution and the notes — stay separate; shared here
+ * beside backendBaseEnv because all three adapters (pi, claude, opencode) build their run
  * environment from it. */
 export function withNotesPath(base, notesPath) {
     if (!notesPath)
         return base;
     return { ...base, [NOTES_PATH_VAR]: notesPath };
 }
+/** The full environment every agent backend's run starts from: the composition every adapter
+ * (pi, claude, codex, opencode) once spelled `withNotesPath(backendBaseEnv(run.runMarker,
+ * undefined, run.binDir), run.notesPath)`; the adapter layers its own settings on top, so
+ * the shared base lives here rather than being re-composed in each. Structurally typed on
+ * the three `AgentRunSpec` fields it reads so run-marker (process/) need not import agent/. */
+export function backendRunEnv(run) {
+    return withNotesPath(backendBaseEnv(run.runMarker, undefined, run.binDir), run.notesPath);
+}
 /** True when a `TUMWATER_RUN=` value names `marker` as one of its comma-separated runs. */
 function markerValueCarries(value, marker) {
     return value.split(",").includes(marker);
@@ -171,13 +180,24 @@ async function findMarkedPids(marker) {
     }
     return pidsMarkedInPs(await psEnvironTable(), marker);
 }
+/** The warning a run logs when its end-of-run sweep had to signal `count` processes it left
+ * running, or undefined when there is nothing to report. A run tumwater killed (abort, deadline,
+ * quiet watchdog, blind image read) is excluded: its process group got SIGTERM moments before
+ * the sweep scans, so members still exiting would be counted and every killed run would raise
+ * a false leak. */
+export function leftoversSweptMessage(kind, count, killed) {
+    if (count === 0 || killed)
+        return undefined;
+    const verb = count === 1 ? "was" : "were";
+    return `run sweep: ${plural(count, "process", "processes")} the ${kind} run started ${verb} still running after pi exited; sent SIGTERM`;
+}
 /** SIGTERM every same-user process whose environment names `marker`, escalating to SIGKILL
  * after 10 s for any that survive — the run's cross-group leftovers: what a tool call
  * backgrounded into its own detached group, which the process-group sweep cannot reach
  * (BUGS.md 2026-09-30). Marker membership is per-run unique, so the blast radius is exactly
  * this run's tree even while sibling runs are live. Never throws: an unreadable table (no
  * ps, a wedged /proc) degrades to no sweep — the group sweep still ran — never a failed
- * tick. Fire-and-forget by design: the run resolves on pi's output, not on the sweep. */
+ * run. Fire-and-forget by design: the run resolves on pi's output, not on the sweep. */
 export async function sweepRunMarker(marker) {
     let victims;
     try {

package/dist/src/process/supervisor.js

@@ -1,10 +1,10 @@
-// vocabulary: plain
 import { spawn } from "node:child_process";
 import { TUMWATER_SOURCE } from "../events/events.js";
 import { RESTART_EXIT_CODE } from "../redeploy/redeploy-policy.js";
 import { childEnv, runOnAbort } from "./process.js";
-/** The respawn loop behind `tumwater run`. The command runs as two processes: this supervisor (the
- * one the operator started, holding the terminal) and a child that actually runs the orchestrator.
+import { liveNodeBin } from "./node-bin.js";
+/** The respawn loop behind `tumwater start`. The command runs as two processes: this supervisor
+ * (the one the operator started, holding the terminal) and a child that runs the orchestrator.
  * When the child rebuilt dist/ onto a newer main (src/redeploy/redeployer.ts) it exits
  * RESTART_EXIT_CODE and the supervisor respawns it — the same script path, now holding the new
  * code — so a self-hosting team picks up its own changes without anyone at the keyboard. Any
@@ -12,7 +12,7 @@ import { childEnv, runOnAbort } from "./process.js";
  * is down with nobody at the keyboard either, so that exit is recorded first (onTeamDown). Ctrl+C
  * reaches both processes from the terminal (same foreground group), so the supervisor forwards only
  * SIGTERM, which a plain `kill` delivers to it alone. */
-/** Marks the child: `tumwater run` with this set runs the orchestrator instead of supervising. */
+/** Marks the child: `tumwater start` with this set runs the orchestrator instead of supervising. */
 export const SUPERVISED_ENV = "TUMWATER_SUPERVISED";
 /** Names the supervisor's pid in a supervised child's environment, so the child's parent-death
  * watch compares against the pid the spawner handed down instead of its own first read. A
@@ -23,9 +23,9 @@ export const SUPERVISOR_PID_ENV = "TUMWATER_SUPERVISOR_PID";
 /** Marks a `run --for` window's start (epoch ms), set once by the supervisor and handed to every
  * orchestrator generation, so a self-redeploy continues the window instead of opening a new one. */
 export const RUN_WINDOW_START_ENV = "TUMWATER_RUN_WINDOW_START";
-/** The exit code of a `run --once` round that finished and found failed ticks (cli-run.ts's
- * onceFailures): an asked-for ending, so the supervisor passes it through without paging the
- * team-down hook. */
+/** The exit code of a `run --once` round that finished and found failed runs
+ * (onceFailures in src/cli/cli-start-summary.ts): an asked-for ending, so the supervisor
+ * passes it through without paging the team-down hook. */
 export const ONCE_FAILED_EXIT_CODE = 3;
 /** How often the supervised generation checks that its supervisor still lives (ms). */
 const PARENT_POLL_MS = 5_000;
@@ -41,7 +41,7 @@ function intervalPoll(intervalMs) {
 /** Parent-death watch for the supervised generation. The supervisor forwards only SIGTERM —
  * SIGKILL (the OOM killer, `kill -9`) cannot be trapped or forwarded, and an uncaught supervisor
  * crash forwards nothing either — so a supervisor that dies outright leaves the generation
- * reparented (on macOS to launchd) and ticking the team unattended, with nothing left to sweep
+ * reparented (on macOS to launchd) and running the team unattended, with nothing left to sweep
  * it. The watch polls the parent pid on an interval: once it changes, the supervisor is gone
  * without having stopped the team, and `onGone` runs the same graceful stop a forwarded SIGTERM
  * would have run — a killed supervisor takes its team down with it. The timer is unref'd so it
@@ -96,7 +96,7 @@ function exitCodeOf(exit) {
 }
 /** Run child generations until one exits with something other than a restart request, and
  * return the code the supervisor should exit with. Pure apart from the injected effects. */
-export async function superviseRun(opts, signal) {
+export async function superviseStart(opts, signal) {
     const now = opts.now ?? Date.now;
     let generation = 1;
     const recentRespawns = [];
@@ -114,7 +114,7 @@ export async function superviseRun(opts, signal) {
             if (exit.code !== RESTART_EXIT_CODE || opts.stopping()) {
                 // A clean exit (a child stopped by its own SIGTERM logs orchestrator_stop) and anything
                 // while the operator is stopping are asked-for endings, and so is a once round that
-                // finished with failed ticks; everything else is the team dying.
+                // finished with failed runs; everything else is the team dying.
                 const code = exitCodeOf(exit);
                 if (code !== 0 && code !== ONCE_FAILED_EXIT_CODE && !opts.stopping())
                     await teamDown({ generation, exit, crashLoop: false });
@@ -163,7 +163,7 @@ export function teamDownEvent(down, diagnosis) {
 }
 /** The production child spawner: the same node binary and cli.js script as this process with
  * `run` as the command — plus any flags the operator's original invocation carried (e.g.
- * `tumwater run --branch x`: the child IS the orchestrator generation, so it must target the
+ * `tumwater start --branch x`: the child IS the orchestrator generation, so it must target the
  * same branch) — stdio shared (the child's event stream is what the operator sees), and
  * SUPERVISED_ENV set so it runs the orchestrator instead of supervising again, plus
  * SUPERVISOR_PID_ENV naming this supervisor so the child's own parent-death watch fires even if
@@ -171,7 +171,7 @@ export function teamDownEvent(down, diagnosis) {
  * RUN_WINDOW_START_ENV for a `--for` window. `stdio` defaults to `"inherit"` (the child's
  * event stream is what a plain `run` operator sees); `run --tui` passes silent stdio instead,
  * because the observer TUI owns the terminal and the child must not paint over its render. */
-export function spawnRunChild(signal, extraArgs = [], env = {}, stdio = "inherit") {
+export function spawnStartChild(signal, extraArgs = [], env = {}, stdio = "inherit") {
     // Spawn `run`, never `start`: the supervisor runs the build it started on, but each child
     // loads dist/src/cli.js, which a redeploy replaces with main's newest build. Every build from
     // the `start` rename on accepts `run`, and older builds accept only `run`, so `run` works
@@ -183,21 +183,22 @@ export function spawnRunChild(signal, extraArgs = [], env = {}, stdio = "inherit
         ...env,
     }, stdio);
 }
-/** The production dashboard spawner for `run --gui`: a `tumwater gui` child on its defaults,
- * stdio shared so a terminal Ctrl+C reaches it exactly as it reaches the orchestrator child —
- * unless `--tui` is hosted, when the caller passes silent stdio so the dashboard's
- * `tumwater gui at http://…` banner cannot paint over the observer TUI's full-screen render.
+/** The production dashboard spawner for `run --gui`: a `tumwater gui` child (on its defaults, or
+ * on `--port <n>` when `extraArgs` carries the port), stdio shared so a terminal Ctrl+C reaches
+ * it exactly as it reaches the orchestrator child — unless `--tui` is hosted, when the caller
+ * passes silent stdio so the dashboard's `tumwater gui at http://…` banner cannot paint over the
+ * observer TUI's full-screen render.
  * `env` carries the caller's mark — in production DASHBOARD_CHILD_ENV naming this supervisor's
  * pid — so the child's own reload watch (src/redeploy/self-reload.ts) both exits
  * RESTART_EXIT_CODE for a fresh generation on a redeploy and exits on its own if this supervisor
  * dies outright (SIGKILL, a crash), freeing the dashboard port. Deliberately not SUPERVISED_ENV:
- * the child must run `gui`, not supervise a team. Resolves like spawnRunChild — a failed spawn
+ * the child must run `gui`, not supervise a team. Resolves like spawnStartChild — a failed spawn
  * is `{ code: 1, signal: null }` — so an EMFILE/ENOMEM here cannot throw an unhandled 'error'. */
-export function spawnGuiChild(signal, env = {}, stdio = "inherit") {
-    return spawnSupervised(["gui"], signal, env, stdio);
+export function spawnGuiChild(signal, env = {}, stdio = "inherit", extraArgs = []) {
+    return spawnSupervised(["gui", ...extraArgs], signal, env, stdio);
 }
 /** Spawn one supervised child (`commandArgs` after the cli.js script path) and resolve on its
- * exit, with the abort signal wiring and spawn-failure handling shared by spawnRunChild and
+ * exit, with the abort signal wiring and spawn-failure handling shared by spawnStartChild and
  * spawnGuiChild: the signal's abort sends SIGTERM, and a spawn that never starts resolves as a
  * failed exit instead of emitting an unhandled 'error'. */
 function spawnSupervised(commandArgs, signal, env, stdio = "inherit") {
@@ -207,7 +208,7 @@ function spawnSupervised(commandArgs, signal, env, stdio = "inherit") {
             resolve({ code: 1, signal: null });
             return;
         }
-        const child = spawn(process.execPath, [script, ...commandArgs], {
+        const child = spawn(liveNodeBin(), [script, ...commandArgs], {
             stdio,
             env: childEnv(env),
         });

package/dist/src/prompt/dialect.js

@@ -1,8 +1,7 @@
-// vocabulary: plain
 /**
  * The only backend-specific prompt text (plans/agent-backends.md "What the pi extensions did,
  * per backend"). Everything else in the prompts already speaks in shell commands and "tool
- * calls"; what differs between pi and claude is the name of the notebook tool and how each
+ * calls"; what differs between pi and claude is the name of the notes tool and how each
  * backend's oversized tool output reaches the model, so those live behind a `PromptDialect`
  * that prompt.ts and prompt-followup.ts take as an optional argument.
  *
@@ -41,6 +40,21 @@ export const OPENCODE_DIALECT = {
         "Run every shell command in the foreground: never set `background`, because a background command is killed when your run ends.",
     ],
 };
+/** codex's dialect (plans/codex-backend.md §6): it has no read tool (so the reading-budget
+ * rule names only `sed -n`/`head`/`tail`), its oversized tool output comes truncated around a
+ * `…N tokens truncated…` marker (finding 18), and two backend rules tell the model how a
+ * longer command works: codex returns a session id to poll with `write_stdin`, and ends the
+ * command when the turn ends (finding 19); and all file edits go through `apply_patch` (finding
+ * 6), because the write guard checks only that tool (plans/codex-write-guard.md). */
+export const CODEX_DIALECT = {
+    readRange: "`sed -n 'A,Bp'` (or `head` / `tail`)",
+    oversizedOutput: `Oversized command output comes back as its head and tail around a \`…N tokens truncated…\`
+  marker — narrow the command (grep, \`sed -n\`, \`head\`/\`tail\`) instead of re-running it whole.`,
+    backendRules: [
+        "A command that runs longer than 30 seconds returns a session id while it keeps running. Keep calling `write_stdin` with that session id until it reports an exit code, and never end your turn while a command is still running: Codex kills it when you finish, and its result is lost.",
+        "Edit and create files with the `apply_patch` tool, not shell redirection (`>`, `>>`, `tee`) or `sed -i`.",
+    ],
+};
 /** The dialect table keyed by backend id: every backend but claude speaks pi's dialect (and
  * an unknown id falls back to pi because run-agent.ts routes an unregistered id to the pi
  * backend). Adding a backend means one row here, not another branch. */
@@ -48,6 +62,7 @@ const DIALECTS = {
     pi: PI_DIALECT,
     claude: CLAUDE_DIALECT,
     opencode: OPENCODE_DIALECT,
+    codex: CODEX_DIALECT,
 };
 /** The dialect for an agent id, read from the per-backend table. */
 export function dialectFor(agent) {