@evomap/evolver-core 2.0.0-beta.14 → 2.0.0-beta.15

package/dist/trace/learningTrace.js

@@ -0,0 +1,274 @@
+// Agent runtime trace instrumentation (Learning Ops slice 1).
+// Aligns with evomap-hub Learning Ops data plane contract (schemaVersion `trace_event.v0` /
+// `learning_packet.v0`): the runtime emits ordered TraceEvents over the agent-run lifecycle and
+// assembles a LearningPacket DRAFT locally. Hub delivery goes through the LearningPacketSink port —
+// core never hardcodes a hub endpoint (file/console/memory sinks let a run trace without hub access).
+import { appendFileSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+export const TRACE_EVENT_SCHEMA = 'trace_event.v0';
+export const LEARNING_PACKET_SCHEMA = 'learning_packet.v0';
+/** Lifecycle vocabulary for slice 1. Kept flat + closed so hub-side eventType stays queryable. */
+export const TRACE_EVENT_TYPES = [
+    'run.started',
+    'run.completed',
+    'model.called',
+    'tool.called',
+    'tool.failed',
+    'retry.attempted',
+    'reflection.recorded',
+    'intervention.received',
+];
+export class InMemoryTraceSink {
+    events = [];
+    emit(event) { this.events.push(event); }
+}
+/** JSONL append sink for local inspection / offline replay. */
+export class FileTraceSink {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    emit(event) {
+        mkdirSync(dirname(this.path), { recursive: true });
+        appendFileSync(this.path, `${JSON.stringify(event)}\n`, 'utf8');
+    }
+}
+export class ConsoleTraceSink {
+    log;
+    constructor(log = (line) => console.error(line)) {
+        this.log = log;
+    }
+    emit(event) { this.log(`[trace] ${event.sequence} ${event.eventType} ${JSON.stringify(event.payload)}`); }
+}
+/**
+ * Per-run trace recorder: the single hook surface the runtime calls at lifecycle points.
+ * Sequence numbers are assigned here (monotonic per run), so downstream ordering never depends on
+ * sink latency or clock resolution.
+ */
+export class AgentRunTraceRecorder {
+    opts;
+    sequence = 0;
+    recorded = [];
+    constructor(opts) {
+        this.opts = opts;
+    }
+    get events() { return this.recorded; }
+    runStarted(input = {}) {
+        return this.record('run.started', {
+            ...(input.taskSummary !== undefined ? { taskSummary: input.taskSummary } : {}),
+            ...(input.signals !== undefined ? { signals: [...input.signals] } : {}),
+            ...(input.geneId !== undefined ? { geneId: input.geneId } : {}),
+        }, input.metadata);
+    }
+    modelCalled(input = {}) {
+        return this.record('model.called', {
+            ...(input.provider !== undefined ? { provider: input.provider } : {}),
+            ...(input.model !== undefined ? { model: input.model } : {}),
+            ...(input.requestId !== undefined ? { requestId: input.requestId } : {}),
+            ...(input.latencyMs !== undefined ? { latencyMs: input.latencyMs } : {}),
+            ...(input.usage !== undefined ? { usage: input.usage } : {}),
+            ...(input.stopReason !== undefined ? { stopReason: input.stopReason } : {}),
+        });
+    }
+    toolCalled(input) {
+        return this.record('tool.called', {
+            toolName: input.toolName,
+            ...(input.callId !== undefined ? { callId: input.callId } : {}),
+            ...(input.durationMs !== undefined ? { durationMs: input.durationMs } : {}),
+        }, input.metadata);
+    }
+    toolFailed(input) {
+        return this.record('tool.failed', {
+            toolName: input.toolName,
+            ...(input.callId !== undefined ? { callId: input.callId } : {}),
+            error: input.error,
+        });
+    }
+    retryAttempted(input) {
+        return this.record('retry.attempted', {
+            attempt: input.attempt,
+            ...(input.reason !== undefined ? { reason: input.reason } : {}),
+            ...(input.target !== undefined ? { target: input.target } : {}),
+        });
+    }
+    reflectionRecorded(input) {
+        return this.record('reflection.recorded', {
+            outcome: input.outcome,
+            ...(input.action !== undefined ? { action: input.action } : {}),
+            ...(input.summary !== undefined ? { summary: input.summary } : {}),
+        });
+    }
+    interventionReceived(input) {
+        return this.record('intervention.received', {
+            kind: input.kind,
+            ...(input.actorId !== undefined ? { actorId: input.actorId } : {}),
+            ...(input.detail !== undefined ? { detail: input.detail } : {}),
+        });
+    }
+    runCompleted(input) {
+        return this.record('run.completed', {
+            status: input.status,
+            ...(input.score !== undefined ? { score: input.score } : {}),
+            ...(input.reason !== undefined ? { reason: input.reason } : {}),
+            ...(input.producedValue !== undefined ? { producedValue: input.producedValue } : {}),
+            ...(input.failureKind !== undefined ? { failureKind: input.failureKind } : {}),
+        });
+    }
+    /** Fold one normalized llm_turn (trace/trajectory.ts) into model.called + tool.called/tool.failed events. */
+    recordLlmTurn(turn) {
+        const out = [this.modelCalled({
+                ...(turn.provider !== null ? { provider: turn.provider } : {}),
+                ...(turn.chosen_model !== null ? { model: turn.chosen_model } : {}),
+                ...(turn.request_id !== null ? { requestId: turn.request_id } : {}),
+                ...(turn.latency_ms !== null ? { latencyMs: turn.latency_ms } : {}),
+                ...(turn.usage !== undefined ? { usage: { ...turn.usage } } : {}),
+                ...(typeof turn.stop_reason === 'string' ? { stopReason: turn.stop_reason } : {}),
+            })];
+        if (Array.isArray(turn.tool_calls)) {
+            for (const call of turn.tool_calls) {
+                const rec = call;
+                const toolName = typeof rec.name === 'string' && rec.name.length > 0 ? rec.name : 'unknown_tool';
+                const callId = typeof rec.id === 'string' ? rec.id : undefined;
+                out.push(typeof rec.error === 'string' && rec.error.length > 0
+                    ? this.toolFailed({ toolName, ...(callId !== undefined ? { callId } : {}), error: rec.error })
+                    : this.toolCalled({ toolName, ...(callId !== undefined ? { callId } : {}) }));
+            }
+        }
+        return out;
+    }
+    record(eventType, payload, metadata) {
+        this.sequence += 1;
+        const at = (this.opts.now ?? Date.now)();
+        const event = {
+            schemaVersion: TRACE_EVENT_SCHEMA,
+            eventId: (this.opts.eventIdFactory ?? ((seq) => `${this.opts.runId}-${String(seq).padStart(4, '0')}`))(this.sequence),
+            eventType,
+            traceId: this.opts.runId,
+            ...(this.opts.sessionId !== undefined ? { sessionId: this.opts.sessionId } : {}),
+            ...(this.opts.taskId !== undefined ? { taskId: this.opts.taskId } : {}),
+            sequence: this.sequence,
+            occurredAt: new Date(at).toISOString(),
+            payload,
+            metadata: metadata ?? {},
+        };
+        this.recorded.push(event);
+        this.opts.sink?.emit(event);
+        return event;
+    }
+}
+/* ── Root-event bridge: existing cycle lifecycle → trace events, via the sanctioned ObserverBus ── */
+const BRIDGED_EVENT_TYPES = [
+    'cycle.started', 'cycle.solidified', 'cycle.failed',
+    'reflection.recorded',
+    'actor.human.nudge', 'actor.human.intervene', 'actor.human.teach',
+    'actor.human.review.approve', 'actor.human.review.reject',
+];
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+}
+/**
+ * Bypass-side bridge (never blocks the write path): maps the engine's existing root events onto the
+ * run's TraceEvent stream, so CycleEngine needs no code change for run start/completion, reflection,
+ * or human intervention coverage.
+ */
+export function learningTraceObserver(deps) {
+    const meta = {
+        name: 'learning_trace',
+        eventTypes: BRIDGED_EVENT_TYPES,
+        idempotent: true,
+        timeoutMs: deps.timeoutMs ?? 2_000,
+    };
+    return {
+        meta,
+        handle(event) {
+            const payload = asRecord(event.payload) ?? {};
+            if (event.type === 'cycle.started') {
+                deps.recorder.runStarted({ metadata: { cycleId: payload['cycleId'] ?? null } });
+                return;
+            }
+            if (event.type === 'cycle.solidified' || event.type === 'cycle.failed') {
+                const outcome = asRecord(payload['outcome']);
+                const status = event.type === 'cycle.solidified' ? 'success' : 'failed';
+                const score = typeof outcome?.['score'] === 'number' ? outcome['score'] : undefined;
+                const reason = typeof payload['error'] === 'string'
+                    ? payload['error']
+                    : typeof payload['reason'] === 'string' ? payload['reason'] : undefined;
+                deps.recorder.runCompleted({
+                    status,
+                    ...(score !== undefined ? { score } : {}),
+                    ...(reason !== undefined ? { reason } : {}),
+                    ...(typeof payload['producedValue'] === 'boolean' ? { producedValue: payload['producedValue'] } : {}),
+                    ...(typeof payload['failureKind'] === 'string' ? { failureKind: payload['failureKind'] } : {}),
+                });
+                return;
+            }
+            if (event.type === 'reflection.recorded') {
+                deps.recorder.reflectionRecorded({
+                    outcome: typeof payload['outcome'] === 'string' ? payload['outcome'] : 'unknown',
+                    ...(typeof payload['action'] === 'string' ? { action: payload['action'] } : {}),
+                    ...(typeof payload['summary'] === 'string' ? { summary: payload['summary'] } : {}),
+                });
+                return;
+            }
+            // actor.human.*: host/human intervention audit trail.
+            deps.recorder.interventionReceived({
+                kind: event.type.replace(/^actor\.human\./, ''),
+                ...(event.actor.id !== undefined ? { actorId: event.actor.id } : {}),
+                ...(typeof payload['detail'] === 'string' ? { detail: payload['detail'] } : {}),
+            });
+        },
+    };
+}
+export function buildLearningPacketDraft(recorder, input) {
+    const events = [...recorder.events].sort((a, b) => a.sequence - b.sequence);
+    const first = events[0];
+    const completed = [...events].reverse().find((e) => e.eventType === 'run.completed');
+    const completedStatus = completed?.payload['status'];
+    const failureKind = completed?.payload['failureKind'];
+    const started = events.find((e) => e.eventType === 'run.started');
+    const startedSummary = started?.payload['taskSummary'];
+    return {
+        schemaVersion: LEARNING_PACKET_SCHEMA,
+        status: 'draft',
+        source: { repo: input.sourceRepo, run: first?.traceId ?? 'unknown-run', type: 'agent_run', id: first?.traceId ?? 'unknown-run' },
+        task: {
+            taskId: first?.taskId ?? null,
+            summary: input.taskSummary ?? (typeof startedSummary === 'string' ? startedSummary : null),
+            signals: [...(input.signals ?? [])],
+        },
+        context: {
+            sessionId: first?.sessionId ?? null,
+            traceId: first?.traceId ?? 'unknown-run',
+            environment: input.environment ?? {},
+        },
+        trajectory: events,
+        artifacts: { placeholder: true, items: [] },
+        evaluation: {
+            placeholder: true,
+            outcomeStatus: completedStatus === 'success' ? 'success' : completedStatus === 'failed' ? 'failed' : 'unknown',
+            verifier: null,
+            failureCategory: typeof failureKind === 'string' ? failureKind : null,
+        },
+        governance: { placeholder: true, redactionStatus: 'metadata_only', consentStatus: 'unknown', trainingEligible: false, retentionPolicy: 'standard' },
+    };
+}
+export class InMemoryLearningPacketSink {
+    drafts = [];
+    async submit(draft) {
+        this.drafts.push(draft);
+        return { accepted: true };
+    }
+}
+/** Writes one JSON file per run — the offline/no-hub path (and a manual-inspection artifact). */
+export class FileLearningPacketSink {
+    dir;
+    constructor(dir) {
+        this.dir = dir;
+    }
+    async submit(draft) {
+        mkdirSync(this.dir, { recursive: true });
+        const path = `${this.dir}/${draft.source.run}.learning-packet.json`;
+        writeFileSync(path, `${JSON.stringify(draft, null, 2)}\n`, 'utf8');
+        return { accepted: true, reason: path };
+    }
+}

