tumwater 0.1.2 → 0.2.0

package/dist/src/process/supervisor.js

@@ -1,13 +1,15 @@
+// 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.
  * 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 fleet picks up its own changes without anyone at the keyboard. Any
- * other exit ends the supervisor with the child's code — and when nobody asked for it, the fleet
- * is down with nobody at the keyboard either, so that exit is recorded first (onFleetDown). Ctrl+C
+ * code — so a self-hosting team picks up its own changes without anyone at the keyboard. Any
+ * other exit ends the supervisor with the child's code — and when nobody asked for it, the team
+ * 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. */
@@ -18,6 +20,13 @@ export const SUPERVISED_ENV = "TUMWATER_SUPERVISED";
  * arms — still counts as gone (the dashboard's DASHBOARD_CHILD_ENV carries the same mark for its
  * reload watch). */
 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. */
+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;
 /** The default poll: `check` every `intervalMs`, on a timer unref'd so an idle watch never holds
@@ -32,10 +41,10 @@ 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 fleet unattended, with nothing left to sweep
+ * reparented (on macOS to launchd) and ticking 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 fleet, and `onGone` runs the same graceful stop a forwarded SIGTERM
- * would have run — a killed supervisor takes its fleet down with it. The timer is unref'd so it
+ * 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
  * never holds the generation's event loop open past its real work. Returns the stop that
  * disarms the watch (a no-op once it fired or was already stopped). */
 export function startParentDeathWatch(onGone, opts = {}) {
@@ -91,12 +100,12 @@ export async function superviseRun(opts, signal) {
     const now = opts.now ?? Date.now;
     let generation = 1;
     const recentRespawns = [];
-    const fleetDown = async (down) => {
+    const teamDown = async (down) => {
         try {
-            await opts.onFleetDown?.(down);
+            await opts.onTeamDown?.(down);
         }
         catch {
-            // Best-effort (see onFleetDown): a trace that cannot be written must not change the exit.
+            // Best-effort (see onTeamDown): a trace that cannot be written must not change the exit.
         }
     };
     try {
@@ -104,9 +113,11 @@ export async function superviseRun(opts, signal) {
             const exit = await opts.spawnChild(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; everything else is the fleet dying.
-                if (exitCodeOf(exit) !== 0 && !opts.stopping())
-                    await fleetDown({ generation, exit, crashLoop: false });
+                // 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.
+                const code = exitCodeOf(exit);
+                if (code !== 0 && code !== ONCE_FAILED_EXIT_CODE && !opts.stopping())
+                    await teamDown({ generation, exit, crashLoop: false });
                 return exitCodeOf(exit);
             }
             const t = now();
@@ -115,7 +126,7 @@ export async function superviseRun(opts, signal) {
             recentRespawns.push(t);
             if (recentRespawns.length > MAX_RAPID_RESPAWNS) {
                 opts.onCrashLoop?.();
-                await fleetDown({ generation, exit, crashLoop: true });
+                await teamDown({ generation, exit, crashLoop: true });
                 return 1;
             }
             generation += 1;
@@ -132,17 +143,17 @@ export async function superviseRun(opts, signal) {
         }
     }
 }
-/** The `supervisor_exit` event for a fleet that went down (see onFleetDown). `diagnosis` is the
+/** The `supervisor_exit` event for a team that went down (see onTeamDown). `diagnosis` is the
  * startup gate re-asked after the death (startup-gate.ts's runStartupProblem): the likeliest
  * reason a generation dies right after a respawn is an environment that no longer boots, and the
  * child's own message reached only the terminal. Null when every precondition passes — the event
  * then carries no reason rather than a guess. A crash loop's reason is the guard itself. */
-export function fleetDownEvent(down, diagnosis) {
+export function teamDownEvent(down, diagnosis) {
     const reason = down.crashLoop
         ? `restarted itself more than ${MAX_RAPID_RESPAWNS} times within ${RESPAWN_WINDOW_MS / 1000}s — giving up`
         : diagnosis;
     return {
-        loop: "harness",
+        source: TUMWATER_SOURCE,
         type: "supervisor_exit",
         generation: down.generation,
         code: down.exit.code,
@@ -156,29 +167,40 @@ export function fleetDownEvent(down, diagnosis) {
  * 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
- * this process is killed before the child reads its first ppid. */
-export function spawnRunChild(signal, extraArgs = []) {
+ * this process is killed before the child reads its first ppid. `env` carries extra marks, e.g.
+ * 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") {
+    // 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
+    // against whatever build the child meets, even after a rollback; spawning `start` would make
+    // an updated supervisor's respawn fail with "unknown command" on a reverted build.
     return spawnSupervised(["run", ...extraArgs], signal, {
         [SUPERVISED_ENV]: "1",
         [SUPERVISOR_PID_ENV]: String(process.pid),
-    });
+        ...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.
+ * 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 fleet. Resolves like spawnRunChild — a failed spawn
+ * the child must run `gui`, not supervise a team. Resolves like spawnRunChild — a failed spawn
  * is `{ code: 1, signal: null }` — so an EMFILE/ENOMEM here cannot throw an unhandled 'error'. */
-export function spawnGuiChild(signal, env = {}) {
-    return spawnSupervised(["gui"], signal, env);
+export function spawnGuiChild(signal, env = {}, stdio = "inherit") {
+    return spawnSupervised(["gui"], 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
  * 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) {
+function spawnSupervised(commandArgs, signal, env, stdio = "inherit") {
     return new Promise((resolve) => {
         const script = process.argv[1];
         if (!script) {
@@ -186,7 +208,7 @@ function spawnSupervised(commandArgs, signal, env) {
             return;
         }
         const child = spawn(process.execPath, [script, ...commandArgs], {
-            stdio: "inherit",
+            stdio,
             env: childEnv(env),
         });
         // runOnAbort closes the register/abort race: an already-fired signal kills the child

package/dist/src/prompt/dialect.js

@@ -1,3 +1,4 @@
+// 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
@@ -10,26 +11,45 @@
  * where its own tool surface does. Adding a backend means adding one dialect here, not editing
  * every prompt builder.
  */
-/** pi's dialect: the identity of the prompts before agent backends — its `role_notes` tool,
- * its `read` tool's `offset`/`limit`, and its bundled head+tail marker. */
+/** pi's dialect: the identity of the prompts before agent backends — its `read` tool's
+ * `offset`/`limit`, and its bundled head+tail marker. */
 export const PI_DIALECT = {
-    notesTool: "role_notes",
     readRange: "the read tool's offset/limit (or `sed -n 'A,Bp'`)",
     oversizedOutput: `Oversized tool results come back as head+tail around a marker that names the omitted amount
   and where the full output lives — follow the pointer (re-read with \`offset\`/\`limit\`, or open
   the full-output file path) instead of retrying the same read.`,
 };
-/** claude's dialect: the `role_notes` MCP server registers as `mcp__tumwater__role_notes`, the
- * Read tool takes `offset`/`limit`, and Claude Code truncates oversized Bash output and spills
- * large results to a file it names (so it needs no head+tail marker). */
+/** claude's dialect: the Read tool takes `offset`/`limit`, and Claude Code truncates
+ * oversized Bash output and spills large results to a file it names (so it needs no head+tail
+ * marker). */
 export const CLAUDE_DIALECT = {
-    notesTool: "mcp__tumwater__role_notes",
     readRange: "the Read tool's offset/limit (or `sed -n 'A,Bp'`)",
     oversizedOutput: `Oversized tool results are truncated and saved to a file the tool names — read that file
   in ranges (the Read tool's offset/limit) instead of retrying the same read.`,
 };
-/** The dialect for an agent 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). */
+/** opencode's dialect (plans/opencode-backend.md §5): its read tool takes `offset`/`limit`,
+ * its oversized shell output spills to a named file (finding 17), and two backend rules tell
+ * the model how OpenCode's shell tool works: a 2-minute default timeout that `timeout`
+ * overrides, and no `background` (a backgrounded command dies when the run ends, finding 18). */
+export const OPENCODE_DIALECT = {
+    readRange: "the read tool's offset/limit (or `sed -n 'A,Bp'`)",
+    oversizedOutput: `Oversized shell output keeps only its last lines, followed by a note naming the file with
+  the full output — read that file in ranges (the read tool's offset/limit) instead of
+  re-running the command.`,
+    backendRules: [
+        "Shell commands time out after 2 minutes unless you pass `timeout` in milliseconds; give the project's check a timeout that covers it (for example 900000).",
+        "Run every shell command in the foreground: never set `background`, because a background command is killed when your run ends.",
+    ],
+};
+/** 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. */
+const DIALECTS = {
+    pi: PI_DIALECT,
+    claude: CLAUDE_DIALECT,
+    opencode: OPENCODE_DIALECT,
+};
+/** The dialect for an agent id, read from the per-backend table. */
 export function dialectFor(agent) {
-    return agent === "claude" ? CLAUDE_DIALECT : PI_DIALECT;
+    return DIALECTS[agent ?? "pi"] ?? PI_DIALECT;
 }