@pugi/cli 0.1.0-beta.10 → 0.1.0-beta.101

package/dist/core/retry-budget/retry-cap.js

@@ -0,0 +1,74 @@
+const DEFAULT_CAP = 3;
+const DEFAULT_RESET_AFTER_MS = 300_000;
+export function createRetryBudget(options = {}) {
+    const cap = normalizePositiveInteger(options.cap, DEFAULT_CAP);
+    const resetAfterMs = normalizeNonNegativeInteger(options.resetAfterMs, DEFAULT_RESET_AFTER_MS);
+    const states = new Map();
+    function clone(state) {
+        return { ...state };
+    }
+    function getFreshState(operationKey, now = Date.now()) {
+        const state = states.get(operationKey);
+        if (!state)
+            return null;
+        if (now - state.lastAttemptAt >= resetAfterMs) {
+            states.delete(operationKey);
+            return null;
+        }
+        return state;
+    }
+    return {
+        record(operationKey) {
+            const now = Date.now();
+            const existing = getFreshState(operationKey, now);
+            const attempts = (existing?.attempts ?? 0) + 1;
+            const next = {
+                operationKey,
+                attempts,
+                firstAttemptAt: existing?.firstAttemptAt ?? now,
+                lastAttemptAt: now,
+                exhausted: attempts >= cap,
+            };
+            states.set(operationKey, next);
+            return clone(next);
+        },
+        reset(operationKey) {
+            states.delete(operationKey);
+        },
+        isExhausted(operationKey) {
+            return getFreshState(operationKey)?.exhausted ?? false;
+        },
+        getState(operationKey) {
+            const state = getFreshState(operationKey);
+            return state ? clone(state) : null;
+        },
+    };
+}
+export function validatePromptWordCount(text, opts) {
+    const words = countWords(text);
+    const chars = text.length;
+    if (opts.min !== undefined && words < opts.min) {
+        return { valid: false, words, chars, reason: 'too-short' };
+    }
+    if (opts.max !== undefined && words > opts.max) {
+        return { valid: false, words, chars, reason: 'too-long' };
+    }
+    return { valid: true, words, chars };
+}
+function countWords(text) {
+    const trimmed = text.trim();
+    if (trimmed.length === 0)
+        return 0;
+    return trimmed.split(/\s+/).length;
+}
+function normalizePositiveInteger(value, fallback) {
+    if (value === undefined || !Number.isFinite(value))
+        return fallback;
+    return Math.max(1, Math.floor(value));
+}
+function normalizeNonNegativeInteger(value, fallback) {
+    if (value === undefined || !Number.isFinite(value))
+        return fallback;
+    return Math.max(0, Math.floor(value));
+}
+//# sourceMappingURL=retry-cap.js.map

package/dist/core/routing/lead-worker.js

@@ -0,0 +1,43 @@
+export function assignRoles(opts) {
+    let hasAssignedWriteLead = false;
+    return opts.steps.map((step) => {
+        const role = assignRole(step, hasAssignedWriteLead);
+        if (step.intent === 'write' && role.role === 'lead') {
+            hasAssignedWriteLead = true;
+        }
+        return {
+            step: step.id,
+            role: role.role,
+            model: role.role === 'lead' ? opts.leadModel : opts.workerModel,
+            reason: role.reason,
+        };
+    });
+}
+function assignRole(step, hasAssignedWriteLead) {
+    if (step.intent === 'plan') {
+        return { role: 'lead', reason: 'planning step requires lead orchestration' };
+    }
+    if (hasLeadHeuristic(step.id)) {
+        return { role: 'lead', reason: 'step id indicates planning or orchestration' };
+    }
+    if (step.intent === 'write' && !hasAssignedWriteLead) {
+        return { role: 'lead', reason: 'first write step needs lead architecture' };
+    }
+    if (step.intent === 'write') {
+        return { role: 'worker', reason: 'subsequent write step is bulk execution' };
+    }
+    if (step.intent === 'read' || step.intent === 'verify') {
+        return { role: 'worker', reason: 'read and verify steps are worker execution' };
+    }
+    if (step.intent === 'explain') {
+        return { role: 'worker', reason: 'explanation step can run on worker model' };
+    }
+    return { role: 'lead', reason: 'unknown intent defaults to lead defensively' };
+}
+function hasLeadHeuristic(stepId) {
+    const normalized = stepId.toLowerCase();
+    return (normalized.includes('plan') ||
+        normalized.includes('design') ||
+        normalized.includes('orchestrate'));
+}
+//# sourceMappingURL=lead-worker.js.map