package/dist/verify/sandboxRunner.d.ts

@@ -19,13 +19,41 @@ export interface SandboxOptions {
      * unprivileged mount namespaces are unavailable. Binaries live outside these dirs, so the command still runs.
      */
     hideHomeSecrets?: boolean;
+    /** Remount the inherited filesystem read-only inside the mount namespace, leaving only an isolated /tmp writable. */
+    readOnlyFilesystem?: boolean;
+    /** Host scratch directory exposed as the sandbox's only writable filesystem. */
+    writableTmpDir?: string;
+    /** Read-only checkout root remounted at its original absolute path after HOME and /tmp are hidden. */
+    readOnlyRoot?: string;
+    /** Put the full command tree in a bounded cgroup v2. Required by verified Skill execution. */
+    resourceLimits?: boolean;
     /** Injected unshare-availability probe (test seam). Default: a real `unshare -r -m -n true` check (cached). */
     unshareCheck?: () => boolean;
+    /** Injected cgroup allocator (test seam). */
+    resourceGroupFactory?: () => SandboxResourceGroup | null;
 }
+export interface SandboxResourceGroup {
+    procsFile: string;
+    cleanup: () => void;
+}
+/** Configure an already-created cgroup. Kept separate so limit values are testable without resource exhaustion. */
+export declare function configureSandboxResourceGroup(path: string): boolean;
+/** Allocate a delegated cgroup v2 for one validation command. Returns null unless every limit is enforceable. */
+export declare function createSandboxResourceGroup(): SandboxResourceGroup | null;
+/** Join the cgroup before exec, so attacker-controlled code never runs outside the aggregate resource budget. */
+export declare function resourceLimitedCommand(cmd: string, args: readonly string[], procsFile: string): {
+    cmd: string;
+    args: string[];
+};
+export declare function sandboxResourceLimitsAvailable(): boolean;
 /** Wrap an (executable,args) in unprivileged namespaces per the requested isolation (pure — testable). */
 export declare function isolationCommand(bin: string, args: readonly string[], opts: {
     noNetwork?: boolean;
     hideHomeSecrets?: boolean;
+    readOnlyFilesystem?: boolean;
+    writableTmpDir?: string;
+    readOnlyRoot?: string;
+    cwd?: string;
 }): {
     cmd: string;
     args: string[];

package/dist/verify/sandboxRunner.js

@@ -5,41 +5,205 @@
 // module hardens EXECUTION: blocked node eval-flags, shell-metachar rejection, a fresh wiped temp cwd,
 // a scrubbed env (no secrets leak in), and a SIGKILL timeout. Output is folded + truncated.
 import { spawn, spawnSync } from 'node:child_process';
-import { mkdtempSync, rmSync } from 'node:fs';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, rmdirSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { isNodeExecutable, nodeFlagViolation, SHELL_METACHARS } from './validation.js';
 const DEFAULT_TIMEOUT_MS = 60_000;
 const MAX_TIMEOUT_MS = 120_000;
 const MAX_OUTPUT_CHARS = 4000;
+const CGROUP_ROOT = '/sys/fs/cgroup';
+const TRUSTED_SYSTEM_PATH = '/usr/sbin:/usr/bin:/sbin:/bin';
+const SYSTEM_SH = '/bin/sh';
+const SYSTEM_UNSHARE = ['/usr/bin/unshare', '/bin/unshare'].find((path) => existsSync(path)) ?? '/usr/bin/unshare';
+const RESOURCE_LIMITS = {
+    memoryBytes: 1024 * 1024 * 1024,
+    processes: 64,
+    cpuQuota: '100000 100000',
+    scratchBytes: 256 * 1024 * 1024,
+};
 // Env scrub: only these keys reach the child, so node-secrets/tokens in the parent env cannot leak into validation.
 const DEFAULT_ENV_ALLOW = ['PATH', 'HOME', 'LANG', 'LC_ALL', 'TMPDIR', 'SYSTEMROOT'];
 /** Credential dirs hidden under $HOME when hideHomeSecrets is set (dirs only — never where binaries live). */
 const SECRET_HOME_DIRS = ['.evomap', '.ssh', '.aws', '.gnupg', '.docker', '.kube'];
 // Fixed setup run inside the mount ns: tmpfs over each existing secret dir, then exec the command. The command
 // is passed as POSITIONAL args (`exec "$@"`), never interpolated into the script — no shell-injection vector.
-const HIDE_SECRETS_SCRIPT = `for d in ${SECRET_HOME_DIRS.map((d) => `"$HOME/${d}"`).join(' ')}; do [ -d "$d" ] && mount -t tmpfs none "$d" 2>/dev/null; done; exec "$@"`;
+const HIDE_SECRETS_SETUP = `PATH=${TRUSTED_SYSTEM_PATH}; export PATH; for d in ${SECRET_HOME_DIRS.map((d) => `"$HOME/${d}"`).join(' ')}; do if [ -d "$d" ]; then mount -t tmpfs none "$d" 2>/dev/null || exit 126; fi; done`;
+const READ_ONLY_FILESYSTEM_SETUP = [
+    `PATH=${TRUSTED_SYSTEM_PATH}; export PATH`,
+    'session_tmp="$1"; shift',
+    'validation_root="$1"; shift',
+    'validation_cwd="$1"; shift',
+    'host_bin="$1"; shift',
+    '[ -n "$HOME" ] && [ "$HOME" != / ] && [ -d "$HOME" ] || exit 126',
+    'case "$validation_cwd/" in "$validation_root/"*) ;; *) exit 126 ;; esac',
+    'case "$HOME/" in "$validation_root/"*) exit 126 ;; esac',
+    `mount -t tmpfs -o size=${RESOURCE_LIMITS.scratchBytes},nr_inodes=65536 none "$session_tmp" 2>/dev/null || exit 126`,
+    'mkdir -p "$session_tmp/source" "$session_tmp/home" || exit 126',
+    'mkdir -p "$session_tmp/dev" || exit 126',
+    ': > "$session_tmp/node" || exit 126',
+    'mount --bind "$validation_root" "$session_tmp/source" 2>/dev/null || exit 126',
+    'mount --bind "$host_bin" "$session_tmp/node" 2>/dev/null || exit 126',
+    'for device in null zero random urandom; do : > "$session_tmp/dev/$device" || exit 126; mount --bind "/dev/$device" "$session_tmp/dev/$device" 2>/dev/null || exit 126; done',
+    'mount -t tmpfs none "$HOME" 2>/dev/null || exit 126',
+    '[ ! -d /run ] || mount -t tmpfs none /run 2>/dev/null || exit 126',
+    'mount -t tmpfs none /tmp 2>/dev/null || exit 126',
+    'mkdir -p "$validation_root" || exit 126',
+    'mount --bind "$session_tmp/source" "$validation_root" 2>/dev/null || exit 126',
+    'mounts="$(findmnt -rn -o TARGET -R /)" || exit 126',
+    '[ -n "$mounts" ] || exit 126',
+    'printf "%s\\n" "$mounts" | while IFS= read -r target; do mount -o remount,bind,ro "$target" 2>/dev/null || exit 126; done || exit 126',
+    'mount -o remount,bind,rw,exec "$session_tmp" 2>/dev/null || exit 126',
+    'mount -t tmpfs -o mode=755,size=65536,nr_inodes=64 none /dev 2>/dev/null || exit 126',
+    'for device in null zero random urandom; do : > "/dev/$device" || exit 126; mount --bind "$session_tmp/dev/$device" "/dev/$device" 2>/dev/null || exit 126; done',
+    'mount -o remount,ro /dev 2>/dev/null || exit 126',
+    'mount --rbind "$session_tmp" /tmp 2>/dev/null || exit 126',
+    'cd "$validation_cwd" || exit 126',
+    'export HOME=/tmp/home TMPDIR=/tmp TMP=/tmp TEMP=/tmp',
+].join('; ');
+const DROP_NAMESPACE_PRIVILEGES = [
+    'supervisor_pid=$$',
+    'exec 3<&0',
+    'setpriv --no-new-privs --securebits=+noroot,+noroot_locked --bounding-set=-all --inh-caps=-all --ambient-caps=-all -- /tmp/node "$@" </dev/null 3<&- & workload_pid=$!',
+    // The pipe is owned by the parent Node process. Kernel EOF is therefore a reliable parent-death signal,
+    // including SIGKILL, while unshare --kill-child propagates supervisor death through the PID namespace.
+    '(IFS= read -r _ <&3 || kill -KILL "$supervisor_pid") & watchdog_pid=$!',
+    'exec 3<&-',
+    'wait "$workload_pid"; status=$?',
+    'kill "$watchdog_pid" 2>/dev/null || true',
+    'wait "$watchdog_pid" 2>/dev/null || true',
+    'exit "$status"',
+].join('; ');
+function pathIsWithin(root, target) {
+    const rel = relative(root, target);
+    return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+function currentCgroupPath() {
+    const entry = readFileSync('/proc/self/cgroup', 'utf8')
+        .split(/\r?\n/)
+        .find((line) => line.startsWith('0::'));
+    if (!entry)
+        return null;
+    const relativePath = entry.slice(3).replace(/^\/+/, '');
+    const path = resolve(CGROUP_ROOT, relativePath);
+    return pathIsWithin(CGROUP_ROOT, path) ? path : null;
+}
+/** Configure an already-created cgroup. Kept separate so limit values are testable without resource exhaustion. */
+export function configureSandboxResourceGroup(path) {
+    try {
+        const required = ['cgroup.procs', 'cgroup.kill', 'memory.max', 'memory.swap.max', 'memory.oom.group', 'pids.max', 'cpu.max'];
+        if (!required.every((name) => existsSync(join(path, name))))
+            return false;
+        writeFileSync(join(path, 'memory.max'), String(RESOURCE_LIMITS.memoryBytes));
+        writeFileSync(join(path, 'memory.swap.max'), '0');
+        writeFileSync(join(path, 'memory.oom.group'), '1');
+        writeFileSync(join(path, 'pids.max'), String(RESOURCE_LIMITS.processes));
+        writeFileSync(join(path, 'cpu.max'), RESOURCE_LIMITS.cpuQuota);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Allocate a delegated cgroup v2 for one validation command. Returns null unless every limit is enforceable. */
+export function createSandboxResourceGroup() {
+    if (process.platform !== 'linux' || !existsSync(join(CGROUP_ROOT, 'cgroup.controllers')))
+        return null;
+    let path = null;
+    try {
+        const parent = currentCgroupPath();
+        if (!parent)
+            return null;
+        path = join(parent, `evolver-validation-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`);
+        mkdirSync(path, { mode: 0o700 });
+        if (!configureSandboxResourceGroup(path))
+            throw new Error('required cgroup v2 controllers are not delegated');
+        let cleaned = false;
+        return {
+            procsFile: join(path, 'cgroup.procs'),
+            cleanup: () => {
+                if (cleaned)
+                    return;
+                cleaned = true;
+                try {
+                    writeFileSync(join(path, 'cgroup.kill'), '1');
+                }
+                catch { /* already empty or removed */ }
+                try {
+                    rmdirSync(path);
+                }
+                catch { /* kernel may release the empty group asynchronously */ }
+            },
+        };
+    }
+    catch {
+        if (path) {
+            try {
+                writeFileSync(join(path, 'cgroup.kill'), '1');
+            }
+            catch { /* best effort */ }
+            try {
+                rmdirSync(path);
+            }
+            catch { /* best effort */ }
+        }
+        return null;
+    }
+}
+/** Join the cgroup before exec, so attacker-controlled code never runs outside the aggregate resource budget. */
+export function resourceLimitedCommand(cmd, args, procsFile) {
+    const setup = 'printf "%s" "$$" > "$1" || exit 126; shift; exec "$@"';
+    return { cmd: SYSTEM_SH, args: ['-c', setup, 'sh', procsFile, cmd, ...args] };
+}
+export function sandboxResourceLimitsAvailable() {
+    const group = createSandboxResourceGroup();
+    if (!group)
+        return false;
+    group.cleanup();
+    return true;
+}
 /** Wrap an (executable,args) in unprivileged namespaces per the requested isolation (pure — testable). */
 export function isolationCommand(bin, args, opts) {
+    if (opts.readOnlyFilesystem && !opts.writableTmpDir) {
+        throw new Error('read-only filesystem isolation requires writableTmpDir');
+    }
+    if (opts.readOnlyFilesystem && (!opts.readOnlyRoot || !opts.cwd)) {
+        throw new Error('read-only filesystem isolation requires readOnlyRoot and cwd');
+    }
     const flags = ['-r'];
-    if (opts.hideHomeSecrets)
+    if (opts.hideHomeSecrets || opts.readOnlyFilesystem)
         flags.push('-m');
     if (opts.noNetwork)
         flags.push('-n');
-    if (!opts.noNetwork && !opts.hideHomeSecrets)
+    if (opts.readOnlyFilesystem)
+        flags.push('-p', '-i', '-u');
+    if (!opts.noNetwork && !opts.hideHomeSecrets && !opts.readOnlyFilesystem)
         return { cmd: bin, args: [...args] };
-    const base = [...flags, '--fork', '--kill-child', '--'];
+    const base = [...flags, '--fork', '--kill-child', ...(opts.readOnlyFilesystem ? ['--mount-proc'] : []), '--'];
+    const setup = [
+        ...(opts.hideHomeSecrets && !opts.readOnlyFilesystem ? [HIDE_SECRETS_SETUP] : []),
+        ...(opts.readOnlyFilesystem ? [READ_ONLY_FILESYSTEM_SETUP] : []),
+        opts.readOnlyFilesystem ? DROP_NAMESPACE_PRIVILEGES : 'exec "$@"',
+    ].join('; ');
     // Mount setup needs a launcher (sh runs the FIXED script then exec "$@"); net-only needs no shell.
-    return opts.hideHomeSecrets
-        ? { cmd: 'unshare', args: [...base, 'sh', '-c', HIDE_SECRETS_SCRIPT, 'sh', bin, ...args] }
-        : { cmd: 'unshare', args: [...base, bin, ...args] };
+    return opts.hideHomeSecrets || opts.readOnlyFilesystem
+        ? {
+            cmd: SYSTEM_UNSHARE,
+            args: [...base, SYSTEM_SH, '-c', setup, 'sh', ...(opts.readOnlyFilesystem
+                    ? [opts.writableTmpDir, opts.readOnlyRoot, opts.cwd]
+                    : []), bin, ...args],
+        }
+        : { cmd: SYSTEM_UNSHARE, args: [...base, bin, ...args] };
 }
 let unshareCache;
 /** Whether unprivileged user+mount+net namespaces (`unshare -r -m -n`) work here (cached) — covers both isolation modes. */
 export function unshareNetAvailable() {
     if (unshareCache === undefined) {
         try {
-            unshareCache = spawnSync('unshare', ['-r', '-m', '-n', 'true'], { timeout: 5000 }).status === 0;
+            unshareCache = spawnSync(SYSTEM_UNSHARE, ['-r', '-m', '-n', 'true'], {
+                env: { PATH: TRUSTED_SYSTEM_PATH },
+                timeout: 5000,
+            }).status === 0;
         }
         catch {
             unshareCache = false;
@@ -78,28 +242,63 @@ export function makeSandboxRunner(opts = {}) {
         if (badFlag)
             return deny(`rejected: blocked node flag ${badFlag}`);
         // Isolation (#26): fail-safe — if we can't actually create the namespaces, refuse rather than run un-isolated.
-        if ((opts.noNetwork || opts.hideHomeSecrets) && !(opts.unshareCheck ?? unshareNetAvailable)()) {
-            return deny('rejected: isolation (noNetwork/hideHomeSecrets) requested but unprivileged namespaces (unshare -r -m -n) are unavailable here');
+        if ((opts.noNetwork || opts.hideHomeSecrets || opts.readOnlyFilesystem) && !(opts.unshareCheck ?? unshareNetAvailable)()) {
+            return deny('rejected: requested namespace isolation is unavailable');
         }
+        const resourceGroup = opts.resourceLimits
+            ? (opts.resourceGroupFactory ?? createSandboxResourceGroup)()
+            : null;
+        if (opts.resourceLimits && !resourceGroup)
+            return deny('rejected: cgroup v2 resource limits are unavailable');
         const ownTemp = !opts.cwd;
         let cwd;
         try {
             cwd = opts.cwd ?? mkdtempSync(join(tmpdir(), 'evo-sbx-'));
         }
         catch (e) {
+            resourceGroup?.cleanup();
             return deny(`temp dir failed: ${e instanceof Error ? e.message : 'err'}`, 1);
         }
-        const cleanup = () => { if (ownTemp) {
-            try {
-                rmSync(cwd, { recursive: true, force: true });
+        let cleaned = false;
+        const cleanup = () => {
+            if (cleaned)
+                return;
+            cleaned = true;
+            resourceGroup?.cleanup();
+            if (ownTemp) {
+                try {
+                    rmSync(cwd, { recursive: true, force: true });
+                }
+                catch { /* best effort */ }
             }
-            catch { /* best effort */ }
-        } };
+        };
         // Resolve 'node' to the running binary so spawn(shell:false) works on Windows too (where bare 'node' would ENOENT).
         const bin = isNodeExecutable(executable) ? process.execPath : executable;
         try {
-            const { cmd: spawnCmd, args: spawnArgs } = isolationCommand(bin, args, { noNetwork: opts.noNetwork, hideHomeSecrets: opts.hideHomeSecrets });
-            const child = spawn(spawnCmd, spawnArgs, { shell: false, cwd, env: scrubEnv(envAllow), timeout, killSignal: 'SIGKILL', stdio: ['ignore', 'pipe', 'pipe'] });
+            const { cmd: spawnCmd, args: spawnArgs } = isolationCommand(bin, args, {
+                noNetwork: opts.noNetwork,
+                hideHomeSecrets: opts.hideHomeSecrets,
+                readOnlyFilesystem: opts.readOnlyFilesystem,
+                writableTmpDir: opts.writableTmpDir,
+                readOnlyRoot: opts.readOnlyRoot ?? cwd,
+                cwd,
+            });
+            const env = scrubEnv(envAllow);
+            if (opts.noNetwork || opts.hideHomeSecrets || opts.readOnlyFilesystem || opts.resourceLimits) {
+                env['PATH'] = TRUSTED_SYSTEM_PATH;
+            }
+            if (opts.readOnlyFilesystem) {
+                Object.assign(env, { TMPDIR: '/tmp', TMP: '/tmp', TEMP: '/tmp' });
+            }
+            const limited = resourceGroup ? resourceLimitedCommand(spawnCmd, spawnArgs, resourceGroup.procsFile) : { cmd: spawnCmd, args: spawnArgs };
+            const child = spawn(limited.cmd, limited.args, {
+                shell: false,
+                cwd,
+                env,
+                timeout,
+                killSignal: 'SIGKILL',
+                stdio: [opts.readOnlyFilesystem ? 'pipe' : 'ignore', 'pipe', 'pipe'],
+            });
             let out = '';
             const cap = (d) => { if (out.length < MAX_OUTPUT_CHARS)
                 out += String(d); };

package/dist/verify/sandboxedValidation.d.ts

@@ -1,3 +1,4 @@
+import { type SandboxResourceGroup } from './sandboxRunner.js';
 import { type ValidationResult } from './validation.js';
 export interface SandboxedValidationSkippedCommand {
     cmd: string;
@@ -19,11 +20,19 @@ export interface SandboxedValidationResult {
      */
     isolated: boolean;
 }
+export declare function readOnlyFilesystemIsolationAvailable(): boolean;
+export declare function readOnlyIsolationAvailable(): boolean;
 export interface SandboxedValidationOptions {
     /** Per-command timeout (ms), forwarded to the sandbox runner. */
     timeoutMs?: number;
     /** Test seam: override the unprivileged-namespace availability probe. */
     unshareCheck?: () => boolean;
+    /** Refuse before spawning when network/home namespace isolation is unavailable. */
+    requireIsolation?: boolean;
+    /** Checkout root to preserve read-only at its original absolute path. */
+    readOnlyRoot?: string;
+    /** Injected cgroup allocator (test seam). */
+    resourceGroupFactory?: () => SandboxResourceGroup | null;
 }
 /**
  * Run validation commands in the hardened sandbox. Isolation (no-network + hidden home secrets) is requested only