tumwater 0.1.2 → 0.2.0

package/dist/src/agent/opencode/opencode-session-id.js

@@ -0,0 +1,37 @@
+// vocabulary: plain
+/** Minting an OpenCode session id (plans/opencode-backend.md "Sessions", finding 3) — a pure
+ * reproduction of OpenCode's `Identifier.descending()` (packages/schema/src/identifier.ts), so
+ * a fresh run's `--session` id is accepted by the free-tier gate. A `ses_…` id in any other
+ * shape is refused with a 403 (finding 3), so this must match OpenCode exactly.
+ *
+ * The id is `ses_` + 12 hex digits + 14 base-62 characters. The hex is the low 48 bits of the
+ * bitwise NOT of (Unix milliseconds × 4096 + a per-millisecond counter), big-endian; the 14
+ * characters are drawn from `0-9A-Za-z` one random byte each. */
+import crypto from "node:crypto";
+/** The 62-character alphabet OpenCode draws a session id's trailing characters from. */
+const ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+/** Per-process minting state, mirroring OpenCode's per-millisecond counter: the counter
+ * restarts at 1 for each new millisecond, and increments within the same millisecond so two
+ * ids minted in one tick still differ in their hex. */
+let lastMintMs = -1;
+let counter = 0;
+/** Mint an OpenCode session id. `now` is a Unix-millisecond epoch (injected for tests);
+ * `randomBytes` supplies the 14 base-62 characters (defaults to `crypto.randomBytes`, so the
+ * trailing part is random, never guessed from the visible prefix). */
+export function mintOpencodeSessionId(now = Date.now(), randomBytes = (n) => crypto.randomBytes(n)) {
+    if (now === lastMintMs)
+        counter += 1;
+    else {
+        lastMintMs = now;
+        counter = 1;
+    }
+    // `Identifier.descending()`: current = now × 4096 + counter, then the low 48 bits of ~current.
+    const current = BigInt(now) * 0x1000n + BigInt(counter);
+    const hex = ((~current) & 0xffffffffffffn).toString(16).padStart(12, "0");
+    const bytes = randomBytes(14);
+    let suffix = "";
+    for (let i = 0; i < 14; i += 1) {
+        suffix += ALPHABET[bytes[i] % 62];
+    }
+    return `ses_${hex}${suffix}`;
+}

package/dist/src/agent/opencode/opencode-stream.js

