atom-agent 1.0.0 → 1.2.0

package/dist/agent/normalize.js

@@ -0,0 +1,151 @@
+import { truncateHead } from "../tools/shared.js";
+// Safety net for custom executors (built-in tools already cap: read 64KB
+// head + truncation note + overflow pointer ≈ 66KB, bash 8KB, webfetch 64KB
+// + notes). The cap sits at 128KB so legitimate built-in outputs (overflow
+// pointers included) pass through byte-identical; only oversized custom
+// results truncate.
+export const TOOL_RESULT_CAP_CHARS = 128 * 1024;
+export function normalizeToolResult(result) {
+    let text;
+    if (typeof result === "string") {
+        text = result;
+    }
+    else if (result === null || result === undefined) {
+        return "Error: tool returned no result";
+    }
+    else {
+        try {
+            const json = JSON.stringify(result);
+            text = typeof json === "string" ? json : String(result);
+        }
+        catch {
+            try {
+                text = String(result);
+            }
+            catch {
+                return "Error: tool returned an unreadable result";
+            }
+        }
+    }
+    if (text.length > TOOL_RESULT_CAP_CHARS) {
+        const t = truncateHead(text, TOOL_RESULT_CAP_CHARS, `\n[truncated: tool result exceeded ${TOOL_RESULT_CAP_CHARS} chars]`);
+        return t.head + t.note;
+    }
+    return text;
+}
+// Recursively key-sorted JSON for stable signatures. Falls back to a short
+// type tag when unstringifiable (never throws, never aliases objects with
+// strings: prefixes the tag).
+function stableStringify(value) {
+    try {
+        return JSON.stringify(sortKeys(value)) ?? "undefined";
+    }
+    catch {
+        return `unstringifiable:${typeof value}`;
+    }
+}
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (typeof value === "object" && value !== null) {
+        const out = {};
+        for (const k of Object.keys(value).sort()) {
+            out[k] = sortKeys(value[k]);
+        }
+        return out;
+    }
+    return value;
+}
+// Stable repetition/cache key: `name` + canonical args. Parsed args come
+// from JSON.parse (insertion-ordered), so sorting closes the alias where
+// `{"a":1,"b":2}` and `{"b":2,"a":1}` would otherwise count as different.
+export function toolSignature(name, parsed) {
+    return `${name} ${stableStringify(parsed ?? {})}`;
+}
+// Defensive validation of one assistant message. Never throws: malformed
+// tool_calls entries are dropped with a warning (the caller surfaces them
+// via onWarning so the transcript shows what the model attempted); a fully
+// unusable message becomes empty final text (the loop's turn-end gates then
+// decide, exactly as if the model sent empty content).
+export function normalizeChatResult(raw) {
+    const warnings = [];
+    if (typeof raw !== "object" || raw === null) {
+        return { result: { content: null }, warnings: ["model returned a non-object message"] };
+    }
+    const m = raw;
+    const contentRaw = m["content"];
+    const content = typeof contentRaw === "string"
+        ? contentRaw
+        : contentRaw === null || contentRaw === undefined
+            ? null
+            : (() => {
+                try {
+                    return JSON.stringify(contentRaw);
+                }
+                catch {
+                    return String(contentRaw);
+                }
+            })();
+    const callsRaw = m["calls"] ?? m["tool_calls"];
+    if (callsRaw === undefined) {
+        const result = { content };
+        if (m["usage"] !== undefined)
+            result["usage"] = m["usage"];
+        if (m["reasoning"] !== undefined)
+            result["reasoning"] = m["reasoning"];
+        // Length-truncation flag survives normalization (no calls or not — the
+        // loop decides; truncated-without-calls behaves as before).
+        if (m["truncated"] === true)
+            result.truncated = true;
+        return { result: result, warnings };
+    }
+    if (!Array.isArray(callsRaw)) {
+        warnings.push("model tool_calls was not an array — ignored");
+        return { result: { content, tool_calls: undefined }, warnings };
+    }
+    const calls = [];
+    for (let i = 0; i < callsRaw.length; i++) {
+        const entry = callsRaw[i];
+        if (typeof entry !== "object" || entry === null) {
+            warnings.push(`dropped malformed tool call at index ${i} (not an object)`);
+            continue;
+        }
+        const fn = entry["function"];
+        const name = fn?.["name"];
+        if (typeof name !== "string" || name.length === 0) {
+            const id = typeof entry["id"] === "string" ? entry["id"] : `#${i}`;
+            warnings.push(`dropped tool call ${id} with no function name`);
+            continue;
+        }
+        const id = typeof entry["id"] === "string" && entry["id"].length > 0
+            ? entry["id"]
+            : `call-${i}`;
+        const argsRaw = fn?.["arguments"];
+        let args;
+        if (typeof argsRaw === "string")
+            args = argsRaw;
+        else if (argsRaw === undefined || argsRaw === null)
+            args = "{}";
+        else {
+            try {
+                args = JSON.stringify(argsRaw) ?? "{}";
+            }
+            catch {
+                warnings.push(`dropped tool call ${id} with unstringifiable arguments`);
+                continue;
+            }
+        }
+        const call = { id, function: { name, arguments: args } };
+        if (typeof entry["type"] === "string")
+            call.type = entry["type"];
+        calls.push(call);
+    }
+    const out = { content, tool_calls: calls.length > 0 ? calls : undefined };
+    if (m["usage"] !== undefined)
+        out["usage"] = m["usage"];
+    if (m["reasoning"] !== undefined)
+        out["reasoning"] = m["reasoning"];
+    if (m["truncated"] === true)
+        out.truncated = true;
+    return { result: out, warnings };
+}

