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

package/src/posture/verification/patch-negative.js

@@ -27,6 +27,10 @@
 //   environment-mismatch         the runs were not in equivalent environments
 //   promotion-refused            the receipts do not match the exact proposed diff and revision
 //
+// The behaviour check is the functional-regression oracle by default. A requester may name `business-state` as `functional.oracleId`
+// (X-406, `invariants/repair.js`): the same two runs and the same expectation, with an authorized-workflow scenario as the declared
+// case, and `promotePatch` then requires the functional receipts to come from that oracle class instead.
+//
 // Scope, stated so no caller overclaims: the exploit scenario and the functional cases are the REQUESTER's; this verifies the
 // declared scenario and cases, not that the patch is correct elsewhere. Linux is not claimed (the oracle platform statements
 // stay `unverified`). Receipts are valid inside this process only (see patch-promotion.js).
@@ -40,6 +44,9 @@ import { appendRepairRecord, recordPromotion, verificationRepairFor, withRepairS
 
 const PATCH_NEGATIVE_FEATURE = 'patch-negative-verification';
 const FUNCTIONAL_ORACLE = 'functional-regression';
+// The check that behaviour is preserved is normally the functional-regression oracle. A requester may name `business-state`
+// instead (X-406): the same two runs, the same expectation (refuted), with an authorized-workflow scenario as the declared case.
+const FUNCTIONAL_ORACLES = Object.freeze([FUNCTIONAL_ORACLE, 'business-state']);
 
 const STEPS = Object.freeze(['original-positive', 'patched-negative', 'functional-baseline', 'functional-regression']);
 
@@ -64,7 +71,8 @@ function classify(step, run) {
   }
   const outcome = run.outcome;
   const observed = run.receipt?.observed || {};
-  const loadBroken = observed.targetLoaded === false || observed.benignCompleted === false;
+  // a business-state run reports its control flow under `preconditions`: a control flow that no longer works is a broken revision
+  const loadBroken = observed.targetLoaded === false || observed.benignCompleted === false || observed.preconditions?.controlRan === false || observed.preconditions?.controlDurableEffect === false;
   if (outcome === 'error') return { status: 'incomplete', code: 'harness-error', reason: String(run.record?.reason || 'the oracle run failed').slice(0, 300), outcome };
   if (outcome === EXPECTED[step]) return { status: 'passed', code: null, reason: run.record?.reason ?? null, outcome };
   const reason = String(run.record?.reason || '').slice(0, 300);
@@ -150,6 +158,10 @@ export async function verifyPatchNegative(req, o = {}) {
   if (!isPlainObject(fn) || !isPlainObject(fn.inputs)) {
     return refuse('functional-regression', 'functional-omitted', 'no functional regression check was supplied: a patch that was never checked for behaviour cannot be a verified fix');
   }
+  const functionalOracle = fn.oracleId === undefined ? FUNCTIONAL_ORACLE : fn.oracleId;
+  if (!FUNCTIONAL_ORACLES.includes(functionalOracle)) {
+    return refuse('input-validation', 'bad-request', `the functional check oracle must be one of ${FUNCTIONAL_ORACLES.join(', ')}`);
+  }
 
   const patchDigest = digestOf(patchFiles);
   base.patchDigest = patchDigest;
@@ -158,8 +170,8 @@ export async function verifyPatchNegative(req, o = {}) {
   const plan = [
     ['original-positive', { oracleId: original.oracleId, entry: original.entry, inputs: original.inputs, patchFiles: null, budgets: original.budgets }],
     ['patched-negative', { oracleId: original.oracleId, entry: original.entry, inputs: original.inputs, patchFiles, budgets: original.budgets }],
-    ['functional-baseline', { oracleId: FUNCTIONAL_ORACLE, entry: original.entry, inputs: fn.inputs, patchFiles: null, budgets: fn.budgets }],
-    ['functional-regression', { oracleId: FUNCTIONAL_ORACLE, entry: original.entry, inputs: fn.inputs, patchFiles, budgets: fn.budgets }],
+    ['functional-baseline', { oracleId: functionalOracle, entry: original.entry, inputs: fn.inputs, patchFiles: null, budgets: fn.budgets }],
+    ['functional-regression', { oracleId: functionalOracle, entry: original.entry, inputs: fn.inputs, patchFiles, budgets: fn.budgets }],
   ];
   const runs = {};
   let failed = null;
@@ -186,7 +198,7 @@ export async function verifyPatchNegative(req, o = {}) {
 
   // ---- the receipts must match the exact proposed diff and revision before anything is promoted
   const receipts = Object.fromEntries(Object.entries(runs).map(([k, r]) => [k, r.receipt]));
-  const promotion = promotePatch({ proposal: { hypothesisId: req.hypothesisId, revision: req.commit, originalFiles: original.files, patchFiles }, receipts });
+  const promotion = promotePatch({ proposal: { hypothesisId: req.hypothesisId, revision: req.commit, originalFiles: original.files, patchFiles, functionalOracle }, receipts });
   if (!promotion.ok) {
     const envBroken = promotion.reasons.some((r) => r.code === 'environment-mismatch');
     const code = envBroken ? 'environment-mismatch' : promotion.reasons.some((r) => r.code === 'oracle-changed') ? 'oracle-changed' : 'promotion-refused';

package/src/posture/verification/patch-promotion.js

@@ -23,6 +23,9 @@ import { isCommit, isPlainObject } from '../assurance/schema-kit.js';
 import { isIssuedReceipt } from '../oracles/oracle.js';
 
 const PROMOTION_ROLES = Object.freeze(['original', 'patched', 'functionalBaseline', 'functional']);
+// The oracle class the behaviour-preservation runs must come from. Default `functional-regression`; a proposal may name
+// `business-state` (X-406: an authorized-workflow scenario as the declared case). Nothing else is accepted.
+const FUNCTIONAL_CLASSES = Object.freeze({ 'functional-regression': 'functional-regression', 'business-state': 'business-state' });
 
 const ISSUED_PROMOTIONS = new WeakSet();
 
@@ -36,7 +39,7 @@ const same = (a, b) => digestOf(a ?? null) === digestOf(b ?? null);
 
 /**
  * @param {object} args
- * @param {object} args.proposal  { hypothesisId, revision, originalFiles, patchFiles }
+ * @param {object} args.proposal  { hypothesisId, revision, originalFiles, patchFiles, functionalOracle? }
  * @param {object} args.receipts  { original, patched, functionalBaseline, functional }, each issued by runOracle
  * @returns {{ ok: boolean, diffDigest: string|null, revision: string|null, reasons: {code,role,message}[], receiptDigests: object }}
  */
@@ -59,6 +62,11 @@ export function promotePatch({ proposal, receipts } = {}) {
     why('revision-unbound', null, 'a promotion is bound to one exact 40 or 64 character commit; none was given');
     return out();
   }
+  const functionalClass = proposal.functionalOracle === undefined ? 'functional-regression' : FUNCTIONAL_CLASSES[proposal.functionalOracle];
+  if (!functionalClass) {
+    why('bad-proposal', null, 'the functional check oracle must be functional-regression or business-state');
+    return out();
+  }
   const diffDigest = digestOf(proposal.patchFiles);
   const originalDigest = digestOf(proposal.originalFiles);
   const patchedDigest = digestOf({ ...proposal.originalFiles, ...proposal.patchFiles });
@@ -92,7 +100,7 @@ export function promotePatch({ proposal, receipts } = {}) {
   if (!same(functionalBaseline.oracle, functional.oracle) || functionalBaseline.request.inputsDigest !== functional.request.inputsDigest) {
     why('oracle-changed', 'functional', 'the functional check on the patched revision did not use the same oracle and cases as its baseline');
   }
-  if (functional.oracle.class !== 'functional-regression') why('oracle-changed', 'functional', 'the functional check is not a functional-regression oracle');
+  if (functional.oracle.class !== functionalClass) why('oracle-changed', 'functional', `the functional check is not a ${functionalClass} oracle`);
   if (original.oracle.class === 'functional-regression') why('oracle-changed', 'original', 'the exploit oracle must not be the functional-regression oracle');
   // equivalent disposable environments: one sanitized environment identity across every run
   const envDigest = digestOf(original.environment);

package/src/report/index.js

@@ -4,6 +4,7 @@ import { _isCustomSuppressed } from '../engine.js';
 import { alertFace, approveFace } from './mascot.js';
 import { SCANNER_VERSION } from '../posture/version.js';
 import { proofBlock } from '../posture/proof-artifact.js';
+import { portfolioAssuranceEnabled, scanVerdictWording, NOT_A_GUARANTEE } from '../posture/portfolio/wording.js';
 import { applyLegacyCompat, legacyFieldDeprecationNotice } from '../pipeline/legacy-compat.js';
 // Finding Provenance (M0/M1). NOTE the name: `findingProvenance` is the
 // git-origin record from posture/provenance/. It is NOT `finding.provenance`
@@ -14,8 +15,11 @@ import { applyLegacyCompat, legacyFieldDeprecationNotice } from '../pipeline/leg
 import { redactFindingProvenance, sanitizeForTerminal } from '../posture/provenance/schema.js';
 // X-206: the one projection of the verification record. This report, the MCP tools and the autopilot response all call it.
 import { verificationFields, verificationCoverage } from '../posture/verification/projection.js';
+import { invariantCoverageFields } from '../posture/invariants/coverage.js';
 // X-207: a hunt hypothesis is advisory and is never a finding in any gating output; promotion is the only way across.
 import { isAdvisoryHypothesis } from '../posture/verification/advisory-state.js';
+// X-307: the one projection of the deployment boundary context. Additive and present only when a finding carries a context.
+import { boundaryFields, boundaryCoverage } from '../lineage/deployment/projection.js';
 // Re-exported: FR-PROV-026. Lives in provenance/schema.js (shared with
 // posture/auditor-walkthrough.js, a second CLI renderer of the same
 // untrusted fields — see that module's header for why it lives there
@@ -341,6 +345,11 @@ export function normalizeFindings(scan){
       ...(f.verificationRecord && typeof f.verificationRecord === 'object'
         ? { verificationRecord: f.verificationRecord, ...(f.verificationReplay ? { verificationReplay: f.verificationReplay } : {}), ...verificationFields(f.verificationRecord, { replay: f.verificationReplay }) }
         : {}),
+      // X-307: the deployment boundary context and its projection, ADDITIVE and present only when a producer (the
+      // `deployment-boundaries` feature) attached one. A plain scan output is byte-identical.
+      ...(f.boundaryContext && typeof f.boundaryContext === 'object'
+        ? boundaryFields(f.boundaryContext)
+        : {}),
       // Phase-1 next-gen P1.3 (FR-UX-1, FR-UX-2): calibrated probability +
       // 95% Wilson CI + sample size. Null when N < MIN_SAMPLES_FOR_CALIBRATION
       // for this family; `calibration_reason` explains why.
@@ -753,6 +762,10 @@ export function toJSON(scan, meta={}, opts={}){
     // X-206: trusted-negative accounting over the findings that carry a verification record. Absent when none does, so a plain
     // scan's output is unchanged.
     ...(findings.some(f => f.verificationRecord) ? { verificationCoverage: verificationCoverage(findings.map(f => f.verificationRecord).filter(Boolean)) } : {}),
+    // X-307: boundary accounting over the findings that carry a context; absent when none does.
+    ...(findings.some(f => f.boundaryContext) ? { boundaryCoverage: boundaryCoverage(findings.map(f => f.boundaryContext).filter(Boolean)) } : {}),
+    // X-407: bounded business-logic coverage, when a caller attached one AND the invariant-scenarios feature is on (off by default).
+    ...invariantCoverageFields(scan.invariantCoverage),
   };
   if (opts.includeSuppressed) out.suppressed = scan.suppressions||[];
   return out;
@@ -932,6 +945,15 @@ export function verificationBlock(f) {
   return Array.isArray(text) && text.length ? text.map((l) => String(l).match(/^ */)[0] + sanitizeForTerminal(String(l))) : null;
 }
 
+/**
+ * X-307: the human-readable boundary block for a normalized finding, from the SAME projection the JSON and MCP surfaces carry.
+ * Null when the finding has no boundary context. Terminal control characters are stripped.
+ */
+export function boundaryBlock(f) {
+  const text = f?.boundaryView?.text;
+  return Array.isArray(text) && text.length ? text.map((l) => String(l).match(/^ */)[0] + sanitizeForTerminal(String(l))) : null;
+}
+
 export function toMarkdown(scan, meta={}){
   const findings = normalizeFindings(scan);
   const lines = ['# Agentic Security — Scan Report', ''];
@@ -981,6 +1003,23 @@ export function toMarkdown(scan, meta={}){
       }
       lines.push('</details>');
     }
+    // X-307: boundary blocks come from the shared projection, never a second renderer.
+    const withBoundary = bySev[sev].filter(f => boundaryBlock(f));
+    if (withBoundary.length) {
+      lines.push('');
+      lines.push('<details><summary>Deployment boundaries</summary>');
+      lines.push('');
+      for (const f of withBoundary) {
+        const block = boundaryBlock(f).join('\n');
+        lines.push(`**\`${f.file}:${f.line}\`**: ${f.vuln}`);
+        const fence = '`'.repeat(_mdFenceLen(block));
+        lines.push(fence);
+        lines.push(block);
+        lines.push(fence);
+        lines.push('');
+      }
+      lines.push('</details>');
+    }
     // FR-PROV-018: one provenance block per finding that has one, reusing
     // explainProvenance's content — never a second, divergent renderer.
     const withProvenance = bySev[sev].filter(f => f.findingProvenance);
@@ -1480,6 +1519,8 @@ export function toCLI(scan, { verbose=false, color=true, provenance=false }={}){
     if (ex.fixCode) for (const ln of ex.fixCode.split('\n').slice(0, 6)) lines.push(`           ${c(ln, DIM)}`);
     const vblock = verificationBlock(f);
     if (vblock) for (const ln of vblock) lines.push(`        ${c(ln, DIM)}`);
+    const bblock = boundaryBlock(f);
+    if (bblock) for (const ln of bblock) lines.push(`        ${c(ln, DIM)}`);
     if (provenance) {
       // `f` here is already normalized, so its findingProvenance has been
       // through redactFindingProvenance — the email is gone before it can
@@ -1492,6 +1533,8 @@ export function toCLI(scan, { verbose=false, color=true, provenance=false }={}){
   const counts = { critical: 0, high: 0, medium: 0, low: 0, info: 0 };
   for (const f of findings) counts[f.severity] = (counts[f.severity]||0) + 1;
   if (findings.some(f => f.verificationRecord)) lines.push(verificationCoverage(findings.map(f => f.verificationRecord).filter(Boolean)).lines[0]);
+  if (findings.some(f => f.boundaryContext)) lines.push(boundaryCoverage(findings.map(f => f.boundaryContext).filter(Boolean)).lines[0]);
+  { const ic = invariantCoverageFields(scan.invariantCoverage); if (ic.invariantCoverage) lines.push(...ic.invariantCoverage.lines); }
   lines.push(`${c('Critical:', SEV_COLOR.critical)} ${counts.critical}    ${c('High:', SEV_COLOR.high)} ${counts.high}    ${c('Medium:', SEV_COLOR.medium)} ${counts.medium}    ${c('Low:', SEV_COLOR.low)} ${counts.low}    ${c('Info:', SEV_COLOR.info)} ${counts.info}`);
   return lines.join('\n');
 }
@@ -1616,7 +1659,14 @@ export function toShipVerdict(scan, options = {}) {
   const clean = actionable.length === 0 && !scanIncomplete;
   lines.push(clean ? approveFace({ color }) : alertFace({ color }));
   lines.push(bar);
-  if (clean) {
+  // X-703.AC03: with the `portfolio-assurance` feature on, the headline is the bounded claim followed by scope and gaps. Off
+  // (the default) the wording below is unchanged, because existing output and documentation pin it.
+  const _bounded = portfolioAssuranceEnabled({ option: options.portfolioAssurance, scanRoot: options.scanRoot });
+  if (_bounded) {
+    const w = scanVerdictWording({ clean, scanIncomplete: !!scanIncomplete, actionableCount: actionable.length });
+    lines.push(c(`  ${w.icon}  ${w.headline}`, w.tier === 'ok' ? SEV_COLOR.low + BOLD : w.tier === 'incomplete' ? SEV_COLOR.high + BOLD : SEV_COLOR.critical + BOLD));
+    lines.push(c(`  Scope: completed supported checks only${scanIncomplete ? '; gaps listed below' : '; no gaps recorded by scan health'}. ${NOT_A_GUARANTEE}`, DIM));
+  } else if (clean) {
     lines.push(c('  ✅  Safe to deploy', SEV_COLOR.low + BOLD));
   } else if (actionable.length === 0) {
     lines.push(c('  ⚠️  Scan incomplete — cannot confirm safe to deploy', SEV_COLOR.high + BOLD));

package/src/sandbox/CLAUDE.md

@@ -388,6 +388,16 @@ then runs supervised with protected paths read-denied.
 - Tests: `test/trust-boundary.test.js` (attack fixture, tree kill with `ps`
   orphan checks, blocked-never-pass), in `test:lifecycle`.
 
+## Capability mode (X-502, X-504)
+
+`backend-userspace.js` has an opt-in mode used by `capabilities/runner.js`; every pre-existing caller passes none of these options and gets the profile it always had.
+
+- `readRoots` (array): reads are confined to a fixed baseline of system paths (loader, libraries, locale, timezone, device nodes), the sandbox root, the write roots and these roots. File metadata is granted only for the ancestors of those roots, so a path outside them cannot be probed for existence. `denyReadPaths` still apply last.
+- `writeRoots`: further writable subtrees (readable too). `cwd`: working directory, which must exist.
+- `networkProxyPort`: opens exactly one loopback port (`(remote ip "localhost:PORT")`); DNS, every other port and every other address stay denied.
+
+Verified by execution on macOS only (`test/capabilities/`, probes in `capabilities/probes.js`). The namespace backend implements none of these options; asked for them it ignores them, which is why the capability runner never asks it: its probes report these controls `unsupported` there and the run is blocked.
+
 ## Extending this module
 
 - Both real backends (`backend-userspace.js`, `backend-namespace.js`) must

package/src/sandbox/backend-userspace.js

@@ -18,20 +18,66 @@ import { resolveUserspaceBin } from './capabilities.js';
 import { buildLimitPrelude, ambientRelativeMaxProcs } from './limits.js';
 import { buildResult, errorResult, buildConfinedEnv } from './result.js';
 
-function _profile({ allowNetwork, denyRead = [] }) {
-  return [
+// Host paths every confined process needs just to start (dynamic loader, system
+// libraries, locale and timezone data, device nodes). Used ONLY when reads are
+// confined; the default profile below still allows reads globally. Metadata
+// (stat) is granted on the ancestors of each readable root and nowhere else, so
+// a path outside the readable set cannot even be probed for existence.
+const BASELINE_READ_SUBPATHS = Object.freeze([
+  '/usr', '/bin', '/sbin', '/System', '/Library/Preferences', '/private/etc', '/dev',
+  '/private/var/db/dyld', '/private/var/db/timezone', '/private/var/select',
+]);
+const BASELINE_META_LITERALS = Object.freeze([
+  '/', '/private', '/private/var', '/private/var/db', '/var', '/etc', '/tmp', '/Library', '/private/tmp',
+]);
+
+function _profile({ allowNetwork, proxyPort = null, denyRead = [], confineReads = false, readRoots = [], writeRoots = [], metaLiterals = [] }) {
+  const lines = [
     '(version 1)',
     '(deny default)',
     '(allow process-exec process-fork)',
     '(allow sysctl-read)',
-    '(allow file-read*)',
-    // Read denial (CORE-003). SBPL is last-match-wins, so these deny rules MUST
-    // come after the blanket read allow. Each path is a parameter, never
-    // spliced into the profile text, so a path cannot inject policy.
-    ...denyRead.map((_, i) => `(deny file-read* (subpath (param "DENY${i}")))`),
-    '(allow file-write* (subpath (param "ROOT")))',
-    allowNetwork ? '(allow network*)' : '',
-  ].filter(Boolean).join('\n');
+  ];
+  if (!confineReads) {
+    lines.push('(allow file-read*)');
+  } else {
+    // Reads are confined to the baseline above, the declared readable roots and
+    // the writable roots. Every path is a parameter or a fixed literal, never
+    // spliced text, so a path cannot inject policy.
+    lines.push(`(allow file-read* (literal "/") ${BASELINE_READ_SUBPATHS.map((p) => `(subpath "${p}")`).join(' ')})`);
+    lines.push(`(allow file-read-metadata ${BASELINE_META_LITERALS.map((p) => `(literal "${p}")`).join(' ')})`);
+    lines.push('(allow file-read* (subpath (param "ROOT")))');
+    readRoots.forEach((_, i) => lines.push(`(allow file-read* (subpath (param "RD${i}")))`));
+    writeRoots.forEach((_, i) => lines.push(`(allow file-read* (subpath (param "WR${i}")))`));
+    metaLiterals.forEach((_, i) => lines.push(`(allow file-read-metadata (literal (param "META${i}")))`));
+    lines.push('(allow file-write* (literal "/dev/null"))');
+  }
+  // Read denial (CORE-003). SBPL is last-match-wins, so these deny rules MUST
+  // come after every read allow.
+  denyRead.forEach((_, i) => lines.push(`(deny file-read* (subpath (param "DENY${i}")))`));
+  lines.push('(allow file-write* (subpath (param "ROOT")))');
+  writeRoots.forEach((_, i) => lines.push(`(allow file-write* (subpath (param "WR${i}")))`));
+  if (allowNetwork) lines.push('(allow network*)');
+  // Mediated network (X-504): the only reachable endpoint is the runner's own
+  // loopback proxy port; everything else, including every other loopback port
+  // and DNS, stays denied by the default rule.
+  else if (Number.isInteger(proxyPort) && proxyPort > 0 && proxyPort < 65536) {
+    lines.push(`(allow network-outbound (remote ip "localhost:${proxyPort}"))`);
+  }
+  return lines.join('\n');
+}
+
+function _realOrResolved(p) {
+  let real = path.resolve(p);
+  try { real = fs.realpathSync(real); } catch { /* not present: use the literal path */ }
+  return real;
+}
+
+function _ancestors(p) {
+  const out = [];
+  let cur = path.dirname(p);
+  while (cur && cur !== path.dirname(cur)) { out.push(cur); cur = path.dirname(cur); }
+  return out;
 }
 
 /**
@@ -46,6 +92,10 @@ export function buildUserspaceInvocation(argv, {
   limits = {},
   env = {},
   denyReadPaths = [],
+  readRoots = null,
+  writeRoots = [],
+  networkProxyPort = null,
+  cwd = null,
 } = {}) {
   if (!root) return { error: errorResult('userspace', 'runUserspace requires a sandbox root') };
 
@@ -70,6 +120,27 @@ export function buildUserspaceInvocation(argv, {
     if (!denyRead.includes(real)) denyRead.push(real);
   }
 
+  // Capability mode (X-502/X-504). `readRoots` non-null confines reads to the
+  // baseline plus those roots; `writeRoots` adds writable subtrees beyond
+  // `root`; `networkProxyPort` opens exactly one loopback port. All of them are
+  // absent for every pre-existing caller, whose profile is unchanged.
+  const confineReads = Array.isArray(readRoots);
+  const rd = confineReads ? [...new Set(readRoots.filter((p) => typeof p === 'string' && p).map(_realOrResolved))] : [];
+  const wr = [...new Set((writeRoots || []).filter((p) => typeof p === 'string' && p).map(_realOrResolved))];
+  let resolvedCwd = resolvedRoot;
+  if (cwd) {
+    resolvedCwd = _realOrResolved(cwd);
+    try { if (!fs.statSync(resolvedCwd).isDirectory()) throw new Error('not a directory'); } catch (e) {
+      return { error: errorResult('userspace', `working directory is not usable: ${e.message}`) };
+    }
+  }
+  const metaSet = new Set();
+  if (confineReads) {
+    for (const p of [resolvedRoot, resolvedCwd, ...rd, ...wr]) for (const a of _ancestors(p)) metaSet.add(a);
+    for (const b of BASELINE_META_LITERALS) metaSet.delete(b);
+  }
+  const metaLiterals = [...metaSet].sort();
+
   const effectiveLimits = {
     ...limits,
     maxProcs: limits.maxProcs ?? ambientRelativeMaxProcs(),
@@ -85,12 +156,15 @@ export function buildUserspaceInvocation(argv, {
   return {
     bin,
     args: [
-      '-p', _profile({ allowNetwork, denyRead }),
+      '-p', _profile({ allowNetwork, proxyPort: networkProxyPort, denyRead, confineReads, readRoots: rd, writeRoots: wr, metaLiterals }),
       '-D', `ROOT=${resolvedRoot}`,
       ...denyRead.flatMap((p, i) => ['-D', `DENY${i}=${p}`]),
+      ...rd.flatMap((p, i) => ['-D', `RD${i}=${p}`]),
+      ...wr.flatMap((p, i) => ['-D', `WR${i}=${p}`]),
+      ...metaLiterals.flatMap((p, i) => ['-D', `META${i}=${p}`]),
       '/bin/sh', '-c', inner, '_sbx', ...argv,
     ],
-    cwd: resolvedRoot,
+    cwd: resolvedCwd,
     env: buildConfinedEnv({ root: resolvedRoot, env }),
     unsupported,
   };
@@ -104,10 +178,14 @@ export function runUserspace(argv, {
   env = {},
   maxBuffer = 8 * 1024 * 1024,
   denyReadPaths = [],
+  readRoots = null,
+  writeRoots = [],
+  networkProxyPort = null,
+  cwd = null,
 } = {}) {
   // Documented shape, never a throw: a caller that wraps this in try/catch and
   // "falls back" is a classic route to unconfined execution.
-  const inv = buildUserspaceInvocation(argv, { root, allowNetwork, limits, env, denyReadPaths });
+  const inv = buildUserspaceInvocation(argv, { root, allowNetwork, limits, env, denyReadPaths, readRoots, writeRoots, networkProxyPort, cwd });
   if (inv.error) return inv.error;
 
   const r = spawnSync(inv.bin, inv.args, {