@@ -0,0 +1,278 @@
+/** The opencode adapter's native-to-canonical stream translator (plans/opencode-backend.md
+ * §6, "The stream translator"). `opencode run --format json` writes one JSON object per line
+ * whose vocabulary differs from pi's in every dimension the readers care about: each step is
+ * opened by `step_start` and closed by `step_finish` carrying the step's cost and tokens; a
+ * tool is reported as a `tool_use` event only ONCE it has completed or errored (never while
+ * it runs); and errors arrive as their own `{type: "error", error: {type, message,
+ * status?, response?}}` line rather than as prose in a message. Rather than teach ~fifteen
+ * readers a second dialect, every native line is translated here into pi's vocabulary — the
+ * canonical stream — so `PiStreamParser`, the
+ * raw log, the transcript, progress, and the GUI all stay unchanged.
+ *
+ * Pure translation: no spawn, no backend registration, no config. The factory keeps per-run
+ * state (the open step buffer, the queued tool calls, the unmapped native types seen, whether
+ * the run was refused by the free tier), so call it once per run. Unmapped native types and a
+ * malformed (non-JSON) line are recorded once each on the seam's optional `warnings()`, and
+ * `opencode_free_tier_refused` is added there once when any step was refused. `--thinking` is
+ * never passed, so no `reasoning` event appears; the mapping below still recognizes one so a
+ * future `--thinking` run degrades gracefully. */
+import { canonicalUsageBlock, isJsonObject, nonNegativeNumber, objectOrEmpty, parseJsonObject } from "../../files/json-object.js";
+/** opencode's tool names → the canonical pi names the readers already know. `shell`→`bash` and
+ * `patch`→`edit` (pi has one edit tool); anything else is lower-cased so a future tool still
+ * reads as a name rather than as `undefined`. */
+const TOOL_NAMES = {
+    shell: "bash",
+    patch: "edit",
+};
+/** A Retry-After hint spelled out in a rate-limit error's message text ("retry after 30s" /
+ * "retry in 30 seconds"). */
+const RETRY_AFTER = /retry (?:after|in) (\d+)\s*s(?:econds?)?\b/i;
+/** How an `error` line classifies into the canonical `tumwaterKind` (and, for a transient
+ * backend, its kind), trusted by `PiStreamParser` before its text regexes. The error's
+ * `type` — the provider signal the plan's table maps (provider.auth, provider.no-route,
+ * unknown) — is consulted FIRST, the message text second (plans/opencode-backend.md §8 and
+ * its classification table). */
+function classifyError(err) {
+    const message = typeof err.message === "string" ? err.message : "";
+    const type = typeof err.type === "string" ? err.type : "";
+    const status = err.status;
+    // The free tier refuses intermittently (a provider failure, not a config error): three
+    // refusals in a row move the tier to its fallback through the existing model-failure
+    // episode. Typed `provider.auth` WITH status 403 — the free tier's own refusal — or the
+    // text naming the free tier. A `provider.auth` with any other status (a 401 bad
+    // credential) is not a refusal and falls through to the config-error row below.
+    if ((type === "provider.auth" && status === 403) || /free\s?tier|FreeTierError/i.test(message))
+        return { kind: "transientBackend", backendKind: "server", freeTier: true };
+    // Rate limiting — 429 or rate-limit text — is the world saying "later", inherently
+    // retryable; carry the echoed Retry-After hint when the message spells it.
+    if (status === 429 || /\b429\b|rate limit|too many requests/i.test(message)) {
+        const retry = RETRY_AFTER.exec(message);
+        return { kind: "transientRateLimit", ...(retry ? { retryAfterSeconds: Number(retry[1]) } : {}) };
+    }
+    // An unknown model or variant, and the malformed `ses_` id, are permanent config errors
+    // (a misconfiguration, not a transient outage): typed `provider.no-route` / `unknown`, or
+    // the model-not-found / 401 text.
+    if (type === "provider.no-route" ||
+        type === "unknown" ||
+        status === 401 ||
+        /unknown model|unknown provider|model not found|provider not found|unauthorized|status\s*401|\b401\b/i.test(message))
+        return { kind: "configError" };
+    // Context overflow that compaction could not fix. Matched STRICTLY (the same shape pi's
+    // own CONTEXT_ERROR matches), so a message that merely mentions "context" or "too long"
+    // in passing — a plugin error, say — is never misread as an overflow that would then be
+    // trusted by PiStreamParser over its own tighter regex.
+    if (/context (size|length|window)?\s*(has been |was )?exceeded|exceeds? (the )?context|too (long|large) for .*context/i.test(message))
+        return { kind: "contextExceeded" };
+    // Transient server, connection and timeout failures.
+    if (/\b(500|501|502|503|504|529)\b|internal server error|bad gateway|service unavailable|gateway timeout|overloaded/i.test(message))
+        return { kind: "transientBackend", backendKind: "server" };
+    if (/connection|econn|refused|reset|terminated/i.test(message))
+        return { kind: "transientBackend", backendKind: "connection" };
+    if (/timed out|timeout/i.test(message))
+        return { kind: "transientBackend", backendKind: "timeout" };
+    return {};
+}
+/** The step's token counts and cost → pi's canonical usage block: the four counts, their sum
+ * as `totalTokens`, and `cost.total` = the step's USD cost (plans/opencode-backend.md §6).
+ * `totalTokens` feeds `peakContextTokens`; `cost.total` accumulates into `costUsd`. */
+function canonicalUsage(tokens, cost) {
+    const cache = objectOrEmpty(tokens.cache);
+    return canonicalUsageBlock(nonNegativeNumber(tokens.input, 0), nonNegativeNumber(cache.read, 0), nonNegativeNumber(cache.write, 0), nonNegativeNumber(tokens.output, 0), cost);
+}
+/** Build a fresh per-run opencode translator. */
+export function opencodeTranslator(opts = {}) {
+    /** True once the run's session has been announced (the first event with a non-empty
+     * `sessionID` emits `session` then `agent_start`, once). */
+    let sessionStarted = false;
+    /** The open step: its buffered content blocks and the tool calls reported so far. OpenCode
+     * reports each call only once it has ended, so the calls are queued and emitted AFTER their
+     * step's `message_end`, in order — the assistant message, then its tool executions, the
+     * order every reader of the raw log assumes. */
+    let step;
+    const seen = new Set();
+    const warnings = new Set();
+    let sawFreeTier = false;
+    const record = (kind) => {
+        if (seen.has(kind))
+            return;
+        seen.add(kind);
+        warnings.add(kind);
+    };
+    /** Emit the open step (if any) as ONE canonical `message_end` (role assistant) carrying
+     * its buffered blocks and, when `withUsage`, its usage; then one `tool_execution_start`
+     * followed by a `tool_execution_end` for each queued call in order. A cut-off step (stream
+     * ended or an error arrived before `step_finish`) flushes without usage. */
+    const flush = (withUsage) => {
+        const s = step;
+        if (!s)
+            return [];
+        step = undefined;
+        const message = { role: "assistant", content: s.content };
+        if (withUsage)
+            message.usage = s.usage;
+        const out = [JSON.stringify({ type: "message_end", message })];
+        for (const call of s.calls) {
+            out.push(JSON.stringify({ type: "tool_execution_start", toolCallId: call.id, toolName: call.name, args: call.args }));
+            out.push(JSON.stringify({ type: "tool_execution_end", toolCallId: call.id, isError: call.isError }));
+        }
+        return out;
+    };
+    const translate = (line) => {
+        const parsed = parseJsonObject(line);
+        if (!parsed) {
+            // A malformed / non-JSON line on stdout is skipped with one warning for the run.
+            record("malformed");
+            return [];
+        }
+        const event = parsed;
+        // The first event with a non-empty `sessionID` announces the session and the agent start.
+        // An error raised before a session exists has `sessionID: ""` (or none) and emits neither.
+        let out = [];
+        if (!sessionStarted) {
+            const sid = event.sessionID;
+            if (typeof sid === "string" && sid !== "") {
+                sessionStarted = true;
+                out.push(JSON.stringify({
+                    type: "session",
+                    id: sid,
+                    ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
+                }));
+                out.push(JSON.stringify({ type: "agent_start" }));
+            }
+        }
+        const type = event.type;
+        switch (type) {
+            case "step_start":
+                step = { content: [], calls: [] };
+                break;
+            case "text": {
+                // A content block with no open buffer opens one: `step_start` is sometimes missing, and
+                // edit-run.jsonl's final `text` lands after its last `step_finish`, so a block dropped
+                // for want of a buffer would lose the run's last turn.
+                step ??= { content: [], calls: [] };
+                step.content.push({ type: "text", text: objectOrEmpty(event.part).text ?? "" });
+                break;
+            }
+            case "reasoning": {
+                step ??= { content: [], calls: [] };
+                const thinking = objectOrEmpty(event.part).text ?? "";
+                step.content.push({ type: "thinking", thinking: typeof thinking === "string" ? thinking : "" });
+                break;
+            }
+            case "tool_use": {
+                // As above, a tool reported with no open buffer opens one.
+                step ??= { content: [], calls: [] };
+                const partValue = objectOrEmpty(event.part);
+                const state = objectOrEmpty(partValue.state);
+                const input = objectOrEmpty(state.input);
+                // `arguments` is the tool's `input` plus a `path` alias of `filePath` —
+                // describeToolCall reads either.
+                const args = { ...input };
+                if (typeof input.filePath === "string")
+                    args.path = input.filePath;
+                // V2 2.0.32 emits the native tool name in `part.tool` (not `part.name`); the live
+                // captures agree.
+                const name = typeof partValue.tool === "string" ? partValue.tool : "";
+                // Own-property test, not a bare index: a tool name like `constructor` or
+                // `__proto__` would otherwise inherit a function from the table's prototype chain and
+                // bypass the lower-cased fallback (the same guard claude-stream.ts applies).
+                const canonicalName = Object.hasOwn(TOOL_NAMES, name) ? (TOOL_NAMES[name] ?? name.toLowerCase()) : name.toLowerCase();
+                const id = typeof partValue.id === "string" ? partValue.id : "";
+                step.content.push({ type: "toolCall", id, name: canonicalName, arguments: args });
+                step.calls.push({ id, name: canonicalName, args, isError: state.status === "error" });
+                break;
+            }
+            case "step_finish": {
+                if (!step)
+                    break;
+                const part = objectOrEmpty(event.part);
+                const tokens = objectOrEmpty(part.tokens);
+                const cache = objectOrEmpty(tokens.cache);
+                step.usage = canonicalUsage({
+                    input: tokens.input,
+                    output: tokens.output,
+                    cache: { read: cache.read, write: cache.write },
+                }, nonNegativeNumber(part.cost, 0));
+                out.push(...flush(true));
+                break;
+            }
+            case "error": {
+                // Errors carry their payload in `event.error` (`{type, message, status?, response?}`,
+                // plan finding 8); classification reads type first, message second.
+                const err = objectOrEmpty(event.error);
+                const cls = classifyError(err);
+                if (cls.freeTier)
+                    sawFreeTier = true;
+                const message = typeof err.message === "string" ? err.message : "";
+                // The open step (if any) is cut off by the error and flushed without usage first.
+                out.push(...flush(false));
+                const m = { role: "assistant", content: [], stopReason: "error" };
+                if (message !== "")
+                    m.errorMessage = message;
+                // tumwaterKind/backendKind ride the canonical EVENT (not its message): the parser
+                // reads event.tumwaterKind and trusts it before its text regexes.
+                out.push(JSON.stringify({
+                    type: "message_end",
+                    message: m,
+                    ...(cls.kind !== undefined ? { tumwaterKind: cls.kind } : {}),
+                    ...(cls.backendKind !== undefined ? { backendKind: cls.backendKind } : {}),
+                    ...(cls.retryAfterSeconds !== undefined ? { retryAfterSeconds: cls.retryAfterSeconds } : {}),
+                }));
+                break;
+            }
+            default:
+                // Record the unknown type ("" for a type-less line), once, in first-seen order.
+                record(typeof type === "string" ? type : "unknown");
+                break;
+        }
+        return out;
+    };
+    return {
+        translate,
+        finalize() {
+            // The native stream ended with a step still open (a killed run, or a stream that just
+            // went idle): flush it as a message_end without usage so the last turn is not lost.
+            return flush(false);
+        },
+        noteOpencodeUsagePartial() {
+            warnings.add("opencode_usage_partial");
+        },
+        warnings() {
+            // The free-tier refusal is recorded lazily so a run reports it exactly once.
+            if (sawFreeTier)
+                warnings.add("opencode_free_tier_refused");
+            return [...warnings];
+        },
+    };
+}
+/** Turn an `opencode session export` object into the run's two authoritative canonical lines,
+ * `run_cost` and `run_usage`, read from the export's `info`. The live stream drops the final
+ * step's usage in most runs (finding 5), so the export — not the sum of the streamed steps — is
+ * the run's real cost and token totals. Anything malformed returns `[]`; part 5/7 logs
+ * `opencode_usage_partial` when this is empty. */
+export function opencodeExportLines(exportJson) {
+    if (typeof exportJson !== "object" || exportJson === null || Array.isArray(exportJson))
+        return [];
+    const info = exportJson.info;
+    if (typeof info !== "object" || info === null)
+        return [];
+    const cost = nonNegativeNumber(info.cost, undefined);
+    if (cost === undefined)
+        return [];
+    // `info.tokens` must itself be a JSON object: a missing, scalar, or array (torn) section
+    // returns [] — never a zeroed run_usage — so part 5/7's `opencode_usage_partial` trigger
+    // fires. isJsonObject rejects the array a bare `typeof === "object"` lets through.
+    const rawTokens = info.tokens;
+    if (!isJsonObject(rawTokens))
+        return [];
+    const tokens = rawTokens;
+    const input = nonNegativeNumber(tokens.input, 0);
+    const output = nonNegativeNumber(tokens.output, 0);
+    const cache = objectOrEmpty(tokens.cache);
+    const cacheRead = nonNegativeNumber(cache.read, 0);
+    const cacheWrite = nonNegativeNumber(cache.write, 0);
+    return [
+        JSON.stringify({ type: "run_cost", total: cost }),
+        JSON.stringify({ type: "run_usage", input, output, cacheRead, cacheWrite }),
+    ];
+}