package/dist/core/routing/pre-flight-estimator.js

@@ -0,0 +1,108 @@
+/**
+ * Pre-flight token estimator — external tokenEstimation port,
+ * adapted for Anvil's 3-tier routing.
+ *
+ * The auto-compact gate counts tokens AFTER a turn lands. This module
+ * runs BEFORE the request leaves the CLI so the router can pick the
+ * cheapest pool that still fits. Three pools exist:
+ *
+ *  cheap    → DeepSeek V4-Pro / Cerebras Qwen3-Coder (128k-256k window)
+ *  mid      → Anthropic Sonnet 4.6 / GPT-5 (200k window, 2-3× cheap-pool cost)
+ *  long     → Kimi K2.6 / Gemini 2.5 Pro (1M window, 5-10× cheap-pool cost)
+ *
+ * The estimator is intentionally synchronous, pure, and free of I/O so
+ * the call site can run it inside a render loop without yielding to
+ * the event loop. The token approximation reuses the existing
+ * char-per-token heuristic from `core/compact/token-counter.ts` (4 chars
+ * ≈ 1 token, biased high). No tiktoken dependency added.
+ */
+import { estimateTokens } from '../compact/token-counter.js';
+/**
+ * Default tier ceilings tuned для Anvil 2026-06 routing matrix.
+ * cheap-pool models (DeepSeek/Cerebras) hard-cap at 100k effective input.
+ * mid-pool (Sonnet/GPT-5) safe through 180k.
+ * long-pool (Kimi/Gemini-Pro) accepts к 900k.
+ *
+ * The numbers stay below the nominal context window к leave room for
+ * output tokens, тек streaming overhead, and tokenizer skew.
+ */
+const DEFAULT_CHEAP_MAX = 100_000;
+const DEFAULT_MID_MAX = 180_000;
+const DEFAULT_LONG_MAX = 900_000;
+const DEFAULT_OUTPUT_BUFFER = 4_096;
+export function estimatePreFlight(input, options = {}) {
+    const cheapMax = options.cheapTierMaxInput ?? DEFAULT_CHEAP_MAX;
+    const midMax = options.midTierMaxInput ?? DEFAULT_MID_MAX;
+    const longMax = options.longTierMaxInput ?? DEFAULT_LONG_MAX;
+    const outputBuffer = input.expectedOutputTokens
+        ?? options.outputBuffer
+        ?? DEFAULT_OUTPUT_BUFFER;
+    if (cheapMax <= 0 || midMax <= 0 || longMax <= 0) {
+        throw new RangeError('tier max values must be positive');
+    }
+    if (cheapMax > midMax || midMax > longMax) {
+        throw new RangeError('tier ceilings must be monotonic: cheap <= mid <= long');
+    }
+    if (outputBuffer < 0) {
+        throw new RangeError('outputBuffer must be >= 0');
+    }
+    const systemTokens = sumStrings(input.systemPrompt ? [input.systemPrompt] : []);
+    const dialogTokens = sumStrings(input.dialogHistory ?? []);
+    const ragTokens = sumStrings(input.ragContext ?? []);
+    const toolTokens = sumStrings(input.toolResults ?? []);
+    const userTokens = sumStrings(input.userMessage ? [input.userMessage] : []);
+    const inputTokens = systemTokens + dialogTokens + ragTokens + toolTokens + userTokens;
+    const totalTokens = inputTokens + outputBuffer;
+    const tier = pickTier(inputTokens, cheapMax, midMax);
+    const overLongTier = inputTokens > longMax;
+    return {
+        inputTokens,
+        outputBuffer,
+        totalTokens,
+        tier,
+        breakdown: {
+            systemPrompt: systemTokens,
+            dialogHistory: dialogTokens,
+            ragContext: ragTokens,
+            toolResults: toolTokens,
+            userMessage: userTokens,
+        },
+        overLongTier,
+    };
+}
+function sumStrings(parts) {
+    let total = 0;
+    for (const part of parts) {
+        total += estimateTokens(part);
+    }
+    return total;
+}
+function pickTier(inputTokens, cheapMax, midMax) {
+    if (inputTokens <= cheapMax)
+        return 'cheap';
+    if (inputTokens <= midMax)
+        return 'mid';
+    return 'long';
+}
+/**
+ * Human-readable explanation для CLI / TUI surfacing.
+ * The format is stable and may be parsed by the doctor command.
+ */
+export function explainEstimate(estimate) {
+    const lines = [];
+    lines.push(`Input tokens: ${estimate.inputTokens.toLocaleString('en-US')}`);
+    lines.push(`Output buffer: ${estimate.outputBuffer.toLocaleString('en-US')}`);
+    lines.push(`Total: ${estimate.totalTokens.toLocaleString('en-US')}`);
+    lines.push(`Routing tier: ${estimate.tier}`);
+    if (estimate.overLongTier) {
+        lines.push('WARNING: input exceeds long-tier ceiling — request will likely fail');
+    }
+    lines.push('Breakdown:');
+    lines.push(` system prompt: ${estimate.breakdown.systemPrompt.toLocaleString('en-US')}`);
+    lines.push(` dialog:        ${estimate.breakdown.dialogHistory.toLocaleString('en-US')}`);
+    lines.push(` rag:           ${estimate.breakdown.ragContext.toLocaleString('en-US')}`);
+    lines.push(` tool results:  ${estimate.breakdown.toolResults.toLocaleString('en-US')}`);
+    lines.push(` user message:  ${estimate.breakdown.userMessage.toLocaleString('en-US')}`);
+    return lines.join('\n');
+}
+//# sourceMappingURL=pre-flight-estimator.js.map

