@vincemakes/kiso-tools-node 0.36.0 → 0.38.0

package/dist/corpus.d.ts

@@ -0,0 +1,96 @@
+/**
+ * THE SEARCH CORPUS — one definition of "which files a search may see",
+ * shared by `search_text` and `list_dir`'s glob.
+ *
+ * They disagreed before this existed: `list_dir` listed every dot entry
+ * and `search_text` skipped all of them. Two walkers is how that happens,
+ * so there is one.
+ *
+ * The rule is the user's own declaration. A `.gitignore` FILE at the
+ * workspace root switches the corpus on — not the presence of `.git`, and
+ * the walk never goes up. A `.gitignore` is the declaration wherever the
+ * repository root happens to be, which is what lets a monorepo
+ * subdirectory carrying its own file be treated properly instead of being
+ * penalised for not being a repository root; and `.git` says nothing the
+ * file does not. With no declaration there is nothing to trust, so the
+ * old conservative rule stands: every dot entry skipped.
+ *
+ * Two things are never searched, declaration or not:
+ *
+ *  - `.git`, which is machinery, not content.
+ *  - the CREDENTIAL SET below — files whose conventional purpose is to
+ *    hold credentials. A committed file is not a secret by the user's own
+ *    declaration, so `.github/` and `.eslintrc` ARE searchable; but an
+ *    incidental hit from a search for "KEY" is exposure without intent,
+ *    and that is what this prevents. An explicit `read_file` of any of
+ *    them is unchanged.
+ *
+ * `node_modules` is skipped unconditionally in both modes, as before. It
+ * is not a declaration question: DC-54 measured 296,924 files under a home
+ * directory, and a corpus that can reach a dependency tree is the freeze
+ * that finding was about.
+ */
+import { type Ignore } from "ignore";
+/** The walk stops here. `search_text` has always used 8; the glob inherits
+ *  it so a pattern cannot reach deeper than a search can. */
+export declare const CORPUS_MAX_DEPTH = 8;
+export declare function isCredentialName(name: string): boolean;
+export interface CorpusOptions {
+    workspaceRoot: string;
+    /** Default CORPUS_MAX_DEPTH. */
+    maxDepth?: number;
+    /** Stop after this many files. Default: no cap (search has its own
+     *  budget; the glob passes 200). */
+    maxEntries?: number;
+    /** DC-49 exclude roots — the user's own knob, unchanged. */
+    isExcluded?: (fullPath: string) => boolean;
+    /** Keep only these. Applied BEFORE the cap, so `maxEntries` bounds the
+     *  files returned and not the files walked past — capping the walk
+     *  first and filtering after would silently return fewer matches than
+     *  exist, which is the defect the cap note exists to prevent. */
+    accept?: (workspaceRelative: string) => boolean;
+    /** Start the walk here instead of at the root. The DECLARATION is still
+     *  read at `workspaceRoot` and paths are still relative to it. */
+    walkFrom?: string;
+}
+export interface CorpusWalk {
+    /** Workspace-relative, POSIX-separated. */
+    files: string[];
+    /** The walk stopped descending somewhere. DIFFERENT from the cap: the
+     *  remedy is "the file is deeper than a search reaches", not "narrow
+     *  the directory". Reported separately, and never claimed when it did
+     *  not happen — a walk that silently returns less is the same defect
+     *  as a read that silently returns 200 lines. */
+    cutByDepth: boolean;
+    /** The entry cap was reached. */
+    cutByCap: boolean;
+}
+/** One directory's `.gitignore`, and the directory it is relative to. */
+export interface Layer {
+    dir: string;
+    matcher: Ignore;
+}
+export declare function readLayer(dir: string): Layer | null;
+/** Ignored by ANY ancestor's file, each tested against the path relative
+ *  to the directory that declared it — which is what makes a nested
+ *  `.gitignore` apply to its own subtree and not above it. */
+export declare function ignoredBy(layers: readonly Layer[], full: string, isDir: boolean): boolean;
+/** The SHARED predicate. `search_text` walks its own tree (its walk is
+ *  interleaved with the budget and the matcher) and `walkCorpus` walks
+ *  here, but both ask THIS — which is the whole point of there being one
+ *  corpus rather than two walkers that agree by coincidence. */
+export declare function corpusSkips(declared: boolean, layers: readonly Layer[], full: string, name: string, isDir: boolean): boolean;
+/** The layers in force inside `dir`, given its parent's. */
+export declare function layersEntering(dir: string, parent: readonly Layer[]): readonly Layer[];
+export declare function walkCorpus(opts: CorpusOptions): CorpusWalk;
+/** A minimal glob → RegExp, anchored, over workspace-relative POSIX paths.
+ *
+ *  `*` any run except `/`, `?` one character except `/`, `**` any run
+ *  including `/`. A leading `** /` (without the space) matches zero or
+ *  more directories, so `**\/*.ts` finds a root-level `a.ts` — the
+ *  behaviour people expect and the one a naive translation gets wrong by
+ *  requiring at least one directory.
+ *
+ *  Everything else is literal, including the regex metacharacters a path
+ *  can legally contain. */
+export declare function globToRegExp(pattern: string): RegExp;

package/dist/corpus.js

