@clear-capabilities/agentic-security-scanner 0.145.0 → 0.147.0

package/bin/agentic-security.js

@@ -4,12 +4,14 @@
 import * as fs from 'node:fs';
 import * as fsp from 'node:fs/promises';
 import * as path from 'node:path';
+import * as crypto from 'node:crypto';
 import { createRequire } from 'node:module';
 const __require = createRequire(import.meta.url);
 const PKG_VERSION = __require('../package.json').version;
 import { signLastScan as _signLastScan, verifyLastScan as _verifyLastScanShared } from '../src/posture/integrity.js';
 import { isProvenanceHealthy, sanitizeForTerminal } from '../src/posture/provenance/schema.js';
 import { runScan } from '../src/runScan.js';
+import { persistGraphSnapshot, loadSnapshots, loadSnapshot, mostRecentPriorSnapshot } from '../src/lineage/graph-snapshot.js';
 
 // Every command is dispatched as `process.exit(await cmdX(args))`, and
 // process.exit() does NOT flush an asynchronous stdout. stdout is asynchronous
@@ -70,7 +72,7 @@ import { decide as decideNextAction, explain as explainDecision } from '../src/p
 import * as triage from '../src/posture/triage.js';
 import { buildSlackDigest, buildDiscordDigest, postWebhook, buildJiraIssue, buildPrComment, buildSiemEvent, loadIntegrationConfig } from '../src/integrations/index.js';
 
-import { stateDir, statePath } from '../src/posture/state-dir.js';
+import { stateDir, statePath, withStateWritesDisabled } from '../src/posture/state-dir.js';
 import { listGeneratedArtifacts } from '../src/posture/artifact-registry.js';
 // last-scan.json integrity helpers — implementation in posture/integrity.js
 // so the MCP server tools can share verification.
@@ -139,6 +141,74 @@ Commands:
   scan-baseline --current <f> --previous <f>
                                Finding-level diff between two scan JSON outputs.
                                Reports added / removed / changed findings.
+  explore [path] [--port <n>] [--keep-open]
+                               Start a local, read-only server over an
+                               already-scanned lineage graph (run
+                               AGENTIC_SECURITY_LINEAGE_DEEP=1 scan first)
+  dataflow export [path] --format png|pdf|svg|json|csv|html|dpia|ropa|briefing|recipients|coverage --output <file>
+                               Export the already-scanned lineage graph.
+                               --view architecture|privacy|trace|inventory  (default: architecture;
+                                                      png/pdf/svg only — no-op + warning for json/csv/html/dpia/ropa/briefing/recipients/coverage)
+                               --size standard|2x    AC-23 pinned PNG sizes (default: standard)
+                               --width <n> --height <n>   custom PNG size, <= 20000 (mutually exclusive with --size)
+                               --no-redact            include unredacted content (json/html only; no-op + warning for csv/dpia/ropa/briefing/recipients/coverage)
+                               --filter <path.json>   {nodeIds,edgeIds} to scope the export (no-op + warning for csv/coverage)
+                               --audience board|ciso|privacy|compliance|regulator|technical
+                                                      (default: technical; briefing only — wording/verbosity, never facts)
+  dataflow scenario apply [path] --operations <file.json> --output <file> [--format json|markdown]
+                               Simulate a hypothetical architecture change against the
+                               already-scanned lineage graph — never mutates the real scan.
+                               --privacy-sink-policy <path-to-json>   re-evaluate each touched
+                                                      flow's policyVerdict under this policy file
+                               --environment <name>   environment context for --privacy-sink-policy
+  dataflow impact assess [path] --target <canonical-id> --output <file> [--format json|markdown]
+                               Blast-radius impact assessment over the already-scanned lineage
+                               graph — read-only, never mutates anything, never re-runs a scan.
+                               --target node:*|edge:*|flow:*|data:*  the compromised entity's id
+  governance propose-edit [path] --patch <file.json> [--output <file>] [--yes] [--base-digest <hex>]
+                               Propose a validated, reviewable edit to
+                               recipient-profiles.json. Without --yes,
+                               previews the diff and writes nothing.
+  federate declare [path] --local-node <node-id> --remote-graph <file>
+                               --remote-node <node-id> [--repository <label>]
+                               [--relationship data_flow] [--rationale <text>]
+                               [--output <file>] [--yes] [--base-digest <hex>]
+                               Declare a CrossRepoLink between a node in the
+                               current locally-scanned graph and a node in a
+                               remote graph export (dataflow export --format
+                               json). Without --yes, previews and writes nothing.
+  federate list [path] [--output <file>]
+                               List every declared cross-repo link, reporting
+                               whether each side still resolves.
+  remediation open [path] --assessment <impact-report.json> --owner <id> --due <YYYY-MM-DD>
+                               --control <text> --required-evidence <flowId,...>
+                               [--id <itemId>] [--snapshot <commit>] [--allow-manual-attestation]
+                               [--output <file>] [--yes]
+                               Open a new remediation work item against an incident
+                               snapshot. Without --yes, previews the folded item and
+                               writes nothing to the append-only ledger.
+  remediation update [path] --id <itemId> --state <in_progress|awaiting_verification>
+                               [--base-event <hash>] [--output <file>] [--yes]
+                               Advance a remediation item's state. --state verified is
+                               always refused — see remediation verify (AC-31).
+  remediation verify [path] --id <itemId> [--against <commit>]
+                               [--manual-attestation --approver <id> --reason <text> [--author <id>]]
+                               [--base-event <hash>] [--output <file>] [--yes]
+                               Verify a remediation item against a fresh lineage scan (or an
+                               explicitly-permitted manual attestation). AC-31: marking work
+                               complete never sets "verified" — only this command can.
+  remediation reopen-check [path] [--drift-policy <file>] [--against <commit>]
+                               [--output <file>] [--yes]
+                               Reopen verified items whose control regressed (drift-policy match,
+                               or an affected flow removed/changed in the latest diff). No
+                               --base-event: this can append events across many items at once.
+  remediation accept-risk [path] --id <itemId> --approver <id> --reason <text>
+                               --scope <text> --expires <YYYY-MM-DD> [--author <id>]
+                               [--base-event <hash>] [--output <file>] [--yes]
+                               Record an accepted-risk exception, gated on the operator's
+                               authorized-approvers registry when one exists.
+  remediation list [path] [--format json|markdown] [--output <file>]
+                               List every remediation item folded from the ledger.
 
 Options:
   --profile vibecoder|pro      Override profile for this run
