@davesheffer/hunch 1.45.1 → 1.46.0

package/dist/cli/verify.js

@@ -0,0 +1,265 @@
+import { execFileSync, spawn, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync } from "node:fs";
+import { availableParallelism, tmpdir } from "node:os";
+import { dirname, isAbsolute, join, relative } from "node:path";
+import { readConfig } from "../core/config.js";
+import { writeFileAtomic } from "../core/io.js";
+import { hunchPaths } from "../core/paths.js";
+import { buildImportGraph, changedFiles, coverageFiles, discoverTests, listRepoFiles, loadImpactMap, selectTests, testDependencyModel, } from "../core/testSelection.js";
+export const DEFAULT_IMPACT_MAP = ".hunch-cache/test-impact.json";
+function testScript(root) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+        return typeof pkg.scripts?.test === "string" ? pkg.scripts.test : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Split a command template into argv tokens; double/single quotes group. */
+export function tokenize(template) {
+    const out = [];
+    for (const m of template.matchAll(/"([^"]*)"|'([^']*)'|(\S+)/g))
+        out.push(m[1] ?? m[2] ?? m[3]);
+    return out;
+}
+/** npm without a shell: run npm-cli.js under this Node; POSIX may exec `npm`. */
+function npmArgv(args) {
+    const dir = dirname(process.execPath);
+    for (const cli of [join(dir, "node_modules/npm/bin/npm-cli.js"), join(dir, "../lib/node_modules/npm/bin/npm-cli.js")]) {
+        if (existsSync(cli))
+            return [process.execPath, cli, ...args];
+    }
+    if (process.platform === "win32")
+        throw new Error("cannot locate npm-cli.js; set verify.command in .hunch/config.json");
+    return ["npm", ...args];
+}
+/** The runner argv (never a shell). A configured template wins (`{files}` expands
+ *  to one argv entry per file); otherwise this repo's runner when present, else
+ *  `npm test` (full) / `npm test -- <files>`. */
+export function runnerArgv(root, template, files, extra, full) {
+    if (template) {
+        const tokens = tokenize(template);
+        const argv = tokens.includes("{files}") ? tokens.flatMap((t) => t === "{files}" ? files : [t]) : [...tokens, ...files];
+        if (argv[0] === "node")
+            argv[0] = process.execPath;
+        return [...argv, ...extra];
+    }
+    if (full && testScript(root))
+        return npmArgv(["test", ...(extra.length ? ["--", ...extra] : [])]);
+    if (existsSync(join(root, "tooling/run-tests.mjs")))
+        return [process.execPath, "tooling/run-tests.mjs", ...files, ...extra];
+    return npmArgv(["test", "--", ...files, ...extra]);
+}
+const display = (argv) => argv.map((a, i) => i === 0 && a === process.execPath ? "node" : /\s/.test(a) ? JSON.stringify(a) : a).join(" ");
+function printSelection(sel, total, note, hasMap) {
+    for (const line of note)
+        console.log(`  note: ${line}`);
+    if (sel.mode === "none") {
+        console.log("✓ no tests selected — nothing the changes can affect.");
+        return;
+    }
+    if (sel.mode === "full") {
+        console.log(`▶ FULL suite (${total} tests): ${sel.fullReason}`);
+        if (sel.unattributed.length)
+            console.log(`  unattributed: ${sel.unattributed.join(", ")}`);
+        // Only trusted map entries narrow spawning tests; triggers, non-code and unattributed changes stay FULL.
+        const spawnWide = /^selection too broad/.test(sel.fullReason ?? "") && Object.values(sel.reasons).some((r) => r.some((why) => why.includes("whole program")));
+        if (!hasMap && spawnWide)
+            console.log("  Run `hunch verify --refresh-map` once to enable narrow selection for CLI/MCP tests.");
+        return;
+    }
+    console.log(`▶ ${sel.tests.length} of ${total} tests selected:`);
+    for (const test of sel.tests)
+        console.log(`  ${test}  ← ${sel.reasons[test].join("; ")}`);
+}
+function headSha(root) {
+    try {
+        return execFileSync("git", ["rev-parse", "HEAD"], { cwd: root, encoding: "utf8", windowsHide: true, stdio: ["ignore", "pipe", "pipe"] }).trim();
+    }
+    catch {
+        return "";
+    }
+}
+function readCoverageDir(dir) {
+    if (!existsSync(dir))
+        return [];
+    const reports = [];
+    for (const name of readdirSync(dir)) {
+        if (!name.endsWith(".json"))
+            continue;
+        try {
+            reports.push(JSON.parse(readFileSync(join(dir, name), "utf8")));
+        }
+        catch { /* partial write → skip */ }
+    }
+    return reports;
+}
+/** Run each test in its own runner process under NODE_V8_COVERAGE (inherited
+ *  by spawned CLI/MCP children) and record the repo files each executed. An
+ *  entry is `complete` only when the test file passed and produced coverage;
+ *  failing tests still record their (partial) files. `only` merges into the
+ *  old map, keeping each untouched entry's own commit stamp. */
+export async function refreshImpactMap(opts) {
+    const { root, mapPath } = opts;
+    const log = opts.log ?? console.log;
+    const run = opts.only?.length ? opts.only.map((t) => t.replace(/\\/g, "/").replace(/^\.\//, "")) : opts.tests;
+    let previous = null;
+    if (opts.only?.length) {
+        try {
+            previous = loadImpactMap(mapPath);
+        }
+        catch {
+            previous = null;
+        }
+    }
+    const repoFiles = new Set(opts.files);
+    const commit = headSha(root);
+    const { closureHash } = testDependencyModel(root, opts.files, buildImportGraph(root, opts.files));
+    const covDir = mkdtempSync(join(tmpdir(), "hunch-verify-cov-"));
+    const map = { ...(previous?.map ?? {}) };
+    const failed = [];
+    const width = Math.max(1, opts.concurrency ?? availableParallelism() - 1);
+    const env = { ...process.env };
+    delete env.NODE_TEST_CONTEXT; // a parent test runner must not turn the child into a reporter
+    let next = 0;
+    const worker = async () => {
+        while (next < run.length) {
+            const index = next++;
+            const test = run[index];
+            const dir = join(covDir, String(index));
+            const argv = runnerArgv(root, opts.template, [test], [], false);
+            const status = await new Promise((done) => {
+                const child = spawn(argv[0], argv.slice(1), { cwd: root, stdio: "ignore", windowsHide: true, env: { ...env, NODE_V8_COVERAGE: dir } });
+                child.on("error", () => done(1));
+                child.on("close", (code) => done(code ?? 1));
+            });
+            const reports = readCoverageDir(dir);
+            if (status !== 0)
+                failed.push(test);
+            const files = coverageFiles(reports, root, repoFiles).filter((f) => f !== test);
+            map[test] = { files, complete: status === 0 && reports.length > 0, commit, closureHash };
+            log(`  ${status === 0 ? "✓" : "✗"} ${test}  (${files.length} files)`);
+        }
+    };
+    try {
+        await Promise.all(Array.from({ length: Math.min(width, run.length) }, worker));
+    }
+    finally {
+        // Coverage is scratch; a straggling child holding a handle must not fail the refresh.
+        try {
+            rmSync(covDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 });
+        }
+        catch { /* best effort */ }
+    }
+    const sortedMap = {};
+    for (const test of Object.keys(map).sort())
+        sortedMap[test] = map[test];
+    const result = { version: 2, commit, generatedAt: new Date().toISOString(), closureHash, map: sortedMap };
+    mkdirSync(dirname(mapPath), { recursive: true });
+    writeFileAtomic(mapPath, JSON.stringify(result, null, 2) + "\n");
+    return { map: result, failed: failed.sort() };
+}
+export function registerVerifyCommand(program) {
+    program
+        .command("verify")
+        .description("Run only the tests the current change can affect (fail-closed: anything unattributed runs the full suite).")
+        .argument("[runnerArgs...]", "extra arguments for the test runner (after --)")
+        .option("--staged", "select from staged changes only")
+        .option("--base <ref>", "select from merge-base(<ref>, HEAD)..HEAD plus the working tree")
+        .option("--list", "print the selection with reasons; run nothing")
+        .option("--full", "run the full suite")
+        .option("--ci", "run the full suite (CI)")
+        .option("--json", "print the selection as JSON; run nothing")
+        .option("--map <path>", `test impact map (default ${DEFAULT_IMPACT_MAP})`)
+        .option("--refresh-map", "rebuild the impact map: run each test under V8 coverage")
+        .option("--only <tests...>", "with --refresh-map: refresh only these tests, merging into the existing map")
+        .action(async (runnerArgs, opts) => {
+        let root;
+        try {
+            root = execFileSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8", windowsHide: true, stdio: ["ignore", "pipe", "pipe"] }).trim();
+        }
+        catch {
+            console.error("hunch verify must run inside a git repository");
+            process.exitCode = 1;
+            return;
+        }
+        const config = readConfig(hunchPaths(root)).verify ?? {};
+        const files = listRepoFiles(root);
+        const allTests = discoverTests(files, typeof config.tests === "string" ? config.tests : undefined);
+        const template = typeof config.command === "string" ? config.command : undefined;
+        const mapPath = opts.map ? (isAbsolute(opts.map) ? opts.map : join(root, opts.map)) : join(root, DEFAULT_IMPACT_MAP);
+        if (opts.refreshMap) {
+            const total = opts.only?.length ?? allTests.length;
+            console.log(`▶ refreshing impact map: ${total} test file(s) under V8 coverage`);
+            const { map, failed } = await refreshImpactMap({ root, tests: allTests, files, template, mapPath, only: opts.only });
+            const covered = new Set(Object.values(map.map).flatMap((e) => e.files)).size;
+            console.log(`✓ wrote ${opts.map ?? DEFAULT_IMPACT_MAP}: ${Object.keys(map.map).length} tests → ${covered} files @ ${map.commit.slice(0, 12) || "(no HEAD)"}`);
+            if (failed.length)
+                console.log(`  ${failed.length} test file(s) failed (partial coverage recorded, not trusted): ${failed.join(", ")}`);
+            return;
+        }
+        const note = [];
+        let sel;
+        let hasMap = false;
+        if (opts.full || opts.ci) {
+            sel = { mode: "full", tests: allTests, reasons: {}, fullReason: opts.ci ? "--ci" : "--full", unattributed: [], mapUsed: [] };
+        }
+        else {
+            const mode = opts.base ? { kind: "base", ref: opts.base } : opts.staged ? { kind: "staged" } : { kind: "worktree" };
+            let impactMap;
+            try {
+                impactMap = loadImpactMap(mapPath) ?? undefined;
+            }
+            catch (e) {
+                note.push(`${e.message}; ignoring it`);
+            }
+            if (!impactMap && !note.length)
+                note.push(`no impact map at ${opts.map ?? DEFAULT_IMPACT_MAP}; using the import graph (build one: hunch verify --refresh-map)`);
+            const model = testDependencyModel(root, files, buildImportGraph(root, files));
+            // The map itself is a derived cache; a not-yet-ignored copy is never a code change.
+            const mapRel = relative(root, mapPath).replace(/\\/g, "/");
+            const changed = changedFiles(root, mode).filter((f) => f !== mapRel);
+            sel = selectTests({
+                changedFiles: changed, allTests, impactMap, importGraph: model.dependencies,
+                testText: model.testText, spawning: model.spawning, closureHash: model.closureHash,
+                wholeProgram: [...model.wholeProgram, ...changed.filter((f) => f.startsWith("src/"))], testNamers: model.testNamers,
+            });
+            hasMap = !!impactMap;
+            if (impactMap) {
+                const head = headSha(root);
+                const stale = sel.mapUsed.filter((t) => impactMap.map[t].commit !== head);
+                if (stale.length)
+                    note.push(`${stale.length} impact-map entr${stale.length === 1 ? "y" : "ies"} used were recorded at another commit than HEAD ${head.slice(0, 12)} (${stale.join(", ")}); the map only adds tests`);
+                if (Object.values(impactMap.map).some((e) => e.closureHash !== model.closureHash)) {
+                    note.push("CLI/MCP/tooling import closure changed since some entries were recorded; those spawning tests use the whole program");
+                }
+            }
+        }
+        if (opts.json) {
+            console.log(JSON.stringify({ ...sel, total: allTests.length }, null, 2));
+            return;
+        }
+        printSelection(sel, allTests.length, note, hasMap);
+        if (opts.list || sel.mode === "none")
+            return;
+        let argv;
+        try {
+            argv = runnerArgv(root, template, sel.tests, runnerArgs, sel.mode === "full");
+        }
+        catch (e) {
+            console.error(e.message);
+            process.exitCode = 1;
+            return;
+        }
+        console.log(`▶ running: ${display(argv)}\n`);
+        const run = spawnSync(argv[0], argv.slice(1), { cwd: root, stdio: "inherit", windowsHide: true });
+        if (run.error) {
+            console.error(run.error.message);
+            process.exitCode = 1;
+            return;
+        }
+        process.exitCode = run.status ?? 1;
+    });
+}
+//# sourceMappingURL=verify.js.map

package/dist/constitution/experiment.d.ts

@@ -237,8 +237,8 @@ export declare const ExperimentOutcomeSchema: z.ZodObject<{
         decision: z.ZodEnum<{
             rejected: "rejected";
             abandoned: "abandoned";
-            uncompilable: "uncompilable";
             timeout: "timeout";
+            uncompilable: "uncompilable";
             cannot_decide: "cannot_decide";
             accepted_precise: "accepted_precise";
             accepted_edited: "accepted_edited";

package/dist/core/agenthook.d.ts

@@ -8,6 +8,7 @@
 export declare const HOOK_PROVIDERS: readonly ["claude", "codex", "vscode", "windsurf", "antigravity", "cursor"];
 export type HookProvider = (typeof HOOK_PROVIDERS)[number];
 export declare function deliversPromptEvent(provider: HookProvider): boolean;
+export declare function deliversCommandOutcome(provider: HookProvider): boolean;
 export type HunchHookEvent = "PreToolUse" | "PostToolUse" | "PostToolUseFailure" | "UserPromptSubmit" | "SessionStart" | "SubagentStart" | "PreCompact" | "Stop";
 /** One file section of a Codex `apply_patch` payload. */
 export interface HunchPatchFile {

package/dist/core/agenthook.js

@@ -17,6 +17,18 @@ const PROMPT_EVENT = {
 export function deliversPromptEvent(provider) {
     return PROMPT_EVENT[provider];
 }
+/** Whether a provider's post-command hook carries the command's result (exit
+ * status or an explicit success/failure). Windsurf's post_run_command sends only
+ * the command line and cwd; Antigravity's installed hooks (PreInvocation,
+ * PreToolUse on edit tools, Stop) include no post-tool event at all. Evidence
+ * gates keyed on a command's result can never be satisfied there and must stay
+ * advisory. A Record, so a new provider must declare its answer. */
+const COMMAND_OUTCOME = {
+    claude: true, codex: true, vscode: true, windsurf: false, cursor: true, antigravity: false,
+};
+export function deliversCommandOutcome(provider) {
+    return COMMAND_OUTCOME[provider];
+}
 function obj(value) {
     return value && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
@@ -197,16 +209,32 @@ function explicitToolOutcome(response) {
         return "success";
     return "unknown";
 }
-function normalizeToolOutcome(input, event) {
+/** Cursor's postToolUse carries `tool_output` as a JSON-stringified result
+ * payload, e.g. `{"exitCode":0,"stdout":"..."}` (cursor.com/docs/agent/hooks, #496).
+ * Parsed, its exit code reaches the probe gate; text that is not a JSON object
+ * stays a bare string, which carries no status. */
+function cursorToolOutput(value) {
+    if (typeof value !== "string")
+        return value;
+    try {
+        const parsed = JSON.parse(value);
+        return obj(parsed) ?? value;
+    }
+    catch {
+        return value;
+    }
+}
+function normalizeToolOutcome(input, event, provider) {
     if (event !== "PostToolUse" && event !== "PostToolUseFailure")
         return undefined;
-    const response = input.tool_response ?? input.toolResponse ?? input.tool_result ?? input.toolResult;
+    const response = input.tool_response ?? input.toolResponse ?? input.tool_result ?? input.toolResult
+        ?? (provider === "cursor" ? cursorToolOutput(input.tool_output) ?? input.output : undefined);
     return {
         // Claude Code splits successful and failed calls into separate lifecycle
         // events. Providers without that split may expose an explicit result flag.
         status: event === "PostToolUseFailure" ? "failure" : explicitToolOutcome(response),
         output: event === "PostToolUseFailure"
-            ? toolOutput(input.error ?? response)
+            ? toolOutput(input.error ?? (provider === "cursor" ? input.error_message : undefined) ?? response)
             : toolOutput(response),
     };
 }
@@ -235,12 +263,11 @@ function eventName(value, provider) {
             return "PostToolUse";
     }
     if (provider === "windsurf") {
-        if (name === "pre_write_code" || name === "pre_run_command")
-            return "PreToolUse";
-        if (name === "post_write_code" || name === "post_run_command")
-            return "PostToolUse";
         if (name === "pre_user_prompt")
             return "UserPromptSubmit";
+        const action = /^(pre|post)_(write_code|run_command|read_code|mcp_tool_use)$/.exec(name);
+        if (action)
+            return action[1] === "pre" ? "PreToolUse" : "PostToolUse";
     }
     // Antigravity's PreInvocation is the lifecycle point which can inject a
     // transient message before the model sees the turn. Internally it provides
@@ -256,6 +283,45 @@ export function hookProvider(value) {
         ? value.toLowerCase()
         : null;
 }
+/** Windsurf Cascade (docs.windsurf.com/windsurf/cascade/hooks) names the event in
+ * top-level `agent_action_name` (`pre_write_code`, `post_run_command`, …) and
+ * carries per-event data in `tool_info`. The tool is implied by the event. Payloads
+ * written before #484 (`event` + `agent_action_name: "write_code"`) still parse. */
+function normalizeWindsurfEvent(input) {
+    const action = stringAt(input, "agent_action_name")?.toLowerCase();
+    const legacy = typeof input.event === "string" ? input.event : typeof input.hook_event_name === "string" ? input.hook_event_name : undefined;
+    const name = eventName(action, "windsurf") ? action : legacy?.toLowerCase();
+    const event = eventName(name, "windsurf");
+    if (!name || !event)
+        return null;
+    const info = obj(input.tool_info) ?? obj(input.toolInput) ?? obj(input.tool_input) ?? {};
+    const kind = name.replace(/^(?:pre|post)_/, "");
+    const base = {
+        hook_event_name: event,
+        session_id: stringAt(input, "trajectory_id", "session_id", "sessionId"),
+    };
+    if (event === "UserPromptSubmit") {
+        return { ...base, prompt: stringAt(info, "user_prompt", "prompt") ?? stringAt(input, "prompt", "user_prompt", "userPrompt") };
+    }
+    const toolOutcome = normalizeToolOutcome(input, event);
+    const outcome = toolOutcome ? { tool_outcome: toolOutcome } : {};
+    if (kind === "run_command") {
+        const command = stringAt(info, "command_line", "command", "commandLine");
+        const cwd = stringAt(info, "cwd");
+        return { ...base, ...(cwd ? { cwd } : {}), tool_name: "Bash", tool_input: command ? { command } : undefined, ...outcome };
+    }
+    // Reads and MCP calls are observed only: their arguments never reach the
+    // pre-edit gate, which treats any file_path as an edit target.
+    if (kind === "read_code")
+        return { ...base, tool_name: "Read", ...outcome };
+    if (kind === "mcp_tool_use") {
+        const server = stringAt(info, "mcp_server_name", "server_name", "server");
+        const tool = stringAt(info, "mcp_tool_name", "tool_name", "tool");
+        return { ...base, tool_name: server && tool ? `mcp__${server}__${tool}` : tool ?? "mcp", ...outcome };
+    }
+    const toolInput = normalizeToolInput(info);
+    return { ...base, tool_name: kind === "write_code" ? "Edit" : hunchToolName(stringAt(input, "tool_name", "toolName"), toolInput ?? {}), tool_input: toolInput, ...outcome };
+}
 /** Normalize a hook stdin payload. Unknown/malformed events return null and the
  * CLI exits successfully without output — the Never Block on Hook Failure rule. */
 export function normalizeHookEvent(raw, provider) {
@@ -276,28 +342,18 @@ export function normalizeHookEvent(raw, provider) {
             tool_input: toolInput,
         };
     }
-    if (provider === "windsurf") {
-        const event = eventName(input.event ?? input.hook_event_name, provider);
-        if (!event)
-            return null;
-        const info = obj(input.tool_info) ?? obj(input.toolInput) ?? obj(input.tool_input);
-        const toolInput = normalizeToolInput(info);
-        const toolOutcome = normalizeToolOutcome(input, event);
-        return {
-            hook_event_name: event,
-            session_id: stringAt(input, "trajectory_id", "session_id", "sessionId"),
-            tool_name: hunchToolName(stringAt(input, "agent_action_name", "tool_name", "toolName"), toolInput ?? {}),
-            tool_input: toolInput,
-            ...(toolOutcome ? { tool_outcome: toolOutcome } : {}),
-            prompt: stringAt(input, "prompt", "user_prompt", "userPrompt"),
-        };
-    }
+    if (provider === "windsurf")
+        return normalizeWindsurfEvent(input);
     const event = eventName(input.hook_event_name ?? input.hookEventName ?? input.event, provider);
     if (!event)
         return null;
-    const rawToolName = stringAt(input, "tool_name", "toolName");
-    const toolInput = normalizeToolInput(input.tool_input ?? input.toolInput, provider === "codex" && /^(?:apply_patch|patch)$/i.test(rawToolName ?? ""));
-    const toolOutcome = normalizeToolOutcome(input, event);
+    // Cursor's before/afterShellExecution carry the command at top level and no
+    // tool name. afterShellExecution has no exit status (only `output`), so its
+    // outcome stays unknown; the installed postToolUse hook delivers the status.
+    const cursorShell = provider === "cursor" && input.tool_name === undefined && input.tool_input === undefined && typeof input.command === "string";
+    const rawToolName = cursorShell ? "Shell" : stringAt(input, "tool_name", "toolName");
+    const toolInput = normalizeToolInput(cursorShell ? { command: input.command } : input.tool_input ?? input.toolInput, provider === "codex" && /^(?:apply_patch|patch)$/i.test(rawToolName ?? ""));
+    const toolOutcome = normalizeToolOutcome(input, event, provider);
     return {
         hook_event_name: event,
         session_id: stringAt(input, "session_id", "sessionId", "conversation_id", "conversationId"),

package/dist/core/boundedSpawn.d.ts

@@ -0,0 +1,57 @@
+export interface BoundedSpawnOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    /** Written to the child's stdin, which is then closed. Omitted = no stdin. */
+    input?: string;
+    /** Supervisor deadline. Omitted or 0 = no deadline. */
+    timeoutMs?: number;
+    /** stdout bytes allowed before the tree is killed. Default 16 MB. */
+    maxBuffer?: number;
+    /** Launch through the platform shell (cmd.exe on Windows). `file` is then
+     *  the whole command line and `args` should be empty. */
+    shell?: boolean;
+    /** POSIX: how long the tree gets after SIGTERM before SIGKILL. Default 1500. */
+    killGraceMs?: number;
+}
+export interface BoundedSpawnResult {
+    stdout: string;
+    stderr: string;
+    /** Exit status, or null when the child was killed or never started. */
+    status: number | null;
+    /** Signal that ended the child: its own exit signal, or on timeout/overflow
+     *  the last signal the supervisor delivered to the tree. */
+    signal: NodeJS.Signals | null;
+    /** The supervisor's deadline fired and the process tree was killed. */
+    timedOut: boolean;
+    /** stdout exceeded maxBuffer and the process tree was killed. */
+    overflowed: boolean;
+    /** Spawn failure (e.g. ENOENT), or the supervisor itself failing. */
+    error?: NodeJS.ErrnoException;
+}
+/** Test seam: replace the ps binary used for the POSIX tree snapshot
+ *  (null restores "ps"). Not for production callers. */
+export declare function __setPsFileForTests(file: string | null): void;
+/** Async bounded run. Always resolves; inspect `timedOut` / `error` / `status`. */
+export declare function boundedSpawn(file: string, args: string[], opts?: BoundedSpawnOptions): Promise<BoundedSpawnResult>;
+export interface BoundedSpawnSyncOptions extends Omit<BoundedSpawnOptions, "timeoutMs"> {
+    /** Supervisor deadline (required: this helper exists to bound the call). */
+    timeout: number;
+    /** stdout: captured ("pipe", the default), discarded, or written straight to
+     *  an open file descriptor. */
+    stdout?: "pipe" | "ignore" | number;
+}
+/** Synchronous bounded run, spawnSync-shaped: never throws. */
+export declare function boundedSpawnSync(file: string, args: string[], opts: BoundedSpawnSyncOptions): BoundedSpawnResult;
+/** Error thrown by boundedExecFileSync, shaped like execFileSync's: `code`
+ *  ETIMEDOUT / ENOBUFS / ENOENT, or `status` + `signal` for a failed exit. */
+export interface BoundedExecError extends Error {
+    code?: string;
+    status?: number | null;
+    signal?: NodeJS.Signals | null;
+    stdout: string;
+    stderr: string;
+}
+/** Synchronous bounded exec: returns stdout (utf8) on exit 0, throws a
+ *  BoundedExecError otherwise. On timeout the error carries
+ *  `code: "ETIMEDOUT"` and the signal actually delivered to the tree. */
+export declare function boundedExecFileSync(file: string, args: string[], opts: BoundedSpawnSyncOptions): string;