@vincemakes/kiso-tools-node 0.45.3 → 0.46.0

package/dist/index.js

@@ -17,11 +17,12 @@
  * states what was dropped (deterministic per file state), so the model
  * always has a path to the full content.
  */
-import { execFile, execFileSync, spawn } from "node:child_process";
+import { execFile } from "node:child_process";
 import { promisify } from "node:util";
-import { appendFileSync, chmodSync, existsSync, linkSync, mkdirSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { appendFileSync, chmodSync, closeSync, existsSync, fstatSync, linkSync, mkdirSync, openSync, readdirSync, readSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { Worker } from "node:worker_threads";
 import { fileURLToPath } from "node:url";
+import { killTree, NO_BASH, processStartTime, RotatingOutput, startCommand } from "./process.js";
 import { createHash } from "node:crypto";
 import { tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
@@ -78,6 +79,16 @@ const ACI2_LINES_SHOWN = 5;
 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;
+/** ADR-0058 §3: with tasks, how long the shell waits before a command
+ *  continues as a task (the model's own value wins). */
+const DEFAULT_FOREGROUND_MS = 60_000;
+/** A promoted task's output file rotates here, as a runner's does. */
+const TASK_OUTPUT_CAP = 64 * 1024 * 1024;
+/** A task's stop: SIGTERM, this long, then the confirmed sweep. */
+const TASK_STOP_GRACE_MS = 5_000;
+/** ADR-0058 Amendment 7: how long task_stop waits for the end it reports —
+ *  the runner's journal poll, TERM, the grace, KILL and the sweep. */
+const TASK_STOP_WAIT_MS = 8_000;
 // the token round: the scoped-read defaults — read_file shows the head 200 lines
 // of a large file (with an actionable continuation note, never a silent
 // drop), search_text caps at 50 excerpts, list_dir at 200 entries. The
@@ -167,6 +178,25 @@ export class PathEscapeError extends Error {
         this.name = "PathEscapeError";
     }
 }
+/** ADR-0058 §4: read_file's resolution — the workspace, or an absolute path
+ *  inside one of the host-granted read-only roots. The containment check is
+ *  the workspace's own, applied to that root. */
+function resolveReadable(opts, input, sessionId) {
+    if (isAbsolute(input)) {
+        // 3b: the session's own task directory, when the host wires tasks
+        const taskRoot = opts.tasks?.(sessionId)?.root;
+        for (const root of [...(opts.extraReadRoots ?? []), ...(taskRoot !== undefined ? [taskRoot] : [])]) {
+            if (!existsSync(root))
+                continue;
+            for (const base of [root, realpathSync(root)]) {
+                const rel = relative(base, input);
+                if (rel !== "" && !rel.startsWith("..") && !isAbsolute(rel))
+                    return { full: resolveWithinRoot(root, rel), root };
+            }
+        }
+    }
+    return { full: resolveWithinRoot(opts.workspaceRoot, input), root: opts.workspaceRoot };
+}
 export function resolveWithinRoot(root, input) {
     if (isAbsolute(input)) {
         throw new PathEscapeError(`absolute paths are not allowed — use workspace-relative paths: ${input}`);
@@ -264,6 +294,10 @@ async function inodeReadPolicy(root, full) {
         return `not a regular file — refusing to read (${full})`;
     if (st.nlink <= 1)
         return null;
+    // Windows: no find can list a file's links (find there is the system's
+    // text search) — refused without a scan, and the refusal says why
+    if (process.platform === "win32")
+        return `file has ${st.nlink} hard links, and on Windows kiso cannot check where they all are — refusing to read (${full})`;
     const key = `${st.dev}:${st.ino}`;
     const cached = inodeVerdict.get(key);
     if (cached !== undefined)
@@ -350,16 +384,16 @@ export function readFileTool(opts) {
         effects: { precommitSafe: true, concurrency: "shared" },
         promptSnippet: "read_file — whole files or offset/limit ranges, workspace-relative paths",
         promptGuidelines: ["read only the range you need — offset/limit beat whole-file reads"],
-        execute: async ({ path, offset, limit }) => {
+        execute: async ({ path, offset, limit }, ctx) => {
             const maxReadBytes = opts.limits?.readMaxFileBytes ?? READ_MAX_FILE_BYTES;
             try {
-                const full = resolveWithinRoot(opts.workspaceRoot, path);
+                const { full, root } = resolveReadable(opts, path, ctx?.sessionId);
                 // the credential store is never served (protected.ts) — checked
                 // by the disk's own resolution and by inode, before any read
                 const guard = protectedIdentity(opts.protectedFiles);
                 if (isProtectedPath(full, guard))
                     return precondition(protectedRefusalText("read_file", path));
-                const denied = await inodeReadPolicy(opts.workspaceRoot, full);
+                const denied = await inodeReadPolicy(root, full);
                 if (denied !== null)
                     return escapeResult(denied);
                 // DC-54 — the ceiling. `read_file` had the same unbounded
@@ -1133,9 +1167,15 @@ export function editFileTool(opts) {
                 // 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).
-                let edited = text;
+                // 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
+                // exact matching: normalizing it would rewrite untouched lines.
+                const crlf = text.includes("\r\n") && !/(^|[^\r])\n/.test(text);
+                const lf = (t) => (crlf ? t.replace(/\r\n/g, "\n") : t);
+                let edited = lf(text);
                 for (let i = 0; i < hunks.length; i += 1) {
-                    const h = hunks[i];
+                    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)`;
                     if (count === 0) {
@@ -1165,7 +1205,10 @@ export function editFileTool(opts) {
                 // E group: safe replacement — never rewrite a shared external inode via a hard link.
                 // round 8: the edited file keeps its mode.
                 preservedMode = statSync(full).mode & 0o7777;
-                writeFileSync(tmp, edited, "utf8");
+                // ONE buffer is written and hashed: the revision returned is the
+                // file's on disk, CRLF or not (the review's finding)
+                const bytesOut = Buffer.from(crlf ? edited.replace(/\n/g, "\r\n") : edited, "utf8");
+                writeFileSync(tmp, bytesOut);
                 chmodSync(tmp, preservedMode);
                 // WR-1A ③: revalidate against the citation right before the
                 // replacement commits.
@@ -1180,7 +1223,7 @@ export function editFileTool(opts) {
                     // WR-1A ①: post-effect — fatal, the rename already landed.
                     return postEffectEscape("edit", path);
                 }
-                return { content: `edited ${path}\n[${contentRevision(Buffer.from(edited, "utf8"))}]`, isError: false };
+                return { content: `edited ${path}\n[${contentRevision(bytesOut)}]`, isError: false };
             }
             catch (err) {
                 // round 8: a failed edit never leaves a temp file behind.
@@ -1205,51 +1248,154 @@ export { PROTECTED_REFUSAL, diskPath, isProtectedPath, protectedIdentity, protec
  *  read-only shell allow holds a shell read to the same definition rather
  *  than a copy of it. */
 export { isCredentialName, isCredentialPath } from "./corpus.js";
+// ADR-0058: the process task backend (the runner ships beside it)
+export { processTaskBackend } from "./process-backend.js";
+/** How a task ended, in a few words: its signal, its exit code, or why it
+ *  never ran. */
+function howEnded(task) {
+    const s = task.state;
+    if (s.kind === "unknown")
+        return "its runner is gone and its end is unknown";
+    if (s.error !== undefined)
+        return `it never started: ${s.error}`;
+    if (s.signal !== undefined && s.signal !== null)
+        return s.signal;
+    if (s.exitCode !== undefined && s.exitCode !== null)
+        return `exit code ${s.exitCode}`;
+    return "no exit code";
+}
+/** The last `bytes` of a task's output file ("" when there is none). */
+function outputTail(path, bytes = 2_048) {
+    try {
+        const fd = openSync(path, "r");
+        try {
+            const size = fstatSync(fd).size;
+            const len = Math.min(size, bytes);
+            const buf = Buffer.alloc(len);
+            readSync(fd, buf, 0, len, size - len);
+            return `${size > len ? "…" : ""}${buf.toString("utf8")}`.trim();
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch {
+        return "";
+    }
+}
+/** This process as a promoted task's owner — read once. */
+let selfIdentity;
+function ownerIdentity() {
+    if (selfIdentity === undefined) {
+        const id = processStartTime(process.pid);
+        selfIdentity = { pid: process.pid, startedAt: id.kind === "running" ? id.startedAt : "" };
+    }
+    return selfIdentity;
+}
 export function shellTool(opts) {
+    // ADR-0058 (3b): the task-aware contract exists only where tasks are
+    // wired; a host without them keeps today's schema byte for byte.
+    const withTasks = opts.tasks !== undefined;
+    // Windows P1: commands run through Git Bash there, /bin/sh elsewhere
+    const sh = process.platform === "win32" ? "bash" : "/bin/sh";
     return defineTool({
         name: "shell",
-        description: "Run a shell command through /bin/sh with the workspace root as the working directory: builds, tests, git, package managers, curl for HTTP APIs, system queries. Side effects are real; the human may be asked to approve the run. Fails loudly on timeout or non-zero exit.",
-        parameters: {
-            type: "object",
-            properties: {
-                command: { type: "string", description: "The command to run" },
-                timeoutMs: { type: "number", description: "Timeout in ms (default 30000)" },
+        description: withTasks
+            ? `Run a shell command through ${sh} with the workspace root as the working directory: builds, tests, git, package managers, curl for HTTP APIs, system queries. Side effects are real; the human may be asked to approve the run. A command still running after foregroundMs is never killed: it continues as a background task, the result gives its id and output path, and you are notified when it ends. Fails loudly on a non-zero exit.`
+            : `Run a shell command through ${sh} with the workspace root as the working directory: builds, tests, git, package managers, curl for HTTP APIs, system queries. Side effects are real; the human may be asked to approve the run. Fails loudly on timeout or non-zero exit.`,
+        parameters: withTasks
+            ? {
+                type: "object",
+                properties: {
+                    command: { type: "string", description: "The command to run" },
+                    foregroundMs: { type: "number", description: "How long to wait for the result, in ms (default 60000); if you need the result to go on, allow enough time" },
+                    background: {
+                        type: "boolean",
+                        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" },
+                },
+                required: ["command"],
+                additionalProperties: false,
+            }
+            : {
+                type: "object",
+                properties: {
+                    command: { type: "string", description: "The command to run" },
+                    timeoutMs: { type: "number", description: "Timeout in ms (default 30000)" },
+                },
+                required: ["command"],
+                additionalProperties: false,
             },
-            required: ["command"],
-            additionalProperties: false,
-        },
         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 }, ctx) => {
-            const timeout = timeoutMs ?? DEFAULT_SHELL_TIMEOUT_MS;
+        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);
             // E group: a PRE-aborted signal never spawns the command.
             if (ctx.signal.aborted) {
                 return { content: "shell aborted before start", isError: true, errorKind: "fatal" };
             }
+            // bootstrap #3 (finding #7): the shell child NEVER inherits kiso's own
+            // provider credentials by default — only the explicit
+            // shellEnv: "inherit" opt-in keeps them. A record (ADR-0031
+            // Amendment 1) rides on the STRIPPED base and wins per key.
+            const env = opts.shellEnv === "inherit" ? process.env : { ...strippedShellEnv(process.env, opts.secretEnvNames), ...(opts.shellEnv ?? {}) };
+            if (background === true) {
+                if (tasks === undefined)
+                    return { content: "background tasks are not available here — run the command in the foreground", isError: true, errorKind: "precondition" };
+                const task = await tasks.start({
+                    command,
+                    cwd: opts.workspaceRoot,
+                    env,
+                    ...(ctx.executionId !== undefined ? { executionId: ctx.executionId } : {}),
+                    ...(readyWhen !== undefined ? { readyWhen } : {}),
+                    profile: readyWhen !== undefined ? "service" : "oneshot",
+                });
+                const settle = tasks.awaitSettled?.bind(tasks);
+                if (readyWhen === undefined || settle === undefined)
+                    return { content: `started background task ${task.id}. ${taskNote(task.outputPath)}`, isError: false };
+                return waitForReady(tasks, settle, task, readyWhen, timeout, ctx);
+            }
             return new Promise((resolvePromise) => {
                 // detached: the command gets its OWN process group, so a
                 // timeout/abort can kill the WHOLE TREE (children included),
                 // not just the outer shell (Area 4). cwd is the workspace.
-                // bootstrap #3 (finding #7): the shell child NEVER inherits kiso's own
-                // provider credentials by default — only the explicit
-                // shellEnv: "inherit" opt-in keeps them. A record (ADR-0031
-                // Amendment 1) rides on the STRIPPED base and wins per key.
-                const child = spawn(command, {
-                    shell: true,
-                    detached: true,
-                    cwd: opts.workspaceRoot,
-                    stdio: ["ignore", "pipe", "pipe"],
-                    env: opts.shellEnv === "inherit"
-                        ? process.env
-                        : { ...strippedShellEnv(process.env, opts.secretEnvNames), ...(opts.shellEnv ?? {}) },
-                });
+                let child;
+                try {
+                    child = startCommand(command, { cwd: opts.workspaceRoot, env });
+                }
+                catch (err) {
+                    // win32 with no usable bash: an answer the model can act on
+                    if (err.code !== NO_BASH)
+                        throw err;
+                    resolvePromise({ content: `shell failed: ${err.message}`, isError: true, errorKind: "fatal" });
+                    return;
+                }
                 let stdout = "";
                 let stderr = "";
                 let stdoutDropped = 0;
                 let stderrDropped = 0;
-                let exited = false;
                 let settled = false;
                 let killing = false;
+                // ADR-0058 (3b): once promoted, the child's output goes to its task
+                let promoted = null;
+                let stopping = false;
+                let readySeen = false;
+                /** 3e: the unregister of this command's detach — while it runs in the foreground */
+                let undetachable = () => { };
+                let recent = ""; // the tail readyWhen is matched against
+                const matchReady = (text) => {
+                    if (readyWhen === undefined || readySeen)
+                        return false;
+                    recent = (recent + text).slice(-(readyWhen.length + 65_536));
+                    if (!recent.includes(readyWhen))
+                        return false;
+                    readySeen = true;
+                    return true;
+                };
                 // TUI2-R1 (C): the progress sidecar — truncated at the start
                 // (a kill -9 leftover is cleared, never appended to), appended
                 // per chunk, removed at settle. Every operation best-effort:
@@ -1284,6 +1430,7 @@ export function shellTool(opts) {
                     if (settled)
                         return;
                     settled = true;
+                    undetachable();
                     dropProgress();
                     clearTimeout(timer);
                     // E group: the abort listener is removed once settled — it
@@ -1291,134 +1438,52 @@ export function shellTool(opts) {
                     ctx.signal.removeEventListener("abort", onAbort);
                     resolvePromise(result);
                 };
-                /**
-                 * Kill the whole tree and CONFIRM it exited (rounds 8/11):
-                 *
-                 * 1. FREEZE the root (SIGSTOP) FIRST — a stopped shell cannot
-                 *    fork new descendants while we enumerate;
-                 * 2. repeatedly discover AND freeze descendants (pid-table
-                 *    sweep — the only way to see a setsid()-escaped process)
-                 *    until the set is STABLE (two identical scans), so the
-                 *    enumeration cannot miss a mid-sweep fork;
-                 * 3. SIGKILL the process group and every tracked pid;
-                 * 4. poll every tracked pid to death. If ANY tracked pid is
-                 *    still alive at the deadline, the verdict is NOT
-                 *    "aborted"/"timed out" — it is an explicit UNCERTAIN
-                 *    error naming the survivors: the side effect may have
-                 *    outlived the tool, and the caller must not assume it
-                 *    was killed.
-                 */
-                const killTree = () => new Promise((resolveKill) => {
-                    const tracked = new Set();
-                    // round 11 (adversarial): the ROOT itself is tracked too — the
-                    // verdict must not read "aborted" while the root
-                    // survives. DOCUMENTED LIMITS: (1) a process that
-                    // forks between SIGSTOP delivery and the next scan,
-                    // setsids, and is then reparented when its parent is
-                    // killed can escape the enumeration entirely — it is
-                    // untracked and unknowable from the pid table; the
-                    // platform cannot confirm it. (2) if THIS process is
-                    // killed between the first SIGSTOP and the SIGKILL
-                    // sweep, the stopped descendants stay permanently
-                    // stopped (nobody SIGCONTs orphans) — the inherent
-                    // cost of freeze-first. Both limits are recorded here
-                    // so no claim of "the whole tree is gone" is ever
-                    // stronger than what the platform can prove.
-                    if (child.pid !== undefined && child.pid > 0) {
-                        tracked.add(child.pid);
-                        try {
-                            process.kill(child.pid, "SIGSTOP"); // freeze the root
-                        }
-                        catch {
-                            // already gone
-                        }
-                    }
-                    // Stable discovery: freeze as we go; stop when two
-                    // consecutive scans are identical.
-                    let previous = new Set();
-                    for (let i = 0; i < 10; i++) {
-                        const current = new Set(descendantsOf(child.pid ?? 0));
-                        for (const pid of current) {
-                            tracked.add(pid);
-                            try {
-                                process.kill(pid, "SIGSTOP"); // freeze each descendant
-                            }
-                            catch {
-                                // already gone
-                            }
-                        }
-                        if (current.size === previous.size && [...current].every((pid) => previous.has(pid))) {
-                            break;
-                        }
-                        previous = current;
-                    }
-                    // The process group (E group: never kill an undefined/0
-                    // pid), which also takes the frozen root down.
-                    if (child.pid !== undefined && child.pid > 0) {
-                        try {
-                            process.kill(-child.pid, "SIGKILL");
-                        }
-                        catch {
-                            try {
-                                child.kill("SIGKILL");
-                            }
-                            catch {
-                                // already gone
-                            }
-                        }
-                    }
-                    for (const pid of tracked) {
-                        try {
-                            process.kill(pid, "SIGKILL");
-                        }
-                        catch {
-                            // already gone
-                        }
-                    }
-                    const confirm = () => {
-                        void waitAllDead([...tracked]).then((unconfirmed) => resolveKill({ unconfirmed }));
-                    };
-                    if (exited) {
-                        confirm();
-                        return;
-                    }
-                    const fallback = setTimeout(confirm, 2000);
-                    child.once("close", () => {
-                        clearTimeout(fallback);
-                        confirm();
-                    });
-                });
                 child.stdout?.on("data", (d) => {
+                    if (promoted !== null)
+                        return feedTask(d);
                     const text = d.toString();
                     progress(text);
                     const r = capAccumulate(stdout, text);
                     stdout = r.text;
                     stdoutDropped += r.dropped;
+                    if (tasks !== undefined && matchReady(text))
+                        promote("ready");
                 });
                 child.stderr?.on("data", (d) => {
+                    if (promoted !== null)
+                        return feedTask(d);
                     const text = d.toString();
                     progress(text);
                     const r = capAccumulate(stderr, text);
                     stderr = r.text;
                     stderrDropped += r.dropped;
+                    if (tasks !== undefined && matchReady(text))
+                        promote("ready");
                 });
                 child.on("error", (err) => {
                     settle({ content: `shell failed: ${err.message}`, isError: true, errorKind: "fatal" });
                 });
-                child.on("close", (code) => {
-                    exited = true;
+                // R-C item 2: the overflow note names WHAT was dropped and
+                // the recovery path — a silent tail-cut would be the exact
+                // destructive class this round kills (W10 made model-facing).
+                const overflowNote = (dropped, stream) => dropped === 0
+                    ? ""
+                    : `\n… [${stream} capped at ${OUTPUT_CAP} chars — ${dropped} more chars dropped; capture to a file and read it with read_file, or narrow the command]`;
+                const combinedOutput = () => (stdout + overflowNote(stdoutDropped, "stdout") + (stderr ? `\n[stderr] ${stderr}` : "") + overflowNote(stderrDropped, "stderr")).trim();
+                let exitInfo = null;
+                child.on("close", (code, signal) => {
+                    if (promoted !== null) {
+                        // a stop's verdict owns the task's last record
+                        exitInfo = { code, signal };
+                        if (!stopping) {
+                            promoted.out.close();
+                            promoted.task.ended(code, signal);
+                        }
+                        return;
+                    }
                     if (killing)
                         return; // the timeout/abort verdict owns the result
-                    // R-C item 2: the overflow note names WHAT was dropped and
-                    // the recovery path — a silent tail-cut would be the exact
-                    // destructive class this round kills (W10 made model-facing).
-                    const overflowNote = (dropped, stream) => dropped === 0
-                        ? ""
-                        : `\n… [${stream} capped at ${OUTPUT_CAP} chars — ${dropped} more chars dropped; capture to a file and read it with read_file, or narrow the command]`;
-                    const combined = (stdout +
-                        overflowNote(stdoutDropped, "stdout") +
-                        (stderr ? `\n[stderr] ${stderr}` : "") +
-                        overflowNote(stderrDropped, "stderr")).trim();
+                    const combined = combinedOutput();
                     settle(code === 0
                         ? { content: combined || "(no output)", isError: false }
                         : { content: `exit ${code}: ${combined}`, isError: true, errorKind: "fatal" });
@@ -1430,16 +1495,86 @@ export function shellTool(opts) {
                     : "";
                 const onAbort = () => {
                     killing = true;
-                    void killTree().then(({ unconfirmed }) => settle({
+                    void killTree(child).then(({ unconfirmed }) => settle({
                         content: `shell aborted${uncertainVerdict(unconfirmed) ? ` — ${uncertainVerdict(unconfirmed)}` : ""}`,
                         isError: true,
                         errorKind: "fatal",
                     }));
                 };
                 ctx.signal.addEventListener("abort", onAbort);
+                /** ADR-0058 §3: the wait is over — the command continues as a
+                 *  task this process owns; nothing is killed. */
+                const promote = (reason) => {
+                    if (settled || killing || promoted !== null || tasks === undefined)
+                        return;
+                    const task = tasks.adopt({
+                        command,
+                        cwd: opts.workspaceRoot,
+                        ...(ctx.executionId !== undefined ? { executionId: ctx.executionId } : {}),
+                        ...(readyWhen !== undefined ? { readyWhen } : {}),
+                        runner: ownerIdentity(),
+                        ready: reason === "ready",
+                        stop: () => stopPromoted(),
+                    });
+                    const out = new RotatingOutput(task.outputPath, TASK_OUTPUT_CAP);
+                    const sofar = combinedOutput();
+                    if (sofar !== "")
+                        out.write(Buffer.from(`${sofar}\n`));
+                    promoted = { task, out };
+                    const tail = sofar.length > 2048 ? `…${sofar.slice(-2048)}` : sofar;
+                    settle({
+                        content: (reason === "ready"
+                            ? `ready — the output contains "${readyWhen}"; `
+                            : reason === "person"
+                                ? "moved to the background by the person; "
+                                : reason === "steer"
+                                    ? "moved to the background so the person's message could land; "
+                                    : `still running after ${timeout} ms; `) +
+                            `continued as background task ${task.id} (not killed — it keeps running). ${taskNote(task.outputPath)}` +
+                            (tail !== "" ? `\nOutput so far:\n${tail}` : ""),
+                        isError: false,
+                    });
+                };
+                const feedTask = (d) => {
+                    if (promoted === null)
+                        return;
+                    promoted.out.write(d);
+                    if (matchReady(d.toString()))
+                        promoted.task.ready(readyWhen);
+                };
+                /** task_stop, or a clean exit: TERM, a grace, the confirmed
+                 *  sweep; survivors mean no terminal — the task stays unknown. */
+                const stopPromoted = () => {
+                    if (stopping)
+                        return;
+                    stopping = true;
+                    void killTree(child, { graceMs: TASK_STOP_GRACE_MS }).then(async ({ unconfirmed }) => {
+                        if (promoted === null)
+                            return;
+                        if (unconfirmed.length > 0) {
+                            promoted.task.unconfirmed(unconfirmed);
+                            return;
+                        }
+                        const waitClose = Date.now() + 1_000;
+                        while (exitInfo === null && Date.now() < waitClose)
+                            await new Promise((r) => setTimeout(r, 25));
+                        promoted.out.close();
+                        const e = exitInfo;
+                        promoted.task.ended(e?.code ?? null, e?.signal ?? null);
+                    });
+                };
+                // 3e: while it runs in the foreground, the person (ctrl+b) or a
+                // steer may move it to the background — through the manager
+                if (tasks?.registerDetachable !== undefined && ctx.executionId !== undefined) {
+                    undetachable = tasks.registerDetachable(ctx.executionId, { startedAt: Date.now(), detach: (by) => promote(by) });
+                }
                 const timer = setTimeout(() => {
+                    if (tasks !== undefined) {
+                        promote("waited");
+                        return;
+                    }
                     killing = true;
-                    void killTree().then(({ unconfirmed }) => settle({
+                    void killTree(child).then(({ unconfirmed }) => settle({
                         content: `shell timed out after ${timeout}ms${uncertainVerdict(unconfirmed) ? ` — ${uncertainVerdict(unconfirmed)}` : ""}`,
                         isError: true,
                         errorKind: "fatal",
@@ -1450,71 +1585,89 @@ export function shellTool(opts) {
         },
     });
 }
-/**
- * All live pids whose ancestor chain includes `pid`, from the pid table
- * (round 8: `ps -axo pid=,ppid=` — the ONLY way to see a setsid()-escaped
- * process, which is in its own group and invisible to a group kill).
- */
-function descendantsOf(pid) {
-    if (pid <= 0)
-        return [];
-    let table;
+/** ADR-0058 Amendment 7: `background` with `readyWhen` — the task is the
+ *  runner's from the start; this call waits for its ready line (up to the
+ *  foreground wait) and reports what it saw. The ready (or an end before
+ *  it) is claimed for this call, so no notice repeats it. The person
+ *  (ctrl+b), a steer or Esc RELEASES the wait: the work is already a task,
+ *  so nothing is promoted and no second task is made. */
+async function waitForReady(tasks, settle, task, readyWhen, timeout, ctx) {
+    const release = new AbortController();
+    let reason = null;
+    const onEsc = () => {
+        reason ??= "interrupted";
+        release.abort();
+    };
+    if (ctx.signal.aborted)
+        onEsc();
+    else
+        ctx.signal.addEventListener("abort", onEsc);
+    const undetach = tasks.registerDetachable !== undefined && ctx.executionId !== undefined
+        ? tasks.registerDetachable(ctx.executionId, {
+            startedAt: Date.now(),
+            detach: (by) => {
+                reason ??= by;
+                release.abort();
+            },
+        })
+        : () => { };
     try {
-        table = execFileSync("ps", ["-axo", "pid=,ppid="], { encoding: "utf8", maxBuffer: 1 << 20 });
-    }
-    catch {
-        return [];
-    }
-    const children = new Map();
-    for (const line of table.split("\n")) {
-        const m = line.trim().match(/^(\d+)\s+(\d+)$/);
-        if (m === null)
-            continue;
-        const child = Number(m[1]);
-        const parent = Number(m[2]);
-        if (!children.has(parent))
-            children.set(parent, []);
-        children.get(parent).push(child);
-    }
-    const out = [];
-    const queue = [pid];
-    while (queue.length > 0) {
-        const current = queue.shift();
-        for (const c of children.get(current) ?? []) {
-            out.push(c);
-            queue.push(c);
+        const w = await settle(task.id, "ready", timeout, { ...(ctx.executionId !== undefined ? { executionId: ctx.executionId } : {}), signal: release.signal });
+        const where = `Output: ${task.outputPath} (read it with read_file); task_stop stops it.`;
+        if (w.settled && w.info.state.kind === "running")
+            return { content: `started background task ${task.id}; ready — the output contains "${readyWhen}". ${taskNote(task.outputPath)}`, isError: false };
+        if (w.settled) {
+            const tail = outputTail(task.outputPath);
+            return { content: `background task ${task.id} ended before it was ready (${howEnded(w.info)})${tail !== "" ? `\n${tail}` : ""}`, isError: true, errorKind: "fatal" };
         }
+        if (reason === null)
+            return { content: `not ready after ${timeout} ms — no "${readyWhen}" in the output yet; it keeps running as background task ${task.id}, and you will be notified when it is ready. ${where}`, isError: false };
+        const why = reason === "person" ? "moved on by the person" : reason === "steer" ? "so the person's message could land" : "interrupted";
+        return { content: `started background task ${task.id}; stopped waiting for "${readyWhen}" (${why}) — not ready yet; you will be notified when it is ready. ${where}`, isError: false };
+    }
+    finally {
+        undetach();
+        ctx.signal.removeEventListener("abort", onEsc);
     }
-    return out;
 }
-/**
- * Poll the pid table until NONE of the tracked pids is alive (bounded).
- * Returns the pids still alive at the deadline — the caller MUST NOT
- * report "aborted"/"timed out" while any tracked pid survives (round 11).
- */
-function waitAllDead(pids) {
-    if (pids.length === 0)
-        return Promise.resolve([]);
-    return new Promise((resolve) => {
-        const deadline = Date.now() + 2000;
-        const poll = () => {
-            const alive = [];
-            for (const pid of pids) {
-                try {
-                    process.kill(pid, 0);
-                    alive.push(pid);
-                }
-                catch (err) {
-                    if (err.code === "EPERM")
-                        alive.push(pid);
-                    // ESRCH — gone
-                }
-            }
-            if (alive.length === 0 || Date.now() > deadline)
-                return resolve(alive);
-            setTimeout(poll, 50);
-        };
-        poll();
+/** Where a task's output is, and what happens next — one wording for the
+ *  shell's results. */
+function taskNote(outputPath) {
+    return `Output: ${outputPath} (read it with read_file). You will be notified when it ends; task_stop stops it.`;
+}
+/** ADR-0058 §4: stop a task this session started — its whole process group. */
+export function taskStopTool(opts) {
+    return defineTool({
+        name: "task_stop",
+        description: "Stop a task, wait briefly for its terminal state, and report how it ended.",
+        parameters: {
+            type: "object",
+            properties: { id: { type: "string", description: "The task id, as the shell reported it (t1, t2, …)" } },
+            required: ["id"],
+            additionalProperties: false,
+        },
+        promptSnippet: "task_stop — stop a background task by id",
+        execute: async ({ id }, ctx) => {
+            const tasks = opts.tasks?.(ctx.sessionId);
+            const info = tasks?.get(id);
+            if (tasks === undefined || info === undefined)
+                return { content: `no task ${id} in this session`, isError: true, errorKind: "precondition" };
+            if (info.state.kind === "ended")
+                return { content: `task ${id} had already ended`, isError: false };
+            if (!tasks.stop(id, "model"))
+                return { content: `task ${id} is not running (${info.state.kind}); nothing to stop`, isError: false };
+            if (tasks.awaitSettled === undefined)
+                return { content: `stopping task ${id}; you will be notified when it has ended`, isError: false };
+            // Amendment 7: wait for the end this result reports — claimed for
+            // THIS call, so no stopped notice follows (Esc: nothing claimed)
+            const w = await tasks.awaitSettled(id, "end", TASK_STOP_WAIT_MS, { ...(ctx.executionId !== undefined ? { executionId: ctx.executionId } : {}), signal: ctx.signal });
+            if (!w.settled)
+                return { content: `stop requested for task ${id}; its end is not confirmed yet — you will be notified when it ends`, isError: false };
+            if (w.info.state.kind === "unknown")
+                return { content: `task ${id} could not be confirmed stopped — some of its processes may still be running`, isError: true, errorKind: "fatal" };
+            const ran = w.info.endedAt !== undefined ? `; it ran ${Math.round((w.info.endedAt - w.info.startedAt) / 100) / 10}s` : "";
+            return { content: `stopped task ${id} (${howEnded(w.info)}${ran})`, isError: false };
+        },
     });
 }
 /** The full coding toolset, bound to one workspace root (Area 5). */
@@ -1526,5 +1679,6 @@ export function createCodingTools(opts) {
         writeFileTool(opts),
         editFileTool(opts),
         shellTool(opts),
+        ...(opts.tasks !== undefined ? [taskStopTool(opts)] : []),
     ];
 }