mixdog 0.9.2 → 0.9.4

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

@@ -29,6 +29,7 @@ export function buildGrepCacheKey(parts) {
         multilineMode,
         fileType,
         onlyMatching,
+        pcre2,
     } = parts;
     return [
         'grep',
@@ -46,6 +47,7 @@ export function buildGrepCacheKey(parts) {
         multilineMode ? 'm1' : 'm0',
         onlyMatching ? 'o1' : 'o0',
         Array.isArray(fileType) ? fileType.join('\x01') : (fileType || ''),
+        pcre2 ? 'p1' : 'p0',
     ].join('|');
 }
 
@@ -64,6 +66,7 @@ export function buildGrepRgArgs(parts) {
         fileType,
         onlyMatching,
         fixedStrings = false,
+        pcre2 = false,
     } = parts;
     // `--hidden`: search dotfiles/dot-dirs (.github, .mixdog) that
     // rg skips by default. The DEFAULT_IGNORE_GLOBS below still exclude .git and
@@ -84,6 +87,11 @@ export function buildGrepRgArgs(parts) {
     }
     if (caseInsensitive) rgArgs.push('-i');
     if (fixedStrings) rgArgs.push('-F');
+    // PCRE2 engine: opt-in only when the caller already confirmed (via
+    // rgSupportsPcre2() in search-tool.mjs) that the installed rg binary was
+    // built with PCRE2 support. Enables lookaround/backreference patterns
+    // that the default Rust regex engine rejects outright.
+    if (pcre2) rgArgs.push('-P');
     if (multilineMode) rgArgs.push('-U', '--multiline-dotall');
     if (Array.isArray(fileType)) {
         for (const t of fileType) if (t) rgArgs.push('--type', t);

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

@@ -0,0 +1,126 @@
+/**
+ * Search path diagnostics: ENOENT recovery + path-shape helpers shared by
+ * grep/glob in search-tool.mjs. Extracted verbatim so search-tool.mjs stays a
+ * thin executor; search-tool.mjs re-exports these for unchanged importers.
+ */
+import { statSync } from 'fs';
+import { isAbsolute, resolve } from 'path';
+import { findBySuffixStrip, findFileByBasename } from './path-diagnostics.mjs';
+import { normalizeOutputPath, resolveAgainstCwd } from './path-utils.mjs';
+
+// 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.
+export 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 '';
+    }
+}
+
+// Models occasionally glue a quoted segment onto an otherwise-unquoted path
+// (e.g. `C:/Project/mixdog/"src/x.mjs"` — prefix bare, trailing segment
+// wrapped in literal quote chars from a mis-escaped interpolation). But
+// quote chars CAN be legit path content (POSIX `src/Bob's/file.mjs`), so
+// stripping is existence-guarded: keep the original if it stats, only fall
+// back to the stripped variant otherwise. Cost is one statSync and only on
+// the rare quote-containing path.
+export function stripEmbeddedPathQuotes(p) {
+    if (typeof p !== 'string' || !p) return p;
+    if (!p.includes('"') && !p.includes("'")) return p;
+    try { statSync(p); return p; } catch { /* fall through to stripped */ }
+    return p.replace(/['"]/g, '');
+}
+
+// Reuse read's own ENOENT recovery (path-diagnostics findBySuffixStrip /
+// findFileByBasename — the exact fs scans read-single-tool.mjs already runs
+// for its "same filename exists at" hint) so a grep/glob path miss redirects
+// to the real location instead of dead-ending. No new fs scan is added here;
+// this only calls the two helpers read already calls, with a caller-supplied
+// action verb ("Search"/"List") in place of read's "Read". Gated to genuine
+// not-found codes: EACCES/EPERM etc. keep their real failure semantics and
+// must not trigger same-basename guidance or the BFS scan.
+const NOT_FOUND_CODES = new Set(['ENOENT', 'ENOTDIR']);
+export function buildNotFoundHint(workDir, missingPath, actionVerb, errCode = 'ENOENT') {
+    if (!NOT_FOUND_CODES.has(String(errCode || 'ENOENT'))) return '';
+    const suffixHit = findBySuffixStrip(workDir, missingPath);
+    if (suffixHit) {
+        return ` Not found at this path; the same filename exists at: "${normalizeOutputPath(suffixHit)}". ${actionVerb} that path directly.`;
+    }
+    const elsewhere = findFileByBasename(workDir, missingPath);
+    if (elsewhere.length) {
+        return ` Not found at this path; the same filename exists at: ${elsewhere.map((p) => `"${normalizeOutputPath(p)}"`).join(', ')}. ${actionVerb} that path directly.`;
+    }
+    return '';
+}
+
+export 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;
+}
+
+export 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;
+}
+
+export function resolveSearchScope(root, workDir) {
+    return isAbsolute(root) ? resolve(root) : resolveAgainstCwd(root, workDir);
+}
+
+export function isUncOrSmbPath(path) {
+    if (typeof path !== 'string' || !path) return false;
+    return path.startsWith('\\\\') || path.startsWith('//');
+}
+
+export 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`;
+}
+
+export 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'})`
+                + buildNotFoundHint(workDir, resolved, 'Search', err?.code);
+        }
+    }).join('; ');
+}

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

@@ -13,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,
@@ -34,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
@@ -49,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;
@@ -112,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)));
 }
@@ -196,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.';
 }
@@ -275,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;
@@ -302,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;
@@ -453,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
@@ -478,6 +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 hint = buildNotFoundHint(workDir, grepResolvedPath, 'Search', err?.code);
+        if (hint) return msg + hint;
         return msg + await _suggestIndexedPaths(grepResolvedPath, executeChildBuiltinTool, workDir);
     }
     const filenameOmitted = grepStat.isFile();
@@ -514,6 +506,7 @@ export async function executeGrepTool(args, workDir, executeChildBuiltinTool, re
             multilineMode,
             fileType,
             onlyMatching: args['-o'] === true,
+            pcre2: pcre2Mode,
         });
         let windowed;
         let totalWindowed = 0;
@@ -731,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';
     }
@@ -861,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}`;
+}