reasonix 0.5.22 → 0.5.24

package/dist/index.js

@@ -47,8 +47,8 @@ function computeWait(attempt, initial, cap, retryAfter) {
 }
 function sleep(ms, signal) {
   if (ms <= 0) return Promise.resolve();
-  return new Promise((resolve8, reject) => {
-    const timer = setTimeout(resolve8, ms);
+  return new Promise((resolve9, reject) => {
+    const timer = setTimeout(resolve9, ms);
     if (signal) {
       const onAbort = () => {
         clearTimeout(timer);
@@ -533,7 +533,7 @@ function matchesTool(hook, toolName) {
   }
 }
 function defaultSpawner(input) {
-  return new Promise((resolve8) => {
+  return new Promise((resolve9) => {
     const child = spawn(input.command, {
       cwd: input.cwd,
       shell: true,
@@ -560,7 +560,7 @@ function defaultSpawner(input) {
     });
     child.once("error", (err) => {
       clearTimeout(timer);
-      resolve8({
+      resolve9({
         exitCode: null,
         stdout,
         stderr,
@@ -570,7 +570,7 @@ function defaultSpawner(input) {
     });
     child.once("close", (code) => {
       clearTimeout(timer);
-      resolve8({
+      resolve9({
         exitCode: code,
         stdout: stdout.trim(),
         stderr: stderr.trim(),
@@ -900,6 +900,12 @@ var ToolRegistry = class {
    * bounced until the user approves a submitted plan.
    */
   _planMode = false;
+  /**
+   * Optional hook run after arg parsing but before tool.fn. Lets the TUI
+   * reroute specific tool calls (e.g. edit_file in review mode) without
+   * modifying the tool definitions themselves.
+   */
+  _interceptor = null;
   constructor(opts = {}) {
     this._autoFlatten = opts.autoFlatten !== false;
   }
@@ -911,6 +917,14 @@ var ToolRegistry = class {
   get planMode() {
     return this._planMode;
   }
+  /**
+   * Install or clear the dispatch interceptor. At most one interceptor
+   * is active at a time — calling twice replaces the previous. Pass
+   * `null` to remove.
+   */
+  setToolInterceptor(fn) {
+    this._interceptor = fn;
+  }
   register(def) {
     if (!def.name) throw new Error("tool requires a name");
     const internal = { ...def };
@@ -967,6 +981,16 @@ var ToolRegistry = class {
         error: `${name}: unavailable in plan mode \u2014 this is a read-only exploration phase. Use read_file / list_directory / search_files / directory_tree / web_search / allowlisted shell commands to investigate. Call submit_plan with your proposed plan when you're ready for the user's review.`
       });
     }
+    if (this._interceptor) {
+      try {
+        const short = await this._interceptor(name, args);
+        if (typeof short === "string") return short;
+      } catch (err) {
+        return JSON.stringify({
+          error: `${name}: interceptor failed \u2014 ${err.message}`
+        });
+      }
+    }
     try {
       const result = await tool.fn(args, { signal: opts.signal });
       const str = typeof result === "string" ? result : JSON.stringify(result);
@@ -1700,6 +1724,7 @@ function round(n, digits) {
 }
 
 // src/loop.ts
+var ARGS_COMPACT_THRESHOLD_TOKENS = 800;
 var CacheFirstLoop = class {
   client;
   prefix;
@@ -1803,12 +1828,62 @@ var CacheFirstLoop = class {
    * authored intent we can't mechanically shrink without losing
    * meaning.
    */
-  compact(maxTokens = 4e3) {
+  /**
+   * Conservative args-only shrink fired after every tool response —
+   * strictly about ONE thing: stop oversized `edit_file` / `write_file`
+   * arguments from riding every future turn's prompt.
+   *
+   * Why this is worth doing AUTOMATICALLY (not just on /compact):
+   * Each tool-call arguments string sticks in the log verbatim. On a
+   * coding session with ~10 edits, that's 20-40K tokens of stale
+   * SEARCH/REPLACE text riding along on every turn. Even at a 98.9%
+   * cache hit rate the input cost still adds up linearly (cache-hit
+   * price × tokens × turns). Compacting IMMEDIATELY after the tool
+   * responds means the next turn's prompt is already smaller — the
+   * shrink is a one-time write that saves every future prompt.
+   *
+   * Threshold rationale: 800 tokens ≈ 3 KB. A typical 20-line edit's
+   * args land well under that; massive rewrites (whole-file content,
+   * 100+ line refactors) land above and get the compaction. Small
+   * edits stay byte-verbatim so nothing common-case changes.
+   *
+   * Safety: we ONLY shrink args whose tool has ALREADY responded.
+   * Structurally that's every call in `log.toMessages()` at this
+   * point — the current turn's assistant/tool pairing is by
+   * construction closed by the time we get here (append happens
+   * AFTER dispatch). The in-flight assistant message being built
+   * lives in scratch, not the log, so this pass can't touch it.
+   *
+   * Model impact: the model may occasionally want to reference the
+   * exact SEARCH text of a prior edit — it then reads the file
+   * directly (which shows current state) or looks at the preceding
+   * assistant text (which has its plan). Losing the stale args is a
+   * net win: one extra read_file vs. dragging N KB of stale text
+   * through every subsequent turn.
+   */
+  compactToolCallArgsAfterResponse() {
     const before = this.log.toMessages();
-    const { messages, healedCount, tokensSaved, charsSaved } = shrinkOversizedToolResultsByTokens(
+    const { messages, healedCount } = shrinkOversizedToolCallArgsByTokens(
       before,
-      maxTokens
+      ARGS_COMPACT_THRESHOLD_TOKENS
     );
+    if (healedCount === 0) return;
+    this.log.compactInPlace(messages);
+    if (this.sessionName) {
+      try {
+        rewriteSession(this.sessionName, messages);
+      } catch {
+      }
+    }
+  }
+  compact(maxTokens = 4e3) {
+    const before = this.log.toMessages();
+    const resultsPass = shrinkOversizedToolResultsByTokens(before, maxTokens);
+    const argsPass = shrinkOversizedToolCallArgsByTokens(resultsPass.messages, maxTokens);
+    const messages = argsPass.messages;
+    const healedCount = resultsPass.healedCount + argsPass.healedCount;
+    const tokensSaved = resultsPass.tokensSaved + argsPass.tokensSaved;
+    const charsSaved = resultsPass.charsSaved + argsPass.charsSaved;
     if (healedCount > 0) {
       this.log.compactInPlace(messages);
       if (this.sessionName) {
@@ -2051,8 +2126,8 @@ var CacheFirstLoop = class {
             }
           );
           for (let k = 0; k < budget; k++) {
-            const sample = queue.shift() ?? await new Promise((resolve8) => {
-              waiter = resolve8;
+            const sample = queue.shift() ?? await new Promise((resolve9) => {
+              waiter = resolve9;
             });
             yield {
               turn: this._turn,
@@ -2318,6 +2393,7 @@ ${reason}`;
           name,
           content: result
         });
+        this.compactToolCallArgsAfterResponse();
         yield {
           turn: this._turn,
           role: "tool",
@@ -2503,6 +2579,56 @@ function shrinkOversizedToolResultsByTokens(messages, maxTokens) {
   });
   return { messages: out, healedCount, tokensSaved, charsSaved };
 }
+function shrinkOversizedToolCallArgsByTokens(messages, maxTokens) {
+  let healedCount = 0;
+  let tokensSaved = 0;
+  let charsSaved = 0;
+  const out = messages.map((msg) => {
+    if (msg.role !== "assistant" || !Array.isArray(msg.tool_calls)) return msg;
+    let changed = false;
+    const newCalls = msg.tool_calls.map((call) => {
+      const args = call.function?.arguments;
+      if (typeof args !== "string" || args.length <= maxTokens) return call;
+      const beforeTokens = countTokens(args);
+      if (beforeTokens <= maxTokens) return call;
+      const shrunk = shrinkJsonLongStrings(args);
+      const afterTokens = countTokens(shrunk);
+      if (afterTokens >= beforeTokens) return call;
+      changed = true;
+      healedCount += 1;
+      tokensSaved += beforeTokens - afterTokens;
+      charsSaved += args.length - shrunk.length;
+      return { ...call, function: { ...call.function, arguments: shrunk } };
+    });
+    if (!changed) return msg;
+    return { ...msg, tool_calls: newCalls };
+  });
+  return { messages: out, healedCount, tokensSaved, charsSaved };
+}
+function shrinkJsonLongStrings(jsonStr) {
+  let parsed;
+  try {
+    parsed = JSON.parse(jsonStr);
+  } catch {
+    const head = jsonStr.slice(0, 200);
+    return `${head}\u2026[shrunk: ${jsonStr.length} chars, unparsed]`;
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return jsonStr;
+  }
+  const LONG_THRESHOLD = 300;
+  const input = parsed;
+  const output = {};
+  for (const [k, v] of Object.entries(input)) {
+    if (typeof v === "string" && v.length > LONG_THRESHOLD) {
+      const newlines = v.match(/\n/g)?.length ?? 0;
+      output[k] = `[\u2026shrunk: ${v.length} chars, ${newlines} lines \u2014 tool already responded, see result]`;
+    } else {
+      output[k] = v;
+    }
+  }
+  return JSON.stringify(output);
+}
 function fixToolCallPairing(messages) {
   const out = [];
   let droppedAssistantCalls = 0;
@@ -2566,10 +2692,41 @@ function formatLoopError(err) {
   if (msg.includes("maximum context length")) {
     const reqMatch = msg.match(/requested\s+(\d+)\s+tokens/);
     const requested = reqMatch ? `${Number(reqMatch[1]).toLocaleString()} tokens` : "too many tokens";
-    return `Context overflow (DeepSeek 400): session history is ${requested}, past the 131,072-token limit. Usually this means a single tool call returned a huge payload. v0.3.0-alpha.6+ caps new tool results at 32k chars, AND auto-heals oversized history on session load \u2014 restart Reasonix and this session should come back trimmed. If it still overflows, run /forget (delete the session) or /clear (drop the displayed history) to start fresh.`;
+    return `Context overflow (DeepSeek 400): session history is ${requested}, past the model's prompt limit (V4: 1M tokens; legacy chat/reasoner: 131k). Usually a single tool result grew too big. Reasonix caps new tool results at 8k tokens and auto-heals oversized history on session load \u2014 a restart often clears it. If it still overflows, run /forget (delete the session) or /clear (drop the displayed history) to start fresh.`;
+  }
+  const m = /^DeepSeek (\d{3}):\s*([\s\S]*)$/.exec(msg);
+  if (!m) return msg;
+  const status = m[1] ?? "";
+  const body = m[2] ?? "";
+  const inner = extractDeepSeekErrorMessage(body);
+  if (status === "401") {
+    return `Authentication failed (DeepSeek 401): ${inner}. Your API key is rejected. Fix with \`reasonix setup\` or \`export DEEPSEEK_API_KEY=sk-...\`. Get one at https://platform.deepseek.com/api_keys.`;
+  }
+  if (status === "402") {
+    return `Out of balance (DeepSeek 402): ${inner}. Top up at https://platform.deepseek.com/top_up \u2014 the panel header shows your balance once it's non-zero.`;
+  }
+  if (status === "422") {
+    return `Invalid parameter (DeepSeek 422): ${inner}`;
+  }
+  if (status === "400") {
+    return `Bad request (DeepSeek 400): ${inner}`;
   }
   return msg;
 }
+function extractDeepSeekErrorMessage(body) {
+  const trimmed = body.trim();
+  if (!trimmed) return "(no message)";
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (parsed && typeof parsed === "object") {
+      const obj = parsed;
+      if (obj.error && typeof obj.error.message === "string") return obj.error.message;
+      if (typeof obj.message === "string") return obj.message;
+    }
+  } catch {
+  }
+  return trimmed;
+}
 
 // src/at-mentions.ts
 import { existsSync as existsSync4, readFileSync as readFileSync4, readdirSync as readdirSync2, statSync as statSync2 } from "fs";
@@ -3335,6 +3492,9 @@ import { promises as fs } from "fs";
 import * as pathMod from "path";
 var DEFAULT_MAX_READ_BYTES = 2 * 1024 * 1024;
 var DEFAULT_MAX_LIST_BYTES = 256 * 1024;
+var DEFAULT_AUTO_PREVIEW_LINES = 200;
+var AUTO_PREVIEW_HEAD_LINES = 80;
+var AUTO_PREVIEW_TAIL_LINES = 40;
 var SKIP_DIR_NAMES = /* @__PURE__ */ new Set([
   "node_modules",
   ".git",
@@ -3427,14 +3587,22 @@ function registerFilesystemTools(registry, opts) {
   };
   registry.register({
     name: "read_file",
-    description: "Read a file under the sandbox root. Returns the full contents (truncated with a notice if larger than the per-call cap). Paths may be relative to the root or absolute-under-root.",
+    description: `Read a file under the sandbox root. To save context, PREFER to scope the read instead of pulling the whole file:
+  - head: N  \u2192 first N lines (imports, public API, small configs)
+  - tail: N  \u2192 last N lines (recently-added code, log tails)
+  - range: "A-B"  \u2192 inclusive line range A..B, 1-indexed (e.g. "120-180" around an edit site)
+When none of these is given AND the file is longer than ${DEFAULT_AUTO_PREVIEW_LINES} lines, the tool auto-returns a head+tail preview with an "N lines omitted" marker rather than dumping everything. If you need the middle, re-call with a range. Prefer search_content to locate a symbol first, then read_file with a range around the hit \u2014 one scoped read beats three full-file reads.`,
     readOnly: true,
     parameters: {
       type: "object",
       properties: {
         path: { type: "string", description: "Path to read (relative to rootDir or absolute)." },
         head: { type: "integer", description: "If set, return only the first N lines." },
-        tail: { type: "integer", description: "If set, return only the last N lines." }
+        tail: { type: "integer", description: "If set, return only the last N lines." },
+        range: {
+          type: "string",
+          description: 'Inclusive line range like "50-100" or "50-50". 1-indexed. Takes precedence over head/tail when all three are set. Out-of-range requests clamp to file bounds.'
+        }
       },
       required: ["path"]
     },
@@ -3446,21 +3614,52 @@ function registerFilesystemTools(registry, opts) {
       }
       const raw = await fs.readFile(abs);
       if (raw.length > maxReadBytes) {
-        const head = raw.slice(0, maxReadBytes).toString("utf8");
-        return `${head}
+        const headBytes = raw.slice(0, maxReadBytes).toString("utf8");
+        return `${headBytes}
 
-[\u2026truncated ${raw.length - maxReadBytes} bytes \u2014 file is ${raw.length} B, cap ${maxReadBytes} B. Retry with head/tail for targeted view.]`;
+[\u2026truncated ${raw.length - maxReadBytes} bytes \u2014 file is ${raw.length} B, cap ${maxReadBytes} B. Retry with head/tail/range for targeted view.]`;
       }
       const text = raw.toString("utf8");
+      let lines = text.split(/\r?\n/);
+      if (lines.length > 0 && lines[lines.length - 1] === "") lines = lines.slice(0, -1);
+      const totalLines = lines.length;
+      if (typeof args.range === "string" && /^\d+\s*-\s*\d+$/.test(args.range)) {
+        const [rawStart, rawEnd] = args.range.split("-").map((s) => Number.parseInt(s, 10));
+        const start = Math.max(1, rawStart ?? 1);
+        const end = Math.min(totalLines, Math.max(start, rawEnd ?? totalLines));
+        const slice = lines.slice(start - 1, end);
+        const label = `[range ${start}-${end} of ${totalLines} lines]`;
+        return `${label}
+${slice.join("\n")}`;
+      }
       if (typeof args.head === "number" && args.head > 0) {
-        return text.split(/\r?\n/).slice(0, args.head).join("\n");
+        const count = Math.min(args.head, totalLines);
+        const slice = lines.slice(0, count);
+        const marker = count < totalLines ? `
+
+[\u2026head ${count} of ${totalLines} lines \u2014 call again with range / tail for more]` : "";
+        return slice.join("\n") + marker;
       }
       if (typeof args.tail === "number" && args.tail > 0) {
-        let lines = text.split(/\r?\n/);
-        if (lines.length > 0 && lines[lines.length - 1] === "") lines = lines.slice(0, -1);
-        return lines.slice(Math.max(0, lines.length - args.tail)).join("\n");
+        const count = Math.min(args.tail, totalLines);
+        const slice = lines.slice(totalLines - count);
+        const marker = count < totalLines ? `[\u2026tail ${count} of ${totalLines} lines \u2014 call again with range / head for more]
+
+` : "";
+        return marker + slice.join("\n");
       }
-      return text;
+      if (totalLines <= DEFAULT_AUTO_PREVIEW_LINES) return lines.join("\n");
+      const head = lines.slice(0, AUTO_PREVIEW_HEAD_LINES).join("\n");
+      const tail = lines.slice(totalLines - AUTO_PREVIEW_TAIL_LINES).join("\n");
+      const omitted = totalLines - AUTO_PREVIEW_HEAD_LINES - AUTO_PREVIEW_TAIL_LINES;
+      return [
+        `[auto-preview: head ${AUTO_PREVIEW_HEAD_LINES} + tail ${AUTO_PREVIEW_TAIL_LINES} of ${totalLines} lines]`,
+        head,
+        `
+[\u2026 ${omitted} lines omitted \u2014 call read_file again with range:"A-B" (1-indexed) or head / tail to get the middle]
+`,
+        tail
+      ].join("\n");
     }
   });
   registry.register({
@@ -3485,21 +3684,34 @@ function registerFilesystemTools(registry, opts) {
   });
   registry.register({
     name: "directory_tree",
-    description: "Recursively list entries in a directory. Shows indented tree structure with directories marked '/'. Caps output so a huge tree doesn't drown the context.",
+    description: `Recursively list entries in a directory. Shows indented tree structure with directories marked '/'. Budget-aware by default:
+  - maxDepth defaults to 2 (root + one level). A depth-4 tree on a real repo blew ~5K tokens in one call. If you truly need deeper, pass maxDepth:N explicitly.
+  - Skips ${[...SKIP_DIR_NAMES].sort().join(", ")} unless include_deps:true. Traversing into node_modules / .git / dist is almost always token-waste.
+  - Large subtrees (>50 children) auto-collapse to "[N files, M dirs hidden \u2014 list_directory <path> to inspect]" so one huge folder can't dominate the output.
+Prefer \`list_directory\` for a single-level view, \`search_files\` to find specific paths, and \`search_content\` to find code.`,
     readOnly: true,
     parameters: {
       type: "object",
       properties: {
         path: { type: "string", description: "Root of the tree (default: sandbox root)." },
-        maxDepth: { type: "integer", description: "Max recursion depth (default 4)." }
+        maxDepth: {
+          type: "integer",
+          description: "Max recursion depth (default 2). Depth 0 shows only the top-level entries; depth 2 is usually enough to see module structure."
+        },
+        include_deps: {
+          type: "boolean",
+          description: "When true, also traverse node_modules / .git / dist / build / etc. Off by default \u2014 most exploration questions are about the user's own code."
+        }
       }
     },
     fn: async (args) => {
       const startAbs = safePath(args.path ?? ".");
-      const maxDepth = typeof args.maxDepth === "number" ? args.maxDepth : 4;
+      const maxDepth = typeof args.maxDepth === "number" ? args.maxDepth : 2;
+      const includeDeps = args.include_deps === true;
       const lines = [];
       let totalBytes = 0;
       let truncated = false;
+      const PER_DIR_CHILD_CAP = 50;
       const walk2 = async (dir, depth) => {
         if (truncated) return;
         if (depth > maxDepth) return;
@@ -3510,10 +3722,27 @@ function registerFilesystemTools(registry, opts) {
           return;
         }
         entries.sort((a, b) => a.name.localeCompare(b.name));
+        let emitted = 0;
         for (const e of entries) {
           if (truncated) return;
+          const skip = e.isDirectory() && !includeDeps && SKIP_DIR_NAMES.has(e.name);
+          if (emitted >= PER_DIR_CHILD_CAP) {
+            const remaining = entries.length - emitted;
+            let restFiles = 0;
+            let restDirs = 0;
+            for (const r of entries.slice(emitted)) {
+              if (r.isDirectory()) restDirs++;
+              else restFiles++;
+            }
+            const indent2 = "  ".repeat(depth);
+            lines.push(
+              `${indent2}[\u2026 ${remaining} entries hidden (${restDirs} dirs, ${restFiles} files) \u2014 list_directory on this path to see all]`
+            );
+            return;
+          }
           const indent = "  ".repeat(depth);
-          const line = e.isDirectory() ? `${indent}${e.name}/` : `${indent}${e.name}`;
+          const suffix = skip ? " (skipped \u2014 pass include_deps:true to traverse)" : "";
+          const line = e.isDirectory() ? `${indent}${e.name}/${suffix}` : `${indent}${e.name}`;
           totalBytes += line.length + 1;
           if (totalBytes > maxListBytes) {
             lines.push(`  [\u2026 tree truncated at ${maxListBytes} bytes \u2026]`);
@@ -3521,7 +3750,8 @@ function registerFilesystemTools(registry, opts) {
             return;
           }
           lines.push(line);
-          if (e.isDirectory()) {
+          emitted++;
+          if (e.isDirectory() && !skip) {
             await walk2(pathMod.join(dir, e.name), depth + 1);
           }
         }
@@ -4231,9 +4461,311 @@ function forkRegistryExcluding(parent, exclude) {
 }
 
 // src/tools/shell.ts
-import { spawn as spawn2 } from "child_process";
+import { spawn as spawn3 } from "child_process";
 import { existsSync as existsSync8, statSync as statSync4 } from "fs";
+import * as pathMod3 from "path";
+
+// src/tools/jobs.ts
+import { spawn as spawn2 } from "child_process";
 import * as pathMod2 from "path";
+function killProcessTree(pid, signal) {
+  if (process.platform === "win32") {
+    const args = ["/pid", String(pid), "/T"];
+    if (signal === "SIGKILL") args.push("/F");
+    try {
+      const killer = spawn2("taskkill", args, {
+        stdio: "ignore",
+        windowsHide: true
+      });
+      killer.on("error", () => {
+      });
+    } catch {
+    }
+    return;
+  }
+  try {
+    process.kill(-pid, signal);
+    return;
+  } catch {
+  }
+  try {
+    process.kill(pid, signal);
+  } catch {
+  }
+}
+var DEFAULT_OUTPUT_CAP_BYTES = 64 * 1024;
+var READY_SIGNALS = [
+  // HTTP server banners
+  /\blistening on\b/i,
+  /\blocal:\s+https?:\/\//i,
+  /\bhttps?:\/\/(?:localhost|127\.0\.0\.1|0\.0\.0\.0)(?::\d+)?\b/i,
+  /\b(?:ready|server started|started server|app listening)\b/i,
+  // Bundlers / compilers
+  /\bcompiled successfully\b/i,
+  /\bbuild complete(?:d)?\b/i,
+  /\bwatching for (?:file )?changes\b/i,
+  /\bready in \d+/i,
+  // Generic
+  /\bstartup (?:complete|finished)\b/i
+];
+var JobRegistry = class {
+  jobs = /* @__PURE__ */ new Map();
+  nextId = 1;
+  /**
+   * Spawn a background child. Resolves after `waitSec` OR on ready
+   * signal OR on early exit, whichever comes first. The child continues
+   * to run (and buffer output) regardless of which path fires.
+   */
+  async start(command, opts) {
+    const trimmed = command.trim();
+    if (!trimmed) throw new Error("run_background: empty command");
+    const op = detectShellOperator(trimmed);
+    if (op !== null) {
+      throw new Error(
+        `run_background: shell operator "${op}" is not supported \u2014 spawn one process per background job. Compose via your orchestration, not the shell.`
+      );
+    }
+    const argv = tokenizeCommand(trimmed);
+    if (argv.length === 0) throw new Error("run_background: empty command");
+    const waitMs = Math.max(0, Math.min(30, opts.waitSec ?? 3)) * 1e3;
+    const maxBytes = opts.maxBufferBytes ?? DEFAULT_OUTPUT_CAP_BYTES;
+    const { bin, args, spawnOverrides } = prepareSpawn(argv);
+    const spawnOpts = {
+      cwd: pathMod2.resolve(opts.cwd),
+      shell: false,
+      windowsHide: true,
+      env: process.env,
+      // POSIX: detach so the child becomes its own process-group leader.
+      // Required for `process.kill(-pid, …)` later — without it a group
+      // kill fails and we end up only signaling the wrapper, leaving
+      // grandchildren (node → vite → esbuild …) orphaned.
+      // Windows: detached would spawn a new console window; leave the
+      // default and use taskkill /T for tree termination.
+      detached: process.platform !== "win32",
+      ...spawnOverrides
+    };
+    let child;
+    try {
+      child = spawn2(bin, args, spawnOpts);
+    } catch (err) {
+      const id2 = this.nextId++;
+      const job2 = {
+        id: id2,
+        command: trimmed,
+        pid: null,
+        startedAt: Date.now(),
+        exitCode: null,
+        output: `[spawn failed] ${err.message}`,
+        totalBytesWritten: 0,
+        running: false,
+        spawnError: err.message,
+        child: null,
+        readyPromise: Promise.resolve(),
+        signalReady: () => {
+        }
+      };
+      this.jobs.set(id2, job2);
+      return {
+        jobId: id2,
+        pid: null,
+        stillRunning: false,
+        readyMatched: false,
+        preview: job2.output,
+        exitCode: null
+      };
+    }
+    const id = this.nextId++;
+    let readyResolve = () => {
+    };
+    const readyPromise = new Promise((res) => {
+      readyResolve = res;
+    });
+    const job = {
+      id,
+      command: trimmed,
+      pid: child.pid ?? null,
+      startedAt: Date.now(),
+      exitCode: null,
+      output: "",
+      totalBytesWritten: 0,
+      running: true,
+      child,
+      readyPromise,
+      signalReady: readyResolve
+    };
+    this.jobs.set(id, job);
+    let readyMatched = false;
+    const onData = (chunk) => {
+      const s = chunk.toString();
+      job.totalBytesWritten += s.length;
+      job.output += s;
+      if (job.output.length > maxBytes) {
+        const overflow = job.output.length - maxBytes;
+        const cut = job.output.indexOf("\n", overflow);
+        const start = cut >= 0 ? cut + 1 : overflow;
+        job.output = `[\u2026 older output dropped \u2026]
+${job.output.slice(start)}`;
+      }
+      if (!readyMatched) {
+        for (const re of READY_SIGNALS) {
+          if (re.test(s) || re.test(job.output)) {
+            readyMatched = true;
+            job.signalReady();
+            break;
+          }
+        }
+      }
+    };
+    child.stdout?.on("data", onData);
+    child.stderr?.on("data", onData);
+    child.on("error", (err) => {
+      job.running = false;
+      job.spawnError = err.message;
+      job.signalReady();
+    });
+    child.on("close", (code) => {
+      job.running = false;
+      job.exitCode = code;
+      job.signalReady();
+    });
+    const onAbort = () => this.stop(id, { graceMs: 100 });
+    opts.signal?.addEventListener("abort", onAbort, { once: true });
+    let timer = null;
+    await Promise.race([
+      readyPromise,
+      new Promise((res) => {
+        timer = setTimeout(res, waitMs);
+      })
+    ]);
+    if (timer) clearTimeout(timer);
+    return {
+      jobId: id,
+      pid: job.pid,
+      stillRunning: job.running,
+      readyMatched,
+      preview: job.output,
+      exitCode: job.exitCode
+    };
+  }
+  /**
+   * Read a job's accumulated output. `since` lets a caller poll
+   * incrementally: pass the byte count returned from the last call to
+   * get only newly-written content. Returns both full output and a
+   * running snapshot so the caller can use whichever.
+   */
+  read(id, opts = {}) {
+    const job = this.jobs.get(id);
+    if (!job) return null;
+    const full = job.output;
+    let slice = full;
+    if (typeof opts.since === "number" && opts.since >= 0 && opts.since < full.length) {
+      slice = full.slice(opts.since);
+    }
+    if (typeof opts.tailLines === "number" && opts.tailLines > 0) {
+      const lines = slice.split("\n");
+      const keep = lines.slice(Math.max(0, lines.length - opts.tailLines));
+      slice = keep.join("\n");
+    }
+    return {
+      output: slice,
+      byteLength: full.length,
+      running: job.running,
+      exitCode: job.exitCode,
+      command: job.command,
+      pid: job.pid,
+      spawnError: job.spawnError
+    };
+  }
+  /**
+   * Send SIGTERM, wait `graceMs`, then SIGKILL if still alive. Returns
+   * the final job record (or null when the job id is unknown). Safe to
+   * call on an already-exited job — returns the record unchanged.
+   */
+  async stop(id, opts = {}) {
+    const job = this.jobs.get(id);
+    if (!job) return null;
+    if (!job.running || !job.child) return snapshot(job);
+    const graceMs = Math.max(0, opts.graceMs ?? 2e3);
+    if (job.pid !== null) {
+      killProcessTree(job.pid, "SIGTERM");
+    } else {
+      try {
+        job.child.kill("SIGTERM");
+      } catch {
+      }
+    }
+    await Promise.race([job.readyPromise, new Promise((res) => setTimeout(res, graceMs))]);
+    if (job.running) {
+      if (job.pid !== null) {
+        killProcessTree(job.pid, "SIGKILL");
+      } else {
+        try {
+          job.child.kill("SIGKILL");
+        } catch {
+        }
+      }
+      await new Promise((res) => setTimeout(res, 800));
+    }
+    return snapshot(job);
+  }
+  list() {
+    return [...this.jobs.values()].map(snapshot);
+  }
+  /**
+   * Best-effort kill of every still-running job. Called on TUI shutdown
+   * so dev servers don't outlive the Reasonix process. Resolves after
+   * every child has closed or a hard deadline passes (3s total).
+   */
+  async shutdown(deadlineMs = 5e3) {
+    const start = Date.now();
+    const runningJobs = [...this.jobs.values()].filter((j) => j.running && j.child);
+    if (runningJobs.length === 0) return;
+    for (const job of runningJobs) {
+      if (job.pid !== null) killProcessTree(job.pid, "SIGTERM");
+      else
+        try {
+          job.child?.kill("SIGTERM");
+        } catch {
+        }
+    }
+    const allClose = Promise.all(runningJobs.map((j) => j.readyPromise));
+    const elapsed = () => Date.now() - start;
+    const graceMs = Math.min(1500, Math.max(0, deadlineMs / 2));
+    await Promise.race([allClose, new Promise((res) => setTimeout(res, graceMs))]);
+    for (const job of runningJobs) {
+      if (!job.running) continue;
+      if (job.pid !== null) killProcessTree(job.pid, "SIGKILL");
+      else
+        try {
+          job.child?.kill("SIGKILL");
+        } catch {
+        }
+    }
+    const remaining = Math.max(800, deadlineMs - elapsed());
+    await Promise.race([allClose, new Promise((res) => setTimeout(res, remaining))]);
+  }
+  /** Count of still-running jobs — drives the TUI status-bar indicator. */
+  runningCount() {
+    let n = 0;
+    for (const job of this.jobs.values()) if (job.running) n++;
+    return n;
+  }
+};
+function snapshot(job) {
+  return {
+    id: job.id,
+    command: job.command,
+    pid: job.pid,
+    startedAt: job.startedAt,
+    exitCode: job.exitCode,
+    output: job.output,
+    totalBytesWritten: job.totalBytesWritten,
+    running: job.running,
+    spawnError: job.spawnError
+  };
+}
+
+// src/tools/shell.ts
 var DEFAULT_TIMEOUT_SEC = 60;
 var DEFAULT_MAX_OUTPUT_CHARS = 32e3;
 var BUILTIN_ALLOWLIST = [
@@ -4402,10 +4934,10 @@ async function runCommand(cmd, opts) {
   };
   const { bin, args, spawnOverrides } = prepareSpawn(argv);
   const effectiveSpawnOpts = { ...spawnOpts, ...spawnOverrides };
-  return await new Promise((resolve8, reject) => {
+  return await new Promise((resolve9, reject) => {
     let child;
     try {
-      child = spawn2(bin, args, effectiveSpawnOpts);
+      child = spawn3(bin, args, effectiveSpawnOpts);
     } catch (err) {
       reject(err);
       return;
@@ -4435,7 +4967,7 @@ async function runCommand(cmd, opts) {
       const output = buf.length > maxChars ? `${buf.slice(0, maxChars)}
 
 [\u2026 truncated ${buf.length - maxChars} chars \u2026]` : buf;
-      resolve8({ exitCode: code, output, timedOut });
+      resolve9({ exitCode: code, output, timedOut });
     });
   });
 }
@@ -4443,16 +4975,16 @@ function resolveExecutable(cmd, opts = {}) {
   const platform = opts.platform ?? process.platform;
   if (platform !== "win32") return cmd;
   if (!cmd) return cmd;
-  if (cmd.includes("/") || cmd.includes("\\") || pathMod2.isAbsolute(cmd)) return cmd;
-  if (pathMod2.extname(cmd)) return cmd;
+  if (cmd.includes("/") || cmd.includes("\\") || pathMod3.isAbsolute(cmd)) return cmd;
+  if (pathMod3.extname(cmd)) return cmd;
   const env = opts.env ?? process.env;
   const pathExt = (env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").map((e) => e.trim()).filter(Boolean);
-  const delimiter2 = opts.pathDelimiter ?? (platform === "win32" ? ";" : pathMod2.delimiter);
+  const delimiter2 = opts.pathDelimiter ?? (platform === "win32" ? ";" : pathMod3.delimiter);
   const pathDirs = (env.PATH ?? "").split(delimiter2).filter(Boolean);
   const isFile = opts.isFile ?? defaultIsFile;
   for (const dir of pathDirs) {
     for (const ext of pathExt) {
-      const full = pathMod2.win32.join(dir, cmd + ext);
+      const full = pathMod3.win32.join(dir, cmd + ext);
       if (isFile(full)) return full;
     }
   }
@@ -4522,8 +5054,8 @@ function withUtf8Codepage(cmdline) {
 function isBareWindowsName(s) {
   if (!s) return false;
   if (s.includes("/") || s.includes("\\")) return false;
-  if (pathMod2.isAbsolute(s)) return false;
-  if (pathMod2.extname(s)) return false;
+  if (pathMod3.isAbsolute(s)) return false;
+  if (pathMod3.extname(s)) return false;
   return true;
 }
 function quoteForCmdExe(arg) {
@@ -4542,12 +5074,13 @@ var NeedsConfirmationError = class extends Error {
   }
 };
 function registerShellTools(registry, opts) {
-  const rootDir = pathMod2.resolve(opts.rootDir);
+  const rootDir = pathMod3.resolve(opts.rootDir);
   const timeoutSec = opts.timeoutSec ?? DEFAULT_TIMEOUT_SEC;
   const maxOutputChars = opts.maxOutputChars ?? DEFAULT_MAX_OUTPUT_CHARS;
+  const jobs = opts.jobs ?? new JobRegistry();
   const getExtraAllowed = typeof opts.extraAllowed === "function" ? opts.extraAllowed : (() => {
-    const snapshot = opts.extraAllowed ?? [];
-    return () => snapshot;
+    const snapshot2 = opts.extraAllowed ?? [];
+    return () => snapshot2;
   })();
   const allowAll = opts.allowAll ?? false;
   registry.register({
@@ -4593,8 +5126,126 @@ function registerShellTools(registry, opts) {
       return formatCommandResult(cmd, result);
     }
   });
+  registry.register({
+    name: "run_background",
+    description: "Spawn a long-running process (dev server, watcher, any command that doesn't naturally exit) and detach. Waits up to `waitSec` seconds for startup (or until the output matches a readiness signal like 'Local:', 'listening on', 'compiled successfully'), then returns the job id + startup preview. The process keeps running; call `job_output` to tail its logs, `stop_job` to kill it, `list_jobs` to see all running jobs. USE THIS \u2014 not `run_command` \u2014 for: npm/yarn/pnpm run dev, uvicorn / flask run, go run, cargo watch, tsc --watch, webpack serve, anything with 'dev' / 'serve' / 'watch' in the name.",
+    parameters: {
+      type: "object",
+      properties: {
+        command: {
+          type: "string",
+          description: "Full command line. Same quoting rules as run_command (no pipes / redirects / chaining)."
+        },
+        waitSec: {
+          type: "integer",
+          description: "Max seconds to wait for startup before returning. 0..30, default 3. A ready-signal match short-circuits this."
+        }
+      },
+      required: ["command"]
+    },
+    fn: async (args, ctx) => {
+      const cmd = args.command.trim();
+      if (!cmd) throw new Error("run_background: empty command");
+      if (!allowAll && !isAllowed(cmd, getExtraAllowed())) {
+        throw new NeedsConfirmationError(cmd);
+      }
+      const result = await jobs.start(cmd, {
+        cwd: rootDir,
+        waitSec: args.waitSec,
+        signal: ctx?.signal
+      });
+      return formatJobStart(result);
+    }
+  });
+  registry.register({
+    name: "job_output",
+    description: "Read the latest output of a background job started with `run_background`. By default returns the tail of the buffer (last 80 lines). Pass `since` (the `byteLength` from a previous call) to stream only new content incrementally. Tells you whether the job is still running, so you can stop polling when it's done.",
+    readOnly: true,
+    parameters: {
+      type: "object",
+      properties: {
+        jobId: { type: "integer", description: "Job id returned by run_background." },
+        since: {
+          type: "integer",
+          description: "Return only output written past this byte offset (for incremental polling)."
+        },
+        tailLines: {
+          type: "integer",
+          description: "Cap the returned slice to the last N lines. Default 80, 0 = unlimited."
+        }
+      },
+      required: ["jobId"]
+    },
+    fn: async (args) => {
+      const out = jobs.read(args.jobId, {
+        since: args.since,
+        tailLines: args.tailLines ?? 80
+      });
+      if (!out) return `job ${args.jobId}: not found (use list_jobs)`;
+      return formatJobRead(args.jobId, out);
+    }
+  });
+  registry.register({
+    name: "stop_job",
+    description: "Stop a background job started with `run_background`. SIGTERM first; SIGKILL after a short grace period if it doesn't exit cleanly. Returns the final output + exit code. Safe to call on an already-exited job.",
+    parameters: {
+      type: "object",
+      properties: {
+        jobId: { type: "integer" }
+      },
+      required: ["jobId"]
+    },
+    fn: async (args) => {
+      const rec = await jobs.stop(args.jobId);
+      if (!rec) return `job ${args.jobId}: not found`;
+      return formatJobStop(rec);
+    }
+  });
+  registry.register({
+    name: "list_jobs",
+    description: "List every background job started this session \u2014 running and exited \u2014 with id, command, pid, status. Use when you've lost track of which job_id corresponds to which process, or to see what's still alive.",
+    readOnly: true,
+    parameters: { type: "object", properties: {} },
+    fn: async () => {
+      const all = jobs.list();
+      if (all.length === 0) return "(no background jobs started this session)";
+      return all.map(formatJobRow).join("\n");
+    }
+  });
   return registry;
 }
+function formatJobStart(r) {
+  const header = r.stillRunning ? `[job ${r.jobId} started \xB7 pid ${r.pid ?? "?"} \xB7 ${r.readyMatched ? "READY signal matched" : "running (no ready signal yet)"}]` : r.exitCode !== null ? `[job ${r.jobId} exited during startup \xB7 exit ${r.exitCode}]` : `[job ${r.jobId} failed to start]`;
+  return r.preview ? `${header}
+${r.preview}` : header;
+}
+function formatJobRead(jobId, r) {
+  const status = r.running ? `running \xB7 pid ${r.pid ?? "?"}` : r.exitCode !== null ? `exited ${r.exitCode}` : r.spawnError ? `failed (${r.spawnError})` : "stopped";
+  const header = `[job ${jobId} \xB7 ${status} \xB7 byteLength=${r.byteLength}]
+$ ${r.command}`;
+  return r.output ? `${header}
+${r.output}` : header;
+}
+function formatJobStop(r) {
+  const running = r.running ? "still running (SIGKILL may be pending)" : `exit ${r.exitCode ?? "?"}`;
+  const tail = tailLines(r.output, 40);
+  const header = `[job ${r.id} stopped \xB7 ${running}]
+$ ${r.command}`;
+  return tail ? `${header}
+${tail}` : header;
+}
+function formatJobRow(r) {
+  const age = ((Date.now() - r.startedAt) / 1e3).toFixed(1);
+  const state = r.running ? `running   \xB7  pid ${r.pid ?? "?"}` : r.exitCode !== null ? `exit ${r.exitCode}` : r.spawnError ? "failed" : "stopped";
+  return `  ${String(r.id).padStart(3)}  ${state.padEnd(24)}  ${age}s ago   $ ${r.command}`;
+}
+function tailLines(s, n) {
+  if (!s) return "";
+  const lines = s.split("\n");
+  if (lines.length <= n) return s;
+  const dropped = lines.length - n;
+  return [`[\u2026 ${dropped} earlier lines \u2026]`, ...lines.slice(-n)].join("\n");
+}
 function formatCommandResult(cmd, r) {
   const header = r.timedOut ? `$ ${cmd}
 [killed after timeout]` : `$ ${cmd}
@@ -4788,11 +5439,11 @@ ${i + 1}. ${r.title}`);
 
 // src/env.ts
 import { readFileSync as readFileSync8 } from "fs";
-import { resolve as resolve6 } from "path";
+import { resolve as resolve7 } from "path";
 function loadDotenv(path = ".env") {
   let raw;
   try {
-    raw = readFileSync8(resolve6(process.cwd(), path), "utf8");
+    raw = readFileSync8(resolve7(process.cwd(), path), "utf8");
   } catch {
     return;
   }
@@ -5474,7 +6125,7 @@ var McpClient = class {
     const id = this.nextId++;
     const frame = { jsonrpc: "2.0", id, method, params };
     let abortHandler = null;
-    const promise = new Promise((resolve8, reject) => {
+    const promise = new Promise((resolve9, reject) => {
       const timeout = setTimeout(() => {
         this.pending.delete(id);
         if (abortHandler && signal) signal.removeEventListener("abort", abortHandler);
@@ -5483,7 +6134,7 @@ var McpClient = class {
         );
       }, this.requestTimeoutMs);
       this.pending.set(id, {
-        resolve: resolve8,
+        resolve: resolve9,
         reject,
         timeout
       });
@@ -5565,7 +6216,7 @@ var McpClient = class {
 };
 
 // src/mcp/stdio.ts
-import { spawn as spawn3 } from "child_process";
+import { spawn as spawn4 } from "child_process";
 var StdioTransport = class {
   child;
   queue = [];
@@ -5580,14 +6231,14 @@ var StdioTransport = class {
         opts.command,
         ...(opts.args ?? []).map((a) => quoteArg(a, process.platform === "win32"))
       ].join(" ");
-      this.child = spawn3(line, [], {
+      this.child = spawn4(line, [], {
         env,
         cwd: opts.cwd,
         stdio: ["pipe", "pipe", "inherit"],
         shell: true
       });
     } else {
-      this.child = spawn3(opts.command, opts.args ?? [], {
+      this.child = spawn4(opts.command, opts.args ?? [], {
         env,
         cwd: opts.cwd,
         stdio: ["pipe", "pipe", "inherit"]
@@ -5606,12 +6257,12 @@ var StdioTransport = class {
   }
   async send(message) {
     if (this.closed) throw new Error("MCP transport is closed");
-    return new Promise((resolve8, reject) => {
+    return new Promise((resolve9, reject) => {
       const line = `${JSON.stringify(message)}
 `;
       this.child.stdin.write(line, "utf8", (err) => {
         if (err) reject(err);
-        else resolve8();
+        else resolve9();
       });
     });
   }
@@ -5622,8 +6273,8 @@ var StdioTransport = class {
         continue;
       }
       if (this.closed) return;
-      const next = await new Promise((resolve8) => {
-        this.waiters.push(resolve8);
+      const next = await new Promise((resolve9) => {
+        this.waiters.push(resolve9);
       });
       if (next === null) return;
       yield next;
@@ -5689,8 +6340,8 @@ var SseTransport = class {
   constructor(opts) {
     this.url = opts.url;
     this.headers = opts.headers ?? {};
-    this.endpointReady = new Promise((resolve8, reject) => {
-      this.resolveEndpoint = resolve8;
+    this.endpointReady = new Promise((resolve9, reject) => {
+      this.resolveEndpoint = resolve9;
       this.rejectEndpoint = reject;
     });
     this.endpointReady.catch(() => void 0);
@@ -5717,8 +6368,8 @@ var SseTransport = class {
         continue;
       }
       if (this.closed) return;
-      const next = await new Promise((resolve8) => {
-        this.waiters.push(resolve8);
+      const next = await new Promise((resolve9) => {
+        this.waiters.push(resolve9);
       });
       if (next === null) return;
       yield next;
@@ -5918,7 +6569,7 @@ async function trySection(load) {
 
 // src/code/edit-blocks.ts
 import { existsSync as existsSync9, mkdirSync as mkdirSync3, readFileSync as readFileSync10, unlinkSync as unlinkSync3, writeFileSync as writeFileSync3 } from "fs";
-import { dirname as dirname4, resolve as resolve7 } from "path";
+import { dirname as dirname4, resolve as resolve8 } from "path";
 var BLOCK_RE = /^(\S[^\n]*)\n<{7} SEARCH\n([\s\S]*?)\n?={7}\n([\s\S]*?)\n?>{7} REPLACE/gm;
 function parseEditBlocks(text) {
   const out = [];
@@ -5936,8 +6587,8 @@ function parseEditBlocks(text) {
   return out;
 }
 function applyEditBlock(block, rootDir) {
-  const absRoot = resolve7(rootDir);
-  const absTarget = resolve7(absRoot, block.path);
+  const absRoot = resolve8(rootDir);
+  const absTarget = resolve8(absRoot, block.path);
   if (absTarget !== absRoot && !absTarget.startsWith(`${absRoot}${sep()}`)) {
     return {
       path: block.path,
@@ -5987,13 +6638,13 @@ function applyEditBlocks(blocks, rootDir) {
   return blocks.map((b) => applyEditBlock(b, rootDir));
 }
 function snapshotBeforeEdits(blocks, rootDir) {
-  const absRoot = resolve7(rootDir);
+  const absRoot = resolve8(rootDir);
   const seen = /* @__PURE__ */ new Set();
   const snapshots = [];
   for (const b of blocks) {
     if (seen.has(b.path)) continue;
     seen.add(b.path);
-    const abs = resolve7(absRoot, b.path);
+    const abs = resolve8(absRoot, b.path);
     if (!existsSync9(abs)) {
       snapshots.push({ path: b.path, prevContent: null });
       continue;
@@ -6007,9 +6658,9 @@ function snapshotBeforeEdits(blocks, rootDir) {
   return snapshots;
 }
 function restoreSnapshots(snapshots, rootDir) {
-  const absRoot = resolve7(rootDir);
+  const absRoot = resolve8(rootDir);
   return snapshots.map((snap) => {
-    const abs = resolve7(absRoot, snap.path);
+    const abs = resolve8(absRoot, snap.path);
     if (abs !== absRoot && !abs.startsWith(`${absRoot}${sep()}`)) {
       return {
         path: snap.path,
@@ -6116,6 +6767,15 @@ In those cases, use tools to gather what you need, then reply in prose. No SEARC
 
 When you do propose edits, the user will review them and decide whether to \`/apply\` or \`/discard\`. Don't assume they'll accept \u2014 write as if each edit will be audited, because it will.
 
+Reasonix runs an **edit gate**. The user's current mode (\`review\` or \`auto\`) decides what happens to your writes; you DO NOT see which mode is active, and you SHOULD NOT ask. Write the same way in both cases.
+
+- In \`auto\` mode \`edit_file\` / \`write_file\` calls land on disk immediately with an undo window \u2014 you'll get the normal "edit blocks: 1/1 applied" style response.
+- In \`review\` mode EACH \`edit_file\` / \`write_file\` call pauses tool dispatch while the user decides. You'll get one of these responses:
+  - \`"edit blocks: 1/1 applied"\` \u2014 user approved it. Continue as normal.
+  - \`"User rejected this edit to <path>. Don't retry the same SEARCH/REPLACE\u2026"\` \u2014 user said no to THIS specific edit. Do NOT re-emit the same block, do NOT switch tools to sneak it past the gate (write_file \u2192 edit_file, or text-form SEARCH/REPLACE). Either take a clearly different approach or stop and ask the user what they want instead.
+  - Text-form SEARCH/REPLACE blocks in your assistant reply queue for end-of-turn /apply \u2014 same "don't retry on rejection" rule.
+- If the user presses Esc mid-prompt the whole turn is aborted; you won't get another tool response. Don't keep spamming tool calls after an abort.
+
 # Editing files
 
 When you've been asked to change a file, output one or more SEARCH/REPLACE blocks in this exact format:
@@ -6156,6 +6816,40 @@ Two different rules depending on which tool:
 - **Filesystem tools** (\`read_file\`, \`list_directory\`, \`search_files\`, \`edit_file\`, etc.): paths are sandbox-relative. \`/\` means the project root, \`/src/foo.ts\` means \`<project>/src/foo.ts\`. Both relative (\`src/foo.ts\`) and POSIX-absolute (\`/src/foo.ts\`) forms work.
 - **\`run_command\`**: the command runs in a real OS shell with cwd pinned to the project root. Paths inside the shell command are interpreted by THAT shell, not by us. **Never use leading \`/\` in run_command arguments** \u2014 Windows treats \`/tests\` as drive-root \`F:\\tests\` (non-existent), POSIX shells treat it as filesystem root. Use plain relative paths (\`tests\`, \`./tests\`, \`src/loop.ts\`) instead.
 
+# Foreground vs. background commands
+
+You have TWO tools for running shell commands, and picking the right one is non-negotiable:
+
+- \`run_command\` \u2014 blocks until the process exits. Use for: **tests, builds, lints, typechecks, git operations, one-shot scripts**. Anything that naturally returns in under a minute.
+- \`run_background\` \u2014 spawns and detaches after a brief startup window. Use for: **dev servers, watchers, any command with "dev" / "serve" / "watch" / "start" in the name**. Examples: \`npm run dev\`, \`pnpm dev\`, \`yarn start\`, \`vite\`, \`next dev\`, \`uvicorn app:app --reload\`, \`flask run\`, \`python -m http.server\`, \`cargo watch\`, \`tsc --watch\`, \`webpack serve\`.
+
+**Never use run_command for a dev server.** It will block for 60s, time out, and the user will see a frozen tool call while the server was actually running fine. Always \`run_background\`, then \`job_output\` to peek at the logs when you need to verify something.
+
+After \`run_background\`, tools available to you:
+- \`job_output(jobId, tailLines?)\` \u2014 read recent logs to verify startup / debug errors.
+- \`list_jobs\` \u2014 see every job this session (running + exited).
+- \`stop_job(jobId)\` \u2014 SIGTERM \u2192 SIGKILL after grace. Stop before switching port / config.
+
+Don't re-start an already-running dev server \u2014 call \`list_jobs\` first when in doubt.
+
+# Scope discipline on "run it" / "start it" requests
+
+When the user's request is to **run / start / launch / serve / boot up** something, your job is ONLY:
+
+1. Start it (\`run_background\` for dev servers, \`run_command\` for one-shots).
+2. Verify it came up (read a ready signal via \`job_output\`, or fetch the URL with \`web_fetch\` if they want you to confirm).
+3. Report what's running, where (URL / port / pid), and STOP.
+
+Do NOT, in the same turn:
+- Run \`tsc\` / type-checkers / linters unless the user asked for it.
+- Scan for bugs to "proactively" fix. The page rendering is success.
+- Clean up unused imports, dead code, or refactor "while you're here."
+- Edit files to improve anything the user didn't mention.
+
+If you notice an obvious issue, MENTION it in one sentence and wait for the user to say "fix it." The cost of over-eagerness is real: you burn tokens, make surprise edits the user didn't want, and chain into cascading "fix the new error I just introduced" loops. The storm-breaker will cut you off, but the user still sees the mess.
+
+"It works" is the end state. Resist the urge to polish.
+
 # Style
 
 - Show edits; don't narrate them in prose. "Here's the fix:" is enough.