package/dist/src/agent/role-notes-write.js

@@ -1,34 +1,18 @@
+// vocabulary: plain
 /**
- * The one write path for a role's notebook, shared by the two agent-facing surfaces: the
- * bundled pi extension (src/pi-extension/role-notes.ts) and claude's stdio MCP server
- * (src/agent/mcp/role-notes-server.ts, plans/agent-backends.md "What the pi extensions did,
- * per backend"). Kept backend-neutral — no pi or claude types — so both registers can quote
- * the SAME 4 KB cap, the SAME parameter schema, and the SAME validate-then-atomic-write
- * execution, and cannot drift on what a valid note is or what a rejected call does.
+ * The one write path for a role's notebook, shared by every surface that touches it: the
+ * `tumwater-notes` command (src/notes-cli.ts), `tumwater role --notes-file` /
+ * `--clear-notes` (cli-query-commands.ts), the dashboard drawer (gui-operator-commands.ts)
+ * and the TUI editors (tui-editor-notes.ts, tui-pane-transcript.ts). Kept backend-neutral —
+ * no pi, claude or opencode types — so every surface quotes the SAME 4 KB cap, the SAME
+ * validation, and the SAME validate-then-atomic-write execution, and cannot drift on what
+ * a valid note is or what a rejected write does.
  */
 import { writeTextAtomic } from "../files/files.js";
 import { gotSuffix } from "../text/text.js";
 /** The cap on a role's note, in UTF-8 bytes. Small enough to cost little on every turn, large
  * enough for the codebase facts a role wants to keep. */
 export const ROLE_NOTES_MAX_BYTES = 4096;
