@cohortapp/agent-sdk 2.3.0

package/lib/security/audit-engine.mjs

@@ -0,0 +1,684 @@
+/**
+ * audit-engine.mjs — Registry-driven security-posture audit + hash-locked
+ * attestations (gaps-enterprise-ops G15).
+ *
+ * Doctor verifies *plumbing* (is the daemon wired, are queues healthy). This
+ * engine verifies *security posture* — the confirmed-CRITICAL/HIGH items from
+ * the enterprise audit that have a binary, machine-checkable answer on a single
+ * agent's disk: file modes on secrets, scoped-permission opt-in, the send-gate
+ * hook, no tracked build artifacts / symlinks, backup configured, an AI
+ * disclosure policy, and the daemon audit hooks being wired.
+ *
+ * Design mirrors lib/setup/sections/*.mjs and scripts/ci/check.mjs: a flat
+ * array of self-contained checks, each `{ id, severity, run(agentRoot, deps) }`.
+ * You extend the audit by adding a check to the array — never by editing a
+ * dispatcher. Every check is pure over its injected `fs`/`env`, so the whole
+ * suite runs in one process with no spawns and is trivially unit-testable.
+ *
+ * Fail-open is deliberately NOT the posture here: a check that cannot read the
+ * thing it audits returns `ok:false` with an explanatory detail, because "I
+ * couldn't verify the secret's mode" is itself a posture failure for an
+ * enterprise conformance artifact. (Contrast the runtime daemon, which fails
+ * open so a sensor glitch never bricks the agent.) The one exception is the
+ * suppression layer, which fails *safe*: a malformed suppressions file is
+ * ignored, never trusted to silence a finding.
+ *
+ * The attestation is a sha256 over the agent's policy/archetype identity plus
+ * the audit result, so the org server can aggregate a per-agent conformance
+ * artifact and detect drift: the hash is stable for an unchanged posture and
+ * changes the instant the policy (or any check outcome) changes.
+ *
+ * @module lib/security/audit-engine
+ */
+
+"use strict";
+
+import * as nodeFs from "node:fs";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+
+// Severity ordering — used to decide which unsuppressed failures fail the run
+// and to sort the summary. `info` never fails a run on its own.
+export const SEVERITIES = Object.freeze(["info", "low", "medium", "high", "critical"]);
+const SEVERITY_RANK = Object.freeze(
+  SEVERITIES.reduce((m, s, i) => ((m[s] = i), m), Object.create(null))
+);
+
+// ---------------------------------------------------------------------------
+// fs adapter — a minimal, injectable surface so tests pass a fake disk.
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the dependency bundle a check sees. Tests pass `{ fs, env }` overrides;
+ * production uses node:fs and process.env. The adapter normalises the handful
+ * of fs calls the checks make so a fake only has to implement those.
+ *
+ * @param {{ fs?: object, env?: object }} [deps]
+ */
+function resolveDeps(deps = {}) {
+  const fs = deps.fs || nodeFs;
+  const env = deps.env || process.env;
+  return { fs, env };
+}
+
+/** statSync that never throws — returns null when the path is absent/unreadable. */
+function safeStat(fs, p) {
+  try { return fs.statSync(p); } catch { return null; }
+}
+/** lstatSync that never throws (used to detect symlinks without following them). */
+function safeLstat(fs, p) {
+  try { return fs.lstatSync(p); } catch { return null; }
+}
+/** readFileSync(utf8) that never throws — returns null when absent/unreadable. */
+function safeRead(fs, p) {
+  try { return fs.readFileSync(p, "utf-8"); } catch { return null; }
+}
+function exists(fs, p) {
+  try { return fs.existsSync(p); } catch { return false; }
+}
+
+/**
+ * Walk a directory tree (lstat-based, never follows symlinks) yielding entries
+ * `{ rel, full, isSymlink, isFile, isDir }`. Bounded and exception-safe so a
+ * single unreadable subtree can't abort the audit.
+ */
+function* walk(fs, root, base = root) {
+  let names;
+  try { names = fs.readdirSync(root); } catch { return; }
+  for (const name of names) {
+    const full = join(root, name);
+    const lst = safeLstat(fs, full);
+    if (!lst) continue;
+    const rel = full.slice(base.length + 1);
+    if (lst.isSymbolicLink()) { yield { rel, full, isSymlink: true, isFile: false, isDir: false }; continue; }
+    if (lst.isDirectory()) {
+      // Don't descend into node_modules / .git — they're never agent posture.
+      if (name === "node_modules" || name === ".git") continue;
+      yield { rel, full, isSymlink: false, isFile: false, isDir: true };
+      yield* walk(fs, full, base);
+    } else if (lst.isFile()) {
+      yield { rel, full, isSymlink: false, isFile: true, isDir: false };
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Checks registry — each entry is self-contained. `run` returns
+// `{ ok, detail, fix?, fixable?, applyFix? }`:
+//   ok       — boolean posture verdict
+//   detail   — one human line for the summary (and the attestation body)
+//   fix      — the exact command/edit an operator should run (shown on fail)
+//   fixable  — true if `maestro audit --fix` can safely auto-remediate
+//   applyFix(agentRoot, deps) — performs the safe fix; returns true on success
+// ---------------------------------------------------------------------------
+
+const MODE_MASK = 0o777;
+
+/** Files whose plaintext contents are credentials — must be owner-only (0600). */
+const SECRET_FILES = [".env", "config/agent.env"];
+
+export const CHECKS = [
+  {
+    id: "env-mode-600",
+    severity: "high",
+    title: "Secret files are owner-only (mode 600)",
+    run(agentRoot, deps) {
+      const { fs } = resolveDeps(deps);
+      const offenders = [];
+      let checkedAny = false;
+      for (const rel of SECRET_FILES) {
+        const p = join(agentRoot, rel);
+        const st = safeStat(fs, p);
+        if (!st) continue; // file absent — not this check's concern
+        checkedAny = true;
+        const mode = st.mode & MODE_MASK;
+        // Owner-only: group + other bits must be clear (<= 0600 in practice).
+        if (mode & 0o077) offenders.push({ rel, mode });
+      }
+      if (!checkedAny) {
+        return { ok: true, detail: "no secret files present to check" };
+      }
+      if (offenders.length === 0) {
+        return { ok: true, detail: "all secret files are mode 600 (owner-only)" };
+      }
+      const list = offenders.map((o) => `${o.rel} (mode ${(o.mode).toString(8).padStart(3, "0")})`).join(", ");
+      return {
+        ok: false,
+        detail: `group/world-readable secret file(s): ${list}`,
+        fix: `chmod 600 ${offenders.map((o) => o.rel).join(" ")}`,
+        fixable: true,
+        applyFix(root, d) {
+          const { fs } = resolveDeps(d);
+          let allOk = true;
+          for (const o of offenders) {
+            try { fs.chmodSync(join(root, o.rel), 0o600); } catch { allOk = false; }
+          }
+          return allOk;
+        },
+      };
+    },
+  },
+
+  {
+    id: "no-world-readable-secrets",
+    severity: "high",
+    title: "No world-readable files under state/ contain credential-shaped values",
+    run(agentRoot, deps) {
+      const { fs } = resolveDeps(deps);
+      const stateDir = join(agentRoot, "state");
+      if (!exists(fs, stateDir)) return { ok: true, detail: "no state/ directory" };
+      // We flag files that are (a) group/world-readable AND (b) look like they
+      // carry secrets by name. We do NOT read+grep arbitrary state for tokens —
+      // that would itself be a data-exposure risk in the audit. Name-based is
+      // the confirmed posture signal (allowlist.yaml pairing codes, *.env, keys).
+      const SECRET_NAME = /(\.env$|secret|token|credential|\.key$|\.pem$|auth\.json$)/i;
+      const offenders = [];
+      for (const e of walk(fs, stateDir)) {
+        if (!e.isFile) continue;
+        if (!SECRET_NAME.test(e.rel)) continue;
+        const st = safeStat(fs, e.full);
+        if (!st) continue;
+        if ((st.mode & MODE_MASK) & 0o044) offenders.push(`state/${e.rel}`); // group/other READ bit
+      }
+      if (offenders.length === 0) {
+        return { ok: true, detail: "no world/group-readable secret-shaped files under state/" };
+      }
+      return {
+        ok: false,
+        detail: `group/world-readable secret-shaped file(s): ${offenders.slice(0, 8).join(", ")}${offenders.length > 8 ? ` (+${offenders.length - 8})` : ""}`,
+        fix: `chmod go-rwx ${offenders.join(" ")}`,
+        fixable: true,
+        applyFix(root, d) {
+          const { fs } = resolveDeps(d);
+          let allOk = true;
+          for (const rel of offenders) {
+            try {
+              const p = join(root, rel);
+              const st = safeStat(fs, p);
+              if (st) fs.chmodSync(p, st.mode & ~0o077 & MODE_MASK);
+            } catch { allOk = false; }
+          }
+          return allOk;
+        },
+      };
+    },
+  },
+
+  {
+    id: "scoped-permissions-configured",
+    severity: "critical",
+    title: "Reactive inbound sessions run with scoped permissions",
+    run(agentRoot, deps) {
+      const { fs, env } = resolveDeps(deps);
+      // Scoped permissions are configured if EITHER the env opt-in is set OR the
+      // recovery/security config records it. The confirmed gap (G3) is that the
+      // default is unscoped; this check passes only when the opt-in is present.
+      if (String(env.MAESTRO_SCOPED_PERMISSIONS || "") === "1") {
+        return { ok: true, detail: "MAESTRO_SCOPED_PERMISSIONS=1 (scoped inbound sessions)" };
+      }
+      const envBody = safeRead(fs, join(agentRoot, ".env")) || "";
+      if (/^MAESTRO_SCOPED_PERMISSIONS=1\s*$/m.test(envBody)) {
+        return { ok: true, detail: "MAESTRO_SCOPED_PERMISSIONS=1 set in .env" };
+      }
+      return {
+        ok: false,
+        detail: "scoped permissions not enabled — inbound sessions run with full tool access (G3)",
+        fix: "set MAESTRO_SCOPED_PERMISSIONS=1 in .env (opt into least-privilege inbound sessions)",
+        // Not auto-fixable: flipping permission posture is an operator decision,
+        // and a blind --fix that edits .env could surprise the operator.
+        fixable: false,
+      };
+    },
+  },
+
+  {
+    id: "send-gate-present",
+    severity: "high",
+    title: "Outbound send-gate hook is wired",
+    run(agentRoot, deps) {
+      const { fs } = resolveDeps(deps);
+      const settings = safeRead(fs, join(agentRoot, ".claude/settings.json"));
+      if (!settings) {
+        return {
+          ok: false,
+          detail: ".claude/settings.json missing — no PreToolUse send-gate",
+          fix: "run `maestro upgrade` to install .claude/settings.json with the send-gate hooks",
+          fixable: false,
+        };
+      }
+      let cfg;
+      try { cfg = JSON.parse(settings); } catch {
+        return { ok: false, detail: ".claude/settings.json is not valid JSON", fix: "repair .claude/settings.json (run `maestro upgrade`)", fixable: false };
+      }
+      const preHooks = JSON.stringify((cfg.hooks && cfg.hooks.PreToolUse) || []);
+      const hasSlackGate = preHooks.includes("block-mcp-slack-send.sh");
+      const hasSendAudit = preHooks.includes("pre-send-audit.sh");
+      if (hasSlackGate && hasSendAudit) {
+        return { ok: true, detail: "PreToolUse send-gate wired (slack block + pre-send audit)" };
+      }
+      const missing = [];
+      if (!hasSlackGate) missing.push("block-mcp-slack-send.sh");
+      if (!hasSendAudit) missing.push("pre-send-audit.sh");
+      return {
+        ok: false,
+        detail: `PreToolUse send-gate incomplete — missing ${missing.join(", ")}`,
+        fix: "run `maestro upgrade` to restore the send-gate PreToolUse hooks",
+        fixable: false,
+      };
+    },
+  },
+
+  {
+    id: "no-tracked-pyc-or-symlinks",
+    severity: "medium",
+    title: "No tracked .pyc files or symlinks in framework paths",
+    run(agentRoot, deps) {
+      const { fs } = resolveDeps(deps);
+      // The confirmed leak (G4) shipped a compiled cross-tenant .pyc and a
+      // broken symlink in the npm tarball. Scan the framework source roots.
+      const roots = ["scripts", "lib", "config", "policies"];
+      const pyc = [];
+      const links = [];
+      for (const r of roots) {
+        const dir = join(agentRoot, r);
+        if (!exists(fs, dir)) continue;
+        for (const e of walk(fs, dir)) {
+          if (e.isSymlink) links.push(`${r}/${e.rel}`);
+          else if (e.isFile && /\.pyc$/.test(e.rel)) pyc.push(`${r}/${e.rel}`);
+          else if (e.isDir && /(^|\/)__pycache__$/.test(e.rel)) pyc.push(`${r}/${e.rel}/`);
+        }
+      }
+      const offenders = [...pyc, ...links];
+      if (offenders.length === 0) {
+        return { ok: true, detail: "no tracked .pyc/__pycache__ or symlinks in framework paths" };
+      }
+      return {
+        ok: false,
+        detail: `found ${pyc.length} .pyc/__pycache__ and ${links.length} symlink(s): ${offenders.slice(0, 6).join(", ")}${offenders.length > 6 ? ` (+${offenders.length - 6})` : ""}`,
+        fix: `remove build artifacts: ${pyc.length ? "find scripts lib -name '*.pyc' -delete; find scripts lib -name __pycache__ -type d -prune -exec rm -rf {} +" : ""}${links.length ? " ; remove the listed symlink(s)" : ""}`,
+        // Only the .pyc/__pycache__ half is safe to auto-remove; symlinks may be
+        // intentional, so we only auto-fix when there are no symlink offenders.
+        fixable: links.length === 0 && pyc.length > 0,
+        applyFix(root, d) {
+          const { fs } = resolveDeps(d);
+          let allOk = true;
+          for (const rel of pyc) {
+            const p = join(root, rel);
+            try { fs.rmSync(p, { recursive: true, force: true }); }
+            catch { allOk = false; }
+          }
+          return allOk;
+        },
+      };
+    },
+  },
+
+  {
+    id: "backup-configured",
+    severity: "medium",
+    title: "Off-machine backup is configured and enabled",
+    run(agentRoot, deps) {
+      const { fs } = resolveDeps(deps);
+      const cfg = safeRead(fs, join(agentRoot, ".maestro/backup-config.yaml"));
+      if (!cfg) {
+        return {
+          ok: false,
+          detail: "no .maestro/backup-config.yaml — a dead Mac mini loses all audit/cost history (G6/G16)",
+          fix: "configure off-machine backup (scripts/maintenance/backup-to-cloud.sh) and set enabled: true",
+          fixable: false,
+        };
+      }
+      if (!/enabled:\s*true/.test(cfg)) {
+        return {
+          ok: false,
+          detail: "backup config present but enabled: false",
+          fix: "set enabled: true in .maestro/backup-config.yaml and schedule the backup job",
+          fixable: false,
+        };
+      }
+      return { ok: true, detail: "off-machine backup configured (enabled: true)" };
+    },
+  },
+
+  {
+    id: "disclosure-policy-present",
+    severity: "high",
+    title: "AI-disclosure policy is present and enabled",
+    run(agentRoot, deps) {
+      const { fs } = resolveDeps(deps);
+      // EU AI Act Art. 50 (G10): the agent must not deny being an AI. The
+      // shipped control lives in config/validation-rules.yaml (ai_disclosure)
+      // and the disclosure_boundaries.py gate. Verify the policy exists & is on.
+      const rules = safeRead(fs, join(agentRoot, "config/validation-rules.yaml"));
+      if (!rules) {
+        return {
+          ok: false,
+          detail: "config/validation-rules.yaml missing — no AI-disclosure gate",
+          fix: "run `maestro upgrade` to install config/validation-rules.yaml",
+          fixable: false,
+        };
+      }
+      // The ai_disclosure block must exist and not be disabled.
+      const block = rules.match(/ai_disclosure:[\s\S]*?(?=\n\w|\n*$)/);
+      if (!block) {
+        return {
+          ok: false,
+          detail: "validation-rules.yaml has no ai_disclosure block",
+          fix: "add an ai_disclosure block (enabled: true, severity: block) to config/validation-rules.yaml",
+          fixable: false,
+        };
+      }
+      if (/enabled:\s*false/.test(block[0])) {
+        return {
+          ok: false,
+          detail: "ai_disclosure policy is enabled: false — agent may deny being an AI (Art. 50 risk)",
+          fix: "set ai_disclosure.enabled: true in config/validation-rules.yaml",
+          fixable: false,
+        };
+      }
+      return { ok: true, detail: "AI-disclosure policy present and enabled" };
+    },
+  },
+
+  {
+    id: "daemon-hooks-wired",
+    severity: "medium",
+    title: "Daemon audit/lifecycle hooks are wired",
+    run(agentRoot, deps) {
+      const { fs } = resolveDeps(deps);
+      const settings = safeRead(fs, join(agentRoot, ".claude/settings.json"));
+      if (!settings) {
+        return { ok: false, detail: ".claude/settings.json missing — no PostToolUse/Stop audit hooks", fix: "run `maestro upgrade`", fixable: false };
+      }
+      let cfg;
+      try { cfg = JSON.parse(settings); } catch {
+        return { ok: false, detail: ".claude/settings.json is not valid JSON", fix: "repair .claude/settings.json", fixable: false };
+      }
+      const hooks = cfg.hooks || {};
+      const post = JSON.stringify(hooks.PostToolUse || []);
+      const stop = JSON.stringify(hooks.Stop || []);
+      const missing = [];
+      if (!post.includes("post-action-log.sh")) missing.push("PostToolUse: post-action-log.sh");
+      if (!stop.includes("session-end-log.sh")) missing.push("Stop: session-end-log.sh");
+      // The referenced scripts must exist on disk, not just be named.
+      for (const s of ["post-action-log.sh", "session-end-log.sh"]) {
+        if (!exists(fs, join(agentRoot, "scripts/hooks", s))) missing.push(`scripts/hooks/${s} missing`);
+      }
+      if (missing.length === 0) {
+        return { ok: true, detail: "daemon audit hooks wired (PostToolUse + Stop) and present on disk" };
+      }
+      return {
+        ok: false,
+        detail: `audit hooks incomplete — ${missing.join("; ")}`,
+        fix: "run `maestro upgrade` to restore the daemon audit hooks",
+        fixable: false,
+      };
+    },
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Suppressions — config/audit-suppressions.yaml: a list of
+//   { id, reason, until }
+// A suppression silences exactly one check id, REQUIRES a non-empty reason, and
+// (if `until` is present) is honoured only before that date. Fails safe: any
+// malformed entry is dropped, never trusted. We parse with js-yaml when
+// available and fall back to a tiny line parser so the engine has no hard dep
+// at import time (matches lib/setup/completeness.mjs).
+// ---------------------------------------------------------------------------
+
+const SUPPRESSIONS_REL = "config/audit-suppressions.yaml";
+
+async function getYaml() {
+  try {
+    const m = await import("js-yaml");
+    return m && m.default ? m.default : m;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Load + validate suppressions. Returns a Map<id, {reason, until}> of ACTIVE
+ * (non-expired, well-formed, reasoned) suppressions. `now` is injectable for
+ * deterministic expiry tests.
+ *
+ * @param {string} agentRoot
+ * @param {{ fs?: object, now?: number, suppressions?: Array }} [deps]
+ */
+export async function loadSuppressions(agentRoot, deps = {}) {
+  const { fs } = resolveDeps(deps);
+  const now = typeof deps.now === "number" ? deps.now : Date.now();
+  let raw = deps.suppressions;
+  if (!Array.isArray(raw)) {
+    const body = safeRead(fs, join(agentRoot, SUPPRESSIONS_REL));
+    if (!body) return new Map();
+    const yaml = await getYaml();
+    if (yaml) {
+      try {
+        const doc = yaml.load(body);
+        raw = Array.isArray(doc) ? doc : (doc && Array.isArray(doc.suppressions) ? doc.suppressions : []);
+      } catch { raw = []; }
+    } else {
+      raw = parseSuppressionsFallback(body);
+    }
+  }
+  const active = new Map();
+  for (const entry of raw) {
+    if (!entry || typeof entry !== "object") continue;
+    const id = typeof entry.id === "string" ? entry.id.trim() : "";
+    const reason = typeof entry.reason === "string" ? entry.reason.trim() : "";
+    if (!id || !reason) continue; // a suppression with no reason is not honoured
+    if (entry.until != null) {
+      const ts = Date.parse(String(entry.until));
+      if (Number.isFinite(ts) && ts < now) continue; // expired
+    }
+    active.set(id, { reason, until: entry.until != null ? String(entry.until) : null });
+  }
+  return active;
+}
+
+/** Minimal YAML-list-of-maps parser for the no-js-yaml fallback. */
+function parseSuppressionsFallback(body) {
+  const out = [];
+  let cur = null;
+  for (const line of body.split(/\r?\n/)) {
+    if (/^\s*#/.test(line) || line.trim() === "") continue;
+    const item = line.match(/^\s*-\s*(.*)$/);
+    if (item) {
+      if (cur) out.push(cur);
+      cur = {};
+      const inline = item[1].match(/^(\w+):\s*(.*)$/);
+      if (inline) cur[inline[1]] = unquote(inline[2]);
+      continue;
+    }
+    const kv = line.match(/^\s+(\w+):\s*(.*)$/);
+    if (kv && cur) cur[kv[1]] = unquote(kv[2]);
+  }
+  if (cur) out.push(cur);
+  return out;
+}
+function unquote(s) {
+  const t = s.trim();
+  if ((t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'"))) {
+    return t.slice(1, -1);
+  }
+  return t;
+}
+
+// ---------------------------------------------------------------------------
+// Runner
+// ---------------------------------------------------------------------------
+
+/**
+ * Run every check against `agentRoot`. A failed check fails the run UNLESS it
+ * carries an active, reasoned suppression — in which case it's reported under
+ * `suppressed` and does not affect `ok`. `info`-severity failures never flip
+ * `ok` on their own (they're advisory).
+ *
+ * @param {string} agentRoot
+ * @param {{ fs?: object, env?: object, now?: number, suppressions?: Array, checks?: Array }} [opts]
+ * @returns {Promise<{ ok, results, suppressed, summary }>}
+ */
+export async function runAudit(agentRoot, opts = {}) {
+  const checks = opts.checks || CHECKS;
+  const deps = { fs: opts.fs, env: opts.env };
+  const suppressionMap = await loadSuppressions(agentRoot, { fs: opts.fs, now: opts.now, suppressions: opts.suppressions });
+
+  const results = [];
+  const suppressed = [];
+  for (const check of checks) {
+    let outcome;
+    try {
+      outcome = check.run(agentRoot, deps);
+    } catch (err) {
+      // A check that throws is a posture failure, not a crash — record it.
+      outcome = { ok: false, detail: `check errored: ${err && err.message ? err.message : String(err)}` };
+    }
+    const sup = suppressionMap.get(check.id);
+    const row = {
+      id: check.id,
+      severity: check.severity,
+      title: check.title,
+      ok: !!outcome.ok,
+      detail: outcome.detail || "",
+      fix: outcome.ok ? undefined : outcome.fix,
+      fixable: outcome.ok ? false : !!outcome.fixable,
+    };
+    if (!row.ok && sup) {
+      row.suppressed = true;
+      row.suppressionReason = sup.reason;
+      if (sup.until) row.suppressionUntil = sup.until;
+      suppressed.push(row);
+    }
+    results.push(row);
+  }
+
+  // A run is OK iff every NON-suppressed, non-info failure is absent.
+  const ok = results.every((r) => r.ok || r.suppressed || r.severity === "info");
+
+  const summary = summarise(results);
+  return { ok, results, suppressed, summary };
+}
+
+/** Aggregate counts for the CLI/org-server consumer. */
+function summarise(results) {
+  const counts = { total: results.length, passed: 0, failed: 0, suppressed: 0 };
+  const bySeverity = Object.create(null);
+  for (const r of results) {
+    if (r.ok) counts.passed++;
+    else if (r.suppressed) counts.suppressed++;
+    else counts.failed++;
+    if (!r.ok && !r.suppressed) bySeverity[r.severity] = (bySeverity[r.severity] || 0) + 1;
+  }
+  // Highest unsuppressed failing severity, for a single at-a-glance signal.
+  let worst = null;
+  for (const r of results) {
+    if (r.ok || r.suppressed || r.severity === "info") continue;
+    if (worst == null || SEVERITY_RANK[r.severity] > SEVERITY_RANK[worst]) worst = r.severity;
+  }
+  return { ...counts, bySeverity, worstSeverity: worst };
+}
+
+/**
+ * Apply the safe fixes for every fixable, currently-failing, non-suppressed
+ * check, then return a re-run. Only checks that declare `applyFix` and are
+ * marked `fixable` are touched; everything else is left for the operator.
+ *
+ * @returns {Promise<{ fixed: string[], audit: object }>}
+ */
+export async function applyFixes(agentRoot, opts = {}) {
+  const deps = { fs: opts.fs, env: opts.env };
+  const fixed = [];
+  for (const check of (opts.checks || CHECKS)) {
+    let outcome;
+    try { outcome = check.run(agentRoot, deps); } catch { continue; }
+    if (outcome.ok || !outcome.fixable || typeof outcome.applyFix !== "function") continue;
+    try {
+      if (outcome.applyFix(agentRoot, deps)) fixed.push(check.id);
+    } catch { /* a fix that throws is just not applied */ }
+  }
+  const audit = await runAudit(agentRoot, opts);
+  return { fixed, audit };
+}
+
+// ---------------------------------------------------------------------------
+// Attestation — hash-locked per-agent conformance artifact.
+// ---------------------------------------------------------------------------
+
+/**
+ * Read the agent's policy/archetype identity that the attestation binds to.
+ * Pulls the function/altitude (archetype) and a digest of the governing
+ * policies from disk. Pure over injected fs; missing fields degrade to "" so
+ * the hash is still well-defined (and changes when they appear).
+ */
+function readPolicyIdentity(agentRoot, deps) {
+  const { fs } = resolveDeps(deps);
+  const identity = { function: "", altitude: "", policyDigest: "" };
+  const agentJson = safeRead(fs, join(agentRoot, "config/agent.json"));
+  if (agentJson) {
+    try {
+      const a = JSON.parse(agentJson);
+      identity.function = String(a.function || "");
+      identity.altitude = String(a.altitude || "");
+    } catch { /* leave blank — blank is a stable, hashable state */ }
+  }
+  // Policy files that define the agent's governance posture. Their combined
+  // content digest is part of the attestation: change a policy → change the hash.
+  const POLICY_FILES = [
+    "policies/action-classification.yaml",
+    "policies/information-barriers.yaml",
+    "policies/prompt-injection-defence.yaml",
+    "config/validation-rules.yaml",
+  ];
+  const h = createHash("sha256");
+  for (const rel of POLICY_FILES) {
+    const body = safeRead(fs, join(agentRoot, rel));
+    h.update(rel + "\0" + (body == null ? "" : body) + "\0");
+  }
+  identity.policyDigest = h.digest("hex");
+  return identity;
+}
+
+/**
+ * Produce a deterministic, hash-locked attestation over the policy/archetype
+ * identity + the audit result. The org server aggregates these into a per-agent
+ * conformance artifact and flags drift when the hash changes.
+ *
+ * The hash covers a canonical projection of the result (id → ok/severity/
+ * suppressed) plus the policy identity — NOT the human-readable `detail` lines,
+ * so cosmetic wording changes don't churn the hash, but any posture or policy
+ * change does. `generatedAt` is carried for humans but excluded from the hash
+ * so the same posture re-attested tomorrow yields the same lock.
+ *
+ * @param {object} audit  result from runAudit
+ * @param {string} agentRoot
+ * @param {{ fs?: object, now?: number, agentId?: string }} [deps]
+ * @returns {{ schema, agentId, identity, posture, ok, hash, generatedAt }}
+ */
+export function buildAttestation(audit, agentRoot, deps = {}) {
+  const identity = readPolicyIdentity(agentRoot, deps);
+  // Canonical posture projection — sorted by id, stable field order.
+  const posture = audit.results
+    .map((r) => ({ id: r.id, severity: r.severity, ok: r.ok, suppressed: !!r.suppressed }))
+    .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+
+  const canonical = JSON.stringify({
+    schema: "maestro.audit.attestation.v1",
+    identity,
+    ok: !!audit.ok,
+    posture,
+  });
+  const hash = createHash("sha256").update(canonical).digest("hex");
+
+  const now = typeof deps.now === "number" ? deps.now : Date.now();
+  return {
+    schema: "maestro.audit.attestation.v1",
+    agentId: deps.agentId || identity.function || "",
+    identity,
+    posture,
+    ok: !!audit.ok,
+    hash,
+    generatedAt: new Date(now).toISOString(),
+  };
+}