@open-everywhere/core 0.1.0

package/agent/access/approver-chain.ts

@@ -0,0 +1,779 @@
+// Any deny wins, order-independent, and the only way to lift one is a reviewed config diff to the element that denies.
+// Otherwise the first opinion in the CODE-PINNED level order wins: config fills slots within a level and can never reorder the levels.
+// Modes, taint and unattendedness are post-resolution transforms that only move allow/ask; a lowered verdict is still bounded by egress, the credential planes, IAM, spend caps and the audit ledger.
+
+import { declaredStandingWrites } from "../routines/declared-permissions.js";
+import { classifyConnectorOp, isConnectorOpTool, judgeDeferredTool, postTurnSurfaceFloors, RESUME_TOOL, TOOL_CONSEQUENCE, type ConsequenceEntry } from "./consequence.js";
+import { awsCommandVerdict, type AwsScreenInput } from "./aws-screen.js";
+import { untrustedIngestedThisTurn, taintKindsThisTurn } from "./taint-signal.js";
+import { taintMode, type TaintMode } from "./taint-enforcement.js";
+// The DEFER-MODEL judge (OPE-318 phase 2). Runtime edge runs ONE way — this module calls the
+// judge; approval-judge.ts imports only TYPES from here (erased), so no cycle.
+import {
+  approvalJudgeAdminDisarmed,
+  approvalJudgeMode,
+  judgeContextOf,
+  judgeVerdictCacheKey,
+  JUDGE_ENFORCE_TIMEOUT_MS,
+  runApprovalJudge,
+  APPROVAL_JUDGE_ADMIN_DISARM,
+  type ApprovalJudgeRun,
+} from "./approval-judge.js";
+import type { ResolvedPreApprovalRule } from "./pre-approval-rules.js";
+// Runtime-safe, no cycle: config.ts's own imports are all type-only, and resolver.ts imports this
+// module type-only (erased) — the runtime edges run one way, from here outward.
+import { getConfig } from "./config.js";
+import { resolveAccess } from "./resolver.js";
+
+/** What one element may answer. `undefined` = defer down the chain — silence is never approval, and the terminal registry element is what makes silence resolvable at all. */
+export type ApproverVerdict = "allow" | "deny" | "ask" | undefined;
+
+/** One approver element's callable — arbitrary TS in config, or a built-in. May be async. */
+export type Approver = (req: ApprovalChainRequest) => ApproverVerdict | Promise<ApproverVerdict>;
+
+/** Only `blocking` is implemented; `queued` is vocabulary reserved so widening later need not pivot every element, transform, clamp and audit row. A resolution whose verdict is `ask` always carries a variant. */
+export type AskVariant = "blocking" | "queued";
+
+/** The three approval-mode names (plan §3.4). Config-as-code only — there is no runtime toggle. */
+export type ApprovalModeName = "DANGEROUSLY_BYPASS" | "APPROVE_ALL" | "DENY_ALL";
+
+/** `allowlist` applies ONLY to APPROVE_ALL: tool names that keep the registry default instead of being floored to ask. A plain tool-name list, deliberately not the `connectorOps` grammar. */
+export interface ApprovalModeConfig {
+  readonly mode: ApprovalModeName;
+  readonly allowlist?: readonly string[];
+}
+
+/** One prospective action. Every field is VERIFIED/host-derived input, never model text; `args` is the frozen payload, handed to operator approvers verbatim. */
+export interface ApprovalChainRequest {
+  /** Tool slug (TOOL_CONSEQUENCE key) or qualified connector-op name (`<connection>__<op>`). */
+  readonly tool: string;
+  /** The ActionKind, when the request arrived via the propose plane (approvals/flow.ts). */
+  readonly action?: string;
+  /** The FROZEN args (propose plane) / the argv (aws) — for operator approvers to read. */
+  readonly args?: unknown;
+  readonly scopeKey?: string;
+  readonly domain?: string;
+  /**
+   * The org this request belongs to — part of the judge's DISARM ADDRESS, not decoration: the operator ledger is read scoped to it, so one org's re-arm cannot move another org's judge.
+   * ABSENT ⇒ that reader answers DISARMED, so omitting it costs a card and can never produce a lift.
+   */
+  readonly org?: string;
+  /** The verified ACTING principal; undefined on an unattended fire. */
+  readonly principalId?: string;
+  /** No human is behind this turn. 🔴 Keyed off UNATTENDEDNESS, never `sessionMode`: an ordinary fire mounts the full ungated kit, and `sessionMode: "job"` would miss it entirely. */
+  readonly unattended: boolean;
+  /** This turn ingested untrusted external content. Absent ⇒ read via {@link chainTaintSignal}. */
+  readonly tainted?: boolean;
+  /** The scope's approval mode, when its domain declares one. */
+  readonly mode?: ApprovalModeConfig;
+  /**
+   * A break-glass HALT covers this request, resolved by the propose plane against the live store and handed in exactly as `mode` is — a runtime source for the same stage, not a second plane.
+   * 🔴 Fail-closed at the source: the propose plane sets it `true` when the halt store could not be read. Absent ⇒ no halt was resolved.
+   */
+  readonly halted?: boolean;
+  /** AWS surface payload — present ONLY when the `aws` tool consults the chain (plan §8.2: the
+   *  host-side command screen is the AWS surface approver at L2). */
+  readonly aws?: AwsScreenInput;
+  /** The deployment's `connectorOps` RAISE for this op, when one covers it (bundle.ts) — raise-only
+   *  today, and it keeps that clamp: the element only ever answers `ask`. */
+  readonly connectorOpRaise?: "write" | "destructive";
+  /**
+   * The ActionKind MINTS live material and destroys what it replaces, and only a card click produces a `decidedBy` that is a person. Set by the propose plane from the kind registry, never from a tool's own args.
+   * The arrow it feeds asks whether a PERSON decided the mint, never who receives the reveal.
+   */
+  readonly beneficiaryClicker?: boolean;
+}
+
+/**
+ * The ONE place this chain reads the turn-taint signal. Fail-soft like the underlying slot: no session context ⇒ untainted.
+ * What the chain does with it: fire `taint:ask` at the sinks that arm or disarm a post-turn surface, and put `tainted` plus the kinds on the audit row. Nothing else.
+ */
+export function chainTaintSignal(): boolean {
+  return untrustedIngestedThisTurn();
+}
+
+/** The DISCLOSURE breakdown for the audit row + the card line — which classes of source this turn
+ *  ingested. May be empty on a tainted turn (an auth-attribute seed knows the bit, not the kinds). */
+export function chainTaintKinds(): readonly string[] {
+  return taintKindsThisTurn();
+}
+
+function taintedOf(req: ApprovalChainRequest): boolean {
+  return req.tainted ?? chainTaintSignal();
+}
+
+/**
+ * Written onto the row ONLY when taint is off, so an `on` deployment's rows stay byte-identical: `tainted: false` otherwise cannot be told from "the model is not running".
+ * 🔴 Not a frozen field, unlike `req.tainted` — the posture belongs to the process resolving the chain, and reading it live stops a row minted after a revert claiming settings that no longer hold.
+ */
+function taintModeNote(): { taintMode: TaintMode } | Record<string, never> {
+  const mode = taintMode();
+  return mode === "off" ? { taintMode: mode } : {};
+}
+
+export type ApproverLevel = "custom" | "surface" | "classifier" | "registry";
+
+/** A declared constant, never an emergent property of import order. Config orders elements WITHIN L1 only; a genuinely new element class needs a code change and a re-review of this order. */
+export const APPROVER_LEVEL_ORDER: readonly ApproverLevel[] = ["custom", "surface", "classifier", "registry"];
+
+/** An element's class decides its verdict clamp — the load-bearing primitive for untrusted-ish
+ *  elements (plan §3.5). */
+export type ElementClass = "operator" | "surface" | "classifier" | "registry" | "connector" | "remote";
+
+/** An element verdict AFTER normalisation (undefined → "defer") — the audit row's vocabulary. */
+export type ElementVerdict = "allow" | "deny" | "ask" | "defer";
+
+/**
+ * Connector-supplied and remote elements are RAISE-ONLY unless config grants `mayAllow`; the registry is terminal and may not defer.
+ * An out-of-clamp verdict is treated as `defer` and the row carries `clamped: true` — never an error, never trusted.
+ */
+export const ELEMENT_CLAMPS: Readonly<Record<ElementClass, readonly ElementVerdict[]>> = {
+  operator: ["allow", "deny", "ask", "defer"],
+  surface: ["allow", "deny", "ask", "defer"],
+  classifier: ["allow", "deny", "ask", "defer"],
+  registry: ["allow", "deny", "ask"],
+  connector: ["deny", "ask", "defer"],
+  remote: ["deny", "ask", "defer"],
+};
+
+/**
+ * An operator-authored approver, declared in bundle config and resolved per scope like every other grant.
+ * `source: "connector"`/`"remote"` marks an element the operator did not write: clamped raise-only unless granted `mayAllow`. No `url` transport ships in v1.
+ */
+export interface OperatorApprover {
+  /** Unique within the bundle; the audit row's `resolvedBy` reads `custom:<name>`. */
+  readonly name: string;
+  readonly approve: Approver;
+  /** Who authored it. Default "operator" (full verdict range — config-as-code is the review). */
+  readonly source?: "operator" | "connector" | "remote";
+  /** Clamp escape for connector/remote sources: permits "allow". Meaningless (and refused by
+   *  config validation) on an operator-authored element, which already has the full range. */
+  readonly mayAllow?: boolean;
+}
+
+export interface ChainElementResult {
+  readonly element: string;
+  readonly level: ApproverLevel;
+  readonly verdict: ElementVerdict;
+  /** The element answered outside its clamp; the verdict shown is the clamped `defer`. */
+  readonly clamped?: true;
+  /** The element threw or timed out; the verdict shown is the fail-closed `ask`. There is deliberately no knob that ignores an element error. */
+  readonly error?: true;
+}
+
+export interface AppliedTransform {
+  readonly name: string;
+  readonly from: "allow" | "ask";
+  readonly to: "allow" | "ask" | "deny";
+  readonly reason?: string;
+}
+
+/** The chain's full resolution — the audit row's content and the simulator's trace (one shape). */
+export interface ChainResolution {
+  readonly verdict: "allow" | "deny" | "ask";
+  /** Present iff verdict === "ask". Always "blocking" in v1 (§11 reservation). */
+  readonly askVariant?: AskVariant;
+  /** Which element produced the resolved (pre-transform) verdict — the "why was there no card?"
+   *  one-pointer, together with `transforms`. `"judge"` when the armed judge's final allow/deny
+   *  displaced a defer row's per-verb default (OPE-318 phase 2). */
+  readonly resolvedBy: string;
+  /** The registry (L4) baseline, ALWAYS — the divergence "config lowered this" is measured
+   *  against it and must be a queryable fact (plan §4.2). */
+  readonly registryVerdict: "allow" | "ask";
+  readonly elements: readonly ChainElementResult[];
+  readonly transforms: readonly AppliedTransform[];
+  /** The SAME taint value the arrows read, so a caller reporting the outcome cannot disagree with the chain that decided it — a second live read is a different question, because the propose site may have frozen `req.tainted`. */
+  readonly tainted: boolean;
+  /** True when an absolute deny skipped the transform pipeline. */
+  readonly denyAbsolute?: true;
+  /** The armed judge's CONSULT, when one happened (OPE-318 phase 2 — enforce mode, a defer row,
+   *  a judge-opted caller). Present on EVERY consult, including a deferring/timed-out one and one
+   *  skipped by an operator disarm, so the propose plane writes its `approval.judge.verdict` row
+   *  per consult. */
+  readonly judge?: ApprovalJudgeRun;
+}
+
+/**
+ * The registry's verdict for one tool — TERMINAL, never defers: an `open` row allows, a `gate:*` row asks, and a qualified connector op maps through the verb classifier.
+ * A name known to neither plane resolves `ask`, fail-closed.
+ */
+export function registryVerdictOf(tool: string): "allow" | "ask" {
+  if (isConnectorOpTool(tool)) return classifyConnectorOp(tool) === "open" ? "allow" : "ask";
+  const row: ConsequenceEntry | undefined = TOOL_CONSEQUENCE[tool];
+  if (row === undefined) return "ask"; // fail-closed terminal for an unknown name
+  return row.tier === "open" ? "allow" : "ask";
+}
+
+/**
+ * The per-sink taint tolerance, in source order: a connector op (writes "disclose", reads none), then a row's declared `taint` column, then a gated row with no column ("gate", fail closed) and an open row with no column (no tolerance).
+ * The open-row arm is a deliberate reading: the fail-closed default is scoped to SINKS, because applying it to every row would card `reply` on any tainted turn.
+ * 🔴 Only "gate" reaches a transform — "disclose" and `undefined` are indistinguishable to {@link TRANSFORM_TABLE}; the column still says which sinks treat provenance as material.
+ * 🔴 `postTurnSurface: "arms"|"disarms"` outranks the column and is read FIRST, so the floor is the UNION of both and removing the column from an arming row would not lift it.
+ */
+export function taintToleranceOf(tool: string): "gate" | "disclose" | undefined {
+  if (isConnectorOpTool(tool)) return classifyConnectorOp(tool) === "open" ? undefined : "disclose";
+  return taintToleranceOfRow(TOOL_CONSEQUENCE[tool]);
+}
+
+/** {@link taintToleranceOf}'s decision over ONE row, split out to be testable: the `postTurnSurface` precedence is redundant on the shipped table, so only a crafted row (arming plus a "disclose" column) can pin it. */
+export function taintToleranceOfRow(row: ConsequenceEntry | undefined): "gate" | "disclose" | undefined {
+  if (row === undefined) return "gate";
+  if (postTurnSurfaceFloors(row.postTurnSurface)) return "gate";
+  if (row.taint !== undefined) return row.taint;
+  return row.tier === "open" ? undefined : "gate";
+}
+
+// The judge is reached only where three independently-reviewed gates agree: the registry row is explicitly defer-flipped, the deployment is armed `enforce`, and the CALLER opted in — so the simulator, the AWS screen and every headless consult stay judge-free.
+// Its verdict is final: a deny skips the transforms like an element deny, an allow still runs every clamp, and ask, defer, timeout or an operator disarm leave the row where it sat before the flip.
+// The consult is AWAITED inline and bounded by {@link JUDGE_ENFORCE_TIMEOUT_MS}; it never touches the per-session sequential model stamp, so judge tokens attribute to whatever the seat last stamped.
+
+export type TransformStage = "mode" | "unattended" | "taint" | "floor";
+
+/**
+ * glossary: Transform order: mode → taint → floor → unattended.
+ * 🔴 `unattended` runs LAST so a taint-raised ask cannot survive into an empty room; it is safe there because every arrow after `mode` only tightens.
+ * `taint` and `floor` run after `mode` so DANGEROUSLY_BYPASS can lift neither: no unattended run may arm those sinks off fetched content, and nothing upstream may leave a beneficiary-clicker kind auto-approved.
+ */
+export const TRANSFORM_STAGE_ORDER: readonly TransformStage[] = ["mode", "taint", "floor", "unattended"];
+
+/** One arrow in the transform table. `from` never contains deny — a deny skips the pipeline
+ *  structurally (the deny-invariant is not each arrow's good manners; it is the runner's shape). */
+export interface TransformRow {
+  readonly name: string;
+  readonly stage: TransformStage;
+  readonly from: readonly ("allow" | "ask")[];
+  readonly reason?: string;
+  fires(req: ApprovalChainRequest): boolean;
+  to(req: ApprovalChainRequest, registryVerdict: "allow" | "ask"): "allow" | "ask" | "deny";
+}
+
+/** The runner honours EXACTLY these arrows; there is no transform logic outside this table. Every arrow tightens or kills cards, and none can affect a deny, because a deny never reaches them. */
+export const TRANSFORM_TABLE: readonly TransformRow[] = [
+  {
+    // Kills CARDS only: it does not touch deny (structurally unreachable), egress, credentials, IAM, spend caps or audit.
+    // 🔴 `resume` is EXEMPT ({@link RESUME_TOOL}): without this, a model turn inside one bypass domain would lift the deployment's org-wide halt with no admin click, and a per-domain setting must never lift an org-wide stop.
+    name: "mode:DANGEROUSLY_BYPASS",
+    stage: "mode",
+    from: ["ask"],
+    fires: (req) => req.mode?.mode === "DANGEROUSLY_BYPASS" && req.tool !== RESUME_TOOL,
+    to: () => "allow",
+  },
+  {
+    // Floor-to-ask with restorations: every allow becomes ask EXCEPT names on the mode's explicit
+    // allowlist, which keep the REGISTRY default (not the resolved verdict — a config-lowered allow
+    // on an allowlisted name goes back to what the registry says, which only ever tightens).
+    name: "mode:APPROVE_ALL",
+    stage: "mode",
+    from: ["allow"],
+    fires: (req) => req.mode?.mode === "APPROVE_ALL",
+    to: (req, registryVerdict) => ((req.mode?.allowlist ?? []).includes(req.tool) ? registryVerdict : "ask"),
+  },
+  {
+    // DENY_ALL's exact arrow is unstated in every source ruling; implemented as the element-equivalent `* → deny`, which satisfies the one stated constraint that it only ever tightens.
+    // Practical scope: the chain is consulted at the gated seams, so a DENY_ALL domain still converses. Operator review may narrow this to `ask → deny`.
+    name: "mode:DENY_ALL",
+    stage: "mode",
+    from: ["allow", "ask"],
+    reason: "mode-deny-all",
+    fires: (req) => req.mode?.mode === "DENY_ALL",
+    to: () => "deny",
+  },
+  {
+    // The break-glass halt: the same stage and arrow as `mode:DENY_ALL`, differing only in SOURCE — a runtime store row an operator writes during an incident, addressed to a surface, tenant, domain, person or the whole org.
+    // 🔴 `resume` is EXEMPT ({@link RESUME_TOOL}), and that is why this is a separate row: `resume` is `gate:admin` and routes through this chain, so without the exemption a halt would deny its own lift. Every other verb, `halt` included, is denied while halted.
+    // The control-MCP `resume` never touches this chain — it is the door that works when the chat door does not.
+    name: "mode:HALT",
+    stage: "mode",
+    from: ["allow", "ask"],
+    reason: "halt",
+    fires: (req) => req.halted === true && req.tool !== RESUME_TOOL,
+    to: () => "deny",
+  },
+  {
+    // Unattended `ask → deny` (plan §5): a card in an empty room is toxic; a deny is KIND — the
+    // fire continues instead of stalling, and the deny row feeds OPE-297's homeostasis loop
+    // (deny hits → a proposed grant-diff PR). Keys off UNATTENDEDNESS, never sessionMode.
+    name: "unattended",
+    stage: "unattended",
+    from: ["ask"],
+    reason: "ask-unattended",
+    fires: (req) => req.unattended,
+    to: () => "deny",
+  },
+  {
+    // The ONLY taint arrow: a per-sink FLOOR TO ASK for the sinks whose `postTurnSurface` arms or disarms. Everywhere else a tainted turn changes no verdict and its provenance is only disclosed.
+    // It stops a LOWERING — a custom approver, a config allow, a judge allow, a bypass domain — from taking one of those sinks below a human decision on a turn that read external content.
+    // Why only these: their output is trusted text on an unwitnessed future run, or a durable external wake path. Attended, a human reads a card carrying the provenance; unattended, the `unattended` arrow denies it.
+    // THE SET IS DERIVED, NEVER TYPED (OPE-419). `postTurnSurface: "arms" | "disarms"` is the predicate, and the predicate answers gate for 11 rows of
+    // TOOL_CONSEQUENCE today, so no reader needs to trust a count somebody typed.
+    name: "taint:ask",
+    stage: "taint",
+    from: ["allow"],
+    reason: "taint-ask",
+    fires: (req) => taintedOf(req) && taintToleranceOf(req.tool) === "gate",
+    to: () => "ask",
+  },
+  {
+    // A beneficiary-clicker kind's execute() mints live material and destroys what it replaces, and a lowered verdict records `chain:<element>` as the decider — a silent, completed, undecided credential rotation. The kind is therefore structurally card-only.
+    // `to` reads the REGISTRY baseline rather than a hardcoded ask, which keeps the arrow a no-op on a beneficiary kind the registry itself marks open.
+    name: "beneficiary-clicker-floor",
+    stage: "floor",
+    from: ["allow"],
+    reason: "beneficiary-clicker",
+    fires: (req) => req.beneficiaryClicker === true,
+    to: (_req, registryVerdict) => registryVerdict,
+  },
+];
+
+interface BuiltInElement {
+  readonly name: string;
+  readonly level: ApproverLevel;
+  readonly clazz: ElementClass;
+  evaluate(req: ApprovalChainRequest): ApproverVerdict | Promise<ApproverVerdict>;
+}
+
+// 🔴 Session grants are NOT an element of this chain and must not become one by accident: a live "Approve for session" grant short-circuits BEFORE the propose plane — the tool reads the memo, publishes through the same execute, and audits the act.
+// An element for it sat at L2 for trace legibility, no caller ever fed it, and it is deleted; anyone adding one must first give the chain a caller that supplies the grant.
+
+const AWS_SURFACE_ELEMENT: BuiltInElement = {
+  // The AWS host-side command screen (plan §8.2) — fires only when the request carries the aws
+  // payload (the `aws` tool's consult). Deny on any screen violation, defer when clean: the
+  // registry terminal supplies the allow, so this element can only ever REFUSE, never widen.
+  name: "aws-allow-list",
+  level: "surface",
+  clazz: "surface",
+  evaluate: (req) => {
+    if (req.aws === undefined) return undefined;
+    return awsCommandVerdict(req.aws).ok ? undefined : "deny";
+  },
+};
+
+const CONNECTOR_OPS_RAISE_ELEMENT: BuiltInElement = {
+  // The bundle `connectorOps` raise (access/bundle.ts) — raise-only today, and it KEEPS that
+  // clamp: the element answers only `ask` (or defers). A raise names an op the operator wants
+  // gated regardless of the verb heuristic's opinion.
+  name: "connector-ops-raise",
+  level: "surface",
+  clazz: "surface",
+  evaluate: (req) => (req.connectorOpRaise !== undefined ? "ask" : undefined),
+};
+
+const VERB_CLASSIFIER_ELEMENT: BuiltInElement = {
+  // The built-in verb classifier (L3) — connector ops only: reads open, writes gated. Defers on
+  // every authored/framework tool (the registry owns those).
+  name: "verb-classifier",
+  level: "classifier",
+  clazz: "classifier",
+  evaluate: (req) => {
+    if (!isConnectorOpTool(req.tool)) return undefined;
+    return classifyConnectorOp(req.tool) === "open" ? "allow" : "ask";
+  },
+};
+
+const REGISTRY_ELEMENT: BuiltInElement = {
+  // L4 — TERMINAL. Never defers, so the positional walk always terminates with allow or ask.
+  name: "registry",
+  level: "registry",
+  clazz: "registry",
+  evaluate: (req) => registryVerdictOf(req.tool),
+};
+
+const LEVEL_RANK: Readonly<Record<ApproverLevel, number>> = Object.fromEntries(
+  APPROVER_LEVEL_ORDER.map((l, i) => [l, i]),
+) as Record<ApproverLevel, number>;
+
+function clampVerdict(
+  raw: ApproverVerdict,
+  clazz: ElementClass,
+  mayAllow: boolean | undefined,
+): { verdict: ElementVerdict; clamped?: true } {
+  const verdict: ElementVerdict = raw === undefined ? "defer" : raw;
+  const permitted = new Set<ElementVerdict>(ELEMENT_CLAMPS[clazz]);
+  if (mayAllow === true && (clazz === "connector" || clazz === "remote")) permitted.add("allow");
+  if (permitted.has(verdict)) return { verdict };
+  return { verdict: "defer", clamped: true };
+}
+
+export interface ResolveChainOptions {
+  /** The scope's L1 operator approvers, CONFIG-ORDERED (resolver order within the band). */
+  readonly approvers?: readonly OperatorApprover[];
+  /** Opt into the armed judge: only the propose plane passes true, because a consult is a real awaited model call whose allow can execute frozen args. Absent or false ⇒ the chain is byte-identical to pre-judge, whatever the env or the registry flips say. */
+  readonly judge?: boolean;
+  /** The scope's admin-authored pre-approval rules reach the judge's CONTEXT and nothing else — never a chain element, so they cannot resolve, clamp or transform anything, and they are ignored unless a consult happens. */
+  readonly rules?: readonly ResolvedPreApprovalRule[];
+}
+
+/**
+ * Why the armed judge may NOT lift this request, or undefined when it may. The ONE eligibility
+ * question the chain asks about a request's own shape before a consult.
+ *
+ * 🔴 RULINGS (Tommy, 2026-09-23, OPE-2101 and OPE-2103): a `routine.create` that declares a
+ * standing unattended WRITE — a connector write or `pr.open` — is armed by a person's click on the
+ * creation card, and by nothing else. The judge
+ * lift would write the same `routine.grant` rows under `chain:judge`, with no person in the loop,
+ * for a permission that then acts on its own on every future fire. So the class is decided here by
+ * capability — `pr.open`, or the declared tool's tier (routines/declared-permissions.ts
+ * `declaredStandingWrites`) — and never by platform. A declaration of reads only keeps the
+ * ordinary judge path.
+ *
+ * The reason names the declarations. They are model-authored, but they are the text the creation
+ * card renders verbatim, and an operator needs them to read the row.
+ */
+export function judgeHumanOnlyReason(req: Pick<ApprovalChainRequest, "action" | "args">): string | undefined {
+  if (req.action !== ROUTINE_CREATE_ACTION) return undefined;
+  const raw = (req.args as { permissions?: unknown } | null | undefined)?.permissions;
+  const declared = Array.isArray(raw) ? raw.filter((d): d is string => typeof d === "string") : [];
+  const writes = declaredStandingWrites(declared);
+  if (writes.length === 0) return undefined;
+  return (
+    `human-only: this routine declares a standing unattended write (${writes.join(", ")}), ` +
+    "and only a person's click on the creation card may arm one — the judge is not consulted (OPE-2101, OPE-2103)"
+  );
+}
+
+/** The ActionKind whose frozen `permissions` arm standing routine permissions on execute. */
+const ROUTINE_CREATE_ACTION = "routine.create";
+
+/** EVALUATE-ALL, not short-circuit: the audit rule requires every element's verdict on the row, and the deny-invariant requires seeing all denies (measured at ~3µs over a 6-element chain). */
+export async function resolveApproverChain(
+  req: ApprovalChainRequest,
+  opts: ResolveChainOptions = {},
+): Promise<ChainResolution> {
+  interface Evaluated extends ChainElementResult {
+    readonly rank: number;
+    readonly order: number;
+  }
+  const evaluated: Evaluated[] = [];
+
+  // 1. Build the element list: L1 (config-ordered) ++ L2 ++ L3 ++ L4. L4 always present, always last.
+  const elements: readonly { name: string; level: ApproverLevel; clazz: ElementClass; mayAllow?: boolean; run: Approver }[] = [
+    ...(opts.approvers ?? []).map((a) => ({
+      name: `custom:${a.name}`,
+      level: "custom" as const,
+      clazz: (a.source === "connector" ? "connector" : a.source === "remote" ? "remote" : "operator") as ElementClass,
+      mayAllow: a.mayAllow,
+      run: a.approve,
+    })),
+    ...[AWS_SURFACE_ELEMENT, CONNECTOR_OPS_RAISE_ELEMENT, VERB_CLASSIFIER_ELEMENT, REGISTRY_ELEMENT].map((e) => ({
+      name: e.name,
+      level: e.level,
+      clazz: e.clazz,
+      run: (r: ApprovalChainRequest) => e.evaluate(r),
+    })),
+  ];
+
+  // 2. Evaluate EVERY element; clamp each verdict; element error ⇒ ask (fail-closed, §3.6).
+  let order = 0;
+  for (const el of elements) {
+    let raw: ApproverVerdict;
+    let error: true | undefined;
+    try {
+      raw = await el.run(req);
+    } catch {
+      raw = "ask";
+      error = true;
+    }
+    const { verdict, clamped } = error === undefined ? clampVerdict(raw, el.clazz, el.mayAllow) : { verdict: "ask" as ElementVerdict };
+    evaluated.push({
+      element: el.name,
+      level: el.level,
+      verdict,
+      ...(clamped !== undefined ? { clamped } : {}),
+      ...(error !== undefined ? { error } : {}),
+      rank: LEVEL_RANK[el.level],
+      order: order++,
+    });
+  }
+
+  const results: ChainElementResult[] = evaluated.map(({ rank: _r, order: _o, ...rest }) => rest);
+  const registryBaseline = registryVerdictOf(req.tool);
+
+  // 3. DENY IS ABSOLUTE — and it SKIPS the transforms structurally (a transform may never lift it).
+  const denies = evaluated.filter((e) => e.verdict === "deny").sort((a, b) => a.rank - b.rank || a.order - b.order);
+  if (denies.length > 0) {
+    return {
+      verdict: "deny",
+      resolvedBy: denies[0]!.element, // first in level order, for the row — the OUTCOME is order-independent
+      registryVerdict: registryBaseline,
+      elements: results,
+      transforms: [],
+      tainted: taintedOf(req),
+      denyAbsolute: true,
+    };
+  }
+
+  // 4. Positional resolve: first non-defer in level order. The registry is terminal, so this
+  //    always lands — the fallback ask below is unreachable by construction and exists fail-closed.
+  const positional = evaluated.filter((e) => e.verdict !== "defer").sort((a, b) => a.rank - b.rank || a.order - b.order);
+  const first = positional[0];
+  let verdict: "allow" | "ask" = first === undefined || first.verdict === "ask" ? "ask" : "allow";
+  let resolvedBy = first?.element ?? "registry";
+
+  // Consulted only when every gate agrees: the caller opted in, the ask came from a PER-VERB DEFAULT (an operator or surface ask is pinned policy), the row is defer-flipped, and the deployment is armed.
+  // Runs BEFORE the transforms, so every clamp — including unattended's ask→deny — applies to what the judge resolved.
+  let judgeRun: ApprovalJudgeRun | undefined;
+  if (
+    opts.judge === true &&
+    verdict === "ask" &&
+    (resolvedBy === "registry" || resolvedBy === "verb-classifier") &&
+    judgeDeferredTool(req.tool) &&
+    approvalJudgeMode() === "enforce"
+  ) {
+    const humanOnly = judgeHumanOnlyReason(req);
+    if (humanOnly !== undefined) {
+      // THE HUMAN-ONLY CLASS (OPE-2101): no model is called, and the verdict stays the ask that
+      // lands on a card. Recorded as a consult (source `human-only`) so the audit row says why.
+      judgeRun = {
+        verdict: "defer",
+        source: "human-only",
+        reasoning: humanOnly,
+        cacheKey: judgeVerdictCacheKey(req.tool),
+        cacheHit: false,
+        passes: 0,
+      };
+    } else if (await approvalJudgeAdminDisarmed(req.domain, req.org)) {
+      // An operator turned the judge off for this address, so the chain degrades to its pre-judge self. Recorded as a consult (source `admin-disarm`) so the disarm is queryable per affected row.
+      // A domain-less request reads the ORG-WIDE address, so the reasoning names which address an operator must re-arm.
+      judgeRun = {
+        verdict: "defer",
+        source: "admin-disarm",
+        reasoning:
+          req.domain === undefined
+            ? `judge disarmed org-wide for domain-less actions by an operator (${APPROVAL_JUDGE_ADMIN_DISARM}) — re-arm with the control plane's rearm_approval_judge with orgWide: true`
+            : `judge disarmed for this domain by an operator (${APPROVAL_JUDGE_ADMIN_DISARM}) — re-arm with the control plane's rearm_approval_judge`,
+        cacheKey: judgeVerdictCacheKey(req.tool),
+        cacheHit: false,
+        passes: 0,
+      };
+    } else {
+      judgeRun = await runApprovalJudge(judgeContextOf(req, { registryVerdict: registryBaseline }, opts.rules), {
+        enforce: true,
+        timeoutMs: JUDGE_ENFORCE_TIMEOUT_MS,
+      });
+      if (judgeRun.verdict === "deny") {
+        // A judge deny is FINAL like any element's — it skips the transform pipeline the same
+        // structural way an element deny does. NOTE (the ticket's rollout ask): the FIRST LIVE
+        // DENY this branch produces deserves individual review — pull its
+        // `approval.judge.verdict` row and check the reasoning before trusting the class.
+        return {
+          verdict: "deny",
+          resolvedBy: "judge",
+          registryVerdict: registryBaseline,
+          elements: results,
+          transforms: [],
+          tainted: taintedOf(req),
+          denyAbsolute: true,
+          judge: judgeRun,
+        };
+      }
+      if (judgeRun.verdict === "allow") {
+        verdict = "allow";
+        resolvedBy = "judge";
+      }
+      // ask/defer/timeout: the last-resort ask — the row lands exactly where it was before its
+      // flip, and the transforms below (taint, floor, unattended) treat it as the ask it is.
+    }
+  }
+
+  // 5. Transforms, in stage order, each only where its arrow's precondition matches. A transform
+  //    error (fires/to throwing) leaves the verdict UNCHANGED — recorded nowhere as a verdict
+  //    change, exactly the "no-fire" posture.
+  const transforms: AppliedTransform[] = [];
+  for (const stage of TRANSFORM_STAGE_ORDER) {
+    for (const row of TRANSFORM_TABLE) {
+      if (row.stage !== stage) continue;
+      let firing = false;
+      try {
+        firing = row.fires(req);
+      } catch {
+        continue; // transform error ⇒ verdict unchanged
+      }
+      if (!firing || !(row.from as readonly string[]).includes(verdict)) continue;
+      let next: "allow" | "ask" | "deny";
+      try {
+        next = row.to(req, registryBaseline);
+      } catch {
+        continue; // transform error ⇒ verdict unchanged
+      }
+      if (next === verdict) continue; // no movement — not an applied transform
+      transforms.push({ name: row.name, from: verdict, to: next, ...(row.reason !== undefined ? { reason: row.reason } : {}) });
+      if (next === "deny") {
+        // A transform-produced deny ends the pipeline: later arrows only move allow/ask, and
+        // nothing may move a deny (same invariant as step 3, now from the tightening side).
+        return {
+          verdict: "deny",
+          resolvedBy,
+          registryVerdict: registryBaseline,
+          elements: results,
+          transforms,
+          tainted: taintedOf(req),
+          ...(judgeRun !== undefined ? { judge: judgeRun } : {}),
+        };
+      }
+      verdict = next;
+    }
+  }
+
+  return {
+    verdict,
+    ...(verdict === "ask" ? { askVariant: "blocking" as AskVariant } : {}),
+    resolvedBy,
+    registryVerdict: registryBaseline,
+    elements: results,
+    transforms,
+    tainted: taintedOf(req),
+    ...(judgeRun !== undefined ? { judge: judgeRun } : {}),
+  };
+}
+
+/** One producer for the `approval.chain` audit row and for the simulator's trace, so the retrospective row and the prospective simulation can never drift. It answers "why was there no card?" with `resolvedBy` plus `transforms`. */
+export function chainAuditDetail(req: ApprovalChainRequest, res: ChainResolution): Record<string, unknown> {
+  return {
+    tool: req.tool,
+    ...(req.action !== undefined ? { action: req.action } : {}),
+    verdict: res.verdict,
+    ...(res.askVariant !== undefined ? { askVariant: res.askVariant } : {}),
+    resolvedBy: res.resolvedBy,
+    registryVerdict: res.registryVerdict,
+    elements: res.elements.map((e) => ({
+      element: e.element,
+      level: e.level,
+      verdict: e.verdict,
+      ...(e.clamped !== undefined ? { clamped: e.clamped } : {}),
+      ...(e.error !== undefined ? { error: e.error, reason: "element-error" } : {}),
+    })),
+    transforms: res.transforms.map((t) => ({ name: t.name, from: t.from, to: t.to, ...(t.reason !== undefined ? { reason: t.reason } : {}) })),
+    ...(res.denyAbsolute !== undefined ? { denyAbsolute: true } : {}),
+    // The judge CONSULT (OPE-318 phase 2), when one happened — a summary here beside the chain
+    // facts; the per-consult `approval.judge.verdict` row (flow.ts) carries the full record.
+    ...(res.judge !== undefined
+      ? {
+          judge: {
+            verdict: res.judge.verdict,
+            source: res.judge.source,
+            passes: res.judge.passes,
+            cacheHit: res.judge.cacheHit,
+            ...(res.judge.pass1 !== undefined ? { pass1: res.judge.pass1 } : {}),
+          },
+        }
+      : {}),
+    unattended: req.unattended,
+    // THE DISCLOSURE PAIR (OPE-307). `tainted` is the fact; `taintKinds` is what makes it usable —
+    // a row saying only "tainted: true" cannot answer "from what?", which is the whole question once
+    // taint stopped changing the verdict. Omitted when empty rather than written as `[]`, so an
+    // untainted row (and a seeded row with no breakdown) is byte-identical to before.
+    tainted: taintedOf(req),
+    ...(taintedOf(req) && chainTaintKinds().length > 0 ? { taintKinds: [...chainTaintKinds()] } : {}),
+    // OPE-399: and WHY it is false, when the answer is "the model is off". Omitted on an `on`
+    // deployment, so the row every existing query reads is unchanged.
+    ...taintModeNote(),
+    ...(req.mode !== undefined ? { mode: req.mode.mode } : {}),
+    ...(req.domain !== undefined ? { domain: req.domain } : {}),
+  };
+}
+
+/** The human-readable resolution trace — `explain_permission`'s renderer, derived from {@link chainAuditDetail}'s fields so both surfaces and the audit row stay one vocabulary. */
+export function renderChainResolution(req: ApprovalChainRequest, res: ChainResolution): string[] {
+  const lines: string[] = [];
+  lines.push(`${req.tool}${req.action !== undefined ? ` (action ${req.action})` : ""} → ${res.verdict.toUpperCase()}${res.askVariant !== undefined ? ` (${res.askVariant})` : ""}`);
+  lines.push(`resolved by: ${res.resolvedBy}${res.denyAbsolute !== undefined ? " — DENY IS ABSOLUTE (transforms skipped)" : ""}`);
+  lines.push(`registry baseline: ${res.registryVerdict}${res.verdict !== res.registryVerdict ? "  ⚠ diverged — see elements/transforms" : ""}`);
+  if (res.judge !== undefined) {
+    lines.push(`judge consult: ${res.judge.verdict} (${res.judge.source}, ${res.judge.passes} pass${res.judge.passes === 1 ? "" : "es"}${res.judge.cacheHit ? ", cache hit" : ""}) — ${res.judge.reasoning}`);
+  }
+  lines.push("elements (level order):");
+  for (const e of res.elements) {
+    const marks = [e.clamped !== undefined ? "clamped→defer" : undefined, e.error !== undefined ? "element-error→ask" : undefined]
+      .filter((m): m is string => m !== undefined)
+      .join(", ");
+    lines.push(`  [${e.level}] ${e.element}: ${e.verdict}${marks.length > 0 ? ` (${marks})` : ""}`);
+  }
+  if (res.transforms.length === 0) {
+    lines.push("transforms: (none applied)");
+  } else {
+    lines.push("transforms (in order):");
+    for (const t of res.transforms) lines.push(`  ${t.name}: ${t.from} → ${t.to}${t.reason !== undefined ? ` (${t.reason})` : ""}`);
+  }
+  // A supplied `req.tainted` is a bit from elsewhere (a simulation input, or a value frozen at propose time), while {@link chainTaintKinds} always reads the turn that RESOLVES the chain.
+  // So a supplied bit carries NO breakdown and names itself, and the live signal prints beside it rather than replacing it.
+  const supplied = req.tainted !== undefined;
+  const kinds = !supplied && taintedOf(req) ? chainTaintKinds() : [];
+  const liveTainted = chainTaintSignal();
+  const liveKinds = supplied && liveTainted ? chainTaintKinds() : [];
+  const context = [
+    `unattended: ${req.unattended}`,
+    // The taint-off suffix is what stops `explain_permission` from telling a reader "tainted: false"
+    // on a deployment where that sentence could never have said anything else (OPE-399).
+    `tainted: ${taintedOf(req)}${kinds.length > 0 ? ` (${kinds.join(", ")})` : ""}` +
+      (supplied ? ` — supplied by the caller, not this turn's own signal (this turn: ${liveTainted}${liveKinds.length > 0 ? ` (${liveKinds.join(", ")})` : ""})` : "") +
+      (taintMode() === "off" ? " — taint.mode: off (the model is not running)" : ""),
+    ...(req.mode !== undefined ? [`mode: ${req.mode.mode}`] : []),
+    // Printed only when the halt is ON: a request that resolved no halt and one that resolved "not halted" are both nothing to say, and `halt: false` would claim the reader asked a question this request may never have asked.
+    ...(req.halted === true ? ["halt: ON"] : []),
+  ];
+  lines.push(`context: ${context.join(" · ")}`);
+  return lines;
+}
+
+/** No domain, no config or no declared mode ⇒ undefined, so no transform fires. Fail-soft on a missing config registration, because a mode can only ever be deliberate, registered config. */
+export function approvalModeForDomain(domain: string | undefined): ApprovalModeConfig | undefined {
+  if (domain === undefined) return undefined;
+  try {
+    return getConfig().loadDomains().find((d) => d.name === domain)?.approvalMode;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The L1 operator approvers bound to `scopeKey`, resolved through the REAL access resolver so the band is exactly what the scope's bundles grant. A non-surface key or a missing config resolves the EMPTY band, never a guess.
+ * ⚠️ Resolved in `channel` mode deliberately: the approvers plane is org policy, so a DM-proposed action still answers to the org's approvers.
+ */
+export function approversForScopeKey(scopeKey: string | undefined, domain: string | undefined): readonly OperatorApprover[] {
+  if (scopeKey === undefined) return [];
+  const parts = scopeKey.split("/");
+  if (parts.length !== 3 || parts.some((p) => p.length === 0)) return [];
+  const [platform, workspace, channel] = parts as [string, string, string];
+  try {
+    const cfg = getConfig();
+    const domains = domain !== undefined ? [domain] : cfg.domainsForSurface({ workspaceKey: `${platform}/${workspace}`, surface: channel });
+    return resolveAccess({ mode: "channel", platform, workspace, channel, domains }, cfg.loadBundles(), cfg.loadBindings(), cfg.pluginRegistry, cfg.loadConnectorCredentials?.() ?? []).approvers;
+  } catch {
+    return []; // fail-soft to the built-in levels — an unresolvable scope must not crash a propose
+  }
+}
+
+/**
+ * The scope's admin-authored pre-approval rules, resolved through the REAL access resolver; a non-surface key or a missing config resolves the EMPTY set, never a guess.
+ * 🔴 The only source is the config repo's bundles — this takes a scope key, never a path, so a repository the agent checked out to work on can never contribute a rule.
+ */
+export function preApprovalRulesForScopeKey(
+  scopeKey: string | undefined,
+  domain: string | undefined,
+): readonly ResolvedPreApprovalRule[] {
+  if (scopeKey === undefined) return [];
+  const parts = scopeKey.split("/");
+  if (parts.length !== 3 || parts.some((p) => p.length === 0)) return [];
+  const [platform, workspace, channel] = parts as [string, string, string];
+  try {
+    const cfg = getConfig();
+    const domains = domain !== undefined ? [domain] : cfg.domainsForSurface({ workspaceKey: `${platform}/${workspace}`, surface: channel });
+    return resolveAccess({ mode: "channel", platform, workspace, channel, domains }, cfg.loadBundles(), cfg.loadBindings(), cfg.pluginRegistry, cfg.loadConnectorCredentials?.() ?? []).preApprovalRules;
+  } catch {
+    return []; // fail-soft: an unresolvable scope means no authored rules, never a guessed one
+  }
+}
+
+let kindToTool: ReadonlyMap<string, string> | undefined;
+
+/** The tool whose `TOOL_CONSEQUENCE` row names this ActionKind. Undefined for the non-tool kinds, where the caller falls back to the kind string and an unknown name resolves fail-closed `ask` at the terminal. */
+export function toolForActionKind(kind: string): string | undefined {
+  if (kindToTool === undefined) {
+    const m = new Map<string, string>();
+    for (const [tool, entry] of Object.entries(TOOL_CONSEQUENCE)) {
+      if (entry.via.kind === "action-kind") m.set(entry.via.action, tool);
+    }
+    kindToTool = m;
+  }
+  return kindToTool.get(kind);
+}