-/** The tool's parameter schema (plain JSON Schema), shared by the pi extension and the MCP
- * server so both declare the same `{ text }` contract. */
-export const ROLE_NOTES_PARAMETERS = {
-    type: "object",
-    properties: {
-        text: {
-            type: "string",
-            description: `The full replacement note, at most ${ROLE_NOTES_MAX_BYTES} bytes. Empty text clears it.`,
-        },
-    },
-    required: ["text"],
-    additionalProperties: false,
-};
-/** The human-facing description both surfaces carry: what the note is for, its cap, and the
- * replacement/clear semantics. */
-export const ROLE_NOTES_DESCRIPTION = `Replace this role's notebook: the short note the role's own earlier ticks left for the ` +
-    `next tick (where things live, what was ruled out, what to look at next; at most ` +
-    `${ROLE_NOTES_MAX_BYTES} bytes). Pass the full replacement text; empty text clears it.`;
 /** Validate note text against the byte cap. Returns null when the text is acceptable, or an
  * error naming the byte count and the fix — the same "shorten it to at most" wording
  * text/text.ts's tooLongMessage gives every other bounded text, so the model that overran
@@ -47,19 +31,19 @@ export function validateRoleNote(text) {
 export function writeRoleNote(notesPath, text) {
     writeTextAtomic(notesPath, text);
 }
-/** Validate and write one `role_notes` call's text, returning the surface's success message.
- * `text` is `unknown` because neither pi nor MCP guarantees the model honored the parameter
- * schema: coercing a malformed `text` to "" cleared the notebook, the destructive reading of
- * a typo the model never sees, so a bad call throws instead and the caller renders it as a
- * tool error. Shared so the two surfaces reject the same inputs with the same wording and the
- * same no-write-on-failure behavior. */
+/** Validate and write one note's text, returning the success message surfaces show. `text` is
+ * `unknown` because a caller may hand it a malformed value (a malformed heredoc, a stray
+ * argument) without having enforced the string contract: coercing a malformed `text` to ""
+ * would clear the notebook, the destructive reading of a typo the writer never sees, so a bad
+ * value throws instead and the caller renders it as an error. Shared so every surface
+ * rejects the same inputs with the same wording and the same no-write-on-failure behavior. */
 export function saveRoleNote(notesPath, text) {
     if (typeof text !== "string") {
-        throw new Error(`role_notes requires a string "text"${text === undefined ? "" : gotSuffix(text)} — pass the full replacement note, or "" to clear it`);
+        throw new Error(`a note must be a string, not ${typeof text}${text === undefined ? "" : gotSuffix(text)} — pass the full replacement note, or "" to clear it`);
     }
     const error = validateRoleNote(text);
     if (error)
         throw new Error(error);
     writeRoleNote(notesPath, text);
-    return text === "" ? "notebook cleared" : `notebook saved (${Buffer.byteLength(text, "utf8")} bytes)`;
+    return text === "" ? "notes cleared" : `notes saved (${Buffer.byteLength(text, "utf8")} bytes)`;
 }

