muonroi-cli 1.2.3 → 1.3.2

package/src/storage/ui-interaction-log.ts

@@ -0,0 +1,160 @@
+/**
+ * src/storage/ui-interaction-log.ts
+ *
+ * Typed, fail-open helpers for persisting UI lifecycle events (askcard
+ * open/answered/cancel, sprint stage transitions, sprint halt, route
+ * decisions) into `interaction_logs` with event_type='ui_interaction'.
+ *
+ * The matching LiveEvent payloads are emitted to the harness sidechannel
+ * for E2E tests — these helpers persist the *same* events so that
+ * `/export` can render an Interaction Timeline section reconstructing
+ * what the user did (which option, which key, at what step).
+ *
+ * All calls are fire-and-forget — DB errors must never break the UI flow.
+ */
+
+import { logInteraction } from "./interaction-log.js";
+
+export type UIInteractionSubtype =
+  | "route_decision"
+  | "sprint_stage"
+  | "sprint_halt"
+  | "askcard_open"
+  | "askcard_answered"
+  | "askcard_cancel"
+  | "halt_card_open"
+  | "halt_card_answered"
+  | "init_new_step"
+  | "init_new_submitted"
+  | "init_new_result"
+  | "init_new_resume"
+  | "init_new_retry";
+
+interface RouteDecisionPayload {
+  path: "hot-path" | "council";
+  complexity: string;
+  forceCouncil: boolean;
+  /** PIL sufficiency gaps that forced the Council path (empty when complete). */
+  sufficiencyMissing?: readonly string[];
+  runId: string;
+}
+
+interface SprintStagePayload {
+  sprintIndex: number;
+  stage: "planning" | "implementation" | "verification" | "judgment";
+  runId: string;
+}
+
+interface SprintHaltPayload {
+  sprintN: number;
+  reason: string;
+  runId: string;
+}
+
+interface AskcardOpenPayload {
+  questionId: string;
+  question: string;
+  phase: string;
+  optionCount: number;
+  defaultIndex?: number;
+}
+
+interface AskcardAnsweredPayload {
+  questionId: string;
+  answerKind: string;
+  answerText: string;
+  /**
+   * The label of the chosen option as rendered to the user. Lets `usage
+   * forensics` and the export timeline answer "what was actually selected"
+   * without cross-referencing the matching askcard_open row — e.g. when
+   * answerText is "accept" the label still carries the underlying
+   * recommendation value ("Recommended: 'saas' — …").
+   */
+  selectedOptionLabel?: string;
+}
+
+interface AskcardCancelPayload {
+  questionId: string;
+}
+
+interface HaltCardOpenPayload {
+  reason: string;
+  optionCount: number;
+  optionIds: string[];
+}
+
+interface HaltCardAnsweredPayload {
+  chosenId: string;
+  chosenLabel: string;
+  index: number;
+}
+
+interface InitNewStepPayload {
+  from: string;
+  to: string;
+}
+
+interface InitNewSubmittedPayload {
+  projectName: string;
+  feStack: string;
+  bbTemplate: string | null;
+  packageCount: number;
+}
+
+interface InitNewResultPayload {
+  outcome: "done" | "error";
+  message: string;
+  usedDotnetTemplate?: boolean;
+  /**
+   * Plan 23-fix — true when this result came from a manual retry in the
+   * error state (no re-running of council debate). Lets forensics see
+   * how often the retry path fires vs first-attempt success.
+   */
+  viaRetry?: boolean;
+}
+
+interface InitNewResumePayload {
+  projectDir: string;
+  templateName: string;
+  originalPrompt: string;
+  /** Plan 23-fix — set when resume followed a retry rather than first scaffold. */
+  viaRetry?: boolean;
+}
+
+interface InitNewRetryPayload {
+  projectName: string;
+  feStack: string;
+  bbTemplate: string | null;
+}
+
+type Payload =
+  | { subtype: "route_decision"; data: RouteDecisionPayload }
+  | { subtype: "sprint_stage"; data: SprintStagePayload }
+  | { subtype: "sprint_halt"; data: SprintHaltPayload }
+  | { subtype: "askcard_open"; data: AskcardOpenPayload }
+  | { subtype: "askcard_answered"; data: AskcardAnsweredPayload }
+  | { subtype: "askcard_cancel"; data: AskcardCancelPayload }
+  | { subtype: "halt_card_open"; data: HaltCardOpenPayload }
+  | { subtype: "halt_card_answered"; data: HaltCardAnsweredPayload }
+  | { subtype: "init_new_step"; data: InitNewStepPayload }
+  | { subtype: "init_new_submitted"; data: InitNewSubmittedPayload }
+  | { subtype: "init_new_result"; data: InitNewResultPayload }
+  | { subtype: "init_new_resume"; data: InitNewResumePayload }
+  | { subtype: "init_new_retry"; data: InitNewRetryPayload };
+
+/**
+ * Persist a UI lifecycle event. Caller passes a discriminated payload so
+ * downstream consumers (export renderer, future analytics) can rely on a
+ * fixed shape per subtype without parsing free-form JSON.
+ */
+export function logUIInteraction(sessionId: string | undefined | null, payload: Payload): void {
+  if (!sessionId) return;
+  try {
+    logInteraction(sessionId, "ui_interaction", {
+      eventSubtype: payload.subtype,
+      data: payload.data as unknown as Record<string, unknown>,
+    });
+  } catch {
+    // Fail-open
+  }
+}

