atom-agent 1.0.0 → 1.2.0

package/dist/tools/ripgrep.js

@@ -0,0 +1,256 @@
+// ripgrep-backed content search: matches from the `rg` binary when it is
+// the faster choice, with the walker as the always-correct fallback.
+//
+// Routing (see grepTool): the caller already enumerated the file set, so the
+// threshold decides on COUNT alone — enumeration cost is sunk. Below the
+// threshold the walker wins (no ~80ms Windows spawn tax); above it rg's
+// parallel scanner wins by multiples. `ATOM_RG_MIN_FILES` overrides the
+// default; `ATOM_RG=0` forces the walker (degraded envs, tests).
+//
+// Exactness contract (parity-tested, never assumed):
+// - File COVERAGE is the enumerated set, always: rg output is intersected
+//   with it, so git-ignored-untracked files, dotfiles, and SKIP_DIRS behave
+//   exactly like the walker path in both git and non-git trees.
+// - `include` globs filter in JS (shared matcher), never via `-g`: our
+//   minimal glob dialect and gitignore semantics could otherwise drift.
+// - Case sensitivity, binary skipping (rg skips NUL files like the walker),
+//   and CRLF handling (one trailing \r\n stripped, mirroring split("\n"))
+//   all match the walker.
+// - Modes map 1:1: content via `--json --max-count` merged in alpha order
+//   with the same 100-hit cap + note; files_with_matches via
+//   `--files-with-matches` into the existing recency pipeline; count via
+//   `--count` into the existing totals pipeline.
+// - ANY rg failure (missing binary, bad exit, unparseable output, invalid
+//   regex for Rust's engine such as lookahead) returns null and the caller
+//   runs the walker — search never fails when the walker could answer.
+// - No timeout: the walker path is equally unbounded, and a timeout would
+//   invent a failure mode neither path had.
+//
+// Known untested edges (documented, not solved): symlink handling (no
+// privilege to create them in this env — both sides skip them by
+// construction: walker via isFile/isDirectory checks, rg via no-follow
+// default), lone-\r line endings, non-ASCII case/boundary semantics.
+import { execFile, execFileSync } from "node:child_process";
+import { rgRelToCwdRel } from "./dir-cache.js";
+// Routing threshold (measured, Windows, 3000-file fixture): below it the
+// walker wins outright (no ~100ms spawn tax); above it rg wins clearly
+// (643ms vs 872ms end-to-end at 3000 files, and the gap widens with size
+// since the walker pays per-file reads while rg does not). Conservative on
+// purpose: small/medium scopes stay on the exact legacy path, and
+// `ATOM_RG_MIN_FILES` overrides per environment.
+export const RG_MIN_FILES_DEFAULT = 1000;
+const RG_MAX_BUFFER = 64 * 1024 * 1024;
+//rg --max-count per file for content mode: bounds output while keeping the
+// merged take-100 exact. Rationale: take-100-alpha needs every file's FULL
+// matching-line list UNLESS a file is capped — so any file hitting the cap
+// forces a walker fallback (rare pathological case: 1000+ matches in one
+// file). Without the cap a minified bundle could dump megabytes of JSON.
+const RG_CONTENT_MAX_COUNT = 1000;
+const stats = { uses: 0, fallbacks: 0 };
+let availability = null;
+export function rgEnabled() {
+    const raw = process.env.ATOM_RG;
+    if (raw === undefined)
+        return true;
+    const v = raw.trim().toLowerCase();
+    return !(v === "0" || v === "false" || v === "no" || v === "off");
+}
+export function rgMinFiles() {
+    const raw = process.env.ATOM_RG_MIN_FILES;
+    if (raw !== undefined) {
+        const n = Number(raw.trim());
+        if (Number.isFinite(n) && n > 0)
+            return Math.floor(n);
+    }
+    return RG_MIN_FILES_DEFAULT;
+}
+// One-time `rg --version` probe (lazy so small searches never pay the spawn).
+// Never throws; false on any failure.
+export function rgAvailable() {
+    if (!rgEnabled())
+        return false;
+    if (availability !== null)
+        return availability;
+    try {
+        const out = execFileSync("rg", ["--version"], {
+            timeout: 10000,
+            encoding: "utf8",
+            windowsHide: true,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        availability = typeof out === "string" && out.includes("ripgrep");
+    }
+    catch {
+        availability = false;
+    }
+    return availability;
+}
+// Test seam: reset the cached probe (production never calls this).
+export function resetRgAvailable() {
+    availability = null;
+}
+export function getRipgrepStats() {
+    return { ...stats, available: rgAvailable() };
+}
+export function resetRipgrepStats() {
+    stats.uses = 0;
+    stats.fallbacks = 0;
+}
+function runRg(absDir, args) {
+    return new Promise((resolve) => {
+        execFile("rg", args, { cwd: absDir, timeout: 0, maxBuffer: RG_MAX_BUFFER, windowsHide: true }, (err, stdout, stderr) => {
+            const code = err == null ? 0 : typeof err.code === "number" ? err.code : 2;
+            resolve({
+                code,
+                stdout: typeof stdout === "string" ? stdout : String(stdout ?? ""),
+                stderr: typeof stderr === "string" ? stderr : String(stderr ?? ""),
+            });
+        });
+    });
+}
+function isRegexError(stderr) {
+    return /regex parse error|unrecognized|error parsing regex/i.test(stderr);
+}
+// Shared runner: exit 0 with output wins; exit 1 + empty means no matches
+// (caller renders the mode's empty shape); anything else is a fallback
+// signal — with regex-parse errors being the EXPECTED fallback trigger
+// (lookahead and friends are valid JS, invalid Rust).
+async function runRgSearch(absDir, baseArgs, pattern) {
+    let res;
+    try {
+        res = await runRg(absDir, [...baseArgs, "-e", pattern, "--", "."]);
+    }
+    catch {
+        return { kind: "fallback" };
+    }
+    if (res.code === 0)
+        return { kind: "ok", stdout: res.stdout };
+    if (res.code === 1)
+        return { kind: "empty" };
+    if (isRegexError(res.stderr))
+        return { kind: "fallback" };
+    return { kind: "fallback" };
+}
+// Strip the leading "./" rg emits for cwd-relative paths + normalize to the
+// posix rels the enumerated set uses. Returns null when unusable.
+function toRel(rawPath) {
+    if (typeof rawPath !== "string" || rawPath.length === 0)
+        return null;
+    let p = rawPath.replace(/\\/g, "/");
+    if (p.startsWith("./"))
+        p = p.slice(2);
+    if (p.length === 0 || p === ".")
+        return null;
+    return p;
+}
+// Mirror of split("\n") line semantics: strip exactly one trailing \n and
+// NOTHING else. In particular a CRLF line keeps its \r, exactly like the
+// walker (parity-tested) — invisible on screen, byte-identical in output.
+function splitLine(text) {
+    if (text.endsWith("\n"))
+        return text.slice(0, -1);
+    return text;
+}
+const BASE_ARGS = ["--hidden", "--no-ignore", "--glob", "!node_modules/**", "--glob", "!.git/**"];
+function parseJsonEvents(stdout) {
+    const out = [];
+    for (const line of stdout.split("\n")) {
+        const t = line.trim();
+        if (!t.startsWith("{"))
+            continue;
+        try {
+            const v = JSON.parse(t);
+            if (typeof v === "object" && v !== null)
+                out.push(v);
+        }
+        catch {
+            // malformed event line: skip, never crash (caller falls back on empty)
+        }
+    }
+    return out;
+}
+// Content scan: --json matches merged per file (line order), files in alpha
+// order. Hits carry raw line text; the caller applies the shared 200-char
+// trim + 100-hit cap + note (same code as the walker path would — see
+// grepTool; this module only supplies ordered raw material).
+export async function rgContentHits(absDir, cwd, pattern, allowed) {
+    const run = await runRgSearch(absDir, [...BASE_ARGS, "--json", "--max-count", String(RG_CONTENT_MAX_COUNT)], pattern);
+    if (run.kind !== "ok")
+        return run.kind === "empty" ? { counts: [], hits: [], cappedFile: false } : null;
+    const perFile = new Map();
+    let cappedFile = false;
+    for (const evt of parseJsonEvents(run.stdout)) {
+        if (evt["type"] !== "match")
+            continue;
+        const data = evt["data"];
+        if (typeof data !== "object" || data === null)
+            continue;
+        const rawPath = data["path"]?.text;
+        const dirRel = typeof rawPath === "string" ? toRel(rawPath) : null;
+        const rel = dirRel === null ? null : rgRelToCwdRel(absDir, cwd, dirRel);
+        if (!rel || !allowed.has(rel))
+            continue;
+        const lineNo = data["line_number"];
+        const lines = data["lines"];
+        if (typeof lineNo !== "number" || typeof lines?.text !== "string")
+            continue;
+        const list = perFile.get(rel) ?? [];
+        list.push({ line: Math.floor(lineNo), text: splitLine(lines.text) });
+        perFile.set(rel, list);
+    }
+    const counts = [];
+    const hits = [];
+    for (const rel of [...perFile.keys()].sort()) {
+        const list = perFile.get(rel);
+        // De-dupe multiple submatches on one line (walker counts LINES).
+        const seen = new Set();
+        let n = 0;
+        for (const h of list) {
+            if (seen.has(h.line))
+                continue;
+            seen.add(h.line);
+            n += 1;
+            hits.push({ rel, line: h.line, text: h.text });
+        }
+        // max-count caps MATCHES per file: a full batch means that file may hold
+        // more (the walker's exactly-100 ambiguity behaves the same way).
+        if (list.length >= RG_CONTENT_MAX_COUNT)
+            cappedFile = true;
+        if (n > 0)
+            counts.push({ rel, n });
+    }
+    stats.uses += 1;
+    return { counts, hits, cappedFile };
+}
+// files_with_matches + count scan: per-file matching-LINE counts via
+// `rg --count` (ripgrep --count semantics already match the walker's).
+// files_with_matches derives its file set from these counts, so one spawn
+// serves both modes. Caller applies totals/caps/recency.
+export async function rgFileCounts(absDir, cwd, pattern, allowed) {
+    const run = await runRgSearch(absDir, [...BASE_ARGS, "--count"], pattern);
+    if (run.kind !== "ok")
+        return run.kind === "empty" ? { counts: [] } : null;
+    const counts = [];
+    for (const rawLine of run.stdout.split("\n")) {
+        const line = rawLine.trim();
+        if (!line)
+            continue;
+        // Right-split: Windows drive letters contain colons.
+        const idx = line.lastIndexOf(":");
+        if (idx <= 0)
+            continue;
+        const dirRel = toRel(line.slice(0, idx));
+        const rel = dirRel === null ? null : rgRelToCwdRel(absDir, cwd, dirRel);
+        const n = Number(line.slice(idx + 1));
+        if (!rel || !allowed.has(rel) || !Number.isFinite(n) || n <= 0)
+            continue;
+        counts.push({ rel, n: Math.floor(n) });
+    }
+    counts.sort((a, b) => (a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0));
+    stats.uses += 1;
+    return { counts };
+}
+// Record a fallback (rg answered nothing usable; walker takes over).
+export function noteRgFallback() {
+    stats.fallbacks += 1;
+}

package/dist/tools/search.js

@@ -2,7 +2,10 @@
 // Read-only over the repo; node_modules/.git skipped by the walker.
 import { promises as fsp } from "node:fs";
 import * as path from "node:path";
-import { err, GLOB_MATCH_CAP, GREP_MATCH_CAP, invalidCall, resolveSandbox, SKIP_DIRS } from "./shared.js";
+import { listFiles } from "./dir-cache.js";
+import { appendOverflow } from "./overflow.js";
+import { noteRgFallback, rgAvailable, rgContentHits, rgFileCounts, rgMinFiles, } from "./ripgrep.js";
+import { err, GLOB_MATCH_CAP, GREP_MATCH_CAP, invalidCall, READ_CHAR_CAP, resolveSandbox, truncateHead } from "./shared.js";
 // Minimal glob matcher: supports **, **/, *, ?. Used for grep `include`
 // and the glob tool. Patterns without a slash match the basename.
 function globToRegExp(glob) {
@@ -46,25 +49,69 @@ function matchesGlob(pattern, relPosix) {
     }
     return globToRegExp(norm).test(relPosix);
 }
-async function walkFiles(absDir, cwd, out) {
-    const entries = await fsp.readdir(absDir, { withFileTypes: true });
-    for (const e of entries) {
-        if (SKIP_DIRS.has(e.name))
-            continue;
-        const full = path.join(absDir, e.name);
-        if (e.isDirectory()) {
-            await walkFiles(full, cwd, out);
-        }
-        else if (e.isFile()) {
-            out.push(path.relative(cwd, full).split(path.sep).join("/"));
-        }
-    }
-}
 export const GREP_OUTPUT_MODES = new Set([
     "content",
     "files_with_matches",
     "count",
 ]);
+// File-read fan-out for scans: bounded parallelism (32 in flight) over an
+// ordered list, results in input order. Disk I/O overlaps instead of
+// serializing one open/read/close at a time; the regex pass stays sequential
+// afterwards so outputs and first-failure errors keep exact alpha order.
+// 32 concurrent opens is far below EMFILE on every supported platform.
+const SCAN_CONCURRENCY = 32;
+async function mapLimit(items, limit, fn) {
+    const out = new Array(items.length);
+    let next = 0;
+    const workers = new Array(Math.min(Math.max(limit, 1), Math.max(items.length, 1)))
+        .fill(0)
+        .map(async () => {
+        for (;;) {
+            const i = next++;
+            if (i >= items.length)
+                return;
+            out[i] = await fn(items[i], i);
+        }
+    });
+    await Promise.all(workers);
+    return out;
+}
+// One hit line, shared by the walker and ripgrep scans so both paths stay
+// byte-identical by construction (1-based line, 200-char trim).
+export function formatGrepHit(rel, lineNo, line) {
+    return `${rel}:${lineNo}: ${line.length > 200 ? line.slice(0, 200) + "…" : line}`;
+}
+// ripgrep scan for one grep call: fills the same {counts, hits, hitsCapped}
+// shape as the walker scan below (or null = run the walker). Content hits
+// arrive merged in (file alpha, line) order; the 100-hit cap + note apply
+// exactly like the walker path (including its take-100-blindly quirk).
+async function scanWithRipgrep(absDir, cwd, pattern, mode, allowed) {
+    if (mode === "content") {
+        const r = await rgContentHits(absDir, cwd, pattern, allowed);
+        if (r === null)
+            return null;
+        if (r.cappedFile)
+            return null; // pathological volume: walker stays exact
+        const hits = r.hits.slice(0, GREP_MATCH_CAP).map((h) => formatGrepHit(h.rel, h.line, h.text));
+        return { counts: r.counts, hits, hitsCapped: r.hits.length >= GREP_MATCH_CAP };
+    }
+    const r = await rgFileCounts(absDir, cwd, pattern, allowed);
+    if (r === null)
+        return null;
+    return { counts: r.counts, hits: [], hitsCapped: false };
+}
+// Issue 04: every tool output passes the shared head-truncation contract.
+// Search hits are already line-capped (100/200) far below the byte cap, so
+// this is a byte-identical safety net that never fires on reachable outputs
+// — grep/glob shape, ordering, modes, count notes, and the ripgrep/walker
+// selection (issue 01) stay exactly as settled. If it ever fires, the head
+// is line-aligned with total-vs-emitted counts plus the overflow pointer.
+function capSearchOutput(out, label) {
+    if (out.length <= READ_CHAR_CAP)
+        return out;
+    const t = truncateHead(out, READ_CHAR_CAP, `\n[truncated: ${label} exceeded 64KB]`);
+    return appendOverflow(t.head, t.note, label, out);
+}
 // Best-effort mtime (ms) for recency sorting; 0 when the file cannot be
 // stat'ed (keeps such entries last instead of failing the search).
 async function mtimeMs(abs) {
@@ -75,6 +122,56 @@ async function mtimeMs(abs) {
         return 0;
     }
 }
+async function scanWithWalker(cwd, re, pattern, sorted, include, mode) {
+    const collectHits = mode === "content";
+    const bodies = await mapLimit(sorted, SCAN_CONCURRENCY, async (rel) => {
+        if (include && !matchesGlob(include, rel))
+            return null;
+        try {
+            const text = await fsp.readFile(path.resolve(cwd, rel), "utf8");
+            if (text.includes("\0"))
+                return null; // binary — skip
+            return { rel, text };
+        }
+        catch {
+            return null; // unreadable — skip
+        }
+    });
+    const counts = [];
+    const hits = [];
+    let hitsCapped = false;
+    for (const body of bodies) {
+        if (body === null)
+            continue;
+        if (collectHits && hitsCapped)
+            break;
+        const { rel, text } = body;
+        const lines = text.split("\n");
+        let n = 0;
+        for (let i = 0; i < lines.length; i++) {
+            let matched;
+            try {
+                matched = re.test(lines[i]);
+            }
+            catch {
+                return { error: err(`regex failed on input: ${pattern}`) };
+            }
+            // Reset lastIndex in case the pattern is global/sticky.
+            re.lastIndex = 0;
+            if (!matched)
+                continue;
+            n += 1;
+            if (collectHits && !hitsCapped) {
+                hits.push(formatGrepHit(rel, i + 1, lines[i]));
+                if (hits.length >= GREP_MATCH_CAP)
+                    hitsCapped = true;
+            }
+        }
+        if (n > 0)
+            counts.push({ rel, n });
+    }
+    return { counts, hits, hitsCapped };
+}
 // Line-regex search under dir (default "."). `include` is a glob like
 // "*.ts". `outputMode` selects the shape (Claude-Code-style):
 // - "content" (default): "file:line: text" lines, capped at 100 matches.
@@ -110,40 +207,36 @@ export async function grepTool(args, cwd = process.cwd()) {
         }
         if (!st.isDirectory())
             return err(`not a directory: ${dir}`);
-        const files = [];
-        await walkFiles(r.abs, cwd, files);
+        const files = await listFiles(r.abs, cwd);
         const include = typeof args.include === "string" && args.include.length > 0 ? args.include : null;
-        // Per-file match counts in alpha order (single scan for all modes).
-        // Counts are matching LINES per file (ripgrep --count semantics).
-        const counts = [];
-        for (const rel of files.sort()) {
-            if (include && !matchesGlob(include, rel))
-                continue;
-            let text;
-            try {
-                text = await fsp.readFile(path.resolve(cwd, rel), "utf8");
-            }
-            catch {
-                continue; // unreadable/binary — skip
+        const sorted = files.sort();
+        // Allowed set shared by both scan paths (include filtering is identical
+        // either way, so ripgrep coverage matches the walker exactly).
+        const allowed = new Set(sorted.filter((rel) => !include || matchesGlob(include, rel)));
+        // ripgrep fast path: large scopes only (process-spawn cost), silent
+        // walker fallback on anything unusable (missing binary, bad exit,
+        // unparseable output, JS-only regex). See src/tools/ripgrep.ts.
+        let counts;
+        let hits;
+        let hitsCapped;
+        if (rgAvailable() && sorted.length >= rgMinFiles()) {
+            const fast = await scanWithRipgrep(r.abs, cwd, args.pattern, mode, allowed);
+            if (fast !== null) {
+                ({ counts, hits, hitsCapped } = fast);
             }
-            if (text.includes("\0"))
-                continue; // binary — skip
-            const lines = text.split("\n");
-            let n = 0;
-            for (let i = 0; i < lines.length; i++) {
-                try {
-                    if (!re.test(lines[i]))
-                        continue;
-                    n += 1;
-                }
-                catch {
-                    return err(`regex failed on input: ${args.pattern}`);
-                }
-                // Reset lastIndex in case the pattern is global/sticky.
-                re.lastIndex = 0;
+            else {
+                noteRgFallback();
+                const walked = await scanWithWalker(cwd, re, args.pattern, sorted, include, mode);
+                if ("error" in walked)
+                    return walked.error;
+                ({ counts, hits, hitsCapped } = walked);
             }
-            if (n > 0)
-                counts.push({ rel, n });
+        }
+        else {
+            const walked = await scanWithWalker(cwd, re, args.pattern, sorted, include, mode);
+            if ("error" in walked)
+                return walked.error;
+            ({ counts, hits, hitsCapped } = walked);
         }
         if (counts.length === 0)
             return "No matches.";
@@ -154,7 +247,7 @@ export async function grepTool(args, cwd = process.cwd()) {
             let out = `Found ${withTime.length} file(s)\n${listed.join("\n")}`;
             if (withTime.length > GREP_MATCH_CAP)
                 out += "\n[truncated: more than 100 matching files]";
-            return out;
+            return capSearchOutput(out, "grep results");
         }
         if (mode === "count") {
             const listed = counts.slice(0, GREP_MATCH_CAP);
@@ -163,37 +256,12 @@ export async function grepTool(args, cwd = process.cwd()) {
                 `\nFound ${total} total match(es) across ${counts.length} file(s).`;
             if (counts.length > GREP_MATCH_CAP)
                 out += "\n[truncated: more than 100 matching files]";
-            return out;
+            return capSearchOutput(out, "grep results");
         }
-        const hits = [];
-        for (const c of counts) {
-            let text;
-            try {
-                text = await fsp.readFile(path.resolve(cwd, c.rel), "utf8");
-            }
-            catch {
-                continue; // vanished mid-search — skip
-            }
-            const lines = text.split("\n");
-            for (let i = 0; i < lines.length; i++) {
-                let line;
-                try {
-                    if (!re.test(lines[i]))
-                        continue;
-                    line = lines[i];
-                }
-                catch {
-                    return err(`regex failed on input: ${args.pattern}`);
-                }
-                // Reset lastIndex in case the pattern is global/sticky.
-                re.lastIndex = 0;
-                hits.push(`${c.rel}:${i + 1}: ${line.length > 200 ? line.slice(0, 200) + "…" : line}`);
-                if (hits.length >= GREP_MATCH_CAP) {
-                    return hits.join("\n") + "\n[truncated: more than 100 matches]";
-                }
-            }
-        }
-        return hits.length > 0 ? hits.join("\n") : "No matches.";
+        // Content hits accumulated inline above (same order, same cap).
+        if (hitsCapped)
+            return capSearchOutput(hits.join("\n") + "\n[truncated: more than 100 matches]", "grep results");
+        return hits.length > 0 ? capSearchOutput(hits.join("\n"), "grep results") : "No matches.";
     }
     catch (e) {
         return err(e instanceof Error ? e.message : String(e));
@@ -219,8 +287,7 @@ export async function globTool(args, cwd = process.cwd()) {
         }
         if (!st.isDirectory())
             return err(`not a directory: ${dir}`);
-        const files = [];
-        await walkFiles(r.abs, cwd, files);
+        const files = await listFiles(r.abs, cwd);
         const matched = files.filter((rel) => matchesGlob(args.pattern, rel));
         const withTime = await Promise.all(matched.map(async (rel) => ({ rel, t: await mtimeMs(path.resolve(cwd, rel)) })));
         withTime.sort((a, b) => b.t - a.t || (a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0));
@@ -228,7 +295,7 @@ export async function globTool(args, cwd = process.cwd()) {
         let out = capped.length > 0 ? capped.join("\n") : "No matches.";
         if (withTime.length > GLOB_MATCH_CAP)
             out += "\n[truncated: more than 200 matches]";
-        return out;
+        return capSearchOutput(out, "glob results");
     }
     catch (e) {
         return err(e instanceof Error ? e.message : String(e));

package/dist/tools/shared.js

@@ -29,3 +29,42 @@ export function resolveSandbox(p, cwd = process.cwd()) {
         return { error: "Error: invalid path" };
     return { abs: path.resolve(cwd, p) };
 }
+export function truncateHead(full, maxChars, truncNote, maxLines = Number.MAX_SAFE_INTEGER) {
+    const text = typeof full === "string" ? full : "";
+    const cap = Math.max(1, Math.floor(maxChars));
+    const lineCap = Math.max(1, Math.floor(maxLines));
+    const totalChars = text.length;
+    const totalLines = text.length === 0 ? 0 : text.split("\n").length;
+    if (totalChars <= cap && totalLines <= lineCap) {
+        return {
+            head: text,
+            truncated: false,
+            totalChars,
+            emittedChars: totalChars,
+            totalLines,
+            emittedLines: totalLines,
+            note: "",
+        };
+    }
+    let head = text;
+    if (totalChars > cap) {
+        const candidate = text.slice(0, cap);
+        const nl = candidate.lastIndexOf("\n");
+        // nl <= 0 means no usable boundary (single giant line, or the text
+        // starts with "\n"): keep the hard cut — the documented tail edge case.
+        head = nl > 0 ? candidate.slice(0, nl) : candidate;
+    }
+    if (totalLines > lineCap) {
+        const lineHead = text.split("\n").slice(0, lineCap).join("\n");
+        if (lineHead.length < head.length)
+            head = lineHead;
+    }
+    const emittedChars = head.length;
+    const emittedLines = head.length === 0 ? 0 : head.split("\n").length;
+    const detail = `showing ${emittedChars} of ${totalChars} chars ` +
+        `(${emittedLines} of ${totalLines} lines)`;
+    const note = truncNote.endsWith("]")
+        ? `${truncNote.slice(0, -1)}; ${detail}]`
+        : `${truncNote} [${detail}]`;
+    return { head, truncated: true, totalChars, emittedChars, totalLines, emittedLines, note };
+}

package/dist/tools/shell.js

@@ -9,8 +9,9 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { scrubSecrets } from "../policy.js";
 import { PROVIDERS } from "../providers.js";
+import { clearDirListingCache } from "./dir-cache.js";
 import { appendOverflow } from "./overflow.js";
-import { err, OUTPUT_CAP } from "./shared.js";
+import { err, OUTPUT_CAP, truncateHead } from "./shared.js";
 // ---- Background bash tasks (Claude-Code-style run_in_background) ----
 const BG_TASK_CAP = 20;
 const BG_POLL_MS = 100;
@@ -120,6 +121,16 @@ async function startBackgroundBash(command, cwd) {
             rec.exitCode = typeof code === "number" ? code : 1;
         });
         child.unref();
+        // A spawned command can touch anything (files, trees, checkouts): the
+        // directory-listing cache cannot know what changed, so drop it all. Cheap
+        // (next search rescans once) and exactly correct for tool-driven flows;
+        // only out-of-process edits stay TTL-bound.
+        try {
+            clearDirListingCache();
+        }
+        catch {
+            // never break the tool
+        }
         return JSON.stringify({ backgroundTaskId: id, status: "running", hint: "use bash_output to poll" });
     }
     catch (e) {
@@ -151,8 +162,8 @@ function capBgStream(s, which) {
     // bash_output passes through here.
     const clean = scrubSecrets(s, providerSecrets());
     if (clean.length > OUTPUT_CAP) {
-        const full = clean;
-        return appendOverflow(full.slice(0, OUTPUT_CAP), `\n[truncated: ${which} exceeded 8KB]`, `background ${which}`, full);
+        const t = truncateHead(clean, OUTPUT_CAP, `\n[truncated: ${which} exceeded 8KB]`);
+        return appendOverflow(t.head, t.note, `background ${which}`, clean);
     }
     return clean;
 }
@@ -213,6 +224,14 @@ export function bashTool(args, cwd = process.cwd()) {
     const timeoutMs = Math.min(Math.max(Math.floor(args.timeoutMs ?? 60000), 1), 120000);
     return new Promise((resolve) => {
         exec(args.command, { cwd, timeout: timeoutMs, windowsHide: true, maxBuffer: 16 * 1024 * 1024 }, (error, stdout, stderr) => {
+            // The command ran (whatever its exit): it may have mutated the tree,
+            // so the listing cache is dropped (see background path above).
+            try {
+                clearDirListingCache();
+            }
+            catch {
+                // never break the tool
+            }
             try {
                 const e = error;
                 const exitCode = e ? (typeof e.code === "number" ? e.code : 1) : 0;
@@ -229,12 +248,14 @@ export function bashTool(args, cwd = process.cwd()) {
                 let stderrTruncated = false;
                 if (out.length > OUTPUT_CAP) {
                     const full = out;
-                    out = appendOverflow(full.slice(0, OUTPUT_CAP), "\n[truncated: stdout exceeded 8KB]", "command stdout", full);
+                    const t = truncateHead(full, OUTPUT_CAP, "\n[truncated: stdout exceeded 8KB]");
+                    out = appendOverflow(t.head, t.note, "command stdout", full);
                     stdoutTruncated = true;
                 }
                 if (errText.length > OUTPUT_CAP) {
                     const full = errText;
-                    errText = appendOverflow(full.slice(0, OUTPUT_CAP), "\n[truncated: stderr exceeded 8KB]", "command stderr", full);
+                    const t = truncateHead(full, OUTPUT_CAP, "\n[truncated: stderr exceeded 8KB]");
+                    errText = appendOverflow(t.head, t.note, "command stderr", full);
                     stderrTruncated = true;
                 }
                 resolve(JSON.stringify({

package/dist/tools/todo.js

@@ -20,7 +20,7 @@ export function clearTodos() {
 function renderTodos(items) {
     if (items.length === 0)
         return "Todo list is empty.";
-    const mark = (s) => s === "completed" ? "✅" : s === "in_progress" ? "🔧" : "❌";
+    const mark = (s) => s === "completed" ? "✅" : s === "in_progress" ? "🔧" : "○";
     return (`Todo list (${items.length}):\n` +
         items
             .map((t, i) => `${i + 1}. ${mark(t.status)} [${t.status}] ${t.content}${t.priority ? ` (${t.priority})` : ""}`)