@vincemakes/kiso-tools-node 0.47.3 → 0.48.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<{

package/dist/index.js

@@ -1367,7 +1367,14 @@ export function shellTool(opts) {
         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" };

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.48.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.48.0",
 		"ignore": "^7.0.9"
 	},
 	"devDependencies": {