package/src/storage/usage.ts

@@ -33,6 +33,7 @@ export function recordUsageEvent(
   messageSeq?: number | null,
   pilActive = false,
   enrichmentDelta = 0,
+  providerOptionsShape: string | null = null,
 ): void {
   if (!usage) return;
 
@@ -48,8 +49,8 @@ export function recordUsageEvent(
     .prepare(`
     INSERT INTO usage_events (
       session_id, message_seq, source, model, input_tokens, output_tokens, total_tokens, cost_micros, created_at,
-      pil_active, enrichment_delta, cache_read_tokens, cache_creation_tokens
-    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      pil_active, enrichment_delta, cache_read_tokens, cache_creation_tokens, provider_options_shape
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
   `)
     .run(
       sessionId,
@@ -65,6 +66,7 @@ export function recordUsageEvent(
       enrichmentDelta,
       cacheReadTokens,
       cacheCreationTokens,
+      providerOptionsShape,
     );
 }
 

package/src/tools/bash.test.ts

@@ -314,6 +314,33 @@ describe("BashTool sandbox state", () => {
     expect(bash.getSandboxSettings()).toEqual({ allowNet: true, allowedHosts: ["api.openai.com"] });
   });
 
+  it("translates POSIX-style absolute paths in cd when shell is POSIX", async () => {
+    if (process.platform !== "win32") return;
+    const root = makeTempDir("muonroi-bash-cdposix-");
+    // Pretend the configured shell is bash (forces POSIX path translation in cd handler).
+    const bash = new BashTool(root, { shellSettings: { kind: "bash" } });
+    if (!bash.getResolvedShell().isPosix) return; // skip if no bash on this Windows host
+
+    const driveLetter = root.match(/^([A-Za-z]):/)?.[1]?.toLowerCase();
+    if (!driveLetter) return;
+    const posixPath = `/${driveLetter}${root.slice(2).replace(/\\/g, "/")}`;
+    const result = await bash.execute(`cd ${posixPath}`);
+    expect(result.success).toBe(true);
+    expect(bash.getCwd()).toBe(root);
+  });
+
+  it("strips trailing backslash from quoted cd target on Windows (E1 regression)", async () => {
+    if (process.platform !== "win32") return;
+    const root = makeTempDir("muonroi-bash-trailbs-");
+    const bash = new BashTool(os.tmpdir());
+    // Simulate: cd "C:\foo\bar\" && pwd  — the trailing \" is mis-parsed as
+    // escaped quote, leaving the path as "C:\foo\bar\". After the fix the
+    // trailing backslash is stripped and the directory resolves correctly.
+    const result = await bash.execute(`cd "${root}\\"`);
+    expect(result.success).toBe(true);
+    expect(bash.getCwd()).toBe(root);
+  });
+
   it("includes network status in tool description when allowNet is set", () => {
     const netOn = new BashTool("/repo", {
       sandboxMode: "shuru",

package/src/tools/bash.ts

@@ -1,5 +1,5 @@
 import { type ChildProcess, exec, spawn } from "child_process";
-import { createReadStream, createWriteStream } from "fs";
+import { createReadStream, createWriteStream, existsSync } from "fs";
 import { mkdtemp, rm, stat, unlink } from "fs/promises";
 import os from "os";
 import path from "path";
@@ -7,6 +7,7 @@ import { executeEventHooks } from "../hooks/index";
 import type { CwdChangedHookInput } from "../hooks/types";
 import type { ToolResult } from "../types/index";
 import type { SandboxMode, SandboxSettings } from "../utils/settings";
+import { posixToNative, type ResolvedShell, resolveShell, type ShellSettings } from "../utils/shell";
 
 const MAX_TAIL_BYTES = 8_192;
 const MAX_BACKGROUND_PROCESSES = 8;
@@ -26,6 +27,7 @@ export interface BackgroundProcess {
 interface BashToolOptions {
   sandboxMode?: SandboxMode;
   sandboxSettings?: SandboxSettings;
+  shellSettings?: ShellSettings;
 }
 
 let nextBgId = 1;
@@ -36,11 +38,15 @@ export class BashTool {
   private tmpDir: string | null = null;
   private sandboxMode: SandboxMode;
   private sandboxSettings: SandboxSettings;
+  private shellSettings: ShellSettings;
+  private resolvedShell: ResolvedShell;
 
   constructor(initialCwd = process.cwd(), options: BashToolOptions = {}) {
     this.cwd = initialCwd;
     this.sandboxMode = options.sandboxMode ?? "off";
     this.sandboxSettings = options.sandboxSettings ?? {};
+    this.shellSettings = options.shellSettings ?? {};
+    this.resolvedShell = resolveShell(this.shellSettings);
   }
 
   private async ensureTmpDir(): Promise<string> {
@@ -56,9 +62,17 @@ export class BashTool {
         const dir = command
           .substring(3)
           .trim()
-          .replace(/^["']|["']$/g, "");
+          .replace(/^["']|["']$/g, "")
+          // Strip a trailing backslash that was an escaped quote in the shell
+          // parse (e.g. cd "C:\foo\" && cmd → C:\foo). Only strip on Windows
+          // because on POSIX a trailing backslash is a valid path continuation.
+          .replace(process.platform === "win32" ? /\\$/ : /(?!x)x/, "");
         try {
-          const nextCwd = path.resolve(this.cwd, dir);
+          // Translate POSIX-style absolute paths (e.g. /d/sources/x, ~/foo)
+          // when the active shell understands them, so cwd tracking matches
+          // what the shell would actually resolve.
+          const translated = this.resolvedShell.isPosix ? posixToNative(dir) : dir;
+          const nextCwd = path.resolve(this.cwd, translated);
           const info = await stat(nextCwd);
           if (!info.isDirectory()) {
             return { success: false, error: `Cannot change directory: ${nextCwd} is not a directory` };
@@ -110,6 +124,10 @@ export class BashTool {
             timeout,
             maxBuffer: 10 * 1024 * 1024,
             env: { ...process.env, FORCE_COLOR: "0" },
+            // Route through the resolved shell so POSIX syntax
+            // (`2>&1 &`, `$()`, single-quotes, `&&` as logical AND, …)
+            // works on Windows instead of falling back to cmd.exe.
+            ...(this.resolvedShell.binary ? { shell: this.resolvedShell.binary } : {}),
           },
           (err, stdout, stderr) => {
             if (aborted || abortSignal?.aborted) {
@@ -191,11 +209,13 @@ export class BashTool {
       const logPath = path.join(tmpDir, `bg-${id}.log`);
       const logStream = createWriteStream(logPath, { flags: "a" });
 
-      const child = spawn("sh", ["-c", prepared.command], {
+      const { binary, args } = this.spawnInvocation(prepared.command);
+      const child = spawn(binary, args, {
         cwd: this.cwd,
         detached: false,
         stdio: ["ignore", "pipe", "pipe"],
         env: { ...process.env, FORCE_COLOR: "0" },
+        windowsHide: true,
       });
 
       child.stdout?.pipe(logStream);
@@ -369,6 +389,16 @@ export class BashTool {
     return this.cwd;
   }
 
+  setCwd(next: string): void {
+    if (!path.isAbsolute(next)) {
+      throw new Error(`setCwd: path must be absolute, got: ${next}`);
+    }
+    if (!existsSync(next)) {
+      throw new Error(`setCwd: path does not exist: ${next}`);
+    }
+    this.cwd = next;
+  }
+
   getSandboxMode(): SandboxMode {
     return this.sandboxMode;
   }
@@ -401,6 +431,32 @@ export class BashTool {
     return "Execute a bash command. Use for find, ls, git, build tools, package managers, running tests, and any other shell command. For content search, prefer the dedicated grep tool. Set background=true for long-running processes like dev servers, watchers, or anything that should keep running while you continue working. For file read/write/edit, prefer the dedicated file tools instead.";
   }
 
+  getResolvedShell(): ResolvedShell {
+    return this.resolvedShell;
+  }
+
+  private spawnInvocation(command: string): { binary: string; args: string[] } {
+    const shell = this.resolvedShell;
+    if (shell.binary) {
+      if (shell.kind === "wsl") {
+        return { binary: shell.binary, args: ["bash", "-lc", command] };
+      }
+      if (shell.kind === "powershell") {
+        return { binary: shell.binary, args: ["-NoProfile", "-NonInteractive", "-Command", command] };
+      }
+      if (shell.kind === "bash") {
+        return { binary: shell.binary, args: ["-lc", command] };
+      }
+      // cmd.exe or unknown
+      return { binary: shell.binary, args: ["/d", "/s", "/c", command] };
+    }
+    // No explicit binary: rely on platform default the same way exec() does.
+    if (process.platform === "win32") {
+      return { binary: process.env.ComSpec || "cmd.exe", args: ["/d", "/s", "/c", command] };
+    }
+    return { binary: "/bin/sh", args: ["-c", command] };
+  }
+
   private prepareCommand(command: string): { ok: true; command: string } | { ok: false; error: string } {
     if (this.sandboxMode !== "shuru") {
       return { ok: true, command };

package/src/tools/file-tracker.test.ts

@@ -0,0 +1,99 @@
+import { readFile as fsRead, writeFile as fsWrite, mkdtemp, rm } from "fs/promises";
+import os from "os";
+import path from "path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { editFile, readFile, writeFile } from "./file";
+import { FileTracker } from "./file-tracker";
+
+vi.mock("../lsp/runtime", () => ({
+  summarizeDiagnostics: () => "",
+  syncFileWithLsp: async () => [],
+}));
+
+const tempDirs: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(tempDirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })));
+});
+
+async function createTempDir(): Promise<string> {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "muonroi-tracker-"));
+  tempDirs.push(dir);
+  return dir;
+}
+
+describe("FileTracker — read-before-write guard", () => {
+  it("rejects edit on an existing file that was not read first", async () => {
+    const cwd = await createTempDir();
+    await fsWrite(path.join(cwd, "demo.ts"), "const a = 1;\n", "utf8");
+    const tracker = new FileTracker();
+
+    const result = await editFile("demo.ts", "1", "2", cwd, tracker);
+
+    expect(result.success).toBe(false);
+    expect(result.output).toMatch(/must be read first/i);
+  });
+
+  it("rejects overwrite on an existing file that was not read first", async () => {
+    const cwd = await createTempDir();
+    await fsWrite(path.join(cwd, "demo.ts"), "old\n", "utf8");
+    const tracker = new FileTracker();
+
+    const result = await writeFile("demo.ts", "new\n", cwd, tracker);
+
+    expect(result.success).toBe(false);
+    expect(result.output).toMatch(/must be read first/i);
+  });
+
+  it("allows creating a new file without a prior read", async () => {
+    const cwd = await createTempDir();
+    const tracker = new FileTracker();
+
+    const result = await writeFile("brand-new.ts", "fresh\n", cwd, tracker);
+
+    expect(result.success).toBe(true);
+    expect(await fsRead(path.join(cwd, "brand-new.ts"), "utf8")).toBe("fresh\n");
+  });
+
+  it("allows edit after a read of the same file", async () => {
+    const cwd = await createTempDir();
+    await fsWrite(path.join(cwd, "demo.ts"), "const a = 1;\n", "utf8");
+    const tracker = new FileTracker();
+
+    readFile("demo.ts", cwd, undefined, undefined, tracker);
+    const result = await editFile("demo.ts", "1", "2", cwd, tracker);
+
+    expect(result.success).toBe(true);
+    expect(await fsRead(path.join(cwd, "demo.ts"), "utf8")).toBe("const a = 2;\n");
+  });
+
+  it("rejects edit when file changed on disk after the read (hash mismatch)", async () => {
+    const cwd = await createTempDir();
+    const filePath = path.join(cwd, "demo.ts");
+    await fsWrite(filePath, "const a = 1;\n", "utf8");
+    const tracker = new FileTracker();
+
+    readFile("demo.ts", cwd, undefined, undefined, tracker);
+    // Simulate external modification.
+    await fsWrite(filePath, "const a = 99;\n", "utf8");
+
+    const result = await editFile("demo.ts", "99", "100", cwd, tracker);
+
+    expect(result.success).toBe(false);
+    expect(result.output).toMatch(/changed on disk/i);
+  });
+
+  it("allows back-to-back edits without re-reading (write refreshes tracker)", async () => {
+    const cwd = await createTempDir();
+    await fsWrite(path.join(cwd, "demo.ts"), "1 2 3\n", "utf8");
+    const tracker = new FileTracker();
+
+    readFile("demo.ts", cwd, undefined, undefined, tracker);
+    const r1 = await editFile("demo.ts", "1", "A", cwd, tracker);
+    const r2 = await editFile("demo.ts", "2", "B", cwd, tracker);
+
+    expect(r1.success).toBe(true);
+    expect(r2.success).toBe(true);
+    expect(await fsRead(path.join(cwd, "demo.ts"), "utf8")).toBe("A B 3\n");
+  });
+});

package/src/tools/file-tracker.ts

@@ -0,0 +1,70 @@
+import { createHash } from "crypto";
+
+/**
+ * Per-session guard that enforces "read before edit/overwrite" semantics
+ * (mirrors Claude Code's safety rule). Prevents the LLM from blindly
+ * overwriting files whose current content it has not seen — and from
+ * stomping on changes another process made between read and write.
+ *
+ * The tracker keys on the absolute, normalized file path. It stores a
+ * SHA-256 of the content at read time; on write, the on-disk content is
+ * re-hashed and compared. A mismatch means the file changed externally
+ * since the last read, and the write is rejected.
+ *
+ * New-file creation is allowed without a prior read (there is nothing to
+ * read). After every successful write/edit, the tracker is refreshed so
+ * back-to-back edits in the same session keep working.
+ */
+export interface ReadRecord {
+  hash: string;
+  mtimeMs: number;
+}
+
+export class FileTracker {
+  private records = new Map<string, ReadRecord>();
+
+  /** Record content as known to the agent. Called after a successful read. */
+  markRead(absolutePath: string, content: string, mtimeMs: number): void {
+    this.records.set(absolutePath, { hash: hashOf(content), mtimeMs });
+  }
+
+  /** True if the file has been recorded as read this session. */
+  hasRead(absolutePath: string): boolean {
+    return this.records.has(absolutePath);
+  }
+
+  /**
+   * Verify a write to an EXISTING file is safe. Returns null when the write
+   * may proceed, or a human-readable error message otherwise.
+   */
+  checkBeforeWrite(absolutePath: string, currentContent: string): string | null {
+    const rec = this.records.get(absolutePath);
+    if (!rec) {
+      return (
+        `File must be read first: ${absolutePath}. ` +
+        `Use the read_file tool to load the current content, then retry the edit/write.`
+      );
+    }
+    if (rec.hash !== hashOf(currentContent)) {
+      return (
+        `File has changed on disk since last read: ${absolutePath}. ` +
+        `Re-read it with read_file to see the current content, then retry.`
+      );
+    }
+    return null;
+  }
+
+  /** Drop the record (e.g. file was deleted). */
+  forget(absolutePath: string): void {
+    this.records.delete(absolutePath);
+  }
+
+  /** Drop everything (e.g. on /clear). */
+  reset(): void {
+    this.records.clear();
+  }
+}
+
+function hashOf(s: string): string {
+  return createHash("sha256").update(s).digest("hex");
+}

package/src/tools/file.ts

@@ -1,8 +1,9 @@
 import { createTwoFilesPatch } from "diff";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "fs";
 import { dirname, isAbsolute, resolve } from "path";
 import { summarizeDiagnostics, syncFileWithLsp } from "../lsp/runtime";
 import type { LspDiagnosticFile } from "../lsp/types";
+import type { FileTracker } from "./file-tracker.js";
 
 export interface FileDiff {
   filePath: string;
@@ -38,7 +39,21 @@ function computeDiff(filePath: string, before: string, after: string): FileDiff
   return { filePath, additions, removals, patch, isNew: before === "" };
 }
 
-export function readFile(filePath: string, cwd: string, startLine?: number, endLine?: number): FileResult {
+function mtimeMsOf(absolutePath: string): number {
+  try {
+    return statSync(absolutePath).mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+
+export function readFile(
+  filePath: string,
+  cwd: string,
+  startLine?: number,
+  endLine?: number,
+  tracker?: FileTracker,
+): FileResult {
   try {
     const full = resolvePath(filePath, cwd);
     if (!existsSync(full)) {
@@ -52,6 +67,10 @@ export function readFile(filePath: string, cwd: string, startLine?: number, endL
     const end = Math.min(totalLines, endLine ?? totalLines);
     const slice = lines.slice(start, end);
 
+    // Track FULL content (not just the slice) so partial reads still satisfy
+    // the read-before-write guard against the on-disk file as a whole.
+    tracker?.markRead(full, content, mtimeMsOf(full));
+
     const numbered = slice.map((line, i) => `${start + i + 1} | ${line}`).join("\n");
     const header = `[${filePath}: lines ${start + 1}-${end} of ${totalLines}]`;
     return { success: true, output: `${header}\n${numbered}` };
@@ -61,14 +80,33 @@ export function readFile(filePath: string, cwd: string, startLine?: number, endL
   }
 }
 
-export async function writeFile(filePath: string, content: string, cwd: string): Promise<FileResult> {
+export async function writeFile(
+  filePath: string,
+  content: string,
+  cwd: string,
+  tracker?: FileTracker,
+): Promise<FileResult> {
   try {
     const full = resolvePath(filePath, cwd);
-    const before = existsSync(full) ? readFileSync(full, "utf-8") : "";
+    const exists = existsSync(full);
+    const before = exists ? readFileSync(full, "utf-8") : "";
+
+    // Safety: existing files must have been read first AND unchanged on disk
+    // since that read. New files (no prior content) skip the guard.
+    if (exists && tracker) {
+      const violation = tracker.checkBeforeWrite(full, before);
+      if (violation) {
+        return { success: false, output: violation };
+      }
+    }
+
     const dir = dirname(full);
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
     writeFileSync(full, content, "utf-8");
 
+    // Refresh tracker so subsequent edits in the same session don't refuse.
+    tracker?.markRead(full, content, mtimeMsOf(full));
+
     const diff = computeDiff(filePath, before, content);
     const verb = before === "" ? "Created" : "Updated";
     const lspDiagnostics = await syncFileWithLsp(cwd, full, content, true, true).catch(() => [] as LspDiagnosticFile[]);
@@ -90,6 +128,7 @@ export async function editFile(
   oldString: string,
   newString: string,
   cwd: string,
+  tracker?: FileTracker,
 ): Promise<FileResult> {
   try {
     const full = resolvePath(filePath, cwd);
@@ -97,10 +136,22 @@ export async function editFile(
       return { success: false, output: `File not found: ${filePath}` };
     }
     const before = readFileSync(full, "utf-8");
+
+    // Safety: edit always requires a prior read of the current on-disk version.
+    if (tracker) {
+      const violation = tracker.checkBeforeWrite(full, before);
+      if (violation) {
+        return { success: false, output: violation };
+      }
+    }
+
     const count = before.split(oldString).length - 1;
 
     if (count === 0) {
-      return { success: false, output: `old_string not found in ${filePath}` };
+      return {
+        success: false,
+        output: `old_string not found in ${filePath}. Re-read the file with read_file before retrying to get the current content.`,
+      };
     }
     if (count > 1) {
       return {
@@ -112,6 +163,9 @@ export async function editFile(
     const after = before.replace(oldString, newString);
     writeFileSync(full, after, "utf-8");
 
+    // Refresh tracker so back-to-back edits keep working.
+    tracker?.markRead(full, after, mtimeMsOf(full));
+
     const diff = computeDiff(filePath, before, after);
     const lspDiagnostics = await syncFileWithLsp(cwd, full, after, true, true).catch(() => [] as LspDiagnosticFile[]);
     const lspSummary = summarizeDiagnostics(lspDiagnostics);

package/src/tools/registry.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vitest";
+import { MAX_TOOL_OUTPUT_CHARS, truncateOutput } from "./registry.js";
+
+describe("truncateOutput", () => {
+  it("returns input unchanged when under cap", () => {
+    const text = "a".repeat(100);
+    expect(truncateOutput(text)).toBe(text);
+  });
+
+  it("preserves head and tail when over cap", () => {
+    const big = "X".repeat(MAX_TOOL_OUTPUT_CHARS + 5_000);
+    const out = truncateOutput(big);
+    expect(out.length).toBeLessThan(big.length);
+    expect(out.startsWith("X")).toBe(true);
+    expect(out.endsWith("X")).toBe(true);
+    expect(out).toContain("chars truncated");
+    expect(out).toContain("full output in transcript");
+  });
+
+  it("honors custom maxChars", () => {
+    const big = "Y".repeat(2_000);
+    const out = truncateOutput(big, 500);
+    expect(out.length).toBeLessThan(big.length);
+    expect(out).toContain("chars truncated");
+  });
+
+  it("exports a cap within the documented range", () => {
+    expect(MAX_TOOL_OUTPUT_CHARS).toBeGreaterThanOrEqual(10_000);
+    expect(MAX_TOOL_OUTPUT_CHARS).toBeLessThanOrEqual(200_000);
+  });
+
+  it("truncation marker accounts for full delta", () => {
+    const big = "Z".repeat(100_000);
+    const out = truncateOutput(big, 10_000);
+    const expectedDelta = 100_000 - 10_000;
+    expect(out).toContain(`${expectedDelta} chars truncated`);
+  });
+});