tokenmaw 0.3.0 → 0.4.0

package/README.md

@@ -17,7 +17,10 @@ Inside the TUI:
 - `/model` selects the default model for the current session.
 - `/agents` shows the effective Agent Specs and their sources.
 - `/sessions` switches sessions; `/new` creates one.
+- `/cd <path>` switches the working directory (relative paths resolve against the current one). The status bar always shows the current directory; `/cd` with no argument or `/pwd` prints it. Switching reloads the project's `.coder/agents` specs and `AGENTS.md`, and tool path authorization follows the new root.
+- `!<command>` runs a shell command directly in the current workspace, outside the agent loop: the prompt turns into `$` and the command text is highlighted while typing, the command and its output stream inline into the conversation transcript (never sent to the model or fed back into context), long-running commands animate their ellipsis, and `Ctrl+C` stops a running command. `/`-commands stay reserved for the built-in slash commands.
 - `Ctrl+K` opens the command palette.
+- `/worktree <name>` creates (or reopens) an isolated git worktree under `.coder/worktrees/<name>` on branch `maw/<name>` and moves this session into it, so parallel sessions stop colliding on one working tree. `/worktree-list` shows status, `/worktree-exit` returns to the main checkout (the worktree stays on disk), `/worktree-remove <name>` drops a clean worktree (the branch is never deleted). A `.worktreeinclude` file copies gitignored files (e.g. `.env`) into new worktrees. Non-interactive equivalent: `maw --worktree [name]`.
 - `Ctrl+B` toggles Agent Activity.
 - `Ctrl+J` or `Alt+Enter` inserts a newline; `Enter` sends. Chinese text wraps by terminal width.
 - `Up` / `Down` browse input history; `Ctrl+U` clears the draft.
@@ -28,7 +31,11 @@ Inside the TUI:
 - `F2` (or `/select`) optionally releases app mouse capture for the terminal's native selection. `F2` again restores app clicks, drag selection and wheel scrolling. `Ctrl+Y` and `PageUp` / `PageDown` also work without the mouse.
 - `Ctrl+X` or `/cancel` stops the current session's agents; send another message to continue.
 - `/compact` summarizes and archives older context of the main agent; an optional argument focuses the digest (e.g. `/compact file changes and pending work`).
-- `Ctrl+C` exits. Runtime errors appear in the conversation.
+- `/aside <note>` queues a side note without starting a turn; it folds into the next message you send and is announced in the conversation stream.
+- `/btw <question>` opens a side conversation forked from the current session (full context included) and sends your question there. `/back` or `Ctrl+C` returns to the main conversation; side sessions are marked `[side]` in the status bar and the `/sessions` list.
+- `/fork` copies the current conversation into a new saved session. `/sessions` lists both; the original stays untouched.
+- `/goal <text>` sets a standing goal for the session: it is injected into every agent's prompt until cleared, shows in the status bar, and survives across sessions. `/goal clear` removes it.
+- `Ctrl+C` copies a selection; without a selection it arms a quit confirmation — press again within 2 seconds to exit. Inside a side conversation, `Ctrl+C` returns to the parent session instead. Runtime errors appear in the conversation.
 
 For a non-interactive run:
 
@@ -49,7 +56,7 @@ Interactive mode requires a terminal. Non-interactive runs report agent failures
 
 ## Architecture
 
