/**
 * ProcessSandbox — Story 15.1 (v1.5, research-track).
 *
 * Thin wrapper around `child_process.spawn` that injects Node's
 * experimental `--permission` flag plus the per-capability `--allow-*`
 * flags so a child node process runs inside a kernel-style sandbox.
 *
 * **Not wired anywhere yet** — see `docs/sandboxing-research.md` for the
 * decision matrix. v1.5 ships this class so v1.6 can opt-in selectively
 * (doctor script first, then TaskExecutor.runShellCommand).
 *
 * Graceful version downgrade:
 *   • Node 20+ → injects `--permission` + the requested allow-list.
 *   • Node 18  → spawns plain (no enforcement) and stamps
 *     `result.enforced=false` so the caller can detect the downgrade.
 *
 * The wrapper does NOT execute anything by default. Callers must opt in
 * by calling `.spawn(cmd, args, opts)`. There is no global side effect
 * just by importing this module — keeping with OpenLife's lazy-import
 * contract in src/index.ts.
 */
import * as child_process from 'child_process';
export interface ProcessSandboxOptions {
    /** Allowed filesystem read scopes. Each entry maps to `--allow-fs-read=<path>`. */
    allowFsRead?: string[];
    /** Allowed filesystem write scopes. Each entry maps to `--allow-fs-write=<path>`. */
    allowFsWrite?: string[];
    /** When false (default), `--allow-child-process` is NOT added. */
    allowChildProcess?: boolean;
    /** When false (default), `--allow-worker` is NOT added. */
    allowWorker?: boolean;
    /** When false (default), `--allow-wasi` is NOT added. */
    allowWasi?: boolean;
    /** When false (default), `--allow-addons` is NOT added. */
    allowAddons?: boolean;
    /** Override Node major version detection (test seam). */
    nodeMajor?: number;
    /** Override the spawn implementation (test seam). */
    spawnImpl?: typeof child_process.spawn;
}
export interface ProcessSandboxResult {
    code: number | null;
    signal: NodeJS.Signals | null;
    enforced: boolean;
    appliedFlags: string[];
    stdout: string;
    stderr: string;
}
export declare class ProcessSandbox {
    private readonly opts;
    private readonly nodeMajor;
    private readonly spawnImpl;
    constructor(opts?: ProcessSandboxOptions);
    /** True when the running Node version supports the `--permission` flag. */
    supportsEnforcement(): boolean;
    /**
     * Build the flag list that `spawn` would prepend. Public for testability —
     * the unit tests inspect this without spawning anything.
     */
    buildPermissionFlags(): string[];
    /**
     * Spawn `command` with `args`. When `command` is `node` (or absolute
     * path ending in `/node`), the permission flags are inserted before
     * the user's argv. Other commands are spawned plain — the wrapper is
     * a no-op for non-node binaries, since Node's permission model only
     * applies to spawning Node itself.
     *
     * The promise resolves with a result envelope; it never rejects.
     * stdout/stderr are captured up to a generous default buffer.
     */
    spawn(command: string, args?: string[], spawnOpts?: child_process.SpawnOptions): Promise<ProcessSandboxResult>;
    private detectNodeMajor;
}
