tumwater 0.1.2 → 0.2.0

package/dist/src/orchestrator/startup-migration-steps.js

@@ -0,0 +1,51 @@
+import { legacyMigrateLandQueueDir } from "../merge/merge-queue.js";
+import fs from "node:fs";
+import { deleteRefIfAt, refSha, refsUnder, setRef } from "../git/git.js";
+import { mergeRefName, legacyLandingStatePath } from "../paths.js";
+import { migrateLegacyRoleIds } from "../roles/legacy-role-migration.js";
+import { registerStartupMigration } from "./startup-migrations.js";
+/** The one place that fixes startup-migration step order. Callers import the runners from here,
+ * so the steps are registered before anything can run. Add a step by appending one
+ * `registerStartupMigration(...)` call at the end. */
+registerStartupMigration({ name: "mergeQueueDir", run: async (root) => legacyMigrateLandQueueDir(root) });
+registerStartupMigration({
+    name: "mergingMarker",
+    run: async (root) => {
+        try {
+            fs.unlinkSync(legacyLandingStatePath(root));
+            return ["removed the old landing.json marker"]; // vocabulary-ok: names the legacy file
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return [];
+            throw err;
+        }
+    },
+});
+registerStartupMigration({
+    name: "mergeRefs",
+    run: async (root) => {
+        const legacyPrefix = "refs/tumwater/landing/"; // vocabulary-ok: legacy name read from old refs or commits
+        const notes = [];
+        for (const { ref, sha } of await refsUnder(root, legacyPrefix)) {
+            const role = ref.slice(legacyPrefix.length);
+            const target = mergeRefName(role);
+            const existing = await refSha(root, target);
+            if (existing === null) {
+                if (!(await setRef(root, target, sha)))
+                    continue; // keep the legacy pin; the next start retries
+                await deleteRefIfAt(root, ref, sha);
+                notes.push(`moved ${ref} to ${target}`);
+            }
+            else if (existing === sha) {
+                await deleteRefIfAt(root, ref, sha);
+                notes.push(`removed ${ref}: ${target} already names the same commit`);
+            }
+            else
+                notes.push(`kept ${ref} and ${target}: they name different commits`);
+        }
+        return notes;
+    },
+});
+registerStartupMigration({ name: "legacyRoleIds", run: (root) => migrateLegacyRoleIds(root) });
+export { runStartupMigrations, runStartupMigrationsIfIdle } from "./startup-migrations.js";

package/dist/src/orchestrator/startup-migrations.js

@@ -0,0 +1,40 @@
+import { logEvent, TUMWATER_SOURCE, warnEventBestEffort } from "../events/events.js";
+import { orchestratorAlive } from "../team/orchestrator-info.js";
+import { errorMessage } from "../text/text.js";
+const registry = [];
+/** Append one step to the registry; a duplicate name throws. */
+export function registerStartupMigration(step) {
+    if (registry.some((s) => s.name === step.name))
+        throw new Error(`startup migration "${step.name}" is already registered`);
+    registry.push(step);
+}
+/** Run every registered step in registration order. A step that moved something logs one
+ * `state_migrated` event; a step that throws logs one warning, the rest still run, and the failed
+ * step retries at the next start. A second call moves and logs nothing. */
+export async function runStartupMigrations(root) {
+    for (const step of registry) {
+        try {
+            const notes = await step.run(root);
+            if (notes.length > 0) {
+                logEvent(root, {
+                    source: TUMWATER_SOURCE,
+                    type: "state_migrated",
+                    step: step.name,
+                    moved: notes.length,
+                    detail: notes.join("; "),
+                });
+            }
+        }
+        catch (err) {
+            warnEventBestEffort(root, TUMWATER_SOURCE, `startup migration ${step.name} failed: ${errorMessage(err)}`);
+        }
+    }
+}
+/** The CLI-reader form: runs the steps only when no orchestrator is alive for `root`, so a CLI
+ * process never moves files under a running team, which may still be the old build. A live team
+ * has already migrated at its own start. */
+export async function runStartupMigrationsIfIdle(root) {
+    if (orchestratorAlive(root))
+        return;
+    await runStartupMigrations(root);
+}

package/dist/src/paths.js

@@ -1,3 +1,4 @@
+import fs from "node:fs";
 import path from "node:path";
 import { DIRECTOR_ROLE } from "./roles/roles.js";
 /** All harness runtime state lives under <repo>/.tumwater (gitignored). */
