tumwater 0.2.0 → 0.3.0

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

@@ -8,22 +8,26 @@ export function registerStartupMigration(step) {
         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. */
+/** Run every registered step in registration order. A step that changed something logs one
+ * `state_migrated` event, whose detail also lists any collisions it kept; a step that only kept
+ * collisions logs nothing. A step that reports failed artifacts or throws logs one warning, the
+ * rest still run, and the step retries at the next start. A second call logs nothing once the
+ * first moved everything it could. */
 export async function runStartupMigrations(root) {
     for (const step of registry) {
         try {
-            const notes = await step.run(root);
-            if (notes.length > 0) {
+            const { moved, kept, failed } = await step.run(root);
+            if (moved.length > 0) {
                 logEvent(root, {
                     source: TUMWATER_SOURCE,
                     type: "state_migrated",
                     step: step.name,
-                    moved: notes.length,
-                    detail: notes.join("; "),
+                    moved: moved.length,
+                    detail: [...moved, ...kept].join("; "),
                 });
             }
+            if (failed.length > 0)
+                warnEventBestEffort(root, TUMWATER_SOURCE, `startup migration ${step.name}: ${failed.join("; ")}`);
         }
         catch (err) {
             warnEventBestEffort(root, TUMWATER_SOURCE, `startup migration ${step.name} failed: ${errorMessage(err)}`);

package/dist/src/paths.js

@@ -1,6 +1,6 @@
-import fs from "node:fs";
 import path from "node:path";
 import { DIRECTOR_ROLE } from "./roles/roles.js";
+import { isDirectory } from "./files/files.js";
 /** All harness runtime state lives under <repo>/.tumwater (gitignored). */
 export const STATE_DIR = ".tumwater";
 /** The config file's basename — the name .gitignore's entry and the init output share. */
@@ -8,7 +8,7 @@ export const CONFIG_BASENAME = "tumwater.json";
 /** The tracked settings template's basename: the shareable baseline an untracked
  * tumwater.json is seeded from (plans/portability.md §4a/7). */
 export const EXAMPLE_CONFIG_BASENAME = "tumwater.example.json";
-/** The files the project brief (the managed initial prompt + status sections) may live in,
+/** The files the project brief (the managed brief text + status sections) may live in,
  * candidates in resolution order: TUMWATER.md first, so an adopted repo's own README.md stays
  * untouched (plans/portability.md §7a/7); README.md is the compatibility path every repo
  * tumwater has created so far. */
@@ -23,7 +23,8 @@ 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
+ * (writeConfigMutation in config/config-write-core.ts and applyConfigRequest in
+ * config/config-request.ts): the CLI's
  * `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
@@ -51,7 +52,7 @@ export function exampleConfigPath(root) {
 }
 /** The director's config-write request file, at its worktree root (plans/portability.md §3/7):
  * the director writes it, the harness consumes and deletes it before any commit path — so it
- * never enters a diff, a review prompt, or the project's history, and custom-loop management
+ * never enters a diff, a review prompt, or the project's history, and custom-role management
  * works whether or not tumwater.json is tracked. */
 export function configRequestPath(wt) {
     return path.join(wt, ".tumwater-config-request.json");
@@ -62,22 +63,46 @@ export function configRequestPath(wt) {
 export function worktreesDir(root) {
     return path.join(tumwaterDir(root), "worktrees");
 }
-/** A loop's persistent git worktree under .tumwater/worktrees/. */
+/** Where a pooled slot's uncommitted leftovers are saved as patches before the slot is reset for
+ * another lease (slot-salvage.ts). A patch directly here is kept for the operator until session
+ * retention prunes it; one waiting for its role's next run lives under salvagePendingDir. */
+export function salvageDir(root) {
+    return path.join(tumwaterDir(root), "salvage");
+}
+/** The patches of `role`'s unfinished work waiting for its next run to restore them
+ * (slot-salvage.ts, restoreSalvagedWork). */
+export function salvagePendingDir(root, role) {
+    return path.join(salvageDir(root), "pending", role);
+}
+/** A role's persistent git worktree under .tumwater/worktrees/. */
 export function worktreePath(root, role) {
     return path.join(worktreesDir(root), role);
 }
-/** A loop's persistent branch name. */
+/** A role's persistent branch name. */
 export function branchName(role) {
     return `tumwater/${role}`;
 }
-/** A role's per-loop state file (.tumwater/state/<role>.json; loop-state.ts). */
+/** A role's state file (.tumwater/state/<role>.json; runner-state.ts). */
 export function statePath(root, role) {
     return path.join(tumwaterDir(root), "state", `${role}.json`);
 }
+/** A backend's subscription account state (.tumwater/state/<backend>-account.json;
+ * subscription-account.ts): the billing answer and newest subscription window readings,
+ * written by the orchestrator only. */
+export function accountPath(root, backend) {
+    return path.join(tumwaterDir(root), "state", `${backend}-account.json`);
+}
 /** The claude account state (.tumwater/state/claude-account.json; claude-account.ts): the
- * billing answer and newest subscription window readings, written by the orchestrator only. */
+ * claude backend's subscription account — accountPath for the "claude" backend. */
 export function claudeAccountPath(root) {
-    return path.join(tumwaterDir(root), "state", "claude-account.json");
+    return accountPath(root, "claude");
+}
+/** The codex write guard's trust cache (.tumwater/state/codex-hook-trust.json;
+ * codex-hook-trust.ts): the `{key, hash}` codex itself reports through `hooks/list`, keyed by
+ * codex version and hook definition so the lookup runs once per build and Codex version, not
+ * once per run. Runtime state under .tumwater/state/, never committed. */
+export function codexHookTrustPath(root) {
+    return path.join(tumwaterDir(root), "state", "codex-hook-trust.json");
 }
 /** The worktree-use registry (plans/disk-floor.md, part 2/4; git/worktree-use.ts): which
  * worktrees are in use and when each was last used, so pressure reclaim can order candidates
@@ -103,15 +128,28 @@ export function orchestratorStatePath(root) {
 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
+/** The images column `tumwater doctor` last read from `pi --list-models`, keyed provider/model.
+ * Runtime state under .tumwater/state/, never committed. */
+export function piListedModelsPath(root) {
+    return path.join(tumwaterDir(root), "state", "pi-listed-models.json");
+}
+/** The `qa` flow-coverage ledger (run/qa-coverage.ts): which flow each observer run 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 team. */
 export function qaCoveragePath(root) {
     return path.join(tumwaterDir(root), "state", "qa-coverage.json");
 }
-/** A role's notebook (.tumwater/state/notes/<role>.md): the bounded note the role's own earlier
- * ticks wrote, carried into the next fresh session. Runtime state under .tumwater/state/, never
- * committed — the worktree resets to main each tick, so a committed note would move main. The
+/** The `feedback` observer's per-install filing ledger (run/feedback-filings.ts): which GitHub
+ * issues this install already filed on znation/tumwater, so the next fresh session's prompt can
+ * render a "previously filed" block without re-deriving its dedupe from the network alone.
+ * Runtime state under .tumwater/state/, never committed — a filing must leave the repo untouched
+ * (the role's only write is `gh`), and the worktree resets to main each run. */
+export function feedbackFilingsPath(root) {
+    return path.join(tumwaterDir(root), "state", "feedback-filings.json");
+}
+/** A role's notes (.tumwater/state/notes/<role>.md): the bounded note the role's own earlier
+ * runs wrote, carried into the next fresh session. Runtime state under .tumwater/state/, never
+ * committed — the worktree resets to main each run, so a committed note would move main. The
  * director has none: its work is the operator's prompt, not a recurring search. */
 export function roleNotesPath(root, role) {
     return path.join(tumwaterDir(root), "state", "notes", `${role}.md`);
@@ -123,6 +161,22 @@ export function roleNotesPath(root, role) {
 export function mergeStatePath(root) {
     return path.join(tumwaterDir(root), "state", "merging.json");
 }
+/** The reverted changes still waiting for a free runner (.tumwater/state/reverted.json;
+ * src/merge/merge-drain.ts): `{ reverted: [{ commit, role, reasons }] }`, each entry dropped once
+ * assigned. */
+export function revertedPendingPath(root) {
+    return path.join(tumwaterDir(root), "state", "reverted.json");
+}
+/** Merged commits awaiting their review after merging (src/review/post-merge-review.ts), for roles
+ * listed in `review.afterMerge`: `{ pending: PostReview[] }`. Runtime state, never committed. */
+export function postReviewPath(root) {
+    return path.join(tumwaterDir(root), "state", "post-review.json");
+}
+/** The detached checkout a post-merge review reads the merged commit in; the leading underscore
+ * keeps it from colliding with a role worktree. */
+export function postReviewWorktreePath(root) {
+    return path.join(worktreesDir(root), "_post-review");
+}
 /** 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) {
@@ -140,13 +194,18 @@ export function autoRestartStampPath(root) {
 export function baselineVerdictsPath(root) {
     return path.join(tumwaterDir(root), "state", "baseline-verdicts.json");
 }
+/** The quarantined flaky tests (review/known-flakes.ts): tests that failed and then passed on the
+ * same tree, newest 100, each with the BUGS.md entry filed for it. */
+export function quarantinePath(root) {
+    return path.join(tumwaterDir(root), "state", "quarantine.json");
+}
 /** 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 team to consume: like the
- * reset-counters marker it must name its targets because it can affect many loops, and like it
+ * reset-counters marker it must name its targets because it can affect many roles, 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. */
 export function wakeRequestPath(root) {
@@ -172,9 +231,9 @@ export function reclaimRequestPath(root) {
     return path.join(tumwaterDir(root), "reclaim.json");
 }
 /** 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
+ * kill that role's in-flight run. 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. */
+ * reset-counters marker, which must name its targets because it affects many roles. */
 export function abortRequestPath(root, role) {
     return path.join(tumwaterDir(root), `abort-${role}.json`);
 }
@@ -186,7 +245,7 @@ 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
+ * running team's watch consumes it when `until` passes; a fresh `tumwater start` clears a
  * stale one. */
 export function scheduledStopPath(root) {
     return path.join(tumwaterDir(root), "stop-at.json");
@@ -216,29 +275,29 @@ export const EVENTS_LOG_BASENAME = "events.jsonl";
 export function eventsLogPath(root) {
     return path.join(tumwaterDir(root), "log", EVENTS_LOG_BASENAME);
 }
-/** The event log's one archived generation (src/files/files.ts rotateIfLarge renames the grown log
- * to events.jsonl.1); the windowed readers continue into it when the live log ends inside the
- * window (event-window.ts). One archive, by design: the rotation note tells the truth about
- * coverage either way, and the archive path belongs beside eventsLogPath so the pair cannot
- * drift apart. */
-export function eventsArchivePath(root) {
-    return eventsLogPath(root) + ".1";
+/** An archived generation of the event log (src/files/files.ts rotateIfLarge renames the grown
+ * log to events.jsonl.1 and shifts older generations down, up to EVENTS_KEEP of them); the
+ * windowed readers continue into them when the live log ends inside the window (event-window.ts).
+ * `generation` defaults to 1, the newest archive. The path lives beside eventsLogPath so the
+ * pair cannot drift apart. */
+export function eventsArchivePath(root, generation = 1) {
+    return eventsLogPath(root) + "." + generation;
 }
 /** A role's raw pi transcript log (.tumwater/log/<role>.pi.jsonl); tailed by the GUI/TUI. */
 export function piLogPath(root, role) {
     return path.join(tumwaterDir(root), "log", `${role}.pi.jsonl`);
 }
-/** A role's backend-native stdout log (.tumwater/log/<role>.<agent>.native.jsonl), written
- * beside the canonical raw log and kept for debugging only: no reader folds it, and the agent
+/** A role's backend-native stdout log (.tumwater/log/<role>.<backend>.native.jsonl), written
+ * beside the canonical raw log and kept for debugging only: no reader folds it, and the backend
  * is in the name because one role's runs may switch backends and the two dialects must not
  * mix. Written and rotated like the raw log (src/agent/run-agent.ts). */
-export function nativeLogPath(root, role, agent) {
-    return path.join(tumwaterDir(root), "log", `${role}.${agent}.native.jsonl`);
+export function nativeLogPath(root, role, backend) {
+    return path.join(tumwaterDir(root), "log", `${role}.${backend}.native.jsonl`);
 }
 /** Root of the full-output files the bundled pi extension writes for oversized tool
  * results (.tumwater/log/tool-output/<toolCallId>.log). Pruned by the same sessionRetentionDays
  * window as sessions (orchestrator.ts's two retention passes): a pointer to a tool result is
- * only useful while its tick is recent, and the files otherwise accumulate without bound. */
+ * only useful while its run is recent, and the files otherwise accumulate without bound. */
 export function toolOutputDir(root) {
     return path.join(tumwaterDir(root), "log", "tool-output");
 }
@@ -246,7 +305,7 @@ export function toolOutputDir(root) {
 export function sessionsRootDir(root) {
     return path.join(tumwaterDir(root), "sessions");
 }
-/** A role's own pi session dir; hasResumableSession looks here for an interrupted tick to
+/** A role's own pi session dir; hasResumableSession looks here for an interrupted run to
  * resume. */
 export function sessionDir(root, role) {
     return path.join(sessionsRootDir(root), role);
@@ -259,14 +318,7 @@ export function sessionDir(root, role) {
 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())
+        if (isDirectory(path.join(dir, ".tumwater")))
             return dir;
         const parent = path.dirname(dir);
         if (parent === dir)
@@ -275,6 +327,17 @@ export function nearestTumwaterRoot(sessionDir) {
     }
     return undefined;
 }
+/** The team root of the workspace `dir` sits in — `dir` lies under `worktreesDir(root)` for the
+ * nearest `.tumwater` root — or undefined for a team root itself, a directory elsewhere under
+ * it, or a directory with no root above. A read-only lookup for messages, never used to decide
+ * where to write (same caution as teamRootOf). */
+export function owningTeamRoot(dir) {
+    const root = nearestTumwaterRoot(dir);
+    if (root === undefined)
+        return undefined;
+    const rel = path.relative(worktreesDir(root), dir);
+    return rel !== "" && !path.isAbsolute(rel) && !rel.startsWith("..") ? root : 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
@@ -291,7 +354,7 @@ export function teamRootOf(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
+ * run-marker's backendBaseEnv 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");
@@ -313,30 +376,30 @@ export function opencodeModelsPath(root) {
 }
 /** 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"
+ * AUTHOR's sessions — a leftover reviewer session would make an interrupted run "resume"
  * into a review context it never had. Old files are cleaned by the same age-based prune.
  */
 export function reviewSessionDir(root, role) {
     return path.join(sessionsRootDir(root), "_review", role);
 }
 /** The per-run child of a role's review session dir: one directory per review of one change,
- * keyed by the run's tick and pinned sha, so a follow-up turn — or a later attempt that
+ * keyed by the review run's number and pinned sha, so a follow-up turn — or a later attempt that
  * resumes this review — continues exactly that run's session rather than whichever review
  * wrote last into the shared parent. */
 export function reviewRunSessionDir(root, role, runKey) {
     return path.join(reviewSessionDir(root, role), runKey);
 }
-/** Queued human prompts awaiting pickup by a loop (inbox.ts). */
+/** Queued human prompts awaiting pickup by a role (inbox.ts). */
 export function inboxDir(root) {
     return path.join(tumwaterDir(root), "inbox");
 }
-/** The queue directory one loop's prompts wait in (inbox.ts): the director keeps its historical
- * queue at the inbox root so existing inboxes stay readable, and every other loop gets a
- * per-role subdirectory — `tumwater prompt --role <id>` writes where only that loop reads. */
+/** The queue directory one role's prompts wait in (inbox.ts): the director keeps its historical
+ * queue at the inbox root so existing inboxes stay readable, and every other role gets a
+ * per-role subdirectory — `tumwater prompt --role <id>` writes where only that role reads. */
 export function roleInboxDir(root, role) {
     return role === DIRECTOR_ROLE ? inboxDir(root) : path.join(inboxDir(root), role);
 }
-/** The durable merge queue (src/merge/merge-queue.ts): a changed tick's pinned commit waits here
+/** The durable merge queue (src/merge/merge-queue.ts): a changed run'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
@@ -349,6 +412,10 @@ export function mergeQueueDir(root) {
 export function legacyLandQueueDir(root) {
     return path.join(tumwaterDir(root), "land-queue"); // vocabulary-ok: legacy path read from old layouts
 }
+/** How long a merge-lock taker outside the merge queue waits for the lock: a merge holds it through
+ * its in-lock check, which can run several minutes. A dead holder is still broken early by
+ * `tryBreakStale`. */
+export const MERGE_LOCK_WAIT_MS = 15 * 60_000;
 /** 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");
@@ -376,7 +443,7 @@ 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 verifies lease and switch commits in place, instead of one `_land-<role>`
+ * checkout that runs 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}`);
@@ -402,7 +469,7 @@ export function slotsLockPath(root) {
     return path.join(tumwaterDir(root), "state", "slots.lock");
 }
 /** 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
+ * written right after the run's commit, before its branch resets to main, so the reset cannot
  * orphan the work. Deleted on every terminal merge outcome; kept until re-merged otherwise. */
 export function mergeRefName(role) {
     return `refs/tumwater/merge/${role}`;
@@ -414,7 +481,7 @@ 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,
+ * written at the gate's rejection, read by the author's next run to re-apply the rejected diff,
  * 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) {

package/dist/src/pi/command-shape.js

@@ -7,6 +7,7 @@
  * keeps a legitimately slow suite below it while a hang surfaces within one quiet window of
  * the default. Both stall surfaces (runPi's warning, the dashboard's flag) must apply the
  * same threshold or one cries wolf while the other stays silent. */
+import { streamsToolOutput } from "../agent/backend-traits.js";
 export function bufferedCommandStallMs(stallMs) {
     return Math.max(stallMs * 2, 10 * 60_000);
 }
@@ -14,7 +15,7 @@ export function bufferedCommandStallMs(stallMs) {
  * silence carries no hang signal and the stall warning would be a false alarm. Two shapes do
  * this: a pipe (`npm test 2>&1 | tail -8`) holds every byte in the pipeline until the upstream
  * command exits, and a stdout redirect (`npm test > /tmp/out`) sends the bytes to a file
- * instead of pi's pipe. Both are shapes the tick prompt itself prescribes for verification
+ * instead of pi's pipe. Both are shapes the run prompt itself prescribes for verification
  * runs, so the stall detector must not read their silence as a stall. A bare `2>&1` is NOT
  * such a shape: it points stderr at stdout's destination — pi's live pipe — so output still
  * streams and a hang stays detectable. `2>` and `2>>` likewise leave or append only stderr.
@@ -50,3 +51,13 @@ export function commandBuffersOutput(command) {
     }
     return false;
 }
+/** True when a tool call gives no silence signal, so it must be judged by the buffered
+ * wall-clock threshold instead: either the agent never streams tool output (claude and
+ * opencode, which send no content updates) or the command itself buffers its stdout
+ * (commandBuffersOutput). The two stall surfaces — pi-watchdogs.ts's runPi stall warning and
+ * progress-data.ts's in-flight stall flag — must agree on this or one surface cries wolf
+ * while the other stays silent (BUGS.md 2026-09-28); this composes streamsToolOutput with the
+ * command classifier so they cannot drift. */
+export function callBuffersOutput(agent, command) {
+    return !streamsToolOutput(agent) || commandBuffersOutput(command);
+}

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

@@ -1,4 +1,4 @@
-/** Building the pi command line for one tick — pure argv construction with no subprocess or
+/** Building the pi command line for one run — pure argv construction with no subprocess or
  * file I/O. Split out of pi.ts; the child-process integration (runPi) now lives in
  * src/agent/run-agent.ts and the run's result types in src/pi/pi-run-result.ts, while
  * test/pi-args.test.ts pins how config and session choices shape the command line. */
@@ -9,8 +9,9 @@ import { fileURLToPath } from "node:url";
  * 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, 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
+ * small-window chat-completions model, trim-system-prompt drops pi's docs section from the
+ * system prompt, and write-guard refuses an edit or write outside the run's worktree. 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 [
@@ -19,6 +20,7 @@ export function bundledExtensionPaths() {
         "context-budget.js",
         "strip-thinking.js",
         "trim-system-prompt.js",
+        "write-guard.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`.
@@ -29,7 +31,7 @@ export function bundledExtensionPaths() {
  * 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
+/** Build the pi argv for one run: the harness's own flags, the bundled extensions, then the
  * user's config.piArgs (so a user flag still wins). */
 export function piArgs(opts) {
     const { config } = opts;

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

@@ -4,11 +4,11 @@
  * stderr exit rules, and the model-fallback-clone warning — so src/agent/run-agent.ts stays
  * 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, withNotesPath } from "../process/run-marker.js";
+import { resolveBinForBackend } from "./pi-bin.js";
+import { backendBaseEnv, 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
+/** pi crashing on malformed JSON, as Node's JSON.parse phrases it on pi's stderr — five runs in
  * the first 18 days died this way (one of them 2 h 39 m of director work on a fresh steering
  * prompt), each traced to a torn chunk from the model server rather than to the session. Matched
  * against the child's stderr at exit; exported for tests. */
@@ -29,7 +29,7 @@ export const piBackend = {
     defaultBin: "pi",
     binEnv: "TUMWATER_PI_BIN",
     resolveBin(config) {
-        return resolveBackendBin(config, this);
+        return resolveBinForBackend(config, this);
     },
     invocation(run) {
         // The prompt rides on stdin, never argv: pi --print reads a piped stdin to EOF as the first
@@ -43,7 +43,7 @@ export const piBackend = {
             continueSession: run.continueSession,
             agentBin: run.agentBin,
         });
-        const env = withNotesPath(agentBaseEnv(run.runMarker, undefined, run.binDir), run.notesPath);
+        const env = withNotesPath(backendBaseEnv(run.runMarker, undefined, run.binDir), run.notesPath);
         return { args, stdin: run.prompt, env };
     },
     translator() {
@@ -63,7 +63,7 @@ export const piBackend = {
         if (info.killed)
             return {};
         // A nonzero exit whose stderr ends in a JSON.parse failure is pi dying on a torn server
-        // chunk: transient, retryable with --continue (the loop decides).
+        // chunk: transient, retryable with --continue (the runner decides).
         if (info.code !== 0 && TRANSIENT_PI_CRASH.test(info.stderr))
             return { transientPiCrash: true };
         // A provider-wide backend failure printed on pi's stderr (a severed stream, the provider's