@open-everywhere/core 0.1.0

package/agent/access/permission-proposal.ts

@@ -0,0 +1,362 @@
+// Evidence into proposals, and a proposal is TEXT: the actuator is always a reviewed config PR. Only grant-WIDTH refusals earn a widening — the fences, the taint gate and context walls are controls working — and a tightening proposal annotates rather than suppresses a connector whose every attempt was refused.
+
+import {
+  MIN_TIGHTEN_OBSERVATIONS,
+  MIN_TIGHTEN_WINDOW_DAYS,
+  MIN_WIDEN_REFUSALS,
+  entryCoversCommand,
+  type AwsGrantUsage,
+  type ConnectorGrantUsage,
+  type ConnectorRefusalEvidence,
+  type PermissionEvidence,
+} from "./permission-evidence.js";
+
+/** The config file every proposal in v1 edits — the deployer app's bundle definitions. */
+export const PERMISSION_CONFIG_FILE = "agent/access/bundles.ts";
+
+/** A concrete, reviewable config edit. `before`/`after` are the array the edit rewrites; a whole-grant removal is spelled `after: []` with a `path` that names the grant rather than its `allow`. */
+export interface PermissionDiff {
+  readonly file: string;
+  /** Every loaded bundle that declares this grant. Where several do, naming all of them is the honest answer: the resolver dedupes an ARN across bundles and does not report which binding won. */
+  readonly bundles: readonly string[];
+  readonly path: string;
+  readonly before: readonly string[];
+  readonly after: readonly string[];
+  readonly text: string;
+}
+
+export interface PermissionProposal {
+  /** Stable and deterministic — the same evidence yields the same id, so a routine that posts these
+   *  weekly can be de-duplicated by a human (or by a rule) without a fingerprint scheme. */
+  readonly id: string;
+  readonly direction: "widen" | "tighten";
+  readonly subject: string;
+  readonly summary: string;
+  /** The rows this stands on, as sentences with counts. Never a principal, never an argument value. */
+  readonly evidence: readonly string[];
+  /** Present when a mechanical config edit is derivable. Absent is NOT a weaker proposal — it means
+   *  the actuator is not a config diff, and {@link remedy} names what it is instead. */
+  readonly diff?: PermissionDiff;
+  readonly remedy?: string;
+}
+
+function renderDiffText(path: string, bundles: readonly string[], before: readonly string[], after: readonly string[]): string {
+  const head = `--- ${PERMISSION_CONFIG_FILE}  (bundle ${bundles.map((b) => JSON.stringify(b)).join(" | ")})`;
+  const lines = [head, `@@ ${path} @@`];
+  for (const entry of before) lines.push(`${after.includes(entry) ? " " : "-"}  ${JSON.stringify(entry)},`);
+  for (const entry of after) if (!before.includes(entry)) lines.push(`+  ${JSON.stringify(entry)},`);
+  return lines.join("\n");
+}
+
+function diff(bundles: readonly string[], path: string, before: readonly string[], after: readonly string[]): PermissionDiff {
+  return { file: PERMISSION_CONFIG_FILE, bundles, path, before, after, text: renderDiffText(path, bundles, before, after) };
+}
+
+function awsAllowPath(roleArn: string): string {
+  return `awsRoles[roleArn=${JSON.stringify(roleArn)}].allow`;
+}
+
+function widenProposals(ev: PermissionEvidence): PermissionProposal[] {
+  const out: PermissionProposal[] = [];
+  const awsUsage = new Map<string, AwsGrantUsage>();
+  for (const u of ev.usage) if (u.kind === "aws-role") awsUsage.set(u.roleArn, u);
+
+  for (const r of ev.refusals) {
+    if (r.kind === "aws-allow-list") {
+      if (r.refusals < MIN_WIDEN_REFUSALS) continue;
+      // The current declared width wins over the width the row recorded: a grant widened since those refusals is a proposal already actioned.
+      const declared = awsUsage.get(r.roleArn);
+      const before = declared?.allow ?? r.allow;
+      const bundles = declared?.bundles ?? [];
+      if (before.some((entry) => entryCoversCommand(entry, r.command))) continue;
+      const after = [...before, r.iamEntry];
+      out.push({
+        id: `widen:aws:${r.roleArn}:${r.command}`,
+        direction: "widen",
+        subject: `AWS grant ${r.roleArn} — \`${r.command}\``,
+        summary:
+          `\`${r.command}\` (\`aws ${r.command.replace(":", " ")}\`) was refused ${r.refusals}× by this grant's host-side allow-list ` +
+          `(${r.unattendedRefusals} of them on an unattended run). The allow-list does not cover it; the IAM role behind it may well.`,
+        evidence: [
+          `${r.refusals} \`aws.refused\` row(s) with reason \`allow-list\`, ${r.firstSeen} → ${r.lastSeen}.`,
+          `${r.unattendedRefusals} of those had no human behind the turn.`,
+          `Allow-list at refusal time: ${r.allow.length > 0 ? r.allow.map((a) => `\`${a}\``).join(", ") : "(none recorded)"}.`,
+        ],
+        diff: diff(bundles, awsAllowPath(r.roleArn), before, after),
+        remedy:
+          "Widening the allow-list re-permits only what the IAM role already allows — the screen can never widen past the role. " +
+          "If the role itself lacks the action, the diff will merge and the command will still fail, in AWS, which is the right place for it to fail.",
+      });
+      continue;
+    }
+
+    if (r.kind === "egress-denied") {
+      if (r.denials < MIN_WIDEN_REFUSALS) continue;
+      // One burst is not a pattern: a crash-looping worker can produce a thousand denials to one host inside a single window, so the `windows` count is stated rather than left to be inferred.
+      const burst = r.windows === 1;
+      out.push({
+        id: `widen:egress:${r.host}`,
+        direction: "widen",
+        subject: `Egress to \`${r.host}\``,
+        summary:
+          `${r.denials} request(s) to \`${r.host}\` were refused by the egress firewall across ${r.windows} observation window(s)` +
+          `${burst ? " — all inside ONE window, so this may be a single crash-loop rather than a standing need" : ""}. ` +
+          `The host is not in this scope's compiled allow-list.`,
+        evidence: [
+          `${r.denials} denied request(s) in ${r.windows} \`egress.denied\` row(s), ${r.firstSeen} → ${r.lastSeen}.`,
+          r.fingerprints.length > 1
+            ? `Denied under ${r.fingerprints.length} distinct policy generations — the host stayed unreachable across a config change.`
+            : `Policy generation: ${r.fingerprints[0] !== undefined ? `\`${r.fingerprints[0].slice(0, 12)}…\`` : "(not recorded)"}.`,
+          `Host only: the firewall's log is reduced to a host and a count before it reaches the audit log, so there is no path, method or query string behind this — and no way to tell WHICH request wanted it. The worker's own report is still the place that detail comes from.`,
+        ],
+        // No mechanical diff: a reachable host lives in a bundle's `domains` or a connection's `allowedWebsites`, and which one depends on whether the call needs a secret — a question the evidence cannot answer.
+        remedy:
+          `Not a mechanical diff, so none is offered. A reachable host is config-as-code in one of two places, and which one is the reviewer's call: add \`${r.host}\` to the bundle's \`domains\` if the call needs no credential, or to the relevant connection's \`allowedWebsites\` if the firewall should inject one. ` +
+          `⚠ This evidence family only exists where the proxy is ours (the self-host egress tier, deploy/egress-proxy). On the Vercel tier the sandbox host denies out of band and NO row is written, so an empty egress section there means "not observed", never "nothing was blocked".`,
+      });
+      continue;
+    }
+
+    if (r.kind === "connector-refused") {
+      // Two reason codes, each with its own actuator, so each gets its own proposal and id. The current declaration wins over the rows, which also splits them: an ungranted connector cannot want a standing routine permission.
+      const declared = ev.usage.some((u) => u.kind === "connector" && u.connector === r.connection);
+      const reasonsSeen = r.reasons.map((x) => `${x.label} ×${x.count}`).join(", ");
+      const opsSeen = r.ops.length > 0 ? r.ops.map((x) => `${x.label} ×${x.count}`).join(", ") : "(no op named — the grant gate refuses before one is)";
+      if (r.ungranted >= MIN_WIDEN_REFUSALS && !declared) {
+        out.push({
+          id: `widen:connector:ungranted:${r.connection}`,
+          direction: "widen",
+          subject: `Connector \`${r.connection}\` — not granted to this scope`,
+          summary:
+            `${r.ungranted} operation(s) on \`${r.connection}\` were refused by the credential gate: the connection is not in this ` +
+            `scope's granted set, and no bundle EFFECTIVE IN THIS SCOPE declares it. The work keeps arriving; the grant does not exist.`,
+          evidence: [
+            `${r.refusals} \`connector.refused\` row(s) for \`${r.connection}\`, ${r.firstSeen} → ${r.lastSeen}; ${r.ungranted} with reason \`ungranted\`.`,
+            `Reasons: ${reasonsSeen}.`,
+            `Ops: ${opsSeen}.`,
+          ],
+          // No mechanical diff: an ungranted connector is absent from every bundle this report can see, and the declaration needs a credential id that no refusal row carries.
+          remedy:
+            `Not a mechanical diff, so none is offered — an ungranted connector is in none of the bundles effective in this scope, and the ` +
+            `declaration needs a credential id that no refusal row carries. Add ` +
+            `\`{ name: "${r.connection}", credential: "<id>", contentOrigin: "internal" | "external" }\` to the \`connectors\` array of a ` +
+            `bundle bound to this scope in \`${PERMISSION_CONFIG_FILE}\`; the credential ids come from that connector's catalogue in ` +
+            `\`agent/access/connector-credentials.ts\`. ⚠ A break-glass \`revoke_connector\` produces this same reason code from the ` +
+            `override store, and no config edit defeats it — check the overrides before merging a widening.`,
+        });
+      }
+      if (r.liftableUnattended >= MIN_WIDEN_REFUSALS && declared) {
+        out.push({
+          id: `widen:connector:unattended:${r.connection}`,
+          direction: "widen",
+          subject: `Connector \`${r.connection}\` — write ops on unattended runs`,
+          summary:
+            `${r.liftableUnattended} unattended \`write\`-tier operation(s) on \`${r.connection}\` were refused because an approval card ` +
+            `has nobody to answer it. This scope holds the connector grant; what is missing is a standing permission for the fire.`,
+          evidence: [
+            `${r.refusals} \`connector.refused\` row(s) for \`${r.connection}\`, ${r.firstSeen} → ${r.lastSeen}; ${r.liftableUnattended} with reason \`ask-unattended\` at the \`write\` tier, a routine behind the turn AND no later row granting the permission.`,
+            ...(r.unroutedUnattended > 0
+              ? [
+                  `${r.unroutedUnattended} further \`ask-unattended\`/\`write\` row(s) carried NO routine (a webhook or job wake, \`routine: null\`). They are NOT counted above, because a standing routine permission is not their actuator — there is no routine card to re-arm.`,
+                ]
+              : []),
+            ...(r.armedSinceUnattended > 0
+              ? [
+                  `${r.armedSinceUnattended} further \`ask-unattended\`/\`write\` row(s) were followed by the permission ARRIVING — a \`connector.unattended_lift\` on the same op under the same ROUTINE, whatever generation of its instruction, so the refusal was already answered (the grant has since been armed, or it was there all along and a transient store read said otherwise). They are NOT counted above, and this proposal stands only on what is still unarmed.`,
+                ]
+              : []),
+            `Reasons: ${reasonsSeen}.`,
+            `Tiers: ${r.tiers.length > 0 ? r.tiers.map((x) => `${x.label} ×${x.count}`).join(", ") : "(none recorded)"}.`,
+            `Ops: ${opsSeen}.`,
+          ],
+          // The actuator is a per-routine store row, not a bundle edit — the same shape as the chain-deny remedy below.
+          remedy:
+            `This one is NOT a config-file diff, so none is offered. The standing permission is a per-tool declared permission on the routine — a human tap on ` +
+            `the routine's own card — not bundle config. Re-arm it with \`edit_routine\`/the creation card. ` +
+            `⚠ Only the \`write\` tier is liftable: a \`destructive\` op and a TAINTED turn are never lifted by any grant ` +
+            `(\`ask-unattended-tainted\` is its own reason code), so any of those rows in the counts above are a control working, not a gap.`,
+        });
+      }
+      continue;
+    }
+
+    // chain-deny — proposed on `ask-unattended` alone (see the header for the other reasons).
+    const unattendedReason = r.reasons.find((x) => x.label === "ask-unattended");
+    if (unattendedReason === undefined || unattendedReason.count < MIN_WIDEN_REFUSALS) continue;
+    out.push({
+      id: `widen:unattended:${r.tool}`,
+      direction: "widen",
+      subject: `\`${r.tool}\` on unattended runs`,
+      summary:
+        `${unattendedReason.count} unattended run(s) were denied \`${r.tool}\` because an approval card has nobody to answer it. ` +
+        `The work keeps arriving; the standing permission does not exist.`,
+      evidence: [
+        `${r.denies} \`approval.chain\` deny row(s) for \`${r.tool}\`, ${r.firstSeen} → ${r.lastSeen}; ${r.unattendedDenies} unattended.`,
+        `Reasons: ${r.reasons.map((x) => `${x.label} ×${x.count}`).join(", ")}.`,
+        `Decided by: ${r.resolvedBy.map((x) => `${x.label} ×${x.count}`).join(", ") || "(not recorded)"}.`,
+        ...(r.domains.length > 0 ? [`Domains: ${r.domains.join(", ")}.`] : []),
+      ],
+      // No mechanical diff: the actuator for "this fire may act without a card" is a per-routine store row, not bundle config.
+      remedy:
+        `This one is NOT a config-file diff, so none is offered. An unattended deny means the fire lacked a STANDING permission for ` +
+        `\`${r.tool}\`, and standing permissions are armed by a human tap on the routine's own creation card (they are per-routine ` +
+        `store rows, not bundle config). Re-arm it with \`edit_routine\`/the creation card, or — if this scope should never card ` +
+        `\`${r.tool}\` at all — add an operator approver to the bundle's \`approvers\` in a reviewed PR, which IS a config diff but one ` +
+        `only a human should author, because it changes policy for every caller in the scope rather than for one routine.`,
+    });
+  }
+  return out;
+}
+
+function tightenAws(u: AwsGrantUsage): PermissionProposal | undefined {
+  if (u.uses === 0) {
+    return {
+      id: `tighten:aws:${u.roleArn}`,
+      direction: "tighten",
+      subject: `AWS grant ${u.roleArn} — unused`,
+      summary: `This scope may assume ${u.roleArn}, and did not, once, in the window — while other AWS calls were made. The grant is a standing capability nobody is using.`,
+      evidence: [
+        `0 \`aws.exec\` rows for this roleArn in the window.`,
+        `Granted allow-list: ${u.allow.map((a) => `\`${a}\``).join(", ")}.`,
+      ],
+      diff: diff(u.bundles, `awsRoles[roleArn=${JSON.stringify(u.roleArn)}]`, u.allow, []),
+      remedy: "Remove the whole `awsRoles` entry (the `allow` lines above are shown as the body being deleted, not as a narrowing to an empty list — an empty `allow` is a config error, never the tightened form).",
+    };
+  }
+  if (u.allow.some((e) => e.trim() === "*") && u.services.length > 0) {
+    const after = u.services;
+    return {
+      id: `tighten:aws:${u.roleArn}`,
+      direction: "tighten",
+      subject: `AWS grant ${u.roleArn} — unrestricted, narrowly used`,
+      summary: `The grant is spelled \`["*"]\` (unrestricted) but ${u.uses} call(s) in the window touched only ${u.services.map((s) => `\`${s}\``).join(", ")}.`,
+      evidence: [
+        `${u.uses} \`aws.exec\` row(s); commands: ${u.commands.map((c) => `${c.label} ×${c.count}`).join(", ")}.`,
+      ],
+      diff: diff(u.bundles, awsAllowPath(u.roleArn), u.allow, after),
+      remedy: "Narrowed to the SERVICES observed, not to the exact operations — service grain is the least likely to send the next ordinary call straight back through loop 1. Tighten further by hand if the operations are genuinely fixed.",
+    };
+  }
+  if (u.unexercised.length > 0 && u.covering.length > 0) {
+    return {
+      id: `tighten:aws:${u.roleArn}`,
+      direction: "tighten",
+      subject: `AWS grant ${u.roleArn} — ${u.unexercised.length} unexercised allow entr${u.unexercised.length === 1 ? "y" : "ies"}`,
+      summary: `${u.unexercised.map((e) => `\`${e}\``).join(", ")} covered nothing this scope ran in the window; ${u.covering.length} other entr${u.covering.length === 1 ? "y" : "ies"} carried all ${u.uses} call(s).`,
+      evidence: [
+        `${u.uses} \`aws.exec\` row(s); commands: ${u.commands.map((c) => `${c.label} ×${c.count}`).join(", ")}.`,
+        `Coverage was tested with the live screen (\`awsCommandVerdict\`), one allow entry at a time — the same function that refuses a command at runtime.`,
+      ],
+      diff: diff(u.bundles, awsAllowPath(u.roleArn), u.allow, u.covering),
+    };
+  }
+  return undefined;
+}
+
+/** `refused` is this connection's refusal cluster in the SAME window, or undefined when it drew none. It never changes the verdict and it changes every word the reviewer reads, because "0 ops" means two opposite things. */
+function tightenConnector(u: ConnectorGrantUsage, refused: ConnectorRefusalEvidence | undefined): PermissionProposal | undefined {
+  if (u.uses > 0) return undefined;
+  const after = u.bundleConnectors.filter((c) => c !== u.connector);
+  const reached = refused !== undefined && refused.refusals > 0;
+  return {
+    id: `tighten:connector:${u.bundle}:${u.connector}`,
+    direction: "tighten",
+    subject: reached ? `Connector \`${u.connector}\` — unused, but REFUSED ${refused.refusals}×` : `Connector \`${u.connector}\` — unused`,
+    summary: reached
+      ? `Bundle \`${u.bundle}\` grants \`${u.connector}\` and no operation on it SUCCEEDED in the window, while other connectors were used — ` +
+        `but ${refused.refusals} operation(s) on it were REFUSED in the same window. This connection is being reached for, not sitting idle, so ` +
+        `read the refusal reasons below before removing the grant.`
+      : `Bundle \`${u.bundle}\` grants \`${u.connector}\` and no operation on it was recorded in the window, while other connectors were used.`,
+    evidence: reached
+      ? [
+          `0 \`connector.op\` rows for \`${u.connector}\` in the window — a refused op writes \`connector.refused\`, never \`connector.op\`, so a wholly-refused connection reads as an idle one on this counter alone.`,
+          `${refused.refusals} \`connector.refused\` row(s) for \`${u.connector}\`, ${refused.firstSeen} → ${refused.lastSeen}.`,
+          `Reasons: ${refused.reasons.map((x) => `${x.label} ×${x.count}`).join(", ")}.`,
+        ]
+      : [`0 \`connector.op\` rows for \`${u.connector}\` in the window.`],
+    diff: diff([u.bundle], "connectors", u.bundleConnectors, after),
+    // The remedy exists only on the annotated arm: an ordinarily-idle grant needs no caveat, and
+    // attaching one to every tightening proposal would drain the words of their meaning here.
+    ...(reached
+      ? {
+          remedy:
+            `Removing the grant is still a defensible call — a connection refused by a context wall and never otherwise used may be a grant nobody should hold. ` +
+            `But decide it against the reasons above, not against the zero: a WIDTH reason (\`ungranted\`, or \`ask-unattended\` at the \`write\` tier) means the work is asking for MORE ` +
+            `access to this connection, so removing the grant answers the opposite question from the one being asked. A context wall (\`dm_only\`, the disclosure legs, the member plane) ` +
+            `is a control no grant can open, so those refusals say nothing about whether the grant is wanted.`,
+        }
+      : {}),
+  };
+}
+
+function tightenProposals(ev: PermissionEvidence): PermissionProposal[] {
+  const out: PermissionProposal[] = [];
+  // The floors, checked once and per family: over a short or silent window nothing is proposed, which is the correct output rather than a gap.
+  if (ev.window.days < MIN_TIGHTEN_WINDOW_DAYS) return out;
+  // Refusals cluster by connection while usage is reported per (bundle, connector), so a connection two bundles declare annotates both.
+  const refusedByConnection = new Map<string, ConnectorRefusalEvidence>();
+  for (const r of ev.refusals) if (r.kind === "connector-refused") refusedByConnection.set(r.connection, r);
+  for (const u of ev.usage) {
+    if (u.kind === "aws-role") {
+      if (ev.activity.awsExec < MIN_TIGHTEN_OBSERVATIONS) continue;
+      const p = tightenAws(u);
+      if (p !== undefined) out.push(p);
+    } else {
+      if (ev.activity.connectorOps < MIN_TIGHTEN_OBSERVATIONS) continue;
+      const p = tightenConnector(u, refusedByConnection.get(u.connector));
+      if (p !== undefined) out.push(p);
+    }
+  }
+  return out;
+}
+
+export type ProposalDirection = "both" | "widen" | "tighten";
+
+/** Evidence into proposals. Deterministic: the same evidence yields the same list in the same order, widen first. */
+export function proposePermissionChanges(ev: PermissionEvidence, direction: ProposalDirection = "both"): readonly PermissionProposal[] {
+  return [
+    ...(direction === "tighten" ? [] : widenProposals(ev)),
+    ...(direction === "widen" ? [] : tightenProposals(ev)),
+  ];
+}
+
+/** The human-readable report. It leads with the window and the denominators, because "no proposals" over 4 rows means something different from "no proposals" over 4,000. */
+export function renderPermissionProposals(ev: PermissionEvidence, proposals: readonly PermissionProposal[]): string {
+  const lines: string[] = [];
+  lines.push(`Permission fit — ${ev.window.since} → ${ev.window.until} (${ev.window.days}d)`);
+  lines.push(
+    `evidence: ${ev.rowsConsidered} audit row(s) in window · ${ev.activity.awsExec} aws execution(s) · ` +
+      `${ev.activity.connectorOps} connector op(s) · ${ev.activity.chainResolutions} approval-chain resolution(s) · ` +
+      `${ev.activity.egressDenialRows} egress-denial row(s)`,
+  );
+  lines.push(`grants examined: ${ev.usage.length} · refusal clusters: ${ev.refusals.length}`);
+  lines.push("");
+
+  if (proposals.length === 0) {
+    lines.push("No proposals.");
+    if (ev.rowsConsidered === 0) {
+      lines.push("Nothing was recorded in this window at all — that is an absence of evidence, not evidence that the grants fit.");
+    } else if (ev.window.days < MIN_TIGHTEN_WINDOW_DAYS) {
+      lines.push(`Tightening was not evaluated: the window is shorter than the ${MIN_TIGHTEN_WINDOW_DAYS}-day floor.`);
+    } else {
+      lines.push("Grants that were exercised drew no refusals, and nothing granted went unused against enough activity to say so.");
+    }
+    lines.push("");
+    lines.push("Nothing here gates anything: this is a scan, and every proposal it can make is a config PR a human merges.");
+    return lines.join("\n");
+  }
+
+  for (const p of proposals) {
+    lines.push(`[${p.direction.toUpperCase()}] ${p.subject}`);
+    lines.push(`  ${p.summary}`);
+    for (const e of p.evidence) lines.push(`  · ${e}`);
+    if (p.diff !== undefined) {
+      lines.push("  proposed config change:");
+      for (const l of p.diff.text.split("\n")) lines.push(`    ${l}`);
+    }
+    if (p.remedy !== undefined) lines.push(`  note: ${p.remedy}`);
+    lines.push("");
+  }
+  lines.push("Every proposal above is TEXT. The actuator is a reviewed pull request against the config repo — nothing changed, and nothing is gated on your reading this.");
+  return lines.join("\n");
+}

