@cirvix_ai/agent-control 0.1.2 → 0.1.5

package/src/core/journal.mjs

@@ -198,23 +198,55 @@ function clock(ts) {
   return m ? m[1] : s.slice(0, 8).padEnd(8);
 }
 
-/** One record, one line. The shape `cirvix logs` prints. */
+/** One record, compact or expanded per risk/decision (spec: ALLOW compact, DENY expanded). */
 export function renderLine(record) {
   if (record.malformed) {
     return `  ${dim(String(record.line).padStart(4))}  ${red("malformed record")} ${dim(record.raw.slice(0, 60))}`;
   }
   const decision = record.decision ?? toDecision(record.verdict);
   const tone = toneFor(record);
-  const risk = RISK_TONE[record.risk] ?? dim;
+  const riskTone = RISK_TONE[record.risk] ?? dim;
+  const isCritical = String(record.risk ?? "").toLowerCase() === "critical" || String(record.risk ?? "").toLowerCase() === "high";
+  const isDenied = decision === DECISION.DENY;
+  const isHeld = decision === DECISION.REQUIRE_APPROVAL;
+  const clockStr = dim(clock(record.ts ?? record.timestamp));
+  const icon = decision === DECISION.ALLOW ? "✓" : decision === DECISION.SANITIZE ? "◈" : isDenied ? "✕" : isHeld ? "⏸" : "·";
+  const label = String(decision).toUpperCase().replace(/_/g, " ");
+  const tool = String(record.tool ?? record.action ?? "—");
+  const resource = truncate(record.resource ?? record.command ?? "", 44);
+  const policy = String(record.policy ?? record.rule ?? "default-deny");
+  const latency = `${record.latency_ms ?? "—"}ms`;
+
+  // Expanded for DENY/CRITICAL/HOLD/HIGH — high visibility, spec layout:
+  // 22:38:53  ◇ SANITIZE  HIGH      network.request
+  //            https://docs.example.com/deploy
+  //            Policy: sanitize-fetched-content       16.82ms
+  if (isDenied || isHeld || isCritical) {
+    const iconLabel = isHeld ? "APPROVAL" : label; // REQUIRE_APPROVAL displays as APPROVAL per spec
+    const iconChar = isHeld ? "●" : icon;
+    const lines = [];
+    // First line: time + icon/verdict + risk + tool — columns aligned, decision strongest
+    lines.push(
+      `  ${clockStr}  ${tone(`${iconChar} ${iconLabel.padEnd(12)}`)} ${riskTone(String(record.risk ?? "—").toUpperCase().padEnd(9))} ${tool.padEnd(20)} ${dim(latency)}`,
+    );
+    if (resource) lines.push(`           ${dim(resource)}`);
+    // Policy line — indented, secondary
+    lines.push(`           ${dim(`Policy: ${policy}`)}`);
+    if (isHeld) {
+      lines.push(`           ${amber("→ AWAITING APPROVAL")}`);
+    }
+    return lines.join("\n");
+  }
 
+  // Compact for ordinary ALLOW.
   return [
-    `  ${dim(clock(record.ts ?? record.timestamp))}`,
-    tone(String(decision).toUpperCase().padEnd(16)),
-    risk(String(record.risk ?? "—").toUpperCase().padEnd(8)),
-    String(record.tool ?? record.action ?? "—").padEnd(20),
-    dim(truncate(record.resource ?? record.command ?? "", 44).padEnd(44)),
-    dim(String(record.policy ?? record.rule ?? "default-deny").padEnd(24)),
-    dim(`${record.latency_ms ?? "—"}ms`),
+    `  ${clockStr}`,
+    tone(`${icon} ${label.padEnd(12)}`),
+    riskTone(String(record.risk ?? "—").toUpperCase().padEnd(8)),
+    tool.padEnd(20),
+    dim(resource.padEnd(44)),
+    dim(latency.padEnd(8)),
+    dim(policy),
   ].join(" ");
 }
 