package/dist/core/runs/run-tree.js

@@ -0,0 +1,103 @@
+/**
+ * Canonical `.pugi/runs/<id>/` artifact tree .
+ *
+ * Karpathy hn-time-capsule pattern: every Pugi execution produces a
+ * deterministic directory structure where downstream tooling (eval
+ * harness, leaderboard, replay, debugging) can find
+ * artifacts at predictable paths.
+ *
+ * Layout per run:
+ *  .pugi/runs/<id>/
+ *    meta.json      — metadata: id, startedAt, finishedAt?, command, tier
+ *    stdout.log     — captured stdout (the engine writes it directly)
+ *    stderr.log     — captured stderr
+ *    events.jsonl   — structured event stream (NDJSON)
+ *    metrics.json   — final metrics summary (written at run end)
+ *    artifacts/     — арbitrary file outputs (plans, diffs, exports)
+ *
+ * The `<id>` is `<ISO-timestamp>-<short-rand>` so runs sort
+ * chronologically when listed by directory order.
+ *
+ * This module only handles the directory + metadata primitive. Actual
+ * stream writing (stdout.log, events.jsonl) is the engine's job —
+ * we return paths so the engine knows where к write.
+ */
+import { mkdir, writeFile, readFile, stat } from 'node:fs/promises';
+import { randomBytes } from 'node:crypto';
+import path from 'node:path';
+export function generateRunId(now = new Date()) {
+    const iso = now.toISOString().replace(/[:.]/g, '-');
+    const rand = randomBytes(3).toString('hex');
+    return `${iso}-${rand}`;
+}
+export function resolveRunPaths(workspaceRoot, id) {
+    const root = path.join(workspaceRoot, '.pugi', 'runs', id);
+    return {
+        root,
+        meta: path.join(root, 'meta.json'),
+        stdout: path.join(root, 'stdout.log'),
+        stderr: path.join(root, 'stderr.log'),
+        events: path.join(root, 'events.jsonl'),
+        metrics: path.join(root, 'metrics.json'),
+        artifacts: path.join(root, 'artifacts'),
+    };
+}
+export async function createRun(options) {
+    if (!options.workspaceRoot) {
+        throw new TypeError('workspaceRoot is required');
+    }
+    const id = options.id ?? generateRunId();
+    if (!/^[A-Za-z0-9_.\-T:Z]+$/.test(id)) {
+        throw new RangeError(`invalid run id: ${id} (forbidden characters)`);
+    }
+    const paths = resolveRunPaths(options.workspaceRoot, id);
+    await mkdir(paths.artifacts, { recursive: true });
+    const meta = {
+        id,
+        startedAt: new Date().toISOString(),
+    };
+    if (options.command !== undefined)
+        meta.command = options.command;
+    if (options.tier !== undefined)
+        meta.tier = options.tier;
+    if (options.extra !== undefined)
+        meta.extra = options.extra;
+    await writeFile(paths.meta, JSON.stringify(meta, null, 2) + '\n');
+    return paths;
+}
+export async function readRunMetadata(paths) {
+    try {
+        const buf = await readFile(paths.meta, 'utf8');
+        return JSON.parse(buf);
+    }
+    catch {
+        return null;
+    }
+}
+export async function finalizeRun(paths, options = {}) {
+    const existing = await readRunMetadata(paths);
+    if (!existing) {
+        throw new Error(`run metadata missing at ${paths.meta}`);
+    }
+    const finished = {
+        ...existing,
+        finishedAt: new Date().toISOString(),
+    };
+    if (options.exitCode !== undefined) {
+        finished.exitCode = options.exitCode;
+    }
+    await writeFile(paths.meta, JSON.stringify(finished, null, 2) + '\n');
+    if (options.metrics !== undefined) {
+        await writeFile(paths.metrics, JSON.stringify(options.metrics, null, 2) + '\n');
+    }
+}
+export async function runExists(paths) {
+    try {
+        const stats = await stat(paths.root);
+        return stats.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=run-tree.js.map

package/dist/core/sandboxing/adapter.js

@@ -0,0 +1,43 @@
+/**
+ * Bash sandbox adapter interface (Trust Sprint item 6 + Phase 1 #302).
+ *
+ * Adapter pattern: a runner wraps the spawn invocation with an
+ * OS-level sandbox primitive. Today's variants:
+ *
+ *   - none           - passthrough (legacy behaviour, default).
+ *   - macOS-seatbelt - /usr/bin/sandbox-exec with a workspace-scoped
+ *                      write allowlist + secret-dir deny list +
+ *                      posture-conditional network rule.
+ *   - bubblewrap     - Linux `bwrap` user-namespace jail with a
+ *                      read-only bind of /usr, /lib, /etc, a tmpfs at
+ *                      /tmp, and a writable bind for workspaceRoot.
+ *                      Posture toggles `--share-net`.
+ *   - docker         - Windows fallback (not shipped in this PR;
+ *                      schema accepts the keyword so a forward-rolled
+ *                      settings.json does not error).
+ *
+ * Mechanism x posture matrix:
+ *
+ *   | mechanism       | strict                              | lenient                           | off          |
+ *   | --------------- | ----------------------------------- | --------------------------------- | ------------ |
+ *   | none            | passthrough (mode wins)             | passthrough (mode wins)           | passthrough  |
+ *   | macOS-seatbelt  | workspace writes + deny network     | workspace writes + allow network  | passthrough  |
+ *   | bubblewrap      | workspace bind + deny network       | workspace bind + allow network    | passthrough  |
+ *   | docker          | (not shipped)                       | (not shipped)                     | passthrough  |
+ *
+ * Wired into `tools/bash.ts` at the `spawn`/`spawnSync` call sites
+ * (foreground async, foreground sync, background). The wrap fires
+ * AFTER the permission gate so a refused command never reaches the
+ * sandbox layer; if the adapter probe returns `armed=false` and the
+ * configured mechanism is non-`none`, the bash tool refuses
+ * fail-closed instead of silently degrading.
+ *
+ * Future: replace bubblewrap with native landlock bindings on Linux
+ * + job-object on Windows. The interface is stable, the adapters
+ * change.
+ */
+export {};
+// The `makeAdapter` resolver lives in `./index.ts` so it can import
+// the concrete adapters via ESM without circular references. This
+// file stays pure interfaces.
+//# sourceMappingURL=adapter.js.map

package/dist/core/sandboxing/bubblewrap.js

@@ -0,0 +1,209 @@
+/**
+ * Linux bubblewrap sandbox adapter (Phase 1 #302).
+ *
+ * Wraps bash command execution with `bwrap` (user-namespace jail).
+ * Policy posture:
+ *
+ *   - Workspace root bound read+write at the same path inside the
+ *     jail so cwd resolves identically for the child.
+ *   - System dirs (/usr, /lib, /lib64, /bin, /sbin, /etc, /opt) bound
+ *     read-only - dev toolchains and shared libraries reachable.
+ *   - /tmp = tmpfs (fresh per-invocation), /proc + /dev mounted so
+ *     standard syscalls work.
+ *   - Secret dirs from the host (~/.ssh, ~/.aws, ~/.config/gh,
+ *     ~/.gitconfig) are NOT bound at all - they vanish from the
+ *     child's view. The deny is structural (no mount), not advisory.
+ *   - Network: `--share-net` only when posture=`lenient` or
+ *     `allowNetwork=true`. Strict drops it via `--unshare-all`
+ *     (default + no override).
+ *
+ * Detection: `bwrap` must be on PATH. We probe via `bwrap --version`
+ * and treat any clean exit as proof the binary is callable. Operators
+ * on a host without bwrap see the install hint
+ * (`apt install bubblewrap` / `brew install bubblewrap`).
+ *
+ * Security note: bwrap requires either CAP_SYS_ADMIN or unprivileged
+ * user namespaces (kernel.unprivileged_userns_clone=1). Modern
+ * distros (Debian 11+, Ubuntu 22.04+, Fedora 35+, Arch) enable this
+ * by default. When the kernel rejects the bwrap invocation, the wrap
+ * succeeds but the spawn fails - the bash tool surfaces the child's
+ * stderr verbatim so the operator sees the kernel-side reason.
+ */
+import { execFileSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { isAbsolute } from 'node:path';
+import { defaultSecretDirs, resolveNetworkAllowance } from './policy.js';
+const BWRAP_BINARY = 'bwrap';
+/**
+ * Install hint surfaced when bwrap is missing from PATH. We tailor
+ * the hint to the most common Linux package managers; macOS users
+ * normally select `macOS-seatbelt`, not `bubblewrap`, so we still
+ * mention Homebrew for completeness.
+ */
+const BWRAP_INSTALL_HINT = 'Install bwrap: `sudo apt install bubblewrap` (Debian/Ubuntu) or ' +
+    '`sudo dnf install bubblewrap` (Fedora/RHEL) or `brew install bubblewrap` (macOS Homebrew).';
+export class BubblewrapSandboxAdapter {
+    mode = 'bubblewrap';
+    probe(opts) {
+        if (process.platform !== 'linux' && process.platform !== 'darwin') {
+            return {
+                mode: 'bubblewrap',
+                armed: false,
+                reason: `bubblewrap unavailable on ${process.platform} - choose 'none', 'macOS-seatbelt', or 'docker'.`,
+                details: [`platform: ${process.platform}`, `expected: linux (primary) or darwin (homebrew)`],
+                installHint: BWRAP_INSTALL_HINT,
+            };
+        }
+        const bwrapPath = locateBwrap();
+        if (bwrapPath === null) {
+            return {
+                mode: 'bubblewrap',
+                armed: false,
+                reason: 'bwrap binary not found on PATH.',
+                details: [
+                    `platform: ${process.platform}`,
+                    `lookup: PATH`,
+                    `remediation: install the bubblewrap package`,
+                ],
+                installHint: BWRAP_INSTALL_HINT,
+            };
+        }
+        return {
+            mode: 'bubblewrap',
+            armed: true,
+            details: [
+                `platform: ${process.platform}`,
+                `binary: ${bwrapPath}`,
+                `workspaceRoot: ${opts.workspaceRoot}`,
+                `extraWritePaths: ${(opts.extraWritePaths ?? []).join(', ') || '<none>'}`,
+                `posture: ${opts.posture ?? 'strict'}`,
+                `network: ${resolveNetworkAllowance(opts.posture, opts.allowNetwork) ? 'allow' : 'deny'}`,
+            ],
+        };
+    }
+    wrap(cmd, opts) {
+        const armed = this.probe(opts);
+        if (!armed.armed) {
+            throw new Error(`BubblewrapSandboxAdapter.wrap: ${armed.reason}`);
+        }
+        if (!isAbsolute(opts.workspaceRoot)) {
+            throw new Error(`BubblewrapSandboxAdapter.wrap: workspaceRoot must be absolute, got "${opts.workspaceRoot}"`);
+        }
+        for (const p of opts.extraWritePaths ?? []) {
+            if (!isAbsolute(p)) {
+                throw new Error(`BubblewrapSandboxAdapter.wrap: extraWritePaths entry must be absolute, got "${p}"`);
+            }
+        }
+        for (const p of opts.extraReadPaths ?? []) {
+            if (!isAbsolute(p)) {
+                throw new Error(`BubblewrapSandboxAdapter.wrap: extraReadPaths entry must be absolute, got "${p}"`);
+            }
+        }
+        const args = renderBwrapArgs(opts);
+        return {
+            command: BWRAP_BINARY,
+            args: [...args, '--', cmd.command, ...cmd.args],
+            description: `sandbox: bubblewrap (posture=${opts.posture ?? 'strict'})`,
+        };
+    }
+    /**
+     * Exposed for unit tests so the spec can pin the exact argv shape
+     * without driving the whole wrap path.
+     */
+    renderArgs(opts) {
+        return renderBwrapArgs(opts);
+    }
+}
+/**
+ * Compose the bwrap argv from the spawn options. Order matters:
+ *
+ *   1. Namespace flags (`--unshare-all`, optional `--share-net`).
+ *   2. Read-only system binds - provides /usr, /bin, /lib, etc.
+ *   3. /proc + /dev so syscalls work.
+ *   4. tmpfs at /tmp so build scratch never persists.
+ *   5. Read-write bind of workspaceRoot + every extraWritePath.
+ *   6. Read-only bind of every extraReadPath.
+ *
+ * Secret dirs are NOT bound. Because bwrap starts from a fresh mount
+ * namespace, anything not explicitly bound is invisible to the child.
+ * The `defaultSecretDirs` helper exists only for symmetry with the
+ * seatbelt adapter's deny rules - the documentation surface stays
+ * consistent across mechanisms.
+ */
+function renderBwrapArgs(opts) {
+    const home = opts.homedir ?? homedir();
+    const networkAllowed = resolveNetworkAllowance(opts.posture, opts.allowNetwork);
+    const args = [];
+    // Namespace isolation. `--unshare-all` removes every namespace -
+    // pid, mount, ipc, uts, cgroup, net. We selectively re-share net
+    // when the policy says so. `--die-with-parent` makes sure the
+    // child does not outlive the bash tool's spawn() handle.
+    args.push('--die-with-parent');
+    args.push('--unshare-all');
+    if (networkAllowed) {
+        args.push('--share-net');
+    }
+    // Read-only system binds. We bind each path with `--ro-bind-try`
+    // so missing dirs (e.g. /lib64 on a non-multilib host) do not
+    // abort the wrap. The order mirrors a minimal POSIX userland.
+    for (const sys of ['/usr', '/bin', '/sbin', '/lib', '/lib64', '/etc', '/opt']) {
+        args.push('--ro-bind-try', sys, sys);
+    }
+    // /proc + /dev - required for most binaries. /dev is the bwrap
+    // virtual /dev (just null, zero, tty, random, urandom). /proc is
+    // the new namespace's proc, not the host's.
+    args.push('--proc', '/proc');
+    args.push('--dev', '/dev');
+    // Fresh tmpfs at /tmp every invocation. Build scratch never
+    // persists across runs and never leaks into the host's /tmp.
+    args.push('--tmpfs', '/tmp');
+    // Workspace bind: read + write. The bind is at the same path
+    // inside the jail so a relative cwd from the parent resolves
+    // identically inside.
+    args.push('--bind', opts.workspaceRoot, opts.workspaceRoot);
+    // Extra writable paths (typical: ~/.pugi for CLI state).
+    for (const writable of opts.extraWritePaths ?? []) {
+        args.push('--bind', writable, writable);
+    }
+    // Extra read-only paths the operator opted into.
+    for (const readonly of opts.extraReadPaths ?? []) {
+        args.push('--ro-bind-try', readonly, readonly);
+    }
+    // `defaultSecretDirs` is computed-and-ignored here. The intent is
+    // documentation: future operators reading this code see the same
+    // list the seatbelt deny block uses. The structural omission of
+    // these binds IS the deny - referencing the list makes that
+    // explicit.
+    void defaultSecretDirs(home);
+    return args;
+}
+/**
+ * Locate `bwrap` on the operator's PATH. We avoid `which` (not POSIX
+ * everywhere) and `command -v` (shell builtin, not spawn-friendly).
+ * Instead we run `bwrap --version` and treat any clean exit as proof
+ * the binary is callable.
+ */
+function locateBwrap() {
+    try {
+        execFileSync(BWRAP_BINARY, ['--version'], {
+            stdio: ['ignore', 'ignore', 'ignore'],
+            timeout: 3000,
+        });
+        return BWRAP_BINARY;
+    }
+    catch (err) {
+        const e = err;
+        if (e?.code === 'ENOENT')
+            return null;
+        // Non-zero exit (e.g. bwrap with a strange host) still means the
+        // binary exists. We treat it as available; the wrap call will
+        // surface the real failure via the child's stderr.
+        return BWRAP_BINARY;
+    }
+}
+/**
+ * Convenience re-export for callers / specs that want the same hint
+ * string without duplicating the literal.
+ */
+export const BUBBLEWRAP_INSTALL_HINT = BWRAP_INSTALL_HINT;
+//# sourceMappingURL=bubblewrap.js.map

package/dist/core/sandboxing/index.js

@@ -0,0 +1,78 @@
+/**
+ * Sandbox adapter resolver (Trust Sprint item 6 + Phase 1 #302).
+ *
+ * Single re-export surface so consumers (`pugi doctor`, the bash
+ * runner indirection, MCP serve diagnostics) can do:
+ *
+ *   import { makeAdapter, type SandboxMode } from '.../sandboxing';
+ *
+ * The concrete adapters live in sibling files; this index wires the
+ * lookup table without forcing a circular import between the
+ * interface (`adapter.ts`) and the implementations.
+ */
+import { BubblewrapSandboxAdapter } from './bubblewrap.js';
+import { NoneSandboxAdapter } from './none.js';
+import { SeatbeltSandboxAdapter } from './seatbelt.js';
+export { BubblewrapSandboxAdapter } from './bubblewrap.js';
+export { NoneSandboxAdapter } from './none.js';
+export { SeatbeltSandboxAdapter } from './seatbelt.js';
+export { SANDBOX_DISABLE_ENV, defaultSecretDirs, isSandboxDisabled, resolveNetworkAllowance, } from './policy.js';
+/**
+ * Resolve a sandbox adapter from a configured mode. Throws for
+ * `docker` (documented but not shipped in this PR) and for unknown
+ * modes (defends against forward-rolled settings.json files).
+ */
+export function makeAdapter(mode) {
+    switch (mode) {
+        case 'none':
+            return new NoneSandboxAdapter();
+        case 'macOS-seatbelt':
+            return new SeatbeltSandboxAdapter();
+        case 'bubblewrap':
+            return new BubblewrapSandboxAdapter();
+        case 'docker':
+            throw new Error('bash sandbox: docker mode is documented but not yet implemented. ' +
+                'Use bash.sandbox = "none", "macOS-seatbelt", or "bubblewrap" until the docker adapter ships.');
+        default: {
+            const exhaustive = mode;
+            throw new Error(`bash sandbox: unknown mode "${String(exhaustive)}"`);
+        }
+    }
+}
+/**
+ * Auto-detect the platform-appropriate sandbox mechanism. Returns:
+ *
+ *   - `'macOS-seatbelt'` on darwin
+ *   - `'bubblewrap'` on linux (regardless of whether bwrap is
+ *      installed; the probe surfaces the install hint if missing)
+ *   - `'none'` on every other platform (windows, freebsd, etc.)
+ *
+ * Callers that prefer explicit selection should read
+ * `.pugi/settings.json::bash.sandbox` directly. This helper exists
+ * for the bash tool's "no settings configured" path so the strongest
+ * available mechanism applies by default.
+ */
+export function detectDefaultMode() {
+    if (process.platform === 'darwin')
+        return 'macOS-seatbelt';
+    if (process.platform === 'linux')
+        return 'bubblewrap';
+    return 'none';
+}
+/**
+ * Convenience: probe the configured mode without spawning anything.
+ * Used by `pugi doctor` so the sandbox probe can report the same
+ * armed state the bash runner would see.
+ */
+export function probeSandbox(opts) {
+    const adapter = makeAdapter(opts.mode);
+    return adapter.probe({
+        workspaceRoot: opts.workspaceRoot,
+        ...(opts.extraWritePaths ? { extraWritePaths: opts.extraWritePaths } : {}),
+        ...(opts.extraReadPaths ? { extraReadPaths: opts.extraReadPaths } : {}),
+        ...(opts.posture ? { posture: opts.posture } : {}),
+        ...(opts.allowNetwork !== undefined ? { allowNetwork: opts.allowNetwork } : {}),
+        ...(opts.homedir ? { homedir: opts.homedir } : {}),
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/core/sandboxing/none.js

@@ -0,0 +1,19 @@
+export class NoneSandboxAdapter {
+    mode = 'none';
+    probe(_opts) {
+        return {
+            mode: 'none',
+            armed: false,
+            reason: "policy 'none' selected — bash dispatches run unsandboxed (classifier + permission FSM still apply).",
+            details: ['mode: none (passthrough)', 'enforcement: bash classifier + permission FSM only'],
+        };
+    }
+    wrap(cmd, _opts) {
+        return {
+            command: cmd.command,
+            args: cmd.args,
+            description: 'sandbox: none (passthrough)',
+        };
+    }
+}
+//# sourceMappingURL=none.js.map