mixdog 0.9.3 → 0.9.4

package/src/runtime/agent/orchestrator/tools/builtin/search-tool.mjs

@@ -1,7 +1,6 @@
 import { statSync } from 'fs';
 import { isAbsolute, resolve } from 'path';
 import { trueCasePath } from './path-utils.mjs';
-import { findBySuffixStrip } from './path-diagnostics.mjs';
 import {
     canonicalizeGlobSlashes,
     coerceShapeFlex,
@@ -14,13 +13,37 @@ import {
     normalizeSearchPattern,
     resolveAgainstCwd,
 } from './path-utils.mjs';
+import {
+    _suggestIndexedPaths,
+    basePathDiagnostic,
+    buildNotFoundHint,
+    isUncOrSmbPath,
+    relativePathPrefix,
+    relativeSearchResultPath,
+    resolveSearchScope,
+    stripEmbeddedPathQuotes,
+    uncRefusalMessage,
+} from './search-path-diagnostics.mjs';
+// Facade re-export: path-diagnostic helpers moved to search-path-diagnostics.mjs;
+// keep prior importers of search-tool.mjs unchanged.
+export {
+    _suggestIndexedPaths,
+    basePathDiagnostic,
+    buildNotFoundHint,
+    isUncOrSmbPath,
+    relativePathPrefix,
+    relativeSearchResultPath,
+    resolveSearchScope,
+    stripEmbeddedPathQuotes,
+    uncRefusalMessage,
+} from './search-path-diagnostics.mjs';
 import {
     buildGlobCacheKey,
     buildGrepCacheKey,
     buildGrepRgArgs,
     DEFAULT_IGNORE_GLOBS,
 } from './search-builders.mjs';
-import { runRg, runRgWindowedLines } from './rg-runner.mjs';
+import { runRg, runRgWindowedLines, rgSupportsPcre2 } from './rg-runner.mjs';
 import { markScopedCacheIncomplete } from '../../session/cache/scoped-cache-outcome.mjs';
 import {
     groupGrepContentByFile,
@@ -35,7 +58,7 @@ import {
     statPathsForMtime,
 } from './cache-layers.mjs';
 import { recordReadSnapshot } from './read-snapshot-runtime.mjs';
-import { applyGrepContextLeadPolicy, GREP_CONTEXT_MAX } from './arg-guard.mjs';
+import { applyGrepContextLeadPolicy, GREP_CONTEXT_MAX, hasUnsupportedRipgrepRegex } from './arg-guard.mjs';
 
 // Default surrounding-lines window applied by output_mode:'content_with_context'
 // when the caller does not pass an explicit -A/-B/-C/context. Sized to cover a
@@ -50,51 +73,6 @@ function expandLegacyEscapedAlternationPattern(rawPattern) {
     return parts.length > 1 ? parts : null;
 }
 
-// Deterministic ENOENT recovery: when a grep path does not exist, surface
-// indexed files that share the missing path's basename, turning a guessed or
-// misplaced path (e.g. session/result-compression.mjs vs the real
-// tools/result-compression.mjs) into the actual file in one step. Exact
-// basename only — no stem/token fuzzing — so the hint is high-signal and
-// noise-free. Invariant: every ENOENT runs the same basename lookup; there is
-// no "guessed a lot" branch. Returns '' (appends nothing) when no same-named
-// indexed file exists or the glob child is unavailable.
-async function _suggestIndexedPaths(missingPath, executeChildBuiltinTool, workDir) {
-    if (typeof executeChildBuiltinTool !== 'function') return '';
-    const base = String(missingPath).replace(/\\/g, '/').split('/').pop();
-    // Skip when there is no usable basename or it carries glob magic (the
-    // pattern, not a literal filename, would not map to a real file).
-    if (!base || /[*?[\]{}]/.test(base)) return '';
-    try {
-        const out = await executeChildBuiltinTool('glob', { pattern: `**/${base}`, head_limit: 6 }, workDir);
-        if (typeof out !== 'string') return '';
-        // Drop ONLY the exact diagnostic forms glob emits: the empty-result line
-        // ("(no files found ...", "(no entries after offset ...") and the
-        // suffix/warning lines ("... [N more entries]", "... [warning] ...").
-        // A broad startsWith('(' / '...' / 'Error') would wrongly drop real
-        // paths like ErrorBoundary.mjs or a "(draft)/x.mjs" leading segment.
-        const hits = out.split('\n')
-            .filter((s) => s && !/^\(no (?:files found|entries\b)/.test(s) && !/^\.\.\. \[/.test(s))
-            .map((s) => s.trim())
-            .filter(Boolean)
-            .slice(0, 5);
-        return hits.length ? `\n[path not found here; same-named indexed file(s): ${hits.join(', ')}]` : '';
-    } catch {
-        return '';
-    }
-}
-
-function relativePathPrefix(pathPrefix, workDir) {
-    if (!workDir) return pathPrefix;
-    const cwdFwd = workDir.replace(/\\/g, '/').replace(/\/+$/, '');
-    const absFwd = String(pathPrefix || '').replace(/\\/g, '/');
-    const haystack = process.platform === 'win32' ? absFwd.toLocaleLowerCase() : absFwd;
-    const needle = process.platform === 'win32' ? cwdFwd.toLocaleLowerCase() : cwdFwd;
-    if (haystack.startsWith(needle + '/') || haystack === needle) {
-        return absFwd.slice(cwdFwd.length + 1) || '.';
-    }
-    return pathPrefix;
-}
-
 function relativeGrepLine(line, workDir, pathOnly = false, outputMode = 'content', filenameOmitted = false) {
     const normalized = normalizeGrepLine(line, pathOnly, outputMode, filenameOmitted);
     if (!workDir) return normalized;
@@ -113,15 +91,6 @@ function relativeGrepLine(line, workDir, pathOnly = false, outputMode = 'content
     return normalized;
 }
 
-function relativeSearchResultPath(path, workDir) {
-    const normalizedWorkDir = normalizeOutputPath(workDir);
-    const normalizedAbs = normalizeOutputPath(path);
-    if (normalizedAbs.startsWith(normalizedWorkDir + '/') || normalizedAbs.startsWith(normalizedWorkDir + '\\')) {
-        return normalizedAbs.slice(normalizedWorkDir.length + 1);
-    }
-    return normalizedAbs;
-}
-
 function uniqueStrings(values) {
     return Array.from(new Set(values.filter((value) => typeof value === 'string' && value)));
 }
@@ -197,32 +166,6 @@ function isRedundantAllFilesGlob(value) {
     return g === '**/*' || g === '**';
 }
 
-function resolveSearchScope(root, workDir) {
-    return isAbsolute(root) ? resolve(root) : resolveAgainstCwd(root, workDir);
-}
-
-function isUncOrSmbPath(path) {
-    if (typeof path !== 'string' || !path) return false;
-    return path.startsWith('\\\\') || path.startsWith('//');
-}
-
-function uncRefusalMessage(toolName, original, resolved) {
-    const shown = normalizeOutputPath(resolved || original || '');
-    return `Error: ${toolName} refuses UNC/SMB path ${JSON.stringify(shown)}; remote share access is blocked to prevent NTLM credential leaks`;
-}
-
-function basePathDiagnostic(basePaths, workDir) {
-    return basePaths.map((basePath) => {
-        const resolved = resolveSearchScope(basePath, workDir);
-        try {
-            const st = statSync(resolved);
-            return `${normalizeOutputPath(basePath)}: ${st.isDirectory() ? 'path exists (dir)' : 'path exists (file)'}`;
-        } catch (err) {
-            return `${normalizeOutputPath(basePath)}: path does not exist (${err?.code || 'ENOENT'})`;
-        }
-    }).join('; ');
-}
-
 function grepMissingPatternMessage() {
     return 'Error: grep requires pattern.';
 }
@@ -276,11 +219,37 @@ function formatGrepOutput({ windowed, totalWindowed, totalKnown, headLimit, offs
 
 export async function executeGrepTool(args, workDir, executeChildBuiltinTool, readStateScope = null, options = {}) {
     args = normalizeGrepArgs(args);
+    // Fan-out guard: batch multiple string paths sequentially, mirroring
+    // code_graph files[] batching. Recursive calls pass a single string
+    // path, so recursion bottoms out after one level.
+    if (Array.isArray(args.path)) {
+        const GREP_PATH_CAP = 10;
+        const seen = new Set();
+        const list = args.path
+            .map(p => typeof p === 'string' ? p.trim() : '')
+            .filter(p => p && !seen.has(p) && seen.add(p));
+        if (list.length > 1) {
+            const capped = list.slice(0, GREP_PATH_CAP);
+            const parts = [];
+            for (const p of capped) {
+                let body;
+                try {
+                    body = await executeGrepTool({ ...args, path: p }, workDir, executeChildBuiltinTool, readStateScope, options);
+                } catch (err) {
+                    body = `Error: ${err && err.message ? err.message : err}`;
+                }
+                parts.push(`# grep ${p}\n${body}`);
+            }
+            if (list.length > GREP_PATH_CAP) parts.push(`[capped at ${GREP_PATH_CAP} of ${list.length} paths]`);
+            return parts.join('\n\n');
+        }
+        args.path = list[0];
+    }
     // Shape context immediately before deriving rg flags. This keeps the
     // Lead-direct MCP path and direct executeGrepTool callers on the same
     // policy even if they bypass or race the outer builtin arg guard.
     applyGrepContextLeadPolicy(args);
-    args.path = normalizeInputPath(args.path);
+    args.path = stripEmbeddedPathQuotes(normalizeInputPath(args.path));
     args.pattern = coerceShapeFlex(args.pattern);
     args.glob = coerceShapeFlex(args.glob);
     const rawPattern = args.pattern;
@@ -303,13 +272,32 @@ export async function executeGrepTool(args, workDir, executeChildBuiltinTool, re
 
     const GREP_MULTILINE_PATTERN_CAP = 5;
     const GREP_ARRAY_PATTERN_CAP = 20;
-    const multilineMode = args.multiline === true;
+    // Rescue: a pattern containing a literal two-char "\n" (backslash + n)
+    // outside multiline mode makes rg hard-error with "the literal '\"\\n\"'
+    // is not allowed in a regex" — rg requires -U/--multiline before a
+    // pattern is allowed to match across a newline. Rather than reject-and-
+    // retry, auto-enable multiline whenever any pattern carries a literal
+    // \n; an explicit multiline:true from the caller still wins outright.
+    const patternsWantMultiline = patterns.some((p) => /\\n/.test(p));
+    const multilineMode = args.multiline === true || patternsWantMultiline;
     if (multilineMode && patterns.length > GREP_MULTILINE_PATTERN_CAP) {
         return `Error: multiline:true with more than ${GREP_MULTILINE_PATTERN_CAP} patterns is not allowed (got ${patterns.length}); split into separate grep calls`;
     }
     if (patterns.length > GREP_ARRAY_PATTERN_CAP) {
         return `Error: pattern array exceeds the ${GREP_ARRAY_PATTERN_CAP}-pattern cap (got ${patterns.length}); split into separate grep calls`;
     }
+    // Rescue: lookaround/backreference patterns are rejected by rg's default
+    // Rust regex engine ("look-around ... is not supported" / "backreferences
+    // ... not supported"). rg builds compiled with the optional `pcre2`
+    // feature accept the same syntax via -P/--pcre2. Probe capability once
+    // (cached) and route there instead of hard-erroring; when the installed
+    // rg has no PCRE2 support, fall through unchanged and let the existing
+    // arg-guard rejection (or rg's own runtime error) stand.
+    const patternsWantPcre2 = hasUnsupportedRipgrepRegex(patterns);
+    const pcre2Mode = patternsWantPcre2 && await rgSupportsPcre2();
+    if (patternsWantPcre2 && !pcre2Mode) {
+        return `Error: grep pattern uses regex syntax ripgrep does not support here (lookaround/backrefs), and the installed rg build has no PCRE2 support (-P unavailable). Use plain pattern arrays or simpler regex.`;
+    }
 
     let searchPath = args.path || '.';
     const rawGlob = args.glob;
@@ -454,6 +442,7 @@ export async function executeGrepTool(args, workDir, executeChildBuiltinTool, re
         multilineMode,
         onlyMatching: args['-o'] === true,
         fileType,
+        pcre2: pcre2Mode,
     });
     // Single-file grep registers a whole-file read snapshot (parity with
     // apply_patch), satisfying the read-before-edit guard while keeping drift
@@ -479,10 +468,8 @@ export async function executeGrepTool(args, workDir, executeChildBuiltinTool, re
     try { grepStat = statSync(grepResolvedPath); }
     catch (err) {
         const msg = `Error: path does not exist: ${normalizeOutputPath(grepResolvedPath)} (${err?.code || 'ENOENT'})`;
-        const suffixHit = findBySuffixStrip(workDir, grepResolvedPath);
-        if (suffixHit) {
-            return msg + ` Not found at this path; the same filename exists at: "${normalizeOutputPath(suffixHit)}". Search that path directly.`;
-        }
+        const hint = buildNotFoundHint(workDir, grepResolvedPath, 'Search', err?.code);
+        if (hint) return msg + hint;
         return msg + await _suggestIndexedPaths(grepResolvedPath, executeChildBuiltinTool, workDir);
     }
     const filenameOmitted = grepStat.isFile();
@@ -519,6 +506,7 @@ export async function executeGrepTool(args, workDir, executeChildBuiltinTool, re
             multilineMode,
             fileType,
             onlyMatching: args['-o'] === true,
+            pcre2: pcre2Mode,
         });
         let windowed;
         let totalWindowed = 0;
@@ -736,8 +724,8 @@ export async function executeGrepTool(args, workDir, executeChildBuiltinTool, re
 export async function executeGlobTool(args, workDir, options = {}) {
     args = normalizeGlobArgs(args);
     args.path = Array.isArray(args.path)
-        ? args.path.map((p) => normalizeInputPath(p)).filter((p) => typeof p === 'string' && p)
-        : normalizeInputPath(args.path);
+        ? args.path.map((p) => stripEmbeddedPathQuotes(normalizeInputPath(p))).filter((p) => typeof p === 'string' && p)
+        : stripEmbeddedPathQuotes(normalizeInputPath(args.path));
     if (Array.isArray(args.path) && args.path.length === 0) {
         return 'Error: path array must contain at least one base directory';
     }
@@ -866,8 +854,9 @@ export async function executeGlobTool(args, workDir, options = {}) {
         rgArgs.push('.');
         try { statSync(rgCwd); }
         catch (err) {
+            const hint = buildNotFoundHint(workDir, rgCwd, 'Search', err?.code);
             return {
-                error: `path does not exist: ${normalizeOutputPath(rgCwd)} (${err?.code || 'ENOENT'})`,
+                error: `path does not exist: ${normalizeOutputPath(rgCwd)} (${err?.code || 'ENOENT'})${hint}`,
                 paths: [],
                 stdoutTruncated: false,
             };

package/src/runtime/agent/orchestrator/tools/builtin/shell-job-paths.mjs

@@ -0,0 +1,161 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import * as fsPromises from 'fs/promises';
+import { join } from 'path';
+import { getPluginData } from '../../config.mjs';
+
+// One-shot sweep of stale shell-job artefacts. Each backgrounded `bash`
+// emits five files (.json/.done/.exit/.stdout.log/.stderr.log); the .done
+// flag is written when the job exits, so a .done file older than
+// SHELL_JOB_STALE_MS is the invariant proof its sibling files are also
+// safe to remove. Active and recently-completed jobs are kept so
+// `task` status/read/wait readers still find them. Runs once per mcp child
+// lifetime on first getShellJobsDir() call. Async dirent walk + parallel
+// stat/unlink keeps the main event loop free; fire-and-forget so the
+// synchronous caller receives `dir` immediately.
+const SHELL_JOB_STALE_MS = 24 * 60 * 60 * 1000;
+let shellJobsSwept = false;
+async function sweepStaleShellJobs(dir) {
+    if (shellJobsSwept) return;
+    shellJobsSwept = true;
+    const cutoff = Date.now() - SHELL_JOB_STALE_MS;
+    let names;
+    try { names = await fsPromises.readdir(dir); } catch { return; }
+    const expired = [];
+    await Promise.all(names.map(async (name) => {
+        if (!name.endsWith('.done')) return;
+        const p = join(dir, name);
+        try {
+            const st = await fsPromises.stat(p);
+            if (st.mtimeMs < cutoff) expired.push(name.slice(0, -5));
+        } catch {}
+    }));
+    // Orphan reclaim: a crashed wrapper leaves <id>.json with no .done —
+    // forever. Invariant proofs of death (either suffices, both gated on the
+    // stale cutoff so a young orphan can't race its own spawn):
+    //   a) deadline: the wrapper enforces timeoutMs, so an entry older than
+    //      timeoutMs + grace cannot still be running — pid-reuse-proof. Only
+    //      trusted on runtime proof: detail.timeoutEnforced:true (PS wrapper,
+    //      unconditional) or the <id>.enforced marker the posix wrapper
+    //      touches when its `timeout` branch actually runs.
+    //   b) ESRCH: the recorded pid no longer exists. Alone this misses pids
+    //      recycled by unrelated live processes, hence (a).
+    const ORPHAN_DEADLINE_GRACE_MS = 30 * 60_000;
+    const doneSet = new Set(names.filter(n => n.endsWith('.done')).map(n => n.slice(0, -5)));
+    await Promise.all(names.map(async (name) => {
+        if (!name.endsWith('.json')) return;
+        const jobId = name.slice(0, -5);
+        if (doneSet.has(jobId)) return;
+        const p = join(dir, name);
+        try {
+            const st = await fsPromises.stat(p);
+            if (st.mtimeMs >= cutoff) return;
+            const detail = JSON.parse(await fsPromises.readFile(p, 'utf-8'));
+            const tmo = Number(detail?.timeoutMs);
+            const enforced = detail?.timeoutEnforced === true
+                || existsSync(join(dir, `${jobId}.enforced`));
+            const deadlinePassed = enforced
+                && Number.isFinite(tmo) && tmo > 0
+                && (Date.now() - st.mtimeMs) > tmo + ORPHAN_DEADLINE_GRACE_MS;
+            if (!deadlinePassed) {
+                const pid = Number(detail?.pid);
+                if (Number.isFinite(pid) && pid > 0) {
+                    try { process.kill(pid, 0); return; } // alive (or EPERM → treated dead only via ESRCH below)
+                    catch (e) { if (e?.code !== 'ESRCH') return; }
+                }
+            }
+            expired.push(jobId);
+        } catch {}
+    }));
+    // Owner sidecar markers carry a dynamic `.owner-<pid>` suffix, so they
+    // can't sit in the fixed-extension list — map each expired jobId to the
+    // marker name(s) actually present in this listing and unlink those too.
+    const expiredSet = new Set(expired);
+    const ownerMarkers = names.filter((n) => {
+        const i = n.lastIndexOf('.owner-');
+        return i > 0 && expiredSet.has(n.slice(0, i));
+    });
+    await Promise.all([
+        ...expired.flatMap((jobId) =>
+            ['.json', '.done', '.exit', '.enforced', '.exit.cmd.sh', '.exit.cmd.ps1', '.stdout.log', '.stderr.log'].map((ext) =>
+                fsPromises.unlink(join(dir, jobId + ext)).catch(() => {}),
+            ),
+        ),
+        ...ownerMarkers.map((n) => fsPromises.unlink(join(dir, n)).catch(() => {})),
+    ]);
+}
+
+export function getShellJobsDir() {
+    const dir = join(getPluginData(), 'shell-jobs');
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    sweepStaleShellJobs(dir);
+    return dir;
+}
+
+export function shellJobDetailPath(jobId) { return join(getShellJobsDir(), `${jobId}.json`); }
+export function shellJobStdoutPath(jobId) { return join(getShellJobsDir(), `${jobId}.stdout.log`); }
+export function shellJobStderrPath(jobId) { return join(getShellJobsDir(), `${jobId}.stderr.log`); }
+export function shellJobExitPath(jobId) { return join(getShellJobsDir(), `${jobId}.exit`); }
+export function shellJobDonePath(jobId) { return join(getShellJobsDir(), `${jobId}.done`); }
+// Runtime proof that the posix wrapper's `timeout` branch actually ran: the
+// wrapper touches this marker immediately before exec'ing `timeout`, so its
+// existence is never optimistic (no spawn-time probe can guarantee the
+// wrapper's own env/cwd resolution). PS jobs don't need it — their wrapper
+// enforces unconditionally and records detail.timeoutEnforced:true.
+export function shellJobEnforcedPath(jobId) { return join(getShellJobsDir(), `${jobId}.enforced`); }
+// Owner sidecar marker: a zero-byte file whose NAME encodes the owning CC host
+// (claude.exe) pid — `<jobId>.owner-<pid>`. It lets the statusline owner-filter
+// jobs from a SINGLE directory listing (no per-job JSON read) so the filter can
+// precede its per-tick scan cap — otherwise other sessions' newer jobs evict
+// this session's live jobs before filtering. Swept alongside the other
+// artefacts.
+export function shellJobOwnerPath(jobId, pid) { return join(getShellJobsDir(), `${jobId}.owner-${pid}`); }
+
+// Resolve the CLI host pid that owns a freshly-spawned job. Standalone CLI
+// execution is process-owned: background tasks are scoped to this CLI lifetime,
+// and the pid stamp is only for statusline filtering / legacy sidecars.
+export function resolveJobOwnerHostPid(clientHostPid) {
+    const explicit = Number(clientHostPid);
+    if (Number.isInteger(explicit) && explicit > 0) return explicit;
+    const envPid = Number(process.env.MIXDOG_OWNER_HOST_PID);
+    if (Number.isInteger(envPid) && envPid > 0) return envPid;
+    return null;
+}
+
+export function writeShellJobDetail(detail) {
+    // Session scope stamp: every job record is tagged with the CC host pid
+    // that owns it (the claude.exe pid). This is the SAME physical pid the
+    // statusline shim passes as --client-host-pid, so the statusline can count
+    // only its own session's jobs by exact pid equality (no heuristic). The
+    // spawn sites set detail.ownerHostPid from the per-request threaded
+    // clientHostPid (resolveJobOwnerHostPid); this fallback only stamps the
+    // single-client env value when no spawn-site pid was set, and NEVER
+    // overwrites an existing stamp — so the field round-trips through disk on
+    // refresh/kill and a correct per-terminal stamp is preserved across rewrites.
+    if (detail && detail.ownerHostPid == null) {
+        const hostPid = Number(process.env.MIXDOG_OWNER_HOST_PID);
+        if (Number.isInteger(hostPid) && hostPid > 0) detail.ownerHostPid = hostPid;
+    }
+    writeFileSync(shellJobDetailPath(detail.jobId), JSON.stringify(detail, null, 2), 'utf-8');
+    // Owner sidecar: encode the resolved owner pid in the marker filename so the
+    // statusline can owner-filter from the directory listing alone (before its
+    // scan cap). Idempotent zero-byte write — safe to repeat on refresh/kill
+    // rewrites. Skipped when no owner is known (legacy/unattributed jobs).
+    if (detail && Number.isInteger(detail.ownerHostPid) && detail.ownerHostPid > 0) {
+        try { writeFileSync(shellJobOwnerPath(detail.jobId, detail.ownerHostPid), '', 'utf-8'); }
+        catch { /* best-effort marker */ }
+    }
+}
+
+export function readShellJobDetail(jobId) {
+    try {
+        const p = shellJobDetailPath(jobId);
+        if (!existsSync(p)) return null;
+        return JSON.parse(readFileSync(p, 'utf-8'));
+    } catch {
+        return null;
+    }
+}
+
+export function buildJobNotFoundMessage(jobId) {
+    return `Error: task not found: ${jobId}`;
+}

package/src/runtime/agent/orchestrator/tools/builtin/shell-job-process.mjs

@@ -0,0 +1,108 @@
+import { spawn, spawnSync } from 'child_process';
+
+// Process/pid lifecycle helpers for background shell jobs: liveness probing,
+// tree-kill, the module-level live-job pid registry, and the CLI-shutdown exit
+// hook that reaps owned children. Async jobs are intentionally CLI-owned; no
+// restart replay or daemon handoff is attempted.
+
+export function isPidAlive(pid) {
+    if (!Number.isFinite(pid) || pid <= 0) return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+export function killProcessTree(pid, signal = 'SIGTERM') {
+    if (!Number.isFinite(pid) || pid <= 0) return false;
+    try {
+        if (process.platform === 'win32') {
+            spawn('taskkill', ['/pid', String(pid), '/t', '/f'], { windowsHide: true, stdio: 'ignore' });
+        } else {
+            try { process.kill(-pid, signal); }
+            catch { process.kill(pid, signal); }
+            // SIGKILL escalation: a background child that ignores SIGTERM must
+            // not survive (foreground treeKill / persistent _killProcessTree
+            // already do this). After a 3s grace, force-kill the group/pid.
+            // unref so this backstop never holds the host process open.
+            if (signal === 'SIGTERM') {
+                const t = setTimeout(() => {
+                    try { process.kill(-pid, 'SIGKILL'); }
+                    catch { try { process.kill(pid, 'SIGKILL'); } catch { /* already gone */ } }
+                }, 3000);
+                if (t.unref) t.unref();
+            }
+        }
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+// Module-level tracking of live background-job pids so CLI shutdown can reap
+// owned children. Async jobs are intentionally CLI-owned; no restart replay or
+// daemon handoff is attempted.
+export const _liveJobPids = new Set();
+export const _liveJobIdsByPid = new Map();
+let _shellJobsExitHookInstalled = false;
+export function _registerLiveJobPid(pid, jobId = null) {
+    if (Number.isFinite(pid) && pid > 0) {
+        _liveJobPids.add(pid);
+        if (jobId) _liveJobIdsByPid.set(pid, jobId);
+    }
+}
+export function _unregisterLiveJobPid(pid) {
+    if (Number.isFinite(pid) && pid > 0) {
+        _liveJobPids.delete(pid);
+        _liveJobIdsByPid.delete(pid);
+    }
+}
+export function _killLiveJobPid(pid, { sync = false } = {}) {
+    try {
+        if (process.platform === 'win32') {
+            if (sync) {
+                spawnSync('taskkill.exe', ['/pid', String(pid), '/t', '/f'], {
+                    windowsHide: true,
+                    stdio: 'ignore',
+                    timeout: 1500,
+                });
+            } else {
+                spawn('taskkill', ['/pid', String(pid), '/t', '/f'], { windowsHide: true, stdio: 'ignore' });
+            }
+        } else {
+            try { process.kill(-pid, 'SIGKILL'); }
+            catch { try { process.kill(pid, 'SIGKILL'); } catch { /* ignore */ } }
+        }
+        return true;
+    } catch {
+        return false;
+    }
+}
+export function _sweepLiveJobsSync() {
+    for (const pid of _liveJobPids) {
+        _killLiveJobPid(pid, { sync: true });
+    }
+    _liveJobPids.clear();
+    _liveJobIdsByPid.clear();
+}
+function _ensureProcessListenerHeadroom(events, extra = 1) {
+    try {
+        if (typeof process.getMaxListeners !== 'function' || typeof process.setMaxListeners !== 'function') return;
+        const current = process.getMaxListeners();
+        if (current === 0) return;
+        let needed = current;
+        for (const event of events) needed = Math.max(needed, process.listenerCount(event) + extra);
+        if (needed > current) process.setMaxListeners(needed);
+    } catch { /* ignore */ }
+}
+export function _installShellJobsExitHook() {
+    if (_shellJobsExitHookInstalled) return;
+    _shellJobsExitHookInstalled = true;
+    _ensureProcessListenerHeadroom(['exit', 'SIGTERM', 'SIGINT', 'SIGHUP'], 1);
+    try { process.on('exit', _sweepLiveJobsSync); } catch { /* ignore */ }
+    try { process.on('SIGTERM', _sweepLiveJobsSync); } catch { /* ignore */ }
+    try { process.on('SIGINT', _sweepLiveJobsSync); } catch { /* ignore */ }
+    try { process.on('SIGHUP', _sweepLiveJobsSync); } catch { /* ignore */ }
+}