@open-everywhere/core 0.1.0

package/agent/approvals/arming-context.ts

@@ -0,0 +1,26 @@
+// An approval click executes OUTSIDE any eve session, so this rides AsyncLocalStorage: `defineState` would throw there every time, and a module global would let two concurrently-served clicks read each other's card.
+// Fail-soft always: a caller outside a decide reads `undefined` and records provenance with no approval id.
+// Nothing here is a security control — it never widens what a click may do, and no authorisation decision may be taken on it.
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+export interface ArmingApproval {
+  /** `pending_actions.id` — the join key to the frozen args and the `approval.*` audit rows. */
+  readonly id: string;
+  readonly kind: string;
+}
+
+const store = new AsyncLocalStorage<ArmingApproval>();
+
+/**
+ * Run `fn` with `approval` readable by anything it awaits. Called once, by the decide core around
+ * `ActionKind.execute` — do NOT wrap anything else, or "armed by this card" stops being true.
+ */
+export function withArmingApproval<T>(approval: ArmingApproval, fn: () => Promise<T>): Promise<T> {
+  return store.run(approval, fn);
+}
+
+/** The card whose click is executing right now, or `undefined` outside a decide. */
+export function armingApproval(): ArmingApproval | undefined {
+  return store.getStore();
+}

package/agent/approvals/card-disclosure.ts

@@ -0,0 +1,53 @@
+// An approval card NEVER lands in a room with an OBSERVED external guest, because the card is a complete rendering of what will execute. The check is ROOM-GRAIN — it reads the room's roster and nothing about the card's kind, tier or content — and it fails OPEN on an unobservable roster, refusing only on a positively observed guest.
+
+import { resolveAudienceFloor, type AudienceFloor, type RoomRoster } from "../access/audience-floor.js";
+
+/** `floor` rides both arms so an allow can be telemetered later without reshaping the type. */
+export type CardDisclosureVerdict =
+  | { readonly ok: true; readonly floor: AudienceFloor }
+  /** The room's audience floor POSITIVELY resolved to `guest` — today, an externally-shared Slack
+   *  channel (the CHANNEL's external bit, not a per-member classification). */
+  | { readonly ok: false; readonly reason: "audience-floor"; readonly floor: AudienceFloor };
+
+export interface CardDisclosureInput {
+  readonly floor: AudienceFloor;
+  /** The live roster the floor came from — read for its `resolved` bit (the inert rule above). */
+  readonly roster: RoomRoster;
+}
+
+/** An OBSERVED `guest` floor refuses; everything else allows, including an unobservable roster whose floor is `guest` by fail-closed default. The action kind, the approver policy and the summary lines are deliberately NOT inputs. */
+export function classifyCardDisclosure(input: CardDisclosureInput): CardDisclosureVerdict {
+  if (input.roster.resolved && input.floor === "guest") {
+    return { ok: false, reason: "audience-floor", floor: input.floor };
+  }
+  return { ok: true, floor: input.floor };
+}
+
+/** EMPTY on purpose: `guest` is decided before computeAudienceFloor consults the admin set at all, so an admin set cannot change the answer and would only drag a config load onto the propose path. */
+const NO_ADMINS: ReadonlySet<string> = new Set<string>();
+
+export interface CardDisclosureDeps {
+  readonly floor?: typeof resolveAudienceFloor;
+}
+
+/** `surfaceKey` is the card's destination `platform/workspace/channel`. FAIL-OPEN on a throw, so a transient platform blip never becomes an org that cannot approve anything. */
+export async function checkCardDisclosure(surfaceKey: string, deps: CardDisclosureDeps = {}): Promise<CardDisclosureVerdict> {
+  try {
+    const resolution = await (deps.floor ?? resolveAudienceFloor)(surfaceKey, NO_ADMINS);
+    return classifyCardDisclosure(resolution);
+  } catch (err) {
+    console.log(`[open-everywhere:approvals] audience floor unresolvable for ${surfaceKey} (${String(err)}) — card disclosure inert`);
+    return { ok: true, floor: "guest" };
+  }
+}
+
+/** The refusal is CONTENT-FREE by construction: it names no action kind, figure, domain or scope, only the property of the ROOM and the one concrete thing to do about it. */
+export function cardDisclosureRefusalNotice(): string {
+  return (
+    "I can't put an approval card in this channel. Its audience floor resolved to \"guest\" — the " +
+    "platform reports it as externally shared, or carrying an observed guest — and an approval card " +
+    "spells out exactly what would execute, so posting one here would show that to people outside " +
+    "your org. Nothing about the action is in this message, deliberately. Ask me again in a channel " +
+    "that isn't shared outside your org (or remove the external members) and it will work as normal."
+  );
+}

package/agent/approvals/card-signal.ts

