mixdog 0.9.52 → 0.9.53

package/src/runtime/agent/orchestrator/tools/builtin/lib/list-helpers.mjs

@@ -0,0 +1,46 @@
+import {
+    buildNotFoundHint,
+    finalizeReadFamilyEnoentTail,
+    tryReadFamilyEnoentRedirect,
+} from '../search-path-diagnostics.mjs';
+import { normalizeErrorMessage } from '../path-diagnostics.mjs';
+import { isUncPath, isWindowsDevicePath, hasUnsafeWin32Component } from '../device-paths.mjs';
+import { normalizeOutputPath } from '../path-utils.mjs';
+
+/** undefined / invalid / negative → defaultCap; 0 = no page cap (absolute caps still apply). */
+export async function readFamilyPathEnoentOrError(workDir, fullPath, inputPath, args, options, err, rerunTool) {
+    const redirected = await tryReadFamilyEnoentRedirect({
+        workDir,
+        resolvedPath: fullPath,
+        requestedPath: inputPath,
+        errCode: err?.code,
+        options,
+        rerun: (target, opts) => rerunTool({ ...args, path: target }, workDir, opts),
+    });
+    if (redirected) return redirected;
+    const msg = `Error: ${normalizeErrorMessage(err instanceof Error ? err.message : String(err))}`;
+    const hint = buildNotFoundHint(workDir, fullPath, 'List', err?.code);
+    return msg + finalizeReadFamilyEnoentTail(hint, inputPath, err?.code);
+}
+
+export function normalizeListHeadLimit(raw, defaultCap) {
+    if (raw === undefined || raw === null || raw === '') return defaultCap;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 0) return defaultCap;
+    return Math.floor(n);
+}
+
+// UNC / Windows-device / NTFS-ADS guard for directory-walking modes
+// (list / tree / find). Walking a UNC share auto-authenticates to the
+// remote host (NTLM hash leak); a raw-device / reserved-name path can
+// hang or grant raw access. Mirrors the read path's string-based checks.
+// Returns an Error string when the path is blocked, else null.
+export function listGuardPath(p) {
+    if (typeof isUncPath === 'function' && isUncPath(p))
+        return `Error: cannot walk UNC / SMB path (network credential leak risk): ${normalizeOutputPath(p)}`;
+    if (typeof isWindowsDevicePath === 'function' && isWindowsDevicePath(p))
+        return `Error: cannot walk Windows device path (reserved name or raw-device namespace): ${normalizeOutputPath(p)}`;
+    if (typeof hasUnsafeWin32Component === 'function' && hasUnsafeWin32Component(p))
+        return `Error: cannot walk Windows path with trailing dot/space or NTFS ADS suffix (bypasses device guard): ${normalizeOutputPath(p)}`;
+    return null;
+}

package/src/runtime/agent/orchestrator/tools/builtin/lib/search-grep-chunks.mjs

