@clear-capabilities/agentic-security-scanner 0.161.0 → 0.163.0

package/src/sandbox/control-probes.js

@@ -0,0 +1,215 @@
+// Active probes for every control the boundary relies on (CORE-003.AC02).
+//
+// A control is "proved" only when a probe ATTACKED it through the real
+// backend and the attack observably failed, AND a paired positive control
+// showed the same probe succeeds when the control is off (so a probe that can
+// never succeed cannot pass for a working control). An executable existing, a
+// flag being passed or an earlier run succeeding proves nothing here.
+//
+// States:
+//   proved       attack failed, positive control succeeded, both observed
+//   not-proved   the probe ran and the control did not hold, or the probe could
+//                not establish its own positive control
+//   unsupported  this backend does not implement the control at all
+//   unavailable  no confinement backend works on this host
+//   unverified   deliberately not probed; the reason says why (never a pass)
+//
+// The probes are generic, so on a Linux host they run against the namespace
+// backend for real. Nothing in this file asserts a Linux outcome in advance.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import { detectBackend } from './capabilities.js';
+import { runConfined } from './index.js';
+import { runConfinedSupervised } from './supervise.js';
+
+export const CONTROLS = Object.freeze([
+  'write-confinement', 'read-denial', 'env-scrub', 'network',
+  'tree-termination', 'file-size-limit', 'process-cap',
+]);
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const alive = (pid) => { try { process.kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; } };
+const NODE = process.execPath;
+
+function mk(prefix) { return fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), prefix))); }
+function rm(p) { try { fs.rmSync(p, { recursive: true, force: true }); } catch { /* best effort */ } }
+const proved = (evidence) => ({ state: 'proved', evidence });
+const notProved = (reason) => ({ state: 'not-proved', reason });
+
+function probeWrite() {
+  const root = mk('agsec-probe-w-'); const outside = mk('agsec-probe-wo-');
+  try {
+    const good = runConfined(['/bin/sh', '-c', 'echo x > "$ROOT/in.txt"'], { root });
+    const inOk = fs.existsSync(path.join(root, 'in.txt'));
+    runConfined(['/bin/sh', '-c', `echo x > '${outside}/escape.txt'; true`], { root });
+    const escaped = fs.existsSync(path.join(outside, 'escape.txt'));
+    if (!inOk) return notProved(`positive control failed: in-root write did not happen (${good.status})`);
+    if (escaped) return notProved('an out-of-root write succeeded');
+    return proved('in-root write succeeded; out-of-root write created no file');
+  } finally { rm(root); rm(outside); }
+}
+
+function probeReadDenial(backend) {
+  if (backend !== 'userspace') return { state: 'unsupported', reason: `read denial of host paths is not implemented on the ${backend} backend` };
+  const root = mk('agsec-probe-r-'); const secretDir = mk('agsec-probe-rs-');
+  try {
+    const secret = path.join(secretDir, 'sealed.txt');
+    const token = `SEALED-${crypto.randomBytes(8).toString('hex')}`;
+    fs.writeFileSync(secret, token);
+    const cmd = ['/bin/sh', '-c', `cat '${secret}' 2>&1; true`];
+    const open = runConfined(cmd, { root });
+    if (!open.stdout.includes(token)) return notProved('positive control failed: the probe could not read the canary even without denial');
+    const closed = runConfined(cmd, { root, denyReadPaths: [secretDir] });
+    if (closed.stdout.includes(token)) return notProved('a denied path was still readable');
+    return proved('canary readable without denial, unreadable with denyReadPaths');
+  } finally { rm(root); rm(secretDir); }
+}
+
+function probeEnv() {
+  const root = mk('agsec-probe-e-');
+  const name = 'AGSEC_PROBE_PARENT_CANARY';
+  const prev = process.env[name];
+  process.env[name] = 'parent-env-canary-value';
+  try {
+    const r = runConfined(['/usr/bin/env'], { root, env: { AGSEC_PROBE_EXPLICIT: 'explicit-ok' } });
+    if (!r.stdout.includes('AGSEC_PROBE_EXPLICIT=explicit-ok')) return notProved(`positive control failed: explicit env not visible (${r.status})`);
+    if (r.stdout.includes(name) || r.stdout.includes('parent-env-canary-value')) return notProved('the parent environment leaked into the target');
+    return proved('explicit variable visible, parent canary variable absent');
+  } finally {
+    if (prev === undefined) delete process.env[name]; else process.env[name] = prev;
+    rm(root);
+  }
+}
+
+async function probeNetwork() {
+  const root = mk('agsec-probe-n-');
+  let hits = 0;
+  const server = net.createServer((s) => { hits++; s.destroy(); });
+  try {
+    await new Promise((res, rej) => { server.once('error', rej); server.listen(0, '127.0.0.1', res); });
+    const port = server.address().port;
+    const script = `require('net').connect(${port},'127.0.0.1').on('error',()=>process.exit(0)).on('connect',()=>process.exit(0));setTimeout(()=>process.exit(0),1500)`;
+    runConfined([NODE, '-e', script], { root, timeoutMs: 6000, allowNetwork: true });
+    await sleep(200);
+    const open = hits;
+    if (open < 1) return notProved('positive control failed: loopback listener saw no connection with network allowed');
+    runConfined([NODE, '-e', script], { root, timeoutMs: 6000, allowNetwork: false });
+    await sleep(200);
+    if (hits > open) return notProved('a connection reached a loopback listener with network denied');
+    return proved('connection seen with network allowed, none with network denied');
+  } finally { server.close(); rm(root); }
+}
+
+async function probeTree() {
+  const root = mk('agsec-probe-t-');
+  try {
+    // Three tree shapes: a plain background child, a grandchild, and one that
+    // ignores SIGTERM and so needs the SIGKILL escalation.
+    const script = [
+      'sleep 300 & echo $! > "$ROOT/p1"',
+      '(sleep 300 & echo $! > "$ROOT/p2"; wait) &',
+      `(trap '' TERM; sleep 300 & echo $! > "$ROOT/p3"; while :; do sleep 1; done) &`,
+      'wait',
+    ].join('\n');
+    const r = await runConfinedSupervised(['/bin/sh', '-c', script], { root, timeoutMs: 1500, graceMs: 300 });
+    if (r.backend !== 'userspace' || !r.supervised) {
+      return { state: 'unsupported', reason: `supervised tree termination is not implemented on the ${r.backend} backend (${r.status})` };
+    }
+    const pids = ['p1', 'p2', 'p3'].map((f) => { try { return Number(fs.readFileSync(path.join(root, f), 'utf8')); } catch { return NaN; } });
+    if (pids.some((p) => !Number.isFinite(p))) return notProved('positive control failed: the probe tree did not start');
+    await sleep(100);
+    const live = pids.filter(alive);
+    for (const p of live) { try { process.kill(p, 'SIGKILL'); } catch { /* probe cleanup */ } }
+    if (live.length) return notProved(`processes survived the timeout: ${live.join(',')}`);
+    return proved('timeout ended a three-process tree including a SIGTERM-ignoring member');
+  } finally { rm(root); }
+}
+
+function probeFileSize() {
+  const root = mk('agsec-probe-f-');
+  try {
+    const cmd = ['/bin/sh', '-c', 'dd if=/dev/zero of="$ROOT/big" bs=1024 count=400 2>&1; true'];
+    runConfined(cmd, { root, limits: { maxFileSizeKb: 65536 } });
+    const full = fs.existsSync(path.join(root, 'big')) ? fs.statSync(path.join(root, 'big')).size : 0;
+    if (full < 400 * 1024) return notProved('positive control failed: the unrestricted write did not complete');
+    fs.rmSync(path.join(root, 'big'));
+    runConfined(cmd, { root, limits: { maxFileSizeKb: 16 } });
+    const capped = fs.existsSync(path.join(root, 'big')) ? fs.statSync(path.join(root, 'big')).size : 0;
+    if (capped >= 400 * 1024) return notProved('the file size limit did not stop a large write');
+    return proved(`400 KiB write completed unrestricted and stopped at ${capped} bytes under a 16 KiB limit`);
+  } finally { rm(root); }
+}
+
+const UNPROBED_PROCESS_CAP = {
+  state: 'unverified',
+  reason: 'a process-count cap is per-uid and system-wide on macOS (a soft brake, not a wall) and did not refuse on the hosted Linux runner in the last release; no enforcement is claimed on any backend',
+};
+
+const _cache = new Map();
+export function resetProbeCache() { _cache.clear(); }
+
+/**
+ * Probe every control on the active backend.
+ * @param {object} [o]
+ * @param {string} [o.force]   backend override (same meaning as runConfined's)
+ * @param {object} [o.probes]  per-control probe overrides (test seam). A probe
+ *                             may only make the report MORE restrictive in
+ *                             practice, since the boundary consults the report
+ *                             before any run; it cannot make a run unconfined.
+ */
+export async function probeControls({ force, probes = {} } = {}) {
+  const backend = detectBackend({ force });
+  const key = `${backend}:${Object.keys(probes).sort().join(',')}`;
+  if (!Object.keys(probes).length && _cache.has(backend)) return _cache.get(backend);
+
+  const controls = {};
+  if (backend === 'disabled') {
+    for (const c of CONTROLS) controls[c] = { state: 'unavailable', reason: 'no confinement backend works on this host' };
+  } else {
+    const run = async (name, fn) => {
+      if (probes[name]) { controls[name] = await probes[name](); return; }
+      try { controls[name] = await fn(); } catch (e) { controls[name] = notProved(`probe threw: ${e.message}`); }
+    };
+    await run('write-confinement', probeWrite);
+    await run('read-denial', () => probeReadDenial(backend));
+    await run('env-scrub', probeEnv);
+    await run('network', probeNetwork);
+    await run('tree-termination', probeTree);
+    await run('file-size-limit', probeFileSize);
+    controls['process-cap'] = probes['process-cap'] ? await probes['process-cap']() : UNPROBED_PROCESS_CAP;
+  }
+  const report = { platform: process.platform, backend, controls };
+  if (!Object.keys(probes).length) _cache.set(backend, report);
+  void key;
+  return report;
+}
+
+/** Controls from `required` that are not proved, with the reason for each. */
+export function unmetControls(report, required) {
+  const out = [];
+  for (const c of required) {
+    const v = report?.controls?.[c];
+    if (!v || v.state !== 'proved') out.push({ control: c, state: v?.state ?? 'not-probed', reason: v?.reason ?? 'no probe result' });
+  }
+  return out;
+}
+
+/**
+ * Human-readable capability matrix. States what each control is on this host
+ * and carries the standing disclosure that Linux enforcement is only evidenced
+ * where the hosted `sandbox-linux` job actually ran.
+ */
+export function capabilityReport(report) {
+  return {
+    ...report,
+    advertisedIsolationBackends: ['userspace (macOS family)', 'namespace (Linux family)'],
+    notes: [
+      'A state of proved was established by an active probe on THIS host in THIS process; it is not inherited from another platform.',
+      'Linux enforcement cannot be exercised on a macOS host. It is evidenced only where the sandbox-linux CI job ran this same probe set.',
+      'Process-count caps are not claimed enforced on any backend.',
+    ],
+  };
+}

