@vincemakes/kiso-tools-node 0.47.3 → 0.49.0

package/dist/corpus.d.ts

@@ -101,6 +101,18 @@ export declare function corpusSkips(declared: boolean, layers: readonly Layer[],
 /** 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;
+/** Directory entries by name, in UTF-16 code-unit order — the same on
+ *  every platform, unlike readdir's own order (name order on APFS and
+ *  NTFS, hash order on ext4). */
+export declare function byName(a: {
+    name: string;
+}, b: {
+    name: string;
+}): number;
+/** Workspace-relative POSIX paths by segment, each by code unit: `a/x`
+ *  before `a-b` before `b`, which is the order a depth-first walk by name
+ *  lists them in. */
+export declare function bySegments(a: string, b: string): number;
 /** A minimal glob → RegExp, anchored, over workspace-relative POSIX paths.
  *
  *  `*` any run except `/`, `?` one character except `/`, `**` any run

package/dist/corpus.js

@@ -147,24 +147,43 @@ export function walkCorpus(opts) {
     let cutByDeadline = false;
     let visited = 0;
     const stopped = () => cutByCap || cutByVisits || cutByDeadline;
-    const walk = (dir, depth, layers) => {
-        if (stopped())
-            return;
+    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);
+        }
+    }
+    // 0.48.0 (finding 0472-F2) — BREADTH-FIRST, files before directories.
+    // The walk was depth-first in readdir order, so under a budget a deep
+    // sibling directory spent it before a file one level up was looked at:
+    // `Desktop/devv/` sorts before `Desktop/generations.ts`, and the owner's
+    // glob for that file stopped inside devv. Level by level, each
+    // directory's entries in name order and its files first, the budget cuts
+    // the deepest part of the tree and never a file nearer the root.
+    const queue = [{ dir: start, depth: 0, layers: startLayers }];
+    for (let next = 0; next < queue.length && !stopped(); next += 1) {
+        const { dir, depth, layers } = queue[next];
         if (Date.now() > deadline) {
             cutByDeadline = true;
-            return;
+            break;
         }
         let entries;
         try {
             entries = readdirSync(dir, { withFileTypes: true });
         }
         catch {
-            return; // unreadable directory: skipped, as before
+            continue; // unreadable directory: skipped, as before
         }
+        entries.sort(byName);
         const here = depth === 0 ? layers : layersEntering(dir, layers);
+        const subdirs = [];
         for (const entry of entries) {
             if (stopped())
-                return;
+                break;
             const name = entry.name;
             const full = join(dir, name);
             const isDir = entry.isDirectory();
@@ -177,42 +196,53 @@ export function walkCorpus(opts) {
                     cutByDepth = true;
                     continue;
                 }
-                walk(full, depth + 1, here);
+                subdirs.push({ dir: full, depth: depth + 1, layers: here });
                 continue;
             }
             if (visited >= maxVisited) {
                 cutByVisits = true;
-                return;
+                break;
             }
             visited += 1;
             // the clock is read every 256 files, not per file
             if ((visited & 255) === 0 && Date.now() > deadline) {
                 cutByDeadline = true;
-                return;
+                break;
             }
             const rel = relative(root, full).split(sep).join("/");
             if (opts.accept !== undefined && !opts.accept(rel))
                 continue;
             if (files.length >= maxEntries) {
                 cutByCap = true;
-                return;
+                break;
             }
             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);
-        }
+        queue.push(...subdirs);
     }
-    walk(start, 0, startLayers);
+    // what was walked, in an order that does not depend on the filesystem's
+    // readdir: by path segments, which is a depth-first listing by name
+    files.sort(bySegments);
     return { files, cutByDepth, cutByCap, cutByVisits, cutByDeadline, visited };
 }
+/** Directory entries by name, in UTF-16 code-unit order — the same on
+ *  every platform, unlike readdir's own order (name order on APFS and
+ *  NTFS, hash order on ext4). */
+export function byName(a, b) {
+    return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+}
+/** Workspace-relative POSIX paths by segment, each by code unit: `a/x`
+ *  before `a-b` before `b`, which is the order a depth-first walk by name
+ *  lists them in. */
+export function bySegments(a, b) {
+    const x = a.split("/");
+    const y = b.split("/");
+    for (let i = 0; i < Math.min(x.length, y.length); i += 1) {
+        if (x[i] !== y[i])
+            return x[i] < y[i] ? -1 : 1;
+    }
+    return x.length - y.length;
+}
 /** A minimal glob → RegExp, anchored, over workspace-relative POSIX paths.
  *
  *  `*` any run except `/`, `?` one character except `/`, `**` any run

package/dist/index.d.ts

@@ -156,6 +156,10 @@ export interface WorkspaceToolsOptions {
         readonly searchMaxMs?: number;
         /** read_file: refuse a file larger than this (default 64 MiB). */
         readonly readMaxFileBytes?: number;
+        /** shell, with tasks wired: the least foreground wait (default 60s,
+         *  the default wait). A shorter `foregroundMs` is raised to it; 0
+         *  keeps the model's value as asked (ADR-0058 Amendment 10). */
+        readonly minForegroundMs?: number;
     };
 }
 export declare function readFileTool(opts: WorkspaceToolsOptions): Tool<{
@@ -183,16 +187,23 @@ export declare function writeFileTool(opts: WorkspaceToolsOptions): Tool<{
     content: string;
     expectedRevision?: string;
 }>;
-export declare function editFileTool(opts: WorkspaceToolsOptions): Tool<{
+/** One hunk as a caller may send it: the current vocabulary, or the
+ *  legacy `search`/`replace` a durable log or a host may still hold. */
+type EditHunkInput = {
+    readonly oldText?: string;
+    readonly newText?: string;
+    readonly search?: string;
+    readonly replace?: string;
+    readonly expectedRevision?: string;
+};
+type EditFileInput = {
     path: string;
+    edits?: readonly EditHunkInput[];
     search?: string;
     replace?: string;
-    edits?: readonly {
-        search: string;
-        replace: string;
-    }[];
     expectedRevision?: string;
-}>;
+};
+export declare function editFileTool(opts: WorkspaceToolsOptions): Tool<EditFileInput>;
 export { SHELL_STRIP_EXACT, strippedShellEnv } from "./secret-env.js";
 export { PROTECTED_REFUSAL, diskPath, isProtectedPath, protectedIdentity, protectedRefusalText, readUnlessProtected, type ProtectedIdentity } from "./protected.js";
 /** The search corpus's credential rule, by name — exported so the CLI's

package/dist/index.js

@@ -382,7 +382,7 @@ export function readFileTool(opts) {
         // safety claim: the kernel enforces both, and had this line been
         // omitted the tool would simply have been slower, never less correct.
         effects: { precommitSafe: true, concurrency: "shared" },
-        promptSnippet: "read_file — whole files or offset/limit ranges, workspace-relative paths",
+        promptSnippet: "read_file — read a file or a line range",
         promptGuidelines: ["read only the range you need — offset/limit beat whole-file reads"],
         execute: async ({ path, offset, limit }, ctx) => {
             const maxReadBytes = opts.limits?.readMaxFileBytes ?? READ_MAX_FILE_BYTES;
@@ -544,7 +544,7 @@ export function listDirTool(opts) {
         idempotent: true,
         // EC-1 ②: read-only, free, local — see read_file above.
         effects: { precommitSafe: true, concurrency: "shared" },
-        promptSnippet: "list_dir — directory entries (the workspace ls)",
+        promptSnippet: "list_dir — list a directory",
         promptGuidelines: ["narrow to a subdirectory when the listing caps at 200 entries"],
         execute: async ({ path, glob }, ctx) => {
             try {
@@ -761,7 +761,7 @@ export function searchTextTool(opts) {
         // commit-required and exclusive, which is what closes the same-path
         // write race without asking their authors to remember anything.
         effects: { precommitSafe: true, concurrency: "shared" },
-        promptSnippet: "search_text — regex search over workspace files",
+        promptSnippet: "search_text — regex search in files",
         promptGuidelines: ["narrow the pattern when the result caps — never re-run a broad search"],
         execute: async ({ pattern, path, caseSensitive }, ctx) => {
             let root;
@@ -868,8 +868,8 @@ export function writeFileTool(opts) {
             required: ["path", "content", "expectedRevision"],
             additionalProperties: false,
         },
-        promptSnippet: "write_file — create or replace a whole file",
-        promptGuidelines: ["write/edit: cite the file's latest revision as expectedRevision; each successful mutation returns the next one; use \"absent\" only to create"],
+        promptSnippet: "write_file — write a whole file",
+        promptGuidelines: ["cite the file's latest revision as expectedRevision; each successful mutation returns the next one; use \"absent\" only to create"],
         execute: async ({ path, content, expectedRevision: citedRevision }) => {
             const maxReadBytes = opts.limits?.readMaxFileBytes ?? READ_MAX_FILE_BYTES;
             // WR-1-F2: normalize every plausible copy of the token FIRST —
@@ -1086,26 +1086,64 @@ function staleReport(text, hunks, single) {
     }
     return out.join("\n");
 }
+/**
+ * ADR-0061 — compatibility belongs in the executor; vocabulary belongs in
+ * the schema. The model is shown one form (`edits` of `{oldText, newText}`):
+ * `search`/`replace` was written SWAPPED in 80 of 86 failed T6 edits (the
+ * 2026-10-08 replay), and old/new cannot be read backwards. Everything a
+ * caller that skips schema validation may send — an approved call persisted
+ * before the upgrade, a host, a test — is still taken here: legacy hunks,
+ * the legacy top-level pair, a hunk-level `expectedRevision` (ignored, the
+ * call's own governs). A hunk that MIXES the two vocabularies takes neither
+ * half. The schema stays in the small portable subset by choice (no
+ * `oneOf`), so the shape rules live here.
+ */
+function editHunksOf(input) {
+    const pair = input.search !== undefined || input.replace !== undefined;
+    if (pair && input.edits !== undefined)
+        return "edit_file: pass edits — never edits and a top-level search/replace together";
+    if (pair) {
+        if (input.search === undefined || input.replace === undefined)
+            return "edit_file: the legacy top-level form needs BOTH search and replace";
+        return { hunks: [{ search: input.search, replace: input.replace }], single: true };
+    }
+    if (input.edits === undefined)
+        return "edit_file: pass edits \u2014 1\u201332 {oldText, newText} replacements";
+    if (input.edits.length === 0 || input.edits.length > 32)
+        return `edit_file: edits must carry 1\u201332 replacements (got ${input.edits.length})`;
+    const hunks = [];
+    for (let i = 0; i < input.edits.length; i += 1) {
+        const h = input.edits[i];
+        const current = h.oldText !== undefined || h.newText !== undefined;
+        const legacy = h.search !== undefined || h.replace !== undefined;
+        if (current && legacy)
+            return `edit_file: hunk ${i + 1} mixes oldText/newText with search/replace \u2014 send oldText and newText`;
+        const oldText = current ? h.oldText : h.search;
+        const newText = current ? h.newText : h.replace;
+        if (typeof oldText !== "string" || typeof newText !== "string")
+            return `edit_file: hunk ${i + 1} needs both oldText and newText`;
+        hunks.push({ search: oldText, replace: newText });
+    }
+    return { hunks, single: false };
+}
 export function editFileTool(opts) {
     return defineTool({
         name: "edit_file",
-        description: "Edit a file at its latest revision (expectedRevision): search+replace (must match once) OR edits (1-32 hunks, applied in order, all or nothing). A refusal shows the current text and ends on its [rev:X].",
+        description: "Edit a file at its latest revision (expectedRevision): exact replacements, applied in order, all or nothing. Batch changes to this file that are already known into one call. A refusal ends on its [rev:X].",
         parameters: {
             type: "object",
             properties: {
                 path: { type: "string", description: "Workspace-relative file" },
-                search: { type: "string", description: "Exact literal text to find (single-hunk form)" },
-                replace: { type: "string", description: "Replacement text (single-hunk form)" },
                 edits: {
                     type: "array",
-                    description: "Batch form: 1-32 {search, replace} hunks, applied in order",
+                    description: "1-32 replacements",
                     items: {
                         type: "object",
-                        // ACI-3: `expectedRevision` inside a hunk is tolerated and ignored —
-                        // the call's own governs (5 refusals on the owner's disk, every
-                        // one with the top-level token present too).
-                        properties: { search: { type: "string" }, replace: { type: "string" }, expectedRevision: { type: "string" } },
-                        required: ["search", "replace"],
+                        properties: {
+                            oldText: { type: "string", description: "Exact text to replace at this step; must match exactly once after the earlier edits in this call" },
+                            newText: { type: "string", description: "Replacement text for oldText" },
+                        },
+                        required: ["oldText", "newText"],
                         additionalProperties: false,
                     },
                     minItems: 1,
@@ -1113,31 +1151,20 @@ export function editFileTool(opts) {
                 },
                 expectedRevision: { type: "string", description: "The file's latest revision token" },
             },
-            required: ["path", "expectedRevision"],
+            required: ["path", "edits", "expectedRevision"],
             additionalProperties: false,
         },
-        promptSnippet: "edit_file — replace an exact old_string block (never rewrite whole files)",
-        promptGuidelines: ["write/edit: cite the file's latest revision as expectedRevision; each successful mutation returns the next one; use \"absent\" only to create"],
-        execute: async ({ path, search, replace, edits, expectedRevision: citedRevision }) => {
+        promptSnippet: "edit_file — replace oldText with newText",
+        promptGuidelines: ["cite the file's latest revision as expectedRevision; each successful mutation returns the next one; use \"absent\" only to create"],
+        execute: async (input) => {
+            const { path, expectedRevision: citedRevision } = input;
             const maxReadBytes = opts.limits?.readMaxFileBytes ?? READ_MAX_FILE_BYTES;
             // WR-1-F2: normalize the citation (see write_file).
             const expectedRevision = citedRevision === undefined ? undefined : normalizeRevision(citedRevision);
-            // WR-1E2 — the form XOR (the draft-07 subset has no oneOf; the
-            // SHAPE rule is enforced here): legacy single-hunk XOR batch.
-            const single = search !== undefined || replace !== undefined;
-            if (single && edits !== undefined) {
-                return { content: "edit_file: pass EITHER search+replace OR edits — never both", isError: true, errorKind: "invalid_input" };
-            }
-            if (!single && edits === undefined) {
-                return { content: "edit_file: pass search+replace, or edits (1\u201332 hunks)", isError: true, errorKind: "invalid_input" };
-            }
-            if (single && (search === undefined || replace === undefined)) {
-                return { content: "edit_file: the single-hunk form needs BOTH search and replace", isError: true, errorKind: "invalid_input" };
-            }
-            if (edits !== undefined && (edits.length === 0 || edits.length > 32)) {
-                return { content: `edit_file: edits must carry 1\u201332 hunks (got ${edits.length})`, isError: true, errorKind: "invalid_input" };
-            }
-            const hunks = edits ?? [{ search: search, replace: replace }];
+            const shape = editHunksOf(input);
+            if (typeof shape === "string")
+                return { content: shape, isError: true, errorKind: "invalid_input" };
+            const { hunks, single } = shape;
             let full;
             try {
                 full = resolveWithinRoot(opts.workspaceRoot, path);
@@ -1191,16 +1218,18 @@ export function editFileTool(opts) {
                     // ACI-3: the refusal carries the file as it is where each hunk
                     // should land, and its current revision last — the retry needs
                     // no read. The headline is unchanged (bench parsers read it).
-                    return precondition(`edit_file: ${path} changed since ${expectedRevision} — the file as it is now is below; re-apply the change against it, citing the [rev:…] on the last line\n${staleReport(text, hunks, edits === undefined)}\n[${current}]`);
+                    return precondition(`edit_file: ${path} changed since ${expectedRevision} — the file as it is now is below; re-apply the change against it, citing the [rev:…] on the last line\n${staleReport(text, hunks, single)}\n[${current}]`);
                 }
                 // ACI-3 (superseding WR-1E2's one-snapshot rule): the hunks apply
                 // IN ORDER, each against the result of the ones before it — the
-                // way a person writes a second change after the first, and the
-                // reference implementation's multi-edit. 57 refusals on the
+                // way a person writes a second change after the first. (The
+                // reference implementation does NOT do this: it matches every edit
+                // against the original and refuses overlaps.) 57 refusals on the
                 // owner's disk were "two hunks overlap": a second hunk written
-                // against the first one's output. Still all or nothing: nothing is
-                // written unless every hunk resolves, and each must match exactly
-                // once in the text it meets (ACI-2).
+                // against the first one's output. The 2026-10-08 replay found 0 of
+                // 86 failures caused by this rule (ADR-0061). Still all or nothing:
+                // nothing is written unless every hunk resolves, and each must
+                // match exactly once in the text it meets (ACI-2).
                 // Windows P3: a uniformly CRLF file is matched on its LF form and
                 // written back CRLF — the model's search text uses LF, and an edit
                 // never changes the file's endings. A file mixing the two keeps
@@ -1211,7 +1240,7 @@ export function editFileTool(opts) {
                 for (let i = 0; i < hunks.length; i += 1) {
                     const h = { search: lf(hunks[i].search), replace: lf(hunks[i].replace) };
                     const { count, offsets } = occurrencesOf(edited, h.search);
-                    const which = hunks.length === 1 && edits === undefined ? "" : i === 0 ? " (hunk 1)" : ` (hunk ${i + 1}, after ${i === 1 ? "hunk 1" : `hunks 1–${i}`} applied)`;
+                    const which = single ? "" : i === 0 ? " (hunk 1)" : ` (hunk ${i + 1}, after ${i === 1 ? "hunk 1" : `hunks 1–${i}`} applied)`;
                     if (count === 0) {
                         // WR-1A ④: the WORLD lacks the pattern (the input is
                         // fine) and nothing ran — precondition; the note never
@@ -1222,7 +1251,13 @@ export function editFileTool(opts) {
                         const region = regionForSearch(edited, h.search);
                         const seen = i === 0 ? "the file now has" : `the text hunk ${i + 1} met`;
                         const block = region === null ? "" : `\n${seen}, lines ${region.from}–${region.to}:\n${region.body}`;
-                        return precondition(`edit_file: pattern not found in ${path}${which}${detail ? `\n${detail}` : ""}${block}\n[${current}]`);
+                        // ADR-0061: the replay's shape — oldText nowhere, newText exactly
+                        // once. Two readings fit it and the tool cannot tell them apart, so
+                        // it names both and applies nothing (ACI-2: never a guess).
+                        const swap = h.replace.length > 0 && occurrencesOf(edited, h.replace).count === 1
+                            ? "\n  newText is already in the file once and oldText is not: either this change is already applied, or oldText and newText are swapped"
+                            : "";
+                        return precondition(`edit_file: pattern not found in ${path}${which}${detail ? `\n${detail}` : ""}${swap}${block}\n[${current}]`);
                     }
                     // ACI-2: more than one resolution is a QUESTION, not an edit.
                     // Taking the first one wrote the wrong place and reported
@@ -1348,7 +1383,10 @@ export function shellTool(opts) {
                         description: "Run independently as a task. Use for services/watchers or work whose exit result is not needed next. If you need the result, keep it foreground and raise foregroundMs. You are notified when it ends; do not sleep/poll.",
                     },
                     readyWhen: { type: "string", description: "For a continuing service, wait up to foregroundMs for this literal output before returning; the task keeps running afterward." },
-                    timeoutMs: { type: "number", description: "Deprecated: use foregroundMs" },
+                    // Plan B: timeoutMs (deprecated here since ADR-0058) leaves the
+                    // model-facing schema; the executor still reads it from a caller
+                    // that skips validation. The schema WITHOUT tasks keeps it — there
+                    // it is the shell's only timeout.
                 },
                 required: ["command"],
                 additionalProperties: false,
@@ -1362,12 +1400,20 @@ export function shellTool(opts) {
                 required: ["command"],
                 additionalProperties: false,
             },
+        // PR-1d row 3: this exact snippet is part of a MEASURED combination (weather 1/5 -> 5/5); Plan B leaves it as pinned
         promptSnippet: "shell — any command the task needs (builds, tests, git, curl, system queries)",
         promptGuidelines: ["commands run in the workspace root; on failure read the error and adjust — never repeat blindly"],
         execute: async ({ command, timeoutMs, foregroundMs, background, readyWhen }, ctx) => {
             // the session's tasks, when wired and this call has a session
             const tasks = opts.tasks?.(ctx.sessionId);
-            const timeout = foregroundMs ?? timeoutMs ?? (tasks !== undefined ? DEFAULT_FOREGROUND_MS : DEFAULT_SHELL_TIMEOUT_MS);
+            // ADR-0058 Amendment 10: with tasks wired a wait shorter than the
+            // floor only moves the command to the background sooner, so the
+            // model may lengthen the wait, never shorten it. Without tasks the
+            // wait is a kill timeout and is kept as asked.
+            const asked = [foregroundMs, timeoutMs].find((v) => typeof v === "number" && Number.isFinite(v));
+            const timeout = tasks !== undefined
+                ? Math.max(asked ?? DEFAULT_FOREGROUND_MS, opts.limits?.minForegroundMs ?? DEFAULT_FOREGROUND_MS)
+                : (asked ?? DEFAULT_SHELL_TIMEOUT_MS);
             // E group: a PRE-aborted signal never spawns the command.
             if (ctx.signal.aborted) {
                 return { content: "shell aborted before start", isError: true, errorKind: "fatal" };
@@ -1680,7 +1726,7 @@ export function taskStopTool(opts) {
             required: ["id"],
             additionalProperties: false,
         },
-        promptSnippet: "task_stop — stop a background task by id",
+        promptSnippet: "task_stop — stop a background task",
         execute: async ({ id }, ctx) => {
             const tasks = opts.tasks?.(ctx.sessionId);
             const info = tasks?.get(id);

package/dist/search-miss.js

@@ -83,13 +83,13 @@ export function describeSearchMiss(text, search) {
     if (endOfMatch >= text.length) {
         return [
             head,
-            `  the file ENDS there — your search continues for ${rest.length} more characters: "${fragment(rest)}"`,
+            `  the file ENDS there — your oldText 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)}"`,
+        `  your oldText wanted: "${fragment(rest)}"`,
     ].join("\n");
 }
 export function regionForSearch(text, search, context = 6, maxChars = 1500) {

package/dist/search-worker.js

@@ -17,7 +17,7 @@
  */
 import { open, readdir } from "node:fs/promises";
 import { basename, join, relative, sep } from "node:path";
-import { corpusSkips, layersEntering, readLayer, walkCorpus } from "./corpus.js";
+import { byName, bySegments, corpusSkips, layersEntering, readLayer, walkCorpus } from "./corpus.js";
 import { isMainThread, parentPort } from "node:worker_threads";
 import { diskPath, isProtectedDiskPath } from "./protected.js";
 /** A scanned file is protected by inode (the store itself, under any name
@@ -74,7 +74,7 @@ export function runGlob(req) {
 }
 export async function runSearch(req) {
     const regex = new RegExp(req.pattern, req.flags);
-    const matches = [];
+    const found = [];
     let totalMatches = 0;
     let filesSeen = 0;
     let skippedFiles = 0;
@@ -136,8 +136,8 @@ export async function runSearch(req) {
                     // 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(`${relative(req.workspaceRoot, full) || basename(full)}:${i + 1}: ${excerptAround(line, regex)}`);
+                    if (found.length < req.maxMatches)
+                        found.push({ path: relative(req.workspaceRoot, full) || basename(full), line: i + 1, text: excerptAround(line, regex) });
                 }
             }
         }
@@ -149,50 +149,67 @@ export async function runSearch(req) {
     // 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;
-        try {
-            entries = await readdir(dir, { withFileTypes: true });
-        }
-        catch (err) {
-            const code = err.code;
-            if (code === "EACCES" || code === "EPERM") {
-                unreadableDirs += 1;
-                return;
-            }
-            throw err;
-        }
-        const here = depth === 0 ? layers : layersEntering(dir, layers);
-        for (const entry of entries) {
+    // 0.48.0 (finding 0472-F2) — the same order as `walkCorpus`: breadth-
+    // first, each directory's entries by name and its files before any
+    // subdirectory, so the budget cuts the deepest part of the tree and
+    // never a file nearer the root. Depth-first, a deep sibling directory
+    // spent the budget before a shallow file was read.
+    const walk = async (start, startLayers) => {
+        const queue = [{ dir: start, depth: 0, layers: startLayers }];
+        for (let next = 0; next < queue.length; next += 1) {
             if (outOfBudget())
                 return;
-            const full = join(dir, entry.name);
-            const isDir = entry.isDirectory();
-            if (corpusSkips(declared, here, full, entry.name, isDir))
-                continue;
-            if (isDir) {
-                if (isExcluded(full)) {
-                    excludedDirs += 1;
+            const { dir, depth, layers } = queue[next];
+            let entries;
+            try {
+                entries = await readdir(dir, { withFileTypes: true });
+            }
+            catch (err) {
+                const code = err.code;
+                if (code === "EACCES" || code === "EPERM") {
+                    unreadableDirs += 1;
                     continue;
                 }
-                await walk(full, depth + 1, here);
+                throw err;
+            }
+            entries.sort(byName);
+            const here = depth === 0 ? layers : layersEntering(dir, layers);
+            for (const entry of entries) {
+                if (outOfBudget())
+                    return;
+                const full = join(dir, entry.name);
+                const isDir = entry.isDirectory();
+                if (corpusSkips(declared, here, full, entry.name, isDir))
+                    continue;
+                if (isDir) {
+                    if (isExcluded(full)) {
+                        excludedDirs += 1;
+                        continue;
+                    }
+                    if (depth + 1 <= 8)
+                        queue.push({ dir: full, depth: depth + 1, layers: here });
+                }
+                else if (entry.isFile())
+                    await scanFile(full);
             }
-            else if (entry.isFile())
-                await scanFile(full);
         }
     };
     try {
         if (req.single !== null)
             await scanFile(req.single);
         else
-            await walk(req.root, 0, rootLayer === null ? [] : [rootLayer]);
+            await walk(req.root, rootLayer === null ? [] : [rootLayer]);
     }
     catch (err) {
-        return { token: req.token, matches, totalMatches, filesSeen, skippedFiles, multiLink, unreadableDirs, excludedDirs, stopped, stoppedAt, error: err.message };
+        return { token: req.token, matches: listed(found), totalMatches, filesSeen, skippedFiles, multiLink, unreadableDirs, excludedDirs, stopped, stoppedAt, error: err.message };
     }
-    return { token: req.token, matches, totalMatches, filesSeen, skippedFiles, multiLink, unreadableDirs, excludedDirs, stopped, stoppedAt };
+    return { token: req.token, matches: listed(found), totalMatches, filesSeen, skippedFiles, multiLink, unreadableDirs, excludedDirs, stopped, stoppedAt };
+}
+/** The matches as the tool prints them: by path segments, then by line —
+ *  a listing that does not depend on the order the walk read them in. */
+function listed(found) {
+    const key = (path) => path.split(sep).join("/");
+    return [...found].sort((a, b) => bySegments(key(a.path), key(b.path)) || a.line - b.line).map((m) => `${m.path}:${m.line}: ${m.text}`);
 }
 if (!isMainThread && parentPort !== null) {
     parentPort.once("message", (req) => {

package/dist/task-runner.js

@@ -69,17 +69,40 @@ function plannedOf(journal) {
     throw new Error(`no planned record in ${journal}`);
 }
 function main(dir) {
+    // The runner's FIRST act: TERM is handled from here on, by one handler
+    // that is never removed. The task reads running the moment
+    // command_started is written, so a stop may arrive before the command and
+    // its stop exist; without a handler, TERM's default disposition killed
+    // the runner with no record, and the task was lost. The handler is
+    // dispatched from the event loop, after this synchronous main returns,
+    // by which time `stopNow` is set. `heldTerm` is a guard, only reachable
+    // if main() ever awaits before the stop exists: such a TERM is held and
+    // performed as soon as the stop exists (below). The handler is never
+    // swapped: dropping the last listener between two moments would drop a
+    // pending signal with it.
+    let stopNow = null;
+    let heldTerm = false;
+    process.on("SIGTERM", () => {
+        if (stopNow !== null)
+            stopNow();
+        else
+            heldTerm = true;
+    });
     const journal = join(dir, "journal.jsonl");
     const planned = plannedOf(journal);
     // test-only crash points: the process dies right after a record, before
     // the step that record gates
     const dieAfter = process.env.KISO_TASK_RUNNER_DIE_AFTER;
+    // test-only: hold the runner right after a record, so a stop can land in
+    // the window the record opens
+    const pauseAfter = process.env.KISO_TASK_RUNNER_PAUSE_AFTER;
     // test-only: report a stop as unconfirmed (a survivor the platform could
     // not kill cannot be made on purpose)
     const forceUnconfirmed = process.env.KISO_TASK_RUNNER_STOP_UNCONFIRMED === "1";
     const cap = Number(process.env.KISO_TASK_OUTPUT_CAP ?? OUTPUT_CAP_DEFAULT);
     const env = { ...process.env };
     delete env.KISO_TASK_RUNNER_DIE_AFTER;
+    delete env.KISO_TASK_RUNNER_PAUSE_AFTER;
     delete env.KISO_TASK_RUNNER_STOP_UNCONFIRMED;
     delete env.KISO_TASK_OUTPUT_CAP;
     // "" when the start time cannot be read: the identity is then the pid
@@ -91,6 +114,8 @@ function main(dir) {
     append(journal, { type: "command_started", ts: Date.now() });
     if (dieAfter === "command_started")
         process.exit(99);
+    if (pauseAfter === "command_started")
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 600);
     const out = new RotatingOutput(join(dir, "output.log"), cap);
     let finished = false;
     /** The last record; the output closes first, and nothing is written after. */
@@ -163,7 +188,9 @@ function main(dir) {
             finish({ type: "terminal", ts: Date.now(), exitCode: e?.code ?? null, signal: e?.signal ?? null });
         });
     };
-    process.on("SIGTERM", stop);
+    stopNow = stop;
+    if (heldTerm)
+        stop();
     // the journal is the stop channel: re-read only when it grew
     let journalSize = -1;
     const watch = setInterval(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vincemakes/kiso-tools-node",
-	"version": "0.47.3",
+	"version": "0.49.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,7 @@
 		"test": "vitest run"
 	},
 	"dependencies": {
-		"@vincemakes/kiso-core": "0.47.3",
+		"@vincemakes/kiso-core": "0.49.0",
 		"ignore": "^7.0.9"
 	},
 	"devDependencies": {