@@ -0,0 +1,218 @@
+/**
+ * THE SEARCH CORPUS — one definition of "which files a search may see",
+ * shared by `search_text` and `list_dir`'s glob.
+ *
+ * They disagreed before this existed: `list_dir` listed every dot entry
+ * and `search_text` skipped all of them. Two walkers is how that happens,
+ * so there is one.
+ *
+ * The rule is the user's own declaration. A `.gitignore` FILE at the
+ * workspace root switches the corpus on — not the presence of `.git`, and
+ * the walk never goes up. A `.gitignore` is the declaration wherever the
+ * repository root happens to be, which is what lets a monorepo
+ * subdirectory carrying its own file be treated properly instead of being
+ * penalised for not being a repository root; and `.git` says nothing the
+ * file does not. With no declaration there is nothing to trust, so the
+ * old conservative rule stands: every dot entry skipped.
+ *
+ * Two things are never searched, declaration or not:
+ *
+ *  - `.git`, which is machinery, not content.
+ *  - the CREDENTIAL SET below — files whose conventional purpose is to
+ *    hold credentials. A committed file is not a secret by the user's own
+ *    declaration, so `.github/` and `.eslintrc` ARE searchable; but an
+ *    incidental hit from a search for "KEY" is exposure without intent,
+ *    and that is what this prevents. An explicit `read_file` of any of
+ *    them is unchanged.
+ *
+ * `node_modules` is skipped unconditionally in both modes, as before. It
+ * is not a declaration question: DC-54 measured 296,924 files under a home
+ * directory, and a corpus that can reach a dependency tree is the freeze
+ * that finding was about.
+ */
+import { readFileSync, readdirSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import ignore, {} from "ignore";
+/** The walk stops here. `search_text` has always used 8; the glob inherits
+ *  it so a pattern cannot reach deeper than a search can. */
+export const CORPUS_MAX_DEPTH = 8;
+/** THE CREDENTIAL SET — files whose CONVENTIONAL PURPOSE is to hold
+ *  credentials. That class is the rule; the list is its application, and
+ *  the next candidate is judged by the class rather than by resemblance.
+ *  Changes to this list are RULINGS, not edits.
+ *
+ *  Enumerated rather than matched by prefix: `.env*` as a prefix would
+ *  also swallow `.environment` and `.envoy.yaml`, which are ordinary
+ *  files that happen to start the same way.
+ *
+ *  IN, and why:
+ *    `.env`, `.env.*`   the convention itself
+ *    `.envrc`           direnv — routinely `export AWS_SECRET_...`
+ *    `.netrc`           machine credentials, by definition
+ *    id_rsa, id_dsa,    private keys, by name. Their `.pub` counterparts
+ *    id_ecdsa,          are different names and stay searchable, which is
+ *    id_ed25519         correct: a public key is public.
+ *    *.pem              the same, by extension
+ *
+ *  OUT, deliberately, so the omissions are decisions and not oversights:
+ *    `.npmrc`   a config file by convention; tokens in it are normally
+ *               `${VAR}` placeholders, so excluding it would cost more
+ *               than it protects
+ *    `*.key`    too many non-secret uses to be a credential by name
+ *
+ *  An explicit `read_file` of ANY of these is unchanged. Reading on
+ *  purpose is the user's model doing what it was told; an incidental hit
+ *  from a search for "KEY" is exposure without intent, and only the
+ *  second is what this prevents. */
+const ENV_TEMPLATES = new Set([".env.example", ".env.sample", ".env.template"]);
+const CREDENTIAL_NAMES = new Set([".envrc", ".netrc", "id_rsa", "id_dsa", "id_ecdsa", "id_ed25519"]);
+export function isCredentialName(name) {
+    if (ENV_TEMPLATES.has(name))
+        return false;
+    if (name === ".env" || name.startsWith(".env."))
+        return true;
+    if (CREDENTIAL_NAMES.has(name))
+        return true;
+    return name.endsWith(".pem");
+}
+export function readLayer(dir) {
+    let text;
+    try {
+        text = readFileSync(join(dir, ".gitignore"), "utf8");
+    }
+    catch {
+        return null;
+    }
+    return { dir, matcher: ignore().add(text) };
+}
+/** Ignored by ANY ancestor's file, each tested against the path relative
+ *  to the directory that declared it — which is what makes a nested
+ *  `.gitignore` apply to its own subtree and not above it. */
+export function ignoredBy(layers, full, isDir) {
+    for (const layer of layers) {
+        const rel = relative(layer.dir, full).split(sep).join("/");
+        if (rel === "" || rel.startsWith("../"))
+            continue;
+        if (layer.matcher.ignores(isDir ? `${rel}/` : rel))
+            return true;
+    }
+    return false;
+}
+/** The SHARED predicate. `search_text` walks its own tree (its walk is
+ *  interleaved with the budget and the matcher) and `walkCorpus` walks
+ *  here, but both ask THIS — which is the whole point of there being one
+ *  corpus rather than two walkers that agree by coincidence. */
+export function corpusSkips(declared, layers, full, name, isDir) {
+    if (name === "node_modules" || name === ".git")
+        return true;
+    if (isCredentialName(name))
+        return true;
+    if (!declared)
+        return name.startsWith(".");
+    return ignoredBy(layers, full, isDir);
+}
+/** The layers in force inside `dir`, given its parent's. */
+export function layersEntering(dir, parent) {
+    const own = readLayer(dir);
+    return own === null ? parent : [...parent, own];
+}
+export function walkCorpus(opts) {
+    const root = opts.workspaceRoot;
+    const maxDepth = opts.maxDepth ?? CORPUS_MAX_DEPTH;
+    const maxEntries = opts.maxEntries ?? Number.POSITIVE_INFINITY;
+    const rootLayer = readLayer(root);
+    /** No declaration, nothing to trust: the pre-corpus rule, unchanged. */
+    const declared = rootLayer !== null;
+    const files = [];
+    let cutByDepth = false;
+    let cutByCap = false;
+    const walk = (dir, depth, layers) => {
+        if (cutByCap)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return; // unreadable directory: skipped, as before
+        }
+        const here = depth === 0 ? layers : layersEntering(dir, layers);
+        for (const entry of entries) {
+            if (cutByCap)
+                return;
+            const name = entry.name;
+            const full = join(dir, name);
+            const isDir = entry.isDirectory();
+            if (corpusSkips(declared, here, full, name, isDir))
+                continue;
+            if (isDir) {
+                if (opts.isExcluded?.(full) === true)
+                    continue;
+                if (depth + 1 > maxDepth) {
+                    cutByDepth = true;
+                    continue;
+                }
+                walk(full, depth + 1, here);
+                continue;
+            }
+            const rel = relative(root, full).split(sep).join("/");
+            if (opts.accept !== undefined && !opts.accept(rel))
+                continue;
+            if (files.length >= maxEntries) {
+                cutByCap = true;
+                return;
+            }
+            files.push(rel);
+        }
+    };
+    const start = opts.walkFrom ?? root;
+    // entering a subtree, the layers between root and it still apply
+    let startLayers = rootLayer === null ? [] : [rootLayer];
+    if (start !== root) {
+        let cur = root;
+        for (const part of relative(root, start).split(sep).filter(Boolean)) {
+            cur = join(cur, part);
+            startLayers = layersEntering(cur, startLayers);
+        }
+    }
+    walk(start, 0, startLayers);
+    return { files, cutByDepth, cutByCap };
+}
+/** A minimal glob → RegExp, anchored, over workspace-relative POSIX paths.
+ *
+ *  `*` any run except `/`, `?` one character except `/`, `**` any run
+ *  including `/`. A leading `** /` (without the space) matches zero or
+ *  more directories, so `**\/*.ts` finds a root-level `a.ts` — the
+ *  behaviour people expect and the one a naive translation gets wrong by
+ *  requiring at least one directory.
+ *
+ *  Everything else is literal, including the regex metacharacters a path
+ *  can legally contain. */
+export function globToRegExp(pattern) {
+    let out = "";
+    for (let i = 0; i < pattern.length; i += 1) {
+        const c = pattern[i];
+        if (c === "*") {
+            if (pattern[i + 1] === "*") {
+                // `**/` spans zero or more directories; a bare `**` spans anything
+                if (pattern[i + 2] === "/") {
+                    out += "(?:.*/)?";
+                    i += 2;
+                }
+                else {
+                    out += ".*";
+                    i += 1;
+                }
+            }
+            else
+                out += "[^/]*";
+            continue;
+        }
+        if (c === "?") {
+            out += "[^/]";
+            continue;
+        }
+        out += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    }
+    return new RegExp(`^${out}$`);
+}