package/src/sandbox/supervise.js

@@ -0,0 +1,201 @@
+// Supervised execution: every process the target starts, and all of its
+// descendants, end when the run ends (CORE-003.AC02).
+//
+// `spawnSync`'s timeout signals only the direct child (see CLAUDE.md, "Timeout
+// does not kill the process tree"). This module is the repair for the backends
+// where it can be proved:
+//
+//   1. The child starts in its own process group and session (`detached`), so
+//      one signal to the negative pid reaches every member that did not move.
+//   2. While it runs, the process table is swept on a short interval and every
+//      descendant seen is remembered, so a member that left the group (for
+//      example via setsid) while its parent was still alive is still killed.
+//   3. Termination is SIGTERM to the group and the tracked set, a grace period,
+//      then SIGKILL, then a poll that CONFIRMS nothing is left. Survivors are
+//      reported, never assumed away.
+//   4. The same cleanup runs on a normal exit, so a backgrounded grandchild
+//      cannot outlive a run that "succeeded".
+//
+// KNOWN GAP (not hidden): a descendant that double-forks and calls setsid
+// between two sweeps, with its parent exiting before the next sweep, is
+// reparented away from the tree and is not found. The sweep interval bounds the
+// window; it does not close it. Only a PID-namespace or cgroup boundary closes
+// it, and neither is available on the macOS backend.
+import { spawn, spawnSync } from 'node:child_process';
+import { detectBackend } from './capabilities.js';
+import { runDisabled } from './backend-disabled.js';
+import { buildUserspaceInvocation } from './backend-userspace.js';
+import { buildResult, errorResult } from './result.js';
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+function alive(pid) {
+  try { process.kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; }
+}
+function groupAlive(pgid) {
+  try { process.kill(-pgid, 0); return true; } catch (e) { return e.code === 'EPERM'; }
+}
+function signalPid(pid, sig) { try { process.kill(pid, sig); } catch { /* already gone */ } }
+function signalGroup(pgid, sig) { try { process.kill(-pgid, sig); } catch { /* already gone */ } }
+
+/** Descendants of `rootPid` plus members of its group, from one `ps` snapshot. */
+function snapshotTree(rootPid) {
+  const r = spawnSync('ps', ['-A', '-o', 'pid=,ppid=,pgid='], { encoding: 'utf8', timeout: 2000 });
+  if (r.error || r.status !== 0) return [];
+  const rows = [];
+  for (const line of String(r.stdout).split('\n')) {
+    const m = line.trim().split(/\s+/).map(Number);
+    if (m.length === 3 && m.every(Number.isFinite)) rows.push({ pid: m[0], ppid: m[1], pgid: m[2] });
+  }
+  const kids = new Map();
+  for (const x of rows) { if (!kids.has(x.ppid)) kids.set(x.ppid, []); kids.get(x.ppid).push(x.pid); }
+  const found = new Set();
+  const queue = [rootPid];
+  while (queue.length) {
+    const p = queue.pop();
+    for (const c of kids.get(p) || []) if (!found.has(c)) { found.add(c); queue.push(c); }
+  }
+  for (const x of rows) if (x.pgid === rootPid && x.pid !== process.pid) found.add(x.pid);
+  return [...found];
+}
+
+function _emptyTermination() { return { signalled: null, killedPids: [], survivors: [] }; }
+
+/**
+ * Spawn `bin args` as a supervised process tree.
+ * @returns {Promise<object>} never rejects.
+ */
+export function superviseSpawn(bin, args, {
+  cwd, env, timeoutMs = 10000, graceMs = 1000, signal, maxOutputBytes = 8 * 1024 * 1024, sweepMs = 100,
+} = {}) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(bin, args, { cwd, env, detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (e) {
+      resolve({ spawnError: e.message, exitCode: null, stdout: '', stderr: '', timedOut: false, cancelled: false, outputCapped: false, termination: _emptyTermination() });
+      return;
+    }
+    const pgid = child.pid;
+    const tracked = new Set();
+    let stdout = '', stderr = '', outBytes = 0;
+    let timedOut = false, cancelled = false, outputCapped = false, spawnError = null;
+    let exitCode = null, exitSignal = null;
+    let finishing = null;
+    let timer = null;
+
+    const sweep = () => { if (pgid) for (const p of snapshotTree(pgid)) tracked.add(p); };
+    const sweeper = setInterval(sweep, sweepMs);
+
+    const survivors = () => {
+      sweep();
+      return { live: [...tracked].filter(alive), group: groupAlive(pgid) };
+    };
+
+    async function terminate() {
+      const t = _emptyTermination();
+      const before = survivors();
+      if (!before.group && before.live.length === 0) return t;
+      t.signalled = 'SIGTERM';
+      signalGroup(pgid, 'SIGTERM');
+      for (const p of tracked) signalPid(p, 'SIGTERM');
+      const deadline = Date.now() + graceMs;
+      while (Date.now() < deadline) {
+        const s = survivors();
+        if (!s.group && s.live.length === 0) return t;
+        await sleep(25);
+      }
+      // Grace expired: SIGKILL cannot be ignored. Repeat until nothing is left,
+      // because a dying process can fork once more before it is reaped.
+      t.signalled = 'SIGKILL';
+      const hard = Date.now() + 3000;
+      while (Date.now() < hard) {
+        const s = survivors();
+        if (!s.group && s.live.length === 0) break;
+        signalGroup(pgid, 'SIGKILL');
+        for (const p of s.live) { signalPid(p, 'SIGKILL'); if (!t.killedPids.includes(p)) t.killedPids.push(p); }
+        await sleep(25);
+      }
+      const s = survivors();
+      t.survivors = s.live.length ? s.live : (s.group ? [-pgid] : []);
+      return t;
+    }
+
+    function finish() {
+      if (finishing) return finishing;
+      finishing = (async () => {
+        clearInterval(sweeper); clearTimeout(timer);
+        const termination = await terminate();
+        try { child.stdout?.destroy(); child.stderr?.destroy(); } catch { /* ignore */ }
+        resolve({ spawnError, exitCode, exitSignal, stdout, stderr, timedOut, cancelled, outputCapped, termination });
+      })();
+      return finishing;
+    }
+
+    const collect = (which) => (d) => {
+      outBytes += d.length;
+      if (outBytes > maxOutputBytes) {
+        if (!outputCapped) { outputCapped = true; finish(); }
+        return;
+      }
+      if (which === 'out') stdout += d.toString('utf8'); else stderr += d.toString('utf8');
+    };
+    child.stdout.on('data', collect('out'));
+    child.stderr.on('data', collect('err'));
+    child.on('error', (e) => { spawnError = e.message; finish(); });
+    child.on('exit', (code, sig) => {
+      exitCode = code; exitSignal = sig;
+      // Let buffered output drain, then clean up any survivors.
+      setTimeout(finish, 50);
+    });
+    timer = setTimeout(() => { timedOut = true; finish(); }, timeoutMs);
+    if (signal) {
+      if (signal.aborted) { cancelled = true; finish(); }
+      else signal.addEventListener('abort', () => { cancelled = true; finish(); }, { once: true });
+    }
+  });
+}
+
+/**
+ * `runConfined`, plus a guarantee about the process tree. Same result shape as
+ * every backend, with extra `cancelled`, `outputCapped`, `termination` and
+ * `supervised: true`. Never throws.
+ *
+ * Backend coverage, stated plainly:
+ *   userspace  supervised (verified by execution on macOS)
+ *   namespace  REFUSED: tree termination has not been implemented and executed
+ *              on the kernel-namespace backend, so the run does not happen
+ *   disabled   refused, as always
+ */
+export async function runConfinedSupervised(argv, opts = {}) {
+  const backend = detectBackend({ force: opts.force });
+  if (backend === 'disabled') return runDisabled(argv, opts);
+  if (backend !== 'userspace') {
+    return errorResult(backend, `process-tree termination is not implemented or verified on the ${backend} backend; refusing to execute`);
+  }
+  const inv = buildUserspaceInvocation(argv, opts);
+  if (inv.error) return inv.error;
+  const r = await superviseSpawn(inv.bin, inv.args, {
+    cwd: inv.cwd, env: inv.env, timeoutMs: opts.timeoutMs ?? 10000, graceMs: opts.graceMs ?? 1000,
+    signal: opts.signal, maxOutputBytes: opts.maxOutputBytes,
+  });
+  const res = buildResult({
+    backend: 'userspace',
+    spawnResult: {
+      status: r.exitCode,
+      stdout: r.stdout,
+      stderr: r.stderr,
+      error: r.timedOut ? { code: 'ETIMEDOUT' } : r.spawnError ? { code: 'SPAWN', message: r.spawnError } : null,
+    },
+    unsupported: inv.unsupported,
+  });
+  let status = res.status;
+  let stderr = res.stderr;
+  if (r.cancelled) status = 'cancelled';
+  if (r.outputCapped) { status = 'error'; stderr += '\n[sandbox] output cap exceeded; process tree terminated'; }
+  if (r.termination.survivors.length) { status = 'error'; stderr += '\n[sandbox] processes survived termination'; }
+  return {
+    ...res, status, stderr, cancelled: r.cancelled, outputCapped: r.outputCapped,
+    supervised: true, termination: r.termination,
+  };
+}