package/agent/access/platform.ts

@@ -0,0 +1,14 @@
+// The ONE platform-detection seam: every "am I on Vercel?" switch reads this module instead of a raw `process.env.VERCEL`, so a self-hoster flips the OE-owned `OE_PLATFORM` rather than impersonating Vercel's own env var. A call site needing a broader notion than Vercel adds that surface here instead of reading env directly.
+
+/** The active platform name: the `OE_PLATFORM` override if set (trimmed, lower-cased), else "vercel" when Vercel's own `VERCEL` env is set, else "self-host". */
+export function platformName(): string {
+  const override = process.env.OE_PLATFORM?.trim().toLowerCase();
+  if (override) return override;
+  if (process.env.VERCEL) return "vercel";
+  return "self-host";
+}
+
+/** True iff the active platform is Vercel. The single "am I on Vercel?" switch. */
+export function onVercel(): boolean {
+  return platformName() === "vercel";
+}

package/agent/access/pre-approval-rules.ts

@@ -0,0 +1,135 @@
+// Admin-authored allow rules that feed the approval judge; the only source is a reviewed `Bundle.preApprovalRules`, never a repository the agent checks out, and there is no runtime write path at all. A rule can only PRE-APPROVE — it can never remove an ask policy code forces — and a narrower scope only ADDS to a wider one.
+
+/** One authored rule. Prose, plus the id that makes an auto-allow traceable to it. */
+export interface PreApprovalRule {
+  /** Stable, citable, and unique across the WHOLE config (`assertBundlesValid` enforces it): the judge cites this id and the `approval.judge.verdict` row carries it. Slug grammar, so a citation parses without ambiguity. */
+  readonly id: string;
+  /** The rule itself, in the org's own words. */
+  readonly rule: string;
+}
+
+/** An assembled rule, with the scope rung that authored it — the judge sees the rung, so it can
+ *  weigh an org-wide rule against a surface-specific one. */
+export interface ResolvedPreApprovalRule extends PreApprovalRule {
+  /** The authoring binding's scope label ("org", "domain:payments", …). */
+  readonly scope: string;
+}
+
+/** Per-rule length cap — Claude Tag's 1,024 characters. A rule is a sentence of policy, not a
+ *  document; the cap keeps the assembled block inside a prompt budget and keeps rules reviewable. */
+export const PRE_APPROVAL_RULE_MAX_CHARS = 1024;
+
+export const PRE_APPROVAL_RULES_MAX_PER_BUNDLE = 50;
+
+/** The assembled ceiling across the whole ladder. Overflow is dropped from the NARROWEST end, so a narrow scope cannot evict the org's reviewed baseline by sheer volume; either direction is safe in verdict terms, since a dropped allow rule can only cost an auto-allow and never buy one. */
+export const PRE_APPROVAL_RULES_MAX_ASSEMBLED = 200;
+
+/** The citable id grammar, in ONE place: no whitespace, so a `RULE: <id>` citation parses unambiguously. `approval-judge.ts` builds its citation regex from this source string rather than a second copy, which would drift into citations that validate and never resolve. */
+export const PRE_APPROVAL_RULE_ID_PATTERN = "[A-Za-z0-9][A-Za-z0-9._-]{0,63}";
+
+const RULE_ID_RE = new RegExp(`^${PRE_APPROVAL_RULE_ID_PATTERN}$`, "u");
+
+export function isValidPreApprovalRuleId(id: string): boolean {
+  return RULE_ID_RE.test(id);
+}
+
+/** One scope's contribution, as the resolver hands it over: widest rung first. */
+export interface PreApprovalRuleLayer {
+  /** Scope label of the authoring binding. */
+  readonly scope: string;
+  readonly rules: readonly PreApprovalRule[];
+}
+
+export interface AssembledPreApprovalRules {
+  /** Ladder order, widest → narrowest. Additive: nothing here replaced anything. */
+  readonly rules: readonly ResolvedPreApprovalRule[];
+  /** How many rules the assembled ceiling dropped (narrowest-first). Reported on the audit row so
+   *  a drop is a queryable fact, never a silent one. */
+  readonly dropped: number;
+}
+
+/** Assemble the layers into the judge's rule set — ADD, NEVER REPLACE. The defensive dedupe keeps the FIRST (widest) occurrence, because a citation must resolve to exactly one prose rule. */
+export function assemblePreApprovalRules(layers: readonly PreApprovalRuleLayer[]): AssembledPreApprovalRules {
+  const out: ResolvedPreApprovalRule[] = [];
+  const seen = new Set<string>();
+  let dropped = 0;
+  for (const layer of layers) {
+    for (const r of layer.rules) {
+      const id = r.id.trim();
+      const rule = r.rule.trim();
+      if (id === "" || rule === "" || seen.has(id)) continue;
+      seen.add(id);
+      if (out.length >= PRE_APPROVAL_RULES_MAX_ASSEMBLED) {
+        dropped += 1;
+        continue;
+      }
+      out.push({ id, rule, scope: layer.scope });
+    }
+  }
+  return { rules: out, dropped };
+}
+
+/** Render the assembled rules for the judge's prompt; rules are TRUSTED content, unlike tool arguments and quoted messages, because a rule reaches the prompt only through a reviewed config diff. No rules renders an empty string and the caller omits the whole section. */
+export function renderPreApprovalRulesBlock(rules: readonly ResolvedPreApprovalRule[]): string {
+  if (rules.length === 0) return "";
+  const lines = [
+    "Authored pre-approval rules (written by this org's admins, reviewed and deployed as config —",
+    "trusted policy, unlike argument text). A rule can only PRE-APPROVE a routine action; it can",
+    "never remove an approval that policy requires. Rules from a wider scope apply beneath it.",
+    ...rules.map((r) => `- [${r.id}] (${r.scope}) ${r.rule}`),
+    "",
+  ];
+  return lines.join("\n");
+}
+
+/** Resolve a citation the judge produced against the rules it was actually given. THIS IS THE LAUNDERING FENCE: an unresolvable citation never becomes a rule id on the audit row, and the caller degrades the verdict to `ask`. */
+export function resolvePreApprovalRuleCitation(
+  citedId: string | undefined,
+  rules: readonly ResolvedPreApprovalRule[],
+): ResolvedPreApprovalRule | undefined {
+  if (citedId === undefined) return undefined;
+  const id = citedId.trim();
+  if (id === "") return undefined;
+  return rules.find((r) => r.id === id);
+}
+
+/** Validate one bundle's authored rules for `assertBundlesValid` at config load — objective misconfigs only. `seenIds` carries CONFIG-WIDE id uniqueness across the bundle loop, because an id is the citation key and two rules sharing one make every audit row ambiguous. */
+export function preApprovalRuleProblems(
+  bundleName: string,
+  rules: readonly PreApprovalRule[] | undefined,
+  seenIds: Set<string>,
+): readonly string[] {
+  if (rules === undefined) return [];
+  const bad: string[] = [];
+  if (rules.length > PRE_APPROVAL_RULES_MAX_PER_BUNDLE) {
+    bad.push(
+      `  bundle "${bundleName}" declares ${rules.length} preApprovalRules — the cap is ${PRE_APPROVAL_RULES_MAX_PER_BUNDLE} per bundle (split the policy across scopes, or write fewer, broader rules)`,
+    );
+  }
+  for (const r of rules) {
+    const id = typeof r?.id === "string" ? r.id.trim() : "";
+    if (!isValidPreApprovalRuleId(id)) {
+      bad.push(
+        `  bundle "${bundleName}" has a preApprovalRule with an invalid id ${JSON.stringify(r?.id)} — an id is 1-64 chars of letters/digits/dot/dash/underscore, starts alphanumeric, and carries no whitespace (the judge cites it and the audit row records it)`,
+      );
+      continue;
+    }
+    if (seenIds.has(id)) {
+      bad.push(
+        `  bundle "${bundleName}" reuses preApprovalRule id "${id}" — ids must be unique across the WHOLE config, because an auto-allow's audit row cites the id and two rules sharing one make it ambiguous`,
+      );
+    }
+    seenIds.add(id);
+    const rule = typeof r?.rule === "string" ? r.rule.trim() : "";
+    if (rule === "") {
+      bad.push(`  bundle "${bundleName}" preApprovalRule "${id}" has no rule text — a rule with no prose tells the judge nothing`);
+      continue;
+    }
+    if (rule.length > PRE_APPROVAL_RULE_MAX_CHARS) {
+      bad.push(
+        `  bundle "${bundleName}" preApprovalRule "${id}" is ${rule.length} chars — the cap is ${PRE_APPROVAL_RULE_MAX_CHARS} (a rule is a sentence of policy, not a document)`,
+      );
+    }
+  }
+  return bad;
+}