package/dist/index.d.ts

@@ -145,6 +145,7 @@ export declare function readFileTool(opts: WorkspaceToolsOptions): Tool<{
 }>;
 export declare function listDirTool(opts: WorkspaceToolsOptions): Tool<{
     path?: string;
+    glob?: string;
 }>;
 /** The instrument behind gate (d): live workers and queue depth. */
 export declare function searchWorkerStats(): {

package/dist/index.js

@@ -24,11 +24,13 @@ import { Worker } from "node:worker_threads";
 import { fileURLToPath } from "node:url";
 import { createHash } from "node:crypto";
 import { tmpdir } from "node:os";
-import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { defineTool } from "@vincemakes/kiso-core";
 // WR-1/WR-1A — the revision-guard primitives (unit-tested in wr1a-coda):
 import { strippedShellEnv } from "./secret-env.js";
 import { contentRevision, normalizeRevision, postEffectEscape, precondition, publishNewFile, revalidateBeforeRename } from "./wr1.js";
+import { CORPUS_MAX_DEPTH, globToRegExp, walkCorpus } from "./corpus.js";
+import { describeSearchMiss } from "./search-miss.js";
 /**
  * TUI2-R1 (C) — THE SHELL PROGRESS SIDECAR.
  *
@@ -68,6 +70,11 @@ export function shellProgressPath(sessionId, command) {
     const key = createHash("sha256").update(`${sessionId ?? ""} ${command}`).digest("hex").slice(0, 16);
     return join(SHELL_PROGRESS_DIR, `${key}.log`);
 }
+/** ACI-2: at most this many DISTINCT match lines are named in a refusal. */
+const ACI2_LINES_SHOWN = 5;
+/** Match offsets kept for that report. Past this the refusal says "more"
+ *  without a number rather than one it cannot stand behind. */
+const ACI2_OFFSETS_KEPT = 500;
 const OUTPUT_CAP = 100_000; // chars of output a tool result may carry
 const DEFAULT_SHELL_TIMEOUT_MS = 30_000;
 // the token round: the scoped-read defaults — read_file shows the head 200 lines
@@ -76,6 +83,12 @@ const DEFAULT_SHELL_TIMEOUT_MS = 30_000;
 // red line: every truncation names its continuation — the model always
 // has a path to the full content.
 const DEFAULT_READ_LINES = 200;
+/** The default window's SECOND bound, and the one lines cannot express: 200
+ *  lines of minified source is megabytes, 200 lines of prose is a few KB.
+ *  Whichever binds first wins, and the cut is always at a line boundary. An
+ *  explicit `limit` is the caller saying what they want and is not capped
+ *  here — the 100k output cap still applies to it. */
+const DEFAULT_READ_CHARS = 16_000;
 /** R3: how many files a search may read before it hands the event loop
  *  back. Small enough that the 200ms motion cadence never misses a beat,
  *  large enough that the yield costs nothing on a small tree. */
@@ -305,13 +318,17 @@ const INODE_SCAN_MS = 2_000;
 /** The "… N more lines" note — the actionable continuation: the exact
  *  line the next read must start at, so the model can always reach the
  *  full content in ranges (the red line). */
-function moreLinesNote(nextOffset, remaining) {
-    return `\n… ${remaining} more ${remaining === 1 ? "line" : "lines"} (call again with offset=${nextOffset})`;
+function moreLinesNote(nextOffset, remaining, limit) {
+    // BOTH parameters. Naming only `offset` was an instruction to read the
+    // rest of the file: with `limit` absent the read runs to EOF, so a model
+    // following its own continuation note defeated the window from the second
+    // read onward. Measured before the fix: 7.3% of real reads took that path.
+    return `\n… ${remaining} more ${remaining === 1 ? "line" : "lines"} (call again with offset=${nextOffset} limit=${limit})`;
 }
 export function readFileTool(opts) {
     return defineTool({
         name: "read_file",
-        description: "Read a workspace file or a range (offset/limit; default: the first 200 lines, with a continuation note). The final [rev:X] line identifies the version read.",
+        description: "Read a workspace file or a range. Without `limit`: 200 lines or 16000 chars from `offset` (default 1), whichever binds, then a note naming the next offset and limit. The final [rev:X] line identifies the version read.",
         parameters: {
             type: "object",
             properties: {
@@ -398,21 +415,44 @@ export function readFileTool(opts) {
                         errorKind: "invalid_input",
                     };
                 }
-                const end = limit === undefined ? total : Math.min(start + limit - 1, total);
-                // DEFAULT: the head 200 lines; a larger file ends with the
-                // honest continuation note (small files ≤ 200 lines are
-                // byte-identical to the pre-token-round behavior).
+                // THE DEFAULT WINDOW applies whenever `limit` is ABSENT, from
+                // `offset ?? 1`. It used to apply only when BOTH were absent,
+                // so an offset alone read to the end of the file — and since
+                // the note named only `offset`, a model following its own
+                // continuation note left the window behind after one read.
                 let text;
                 let note = "";
-                if (offset === undefined && limit === undefined) {
-                    text = total <= DEFAULT_READ_LINES ? content : parts.slice(0, DEFAULT_READ_LINES).join("\n");
-                    if (total > DEFAULT_READ_LINES)
-                        note = moreLinesNote(DEFAULT_READ_LINES + 1, total - DEFAULT_READ_LINES);
+                if (limit === undefined) {
+                    const lastLine = Math.min(start + DEFAULT_READ_LINES - 1, total);
+                    const slice = parts.slice(start - 1, lastLine);
+                    let body = slice.join("\n");
+                    let shown = slice.length;
+                    if (body.length > DEFAULT_READ_CHARS) {
+                        const cut = body.lastIndexOf("\n", DEFAULT_READ_CHARS);
+                        if (cut > 0) {
+                            body = body.slice(0, cut);
+                            shown = body.split("\n").length;
+                        }
+                        else {
+                            // No newline inside the budget: the first line alone
+                            // is over it. One WHOLE line is the smallest honest
+                            // answer — a cut mid-line is a lie about the file.
+                            body = slice[0] ?? "";
+                            shown = 1;
+                        }
+                    }
+                    // The whole file from line 1 is returned VERBATIM, trailing
+                    // newline included: `parts.join` would drop it.
+                    text = start === 1 && shown === total ? content : body;
+                    const next = start + shown;
+                    if (next <= total)
+                        note = moreLinesNote(next, total - next + 1, DEFAULT_READ_LINES);
                 }
                 else {
+                    const end = Math.min(start + limit - 1, total);
                     text = parts.slice(start - 1, end).join("\n");
                     if (end < total)
-                        note = moreLinesNote(end + 1, total - end);
+                        note = moreLinesNote(end + 1, total - end, limit);
                 }
                 // The output cap's cut must STAY actionable: cut at a line
                 // boundary and name the exact next offset (the generic cap()
@@ -449,10 +489,13 @@ export function readFileTool(opts) {
 export function listDirTool(opts) {
     return defineTool({
         name: "list_dir",
-        description: "List the entries of a directory. Omit path to list the workspace root. Capped at 200 entries with an overflow note (narrow to a subdirectory for more).",
+        description: "List the entries of a directory, or with glob, search the tree recursively for workspace-relative paths matching it. Capped at 200 with an overflow note.",
         parameters: {
             type: "object",
-            properties: { path: { type: "string", description: "Workspace-relative directory to list" } },
+            properties: {
+                path: { type: "string", description: "Workspace-relative directory to list" },
+                glob: { type: "string", description: "Recursive search: * and ? within a segment, ** across them; matched against workspace-relative paths" },
+            },
             additionalProperties: false,
         },
         idempotent: true,
@@ -460,9 +503,35 @@ export function listDirTool(opts) {
         effects: { precommitSafe: true, concurrency: "shared" },
         promptSnippet: "list_dir — directory entries (the workspace ls)",
         promptGuidelines: ["narrow to a subdirectory when the listing caps at 200 entries"],
-        execute: async ({ path }) => {
+        execute: async ({ path, glob }) => {
             try {
                 const dir = resolveWithinRoot(opts.workspaceRoot, path ?? ".");
+                // ACI-8: with a pattern this is a recursive search over the
+                // SAME corpus `search_text` uses — one definition, so the two
+                // cannot drift the way they had.
+                if (glob !== undefined) {
+                    const re = globToRegExp(glob);
+                    const walk = walkCorpus({
+                        workspaceRoot: opts.workspaceRoot,
+                        walkFrom: dir,
+                        maxEntries: MAX_DIR_ENTRIES,
+                        accept: (rel) => re.test(rel),
+                        isExcluded: (full) => {
+                            const r = relative(opts.workspaceRoot, full).split(sep).join("/");
+                            return (opts.excludeRoots ?? []).some((ex) => r === ex || r.startsWith(`${ex}/`));
+                        },
+                    });
+                    const body = walk.files.length ? cap(walk.files.join("\n")) : `(no match for ${glob})`;
+                    // TWO truncations, different remedies, and neither claimed
+                    // when it did not happen: a walk that silently returns less
+                    // is the defect a note exists to prevent.
+                    const notes = [];
+                    if (walk.cutByCap)
+                        notes.push(`${MAX_DIR_ENTRIES} shown (narrow the pattern for more)`);
+                    if (walk.cutByDepth)
+                        notes.push(`the walk stopped at depth ${CORPUS_MAX_DEPTH} — anything deeper is not listed`);
+                    return { content: notes.length ? `${body}\n… ${notes.join("; ")}` : body, isError: false };
+                }
                 // DC-54 — TRUNCATED BEFORE IT BUILDS. It was a `.map` over
                 // EVERY entry with the 200-entry slice only after: a directory
                 // of 200,000 entries built 200,000 strings to show 200 of
@@ -663,7 +732,12 @@ export function searchTextTool(opts) {
             // CX-1 F4 (audit F4): the walk-and-match runs on its OWN thread, which
             // the deadline and the abort both TERMINATE. A catastrophic regex used
             // to block this loop — no budget check, timer or abort could run.
-            const outcome = await runSearchWorker({ token: 0, root: searchRootReal, single, pattern, flags, excluded, maxFileBytes, maxFiles, deadline, maxMatches: MAX_SEARCH_MATCHES, sniffBytes: BINARY_SNIFF_BYTES }, deadline, ctx.signal);
+            const outcome = await runSearchWorker(
+            // The workspace root is realpath'd with the SAME helper the search
+            // root uses: `full` is walked from a realpath'd root, and making
+            // a path relative between a resolved and an unresolved base
+            // yields `../..` the moment a symlink sits between them.
+            { token: 0, root: searchRootReal, workspaceRoot: realOrSelf(opts.workspaceRoot), single, pattern, flags, excluded, maxFileBytes, maxFiles, deadline, maxMatches: MAX_SEARCH_MATCHES, sniffBytes: BINARY_SNIFF_BYTES }, deadline, ctx.signal);
             if (outcome.kind === "aborted")
                 return { content: "search_text aborted", isError: true, errorKind: "fatal" };
             if (outcome.kind === "error")
@@ -838,10 +912,62 @@ export function writeFileTool(opts) {
         },
     });
 }
+/** ACI-2: every offset where `search` occurs, OVERLAPPING ones included —
+ *  "aa" occurs twice in "aaa", and the two resolutions differ, so the call
+ *  is ambiguous. A scan that steps past each match by its own length
+ *  reports one and edits blind. This is the ONLY scan: `count === 0` is the
+ *  missing pattern and `offsets[0]` is where a unique one resolved. */
+function occurrencesOf(text, search) {
+    const offsets = [];
+    let count = 0;
+    for (let at = text.indexOf(search); at !== -1;) {
+        count += 1;
+        if (offsets.length < ACI2_OFFSETS_KEPT)
+            offsets.push(at);
+        // The cursor must ADVANCE. indexOf("", n) clamps n to the string
+        // length and then returns the same offset forever — a synchronous
+        // spin no test timeout can interrupt. The single indexOf this
+        // replaced could not hang; a loop has to earn that.
+        const next = text.indexOf(search, at + 1);
+        if (next <= at)
+            break;
+        at = next;
+    }
+    return { count, offsets };
+}
+/** The distinct 1-based lines the (ASCENDING) offsets fall on, in ONE pass —
+ *  a line lookup per offset re-walks the file and a common pattern has
+ *  hundreds of them. Ascending order is what lets adjacent-dedupe stand in
+ *  for a set. */
+function linesOfOffsets(text, offsets) {
+    const lines = [];
+    let line = 1;
+    let i = 0;
+    for (const at of offsets) {
+        for (; i < at; i += 1)
+            if (text.charCodeAt(i) === 10)
+                line += 1;
+        if (lines[lines.length - 1] !== line)
+            lines.push(line);
+    }
+    return lines;
+}
+/** "line 4" / "lines 1, 2" / "lines 1, 2, 3, 4, 5 and 35 more" — the tail
+ *  counts LINES not yet named, never matches: a pattern hit ten times on
+ *  one line reads "line 1", because "and 9 more" would send the caller
+ *  looking for nine lines that are not there. `exhaustive` false means the
+ *  offsets themselves were capped, so the tail carries no number at all. */
+function describeMatchLines(text, offsets, exhaustive) {
+    const lines = linesOfOffsets(text, offsets);
+    const shown = lines.slice(0, ACI2_LINES_SHOWN);
+    const hidden = lines.length - shown.length;
+    const tail = !exhaustive ? " and more" : hidden > 0 ? ` and ${hidden} more` : "";
+    return `${shown.length === 1 && tail === "" ? "line" : "lines"} ${shown.join(", ")}${tail}`;
+}
 export function editFileTool(opts) {
     return defineTool({
         name: "edit_file",
-        description: "Edit a workspace file at its latest revision (expectedRevision). ONE of: search+replace (first exact occurrence), or edits (1-32 disjoint hunks resolved against the same snapshot, applied atomically).",
+        description: "Edit a workspace file at its latest revision (expectedRevision). ONE of: search+replace (must match exactly once), or edits (1-32 disjoint hunks resolved against the same snapshot, applied atomically).",
         parameters: {
             type: "object",
             properties: {
@@ -936,19 +1062,37 @@ export function editFileTool(opts) {
                 const text = bytes.toString("utf8");
                 // WR-1E2: EVERY hunk resolves against THIS snapshot — never the
                 // output of an earlier hunk. All spans are known before any
-                // staging; overlaps refuse (duplicate searches both resolve
-                // first-occurrence and therefore overlap — never retargeted).
+                // staging; overlaps refuse. Since ACI-2 a non-unique search is
+                // already refused above, so the overlap left to catch is two
+                // hunks aimed at the same unique text — never retargeted.
                 const spans = [];
                 for (let i = 0; i < hunks.length; i += 1) {
                     const h = hunks[i];
-                    const at = text.indexOf(h.search);
-                    if (at === -1) {
+                    const { count, offsets } = occurrencesOf(text, h.search);
+                    if (count === 0) {
                         // WR-1A ④: the WORLD lacks the pattern (the input is
                         // fine) and nothing ran — precondition; the note never
                         // rides an edit that wrote nothing.
-                        return precondition(hunks.length === 1 && edits === undefined ? `edit_file: pattern not found in ${path}` : `edit_file: pattern not found in ${path} (hunk ${i + 1})`);
+                        // The headline says WHAT failed; the detail says WHERE.
+                        // A refusal that names the divergence costs one line
+                        // here and saves a whole file read at the caller.
+                        const headline = hunks.length === 1 && edits === undefined
+                            ? `edit_file: pattern not found in ${path}`
+                            : `edit_file: pattern not found in ${path} (hunk ${i + 1})`;
+                        const detail = describeSearchMiss(text, h.search);
+                        return precondition(detail ? `${headline}\n${detail}` : headline);
+                    }
+                    // ACI-2: more than one resolution is a QUESTION, not an edit.
+                    // Taking the first one wrote the wrong place and reported
+                    // success — the one failure shape a mutation tool must not
+                    // have. The refusal carries the count and the lines so the
+                    // call can be fixed without reading the file again.
+                    if (count > 1) {
+                        const lines = describeMatchLines(text, offsets, count <= ACI2_OFFSETS_KEPT);
+                        const where = hunks.length === 1 && edits === undefined ? lines : `hunk ${i + 1}, ${lines}`;
+                        return precondition(`edit_file: pattern matches ${count} places in ${path} (${where}) — include enough surrounding text to make it unique`);
                     }
-                    spans.push({ start: at, end: at + h.search.length, replace: h.replace });
+                    spans.push({ start: offsets[0], end: offsets[0] + h.search.length, replace: h.replace });
                 }
                 const bySpan = [...spans].sort((a, b) => a.start - b.start);
                 for (let i = 1; i < bySpan.length; i += 1) {

package/dist/search-miss.d.ts

@@ -0,0 +1,24 @@
+/**
+ * When a search does not match, say WHERE it stopped matching.
+ *
+ * `edit_file: pattern not found in src/report.js (hunk 2)` is true and
+ * useless. The tool has already established, by failing, that the text is
+ * not there — but it also knows, or can cheaply find out, how much of the
+ * search DID match and what the file has instead. Withholding that leaves
+ * one recourse: read the whole file again.
+ *
+ * This is not a guess about what callers need. Ten refused edits in one
+ * measured session were all `pattern not found`, none stale, none
+ * overlapping, and in every one of them a long prefix matched before the
+ * search ran into text the caller had not written yet — 93 of 223
+ * characters, 94 of 286, 306 of 913. Four more searched for an import
+ * line with the new symbol ALREADY IN IT. The failure has one shape: the
+ * search describes the file as it will be, not as it is. A message that
+ * names the divergence answers that in one line; the current one costs a
+ * whole file read to discover.
+ */
+/**
+ * The detail lines for a failed search, or "" when there is nothing useful
+ * to say. The caller owns the headline; this is what follows it.
+ */
+export declare function describeSearchMiss(text: string, search: string): string;

package/dist/search-miss.js

@@ -0,0 +1,94 @@
+/**
+ * When a search does not match, say WHERE it stopped matching.
+ *
+ * `edit_file: pattern not found in src/report.js (hunk 2)` is true and
+ * useless. The tool has already established, by failing, that the text is
+ * not there — but it also knows, or can cheaply find out, how much of the
+ * search DID match and what the file has instead. Withholding that leaves
+ * one recourse: read the whole file again.
+ *
+ * This is not a guess about what callers need. Ten refused edits in one
+ * measured session were all `pattern not found`, none stale, none
+ * overlapping, and in every one of them a long prefix matched before the
+ * search ran into text the caller had not written yet — 93 of 223
+ * characters, 94 of 286, 306 of 913. Four more searched for an import
+ * line with the new symbol ALREADY IN IT. The failure has one shape: the
+ * search describes the file as it will be, not as it is. A message that
+ * names the divergence answers that in one line; the current one costs a
+ * whole file read to discover.
+ */
+/** The longest prefix of `needle` that occurs in `hay`, by length.
+ *
+ *  Monotone — if a prefix occurs then so does every shorter one — so this
+ *  binary-searches instead of walking. A linear walk is O(m) substring
+ *  searches, which on a large file and a long search is the kind of cost
+ *  that turns a better error message into a worse tool.
+ */
+function longestMatchingPrefix(hay, needle) {
+    let lo = 0;
+    let hi = needle.length;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if (hay.includes(needle.slice(0, mid)))
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return lo;
+}
+/** 1-based line number of an offset. */
+function lineAt(text, offset) {
+    let n = 1;
+    for (let i = 0; i < offset && i < text.length; i += 1)
+        if (text.charCodeAt(i) === 10)
+            n += 1;
+    return n;
+}
+/** A fragment for a one-line message: escaped, and bounded. */
+function fragment(s, max = 60) {
+    const cut = s.slice(0, max);
+    const shown = JSON.stringify(cut).slice(1, -1); // drop the quotes, keep \n and \t visible
+    return s.length > max ? `${shown}…` : shown;
+}
+/**
+ * The detail lines for a failed search, or "" when there is nothing useful
+ * to say. The caller owns the headline; this is what follows it.
+ */
+export function describeSearchMiss(text, search) {
+    if (search.length === 0)
+        return "";
+    const matched = longestMatchingPrefix(text, search);
+    if (matched === 0) {
+        const firstLine = search.split("\n", 1)[0] ?? "";
+        return `  no part of it appears in the file — it begins "${fragment(firstLine)}"`;
+    }
+    // The FIRST place the prefix appears. Since ACI-2 the tool no longer
+    // has first-occurrence semantics to match, so the reason is now this
+    // function's own: a miss report needs one location and the earliest is
+    // the deterministic choice. A prefix occurring in several places is
+    // reported at the earliest of them, which can be further from where the
+    // caller was aiming than the report admits.
+    const at = text.indexOf(search.slice(0, matched));
+    const endOfMatch = at + matched;
+    const line = lineAt(text, at);
+    const endLine = lineAt(text, endOfMatch);
+    const head = `  ${matched} of ${search.length} characters matched, from line ${line} to line ${endLine}`;
+    const rest = search.slice(matched);
+    // RUNNING PAST THE END IS THE COMMON CASE AND ITS OWN SENTENCE. Four of
+    // the ten refusals in the measured session ended exactly here, and
+    // rendering that as `the file then has: ""` buries the one fact worth
+    // having: there is no more file. A caller that appended what it meant
+    // to ADD onto the end of what it meant to FIND reads its own mistake
+    // off this line.
+    if (endOfMatch >= text.length) {
+        return [
+            head,
+            `  the file ENDS there — your search continues for ${rest.length} more characters: "${fragment(rest)}"`,
+        ].join("\n");
+    }
+    return [
+        head,
+        `  the file then has:  "${fragment(text.slice(endOfMatch))}"`,
+        `  your search wanted: "${fragment(rest)}"`,
+    ].join("\n");
+}

package/dist/search-worker.d.ts

@@ -18,6 +18,12 @@
 export interface SearchRequest {
     readonly token: number;
     readonly root: string;
+    /** The WORKSPACE root, which is not always the search root: a search under
+     *  `packages/runtime` must still name `packages/runtime/src/run.ts` so the
+     *  result can be handed to `read_file` unchanged. Realpath'd by the
+     *  caller, because `full` is walked from a realpath'd root and a mixed
+     *  pair produces `../..` the moment a symlink is involved. */
+    readonly workspaceRoot: string;
     /** a single file to scan instead of walking `root` */
     readonly single: string | null;
     readonly pattern: string;

package/dist/search-worker.js

@@ -16,8 +16,33 @@
  * message from a superseded worker is ignored.
  */
 import { open, readdir } from "node:fs/promises";
-import { join, relative } from "node:path";
+import { basename, join, relative } from "node:path";
+import { corpusSkips, layersEntering, readLayer } from "./corpus.js";
 import { isMainThread, parentPort } from "node:worker_threads";
+/** ACI-5 — the excerpt WINDOWS THE MATCH instead of taking the line's head.
+ *
+ *  `line.trim().slice(0, 160)` answers "what does this line start with",
+ *  and the model asked "where is my pattern". Measured over 171 real
+ *  search results and 1,931 excerpt lines: 11.7% hit the 160-char cut and
+ *  6.1% did not contain the pattern they matched — a hit the model cannot
+ *  act on without spending a read to find out what it found.
+ *
+ *  A short line is returned exactly as before, markers and all absent, so
+ *  the common case is byte-identical. */
+const EXCERPT_RADIUS = 80;
+function excerptAround(line, regex) {
+    const trimmed = line.trim();
+    if (trimmed.length <= EXCERPT_RADIUS * 2)
+        return trimmed;
+    // A fresh non-global copy: `lastIndex` on a shared /g regex would make
+    // the excerpt depend on which line was scanned before it.
+    const found = new RegExp(regex.source, regex.flags.replace("g", "")).exec(trimmed);
+    const at = found ? found.index : 0;
+    const hit = found ? found[0].length : 0;
+    const start = Math.max(0, at - EXCERPT_RADIUS);
+    const end = Math.min(trimmed.length, at + hit + EXCERPT_RADIUS);
+    return `${start > 0 ? "…" : ""}${trimmed.slice(start, end)}${end < trimmed.length ? "…" : ""}`;
+}
 export async function runSearch(req) {
     const regex = new RegExp(req.pattern, req.flags);
     const matches = [];
@@ -77,8 +102,11 @@ export async function runSearch(req) {
             for (const [i, line] of text.split("\n").entries()) {
                 if (regex.test(line)) {
                     totalMatches += 1;
+                    // WORKSPACE-RELATIVE, not absolute: `read_file` refuses an
+                    // absolute path, so an absolute hit here is a result the
+                    // model cannot feed back without rewriting it by hand.
                     if (matches.length < req.maxMatches)
-                        matches.push(`${full}:${i + 1}: ${line.trim().slice(0, 160)}`);
+                        matches.push(`${relative(req.workspaceRoot, full) || basename(full)}:${i + 1}: ${excerptAround(line, regex)}`);
                 }
             }
         }
@@ -86,7 +114,11 @@ export async function runSearch(req) {
             // unreadable file: skipped, like before
         }
     };
-    const walk = async (dir, depth) => {
+    // ACI-4/ACI-8: the corpus is declared by a `.gitignore` FILE at the
+    // workspace root — not by `.git`, and the walk never goes up.
+    const rootLayer = readLayer(req.root);
+    const declared = rootLayer !== null;
+    const walk = async (dir, depth, layers) => {
         if (depth > 8 || outOfBudget())
             return;
         let entries;
@@ -101,18 +133,20 @@ export async function runSearch(req) {
             }
             throw err;
         }
+        const here = depth === 0 ? layers : layersEntering(dir, layers);
         for (const entry of entries) {
             if (outOfBudget())
                 return;
-            if (entry.name.startsWith(".") || entry.name === "node_modules")
-                continue;
             const full = join(dir, entry.name);
-            if (entry.isDirectory()) {
+            const isDir = entry.isDirectory();
+            if (corpusSkips(declared, here, full, entry.name, isDir))
+                continue;
+            if (isDir) {
                 if (isExcluded(full)) {
                     excludedDirs += 1;
                     continue;
                 }
-                await walk(full, depth + 1);
+                await walk(full, depth + 1, here);
             }
             else if (entry.isFile())
                 await scanFile(full);
@@ -122,7 +156,7 @@ export async function runSearch(req) {
         if (req.single !== null)
             await scanFile(req.single);
         else
-            await walk(req.root, 0);
+            await walk(req.root, 0, rootLayer === null ? [] : [rootLayer]);
     }
     catch (err) {
         return { token: req.token, matches, totalMatches, filesSeen, skippedFiles, multiLink, unreadableDirs, excludedDirs, stopped, stoppedAt, error: err.message };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vincemakes/kiso-tools-node",
-	"version": "0.36.0",
+	"version": "0.38.0",
 	"description": "kiso coding tools for Node hosts \u2014 read file, list directory, search text, write/edit file, shell command.",
 	"type": "module",
 	"license": "MIT",
@@ -25,7 +25,8 @@
 		"test": "vitest run"
 	},
 	"dependencies": {
-		"@vincemakes/kiso-core": "0.36.0"
+		"@vincemakes/kiso-core": "0.38.0",
+		"ignore": "^7.0.9"
 	},
 	"devDependencies": {
 		"@types/node": "^26.1.2",