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

package/src/posture/autopilot.js

@@ -26,6 +26,8 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
+import { emitVerification } from './verification/emit.js';
+import { verificationFields } from './verification/projection.js';
 
 const SCHEMA = 'agentic-security/autopilot@1';
 
@@ -73,8 +75,15 @@ function _save(stateFile, state) {
  */
 export async function runAutopilot({
   stages = {}, stateFile = null, resume = true, apply = false,
-  onStage = () => {}, severities = ['critical', 'high'], maxFindings = Infinity,
+  onStage = () => {}, severities = ['critical', 'high'], maxFindings = Infinity, commit = null,
 } = {}) {
+  // X-201: every settled finding carries the one version-1 verification record, ADDITIVELY (`outcome`, `reason` and
+  // every other field are unchanged). The chain's own proof and re-verify stages run under the older sandbox path, so
+  // the record never says `confirmed` or `refuted` here: it records what was observed and what remains unproven.
+  const seal = (rec, finding, patch) => {
+    const e = emitVerification('autopilot', rec, { finding, patch: patch?.patch, commit });
+    if (e.ok) rec.verificationRecord = e.record;
+  };
   const required = ['scan'];
   for (const r of required) {
     if (typeof stages[r] !== 'function') return { ok: false, reason: `no ${r} stage supplied` };
@@ -138,6 +147,7 @@ export async function runAutopilot({
       if (rec.validation === 'refuted') {
         rec.outcome = 'NEEDS_REVIEW';
         rec.reason = 'an independent verifier refuted this finding; not fixed automatically';
+        seal(rec, f, null);
         results.push(rec); state.findings[key] = rec; _save(stateFile, state);
         onStage({ stage: 'validate', key, verdict: 'refuted' });
         continue;
@@ -149,6 +159,7 @@ export async function runAutopilot({
     if (!isProven) {
       rec.outcome = 'UNPROVEN';
       rec.reason = proved?.proofEvidence?.reason || 'no proof-of-concept demonstrated this finding';
+      seal(rec, f, null);
       results.push(rec); state.findings[key] = rec; _save(stateFile, state);
       continue;
     }
@@ -161,6 +172,7 @@ export async function runAutopilot({
     if (!patch || !patch.patch) {
       rec.outcome = 'NO_FIX';
       rec.reason = 'no patch was synthesised';
+      seal(rec, f, null);
       results.push(rec); state.findings[key] = rec; _save(stateFile, state);
       continue;
     }
@@ -171,6 +183,7 @@ export async function runAutopilot({
     if (typeof stages.verifyFix !== 'function') {
       rec.outcome = 'NEEDS_REVIEW';
       rec.reason = 'no verifyFix stage supplied — a patch that cannot be re-verified is never applied';
+      seal(rec, f, patch);
       results.push(rec); state.findings[key] = rec; _save(stateFile, state);
       continue;
     }
@@ -194,6 +207,7 @@ export async function runAutopilot({
         : (!rec.testsPass ? 'the project test suite fails with this patch'
           : (v?.reason || 'the patch did not re-verify'));
     }
+    seal(rec, f, patch);
     results.push(rec);
     state.findings[key] = rec;
     _save(stateFile, state);
@@ -203,6 +217,19 @@ export async function runAutopilot({
   return { ok: true, results, skipped, outOfScope, capped, summary: summarizeAutopilot(results, outOfScope, capped) };
 }
 
+/**
+ * X-206: the autopilot response as it is serialized for a caller. Every field of every result is kept (the native `outcome`
+ * vocabulary and its meaning are unchanged); a result that carries a verification record additionally gets `verificationView`, the
+ * shared projection every other interface shows for the same finding. Results without a record are returned as they were.
+ */
+export function serializeAutopilotResult(res) {
+  if (!res || !Array.isArray(res.results)) return res;
+  return {
+    ...res,
+    results: res.results.map((r) => (r && r.verificationRecord ? { ...r, ...verificationFields(r.verificationRecord, { replay: r.verificationReplay }) } : r)),
+  };
+}
+
 export function summarizeAutopilot(results, outOfScope = 0, capped = 0) {
   const byOutcome = Object.fromEntries(OUTCOMES.map(o => [o, 0]));
   for (const r of results) if (r.outcome in byOutcome) byOutcome[r.outcome]++;

package/src/posture/business-logic.js

@@ -17,6 +17,8 @@
 //     case. Heuristic: check the test-files corpus for any test asserting
 //     a 401 / 403 status against the route's path.
 
+import { inferredInvariant } from './invariants/lifecycle.js';
+
 const JS_TS_RE = /\.(?:js|jsx|ts|tsx|mjs|cjs)$/i;
 const PY_RE    = /\.py$/i;
 
@@ -135,20 +137,25 @@ function emitAuthZMatrixFindings(matrix) {
 
 // ─── FR-LOGIC-2 State machine extraction ──────────────────────────────────
 
-function extractStateMachine(fileContents) {
+function collectStateSets(fileContents) {
   // Find sites where a literal set of statuses appears (e.g.
   // `STATUSES = ['pending', 'approved', 'rejected']` or an enum-like in TS).
-  // Then look for direct writes like `.status = "<not in set>"` and flag.
-  const stateSets = [];   // [{file, line, name, values: Set<string>}]
+  const stateSets = [];   // [{file, line, name, values: Set<string>, ordered: string[]}]
   for (const [fp, c] of Object.entries(fileContents || {})) {
     if (typeof c !== 'string' || !JS_TS_RE.test(fp)) continue;
     const re = /\b(STATUSES|STATES|PHASES|ALLOWED_STATUSES|[A-Z_]+_STATUSES)\s*=\s*\[\s*((?:['"][^'"]+['"]\s*,?\s*){2,})\]/g;
     let m;
     while ((m = re.exec(c))) {
       const values = [...m[2].matchAll(/['"]([^'"]+)['"]/g)].map(x => x[1]);
-      stateSets.push({ file: fp, line: _lineOf(c, m.index), name: m[1], values: new Set(values) });
+      stateSets.push({ file: fp, line: _lineOf(c, m.index), name: m[1], values: new Set(values), ordered: values });
     }
   }
+  return stateSets;
+}
+
+function extractStateMachine(fileContents) {
+  // Then look for direct writes like `.status = "<not in set>"` and flag.
+  const stateSets = collectStateSets(fileContents);
   if (!stateSets.length) return [];
   const findings = [];
   for (const [fp, c] of Object.entries(fileContents || {})) {
@@ -236,4 +243,19 @@ export function scanBusinessLogic(fileContents) {
 }
 
 // For tests + the no-dead-modules check.
+// X-402: a declared status list read as an inferred workflow contract. The declared order is the only evidence for the allowed
+// transitions (each value to the next), which is a guess a reviewer must confirm, so the proposal carries a high uncertainty and is
+// advisory until approved in the signed ledger.
+export function mineWorkflowInvariants(fileContents) {
+  const out = [];
+  for (const set of collectStateSets(fileContents)) {
+    const states = set.ordered.filter((v) => /^[A-Za-z0-9_.:/-]{1,64}$/.test(v));
+    if (states.length < 2) continue;
+    const allowed = states.slice(0, -1).map((from, i) => ({ from, to: states[i + 1] }));
+    const inv = inferredInvariant({ class: 'workflow-order', source: 'state-machine', evidence: { file: set.file, line: set.line, set: set.name }, uncertainty: 0.7, action: 'advance', allowed: allowed.slice(0, 16) });
+    if (inv) out.push(inv);
+  }
+  return out;
+}
+
 export const _internals = { extractAuthZMatrix, extractStateMachine, findNegativeTestGaps };

package/src/posture/evaluation/bakeoff.js

@@ -0,0 +1,148 @@
+// Bake-off recipe: the manifest, the adapter contract and the claim guard (QA-008.AC02, QA-008.AC03).
+//
+// A bake-off compares this engine with other tools on one workload. The failure modes that make such a comparison worthless are
+// all about what is silently different between the runs, so the recipe pins them in a manifest, and this module refuses to
+// produce a comparative claim when any of them is not identical:
+//
+//   workload             the same target set, by digest, for every participant
+//   scope                the same languages and families
+//   provider and model   named per participant (an engine with no model says so)
+//   verification         one standard for what counts as a confirmed defect
+//   limits               the same time and spend ceilings
+//   failures             a timeout or crash is a recorded failure, scored as a miss, never dropped
+//
+// Comparators are GENERIC SLOTS (`comparator-a`, `comparator-b`, ...). This repository names no other tool: the operator maps a
+// slot to whatever they run. An adapter can declare itself `unavailable` (not installed, no licence, no provider access), and that
+// participant is `not-evaluated`: it is not a zero, not a loss and not excluded quietly. It appears in the report with its
+// reason. A comparative accuracy or cost claim exists only between participants that were actually evaluated on the identical
+// workload under the identical standard, and only for a quantity both measured; otherwise the claim is withheld with the reasons.
+//
+// Scoring is delegated to comparison.js (CWE-only matching, intersection of completed entries), unchanged.
+//
+// Pure: no fs, no clock, no process execution. An adapter's `run` is supplied by the caller.
+
+import { digestOf } from '../assurance/identity.js';
+import { compareParticipants, scoreParticipant } from '../comparison.js';
+
+const BAKEOFF_SCHEMA = 'agentic-security/bakeoff-manifest';
+const ENGINE_SLOT = 'this-engine';
+const SLOT_RE = /^(?:this-engine|comparator-[a-z])$/;
+export const UNAVAILABLE_REASONS = Object.freeze(['not-installed', 'no-licence', 'no-provider-access', 'not-configured', 'platform-unsupported', 'operator-declined']);
+
+const isObj = (x) => x && typeof x === 'object' && !Array.isArray(x);
+const err = (path, message) => ({ code: 'BAD_MANIFEST', path, message });
+
+/** @returns {{ok: boolean, errors: object[]}} */
+export function validateBakeoffManifest(m) {
+  const errors = [];
+  if (!isObj(m)) return { ok: false, errors: [err('', 'manifest must be an object')] };
+  if (m.schema !== BAKEOFF_SCHEMA) errors.push(err('schema', `schema must be ${BAKEOFF_SCHEMA}`));
+  const w = m.workload;
+  if (!isObj(w) || !Array.isArray(w.targetIds) || !w.targetIds.length) errors.push(err('workload.targetIds', 'name the target ids the workload consists of'));
+  else {
+    if (!/^sha256:[0-9a-f]{64}$/.test(w.workloadDigest || '')) errors.push(err('workload.workloadDigest', 'the workload is pinned by digest'));
+    else if (w.workloadDigest !== workloadDigestOf(w)) errors.push(err('workload.workloadDigest', 'the digest does not match the targets and tree digests listed'));
+  }
+  if (!isObj(m.scope) || !Array.isArray(m.scope.languages) || !Array.isArray(m.scope.families)) errors.push(err('scope', 'declare the languages and families in scope'));
+  if (!isObj(m.verification) || !m.verification.standard) errors.push(err('verification.standard', 'one verification standard must be named (what counts as a confirmed defect)'));
+  const lim = m.limits;
+  if (!isObj(lim) || !(lim.perTargetTimeoutMs > 0) || !(lim.wallClockMs > 0) || typeof lim.spendCeilingUsd !== 'number') errors.push(err('limits', 'perTargetTimeoutMs, wallClockMs and spendCeilingUsd are all required'));
+  if (m.failurePolicy !== 'count-as-misses') errors.push(err('failurePolicy', 'failures are scored as misses; the only accepted policy is count-as-misses'));
+  const ps = m.participants;
+  if (!Array.isArray(ps) || ps.length < 2) errors.push(err('participants', 'a bake-off needs this engine and at least one comparator slot'));
+  else {
+    const seen = new Set();
+    ps.forEach((p, i) => {
+      if (!isObj(p) || !SLOT_RE.test(p.slot || '')) { errors.push(err(`participants[${i}].slot`, 'a slot is "this-engine" or "comparator-a".."comparator-z"; no product name belongs in a recipe')); return; }
+      if (seen.has(p.slot)) errors.push(err(`participants[${i}].slot`, `duplicate slot ${p.slot}`));
+      seen.add(p.slot);
+      if (!isObj(p.provider) || !('model' in p.provider)) errors.push(err(`participants[${i}].provider`, 'name the provider and model, or {"model": null} for a tool that uses none'));
+    });
+    if (!seen.has(ENGINE_SLOT)) errors.push(err('participants', 'this-engine must be one of the participants'));
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+/** The digest a workload is pinned by: its targets and their tree digests, nothing else. */
+export function workloadDigestOf(workload) {
+  const targets = Object.fromEntries((workload.targetIds || []).slice().sort().map((id) => [id, workload.treeDigests?.[id] ?? null]));
+  return digestOf({ kind: 'bakeoff-workload', targets });
+}
+
+/**
+ * Decide, per participant, whether it can be evaluated. `adapters` maps a slot to `{ available: boolean, reason?, run? }`.
+ * A slot with no adapter, or an adapter that says it is unavailable, is `not-evaluated` with a typed reason.
+ */
+export function resolveParticipants(manifest, adapters = {}) {
+  return manifest.participants.map((p) => {
+    const a = adapters[p.slot];
+    if (!a) return { slot: p.slot, provider: p.provider, state: 'not-evaluated', reason: 'not-configured', detail: 'no adapter was supplied for this slot' };
+    if (a.available === false) {
+      const reason = UNAVAILABLE_REASONS.includes(a.reason) ? a.reason : 'not-configured';
+      return { slot: p.slot, provider: p.provider, state: 'not-evaluated', reason, detail: a.detail || null };
+    }
+    return { slot: p.slot, provider: p.provider, state: 'evaluated', reason: null, detail: null };
+  });
+}
+
+/**
+ * Judge a finished bake-off.
+ * @param {object} o
+ * @param {object} o.manifest   a valid manifest
+ * @param {object[]} o.entries  [{id, cwe}] the workload's answer key
+ * @param {Object<string, {workloadDigest: string, verificationStandard: string, results: object, costUsd?: number|null, completed?: number}>} o.runs  by slot, for evaluated participants
+ * @param {Object<string, object>} [o.adapters]
+ */
+export function judgeBakeoff({ manifest, entries, runs = {}, adapters = {} }) {
+  const v = validateBakeoffManifest(manifest);
+  if (!v.ok) return { ok: false, errors: v.errors };
+  const resolved = resolveParticipants(manifest, adapters);
+  const participants = resolved.map((r) => {
+    if (r.state !== 'evaluated') return r;
+    const run = runs[r.slot];
+    if (!run) return { ...r, state: 'not-evaluated', reason: 'no-run-recorded', detail: 'the adapter was available but no result was recorded' };
+    return { ...r, run: { workloadDigest: run.workloadDigest, verificationStandard: run.verificationStandard, costUsd: run.costUsd ?? null } };
+  });
+  const evaluated = participants.filter((p) => p.state === 'evaluated');
+  const withheld = [];
+  for (const p of participants.filter((x) => x.state === 'not-evaluated')) withheld.push({ slot: p.slot, reason: `${p.slot} was not evaluated (${p.reason}); no comparison with it is made` });
+
+  // Comparability: every evaluated participant must have run the manifest's workload under the manifest's standard.
+  const mismatched = evaluated.filter((p) => p.run.workloadDigest !== manifest.workload.workloadDigest || p.run.verificationStandard !== manifest.verification.standard);
+  for (const p of mismatched) withheld.push({ slot: p.slot, reason: `${p.slot} ran a different workload or verification standard than the manifest pins; its figures are not comparable` });
+  const comparable = evaluated.filter((p) => !mismatched.includes(p));
+
+  let comparison = null;
+  const claims = [];
+  if (comparable.length >= 2) {
+    const parts = comparable.map((p) => ({ id: p.slot, results: runs[p.slot].results }));
+    comparison = compareParticipants(entries, parts);
+    if (!comparison.ok) { withheld.push({ slot: null, reason: `scoring refused: ${comparison.reason}` }); comparison = null; }
+  } else {
+    withheld.push({ slot: null, reason: 'fewer than two participants were evaluated on the identical workload; there is nothing to compare' });
+  }
+  // End-to-end view per participant: an entry it could not complete is a MISS here (the comparison above is over the shared
+  // intersection and is labelled as such). Both views are published; neither replaces the other.
+  const endToEnd = {};
+  for (const p of comparable) {
+    const sc = scoreParticipant(entries, runs[p.slot].results);
+    let detected = 0; for (const v of sc.per.values()) if (v.detected) detected++;
+    endToEnd[p.slot] = { entries: entries.length, completed: sc.completed, failedOrMissing: entries.length - sc.completed, detected, recallEndToEnd: entries.length ? detected / entries.length : null, rule: 'failures and missing results count as misses' };
+  }
+  if (comparison) {
+    // An accuracy claim is a statement of the measured figures over the shared intersection; it never says "better" for a tie or an
+    // interval overlap, and it needs every participant to have completed the shared entries.
+    claims.push({ kind: 'accuracy', basis: 'shared-intersection', participants: comparable.map((p) => p.slot), statement: 'figures over the entries every compared participant completed; see the comparison table' });
+    const costs = comparable.map((p) => ({ slot: p.slot, usd: runs[p.slot].costUsd ?? null }));
+    if (costs.every((c) => typeof c.usd === 'number')) claims.push({ kind: 'cost', participants: costs.map((c) => c.slot), costsUsd: Object.fromEntries(costs.map((c) => [c.slot, c.usd])), statement: 'measured spend per participant under the same limits' });
+    else withheld.push({ slot: null, reason: `no cost claim: ${costs.filter((c) => typeof c.usd !== 'number').map((c) => c.slot).join(', ')} did not report a measured cost` });
+  }
+  const report = {
+    schema: 'agentic-security/bakeoff-report', ok: true, errors: [], manifestDigest: digestOf(manifest),
+    workloadDigest: manifest.workload.workloadDigest, participants, comparison, endToEnd, claims, withheld,
+    superiority: 'none claimed',
+    note: 'a participant that was not evaluated is reported as such; it is never a zero, a loss or a silent omission',
+  };
+  report.reportDigest = digestOf({ ...report, reportDigest: undefined });
+  return report;
+}

package/src/posture/evaluation/custody.js

@@ -0,0 +1,200 @@
+// Label custody and leakage controls (QA-002.AC03).
+//
+// Two trust domains meet here. The CUSTODIAN (verifier domain) holds adjudicated
+// labels. The engine under test, and any worker or model prompt, is on the other
+// side and must never see an answer key. This module provides the custodian's
+// store, the workspace staging that builds what the engine is allowed to read,
+// and the audits that fail a run when anything label-shaped crosses over.
+//
+// Enforcement, honestly stated:
+//   - role checks use the existing trust-domain policy (`mayDo`): workers and
+//     targets are denied sealed-label read AND write;
+//   - staging and prompt audits are PATTERN checks over known protected terms and
+//     file names. They catch planted and accidental leaks of the kinds listed in
+//     `leakFixtures`; they are not a proof that no paraphrase gets through;
+//   - process-level read denial of the label directory is the sandbox trust
+//     boundary's job (`runInBoundary({ labelDirs })`), which this module only
+//     feeds. Where no backend proves that control the boundary reports `blocked`.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { DOMAINS, RESOURCES, mayDo, isUntrusted, scrubEnv } from '../../sandbox/trust-domains.js';
+import { digestOf } from '../assurance/identity.js';
+import { STATE_DIR_NAME } from '../state-dir.js';
+import { validateDefectLabel, validateNegativeLabel } from './labels.js';
+
+export const LABEL_FILE = 'adjudicated-labels.json';
+
+// File names that look like an answer key. Regexes, not literals, so this file
+// is not itself a reference to any particular key file.
+const LEAK_FILENAME_PATTERNS = Object.freeze([
+  /(^|\/)(labels?|answers?|expected|ground[-_]?truth|answer[-_]?key|adjudicat\w*|oracle)[^/]*\.(json|jsonl|ya?ml|csv|txt)$/i,
+  /(^|\/)result\.json$/i,
+  /(^|\/)corpus-baseline[^/]*$/i,
+  /(^|\/)(advisory|advisories|ghsa|osv)[^/]*\.(json|md|txt|ya?ml)$/i,
+]);
+
+const BENCHMARK_NAMES = Object.freeze(['owasp benchmark', 'juliet', 'sard test', 'cve-replay', 'corpus-baseline', 'answer key', 'ground truth']);
+const ADVISORY_ID = /\b(CVE-\d{4}-\d{4,}|GHSA-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4})\b/i;
+const MIN_TERM = 8;
+
+/**
+ * Terms that must never reach the engine or a prompt: reviewer evidence refs and
+ * rationale, advisory ids and prose, root-cause ids, and fixed-source hints.
+ */
+export function protectedTermsFrom({ defects = [], negatives = [], advisoryText = [], fixedSourceHints = [], benchmarkNames = BENCHMARK_NAMES } = {}) {
+  const terms = new Set();
+  const add = (s) => { if (typeof s === 'string' && s.trim().length >= MIN_TERM) terms.add(s.trim().toLowerCase()); };
+  for (const d of defects) {
+    add(d.rootCauseId);
+    for (const e of d.evidence || []) add(e.ref);
+    for (const a of d.advisoryRefs || []) add(a);
+  }
+  for (const n of negatives) add(n.rationale);
+  for (const s of [...advisoryText, ...fixedSourceHints, ...benchmarkNames]) add(s);
+  return [...terms].sort();
+}
+
+/** Leaks in a piece of text (a prompt, a file body). */
+export function auditText(text, terms, { strictAdvisoryIds = true } = {}) {
+  const hay = String(text ?? '');
+  const lower = hay.toLowerCase();
+  const leaks = [];
+  for (const t of terms || []) if (lower.includes(t)) leaks.push({ kind: 'protected-term', detail: t.length > 60 ? `${t.slice(0, 57)}...` : t });
+  if (strictAdvisoryIds) {
+    const m = ADVISORY_ID.exec(hay);
+    if (m) leaks.push({ kind: 'advisory-id', detail: m[1] });
+  }
+  return leaks;
+}
+
+/** Gate a model/scanner prompt. `ok:false` means the call must not be made. */
+export function guardPrompt(prompt, terms, opts) {
+  const leaks = auditText(prompt, terms, opts);
+  return { ok: leaks.length === 0, leaks };
+}
+
+const SKIP_DIRS = new Set(['.git', STATE_DIR_NAME, 'node_modules']);
+
+/**
+ * Audit a directory the engine may read: no answer-key file names, no symlinks
+ * (which could point outside it), no protected term or advisory id in content.
+ * Bounded so a hostile tree cannot make the audit itself the problem.
+ */
+export function auditWorkspace(dir, terms, { strictAdvisoryIds = true, maxFiles = 20000, maxFileBytes = 2 * 1024 * 1024 } = {}) {
+  const leaks = [];
+  let scanned = 0; let skippedLarge = 0; let truncated = false;
+  const walk = (d, rel) => {
+    let entries = [];
+    try { entries = fs.readdirSync(d, { withFileTypes: true }); } catch { return; }
+    for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+      if (truncated) return;
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isSymbolicLink()) { leaks.push({ kind: 'symlink', file: r, detail: 'symlinks are refused in an engine workspace' }); continue; }
+      if (e.isDirectory()) { if (!SKIP_DIRS.has(e.name)) walk(path.join(d, e.name), r); continue; }
+      if (!e.isFile()) continue;
+      if (++scanned > maxFiles) { truncated = true; leaks.push({ kind: 'audit-truncated', file: r, detail: `more than ${maxFiles} files; the audit cannot vouch for the rest` }); return; }
+      if (LEAK_FILENAME_PATTERNS.some((re) => re.test(r))) { leaks.push({ kind: 'answer-key-file', file: r, detail: 'file name looks like a label, answer key or advisory record' }); continue; }
+      let st; try { st = fs.statSync(path.join(d, e.name)); } catch { continue; }
+      if (st.size > maxFileBytes) { skippedLarge++; continue; }
+      let body; try { body = fs.readFileSync(path.join(d, e.name), 'utf8'); } catch { continue; }
+      for (const l of auditText(body, terms, { strictAdvisoryIds })) leaks.push({ ...l, file: r });
+    }
+  };
+  walk(dir, '');
+  return { ok: leaks.length === 0, leaks, scannedFiles: scanned, skippedLargeFiles: skippedLarge };
+}
+
+/**
+ * Copy a target tree into a fresh workspace for the engine, then audit it. On any
+ * leak the workspace is removed and the target is reported quarantined; the run
+ * must record that as a failure, never silently scan the tree anyway.
+ */
+export function stageWorkspace({ srcDir, destDir, terms, strictAdvisoryIds = true }) {
+  fs.rmSync(destDir, { recursive: true, force: true });
+  fs.cpSync(srcDir, destDir, {
+    recursive: true, dereference: false,
+    filter: (s) => !SKIP_DIRS.has(path.basename(s)) || s === srcDir,
+  });
+  const audit = auditWorkspace(destDir, terms, { strictAdvisoryIds });
+  if (!audit.ok) {
+    fs.rmSync(destDir, { recursive: true, force: true });
+    return { ok: false, quarantined: true, leaks: audit.leaks, destDir: null };
+  }
+  return { ok: true, quarantined: false, leaks: [], destDir };
+}
+
+// ---------------------------------------------------------------- the custodian's store
+
+/** Content hash binding a label set: key-order independent, order independent. */
+export function sealLabels(defects, negatives) {
+  const sortById = (xs) => [...xs].sort((a, b) => String(a.id).localeCompare(String(b.id)));
+  return digestOf({ kind: 'evaluation-labels', defects: sortById(defects || []), negatives: sortById(negatives || []) });
+}
+
+const isCustodian = (actor) => actor?.domain === DOMAINS.VERIFIER && actor?.role === 'custodian' && !isUntrusted(actor.domain);
+
+function denied(code, message) { return { ok: false, errors: [{ code, path: '', message }] }; }
+
+/**
+ * Write the label set. Only the custodian may; a worker or the target is denied
+ * by the trust-domain policy. Every label is validated first: one invalid label
+ * rejects the whole write.
+ */
+export function custodianWriteLabels(labelDir, actor, { defects = [], negatives = [] } = {}) {
+  if (!isCustodian(actor)) return denied('CUSTODY_DENIED', `domain '${actor?.domain}' role '${actor?.role}' may not write sealed labels`);
+  const errors = [];
+  for (const d of defects) { const v = validateDefectLabel(d); if (!v.ok) errors.push(...v.errors.map((e) => ({ ...e, path: `${d?.id}.${e.path}` }))); }
+  for (const n of negatives) { const v = validateNegativeLabel(n); if (!v.ok) errors.push(...v.errors.map((e) => ({ ...e, path: `${n?.id}.${e.path}` }))); }
+  if (errors.length) return { ok: false, errors };
+  fs.mkdirSync(labelDir, { recursive: true, mode: 0o700 });
+  try { fs.chmodSync(labelDir, 0o700); } catch { /* best effort */ }
+  const file = path.join(labelDir, LABEL_FILE);
+  fs.writeFileSync(file, JSON.stringify({ defects, negatives }), { mode: 0o600 });
+  return { ok: true, errors: [], labelsHash: sealLabels(defects, negatives), count: { defects: defects.length, negatives: negatives.length } };
+}
+
+/** Read the label set. Allowed only where the policy grants sealed-label read, and only if it still matches the sealed hash. */
+export function custodianReadLabels(labelDir, actor, { expectedHash } = {}) {
+  if (!mayDo(actor?.domain, RESOURCES.SEALED_LABELS, 'read')) return denied('CUSTODY_DENIED', `domain '${actor?.domain}' may not read sealed labels`);
+  let data;
+  try { data = JSON.parse(fs.readFileSync(path.join(labelDir, LABEL_FILE), 'utf8')); } catch (e) { return denied('LABELS_UNREADABLE', `cannot read labels: ${e.code || e.message}`); }
+  const defects = Array.isArray(data?.defects) ? data.defects : []; const negatives = Array.isArray(data?.negatives) ? data.negatives : [];
+  const labelsHash = sealLabels(defects, negatives);
+  if (expectedHash && labelsHash !== expectedHash) return denied('LABELS_HASH_MISMATCH', 'labels changed after they were sealed');
+  return { ok: true, errors: [], defects, negatives, labelsHash };
+}
+
+// realpath of the nearest existing ancestor plus the not-yet-existing remainder, so a path that does not exist
+// yet still compares correctly against one reached through a symlinked parent (macOS /var -> /private/var).
+function real(p) {
+  let cur = path.resolve(p); const rest = [];
+  for (;;) {
+    try { return path.join(fs.realpathSync(cur), ...rest.reverse()); } catch { /* climb */ }
+    const parent = path.dirname(cur);
+    if (parent === cur) return path.resolve(p);
+    rest.push(path.basename(cur)); cur = parent;
+  }
+}
+
+/** A workspace that contains, or sits inside, the label directory would hand the engine the answer key by construction. */
+export function assertCustodyIsolation(labelDir, workspaceDir) {
+  const a = real(labelDir); const b = real(workspaceDir);
+  if (a === b || a.startsWith(b + path.sep) || b.startsWith(a + path.sep)) {
+    return denied('CUSTODY_OVERLAP', `workspace ${workspaceDir} overlaps the label directory ${labelDir}`);
+  }
+  return { ok: true, errors: [] };
+}
+
+/** Environment for the engine under test: secret-looking variables, evaluation variables and anything naming the label directory are removed. */
+export function engineEnvironment(base, { labelDir } = {}) {
+  const scrubbed = scrubEnv(base || {});
+  const out = {};
+  const labelReal = labelDir ? real(labelDir) : null;
+  for (const [k, v] of Object.entries(scrubbed)) {
+    if (/^AGENTIC_(SECURITY_)?EVAL/i.test(k)) continue;
+    if (labelDir && typeof v === 'string' && (v.includes(labelDir) || v.includes(labelReal))) continue;
+    out[k] = v;
+  }
+  return out;
+}