@@ -957,6 +1027,12 @@ async function cmdScan(args) {
   if (_writesOnScan() && _isSafeStateDir(stateDirPath)) {
     await fsp.mkdir(stateDirPath, { recursive: true });
     persistedScan = toJSON(scan, meta);
+    // Sub-project E, increment 5: the lineage graph gets its OWN artifact
+    // file (below), never duplicated inside last-scan.json — a
+    // DataFlowGraph v1 document is a separate, potentially large artifact,
+    // and embedding it a second time here would bloat the file every other
+    // consumer of last-scan.json already reads in full.
+    delete persistedScan.lineageGraph;
     // #10 — MTTR: stamp firstSeenAt/lastSeenAt/ageDays from the PREVIOUS scan so
     // every finding carries an age, SLA breaches can be surfaced, and the fix
     // loop can report time-to-clean. Best-effort; skipped under --deterministic
@@ -1050,6 +1126,32 @@ async function cmdScan(args) {
     try {
       await fsp.writeFile(path.join(stateDirPath, 'last-scan.json.sig'), _signLastScan(lastScanBody));
     } catch { /* non-fatal — sig file is best-effort */ }
+    // Sub-project E, increment 5: persist the lineage graph as its own
+    // artifact, mirroring last-scan.json's own write+sign pattern exactly
+    // — signLastScan/verifyLastScan are fully generic (an arbitrary string
+    // body + an explicit sig-file path, no filename baked in), confirmed by
+    // reading posture/integrity.js directly, so no new signing mechanism
+    // is introduced. Written only when a graph actually exists — an
+    // ordinary scan (AGENTIC_SECURITY_LINEAGE_DEEP unset) writes nothing
+    // new here at all.
+    if (scan.lineageGraph) {
+      try {
+        const lineageBody = JSON.stringify(scan.lineageGraph, null, 2);
+        await fsp.writeFile(path.join(stateDirPath, 'lineage-graph.json'), lineageBody);
+        try {
+          await fsp.writeFile(path.join(stateDirPath, 'lineage-graph.json.sig'), _signLastScan(lineageBody));
+        } catch { /* non-fatal — sig file is best-effort, same precedent as last-scan.json.sig above */ }
+      } catch { /* non-fatal — the lineage artifact write is best-effort and must never block a scan */ }
+      // M4 deliverable #8 (FR-503 §14, DFG-022, sub-project 8a): ADDITIVELY
+      // persist the SAME graph into the commit-keyed snapshot history
+      // (.agentic-security/lineage-snapshots/<HEAD>.json), never replacing
+      // the single-current-graph artifact written just above. Best-effort,
+      // same precedent as the write above — a snapshot-history failure must
+      // never block a scan.
+      try {
+        persistGraphSnapshot(scan.lineageGraph, targetAbs);
+      } catch { /* non-fatal — snapshot history is best-effort and must never block a scan */ }
+    }
   } else {
     if (process.env.AGENTIC_SECURITY_DEBUG === '1') process.stderr.write(`[agentic-security] refusing to write state at ${stateDirPath} — no project marker in ${path.resolve(target)}\n`);
   }
@@ -2231,6 +2333,48 @@ async function cmdHunt(args) {
   return 0;
 }
 
+// Data Flow Explorer M4 sub-project 6c's final whole-branch review,
+// findings F2/F3/F5-followup: every caller that discards a
+// loadFreshLineageGraph result for staleness must also disclose WHY,
+// distinguishing "no graph exists at all" from "a graph exists but isn't
+// fresh for this scan" (never letting the latter print the former's
+// "no lineage graph found" message, which would be actively false — a
+// graph DOES exist, it just isn't trusted). Shared by cmdAttest's
+// --obligations branch and cmdCompliance's --walkthrough/--report branch
+// rather than duplicated a third time, since this predicate's own
+// duplication was already flagged once (F3) as unacceptable for a safety
+// disclosure.
+function _lineageStalenessNoteLines(graphIsFresh, loaded, scan, subject) {
+  if (graphIsFresh) return null;
+  const capSubject = subject.charAt(0).toUpperCase() + subject.slice(1);
+  if (!loaded.ok) {
+    if (loaded.reason === 'missing') {
+      return [
+        'NOTE: no lineage graph found (AGENTIC_SECURITY_LINEAGE_DEEP=1 was not set on',
+        `the scan that produced last-scan.json) — ${subject} reads "unknown", by design.`,
+      ];
+    }
+    return [
+      `NOTE: lineage graph could not be loaded (${loaded.reason}: ${loaded.message})`,
+      `— ${subject} reads "unknown", by design.`,
+    ];
+  }
+  if (scan.scanHealth?.lineageAnalysis?.failure) {
+    return [
+      'NOTE: a lineage graph exists on disk, but this scan\'s own lineage build',
+      `failed (${scan.scanHealth.lineageAnalysis.failure}) — ignoring the stale graph`,
+      'rather than asserting a fact about code it may no longer reflect.',
+      `${capSubject} reads "unknown", by design.`,
+    ];
+  }
+  return [
+    'NOTE: a lineage graph exists on disk from an earlier deep scan, but this scan',
+    'did not run one (AGENTIC_SECURITY_LINEAGE_DEEP=1 was not set) — ignoring the',
+    'stale graph rather than asserting a fact about code it may no longer reflect.',
+    `${capSubject} reads "unknown", by design.`,
+  ];
+}
+
 // PRD D2 — emit signed, per-finding evidence bundles, and verify them.
 //
 // `attest` needs our private key. `verify-attestation` needs ONLY a public key,
@@ -2285,7 +2429,21 @@ async function cmdCompliance(args) {
       console.error(`Unknown framework "${wt}". Try --list.`);
       return 2;
     }
-    const evaluation = evaluateFramework(scanRoot, fw, scan);
+    // Final whole-branch review finding R2 (sub-project 6c), fixed here
+    // rather than merely disclosed: `scan.lineageGraph` is NEVER present
+    // in last-scan.json (see the identical, already-fixed defect in
+    // cmdAttest's --obligations branch above — engine.js only assigns
+    // scan.lineageGraph in-process; bin/agentic-security.js strips it
+    // before persisting, since the real graph gets its own signed
+    // artifact). --walkthrough has read scan.lineageGraph directly since
+    // it shipped in sub-project 6b, so every graph: mapping has always
+    // read "unknown" through this command regardless of whether
+    // AGENTIC_SECURITY_LINEAGE_DEEP=1 was ever set. Same shared, freshness
+    // -checked loader --obligations uses (loadFreshLineageGraph's own
+    // header has the full staleness reasoning).
+    const { loadFreshLineageGraph } = await import('../src/server/graph-loader.js');
+    const { graph: wtGraph, fresh: wtGraphIsFresh, loaded: wtLoaded } = loadFreshLineageGraph(scanRoot, scan);
+    const evaluation = evaluateFramework(scanRoot, fw, { ...scan, lineageGraph: wtGraph });
     if (fmt === 'oscal') {
       const { toOSCALCompliance, complianceRowsFromEvaluation } = await import('../src/report/oscal.js');
       writeStdout(JSON.stringify(
@@ -2295,6 +2453,13 @@ async function cmdCompliance(args) {
     }
     if (fmt === 'json') { writeStdout(JSON.stringify(evaluation, null, 2) + '\n'); return 0; }
     console.log(renderWalkthrough(fw, evaluation, {}));
+    // Scoped re-review finding (non-blocking, fixed): a stale/missing
+    // graph used to be discarded here with no disclosure at all — the
+    // same F2 gap already fixed for `attest --obligations`, unfixed on
+    // this sibling surface. Only the plain narrative gets the NOTE
+    // (never --format json/oscal, which must stay machine-parseable).
+    const wtNote = _lineageStalenessNoteLines(wtGraphIsFresh, wtLoaded, scan, 'every graph: mapping in this walkthrough');
+    if (wtNote) { console.log(''); for (const line of wtNote) console.log(line); }
     return 0;
   }
 
@@ -2395,6 +2560,106 @@ async function cmdAttest(args) {
     return 0;
   }
 
+  // Data Flow Explorer M4 sub-project 6c: a signed evidence pack for a
+  // Regulatory Obligation Overlay framework evaluation (FR-504). Unlike
+  // `--provenance` (a broad "attest everything" toggle with an optional
+  // narrowing id), `--obligations` genuinely REQUIRES a framework id — an
+  // evidence pack only exists per framework, and no "attest every
+  // framework" loop exists anywhere in this codebase.
+  if (args.flags.obligations) {
+    const frameworkId = args.flags.obligations === true ? null : args.flags.obligations;
+    if (!frameworkId) {
+      const { listFrameworks } = await import('../src/posture/auditor-walkthrough.js');
+      console.error('Usage: agentic-security attest --obligations <framework-id>');
+      console.error(`Bundled frameworks: ${listFrameworks(scanRoot).map((f) => f.id).join(', ')}`);
+      return 2;
+    }
+    const { loadFramework, evaluateFramework } = await import('../src/posture/auditor-walkthrough.js');
+    const {
+      buildObligationEvidencePack, signObligationEvidencePack, ensureKeyPair,
+    } = await import('../src/posture/obligation-evidence-pack.js');
+    // Task-2 review finding (blocking): scan.lineageGraph is NEVER present
+    // in last-scan.json — bin/agentic-security.js's own scan persistence
+    // deletes it before writing (`delete persistedScan.lineageGraph`,
+    // Sub-project E increment 5's own comment: "the lineage graph gets its
+    // OWN artifact file, never duplicated inside last-scan.json"). The real
+    // graph lives at .agentic-security/lineage-graph.json, signed
+    // separately — cmdExplore already established the correct way to read
+    // it. Final-review finding B2/F1 (blocking): a stale copy of that file
+    // must never be trusted just because it exists — see
+    // loadFreshLineageGraph's own header for the full reasoning
+    // (shared with compliance --walkthrough below, which had the
+    // identical gap).
+    const { loadFreshLineageGraph } = await import('../src/server/graph-loader.js');
+
+    let scan;
+    try { scan = JSON.parse(fs.readFileSync(statePath(scanRoot, 'last-scan.json'), 'utf8')); }
+    catch { console.error('No .agentic-security/last-scan.json — run a scan first.'); return 2; }
+
+    const fw = loadFramework(scanRoot, frameworkId);
+    if (!fw) { console.error(`Unknown framework: ${frameworkId}`); return 2; }
+
+    const { graph, fresh: graphIsFresh, loaded } = loadFreshLineageGraph(scanRoot, scan);
+
+    const evaluation = evaluateFramework(scanRoot, fw, { ...scan, lineageGraph: graph });
+    const pack = buildObligationEvidencePack({
+      graph,
+      framework: fw,
+      evaluation,
+      scanHealth: scan.scanHealth ?? null,
+      // Final whole-branch review finding B1 (blocking): these three
+      // fields live under scan.attestation (set by computeRunAttestation
+      // at scan time — bin/agentic-security.js's own `scan.attestation =
+      // computeRunAttestation({...})` call), never at the top level of
+      // last-scan.json — reading scan.engineVersion etc. directly always
+      // read undefined, leaving reproducibility permanently null through
+      // the real CLI. NOTE: the sibling attest (finding-bundle) and
+      // attest --provenance code paths a little above this branch read
+      // the SAME wrong top-level fields and carry the identical,
+      // pre-existing bug — real, disclosed, but out of this sub-project's
+      // scope to fix (they predate this branch's own diff).
+      engineVersion: scan.attestation?.engineVersion || null,
+      rulesetVersion: scan.attestation?.rulesetVersion || null,
+      bundleSha: scan.attestation?.bundleSha || null,
+    });
+
+    const kp = ensureKeyPair();
+    if (kp.created) console.error(`Generated a new signing key at ${kp.privateKey} (public: ${kp.publicKey}).`);
+
+    const outDir = statePath(scanRoot, 'attestations');
+    fs.mkdirSync(outDir, { recursive: true });
+    const signed = signObligationEvidencePack(pack, kp.privateKeyPem);
+    const name = `evidence-pack-${frameworkId}.json`.replace(/[^\w.-]/g, '_');
+    fs.writeFileSync(path.join(outDir, name), JSON.stringify(signed, null, 2) + '\n');
+
+    console.log(`Signed evidence pack for ${frameworkId} → ${path.relative(scanRoot, path.join(outDir, name))}`);
+    console.log(`Public key (share this with whoever verifies): ${kp.publicKey}`);
+    console.log('');
+    // Final whole-branch review finding R1 (recommended, fixed): the
+    // summary line named only unknown/manual/acceptedExceptions — an
+    // auditor scanning this output for a real, assessed gap_detected fact
+    // (the state a graph: predicate actually failing produces) saw "0 0 0"
+    // and nothing else, the same "a real gap can hide under an all-clear
+    // summary" failure class auditor-walkthrough.js's own ⚠️ prefix
+    // already exists to prevent (sub-project 6b's own final review).
+    const gapCount = pack.facts.filter((f) => f.state === 'gap_detected').length;
+    console.log(`  facts: ${pack.facts.length}  ${gapCount > 0 ? '⚠️ gaps: ' + gapCount + '  ' : ''}unknown: ${pack.unknownItems.length}  manual: ${pack.manualItems.length}  accepted exceptions: ${pack.acceptedExceptions.length}`);
+    console.log('');
+    console.log('A pack proves its contents are unmodified since signing. It does NOT');
+    console.log('certify compliance — read the pack\'s own `disclaimer` field.');
+    // Final whole-branch review finding F2 (recommended, fixed): this
+    // NOTE previously keyed on `!loaded.ok`, so the B2/F1 staleness guard
+    // above could silently discard a real graph with NO disclosure at
+    // all — an operator saw "unknown: 1" and nothing explaining why, even
+    // though a signed graph genuinely existed on disk. Keyed on
+    // `!graphIsFresh` instead (via the shared helper above
+    // cmdCompliance), so every path that discards a graph also explains
+    // why.
+    const obNote = _lineageStalenessNoteLines(graphIsFresh, loaded, scan, 'every graph: fact in this pack');
+    if (obNote) { console.log(''); for (const line of obNote) console.log(line); }
+    return 0;
+  }
+
   const {
     ensureKeyPair, buildEvidenceBundle, signEvidenceBundle,
   } = await import('../src/posture/evidence-bundle.js');
@@ -2566,6 +2831,31 @@ async function cmdVerifyAttestation(args) {
     return 0;
   }
 
+  // Data Flow Explorer M4 sub-project 6c: an obligation evidence pack
+  // (schema: agentic-security/obligation-evidence-pack@1) is a fifth
+  // distinct shape this same command can be handed — same auto-detection
+  // chain as the ComplianceEvidence/provenance branches above, dispatched
+  // by schema marker. Must be checked BEFORE the fallback
+  // verifyEvidenceBundle() call below, which assumes evidence-bundle.js's
+  // own shape and would misinterpret an evidence pack.
+  const { verifyObligationEvidencePack, OBLIGATION_EVIDENCE_PACK_SCHEMA } = await import('../src/posture/obligation-evidence-pack.js');
+  if (bundle.schema === OBLIGATION_EVIDENCE_PACK_SCHEMA) {
+    const or = verifyObligationEvidencePack(bundle, publicKeyPem);
+    if (!or.ok) { console.error(`✗ INVALID — ${or.reason}`); return 1; }
+    console.log('✓ VALID — the evidence pack is exactly what the signer produced.');
+    console.log('');
+    console.log(`  framework: ${bundle.framework?.id}  version: ${bundle.framework?.version}`);
+    // Final whole-branch review finding R1 (recommended, fixed) — same
+    // "a real gap must never hide under an all-clear summary" guard as
+    // the signing side above.
+    const bundleGapCount = (bundle.facts ?? []).filter((f) => f?.state === 'gap_detected').length;
+    console.log(`  facts: ${bundle.facts?.length ?? 0}  ${bundleGapCount > 0 ? '⚠️ gaps: ' + bundleGapCount + '  ' : ''}unknown: ${bundle.unknownItems?.length ?? 0}  manual: ${bundle.manualItems?.length ?? 0}  accepted exceptions: ${bundle.acceptedExceptions?.length ?? 0}`);
+    if (bundle.graphDigest) console.log(`  graph digest: ${bundle.graphDigest}`);
+    console.log('');
+    console.log(`  ${bundle.disclaimer}`);
+    return 0;
+  }
+
   const r = verifyEvidenceBundle(bundle, publicKeyPem);
   if (!r.ok) {
     console.error(`✗ INVALID — ${r.reason}`);
@@ -2974,76 +3264,3225 @@ Do not suppress anything you are not certain is a false positive. When in doubt,
   return 0;
 }
 
-async function main() {
-  const args = parseArgs(process.argv.slice(2));
-  const cmd = args._[0];
+// `agentic-security explore [path] [--port <n>] [--keep-open]` — Milestone 3,
+// sub-project Server, increment 1. Starts a local, read-only, loopback-only
+// HTTP server over an already-built, signed lineage graph
+// (.agentic-security/lineage-graph.json + .sig, written by a prior scan
+// with AGENTIC_SECURITY_LINEAGE_DEEP=1). Never triggers a scan itself
+// (Decision 2 of the scoping doc) — genuinely read-only end to end.
+//
+// Argument parsing mirrors cmdScan's own shape: scan root from args._[1]
+// (defaulting to cwd), flags parsed via args.flags. On a failed
+// loadSignedGraph, prints ONE of four distinct, clear error messages (see
+// graph-loader.js) and returns a non-zero exit code WITHOUT ever starting
+// the server. On success, starts the server and prints the URL + session
+// token to stdout — the ONLY place the token is ever displayed; it is
+// never written to a file and never logged again after this one print.
+//
+// The returned promise resolves (with exit code 0) only once the server
+// itself closes (idle-timeout auto-stop, or an external kill) — matching
+// every other cmdX(args) function's "resolves to an exit code" contract
+// while keeping the process alive for as long as the server is listening.
+async function cmdExplore(args) {
+  const target = args._[1] || '.';
+  const targetAbs = path.resolve(target);
+
+  const { loadSignedGraph } = await import('../src/server/graph-loader.js');
+  const loaded = loadSignedGraph(targetAbs);
+  if (!loaded.ok) {
+    process.stderr.write(`agentic-security explore: ${loaded.message}\n`);
+    return 1;
+  }
+
+  let port = 0;
+  if (args.flags.port !== undefined) {
+    if (typeof args.flags.port !== 'string' || !/^\d+$/.test(args.flags.port)) {
+      process.stderr.write(`agentic-security explore: invalid --port value "${args.flags.port}" — must be a non-negative integer.\n`);
+      return 1;
+    }
+    port = Number(args.flags.port);
+    if (port > 65535) {
+      process.stderr.write(`agentic-security explore: invalid --port value "${args.flags.port}" — must be <= 65535.\n`);
+      return 1;
+    }
+  }
+  const keepOpen = !!args.flags['keep-open'];
+
+  const { createExploreServer } = await import('../src/server/http-server.js');
+  const { generateSessionToken } = await import('../src/server/security.js');
+  const sessionToken = generateSessionToken();
+
+  let started;
   try {
-    switch (cmd) {
-      case 'scan':     process.exit(await cmdScan(args));
-      case 'ship':     process.exit(await cmdShip(args));
-      case 'ci':       process.exit(await cmdCi(args));
-      case 'fix':      process.exit(await cmdFix(args));
-      case 'undo':     process.exit(await cmdUndo(args));
-      case 'accept':   process.exit(await cmdAccept(args));
-      case 'profile':  process.exit(await cmdProfile(args));
-      case 'triage':   process.exit(await cmdTriage(args));
-      case 'org-scan': process.exit(await cmdOrgScan(args));
-      case 'rules':    process.exit(await cmdRules(args));
-      case 'rule':     process.exit(await cmdRule(args));
-      case 'tickets':  process.exit(await cmdTickets(args));
-      case 'secure':   process.exit(await cmdSecure(args));
-      case 'packs':    process.exit(await cmdPacks(args));
-      case 'validator-cache': process.exit(await cmdValidatorCache(args));
-      case 'verify':   process.exit(await cmdVerify(args));
-      case 'reset':    process.exit(await cmdReset(args));
-      case 'export':   process.exit(await cmdExport(args));
-      case 'legal-hold': process.exit(await cmdLegalHold(args));
-      case 'calibration-feedback': process.exit(await cmdCalibrationFeedback(args));
-      case 'calibration-report': process.exit(await cmdCalibrationReport(args));
-      case 'hunt':     process.exit(await cmdHunt(args));
-      case 'compliance': process.exit(await cmdCompliance(args));
-      case 'attest':   process.exit(await cmdAttest(args));
-      case 'verify-attestation': process.exit(await cmdVerifyAttestation(args));
-      case 'policy-explain': process.exit(await cmdPolicyExplain(args));
-      case 'policy-sign': process.exit(await cmdPolicySign(args));
-      case 'rule-synth': process.exit(await cmdRuleSynth(args));
-      case 'digest':   process.exit(await cmdDigest(args));
-      case 'setup':    process.exit(await cmdSetup(args));
-      case 'cache-report': {
-        // Prompt-cache economics for the current session: parse the Claude Code
-        // transcript usage and report cache-hit %, $ saved, and avoidable leaks.
-        // Advisory/read-only — always exits 0.
-        const { analyzeTranscript, formatCacheReport } = await import('../src/posture/cache-economics.js');
-        const projectDir = path.resolve(args.flags.root || process.env.CLAUDE_PROJECT_DIR || process.cwd());
-        const result = analyzeTranscript({ transcriptPath: args.flags.transcript, projectDir });
-        if (args.flags.json) writeStdout(JSON.stringify(result, null, 2) + '\n');
-        else console.log(formatCacheReport(result));
-        process.exit(0);
+    started = await createExploreServer({ graph: loaded.graph, port, sessionToken, keepOpen });
+  } catch (e) {
+    process.stderr.write(`agentic-security explore: failed to start server: ${e && e.message ? e.message : e}\n`);
+    return 1;
+  }
+  const { server, port: actualPort } = started;
+
+  // THE ONLY place the session token is ever displayed — never written to
+  // a file, never logged by the server itself after this one print. The
+  // token travels as a URL FRAGMENT (`#token=...`), never a query string:
+  // a fragment is never sent to the server in any HTTP request (so it can
+  // never be captured in an access log), yet the page's own JS can read it
+  // once via location.hash and attach it as a header on every subsequent
+  // /api/v1/* fetch() call (frontend/src/lib/api-client.js).
+  process.stdout.write(`agentic-security explore: serving ${targetAbs}\n`);
+  process.stdout.write(`  URL: http://127.0.0.1:${actualPort}/#token=${sessionToken}\n`);
+  process.stdout.write('  Open this URL in a browser — the page authenticates itself automatically.\n');
+  if (keepOpen) {
+    process.stdout.write('  --keep-open set: no idle-timeout auto-stop. Ctrl-C to stop.\n');
+  } else {
+    process.stdout.write('  Server auto-stops after a period of inactivity, or Ctrl-C to stop now.\n');
+  }
+
+  return new Promise((resolve) => {
+    server.on('close', () => resolve(0));
+  });
+}
+
+// `agentic-security dataflow export [path] --format <fmt> --output <file>
+// [--view <name>] [--size standard|2x] [--width <n>] [--height <n>]
+// [--no-redact] [--filter <path>]` — Milestone 4, sub-project 5 (CLI +
+// slash commands). Wires the six already-shipped M4 export/report
+// functions (scanner/scripts/export-image.mjs's exportPng/exportPdf/
+// exportSvg, scanner/src/lineage/export-json.js's exportGraphJSON,
+// scanner/src/lineage/export-csv.js's exportFlowsCSV, and
+// scanner/scripts/generate-html-report.mjs's generateHtmlReport) into
+// one consistent CLI surface.
+//
+// Argument shape mirrors cmdExplore's own: scan root from args._[2]
+// (args._[0]='dataflow', args._[1]='export', so the path — if given —
+// is the THIRD positional), defaulting to cwd. Uses the identical
+// loadSignedGraph contract and error-message pass-through as cmdExplore
+// (scoping doc's own binding decision: never proceed past a graph-load
+// failure).
+//
+// Exit codes: 0 success. 1 graph-load failure (loadSignedGraph's own
+// four reasons). 2 export-stage failure — bad/missing flags, an
+// unsupported format+view combination (svg + non-architecture view,
+// rejected BEFORE any Chrome invocation — Chrome's own dump-failure
+// reason for this case is confusing, not a good user-facing error), or
+// a caught throw/{ok:false} from the underlying export function.
+const DATAFLOW_EXPORT_FORMATS = new Set(['png', 'pdf', 'svg', 'json', 'csv', 'html', 'dpia', 'ropa', 'briefing', 'recipients', 'coverage']);
+const DATAFLOW_EXPORT_VIEWS = new Set(['architecture', 'privacy', 'trace', 'inventory']);
+const DATAFLOW_EXPORT_SIZES = { standard: { width: 1680, height: 945 }, '2x': { width: 3360, height: 1890 } };
+
+async function cmdDataflowExport(args) {
+  const target = args._[2] || '.';
+  const targetAbs = path.resolve(target);
+
+  const format = args.flags.format;
+  if (!format || !DATAFLOW_EXPORT_FORMATS.has(format)) {
+    process.stderr.write(`agentic-security dataflow export: --format must be one of ${[...DATAFLOW_EXPORT_FORMATS].join('|')} (got ${JSON.stringify(format)}).\n`);
+    return 2;
+  }
+  const outputPath = args.flags.output;
+  if (!outputPath || typeof outputPath !== 'string') {
+    process.stderr.write('agentic-security dataflow export: --output <file> is required.\n');
+    return 2;
+  }
+  const viewExplicit = args.flags.view !== undefined;
+  const view = args.flags.view || 'architecture';
+  if (!DATAFLOW_EXPORT_VIEWS.has(view)) {
+    process.stderr.write(`agentic-security dataflow export: --view must be one of ${[...DATAFLOW_EXPORT_VIEWS].join('|')} (got ${JSON.stringify(view)}).\n`);
+    return 2;
+  }
+  if (format === 'svg' && view !== 'architecture') {
+    process.stderr.write('agentic-security dataflow export: --format svg only supports --view architecture — only the Architecture View renders a real <svg> element.\n');
+    return 2;
+  }
+  // json/csv/html are not view-scoped (exportGraphJSON/exportFlowsCSV have
+  // no view concept; generateHtmlReport embeds the full interactive report,
+  // not one captured view) — found by the final whole-branch review: an
+  // explicit --view silently did nothing for these three formats, with no
+  // warning, while the docs presented --view as a universal option.
+  // dpia/ropa (M4 deliverable #10) join this same non-view-scoped set —
+  // emitGraphDpiaArtifact/emitGraphRopaArtifact have no --view concept
+  // either, mirroring json/csv's own precedent exactly. briefing (FR-501)
+  // joins the same set — emitDecisionStory has no --view concept either.
+  // recipients (FR-506) joins the same set — a Markdown table over
+  // graph.recipientProfiles[] has no --view concept either.
+  // coverage (M5, language coverage-tier disclosure) joins the same set —
+  // a Markdown table over graph.coverage.languages[] has no --view concept
+  // either.
+  if (viewExplicit && (format === 'json' || format === 'csv' || format === 'html' || format === 'dpia' || format === 'ropa' || format === 'briefing' || format === 'recipients' || format === 'coverage')) {
+    process.stderr.write(`agentic-security dataflow export: --view has no effect on --format ${format} — ${format} exports are not view-scoped.\n`);
+  }
+
+  // --audience (FR-501, briefing only): parsed and enum-validated
+  // unconditionally, matching --view's own precedent above — an invalid
+  // value is a clear exit-2 error regardless of --format, not silently
+  // accepted and then ignored. Defaults to export-briefing.js's own
+  // documented default ('technical') when omitted. AUDIENCE_MODES is
+  // imported (never hand-copied) so this validation can never drift from
+  // emitDecisionStory's own enum — the same single-source-of-truth
+  // discipline every other enum in this file follows.
+  const { AUDIENCE_MODES } = await import('../src/lineage/export-briefing.js');
+  const audienceExplicit = args.flags.audience !== undefined;
+  const audienceMode = args.flags.audience || 'technical';
+  if (!AUDIENCE_MODES.includes(audienceMode)) {
+    process.stderr.write(`agentic-security dataflow export: --audience must be one of ${AUDIENCE_MODES.join('|')} (got ${JSON.stringify(audienceMode)}).\n`);
+    return 2;
+  }
+  // Final whole-branch review finding (NITPICK, fixed): --view/--no-redact/
+  // --filter each warn when given for a format that ignores them; --audience
+  // silently no-op'd on every non-briefing format with no such warning.
+  if (audienceExplicit && format !== 'briefing') {
+    process.stderr.write(`agentic-security dataflow export: --audience has no effect on --format ${format} — only --format briefing is audience-aware.\n`);
+  }
+
+  // A bare flag (no following value, e.g. "--width --height 500") is
+  // parsed as boolean `true` by parseArgs — found by the final
+  // whole-branch review: `Number(true) === 1` passed the old
+  // Number.isSafeInteger guard unchanged, silently producing a 1-pixel
+  // image at exit 0. Require a plain, unsigned, non-hex/non-exponential
+  // digit string (rejects "true", "0x10", "1e3", leading zeros) AND cap
+  // the value — an absurd-but-safe-integer width/height (e.g.
+  // Number.MAX_SAFE_INTEGER) silently made Chrome fall back to its own
+  // default size instead of erroring; a sane ceiling turns that into a
+  // clean argument error instead of a silently-wrong image.
+  const MAX_DATAFLOW_EXPORT_DIMENSION = 20000;
+  function _isPlainPositiveIntString(s) {
+    return typeof s === 'string' && /^[1-9]\d*$/.test(s);
+  }
+
+  const sizeFlag = args.flags.size;
+  const hasWidthHeight = args.flags.width !== undefined || args.flags.height !== undefined;
+  if (sizeFlag !== undefined && hasWidthHeight) {
+    process.stderr.write('agentic-security dataflow export: --size and --width/--height are mutually exclusive — pick one.\n');
+    return 2;
+  }
+  let width, height;
+  if (sizeFlag !== undefined) {
+    if (!Object.prototype.hasOwnProperty.call(DATAFLOW_EXPORT_SIZES, sizeFlag)) {
+      process.stderr.write(`agentic-security dataflow export: --size must be one of ${Object.keys(DATAFLOW_EXPORT_SIZES).join('|')} (got ${JSON.stringify(sizeFlag)}).\n`);
+      return 2;
+    }
+    ({ width, height } = DATAFLOW_EXPORT_SIZES[sizeFlag]);
+  } else if (hasWidthHeight) {
+    if (!_isPlainPositiveIntString(args.flags.width) || !_isPlainPositiveIntString(args.flags.height)) {
+      process.stderr.write('agentic-security dataflow export: --width/--height must both be positive integers.\n');
+      return 2;
+    }
+    width = Number(args.flags.width);
+    height = Number(args.flags.height);
+    if (width > MAX_DATAFLOW_EXPORT_DIMENSION || height > MAX_DATAFLOW_EXPORT_DIMENSION) {
+      process.stderr.write(`agentic-security dataflow export: --width/--height must both be <= ${MAX_DATAFLOW_EXPORT_DIMENSION}.\n`);
+      return 2;
+    }
+  } else {
+    ({ width, height } = DATAFLOW_EXPORT_SIZES.standard);
+  }
+
+  const redact = args.flags['no-redact'] ? false : true;
+  if (!redact && format === 'csv') {
+    process.stderr.write('agentic-security dataflow export: --no-redact has no effect on --format csv — CSV export does not support redaction yet.\n');
+  }
+  // dpia/ropa (M4 deliverable #10): emitGraphDpiaArtifact/emitGraphRopaArtifact
+  // never call exportGraphJSON's own redaction path either — same
+  // precedent as csv above, same guard. briefing (FR-501) joins the same
+  // set — emitDecisionStory never calls exportGraphJSON's redaction path
+  // either. recipients (FR-506) joins the same set too — a judgment call,
+  // disclosed: as of fix-round-1 (B1), `redact-graph.js`'s `_redactGraph`
+  // DOES cover `graph.recipientProfiles[].technicalEndpoint`/`.legalEntity`/
+  // `.retentionCommitment`/`.transferMechanism` — but `--no-redact` is
+  // still a no-op for `recipients` specifically because
+  // `_renderDataflowRecipientsMarkdown` below never calls
+  // `exportGraphJSON`'s redaction path at all (it reads `graph` directly,
+  // the same way dpia/ropa/briefing's own renderers do) — a fact about
+  // THIS renderer's own code path, unrelated to whether `_redactGraph`
+  // itself has an opinion about the field.
+  // coverage (M5, language coverage-tier disclosure) joins the same set —
+  // graph.coverage.languages[] carries only curated static tier data and
+  // plain per-repo file counts, never a destination literal or evidence
+  // snippet redact-graph.js has any opinion about.
+  if (!redact && (format === 'dpia' || format === 'ropa' || format === 'briefing' || format === 'recipients' || format === 'coverage')) {
+    process.stderr.write(`agentic-security dataflow export: --no-redact has no effect on --format ${format} — ${format} export does not support redaction yet.\n`);
+  }
+
+  let filter;
+  if (args.flags.filter !== undefined) {
+    // A bare "--filter" (no value) or "--filter=" (empty string) must be
+    // rejected up front, not passed to path.resolve() — found by the
+    // final whole-branch review: path.resolve(true) throws a raw
+    // TypeError that escapes uncaught to exit 4 (the same defect class
+    // Task 1's own review found and fixed at the write stage, surviving
+    // here on a different flag); an empty string was falsy and silently
+    // dropped the whole filter instead of erroring.
+    if (typeof args.flags.filter !== 'string' || !args.flags.filter) {
+      process.stderr.write('agentic-security dataflow export: --filter requires a file path.\n');
+      return 2;
+    }
+    const filterPath = path.resolve(args.flags.filter);
+    try {
+      filter = JSON.parse(fs.readFileSync(filterPath, 'utf8'));
+    } catch (e) {
+      process.stderr.write(`agentic-security dataflow export: could not read/parse --filter file "${args.flags.filter}": ${e.message}\n`);
+      return 2;
+    }
+    // Milestone 5, large-graph pagination: this shape check now lives in
+    // export-json.js's validateFilterShape (extracted verbatim from what
+    // was previously this file's own inline copy) so the server's new
+    // POST /api/v1/query endpoint and the dataflow_get_graph MCP tool
+    // share the identical protection rather than a third, drifting copy.
+    const { validateFilterShape } = await import('../src/lineage/export-json.js');
+    const filterCheck = validateFilterShape(filter);
+    if (!filterCheck.valid) {
+      process.stderr.write(`agentic-security dataflow export: --filter file "${args.flags.filter}" ${filterCheck.error}.\n`);
+      return 2;
+    }
+    // exportFlowsCSV(graph) takes no opts at all — found by the final
+    // whole-branch review: --filter silently did nothing for --format
+    // csv (an operator scoping a CSV export to a safe subset silently
+    // got everything instead), with no warning, while both this file's
+    // own USAGE text and commands/dataflow.md presented --filter as a
+    // universal option.
+    // coverage (M5, language coverage-tier disclosure) joins the same set —
+    // a per-language table has no node/edge-id-scoped meaning to narrow by.
+    if (format === 'csv' || format === 'coverage') {
+      process.stderr.write(`agentic-security dataflow export: --filter has no effect on --format ${format} — ${format} export does not support scoping yet.\n`);
+    }
+  }
+
+  const { loadSignedGraph } = await import('../src/server/graph-loader.js');
+  const loaded = loadSignedGraph(targetAbs);
+  if (!loaded.ok) {
+    process.stderr.write(`agentic-security dataflow export: ${loaded.message}\n`);
+    return 1;
+  }
+  const graph = loaded.graph;
+  // Task-3 review finding (non-blocking, fixed): emitGraphDpiaArtifact's
+  // own opts.generatedAt fallback is `new Date()` — omitting it here made
+  // dpia/ropa the only two formats whose content reflects EXPORT-time
+  // wall clock rather than the graph's own already-fixed generatedAt (the
+  // same field json/html embed unconditionally), so exporting the
+  // identical persisted graph twice on two different days produced two
+  // different documents.
+  const opts = { view, width, height, redact, filter, generatedAt: graph.generatedAt, audienceMode };
+
+  let data;
+  try {
+    if (format === 'png' || format === 'pdf' || format === 'svg') {
+      const { exportPng, exportPdf, exportSvg } = await import('../scripts/export-image.mjs');
+      const fn = { png: exportPng, pdf: exportPdf, svg: exportSvg }[format];
+      const result = await fn(graph, opts);
+      if (!result.ok) {
+        process.stderr.write(`agentic-security dataflow export: ${result.reason}\n`);
+        return 2;
       }
-      case 'cache-statusline': {
-        // F6 — one-line cost HUD for a Claude Code statusLine command. Also writes
-        // .agentic-security/cache-telemetry.json for other pollers. Always exits 0.
-        const { analyzeTranscript, renderCacheStatusLine } = await import('../src/posture/cache-economics.js');
-        const projectDir = path.resolve(args.flags.root || process.env.CLAUDE_PROJECT_DIR || process.cwd());
-        const result = analyzeTranscript({ transcriptPath: args.flags.transcript, projectDir });
-        if (result.ok) {
-          try {
-            const dir = stateDir(projectDir);
-            fs.mkdirSync(dir, { recursive: true });
-            fs.writeFileSync(path.join(dir, 'cache-telemetry.json'),
-              JSON.stringify({ updatedAt: new Date().toISOString(), metrics: result.metrics, leaks: result.leaks }, null, 2));
-          } catch { /* best-effort */ }
-          console.log(renderCacheStatusLine(result.metrics));
-        } else {
-          console.log('agentic-security: no session cost yet');
-        }
-        process.exit(0);
+      data = result.data;
+    } else if (format === 'json') {
+      const { exportGraphJSON } = await import('../src/lineage/export-json.js');
+      data = JSON.stringify(exportGraphJSON(graph, opts), null, 2);
+    } else if (format === 'csv') {
+      const { exportFlowsCSV } = await import('../src/lineage/export-csv.js');
+      data = exportFlowsCSV(graph);
+    } else if (format === 'html') {
+      const { generateHtmlReport } = await import('../scripts/generate-html-report.mjs');
+      data = generateHtmlReport(graph, opts);
+    } else if (format === 'dpia') {
+      const { emitGraphDpiaArtifact } = await import('../src/lineage/export-privacy.js');
+      data = emitGraphDpiaArtifact(graph, opts);
+    } else if (format === 'ropa') {
+      const { emitGraphRopaArtifact } = await import('../src/lineage/export-privacy.js');
+      data = emitGraphRopaArtifact(graph, opts);
+    } else if (format === 'briefing') {
+      const { emitDecisionStory } = await import('../src/lineage/export-briefing.js');
+      data = emitDecisionStory(graph, opts).markdown;
+    } else if (format === 'recipients') {
+      data = _renderDataflowRecipientsMarkdown(graph, opts);
+    } else if (format === 'coverage') {
+      data = _renderDataflowCoverageMarkdown(graph, opts);
+    }
+  } catch (e) {
+    // dpia/ropa reach frontend/src/views/privacy-view.js via a relative
+    // import that lives OUTSIDE the published scanner/ package directory
+    // (`../../../frontend/...`, a repo-root sibling of scanner/) — real
+    // for the `agentic-security`/`as` commands (dist/agentic-security.mjs
+    // is ncc-bundled, so that content is already inlined and this path
+    // never triggers there), but a genuine ERR_MODULE_NOT_FOUND when
+    // someone runs THIS raw, unbundled file directly out of an installed
+    // package's node_modules, reproduced live via a real `npm pack` +
+    // install into a fresh consumer project. Give that one narrow case an
+    // actionable message instead of a bare "Cannot find package
+    // '@clear-capabilities/frontend'" that names a package the user has
+    // never heard of. Scoped re-review finding (fixed): checking only
+    // e.code === 'ERR_MODULE_NOT_FOUND' is too broad — it would also
+    // catch and mislabel an UNRELATED module-resolution failure (a real
+    // future bug, a genuinely broken install) with this same "you ran
+    // the raw bin file" message, masking it. Requiring the message to
+    // actually name the frontend import keeps this narrow to the one
+    // real case it was written for.
+    if ((format === 'dpia' || format === 'ropa') && e && e.code === 'ERR_MODULE_NOT_FOUND' && /privacy-view\.js/.test(e.message)) {
+      process.stderr.write(`agentic-security dataflow export: export failed: --format ${format} could not load its frontend module (${e.message}). This usually means you ran the raw bin/agentic-security.js file directly out of an installed package instead of using the published \`agentic-security\`/\`as\` command (which is fully self-contained). Use the published command, or run from a full source checkout with frontend/ present alongside scanner/.\n`);
+      return 2;
+    }
+    process.stderr.write(`agentic-security dataflow export: export failed: ${e && e.message ? e.message : e}\n`);
+    return 2;
+  }
+
+  const outAbs = path.resolve(outputPath);
+  try {
+    await fsp.mkdir(path.dirname(outAbs), { recursive: true });
+    await fsp.writeFile(outAbs, data);
+  } catch (e) {
+    // Found by Task 1's own review, reproduced live (--output pointing at
+    // an existing directory: EISDIR): left unguarded, this escaped to
+    // main()'s generic top-level catch, printing a raw stack trace and
+    // exiting 4 instead of the documented clean 0/1/2 contract.
+    process.stderr.write(`agentic-security dataflow export: could not write --output "${outputPath}": ${e && e.message ? e.message : e}\n`);
+    return 2;
+  }
+  process.stdout.write(`agentic-security dataflow export: wrote ${format} to ${outAbs}\n`);
+  return 0;
+}
+
+// Local Markdown-escaping helpers for `--format recipients` — byte-identical
+// to export-briefing.js's/export-privacy.js's/`_dfDiffMd*`'s own
+// _mdInline/_mdCell/_mdCode, reimplemented locally per this codebase's
+// established per-module-owns-its-own-escaping-helpers convention (see
+// export-briefing.js's own header comment for why these are never imported
+// across modules). Applied to every graph-derived or operator-recipient-
+// config-derived string (provider/legalEntity/dpaStatus/etc.) interpolated
+// into the Markdown report below.
+function _dfRecipientsMdInline(value) {
+  return String(value).replace(/\r\n|\r|\n/g, ' ');
+}
+function _dfRecipientsMdCell(value) {
+  return _dfRecipientsMdInline(value).replace(/\\/g, '\\\\').replace(/\|/g, '\\|');
+}
+function _dfRecipientsMdCode(value) {
+  const s = _dfRecipientsMdInline(value);
+  const runs = s.match(/`+/g);
+  const maxRun = runs ? Math.max(...runs.map((r) => r.length)) : 0;
+  if (maxRun === 0) return `\`${s}\``;
+  const fence = '`'.repeat(maxRun + 1);
+  return `${fence} ${s} ${fence}`;
+}
+
+// `--filter`'s scoping rule for `--format recipients` (a real design
+// decision the task brief left open, disclosed here): a RecipientProfile
+// has no node/edge of its own — it is a §10.10 extension record keyed by
+// `recipientKey`, associated with the graph only via `contributingGraphIds`
+// (the sink NODE ids that resolved to it, per `graph-builder.js`'s own
+// `opts.buildRecipientProfile` hook). So this format narrows
+// `graph.recipientProfiles` by whether ANY of a profile's
+// `contributingGraphIds` survive `filter.nodeIds` — mirroring the same
+// "narrow by referential soundness against the filtered node set" spirit
+// `export-json.js`'s own `_filterGraph` uses for flows, applied to this
+// format's own, different entity shape. `filter.edgeIds` has no effect on
+// this format (a recipient profile carries no edge reference at all) — a
+// filter file supplying only `edgeIds` therefore narrows this format to
+// nothing, an honest (not silently-wrong) consequence of the format having
+// no edge concept, not a bug.
+function _filterRecipientProfiles(recipientProfiles, filter) {
+  if (!filter) return recipientProfiles;
+  const nodeIds = new Set(filter.nodeIds ?? []);
+  return recipientProfiles.filter((p) => (p.contributingGraphIds ?? []).some((id) => nodeIds.has(id)));
+}
+
+// The table columns named by the task brief — a deliberate SUBSET of
+// `RecipientProfile`'s full `RECIPIENT_FACT_FIELDS` (14 fields; see
+// recipient-profile.js), not all of them: technicalEndpoint/servicePurpose/
+// subprocessorChain/dataResidencyCommitment/observedRegion/
+// transferMechanism/transferImpactReviewStatus/retentionCommitment are
+// real fields but not part of the brief's own named column list, so they
+// are omitted from the table (a future format revision could add them).
+// `processingCountries` is rendered under the "Jurisdiction(s)" header per
+// the brief's own wording. `confidence` is record-level metadata (no
+// `fieldEvidence` entry of its own — see recipient-profile.js's own header
+// comment on why), so it is shown in the table but excluded from the
+// per-row evidence-disclosure footer below.
+const _DATAFLOW_RECIPIENTS_FACT_COLUMNS = [
+  ['provider', 'Provider'],
+  ['serviceType', 'Service Type'],
+  ['legalEntity', 'Legal Entity'],
+  ['processorRole', 'Processor Role'],
+  ['processingCountries', 'Jurisdiction(s)'],
+  ['dpaStatus', 'DPA Status'],
+];
+
+function _dataflowRecipientsCellValue(profile, field) {
+  const value = profile[field];
+  if (field === 'processingCountries') {
+    return Array.isArray(value) && value.length > 0 ? value.join(', ') : '—';
+  }
+  return value === null || value === undefined || value === '' ? '—' : String(value);
+}
+
+// `agentic-security dataflow export --format recipients` (Milestone 4,
+// FR-506, Task 3) — one Markdown table row per `graph.recipientProfiles[]`
+// entry, plus a footer disclosing which fields are `code_inferred` vs
+// `declared` vs absent for each row (never fabricated — a field with no
+// `fieldEvidence` entry is disclosed as `absent`, not silently omitted).
+function _renderDataflowRecipientsMarkdown(graph, opts = {}) {
+  const profiles = _filterRecipientProfiles(graph.recipientProfiles ?? [], opts.filter);
+  const lines = [];
+  lines.push('# Third-Party and Cross-Border Recipient Intelligence');
+  lines.push('');
+  lines.push(`**Graph:** ${_dfRecipientsMdCode(graph.graphId ?? '(no graphId)')}`);
+  lines.push(`**Generated:** ${_dfRecipientsMdInline(opts.generatedAt ?? graph.generatedAt ?? '')}`);
+  if (opts.filter) lines.push('**Scope:** filtered to a subset of the graph (`--filter`).');
+  lines.push('');
+
+  if (profiles.length === 0) {
+    lines.push(opts.filter
+      ? 'No recipients survive the given `--filter` scope.'
+      : 'No recipients resolved for this graph — no sink site matched a known technical-provider catalog entry or an operator-declared `recipient-profiles.json` entry.');
+    return `${lines.join('\n')}\n`;
+  }
+
+  lines.push(`| ${_DATAFLOW_RECIPIENTS_FACT_COLUMNS.map(([, header]) => header).join(' | ')} | Confidence |`);
+  lines.push(`|${_DATAFLOW_RECIPIENTS_FACT_COLUMNS.map(() => '---').join('|')}|---|`);
+  for (const p of profiles) {
+    const cells = _DATAFLOW_RECIPIENTS_FACT_COLUMNS.map(([field]) => _dfRecipientsMdCell(_dataflowRecipientsCellValue(p, field)));
+    cells.push(_dfRecipientsMdCell(p.confidence ?? '—'));
+    lines.push(`| ${cells.join(' | ')} |`);
+  }
+
+  lines.push('');
+  lines.push('## Field evidence');
+  lines.push('');
+  lines.push('For each recipient above, whether each shown fact is code-inferred (from a real call site matching this codebase\'s technical-provider catalog), declared (from operator-supplied `recipient-profiles.json`), or absent (no source at all — never fabricated):');
+  lines.push('');
+  for (const p of profiles) {
+    lines.push(`### ${_dfRecipientsMdInline(p.provider ?? p.recipientKey ?? '(unknown recipient)')}`);
+    for (const [field, header] of _DATAFLOW_RECIPIENTS_FACT_COLUMNS) {
+      const ev = p.fieldEvidence ? p.fieldEvidence[field] : undefined;
+      const status = ev ? ev.factType : 'absent';
+      const sourceNote = ev && ev.source ? ` (source: ${_dfRecipientsMdInline(ev.source)})` : '';
+      lines.push(`- ${_dfRecipientsMdInline(header)}: ${_dfRecipientsMdInline(status)}${sourceNote}`);
+    }
+    lines.push('');
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+// Local Markdown-escaping helpers for `--format coverage` — byte-identical
+// to _dfRecipientsMdInline/_dfRecipientsMdCell/_dfRecipientsMdCode above,
+// reimplemented locally per this codebase's established
+// per-module-owns-its-own-escaping-helpers convention.
+function _dfCoverageMdInline(value) {
+  return String(value).replace(/\r\n|\r|\n/g, ' ');
+}
+function _dfCoverageMdCell(value) {
+  return _dfCoverageMdInline(value).replace(/\\/g, '\\\\').replace(/\|/g, '\\|');
+}
+
+// Milestone 5, language coverage-tier disclosure. Renders graph.coverage.
+// languages[] (Task 1's own additive fields: tier/irTaintRecallPct/
+// measuredAt/source, alongside the pre-existing filesExpected/filesAnalyzed)
+// as a Markdown table, with an explicit disclosure paragraph distinguishing
+// the two different KINDS of fact in this report: real, per-repo file
+// counts (filesAnalyzed/filesExpected, computed fresh on every scan) versus
+// a curated, product-level recall estimate (irTaintRecallPct/measuredAt/
+// source, unchanged since docs/METRICS.md was last measured) — never
+// presented as one number, since conflating them would imply this scan
+// itself measured its own recall, which it did not.
+function _renderDataflowCoverageMarkdown(graph, opts = {}) {
+  const lines = [];
+  lines.push('# Language Coverage');
+  lines.push('');
+  lines.push(`**Graph:** \`${_dfCoverageMdInline(graph.graphId ?? '(no graphId)')}\``);
+  lines.push(`**Generated:** ${_dfCoverageMdInline(opts.generatedAt ?? graph.generatedAt ?? '')}`);
+  lines.push('');
+  lines.push('`Files Analyzed`/`Files Expected` are real counts from THIS scan. `Tier` and `Recall (docs/METRICS.md)` are a curated, product-level estimate — unchanged since the date shown, not measured on this repository. The two are never the same kind of fact.');
+  lines.push('');
+  const languages = Array.isArray(graph.coverage?.languages) ? graph.coverage.languages : [];
+  if (languages.length === 0) {
+    lines.push('_No language coverage data available for this scan._');
+  } else {
+    lines.push('| Language | Files Analyzed | Files Expected | Tier | Recall (docs/METRICS.md) |');
+    lines.push('|---|---|---|---|---|');
+    for (const l of languages) {
+      const recall = typeof l.irTaintRecallPct === 'number'
+        ? `${l.irTaintRecallPct}% (as of ${_dfCoverageMdCell(l.measuredAt ?? '?')})`
+        : '—';
+      lines.push(`| ${_dfCoverageMdCell(l.language)} | ${_dfCoverageMdCell(l.filesAnalyzed)} | ${_dfCoverageMdCell(l.filesExpected)} | ${_dfCoverageMdCell(l.tier)} | ${recall} |`);
+    }
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+// `agentic-security dataflow diff [path] [--against <commit>]
+// [--drift-policy <path>] --output <file> [--format json|markdown]
+// [--fail-on-drift]` — Milestone 4, FR-503 sub-project 8b, Task 3. Reads
+// two persisted GraphSnapshot records (src/lineage/graph-snapshot.js),
+// computes a GraphDiff (src/lineage/graph-diff.js's computeGraphDiff, which
+// THROWS on an incomparable pair rather than returning an error object —
+// caught below and converted to the same clean-message-then-return-2
+// discipline cmdDataflowExport's own try/catch already established),
+// optionally evaluates operator drift policies against it
+// (src/lineage/drift-policy.js), and writes a JSON or Markdown report.
+//
+// Snapshot resolution — a real design decision the task brief itself left
+// open, disclosed here rather than in a comment only cmdDataflowExport's
+// own precedent would lead a reader to expect: graph-snapshot.js's own
+// git-HEAD resolver (`_gitHead`) is private and unexported, so this
+// function cannot independently ask "what is the current commit" the way
+// the scan-time persistence call site can. Instead, the CLI's own "AFTER"
+// snapshot is always `loadSnapshots(scanRoot)[0]` — the newest persisted
+// snapshot by file mtime — which is consistent with how a scan always
+// persists a snapshot for its own commit before `dataflow diff` would ever
+// run against that scanRoot (see test/cli/lineage-snapshot-persist.test.js
+// for the real, already-shipped precedent this assumption rests on).
+// `loadSnapshots(scanRoot)` returning `[]` is this function's "no snapshot
+// to compare against" exit-2 case. Without an explicit `--against`, the
+// "BEFORE" snapshot defaults to `mostRecentPriorSnapshot(scanRoot,
+// afterSnapshot.commit)` — also exit-2 if that is `null` (only one
+// snapshot exists, nothing to diff against yet). An explicit
+// `--against <commit>` resolves via `loadSnapshot(scanRoot, commit)` —
+// exit-2 with a clear message if that commit has no persisted snapshot.
+//
+// --format: the task brief's own invocation-signature line brackets
+// `[--format json|markdown]` as optional, but its own exit-code contract
+// explicitly lists "missing/invalid --format" as one of the enumerated
+// exit-2 cases — a real conflict between the two, resolved here (disclosed,
+// not silently picked) in favor of the more precisely-worded exit-code
+// contract: --format is REQUIRED, exactly like --output and exactly like
+// cmdDataflowExport's own --format above, never defaulted.
+//
+// --format json emits the raw GraphDiff record plus a `violations` array
+// (from evaluateDriftPolicies when --drift-policy was supplied). The task
+// brief leaves it as this implementation's own call whether to omit
+// `violations` or emit an empty array when no --drift-policy was given —
+// this always emits `violations: []` so the JSON shape is uniform across
+// both cases (a caller/test can always read `.violations` without an
+// `in`/`?.` check), disclosed here per the brief's own request.
+//
+// Exit codes, matching cmdDataflowExport's own documented contract shape:
+// 0 success (no violations, or violations found but --fail-on-drift not
+// passed); 2 usage/argument error (missing --output, missing/invalid
+// --format, no snapshot to compare against, an incomparable pair, a
+// malformed --drift-policy file); 1 if --drift-policy violations were
+// found AND --fail-on-drift was passed — the report is still written to
+// --output in that case, exactly like a passing run, so a CI caller gets
+// both the gate signal AND the artifact in one invocation.
+const DATAFLOW_DIFF_FORMATS = new Set(['json', 'markdown']);
+
+/** Resolves a flow id against a real DataFlowGraph v1 document for
+ * human-readable Markdown rendering — a GraphDiff's own added/removed/
+ * changed entries carry only {id, causeClassification, ...} (see
+ * graph-diff.js's own header), never dataElement/sink names directly.
+ * Mirrors drift-policy.js's own private _resolveFlowContext in spirit
+ * (same id-chasing logic), reimplemented locally here since that helper
+ * is not exported and this CLI's own rendering needs are narrower (labels
+ * only, no dataClasses/sinkCategory matching). Returns raw, UNESCAPED
+ * strings — callers interpolating into Markdown MUST pass every returned
+ * value through _mdInline/_mdCell/_mdCode below, never this function's
+ * output directly. */
+function _dataflowDiffFlowLabel(flowId, graph) {
+  const flow = (graph?.flows ?? []).find((f) => f.id === flowId);
+  if (!flow) return { dataElementNames: [], sinkLabel: null };
+  const dataElementNames = (flow.dataElementIds ?? [])
+    .map((id) => (graph.dataElements ?? []).find((d) => d.id === id)?.name)
+    .filter((n) => typeof n === 'string' && n.length > 0);
+  const sinkNode = (graph.nodes ?? []).find((n) => n.id === flow.sink) ?? null;
+  const sinkLabel = sinkNode?.label ?? sinkNode?.subtype ?? sinkNode?.kind ?? flow.sink ?? null;
+  return { dataElementNames, sinkLabel };
+}
+
+// Local Markdown-escaping helpers — byte-identical to export-briefing.js's/
+// export-privacy.js's own _mdInline/_mdCell/_mdCode, reimplemented locally
+// per this codebase's established per-module-owns-its-own-escaping-helpers
+// convention (see export-briefing.js's own header comment for why these
+// are never imported across modules). Applied to every graph-derived or
+// operator-drift-policy-derived string (flow ids, data element names, sink
+// labels, rule `reason` text) interpolated into the Markdown report below.
+function _dfDiffMdInline(value) {
+  return String(value).replace(/\r\n|\r|\n/g, ' ');
+}
+function _dfDiffMdCell(value) {
+  return _dfDiffMdInline(value).replace(/\\/g, '\\\\').replace(/\|/g, '\\|');
+}
+function _dfDiffMdCode(value) {
+  const s = _dfDiffMdInline(value);
+  const runs = s.match(/`+/g);
+  const maxRun = runs ? Math.max(...runs.map((r) => r.length)) : 0;
+  if (maxRun === 0) return `\`${s}\``;
+  const fence = '`'.repeat(maxRun + 1);
+  return `${fence} ${s} ${fence}`;
+}
+
+function _renderDataflowDiffMarkdown(diff, violations, beforeSnapshot, afterSnapshot, driftPolicyProvided) {
+  const graphAfter = afterSnapshot.graph ?? {};
+  const graphBefore = beforeSnapshot.graph ?? {};
+  const lines = [];
+
+  lines.push('# Data Flow Explorer — Graph Diff');
+  lines.push('');
+  lines.push(`**Before:** commit ${_dfDiffMdCode(beforeSnapshot.commit)} — captured ${_dfDiffMdInline(beforeSnapshot.capturedAt)}`);
+  lines.push(`**After:** commit ${_dfDiffMdCode(afterSnapshot.commit)} — captured ${_dfDiffMdInline(afterSnapshot.capturedAt)}`);
+  lines.push(`**Generated:** ${_dfDiffMdInline(diff.generatedAt)}`);
+  lines.push('');
+
+  // Drift-policy violations get their own top section — flagged
+  // prominently, never buried under the added/removed/changed detail, per
+  // the task brief's own explicit instruction.
+  lines.push('## Drift Policy Violations');
+  lines.push('');
+  if (!driftPolicyProvided) {
+    lines.push('_No `--drift-policy` supplied — policy evaluation was skipped._');
+  } else if (violations.length === 0) {
+    lines.push('No drift-policy violations detected.');
+  } else {
+    lines.push('| Trigger | Flow | Data Elements | Sink | Reason |');
+    lines.push('|---|---|---|---|---|');
+    for (const v of violations) {
+      const cells = [
+        v.trigger,
+        v.flowId,
+        (v.dataElementNames ?? []).join(', ') || '(none)',
+        v.sinkCategory ?? v.sinkNodeId ?? 'unknown',
+        v.reason,
+      ];
+      lines.push(`| ${cells.map(_dfDiffMdCell).join(' | ')} |`);
+    }
+  }
+  lines.push('');
+
+  lines.push('## Summary');
+  lines.push('');
+  lines.push(`- Nodes: +${diff.added.nodes.length} / -${diff.removed.nodes.length}`);
+  lines.push(`- Edges: +${diff.added.edges.length} / -${diff.removed.edges.length}`);
+  lines.push(`- Data elements: +${diff.added.dataElements.length} / -${diff.removed.dataElements.length}`);
+  lines.push(`- Flows: +${diff.added.flows.length} / -${diff.removed.flows.length} / ~${diff.changed.flows.length} changed`);
+  lines.push('');
+
+  const _entityList = (entries) => entries.map((e) => `- ${_dfDiffMdCode(e.id)} (${_dfDiffMdInline(e.causeClassification)})`);
+
+  lines.push('## Added');
+  lines.push('');
+  lines.push('### Flows');
+  if (diff.added.flows.length === 0) {
+    lines.push('_None._');
+  } else {
+    for (const e of diff.added.flows) {
+      const { dataElementNames, sinkLabel } = _dataflowDiffFlowLabel(e.id, graphAfter);
+      const de = dataElementNames.length ? dataElementNames.map(_dfDiffMdCode).join(', ') : 'unclassified data';
+      // Reidentification (fix round 1, Important 1 — see graph-diff.js's
+      // own judgment call #4): this is the SAME real-world flow as
+      // e.reidentifiedFrom, not a genuinely new code-level flow — only
+      // engine confidence/shape (evidenceGrade/transformationIds) changed.
+      // Must be surfaced here, never hidden, or a Markdown-only reader has
+      // no way to see the distinction the JSON report carries.
+      const flag = e.causeClassification === 'reidentified'
+        ? ` **(reidentified — same flow as ${_dfDiffMdCode(e.reidentifiedFrom)}, not a new code-level flow; only engine confidence/shape changed)**`
+        : '';
+      lines.push(`- ${_dfDiffMdCode(e.id)} — ${de} → ${_dfDiffMdCode(sinkLabel ?? 'unknown sink')} (first seen ${_dfDiffMdInline(e.firstSeen?.commit ?? '')})${flag}`);
+    }
+  }
+  lines.push('');
+  for (const [heading, key] of [['Nodes', 'nodes'], ['Edges', 'edges'], ['Data Elements', 'dataElements']]) {
+    lines.push(`### ${heading}`);
+    lines.push(diff.added[key].length === 0 ? '_None._' : _entityList(diff.added[key]).join('\n'));
+    lines.push('');
+  }
+
+  lines.push('## Removed');
+  lines.push('');
+  lines.push('### Flows');
+  if (diff.removed.flows.length === 0) {
+    lines.push('_None._');
+  } else {
+    for (const e of diff.removed.flows) {
+      const { dataElementNames, sinkLabel } = _dataflowDiffFlowLabel(e.id, graphBefore);
+      const de = dataElementNames.length ? dataElementNames.map(_dfDiffMdCode).join(', ') : 'unclassified data';
+      // Minor 1: inline the real reasons — the old text pointed at
+      // coverageRegressionReasons without ever rendering it, so a
+      // Markdown-only reader had no way to see the field at all.
+      // Reidentification flag mirrors the ## Added / ### Flows loop above
+      // (fix round 1, Important 1).
+      let flag = '';
+      if (e.causeClassification === 'possible_coverage_regression') {
+        flag = ` **(possible coverage regression: ${_dfDiffMdInline((e.coverageRegressionReasons ?? []).join('; '))})**`;
+      } else if (e.causeClassification === 'reidentified') {
+        flag = ` **(reidentified — same flow as ${_dfDiffMdCode(e.reidentifiedTo)}, not a real removal; only engine confidence/shape changed)**`;
       }
-      case 'mcp':      {
-        const { runStdio } = await import('../src/mcp/stdio.js');
-        const root = args.flags.root || process.env.AGENTIC_SECURITY_MCP_ROOT || process.cwd();
-        runStdio({ sessionRoot: path.resolve(root) });
-        return;
+      lines.push(`- ${_dfDiffMdCode(e.id)} — ${de} → ${_dfDiffMdCode(sinkLabel ?? 'unknown sink')} (last seen ${_dfDiffMdInline(e.lastSeen?.commit ?? '')})${flag}`);
+    }
+  }
+  lines.push('');
+  for (const [heading, key] of [['Nodes', 'nodes'], ['Edges', 'edges'], ['Data Elements', 'dataElements']]) {
+    lines.push(`### ${heading}`);
+    lines.push(diff.removed[key].length === 0 ? '_None._' : _entityList(diff.removed[key]).join('\n'));
+    lines.push('');
+  }
+
+  lines.push('## Changed');
+  lines.push('');
+  lines.push('### Flows');
+  if (diff.changed.flows.length === 0) {
+    lines.push('_None._');
+  } else {
+    for (const e of diff.changed.flows) {
+      const changeText = e.changes.map((c) => `${_dfDiffMdInline(c.field)}: ${_dfDiffMdCode(JSON.stringify(c.before))} -> ${_dfDiffMdCode(JSON.stringify(c.after))}`).join('; ');
+      lines.push(`- ${_dfDiffMdCode(e.id)} — ${changeText}`);
+    }
+  }
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+// Shared between `dataflow diff` and `dataflow watch` — parse-then-shape-
+// check a --drift-policy file BEFORE ever calling loadDriftPolicies.
+// loadDriftPolicies (src/lineage/drift-policy.js) never throws — a
+// malformed file degrades to {policies: []} with only a console.error
+// warning, matching loadPrivacySinkPolicy's own precedent. That is the
+// right default for a LOADER with no caller-facing error channel, but both
+// CLI commands' own exit-code contracts explicitly promise exit 2 for "a
+// malformed --drift-policy file" — so the malformed-JSON case, AND the
+// wrong-top-level-shape case (syntactically valid JSON, wrong shape, which
+// previously loaded zero rules with zero warning — sub-project 8b's own fix
+// round, Important 2), are both detected independently, here, before
+// delegating to the real loader for the actual (identically-parsed) policy
+// content. `cmdLabel` names the subcommand ("diff"/"watch") in the error
+// text. Returns `{ok:true}` or `{ok:false, message}` — never throws.
+function _validateDriftPolicyFile(driftPolicyAbs, driftPolicyFlag, cmdLabel) {
+  if (!fs.existsSync(driftPolicyAbs)) {
+    return { ok: false, message: `agentic-security dataflow ${cmdLabel}: --drift-policy file "${driftPolicyFlag}" does not exist.\n` };
+  }
+  let parsedDriftPolicy;
+  try {
+    parsedDriftPolicy = JSON.parse(fs.readFileSync(driftPolicyAbs, 'utf8'));
+  } catch (e) {
+    return { ok: false, message: `agentic-security dataflow ${cmdLabel}: could not parse --drift-policy file "${driftPolicyFlag}": ${e.message}\n` };
+  }
+  if (!parsedDriftPolicy || typeof parsedDriftPolicy !== 'object' || Array.isArray(parsedDriftPolicy) || !Array.isArray(parsedDriftPolicy.policies)) {
+    return { ok: false, message: `agentic-security dataflow ${cmdLabel}: --drift-policy file "${driftPolicyFlag}" must be a JSON object of the form {"policies":[...]} (got a different shape).\n` };
+  }
+  return { ok: true };
+}
+
+async function cmdDataflowDiff(args) {
+  const target = args._[2] || '.';
+  const targetAbs = path.resolve(target);
+
+  const outputPath = args.flags.output;
+  if (!outputPath || typeof outputPath !== 'string') {
+    process.stderr.write('agentic-security dataflow diff: --output <file> is required.\n');
+    return 2;
+  }
+
+  const format = args.flags.format;
+  if (!format || !DATAFLOW_DIFF_FORMATS.has(format)) {
+    process.stderr.write(`agentic-security dataflow diff: --format must be one of ${[...DATAFLOW_DIFF_FORMATS].join('|')} (got ${JSON.stringify(format)}).\n`);
+    return 2;
+  }
+
+  const againstFlag = args.flags.against;
+  if (againstFlag !== undefined && (typeof againstFlag !== 'string' || !againstFlag)) {
+    process.stderr.write('agentic-security dataflow diff: --against requires a commit value.\n');
+    return 2;
+  }
+
+  const driftPolicyFlag = args.flags['drift-policy'];
+  if (driftPolicyFlag !== undefined && (typeof driftPolicyFlag !== 'string' || !driftPolicyFlag)) {
+    process.stderr.write('agentic-security dataflow diff: --drift-policy requires a file path.\n');
+    return 2;
+  }
+
+  const failOnDrift = !!args.flags['fail-on-drift'];
+
+  // Snapshot resolution — see this function's own header comment above for
+  // the full disclosed reasoning (no unexported git-HEAD resolver
+  // available to this CLI, so "AFTER" is always the newest persisted
+  // snapshot for scanRoot).
+  const snapshots = loadSnapshots(targetAbs);
+  if (snapshots.length === 0) {
+    process.stderr.write(`agentic-security dataflow diff: no persisted GraphSnapshot found for "${targetAbs}" — run a scan with AGENTIC_SECURITY_LINEAGE_DEEP=1 first.\n`);
+    return 2;
+  }
+  const afterSnapshot = snapshots[0];
+
+  let beforeSnapshot;
+  if (againstFlag !== undefined) {
+    beforeSnapshot = loadSnapshot(targetAbs, againstFlag);
+    if (!beforeSnapshot) {
+      process.stderr.write(`agentic-security dataflow diff: no persisted GraphSnapshot found for commit "${againstFlag}" — pass a commit that was actually scanned.\n`);
+      return 2;
+    }
+  } else {
+    beforeSnapshot = mostRecentPriorSnapshot(targetAbs, afterSnapshot.commit);
+    if (!beforeSnapshot) {
+      process.stderr.write(`agentic-security dataflow diff: only one persisted GraphSnapshot exists (commit "${afterSnapshot.commit}") — nothing to compare against yet. Scan again after a code change, or pass --against <commit>.\n`);
+      return 2;
+    }
+  }
+
+  // Fix round 1, Minor 2: --against resolving to the SAME commit as the
+  // current ("AFTER") snapshot is a plausible CI mistake that would
+  // otherwise silently resolve an all-empty diff and pass --fail-on-drift.
+  // The default (--against omitted) path can't hit this on its own —
+  // mostRecentPriorSnapshot explicitly excludes afterSnapshot.commit — but
+  // checking here, after both branches converge, is simpler and correct
+  // either way.
+  if (beforeSnapshot.commit === afterSnapshot.commit) {
+    process.stderr.write(`agentic-security dataflow diff: refusing a self-diff — --against resolved to the same commit as the current snapshot ("${afterSnapshot.commit}"). Pass a different --against, or scan again after a code change.\n`);
+    return 2;
+  }
+
+  const { computeGraphDiff } = await import('../src/lineage/graph-diff.js');
+  let diff;
+  try {
+    diff = computeGraphDiff(beforeSnapshot, afterSnapshot);
+  } catch (e) {
+    // computeGraphDiff THROWS (never returns an error object) on an
+    // incomparable pair — converted to the same clean-message-then-
+    // return-2 discipline cmdDataflowExport's own try/catch establishes.
+    process.stderr.write(`agentic-security dataflow diff: ${e && e.message ? e.message : e}\n`);
+    return 2;
+  }
+
+  let violations = [];
+  const driftPolicyProvided = driftPolicyFlag !== undefined;
+  if (driftPolicyProvided) {
+    const driftPolicyAbs = path.resolve(driftPolicyFlag);
+    const check = _validateDriftPolicyFile(driftPolicyAbs, driftPolicyFlag, 'diff');
+    if (!check.ok) {
+      process.stderr.write(check.message);
+      return 2;
+    }
+
+    const { loadDriftPolicies, evaluateDriftPolicies } = await import('../src/lineage/drift-policy.js');
+    const policies = loadDriftPolicies(driftPolicyAbs);
+    violations = evaluateDriftPolicies(diff, policies, afterSnapshot.graph).violations;
+  }
+
+  let data;
+  if (format === 'json') {
+    data = JSON.stringify({ ...diff, violations }, null, 2);
+  } else {
+    data = _renderDataflowDiffMarkdown(diff, violations, beforeSnapshot, afterSnapshot, driftPolicyProvided);
+  }
+
+  const outAbs = path.resolve(outputPath);
+  try {
+    await fsp.mkdir(path.dirname(outAbs), { recursive: true });
+    await fsp.writeFile(outAbs, data);
+  } catch (e) {
+    process.stderr.write(`agentic-security dataflow diff: could not write --output "${outputPath}": ${e && e.message ? e.message : e}\n`);
+    return 2;
+  }
+
+  process.stdout.write(`agentic-security dataflow diff: wrote ${format} to ${outAbs} (${violations.length} drift-policy violation(s))\n`);
+
+  if (failOnDrift && violations.length > 0) return 1;
+  return 0;
+}
+
+// agentic-security dataflow scenario apply [path] --operations <file>
+// --output <file> [--format json|markdown] [--privacy-sink-policy <file>]
+// [--environment <name>] — M5 deliverable #3a (FR-502). Loads the
+// already-scanned, already-signed graph via loadSignedGraph (same
+// loader/error-message contract as cmdDataflowExport/cmdDataflowDiff),
+// applies the Scenario in --operations via applyScenario, diffs the
+// result against the base graph via diffScenarioGraph, writes the
+// report to --output. Exit codes: 0 success, 1 graph-load failure
+// (loadSignedGraph's own 4 messages), 2 argument/operations-file
+// problem.
+async function cmdDataflowScenarioApply(args) {
+  const target = args._[3] || '.'; // args._ = ['dataflow', 'scenario', 'apply', <path>?]
+  const targetAbs = path.resolve(target);
+
+  const operationsFlag = args.flags.operations;
+  if (!operationsFlag || typeof operationsFlag !== 'string') {
+    process.stderr.write('agentic-security dataflow scenario apply: --operations <file> is required.\n');
+    return 2;
+  }
+  const outputPath = args.flags.output;
+  if (!outputPath || typeof outputPath !== 'string') {
+    process.stderr.write('agentic-security dataflow scenario apply: --output <file> is required.\n');
+    return 2;
+  }
+  const format = args.flags.format ?? 'json';
+  if (format !== 'json' && format !== 'markdown') {
+    process.stderr.write(`agentic-security dataflow scenario apply: --format must be one of json|markdown (got ${JSON.stringify(format)}).\n`);
+    return 2;
+  }
+
+  let opsInput;
+  try {
+    opsInput = JSON.parse(fs.readFileSync(path.resolve(operationsFlag), 'utf8'));
+  } catch (e) {
+    process.stderr.write(`agentic-security dataflow scenario apply: could not read/parse --operations file "${operationsFlag}": ${e.message}\n`);
+    return 2;
+  }
+
+  const { loadSignedGraph } = await import('../src/server/graph-loader.js');
+  const loaded = loadSignedGraph(targetAbs);
+  if (!loaded.ok) {
+    process.stderr.write(`agentic-security dataflow scenario apply: ${loaded.message}\n`);
+    return 1;
+  }
+  const baseGraph = loaded.graph;
+
+  const { validateScenario } = await import('../src/lineage/scenario.js');
+  const { computeGraphDigest } = await import('../src/lineage/export-json.js');
+  const { scenarioId } = await import('../src/lineage/ids.js');
+  const baseGraphDigest = computeGraphDigest(baseGraph);
+  const cliAuthor = opsInput.author ?? 'cli';
+  const cliCreatedAt = new Date().toISOString();
+  const scenarioDraft = {
+    id: scenarioId({ graphId: baseGraph.graphId, graphDigest: baseGraphDigest }, [cliAuthor, cliCreatedAt]),
+    version: '1.0.0',
+    baseGraphId: baseGraph.graphId, baseGraphDigest,
+    operations: opsInput.operations ?? [],
+    assumptions: opsInput.assumptions ?? [], author: cliAuthor,
+    createdAt: cliCreatedAt, expiration: null,
+    simulatedDelta: null, verificationRequirements: opsInput.verificationRequirements ?? [],
+  };
+  const { valid, errors } = validateScenario(scenarioDraft);
+  if (!valid) {
+    process.stderr.write(`agentic-security dataflow scenario apply: --operations file failed validation:\n${errors.map((e) => `  ${e.path}: ${e.message}`).join('\n')}\n`);
+    return 2;
+  }
+
+  let privacySinkPolicy;
+  const policyFlag = args.flags['privacy-sink-policy'];
+  if (policyFlag !== undefined) {
+    try {
+      privacySinkPolicy = JSON.parse(fs.readFileSync(path.resolve(policyFlag), 'utf8'));
+    } catch (e) {
+      process.stderr.write(`agentic-security dataflow scenario apply: could not read/parse --privacy-sink-policy file "${policyFlag}": ${e.message}\n`);
+      return 2;
+    }
+  }
+
+  const { applyScenario } = await import('../src/lineage/scenario-engine.js');
+  const { diffScenarioGraph } = await import('../src/lineage/scenario-diff.js');
+  const opts = { privacySinkPolicy, environment: args.flags.environment };
+  const { graph: scenarioGraph, appliedOperations, skippedOperations } = applyScenario(baseGraph, scenarioDraft, opts);
+  const { changedEntities, removedEntityIds } = diffScenarioGraph(baseGraph, scenarioGraph);
+
+  const report = { scenarioId: scenarioDraft.id, appliedOperations, skippedOperations, changedEntities, removedEntityIds, generatedAt: new Date().toISOString() };
+  let data;
+  if (format === 'json') {
+    data = JSON.stringify(report, null, 2);
+  } else {
+    const lines = [`# Scenario delta`, '', `Applied ${appliedOperations.length} operation(s), skipped ${skippedOperations.length}.`, ''];
+    if (skippedOperations.length) {
+      lines.push('## Skipped operations', '');
+      for (const s of skippedOperations) lines.push(`- \`${s.operation.kind}\`: ${s.reason}`);
+      lines.push('');
+    }
+    lines.push('## Changed entities', '');
+    for (const c of changedEntities) {
+      lines.push(`- **${c.kind} ${c.id}**${c.label ? ` — **${c.label}**` : ''}`);
+      for (const f of c.changedFields) lines.push(`  - \`${f.field}\`: ${JSON.stringify(f.before)} → ${JSON.stringify(f.after)}`);
+    }
+    if (removedEntityIds.length) {
+      lines.push('', '## Removed entities', '');
+      for (const id of removedEntityIds) lines.push(`- ${id}`);
+    }
+    data = lines.join('\n') + '\n';
+  }
+  try {
+    await fsp.mkdir(path.dirname(path.resolve(outputPath)), { recursive: true });
+    await fsp.writeFile(path.resolve(outputPath), data);
+  } catch (e) {
+    process.stderr.write(`agentic-security dataflow scenario apply: could not write --output "${outputPath}": ${e && e.message ? e.message : e}\n`);
+    return 2;
+  }
+  return 0;
+}
+
+// agentic-security dataflow impact assess [path] --target <canonical-id>
+// --output <file> [--format json|markdown] — M5 deliverable #4
+// (FR-507). Loads the already-scanned, already-signed graph via
+// loadSignedGraph (same loader/error-message contract as every other
+// dataflow subcommand), computes an ImpactAssessment via
+// computeImpactAssessment, writes it to --output. Exit codes: 0
+// success; 1 graph-load failure (loadSignedGraph's own 4 messages) OR
+// a structurally malformed graph reaching computeImpactAssessment
+// (loadSignedGraph performs no schema validation — a graph-CONTENT
+// problem, not a CLI argument problem); 2 a genuine CLI argument
+// problem (missing --target/--output, or a --target with no
+// recognized canonical-id prefix).
+async function cmdDataflowImpactAssess(args) {
+  const target = args._[3] || '.'; // args._ = ['dataflow', 'impact', 'assess', <path>?]
+  const targetAbs = path.resolve(target);
+
+  const targetIdFlag = args.flags.target;
+  if (!targetIdFlag || typeof targetIdFlag !== 'string') {
+    process.stderr.write('agentic-security dataflow impact assess: --target <canonical-id> is required.\n');
+    return 2;
+  }
+  const outputPath = args.flags.output;
+  if (!outputPath || typeof outputPath !== 'string') {
+    process.stderr.write('agentic-security dataflow impact assess: --output <file> is required.\n');
+    return 2;
+  }
+  const format = args.flags.format ?? 'json';
+  if (format !== 'json' && format !== 'markdown') {
+    process.stderr.write(`agentic-security dataflow impact assess: --format must be one of json|markdown (got ${JSON.stringify(format)}).\n`);
+    return 2;
+  }
+
+  const { loadSignedGraph } = await import('../src/server/graph-loader.js');
+  const loaded = loadSignedGraph(targetAbs);
+  if (!loaded.ok) {
+    process.stderr.write(`agentic-security dataflow impact assess: ${loaded.message}\n`);
+    return 1;
+  }
+
+  const { computeImpactAssessment } = await import('../src/lineage/impact-engine.js');
+  let record;
+  try {
+    record = computeImpactAssessment(loaded.graph, targetIdFlag);
+  } catch (e) {
+    const message = e && e.message ? e.message : String(e);
+    process.stderr.write(`agentic-security dataflow impact assess: ${message}\n`);
+    // A malformed graph (e.g. a signed-but-structurally-broken document —
+    // loadSignedGraph performs no schema validation, only signature +
+    // JSON.parse) is a graph-CONTENT problem, not a CLI argument
+    // problem — exit 1, matching loadSignedGraph's own failure exit
+    // code above, not the exit-2 "bad --target/--output" case below.
+    return message.startsWith('computeImpactAssessment: malformed graph') ? 1 : 2;
+  }
+
+  let data;
+  if (format === 'json') {
+    data = JSON.stringify(record, null, 2);
+  } else {
+    const lines = [
+      `# Impact assessment`, '',
+      `id: \`${record.id}\``,
+      `graphId: \`${record.graphId}\``,
+      `graphDigest: \`${record.graphDigest}\``,
+      `generatedAt: ${record.generatedAt}`, '',
+      `Target: \`${record.targetId}\` (${record.targetKind})`,
+      `Scope: ${record.scope} (traceKind: ${record.traceKind})`, '',
+      `## Affected nodes (${record.affectedNodeIds.length})`, '',
+      ...record.affectedNodeIds.map((id) => `- ${id}`), '',
+      `## Affected edges (${record.affectedEdgeIds.length})`, '',
+      ...record.affectedEdgeIds.map((id) => `- ${id}`), '',
+      `## Affected data classes`, '',
+      record.affectedDataClasses.length ? record.affectedDataClasses.map((c) => `- ${c}`).join('\n') : '_none_', '',
+      `## Affected recipients`, '',
+      record.affectedRecipientProfileIds.length ? record.affectedRecipientProfileIds.map((id) => `- ${id}`).join('\n') : '_none_', '',
+    ];
+    if (record.coverageLimitations.length) {
+      lines.push('## Coverage limitations', '', ...record.coverageLimitations.map((s) => `- ${s}`), '');
+    }
+    data = lines.join('\n') + '\n';
+  }
+  try {
+    await fsp.mkdir(path.dirname(path.resolve(outputPath)), { recursive: true });
+    await fsp.writeFile(path.resolve(outputPath), data);
+  } catch (e) {
+    process.stderr.write(`agentic-security dataflow impact assess: could not write --output "${outputPath}": ${e && e.message ? e.message : e}\n`);
+    return 2;
+  }
+  return 0;
+}
+
+// ── dataflow observations import/list + dataflow twin — M5 deliverable #7
+// (Runtime-Corroborated Digital Twin, "7b" — runtime-observed only; FR-505,
+// AC-29). This is the AC-29 proof surface: the first place a human operator
+// can actually see and act on the whole deliverable.
+//
+// `observations import` is the one mutating verb in this trio, and it is
+// dry-run-by-default exactly like `governance propose-edit`/`remediation
+// open`: without --yes it computes and prints exactly what WOULD be
+// imported and writes nothing; with --yes it writes through
+// `persistObservationImport` (the store's own closed-world validation is
+// the authoritative gate — this command's own `validateRuntimeObservation`
+// call below is a deliberate PREVIEW, so an operator sees a rejection
+// before ever passing --yes) and appends a real `auditCall` entry, never
+// on a dry run and never on a rejected import.
+//
+// Exit-code contract, identical to `dataflow impact assess`'s plus an
+// explicit 4: 0 success (preview or real write); 1 a validation failure (a
+// rejected record, a malformed adapter input, a graph-load failure via
+// `loadSignedGraph`'s own four messages); 2 a usage/argument error or an
+// `isSafeStateDir` refusal; 4 an unexpected I/O error during the write
+// itself — nothing was written and no audit event was recorded.
+//
+// Refuse the WHOLE import, never a partial one (AC-29 clause 5): every
+// adapter parse error AND every per-record `validateRuntimeObservation`
+// failure is collected across the whole file before any exit decision is
+// made, so a payload-shaped record caught at the wire layer (an unknown
+// top-level key) and a payload-shaped record caught one layer up (an
+// unapproved attribute key) are both named in the SAME refusal — silently
+// dropping just the ones the adapter caught and importing the rest would
+// be exactly the partial-import failure this deliverable exists to
+// prevent.
+// M5 (final review): --source is a second unconstrained, ≤512-char,
+// verbatim-persisted, verbatim-echoed-by-`observations list` value channel
+// — smaller than B1's own attribute-value hole but the same shape. Mirrors
+// runtime-observation.js's own `_isIdentifierValue` character class
+// locally rather than importing it — that module's own constant caps at
+// 128 characters (the attribute-value cap), while `source` is validated up
+// to 512 characters (`validateRuntimeObservation`'s own `$.source` check),
+// so reusing the 128-char-capped version verbatim would reject a
+// legitimate long-but-real source name the schema itself still permits.
+// A real filename basename (this flag's own default) already satisfies
+// this grammar.
+const _SOURCE_IDENTIFIER_RE = /^[A-Za-z0-9._:-]{1,512}$/;
+
+async function cmdDataflowObservationsImport(args) {
+  const target = args._[3] || '.'; // args._ = ['dataflow', 'observations', 'import', <path>?]
+  const targetAbs = path.resolve(target);
+
+  const { adapterFor } = await import('../src/lineage/observation-adapters.js');
+  const adapterFlag = args.flags.adapter;
+  if (!adapterFlag || typeof adapterFlag !== 'string') {
+    process.stderr.write('agentic-security dataflow observations import: --adapter <name> is required (currently only "native-jsonl" is supported).\n');
+    return 2;
+  }
+  const adapterImpl = adapterFor(adapterFlag);
+  if (!adapterImpl) {
+    process.stderr.write(`agentic-security dataflow observations import: unknown --adapter "${adapterFlag}" — only "native-jsonl" is supported.\n`);
+    return 2;
+  }
+
+  const inputFlag = args.flags.input;
+  if (!inputFlag || typeof inputFlag !== 'string') {
+    process.stderr.write('agentic-security dataflow observations import: --input <file> is required.\n');
+    return 2;
+  }
+  const inputPath = path.resolve(inputFlag);
+  if (!fs.existsSync(inputPath)) {
+    process.stderr.write(`agentic-security dataflow observations import: --input file not found: "${inputFlag}".\n`);
+    return 2;
+  }
+
+  const _isoOk = (v) => typeof v === 'string' && v.length > 0 && Number.isFinite(Date.parse(v));
+  const windowStart = args.flags['window-start'];
+  const windowEnd = args.flags['window-end'];
+  if (!_isoOk(windowStart) || !_isoOk(windowEnd)) {
+    process.stderr.write('agentic-security dataflow observations import: --window-start and --window-end are both required and must be parseable ISO-8601 date-times.\n');
+    return 2;
+  }
+  if (Date.parse(windowStart) > Date.parse(windowEnd)) {
+    process.stderr.write('agentic-security dataflow observations import: --window-start must not be after --window-end.\n');
+    return 2;
+  }
+
+  // M1 (final review): --retain-until is recorded as retention.expiresAt
+  // and NOTHING ELSE — it is not currently enforced in either direction.
+  // An import past its declared expiresAt is not automatically deleted
+  // (grep confirms zero consumers of retention.expiresAt outside this
+  // store's own validator and `observations list`'s display column), and
+  // `reset --yes` sweeps the WHOLE store regardless of any individual
+  // import's own expiresAt. Real enforcement is separate, larger scope
+  // (touching `reset`/`retention-policy.js`) — this comment (and
+  // `commands/dataflow.md`'s own matching wording) exists so this flag's
+  // NAME never implies protection the implementation does not provide.
+  const retainUntilFlag = args.flags['retain-until'];
+  let retainUntil = null;
+  if (retainUntilFlag !== undefined) {
+    if (!_isoOk(retainUntilFlag)) {
+      process.stderr.write('agentic-security dataflow observations import: --retain-until must be a parseable ISO-8601 date-time. Note: this value is recorded as retention.expiresAt but is NOT currently enforced by anything — an import past its declared expiresAt is not auto-deleted, and `reset --yes` sweeps the whole store regardless.\n');
+      return 2;
+    }
+    retainUntil = retainUntilFlag;
+  }
+
+  const { loadSignedGraph } = await import('../src/server/graph-loader.js');
+  const loaded = loadSignedGraph(targetAbs);
+  if (!loaded.ok) {
+    process.stderr.write(`agentic-security dataflow observations import: ${loaded.message}\n`);
+    return 1;
+  }
+
+  const adapter = adapterFlag;
+  const source = (typeof args.flags.source === 'string' && args.flags.source) || path.basename(inputPath);
+  const environment = (typeof args.flags.environment === 'string' && args.flags.environment) || 'unspecified';
+
+  // M5 (final review): refuse a --source value that doesn't look like an
+  // identifier/filename-shaped token, BEFORE reading the --input file's
+  // own content — the same value-axis smuggling shape B1 closed on
+  // attribute values, applied here since --source is persisted verbatim
+  // and echoed by `observations list`.
+  if (!_SOURCE_IDENTIFIER_RE.test(source)) {
+    process.stderr.write(`agentic-security dataflow observations import: --source must look like an identifier/filename (letters, digits, '.', '_', ':', '-', 512 characters max) — a value containing whitespace, quotes, or punctuation is how a payload arrives disguised as metadata (got ${JSON.stringify(source)}).\n`);
+    return 2;
+  }
+
+  let text;
+  try {
+    text = fs.readFileSync(inputPath, 'utf8');
+  } catch (e) {
+    process.stderr.write(`agentic-security dataflow observations import: could not read --input "${inputFlag}": ${e && e.message ? e.message : e}\n`);
+    return 2;
+  }
+
+  const { RUNTIME_OBSERVATION_VERSION, validateRuntimeObservation } = await import('../src/lineage/runtime-observation.js');
+  const importedAt = new Date().toISOString();
+  const context = {
+    adapter, source, environment, windowStart, windowEnd, importedAt,
+    retention: { expiresAt: retainUntil },
+    version: RUNTIME_OBSERVATION_VERSION,
+  };
+  const { drafts, errors: parseErrors } = adapterImpl.parse(text, context);
+
+  const { matchObservationToGraph } = await import('../src/lineage/observation-correlation.js');
+  const { observationId, observationImportId } = await import('../src/lineage/ids.js');
+
+  // Never print an attribute VALUE anywhere in this function (AC-29
+  // clause 5's own "no captured payload... exists in the observation
+  // artifact" extends to this preview, which is not the artifact itself
+  // but must not become a second leak channel for the same values).
+  const records = [];
+  const recordErrors = [];
+  let matchedCount = 0;
+  let unmatchedCount = 0;
+  drafts.forEach((draft, i) => {
+    const match = matchObservationToGraph(loaded.graph, draft);
+    const fingerprint = Object.entries(draft.attributes ?? {})
+      .sort()
+      .map(([k, v]) => `${k}=${JSON.stringify(v)}`)
+      .join('&');
+    const id = observationId(
+      { adapter, environment: draft.environment, windowStart: draft.windowStart, windowEnd: draft.windowEnd },
+      [fingerprint],
+    );
+    const record = {
+      id, version: draft.version, adapter: draft.adapter, source: draft.source,
+      environment: draft.environment, windowStart: draft.windowStart, windowEnd: draft.windowEnd,
+      matchedNodeIds: match.matchedNodeIds, matchedEdgeIds: match.matchedEdgeIds, matchedFlowIds: match.matchedFlowIds,
+      attributes: draft.attributes, eventCountBand: draft.eventCountBand,
+      firstObservedAt: draft.firstObservedAt, lastObservedAt: draft.lastObservedAt,
+      matchMethod: match.matchMethod, matchConfidence: match.matchConfidence,
+      retention: draft.retention, importedAt: draft.importedAt,
+    };
+    const { valid, errors } = validateRuntimeObservation(record);
+    if (!valid) {
+      recordErrors.push({ index: i + 1, errors });
+    } else {
+      records.push(record);
+      if (match.matchMethod === 'unmatched') unmatchedCount++; else matchedCount++;
+    }
+  });
+
+  // Refuse the WHOLE import — deliberately, so a partial import can never
+  // silently drop the offending record (AC-29 clause 5). Both error
+  // sources (the adapter's own wire-shape rejections AND this command's
+  // preview validateRuntimeObservation rejections) are combined into one
+  // report before any exit decision is made.
+  if (parseErrors.length > 0 || recordErrors.length > 0) {
+    process.stderr.write('agentic-security dataflow observations import: refusing the WHOLE import — a partial import that silently drops an offending record would misrepresent what the operator believes the artifact holds (AC-29 clause 5). Nothing was written. Every offending record:\n');
+    for (const e of parseErrors) {
+      process.stderr.write(`  line ${e.line}: ${e.message}\n`);
+    }
+    for (const re of recordErrors) {
+      for (const e of re.errors) {
+        process.stderr.write(`  record ${re.index}: ${e.path}: ${e.message}\n`);
+      }
+    }
+    return 1;
+  }
+
+  const { OBSERVATION_IMPORT_VERSION } = await import('../src/lineage/observation-store.js');
+  // B2 (final review): importedAt alone is millisecond-resolution, so two
+  // concurrent imports sharing adapter/source/environment/window CAN land
+  // in the same millisecond and mint the identical import id — the same
+  // file name, one silently clobbering the other while both report
+  // success. A fresh random discriminator makes that collision impossible
+  // regardless of timing, mirroring this package's own established
+  // discriminatorParts convention (pathId/scenarioId/etc., ids.js).
+  const importId = observationImportId(
+    { adapter, source, environment, windowStart, windowEnd, importedAt },
+    [crypto.randomBytes(4).toString('hex')],
+  );
+  const importRecord = {
+    id: importId, version: OBSERVATION_IMPORT_VERSION, adapter, source, environment,
+    windowStart, windowEnd, importedAt, retention: { expiresAt: retainUntil },
+    observations: records,
+  };
+
+  const preview = {
+    adapter, source, environment, windowStart, windowEnd,
+    recordCount: records.length, matched: matchedCount, unmatched: unmatchedCount,
+    retention: { expiresAt: retainUntil }, importId, written: false,
+  };
+
+  const yes = !!args.flags.yes;
+  if (!yes) {
+    process.stdout.write(JSON.stringify(preview, null, 2) + '\n');
+    return 0;
+  }
+
+  // `isSafeStateDir(statePath(targetAbs, 'runtime-observations'))` —
+  // string literal, third registry-guard call site (the other two are
+  // `observation-store.js` and `index.js`) — before any mkdirSync/write.
+  const dir = statePath(targetAbs, 'runtime-observations');
+  const { isSafeStateDir } = await import('../src/posture/state-dir.js');
+  if (!isSafeStateDir(dir)) {
+    process.stderr.write(`agentic-security dataflow observations import: refusing to write — "${targetAbs}" does not look like a project directory.\n`);
+    return 2;
+  }
+
+  const { persistObservationImport } = await import('../src/lineage/observation-store.js');
+  let result;
+  try {
+    result = persistObservationImport(targetAbs, importRecord);
+  } catch (e) {
+    process.stderr.write(`agentic-security dataflow observations import: unexpected error writing the store: ${e && e.message ? e.message : e}\n`);
+    return 4;
+  }
+  if (!result.ok) {
+    process.stderr.write(`agentic-security dataflow observations import: ${result.reason}\n`);
+    return result.reason && result.reason.startsWith('invalid ObservationImport record') ? 1 : 4;
+  }
+
+  const { auditCall } = await import('../src/mcp/audit.js');
+  auditCall({
+    sessionRoot: targetAbs,
+    tool: 'dataflow_observations_import',
+    args: { adapter, source, environment, windowStart, windowEnd, observations: records.length, matched: matchedCount, importId },
+    outcome: 'ok',
+  });
+
+  preview.written = true;
+  process.stdout.write(JSON.stringify(preview, null, 2) + '\n');
+  return 0;
+}
+
+// agentic-security dataflow observations list [path] [--json] — read-only,
+// never writes, exit 0 always (an empty store is not an error). Never
+// prints an attribute key or value anywhere (CLI/list-2) — every row is
+// built from ONLY the import-level metadata fields below; no per-
+// observation `.attributes` object is ever touched by this function.
+async function cmdDataflowObservationsList(args) {
+  const target = args._[3] || '.'; // args._ = ['dataflow', 'observations', 'list', <path>?]
+  const targetAbs = path.resolve(target);
+
+  const { loadObservationImports } = await import('../src/lineage/observation-store.js');
+  const imports = loadObservationImports(targetAbs);
+
+  const rows = imports.map((imp) => ({
+    importId: imp.id,
+    adapter: imp.adapter,
+    source: imp.source,
+    environment: imp.environment,
+    windowStart: imp.windowStart,
+    windowEnd: imp.windowEnd,
+    observations: Array.isArray(imp.observations) ? imp.observations.length : 0,
+    importedAt: imp.importedAt,
+    expiresAt: imp.retention?.expiresAt ?? 'no expiry declared',
+  }));
+
+  if (args.flags.json) {
+    process.stdout.write(JSON.stringify(rows, null, 2) + '\n');
+    return 0;
+  }
+
+  if (rows.length === 0) {
+    process.stdout.write('No runtime observation imports found.\n');
+    return 0;
+  }
+
+  for (const r of rows) {
+    process.stdout.write(
+      `${r.importId}  adapter=${r.adapter}  source=${r.source}  environment=${r.environment}  `
+      + `window=${r.windowStart}..${r.windowEnd}  observations=${r.observations}  `
+      + `importedAt=${r.importedAt}  expiresAt=${r.expiresAt}\n`,
+    );
+  }
+  return 0;
+}
+
+// Local Markdown-escaping helpers for `dataflow twin --format markdown` —
+// byte-identical to _dfCoverageMdInline/_dfCoverageMdCell above,
+// reimplemented locally per this codebase's established
+// per-module-owns-its-own-escaping-helpers convention.
+function _dfTwinMdInline(value) {
+  return String(value).replace(/\r\n|\r|\n/g, ' ');
+}
+function _dfTwinMdCell(value) {
+  return _dfTwinMdInline(value).replace(/\\/g, '\\\\').replace(/\|/g, '\\|');
+}
+
+const _TWIN_LAYER_DISPLAY = Object.freeze({
+  runtime_observed: 'RUNTIME OBSERVED',
+  not_observed_in_window: 'not_observed_in_window',
+  not_evaluated: 'not_evaluated',
+});
+
+// agentic-security dataflow twin [path] --output <file> [--format
+// json|markdown] [--environment <name>] [--window-start <iso>]
+// [--window-end <iso>] — the AC-29 Runtime Digital Twin proof surface.
+// Read-only: never writes into .agentic-security/ (CLI/twin-7). `null`
+// (never `[]`) observations means "no store was consulted" — the
+// not_evaluated signal correlateObservations relies on to keep the
+// three-valued layer honest (AC-29 clause 2).
+async function cmdDataflowTwin(args) {
+  const target = args._[2] || '.'; // args._ = ['dataflow', 'twin', <path>?]
+  const targetAbs = path.resolve(target);
+
+  const outputPath = args.flags.output;
+  if (!outputPath || typeof outputPath !== 'string') {
+    process.stderr.write('agentic-security dataflow twin: --output <file> is required.\n');
+    return 2;
+  }
+  const format = args.flags.format ?? 'json';
+  if (format !== 'json' && format !== 'markdown') {
+    process.stderr.write(`agentic-security dataflow twin: --format must be one of json|markdown (got ${JSON.stringify(format)}).\n`);
+    return 2;
+  }
+
+  const { loadSignedGraph } = await import('../src/server/graph-loader.js');
+  const loaded = loadSignedGraph(targetAbs);
+  if (!loaded.ok) {
+    process.stderr.write(`agentic-security dataflow twin: ${loaded.message}\n`);
+    return 1;
+  }
+
+  const environment = typeof args.flags.environment === 'string' ? args.flags.environment : null;
+  const windowStart = typeof args.flags['window-start'] === 'string' ? args.flags['window-start'] : null;
+  const windowEnd = typeof args.flags['window-end'] === 'string' ? args.flags['window-end'] : null;
+
+  // Fourth registry-guard call site — string literal, matching
+  // observation-store.js/index.js/cmdDataflowObservationsImport above.
+  const dir = statePath(targetAbs, 'runtime-observations');
+  const observations = fs.existsSync(dir)
+    ? (await import('../src/lineage/observation-store.js')).loadObservations(targetAbs)
+    : null;
+
+  const { correlateObservations } = await import('../src/lineage/observation-correlation.js');
+  const result = correlateObservations(loaded.graph, observations, { environment, windowStart, windowEnd });
+
+  let data;
+  if (format === 'json') {
+    data = JSON.stringify(result, null, 2);
+  } else {
+    const { computeGraphDigest } = await import('../src/lineage/export-json.js');
+    const nodesById = new Map(loaded.graph.nodes.map((n) => [n.id, n]));
+    const flowsById = new Map(loaded.graph.flows.map((f) => [f.id, f]));
+    const lines = [];
+    lines.push('# Runtime Digital Twin', '');
+    lines.push(`**Graph:** \`${_dfTwinMdInline(loaded.graph.graphId ?? '(no graphId)')}\``);
+    lines.push(`**Graph digest:** \`${_dfTwinMdInline(computeGraphDigest(loaded.graph))}\``);
+    lines.push(`**Environment filter:** ${_dfTwinMdInline(result.environment ?? '(none)')}`);
+    lines.push(`**Window:** ${_dfTwinMdInline(result.windowStart ?? '(open)')} .. ${_dfTwinMdInline(result.windowEnd ?? '(open)')}`, '');
+    lines.push('## Layers', '');
+    lines.push('| Flow | Source | Sink | Layer |');
+    lines.push('|---|---|---|---|');
+    const flowIds = Object.keys(result.byFlow).sort();
+    for (const fid of flowIds) {
+      const flow = flowsById.get(fid);
+      const srcLabel = flow ? (nodesById.get(flow.source)?.label ?? flow.source) : '(unknown)';
+      const snkLabel = flow ? (nodesById.get(flow.sink)?.label ?? flow.sink) : '(unknown)';
+      const entry = result.byFlow[fid];
+      const layerDisplay = _TWIN_LAYER_DISPLAY[entry.layer] ?? entry.layer;
+      lines.push(`| ${_dfTwinMdCell(fid)} | ${_dfTwinMdCell(srcLabel)} | ${_dfTwinMdCell(snkLabel)} | ${_dfTwinMdCell(layerDisplay)} |`);
+    }
+    lines.push('');
+
+    const observedFlowIdsSorted = flowIds.filter((fid) => result.byFlow[fid].layer === 'runtime_observed');
+    if (observedFlowIdsSorted.length > 0) {
+      lines.push('## Runtime-observed flow detail', '');
+      for (const fid of observedFlowIdsSorted) {
+        const entry = result.byFlow[fid];
+        lines.push(`### ${_dfTwinMdInline(fid)}`, '');
+        lines.push(`- Match method: ${_dfTwinMdInline(entry.matchMethod ?? '(none)')}`);
+        lines.push(`- Match confidence: ${_dfTwinMdInline(entry.matchConfidence ?? '(none)')}`);
+        lines.push(`- Environment: ${_dfTwinMdInline(entry.environment ?? '(none)')}`);
+        lines.push(`- Window: ${_dfTwinMdInline(entry.windowStart ?? '(none)')} .. ${_dfTwinMdInline(entry.windowEnd ?? '(none)')}`);
+        lines.push(`- First observed: ${_dfTwinMdInline(entry.firstObservedAt ?? '(none)')}`);
+        lines.push(`- Last observed: ${_dfTwinMdInline(entry.lastObservedAt ?? '(none)')}`);
+        lines.push(`- Event count band: ${_dfTwinMdInline(entry.eventCountBand ?? '(none)')}`);
+        if (Array.isArray(entry.contributingEnvironments) && entry.contributingEnvironments.length > 1) {
+          lines.push(`- Contributing environments: ${_dfTwinMdInline(entry.contributingEnvironments.join(', '))} — the fields above describe only the representative (strongest-confidence) environment (I2).`);
+        }
+        if (entry.siblingFlowCount) {
+          lines.push(`- Sibling flow count: ${_dfTwinMdInline(entry.siblingFlowCount)} — this observation corroborates the destination NODE, never which sibling flow produced the traffic, which is why matchConfidence reads 'ambiguous' here.`);
+        }
+        lines.push('');
+      }
+    }
+
+    lines.push('## Limitations', '');
+    for (const l of result.limitations ?? []) {
+      lines.push(`- ${_dfTwinMdInline(l)}`);
+    }
+    lines.push("- `not_observed_in_window` means the flow was not observed in the selected environment/window — it does NOT mean the flow does not occur (PRD line 2098).");
+    lines.push('- Runtime observation increases corroboration confidence but cannot prove field-level identity — observations correlate to node/edge/flow ids only, never a specific data element instance (FR-505).');
+    lines.push('- Every statically possible path in this graph is listed above regardless of layer; nothing was filtered out (AC-29 clause 3).');
+    lines.push('');
+    data = lines.join('\n');
+  }
+
+  try {
+    await fsp.mkdir(path.dirname(path.resolve(outputPath)), { recursive: true });
+    await fsp.writeFile(path.resolve(outputPath), data);
+  } catch (e) {
+    process.stderr.write(`agentic-security dataflow twin: could not write --output "${outputPath}": ${e && e.message ? e.message : e}\n`);
+    return 2;
+  }
+  return 0;
+}
+
+// Mirrors posture/fix-history.js's own _writeAtomicAndSync (temp file in
+// the same directory, fsync, then rename over the target) — a crash
+// mid-write must never leave recipient-profiles.json as invalid JSON,
+// since loadRecipientConfig silently degrades a malformed file to "no
+// recipients" with only a console warning, not a hard failure.
+async function _writeConfigAtomic(fp, content) {
+  const dir = path.dirname(fp);
+  await fsp.mkdir(dir, { recursive: true });
+  const tmp = path.join(dir, `.${path.basename(fp)}.tmp-${process.pid}-${crypto.randomBytes(4).toString('hex')}`);
+  try {
+    const handle = await fsp.open(tmp, 'w');
+    try {
+      await handle.writeFile(content);
+      if (typeof handle.sync === 'function') await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    // Preserve the target's existing permissions (if any) — this file
+    // may hold sensitive governance data (DPA/jurisdiction/transfer
+    // facts) an operator deliberately restricted; a fresh temp file
+    // would otherwise silently widen it to the process umask (real bug
+    // found live by the final review: chmod 600 -> 0644 after a write).
+    try {
+      const { mode } = await fsp.stat(fp);
+      await fsp.chmod(tmp, mode & 0o777);
+    } catch { /* target doesn't exist yet — nothing to preserve */ }
+    await fsp.rename(tmp, fp);
+  } catch (e) {
+    try { await fsp.unlink(tmp); } catch { /* never existed, or already gone — fine either way */ }
+    throw e;
+  }
+}
+
+// agentic-security governance propose-edit [path] --patch <file>
+// [--output <file>] [--yes] [--base-digest <hex>] — M5 deliverable #5.
+// Proposes a validated, reviewable edit to recipient-profiles.json.
+// Without --yes: computes and previews the diff, writes nothing.
+// With --yes: re-validates, checks the version guard, backs up the
+// current file, writes the new content atomically, and appends a real
+// audit event via auditCall. Exit codes: 0 success (preview or real
+// write), 1 validation failure, 2 argument/version-guard problem.
+//
+// NOT a `dataflow` subcommand — this edits operator config
+// (recipient-profiles.json), never the scanned graph, so it is its own
+// top-level `governance` command (see `case 'governance':` in main()).
+async function cmdGovernancePropose(args) {
+  const target = args._[2] || '.'; // args._ = ['governance', 'propose-edit', <path>?]
+  const targetAbs = path.resolve(target);
+
+  const patchFlag = args.flags.patch;
+  if (!patchFlag || typeof patchFlag !== 'string') {
+    process.stderr.write('agentic-security governance propose-edit: --patch <file> is required.\n');
+    return 2;
+  }
+  let patch;
+  try {
+    patch = JSON.parse(fs.readFileSync(path.resolve(patchFlag), 'utf8'));
+  } catch (e) {
+    process.stderr.write(`agentic-security governance propose-edit: could not read/parse --patch file "${patchFlag}": ${e.message}\n`);
+    return 2;
+  }
+
+  const { RECIPIENT_CONFIG_FILENAME } = await import('../src/lineage/recipient-registry.js');
+  const { statePath } = await import('../src/posture/state-dir.js');
+  const configPath = statePath(targetAbs, RECIPIENT_CONFIG_FILENAME);
+  const currentRaw = fs.existsSync(configPath) ? fs.readFileSync(configPath, 'utf8') : '{"recipients":{}}';
+  const currentDigest = crypto.createHash('sha256').update(currentRaw).digest('hex');
+  // The merge base is the file's REAL bytes, parsed directly — never
+  // loadRecipientConfig's sanitized view, which silently drops any
+  // entry failing isValidRecipientConfigEntry, any non-string/empty
+  // key, and any top-level key other than `recipients`. Merging against
+  // that sanitized object and writing it back permanently deletes
+  // whatever it dropped (B1, the final review's Blocking finding), with
+  // the preview and audit event both falsely reporting nothing removed.
+  // This single JSON.parse is now the ONLY read of the current file, so
+  // currentDigest and the merge base provably describe the same bytes
+  // (also closes M3).
+  let currentConfig;
+  try {
+    currentConfig = JSON.parse(currentRaw);
+  } catch (e) {
+    process.stderr.write(`agentic-security governance propose-edit: the current config file is not valid JSON: ${e.message}\n`);
+    return 2;
+  }
+
+  // Version guard runs BEFORE validation and BEFORE any write — a
+  // concurrent-edit rejection must never partially validate or
+  // partially write first.
+  const baseDigestFlag = args.flags['base-digest'];
+  if (baseDigestFlag && baseDigestFlag !== currentDigest) {
+    process.stderr.write(`agentic-security governance propose-edit: the config file changed since --base-digest was computed (a concurrent edit) — refusing to write. Re-read the current file and recompute your patch.\n`);
+    return 2;
+  }
+
+  const { proposeGovernanceEdit } = await import('../src/lineage/governance-edit.js');
+  const { valid, errors, diff, merged } = proposeGovernanceEdit(currentConfig, patch);
+  if (!valid) {
+    process.stderr.write(`agentic-security governance propose-edit: --patch file failed validation:\n${errors.map((e) => `  ${e.key}: ${e.message}`).join('\n')}\n`);
+    return 1;
+  }
+
+  const yes = !!args.flags.yes;
+  let written = false;
+  let backupPath = null;
+  if (yes) {
+    // Refuse before touching disk if the target doesn't look like a real
+    // project directory — the same guard every other write path in this
+    // file uses, applied here before any mkdirSync/backup/write (M5).
+    const { isSafeStateDir } = await import('../src/posture/state-dir.js');
+    if (!isSafeStateDir(path.dirname(configPath))) {
+      process.stderr.write(`agentic-security governance propose-edit: refusing to write — "${targetAbs}" does not look like a project directory.\n`);
+      return 2;
+    }
+    // Backup BEFORE the new content is written — a failed write below
+    // this point leaves the backup intact and the original untouched.
+    // Only recorded when a backup actually happened (i.e. a prior file
+    // existed) — reporting a backup path that was never written would
+    // mislead a consumer trusting the report. Backups live in their own
+    // dedicated subdirectory (mirroring posture/fix-history.js's own
+    // `fix-history/` precedent), never as a sibling `.bak-*` file next
+    // to the config — that's what lets artifact-registry.js register the
+    // WHOLE DIRECTORY as one entry (I5) so `reset` can sweep it, since
+    // the registry only supports exact-name matches, never a per-file
+    // timestamped name. The `Date.now()-<random>` naming (mirroring this
+    // file's own temp-file naming convention in `_writeConfigAtomic`)
+    // closes M6 — two writes in the same millisecond no longer collide.
+    const backupDir = statePath(targetAbs, 'recipient-profiles-backups');
+    const candidateBackupPath = path.join(backupDir, `${Date.now()}-${crypto.randomBytes(4).toString('hex')}.bak`);
+    if (fs.existsSync(configPath)) {
+      fs.mkdirSync(backupDir, { recursive: true });
+      fs.copyFileSync(configPath, candidateBackupPath);
+      backupPath = candidateBackupPath;
+    }
+    // The write is the MERGE RESULT (`merged`, per proposeGovernanceEdit's
+    // merge-patch semantics), never the raw patch — writing the patch
+    // verbatim would silently delete every recipient it doesn't name.
+    // `merged` is never null here — a null merge base only happens on a
+    // container-shape validation failure, which already returned 1 above.
+    await _writeConfigAtomic(configPath, JSON.stringify(merged, null, 2));
+    written = true;
+    // Audited ONLY on the real write path — --yes supplied AND
+    // validation passed AND the version guard passed. Never on a
+    // dry-run preview, never on a validation failure. Carries the
+    // pre-write digest and the backup path so a later auditor can tell
+    // which bytes this event produced (M2).
+    const { auditCall } = await import('../src/mcp/audit.js');
+    auditCall({
+      sessionRoot: targetAbs, tool: 'governance_propose_edit',
+      args: {
+        file: RECIPIENT_CONFIG_FILENAME, added: diff.added, removed: diff.removed,
+        changedKeys: diff.changed.map((c) => c.key), beforeDigest: currentDigest, backupPath,
+      },
+      outcome: 'ok',
+    });
+  }
+
+  const report = { currentDigest, diff, written, backupPath };
+  const outputPath = args.flags.output;
+  if (outputPath) {
+    fs.writeFileSync(path.resolve(outputPath), JSON.stringify(report, null, 2));
+  } else {
+    process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+  }
+  return 0;
+}
+
+// agentic-security federate declare [path] --local-node <node-id>
+// --remote-graph <file> --remote-node <node-id> [--repository <label>]
+// [--relationship data_flow] [--rationale <text>] [--output <file>]
+// [--yes] [--base-digest <hex>] — M5 deliverable #8 (FR-304's "declared"
+// half). Declares a CrossRepoLink between a node in the CURRENT
+// locally-scanned graph and a node in a REMOTE graph export
+// (`dataflow export --format json`'s own artifact, loaded via
+// federation-loader.js's loadRemoteGraphExport — never loadSignedGraph,
+// which authenticates against a per-install HMAC key, the wrong trust
+// model for a file that crossed a repo/machine boundary).
+//
+// Reuses cmdGovernancePropose's exact write contract: (1) version guard
+// on cross-repo-links.json BEFORE any read of the remote file or any
+// validation; (2) loads+validates the remote export (a digest-mismatch
+// is a printed warning, never silently swallowed, and never blocks
+// --yes — the operator is explicitly asserting this file); (3) confirms
+// --local-node exists in the CURRENT locally-scanned graph and
+// --remote-node exists in the loaded remote export's own nodes[];
+// (4) on --yes: backup, atomic write (via the already-shipped
+// _writeConfigAtomic), a real hash-chained audit event. Exit codes
+// mirror cmdGovernancePropose's own scheme: 0 success (incl. preview),
+// 1 validation failure, 2 usage/version-guard/node-not-found, 4 an
+// unexpected I/O error during the write itself — uncaught, falling
+// through to main()'s own outer catch/process.exit(4), the identical,
+// deliberate non-pattern cmdGovernancePropose itself relies on (no local
+// try/catch here either).
+async function cmdFederateDeclare(args) {
+  const target = args._[2] || '.'; // args._ = ['federate', 'declare', <path>?]
+  const targetAbs = path.resolve(target);
+
+  const localNodeFlag = args.flags['local-node'];
+  const remoteGraphFlag = args.flags['remote-graph'];
+  const remoteNodeFlag = args.flags['remote-node'];
+  if (!localNodeFlag || typeof localNodeFlag !== 'string') {
+    process.stderr.write('agentic-security federate declare: --local-node <node-id> is required.\n');
+    return 2;
+  }
+  if (!remoteGraphFlag || typeof remoteGraphFlag !== 'string') {
+    process.stderr.write('agentic-security federate declare: --remote-graph <file> is required.\n');
+    return 2;
+  }
+  if (!remoteNodeFlag || typeof remoteNodeFlag !== 'string') {
+    process.stderr.write('agentic-security federate declare: --remote-node <node-id> is required.\n');
+    return 2;
+  }
+
+  const { CROSS_REPO_LINK_VERSION, CROSS_REPO_LINKS_FILENAME, CROSS_REPO_LINK_RELATIONSHIP, validateCrossRepoLink } = await import('../src/lineage/cross-repo-link.js');
+
+  const relationshipFlag = args.flags.relationship ?? CROSS_REPO_LINK_RELATIONSHIP;
+  if (relationshipFlag !== CROSS_REPO_LINK_RELATIONSHIP) {
+    process.stderr.write(`agentic-security federate declare: --relationship must be "${CROSS_REPO_LINK_RELATIONSHIP}" (got "${relationshipFlag}") — no other relationship value is defined.\n`);
+    return 2;
+  }
+
+  const { statePath, isSafeStateDir } = await import('../src/posture/state-dir.js');
+  const { crossRepoLinkId } = await import('../src/lineage/ids.js');
+  const { loadRemoteGraphExport } = await import('../src/lineage/federation-loader.js');
+  const { loadSignedGraph } = await import('../src/server/graph-loader.js');
+  const { computeGraphDigest } = await import('../src/lineage/export-json.js');
+
+  const configPath = statePath(targetAbs, CROSS_REPO_LINKS_FILENAME);
+  const currentRaw = fs.existsSync(configPath) ? fs.readFileSync(configPath, 'utf8') : '{"links":[]}';
+  const currentDigest = crypto.createHash('sha256').update(currentRaw).digest('hex');
+
+  // Version guard runs BEFORE any read of the remote file or any
+  // validation — mirrors cmdGovernancePropose's own ordering exactly.
+  const baseDigestFlag = args.flags['base-digest'];
+  if (baseDigestFlag && baseDigestFlag !== currentDigest) {
+    process.stderr.write('agentic-security federate declare: the cross-repo-links file changed since --base-digest was computed (a concurrent edit) — refusing to write. Re-read the current file and recompute your declaration.\n');
+    return 2;
+  }
+
+  let currentDoc;
+  try {
+    currentDoc = JSON.parse(currentRaw);
+  } catch (e) {
+    process.stderr.write(`agentic-security federate declare: the current cross-repo-links file is not valid JSON: ${e.message}\n`);
+    return 2;
+  }
+  if (!currentDoc || typeof currentDoc !== 'object' || Array.isArray(currentDoc) || !Array.isArray(currentDoc.links)) {
+    process.stderr.write('agentic-security federate declare: the current cross-repo-links file has no "links" array (expected {"links": [...]}).\n');
+    return 2;
+  }
+
+  // Step 2: load and validate the remote export. A digest-mismatch is a
+  // printed WARNING, never a blocking failure — the operator is
+  // explicitly asserting this file.
+  const remote = loadRemoteGraphExport(path.resolve(remoteGraphFlag));
+  if (!remote.ok) {
+    process.stderr.write(`agentic-security federate declare: could not load --remote-graph "${remoteGraphFlag}": ${remote.message}\n`);
+    return 2;
+  }
+  if (!remote.digestMatches) {
+    process.stderr.write(`agentic-security federate declare: WARNING — ${remote.message}\n`);
+  }
+  const remoteNode = (remote.graph.nodes ?? []).find((n) => n.id === remoteNodeFlag);
+  if (!remoteNode) {
+    process.stderr.write(`agentic-security federate declare: --remote-node "${remoteNodeFlag}" was not found in the remote export's own nodes.\n`);
+    return 2;
+  }
+
+  // Step 3: confirm --local-node exists in the CURRENT locally-scanned
+  // graph — loadSignedGraph is the correct mechanism here (the LOCAL
+  // side, same install, same machine).
+  const local = loadSignedGraph(targetAbs);
+  if (!local.ok) {
+    process.stderr.write(`agentic-security federate declare: could not load the local scanned graph: ${local.message}\n`);
+    return 1;
+  }
+  const localNode = (local.graph.nodes ?? []).find((n) => n.id === localNodeFlag);
+  if (!localNode) {
+    process.stderr.write(`agentic-security federate declare: --local-node "${localNodeFlag}" was not found in the current locally-scanned graph.\n`);
+    return 2;
+  }
+
+  // Strip crossRepoLinks before hashing — final whole-branch review,
+  // M5 deliverable #8, B3: computeGraphDigest has no exclusion for this
+  // field, so a graph's own digest otherwise depends on what
+  // cross-repo links have ALREADY been declared and re-attached by a
+  // later scan (graph-builder.js's own opts.crossRepoLinks hook). Left
+  // unfixed, every declare-then-rescan cycle changes the digest that
+  // the NEXT declaration's own id is derived from, minting a new,
+  // unrelated id for the identical real-world fact. Using an object
+  // without the key (not a key set to undefined) guarantees this is
+  // hash-equivalent to a graph that never had the field at all,
+  // regardless of how the hashing internals treat undefined values.
+  const { crossRepoLinks: _omitForDigest, ...localGraphForDigest } = local.graph;
+  const localGraphDigest = computeGraphDigest(localGraphForDigest);
+  const idInputs = {
+    localGraphId: local.graph.graphId, localGraphDigest, localNodeId: localNodeFlag,
+    remoteGraphId: remote.graph.graphId, remoteGraphDigest: remote.digest, remoteNodeId: remoteNodeFlag,
+    relationship: relationshipFlag,
+  };
+  const record = {
+    id: crossRepoLinkId(idInputs),
+    version: CROSS_REPO_LINK_VERSION,
+    provenance: 'manual',
+    relationship: relationshipFlag,
+    local: { graphId: local.graph.graphId, graphDigest: localGraphDigest, nodeId: localNodeFlag },
+    remote: {
+      // Honest placeholder literal when the operator supplied none — no
+      // code-derived signal exists to name "which repo" a bare exported
+      // JSON file came from (mirrors recipient-registry.js's own
+      // `graphId ?? '(no graph)'` precedent).
+      repository: args.flags.repository ?? '(unspecified)',
+      sourceFile: path.resolve(remoteGraphFlag),
+      graphId: remote.graph.graphId, graphDigest: remote.digest, nodeId: remoteNodeFlag,
+    },
+    rationale: args.flags.rationale ?? null,
+    declaredBy: process.env.USER || process.env.USERNAME || '(unspecified)',
+    declaredAt: new Date().toISOString(),
+  };
+
+  const { valid, errors } = validateCrossRepoLink(record);
+  if (!valid) {
+    process.stderr.write(`agentic-security federate declare: constructed record failed validation:\n${errors.map((e) => `  ${e.path}: ${e.message}`).join('\n')}\n`);
+    return 1;
+  }
+
+  const yes = !!args.flags.yes;
+  let written = false;
+  let backupPath = null;
+  if (yes) {
+    if (!isSafeStateDir(path.dirname(configPath))) {
+      process.stderr.write(`agentic-security federate declare: refusing to write — "${targetAbs}" does not look like a project directory.\n`);
+      return 2;
+    }
+    const backupDir = statePath(targetAbs, 'cross-repo-links-backups');
+    const candidateBackupPath = path.join(backupDir, `${Date.now()}-${crypto.randomBytes(4).toString('hex')}.bak`);
+    if (fs.existsSync(configPath)) {
+      fs.mkdirSync(backupDir, { recursive: true });
+      fs.copyFileSync(configPath, candidateBackupPath);
+      backupPath = candidateBackupPath;
+    }
+    // Dedupe by id, IN PLACE — final whole-branch review, M5 deliverable
+    // #8, B3, refined in round 2 per the re-review's own Minor finding:
+    // a redeclare of the identical fact now replaces the existing entry
+    // at its ORIGINAL array position, rather than moving it to the end
+    // (round 1's filter-then-append did the latter — harmless, but an
+    // unnecessary, undocumented ordering change `federate list`'s own
+    // output would otherwise silently exhibit on every redeclare).
+    const existingIndex = currentDoc.links.findIndex((l) => l && l.id === record.id);
+    const newLinks = existingIndex === -1
+      ? [...currentDoc.links, record]
+      : currentDoc.links.map((l, i) => (i === existingIndex ? record : l));
+    const merged = { ...currentDoc, links: newLinks };
+    await _writeConfigAtomic(configPath, JSON.stringify(merged, null, 2));
+    written = true;
+    const { auditCall } = await import('../src/mcp/audit.js');
+    auditCall({
+      sessionRoot: targetAbs, tool: 'federate_declare',
+      args: {
+        file: CROSS_REPO_LINKS_FILENAME, id: record.id, localNodeId: localNodeFlag, remoteNodeId: remoteNodeFlag,
+        digestMatches: remote.digestMatches, beforeDigest: currentDigest, backupPath,
+      },
+      outcome: 'ok',
+    });
+  }
+
+  const report = { currentDigest, record, digestMatches: remote.digestMatches, written, backupPath };
+  const outputPath = args.flags.output;
+  if (outputPath) {
+    fs.writeFileSync(path.resolve(outputPath), JSON.stringify(report, null, 2));
+  } else {
+    process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+  }
+  return 0;
+}
+
+// agentic-security federate list [path] [--output <file>] — M5
+// deliverable #8. Read-only. Reads cross-repo-links.json and, for each
+// entry, reports whether local.nodeId still resolves against the
+// current loadSignedGraph output and whether remote.sourceFile still
+// exists/parses/digest-matches/still names the declared remote node —
+// never fabricates "still valid" when it cannot check (mirrors
+// `dataflow observations list`'s own precedent). Exit codes: 0 success
+// (including an empty list), 2 a malformed cross-repo-links.json.
+async function cmdFederateList(args) {
+  const target = args._[2] || '.'; // args._ = ['federate', 'list', <path>?]
+  const targetAbs = path.resolve(target);
+
+  const { statePath } = await import('../src/posture/state-dir.js');
+  const { CROSS_REPO_LINKS_FILENAME } = await import('../src/lineage/cross-repo-link.js');
+  const { loadRemoteGraphExport } = await import('../src/lineage/federation-loader.js');
+  const { loadSignedGraph } = await import('../src/server/graph-loader.js');
+
+  const configPath = statePath(targetAbs, CROSS_REPO_LINKS_FILENAME);
+  let links = [];
+  if (fs.existsSync(configPath)) {
+    let doc;
+    try {
+      doc = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    } catch (e) {
+      process.stderr.write(`agentic-security federate list: ${configPath} is not valid JSON: ${e.message}\n`);
+      return 2;
+    }
+    links = Array.isArray(doc?.links) ? doc.links : [];
+  }
+
+  const local = loadSignedGraph(targetAbs);
+  const localNodeIds = local.ok ? new Set((local.graph.nodes ?? []).map((n) => n.id)) : null;
+
+  const results = links.map((record) => {
+    // `stillValid` is null — "could not check" — whenever there is no
+    // current local graph to check against, never fabricated as true or
+    // false.
+    const localStillValid = localNodeIds ? localNodeIds.has(record?.local?.nodeId) : null;
+
+    let remoteStatus;
+    const sourceFile = record?.remote?.sourceFile;
+    if (typeof sourceFile !== 'string' || !sourceFile) {
+      remoteStatus = { checked: false, reason: 'no sourceFile recorded on this record' };
+    } else {
+      const remote = loadRemoteGraphExport(sourceFile);
+      if (!remote.ok) {
+        remoteStatus = { checked: true, ok: false, reason: remote.reason, message: remote.message };
+      } else {
+        const nodeStillPresent = (remote.graph.nodes ?? []).some((n) => n.id === record?.remote?.nodeId);
+        remoteStatus = { checked: true, ok: true, digestMatches: remote.digestMatches, nodeStillPresent };
+      }
+    }
+
+    return {
+      id: record?.id ?? null,
+      local: { nodeId: record?.local?.nodeId ?? null, stillValid: localStillValid },
+      remote: { sourceFile: sourceFile ?? null, nodeId: record?.remote?.nodeId ?? null, ...remoteStatus },
+      rationale: record?.rationale ?? null,
+      declaredBy: record?.declaredBy ?? null,
+      declaredAt: record?.declaredAt ?? null,
+    };
+  });
+
+  const report = { links: results, localGraphAvailable: local.ok };
+  const outputPath = args.flags.output;
+  if (outputPath) {
+    fs.writeFileSync(path.resolve(outputPath), JSON.stringify(report, null, 2));
+  } else {
+    process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+  }
+  return 0;
+}
+
+// ── remediation open/update/accept-risk/list — M5 deliverable #6
+// (Blast-Radius: Remediation Command Center, FR-507 + AC-31), Task 3.
+// The CLI wiring for the non-GraphDiff-dependent half of the `remediation`
+// dispatcher (Task 4 adds `verify`/`reopen-check`). Same shape as
+// `cmdGovernancePropose` above: dry-run-by-default, `--yes` to write,
+// `isSafeStateDir` guard, `auditCall` on every real write, exit codes
+// 0/1/2/4 — but writing through Task 2's `appendLedgerEvent` (an
+// append-only JSONL event log) rather than a whole-file rewrite.
+
+function _emitRemediationReport(report, args) {
+  const data = JSON.stringify(report, null, 2);
+  const outputPath = args.flags.output;
+  if (outputPath) {
+    fs.writeFileSync(path.resolve(outputPath), data);
+  } else {
+    process.stdout.write(data + '\n');
+  }
+}
+
+// Shared write path for every mutating `remediation` verb. Order is the
+// same one cmdGovernancePropose established and is load-bearing:
+//   1. --base-event optimistic-concurrency guard (BEFORE any validation
+//      or write) — the append-only analogue of #5's whole-file
+//      --base-digest, keyed to the last EVENT hash per the scoping doc's
+//      §3 "reuse this shape, with one genuine adaptation."
+//   2. isSafeStateDir refusal (--yes path only).
+//   3. Dry run: fold the CURRENT ledger, report what WOULD happen, write
+//      nothing, exit 0 (or 1 if the proposed event is itself illegal).
+//   4. --yes: appendLedgerEvent (which is the ONLY caller of
+//      validateTransition), then auditCall — never the reverse, and
+//      never auditCall on a rejected or previewed write.
+// `extraReport` (Task 4) is an optional object of additional fields merged
+// into the emitted report, in BOTH the dry-run-preview and the real-write
+// branches — e.g. cmdRemediationVerify's own beforeSnapshotId/
+// afterSnapshotId/beforeSnapshotSource/evidenceOutcome. It is never
+// consulted for validity — only validateTransition (inside
+// appendLedgerEvent, or this function's own preview call below) decides
+// that — so a caller cannot use it to smuggle a write past validation.
+// Returns an exit code; the caller returns it verbatim.
+async function _remediationWrite(targetAbs, verb, auditTool, eventPayload, args, extraReport = {}) {
+  const { ledgerPaths, latestEventHash, readLedgerEvents, appendLedgerEvent } =
+    await import('../src/posture/remediation-ledger.js');
+  const { foldRemediationLedger, validateTransition } = await import('../src/lineage/remediation.js');
+
+  const { ledgerPath } = ledgerPaths(targetAbs);
+  const itemId = eventPayload.itemId ?? eventPayload.id ?? null;
+
+  // 1. --base-event guard — before any validation or write.
+  const currentBaseEvent = latestEventHash(targetAbs);
+  const baseEventFlag = args.flags['base-event'];
+  if (baseEventFlag !== undefined && baseEventFlag !== currentBaseEvent) {
+    process.stderr.write(`agentic-security remediation ${verb}: the ledger changed since --base-event was computed (a concurrent write) — refusing to append. Re-read the ledger with \`remediation list\` and retry.\n`);
+    return 2;
+  }
+
+  const yes = !!args.flags.yes;
+
+  // 2. isSafeStateDir refusal — --yes path only.
+  if (yes) {
+    const { isSafeStateDir } = await import('../src/posture/state-dir.js');
+    if (!isSafeStateDir(path.dirname(ledgerPath))) {
+      process.stderr.write(`agentic-security remediation ${verb}: refusing to write — "${targetAbs}" does not look like a project directory.\n`);
+      return 2;
+    }
+  }
+
+  // 3. Dry run — a genuine preview of the resulting state, computed by
+  // folding the CURRENT ledger with the proposed event appended in
+  // memory. The proposed event's own legality is checked here too (for
+  // the preview only — the authoritative call remains the one inside
+  // appendLedgerEvent below), so --yes never surprises an operator who
+  // previewed first.
+  if (!yes) {
+    const events = readLedgerEvents(targetAbs);
+    const currentItems = foldRemediationLedger(events);
+    const currentItem = itemId != null ? (currentItems[itemId] ?? null) : null;
+    const wouldBeItems = foldRemediationLedger([...events, eventPayload]);
+    const wouldBe = itemId != null ? (wouldBeItems[itemId] ?? null) : null;
+    const report = { verb, itemId, proposedEvent: eventPayload, baseEvent: currentBaseEvent, written: false, wouldBe, ...extraReport };
+    const { valid, errors } = validateTransition(currentItem, eventPayload);
+    if (!valid) {
+      report.errors = errors;
+      _emitRemediationReport(report, args);
+      for (const e of errors) process.stderr.write(`agentic-security remediation ${verb}: ${e.field}: ${e.message}\n`);
+      return 1;
+    }
+    _emitRemediationReport(report, args);
+    return 0;
+  }
+
+  // 4. --yes: the real write. `expectedBaseHash` (I5) threads the
+  // --base-event guard through to the authoritative, inside-the-lock
+  // check — the pre-lock check above (#1) remains as a cheap early fail,
+  // but this is the one that cannot be raced by a concurrent writer.
+  let result;
+  try {
+    result = await appendLedgerEvent(targetAbs, eventPayload, { expectedBaseHash: baseEventFlag });
+  } catch (e) {
+    process.stderr.write(`agentic-security remediation ${verb}: unexpected error writing the ledger: ${e && e.message ? e.message : e}\n`);
+    return 4;
+  }
+  if (!result.valid) {
+    for (const e of result.errors) process.stderr.write(`agentic-security remediation ${verb}: ${e.field}: ${e.message}\n`);
+    // M10: a state-writes-disabled or unsafe-scanRoot refusal is a
+    // usage/environment condition, not a rejected state transition —
+    // `commands/remediation.md`'s exit-code table reserves 1 for the
+    // latter. Both error fields are environment refusals emitted by
+    // appendLedgerEvent BEFORE any real validation runs; every other
+    // error field is a genuine validation/state-machine rejection.
+    if (result.errors.some((e) => e.field === '(state)' || e.field === '(scanRoot)')) return 2;
+    return 1;
+  }
+  const { auditCall } = await import('../src/mcp/audit.js');
+  auditCall({
+    sessionRoot: targetAbs,
+    tool: auditTool,
+    args: { itemId, eventType: eventPayload.type, baseEvent: currentBaseEvent, eventHash: result.hash },
+    outcome: 'ok',
+  });
+  const report = { verb, itemId, proposedEvent: eventPayload, baseEvent: currentBaseEvent, written: true, eventHash: result.hash, ...extraReport };
+  _emitRemediationReport(report, args);
+  return 0;
+}
+
+// agentic-security remediation open [path] --assessment <impact-report.json>
+//   --owner <id> --due <YYYY-MM-DD> --control <text>
+//   --required-evidence <flowId,...> [--id <itemId>] [--snapshot <commit>]
+//   [--allow-manual-attestation] [--output <file>] [--yes]
+async function cmdRemediationOpen(args) {
+  const target = args._[2] || '.'; // args._ = ['remediation', 'open', <path>?]
+  const targetAbs = path.resolve(target);
+
+  const assessmentFlag = args.flags.assessment;
+  const ownerFlag = args.flags.owner;
+  const dueFlag = args.flags.due;
+  const controlFlag = args.flags.control;
+  const requiredEvidenceFlag = args.flags['required-evidence'];
+
+  for (const [name, val] of [
+    ['--assessment', assessmentFlag], ['--owner', ownerFlag], ['--due', dueFlag],
+    ['--control', controlFlag], ['--required-evidence', requiredEvidenceFlag],
+  ]) {
+    if (!val || typeof val !== 'string') {
+      process.stderr.write(`agentic-security remediation open: ${name} is required.\n`);
+      return 2;
+    }
+  }
+
+  // This is the RAW `dataflow impact assess --format json --output`
+  // report — cmdDataflowImpactAssess writes JSON.stringify(record, null,
+  // 2), so the file on disk IS the record. No hand-extraction needed.
+  let record;
+  try {
+    record = JSON.parse(fs.readFileSync(path.resolve(assessmentFlag), 'utf8'));
+  } catch (e) {
+    process.stderr.write(`agentic-security remediation open: could not read/parse --assessment file "${assessmentFlag}": ${e && e.message ? e.message : e}\n`);
+    return 2;
+  }
+  const { validateImpactAssessment } = await import('../src/lineage/impact-assessment.js');
+  const { valid: assessmentValid, errors: assessmentErrors } = validateImpactAssessment(record);
+  if (!assessmentValid) {
+    process.stderr.write(`agentic-security remediation open: --assessment file failed validation:\n${assessmentErrors.map((e) => `  ${e.path}: ${e.message}`).join('\n')}\n`);
+    return 2;
+  }
+
+  // Resolve the incident snapshot: --snapshot <commit> pins one specific
+  // persisted snapshot; otherwise the newest one is used. Refuses (exit
+  // 2) when no snapshot exists at all — an item with no incident
+  // snapshot can never be verified, so opening one would be a
+  // guaranteed dead end.
+  const snapshotFlag = args.flags.snapshot;
+  let snapshot;
+  if (snapshotFlag !== undefined) {
+    snapshot = loadSnapshot(targetAbs, snapshotFlag);
+    if (!snapshot) {
+      process.stderr.write(`agentic-security remediation open: no persisted GraphSnapshot found for commit "${snapshotFlag}" — pass a commit that was actually scanned.\n`);
+      return 2;
+    }
+  } else {
+    const snapshots = loadSnapshots(targetAbs);
+    if (snapshots.length === 0) {
+      process.stderr.write(`agentic-security remediation open: no persisted GraphSnapshot found for "${targetAbs}" — run a scan with AGENTIC_SECURITY_LINEAGE_DEEP=1 first.\n`);
+      return 2;
+    }
+    snapshot = snapshots[0];
+  }
+
+  const requiredEvidence = String(requiredEvidenceFlag).split(',').map((s) => s.trim()).filter(Boolean);
+  if (requiredEvidence.length === 0) {
+    process.stderr.write('agentic-security remediation open: --required-evidence must name at least one flow id.\n');
+    return 2;
+  }
+
+  const itemId = args.flags.id || `rem-${crypto.randomBytes(6).toString('hex')}`;
+  // affectedFlowIds is DERIVED, not copied — ImpactAssessment carries no
+  // affectedFlowIds field of its own (impact-assessment.js). The sorted,
+  // deduplicated union of --required-evidence and (the target itself,
+  // when it names a flow) is the only real flow-id source available.
+  const affectedFlowIds = [...new Set([
+    ...requiredEvidence,
+    ...(typeof record.targetId === 'string' && record.targetId.startsWith('flow:') ? [record.targetId] : []),
+  ])].sort();
+
+  const payload = {
+    type: 'opened',
+    at: new Date().toISOString(),
+    itemId,
+    id: itemId,
+    owner: ownerFlag,
+    dueDate: dueFlag,
+    recommendedControl: controlFlag,
+    assessment: {
+      assessmentId: record.id,
+      targetId: record.targetId,
+      targetKind: record.targetKind,
+      traceKind: record.traceKind,
+      scope: record.scope,
+      graphId: record.graphId,
+      graphDigest: record.graphDigest,
+      snapshotId: snapshot.id,
+      assessmentPath: path.resolve(assessmentFlag),
+    },
+    affectedFlowIds,
+    affectedNodeIds: record.affectedNodeIds ?? [],
+    affectedEdgeIds: record.affectedEdgeIds ?? [],
+    requiredEvidence,
+    manualAttestationPermitted: !!args.flags['allow-manual-attestation'],
+  };
+
+  const { validateOpenPayload } = await import('../src/lineage/remediation.js');
+  const { valid, errors } = validateOpenPayload(payload);
+  if (!valid) {
+    process.stderr.write(`agentic-security remediation open: ${errors.map((e) => `${e.field}: ${e.message}`).join('\n')}\n`);
+    return 1;
+  }
+
+  return _remediationWrite(targetAbs, 'open', 'remediation_open', payload, args);
+}
+
+// agentic-security remediation update [path] --id <itemId>
+//   --state <in_progress|awaiting_verification> [--base-event <hash>]
+//   [--output <file>] [--yes]
+async function cmdRemediationUpdate(args) {
+  const target = args._[2] || '.'; // args._ = ['remediation', 'update', <path>?]
+  const targetAbs = path.resolve(target);
+
+  const idFlag = args.flags.id;
+  if (!idFlag || typeof idFlag !== 'string') {
+    process.stderr.write('agentic-security remediation update: --id <itemId> is required.\n');
+    return 2;
+  }
+  const stateFlag = args.flags.state;
+  if (!stateFlag || typeof stateFlag !== 'string') {
+    process.stderr.write('agentic-security remediation update: --state <in_progress|awaiting_verification> is required.\n');
+    return 2;
+  }
+  // AC-31 at the CLI boundary: `state_changed` can never reach `verified`
+  // — this is the friendlier of two independent guards for the one rule
+  // that matters most (the ledger's own validateTransition rejection,
+  // enforced inside appendLedgerEvent, is the one that cannot be
+  // bypassed). Checked BEFORE the recognized-values check below so a
+  // caller gets this specific message rather than a generic usage error.
+  if (stateFlag === 'verified') {
+    process.stderr.write('agentic-security remediation update: state_changed can never reach "verified" — run `agentic-security remediation verify` instead.\n');
+    return 1;
+  }
+  if (stateFlag !== 'in_progress' && stateFlag !== 'awaiting_verification') {
+    process.stderr.write(`agentic-security remediation update: --state must be one of in_progress|awaiting_verification (got ${JSON.stringify(stateFlag)}).\n`);
+    return 2;
+  }
+
+  const payload = { type: 'state_changed', at: new Date().toISOString(), itemId: idFlag, state: stateFlag };
+  return _remediationWrite(targetAbs, 'update', 'remediation_update', payload, args);
+}
+
+// agentic-security remediation accept-risk [path] --id <itemId>
+//   --approver <id> --reason <text> --scope <text> --expires <YYYY-MM-DD>
+//   [--author <id>] [--base-event <hash>] [--output <file>] [--yes]
+async function cmdRemediationAcceptRisk(args) {
+  const target = args._[2] || '.'; // args._ = ['remediation', 'accept-risk', <path>?]
+  const targetAbs = path.resolve(target);
+
+  const idFlag = args.flags.id;
+  const approverFlag = args.flags.approver;
+  const reasonFlag = args.flags.reason;
+  const scopeFlag = args.flags.scope;
+  const expiresFlag = args.flags.expires;
+
+  for (const [name, val] of [
+    ['--id', idFlag], ['--approver', approverFlag], ['--reason', reasonFlag],
+    ['--scope', scopeFlag], ['--expires', expiresFlag],
+  ]) {
+    if (!val || typeof val !== 'string') {
+      process.stderr.write(`agentic-security remediation accept-risk: ${name} is required.\n`);
+      return 2;
+    }
+  }
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(expiresFlag)) {
+    process.stderr.write(`agentic-security remediation accept-risk: --expires must be a YYYY-MM-DD date (got ${JSON.stringify(expiresFlag)}).\n`);
+    return 2;
+  }
+
+  const { loadApproverRegistry, verifyApprover, checkSeparationOfDuties } =
+    await import('../src/fix/approver-registry.js');
+  const registry = loadApproverRegistry(targetAbs);
+  const v = verifyApprover(registry, approverFlag, []);
+  if (!v.verified) {
+    process.stderr.write(`agentic-security remediation accept-risk: ${v.reason}\n`);
+    return 1;
+  }
+  const sod = checkSeparationOfDuties(registry, args.flags.author, approverFlag);
+  if (!sod.ok) {
+    process.stderr.write(`agentic-security remediation accept-risk: ${sod.reason}\n`);
+    return 1;
+  }
+
+  const payload = {
+    type: 'accepted_risk',
+    at: new Date().toISOString(),
+    itemId: idFlag,
+    approver: approverFlag,
+    reason: reasonFlag,
+    scope: scopeFlag,
+    expiration: expiresFlag,
+  };
+  return _remediationWrite(targetAbs, 'accept-risk', 'remediation_accept_risk', payload, args);
+}
+
+// Byte-identical in behavior to _dfDiffMdInline/_dfDiffMdCell's own bodies
+// (bin/agentic-security.js), reimplemented locally per this codebase's
+// established per-module-owns-its-own-escaping-helpers convention.
+function _remMdInline(value) {
+  return String(value).replace(/\r\n|\r|\n/g, ' ');
+}
+function _remMdCell(value) {
+  return _remMdInline(value).replace(/\\/g, '\\\\').replace(/\|/g, '\\|');
+}
+
+function _renderRemediationListMarkdown(items, integrity) {
+  const lines = [];
+  if (integrity && !integrity.ok) {
+    lines.push(`> **WARNING — ledger integrity check failed**: the ledger's real content has ${integrity.totalLines} lines but only ${integrity.verifiedLines} verify; the list below may be missing recent items or reflect a tampered/truncated history. Do not treat it as complete.`);
+    lines.push('');
+  }
+  if (items.length === 0) {
+    lines.push('_no remediation items_');
+    return lines.join('\n') + '\n';
+  }
+  lines.push('| id | state | owner | dueDate | recommendedControl |');
+  lines.push('| --- | --- | --- | --- | --- |');
+  for (const item of items) {
+    const control = String(item.recommendedControl ?? '');
+    const truncated = control.length > 60 ? control.slice(0, 60) + '…' : control;
+    lines.push(`| ${_remMdCell(item.id)} | ${_remMdCell(item.state)} | ${_remMdCell(item.owner)} | ${_remMdCell(item.dueDate)} | ${_remMdCell(truncated)} |`);
+  }
+  return lines.join('\n') + '\n';
+}
+
+// agentic-security remediation list [path] [--format json|markdown] [--output <file>]
+async function cmdRemediationList(args) {
+  const target = args._[2] || '.'; // args._ = ['remediation', 'list', <path>?]
+  const targetAbs = path.resolve(target);
+
+  const format = args.flags.format ?? 'json';
+  if (format !== 'json' && format !== 'markdown') {
+    process.stderr.write(`agentic-security remediation list: --format must be one of json|markdown (got ${JSON.stringify(format)}).\n`);
+    return 2;
+  }
+
+  const { readLedgerEvents, ledgerIntegrity } = await import('../src/posture/remediation-ledger.js');
+  const { foldRemediationLedger } = await import('../src/lineage/remediation.js');
+  const items = Object.values(foldRemediationLedger(readLedgerEvents(targetAbs)))
+    .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+
+  // I7: a tampered/truncated ledger otherwise silently presents a
+  // shorter-than-real history with no signal anywhere. `ledgerIntegrity`
+  // is a read-only diagnostic — it never changes `items` itself (already
+  // computed from the same longest-verifying-prefix `readLedgerEvents`
+  // always returned) — it just surfaces the loud warning this command
+  // previously had no way to give.
+  const integrity = ledgerIntegrity(targetAbs);
+  if (!integrity.ok) {
+    process.stderr.write(`agentic-security remediation list: WARNING — the ledger's real content has ${integrity.totalLines} lines but only ${integrity.verifiedLines} verify; the list below may be missing recent items or reflect a tampered/truncated history. Do not treat it as complete.\n`);
+  }
+
+  const data = format === 'json' ? JSON.stringify({ items, integrity }, null, 2) : _renderRemediationListMarkdown(items, integrity);
+  const outputPath = args.flags.output;
+  if (outputPath) {
+    fs.writeFileSync(path.resolve(outputPath), data);
+  } else {
+    process.stdout.write(data.endsWith('\n') ? data : data + '\n');
+  }
+  return 0;
+}
+
+// ── remediation verify / reopen-check — M5 deliverable #6, Task 4. The
+// AC-31-CRITICAL half: nothing in this sub-project satisfies AC-31 until
+// these two verbs land — they are the only callers of computeGraphDiff/
+// evaluateVerificationEvidence/drift-policy.js that actually gate the
+// remediation ledger's own `verified`/`reopened` transitions.
+
+// agentic-security remediation verify [path] --id <itemId> [--against <commit>]
+//   [--manual-attestation --approver <id> --reason <text> [--author <id>]]
+//   [--base-event <hash>] [--output <file>] [--yes]
+//
+// Two branches:
+//
+//  - `--manual-attestation`: after the same approver/separation-of-duties
+//    gating `accept-risk` uses, builds a manual_attestation payload and
+//    delegates straight to `_remediationWrite` — NEVER computes a diff.
+//    The `manualAttestationPermitted` check is `validateTransition`'s job
+//    (enforced inside `appendLedgerEvent`), not duplicated here — V/7
+//    proves it fires through the ledger, not through this handler.
+//
+//  - default (scan-verification): resolves the AFTER snapshot exactly as
+//    `cmdDataflowDiff` does (`loadSnapshots(targetAbs)[0]`; `--against
+//    <commit>` is a COMMIT KEY resolved via `loadSnapshot`, never a
+//    snapshot id — same resolution `cmdDataflowDiff` uses). The BEFORE
+//    snapshot is preferentially the item's own incident snapshot
+//    (`item.assessment.snapshotId`, resolved by scanning `loadSnapshots`
+//    for a record whose `.id` matches) — that is what makes AC-31's
+//    "fixed to the incident snapshot" clause true in verification too.
+//    When the incident snapshot is no longer on disk, falls back to the
+//    `cmdDataflowDiff` resolution (`mostRecentPriorSnapshot`), and says so
+//    (`beforeSnapshotSource`) rather than silently substituting a
+//    different baseline. An explicit `--against` always wins over both.
+//    `computeGraphDiff` is wrapped in a try/catch — it THROWS on an
+//    incomparable pair (`graph-diff.js:319`) — converted to an
+//    `incomparable_snapshots` unverifiable outcome, never an abort:
+//    verification was genuinely attempted and genuinely refused, and the
+//    ledger records that.
+//
+// A `snapshotsComparable`-passed pair means "same schemaVersion" and
+// nothing more (`graph-snapshot.js:173`) — two snapshots from genuinely
+// different analyzer configurations are reported comparable; this is a
+// disclosed limitation, not papered over (see commands/remediation.md).
+async function cmdRemediationVerify(args) {
+  const target = args._[2] || '.'; // args._ = ['remediation', 'verify', <path>?]
+  const targetAbs = path.resolve(target);
+
+  const idFlag = args.flags.id;
+  if (!idFlag || typeof idFlag !== 'string') {
+    process.stderr.write('agentic-security remediation verify: --id <itemId> is required.\n');
+    return 2;
+  }
+
+  const { readLedgerEvents } = await import('../src/posture/remediation-ledger.js');
+  const { foldRemediationLedger, evaluateVerificationEvidence } = await import('../src/lineage/remediation.js');
+  const items = foldRemediationLedger(readLedgerEvents(targetAbs));
+  const item = items[idFlag];
+  if (!item) {
+    process.stderr.write(`agentic-security remediation verify: no remediation item found with id "${idFlag}".\n`);
+    return 1;
+  }
+
+  // ── Manual-attestation branch. Never computes a diff. ──────────────────
+  if (args.flags['manual-attestation']) {
+    const approverFlag = args.flags.approver;
+    const reasonFlag = args.flags.reason;
+    if (!approverFlag || typeof approverFlag !== 'string' || !reasonFlag || typeof reasonFlag !== 'string') {
+      process.stderr.write('agentic-security remediation verify: --manual-attestation requires --approver <id> and --reason <text>.\n');
+      return 2;
+    }
+    const { loadApproverRegistry, verifyApprover, checkSeparationOfDuties } =
+      await import('../src/fix/approver-registry.js');
+    const registry = loadApproverRegistry(targetAbs);
+    const v = verifyApprover(registry, approverFlag, []);
+    if (!v.verified) {
+      process.stderr.write(`agentic-security remediation verify: ${v.reason}\n`);
+      return 1;
+    }
+    const sod = checkSeparationOfDuties(registry, args.flags.author, approverFlag);
+    if (!sod.ok) {
+      process.stderr.write(`agentic-security remediation verify: ${sod.reason}\n`);
+      return 1;
+    }
+    if (args.flags.against !== undefined) {
+      // M15: --against has no effect on this branch — it never computes a
+      // diff — but a caller supplying both should be told, not left to
+      // wonder why it was silently ignored.
+      process.stderr.write('agentic-security remediation verify: --against has no effect with --manual-attestation (no scan comparison is performed for a manual attestation).\n');
+    }
+    // Resolves the newest available snapshot (if any exist yet — a manual
+    // attestation before any lineage scan has ever run is legitimate, so
+    // this is never required) and records it as the item's new baseline
+    // (final-review fix round 1, Blocking-3) — `foldRemediationItem`'s
+    // `manual_attestation` case reads `ev.snapshotId` to set
+    // `verificationSnapshotId`, which is what makes the attestation
+    // survive the very next `reopen-check` instead of being immediately
+    // undone by a stale old anchor.
+    const attestationSnapshots = loadSnapshots(targetAbs);
+    const payload = {
+      type: 'manual_attestation',
+      at: new Date().toISOString(),
+      itemId: idFlag,
+      approver: approverFlag,
+      reason: reasonFlag,
+      ...(attestationSnapshots.length > 0 ? { snapshotId: attestationSnapshots[0].id } : {}),
+    };
+    return _remediationWrite(targetAbs, 'verify', 'remediation_verify', payload, args);
+  }
+
+  // ── Scan-verification branch (the default). ─────────────────────────────
+  const snapshots = loadSnapshots(targetAbs);
+  if (snapshots.length === 0) {
+    process.stderr.write(`agentic-security remediation verify: no persisted GraphSnapshot found for "${targetAbs}" — run a scan with AGENTIC_SECURITY_LINEAGE_DEEP=1 first.\n`);
+    return 2;
+  }
+  const afterSnapshot = snapshots[0];
+
+  const againstFlag = args.flags.against;
+  if (againstFlag !== undefined && (typeof againstFlag !== 'string' || !againstFlag)) {
+    process.stderr.write('agentic-security remediation verify: --against requires a commit value.\n');
+    return 2;
+  }
+
+  let beforeSnapshot;
+  let beforeSnapshotSource;
+  if (againstFlag !== undefined) {
+    beforeSnapshot = loadSnapshot(targetAbs, againstFlag);
+    if (!beforeSnapshot) {
+      process.stderr.write(`agentic-security remediation verify: no persisted GraphSnapshot found for commit "${againstFlag}" — pass a commit that was actually scanned.\n`);
+      return 2;
+    }
+    beforeSnapshotSource = 'against';
+  } else {
+    const incidentSnapshotId = item.assessment?.snapshotId;
+    const incidentSnapshot = incidentSnapshotId ? snapshots.find((s) => s.id === incidentSnapshotId) : null;
+    if (incidentSnapshot) {
+      beforeSnapshot = incidentSnapshot;
+      beforeSnapshotSource = 'incident';
+    } else {
+      beforeSnapshot = mostRecentPriorSnapshot(targetAbs, afterSnapshot.commit);
+      beforeSnapshotSource = 'most-recent-prior';
+    }
+  }
+
+  if (!beforeSnapshot || beforeSnapshot.commit === afterSnapshot.commit) {
+    process.stderr.write(`agentic-security remediation verify: an item cannot be verified until a second lineage scan exists — only one persisted GraphSnapshot is available (commit "${afterSnapshot.commit}"). Scan again after a code change, or pass --against <commit>.\n`);
+    return 2;
+  }
+
+  let evidenceOutcome;
+  if (afterSnapshot.capturedAt <= beforeSnapshot.capturedAt) {
+    // A real, live-reproduced Blocking bug (final review, B1): a `verified`
+    // outcome must never be granted by comparing backwards. `loadSnapshots`
+    // sorts by file mtime (pre-existing, out of scope to fix here), so
+    // `cp -R`/rsync/a CI cache restore/tar/Docker COPY can silently reorder
+    // "history" — nothing else in this deliverable's own code checks
+    // direction. `capturedAt` is an ISO-8601 string on every real
+    // GraphSnapshot record, so plain string comparison is chronologically
+    // correct here, no `Date` parsing needed.
+    evidenceOutcome = {
+      outcome: 'unverifiable',
+      reason: 'stale_after_snapshot',
+      beforeCapturedAt: beforeSnapshot.capturedAt,
+      afterCapturedAt: afterSnapshot.capturedAt,
+    };
+  } else {
+    const { computeGraphDiff } = await import('../src/lineage/graph-diff.js');
+    try {
+      const diff = computeGraphDiff(beforeSnapshot, afterSnapshot);
+      evidenceOutcome = evaluateVerificationEvidence(diff, item.requiredEvidence);
+    } catch (e) {
+      // computeGraphDiff THROWS on an incomparable pair — this is NOT an
+      // exit-2 abort: verification was genuinely attempted and genuinely
+      // refused, and the ledger must record why.
+      evidenceOutcome = { outcome: 'unverifiable', reason: 'incomparable_snapshots', detail: e && e.message ? e.message : String(e) };
+    }
+  }
+
+  const at = new Date().toISOString();
+  let payload;
+  if (evidenceOutcome.outcome === 'verified') {
+    payload = { type: 'scan_verification', at, itemId: idFlag, outcome: 'verified', snapshotId: afterSnapshot.id };
+  } else {
+    // Carry every detail field through verbatim so the ledger records WHY,
+    // not just THAT — unsatisfiedFlowIds/coverageRegressionReasons/
+    // reidentifiedTo/flowId/detail are all conditionally present depending
+    // on which evaluateVerificationEvidence branch fired.
+    payload = { type: 'scan_verification', at, itemId: idFlag, outcome: 'unverifiable', reason: evidenceOutcome.reason };
+    for (const field of ['unsatisfiedFlowIds', 'coverageRegressionReasons', 'reidentifiedTo', 'flowId', 'detail']) {
+      if (evidenceOutcome[field] !== undefined) payload[field] = evidenceOutcome[field];
+    }
+  }
+
+  const extraReport = {
+    beforeSnapshotId: beforeSnapshot.id,
+    afterSnapshotId: afterSnapshot.id,
+    beforeSnapshotSource,
+    evidenceOutcome,
+  };
+  return _remediationWrite(targetAbs, 'verify', 'remediation_verify', payload, args, extraReport);
+}
+
+// agentic-security remediation reopen-check [path] [--drift-policy <file>]
+//   [--against <commit>] [--output <file>] [--yes]
+//
+// AC-31's automatic-reopening half. Resolves the AFTER snapshot exactly
+// like `cmdDataflowDiff`/`cmdRemediationVerify`; `--against <commit>`
+// pins a DEFAULT/FALLBACK before-commit (never used per-item directly —
+// see below). Every item currently in state `verified` is checked
+// against TWO independently-evaluated, separately-labelled mechanisms
+// (scoping doc §4.5) — never collapsed into one unlabelled "reopened"
+// reason:
+//
+//  - mechanism 'drift-policy' (Mechanism A, regression via operator
+//    policy): requires `--drift-policy`; a violation whose own `flowId`
+//    names one of the item's own `affectedFlowIds` is a hit.
+//  - mechanism 'affected-flow-diff' (Mechanism B, control went away, a
+//    direct diff read): any of the item's `affectedFlowIds` (or a flow
+//    `reidentifiedFrom` one of them, I6) REAPPEARING in `diff.added.flows`
+//    is a hit — final-review fix round 1's own Blocking-2 correction: a
+//    scan-verified item's flagged flow was, by construction, ABSENT from
+//    its own before-baseline, so a regression can only ever show up in
+//    `diff.added.flows`, never `diff.removed.flows`/`diff.changed.flows`
+//    (the original code read those two buckets instead, which is dead
+//    for the canonical scan-verified case and fires INVERTED — reopening
+//    an item because its flow successfully disappeared — for a manually-
+//    attested item whose baseline still contained the flow). This exists
+//    because `drift-policy.js`'s trigger vocabulary is exactly
+//    `['new_flow', 'changed_flow']` — there is no `removed_flow` trigger,
+//    so a control that goes away (the flow itself disappears from a
+//    later scan) cannot be expressed as a drift policy at ALL.
+//
+//    Disclosed limitation, not attempted in this round: a manually-
+//    attested item whose flagged flow was ALREADY present at attestation
+//    time (the typical manual-attestation scenario — a compensating
+//    control, not flow removal) can never trigger Mechanism B this way,
+//    since the flow never left `diff.added.flows`'s scope (it's already
+//    present in both before/after). Such an item can only be reopened via
+//    Mechanism A (`--drift-policy`).
+//
+// Per item, the BEFORE snapshot is preferentially the item's own
+// `verificationSnapshotId` (the snapshot its verification was granted
+// against — the only defensible "has it regressed since" baseline),
+// falling back to the CLI-resolved default BEFORE (`--against` /
+// `mostRecentPriorSnapshot`) when that snapshot is no longer on disk.
+//
+// No `--base-event`: this appends N events across N items, so a single
+// whole-ledger token has no coherent meaning (documented in
+// commands/remediation.md, not left for a reader to wonder about).
+async function cmdRemediationReopenCheck(args) {
+  const target = args._[2] || '.'; // args._ = ['remediation', 'reopen-check', <path>?]
+  const targetAbs = path.resolve(target);
+
+  const snapshots = loadSnapshots(targetAbs);
+  if (snapshots.length === 0) {
+    process.stderr.write(`agentic-security remediation reopen-check: no persisted GraphSnapshot found for "${targetAbs}" — run a scan with AGENTIC_SECURITY_LINEAGE_DEEP=1 first.\n`);
+    return 2;
+  }
+  const afterSnapshot = snapshots[0];
+
+  const againstFlag = args.flags.against;
+  if (againstFlag !== undefined && (typeof againstFlag !== 'string' || !againstFlag)) {
+    process.stderr.write('agentic-security remediation reopen-check: --against requires a commit value.\n');
+    return 2;
+  }
+
+  let defaultBeforeSnapshot;
+  if (againstFlag !== undefined) {
+    defaultBeforeSnapshot = loadSnapshot(targetAbs, againstFlag);
+    if (!defaultBeforeSnapshot) {
+      process.stderr.write(`agentic-security remediation reopen-check: no persisted GraphSnapshot found for commit "${againstFlag}" — pass a commit that was actually scanned.\n`);
+      return 2;
+    }
+  } else {
+    defaultBeforeSnapshot = mostRecentPriorSnapshot(targetAbs, afterSnapshot.commit);
+    if (!defaultBeforeSnapshot) {
+      process.stderr.write(`agentic-security remediation reopen-check: only one persisted GraphSnapshot exists (commit "${afterSnapshot.commit}") — nothing to compare against yet. Scan again after a code change, or pass --against <commit>.\n`);
+      return 2;
+    }
+  }
+
+  const driftPolicyFlag = args.flags['drift-policy'];
+  const driftPolicyProvided = driftPolicyFlag !== undefined;
+  let policies = { policies: [] };
+  if (driftPolicyProvided) {
+    if (typeof driftPolicyFlag !== 'string' || !driftPolicyFlag) {
+      process.stderr.write('agentic-security remediation reopen-check: --drift-policy requires a file path.\n');
+      return 2;
+    }
+    const driftPolicyAbs = path.resolve(driftPolicyFlag);
+    const check = _validateDriftPolicyFile(driftPolicyAbs, driftPolicyFlag, 'reopen-check');
+    if (!check.ok) {
+      process.stderr.write(check.message);
+      return 2;
+    }
+    const { loadDriftPolicies } = await import('../src/lineage/drift-policy.js');
+    policies = loadDriftPolicies(driftPolicyAbs);
+  }
+
+  const { readLedgerEvents, appendLedgerEvent } = await import('../src/posture/remediation-ledger.js');
+  const { foldRemediationLedger } = await import('../src/lineage/remediation.js');
+  const { computeGraphDiff } = await import('../src/lineage/graph-diff.js');
+  let evaluateDriftPolicies = null;
+  if (driftPolicyProvided) {
+    ({ evaluateDriftPolicies } = await import('../src/lineage/drift-policy.js'));
+  }
+
+  const verifiedItems = Object.values(foldRemediationLedger(readLedgerEvents(targetAbs)))
+    .filter((it) => it.state === 'verified')
+    .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+
+  const findings = []; // {itemId, mechanism, reason, beforeSnapshotSource}
+  const skipped = []; // {itemId, reason}
+
+  for (const item of verifiedItems) {
+    let beforeSnapshot;
+    let beforeSnapshotSource;
+    if (item.verificationSnapshotId) {
+      const found = snapshots.find((s) => s.id === item.verificationSnapshotId);
+      if (found) { beforeSnapshot = found; beforeSnapshotSource = 'verification'; }
+    }
+    if (!beforeSnapshot) { beforeSnapshot = defaultBeforeSnapshot; beforeSnapshotSource = 'default'; }
+
+    if (!beforeSnapshot || beforeSnapshot.commit === afterSnapshot.commit) {
+      skipped.push({ itemId: item.id, reason: 'no distinct before-snapshot could be resolved for this item' });
+      continue;
+    }
+
+    let diff;
+    try {
+      diff = computeGraphDiff(beforeSnapshot, afterSnapshot);
+    } catch (e) {
+      // Never a crash and never a silent pass — a diff-error item is
+      // recorded as skipped, with its real reason.
+      skipped.push({ itemId: item.id, reason: `incomparable snapshots: ${e && e.message ? e.message : e}` });
+      continue;
+    }
+
+    const affectedFlowIds = new Set(item.affectedFlowIds ?? []);
+    let hit = null;
+
+    // Mechanism A: drift-policy regression.
+    if (driftPolicyProvided) {
+      const { violations } = evaluateDriftPolicies(diff, policies, afterSnapshot.graph);
+      const violation = violations.find((v) => affectedFlowIds.has(v.flowId));
+      if (violation) {
+        hit = { mechanism: 'drift-policy', reason: `drift-policy rule (${violation.trigger}) matched flow ${violation.flowId}: ${violation.reason}` };
+      }
+    }
+
+    // Mechanism B: the control this item established went away — the
+    // flagged flow REAPPEARED relative to the item's own baseline. This is
+    // the symmetric complement of evaluateVerificationEvidence's own
+    // "gone via diff.removed.flows" check: a regression is the flow coming
+    // BACK, which shows up in diff.added.flows, never diff.removed/changed
+    // (a flow disappearing is a FIX, never a regression — the original
+    // code fired on exactly the wrong signal here, a real Blocking bug
+    // found by the final review, live-reproduced against a successfully
+    // remediated item). Also matches a re-identified reappearance (I6): a
+    // flow whose own discriminator moved on the way back still counts, via
+    // reidentifiedFrom.
+    if (!hit) {
+      const addedHit = (diff.added?.flows ?? []).find((e) =>
+        affectedFlowIds.has(e.id) ||
+        (e.causeClassification === 'reidentified' && affectedFlowIds.has(e.reidentifiedFrom))
+      );
+      if (addedHit) {
+        hit = { mechanism: 'affected-flow-diff', reason: `affected flow reappeared as ${addedHit.id} in diff.added.flows (causeClassification: ${addedHit.causeClassification}${addedHit.reidentifiedFrom ? `, reidentified from ${addedHit.reidentifiedFrom}` : ''})` };
+      }
+    }
+
+    if (hit) {
+      findings.push({ itemId: item.id, mechanism: hit.mechanism, reason: hit.reason, beforeSnapshotSource });
+    }
+  }
+
+  const yes = !!args.flags.yes;
+
+  if (!yes) {
+    const report = {
+      verb: 'reopen-check', afterSnapshotId: afterSnapshot.id, driftPolicyProvided,
+      written: false, wouldReopen: findings, skipped,
+    };
+    _emitRemediationReport(report, args);
+    return 0;
+  }
+
+  if (findings.length > 0) {
+    const { isSafeStateDir } = await import('../src/posture/state-dir.js');
+    const { ledgerPaths } = await import('../src/posture/remediation-ledger.js');
+    const { ledgerPath } = ledgerPaths(targetAbs);
+    if (!isSafeStateDir(path.dirname(ledgerPath))) {
+      process.stderr.write(`agentic-security remediation reopen-check: refusing to write — "${targetAbs}" does not look like a project directory.\n`);
+      return 2;
+    }
+  }
+
+  const reopened = [];
+  const failedToReopen = [];
+  try {
+    for (const f of findings) {
+      const payload = { type: 'reopened', at: new Date().toISOString(), itemId: f.itemId, reason: f.reason };
+      // Each event is independently validated by appendLedgerEvent's own
+      // (sole-authoritative) validateTransition call — an item that raced
+      // into a non-`verified` state between the fold above and this append
+      // is correctly rejected here and reported as skipped, never
+      // force-written.
+      const result = await appendLedgerEvent(targetAbs, payload);
+      if (result.valid) {
+        reopened.push({ itemId: f.itemId, mechanism: f.mechanism, reason: f.reason, beforeSnapshotSource: f.beforeSnapshotSource, eventHash: result.hash });
+      } else {
+        failedToReopen.push({ itemId: f.itemId, errors: result.errors });
+      }
+    }
+  } catch (e) {
+    process.stderr.write(`agentic-security remediation reopen-check: unexpected error writing the ledger: ${e && e.message ? e.message : e}\n`);
+    return 4;
+  }
+
+  if (reopened.length > 0) {
+    const { auditCall } = await import('../src/mcp/audit.js');
+    auditCall({
+      sessionRoot: targetAbs,
+      tool: 'remediation_reopen_check',
+      args: { itemIds: reopened.map((r) => r.itemId) },
+      outcome: 'ok',
+    });
+  }
+
+  const report = {
+    verb: 'reopen-check', afterSnapshotId: afterSnapshot.id, driftPolicyProvided,
+    written: reopened.length > 0, reopened, failedToReopen, skipped,
+  };
+  _emitRemediationReport(report, args);
+  return 0;
+}
+
+// Terse [watch-dataflow] status line — mirrors watch-mode.js's own
+// renderStatusLine terse style, adapted to a GraphDiff's own
+// added/removed/changed shape (computeGraphDiff's `changed` bucket is
+// flows-only, per graph-diff.js's own header).
+function _renderDataflowWatchStatusLine(diff) {
+  const n = diff.added.nodes.length, N = diff.removed.nodes.length;
+  const e = diff.added.edges.length, E = diff.removed.edges.length;
+  const d = diff.added.dataElements.length, D = diff.removed.dataElements.length;
+  const f = diff.added.flows.length, F = diff.removed.flows.length, C = diff.changed.flows.length;
+  if (n + N + e + E + d + D + f + F + C === 0) return 'no data-flow graph changes';
+  return `+${f}/-${F} flows (~${C} changed), +${n}/-${N} nodes, +${e}/-${E} edges, +${d}/-${D} data elements`;
+}
+
+// A louder, clearly-marked, Markdown-free plain-text block naming each
+// drift-policy violation — a model of _renderDataflowDiffMarkdown's own
+// violation-table CONTENT (trigger/flow/data-elements/sink/reason), never
+// its literal Markdown-table code (this command's whole output is a live
+// stderr stream, not a file). --fail-on-drift has no exit-code effect in a
+// long-running watch process (there is no single exit code to gate — see
+// this command's own startup banner / commands/dataflow.md) — it only
+// changes how loud this block reads.
+function _renderDataflowWatchViolations(violations, failOnDrift) {
+  const marker = failOnDrift
+    ? '[watch-dataflow] !!! DRIFT POLICY VIOLATION !!!'
+    : '[watch-dataflow] *** drift policy violation ***';
+  const lines = [];
+  for (const v of violations) {
+    lines.push(marker);
+    lines.push(`[watch-dataflow]   ${v.trigger}: flow ${v.flowId} — ${(v.dataElementNames ?? []).join(', ') || '(unclassified data)'} -> ${v.sinkCategory ?? v.sinkNodeId ?? 'unknown sink'}`);
+    lines.push(`[watch-dataflow]   ${v.reason}`);
+  }
+  return lines.length ? lines.join('\n') + '\n' : '';
+}
+
+// #9 (M4 deliverable #9, watch-mode graph delta updates) — re-runs a deep
+// lineage scan on every debounced file-system change and reports the real
+// GraphDiff, reusing already-shipped Task 1 (buildGraphSnapshot)/8b
+// (computeGraphDiff/drift-policy) primitives. Mirrors cmdScan's own
+// `--watch` blocking/Ctrl-C/stderr-status-line UX (bin/agentic-security.js,
+// `args.flags['watch']`) — see that block's own header comment for the
+// shared "blocks until Ctrl-C" contract.
+//
+// Two disclosed, deliberate scope boundaries (docs/superpowers/plans/
+// 2026-09-02-data-flow-explorer-m4-watch-mode-scoping.md §2/§3), both named
+// in this command's own startup banner, not just here:
+//   - NEVER calls persistGraphSnapshot — only buildGraphSnapshot (Task 1's
+//     own pure, zero-disk-I/O builder). Every rescan before a real `git
+//     commit` resolves to the same HEAD, so persisting on every debounced
+//     rescan would silently overwrite real, commit-keyed snapshot history
+//     with transient, mid-edit graph state. The "before" snapshot lives
+//     purely in the closure variable `prevSnapshot` below, exactly like
+//     the existing SAST `--watch`'s own `prevFindings` closure variable.
+//   - Does NOT refresh .agentic-security/lineage-graph.json on any
+//     rescan — an already-running `explore` session has no live-reload
+//     (confirmed directly against src/server/*.js) and would not reflect
+//     these edits regardless; disclosed rather than implied away.
+async function cmdDataflowWatch(args) {
+  const target = args._[2] || '.';
+  const targetAbs = path.resolve(target);
+
+  const driftPolicyFlag = args.flags['drift-policy'];
+  if (driftPolicyFlag !== undefined && (typeof driftPolicyFlag !== 'string' || !driftPolicyFlag)) {
+    process.stderr.write('agentic-security dataflow watch: --drift-policy requires a file path.\n');
+    return 2;
+  }
+  const failOnDrift = !!args.flags['fail-on-drift'];
+  const driftPolicyProvided = driftPolicyFlag !== undefined;
+
+  let policies = null;
+  let evaluateDriftPolicies = null;
+  if (driftPolicyProvided) {
+    const driftPolicyAbs = path.resolve(driftPolicyFlag);
+    const check = _validateDriftPolicyFile(driftPolicyAbs, driftPolicyFlag, 'watch');
+    if (!check.ok) {
+      process.stderr.write(check.message);
+      return 2;
+    }
+    const driftPolicyModule = await import('../src/lineage/drift-policy.js');
+    policies = driftPolicyModule.loadDriftPolicies(driftPolicyAbs);
+    evaluateDriftPolicies = driftPolicyModule.evaluateDriftPolicies;
+  }
+
+  const { watchProject } = await import('../src/posture/watch-mode.js');
+  const { buildGraphSnapshot } = await import('../src/lineage/graph-snapshot.js');
+  const { computeGraphDiff } = await import('../src/lineage/graph-diff.js');
+
+  // This is what makes runScan attach scan.lineageGraph at all — without
+  // it, every rescan (including the seed) produces no graph and this
+  // command has nothing to diff. Mirrors cmdScan's own `--watch` branch
+  // setting AGENTIC_SECURITY_INCREMENTAL before its own seed scan.
+  process.env.AGENTIC_SECURITY_LINEAGE_DEEP = '1';
+
+  // Deliberately printed BEFORE the (possibly multi-second) seed scan —
+  // real-time feedback that the command is alive, not stuck — but this is
+  // NOT the "the watcher is live" signal; see the banner printed below,
+  // right before `watchProject` is called, for that.
+  process.stderr.write(`[watch-dataflow] running seed scan for ${targetAbs}...\n`);
+
+  const _lineageStatusReason = (ls) => (ls && ls.failure) ? `failure: ${ls.failure}` : (ls && ls.reason) ? `reason: ${ls.reason}` : 'unknown reason';
+
+  // withStateWritesDisabled, for the same reason lsp/server.js's on-save scan
+  // and mcp/tools.js's scan_diff (FR-704) wrap their own repeated runScan
+  // calls. This command reruns a full scan on every debounced file edit for
+  // as long as the watch session stays open, against the user's real project
+  // root, with state writes fully enabled by default — without the wrapper,
+  // every single-edit rescan writes ~11 real files into .agentic-security/
+  // (dpia.md, ropa.md, threat-model.*, privacy-framework.*, data-inventory.json,
+  // sbom-history/, ...), appends to scan-history.json, and — the genuinely
+  // dangerous part — feeds posture/provenance/lifecycle.js's introduce/
+  // remediate/reintroduce ledger. A real, transient mid-edit change (e.g. a
+  // cut-and-paste during a refactor) would get recorded as a FABRICATED
+  // `remediated` event (commit: null, authorDate: null), later undone by a
+  // fabricated `reintroduced` event — permanently corrupting the one
+  // artifact that backs finding provenance, MTTR reporting, and signed
+  // evidence bundles, for a "fix" that never happened. exceptCategories:
+  // ['provenance-cache'] mirrors lsp/server.js's own exact precedent: it
+  // keeps ONLY the provenance disk cache live across repeated rescans in one
+  // watch session (so a slowly-changing project doesn't pay the full
+  // uncached provenance-resolution cost on every edit), while every OTHER
+  // state write named above stays fully suppressed. Do not "simplify" this
+  // back to a bare runScan call.
+  const seed = await withStateWritesDisabled(() => runScan(targetAbs, {}), { exceptCategories: ['provenance-cache'] });
+  if (!seed.scan.lineageGraph) {
+    process.stderr.write(`agentic-security dataflow watch: seed scan produced no data-flow graph (${_lineageStatusReason(seed.scan.lineageStatus)}) — nothing to watch/diff against.\n`);
+    return 1;
+  }
+  let prevSnapshot = buildGraphSnapshot(seed.scan.lineageGraph, targetAbs);
+
+  // watchProject itself checks process.env.AGENTIC_SECURITY_NO_WATCH === '1'
+  // internally and returns immediately without ever subscribing to fs.watch
+  // — so if we printed the "watching..." banner unconditionally below, a
+  // caller with the env var set would see "watching..." immediately followed
+  // by the process exiting, having watched nothing. Check the exact same
+  // condition watchProject checks (do not invent a different one that could
+  // drift from it) and print an honest message instead.
+  if (process.env.AGENTIC_SECURITY_NO_WATCH === '1') {
+    process.stderr.write(`[watch-dataflow] AGENTIC_SECURITY_NO_WATCH=1 — watch mode is disabled; ran the seed scan only, not watching ${targetAbs} for changes.\n`);
+    return 0;
+  }
+
+  // Printed AFTER the seed scan succeeds, immediately before `watchProject`
+  // subscribes — this is the real "the watcher is live" signal a caller
+  // (this command's own CLI test included) can poll stderr for, unlike the
+  // pre-seed-scan message above.
+  process.stderr.write(`[watch-dataflow] watching ${targetAbs} for data-flow graph changes on file change — Ctrl-C to stop.\n`);
+  process.stderr.write('[watch-dataflow] does NOT refresh .agentic-security/lineage-graph.json on any rescan — an already-running `agentic-security explore` session will not reflect these edits live.\n');
+
+  // No in-flight-rescan guard: if a debounced batch fires while a previous
+  // rescan is still running, two concurrent invocations of this callback
+  // can race on `prevSnapshot` (the closure variable below), producing a
+  // diff against a stale baseline or clobbering it out of order on a large
+  // enough project. Not fixed here — watchProject's own design has no
+  // such guard, and the pre-existing `scan --watch` (this file's own
+  // args.flags['watch'] branch) has the identical unguarded shape on its
+  // own `prevFindings` variable; adding one here alone would diverge from
+  // that established UX for no consistent reason. A future increment
+  // could add a real mutex/generation-counter to BOTH commands together.
+  await watchProject(targetAbs, async (batch, watchErr) => {
+    if (watchErr) {
+      process.stderr.write(`[watch-dataflow] file watcher error: ${watchErr && watchErr.message ? watchErr.message : watchErr} — no longer watching for changes.\n`);
+      return;
+    }
+    try {
+      const { scan } = await withStateWritesDisabled(() => runScan(targetAbs, {}), { exceptCategories: ['provenance-cache'] });
+      if (!scan.lineageGraph) {
+        process.stderr.write(`[watch-dataflow] rescan produced no data-flow graph (${_lineageStatusReason(scan.lineageStatus)}) — skipping this change.\n`);
+        return;
+      }
+      const currSnapshot = buildGraphSnapshot(scan.lineageGraph, targetAbs);
+
+      let diff;
+      try {
+        diff = computeGraphDiff(prevSnapshot, currSnapshot);
+      } catch (e) {
+        process.stderr.write(`[watch-dataflow] could not diff: ${e && e.message ? e.message : e}\n`);
+        return;
+      }
+
+      let violations = [];
+      if (driftPolicyProvided) {
+        violations = evaluateDriftPolicies(diff, policies, currSnapshot.graph).violations;
+      }
+
+      process.stderr.write('[watch-dataflow] ' + _renderDataflowWatchStatusLine(diff) + '\n');
+      if (violations.length) {
+        process.stderr.write(_renderDataflowWatchViolations(violations, failOnDrift));
+      }
+
+      prevSnapshot = currSnapshot;
+    } catch (e) {
+      process.stderr.write(`[watch-dataflow] rescan failed: ${e && e.message ? e.message : e}\n`);
+    }
+  });
+
+  return 0; // watchProject itself does not block (see the dispatch site's
+  // own comment, case 'dataflow' -> the `watch` branch, for the full
+  // explanation) — the process stays alive on the live fs.watch handle
+  // watchProject subscribes internally, exiting only via Ctrl-C/SIGTERM.
+  // Do NOT "simplify" the dispatch call around this function back to
+  // `process.exit(await cmdDataflowWatch(args))` — that is the exact
+  // change that makes `scan --watch` exit before it ever watches anything.
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const cmd = args._[0];
+  try {
+    switch (cmd) {
+      case 'scan':     process.exit(await cmdScan(args));
+      case 'ship':     process.exit(await cmdShip(args));
+      case 'ci':       process.exit(await cmdCi(args));
+      case 'fix':      process.exit(await cmdFix(args));
+      case 'undo':     process.exit(await cmdUndo(args));
+      case 'accept':   process.exit(await cmdAccept(args));
+      case 'profile':  process.exit(await cmdProfile(args));
+      case 'triage':   process.exit(await cmdTriage(args));
+      case 'org-scan': process.exit(await cmdOrgScan(args));
+      case 'rules':    process.exit(await cmdRules(args));
+      case 'rule':     process.exit(await cmdRule(args));
+      case 'tickets':  process.exit(await cmdTickets(args));
+      case 'secure':   process.exit(await cmdSecure(args));
+      case 'packs':    process.exit(await cmdPacks(args));
+      case 'validator-cache': process.exit(await cmdValidatorCache(args));
+      case 'verify':   process.exit(await cmdVerify(args));
+      case 'reset':    process.exit(await cmdReset(args));
+      case 'export':   process.exit(await cmdExport(args));
+      case 'legal-hold': process.exit(await cmdLegalHold(args));
+      case 'calibration-feedback': process.exit(await cmdCalibrationFeedback(args));
+      case 'calibration-report': process.exit(await cmdCalibrationReport(args));
+      case 'hunt':     process.exit(await cmdHunt(args));
+      case 'compliance': process.exit(await cmdCompliance(args));
+      case 'attest':   process.exit(await cmdAttest(args));
+      case 'verify-attestation': process.exit(await cmdVerifyAttestation(args));
+      case 'policy-explain': process.exit(await cmdPolicyExplain(args));
+      case 'policy-sign': process.exit(await cmdPolicySign(args));
+      case 'rule-synth': process.exit(await cmdRuleSynth(args));
+      case 'digest':   process.exit(await cmdDigest(args));
+      case 'setup':    process.exit(await cmdSetup(args));
+      case 'cache-report': {
+        // Prompt-cache economics for the current session: parse the Claude Code
+        // transcript usage and report cache-hit %, $ saved, and avoidable leaks.
+        // Advisory/read-only — always exits 0.
+        const { analyzeTranscript, formatCacheReport } = await import('../src/posture/cache-economics.js');
+        const projectDir = path.resolve(args.flags.root || process.env.CLAUDE_PROJECT_DIR || process.cwd());
+        const result = analyzeTranscript({ transcriptPath: args.flags.transcript, projectDir });
+        if (args.flags.json) writeStdout(JSON.stringify(result, null, 2) + '\n');
+        else console.log(formatCacheReport(result));
+        process.exit(0);
+      }
+      case 'cache-statusline': {
+        // F6 — one-line cost HUD for a Claude Code statusLine command. Also writes
+        // .agentic-security/cache-telemetry.json for other pollers. Always exits 0.
+        const { analyzeTranscript, renderCacheStatusLine } = await import('../src/posture/cache-economics.js');
+        const projectDir = path.resolve(args.flags.root || process.env.CLAUDE_PROJECT_DIR || process.cwd());
+        const result = analyzeTranscript({ transcriptPath: args.flags.transcript, projectDir });
+        if (result.ok) {
+          try {
+            const dir = stateDir(projectDir);
+            fs.mkdirSync(dir, { recursive: true });
+            fs.writeFileSync(path.join(dir, 'cache-telemetry.json'),
+              JSON.stringify({ updatedAt: new Date().toISOString(), metrics: result.metrics, leaks: result.leaks }, null, 2));
+          } catch { /* best-effort */ }
+          console.log(renderCacheStatusLine(result.metrics));
+        } else {
+          console.log('agentic-security: no session cost yet');
+        }
+        process.exit(0);
+      }
+      case 'mcp':      {
+        const { runStdio } = await import('../src/mcp/stdio.js');
+        const root = args.flags.root || process.env.AGENTIC_SECURITY_MCP_ROOT || process.cwd();
+        runStdio({ sessionRoot: path.resolve(root) });
+        return;
+      }
+      case 'explore':  process.exit(await cmdExplore(args));
+      case 'dataflow': {
+        const sub = args._[1];
+        if (sub === 'export') { process.exit(await cmdDataflowExport(args)); }
+        else if (sub === 'diff') { process.exit(await cmdDataflowDiff(args)); }
+        else if (sub === 'watch') {
+          // NOT `process.exit(await cmdDataflowWatch(args))` — deliberately.
+          // process.exit() terminates immediately, ignoring any pending
+          // handles/timers; cmdDataflowWatch's own success path (return 0)
+          // resolves almost immediately once watchProject's internal
+          // subscription is set up (watchProject itself doesn't block —
+          // see that function's own header), so wrapping it in
+          // process.exit() here would tear the process down before the
+          // live fs.watch async iterator inside watchProject ever gets a
+          // chance to fire — confirmed empirically (measured exit in
+          // <1s, no rescan ever observed) against the pre-existing SAST
+          // `scan --watch` (bin/agentic-security.js's `args.flags['watch']`
+          // branch), which has this exact same latent bug via its own
+          // identical `process.exit(await cmdScan(args))` dispatch — out
+          // of scope to fix here (watch-mode.js/scan --watch are
+          // deliberately unmodified by this sub-project), but the fix for
+          // THIS new subcommand is to only exit explicitly on a non-zero
+          // (validation-failure / no-lineage-graph) return, which happens
+          // before watchProject is ever called and has nothing keeping
+          // the process alive on its own. On the success path the process
+          // is left to Node's default "still has an active handle" event
+          // loop keep-alive, exiting only via Ctrl-C (SIGINT)'s own
+          // Node-default termination.
+          const code = await cmdDataflowWatch(args);
+          if (code !== 0) process.exit(code);
+          break;
+        }
+        else if (sub === 'scenario') {
+          const scenarioSub = args._[2];
+          if (scenarioSub === 'apply') { process.exit(await cmdDataflowScenarioApply(args)); }
+          else {
+            process.stderr.write(`agentic-security dataflow scenario: unrecognized sub-command "${scenarioSub}" — must be "apply".\n`);
+            process.exit(2);
+          }
+          break;
+        }
+        else if (sub === 'impact') {
+          const impactSub = args._[2];
+          if (impactSub === 'assess') { process.exit(await cmdDataflowImpactAssess(args)); }
+          else {
+            process.stderr.write(`agentic-security dataflow impact: unrecognized sub-command "${impactSub}" — must be "assess".\n`);
+            process.exit(2);
+          }
+          break;
+        }
+        else if (sub === 'observations') {
+          const obsSub = args._[2];
+          if (obsSub === 'import') { process.exit(await cmdDataflowObservationsImport(args)); }
+          else if (obsSub === 'list') { process.exit(await cmdDataflowObservationsList(args)); }
+          else {
+            process.stderr.write(`agentic-security dataflow observations: unrecognized sub-command "${obsSub}" — must be "import" or "list".\n`);
+            process.exit(2);
+          }
+          break;
+        }
+        else if (sub === 'twin') { process.exit(await cmdDataflowTwin(args)); }
+        process.stderr.write(`agentic-security dataflow: unknown subcommand "${sub}" — only "export", "diff", "watch", "scenario", "impact", "observations", and "twin" are supported.\n`);
+        process.exit(2);
+      }
+      case 'governance': {
+        // NOT a `dataflow` subcommand — this edits operator config
+        // (recipient-profiles.json), never the scanned graph. See
+        // cmdGovernancePropose's own header comment for the full
+        // exit-code/backup/audit contract.
+        const sub = args._[1];
+        if (sub === 'propose-edit') { process.exit(await cmdGovernancePropose(args)); }
+        else {
+          process.stderr.write(`agentic-security governance: unrecognized sub-command "${sub}" — must be "propose-edit".\n`);
+          process.exit(2);
+        }
+        break;
+      }
+      case 'federate': {
+        // NOT a `dataflow` subcommand — this writes operator-declared
+        // config (cross-repo-links.json), never the scanned graph. Same
+        // distinction that made `governance`/`remediation` their own
+        // dispatchers. See cmdFederateDeclare's own header comment for
+        // the full exit-code/backup/audit contract.
+        const sub = args._[1];
+        if (sub === 'declare') { process.exit(await cmdFederateDeclare(args)); }
+        else if (sub === 'list') { process.exit(await cmdFederateList(args)); }
+        else {
+          process.stderr.write(`agentic-security federate: unrecognized sub-command "${sub}" — must be "declare" or "list".\n`);
+          process.exit(2);
+        }
+        break;
+      }
+      case 'remediation': {
+        // NOT a `dataflow` subcommand — this writes operator/incident
+        // state (the append-only remediation ledger), never the scanned
+        // graph. Same distinction that made `governance` its own
+        // dispatcher. See _remediationWrite's own header for the full
+        // base-event/isSafeStateDir/audit/exit-code contract.
+        const sub = args._[1];
+        if (sub === 'open') { process.exit(await cmdRemediationOpen(args)); }
+        else if (sub === 'update') { process.exit(await cmdRemediationUpdate(args)); }
+        else if (sub === 'verify') { process.exit(await cmdRemediationVerify(args)); }
+        else if (sub === 'accept-risk') { process.exit(await cmdRemediationAcceptRisk(args)); }
+        else if (sub === 'reopen-check') { process.exit(await cmdRemediationReopenCheck(args)); }
+        else if (sub === 'list') { process.exit(await cmdRemediationList(args)); }
+        else {
+          process.stderr.write(`agentic-security remediation: unrecognized sub-command "${sub}" — must be one of open|update|verify|accept-risk|reopen-check|list.\n`);
+          process.exit(2);
+        }
+        break;
       }
       case 'cve-watch': {
         // Continuous CVE-watch daemon (one-shot). Polls OSV for the project's