@@ -0,0 +1,151 @@
+// Two per-turn approval signals a later, disconnected call site in the same session reads: a card posted this turn, and what this run asked for and did not get. Both ride a per-session `defineState` slot — a module global would interleave concurrently-served sessions — and both fail soft.
+
+import { defineState } from "eve/context";
+import { readTurnClock } from "../observability/turn-clock.js";
+
+const slot = defineState<boolean>("open-everywhere.approval-card-posted", () => false);
+
+/** Mark that an approval card was actually posted this turn. Call it ONLY after the post succeeds — never on a validation or refusal path, whose thrown error is exactly the text the user still needs to see. */
+export function markCardPostedThisTurn(): void {
+  try {
+    slot.update(() => true);
+  } catch {
+    /* no session context here — nothing to signal, never blocks the propose tool */
+  }
+}
+
+/** Peek without consuming: is the card signal currently set? For a mid-turn reader that must NOT disturb the read-and-reset contract message.completed owns, and fail-soft — no session context reads false. */
+export function peekCardPostedThisTurn(): boolean {
+  try {
+    return slot.get();
+  } catch {
+    return false;
+  }
+}
+
+/** Read-and-reset: was a card posted this turn? It always clears the slot in the same call, so the next turn starts clean whether or not this one posted a card. */
+export function consumeCardPostedThisTurn(): boolean {
+  try {
+    const was = slot.get();
+    slot.update(() => false);
+    return was;
+  } catch {
+    return false;
+  }
+}
+
+// The per-run complement of `list_routines.permissionAsks`: what THIS run asked for and did not get, rendered at the delivery chokepoint. Only the HOST writes here, and every field is host-derived, so no model text can reach a reader through this channel.
+
+/** One permission this run asked for and did not get. */
+export interface RoutineRunPermissionRefusal {
+  /** The permission in plain language — the same words `list_routines` uses for a live permission. */
+  readonly permission: string;
+  /** Where its card is, as a PERMALINK — null whenever the surface minted none, which is every Teams and Linear card and any card whose row could not be read. Never the room id: this block rides every reply, so a raw `platform/workspace/channel` triple would print the card room's internal ids into another window. */
+  readonly card: string | null;
+  /** Is there a card on a surface at all? Answered from the PLANNER's own `cardId` and never from a pointer read, which answers `{}` on any throw — a live card would then report `cardPosted: false` and send an owner to the `edit_routine` bump that destroys it. */
+  readonly cardPosted: boolean;
+  /** Did this run give up on the card plane for this permission WITHOUT consulting it, because the per-fire cap was already spent? It is not "no card": the run never looked, so both other absence arms would lie, and the entry exists so the cap costs a card and never a report line. */
+  readonly cardCapped: boolean;
+  /** Did this run ESTABLISH what became of the card? False ONLY when the card store could not be read: a null pointer must never render as "no card is waiting", which would send an owner to `edit_routine` and kill the card the failed read could not see. */
+  readonly cardKnown: boolean;
+}
+
+/** The ledger, KEYED ON THE TURN. A bare slot is not per-turn: `defineState` rides the session container, and a `job` routine keeps one session across fires, so a fire that posts nothing would leave its entries to surface days later on another fire's report. */
+interface RunRefusalLedger {
+  /**
+   * The wake this ledger was CARRIED OVER for, set only by {@link carryRunRefusalsToRedrive}.
+   * 🔴 WHY A SECOND KEY EXISTS (OPE-1982). The turn key below is what stops one fire's losses
+   * surfacing on another fire's report, and it is still the primary key. But a fire whose turn ends
+   * in prose no longer posts at all: the prose is dropped and ONE corrective wake is re-injected,
+   * and that correction is a NEW TURN. Without this the turn key alone would drop the ledger exactly
+   * when the fire's report was about to be written, and the room would never hear the host's
+   * "could not do X" line — the guarantee the deleted prose bridge used to hold by posting the
+   * refusal-framed body itself. The corrective wake RE-STAMPS THE ORIGINAL WAKE ID, so that id is
+   * the one thing both turns share, and it is what the carry keys on.
+   */
+  readonly carriedForWakeId?: string;
+  readonly turnId: string;
+  readonly entries: readonly RoutineRunPermissionRefusal[];
+}
+
+const refusals = defineState<RunRefusalLedger | null>("open-everywhere.routine-run-permission-refusals", () => null);
+
+/** How many permissions one run's report lists; past the cap the ledger stops recording and never drops what it already holds. The card-offer cap reuses the number, which does NOT make the two counts equal — that cap counts offers through one seam, this ledger counts refusals from both refusal planes. */
+export const MAX_RUN_REFUSALS = 16;
+
+/** The turn key a CARRIED ledger holds. It is not a real turn id and never equals `currentTurnKey()`
+ *  — including its `""` reading — so a carried ledger is reachable only through its wake. */
+const CARRIED_TURN_KEY = "carried:redrive";
+
+/** This turn's id, or "" when no turn clock has been started. "" is a fine key: it never equals a
+ *  real `turn_<n>`, so an entry left by a real turn can never be read back under it. */
+function currentTurnKey(): string {
+  return readTurnClock()?.turnId ?? "";
+}
+
+/** Record one permission this run was refused; call it AFTER the refusal is settled, so `card` names what is really in the room. De-duplicated by permission, and the FIRST entry wins — it is the one whose pointer was resolved beside the card that was posted. */
+export function noteRoutineRunPermissionRefusal(entry: RoutineRunPermissionRefusal): void {
+  try {
+    const turnId = currentTurnKey();
+    refusals.update((prev) => {
+      const entries = prev !== null && prev.turnId === turnId ? prev.entries : [];
+      if (entries.some((e) => e.permission === entry.permission) || entries.length >= MAX_RUN_REFUSALS) return { turnId, entries };
+      return { turnId, entries: [...entries, entry] };
+    });
+  } catch {
+    /* no session context here — nothing to record, never blocks the refusal */
+  }
+}
+
+/**
+ * Read-and-reset: what did this run ask for and not get? The reset is at READ, not at post, so a post that then fails loses the block for this run — the standing record still answers the same question from the rows.
+ * `wakeId` is the wake the caller is ANSWERING. It admits a ledger a previous turn handed to this wake's one corrective re-drive ({@link carryRunRefusalsToRedrive}); pass it wherever the caller knows which conversation it is answering, and omit it where it does not — omitting it only ever reads the turn key, which is the behaviour this function had before the carry existed.
+ */
+export function consumeRoutineRunPermissionRefusals(wakeId?: string): readonly RoutineRunPermissionRefusal[] {
+  try {
+    const held = refusals.get();
+    if (held === null) return [];
+    // A ledger from an EARLIER turn is not this run's, and reading it would attach one run's losses
+    // to another run's report. Dropped rather than returned — and dropped rather than left, so the
+    // container does not carry it further.
+    // THE ONE EXCEPTION is a ledger explicitly handed to THIS WAKE's corrective turn: same fire, same
+    // conversation, one turn later, and the carry was written by the host rather than inferred here.
+    const carried = held.carriedForWakeId !== undefined && wakeId !== undefined && held.carriedForWakeId === wakeId;
+    const mine = held.turnId === currentTurnKey() || carried ? held.entries : [];
+    // 🔴 CLEAR ONLY WHAT THIS CALL CLAIMED. A CARRIED ledger belongs to one wake, and a coalesced
+    // turn answers several: a reply to some OTHER wake must not destroy the fire's report on its way
+    // past. An unclaimed ledger that is NOT carried is still dropped, which is the original rule —
+    // a stale turn-keyed ledger is nobody's and must not be left to surface later.
+    if (mine.length > 0 || held.carriedForWakeId === undefined) refusals.update(() => null);
+    return mine;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Hand this turn's held refusals to the ONE corrective re-drive of `wakeId`, so the fire's report still carries them when the seat answers on the corrective turn (OPE-1982). Called by the unified window's drop branch, and ONLY when a re-drive really fired.
+ * 🔴 IT RE-KEYS, IT DOES NOT COPY. The turn key is cleared to a value no real turn can hold, so the carried ledger is readable ONLY by a caller that names this wake.
+ * 🔴 AND IT CARRIES ONLY THIS TURN'S OWN LEDGER. A `job` routine keeps ONE session across fires, and a fire whose turn ended in judged silence leaves its entries in the slot unconsumed — the silence arm returns before the drop branch and nothing clears them there. Without the turn check a LATER fire's drop would re-key that stranded ledger onto its own wake, and its corrective reply would report a permission it never asked for, pointing at a card minted in another conversation. That is the precise harm the turn key exists to prevent, so the carry honours it rather than stepping around it.
+ * A no-op when nothing is held, when the held ledger belongs to another turn, or outside a session, so an ordinary drop writes nothing.
+ */
+export function carryRunRefusalsToRedrive(wakeId: string): void {
+  try {
+    const turnId = currentTurnKey();
+    refusals.update((prev) => (prev === null || prev.entries.length === 0 || prev.turnId !== turnId ? prev : { carriedForWakeId: wakeId, turnId: CARRIED_TURN_KEY, entries: prev.entries }));
+  } catch {
+    /* no session context — nothing to carry, and never blocks the drop */
+  }
+}
+
+/**
+ * Drop a ledger carried to `wakeId` because its correction is EXHAUSTED — the corrective turn ended without answering, and there is no second re-drive. Without this the entries would sit in the session container until some later turn happened to name the same wake.
+ * It drops ONLY a ledger carried for this exact wake: a live ledger belonging to the CURRENT turn is somebody else's and is left alone.
+ */
+export function dropCarriedRunRefusals(wakeId: string): void {
+  try {
+    refusals.update((prev) => (prev !== null && prev.carriedForWakeId === wakeId ? null : prev));
+  } catch {
+    /* no session context — nothing to drop */
+  }
+}

package/agent/approvals/card-venue.ts

@@ -0,0 +1,152 @@
+// Where an approval card goes when the asking room cannot host one: a card-capable room in the SAME domain, never outside it, with every input host-derived. Redirecting AWAY from a guest-floored room that CAN host a card is not licensed here — that stays a refusal.
+
+import { domainForChannel, domainRoster, type Domain } from "../memory/domain.js";
+import { domainKeyOf, type Partition } from "../memory/partition.js";
+import type { SurfaceBinding } from "../identity/binding.js";
+import { postedToSurfaceKey, type PriorRejection } from "./flow.js";
+import { checkCardDisclosure, type CardDisclosureDeps } from "./card-disclosure.js";
+import { hasApprovalCardPath } from "../tools/set_spend_limit.js";
+
+/** A resolved place to post an approval card. */
+export interface ApprovalVenue {
+  /** The platform whose CardPoster renders + posts it (drives approvalPostDeps). */
+  readonly platform: string;
+  /** The channel id the card is posted into (PendingActionRow.channelId). */
+  readonly channelId: string;
+  /** Fully-qualified `platform/workspace/surface` of that channel — the pending's `postedTo`. */
+  readonly surfaceKey: string;
+  /** Is this the room the request came from? False ⇒ the caller MUST say where the card went. */
+  readonly sameRoom: boolean;
+}
+
+/** Why no venue could be resolved — carried so the refusal can name the config to change. */
+export interface ApprovalVenueRefusal {
+  readonly reason:
+    | "no-domain"
+    | "no-card-channel"
+    /** The domain has card-capable channels and every one of them positively floors to `guest`. Only {@link checkApprovalVenue} can produce it, because the pure walk cannot see a floor. */
+    | "no-internal-card-channel";
+  readonly domain?: string;
+}
+
+export type ApprovalVenueResult = { readonly venue: ApprovalVenue } | { readonly refusal: ApprovalVenueRefusal };
+
+/** Resolve the venue, PURE: this room if it can host a card, else the first card-capable channel of its explicit domain in declaration order, else a refusal naming what to add. FLOOR-BLIND, so {@link checkApprovalVenue} is the production entry; a channel in no explicit domain gets no venue. */
+export function approvalVenueFor(
+  binding: SurfaceBinding,
+  partition: Partition,
+  /** LAZY on purpose: the overwhelmingly common path (a Slack or Discord room hosting its own card)
+   *  returns before this is called, so `create_routine` on a card-capable surface reads no config at
+   *  all and stays exactly as cheap — and as test-constructible — as it was before OPE-148. */
+  loadDomains: () => readonly Domain[],
+): ApprovalVenueResult {
+  const own = ownRoomVenue(binding);
+  if (own) return { venue: own };
+  const candidates = inDomainVenues(partition, loadDomains);
+  if ("refusal" in candidates) return candidates;
+  const first = candidates.venues[0];
+  return first ? { venue: first } : { refusal: { reason: "no-card-channel", domain: candidates.domain } };
+}
+
+/** Step 1 of the order above, extracted so the pure walk and {@link checkApprovalVenue} cannot
+ *  disagree about what "this room can host its own card" means. */
+function ownRoomVenue(binding: SurfaceBinding): ApprovalVenue | undefined {
+  const ownChannelId = typeof binding.target?.["channelId"] === "string" ? (binding.target["channelId"] as string) : undefined;
+  if (!hasApprovalCardPath(binding.platform) || !ownChannelId) return undefined;
+  return { platform: binding.platform, channelId: ownChannelId, surfaceKey: postedToSurfaceKey(binding, ownChannelId), sameRoom: true };
+}
+
+/** Step 2: EVERY card-capable channel in this room's explicit domain, in declaration order. It enumerates rather than short-circuiting because the operator's first-listed channel can itself be externally shared, and a redirect that stops there just moves the leak. */
+function inDomainVenues(
+  partition: Partition,
+  loadDomains: () => readonly Domain[],
+): { readonly venues: readonly ApprovalVenue[]; readonly domain: string } | { readonly refusal: ApprovalVenueRefusal } {
+  const domain = domainForChannel(domainKeyOf(partition), loadDomains());
+  if (!domain) return { refusal: { reason: "no-domain" } };
+  const venues: ApprovalVenue[] = [];
+  for (const ch of domainRoster(domain)) {
+    const segs = ch.split("/");
+    // A card-capable surfaceKey's THIRD segment is literally the channel id, which is the only reason a configured key can become a poster target with no binding. That holds for exactly the platforms `hasApprovalCardPath` admits, so the check stays inside the loop.
+    if (segs.length !== 3) continue;
+    const platform = segs[0] as string;
+    const channelId = segs[2] as string;
+    if (channelId.length === 0 || !hasApprovalCardPath(platform)) continue;
+    venues.push({ platform, channelId, surfaceKey: ch, sameRoom: false });
+  }
+  return { venues, domain: domain.name };
+}
+
+/** The floor-aware venue: a REDIRECT candidate whose audience floor positively resolves to `guest` is skipped and the walk continues. The own room is deliberately not floor-checked, because redirecting out of it would launder external provenance into an internal approval room, and this never replaces the propose-time gate. */
+export async function checkApprovalVenue(
+  binding: SurfaceBinding,
+  partition: Partition,
+  loadDomains: () => readonly Domain[],
+  deps: CardDisclosureDeps = {},
+): Promise<ApprovalVenueResult> {
+  const own = ownRoomVenue(binding);
+  if (own) return { venue: own };
+  const candidates = inDomainVenues(partition, loadDomains);
+  if ("refusal" in candidates) return candidates;
+  for (const venue of candidates.venues) {
+    if ((await checkCardDisclosure(venue.surfaceKey, deps)).ok) return { venue };
+  }
+  // Which refusal depends on whether there was anything to reject: an empty candidate list means the domain has no card path at all, and a wholly-rejected one means every card path it has is shared outside the org.
+  return {
+    refusal: { reason: candidates.venues.length === 0 ? "no-card-channel" : "no-internal-card-channel", domain: candidates.domain },
+  };
+}
+
+/** The refusal a caller shows a human — it names the exact config change, never just the blockage. `action` is the verb in the reader's own terms, and it defaults to create_routine's original wording. */
+export function describeVenueRefusal(refusal: ApprovalVenueRefusal, platform: string, action = "set that up"): string {
+  if (refusal.reason === "no-domain") {
+    return (
+      `I can't ${action} from here: "${platform}" has no approval-card path, and this channel isn't in an explicit domain, so there's nowhere in-domain to put the card a human has to click. ` +
+      `Add this channel to a domain (agent/memory/config/domains/<name>.ts) that also contains a Slack or Discord channel, or ask me in one of those channels.`
+    );
+  }
+  if (refusal.reason === "no-internal-card-channel") {
+    // Deliberately does NOT say "ask somewhere that isn't shared": the reader is not standing in the offending room, and the shared room was chosen by domain config on their behalf. It names no channel id either — the domain is the smallest handle that unblocks them.
+    return (
+      `I can't ${action} from here: "${platform}" has no approval-card path, so the card has to go to a Slack or Discord channel in domain "${refusal.domain}" — and every one of those is shared outside your org (or has an observed guest), so an approval card there would spell out exactly what would execute to people outside it. ` +
+      `Add an internal Slack or Discord channel to "${refusal.domain}".reach (agent/memory/config/domains/<name>.ts), or stop sharing the one that's there, and I'll use it.`
+    );
+  }
+  return (
+    `I can't ${action} from here: "${platform}" has no approval-card path, and domain "${refusal.domain}" has no Slack or Discord channel to put the card in. ` +
+    `Add one to "${refusal.domain}".reach (agent/memory/config/domains/<name>.ts), or ask me from a Slack or Discord channel.`
+  );
+}
+
+/** `card posted` — or `card posted in <venue>` when it landed somewhere else. */
+export function cardPostedPrefix(venue: ApprovalVenue): string {
+  return venue.sameRoom ? "card posted" : `card posted in ${venue.surfaceKey}`;
+}
+
+/** The trailing instruction a REDIRECTED card owes the model, or "" when the card is in this room. It addresses the MODEL because the tool result is the only channel through which "your confirmation is in another room" reaches a human here. */
+export function describeVenueRedirect(venue: ApprovalVenue, whatNext: string): string {
+  if (venue.sameRoom) return "";
+  return ` This surface can't host an approval card, so it went to the card-capable channel in this domain — tell the user where it is, by name, and that someone there has to ${whatNext}.`;
+}
+
+/** The fixed sentence every card-path result carries (OPE-2071). The decision wake goes to the OWNING conversation session, never to the proposing call, so a proposer that waits for an answer, or calls again to get one, waits for nothing. */
+export const PROPOSER_DECISION_NOTE =
+  " The card is with the approvers. Their decision goes to the owning conversation session, not to this call. " +
+  "Do not call again for the same change: a repeat while the card is undecided returns this same pending id. Report the pending id and finish.";
+
+/** The line a result carries when a person rejected the same proposal inside the approval TTL. It informs and never blocks: a second human ask must still get its card. */
+export function describePriorRejection(prior: PriorRejection): string {
+  return (
+    ` The same proposal was REJECTED by ${prior.decidedBy} at ${prior.decidedAt}. This card stands only if a person asked again. ` +
+    `If you are retrying on your own, stop and report the rejection.`
+  );
+}
+
+/** The proposer's tail for a POSTED card: the fixed decision note, then the prior-reject line when there is one. {@link cardPostedTail} adds the venue redirect; a tool with no venue calls this directly. */
+export function proposerTail(posted: { readonly priorRejection?: PriorRejection }): string {
+  return PROPOSER_DECISION_NOTE + (posted.priorRejection !== undefined ? describePriorRejection(posted.priorRejection) : "");
+}
+
+/** THE ONE TAIL of every card-path tool result: the venue redirect (empty in the same room), then {@link proposerTail}. `posted` is required, so a tool cannot build a card-path result without the decision note. */
+export function cardPostedTail(venue: ApprovalVenue, whatNext: string, posted: { readonly priorRejection?: PriorRejection }): string {
+  return describeVenueRedirect(venue, whatNext) + proposerTail(posted);
+}

package/agent/approvals/card.ts

@@ -0,0 +1,121 @@
+// Pure Block Kit renderers — no I/O, nothing async — because the security property is that the card is a CODE-RENDERED view of the FROZEN args, never model text. `SlackBlock` is a deliberately loose structural type; Block Kit has no first-party types in this repo.
+
+import type { PendingActionRow } from "./types.js";
+import { grantButtonLabel, sessionGrantKind } from "./session-grant.js";
+
+// Duplicated from flow.ts's `OE_APPROVAL_PREFIX` rather than imported, to keep this file a leaf; approvals-test.ts pins that the two stay in sync.
+const APPROVAL_PREFIX = "oe_approval:";
+
+export interface SlackBlock {
+  readonly type: string;
+  readonly [key: string]: unknown;
+}
+
+/** A rendered card: the `blocks` payload plus Slack's required plain-text `text` fallback
+ *  (used for notifications/accessibility when a client can't render blocks). */
+export interface RenderedCard {
+  readonly blocks: readonly SlackBlock[];
+  readonly text: string;
+}
+
+function headerBlock(kind: string): SlackBlock {
+  return { type: "header", text: { type: "plain_text", text: `Approval requested: ${kind}`, emoji: true } };
+}
+
+function summarySection(summaryLines: readonly string[]): SlackBlock {
+  return { type: "section", text: { type: "mrkdwn", text: summaryLines.join("\n") } };
+}
+
+function contextBlock(text: string): SlackBlock {
+  return { type: "context", elements: [{ type: "mrkdwn", text }] };
+}
+
+/** `value` on every button is the org, because the click handler needs the org BEFORE it can look up the row and Slack's block_actions payload has nowhere else to carry it; the id rides in the action_id. */
+export function pendingCardBlocks(row: PendingActionRow, summaryLines: readonly string[]): RenderedCard {
+  const requestedContext = `Requested by <@${row.requestedBy}> · expires ${row.expiresAt}`;
+  const elements: SlackBlock[] = [
+    {
+      type: "button",
+      style: "primary",
+      text: { type: "plain_text", text: "Approve", emoji: true },
+      action_id: `${APPROVAL_PREFIX}approve:${row.id}`,
+      value: row.org,
+    },
+  ];
+  // sessionGrantKind() is the ONE predicate for the middle button, and it grants for `pr.open` alone — every other kind stays two-button per call. Old cards carry no third button, and the click grammar still parses them.
+  if (sessionGrantKind(row) !== null) {
+    elements.push({
+      type: "button",
+      // Only the LABEL differs on a routine fire's card: a permission minted there is keyed on the routine and outlives every session, so a "for session" label would make the card lie about what the click does.
+      text: { type: "plain_text", text: grantButtonLabel(row), emoji: true },
+      action_id: `${APPROVAL_PREFIX}approve_session:${row.id}`,
+      value: row.org,
+    });
+  }
+  elements.push({
+    type: "button",
+    style: "danger",
+    text: { type: "plain_text", text: "Reject", emoji: true },
+    action_id: `${APPROVAL_PREFIX}reject:${row.id}`,
+    value: row.org,
+  });
+  const blocks: SlackBlock[] = [
+    headerBlock(row.kind),
+    summarySection(summaryLines),
+    contextBlock(requestedContext),
+    { type: "actions", block_id: `oe_approval_actions:${row.id}`, elements },
+  ];
+  return { blocks, text: `Approval requested: ${row.kind}\n${summaryLines.join(" · ")}\n${requestedContext}` };
+}
+
+/** The notice for an act the armed judge lifted, which posts no card — its single button writes the `approval.judge.contradicted` row a reviewer reads. NOT an approval card: no Approve, no Reject, no expiry line, because the act is already done and this is a review surface. */
+export function judgeLiftNoticeBlocks(row: PendingActionRow, summaryLines: readonly string[], outcomeLine: string): RenderedCard {
+  const context = `⚡ Auto-approved by the approval judge — no card was posted and this has already run · ${outcomeLine}`;
+  const blocks: SlackBlock[] = [
+    { type: "header", text: { type: "plain_text", text: `Ran without asking: ${row.kind}`, emoji: true } },
+    summarySection(summaryLines),
+    contextBlock(context),
+    {
+      type: "actions",
+      block_id: `oe_approval_actions:${row.id}`,
+      elements: [
+        {
+          type: "button",
+          style: "danger",
+          text: { type: "plain_text", text: "This should not have run", emoji: true },
+          action_id: `${APPROVAL_PREFIX}contradict:${row.id}`,
+          value: row.org,
+        },
+      ],
+    },
+  ];
+  return { blocks, text: `Ran without asking: ${row.kind}\n${summaryLines.join(" · ")}\n${context}` };
+}
+
+/**
+ * The judge-lift notice for a room that cannot carry a BUTTON — every surface whose bundle registers no notice poster and that is not Slack (Teams, GitHub, Linear, Notion today).
+ * 🔴 IT IS THE SAME NOTICE, NOT A LESSER ONE. The act already ran and nobody was asked, so the trace is the whole point; only the affordance differs. Where the tap is missing the instruction is spelled out instead, and it names ONLY routes that exist — `row.id` is the id a reviewer finds the act by in the audit trail, and the operator disarm is the one verb that stops the judge lifting the next act. It must never promise a tap, a reply keyword or a command this deployment does not route: a member told to press something that is not there is exactly the silence this render replaces.
+ */
+export function judgeLiftNoticeText(row: PendingActionRow, summaryLines: readonly string[], outcomeLine: string): string {
+  return [
+    `Ran without asking: ${row.kind}`,
+    ...summaryLines,
+    `⚡ Auto-approved by the approval judge — no card was posted and this has already run · ${outcomeLine}`,
+    `This surface cannot carry the "This should not have run" button, so there is nothing to tap here. If it should not have run, say so in this conversation and quote action ${row.id} — that is the id the act is recorded under in the audit trail. An operator stops the judge lifting further acts from the control plane.`,
+  ].join("\n");
+}
+
+/** The card once a decision has landed: the same summary, with the actions block replaced by one context line. It decides nothing — it renders whatever the caller already CAS-decided. */
+export function decidedCardBlocks(row: PendingActionRow, summaryLines: readonly string[], outcomeLine: string): RenderedCard {
+  const decidedContext =
+    row.status === "approved"
+      ? `✅ Approved by <@${row.decidedBy}> · ${outcomeLine}`
+      : row.status === "rejected"
+        ? // A kind whose DECLINE is itself durable returns a line saying what the decline recorded
+          // (approvals/types.ts ActionKind.declined). Every other kind's reject passes the literal
+          // "rejected" and renders byte-for-byte what it always did.
+          `❌ Rejected by <@${row.decidedBy}>${outcomeLine === "rejected" ? "" : ` · ${outcomeLine}`}`
+        : "⏰ Expired";
+  const blocks: SlackBlock[] = [headerBlock(row.kind), summarySection(summaryLines), contextBlock(decidedContext)];
+  return { blocks, text: `Approval requested: ${row.kind}\n${summaryLines.join(" · ")}\n${decidedContext}` };
+}

package/agent/approvals/chat-dm.ts

@@ -0,0 +1,63 @@
+// This kind is reached ONCE PER PERSON, not once per message: the card gates the FIRST proactive DM to somebody and every later one flows, so never describe tier P2 as carded without saying "the first one". After that first message the model's bytes reach a person with no reviewer between. Everything the delivery needs is FROZEN at propose, because there is no ctx at decide time, and the kind is not session-grantable.
+
+import { deliverProactiveDm } from "../channels/dm-audience.js";
+import { registerActionKind, whereFromScope } from "./actions.js";
+import type { ActionKind } from "./types.js";
+
+export interface ChatDmArgs {
+  readonly org: string;
+  readonly scopeKey: string;
+  /** The RECIPIENT's platform — chooses the transport at decide time. */
+  readonly platform: string;
+  /** The recipient's bare platform member id — what `deliverDirectMessage` takes. */
+  readonly principalId: string;
+  /** The ARN-like address the grant named — the audit row's "which config line allowed this". */
+  readonly grant: string;
+  /** The model's message. Rendered in FULL on the card, because the card is the injection gate. */
+  readonly text: string;
+  /** The HOST-authored attribution + stop line, frozen at propose time. Rendered on the card too, so
+   *  the approver sees exactly what the recipient will see — including how they can stop it. */
+  readonly footer: string;
+  readonly requestedBy: string;
+  /** Proposing turn ingested untrusted content — reviewer-scrutiny flag, never auto-reject. */
+  readonly tainted?: boolean;
+}
+
+/** The card body. The recipient AND the full text AND the footer, because the card is the injection
+ *  gate and because an approver must be able to check the stop line is really there. */
+function summarizeDm(args: ChatDmArgs): string[] {
+  const lines = [
+    `Start a direct message with ${args.platform} person ${args.principalId} (granted by ${args.grant})`,
+    args.text,
+    `They will also see: ${args.footer.trim()}`,
+    "Approving this also lets later messages to this person go without a card. They can stop it from their own DM at any time.",
+  ];
+  if (args.tainted) lines.push("⚠ proposed in a turn that read external content — review before approving");
+  return lines;
+}
+
+const chatDm: ActionKind<ChatDmArgs> = {
+  kind: "chat.dm",
+  policy: "member",
+  summarize: summarizeDm,
+  async execute(args, decidedBy) {
+    // ONE delivery path, shared with the flowing arm; `first: true` is the only thing this arm says differently. It THROWS when the send did not land — Slack refuses without `im:write`, Discord when the recipient shares no server or has DMs off — because a silent failure would be the fabrication class this tier exists to avoid.
+    // 🔴 IT ALSO THROWS WHEN THE RECIPIENT STOPPED, and the read happens INSIDE the road rather than here (OPE-1855). The propose-time fence ran minutes or hours ago; a person who asks the agent to stop while their card sits open must not then receive the message the card was about.
+    await deliverProactiveDm({
+      where: whereFromScope(args.org, args.scopeKey),
+      plane: "chat.dm",
+      platform: args.platform,
+      recipientId: args.principalId,
+      address: args.grant,
+      text: args.text,
+      footer: args.footer,
+      requestedBy: args.requestedBy,
+      attributedTo: decidedBy,
+      first: true,
+      ...(args.tainted === undefined ? {} : { tainted: args.tainted }),
+    });
+    return `sent a direct message to ${args.platform} person ${args.principalId}`;
+  },
+};
+
+registerActionKind(chatDm);

package/agent/approvals/chat-post.ts

@@ -0,0 +1,60 @@
+// The gated `post_message` kind: the propose tool fences the destination and freezes everything, because there is no ctx at decide time and a row may be decided hours later. The card renders the FULL body, because the card is the injection gate. The audit row names the GRANT that allowed the post, not merely the destination, and the kind is not session-grantable.
+
+import { postSurfaceTextStrict } from "../channels/surface-message-ops.js";
+import { appendAudit } from "../audit/audit.js";
+import { registerActionKind, whereFromScope } from "./actions.js";
+import type { ActionKind } from "./types.js";
+
+export interface ChatPostArgs {
+  readonly org: string;
+  readonly scopeKey: string;
+  /** The DESTINATION's platform — chooses the transport at decide time. */
+  readonly platform: string;
+  /** The destination container's own id on that platform (a Slack channel id). */
+  readonly container: string;
+  /** The ARN-like address the grant named — the audit row's "which config line allowed this". */
+  readonly grant: string;
+  readonly text: string;
+  readonly requestedBy: string;
+  /** Proposing turn ingested untrusted content — reviewer-scrutiny flag, never auto-reject. */
+  readonly tainted?: boolean;
+}
+
+/** The card body. The destination AND the full text, because the card is the injection gate. */
+function summarizePost(args: ChatPostArgs): string[] {
+  const lines = [`Post a message into ${args.platform} container ${args.container} (granted by ${args.grant})`, args.text];
+  if (args.tainted) lines.push("⚠ proposed in a turn that read external content — review before approving");
+  return lines;
+}
+
+const chatPost: ActionKind<ChatPostArgs> = {
+  kind: "chat.post",
+  policy: "member",
+  summarize: summarizePost,
+  async execute(args, decidedBy) {
+    // `postSurfaceText` never throws and answers `undefined` on failure, but here the post IS the work, so the strict form is used: it throws the TRANSPORT'S OWN reason, which is what the human deciding this row needs, and every arm of it is token-free by construction.
+    let messageId: string;
+    try {
+      messageId = await postSurfaceTextStrict(args.platform, { channelId: args.container, text: args.text });
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err);
+      throw new Error(`chat.post: the ${args.platform} post into "${args.container}" did not land — ${reason}`);
+    }
+    await appendAudit({
+      ...whereFromScope(args.org, args.scopeKey),
+      principalId: decidedBy,
+      action: "chat.post",
+      detail: {
+        platform: args.platform,
+        container: args.container,
+        grant: args.grant,
+        messageId,
+        requestedBy: args.requestedBy,
+        tainted: Boolean(args.tainted),
+      },
+    });
+    return `posted into ${args.platform} container ${args.container}`;
+  },
+};
+
+registerActionKind(chatPost);