package/dist/cli.js

@@ -60,7 +60,7 @@ Env:
   OPENAI_API_KEY / ANTHROPIC_API_KEY / DEEPSEEK_API_KEY / MISTRAL_API_KEY / GEMINI_API_KEY (GOOGLE_API_KEY alias)  optional per provider (env wins over stored)
   OPENCODE_ZEN_MODEL    optional (default: ${DEFAULT_MODEL}; when set, wins over the saved /model)
   OPENCODE_ZEN_ENDPOINT optional (default: ${DEFAULT_ENDPOINT})
-Commands: /model (model picker) | /models [refresh] (local discovery refresh; Kilo catalog refresh when Kilo is active) | /provider (provider + key picker) | /effort (reasoning-effort picker) | /tools | /skills (list installed skills) | /skill:name (invoke) | /context (context usage) | /queue + /steer (follow-ups while busy) | /mode | /clear | /resume (restore last saved session) | /help | /exit | /quit — Tab cycles the permission mode normal → yolo → plan
+ Commands: /model (model picker) | /models [refresh] (local discovery refresh; Kilo catalog refresh when Kilo is active) | /provider (provider + key picker) | /effort (reasoning-effort picker) | /tools | /skills (list installed skills) | /skill:name (invoke) | /context (context usage) | /queue + /steer (follow-ups while busy) | /autoscroll (toggle follow new output) | /thinking (toggle reasoning visibility) | /mode | /clear | /new (fresh conversation, previous kept) | /rename <name> (rename current session) | /session (switch session picker) | /resume (restore last saved session) | /help | /exit | /quit — Tab cycles the permission mode normal → yolo → plan
 Providers: kilo (default; anonymous free models, key optional)/opencode-zen/openai/anthropic/deepseek/mistral/google-gemini/openai-compatible (keys in ~/.atom/auth.json, 0600 POSIX; use /provider to paste one) + local auto-discovery: ollama (:11434), lmstudio (:1234), llamacpp (:8080) — no keys needed, overrides via ATOM_OLLAMA_URL/ATOM_LMSTUDIO_URL/ATOM_LLAMACPP_URL.
 Note: reasoning_effort is sent only for opencode-zen supported models.`);
     process.exit(0);
@@ -86,5 +86,19 @@ const envModel = process.env.OPENCODE_ZEN_MODEL?.trim() || undefined;
 // --serve parks above (the server holds the event loop), so the TUI must
 // never start alongside it: serve is a standalone mode like --dashboard.
 if (!args.includes("--serve")) {
-    render(_jsx(App, { apiKey: apiKey, endpoint: endpoint, initialModel: envModel, restorePrefs: true }));
+    // Production frame policy (Ink 7.1.1):
+    // - incrementalRendering: only changed terminal lines rewrite per frame.
+    //   Streaming paints touch the live tail + status bar, not the scrollback,
+    //   so this cuts flicker and stdout bytes on every token flush.
+    //   Escape hatch: ATOM_INCREMENTAL=0 restores full-frame rendering.
+    // - maxFps: 30 keeps keystroke-to-paint latency low; token paints already
+    //   coalesce to ~15fps via DRAFT_THROTTLE_MS, so Ink never does extra work.
+    // - concurrent: enables React concurrent features (useTransition /
+    //   useDeferredValue) for future deferral of expensive subtrees.
+    // Tests are unaffected: they render via ink-testing-library, not here.
+    render(_jsx(App, { apiKey: apiKey, endpoint: endpoint, initialModel: envModel, restorePrefs: true }), {
+        incrementalRendering: process.env.ATOM_INCREMENTAL !== "0",
+        maxFps: 30,
+        concurrent: true,
+    });
 }

package/dist/compact.js

@@ -20,6 +20,7 @@ import { chatCompletionForProvider, } from "./zen.js";
 // ContextManager module; compact.ts imports what its splitter needs and
 // re-exports the stable surface so existing importers keep working untouched.
 import { estimateTokensForChars, messageChars } from "./context-manager.js";
+import { truncateHead } from "./tools/shared.js";
 export { COMPACT_PCT_DEFAULT, compactPct, computeContextLoad, estimateTokensForChars, historyChars, shouldAutoCompact, } from "./context-manager.js";
 // ---- Constants ----
 export const COMPACT_KEEP_TOKENS = 8000;
@@ -62,10 +63,12 @@ function turnChars(history, start, end) {
 export function capToolOutputsInTail(tail) {
     return tail.map((m) => {
         if (m.role === "tool" && typeof m.content === "string" && m.content.length > COMPACT_TOOL_OUTPUT_CAP) {
+            // Line-aware cap (issue 04): the retained head never ends mid-line;
+            // cap value and legacy note prefix are unchanged.
+            const t = truncateHead(m.content, COMPACT_TOOL_OUTPUT_CAP, "\n[truncated: tool output exceeded 2000 chars]");
             return {
                 ...m,
-                content: m.content.slice(0, COMPACT_TOOL_OUTPUT_CAP) +
-                    "\n[truncated: tool output exceeded 2000 chars]",
+                content: t.head + t.note,
             };
         }
         return { ...m };
@@ -233,3 +236,126 @@ export async function requestCompactSummary(req) {
         }
     }
 }
+function pushUniquePath(list, p) {
+    if (p.length === 0 || list.includes(p))
+        return;
+    list.push(p);
+}
+// Collect read/modified paths from committed tool_calls in head (insertion
+// order, unique). Unparseable arguments are skipped — a bad payload must
+// never break compaction. A path both read and written lands in modified
+// only (the write implies the read).
+export function collectTouchedFiles(head) {
+    const read = [];
+    const modified = [];
+    for (const m of head) {
+        if (m?.role !== "assistant")
+            continue;
+        const calls = m.tool_calls;
+        if (!Array.isArray(calls))
+            continue;
+        for (const c of calls) {
+            const fn = c?.function;
+            if (typeof fn?.name !== "string")
+                continue;
+            let p = "";
+            try {
+                const args = typeof fn.arguments === "string" ? JSON.parse(fn.arguments) : null;
+                const raw = args?.path;
+                if (typeof raw === "string")
+                    p = raw.trim();
+            }
+            catch {
+                continue; // unparseable args pin nothing
+            }
+            if (p.length === 0)
+                continue;
+            if (fn.name === "write" || fn.name === "edit")
+                pushUniquePath(modified, p);
+            else if (fn.name === "read")
+                pushUniquePath(read, p);
+        }
+    }
+    // Modified implies read: keep modified entries out of the read list.
+    const modifiedSet = new Set(modified);
+    return { read: read.filter((p) => !modifiedSet.has(p)), modified };
+}
+// Canonical on-disk + on-resume format. Empty sections are omitted; both
+// empty renders "" (the caller then appends nothing).
+export function formatTouchedFiles(t) {
+    const lines = ["Touched files:"];
+    if (t.read.length > 0)
+        lines.push(`Read: ${t.read.join(", ")}`);
+    if (t.modified.length > 0)
+        lines.push(`Modified: ${t.modified.join(", ")}`);
+    return lines.length > 1 ? lines.join("\n") : "";
+}
+export function appendTouchedFiles(summaryText, touched) {
+    const block = formatTouchedFiles(touched);
+    if (!block)
+        return summaryText;
+    return `${summaryText}\n\n${block}`;
+}
+// ---- Size budget for the summary message ----
+// The summary text itself is never cut — only the file lists shrink to fit,
+// so an over-budget summary degrades gracefully instead of failing
+// compaction. Budget = the summary output cap via the 4ch/token estimator.
+export const COMPACT_SUMMARY_MAX_CHARS = COMPACT_SUMMARY_MAX_TOKENS * COMPACT_CHARS_PER_TOKEN;
+// Shrink the lists until the formatted block fits maxChars. Drops the oldest
+// entry from the longer list (ties: read first — modifications are the
+// higher-signal list). Never throws; an empty result formats to "".
+export function truncateTouchedFiles(touched, maxChars) {
+    const read = [...touched.read];
+    const modified = [...touched.modified];
+    while ((read.length > 0 || modified.length > 0) &&
+        formatTouchedFiles({ read, modified }).length > maxChars) {
+        if (read.length >= modified.length)
+            read.shift();
+        else
+            modified.shift();
+    }
+    return { read, modified };
+}
+// Append file lists to the summary within budget: shrink the lists (never
+// the model text) until summary + block fits; when nothing fits, the summary
+// stands alone and compaction still succeeds.
+export function fitSummaryWithFiles(summaryText, touched, maxChars = COMPACT_SUMMARY_MAX_CHARS) {
+    const before = touched.read.length + touched.modified.length;
+    const block = formatTouchedFiles(touched);
+    if (!block)
+        return { text: summaryText, truncated: false };
+    if (summaryText.length + 2 + block.length <= maxChars) {
+        return { text: `${summaryText}\n\n${block}`, truncated: false };
+    }
+    const room = Math.max(0, maxChars - summaryText.length - 2);
+    const shrunk = truncateTouchedFiles(touched, room);
+    const shrunkBlock = formatTouchedFiles(shrunk);
+    const truncated = shrunk.read.length + shrunk.modified.length < before;
+    if (!shrunkBlock)
+        return { text: summaryText, truncated };
+    return { text: `${summaryText}\n\n${shrunkBlock}`, truncated };
+}
+// ---- Resume surfacing ----
+// Pull the stored block(s) verbatim out of compacted summary messages — the
+// same format as stored, no reformatting. lastIndexOf prefers the appended
+// block (ours is always last; model prose comes first).
+export function extractTouchedFilesSection(text) {
+    const idx = text.lastIndexOf("Touched files:");
+    if (idx < 0)
+        return null;
+    const section = text.slice(idx).trimEnd();
+    return section.length > 0 ? section : null;
+}
+export function collectStoredTouchedFiles(history) {
+    const out = [];
+    for (const m of history) {
+        if (m?.role !== "user" || typeof m.content !== "string")
+            continue;
+        if (!m.content.includes("[Compacted context"))
+            continue;
+        const section = extractTouchedFilesSection(m.content);
+        if (section)
+            out.push(section);
+    }
+    return out;
+}

package/dist/env-block.js

@@ -6,14 +6,15 @@
 // content via withEnvBlock), NEVER into user content. history[0] is the only
 // slot truncateHistory never drops, so the block survives budget trimming.
 // Caching: the App refreshes history[0] once per turn in submit() (before the
-// budget check, so truncation accounts for it) — the loop's up-to-30 POSTs
-// reuse the same history[0], so git is shelled at most once per turn.
+// budget check, so truncation accounts for it) — the loop's POSTs reuse the
+// same history[0], so git is shelled at most once per turn.
 // Failure-silent: missing git / non-repo cwd / timeout → the block shrinks
 // (cwd + node + time only), never throws, never blocks the turn. No new
 // dependencies; one cheap `git status` invocation with a short timeout, and
 // zero shell-outs when `.git` is absent.
 import { execFileSync } from "node:child_process";
 import { existsSync } from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
 // Cap for the block itself (~500 chars per the task). The base system prompt
 // (SYSTEM_PROMPT + AGENTS.md overlay) is untouched by this cap.
@@ -30,8 +31,9 @@ function shortCwd(cwd) {
     return `…${cwd.slice(cwd.length - (CWD_DISPLAY_CAP - 1))}`;
 }
 // Pure formatter (no I/O): always `cwd + node + time`, plus
-// `branch + status` only when git reported them. Capped to
-// ENV_BLOCK_CHAR_CAP (cwd is pre-truncated so time/node survive the cap).
+// `branch + status` only when git reported them, plus the operating context
+// (`os + shell + user`) when provided. Capped to ENV_BLOCK_CHAR_CAP (cwd is
+// pre-truncated so time/node survive the cap).
 export function buildEnvBlock(parts) {
     const cwd = shortCwd(parts.cwd);
     const git = parts.branch !== undefined &&
@@ -39,7 +41,10 @@ export function buildEnvBlock(parts) {
         parts.branch.length > 0
         ? ` branch=${parts.branch} status=${parts.status ?? "unknown"}`
         : "";
-    const block = `[env cwd=${cwd}${git} node=${parts.nodeVersion} time=${parts.timestamp}]`;
+    const machine = parts.os !== undefined && parts.os !== null && parts.os.length > 0
+        ? ` os=${parts.os} shell=${parts.shell ?? "unknown"} user=${parts.user ?? "unknown"}`
+        : "";
+    const block = `[env cwd=${cwd}${git}${machine} node=${parts.nodeVersion} time=${parts.timestamp}]`;
     return block.length > ENV_BLOCK_CHAR_CAP
         ? `${block.slice(0, ENV_BLOCK_CHAR_CAP - 1)}]`
         : block;
@@ -117,12 +122,45 @@ export function getEnvBlock(cwd = process.cwd()) {
         catch {
             git = null;
         }
+        // Operating context (best-effort, never throws): tells the model which
+        // shell runs its commands and who/where it is, so it stops probing with
+        // whoami/hostname and guessing `ls` vs `dir` (measured: 2–4 wasted bash
+        // calls per task before this existed).
+        let osName = "unknown";
+        try {
+            if (typeof process.platform === "string" && process.platform.length > 0) {
+                osName = process.platform;
+            }
+        }
+        catch {
+            // keep fallback
+        }
+        let shell = "unknown";
+        try {
+            shell = process.platform === "win32" ? "cmd.exe" : "sh";
+        }
+        catch {
+            // keep fallback
+        }
+        let user = "unknown";
+        try {
+            const name = os.userInfo?.().username;
+            if (typeof name === "string" && name.length > 0) {
+                user = name;
+            }
+        }
+        catch {
+            // keep fallback (sandboxed runtimes may forbid userInfo)
+        }
         return buildEnvBlock({
             cwd: dir,
             branch: git?.branch ?? null,
             status: git?.status ?? null,
             nodeVersion,
             timestamp,
+            os: osName,
+            shell,
+            user,
         });
     }
     catch {

package/dist/scheduler.js

@@ -1,10 +1,10 @@
 // Effect-aware tool scheduler: data-driven parallelism without Promise.all-
 // ing every tool.
 //
-// The conservative contract (unchanged): batchable reads run concurrently,
-// mutations stay serialized, results commit in original call order, cancel
-// stops between batches, approval happens per call inside runOneTool. This
-// module only PLANS batches; execution (zen.ts runLoopWithChat) is untouched.
+// The contract: batchable calls run concurrently, conflicting calls stay
+// serialized, results commit in original call order, cancel stops between
+// batches, approval happens per call in order before execution. This module
+// only PLANS batches; execution (agent/loop.ts runLoopWithChat) is untouched.
 //
 // How it reasons (per tool, from the TOOL_EFFECTS table — the single
 // coupling point; the algorithm below has no per-tool branches):
@@ -16,23 +16,33 @@
 //   become inline-error singletons downstream, exactly as before).
 // - interactive (ask_question) or exclusive (shared ambient state the effect
 //   model cannot see: todowrite/todo_update/todo_get) → serial singleton.
-// - any filesystem/network WRITE, or any process SPAWN → serial singleton.
-//   Writes conflict GLOBALLY (not just same-target): a write splits the
-//   block and read-after-write stays ordered. Target-scoped write batching
-//   is a deliberate non-goal — correctness over theoretical parallelism.
-// - reads (filesystem or network) batch with pairwise-disjoint keys, where
-//   the key is tool + target. Same tool + same target serializes (the old
-//   overlap rule, kept verbatim: e.g. two reads of one path). Reads never
-//   conflict across keys — an all-read batch cannot race a writer, because
-//   writers never join batches.
+// - process SPAWN or network WRITE (bash: unbounded footprint) → serial
+//   singleton, splitting the block globally.
+// - filesystem writes (write/edit) batch on disjoint canonical file keys
+//   (see canonicalFileKey): same-file mutations never share a batch, so they
+//   stay strictly ordered in program order; different files run concurrently.
+//   An unresolvable target stays serial (never batch what you cannot see).
+// - reads batch with pairwise-disjoint keys, where the key is tool + target.
+//   Same tool + same target serializes (the old overlap rule, kept verbatim:
+//   e.g. two reads of one path). A path read also conflicts with an open
+//   write to the same canonical file (read-after-write stays ordered), and a
+//   write conflicts with any open member on its key (write-after-read stays
+//   ordered). Directory-scoped scans (grep/glob) vs concurrent writes to
+//   unscanned-listed files are out of scope — same exposure as an editor
+//   saving mid-scan; only same-canonical-path pairs are ordered.
 // - deterministic is declared per tool; its current enforcement is the
 //   same-key rule (a re-poll of the same background task, whose output can
 //   grow, never runs concurrently with itself).
 //
 // Pure module except the shared arg validators (same imports zen.ts already
-// carries — no new coupling class). Covered by tests/scheduler.test.ts; the
-// end-to-end ordering/cancel behavior stays pinned by
-// tests/parallel-calls.test.ts.
+// carries — no new coupling class) plus best-effort path canonicalization
+// (node:fs/node:path only, so the architecture boundary is unchanged:
+// scheduler still reasons from metadata, never from tool branches).
+// Covered by tests/scheduler.test.ts; the end-to-end ordering/cancel
+// behavior stays pinned by tests/parallel-calls.test.ts and
+// tests/parallel-writes.test.ts.
+import * as fs from "node:fs";
+import * as path from "node:path";
 import { toolNames, validateToolArgs } from "./tools.js";
 const str = (v) => (typeof v === "string" ? v : "");
 const targetOf = (key) => (args) => {
@@ -166,22 +176,65 @@ export const TOOL_EFFECTS = {
         target: () => null,
     },
 };
+// Canonical per-file mutation key: the identity two mutation calls compare
+// before sharing a batch. Lexical resolve against the process cwd (the same
+// base the executors default to), then best-effort symlink resolution, then
+// case-folding on case-insensitive filesystems. Null when the target is
+// missing, empty, or unresolvable — unknown footprints stay serial. Sync and
+// best-effort by design: a handful of calls per tool block, and a miss only
+// costs parallelism, never correctness.
+export function canonicalFileKey(rawPath, cwd = process.cwd()) {
+    if (typeof rawPath !== "string" || rawPath.length === 0)
+        return null;
+    if (rawPath.includes("\0"))
+        return null;
+    let abs;
+    try {
+        abs = path.resolve(cwd, rawPath);
+    }
+    catch {
+        return null;
+    }
+    try {
+        abs = fs.realpathSync(abs);
+    }
+    catch {
+        // Fresh write target or unreadable link: the lexical path stands.
+    }
+    try {
+        abs = path.normalize(abs);
+    }
+    catch {
+        return null;
+    }
+    if (process.platform === "win32" || process.platform === "darwin") {
+        abs = abs.toLowerCase();
+    }
+    return abs;
+}
 // Partition one assistant message's tool_calls into commit batches,
 // preserving program order: consecutive batchable calls with pairwise
 // disjoint keys form one batch; any serial-only call — and any call whose
 // key already appears in the open batch — closes the batch and runs as a
-// strict serial singleton. A later batch never moves ahead of an earlier
-// serial call (read-after-write stays ordered), and batches never span the
-// block boundary.
+// strict serial singleton. Filesystem writes join a batch only on a
+// disjoint canonical file key (same-file mutations split into sequential
+// batches, never concurrent); a path read conflicting with an open write —
+// or a write conflicting with any open member — on the same canonical key
+// also splits, so per-file program order always holds. A later batch never
+// moves ahead of an earlier serial call, and batches never span the block
+// boundary.
 export function planBatches(calls) {
     const batches = [];
     let open = [];
     const keys = new Set();
+    // Canonical file keys of the open batch ("read" and/or "write" per key).
+    const openFiles = new Map();
     const flush = () => {
         if (open.length > 0) {
             batches.push(open);
             open = [];
             keys.clear();
+            openFiles.clear();
         }
     };
     const singleton = (call, parsed) => {
@@ -212,15 +265,28 @@ export function planBatches(calls) {
             singleton(call, parsed);
             continue;
         }
-        // Interactive, ambient-state, mutating, or spawning calls serialize.
+        // Interactive, ambient-state, spawning, or network-writing calls
+        // serialize (bash has no statically visible footprint: global conflict).
         if (meta.interactive ||
             meta.exclusive ||
-            meta.filesystem === "write" ||
             meta.network === "write" ||
             meta.process !== "none") {
             singleton(call, parsed);
             continue;
         }
+        // Filesystem writes batch on disjoint canonical file keys: the
+        // per-file mutation queue. Same-file mutations split into sequential
+        // batches (never interleave); disjoint files run concurrently.
+        if (meta.filesystem === "write") {
+            const fileKey = canonicalFileKey(parsed["path"]);
+            if (!fileKey || openFiles.has(fileKey)) {
+                singleton(call, parsed);
+                continue;
+            }
+            openFiles.set(fileKey, "write");
+            open.push({ call, parsed, parallelKey: `${name} ${fileKey}` });
+            continue;
+        }
         // Reads batch on disjoint tool+target keys; empty target = unknown
         // footprint = serial.
         let target = null;
@@ -239,6 +305,20 @@ export function planBatches(calls) {
             singleton(call, parsed);
             continue;
         }
+        // A path read against an open write to the same canonical file stays
+        // ordered (read-after-write): split the batch.
+        if (name === "read") {
+            const fileKey = canonicalFileKey(target);
+            if (fileKey && openFiles.get(fileKey) === "write") {
+                singleton(call, parsed);
+                continue;
+            }
+            keys.add(key);
+            if (fileKey && !openFiles.has(fileKey))
+                openFiles.set(fileKey, "read");
+            open.push({ call, parsed, parallelKey: key });
+            continue;
+        }
         keys.add(key);
         open.push({ call, parsed, parallelKey: key });
     }