teapot-coding-agent 0.37.59 → 0.37.61

package/dist/agent/tools.js

@@ -1,7 +1,3 @@
-/**
- * Tool execution: file ops, shell (with process-group kill + timeout), git.
- * Tool specs are plain JSON-schema function definitions — provider-agnostic.
- */
 import { spawn } from "node:child_process";
 import { existsSync, promises as fs, mkdirSync, readFileSync, readlinkSync, realpathSync, writeFileSync } from "node:fs";
 import path from "node:path";
@@ -20,16 +16,6 @@ function clip(s, max) {
 async function readText(p) {
     return fs.readFile(p, "utf8");
 }
-/**
- * Is this file binary, i.e. not something `read_file` should return as text?
- *
- * `readText` decodes with "utf8" unconditionally, so pointing `read_file` at an image returned the
- * raw bytes as a lossy string — reported as "画像をread_fileしてバイナリが帰ってきてる". The model then
- * spends tokens on unreadable mojibake and cannot tell it is looking at data rather than source.
- *
- * The test is the classic one, applied to the FIRST block only: a NUL byte means "not text". Reads
- * are bounded, because deciding costs a file read and the answer never needs the whole file.
- */
 export async function looksBinary(p) {
     const fh = await fs.open(p, "r");
     try {
@@ -37,14 +23,6 @@ export async function looksBinary(p) {
         const head = Buffer.alloc(Math.min(4096, Math.max(0, st.size)));
         if (head.length)
             await fh.read(head, 0, head.length, 0);
-        /**
-         * MAGIC BYTES FIRST, then the NUL test.
-         *
-         * A NUL scan alone missed PDF and zip: their headers contain no zero byte in the first few
-         * bytes, so `%PDF-1.4` and `PK\x03\x04` both read as "text" — MEASURED, and it would have
-         * shipped a silent hole. A known signature is proof regardless of what the bytes happen to
-         * contain; the NUL test is the fallback for everything unrecognised.
-         */
         const kind = sniff(head);
         if (kind)
             return { binary: true, bytes: st.size, kind };
@@ -54,7 +32,6 @@ export async function looksBinary(p) {
         await fh.close();
     }
 }
-/** the guessed format from magic bytes, or null when nothing is recognised */
 function sniff(head) {
     const hex = (n) => head.subarray(0, n).toString("hex");
     if (hex(8).startsWith("89504e47"))
@@ -75,13 +52,6 @@ function sniff(head) {
         return "RTF document";
     return null;
 }
-/**
- * Persist a `write_file` payload and report what line endings it used (#84/#109).
- *
- * Extracted so the two paths — a file whose own EOL was detected, and one decided
- * by `.editorconfig` — share one write. The message names CRLF/CR only when a
- * conversion actually happened, so an ordinary LF write stays quiet.
- */
 async function finishWrite(p, out, eol, original) {
     await fs.writeFile(p, out, "utf8");
     const converted = eol !== null && eol !== "\n" && out !== original;
@@ -91,20 +61,13 @@ async function finishWrite(p, out, eol, original) {
             (converted ? ` (kept ${eol === "\r\n" ? "CRLF" : "CR"} line endings)` : ""),
     };
 }
-/**
- * The file's dominant line ending, or null when it is mixed or empty.
- *
- * `null` means "do not normalise" — see the note above.
- */
 export function detectEol(text) {
     if (!text)
         return null;
     const crlf = (text.match(/\r\n/g) ?? []).length;
-    // a bare CR is a CR not followed by LF
     const cr = (text.match(/\r(?!\n)/g) ?? []).length;
     const lf = (text.match(/(?<!\r)\n/g) ?? []).length;
     const kinds = [crlf, cr, lf].filter((n) => n > 0).length;
-    // one kind only -> unambiguous. Mixed -> null.
     if (kinds !== 1)
         return null;
     if (crlf > 0)
@@ -113,71 +76,22 @@ export function detectEol(text) {
         return "\r";
     return "\n";
 }
-/** Split on ANY of the three line endings, dropping the terminators. */
 export function splitEolLines(text) {
     return text.split(/\r\n|\r|\n/);
 }
-/**
- * Re-apply `eol` to content the model supplied.
- *
- * Models emit `\n` essentially always, so a CRLF or CR file rewritten with LF
- * content would otherwise be silently converted. Untouched terminators already
- * in the right form are left alone, so this is safe to run on merged content.
- */
 export function applyEol(content, eol) {
     if (!eol || eol === "\n")
         return content;
-    // normalise to \n first, then re-apply — avoids double-CR on "\r\n"
     return content.replace(/\r\n|\r|\n/g, eol);
 }
-/**
- * Optimistic-concurrency guard. The model reads a file, thinks, then
- * writes — and in between, a sub-agent, a background job or the operator may
- * have changed it. Anchored edits usually fail safe (old_text is gone, so the
- * call errors), but two paths silently clobber work nobody looked at:
- * `replace_all` rewrites every occurrence present NOW, including ones that
- * appeared after the model formed its plan, and write_file/apply_patch replace
- * whole files unconditionally.
- *
- * A caller that passes `base_content` (the bytes it actually read) therefore
- * gets a refusal instead of a lost update — the same contract the web file
- * editor already enforces (see api.ts PUT /file). The check is advisory by
- * design: omitting the parameter keeps today's behaviour, so this can never
- * break a working agent loop that does not use it.
- */
 function staleGuard(pathArg, base, current) {
     if (typeof base !== "string")
-        return null; // not supplied → no check
-    /**
-     * A base_content that cannot BE the file is not evidence of a change.
-     *
-     * MEASURED in tyb2-9-8155867c: four `edit_file` calls, two of which passed `base_content: "x"` —
-     * a single byte — and were refused with "changed on disk since you read it … your base_content: 1
-     * bytes, on disk now: 52351 bytes". The guard was right that the bytes differ and useless about
-     * it: nothing in the file's history can make "x" the content of a 52KB script, so the message sent
-     * the model to re-read a file it had never successfully checked against.
-     *
-     * A guard whose input cannot be the thing it guards is noise. Below a plausible-file floor the
-     * value is treated as not supplied — the edit still has to pass the anchor checks, which is where
-     * a stale read is actually caught.
-     */
-    /**
-     * A base_content that is a tiny FRACTION of the file cannot be its content.
-     *
-     * MEASURED in tyb2-9-8155867c: two of four `edit_file` calls passed `base_content: "x"` — one
-     * byte — and were refused with "changed on disk since you read it … your base_content: 1 bytes, on
-     * disk now: 52351 bytes". The guard was right that the bytes differ and useless about it: nothing
-     * can make "x" the content of a 52KB script, so the message sent the model to re-read a file whose
-     * state was never in question.
-     *
-     * The test is "unmistakably not this file", NOT "short": a legitimately small file edited by a
-     * model that re-read it must keep the guard, which is what the two #5 tests would have lost.
-     */
+        return null;
     const MIN_PLAUSIBLE_BASE = 16;
     if (base.length < MIN_PLAUSIBLE_BASE && current !== null && current.length >= MIN_PLAUSIBLE_BASE * 4)
         return null;
     if (base === current)
-        return null; // unchanged → proceed
+        return null;
     const rel = pathArg;
     return {
         ok: false,
@@ -186,39 +100,15 @@ function staleGuard(pathArg, base, current) {
             `Re-read ${rel}, redo the edit against the current content, and pass the fresh text as base_content.`,
     };
 }
-/** Read the file for a guarded write, or null when it does not exist. */
 async function currentOrNull(p) {
     return fs.readFile(p, "utf8").catch(() => null);
 }
-/** Resolve a path inside the workspace; reject escapes (incl. symlink targets).
- *  KNOWN LIMIT (review finding, accepted): the check-then-open pattern has a
- *  TOCTOU window — a symlink swapped in between safeJoin() and fs.open() could
- *  point outside the workspace. Closing it needs openat(2)/O_NOFOLLOW at every
- *  call site; the operator-facing risk is low (requires workspace write access
- *  already), so we document rather than rewrite all call sites. */
 export function safeJoin(cwd, p) {
     const abs = path.resolve(cwd, p);
     const rel = path.relative(cwd, abs);
     if (rel.startsWith("..") || path.isAbsolute(rel)) {
         throw new Error(`path escapes workspace: ${p}`);
     }
-    // symlinks inside the workspace can point anywhere — resolve the real target
-    // and confine THAT too (path.resolve alone doesn't follow links)
-    //
-    // the old code resolved `abs` and swallowed a throw, treating failure as
-    // "fine". That is exactly backwards, and the failure is the NORMAL case:
-    // `realpathSync` throws ENOENT for a file that does not exist yet, which is
-    // every write_file creating something new. So `real` stayed as the LEXICAL
-    // path — which is inside the workspace — and the symlink guard never ran.
-    //
-    // Demonstrated: with `esc -> /outside` (a real directory), safeJoin allowed
-    // `esc/pwned.txt` and write_file wrote straight through it, landing outside
-    // the workspace. The dangling case happened to fail later with ENOTDIR, which
-    // is luck, not a control.
-    //
-    // So on ENOENT/ENOTDIR, resolve the nearest EXISTING ancestor instead of
-    // giving up. That still catches the escape — the ancestor IS the symlink —
-    // while allowing genuinely new files inside the workspace.
     let real = abs;
     try {
         real = realpathSync(abs);
@@ -226,11 +116,6 @@ export function safeJoin(cwd, p) {
     catch (err) {
         const code = err.code;
         if (code === "ENOENT" || code === "ENOTDIR") {
-            // Walk up one component at a time. A component that is itself a SYMLINK
-            // must be resolved even when its target does not exist — realpathSync
-            // throws ENOENT for the dangling link itself, so naively walking to the
-            // first existing ancestor steps OVER the symlink and loses it. So read
-            // the link and check its target directly.
             let probe = path.dirname(abs);
             for (;;) {
                 try {
@@ -240,22 +125,19 @@ export function safeJoin(cwd, p) {
                 catch (inner) {
                     if (inner.code !== "ENOENT")
                         break;
-                    // this component is a dangling symlink: resolve where it POINTS
                     try {
                         const target = readlinkSync(probe);
                         real = path.isAbsolute(target) ? target : path.resolve(path.dirname(probe), target);
                         break;
                     }
                     catch {
-                        /* not a symlink after all — keep walking */
                     }
                     const next = path.dirname(probe);
                     if (next === probe)
-                        break; // reached the filesystem root
+                        break;
                     probe = next;
                 }
             }
-            // keep the un-resolved tail so the comparison below sees the full path
             const tail = path.relative(probe, abs);
             if (tail && !tail.startsWith(".."))
                 real = path.join(real, tail);
@@ -267,10 +149,8 @@ export function safeJoin(cwd, p) {
     }
     return abs;
 }
-/** per-workspace background shells (key: workspace path) */
 const bgShellsByWs = new Map();
 let bgSeq = 0;
-/** how much of each job's output has already been handed to the model */
 const bgReadCursors = new Map();
 function bgMapFor(cwd) {
     let m = bgShellsByWs.get(cwd);
@@ -280,32 +160,10 @@ function bgMapFor(cwd) {
     }
     return m;
 }
-/**
- * Environment for every shell the agent runs.
- *
- * `PWD` is deliberately removed: the server's own PWD would contradict the
- * `cwd` we spawn with, so a command trusting `$PWD` would act on the wrong
- * directory. `bash` re-creates PWD from its actual cwd.
- */
 function shellEnv() {
     const { PWD: _pwd, ...rest } = process.env;
     return { ...rest, TERM: "dumb", GIT_PAGER: "cat", PAGER: "cat" };
 }
-/**
- * The shell to run a `bash` tool command in, per platform.
- *
- * Both call sites used to hardcode `/bin/bash`, so on Windows every `bash` tool invocation
- * failed with ENOENT — the tool was entirely unavailable on a platform this package claims to
- * support. Windows has no `/bin/bash`; `cmd.exe` is always present, and Git for Windows (which
- * the CI runner has) provides `bash.exe` on PATH.
- *
- * Preference order on Windows: `%TEAPOT_SHELL%`, then `bash.exe` if it is on PATH, then
- * `cmd.exe`. `bash.exe` first because teapot's tool prompts and most commands the model writes
- * are POSIX (`&&`, `$VAR`, single quotes); a `cmd.exe` fallback keeps the tool working on a bare
- * install rather than failing outright.
- *
- * POSIX is unchanged: `$SHELL`, else `/bin/bash`.
- */
 export function toolShellFor(platform, env, exists = existsSync) {
     const override = env.TEAPOT_SHELL?.trim();
     if (override)
@@ -323,23 +181,13 @@ export function toolShellFor(platform, env, exists = existsSync) {
         return { file: "bash", args: (cmd) => ["-c", cmd] };
     return { file: env.COMSPEC || "cmd.exe", args: (cmd) => ["/d", "/s", "/c", cmd] };
 }
-/** the shell for THIS process — see `toolShellFor` for the rules and why they exist */
 function toolShell() {
     return toolShellFor(process.platform, process.env);
 }
-/**
- * Human-readable elapsed-time suffix appended to a shell result so the MODEL
- * sees how long a command actually took. Only the operator saw it — the
- * model happily re-issued commands that ran for tens of minutes.
- *
- * Kept terse and single-line: it rides along with the tool output, and mirrors
- * what bash_output already prints for a still-running job.
- */
 export function elapsed(t0, now = Date.now()) {
     return `\n[took ${((now - t0) / 1000).toFixed(1)}s]`;
 }
 const jobsFile = (dir) => path.join(dir, "bg-jobs.json");
-/** read the persisted records, tolerating a missing or corrupt file (never throws) */
 function readJobRecords(dir) {
     try {
         const raw = readFileSync(jobsFile(dir), "utf8");
@@ -350,39 +198,22 @@ function readJobRecords(dir) {
         return [];
     }
 }
-/**
- * Write the records atomically enough for this purpose.
- *
- * A torn write here is not worth a fsync: the file is a hint for the NEXT boot, and the worst case is
- * losing one restart's worth of "this was running". Losing a job's identity entirely (the shipped
- * behaviour) is what this exists to stop.
- */
 function writeJobRecords(dir, records) {
     try {
         mkdirSync(dir, { recursive: true });
         writeFileSync(jobsFile(dir), JSON.stringify(records, null, 1));
     }
     catch {
-        /* a read-only session dir must not break the tool */
     }
 }
-/** add or update one record (by id) */
 function rememberJob(dir, rec) {
     const all = readJobRecords(dir).filter((r) => r.id !== rec.id);
     all.push(rec);
     writeJobRecords(dir, all);
 }
-/** drop a record — the job finished AND was reported, or was killed */
 function forgetJob(dir, id) {
     writeJobRecords(dir, readJobRecords(dir).filter((r) => r.id !== id));
 }
-/**
- * Jobs a PREVIOUS process started and whose processes may still be alive.
- *
- * `alive` is answered by the caller (pidExists) rather than here, so this module stays free of the
- * signal-plumbing and the test can drive either answer. A record whose pid is gone is stale and is
- * dropped: reporting a finished job as running is the same class of lie as forgetting a live one.
- */
 export function recoverableJobs(dir, alive) {
     const all = readJobRecords(dir);
     const live = [];
@@ -396,14 +227,11 @@ export function recoverableJobs(dir, alive) {
 }
 function startBackgroundShell(cmd, ctx) {
     const map = bgMapFor(ctx.cwd);
-    // opportunistic cleanup of long-dead jobs so the map can't grow forever
     for (const [id, sh] of map) {
         if (sh.exited && Date.now() - sh.startedAt > 30 * 60_000 && !map.delete(id))
             void id;
     }
     const id = `bg${++bgSeq}`;
-    // plain `-c`, not `-lc`: a login shell sources ~/.bash_profile, whose `cd`
-    // would move background jobs out of the workspace
     const shellSpec = toolShell();
     const child = spawn(shellSpec.file, shellSpec.args(cmd), {
         cwd: ctx.cwd,
@@ -423,13 +251,6 @@ function startBackgroundShell(cmd, ctx) {
         else
             sh.truncated = true;
     };
-    /**
-     * Persist the RECORD, so a later process can at least say this job exists.
-     *
-     * The `pid` is what makes it checkable on boot: a job whose pid is gone is dropped, one whose pid
-     * is alive is reported as "still running, output no longer reachable". That is the honest answer
-     * after a restart — see `ToolContext.stateDir`.
-     */
     if (ctx.stateDir) {
         rememberJob(ctx.stateDir, {
             id, cmd, owner: ctx.agentId ?? "", workspace: ctx.cwd,
@@ -439,18 +260,6 @@ function startBackgroundShell(cmd, ctx) {
     }
     child.stdout?.on("data", collect);
     child.stderr?.on("data", collect);
-    // "exit" (process gone) and "close" (all stdio drained) are DIFFERENT events.
-    // A backgrounded grandchild that inherits stdout — `npm run dev &`,
-    // `docker compose up &`, a script that forks a watcher — keeps the pipe open,
-    // so "close" can stay pending long after the shell itself is dead. Keying
-    // the exit state off "close" alone left such jobs marked running FOREVER:
-    // hasRunningBgShells() said yes, the auto-continue loop kept breaking out on
-    // "background job still running", and the agent sat in "running" with the
-    // job long dead and no notification ever delivered.
-    //
-    // So: "exit" is authoritative for state and for the completion
-    // notification; "close" only means "output finally drained" and is used to
-    // capture the tail. The notify() helper keeps this exactly-once.
     let exitNotified = false;
     const notify = (code) => {
         sh.exited = true;
@@ -459,10 +268,8 @@ function startBackgroundShell(cmd, ctx) {
         if (exitNotified)
             return;
         exitNotified = true;
-        // the job is over: its record must not claim otherwise on the next boot
         if (ctx.stateDir)
             forgetJob(ctx.stateDir, id);
-        // tell the harness so the agent learns the outcome WITHOUT polling
         try {
             ctx.onBackgroundExit?.({
                 id,
@@ -473,7 +280,6 @@ function startBackgroundShell(cmd, ctx) {
             });
         }
         catch {
-            /* notification is best-effort */
         }
     };
     child.on("exit", (code) => notify(code));
@@ -481,42 +287,14 @@ function startBackgroundShell(cmd, ctx) {
     map.set(id, sh);
     return id;
 }
-/** Heuristic: did this provider error mean "prompt exceeded the context window"?
- *  Wording varies by provider (OpenRouter/OpenAI/Anthropic/local servers). */
 export function isContextOverflow(err) {
     const msg = String(err?.message ?? "").toLowerCase();
     return (/context (length|window|limit)|too many tokens|prompt is too long|max.{0,12}tokens.{0,20}(exceed|surpass)|request too large|payload too large|exceeds.{0,20}limit/.test(msg) ||
         /\b(400|413)\b.*token/.test(msg) ||
-        // some gateways answer an over-long request with HTTP 200 and put the
-        // real diagnosis in the body, which llm.ts now surfaces after the "no
-        // choices" prefix. Without this the compact-and-retry recovery never
-        // recognised it and the turn simply failed.
         /no choices:[\s\S]{0,300}context (length|window|limit)/.test(msg));
 }
-/** Any background shell still running for this workspace? The auto-continue
- *  loop consults this before nudging a finished round: an agent that parked
- *  its work on `bash(background=true)` — dev server, watcher, long build —
- *  must NOT be nagged with "Continue working toward the current goal". The
- *  job's exit notification will wake the agent on its own. */
-/**
- * The background shells for a workspace, as the UI sees them.
- *
- * Only a VIEW: no child process, no cursors. The `out` field is the tail kept for `bash_output`, so
- * showing it costs nothing extra — the buffer is already there.
- *
- * `owner` is included because several agents share one workspace (every sub-agent inherits its
- * parent's), and "whose job is this" is the first thing an operator asks when deciding what to kill.
- */
 export function listBgShells(cwd, stateDir) {
     const live = liveShells(cwd);
-    /**
-     * Records from a previous process are appended, marked `detached`.
-     *
-     * Without them a job that survived a restart is INVISIBLE — MEASURED: a 3-hour GPU sweep kept
-     * writing while the panel showed nothing and `bash_output` said "forgotten on harness restart".
-     * The process cannot be re-attached (no fd survives the parent), so `detached` is the whole truth
-     * the UI can be given: it is running, and its output lives wherever the command redirected it.
-     */
     if (!stateDir)
         return live;
     const known = new Set(live.map((j) => j.id));
@@ -537,7 +315,6 @@ export function listBgShells(cwd, stateDir) {
     }));
     return [...live, ...recovered].sort((a, b) => b.startedAt - a.startedAt);
 }
-/** does this pid exist? (EPERM means it exists but is not ours to signal) */
 function pidExists(pid) {
     try {
         process.kill(pid, 0);
@@ -547,7 +324,6 @@ function pidExists(pid) {
         return err.code === "EPERM";
     }
 }
-/** the jobs THIS process is running, as the UI sees them */
 function liveShells(cwd) {
     const m = bgShellsByWs.get(cwd);
     if (!m)
@@ -560,22 +336,12 @@ function liveShells(cwd) {
         running: !b.exited,
         code: b.code,
         startedAt: b.startedAt,
-        // the LAST slice: a job is watched to see what it is doing NOW, and the head of a 10MB log is
-        // the least interesting part of it
         tail: b.out.slice(-4000),
         bytes: b.out.length,
         truncated: b.truncated,
     }))
         .sort((a, b) => b.startedAt - a.startedAt);
 }
-/**
- * Kill ONE background job; returns whether it existed.
- *
- * A DETACHED job (a record from a previous process) is handled differently on purpose: the harness no
- * longer owns that process, so this drops the RECORD and does NOT signal the pid. Killing a pid we
- * merely remember is how an unrelated process gets killed after pid reuse — and the operator's own
- * instruction was to never touch a job from an earlier session. The caller reports what happened.
- */
 export function killBgShell(cwd, id, stateDir) {
     const m = bgShellsByWs.get(cwd);
     const b = m?.get(id);
@@ -584,14 +350,12 @@ export function killBgShell(cwd, id, stateDir) {
             killTree(b.child);
         }
         catch {
-            /* already gone */
         }
         m.delete(id);
         if (stateDir)
             forgetJob(stateDir, id);
         return true;
     }
-    // not ours any more: forget it, leave the process alone
     if (stateDir) {
         const rec = readJobRecords(stateDir).find((r) => r.id === id);
         if (rec) {
@@ -606,7 +370,6 @@ export function hasRunningBgShells(cwd) {
     if (!m)
         return false;
     for (const sh of m.values()) {
-        // opportunistic cleanup mirrors startBackgroundShell's
         if (sh.exited && Date.now() - sh.startedAt > 30 * 60_000) {
             m.delete(sh.id);
             continue;
@@ -616,17 +379,6 @@ export function hasRunningBgShells(cwd) {
     }
     return false;
 }
-/**
- * Does THIS agent have a background job still running?
- *
- * `hasRunningBgShells(cwd)` answers for a DIRECTORY, which is the right question for
- * `killBgShells` and the wrong one for "is this agent busy". Sub-agents inherit their parent's
- * workspace, so a shared directory made every sibling of a busy agent report `live: true` —
- * their stop buttons offered to stop work that was already gone.
- *
- * An empty owner means a job started before owners were recorded; those are treated as
- * belonging to nobody, so they cannot make an unrelated agent look busy.
- */
 export function hasRunningBgShellsFor(cwd, owner) {
     const m = bgShellsByWs.get(cwd);
     if (!m || !owner)
@@ -639,18 +391,6 @@ export function hasRunningBgShellsFor(cwd, owner) {
     }
     return false;
 }
-/**
- * Kill every background shell for one workspace and forget the jobs.
- *
- * `stop()` left these running. They are spawned `detached: true` for group-killing
- * and are NOT covered by `toolAbort` (that signal only reaches a tool that is
- * still on the stack), so pressing stop on an agent that had parked its round on
- * a background job killed nothing: the loop sat in its deliberate "wait for the
- * job" idle state while the job kept burning CPU, and no control could end it.
- *
- *
- * Returns how many were actually killed, so a caller can report it.
- */
 export function killBgShells(cwd) {
     const m = bgShellsByWs.get(cwd);
     if (!m)
@@ -666,19 +406,13 @@ export function killBgShells(cwd) {
     m.clear();
     return killed;
 }
-/** Run a command in its own process group; kill the whole group on timeout. */
-function runShell(cmd, ctx, timeoutMs, 
-/** did the caller pass `timeout_ms`, or is this the default? the message says which */
-explicitTimeout = false) {
+function runShell(cmd, ctx, timeoutMs, explicitTimeout = false) {
     return new Promise((resolve) => {
         const t0 = Date.now();
-        // `bash -l` sources /etc/profile + ~/.bash_profile, either of which may
-        // `cd` somewhere — which silently moved every later relative path out of
-        // the workspace. Plain `-c` starts in ctx.cwd and stays there.
         const sh = toolShell();
         const child = spawn(sh.file, sh.args(cmd), {
             cwd: ctx.cwd,
-            detached: true, // own process group
+            detached: true,
             stdio: ["ignore", "pipe", "pipe"],
             env: shellEnv(),
         });
@@ -691,32 +425,8 @@ explicitTimeout = false) {
         };
         child.stdout.on("data", collect);
         child.stderr.on("data", collect);
-        // the kill REPORTS whether it worked. It used to swallow every failure
-        // as "already gone", and on Windows a group kill throws ALWAYS — so a timeout
-        // would report `TIMEOUT after …ms` for a process that was still running, and
-        // shutdown would leave it alive. A timeout that claims success is worse than
-        // a crash, because nothing afterwards looks wrong.
         const killGroup = () => killTree(child);
         const timer = setTimeout(() => {
-            /**
-             * The message has to teach the agent what it did not know.
-             *
-             * It read `TIMEOUT after 120000ms — killed`, which names neither the limit in human terms nor
-             * the parameter that changes it. MEASURED: an agent that never noticed `timeout_ms` hit this
-             * repeatedly, retrying the same command. So the message says WHAT the limit was, WHERE it came
-             * from (default vs explicit), what to pass next time, and when to switch to `background`.
-             */
-            /**
-             * The message has to teach the agent what it did not know.
-             *
-             * It read `TIMEOUT after 120000ms — killed`, which names neither the limit in human terms nor
-             * the parameter that changes it. MEASURED: an agent that never noticed `timeout_ms` hit this
-             * repeatedly, retrying the same command. So the message says WHAT the limit was, WHERE it came
-             * from (default vs explicit), what to pass next time, and when to switch to `background`.
-             *
-             * The limit keeps its raw `ms` when it is sub-second: "TIMEOUT after 0s" for a 300ms limit
-             * both reads wrong and loses the precision a caller needs to judge its next attempt.
-             */
             const limit = timeoutMs < 1000 ? `${timeoutMs}ms` : `${Math.round(timeoutMs / 1000)}s`;
             killReason =
                 `TIMEOUT after ${limit} — ${describeKill(killGroup())}. ` +
@@ -728,7 +438,6 @@ explicitTimeout = false) {
                             `or use background=true for a job with no timeout at all.`
                         : `If it needs longer than the maximum, use background=true — a background job has no timeout.`);
         }, timeoutMs);
-        // harness shutdown must not wait out a long-running command
         const onAbort = () => {
             killReason = `ABORTED (harness shutdown) — ${describeKill(killGroup())}`;
         };
@@ -763,14 +472,11 @@ explicitTimeout = false) {
                 ok: code === 0,
                 result: (code === 0 ? "" : `exit=${code}${signal ? ` signal=${signal}` : ""}\n`) +
                     clip(out.trim() || "(no output)", ctx.maxOutputBytes) +
-                    // the model, not just the operator, needs to know a command was slow —
-                    // otherwise it happily re-issues something that takes 40 minutes
                     elapsed(t0),
             });
         });
     });
 }
-/** 1-based line number of each occurrence of needle in text. */
 function matchLines(text, needle) {
     const out = [];
     let idx = text.indexOf(needle);
@@ -780,10 +486,6 @@ function matchLines(text, needle) {
     }
     return out;
 }
-/**
- * Fuzzy-but-safe locator: find windows of lines equal to the pattern after
- * trimming trailing whitespace on each side. Returns 0-based start line hits.
- */
 function trailingWsMatches(srcLines, patLines) {
     const hits = [];
     for (let i = 0; i + patLines.length <= srcLines.length; i++) {
@@ -799,64 +501,20 @@ function trailingWsMatches(srcLines, patLines) {
     }
     return hits;
 }
-/**
- * Did `anchor` resolve to a span far larger than it asked for? Returns the refusal, or null.
- *
- * ## Why this is a separate function
- *
- * The first version was inlined and measured `text.indexOf(anchor)` — which by definition finds
- * exactly `anchor.length` characters, so it could NEVER fire, and its test passed with the guard
- * disabled. The overshoot does not come from the exact match: it comes from the TOLERANT path,
- * where a model that omits indentation or trailing spaces hands over a short anchor and the
- * per-line comparison then accepts a much longer region.
- *
- * So the question is: how many file lines does the anchor's FIRST line's text actually cover
- * once tolerance is applied? If that region is more than twice the anchor's own line count, the
- * anchor is not specific enough and the edit would rewrite something unintended.
- *
- * cases are exactly the ones where tolerance decides what matched. Being wrong there is silent.
- */
 export function disproportionateSpan(text, anchor) {
     const anchorLines = anchor.split("\n");
     const askedLines = anchorLines.length;
     if (askedLines < 2)
-        return null; // a single line cannot span disproportionately
-    /**
-     * Do NOT require an exact substring match.
-     *
-     * The whole point is the near-miss case: the anchor does not appear verbatim, which is why the
-     * tolerant path is consulted at all and why it can overshoot. Requiring `indexOf` here made
-     * the guard unreachable exactly when it matters.
-     */
+        return null;
     const anchorFirst = anchorLines[0].trimEnd();
     const allSrcLines = text.split("\n");
-    /** every place the anchor's first line appears — the BEST one decides, not the first */
     const starts = [];
     for (let i = 0; i < allSrcLines.length; i++)
         if (allSrcLines[i].trimEnd() === anchorFirst)
             starts.push(i);
     if (!starts.length)
-        return null; // its first line is not in the file at all: not this guard's case
-    /**
-     * How many file lines does the anchor COVER, allowing the same trailing-whitespace tolerance
-     * the tolerant matcher uses?
-     *
-     * This walks the file and the anchor together, and counts file lines consumed. If matching
-     * the anchor requires consuming more than twice its own line count, the anchor is too loose:
-     * applying it would replace a region the model did not point at.
-     */
+        return null;
     const srcLines = allSrcLines;
-    /**
-     * EVERY candidate start is considered, and the guard only fires when ALL of them overshoot.
-     *
-     * Probing just the FIRST occurrence was wrong whenever the anchor's opening line is not unique —
-     * `\tif (pwrseq->skip_power_cycle) {` appears more than once in that file, and the first one led
-     * the walk into a distant match, so a legitimate 7-line anchor was refused for "covering 58
-     * lines". MEASURED in tyb2-9-8155867c: the model then abandoned `edit_file` for that region.
-     *
-     * The guard's question is "could this anchor be read as pointing somewhere else?" — if ANY
-     * plausible reading fits inside the tolerance, it cannot.
-     */
     let best = Number.POSITIVE_INFINITY;
     for (const start of starts) {
         let fileAt = start;
@@ -882,7 +540,7 @@ export function disproportionateSpan(text, anchor) {
             best = Math.min(best, consumed);
     }
     if (!Number.isFinite(best))
-        return null; // did not resolve under tolerance; not this guard's business
+        return null;
     if (best > askedLines * 2) {
         return (`old_text spans ${askedLines} line(s) but the nearest reading of it covers ${best} ` +
             `lines of the file — refusing a disproportionate match. An anchor this loose would ` +
@@ -890,62 +548,21 @@ export function disproportionateSpan(text, anchor) {
     }
     return null;
 }
-/**
- * How long a `bash` command may run when `timeout_ms` is not given.
- *
- * The UI imports this (via `frontend/lib/bash-timeout.ts`) so the row shows the SAME cap the server
- * enforces. They drifted once: the server applied 120s while the row drew nothing, because the row
- * only looked at a `timeout_ms` the model had omitted.
- */
 export const BASH_DEFAULT_TIMEOUT_MS = 120_000;
-/** the hard ceiling, applied after any `timeout_ms` the model passes */
 export const BASH_MAX_TIMEOUT_MS = 600_000;
 export const DEFAULT_TIMEOUT_MS = BASH_DEFAULT_TIMEOUT_MS;
-/* ---------- read_url cache ---------- */
 const URL_CACHE_TTL_MS = 3_600_000;
 const urlCache = new Map();
 function clipText(s, max) {
     const n = Math.max(1000, Math.min(max, 80_000));
     return s.length <= n ? s : `${s.slice(0, n)}\n… [truncated, ${s.length} chars total]`;
 }
-/**
- * Patterns that backtrack catastrophically.
- *
- * A nested quantifier — a quantified group whose body is itself quantified, or
- * alternation that can match the same text more than one way — makes the engine
- * explore exponentially many splits. Measured on this codebase: `(a+)+b` against
- * 28 characters of "a" took 3.8s, roughly DOUBLING per character added, and a
- * 40-character line would run for days.
- *
- * There is no timeout on this path: `ctx.defaultTimeoutMs` guards `bash` only,
- * so the scan is a synchronous `re.test(line)` with nothing able to interrupt it.
- * The agent process blocks and takes the UI and every other agent with it.
- *
- * A model is poorly placed to reason about backtracking cost and nothing tells it
- * not to try, so the pattern is checked rather than trusted. This rejects the
- * SHAPE rather than trying to bound the runtime, because a synchronous regex
- * cannot be abandoned once `test` starts — the only reliable protection is to
- * never compile one.
- */
 const BACKTRACKING_PATTERNS = [
-    // (a+)+  (a*)*  (a+)*  (a?)* … — a quantifier wrapping another quantifier
     { re: /\([^()]*[+*}][^()]*\)\s*[+*{]/, why: "a quantifier nested inside another quantifier" },
-    // (a|a)+ — alternation whose branches can match the SAME text. Distinct
-    // branches like (foo|bar)+ are fine and common, so this only fires when two
-    // branches are literally identical, which is the shape that explodes.
     { re: /\(([^()|]*)\|\1\)\s*[+*{]/, why: "an alternation with identical branches inside a quantifier" },
-    // (.*)*  (.+)+ — a wildcard quantified inside a quantifier
     { re: /\(\s*[.][*+]\s*\)\s*[+*{]/, why: "a wildcard quantified inside a quantifier" },
 ];
-/** Above this, the O(lines x pattern) scan itself becomes the cost. */
 const MAX_PATTERN_LENGTH = 1000;
-/**
- * Compile a model-supplied regex, refusing ones that can backtrack
- * catastrophically.
- *
- * Returns an error STRING rather than a RegExp so every existing call site —
- * which already handles that shape for an invalid pattern — needs no change.
- */
 function compileRegex(pattern, ignoreCase) {
     if (pattern.length > MAX_PATTERN_LENGTH)
         return `pattern too long (${pattern.length} chars, max ${MAX_PATTERN_LENGTH}) — narrow it, or grep for a literal substring instead`;
@@ -960,7 +577,6 @@ function compileRegex(pattern, ignoreCase) {
         return `invalid regex: ${e.message}`;
     }
 }
-/** Codex seek_sequence: find pattern lines at/after `start`, loosening match rules stepwise. */
 function seekSequence(lines, pattern, start, eof) {
     if (pattern.length === 0)
         return start;
@@ -970,7 +586,6 @@ function seekSequence(lines, pattern, start, eof) {
     const eqExact = (a, b) => a === b;
     const eqRstrip = (a, b) => a.trimEnd() === b.trimEnd();
     const eqTrim = (a, b) => a.trim() === b.trim();
-    // typographic dashes/quotes/spaces → ASCII, mirroring codex's final pass
     const normalise = (s) => s
         .trim()
         .replace(/[\u2010-\u2015\u2212]/g, "-")
@@ -995,7 +610,6 @@ function seekSequence(lines, pattern, start, eof) {
 }
 function parsePatch(patch) {
     let text = patch.trim();
-    // lenient: strip a heredoc wrapper (<<EOF … EOF), as models sometimes emit one
     const lines0 = text.split("\n");
     if (lines0.length >= 4 &&
         ["<<EOF", "<<'EOF'", '<<"EOF"'].includes(lines0[0].trim()) &&
@@ -1005,12 +619,6 @@ function parsePatch(patch) {
     const lines = text.split("\n").map((l) => l.replace(/\r$/, ""));
     if (lines[0]?.trim() !== "*** Begin Patch")
         return `invalid patch: The first line must be '*** Begin Patch'`;
-    // Backslash-corruption tripwire: models occasionally emit "\u0000" where a
-    // literal backslash belonged (a provider-side JSON escaping failure, seen
-    // live as 90× "\u0000sqrt{12}" in a LaTeX-heavy patch). Applying that
-    // verbatim writes broken source; the model then burns turns repairing the
-    // file (or discards its own work). Reject with an actionable message —
-    // retrying the SAME patch won't help, so say what will.
     if (text.includes("\\u0000")) {
         const count = (text.match(/\\u0000/g) ?? []).length;
         return (`invalid patch: contains ${count} × "\\u0000" — this is mangled backslash output, not real content. ` +
@@ -1074,7 +682,7 @@ function parsePatch(patch) {
                     continue;
                 }
                 if (l.startsWith("+") || l.startsWith("-") || l.startsWith(" ")) {
-                    cur ??= { changeContext: null, oldLines: [], newLines: [], isEndOfFile: false }; // implicit first chunk
+                    cur ??= { changeContext: null, oldLines: [], newLines: [], isEndOfFile: false };
                     if (l.startsWith("+"))
                         cur.newLines.push(l.slice(1));
                     else if (l.startsWith("-"))
@@ -1095,7 +703,7 @@ function parsePatch(patch) {
                 }
                 if (!l.trim()) {
                     i++;
-                    continue; // blank between hunks
+                    continue;
                 }
                 return `invalid patch: bad line in Update File '${filePath}': "${l.slice(0, 60)}" (expected ' ', '-', '+' or '@@')`;
             }
@@ -1109,7 +717,6 @@ function parsePatch(patch) {
     }
     return ops;
 }
-/** Compute the updated content of one file (no I/O writes). Error string on failure. */
 async function deriveUpdate(p, displayPath, chunks) {
     let raw;
     try {
@@ -1121,7 +728,7 @@ async function deriveUpdate(p, displayPath, chunks) {
     const hadCrlf = raw.includes("\r\n");
     const originalLines = raw.split("\n");
     if (originalLines.at(-1) === "")
-        originalLines.pop(); // trailing newline → diff-standard line list
+        originalLines.pop();
     const replacements = [];
     let lineIndex = 0;
     for (const ch of chunks) {
@@ -1134,13 +741,11 @@ async function deriveUpdate(p, displayPath, chunks) {
         let pattern = ch.oldLines;
         let newSlice = ch.newLines;
         if (pattern.length === 0) {
-            // codex semantics: a chunk with no context/removed lines appends at end of file
             replacements.push([originalLines.length, 0, newSlice]);
             continue;
         }
         let found = seekSequence(originalLines, pattern, lineIndex, ch.isEndOfFile);
         if (found == null && pattern.at(-1) === "") {
-            // trailing "" usually represents the file's final newline sentinel
             const p2 = pattern.slice(0, -1);
             const n2 = newSlice.at(-1) === "" ? newSlice.slice(0, -1) : newSlice;
             found = seekSequence(originalLines, p2, lineIndex, ch.isEndOfFile);
@@ -1155,7 +760,7 @@ async function deriveUpdate(p, displayPath, chunks) {
         replacements.push([found, pattern.length, newSlice]);
         lineIndex = found + pattern.length;
     }
-    replacements.sort((a, b) => b[0] - a[0]); // descending so earlier edits keep indices valid
+    replacements.sort((a, b) => b[0] - a[0]);
     const out = originalLines.slice();
     for (const [startIdx, oldLen, seg] of replacements)
         out.splice(startIdx, oldLen, ...seg);
@@ -1169,7 +774,6 @@ async function applyPatch(patch, ctx) {
         return { ok: false, result: ops };
     if (ops.length === 0)
         return { ok: false, result: "patch contains no file operations" };
-    // resolve every path up front (workspace confinement + duplicate guard)
     const seen = new Set();
     const resolved = [];
     try {
@@ -1191,7 +795,6 @@ async function applyPatch(patch, ctx) {
     catch (e) {
         return { ok: false, result: e.message };
     }
-    // phase 1 — validate everything, write nothing
     const writes = [];
     const deletes = [];
     const summary = [];
@@ -1226,20 +829,6 @@ async function applyPatch(patch, ctx) {
     catch (e) {
         return { ok: false, result: `patch validation failed: ${e.message}` };
     }
-    // phase 2 — commit.
-    //
-    // Phase 1 validates every hunk in memory, so a CONTENT mismatch never
-    // lands halfway. An I/O failure still could: the old loop wrote straight
-    // to the final paths, so a failure on write k of n left writes 1..k-1
-    // already on disk while the tool reported "patch failed". apply_patch is
-    // documented as atomic, so make the commit phase live up to it:
-    //   1. back up the current bytes of every path we are about to change
-    //   2. write each new file to a sibling temp file, then rename() over the
-    //      target (rename within a directory is atomic, so a reader never
-    //      observes a half-written file)
-    //   3. on ANY failure, restore the backups and remove temp files
-    // Deletes are only performed once every write has landed, and a failed
-    // delete is now reported instead of silently swallowed.
     const backups = new Map();
     const temps = [];
     try {
@@ -1261,9 +850,6 @@ async function applyPatch(patch, ctx) {
                 "re-read the files and regenerate the patch",
         };
     }
-    // writes are in — now the deletes. A delete that fails is a real, visible
-    // inconsistency (the old content moved/updated but the source survived),
-    // so roll the whole patch back rather than report a false success.
     const removed = [];
     try {
         for (const d of deletes) {
@@ -1285,11 +871,6 @@ async function applyPatch(patch, ctx) {
     }
     return { ok: true, result: `patch applied:\n${summary.join("\n")}` };
 }
-/**
- * Undo a partially committed patch: restore each target's original bytes
- * (null = it did not exist before, so remove the file we created) and clean
- * up any temp file that never made it through its rename.
- */
 async function rollbackWrites(backups, temps) {
     for (const t of temps)
         await fs.rm(t, { force: true }).catch(() => { });
@@ -1300,35 +881,8 @@ async function rollbackWrites(backups, temps) {
             await fs.writeFile(abs, orig, "utf8").catch(() => { });
     }
 }
-/* ---------- hashline: stable, verifiable line anchors (#7 / #4) ----------
- *
- * The default `N| ` gutter is a trap: read_file prints it, but edit_file's
- * old_text must NOT contain it — so the model strips the gutter by hand on
- * every read, and the only mitigation is a sentence in the tool description.
- *
- * Format follows the established "hashline" convention used across AI coding
- * harnesses (quangdang46/hashline, kebbbnnn/hashline, opencode-hashline,
- * pi-hashline-edit-pro, …) so anchors read the same everywhere:
- *
- *     12:a3f1| function calculateTotal(items) {
- *
- * i.e. `LINE:HASH| content` — the line number is KEPT (humans and models both
- * navigate by line) and the content hash is ADDED as an integrity anchor.
- *
- * Design points taken from those implementations rather than invented:
- *  - the hash covers the STRIPPED content, so re-indenting a line does not
- *    invalidate its anchor;
- *  - blank/whitespace-only lines get a fixed reserved hash;
- *  - when a hash occurs more than once, the anchor's line number disambiguates
- *    via PROXIMITY search, instead of silently taking the first match.
- */
-const HASH_BLANK = "    "; // 4 spaces: reserved, cannot collide with a hex hash
-// A real hash is 4 HEX chars, but the shape also accepts other 4-8 char
-// alphanumerics: a model that mistypes or invents an anchor is common enough
-// that we should still recognise the SHAPE and say "that anchor is malformed"
-// rather than falling through to "no similar text found".
+const HASH_BLANK = "    ";
 const ANCHOR_RE = /^\s*(\d+):([0-9a-z]{4,8}| {4})\|/;
-/** 4-char content hash (FNV-1a 32-bit → hex), of the STRIPPED line */
 export function hashLine(content) {
     const stripped = content.trim();
     if (!stripped)
@@ -1340,60 +894,28 @@ export function hashLine(content) {
     }
     return (h >>> 0).toString(16).padStart(8, "0").slice(-4);
 }
-/** `LINE:HASH| content` for each line, 1-indexed */
 export function renderHashlines(lines, startLine = 1) {
-    // same trailing-newline rule as renderGutter: a file ending in "\n"
-    // splits into a final "" that is not a line, and an anchor for it is a lie
-    // the model can copy into an edit that then never verifies
     const body = lines.length && lines[lines.length - 1] === "" ? lines.slice(0, -1) : lines;
     return body
         .map((l, i) => `${startLine + i}:${hashLine(l)}| ${l}`)
         .join("\n");
 }
-/**
- * Width of the `N| ` gutter for a page, so every line in it lines up.
- *
- * the prefix had no padding, so the gutter silently widened at line 1000
- * and the whole block jumped sideways mid-file — the exact "unfriendly line
- * numbers" complaint. Padding to the widest number IN THE PAGE is enough: a
- * page is a bounded window, and aligning to the file's total length would
- * push every line of a 20-line read of a 500k-line file 6 characters right.
- */
 export function gutterWidth(startLine, count) {
     return String(Math.max(0, startLine - 1) + count).length;
 }
-/**
- * The default `N| ` display, with a stable gutter width and no phantom line.
- *
- * #7, second half: the prefix was added AFTER `text.split("\n")`, so a file
- * ending in a newline produced a final numbered row for a line that does not
- * exist. A model that copies the tail verbatim then hands `edit_file` an
- * old_text with a phantom line in it, and the edit fails for no visible reason.
- * A trailing empty element is dropped, which is what the reader means.
- */
 export function renderGutter(lines, startLine = 1) {
-    // a trailing newline splits into a final "" — not a line of the file
     const body = lines.length && lines[lines.length - 1] === "" ? lines.slice(0, -1) : lines;
     if (!body.length)
         return "";
     const w = gutterWidth(startLine, body.length);
     return body.map((l, i) => `${String(startLine + i).padStart(w)}| ${l}`).join("\n");
 }
-/** parse a `LINE:HASH` anchor; returns null when the text is not an anchor */
 export function parseAnchor(anchor) {
     const m = /^\s*(\d+):([0-9a-z]{4,8}| {4})\s*$/.exec(anchor);
     if (!m)
         return null;
     return { line: Number(m[1]), hash: m[2] };
 }
-/**
- * Locate the line an anchor refers to.
- *
- * The hash is authoritative; the line number only disambiguates when the same
- * content appears twice (proximity search). Falling back to "nearest line" for
- * an unknown hash is deliberately NOT done — that would silently edit the wrong
- * line, which is the entire failure mode hashline exists to prevent.
- */
 export function resolveAnchor(lines, anchor) {
     const hits = [];
     for (let i = 0; i < lines.length; i++)
@@ -1403,25 +925,11 @@ export function resolveAnchor(lines, anchor) {
         return {
             error: /^[0-9a-f]{4}$/.test(anchor.hash) || anchor.hash === HASH_BLANK
                 ? `no line matches hash ${anchor.hash} — the file changed since you read it (re-read it)`
-                : // distinguish "you invented/mistyped this anchor" from "the file moved",
-                    // which sends the agent to fix the right thing
+                :
                     `hash ${JSON.stringify(anchor.hash)} is not a valid anchor (expected 4 hex chars) — re-read the file and copy the anchor verbatim`,
         };
     if (hits.length === 1)
         return { index: hits[0], how: "unique" };
-    /**
-     * Several lines share this hash — because the hash is DERIVED FROM CONTENT.
-     *
-     * That is the structural weakness of this format compared with the anchor-table implementations
-     * (`pi-hashline-edit-pro` allocates an anchor per line "never derived from content, so
-     * byte-identical lines never share an anchor"). Here two identical lines are one anchor, so the
-     * line number has to break the tie by proximity — a guess, and a guess that can be wrong in a file
-     * with repeated blocks.
-     *
-     * The guess is kept (refusing outright would make editing any file with repeated lines
-     * impossible), but it is now REPORTED instead of being a silent choice: the caller appends it to
-     * the tool result, so a model that landed on the wrong copy can see why.
-     */
     const target = anchor.line - 1;
     const best = hits.reduce((a, b) => (Math.abs(b - target) < Math.abs(a - target) ? b : a));
     return {
@@ -1430,19 +938,12 @@ export function resolveAnchor(lines, anchor) {
             `resolved by proximity, VERIFY you edited the copy you meant`,
     };
 }
-/** Is this whole block a hashline block (every line carries an anchor)? */
 export function isHashlineBlock(block) {
     const rows = block.split("\n").filter((l) => l !== "");
     if (!rows.length)
         return false;
     return rows.every((l) => ANCHOR_RE.test(l));
 }
-/**
- * Turn a copied hashline block back into file content.
- *
- * The anchors are verified against the CURRENT file, so a stale read is
- * refused instead of editing the wrong bytes — the whole point of the format.
- */
 export function resolveHashlineBlock(block, lines) {
     const rows = block.split("\n").filter((l) => l !== "");
     const picked = [];
@@ -1468,7 +969,6 @@ export function resolveHashlineBlock(block, lines) {
         return { error: "empty hashline block" };
     return { text: content.join("\n"), indices: picked, notes };
 }
-/** normalize the read_file line-reference argument */
 export function lineIdMode(args) {
     const v = args.line_ids ?? args.hashline;
     if (v === true)
@@ -1519,13 +1019,6 @@ export const TOOLS = [
             required: ["path"],
         },
         async run(args, ctx) {
-            // MULTI-FILE and FUZZY reads.
-            //
-            // Both are opt-in and handled HERE rather than by restructuring this
-            // tool: `paths` re-enters executeTool once per file, and `fuzzy` locates
-            // a file then re-enters it. Nothing about the single-file path below
-            // changes, so its output stays byte-identical — which #7's hashline
-            // anchors and the existing tests both depend on.
             if (Array.isArray(args.paths) && args.paths.length) {
                 const wanted = args.paths
                     .map((v) => str(v).trim())
@@ -1541,7 +1034,6 @@ export const TOOLS = [
                 const chunks = [];
                 for (const rel of wanted) {
                     const r = await executeTool("read_file", JSON.stringify({ ...args, path: rel, paths: undefined }), ctx);
-                    // one bad file must not sink the others: report it inline
                     chunks.push(`--- ${rel} ---\n${r.ok ? r.result : `ERROR: ${r.result}`}`);
                 }
                 return { ok: true, result: chunks.join("\n\n") };
@@ -1551,15 +1043,6 @@ export const TOOLS = [
             const p = safeJoin(ctx.cwd, str(args.path));
             let text;
             try {
-                /**
-                 * Refuse a BINARY file instead of decoding it as UTF-8.
-                 *
-                 * `readText` has no notion of encoding, so `read_file` on an image returned the raw bytes as
-                 * a lossy string — reported as "画像をread_fileしてバイナリが帰ってきてる". The model then pays
-                 * for mojibake it cannot interpret and has no way to tell "this is data" from "this is
-                 * source". Naming the likely type (PNG/JPEG/PDF/ELF/zip) is what lets it choose the right
-                 * next step instead of retrying the same read.
-                 */
                 const probe = await looksBinary(p);
                 if (probe.binary) {
                     return {
@@ -1572,9 +1055,6 @@ export const TOOLS = [
                 text = await readText(p);
             }
             catch (err) {
-                // name the file, not just the errno: a multi-file read reports each bad
-                // path inline, and "ENOENT … /tmp/xyz/nope.ts" leaves the model to work
-                // out which of the paths it asked for
                 const code = err.code;
                 return {
                     ok: false,
@@ -1582,15 +1062,8 @@ export const TOOLS = [
                 };
             }
             ctx.onFileRead?.(str(args.path));
-            // split on ALL THREE line endings. A CR-only (old-Mac) file used to
-            // come back as a single line, so the model could not address lines 2..n at
-            // all — and a CRLF file left a trailing "\r" on every line, which then
-            // had to be stripped again by every consumer.
             const lines = splitEolLines(text);
-            // #7/#4: opt-in hashline output. Default stays the historical `N| ` so
-            // nothing that depends on it changes until the mode is chosen.
             const idMode = lineIdMode(args);
-            // grep mode
             if (typeof args.pattern === "string" && args.pattern !== "") {
                 const re = compileRegex(args.pattern, args.ignore_case === true);
                 if (typeof re === "string")
@@ -1624,31 +1097,18 @@ export const TOOLS = [
                     result += `\n(${off + 1}–${off + page.length} of ${idxs.length} matches)`;
                 return { ok: true, result };
             }
-            // plain mode
             let off = num(args.offset, 1);
             off = off < 0 ? Math.max(0, lines.length + off) : Math.max(0, off - 1);
             const lim = num(args.limit, 2000);
-            // A LINE cap alone does not bound the output: a single 5MB minified line is one
-            // "line", and 2000 lines of 2000 chars is 4MB. The three caps below each kill a
-            // different shape of oversized file (#17 item 3):
-            //   lines  → a 3000-line source file
-            //   bytes  → a big log, whatever its line structure
-            //   per-line → minified.js / a one-line JSON blob
             const pageLines = lines.slice(off, off + lim);
-            // PER-LINE cap first: clipping lines before joining means one giant line cannot
-            // blow the byte budget on its own, and the marker names how much was cut.
             const cappedLines = pageLines.map((l) => l.length > MAX_READ_LINE_CHARS
                 ? l.slice(0, MAX_READ_LINE_CHARS) +
                     ` …[line clipped: ${l.length - MAX_READ_LINE_CHARS} more chars]`
                 : l);
             const rendered = idMode === "hash" ? renderHashlines(cappedLines, off + 1) : renderGutter(cappedLines, off + 1);
-            // the phantom trailing line is dropped for the count too, or a file that
-            // ends in a newline always reports one line more than it has
             const total = lines.length && lines[lines.length - 1] === "" ? lines.length - 1 : lines.length;
             const more = off + lim < total ? `\n... (${total - off - lim} more lines)` : "";
             const out = rendered + more;
-            // BYTE cap last, with the remaining line count in the marker so the model knows
-            // how to continue rather than assuming it saw everything.
             if (out.length > MAX_READ_BYTES) {
                 const head = out.slice(0, MAX_READ_BYTES);
                 const cutAt = head.lastIndexOf("\n");
@@ -1656,9 +1116,6 @@ export const TOOLS = [
                     ok: true,
                     result: (cutAt > 0 ? head.slice(0, cutAt) : head) +
                         `\n... [output clipped at ${MAX_READ_BYTES} bytes of ${out.length}; ` +
-                        // `head` holds N rendered lines separated by N-1 newlines, and rendering
-                        // started at 1-indexed line `off + 1`, so the next unread line is
-                        // off + 1 + N. Counting newlines alone gives N-1 and would re-read one line.
                         `continue with offset=${off + 1 + countLines(cutAt > 0 ? head.slice(0, cutAt) : head) + 1}]`,
                 };
             }
@@ -1684,9 +1141,6 @@ export const TOOLS = [
             required: ["path", "content"],
         },
         async run(args, ctx) {
-            // content must be a real string: a non-string (object/array from bad
-            // model output) coerced to "[object Object]" or silently truncated —
-            // worse, an undefined slipped past required and WIPED the file
             if (typeof args.content !== "string") {
                 return {
                     ok: false,
@@ -1700,22 +1154,6 @@ export const TOOLS = [
             if (stale)
                 return stale;
             await fs.mkdir(path.dirname(p), { recursive: true });
-            // a file's line endings belong to the FILE. Writing the model's
-            // content verbatim silently converted a CRLF (or CR) file to LF whenever
-            // the model rewrote it — the model never emits \r — so one logical edit
-            // produced a whole-file diff, and any tool that normalises on EOL (git,
-            // prettier) would rewrite it afterwards.
-            //
-            // So an EXISTING file's dominant EOL is re-applied. detectEol returns null
-            // for a mixed file, which is left untouched on purpose: choosing a winner
-            // there would itself be the silent whole-file rewrite this prevents.
-            //
-            // when the file CANNOT answer — it is new, or its EOL is mixed — ask
-            // `.editorconfig` before falling back to LF. The order is deliberate: the
-            // file's own bytes outrank configuration, which outranks the default. A
-            // `end_of_line = crlf` in a repo whose files are all LF must not convert
-            // every file the agent touches, so config is never consulted for a file that
-            // already has an unambiguous ending.
             const before = await currentOrNull(p);
             const detected = before === null ? null : detectEol(before);
             if (detected !== null)
@@ -1759,12 +1197,6 @@ export const TOOLS = [
                 return stale;
             let oldText = str(args.old_text);
             let newText = str(args.new_text);
-            // the single most common edit_file failure in the real logs (22
-            // occurrences) said only "old_text is required", while the tool's own
-            // schema already documents the better form. Name it and say what to do —
-            // the pattern master.ts uses for "not your sub-agent" (its
-            // `messageChild`),
-            // which turned a confusing refusal into a re-addressable one.
             if (!oldText)
                 return {
                     ok: false,
@@ -1773,31 +1205,9 @@ export const TOOLS = [
                         "Do NOT copy read_file's `N| ` line-number prefixes.",
                 };
             const replaceAll = args.replace_all === true;
-            // #7/#4: accept a block copied straight out of read_file's hashline
-            // output. When the anchors do not verify we FAIL with the specific reason
-            // rather than silently falling back to literal matching — a literal match
-            // that happened to succeed would edit the wrong bytes, which is the exact
-            // failure mode hashline exists to prevent.
-            //
-            // On success we edit by RESOLVED LINE INDEX rather than by searching for
-            // the text: the anchors already pinpointed the lines, so a block whose
-            // content legitimately appears twice (the case proximity search exists
-            // for) must not then fail the uniqueness check on the resolved text.
             let hashNote = "";
             let hashNotes = [];
             let hashSpan = null;
-            /**
-             * A hashline-formatted `new_text` is STRIPPED, not pasted.
-             *
-             * MEASURED in tyb2-9-8155867c: `old_text` and `new_text` were IDENTICAL, both carrying anchors
-             * (`155c| …`, `59d3| …`) copied from the read. The model meant "these lines, rewritten" but
-             * pasted the anchor gutter on both sides. The result was refused as "old_text not found",
-             * which names the wrong argument — the anchors had already been resolved away, so the literal
-             * search could not find them, and the reply never mentioned the real mistake.
-             *
-             * The anchors belong to the READ, not to the file. Stripping them from `new_text` is what the
-             * model meant, and writing them into the source would be corruption.
-             */
             const newTextHasAnchors = isHashlineBlock(newText);
             if (isHashlineBlock(oldText)) {
                 const srcLines = text.replace(/\r\n/g, "\n").split("\n");
@@ -1810,13 +1220,6 @@ export const TOOLS = [
                     hashSpan = { start: r.indices[0], end: r.indices[r.indices.length - 1] + 1 };
                 }
             }
-            /**
-             * Drop anchors from `new_text` — they are the READ's numbering, not file content.
-             *
-             * A block whose anchors cannot be resolved is still stripped (the content is what was meant);
-             * writing `155c| ` into a source file would be corruption, so the safe direction is to remove
-             * them and let the rest of the edit be judged on its text.
-             */
             if (newTextHasAnchors) {
                 const stripped = newText
                     .split("\n")
@@ -1831,27 +1234,7 @@ export const TOOLS = [
                 }
             }
             let count = hashNote ? 0 : text.split(oldText).length - 1;
-            /**
-             * A MINIMUM ANCHOR LENGTH, from Gemini's `edit.ts`.
-             *
-             * Below this, an anchor cannot identify anything: "  }" or "\n\n" appear everywhere, and
-             * any tolerant matching on them either fails ambiguously or picks a wrong span. MEASURED
-             * across every session: `old_text not found` is 117 of 168 edit failures, and a
-             * large share of those are anchors too short to be unique, sent by a model that believed
-             * them specific.
-             *
-             * Short anchors are still ACCEPTED when they match exactly once — a one-character edit is
-             * legitimate. What is refused is trying to make a short anchor work by relaxing the match.
-             */
             const MIN_FUZZY_ANCHOR = 10;
-            /**
-             * A MULTI-LINE anchor is specific by construction: two matching lines pin both a start
-             * and a continuation, which is far stronger evidence than 10 characters on one line.
-             * Gemini's floor is about single-line anchors, where "  }" and "foo();" genuinely cannot
-             * identify anything. Applying it by raw character count rejected `foo\nbar` — a perfectly
-             * unambiguous two-line anchor — which is the guard making normal editing harder, the
-             * exact failure mode #157 warns about.
-             */
             const anchorLines = oldText.split("\n").length;
             const anchorTooShort = anchorLines < 2 && oldText.trim().length < MIN_FUZZY_ANCHOR;
             let normalized = false;
@@ -1864,17 +1247,11 @@ export const TOOLS = [
                     normalized = true;
                 }
             }
-            // tolerate patterns whose only difference is trailing whitespace per line
-            // (the most common near-miss) — applied only when it resolves uniquely
             if (count === 0 && !anchorTooShort) {
                 const srcLines = text.replace(/\r\n/g, "\n").split("\n");
                 const patLines = oldText.replace(/\r\n/g, "\n").split("\n");
                 const hits = trailingWsMatches(srcLines, patLines);
                 if (hits.length === 1 && patLines.length > 0) {
-                    // same detection as the hashline path — CR-only files are detected
-                    // too, and a MIXED file yields null and is left as-is rather than
-                    // homogenised. The old `includes("\r\n")` test called a CR-only file
-                    // "\n", so an edit to one silently converted its line endings.
                     const rebuilt = [
                         ...srcLines.slice(0, hits[0]),
                         ...splitEolLines(newText),
@@ -1893,17 +1270,12 @@ export const TOOLS = [
                     };
             }
             if (count === 0) {
-                // actionable miss: point the model at recovery instead of pushing it
-                // toward bash-based editing
                 const lines = matchLines(text, oldText.trim());
                 const hint = lines.length
                     ? `A trimmed variant appears at line(s) ${lines.slice(0, 5).join(", ")}.`
                     : `No similar text found — re-read ${str(args.path)} around the target area and copy old_text exactly.`;
                 return {
                     ok: false,
-                    // a hashline block that did not resolve gets ITS reason — the generic
-                    // "not found" would send the model hunting for a whitespace problem
-                    // when the real issue is a stale read
                     result: hashNote
                         ? `old_text is a hashline block but did not resolve: ${hashNote}.`
                         : `old_text not found in file. ${hint} Watch indentation/trailing spaces and drop the \`N| \` line-number prefixes.`,
@@ -1916,35 +1288,11 @@ export const TOOLS = [
                     result: `old_text matched ${count} times (lines ${at.slice(0, 5).join(", ")}) and must be unique — add surrounding lines to old_text, or pass replace_all=true`,
                 };
             }
-            /**
-             * DISPROPORTIONATE MATCH guard, from OpenCode's `isDisproportionateMatch`.
-             *
-             * The dangerous shape is not "no match" — that is loud and recoverable — but a match far
-             * LARGER than the anchor, where asking to change one call site silently rewrites a whole
-             * function. A confident wrong edit is worse than a failed one.
-             */
             if (!hashSpan) {
                 const over = disproportionateSpan(text, oldText);
                 if (over)
                     return { ok: false, result: over };
             }
-            // A verified hashline block is addressed BY LINE INDEX: the anchors
-            // already proved which lines it means, so a block whose content occurs
-            // twice must still edit the anchored occurrence rather than fail the
-            // uniqueness check.
-            // The hashline path splits on "\n" to index by resolved line number, which
-            // leaves a trailing "\r" on every line of a CRLF file. Rejoining with
-            // "\n" then DROPS all of them, so a single edit silently rewrote a
-            // Windows file's line endings: the replaced line arrived with the model's
-            // "\n" while every untouched line kept its "\r\n". The file still parsed
-            // and the edit "succeeded", so nothing reported it — but the next
-            // checkout diff shows the whole file changed, and tools that normalise on
-            // EOL (git, prettier, formatters) now rewrite it.
-            //
-            // So the EOL is detected ONCE from the untouched text and re-applied to
-            // the replacement, which also keeps a CRLF file CRLF when the model sends
-            // LF-separated new_text (the overwhelmingly common case — models never
-            // emit \r).
             const eol = text.includes("\r\n") ? "\r\n" : "\n";
             const out = hashSpan
                 ? splitEolLines(text)
@@ -2077,13 +1425,10 @@ export const TOOLS = [
                         `jobs are per-workspace and forgotten on harness restart`,
                 };
             if (str(args.action) === "kill") {
-                // same swallowed-kill bug — this reported "killed" and dropped the
-                // job from the map while the process kept running, now untrackable.
                 const note = sh.exited ? "(already exited)" : describeKill(killTree(sh.child));
                 map.delete(sh.id);
                 return { ok: true, result: `job ${sh.id} ${note}. Output so far:\n${clip(sh.out, 4000)}` };
             }
-            // action === read (default): hand back NEW bytes and remember the cursor
             const fresh = sh.out.slice(bgReadCursors.get(sh.id) ?? 0);
             bgReadCursors.set(sh.id, sh.out.length);
             const status = sh.exited
@@ -2092,7 +1437,6 @@ export const TOOLS = [
             const body = (fresh.length ? fresh : "(no new output)") +
                 (sh.truncated ? "\n… (output truncated at 200KB)" : "") +
                 status;
-            // finished jobs are removed once fully drained
             if (sh.exited && bgReadCursors.get(sh.id) >= sh.out.length) {
                 map.delete(sh.id);
                 bgReadCursors.delete(sh.id);
@@ -2138,7 +1482,6 @@ export const TOOLS = [
             const html = await res.text();
             if (!html.trim())
                 return { ok: false, result: `HTTP ${res.status} with an empty body` };
-            // heavy DOM deps are loaded lazily so the master's idle startup stays lean
             const { Browser } = await import("happy-dom");
             const { Readability } = await import("@mozilla/readability");
             const browser = new Browser();
@@ -2183,18 +1526,6 @@ export const TOOLS = [
                 task: { type: "string", description: "self-contained instructions for the sub-agent" },
                 context: { type: "string", enum: ["none", "fork"], description: "default none" },
                 name: { type: "string", description: "optional short name fragment for the id" },
-                // reasoning effort for THIS sub-agent, overriding both the
-                // configured subagent default and the parent's inherited value.
-                //
-                // Precedence mirrors OpenAI Codex (codex-rs/core/src/agent/child_config.rs):
-                // spawn argument -> configured default -> parent's effort. Codex
-                // deliberately does NOT inherit by default — its own test sets a parent at
-                // XHigh and asserts a child spawned with Low runs at Low, because
-                // sub-agents are usually narrow and cheap and inheriting a parent's high
-                // effort across many trivial scouts multiplies cost for no gain.
-                //
-                // Naming it here is what stops the silent loss: previously a spawn could
-                // not express an effort at all, so the parent's value simply vanished.
                 reasoning_effort: {
                     type: "string",
                     enum: ["minimal", "low", "medium", "high", "xhigh"],
@@ -2213,8 +1544,6 @@ export const TOOLS = [
                 return { ok: false, result: "task required" };
             const context = args.context === "fork" ? "fork" : "none";
             try {
-                // validate like the per-agent setter does, so a typo cannot reach
-                // the provider as an unrecognised effort value.
                 const effort = str(args.reasoning_effort).trim();
                 if (effort && !isReasoningEffort(effort))
                     return {
@@ -2298,12 +1627,6 @@ export const TOOLS = [
                 return { ok: false, result: "sub-agents are not available here" };
             const ids = Array.isArray(args.ids) ? args.ids.map(String) : undefined;
             const ms = Math.min(Math.max(num(args.timeout_ms, 300_000), 1_000), 3_600_000);
-            // a prompt ALREADY in the queue must be consumed FIRST. The
-            // enqueue-time wake only fires for prompts arriving DURING the park —
-            // one queued before the park is invisible to it, and parking over it
-            // strands the operator's message ("idle" display, nothing processed)
-            // until a child settles. Stand down and let the next turn boundary
-            // drain it; the model can call wait_children again afterwards.
             if (ctx.hasPendingPrompts?.()) {
                 ctx.onProgressGateReset?.();
                 return {
@@ -2311,24 +1634,19 @@ export const TOOLS = [
                     result: "A prompt is already queued for you — handle it first, then call wait_children again if you still need to wait.",
                 };
             }
-            // park VISIBLY: the UI shows idle ("waiting on sub-agents") instead of a
-            // running spinner, and any user prompt / stop wakes us instantly
             const parked = ctx.onIdlePark?.(`waiting on sub-agent${ids?.length === 1 ? ` ${ids[0]}` : "s"}`);
             if (parked === false) {
-                // the agent refused the park (a prompt raced in) — same answer as above
                 ctx.onProgressGateReset?.();
                 return {
                     ok: true,
                     result: "A prompt arrived while you were about to wait — handle it first, then call wait_children again if you still need to wait.",
                 };
             }
-            // the child's report is about to land in our mailbox — a progress report
-            // right after it would be pure noise, so re-arm the gate here
             ctx.onProgressGateReset?.();
             try {
                 const r = await sa.wait(ids, ms);
                 ctx.onIdleUnpark?.();
-                ctx.onProgressGateReset?.(); // also after: waiting itself isn't "activity"
+                ctx.onProgressGateReset?.();
                 return { ok: true, result: r.note };
             }
             catch (e) {
@@ -2372,9 +1690,6 @@ export const TOOLS = [
         name: "load_skill",
         description: "Load a skill's full instructions by name. Use when the system prompt's skill list " +
             "matches your current task; follow the loaded playbook. " +
-            // the instruction used to need a SECOND, separately-queued message that
-            // only arrived at the next turn boundary. Passing `instructions` delivers it
-            // in the SAME turn as the playbook, so "load X and do Y" costs one round-trip.
             "Pass `instructions` with what you want done with it to receive both at once.",
         parameters: {
             type: "object",
@@ -2400,8 +1715,6 @@ export const TOOLS = [
             }
             let result = await readSkillFile(def);
             if (def.files.length) {
-                // surface bundled scripts as runnable paths: workspace-relative when
-                // possible (bash runs in the workspace), absolute for global skills
                 const dirAbs = path.dirname(def.filePath);
                 const rootDir = roots
                     .map((r) => r.dir)
@@ -2415,8 +1728,6 @@ export const TOOLS = [
                         listed.map((f) => `- ${f}`).join("\n") +
                         `\nRun scripts with bash (chmod +x first if needed).`;
             }
-            // deliver the caller's instructions in THIS result, so the model does
-            // not have to queue a second message that only lands next turn.
             const instructions = str(args.instructions).trim();
             if (instructions)
                 result +=
@@ -2465,12 +1776,6 @@ export const TOOLS = [
             const content = str(args.content);
             if (!content.trim())
                 return { ok: false, result: "content required" };
-            // save GLOBALLY (config dir) so skills survive workspace switches and
-            // are shared by every agent. Same-name handling is safe:
-            //  · overwriting the global copy replaces it atomically (writeFile)
-            //  · a same-name skill in a HIGHER-priority root (workspace) still
-            //    shadows this one at load time — that's the intended override,
-            //    so tell the model when its save would be invisible
             const globalRoot = roots.find((r) => r.source === "global") ?? roots[0];
             const filePath = await saveSkill(globalRoot.dir, name, description, content.slice(0, 64_000));
             let note = "";
@@ -2482,10 +1787,9 @@ export const TOOLS = [
                         await fs.access(path.join(r.dir, name, SKILL_FILE));
                         note = ` (note: a workspace skill with the same name "${name}" takes precedence at load time)`;
                     }
-                    catch { /* no clash in this root */ }
+                    catch { }
                 }
             }
-            // bundled scripts/files next to SKILL.md
             const written = [];
             const rawFiles = Array.isArray(args.files) ? args.files : [];
             for (const f of rawFiles.slice(0, 10)) {
@@ -2509,24 +1813,9 @@ export const TOOLS = [
         },
     },
 ];
-/** #16: how many files one read_file call may cover. Each costs context, so an
- *  unbounded array would just be a way to overflow the window in one shot. */
 const MAX_MULTI_READ = 10;
-/**
- * The three read caps (#17 item 3). A line cap alone is not a bound: one 5MB minified
- * line is a single "line", and 2000 lines of 2000 chars is 4MB. Each cap kills a
- * different shape of oversized file:
- *
- *   2000 lines  → a 3000-line source file        (the `limit` default, unchanged)
- *   256 KB      → a 5MB log, whatever its lines
- *   2000 chars  → minified.js / a one-line JSON blob
- *
- * The byte cap is a SHARE of what a tool result can be, not the whole budget: the model
- * still needs room to reason about what it read.
- */
 const MAX_READ_BYTES = 256 * 1024;
 const MAX_READ_LINE_CHARS = 2_000;
-/** how many lines a string contains — used to say where to resume a clipped read */
 function countLines(s) {
     let n = 0;
     for (let i = 0; i < s.length; i++)
@@ -2534,15 +1823,6 @@ function countLines(s) {
             n++;
     return n;
 }
-/**
- * Subsequence match: every character of `needle` appears in `hay`, in order,
- * gaps allowed (#16 "fuzzy").
- *
- * Deliberately not a ranked edit-distance search. This answers "is this the
- * file I meant", and it can only say yes or no — it cannot rank a plausible
- * WRONG file above the right one, which is the failure mode that actually costs
- * an agent time. Searching file CONTENT is what bash/grep are for.
- */
 export function fuzzyPathMatch(needle, hay) {
     const n = needle.toLowerCase().replace(/[\s._/-]+/g, "");
     if (!n)
@@ -2557,14 +1837,6 @@ export function fuzzyPathMatch(needle, hay) {
     }
     return false;
 }
-/**
- * Locate a file by a loose name and read it.
- *
- * Walks the workspace (skipping .git, node_modules and build noise) and ranks
- * matches: exact path, exact basename, ends-with, then subsequence. When
- * several match it LISTS them rather than picking one — guessing here would have
- * the agent edit the wrong file, which is the expensive mistake.
- */
 async function fuzzyRead(needle, ctx, args) {
     const q = needle.trim();
     if (!q)
@@ -2614,12 +1886,7 @@ async function fuzzyRead(needle, ctx, args) {
     }
     found.sort((a, b) => a.rank - b.rank || a.rel.length - b.rel.length || a.rel.localeCompare(b.rel));
     const best = found[0];
-    // Only a confident match is read directly. If the query is vague enough that
-    // several files match, LIST them: guessing would hand the agent the wrong
-    // file, and the cost of that mistake is far higher than one extra call.
-    // An exact path or basename is unambiguous, so those still read straight away.
     if (best.rank <= 1 || found.length === 1) {
-        // re-enter the tool so a unique match behaves exactly like a normal read
         return executeTool("read_file", JSON.stringify({ ...args, path: best.rel, fuzzy: undefined }), ctx);
     }
     return {
@@ -2628,7 +1895,6 @@ async function fuzzyRead(needle, ctx, args) {
             found.slice(0, 8).map((f) => `  ${f.rel}`).join("\n"),
     };
 }
-/** Current skills across the configured roots (for the system prompt listing). */
 export async function currentSkills(ctx) {
     return discoverSkills(ctx.skillRoots ?? []);
 }
@@ -2638,9 +1904,7 @@ export function toolSpecs() {
         function: { name: t.name, description: t.description, parameters: t.parameters },
     }));
 }
-/** tools that mutate the workspace — blocked for read-only personas */
 const MUTATING_TOOLS = new Set(["write_file", "edit_file", "apply_patch", "bash"]);
-/** per-tool aliases: the common wrong key -> the key the schema declares. */
 const ARG_ALIASES = {
     bash: { cmd: "command", script: "command", shell: "command", input: "command" },
     read_file: { file_path: "path", filepath: "path", file: "path", name: "path" },
@@ -2651,11 +1915,6 @@ const ARG_ALIASES = {
     list_children: { file_path: "path", dir: "path" },
     read_url: { uri: "url", link: "url" },
 };
-/**
- * The one argument each tool's whole call usually boils down to. Used to
- * salvage a bare word ("ls") that was never wrapped in JSON at all — but ONLY
- * for tools where that is unambiguous, so "12" is never mistaken for a path.
- */
 const PRIMARY_STRING_ARG = {
     bash: "command",
     read_file: "path",
@@ -2666,7 +1925,6 @@ const PRIMARY_STRING_ARG = {
     load_skill: "name",
     save_skill: "content",
 };
-/** keys whose schema type is a number / boolean, per tool. */
 const NUMERIC_ARGS = {
     read_file: ["offset", "limit", "context"],
     bash: ["timeout_ms"],
@@ -2680,12 +1938,10 @@ const BOOL_ARGS = {
     write_file: [],
     list_dir: [],
 };
-/** markdown/backtick framing models like to wrap a path in */
 function unframe(v) {
     const m = /^[`*_\s]+(.+?)[`*_\s]*$/.exec(v);
     return m ? m[1] : v;
 }
-/** coerce "100" -> 100, "true" -> true; returns undefined when not coercible */
 function coerceScalar(v) {
     if (typeof v !== "string")
         return v;
@@ -2698,7 +1954,6 @@ function coerceScalar(v) {
         return Number(t);
     return v;
 }
-/** Turn a value into an array, tolerating a bare scalar or a JSON array. */
 function toArray(v) {
     if (Array.isArray(v))
         return v;
@@ -2711,7 +1966,6 @@ function toArray(v) {
                     return p;
             }
             catch {
-                /* fall through — treat as a single element */
             }
         }
         return [v];
@@ -2727,12 +1981,8 @@ export function repairToolInput(name, rawArgs) {
         parsed = rawArgs?.trim() ? JSON.parse(rawArgs) : {};
     }
     catch {
-        // not JSON at all: a whole call was stringified, or the model emitted a
-        // bare word. Only salvageable when the tool takes a single obvious string.
         const bare = rawArgs?.trim().replace(/^[`*\s]+|[`*\s]+$/g, "");
         const primary = PRIMARY_STRING_ARG[name];
-        // a bare number/boolean is never a path or a command — refusing is far
-        // better than inventing one
         const isScalarish = bare !== "" && /^(true|false|null|-?\d+(\.\d+)?)$/i.test(bare);
         if (bare && primary && !isScalarish && !bare.startsWith("{") && !bare.startsWith("[")) {
             notes.push(`wrapped a bare string as {"${primary}": …}`);
@@ -2740,23 +1990,17 @@ export function repairToolInput(name, rawArgs) {
         }
         return { args: {}, notes, error: `arguments were not valid JSON — send a JSON object, e.g. {"…"}` };
     }
-    // a JSON-stringified object arrives as a string
     if (typeof parsed === "string" && /[{[]/.test(parsed.trim().slice(0, 2))) {
         try {
             parsed = JSON.parse(parsed);
             notes.push("unwrapped a JSON-stringified argument object");
         }
         catch {
-            /* leave as-is; it may genuinely be a string argument */
         }
     }
-    // a bare scalar where an object is required
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
         if (parsed === null || parsed === undefined)
             return { args: {}, notes, error: "arguments were empty" };
-        // An ARRAY is a legitimate value for a path-ish argument, but only for the
-        // tools that actually take one — inventing {path:[…]} for apply_patch would
-        // hand the tool a key it has never heard of.
         if (Array.isArray(parsed) && name === "read_file") {
             notes.push("kept the array as a paths list");
             return { args: { paths: parsed }, notes };
@@ -2774,7 +2018,6 @@ export function repairToolInput(name, rawArgs) {
         };
     }
     const args = { ...parsed };
-    // alias normalisation
     for (const [from, to] of Object.entries(ARG_ALIASES[name] ?? {})) {
         if (!(from in args))
             continue;
@@ -2783,13 +2026,10 @@ export function repairToolInput(name, rawArgs) {
             notes.push(`renamed "${from}" -> "${to}"`);
         }
         else {
-            // both present: the schema key wins and the stray alias is DROPPED, not
-            // left behind as an unknown argument the tool would ignore
             notes.push(`dropped "${from}" — "${to}" was also given and wins`);
         }
         delete args[from];
     }
-    // string -> number / boolean for the keys whose schema says so
     for (const k of NUMERIC_ARGS[name] ?? []) {
         if (k in args) {
             const c = coerceScalar(args[k]);
@@ -2808,18 +2048,12 @@ export function repairToolInput(name, rawArgs) {
             }
         }
     }
-    // an array-typed arg arriving as a scalar
     if (name === "read_file" && "paths" in args) {
         const before = args.paths;
         args.paths = toArray(before);
         if (!Array.isArray(before))
             notes.push('coerced "paths" to an array');
     }
-    // a JSON-stringified object hiding inside a single argument, e.g.
-    // {"path": "{\"path\": \"a.ts\"}"} — unwrap it and merge its keys
-    // Only PATH-like keys: `content`/`old_text`/`new_text` legitimately hold JSON
-    // (writing a .json file!), and unwrapping those would REPLACE the file's
-    // actual data with an inner field — silent data loss, not repair.
     for (const k of ["path", "command"]) {
         const v = args[k];
         if (typeof v !== "string")
@@ -2837,10 +2071,8 @@ export function repairToolInput(name, rawArgs) {
             }
         }
         catch {
-            /* genuinely not JSON — leave it alone */
         }
     }
-    // markdown framing on a path
     for (const k of ["path", "file_path"]) {
         if (typeof args[k] === "string") {
             const f = unframe(args[k]);
@@ -2853,9 +2085,6 @@ export function repairToolInput(name, rawArgs) {
     return { args, notes };
 }
 export async function executeTool(name, rawArgs, ctx) {
-    // MCP tools are namespaced (`mcp__server__tool`) so they can never reach this point
-    // by shadowing a built-in. Dispatched BEFORE the built-in lookup because there is no
-    // static TOOLS entry to find — the tool list belongs to the server.
     if (name.startsWith(MCP_PREFIX)) {
         if (ctx.signal?.aborted)
             return { ok: false, result: "aborted (harness shutdown)" };
@@ -2876,12 +2105,8 @@ export async function executeTool(name, rawArgs, ctx) {
         return { ok: false, result: `unknown tool: ${name}` };
     if (ctx.signal?.aborted)
         return { ok: false, result: "aborted (harness shutdown)" };
-    // read-only personas (researcher/reviewer) are enforced, not just asked
     if (ctx.readOnly && MUTATING_TOOLS.has(name) && !ctx.allowMutatingForReview?.includes(name))
         return { ok: false, result: `${name} is blocked: this agent runs with read-only tools` };
-    // repair the call before handing it to the tool. A model that sends
-    // {"cmd":"ls"} or {"limit":"100"} should get the work done, not a generic parse
-    // failure and a wasted turn. Unrepairable calls say what to send instead.
     const repaired = repairToolInput(name, rawArgs);
     if (repaired.error)
         return { ok: false, result: `${name}: ${repaired.error}` };
@@ -2895,24 +2120,6 @@ export async function executeTool(name, rawArgs, ctx) {
         return { ok: false, result: `tool error: ${err.message}` };
     }
 }
-/**
- * The gateway's cap on the REQUEST BODY'S STRUCTURE, not on its token count.
- *
- * Command Code's `/alpha` gateway rejects with
- * `400 Invalid request JSON: JSON node count cannot exceed 32768`, and the distinction matters
- * because every usual recovery is wrong for it:
- *
- *   - COMPACTING does not reliably help. It does reduce message and content-part counts, but a
- *     session heavy in tool calls and images stays above the cap — measured upstream at 22.6% of a
- *     1,000,000-token window with 1,436 messages and 61 image parts. Retrying after a compaction
- *     therefore burns a full-price summarisation to be refused again.
- *   - RESENDING the same structure cannot succeed at all, so this is not a transient error.
- *
- * So it is detected SEPARATELY from `isContextOverflow`, and the remedy is the honest one: a new
- * session, or fewer messages / tool calls / images in this one.
- *
- * Reference: Mars-Sea/dsh-commandcode-provider issue #96 and its `JSON_NODE_LIMIT_REJECTION`.
- */
 export function isRequestNodeLimit(err) {
     const msg = String(err?.message ?? "");
     const m = /JSON node count cannot exceed\s+(\d+)/i.exec(msg);