@@ -237,44 +269,103 @@ export function renderLine(record) {
 export function renderTree(record, { indent = "  " } = {}) {
   const decision = record.decision ?? toDecision(record.verdict);
   const tone = toneFor(record);
-  const risk = RISK_TONE[record.risk] ?? dim;
-
-  const rows = [
-    ["input", truncate(record.resource || record.command || "(no resource)", 70)],
-    ["risk", risk(String(record.risk ?? "unknown").toUpperCase()) + (record.risk_signals?.length ? dim(`  ${record.risk_signals.join(", ")}`) : "")],
-    ["policy", record.policy ?? record.rule ?? dim("— no rule matched (default deny)")],
-    ["decision", tone(String(decision).toUpperCase()) + (record.enforced === false ? dim("  (not enforced — audit mode)") : "")],
-    ["latency", `${record.latency_ms ?? "—"}ms`],
-  ];
-
-  if (record.would_have) {
-    rows.push(["would have", red(String(record.would_have.decision).toUpperCase()) + dim(` by ${record.would_have.rule ?? "default-deny"}`)]);
+  const riskTone = RISK_TONE[record.risk] ?? dim;
+  const isDeny = decision === DECISION.DENY;
+  const isHold = decision === DECISION.REQUIRE_APPROVAL;
+  const isSanitize = decision === DECISION.SANITIZE;
+
+  // Header — spec: CIRVIX DECISION ANALYSIS
+  const lines = [];
+  lines.push(`${indent}${bold("CIRVIX DECISION ANALYSIS")}`);
+  lines.push("");
+
+  // Top: Decision + Risk — strongest visual
+  const decisionLabel = isDeny ? "✕ BLOCKED" : isHold ? "● AWAITING APPROVAL" : isSanitize ? "◇ SANITIZED" : "✓ " + String(decision).toUpperCase();
+  const decisionTone = isDeny ? red : isHold ? amber : isSanitize ? blue : green;
+  lines.push(`${indent}${dim("Decision".padEnd(12))} ${decisionTone(bold(decisionLabel))}${record.enforced === false ? dim("  (not enforced — audit mode)") : ""}`);
+  lines.push(`${indent}${dim("Risk".padEnd(12))} ${riskTone(bold(String(record.risk ?? "unknown").toUpperCase()))}${record.risk_signals?.length ? dim(`  ${record.risk_signals.join(", ")}`) : ""}`);
+  lines.push("");
+
+  // Tool / Target / Policy / Latency / Request
+  lines.push(`${indent}${dim("Tool".padEnd(12))} ${bold(String(record.tool ?? record.action ?? "—"))}`);
+  if (record.resource || record.command) {
+    lines.push(`${indent}${dim("Target".padEnd(12))} ${truncate(record.resource || record.command || "", 70)}`);
   }
-  if (record.approval_id) rows.push(["approval", blue(record.approval_id)]);
-  if (record.secrets_brokered?.length) rows.push(["secrets", `${record.secrets_brokered.join(", ")} ${dim("(brokered — the agent never held the value)")}`]);
-  if (record.secrets_detected?.length) {
-    rows.push(["detected", record.secrets_detected.map((s) => `${s.detector} ${dim(s.masked)}`).join(", ")]);
+  if (record.destination) {
+    lines.push(`${indent}${dim("Destination".padEnd(12))} ${record.destination}`);
   }
-  if (record.sanitized?.arguments?.length) {
-    rows.push(["sanitized", `${record.sanitized.arguments.length} value(s) stripped from arguments`]);
+  lines.push(`${indent}${dim("Policy".padEnd(12))} ${record.policy ?? record.rule ?? dim("— no rule matched (default deny)")}`);
+  lines.push(`${indent}${dim("Latency".padEnd(12))} ${record.latency_ms ?? "—"}ms`);
+  lines.push(`${indent}${dim("Request".padEnd(12))} ${dim(record.request_id ?? record.decision_id ?? "—")}  ${dim(`agent ${record.agent ?? "—"}`)}`);
+  if (record.approval_id) {
+    lines.push(`${indent}${dim("Approval".padEnd(12))} ${blue(record.approval_id)}`);
   }
-  if (record.observed_by?.length) rows.push(["observed", dim(record.observed_by.join(", "))]);
-  rows.push(["result", decision === DECISION.DENY ? red("not forwarded") : decision === DECISION.REQUIRE_APPROVAL ? amber("held") : green("forwarded")]);
-
-  const width = Math.max(...rows.map(([k]) => k.length));
-  const lines = [
-    `${indent}${bold(record.agent ?? "agent")}  ${dim(record.request_id ?? "")}`,
-    `${indent} └── ${bold(record.tool ?? record.action ?? "tool")}`,
-  ];
-  rows.forEach(([key, value], i) => {
-    const branch = i === rows.length - 1 ? "└──" : "├──";
-    lines.push(`${indent}      ${branch} ${dim(key.padEnd(width))}  ${value}`);
-  });
+  lines.push("");
 
+  // Matched policy + Reason — if present
+  if (record.policy ?? record.rule) {
+    lines.push(`${indent}${dim("Matched policy")}`);
+    lines.push(`${indent}  ${record.policy ?? record.rule}`);
+    lines.push("");
+  }
   if (record.reason) {
+    lines.push(`${indent}${dim("Reason")}`);
+    lines.push(`${indent}  ${wrap(record.reason, 70, `${indent}  `)}`);
+    lines.push("");
+  }
+
+  // Approval panel — for REQUIRE_APPROVAL, spec: HUMAN APPROVAL REQUIRED
+  if (isHold) {
+    const W = 48;
+    const top = `${indent}${dim(`╭─ HUMAN APPROVAL REQUIRED ${"─".repeat(Math.max(0, W - 26))}╮`)}`;
+    const bottom = `${indent}${dim(`╰${"─".repeat(W)}╯`)}`;
+    lines.push(top);
+    lines.push(`${indent}${dim("│")} ${dim("Agent".padEnd(10))} ${record.agent ?? "—"}  ${dim("│")}`);
+    lines.push(`${indent}${dim("│")} ${dim("Action".padEnd(10))} ${record.action ?? record.tool ?? "—"}  ${dim("│")}`);
+    lines.push(`${indent}${dim("│")} ${dim("Target".padEnd(10))} ${truncate(record.resource ?? "", 30)}  ${dim("│")}`);
+    lines.push(`${indent}${dim("│")} ${"".padEnd(42)} ${dim("│")}`);
+    lines.push(`${indent}${dim("│")} ${dim("Risk".padEnd(10))} ${amber(String(record.risk ?? "").toUpperCase())}  ${dim("│")}`);
+    lines.push(`${indent}${dim("│")} ${dim("Policy".padEnd(10))} ${record.policy ?? record.rule ?? "—"}  ${dim("│")}`);
+    lines.push(`${indent}${dim("│")} ${"".padEnd(42)} ${dim("│")}`);
+    lines.push(`${indent}${dim("│")} ${dim("Reason")}  ${dim("│")}`);
+    lines.push(`${indent}${dim("│")} ${wrap(record.reason ?? "Production database mutation requires human authorization.", 42, `${indent}${dim("│")} `)}  ${dim("│")}`);
+    lines.push(`${indent}${dim("│")} ${"".padEnd(42)} ${dim("│")}`);
+    lines.push(`${indent}${dim("│")} ${blue("[A] Approve")}  ${dim("  ")} ${red("[R] Reject")}  ${dim("│")}`);
+    lines.push(bottom);
     lines.push("");
-    lines.push(`${indent}      ${dim(wrap(record.reason, 84, `${indent}      `))}`);
   }
+
+  // Decision path — spec: secret detection → risk classification → policy evaluation → BLOCK
+  lines.push(`${indent}${dim("Decision path")}`);
+  lines.push(`${indent}  ${dim("secret detection")}`);
+  lines.push(`${indent}    ${dim("↓")}`);
+  lines.push(`${indent}  ${dim("risk classification")}`);
+  lines.push(`${indent}    ${dim("↓")}`);
+  lines.push(`${indent}  ${dim("policy evaluation")}`);
+  lines.push(`${indent}    ${dim("↓")}`);
+  lines.push(`${indent}  ${decisionTone(isDeny ? "BLOCK" : isHold ? "HOLD" : isSanitize ? "SANITIZE" : "ALLOW")}`);
+
+  // Low-level details — keep for debugging, muted
+  const extra = [];
+  if (record.secrets_brokered?.length) extra.push(`secrets brokered: ${record.secrets_brokered.join(", ")}`);
+  if (record.secrets_detected?.length) extra.push(`detected: ${record.secrets_detected.map((s) => `${s.detector} ${s.masked}`).join(", ")}`);
+  if (record.sanitized?.arguments?.length) extra.push(`sanitized: ${record.sanitized.arguments.length} value(s) stripped`);
+  if (record.would_have) extra.push(`would have: ${String(record.would_have.decision).toUpperCase()} by ${record.would_have.rule ?? "default-deny"}`);
+  if (extra.length) {
+    lines.push("");
+    lines.push(`${indent}${dim(extra.join("  ·  "))}`);
+  }
+
+  // Considered tree — compact, for dead-rule discovery (keep, muted)
+  if (record.considered?.length) {
+    lines.push("");
+    lines.push(`${indent}${dim("considered")}  ${dim(`${record.considered.filter((c) => c.matched).length} of ${record.considered.length} matched`)}`);
+    for (const c of record.considered.slice(0, 12)) {
+      const marker = c.matched ? bold("→") : dim(" ");
+      lines.push(`${indent}  ${marker} ${dim(String(c.effect).padEnd(11))} ${c.matched ? c.rule : dim(c.rule)}`);
+    }
+  }
+
   return lines.join("\n");
 }
 

package/src/core/kill-switch.mjs

@@ -0,0 +1,122 @@
+/**
+ * Unified Multi-Scope Emergency Kill Switch.
+ *
+ * Provides emergency freezing across scopes:
+ * - single agent
+ * - agent family
+ * - organization
+ * - environment
+ * - MCP server
+ * - credential
+ * - session
+ * - model
+ * - tool
+ */
+
+import { DECISION } from "./decisions.mjs";
+
+export const KILL_SCOPES = {
+  AGENT: "agent",
+  FAMILY: "family",
+  ORG: "org",
+  ENVIRONMENT: "environment",
+  MCP: "mcp",
+  CREDENTIAL: "credential",
+  SESSION: "session",
+  MODEL: "model",
+  TOOL: "tool",
+};
+
+export class KillSwitchEngine {
+  constructor() {
+    this.activeRules = new Map(); // id -> rule
+  }
+
+  /**
+   * Arms a kill switch.
+   */
+  arm({ scope, target, reason = "Emergency freeze activated", triggeredBy = "system" }) {
+    if (!Object.values(KILL_SCOPES).includes(scope)) {
+      throw new Error(`Invalid kill switch scope '${scope}'`);
+    }
+    const id = `ks_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    const rule = {
+      id,
+      scope,
+      target: String(target).toLowerCase(),
+      reason,
+      triggeredBy,
+      armedAt: new Date().toISOString(),
+      active: true,
+    };
+    this.activeRules.set(id, rule);
+    return rule;
+  }
+
+  /**
+   * Disarms a kill switch.
+   */
+  disarm(id) {
+    return this.activeRules.delete(id);
+  }
+
+  /**
+   * Checks whether a request matches any active kill rule.
+   *
+   * @param {Object} context
+   * @returns {{ killed: boolean, decision: string, reason?: string, matchedRule?: Object }}
+   */
+  evaluate({
+    agentId = null,
+    family = null,
+    orgId = null,
+    environment = null,
+    mcp = null,
+    credential = null,
+    session = null,
+    model = null,
+    tool = null,
+  } = {}) {
+    for (const rule of this.activeRules.values()) {
+      if (!rule.active) continue;
+
+      const target = rule.target;
+
+      if (rule.scope === KILL_SCOPES.ORG && orgId && orgId.toLowerCase() === target) {
+        return { killed: true, decision: DECISION.QUARANTINE, reason: `Organization under emergency freeze: ${rule.reason}`, matchedRule: rule };
+      }
+      if (rule.scope === KILL_SCOPES.AGENT && agentId && agentId.toLowerCase() === target) {
+        return { killed: true, decision: DECISION.QUARANTINE, reason: `Agent '${agentId}' is frozen: ${rule.reason}`, matchedRule: rule };
+      }
+      if (rule.scope === KILL_SCOPES.FAMILY && family && family.toLowerCase() === target) {
+        return { killed: true, decision: DECISION.QUARANTINE, reason: `Agent family '${family}' is frozen: ${rule.reason}`, matchedRule: rule };
+      }
+      if (rule.scope === KILL_SCOPES.ENVIRONMENT && environment && environment.toLowerCase() === target) {
+        return { killed: true, decision: DECISION.QUARANTINE, reason: `Environment '${environment}' is frozen: ${rule.reason}`, matchedRule: rule };
+      }
+      if (rule.scope === KILL_SCOPES.MCP && mcp && mcp.toLowerCase() === target) {
+        return { killed: true, decision: DECISION.DENY, reason: `MCP server '${mcp}' is disabled: ${rule.reason}`, matchedRule: rule };
+      }
+      if (rule.scope === KILL_SCOPES.TOOL && tool && tool.toLowerCase() === target) {
+        return { killed: true, decision: DECISION.DENY, reason: `Tool '${tool}' is disabled: ${rule.reason}`, matchedRule: rule };
+      }
+      if (rule.scope === KILL_SCOPES.SESSION && session && session.toLowerCase() === target) {
+        return { killed: true, decision: DECISION.QUARANTINE, reason: `Session '${session}' is terminated: ${rule.reason}`, matchedRule: rule };
+      }
+      if (rule.scope === KILL_SCOPES.MODEL && model && model.toLowerCase() === target) {
+        return { killed: true, decision: DECISION.DENY, reason: `Model '${model}' is suspended: ${rule.reason}`, matchedRule: rule };
+      }
+      if (rule.scope === KILL_SCOPES.CREDENTIAL && credential && credential.toLowerCase() === target) {
+        return { killed: true, decision: DECISION.DENY, reason: `Credential '${credential}' is revoked: ${rule.reason}`, matchedRule: rule };
+      }
+    }
+
+    return { killed: false, decision: DECISION.ALLOW };
+  }
+
+  list() {
+    return Array.from(this.activeRules.values());
+  }
+}
+
+export const globalKillSwitch = new KillSwitchEngine();

package/src/core/notices.mjs

@@ -24,10 +24,18 @@
  * The limit notice fires on the transition into the limit, not on every
  * refused call after it — a process that keeps calling past its quota would
  * otherwise print the same paragraph hundreds of times. The nudge is once per
- * day and `Meter` owns that flag.
+ * day and `Meter` owns that flag. The domain-signal prompt is once per
+ * process, on the first egress-class denial: the story it offers to share is
+ * worth telling once, not every time an agent reaches for a credential file.
  */
 
-import { agentLimitReached, quotaReached, softNudge } from "./prompts.mjs";
+import {
+  agentLimitReached,
+  domainSignal,
+  quotaReached,
+  softNudge,
+  EGRESS_DENY_RULES,
+} from "./prompts.mjs";
 
 /**
  * Builds the per-decision notice hook.
@@ -43,6 +51,7 @@ export function commercialNotices({ licence, meter, write }) {
 
   let saidQuota = false;
   let saidAgents = false;
+  let saidDomain = false;
 
   return function notice(decision) {
     if (!decision) return;
@@ -54,6 +63,17 @@ export function commercialNotices({ licence, meter, write }) {
     // this whole file exists to correct.
     const rule = decision.rule ?? decision.policy;
 
+    if (decision.verdict === "deny" && EGRESS_DENY_RULES.has(rule)) {
+      if (saidDomain) return;
+      saidDomain = true;
+      const text = domainSignal(licence, {
+        rule,
+        destination: decision.destination ?? "",
+      });
+      if (text) write(`\n${text}\n`);
+      return;
+    }
+
     if (rule === "quota-exhausted") {
       if (saidQuota) return;
       saidQuota = true;

package/src/core/packs.mjs

@@ -0,0 +1,193 @@
+/**
+ * Policy packs — installable, forkable, provenanced rule sets.
+ *
+ * The four files in `policies/` were already packs in everything but name: a
+ * curated set of rules with a stated purpose. What they lacked was the
+ * metadata that makes a pack shareable — who wrote it, what version it is,
+ * what it is for, what it was forked from, and whether the rules still match
+ * the hash somebody reviewed.
+ *
+ * WHY THE MANIFEST LIVES IN COMMENTS
+ * ----------------------------------
+ * A pack is a `.policy` file and nothing else. The manifest is carried on
+ * `#@ key: value` lines, which the DSL parser already skips as comments.
+ *
+ * The alternative — a sidecar `.pack.json` — was rejected because it splits a
+ * pack into two files that can drift apart, and the failure mode of that drift
+ * is a manifest describing rules that are no longer there. One file cannot
+ * disagree with itself about what it contains.
+ *
+ * WHAT THE HASH COVERS
+ * --------------------
+ * The rules, not the manifest. Bumping a description or adding an author must
+ * not invalidate a review of the rules, and editing a single `deny` must
+ * invalidate it. Hashing the whole file would get both of those backwards.
+ */
+
+import { createHash } from "node:crypto";
+
+/** Manifest fields a pack may declare. Anything else is ignored, not an error:
+ *  a pack written against a newer Cirvix must still install on an older one. */
+const FIELDS = new Set([
+  "id", "name", "version", "description", "author", "homepage",
+  "risk", "targets", "requires", "forked-from", "forked-at", "official",
+]);
+
+const MANIFEST_LINE = /^#@\s*([a-z-]+)\s*:\s*(.*)$/i;
+
+/**
+ * Split a pack file into its manifest and its rule text.
+ *
+ * The rule text is returned verbatim, including comments that are not manifest
+ * lines, because those comments are the author explaining their reasoning and
+ * dropping them would make an installed pack less useful than the one on disk.
+ */
+export function parsePack(text, { source = null } = {}) {
+  const manifest = {};
+  const ruleLines = [];
+
+  for (const line of String(text ?? "").split(/\r?\n/)) {
+    const m = line.match(MANIFEST_LINE);
+    if (m && FIELDS.has(m[1].toLowerCase())) {
+      const key = m[1].toLowerCase();
+      const value = m[2].trim();
+      if (key === "targets" || key === "requires") {
+        manifest[key] = value.split(/[,\s]+/).filter(Boolean);
+      } else if (key === "official") {
+        manifest[key] = value === "true";
+      } else {
+        manifest[key] = value;
+      }
+      continue;
+    }
+    ruleLines.push(line);
+  }
+
+  const rules = ruleLines.join("\n");
+  return {
+    manifest: {
+      id: manifest.id ?? null,
+      name: manifest.name ?? manifest.id ?? "untitled pack",
+      version: manifest.version ?? "0.0.0",
+      description: manifest.description ?? "",
+      author: manifest.author ?? "unknown",
+      risk: manifest.risk ?? "unspecified",
+      targets: manifest.targets ?? [],
+      requires: manifest.requires ?? [],
+      official: manifest.official ?? false,
+      forkedFrom: manifest["forked-from"] ?? null,
+      forkedAt: manifest["forked-at"] ?? null,
+      homepage: manifest.homepage ?? null,
+      source,
+    },
+    rules,
+    hash: hashRules(rules),
+  };
+}
+
+/** sha256 over the rule text with trailing whitespace normalised, so a pack
+ *  that survives a round trip through an editor still verifies. */
+export function hashRules(rules) {
+  const normalised = String(rules ?? "")
+    .split(/\r?\n/)
+    .map((l) => l.replace(/\s+$/, ""))
+    .join("\n")
+    .replace(/\n+$/, "\n");
+  return "sha256:" + createHash("sha256").update(normalised, "utf8").digest("hex");
+}
+
+/** Does this pack still contain the rules somebody reviewed? */
+export function verifyPack(pack, expectedHash) {
+  const actual = hashRules(pack.rules);
+  return { ok: actual === expectedHash, expected: expectedHash, actual };
+}
+
+/**
+ * Render a pack back to a file.
+ *
+ * Manifest first, then the rules exactly as they were. Round-tripping a pack
+ * through parse → render must not change its hash, which the tests assert.
+ */
+export function renderPack(pack) {
+  const m = pack.manifest;
+  const head = [
+    `#@ id: ${m.id}`,
+    `#@ name: ${m.name}`,
+    `#@ version: ${m.version}`,
+    m.description ? `#@ description: ${m.description}` : null,
+    `#@ author: ${m.author}`,
+    `#@ risk: ${m.risk}`,
+    m.targets?.length ? `#@ targets: ${m.targets.join(", ")}` : null,
+    m.requires?.length ? `#@ requires: ${m.requires.join(", ")}` : null,
+    m.official ? `#@ official: true` : null,
+    m.forkedFrom ? `#@ forked-from: ${m.forkedFrom}` : null,
+    m.forkedAt ? `#@ forked-at: ${m.forkedAt}` : null,
+    m.homepage ? `#@ homepage: ${m.homepage}` : null,
+  ].filter(Boolean);
+  return head.join("\n") + "\n" + pack.rules.replace(/^\n+/, "\n");
+}
+
+/**
+ * Fork a pack under a new identity, keeping provenance.
+ *
+ * The fork records the parent's id AND the parent's rule hash. The id alone
+ * would be a claim; the hash is what lets anyone check which version of the
+ * parent this actually came from, including after the parent has moved on.
+ */
+export function forkPack(pack, { id, name, author = "unknown", now = new Date() } = {}) {
+  if (!id) throw new Error("A fork needs an id.");
+  return {
+    manifest: {
+      ...pack.manifest,
+      id,
+      name: name ?? `${pack.manifest.name} (fork)`,
+      version: "0.1.0",
+      author,
+      official: false,
+      forkedFrom: `${pack.manifest.id ?? "unknown"}@${hashRules(pack.rules)}`,
+      forkedAt: now.toISOString(),
+    },
+    rules: pack.rules,
+    hash: hashRules(pack.rules),
+  };
+}
+
+/**
+ * The difference between two packs, as rule names.
+ *
+ * Reported by name rather than by line, because a pack update that reorders
+ * rules or rewrites a comment is not a change anyone needs to review, and a
+ * line diff would present it as though it were.
+ */
+export function diffPacks(before, after) {
+  const names = (p) => {
+    const out = [];
+    for (const m of String(p?.rules ?? "").matchAll(/^\s*name\s*=\s*(\S+)/gm)) out.push(m[1]);
+    return out;
+  };
+  const a = new Set(names(before));
+  const b = new Set(names(after));
+  return {
+    added: [...b].filter((n) => !a.has(n)),
+    removed: [...a].filter((n) => !b.has(n)),
+    kept: [...a].filter((n) => b.has(n)),
+    changed: hashRules(before?.rules) !== hashRules(after?.rules),
+  };
+}
+
+/**
+ * Sort packs for a listing.
+ *
+ * Official first, then by risk posture descending, then by name. A developer
+ * scanning this list is looking for "the safe default written by the vendor",
+ * and that should not be somewhere in the middle alphabetically.
+ */
+const RISK_WEIGHT = { strict: 3, balanced: 2, permissive: 1, unspecified: 0 };
+export function sortPacks(packs) {
+  return [...packs].sort((x, y) => {
+    if (x.manifest.official !== y.manifest.official) return x.manifest.official ? -1 : 1;
+    const rw = (RISK_WEIGHT[y.manifest.risk] ?? 0) - (RISK_WEIGHT[x.manifest.risk] ?? 0);
+    if (rw) return rw;
+    return String(x.manifest.name).localeCompare(String(y.manifest.name));
+  });
+}