package/dist/src/agent/run-agent.js

@@ -1,3 +1,4 @@
+// vocabulary: plain
 /** The backend-neutral agent runner (plans/agent-backends.md \"The seam\"): everything a run
  * needs regardless of which agent it drives — the spawn, the `tumwater_run` raw-log marker,
  * the watchdog wiring, abort, the group kill and marker sweep, stderr capture, and result
@@ -20,6 +21,11 @@ import { DEFAULT_AGENT, agentBackend, registerAgentBackend } from "./agent-backe
 import { recordSession } from "./session-ledger.js";
 import { piBackend } from "../pi/pi-backend.js";
 import { claudeBackend } from "./claude/claude-backend.js";
+import { opencodeBackend } from "./opencode/opencode-backend.js";
+import { seamImageInput } from "./image-input.js";
+import { ensureNotesShim } from "./notes-shim.js";
+import { nearestTumwaterRoot } from "../paths.js";
+import { piModelsPath, readPiProviders } from "../pi/pi-models.js";
 /** How many trailing stderr characters are carried into the next chunk's warning match, so a
  * warning split across two `data` events is still seen. The warnings are short lines, so a few
  * hundred characters always cover a straddle. */
@@ -35,6 +41,7 @@ export const MAX_NATIVE_LINE_CHARS = 16 * 1024 * 1024;
 // explicit and lets a test register a fake under its own id.
 registerAgentBackend(piBackend);
 registerAgentBackend(claudeBackend);