package/src/sandbox/trust-boundary.js

@@ -0,0 +1,113 @@
+// The execution boundary between target/worker code and the verifier
+// (CORE-003). Every verifier-side execution of untrusted code goes through
+// `runInBoundary`; it is where the trust domains are ENFORCED rather than
+// described.
+//
+// Order of operations, and why each step exists:
+//   1. Refuse secret material in the environment bound for the target.
+//   2. Refuse a workspace that overlaps a protected path (a root that CONTAINS
+//      the key directory would hand the target the keys by construction).
+//   3. Probe the backend's controls actively (cached per process). Any required
+//      control that is not `proved` makes the result `blocked` and NOTHING runs.
+//      Insufficient isolation is never a pass and never a warning.
+//   4. Run supervised, with protected paths read-denied, a scrubbed environment
+//      and a process-tree deadline.
+//   5. Report. The status is formed from what the boundary observed, never from
+//      what the target printed; target output is returned labelled untrusted.
+import fs from 'node:fs';
+import path from 'node:path';
+import { detectBackend } from './capabilities.js';
+import { runConfinedSupervised } from './supervise.js';
+import { probeControls, unmetControls } from './control-probes.js';
+import {
+  protectedReadPaths, assertNoSecretMaterial, classifyRun, countStatusLikeLines,
+} from './trust-domains.js';
+
+export const DEFAULT_REQUIRED_CONTROLS = Object.freeze([
+  'write-confinement', 'read-denial', 'env-scrub', 'tree-termination', 'file-size-limit',
+]);
+
+function _real(p) { try { return fs.realpathSync(p); } catch { return path.resolve(p); } }
+function _overlaps(a, b) {
+  const x = _real(a), y = _real(b);
+  return x === y || x.startsWith(y + path.sep) || y.startsWith(x + path.sep);
+}
+
+function _blocked(reasons, extra = {}) {
+  return {
+    status: 'blocked', blocked: true, executed: false, denied: false, reasons,
+    verificationStatus: 'not-run', targetOutput: null, ...extra,
+  };
+}
+
+/**
+ * @param {string[]} argv
+ * @param {object}   o
+ * @param {string}   o.root          the target's only writable directory
+ * @param {string[]} [o.labelDirs]     sealed-label directories (read-denied)
+ * @param {string[]} [o.evidenceDirs]  authoritative-evidence directories (read-denied, and write-denied by confinement)
+ * @param {string[]} [o.denyReadPaths] further host paths to read-deny
+ * @param {object}   [o.env]           explicit variables for the target; secret-looking ones are refused
+ * @param {string[]} [o.require]       controls that must be `proved`
+ * @param {string}   [o.home]          home directory whose credential dirs are denied
+ * @param {boolean}  [o.allowNetwork]
+ * @param {AbortSignal} [o.signal]     cancel
+ * @param {object}   [o.controlProbes] probe overrides (test seam)
+ */
+export async function runInBoundary(argv, o = {}) {
+  const {
+    root, labelDirs = [], evidenceDirs = [], denyReadPaths = [], env = {},
+    allowNetwork = false, timeoutMs = 10000, graceMs = 1000, signal, force, limits,
+    maxOutputBytes, controlProbes,
+  } = o;
+  const required = [...(o.require || DEFAULT_REQUIRED_CONTROLS)];
+  if (!allowNetwork && !required.includes('network')) required.push('network');
+
+  if (!root || typeof root !== 'string') return _blocked(['no workspace root']);
+  const backend = detectBackend({ force });
+  if (backend === 'disabled') {
+    return _blocked(['no confinement backend works on this host; the target was not executed'], { backend });
+  }
+
+  const secrets = assertNoSecretMaterial(env);
+  if (!secrets.ok) {
+    return _blocked([`secret-looking variables refused for the target: ${secrets.offenders.join(', ')}`], { backend });
+  }
+
+  const protectedPaths = protectedReadPaths({
+    ...(o.home ? { home: o.home } : {}), labelDirs, evidenceDirs, extra: denyReadPaths,
+  });
+  const clash = protectedPaths.filter((p) => _overlaps(root, p));
+  if (clash.length) {
+    return _blocked([`the workspace overlaps protected path(s): ${clash.join(', ')}`], { backend });
+  }
+
+  const report = await probeControls({ force, probes: controlProbes || {} });
+  const unmet = unmetControls(report, required);
+  if (unmet.length) {
+    return _blocked(
+      unmet.map((u) => `control '${u.control}' is ${u.state}: ${u.reason}`),
+      { backend, controls: report.controls },
+    );
+  }
+
+  const r = await runConfinedSupervised(argv, {
+    root, timeoutMs, graceMs, signal, force, allowNetwork, limits, maxOutputBytes,
+    env, denyReadPaths: protectedPaths,
+  });
+  const executed = r.status !== 'disabled' && !(r.status === 'error' && !r.supervised);
+  const run = { ...r, executed };
+  return {
+    status: r.status, blocked: false, executed, denied: r.denied, backend: r.backend,
+    reasons: [], controls: report.controls,
+    verificationStatus: classifyRun(run),
+    // Target output is DATA. It is capped and labelled; it is never parsed for
+    // a status. The count below is informational only.
+    targetOutput: {
+      trust: 'untrusted', stdout: r.stdout, stderr: r.stderr,
+      statusLikeLines: countStatusLikeLines(r.stdout) + countStatusLikeLines(r.stderr),
+    },
+    exitCode: r.exitCode, timedOut: r.timedOut, cancelled: !!r.cancelled,
+    outputCapped: !!r.outputCapped, termination: r.termination,
+  };
+}