-The user talks to `main`, whose primary responsibility is responsive conversation and coordination. Execution tasks, including saving an HTML page, are delegated to coordinators by default; coordinators select specialists. Main yields after handing off work and is automatically resumed by agent results. Its broad tool access remains available for bounded checks and fallback, subject to the configured workspace policy. The scheduler reserves user-facing capacity independently of the background concurrency limit.
+The user talks to `main`, whose primary responsibility is responsive conversation and forward progress. Main handles small, local, and well-scoped work directly. It delegates only genuinely multi-file, ambiguous, or independently parallel work; coordinators select specialists only when that extra coordination is useful. Main remains available while background work runs and is resumed by verified agent results. The scheduler reserves user-facing capacity independently of the background concurrency limit.
 
 ```text
 user ↔ main → coordinator(s) → explorer / implement / review / custom agents
@@ -102,6 +109,20 @@ Specs can reduce capabilities but cannot bypass global tool policy, path boundar
 - New user input interrupts only main's current generation. Background agents keep running until main explicitly redirects or cancels them.
 - Only main output enters the user-visible conversation.
 - Sessions and instances persist under `~/.coder/runtime/` and recover after restart.
+- Each turn records requests, input/output tokens, provider-reported cached input, and first-token latency when the backend supplies them. The status bar shows the session aggregate.
+- `AGENT_MAX_CHILDREN_PER_TURN` limits fan-out (default `3`); `AGENT_MAX_CONCURRENT_TURNS` and `AGENT_MAX_DEPTH` provide additional scheduler guardrails.
+
+### Multi-process safety
+
+Multiple `maw` processes can run against the same project without silently destroying each other's work:
+
+- **Cross-process write locks** — every file write (`edit_file`, `write_file`) and every session is guarded by an O_EXCL lock file under `~/.coder/runtime/locks/`. Lock records carry the holder pid and process start time, so a lock left by a crashed process is detected and taken over automatically, while a live holder is reported by pid (`AGENT_SESSION_LOCK_TIMEOUT_MS` adjusts the session-lock wait, default 5s).
+- **Optimistic conflict detection** — `edit_file` re-verifies inside the lock that the file still matches what the edit was based on; `write_file` refuses to overwrite a file that changed after it was read in this session. Changes from external editors or other tooling surface as explicit errors instead of silent lost updates.
+- **Single writer per session** — opening a session another process is writing succeeds in read-only mode (the status bar shows `[read-only pid <n>]`); submissions, `/goal`, and `/clear` are refused with guidance. `/fork` continues from that point in a writable copy, and once the other writer exits, the session self-heals back to writable on the next message.
+- **Concurrent instance awareness** — live instances register under `~/.coder/runtime/instances/`; the status bar warns when other maw processes share the workspace.
+- **Managed worktrees** — for genuine parallelism, `/worktree <name>` (or `maw --worktree [name]`) isolates each session in its own checkout so conflicts become ordinary merges. Worktrees are `git worktree lock`ed while a session uses them; cleanup removes clean, unlocked ones and never touches dirty checkouts or branches.
+
+Provider prompt caching is used when the provider supports it: runtime system prefixes stay stable and live sibling state travels through mailboxes instead of being re-injected into every request. Cross-request response caching is intentionally avoided because coding answers depend on the current workspace and tool results.
 
 ### Context compaction
 

package/agents/coordinator.md

@@ -7,7 +7,6 @@ agents:
   - '*'
 ---
 
-You coordinate a complex workstream for the parent agent. Understand the goal, inspect the available agent catalog, and decide your own workflow. Delegate concrete work to the smallest useful set of specialist agents. Use parallel agents only when their work is independent. Send corrections to an existing instance instead of spawning duplicates.
-
-You do not talk to the user. Report meaningful progress, blockers, and the final integrated result to your parent. Verify claims using specialist results and do not report completion without evidence appropriate to the request. If user input is required, explain the exact decision and choices to the parent agent.
+You coordinate a complex workstream for the parent agent. Understand the goal and choose the smallest workflow that can finish it. Start with one focused explorer or implementer; add another agent only when its work is independent and necessary. As soon as the root cause and edit location are clear, stop exploration and implement. Reuse existing instances instead of spawning duplicates.
 
+You do not talk to the user. Report concise progress to your parent: conclusion, evidence, changed paths, and next action. Do not paste large tool outputs. Verify claims with focused checks and do not report completion without evidence. If user input is required, explain the exact decision and choices to the parent agent. Stop or cancel redundant agents once one result resolves the question.

package/agents/main.md

@@ -10,9 +10,9 @@ agents:
 
 You are TokenMaw's user-facing main agent. You are the only agent that talks to the user.
 
-Your primary responsibility is responsiveness to the user, not doing all the work yourself. Answer conversational questions directly. For requests involving implementation, file creation, investigation, research, or verification, briefly acknowledge the concrete task and delegate execution to a coordinator by default, including small tasks such as saving an HTML page. Give it the user's objective, target paths, constraints, and acceptance checks. Do not perform a long sequence of execution tools before delegating.
+Your primary responsibility is responsiveness and forward progress. Answer conversational questions directly. Handle small, local, or well-scoped fixes yourself with the available tools. Delegate only when the task is genuinely multi-file, ambiguous, or benefits from independent parallel work. Never create a coordinator merely to inspect one or two files. When delegating, give one concrete objective, target paths, constraints, and acceptance checks.
 
-Delegation is asynchronous: after assigning work, finish your current response so you remain available to the user. Child results automatically wake you through your mailbox; do not repeatedly call wait_agent or poll status. A handoff acknowledgement is not a completion claim. When the user sends a follow-up, respond promptly and forward relevant changes to the existing coordinator without restarting unrelated background work.
+Delegation is asynchronous: after assigning work, remain available to the user. Child results automatically wake you through your mailbox; do not repeatedly call wait_agent or poll status. A handoff acknowledgement is not a completion claim. When evidence is sufficient, stop further exploration and implement or ask the existing worker to implement. Never restart an equivalent workstream for a follow-up.
 
 Your broad tool access is a fallback capability, not the default workflow. Use tools directly for a brief necessary clarification or evidence check, when the user explicitly requests your direct execution, or when delegation is unavailable or has failed. Keep such work bounded and explain a material fallback.
 

package/dist/backend.js

@@ -89,7 +89,11 @@ async function* ollamaStream(config, systemPrompt, messages, tools, signal) {
                 yield { content: null, toolCalls: obj.message.tool_calls, done: false };
             }
             if (obj.done) {
-                yield { content: null, done: true };
+                const stats = obj;
+                yield { content: null, done: true, usage: (stats.prompt_eval_count !== undefined || stats.eval_count !== undefined) ? {
+                        inputTokens: stats.prompt_eval_count,
+                        outputTokens: stats.eval_count,
+                    } : undefined };
                 return;
             }
         }
@@ -200,6 +204,7 @@ async function* openaiStream(config, systemPrompt, messages, tools, signal) {
         model: config.model,
         stream: true,
         messages: convertToOpenAIMessages(systemPrompt, messages),
+        stream_options: { include_usage: true },
     };
     applyOpenAIRequestOptions(body, config);
     const openaiTools = convertToolsToOpenAI(tools);
@@ -245,6 +250,13 @@ async function* openaiStream(config, systemPrompt, messages, tools, signal) {
                 continue;
             try {
                 const parsed = JSON.parse(trimmed.slice(6));
+                if (parsed.usage)
+                    yield { content: null, done: false, usage: {
+                            inputTokens: parsed.usage.prompt_tokens,
+                            outputTokens: parsed.usage.completion_tokens,
+                            cachedInputTokens: parsed.usage.prompt_tokens_details?.cached_tokens,
+                            reasoningTokens: parsed.usage.completion_tokens_details?.reasoning_tokens,
+                        } };
                 const choice = parsed.choices?.[0];
                 if (!choice)
                     continue;
@@ -495,6 +507,24 @@ async function* anthropicStream(config, systemPrompt, messages, tools, signal) {
                     yield { content: null, toolCalls: [toolCall], done: false };
                     continue;
                 }
+                if (event === 'message_start' && (parsed.message?.usage?.input_tokens !== undefined)) {
+                    const usage = parsed.message.usage;
+                    yield { content: null, done: false, usage: {
+                            inputTokens: usage.input_tokens,
+                            cachedInputTokens: usage.cache_read_input_tokens,
+                            cacheCreationInputTokens: usage.cache_creation_input_tokens,
+                        } };
+                }
+                if (event === 'message_delta' && parsed.usage) {
+                    const usage = parsed.usage;
+                    if (usage.output_tokens !== undefined || usage.cache_read_input_tokens !== undefined || usage.cache_creation_input_tokens !== undefined) {
+                        yield { content: null, done: false, usage: {
+                                outputTokens: usage.output_tokens,
+                                cachedInputTokens: usage.cache_read_input_tokens,
+                                cacheCreationInputTokens: usage.cache_creation_input_tokens,
+                            } };
+                    }
+                }
                 if (event === 'message_stop') {
                     yield { content: null, done: true };
                     return;

package/dist/cli.js

@@ -6,6 +6,8 @@ import { resolveModelConfig } from './model-config.js';
 import { defaultPolicy } from './policy.js';
 import { AgentRegistry } from './runtime/agent-registry.js';
 import { AgentRuntime } from './runtime/agent-runtime.js';
+import { WorktreeManager } from './runtime/worktree.js';
+import { registerWorkspaceInstance } from './runtime/workspace-instances.js';
 import { runFullscreenTui } from './ui/fullscreen-tui.js';
 import { CODER_VERSION } from './version.js';
 async function main() {
@@ -13,6 +15,7 @@ async function main() {
     program.name('maw').description('Document-driven coding agent runtime').version(CODER_VERSION);
     program.allowExcessArguments(false).showSuggestionAfterError();
     program.option('--model <name>', 'default model name or .agentrc alias');
+    program.option('--worktree [name]', 'start inside an isolated managed git worktree (.coder/worktrees/<name>)');
     let config = await loadConfig();
     const selectedFromCli = () => program.opts().model;
     setToolPolicy(defaultPolicy(config.policyLevel ?? 'moderate', process.cwd()));
@@ -23,6 +26,19 @@ async function main() {
         defaultModel: selectedFromCli() ?? config.model,
         resolveModel: (alias) => resolveModelConfig(config, alias).config,
     });
+    // Announce this instance so concurrent maw processes in the same workspace
+    // can surface a warning (and users can see who else is editing).
+    const stopInstanceHeartbeat = await registerWorkspaceInstance(process.cwd());
+    // /cd moves the runtime to a new workspace root; the tool policy must follow
+    // so read/write authorization keeps covering the new tree.
+    runtime.subscribe((event) => {
+        if (event.type !== 'workspace_changed')
+            return;
+        setToolPolicy(defaultPolicy(config.policyLevel ?? 'moderate', event.workspaceRoot));
+        void registerWorkspaceInstance(event.workspaceRoot).then((stop) => {
+            void stopInstanceHeartbeat().then(stop);
+        });
+    });
     const configManager = {
         getConfig: () => config,
         saveConfig: async (next) => {
@@ -73,6 +89,19 @@ async function main() {
         if (!process.stdin.isTTY || !process.stdout.isTTY)
             throw new Error('Interactive mode requires a terminal. Use maw run --prompt "..." for non-interactive execution.');
         await runtime.whenReady();
+        const worktreeArg = program.opts().worktree;
+        if (worktreeArg !== undefined) {
+            const manager = new WorktreeManager(process.cwd());
+            if (!await manager.isGitRepository()) {
+                console.error('--worktree requires a git repository');
+                process.exitCode = 1;
+                return;
+            }
+            const name = typeof worktreeArg === 'string' && worktreeArg.trim() ? worktreeArg.trim() : `session-${Date.now()}`;
+            const info = await manager.create(name);
+            await runtime.changeWorkspace(info.path);
+            process.stdout.write(`worktree ready: ${info.path} (${info.branch})\n`);
+        }
         const requested = selectedFromCli();
         const selected = resolveModelConfig(config, requested);
         runtime.setDefaultModel(requested ?? config.model);
@@ -90,6 +119,7 @@ async function main() {
     });
     const shutdown = async () => {
         await runtime.shutdown().catch(() => undefined);
+        await stopInstanceHeartbeat().catch(() => undefined);
         process.exit(0);
     };
     process.once('SIGTERM', () => { void shutdown(); });

package/dist/infra/tools.js

@@ -1,6 +1,6 @@
 import { readFile, writeFile, readdir, mkdir, stat, rename, rm } from 'node:fs/promises';
 import { createHash, randomUUID } from 'node:crypto';
-import { exec, execFile } from 'node:child_process';
+import { exec, execFile, spawn } from 'node:child_process';
 import { promisify } from 'node:util';
 import { basename, dirname, extname, isAbsolute, join, relative, resolve } from 'node:path';
 import { ToolRegistry } from '../tools/registry.js';
@@ -63,6 +63,36 @@ async function writeViaWorkspace(targetPath, content, ctx) {
     await atomicWrite(absoluteTarget, content);
     return absoluteTarget;
 }
+/**
+ * Staged, all-or-nothing write: content goes to a staging file next to the
+ * target, is verified from disk, and only then is atomically swapped in via
+ * rename. The target is never observable in a partially written or unverified
+ * state, and any failure (including failed readback verification) leaves the
+ * target byte-for-byte unchanged — no post-failure restore pass needed.
+ */
+async function stagedWrite(path, content, ctx, verify) {
+    const absoluteTarget = resolveWriteTarget(path, ctx);
+    const root = workspaceRoot(ctx);
+    const rel = absoluteTarget.startsWith(root)
+        ? relative(root, absoluteTarget)
+        : join('__external__', absoluteTarget.replace(/^([a-zA-Z]:)?[/\\]+/, ''));
+    const workspacePath = join(root, '.agent-workspace', rel);
+    const staging = `${absoluteTarget}.${process.pid}.${randomUUID()}.staging`;
+    await mkdir(dirname(absoluteTarget), { recursive: true });
+    try {
+        await writeFile(staging, content, 'utf8');
+        const written = await readFile(staging, 'utf8');
+        await verify(written);
+        await mkdir(dirname(workspacePath), { recursive: true });
+        await atomicWrite(workspacePath, content);
+        await rename(staging, absoluteTarget);
+    }
+    catch (error) {
+        await rm(staging, { force: true }).catch(() => undefined);
+        throw error;
+    }
+    return absoluteTarget;
+}
 async function atomicWrite(path, content) {
     const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
     await writeFile(temp, content, 'utf8');
@@ -196,6 +226,54 @@ function closestLineHints(content, search) {
         return hints;
     return lineNumbersOf(content, firstLine.slice(0, 24), 3);
 }
+function normalizedForSimilarity(value) {
+    return value.replace(/\r\n/g, '\n').replace(/[\t ]+/g, ' ').trim();
+}
+function editDistance(a, b) {
+    if (a === b)
+        return 0;
+    if (!a.length)
+        return b.length;
+    if (!b.length)
+        return a.length;
+    let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i += 1) {
+        const current = [i];
+        for (let j = 1; j <= b.length; j += 1) {
+            current[j] = Math.min(current[j - 1] + 1, previous[j] + 1, previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        previous = current;
+    }
+    return previous[b.length];
+}
+function closestMatch(content, search) {
+    const requested = search.split('\n');
+    const lines = content.split('\n');
+    const count = requested.length;
+    if (!search.trim() || !lines.length)
+        return undefined;
+    let best;
+    for (let i = 0; i <= lines.length - count; i += 1) {
+        const matched = lines.slice(i, i + count).join('\n');
+        const left = normalizedForSimilarity(search);
+        const right = normalizedForSimilarity(matched);
+        const max = Math.max(left.length, right.length, 1);
+        const similarity = 1 - editDistance(left, right) / max;
+        if (!best || similarity > best.similarity)
+            best = { line: i + 1, matched, similarity };
+    }
+    return best;
+}
+function diagnosticDiff(requested, matched) {
+    const requestedLines = requested.split('\n');
+    const matchedLines = matched.split('\n');
+    const lines = ['```diff', '- requested'];
+    lines.push(...requestedLines.map((line) => `- ${line}`));
+    lines.push('+ matched');
+    lines.push(...matchedLines.map((line) => `+ ${line}`));
+    lines.push('```');
+    return lines.join('\n');
+}
 function stripReadFileLineNumbers(search) {
     const lines = search.split('\n');
     const contentLines = lines.filter((line) => !line.startsWith('... (showing lines '));
@@ -258,7 +336,17 @@ export function getToolPolicy() {
     return clonePolicy(defaultToolPolicy);
 }
 async function withWriteLock(ctx, path, action) {
-    const release = await ctx?.acquireWriteLock?.(path);
+    if (!ctx) {
+        // Bare toolkit call without a runtime context (direct library use): no
+        // lock service exists to consult. Documented as unlocked.
+        return action();
+    }
+    if (!ctx.acquireWriteLock) {
+        // Never write unlocked when a runtime context is present: a silent
+        // unlocked write would lose updates against concurrent processes.
+        throw new Error(`write lock unavailable for ${path}: the runtime context did not provide acquireWriteLock; refusing unlocked write`);
+    }
+    const release = await ctx.acquireWriteLock(path);
     try {
         return await action();
     }
@@ -535,8 +623,7 @@ function parseStringArray(value) {
         return undefined;
     }
 }
-async function readLineRange(filePath, offset = 1, limit) {
-    const raw = await readFile(filePath, 'utf8');
+function formatLineRange(raw, offset = 1, limit) {
     if (raw === '')
         return '';
     const allLines = raw.split('\n');
@@ -548,11 +635,17 @@ async function readLineRange(filePath, offset = 1, limit) {
         ? `${numbered}\n... (showing lines ${startLine}-${endLine} of ${totalLines}; use offset/limit to read more)`
         : numbered;
 }
+async function readLineRange(filePath, offset = 1, limit) {
+    return formatLineRange(await readFile(filePath, 'utf8'), offset, limit);
+}
 function boundedOutput(value, maxChars = 4 * 1024 * 1024) {
     if (value.length <= maxChars)
         return value;
     return `${value.slice(0, maxChars)}\n... (output truncated at ${maxChars} characters)`;
 }
+function contentVersion(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
 // ── Pure-Node search fallback (used when `rg` is not installed) ──────────────
 // Mirrors the rg invocations in `search_text`/`search_files`: hidden files are
 // included, only `.git` and `node_modules` are skipped.
@@ -934,7 +1027,10 @@ async function executeBuiltinTool(name, args, ctx) {
             const offsetArg = typeof args['offset'] === 'number' ? args['offset'] : undefined;
             const limitArg = typeof args['limit'] === 'number' ? args['limit'] : undefined;
             try {
-                return await readLineRange(resolveToolPath(path, ctx), offsetArg, limitArg);
+                const targetPath = resolveToolPath(path, ctx);
+                const content = await readFile(targetPath, 'utf8');
+                ctx?.recordReadVersion?.(targetPath, contentVersion(content));
+                return formatLineRange(content, offsetArg, limitArg);
             }
             catch (error) {
                 return `Error reading file: ${String(error)}`;
@@ -955,7 +1051,10 @@ async function executeBuiltinTool(name, args, ctx) {
                     continue;
                 }
                 try {
-                    sections.push(`===== ${path} =====\n${await readLineRange(resolveToolPath(path, ctx), 1, maxLines)}`);
+                    const targetPath = resolveToolPath(path, ctx);
+                    const content = await readFile(targetPath, 'utf8');
+                    ctx?.recordReadVersion?.(targetPath, contentVersion(content));
+                    sections.push(`===== ${path} =====\n${formatLineRange(content, 1, maxLines)}`);
                 }
                 catch (error) {
                     sections.push(`===== ${path} =====\nError reading file: ${String(error)}`);
@@ -1006,6 +1105,16 @@ async function executeBuiltinTool(name, args, ctx) {
                 catch (error) {
                     return `Error reading file for edit: ${String(error)}`;
                 }
+                const currentVersion = contentVersion(src);
+                if (ctx?.requirePriorRead) {
+                    const readVersion = ctx.getReadVersion?.(targetPath);
+                    if (!readVersion) {
+                        return `Error: edit_file requires a prior read_file of ${path} in this session. Read the file, then retry the edit.`;
+                    }
+                    if (readVersion !== currentVersion) {
+                        return `Error: edit_file read lease is stale for ${path}; the file changed after it was read. Read it again before editing.`;
+                    }
+                }
                 let parsed;
                 try {
                     if (Array.isArray(editsArg)) {
@@ -1022,13 +1131,18 @@ async function executeBuiltinTool(name, args, ctx) {
                 catch (error) {
                     return `Error parsing edits JSON: ${String(error)}`;
                 }
-                const noMatchError = (index, search) => {
-                    const hints = closestLineHints(src, search);
+                const noMatchError = (index, search, haystack = content) => {
+                    const hints = closestLineHints(haystack, search);
                     const hint = hints.length > 0 ? `\nFirst line of the search loosely appears near lines: ${hints.join(', ')}.` : '';
-                    return `Error: edit[${index}]: Could not find old text in ${path}. It must match exactly, including whitespace, indentation, and line endings.\nSearch string was:\n${search}${hint}`;
+                    const closest = closestMatch(haystack, search);
+                    const detail = closest
+                        ? `\nClosest normalized window: lines ${closest.line}-${closest.line + search.split('\n').length - 1} (similarity ${closest.similarity.toFixed(3)}).\n${diagnosticDiff(search, closest.matched)}`
+                        : '';
+                    return `Error: edit[${index}]: Could not find old text in ${path}. It must match exactly, including whitespace, indentation, and line endings.\nSearch string was:\n${search}${hint}${detail}\nNext action: resubmit the exact matched text.`;
                 };
                 let content = src;
                 const log = [];
+                const diagnostics = [];
                 const applied = [];
                 for (let i = 0; i < parsed.length; i += 1) {
                     const entry = parsed[i];
@@ -1047,10 +1161,12 @@ async function executeBuiltinTool(name, args, ctx) {
                     const numberedSearch = stripReadFileLineNumbers(search);
                     const unescapedSearch = unescapeEscapes(search);
                     const variants = [search];
-                    if (numberedSearch !== undefined && numberedSearch !== search && !variants.includes(numberedSearch))
-                        variants.push(numberedSearch);
-                    if (unescapedSearch !== search && !variants.includes(unescapedSearch))
-                        variants.push(unescapedSearch);
+                    if (!replaceAll) {
+                        if (numberedSearch !== undefined && numberedSearch !== search && !variants.includes(numberedSearch))
+                            variants.push(numberedSearch);
+                        if (unescapedSearch !== search && !variants.includes(unescapedSearch))
+                            variants.push(unescapedSearch);
+                    }
                     if (replaceAll) {
                         let usedVariant;
                         let count = 0;
@@ -1096,33 +1212,52 @@ async function executeBuiltinTool(name, args, ctx) {
                     content = content.replace(matched, effectiveReplace);
                     applied.push({ search: matched, replace: effectiveReplace, made: 1 });
                     const normalizedLineNumbers = numberedSearch !== undefined && matchedVariant === numberedSearch;
-                    log.push(`edit[${i}]: replaced ${matched.length} chars via ${outcome.strategy}${normalizedLineNumbers ? ' (line-number normalized)' : ''}`);
+                    log.push(`edit[${i}]: replaced ${matched.length} chars via ${outcome.strategy}${normalizedLineNumbers ? ' (line-number normalized)' : ''}${outcome.strategy === 'exact' ? '' : ' [non-exact; use exact text next time]'}`);
+                    if (outcome.strategy !== 'exact' || normalizedLineNumbers) {
+                        diagnostics.push(`edit[${i}] matched span vs requested (strategy: ${outcome.strategy}${normalizedLineNumbers ? ', line-number normalized' : ''}):\n${diagnosticDiff(search, matched)}`);
+                    }
                 }
                 if (content === src) {
                     return `OK: no changes made to ${path}${log.length > 0 ? ` (${log.join('; ')})` : ''}`;
                 }
+                // Optimistic conflict check: while holding the write lock, confirm the
+                // file on disk still matches the content these edits were based on.
+                // The cross-process lock excludes other runtime processes, so a
+                // mismatch means an external writer (editor, script) touched the file
+                // between our read and this write — refuse instead of clobbering it.
                 try {
-                    const writtenPath = await writeViaWorkspace(path, content, ctx);
-                    const written = await readFile(writtenPath, 'utf8');
-                    for (const edit of applied) {
-                        if (edit.replace === '') {
-                            if (countOccurrences(written, edit.search) !== 0) {
-                                return `Error: readback verification failed for ${path}: deleted text is still present after write.`;
+                    const fresh = await readFile(targetPath, 'utf8');
+                    if (contentVersion(fresh) !== currentVersion) {
+                        return `Error: ${path} changed underneath this edit (modified by another process after it was read). No changes were applied. Read the file again and retry with fresh content.`;
+                    }
+                }
+                catch {
+                    return `Error: ${path} could not be re-read before applying edits (it may have been deleted externally). No changes were applied.`;
+                }
+                try {
+                    const writtenPath = await stagedWrite(path, content, ctx, (written) => {
+                        for (const edit of applied) {
+                            if (edit.replace === '') {
+                                if (countOccurrences(written, edit.search) !== 0) {
+                                    throw new Error(`readback verification failed for ${path}: deleted text is still present after write.`);
+                                }
+                            }
+                            else if (countOccurrences(written, edit.replace) < edit.made) {
+                                throw new Error(`readback verification failed for ${path}: expected at least ${edit.made} occurrence(s) of the replaced text in the written file.`);
                             }
                         }
-                        else if (countOccurrences(written, edit.replace) < edit.made) {
-                            return `Error: readback verification failed for ${path}: expected at least ${edit.made} occurrence(s) of the replaced text in the written file.`;
-                        }
-                    }
+                    });
                     await gitAutoCommit(writtenPath, `edit: ${path} (${applied.length} change${applied.length === 1 ? '' : 's'})`, ctx);
                     const diff = unifiedDiff(path, src, content);
-                    const sha256 = createHash('sha256').update(written).digest('hex').slice(0, 12);
+                    const sha256 = createHash('sha256').update(content).digest('hex').slice(0, 12);
+                    ctx?.recordWriteVersion?.(targetPath, contentVersion(content));
                     const linesBefore = src.split('\n').length;
-                    const linesAfter = written.split('\n').length;
-                    return [`OK: ${log.join('; ')} (${writtenPath}); ${linesBefore} → ${linesAfter} lines; sha256:${sha256}`, diff].filter(Boolean).join('\n\n');
+                    const linesAfter = content.split('\n').length;
+                    return [`OK: ${log.join('; ')} (${writtenPath}); ${linesBefore} → ${linesAfter} lines; sha256:${sha256}`, diagnostics.join('\n\n'), diff].filter(Boolean).join('\n\n');
                 }
                 catch (error) {
-                    return `Error writing edited file: ${String(error)}`;
+                    const message = error instanceof Error ? error.message : String(error);
+                    return `Error writing edited file: ${message} (target left unchanged)`;
                 }
             });
         }
@@ -1170,6 +1305,15 @@ async function executeBuiltinTool(name, args, ctx) {
                     catch {
                         previous = '';
                     }
+                    // Stale-read check: when this session read the file before and it has
+                    // since changed (another process wrote it), a blind overwrite would
+                    // silently destroy that work. Force a fresh read + retry instead.
+                    if (ctx?.requirePriorRead && existed) {
+                        const readVersion = ctx.getReadVersion?.(targetPath);
+                        if (readVersion && readVersion !== contentVersion(previous)) {
+                            return `Error: ${path} changed after it was read in this session (another process may have written it). Read the file again, then retry write_file.`;
+                        }
+                    }
                     const snapshot = existed ? await snapshotBeforeWrite(targetPath, workspaceRoot(ctx)) : { path: null };
                     const writtenPath = await writeViaWorkspace(path, content, ctx);
                     await gitAutoCommit(writtenPath, `write: ${path}`, ctx);
@@ -1298,3 +1442,105 @@ export function listTools(options = {}) {
 export async function executeTool(name, args, ctx) {
     return toolRegistry.execute(name, args, ctx);
 }
+/** Spawn a command without a shell layer around it, wired for incremental
+ * output: stdout/stderr chunks arrive through callbacks as the process runs,
+ * and `signal` (or the runtime timeout) kills the process tree. */
+function shellSpawn(file, args, options) {
+    return new Promise((resolveExit) => {
+        let settled = false;
+        const settle = (code, signal) => {
+            if (settled)
+                return;
+            settled = true;
+            resolveExit({ code, signal });
+        };
+        let spawnError;
+        const child = spawn(file, args, {
+            cwd: options.cwd,
+            signal: options.signal,
+            windowsVerbatimArguments: options.windowsVerbatimArguments,
+            env: process.env,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        child.stdout?.on('data', (chunk) => options.onStdout(chunk.toString('utf8')));
+        child.stderr?.on('data', (chunk) => options.onStderr(chunk.toString('utf8')));
+        child.on('error', (error) => {
+            spawnError = error;
+            // Spawn failures (missing shell, bad cwd) behave like a 127 exit.
+            settle(error.code === 'ENOENT' ? 127 : 1, undefined);
+        });
+        child.on('close', (code, signal) => {
+            if (spawnError)
+                return;
+            settle(code ?? undefined, signal ?? undefined);
+        });
+    });
+}
+/** Run a user-typed `!command` directly in a shell, bypassing the agent loop
+ * and tool policy entirely: the user is the authorizer. Output is streamed to
+ * the TUI via `onChunk` (stdout and stderr interleaved as they arrive), and
+ * `abort` kills the process tree. Like a normal shell, a nonzero exit code is
+ * not an error for the caller — the exit code rides in the result. */
+export function runShellCommand(command, options) {
+    const timeoutMs = Math.max(100, Math.min(Number(options.timeoutMs ?? 300_000), 600_000));
+    const nl = String.fromCharCode(10);
+    const maxChars = 16 * 1024 * 1024;
+    return new Promise((resolveShell) => {
+        const argv0 = process.platform === 'win32'
+            ? { file: process.env.ComSpec ?? 'cmd.exe', args: ['/d', '/s', '/c', command], verbatim: true }
+            : { file: '/bin/sh', args: ['-c', command], verbatim: false };
+        const controller = new AbortController();
+        if (options.signal) {
+            if (options.signal.aborted)
+                controller.abort(options.signal.reason);
+            else
+                options.signal.addEventListener('abort', () => controller.abort(), { once: true });
+        }
+        let output = '';
+        let truncated = false;
+        let timedOut = false;
+        let settled = false;
+        const push = (text) => {
+            if (!text)
+                return;
+            const room = maxChars - output.length;
+            if (room <= 0) {
+                truncated = true;
+                return;
+            }
+            output += text.length > room ? text.slice(0, room) : text;
+            if (text.length > room)
+                truncated = true;
+            options.onChunk?.(text);
+        };
+        const settle = (exitCode, note) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolveShell({ output: `${output}${truncated ? `${nl}(output truncated)` : ''}${note ?? ''}`, exitCode });
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, timeoutMs);
+        timer.unref?.();
+        void shellSpawn(argv0.file, argv0.args, {
+            cwd: options.workspaceRoot,
+            signal: controller.signal,
+            windowsVerbatimArguments: argv0.verbatim,
+            onStdout: push,
+            onStderr: push,
+        }).then(({ code, signal }) => {
+            if (timedOut) {
+                settle(undefined, `${nl}Error: command timed out`);
+                return;
+            }
+            if (controller.signal.aborted || signal) {
+                settle(undefined, `${nl}(stopped)`);
+                return;
+            }
+            settle(code ?? 0);
+        });
+    });
+}