@@ -0,0 +1,173 @@
+import { splitGrepLinePrefix } from '../grep-formatting.mjs';
+
+const GREP_RESULT_LINE_SKIP = /^\[(?:Showing|total|pattern set|capped|warning|redirected|regex parse)/;
+const GREP_CHUNK_AGGREGATE_FLOOR = 200;
+const GREP_CHUNK_AGGREGATE_DEFAULT = 800;
+const GREP_CHUNK_AGGREGATE_MAX = 4000;
+
+export function chunkPatternList(patterns, cap) {
+    const out = [];
+    for (let i = 0; i < patterns.length; i += cap) out.push(patterns.slice(i, i + cap));
+    return out;
+}
+
+export function computeGrepChunkAggregateBudget(offset, headLimit, headLimitCoerced) {
+    if (headLimitCoerced === 0 && headLimit === Infinity) return GREP_CHUNK_AGGREGATE_MAX;
+    if (headLimit === Infinity) return GREP_CHUNK_AGGREGATE_DEFAULT;
+    const need = offset + headLimit;
+    return Math.min(GREP_CHUNK_AGGREGATE_MAX, Math.max(GREP_CHUNK_AGGREGATE_FLOOR, need * 2));
+}
+
+function compareGrepLinesByPathLine(a, b) {
+    const pa = splitGrepLinePrefix(a);
+    const pb = splitGrepLinePrefix(b);
+    if (!pa && !pb) return String(a).localeCompare(String(b));
+    if (!pa) return 1;
+    if (!pb) return -1;
+    const byPath = pa.path.localeCompare(pb.path);
+    if (byPath !== 0) return byPath;
+    return pa.lineNo - pb.lineNo;
+}
+
+function deriveGrepCountLinesFromMatchContent(lines) {
+    const byPath = new Map();
+    for (const line of lines) {
+        const split = splitGrepLinePrefix(line);
+        if (!split || split.delimiter !== ':') continue;
+        if (!byPath.has(split.path)) byPath.set(split.path, new Set());
+        byPath.get(split.path).add(split.lineNo);
+    }
+    return [...byPath.entries()]
+        .sort((a, b) => a[0].localeCompare(b[0]))
+        .map(([path, lineNos]) => `${path}:${lineNos.size}`);
+}
+
+function isGrepMatchLine(line) {
+    const split = splitGrepLinePrefix(line);
+    return !!(split && split.delimiter === ':');
+}
+
+function grepMatchAnchorKey(line) {
+    const split = splitGrepLinePrefix(line);
+    if (!split || split.delimiter !== ':') return '';
+    return `${split.path}\0${split.lineNo}`;
+}
+
+function parseGrepContextBlocksInSegment(segmentLines) {
+    const blocks = [];
+    let pending = [];
+    let i = 0;
+    while (i < segmentLines.length) {
+        const line = segmentLines[i];
+        if (isGrepMatchLine(line)) {
+            const blockLines = pending.concat([line]);
+            pending = [];
+            i += 1;
+            while (i < segmentLines.length) {
+                const next = segmentLines[i];
+                if (next === '--' || isGrepMatchLine(next)) break;
+                blockLines.push(next);
+                i += 1;
+            }
+            const anchor = grepMatchAnchorKey(line);
+            if (anchor) blocks.push({ anchor, lines: blockLines });
+            continue;
+        }
+        pending.push(line);
+        i += 1;
+    }
+    return blocks;
+}
+
+function compareGrepAnchorKeys(a, b) {
+    const [pa, la] = String(a || '').split('\0');
+    const [pb, lb] = String(b || '').split('\0');
+    const byPath = pa.localeCompare(pb);
+    if (byPath !== 0) return byPath;
+    return Number(la) - Number(lb);
+}
+
+function mergeGrepContextChunkLines(lines) {
+    const segments = [];
+    let current = [];
+    for (const line of lines) {
+        if (line === '--') {
+            segments.push(current);
+            current = [];
+        } else {
+            current.push(line);
+        }
+    }
+    segments.push(current);
+    const seen = new Set();
+    const blocks = [];
+    for (const segment of segments) {
+        if (!segment.length) continue;
+        for (const block of parseGrepContextBlocksInSegment(segment)) {
+            if (!block.anchor || seen.has(block.anchor)) continue;
+            seen.add(block.anchor);
+            blocks.push(block);
+        }
+    }
+    blocks.sort((a, b) => compareGrepAnchorKeys(a.anchor, b.anchor));
+    const out = [];
+    for (const block of blocks) {
+        if (out.length) out.push('--');
+        out.push(...block.lines);
+    }
+    return out;
+}
+
+export function mergeGrepChunkLines(lines, { outputMode, beforeN, afterN, contextN }) {
+    const hasContext = (beforeN > 0 || afterN > 0 || contextN > 0);
+    if (outputMode === 'count') {
+        return deriveGrepCountLinesFromMatchContent(lines);
+    }
+    if (outputMode === 'files_with_matches') {
+        const seen = new Set();
+        const out = [];
+        for (const line of lines) {
+            const path = String(line || '').trim();
+            if (!path || seen.has(path)) continue;
+            seen.add(path);
+            out.push(path);
+        }
+        out.sort((a, b) => a.localeCompare(b));
+        return out;
+    }
+    if (outputMode === 'content' && hasContext) {
+        return mergeGrepContextChunkLines(lines);
+    }
+    const matches = new Map();
+    for (const line of lines) {
+        const split = splitGrepLinePrefix(line);
+        if (split && split.delimiter === ':') {
+            const key = `${split.path}\0${split.lineNo}`;
+            if (!matches.has(key)) matches.set(key, line);
+        }
+    }
+    return [...matches.values()].sort(compareGrepLinesByPathLine);
+}
+
+export function extractGrepChunkResultLines(body, room = Infinity) {
+    const text = String(body || '').trim();
+    if (!text || /^Error:/i.test(text)) return { error: text || 'Error: empty grep chunk result' };
+    if (/^\(no matches\)/i.test(text)) return { lines: [], truncated: false };
+    const rawLines = text.split('\n');
+    const childShowingTruncated = rawLines.some((line) => /^\[Showing /i.test(String(line || '').trim()));
+    const lines = rawLines.filter((line) => line && !GREP_RESULT_LINE_SKIP.test(line));
+    const truncated = childShowingTruncated
+        || (Number.isFinite(room) && room >= 0 && lines.length >= room);
+    return { lines, truncated };
+}
+
+export function buildGrepChunkMergePrefix(patternChunkCount, truncated, aggregateBudget, outputMode = 'content') {
+    if (patternChunkCount <= 1 && !truncated) return '';
+    const parts = [];
+    if (patternChunkCount > 1) parts.push(`pattern set split into ${patternChunkCount} chunks`);
+    if (truncated) {
+        parts.push(`chunk results truncated at aggregate budget ${aggregateBudget} lines; results are partial`);
+        if (outputMode === 'count') parts.push('counts are lower bounds (>=)');
+    }
+    return `[${parts.join('; ')}]\n`;
+}

package/src/runtime/agent/orchestrator/tools/builtin/lib/search-input-helpers.mjs

@@ -0,0 +1,117 @@
+import { isAbsolute } from 'path';
+import { canonicalizeGlobSlashes, normalizeOutputPath } from '../path-utils.mjs';
+import {
+    relativePathPrefix,
+} from '../search-path-diagnostics.mjs';
+import {
+    normalizeGrepLine,
+    splitGrepCountPrefix,
+    splitGrepLinePrefix,
+} from '../grep-formatting.mjs';
+
+export function expandLegacyEscapedAlternationPattern(rawPattern) {
+    if (typeof rawPattern !== 'string' || !rawPattern.includes('\\|')) return null;
+    const parts = rawPattern.split('\\|').map((part) => part.trim()).filter(Boolean);
+    return parts.length > 1 ? parts : null;
+}
+
+export function relativeGrepLine(line, workDir, pathOnly = false, outputMode = 'content', filenameOmitted = false) {
+    const normalized = normalizeGrepLine(line, pathOnly, outputMode, filenameOmitted);
+    if (!workDir) return normalized;
+    if (pathOnly) return relativePathPrefix(normalized, workDir);
+    if (filenameOmitted) return normalized;
+    const split = splitGrepLinePrefix(normalized);
+    if (split) {
+        return relativePathPrefix(normalized.slice(0, split.pathEnd), workDir) + normalized.slice(split.pathEnd);
+    }
+    if (outputMode === 'count') {
+        const countSplit = splitGrepCountPrefix(normalized);
+        if (countSplit) {
+            return relativePathPrefix(normalized.slice(0, countSplit.pathEnd), workDir) + normalized.slice(countSplit.pathEnd);
+        }
+    }
+    return normalized;
+}
+
+export function uniqueStrings(values) {
+    return Array.from(new Set(values.filter((value) => typeof value === 'string' && value)));
+}
+
+export function isRgRegexParseError(err) {
+    const msg = `${err?.stderr || ''}\n${err?.message || err || ''}`;
+    return /regex parse error/i.test(msg);
+}
+
+export function regexPatternToFixedTerms(pattern) {
+    const raw = String(pattern || '');
+    if (!raw) return [];
+    return raw
+        .split(/\\?\|/g)
+        .map((part) => part.trim())
+        .map((part) => part
+            .replace(/\\[bB]/g, '')
+            .replace(/^\^/, '')
+            .replace(/\$$/, '')
+            .replace(/\\([\\.^$*+?()[\]{}|/-])/g, '$1')
+            .trim())
+        .filter((part) => part.length > 0);
+}
+
+export function coerceNonNegInt(value) {
+    if (value === undefined || value === null || value === '') return null;
+    const n = Number(value);
+    if (!Number.isFinite(n) || n < 0) return NaN;
+    return Math.floor(n);
+}
+
+export function globMtimeTiePath(entry) {
+    const p = String(entry?.path ?? entry?.full ?? '');
+    return process.platform === 'win32' ? p.toLocaleLowerCase() : p;
+}
+
+export function splitGlobString(value) {
+    const out = [];
+    const str = String(value);
+    let depth = 0;
+    let token = '';
+    const flush = () => {
+        const trimmed = token.trim();
+        if (trimmed) out.push(trimmed);
+        token = '';
+    };
+    for (const ch of str) {
+        if (ch === '{') {
+            depth++;
+            token += ch;
+        } else if (ch === '}') {
+            if (depth > 0) depth--;
+            token += ch;
+        } else if (depth === 0 && (ch === ',' || /\s/.test(ch))) {
+            flush();
+        } else {
+            token += ch;
+        }
+    }
+    flush();
+    return out;
+}
+
+export function isRedundantAllFilesGlob(value) {
+    const g = canonicalizeGlobSlashes(String(value || '').trim())
+        .replace(/^\.\//, '')
+        .replace(/^\/+/, '')
+        .replace(/\/+$/, '');
+    return g === '**/*' || g === '**';
+}
+
+export function parseGrepCountLine(line) {
+    const text = String(line || '');
+    const searchFrom = /^[A-Za-z]:/.test(text) ? 2 : 0;
+    const idx = text.lastIndexOf(':');
+    if (idx <= searchFrom) return null;
+    const count = Number(text.slice(idx + 1));
+    if (!Number.isFinite(count) || count <= 0) return null;
+    const path = text.slice(0, idx);
+    if (!path) return null;
+    return { path, count };
+}

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

@@ -0,0 +1,199 @@
+import { closeSync, existsSync, openSync, readSync, statSync } from 'fs';
+import { stripAnsi } from '../../shell-command.mjs';
+
+const JOB_STATUS_PREVIEW_MAX_BYTES = 4096;
+const JOB_STATUS_PREVIEW_MAX_LINES = 20;
+const JOB_STATUS_PREVIEW_MAX_CHARS = 1200;
+// Hard ceiling on a background job's on-disk stdout+stderr. Mirrors the
+// foreground SHELL_OUTPUT_DISK_CAP (shell-command.mjs) so a runaway
+// background loop is killed and flagged instead of filling the filesystem.
+export const SHELL_JOB_OUTPUT_DISK_CAP = 100 * 1024 * 1024;
+
+// Combined byte size of a job's spilled stdout/stderr files, or 0 if
+// unreadable. mergeStderr collapses both onto stdoutPath, so count it once.
+export function shellJobOutputBytes(detail) {
+    let total = 0;
+    const seen = new Set();
+    for (const p of [detail?.stdoutPath, detail?.stderrPath]) {
+        if (!p || seen.has(p)) continue;
+        seen.add(p);
+        try {
+            if (existsSync(p)) total += statSync(p).size;
+        } catch { /* ignore */ }
+    }
+    return total;
+}
+
+function readTailPreviewSync(filePath, { maxBytes = JOB_STATUS_PREVIEW_MAX_BYTES, maxLines = JOB_STATUS_PREVIEW_MAX_LINES, maxChars = JOB_STATUS_PREVIEW_MAX_CHARS } = {}) {
+    try {
+        if (!filePath || !existsSync(filePath)) return null;
+        const st = statSync(filePath);
+        if (!st.isFile()) return null;
+        const size = st.size;
+        if (size <= 0) return { bytes: 0, preview: '' };
+        const readBytes = Math.min(size, maxBytes);
+        const fd = openSync(filePath, 'r');
+        try {
+            const buf = Buffer.alloc(readBytes);
+            readSync(fd, buf, 0, readBytes, size - readBytes);
+            let text = buf.toString('utf8');
+            if (size > readBytes) {
+                const nl = text.indexOf('\n');
+                if (nl !== -1) text = text.slice(nl + 1);
+            }
+            let lines = text.split(/\r?\n/);
+            if (lines.length > 0 && lines[lines.length - 1] === '') lines.pop();
+            let truncated = size > readBytes;
+            if (lines.length > maxLines) {
+                lines = lines.slice(-maxLines);
+                truncated = true;
+            }
+            let preview = lines.join('\n');
+            if (preview.length > maxChars) {
+                preview = preview.slice(preview.length - maxChars);
+                const nl = preview.indexOf('\n');
+                if (nl !== -1) preview = preview.slice(nl + 1);
+                truncated = true;
+            }
+            return {
+                bytes: size,
+                preview,
+                truncated,
+            };
+        } finally {
+            try { closeSync(fd); } catch { /* ignore */ }
+        }
+    } catch {
+        return null;
+    }
+}
+
+function attachJobPreview(detail) {
+    if (!detail || typeof detail !== 'object') return detail;
+    const withPreview = { ...detail };
+    const stdoutInfo = readTailPreviewSync(detail.stdoutPath);
+    if (stdoutInfo) {
+        withPreview.stdoutBytes = stdoutInfo.bytes;
+        if (stdoutInfo.preview) withPreview.stdoutPreview = stdoutInfo.preview;
+        if (stdoutInfo.truncated) withPreview.stdoutPreviewTruncated = true;
+    }
+    if (detail.mergeStderr !== true) {
+        const stderrInfo = readTailPreviewSync(detail.stderrPath);
+        if (stderrInfo) {
+            withPreview.stderrBytes = stderrInfo.bytes;
+            if (stderrInfo.preview) withPreview.stderrPreview = stderrInfo.preview;
+            if (stderrInfo.truncated) withPreview.stderrPreviewTruncated = true;
+        }
+    }
+    return withPreview;
+}
+
+function summarizeJobPreviewText(text, maxChars = 160) {
+    if (typeof text !== 'string' || !text.trim()) return '';
+    const lines = text
+        .split(/\r?\n/)
+        .map((line) => stripAnsi(line).replace(/\s+/g, ' ').trim())
+        .filter(Boolean);
+    if (lines.length === 0) return '';
+    let summary = lines[lines.length - 1];
+    if (summary.length > maxChars) summary = `${summary.slice(0, maxChars - 1)}…`;
+    return summary;
+}
+
+const SHELL_JOB_PROMPT_TAIL_BYTES = 1024;
+const SHELL_JOB_PROMPT_TAIL_LINES = 16;
+const SHELL_JOB_PROMPT_TAIL_CHARS = 1024;
+const SHELL_JOB_PROMPT_PATTERNS = [
+    /\((?:y|yes)\/(?:n|no)\)\s*[:?]?\s*$/i,
+    /\[(?:y|yes)\/(?:n|no)\]\s*[:?]?\s*$/i,
+    /\b(?:continue|proceed|confirm|overwrite|replace)\b[^\n]*[?:]\s*$/i,
+    /\bpress\s+(?:enter|return)\b[^\n]*$/i,
+    /\bdo you (?:want|wish|agree|accept)\b[^\n]*\?\s*$/i,
+    /\b(?:password|passphrase|otp|verification code)\b[^\n]*[:?]\s*$/i,
+];
+
+export function looksLikeInteractivePrompt(text) {
+    const tail = stripAnsi(String(text || '')).trim();
+    if (!tail) return false;
+    const last = tail.split(/\r?\n/).slice(-4).join('\n').trim();
+    return SHELL_JOB_PROMPT_PATTERNS.some((pattern) => pattern.test(last));
+}
+
+export function readPromptTail(detail) {
+    if (!detail || typeof detail !== 'object') return { bytes: 0, text: '' };
+    const stdoutInfo = readTailPreviewSync(detail.stdoutPath, {
+        maxBytes: SHELL_JOB_PROMPT_TAIL_BYTES,
+        maxLines: SHELL_JOB_PROMPT_TAIL_LINES,
+        maxChars: SHELL_JOB_PROMPT_TAIL_CHARS,
+    });
+    const stderrInfo = detail.mergeStderr === true ? null : readTailPreviewSync(detail.stderrPath, {
+        maxBytes: SHELL_JOB_PROMPT_TAIL_BYTES,
+        maxLines: SHELL_JOB_PROMPT_TAIL_LINES,
+        maxChars: SHELL_JOB_PROMPT_TAIL_CHARS,
+    });
+    const bytes = (stdoutInfo?.bytes || 0) + (stderrInfo?.bytes || 0);
+    const parts = [
+        stdoutInfo?.preview ? `[stdout tail]\n${stdoutInfo.preview}` : '',
+        stderrInfo?.preview ? `[stderr tail]\n${stderrInfo.preview}` : '',
+    ].filter(Boolean);
+    return { bytes, text: parts.join('\n\n') };
+}
+
+export function attachJobInsights(detail) {
+    const withPreview = attachJobPreview(detail);
+    if (!withPreview || typeof withPreview !== 'object') return withPreview;
+    let summary = '';
+    let summarySource = '';
+    if (withPreview.status === 'completed') {
+        summary = summarizeJobPreviewText(withPreview.stdoutPreview)
+            || summarizeJobPreviewText(withPreview.stderrPreview);
+        summarySource = summary ? (withPreview.stdoutPreview ? 'stdout' : 'stderr') : '';
+    } else if (withPreview.status === 'failed') {
+        summary = summarizeJobPreviewText(withPreview.stderrPreview)
+            || summarizeJobPreviewText(withPreview.stdoutPreview)
+            || String(withPreview.error || '').trim();
+        summarySource = summary ? (withPreview.stderrPreview ? 'stderr' : (withPreview.stdoutPreview ? 'stdout' : 'status')) : '';
+    } else if (withPreview.status === 'cancelled') {
+        summary = 'cancelled before completion';
+        summarySource = 'status';
+    } else if (withPreview.status === 'running') {
+        summary = summarizeJobPreviewText(withPreview.stdoutPreview)
+            || summarizeJobPreviewText(withPreview.stderrPreview);
+        summarySource = summary ? (withPreview.stdoutPreview ? 'stdout' : 'stderr') : '';
+    }
+    if (summary) {
+        withPreview.summary = summary;
+        withPreview.summarySource = summarySource;
+    }
+    return withPreview;
+}
+
+export function shellJobPublicTaskResult(detail) {
+    if (!detail || typeof detail !== 'object') return detail;
+    const result = {
+        task_id: detail.jobId || detail.task_id || null,
+        shell: detail.shellType || null,
+        status: detail.status || null,
+        cwd: detail.cwd || null,
+        pid: detail.pid || null,
+        exit_code: (typeof detail.exitCode === 'number') ? detail.exitCode : null,
+        signal: detail.signal || null,
+        timed_out: detail.timedOut === true ? true : null,
+        killed: detail.killed === true ? true : null,
+        stdout_bytes: (typeof detail.stdoutBytes === 'number') ? detail.stdoutBytes : null,
+        stderr_bytes: (typeof detail.stderrBytes === 'number') ? detail.stderrBytes : null,
+        stdout_preview: detail.stdoutPreview || null,
+        stderr_preview: detail.stderrPreview || null,
+        summary: detail.summary || null,
+        summary_source: detail.summarySource || null,
+        waited_ms: (typeof detail.waitedMs === 'number') ? detail.waitedMs : null,
+        wait_timed_out: detail.waitTimedOut === true ? true : null,
+        started_at: detail.startedAt || null,
+        finished_at: detail.finishedAt || null,
+        error: detail.error || null,
+    };
+    for (const [key, value] of Object.entries(result)) {
+        if (value == null || value === '') delete result[key];
+    }
+    return result;
+}

package/src/runtime/agent/orchestrator/tools/builtin/lib/shell-spawn-helpers.mjs

@@ -0,0 +1,107 @@
+import { basename } from 'path';
+import { killProcessTree } from '../shell-job-process.mjs';
+
+const SPAWN_ERROR_GUARD = Symbol('mixdog.spawnErrorGuard');
+
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export function awaitSpawnReady(child, label) {
+    return new Promise((resolve, reject) => {
+        if (!child || typeof child.once !== 'function') {
+            reject(new Error(`${label} spawn returned no child process`));
+            return;
+        }
+        let spawned = false;
+        let bufferedError = null;
+        const cleanup = () => child.removeListener('spawn', onSpawn);
+        const onError = (error) => {
+            if (spawned) {
+                bufferedError = bufferedError || error;
+                return;
+            }
+            cleanup();
+            child.removeListener('error', onError);
+            reject(error);
+        };
+        const onSpawn = () => {
+            cleanup();
+            spawned = true;
+            const pid = Number(child.pid);
+            if (!Number.isFinite(pid) || pid <= 0) {
+                child.removeListener('error', onError);
+                reject(new Error(`${label} spawn returned no pid`));
+                return;
+            }
+            child[SPAWN_ERROR_GUARD] = {
+                adopt(handler) {
+                    child.on('error', handler);
+                    child.removeListener('error', onError);
+                    if (bufferedError) handler(bufferedError);
+                    delete child[SPAWN_ERROR_GUARD];
+                },
+                discard() {
+                    child.removeListener('error', onError);
+                    delete child[SPAWN_ERROR_GUARD];
+                },
+            };
+            resolve(child);
+        };
+        child.once('error', onError);
+        child.once('spawn', onSpawn);
+    });
+}
+
+export function adoptSpawnErrorHandler(child, handler) {
+    const guard = child?.[SPAWN_ERROR_GUARD];
+    if (guard) guard.adopt(handler);
+    else child?.on?.('error', handler);
+}
+
+export function discardSpawnErrorGuard(child) {
+    child?.[SPAWN_ERROR_GUARD]?.discard?.();
+}
+
+export async function rollbackSpawnedChild(child, { timeoutMs = 5000 } = {}) {
+    if (!child || child.exitCode != null || child.signalCode != null) {
+        return { confirmed: true, errors: [] };
+    }
+    const errors = [];
+    let timer = null;
+    let settled = false;
+    const outcome = await new Promise((resolve) => {
+        const finish = (confirmed) => {
+            if (settled) return;
+            settled = true;
+            if (timer) clearTimeout(timer);
+            child.removeListener('exit', onExit);
+            child.removeListener('close', onExit);
+            child.removeListener('error', onError);
+            resolve({ confirmed, errors });
+        };
+        const onExit = () => finish(true);
+        const onError = (error) => { errors.push(error); };
+        child.on('error', onError);
+        child.once('exit', onExit);
+        child.once('close', onExit);
+        timer = setTimeout(() => finish(false), Math.max(1, Number(timeoutMs) || 5000));
+        try { killProcessTree(child.pid, 'SIGKILL'); } catch (error) { errors.push(error); }
+        try { child.kill?.('SIGKILL'); } catch (error) { errors.push(error); }
+    });
+    return outcome;
+}
+
+export function shellQuoteSingle(s) {
+    return `'${String(s).replace(/'/g, `'\"'\"'`)}'`;
+}
+
+export function psSingleQuote(s) {
+    return `'${String(s).replace(/'/g, "''")}'`;
+}
+
+export function isPowerShellShell(shell, shellType) {
+    if (shellType === 'powershell') return true;
+    const stem = basename(String(shell || '')).toLowerCase().replace(/\.exe$/, '');
+    return stem === 'pwsh' || stem === 'powershell';
+}