+registerAgentBackend(opencodeBackend);
 /** Prefix of PiRunResult.errorMessage when the agent process never started (no session file
  * is created for such a run). The resolved binary follows it, so a configured agentBin
  * reads "failed to spawn <bin>" rather than blaming an ambient "pi". */
@@ -42,7 +49,7 @@ const SPAWN_ERROR_PREFIX = "failed to spawn";
 /** The spawn-error message for a resolved binary: the default source keeps today's text
  * ("failed to spawn pi: …"); a configured source names the binary and where it came from —
  * the backend's own env var and config key (agentBinConfigKey) — so a wrong
- * `agents.claude.bin` does not read as pi's legacy `agentBin`. */
+ * `backends.claude.bin` does not read as pi's legacy `agentBin`. */
 function spawnErrorMessage(resolved, errMessage, backend) {
     const source = resolved.source === "default"
         ? ""
@@ -88,12 +95,52 @@ export function runAgent(opts) {
                 marker.label = opts.label;
             rawLog.stream.write(JSON.stringify(marker) + "\n");
         }
-        const parser = new PiStreamParser(opts.onToolCallStart);
+        // The first blind image read an authoring run made (plans/image-input.md "Detecting a
+        // blind read"): the path, plus an indirection to the child so the parser's parse-time
+        // callback (which fires during feed, after spawn) can kill it. Unset for a gate run,
+        // which only records the read. Declared before the parser so its onBlindRead closure
+        // (which assigns them at parse time, after spawn) can reference them.
+        let blindRead;
+        let terminateRun;
+        const parser = new PiStreamParser(opts.onToolCallStart, {
+            // The seam's effective image input (src/agent/image-input.ts): a text-only seam makes
+            // every image read blind even when pi adds no note — a claim its doctor probe proved
+            // false — which the parser checks against its own note rule.
+            imageInput: seamImageInput(opts.config, readPiProviders(piModelsPath())),
+            onBlindRead: (path) => {
+                // Kill an authoring run at once, before the agent goes on working from a picture it
+                // never saw (terminateChild is what the watchdogs use). Gate runs (reviewer,
+                // resolver) only record the read and keep going.
+                if (opts.kind === "author") {
+                    blindRead = path;
+                    terminateRun?.();
+                }
+            },
+        });
         // The run's cross-group attribution mark, minted before the spawn so the environment can
         // carry it and the exit sweep can name it.
         const runMarker = makeRunMarker();
         const resolved = backend.resolveBin(opts.config);
-        const invocation = backend.invocation({
+        // Install the notes shim under the team root's `.tumwater/bin` so every backend's run finds
+        // `tumwater-notes` first on PATH (notes-shim.ts). A failure to write it logs one warning and
+        // the run goes on without it — notes would then be unwritable by the command, but the run
+        // itself is not blocked.
+        let binDir;
+        try {
+            // Install the shim only under a real team root — the nearest ancestor holding a
+            // `.tumwater`. A session dir with no such ancestor (a lab script, a smoke run, a
+            // prompt-lab replay) must never mint one: nearestTumwaterRoot is undefined then, and the
+            // run goes on without the shim, exactly as if the install had failed — writing
+            // `<fallback>/.tumwater` from a run created a phantom harness root in a shared directory
+            // and broke every other suite on the host (BUGS.md 2026-10-18).
+            const root = nearestTumwaterRoot(opts.sessionDir);
+            if (root !== undefined)
+                binDir = ensureNotesShim(root);
+        }
+        catch {
+            opts.onAgentWarning?.("could not install the tumwater-notes shim; this run will not find tumwater-notes on PATH");
+        }
+        const runSpec = {
             cwd: opts.cwd,
             prompt: opts.prompt,
             config: opts.config,
@@ -104,8 +151,10 @@ export function runAgent(opts) {
             agentBin: resolved.bin,
             runMarker,
             notesPath: opts.notesPath,
+            ...(binDir !== undefined ? { binDir } : {}),
             ...(opts.maxBudgetUsd !== undefined ? { maxBudgetUsd: opts.maxBudgetUsd } : {}),
-        });
+        };
+        const invocation = backend.invocation(runSpec);
         // Record the run in the session ledger before its spawn, so a later resume can pick the
         // newest session of its own kind instead of whatever file is newest in the dir. The id is
         // the backend's own when it mints one ahead of the run (claude's UUID, or the resumed
@@ -147,8 +196,8 @@ export function runAgent(opts) {
         const runTmp = fs.mkdtempSync(path.join(os.tmpdir(), "tumwater-run-"));
         const child = spawn(resolved.bin, invocation.args, {
             cwd: opts.cwd,
-            // The prompt-argv backends (pi) deliver no stdin and keep stdio[0] "ignore"; a backend
-            // that feeds the prompt on stdin gets a pipe the runner writes and ends below.
+            // A backend that feeds the prompt on stdin (every registered one) gets a pipe the runner
+            // writes and ends below; one that returns no stdin keeps stdio[0] "ignore".
             stdio: [invocation.stdin !== undefined ? "pipe" : "ignore", "pipe", "pipe"],
             // pi sets its process title at startup, and so does every npm its tool calls run: on
             // macOS each would register with LaunchServices and leak a launchservicesd port.
@@ -168,20 +217,23 @@ export function runAgent(opts) {
             // an unknown flag, an unresumable session, or a not-logged-in exit — leaves this write
             // nothing to feed. Once the prompt exceeds the OS pipe buffer the write then fails EPIPE,
             // and an unhandled 'error' event on the stdin stream is thrown from the event loop and
-            // takes the whole process (the whole fleet) down. The child's own exit status and stderr
+            // takes the whole process (the whole team) down. The child's own exit status and stderr
             // already report why the run died, so swallowing the failed write adds no silence the
             // caller needs to break; git.ts's patchId carries the same guard for a patch-id that
             // dies before reading its input.
             child.stdin?.on("error", () => { });
             child.stdin?.end(invocation.stdin);
         }
+        // Armed now that the child exists, so the parser's parse-time onBlindRead (fires during
+        // feed, always after spawn) can reach it.
+        terminateRun = () => terminateChild(child);
         // The run's two watchdog clocks (src/pi/pi-watchdogs.ts): the tick deadline and the quiet
         // watchdog (quiet-kill plus the stalled-tool-call warning). The flags their timers set
         // (timedOut/timedOutProgressing/quietKilled/sawOutput) read live off the returned handle.
         const wd = startPiWatchdogs({
             progressCount: () => parser.progressCount,
             openToolCalls: () => parser.openToolCalls,
-            tickTimeoutMs: opts.config.tickTimeoutSeconds * 1000,
+            tickTimeoutMs: opts.config.runTimeoutSeconds * 1000,
             quietMs: opts.config.quietTimeoutSeconds * 1000,
             stallMs: Math.max(0, opts.config.toolCallStallSeconds) * 1000,
             // The run's backend id: claude never sends content updates, so the watchdog judges its
@@ -272,6 +324,13 @@ export function runAgent(opts) {
             if (settled)
                 return;
             settled = true;
+            // A blind image read (plans/image-input.md "Detecting a blind read"): surface it to the
+            // caller once, at settle, with the action its kind earned — the authoring run was killed
+            // ("fail"), a gate run only recorded it ("logged"). The caller logs the image_blind event
+            // with its own loop/tick context.
+            if (parser.imageBlind) {
+                opts.onBlindRead?.(parser.imageBlind.path, opts.kind === "author" ? "fail" : "logged");
+            }
             // Best-effort: an unremovable scratch dir (read-only subdir, a straggler still writing) must
             // not throw out of the close handler before the run's result resolves.
             try {
@@ -395,7 +454,19 @@ export function runAgent(opts) {
             feedCanonical(decoder.end(), true);
             for (const canonical of translator.finalize?.() ?? [])
                 parser.feed(canonical + "\n", onLine);
-            const killed = aborted || wd.timedOut || wd.quietKilled;
+            // A blind image read on an authoring run deliberately killed it (terminateRun above),
+            // so its exit is a kill like the watchdogs' — the half-done work is discarded.
+            const killed = aborted || wd.timedOut || wd.quietKilled || blindRead !== undefined;
+            // The backend's post-run reconciliation (opencode's authoritative session export), only
+            // when the run is not already settled (a failed spawn settles in the 'error' handler
+            // before 'close') and was not killed — a killed run's session is half-done and no export
+            // should spend its 10 s on it. Its lines are written and parsed like streamed ones, so
+            // they reach the raw log and the parser's authoritative fold (run_cost/run_usage).
+            if (!settled && !killed) {
+                for (const canonical of backend.afterRun?.(runSpec, invocation, translator) ?? []) {
+                    parser.feed(canonical + "\n", onLine);
+                }
+            }
             const failed = killed ||
                 parser.stopReason === "error" ||
                 (code !== 0 && !parser.finalText.trim());
@@ -408,21 +479,25 @@ export function runAgent(opts) {
                 cls.transientPiCrash !== true &&
                 stderrBackend === undefined &&
                 (parser.configError || cls.configError === true);
+            // The blind-read failure names both the file and the model (plans/image-input.md
+            // "Failing the tick"): take it over any generic exit text so lastError is actionable.
+            const errorMessage = blindRead !== undefined
+                ? `read ${blindRead}, but ${opts.config.model ?? "the model"} cannot read images`
+                : aborted
+                    ? "stopped by tumwater shutdown"
+                    : wd.quietKilled
+                        ? `killed as hung: no agent progress for over ${opts.config.quietTimeoutSeconds}s`
+                        : wd.timedOut
+                            ? wd.timedOutProgressing
+                                ? `timed out after ${wd.timeoutBudgetMs / 1000}s while still making progress — session and worktree edits preserved for resume`
+                                : `timed out after ${wd.timeoutBudgetMs / 1000}s`
+                            : (parser.errorMessage ?? (failed ? stderr.trim().slice(-500) || `the agent exited ${code}` : undefined));
             finish(resultFromParser({
                 ok: !failed,
                 transientPiCrash: cls.transientPiCrash === true,
                 transientBackend: parser.transientBackend || cls.transientBackend === true,
                 backendKind: parser.backendFailureKind ?? stderrBackend,
                 configError,
-                errorMessage: aborted
-                    ? "aborted by harness shutdown"
-                    : wd.quietKilled
-                        ? `killed as hung: no pi progress for over ${opts.config.quietTimeoutSeconds}s`
-                        : wd.timedOut
-                            ? wd.timedOutProgressing
-                                ? `timed out after ${wd.timeoutBudgetMs / 1000}s while still making progress — session and worktree edits preserved for resume`
-                                : `timed out after ${wd.timeoutBudgetMs / 1000}s`
-                            : (parser.errorMessage ?? (failed ? stderr.trim().slice(-500) || `pi exited ${code}` : undefined)),
                 // Kept distinct on purpose: a hung tool call leaves its session and worktree edits
                 // intact, so the loop resumes them (quiet_killed) instead of discarding them as an
                 // unfulfilled timeout does. A deadline that fired on a run still making progress
@@ -430,6 +505,8 @@ export function runAgent(opts) {
                 timedOut: wd.timedOut,
                 timedOutProgressing: wd.timedOut && wd.timedOutProgressing,
                 quietKilled: wd.quietKilled,
+                imageBlind: parser.imageBlind,
+                errorMessage,
             }));
         });
     });