@@ -17,13 +18,13 @@ export function briefCandidates(root) {
 function tumwaterDir(root) {
     return path.join(root, STATE_DIR);
 }
-/** The repo's tumwater.json — the fleet config (config.ts). */
+/** The repo's tumwater.json — the team config (config.ts). */
 export function configPath(root) {
     return path.join(root, CONFIG_BASENAME);
 }
 /** The cross-process lock serializing read-modify-write updates of tumwater.json
  * (writeConfigMutation and applyConfigRequest in config/config-write.ts): the CLI's
- * `tumwater config set`, a standalone `tumwater gui` server, and the running fleet are separate
+ * `tumwater config set`, a standalone `tumwater gui` server, and the running team are separate
  * processes that can rewrite one config in the same instant, and without serialization each
  * one's whole-file write silently drops the others' change. A lock directory owned by the
  * shared mkdir-and-pid mutex (withSyncLock, src/concurrency/lock.ts), which creates and removes
@@ -33,10 +34,11 @@ export function configLockPath(root) {
 }
 /** The cross-process lock serializing writes to the primary checkout's tracked backlog files:
  * `tumwater bug`/`plan` (backlog-write.ts's appendEntry) and `tumwater questions answer`
- * (question-commands.ts's answerQuestion) each read a whole backlog file and rewrite it, while a
- * landing's working-tree fast-forward (landing-git.ts's ffMainTo) updates those same files in
+ * (backlog/question-answer.ts's tryAnswerQuestion) each read a whole backlog file and rewrite
+ * it, while a merge's working-tree fast-forward (merge-git.ts's ffMainTo) updates those
+ * same files in
  * the same checkout by `git merge --ff-only`. Without a shared lock the CLI's stale read can
- * overwrite the landed change, and vice versa. Same mkdir-and-pid mutex as configLockPath, under
+ * overwrite the merged change, and vice versa. Same mkdir-and-pid mutex as configLockPath, under
  * .tumwater/state so it never enters the tracked tree; its critical sections are one file read
  * plus one atomic rename, short enough to exclude a merge without stalling the build re-check. */
 export function primaryWorktreeLockPath(root) {
@@ -54,7 +56,7 @@ export function exampleConfigPath(root) {
 export function configRequestPath(wt) {
     return path.join(wt, ".tumwater-config-request.json");
 }
-/** The directory every harness worktree lives under — role, lander and mirror alike. The
+/** The directory every harness worktree lives under — role, merger and mirror alike. The
  * single home of the tumwaterDir + worktrees pair: every worktree path helper below joins
  * its leaf through this, so the layout moves in one place. */
 export function worktreesDir(root) {
@@ -91,13 +93,19 @@ export function worktreeUseLockPath(root) {
     return path.join(tumwaterDir(root), "state", "worktree-use.lock");
 }
 /** The orchestrator's own info file (its pid, for liveness checks —
- * fleet/orchestrator-info.ts). */
+ * team/orchestrator-info.ts). */
 export function orchestratorStatePath(root) {
     return path.join(tumwaterDir(root), "state", "orchestrator.json");
 }
+/** The doctor's image-probe verdict cache (src/doctor/image-probe.ts): how each claimed
+ * image-input model actually answered a live probe, keyed agent/provider/model. Runtime state
+ * under .tumwater/state/, never committed. */
+export function imageProbesPath(root) {
+    return path.join(tumwaterDir(root), "state", "image-probes.json");
+}
 /** The `qa` flow-coverage ledger (tick/qa-coverage.ts): which flow each observer tick exercised
  * and how it went. Runtime state under .tumwater/state/, never committed — a passing check
- * must leave the repo untouched, or every cheap pass would move main and wake the fleet. */
+ * must leave the repo untouched, or every cheap pass would move main and wake the team. */
 export function qaCoveragePath(root) {
     return path.join(tumwaterDir(root), "state", "qa-coverage.json");
 }
@@ -108,12 +116,17 @@ export function qaCoveragePath(root) {
 export function roleNotesPath(root, role) {
     return path.join(tumwaterDir(root), "state", "notes", `${role}.md`);
 }
-/** The in-flight landing marker (merge queue 4/5): the orchestrator's drain task
- * writes it (landing-slot.ts, merge queue 4/5) and removes it after every outcome — the observers
+/** The in-flight merge marker (merge queue 4/5): the orchestrator's drain task
+ * writes it (merge-slot.ts, merge queue 4/5) and removes it after every outcome — the observers
  * (`status`, TUI, GUI) are separate processes that cannot see the drain's in-memory promise,
  * but they can read this file (plans/merge-queue.md). */
-export function landingStatePath(root) {
-    return path.join(tumwaterDir(root), "state", "landing.json");
+export function mergeStatePath(root) {
+    return path.join(tumwaterDir(root), "state", "merging.json");
+}
+/** The merge marker's old file, deleted by the startup migration (the marker is display-only,
+ * so a previous generation's is stale and is not read). */
+export function legacyLandingStatePath(root) {
+    return path.join(tumwaterDir(root), "state", "landing.json"); // vocabulary-ok: legacy path read from old layouts
 }
 /** The last completed auto-restart's timestamp (epoch ms) — unlike orchestrator.json it must
  * survive the process exit that IS the restart, so it lives in its own file and is never removed
@@ -121,17 +134,18 @@ export function landingStatePath(root) {
 export function autoRestartStampPath(root) {
     return path.join(tumwaterDir(root), "state", "auto-restart.json");
 }
-/** The green main-baseline verdicts the fleet keeps across restarts (baseline/main-baseline.ts's
- * persistBaselineVerdicts): SHAs whose suite passed, so a new generation does not re-verify them. */
+/** The green main-baseline verdicts the team keeps across restarts (baseline/main-baseline.ts's
+ * persistBaselineVerdicts): SHAs whose suite passed, so a new generation does not re-verify
+ * them. */
 export function baselineVerdictsPath(root) {
     return path.join(tumwaterDir(root), "state", "baseline-verdicts.json");
 }
-/** Marker file `tumwater reset-counters` drops for a running fleet to consume (it must also
+/** Marker file `tumwater reset-counters` drops for a running team to consume (it must also
  * zero the runners' in-memory counters, or their next save resurrects the old values). */
 export function resetRequestPath(root) {
     return path.join(tumwaterDir(root), "reset-counters.json");
 }
-/** Marker file `tumwater wake [--role <id>]` drops for a running fleet to consume: like the
+/** Marker file `tumwater wake [--role <id>]` drops for a running team to consume: like the
  * reset-counters marker it must name its targets because it can affect many loops, and like it
  * it must reach the runners' IN-MEMORY schedule — the poll loop reads eligibility from the
  * in-memory state, so clearing only the on-disk file would not wake anything. */
@@ -145,43 +159,49 @@ export function scheduledWakeDir(root) {
     return path.join(tumwaterDir(root), "wakes");
 }
 /** Marker file the dashboard's restart button (the build-stale alert's refresh icon) drops for
- * a running fleet to consume: force the pending self-redeploy past its cooldown now. Presence
+ * a running team to consume: force the pending self-redeploy past its cooldown now. Presence
  * is the request; the content is just `{ at }` — like the abort markers, one untyped flag. */
 export function restartRequestPath(root) {
     return path.join(tumwaterDir(root), "restart.json");
 }
-/** Marker file `tumwater reclaim` drops for a running fleet to consume: presence means "run
+/** Marker file `tumwater reclaim` drops for a running team to consume: presence means "run
  * one manual reclaim pass over every candidate." Like the restart marker, presence is the
- * request and the content is just `{ at }` — one untyped flag. A fleet that is not running
+ * request and the content is just `{ at }` — one untyped flag. A team that is not running
  * cannot consume it, so `cmdReclaim` runs the pass in-process instead. */
 export function reclaimRequestPath(root) {
     return path.join(tumwaterDir(root), "reclaim.json");
 }
-/** Per-role marker file `tumwater abort --role <id>` drops for a running fleet to consume:
+/** Per-role marker file `tumwater abort --role <id>` drops for a running team to consume:
  * kill that loop's in-flight tick. One file per role (presence = pending request; content is
  * just `{ at }`) keeps consumption race-free and needs no parsing — unlike the single shared
  * reset-counters marker, which must name its targets because it affects many loops. */
 export function abortRequestPath(root, role) {
     return path.join(tumwaterDir(root), `abort-${role}.json`);
 }
-/** Persistent operator-intent marker for `tumwater pause`: its presence means "the fleet is
+/** Persistent operator-intent marker for `tumwater pause`: its presence means "the team is
  * paused" until `resume` removes it — unlike the abort/reset markers above, which are one-shot
  * requests consumed on pickup. Content is `{ at }` (the pause timestamp), read for display
  * only, never required. */
 export function pausedPath(root) {
     return path.join(tumwaterDir(root), "paused.json");
 }
+/** Operator-intent marker for `tumwater stop --in <duration>`: `{ at, until }` in epoch ms. The
+ * running team's watch consumes it when `until` passes; a fresh `tumwater run` clears a
+ * stale one. */
+export function scheduledStopPath(root) {
+    return path.join(tumwaterDir(root), "stop-at.json");
+}
 /** Persistent operator-intent marker for `tumwater pause --role <id>` / `resume --role <id>`:
  * the set of individually paused roles, `{ roles: string[], at: number }` — the same
- * presence-means-paused persistence as the fleet marker above, so pausing a role before
+ * presence-means-paused persistence as the team marker above, so pausing a role before
  * startup starts it paused. Under state/ beside the orchestrator info file: unlike the
- * fleet marker it is structured state several writers rewrite (the orchestrator never does,
+ * team marker it is structured state several writers rewrite (the orchestrator never does,
  * but the shape is atomic-json state, not a presence flag). */
 export function pausedRolesPath(root) {
     return path.join(tumwaterDir(root), "state", "paused-roles.json");
 }
 /** The cross-process lock serializing read-modify-write updates of the paused-roles marker
- * (pauseRole/resumeRole in fleet/fleet-state.ts): the CLI and the GUI server are separate processes
+ * (pauseRole/resumeRole in team/team-state.ts): the CLI and the GUI server are separate processes
  * that can toggle different roles in the same instant, and without serialization the last
  * writer's whole-set overwrite silently drops the other's pause. A lock directory owned by the
  * shared mkdir-and-pid mutex (withSyncLock, src/concurrency/lock.ts), which creates and removes it;
@@ -231,6 +251,66 @@ export function sessionsRootDir(root) {
 export function sessionDir(root, role) {
     return path.join(sessionsRootDir(root), role);
 }
+/** `sessionDir`'s real team root — the nearest ancestor holding a `.tumwater` directory — or
+ * undefined when none does. run-agent installs the notes shim from THIS (never from teamRootOf,
+ * whose no-ancestor fallback can be a shared directory): writing `.tumwater` at the fallback
+ * would mint a phantom harness root every other suite on the host then found — BUGS.md
+ * 2026-10-18's `$TMPDIR/.tumwater/bin/tumwater-notes`. */
+export function nearestTumwaterRoot(sessionDir) {
+    let dir = sessionDir;
+    for (let i = 0; i < 64; i += 1) {
+        let tumwater;
+        try {
+            tumwater = fs.statSync(path.join(dir, ".tumwater"));
+        }
+        catch {
+            tumwater = undefined;
+        }
+        if (tumwater?.isDirectory())
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return undefined;
+}
+/** The team root that owns `sessionDir`: the `.tumwater` directory that contains it. A run's
+ * session dir is always `<root>/.tumwater/sessions/…`, so the first ancestor holding a
+ * `.tumwater` directory is the root; opencodeDbPath reads back to that same `.tumwater` for
+ * the run's shared database. The no-ancestor fallback — a directory two levels up — is
+ * unreachable in a harness run and used only by OpenCode's harness-only read-back lookups
+ * (opencodeDbPath, loadConfigSafe), which always see a real root. Never use this to decide
+ * where to WRITE a `.tumwater`: the fallback can be a shared directory, and creating `.tumwater`
+ * there mints a phantom root (BUGS.md 2026-10-18); run-agent's shim install uses
+ * nearestTumwaterRoot instead. Moved here from the opencode adapter (plans/notes-command.md) so
+ * run-agent's shim install — which every backend's run needs — shares the one lookup instead of
+ * the opencode adapter keeping it private. */
+export function teamRootOf(sessionDir) {
+    return nearestTumwaterRoot(sessionDir) ?? path.dirname(path.dirname(sessionDir));
+}
+/** The directory the notes shim lands in, under a team root: `<root>/.tumwater/bin`.
+ * run-agent installs the `tumwater-notes` command there (src/agent/notes-shim.ts) and
+ * run-marker's agentBaseEnv prepends it to every run's PATH, so a run on any backend finds
+ * the command (plans/notes-command.md "Reaching it from a run"). */
+export function notesShimDir(root) {
+    return path.join(tumwaterDir(root), "bin");
+}
+/** The shared OpenCode session database for a team root (plans/opencode-backend.md §4): one
+ * file per root, under the same `.tumwater` the run's session dir lives in, so the 6.5 MB
+ * models catalog is downloaded once and six concurrent runs on one file work. The opencode
+ * adapter derives `root` from a run's session dir (the `.tumwater` that contains it) and
+ * points `OPENCODE_DB` here. */
+export function opencodeDbPath(root) {
+    return path.join(tumwaterDir(root), "opencode", "opencode.db");
+}
+/** tumwater's cached models.dev catalog for OpenCode (plans/opencode-backend.md §7; part
+ * 6a/7 opencode-catalog.ts): the providers the config routes through OpenCode, priced from
+ * models.dev's `api.json` at most once a day. Runtime state under .tumwater/state/, never
+ * committed. */
+export function opencodeModelsPath(root) {
+    return path.join(tumwaterDir(root), "state", "opencode-models.json");
+}
 /** Session dir for a role's review-gate runs. Kept OUTSIDE the role's own session dir on
  * purpose: hasResumableSession (the resume-after-shutdown guard) must only ever see the
  * AUTHOR's sessions — a leftover reviewer session would make an interrupted tick "resume"
@@ -256,15 +336,20 @@ export function inboxDir(root) {
 export function roleInboxDir(root, role) {
     return role === DIRECTOR_ROLE ? inboxDir(root) : path.join(inboxDir(root), role);
 }
-/** The durable land queue (src/landing/landing-queue.ts): a changed tick's pinned commit waits here
- * as one JSON file for the orchestrator's landing pipeline (plans/merge-queue.md 3/5, land-queue
+/** The durable merge queue (src/merge/merge-queue.ts): a changed tick's pinned commit waits here
+ * as one JSON file for the orchestrator's merge pipeline (plans/merge-queue.md 3/5, land-queue
  * speed 2c). Like the inbox it is a directory of timestamped files —
  * a crash between enqueue and drop loses nothing, and `tumwater status` can read it without the
  * scheduler. */
-export function landQueueDir(root) {
-    return path.join(tumwaterDir(root), "land-queue");
+export function mergeQueueDir(root) {
+    return path.join(tumwaterDir(root), "merge-queue");
+}
+/** The merge queue's old directory, still read by observers until the startup migration
+ * (src/orchestrator/startup-migration-steps.ts) moves its files into `mergeQueueDir`. */
+export function legacyLandQueueDir(root) {
+    return path.join(tumwaterDir(root), "land-queue"); // vocabulary-ok: legacy path read from old layouts
 }
-/** The lock dir serializing merges to main (landing-merge.ts; doctor checks it). */
+/** The lock dir serializing merges to main (merge-to-main.ts; doctor checks it). */
 export function mergeLockDir(root) {
     return path.join(tumwaterDir(root), "merge.lock");
 }
@@ -284,19 +369,19 @@ export function gateMainWorktreePath(root) {
 }
 /** Detached worktree pinned at the RUNNING build's own SHA for the redeployer's urgency
  * carve-out (redeploy.ts's buildRed): the baseline check that decides whether the build the
- * fleet is executing is red runs here — its own checkout, not the redeploy mirror above, so a
+ * team is executing is red runs here — its own checkout, not the redeploy mirror above, so a
  * witness check at an old SHA can never repoint the mirror a green check or compile is using.
  * The leading underscore follows the _main convention, so it can never collide with a role. */
 export function witnessWorktreePath(root) {
     return path.join(worktreesDir(root), "_build");
 }
 /** One slot of the worktree pool (plans/worktree-pool.md): a fixed `.tumwater/worktrees/_slot-<n>`
- * checkout that ticks and vets lease and switch commits in place, instead of one `_land-<role>`
+ * checkout that ticks and verifies lease and switch commits in place, instead of one `_land-<role>`
  * per role. The leading underscore keeps it from colliding with a role worktree. */
 export function slotWorktreePath(root, n) {
     return path.join(worktreesDir(root), `_slot-${n}`);
 }
-/** The worktree pool's dedicated checkout for the landing drain's merge-side work
+/** The worktree pool's dedicated checkout for the merge drain's merge-side work
  * (plans/worktree-pool.md, "Layout"): a single change, a stack and its bisect, the conflict
  * resolver and the post-resolve re-review. Kept out of the pool so a permit-waiting lease can
  * never deadlock behind the merge lock, and the leading underscore keeps it from colliding with
@@ -316,15 +401,21 @@ export function slotsStatePath(root) {
 export function slotsLockPath(root) {
     return path.join(tumwaterDir(root), "state", "slots.lock");
 }
-/** The ref pinning a role's committed-but-unlanded sha (plans/merge-queue.md invariant 4):
+/** The ref pinning a role's committed-but-not yet merged sha (plans/merge-queue.md invariant 4):
  * written right after the tick's commit, before its branch resets to main, so the reset cannot
- * orphan the work. Deleted on every terminal landing outcome; kept until re-landed otherwise. */
-export function landingRefName(role) {
-    return `refs/tumwater/landing/${role}`;
+ * orphan the work. Deleted on every terminal merge outcome; kept until re-merged otherwise. */
+export function mergeRefName(role) {
+    return `refs/tumwater/merge/${role}`;
+}
+/** The pre-rename pin name (`refs/tumwater/landing/<role>`): the startup step moves these to
+ * mergeRefName, and retire still reads and deletes it for a team stopped before its first
+ * start on this build. */
+export function legacyLandingRefName(role) {
+    return `refs/tumwater/landing/${role}`; // vocabulary-ok: legacy name read from old refs or commits
 }
 /** The ref naming a role's rejected change while a revision is due (plans/revise-rejected.md):
  * written at the gate's rejection, read by the author's next tick to re-apply the rejected diff,
- * and deleted once the revision lands, is dropped, conflicts, or exhausts its rounds. Keeping
+ * and deleted once the revision merges, is dropped, conflicts, or exhausts its rounds. Keeping
  * the head reachable here stops git gc from collecting the one commit the revision re-applies. */
 export function rejectedRefName(role) {
     return `refs/tumwater/rejected/${role}`;

package/dist/src/pi/pi-args.js

@@ -8,11 +8,27 @@ import { fileURLToPath } from "node:url";
  * location so staged builds (.tumwater/build/<sha>) load their own copies: bounded-output caps
  * oversized tool results, context-shake then reclaims old bulky results at 70% of the window,
  * context-budget appends its context-usage note to the (already bounded) result that crosses a
- * threshold, and role-notes registers the `role_notes` tool (only when TUMWATER_NOTES_PATH
- * names a notebook — see pi-extension/role-notes.ts). */
+ * threshold, strip-thinking drops the model's replayed thinking from each request on a
+ * small-window chat-completions model, and trim-system-prompt drops pi's docs section from the
+ * system prompt. Notes ride the `tumwater-notes` command on
+ * every backend from part 2/4 on, so the role-notes extension is no longer bundled. */
 export function bundledExtensionPaths() {
-    return ["bounded-output.js", "context-shake.js", "context-budget.js", "role-notes.js"].map((file) => fileURLToPath(new URL(`../pi-extension/${file}`, import.meta.url)));
+    return [
+        "bounded-output.js",
+        "context-shake.js",
+        "context-budget.js",
+        "strip-thinking.js",
+        "trim-system-prompt.js",
+    ].map((file) => fileURLToPath(new URL(`../pi-extension/${file}`, import.meta.url)));
 }
+/** pi 1.2.0's built-in extensions other than `mcp`, read from pi's own `dist/extensions/index.js`.
+ * Team runs skip pi's auto-discovery with `--no-extensions`, then re-enable exactly these with an
+ * explicit `-e builtin:` — so an installed pi package, a `~/.pi/agent/extensions` file, a target
+ * repo's own `.pi/extensions`, and pi's built-in MCP extension (which reads `~/.pi/agent/mcp.json`)
+ * can never smuggle an operator MCP server (e.g. funes) into a team run, while behavior is
+ * otherwise unchanged. A pi bump that renames or adds a built-in is a visible diff here; doctor
+ * prints the same names so a package meant for the team does not vanish silently. */
+export const PI_KEPT_BUILTINS = ["llama.cpp", "codemode", "tool-search"];
 /** Build the pi argv for one tick: the harness's own flags, the bundled extensions, then the
  * user's config.piArgs (so a user flag still wins). */
 export function piArgs(opts) {
@@ -33,6 +49,13 @@ export function piArgs(opts) {
     // tumwater pi extension") and tell the model how full its window is at fixed thresholds.
     // Loaded before config.piArgs so a user flag still wins.
     if (path.basename(opts.agentBin ?? "pi") === "pi") {
+        // Disable pi's discovered extensions (packages, ~/.pi/agent/extensions, a repo's own
+        // .pi/extensions, and the built-in MCP reader for ~/.pi/agent/mcp.json), then re-enable only
+        // the named built-ins so operator MCP servers stay out of team runs. Kept before tumwater's
+        // own `-e` extensions; config.piArgs still wins (appended last).
+        args.push("--no-extensions");
+        for (const builtin of PI_KEPT_BUILTINS)
+            args.push("-e", `builtin:${builtin}`);
         for (const ext of bundledExtensionPaths())
             args.push("-e", ext);
     }

package/dist/src/pi/pi-backend.js

@@ -5,8 +5,8 @@
  * backend-neutral. The claude adapter registers alongside it in src/agent/run-agent.ts. */
 import { piArgs } from "./pi-args.js";
 import { resolveBackendBin } from "./pi-bin.js";
-import { agentBaseEnv } from "../process/run-marker.js";
-import { isPermanentConfigError, matchBackendFailure } from "./pi-stream.js";
+import { agentBaseEnv, withNotesPath } from "../process/run-marker.js";
+import { isPermanentConfigError, matchBackendFailure } from "./pi-failure.js";
 import { hasResumableSession, sessionResumable } from "../agent/session-ledger.js";
 /** pi crashing on malformed JSON, as Node's JSON.parse phrases it on pi's stderr — five ticks in
  * the first 18 days died this way (one of them 2 h 39 m of director work on a fresh steering
@@ -18,13 +18,6 @@ export const TRANSIENT_PI_CRASH = /Unexpected end of JSON input|is not valid JSO
  * mispricing of BUGS.md 2026-10-06. Matched against the child's stderr at exit; exported for
  * tests. */
 export const MODEL_FALLBACK_CLONE = /not found for provider[^\n]*Using custom model id/i;
-/** `base` plus TUMWATER_NOTES_PATH when this run carries a notebook. Kept out of runMarkerEnv so
- * the two environment concerns — cross-group attribution and the notebook — stay separate. */
-function withNotesPath(base, notesPath) {
-    if (!notesPath)
-        return base;
-    return { ...base, TUMWATER_NOTES_PATH: notesPath };
-}
 /** pi's identity translator: every native line is already a canonical line. */
 const identityTranslator = {
     translate: (line) => [line],
@@ -39,20 +32,19 @@ export const piBackend = {
         return resolveBackendBin(config, this);
     },
     invocation(run) {
-        // The prompt rides as the last argv element (pi's own reading of a bare trailing arg), so
-        // pi delivers no stdin — the runner leaves stdio[0] "ignore" exactly as before.
-        const args = [
-            ...piArgs({
-                config: run.config,
-                sessionDir: run.sessionDir,
-                sessionName: run.sessionName,
-                continueSession: run.continueSession,
-                agentBin: run.agentBin,
-            }),
-            run.prompt,
-        ];
-        const env = withNotesPath(agentBaseEnv(run.runMarker), run.notesPath);
-        return { args, env };
+        // The prompt rides on stdin, never argv: pi --print reads a piped stdin to EOF as the first
+        // message (trimmed), and the runner writes and closes it. As the last argv element it sat
+        // in every pi's `ps` command line, so one agent's `pkill -f "npm run test"` matched — and
+        // SIGTERMed — every pi run on the host whose prompt mentions the check (BUGS.md 2026-10-18).
+        const args = piArgs({
+            config: run.config,
+            sessionDir: run.sessionDir,
+            sessionName: run.sessionName,
+            continueSession: run.continueSession,
+            agentBin: run.agentBin,
+        });
+        const env = withNotesPath(agentBaseEnv(run.runMarker, undefined, run.binDir), run.notesPath);
+        return { args, stdin: run.prompt, env };
     },
     translator() {
         return identityTranslator;

package/dist/src/pi/pi-bin.js

@@ -3,7 +3,7 @@ import path from "node:path";
 import { resolvedAgentConfig } from "../config/config-views.js";
 import { envPath, findOnPath } from "../files/files.js";
 /** Which agent binary the harness spawns and where that value came from — the per-agent
- * resolution `TUMWATER_<ID>_BIN` → `agents.<id>.bin` (pi's legacy `agentBin` alias) → the
+ * resolution `TUMWATER_<ID>_BIN` → `backends.<id>.bin` (pi's legacy `agentBin` alias) → the
  * backends' defaults (plans/agent-backends.md "Config"; plans/portability.md §5/7), the
  * executability rule the preflight askers share, and the missing-binary wording they quote.
  * The spawn (src/agent/run-agent.ts) resolves through each backend's resolveBin; the startup
@@ -19,7 +19,7 @@ const PI_MISSING_MESSAGE = "pi not found on PATH — install it (https://github.
  * report. Exported so src/agent/run-agent.ts's spawn errors and doctor's checks quote the same
  * string. `binEnv` is the environment variable a backend reads (pi's TUMWATER_PI_BIN by
  * default; claude's adapter passes TUMWATER_CLAUDE_BIN), and `configKey` is the tumwater.json
- * key the "config" source names (pi's legacy `agentBin`, or `agents.<id>.bin`), so a claude
+ * key the "config" source names (pi's legacy `agentBin`, or `backends.<id>.bin`), so a claude
  * failure names its own var and key rather than pi's. */
 export function agentBinSourceLabel(source, binEnv = "TUMWATER_PI_BIN", configKey = "agentBin") {
     switch (source) {
@@ -45,7 +45,7 @@ export function piMissingMessage(resolved) {
 /** The missing-binary message for any agent's resolved binary, used by the startup gate's walk
  * over every enabled seam's agent. pi delegates to piMissingMessage so its pinned wording is
  * untouched; any other agent names itself, the resolved value, and where it came from, so a
- * wrong `agents.<id>.bin` or `TUMWATER_<ID>_BIN` never reads as a missing pi. */
+ * wrong `backends.<id>.bin` or `TUMWATER_<ID>_BIN` never reads as a missing pi. */
 export function agentMissingMessage(resolved, agent) {
     if (agent === "pi")
         return piMissingMessage(resolved);
@@ -61,14 +61,14 @@ function agentBinEnv(agent) {
     return `TUMWATER_${agent.toUpperCase()}_BIN`;
 }
 /** The tumwater.json key that names one agent's binary: pi's legacy `agentBin`, or the
- * per-agent `agents.<id>.bin`. Shared by the missing-binary and spawn-error wording so a
+ * per-agent `backends.<id>.bin`. Shared by the missing-binary and spawn-error wording so a
  * non-pi failure never names pi's key. */
 export function agentBinConfigKey(agent) {
-    return agent === "pi" ? "agentBin" : `agents.${agent}.bin`;
+    return agent === "pi" ? "agentBin" : `backends.${agent}.bin`;
 }
 /** The source label for one agent's resolved binary, deriving the env var and config key from
  * the agent id when the caller has no backend defaults in hand. pi keeps its pinned legacy
- * wording; any other agent names its own `TUMWATER_<ID>_BIN` and `agents.<id>.bin`. One home
+ * wording; any other agent names its own `TUMWATER_<ID>_BIN` and `backends.<id>.bin`. One home
  * for the convention agentMissingMessage and doctor's ok detail both read. */
 export function agentBinSourceLabelFor(agent, source) {
     return agent === "pi"
@@ -79,13 +79,19 @@ export function agentBinSourceLabelFor(agent, source) {
  * the startup gate should refuse to boot and doctor should fail its check. This is the whole
  * executability rule in one place so the two askers cannot drift: a path-shaped value (already
  * normalized against the process cwd by resolveAgentBin) is tested directly with
- * accessSync(X_OK); a bare name resolves through PATH. `pathEnv` is injectable so tests need
- * no PATH mutation — the gate and doctor both default it to the process PATH. */
+ * accessSync(X_OK) and required to be a regular file — a directory passes X_OK, but can never
+ * be spawned, so it is rejected here with exactly the file requirement findOnPath's bare-name
+ * branch applies (a bin pointed at a directory would otherwise pass the preflight and die
+ * mid-run at the spawn instead of failing the gate with the "not an executable" message). A
+ * bare name resolves through PATH. `pathEnv` is injectable so tests need no PATH mutation —
+ * the gate and doctor both default it to the process PATH. */
 export function findAgentBinary(resolved, pathEnv = envPath()) {
     if (resolved.bin.includes("/")) {
         try {
-            fs.accessSync(resolved.bin, fs.constants.X_OK);
-            return resolved.bin;
+            fs.accessSync(resolved.bin, fs.constants.X_OK); // Directories pass X_OK; require a file.
+            if (fs.statSync(resolved.bin).isFile())
+                return resolved.bin;
+            return null;
         }
         catch {
             return null;
@@ -106,7 +112,7 @@ function absBin(value) {
 /** The precedence every backend shares, parameterized by its own env override and default
  * binary name: `<binEnv>` env → the configured entry's bin → `defaultBin`. An empty or
  * whitespace value falls through to the next source, so `TUMWATER_PI_BIN= tumwater run` cannot
- * wedge the fleet on a typo'd export. This is precedence only — resolvability is checked at the
+ * wedge the team on a typo'd export. This is precedence only — resolvability is checked at the
  * preflight sites (cmdRun and doctor), never here. Private: the backends and the gate resolve
  * through resolveAgentBin, its one caller. */
 function resolveBinFrom(binEnv, defaultBin, configured) {
@@ -119,7 +125,7 @@ function resolveBinFrom(binEnv, defaultBin, configured) {
     return { bin: defaultBin, source: "default" };
 }
 /** Resolve which binary one agent spawns: `TUMWATER_<ID>_BIN` → the effective
- * `agents.<id>.bin` (config-views.ts resolvedAgentConfig, so pi's legacy `agentBin` still
+ * `backends.<id>.bin` (config-views.ts resolvedAgentConfig, so pi's legacy `agentBin` still
  * names pi) → the agent's default. `agent` defaults to pi, the historical backend; the
  * backends pass their own id, binEnv and defaultBin, while the startup gate derives the
  * reserved agents' conventional env name and default binary when it walks every enabled seam. */

package/dist/src/pi/pi-event-line.js

@@ -51,7 +51,7 @@ export function parsePiEventLine(line, types) {
  * empty-content update right after start, and only updates with real text prove the command is
  * alive — so stalled-tool-call tracking (src/pi/pi-watchdogs.ts's warning,
  * src/ui/progress-data.ts's flag) moves its clock on these alone: a content-free keepalive must
- * not mask a hang, exactly as message_update deltas cannot reset the quiet watchdog. */
+ * not mask a hang — the same rule messageUpdateHasContent applies to streaming deltas. */
 export function toolUpdateHasContent(partialResult) {
     if (!isJsonObject(partialResult))
         return false;
@@ -60,6 +60,22 @@ export function toolUpdateHasContent(partialResult) {
         return false;
     return content.some((block) => isJsonObject(block) && isNonBlankString(block.text));
 }
+/** True when a `message_update` carries new assistant content — a non-blank
+ * `assistantMessageEvent.delta`. pi's protocol strips the cumulative message snapshot from
+ * these lines, so the delta is all they carry: a content-free one (a zombie stream's
+ * keepalive, or the pre-strip shape with no delta event at all) proves nothing and must not
+ * reset the hang watchdog, exactly as a content-free tool_execution_update must not
+ * (toolUpdateHasContent). A content-bearing delta IS real generation, and the quiet watchdog
+ * counts it: a long thinking block on a slow model emits nothing else for its whole duration,
+ * so ignoring deltas killed live runs as hung (BUGS.md 2026-10-17). */
+export function messageUpdateHasContent(event) {
+    if (!isJsonObject(event))
+        return false;
+    const update = event.assistantMessageEvent;
+    if (!isJsonObject(update))
+        return false;
+    return isNonBlankString(update.delta);
+}
 /** The call's full raw command text from a tool-execution event's args (bash-like tools name
  * it `command`, some `cmd`; other tools yield ""). The two open-call trackers
  * (src/pi/pi-watchdogs.ts's stall warning, src/ui/progress-data.ts's dashboard flag) store this