profclaw 2.0.0 → 2.4.0

package/dist/agents/checkpoint-manager.js

@@ -0,0 +1,156 @@
+/**
+ * Checkpoint Manager
+ *
+ * Saves and restores executor state so long-running agentic sessions can be
+ * interrupted and resumed without losing progress.  Checkpoints live at
+ * .profclaw/checkpoints/<sessionId>.json relative to the project root (or the
+ * current working directory when no root is supplied).
+ */
+import { mkdir, readFile, writeFile, unlink, readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { logger } from '../utils/logger.js';
+// ─── CheckpointManager ────────────────────────────────────────────────────────
+export class CheckpointManager {
+    checkpointsDir;
+    constructor(projectRoot) {
+        const root = projectRoot ? resolve(projectRoot) : process.cwd();
+        this.checkpointsDir = join(root, '.profclaw', 'checkpoints');
+    }
+    // ── Private helpers ──────────────────────────────────────────────────────
+    filePath(sessionId) {
+        return join(this.checkpointsDir, `${sessionId}.json`);
+    }
+    async ensureDir() {
+        if (!existsSync(this.checkpointsDir)) {
+            await mkdir(this.checkpointsDir, { recursive: true });
+        }
+    }
+    // ── Public API ───────────────────────────────────────────────────────────
+    /**
+     * Persist a checkpoint to disk.  Creates .profclaw/checkpoints/ if needed.
+     */
+    async save(checkpoint) {
+        await this.ensureDir();
+        const path = this.filePath(checkpoint.sessionId);
+        const payload = JSON.stringify({ ...checkpoint, updatedAt: Date.now() }, null, 2);
+        await writeFile(path, payload, 'utf-8');
+        logger.debug('[CheckpointManager] Saved checkpoint', {
+            sessionId: checkpoint.sessionId,
+            step: checkpoint.currentStep,
+            path,
+        });
+    }
+    /**
+     * Load a previously saved checkpoint.  Returns null when none exists.
+     */
+    async load(sessionId) {
+        const path = this.filePath(sessionId);
+        try {
+            const raw = await readFile(path, 'utf-8');
+            const parsed = JSON.parse(raw);
+            logger.debug('[CheckpointManager] Loaded checkpoint', {
+                sessionId,
+                step: parsed.currentStep,
+            });
+            return parsed;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * List all checkpoints, sorted newest first.
+     */
+    async list() {
+        if (!existsSync(this.checkpointsDir))
+            return [];
+        let files;
+        try {
+            files = await readdir(this.checkpointsDir);
+        }
+        catch {
+            return [];
+        }
+        const summaries = [];
+        for (const file of files) {
+            if (!file.endsWith('.json'))
+                continue;
+            try {
+                const raw = await readFile(join(this.checkpointsDir, file), 'utf-8');
+                const cp = JSON.parse(raw);
+                summaries.push({
+                    sessionId: cp.sessionId,
+                    taskDescription: cp.taskDescription,
+                    step: cp.currentStep,
+                    updatedAt: cp.updatedAt,
+                });
+            }
+            catch {
+                // Skip malformed files
+            }
+        }
+        return summaries.sort((a, b) => b.updatedAt - a.updatedAt);
+    }
+    /**
+     * Delete a checkpoint after the session has completed successfully.
+     */
+    async remove(sessionId) {
+        const path = this.filePath(sessionId);
+        try {
+            await unlink(path);
+            logger.debug('[CheckpointManager] Removed checkpoint', { sessionId });
+        }
+        catch {
+            // Already gone — not an error
+        }
+    }
+    /**
+     * Find a resumable checkpoint whose taskDescription loosely matches the
+     * given description (case-insensitive substring + word overlap heuristic).
+     * Returns the most recently updated match, or null if nothing qualifies.
+     */
+    async findResumable(taskDescription) {
+        const all = await this.list();
+        if (all.length === 0)
+            return null;
+        const needle = taskDescription.toLowerCase();
+        const needleWords = new Set(needle.split(/\W+/).filter(Boolean));
+        let bestScore = 0;
+        let bestId = null;
+        for (const summary of all) {
+            if (!summary.taskDescription)
+                continue;
+            const hay = summary.taskDescription.toLowerCase();
+            // Substring match is a strong signal
+            if (hay.includes(needle) || needle.includes(hay)) {
+                // Prefer the most recently updated substring match
+                if (summary.updatedAt > (bestScore === 2 ? 0 : -1)) {
+                    bestScore = 2;
+                    bestId = summary.sessionId;
+                }
+                continue;
+            }
+            // Word-overlap fallback
+            const hayWords = hay.split(/\W+/).filter(Boolean);
+            const overlap = hayWords.filter((w) => needleWords.has(w)).length;
+            const ratio = needleWords.size > 0 ? overlap / needleWords.size : 0;
+            if (ratio >= 0.5 && ratio > bestScore) {
+                bestScore = ratio;
+                bestId = summary.sessionId;
+            }
+        }
+        if (!bestId)
+            return null;
+        return this.load(bestId);
+    }
+}
+// ─── Singleton ────────────────────────────────────────────────────────────────
+let _instance;
+export function getCheckpointManager(projectRoot) {
+    if (!_instance) {
+        _instance = new CheckpointManager(projectRoot);
+    }
+    return _instance;
+}
+//# sourceMappingURL=checkpoint-manager.js.map

package/dist/agents/circuit-breaker.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Tool Circuit Breaker
+ *
+ * Prevents tools from being called repeatedly when they are failing.
+ * Implements the standard circuit breaker pattern:
+ *   closed → (3 failures in 2 min) → open → (cooldown expires) → half-open
+ *   half-open → (1 success) → closed
+ *   half-open → (1 failure) → open (doubled cooldown)
+ */
+export type CircuitBreakerStateValue = 'closed' | 'open' | 'half-open';
+export interface CircuitBreakerState {
+    state: CircuitBreakerStateValue;
+    failureCount: number;
+    lastFailureAt: number;
+    cooldownMs: number;
+}
+export interface CanExecuteResult {
+    allowed: boolean;
+    reason?: string;
+}
+export declare class ToolCircuitBreaker {
+    private breakers;
+    private readonly failureThreshold;
+    private readonly windowMs;
+    constructor(failureThreshold?: number, windowMs?: number);
+    /**
+     * Check whether a tool is allowed to execute.
+     * Transitions open → half-open when the cooldown has expired.
+     */
+    canExecute(toolName: string): CanExecuteResult;
+    /**
+     * Record a successful tool execution.
+     * In half-open state this closes the circuit.
+     */
+    recordSuccess(toolName: string): void;
+    /**
+     * Record a failed tool execution.
+     * Counts failures within the time window and trips the breaker when the
+     * threshold is reached. In half-open state it immediately re-opens with
+     * a doubled cooldown.
+     */
+    recordFailure(toolName: string): void;
+    /**
+     * Reset the circuit breaker for a specific tool, or all tools if no name is given.
+     */
+    reset(toolName?: string): void;
+    /**
+     * Return a deep snapshot of all breaker states.
+     * Mutations to the live breakers do not affect the returned map.
+     */
+    getStatus(): Map<string, CircuitBreakerState>;
+    private getOrCreate;
+}
+//# sourceMappingURL=circuit-breaker.d.ts.map

package/dist/agents/circuit-breaker.js

@@ -0,0 +1,153 @@
+/**
+ * Tool Circuit Breaker
+ *
+ * Prevents tools from being called repeatedly when they are failing.
+ * Implements the standard circuit breaker pattern:
+ *   closed → (3 failures in 2 min) → open → (cooldown expires) → half-open
+ *   half-open → (1 success) → closed
+ *   half-open → (1 failure) → open (doubled cooldown)
+ */
+import { logger } from '../utils/logger.js';
+// Constants
+const DEFAULT_FAILURE_THRESHOLD = 3;
+const DEFAULT_WINDOW_MS = 120_000; // 2 minutes
+const INITIAL_COOLDOWN_MS = 5_000;
+const MAX_COOLDOWN_MS = 60_000;
+function defaultBreakerState() {
+    return {
+        state: 'closed',
+        failureCount: 0,
+        lastFailureAt: 0,
+        cooldownMs: INITIAL_COOLDOWN_MS,
+    };
+}
+// Circuit Breaker
+export class ToolCircuitBreaker {
+    breakers;
+    failureThreshold;
+    windowMs;
+    constructor(failureThreshold = DEFAULT_FAILURE_THRESHOLD, windowMs = DEFAULT_WINDOW_MS) {
+        this.breakers = new Map();
+        this.failureThreshold = failureThreshold;
+        this.windowMs = windowMs;
+    }
+    /**
+     * Check whether a tool is allowed to execute.
+     * Transitions open → half-open when the cooldown has expired.
+     */
+    canExecute(toolName) {
+        const breaker = this.getOrCreate(toolName);
+        const now = Date.now();
+        if (breaker.state === 'closed') {
+            return { allowed: true };
+        }
+        if (breaker.state === 'open') {
+            const elapsed = now - breaker.lastFailureAt;
+            if (elapsed >= breaker.cooldownMs) {
+                // Transition to half-open to allow a probe call
+                breaker.state = 'half-open';
+                logger.debug('[CircuitBreaker] Transitioning to half-open', {
+                    tool: toolName,
+                    elapsed,
+                    cooldownMs: breaker.cooldownMs,
+                });
+                return { allowed: true };
+            }
+            const remainingMs = breaker.cooldownMs - elapsed;
+            return {
+                allowed: false,
+                reason: `Circuit breaker open for ${toolName}: too many recent failures. Retry in ${Math.ceil(remainingMs / 1000)}s.`,
+            };
+        }
+        // half-open: allow one probe through
+        return { allowed: true };
+    }
+    /**
+     * Record a successful tool execution.
+     * In half-open state this closes the circuit.
+     */
+    recordSuccess(toolName) {
+        const breaker = this.getOrCreate(toolName);
+        if (breaker.state === 'half-open') {
+            logger.info('[CircuitBreaker] Probe succeeded, closing circuit', { tool: toolName });
+            breaker.state = 'closed';
+            breaker.failureCount = 0;
+            breaker.cooldownMs = INITIAL_COOLDOWN_MS;
+        }
+        else if (breaker.state === 'closed') {
+            // Reset failure count on success within the window
+            breaker.failureCount = 0;
+        }
+    }
+    /**
+     * Record a failed tool execution.
+     * Counts failures within the time window and trips the breaker when the
+     * threshold is reached. In half-open state it immediately re-opens with
+     * a doubled cooldown.
+     */
+    recordFailure(toolName) {
+        const breaker = this.getOrCreate(toolName);
+        const now = Date.now();
+        if (breaker.state === 'half-open') {
+            // Probe failed — re-open with doubled cooldown
+            breaker.cooldownMs = Math.min(breaker.cooldownMs * 2, MAX_COOLDOWN_MS);
+            breaker.state = 'open';
+            breaker.lastFailureAt = now;
+            logger.warn('[CircuitBreaker] Probe failed, re-opening circuit', {
+                tool: toolName,
+                cooldownMs: breaker.cooldownMs,
+            });
+            return;
+        }
+        // In closed state, check if previous failures are still within the window
+        const withinWindow = breaker.lastFailureAt > 0 && now - breaker.lastFailureAt <= this.windowMs;
+        if (withinWindow) {
+            breaker.failureCount++;
+        }
+        else {
+            // Failures outside the window don't count; start a fresh count
+            breaker.failureCount = 1;
+        }
+        breaker.lastFailureAt = now;
+        if (breaker.failureCount >= this.failureThreshold) {
+            breaker.state = 'open';
+            logger.warn('[CircuitBreaker] Threshold reached, opening circuit', {
+                tool: toolName,
+                failureCount: breaker.failureCount,
+                cooldownMs: breaker.cooldownMs,
+            });
+        }
+    }
+    /**
+     * Reset the circuit breaker for a specific tool, or all tools if no name is given.
+     */
+    reset(toolName) {
+        if (toolName !== undefined) {
+            this.breakers.set(toolName, defaultBreakerState());
+        }
+        else {
+            this.breakers.clear();
+        }
+    }
+    /**
+     * Return a deep snapshot of all breaker states.
+     * Mutations to the live breakers do not affect the returned map.
+     */
+    getStatus() {
+        const snapshot = new Map();
+        for (const [key, value] of this.breakers) {
+            snapshot.set(key, { ...value });
+        }
+        return snapshot;
+    }
+    // Private helpers
+    getOrCreate(toolName) {
+        let breaker = this.breakers.get(toolName);
+        if (!breaker) {
+            breaker = defaultBreakerState();
+            this.breakers.set(toolName, breaker);
+        }
+        return breaker;
+    }
+}
+//# sourceMappingURL=circuit-breaker.js.map

package/dist/agents/command-sandbox.d.ts

@@ -0,0 +1,93 @@
+/**
+ * OS-level confinement for shell commands run by `profclaw run`.
+ *
+ * Wraps a command so the kernel, not pattern matching, enforces the limits:
+ *  - writes only inside the worktree, a per-run temp dir, the git metadata the
+ *    worktree needs and a few device nodes (plus opt-in extras)
+ *  - reads are broad (node, pnpm, git and tsc need many system paths) but
+ *    credential directories such as ~/.ssh and ~/.aws are denied
+ *  - network is denied unless PROFCLAW_RUN_ALLOW_NETWORK is set
+ *
+ * Backends: macOS Seatbelt (`/usr/bin/sandbox-exec`) and Linux `bwrap`.
+ * Modes (PROFCLAW_RUN_SANDBOX): `auto` uses a sandbox when available and
+ * otherwise falls back to pattern screening with a one-time warning, `on`
+ * fails closed, `off` disables.
+ *
+ * Known limits: a writable git dir can be used to plant state outside the
+ * worktree (hooks and config are denied, other refs are not), and a sandboxed
+ * process can still read anything not in the deny list.
+ */
+export type SandboxMode = 'auto' | 'on' | 'off';
+export type SandboxBackend = 'seatbelt' | 'bwrap' | 'none';
+export interface SandboxAvailability {
+    backend: SandboxBackend;
+    /** Absolute path of the sandbox binary */
+    binary: string;
+}
+export interface SandboxOptions {
+    workdir: string;
+    /** Per-run scratch directory that is writable */
+    tempDir: string;
+    /** Home directory whose credential dirs are denied (default: os.homedir()) */
+    home?: string;
+    allowNetwork?: boolean;
+    /** Extra writable paths (e.g. the git dir of a linked worktree) */
+    extraWritable?: string[];
+    /** Paths inside an extraWritable tree that stay read-only (e.g. hooks) */
+    extraReadOnly?: string[];
+    /** Extra paths whose reads are denied */
+    extraDenyRead?: string[];
+}
+export interface SandboxPlan {
+    backend: SandboxBackend;
+    file: string;
+    args: string[];
+    /** Environment overrides the caller must merge in (TMPDIR) */
+    env: Record<string, string>;
+}
+export type DetectFn = () => SandboxAvailability;
+/** Home-relative locations holding credentials. Reads are denied. */
+export declare const SENSITIVE_HOME_PATHS: string[];
+/** Absolute credential locations outside of HOME. */
+export declare const SENSITIVE_ABSOLUTE_PATHS: string[];
+export declare function resolveSandboxMode(env?: NodeJS.ProcessEnv): SandboxMode;
+export declare function resolveAllowNetwork(env?: NodeJS.ProcessEnv): boolean;
+/** Extra writable paths from PROFCLAW_RUN_SANDBOX_WRITABLE (path-delimiter separated). */
+export declare function resolveExtraWritable(env?: NodeJS.ProcessEnv): string[];
+/** Resolve symlinks (Seatbelt matches real paths, e.g. /tmp is /private/tmp). */
+export declare function canonicalPath(path: string): string;
+/**
+ * Quote a path as an SBPL string literal. Backslash and double quote are
+ * escaped; control characters cannot be represented safely and are rejected,
+ * so a crafted path can never terminate the literal and inject rules.
+ */
+export declare function escapeSeatbeltString(value: string): string;
+/**
+ * Build the Seatbelt profile. SBPL applies the last matching rule, so the
+ * broad allow comes first and the specific denies and re-allows follow.
+ */
+export declare function buildSeatbeltProfile(options: SandboxOptions): string;
+export declare function buildBwrapArgs(options: SandboxOptions): string[];
+/**
+ * Detect a working sandbox. A probe run confirms it functions, since
+ * sandbox-exec fails when already inside a sandbox and bwrap can be blocked
+ * by unprivileged user namespace policy.
+ */
+export declare function detectSandbox(): SandboxAvailability;
+/** Test hook: allow the one-time warning to fire again. */
+export declare function resetSandboxWarning(): void;
+/** One-line description for CLI output. */
+export declare function describeSandbox(mode: SandboxMode, detect?: DetectFn, allowNetwork?: boolean): string;
+export interface PlanOptions {
+    mode?: SandboxMode;
+    detect?: DetectFn;
+    /** Receives the one-time fallback warning (default: stderr) */
+    warn?: (message: string) => void;
+    shell?: string;
+}
+/**
+ * Turn a shell command into the process to spawn. Throws in `on` mode when no
+ * sandbox is available. In `auto` mode falls back to the plain shell and warns once.
+ */
+export declare function planSandboxedCommand(command: string, options: SandboxOptions, plan?: PlanOptions): SandboxPlan;
+//# sourceMappingURL=command-sandbox.d.ts.map

package/dist/agents/command-sandbox.js

@@ -0,0 +1,235 @@
+/**
+ * OS-level confinement for shell commands run by `profclaw run`.
+ *
+ * Wraps a command so the kernel, not pattern matching, enforces the limits:
+ *  - writes only inside the worktree, a per-run temp dir, the git metadata the
+ *    worktree needs and a few device nodes (plus opt-in extras)
+ *  - reads are broad (node, pnpm, git and tsc need many system paths) but
+ *    credential directories such as ~/.ssh and ~/.aws are denied
+ *  - network is denied unless PROFCLAW_RUN_ALLOW_NETWORK is set
+ *
+ * Backends: macOS Seatbelt (`/usr/bin/sandbox-exec`) and Linux `bwrap`.
+ * Modes (PROFCLAW_RUN_SANDBOX): `auto` uses a sandbox when available and
+ * otherwise falls back to pattern screening with a one-time warning, `on`
+ * fails closed, `off` disables.
+ *
+ * Known limits: a writable git dir can be used to plant state outside the
+ * worktree (hooks and config are denied, other refs are not), and a sandboxed
+ * process can still read anything not in the deny list.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, realpathSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, join, resolve } from 'node:path';
+/** Home-relative locations holding credentials. Reads are denied. */
+export const SENSITIVE_HOME_PATHS = [
+    '.ssh',
+    '.aws',
+    '.config/gh',
+    '.gnupg',
+    '.netrc',
+    '.git-credentials',
+    '.kube',
+    '.azure',
+    '.config/gcloud',
+    '.docker/config.json',
+    'Library/Keychains',
+];
+/** Absolute credential locations outside of HOME. */
+export const SENSITIVE_ABSOLUTE_PATHS = ['/Library/Keychains', '/private/var/db/dslocal'];
+// Environment parsing
+export function resolveSandboxMode(env = process.env) {
+    const raw = (env.PROFCLAW_RUN_SANDBOX ?? 'auto').trim().toLowerCase();
+    if (raw === 'on' || raw === 'off' || raw === 'auto')
+        return raw;
+    if (raw === '1' || raw === 'true')
+        return 'on';
+    if (raw === '0' || raw === 'false')
+        return 'off';
+    throw new Error(`Invalid PROFCLAW_RUN_SANDBOX "${raw}" (expected auto, on or off)`);
+}
+export function resolveAllowNetwork(env = process.env) {
+    const raw = (env.PROFCLAW_RUN_ALLOW_NETWORK ?? '').trim().toLowerCase();
+    return raw === '1' || raw === 'true' || raw === 'yes';
+}
+/** Extra writable paths from PROFCLAW_RUN_SANDBOX_WRITABLE (path-delimiter separated). */
+export function resolveExtraWritable(env = process.env) {
+    return (env.PROFCLAW_RUN_SANDBOX_WRITABLE ?? '')
+        .split(delimiter)
+        .map((p) => p.trim())
+        .filter((p) => p.length > 0);
+}
+// Path handling
+/** Resolve symlinks (Seatbelt matches real paths, e.g. /tmp is /private/tmp). */
+export function canonicalPath(path) {
+    const absolute = resolve(path);
+    try {
+        return realpathSync(absolute);
+    }
+    catch {
+        return absolute;
+    }
+}
+/**
+ * Quote a path as an SBPL string literal. Backslash and double quote are
+ * escaped; control characters cannot be represented safely and are rejected,
+ * so a crafted path can never terminate the literal and inject rules.
+ */
+export function escapeSeatbeltString(value) {
+    if (/[\u0000-\u001f\u007f]/.test(value))
+        throw new Error('Path contains control characters and cannot be sandboxed');
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+function subpath(path) {
+    return `(subpath ${escapeSeatbeltString(path)})`;
+}
+function deniedReadPaths(options) {
+    const home = canonicalPath(options.home ?? homedir());
+    return [
+        ...SENSITIVE_HOME_PATHS.map((p) => join(home, p)),
+        ...SENSITIVE_ABSOLUTE_PATHS,
+        ...(options.extraDenyRead ?? []).map(canonicalPath),
+    ];
+}
+// Seatbelt
+/**
+ * Build the Seatbelt profile. SBPL applies the last matching rule, so the
+ * broad allow comes first and the specific denies and re-allows follow.
+ */
+export function buildSeatbeltProfile(options) {
+    const writable = [options.workdir, options.tempDir, ...(options.extraWritable ?? [])].map(canonicalPath);
+    const readOnly = (options.extraReadOnly ?? []).map(canonicalPath);
+    const lines = [
+        '(version 1)',
+        '(allow default)',
+        '(deny file-write*)',
+        `(allow file-write* ${writable.map(subpath).join(' ')})`,
+        '(allow file-write* (literal "/dev/null") (literal "/dev/zero") (literal "/dev/tty") (literal "/dev/dtracehelper"))',
+    ];
+    if (readOnly.length > 0)
+        lines.push(`(deny file-write* ${readOnly.map(subpath).join(' ')})`);
+    lines.push(`(deny file-read* ${deniedReadPaths(options).map(subpath).join(' ')})`);
+    if (options.allowNetwork !== true)
+        lines.push('(deny network*)');
+    return `${lines.join('\n')}\n`;
+}
+// bubblewrap
+function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export function buildBwrapArgs(options) {
+    const workdir = canonicalPath(options.workdir);
+    const tempDir = canonicalPath(options.tempDir);
+    const args = ['--ro-bind', '/', '/', '--dev', '/dev', '--proc', '/proc', '--die-with-parent', '--new-session'];
+    for (const path of [workdir, tempDir, ...(options.extraWritable ?? []).map(canonicalPath)]) {
+        args.push('--bind', path, path);
+    }
+    for (const path of (options.extraReadOnly ?? []).map(canonicalPath)) {
+        if (existsSync(path))
+            args.push('--ro-bind', path, path);
+    }
+    for (const path of deniedReadPaths(options)) {
+        if (!existsSync(path))
+            continue;
+        // Directories are hidden behind an empty tmpfs, files behind /dev/null.
+        args.push(...(isDirectory(path) ? ['--tmpfs', path] : ['--ro-bind', '/dev/null', path]));
+    }
+    if (options.allowNetwork !== true)
+        args.push('--unshare-net');
+    args.push('--chdir', workdir);
+    return args;
+}
+// Detection
+let cachedAvailability;
+function findOnPath(name) {
+    for (const dir of (process.env.PATH ?? '').split(delimiter)) {
+        if (dir.length > 0 && existsSync(join(dir, name)))
+            return join(dir, name);
+    }
+    return undefined;
+}
+/**
+ * Detect a working sandbox. A probe run confirms it functions, since
+ * sandbox-exec fails when already inside a sandbox and bwrap can be blocked
+ * by unprivileged user namespace policy.
+ */
+export function detectSandbox() {
+    if (cachedAvailability)
+        return cachedAvailability;
+    let found = { backend: 'none', binary: '' };
+    if (process.platform === 'darwin' && existsSync('/usr/bin/sandbox-exec')) {
+        const probe = spawnSync('/usr/bin/sandbox-exec', ['-p', '(version 1)(allow default)', '/usr/bin/true']);
+        if (probe.status === 0)
+            found = { backend: 'seatbelt', binary: '/usr/bin/sandbox-exec' };
+    }
+    else if (process.platform === 'linux') {
+        const bwrap = findOnPath('bwrap');
+        if (bwrap) {
+            const probe = spawnSync(bwrap, ['--ro-bind', '/', '/', '--unshare-net', 'true']);
+            if (probe.status === 0)
+                found = { backend: 'bwrap', binary: bwrap };
+        }
+    }
+    cachedAvailability = found;
+    return found;
+}
+// Planning
+let warned = false;
+/** Test hook: allow the one-time warning to fire again. */
+export function resetSandboxWarning() {
+    warned = false;
+}
+/** One-line description for CLI output. */
+export function describeSandbox(mode, detect = detectSandbox, allowNetwork = resolveAllowNetwork()) {
+    if (mode === 'off')
+        return 'Sandbox: off (pattern screening only)';
+    const { backend } = detect();
+    if (backend === 'none') {
+        return mode === 'on'
+            ? 'Sandbox: required but unavailable, bash commands will fail'
+            : 'Sandbox: unavailable, bash commands are pattern screened only';
+    }
+    return `Sandbox: ${mode} (${backend}, network ${allowNetwork ? 'allowed' : 'denied'})`;
+}
+/**
+ * Turn a shell command into the process to spawn. Throws in `on` mode when no
+ * sandbox is available. In `auto` mode falls back to the plain shell and warns once.
+ */
+export function planSandboxedCommand(command, options, plan = {}) {
+    const mode = plan.mode ?? resolveSandboxMode();
+    const shell = plan.shell ?? '/bin/sh';
+    const plain = { backend: 'none', file: shell, args: ['-c', command], env: {} };
+    if (mode === 'off')
+        return plain;
+    const available = (plan.detect ?? detectSandbox)();
+    if (available.backend === 'none') {
+        if (mode === 'on') {
+            throw new Error('PROFCLAW_RUN_SANDBOX=on but no sandbox is available (need sandbox-exec on macOS or bwrap on Linux)');
+        }
+        if (!warned) {
+            warned = true;
+            const message = '[profclaw] No OS sandbox available, shell commands are only pattern screened (set PROFCLAW_RUN_SANDBOX=on to require one).\n';
+            if (plan.warn)
+                plan.warn(message);
+            else
+                process.stderr.write(message);
+        }
+        return plain;
+    }
+    const env = { TMPDIR: canonicalPath(options.tempDir) };
+    if (available.backend === 'seatbelt') {
+        return {
+            backend: 'seatbelt',
+            file: available.binary,
+            args: ['-p', buildSeatbeltProfile(options), shell, '-c', command],
+            env,
+        };
+    }
+    return { backend: 'bwrap', file: available.binary, args: [...buildBwrapArgs(options), shell, '-c', command], env };
+}
+//# sourceMappingURL=command-sandbox.js.map