@open-everywhere/core 0.1.0

package/agent/routines/permission-card.ts

@@ -0,0 +1,496 @@
+// THE ROUTINE PERMISSION CARD — the planner (OPE-1290).
+//
+// WHAT THIS FILE DECIDES. A routine fire has just been refused a gated action it holds no standing
+// grant for. Four things could be true, and exactly one row-derived answer distinguishes them:
+//
+//   • a human already DECLINED this permission for this routine generation ⇒ say nothing, post
+//     nothing, and tell the model it was previously declined;
+//   • a card is already LIVE for it — a PENDING ROW says so ⇒ post nothing (one card per tool per
+//     generation), and point at that row;
+//   • the card store could not be read ⇒ post nothing and claim nothing;
+//   • no card is there ⇒ plan a fresh one for the routine's own room. Whether this routine has
+//     asked before (`lapsed`) or never has (`absent`) changes what is reported, not what is done.
+//
+// 🔴 THE STATE IS DERIVED FROM THE ROWS, NEVER FROM A CLOCK OR A MEMORY. That is the whole design:
+// a pointer to a card that is not there must be unreachable by construction. So "a card is waiting"
+// comes from the CARD'S OWN PENDING ROW, and the two memos `approvals/routine-permission.ts` writes
+// answer only what they can — that a decline was recorded, and that this routine once asked.
+//
+// WHY A PLANNER AND NOT A POSTER. `approvals/flow.ts` owns every card post in the tree, and it is
+// the module that KNOWS a refusal happened — so it does the posting. This file stays free of
+// `flow.ts` (it imports only its TYPES, which erase at runtime), which is what keeps the approvals
+// plane's one-way dependency intact. The split mirrors `session-checkpoint.ts` / `spend/checkpoint.ts`.
+//
+// THE POINTER (OPE-1356). A refusal names the card's STATE and, where the platform can express one,
+// carries a PERMALINK to the card itself. The reference is not invented here: it is read back off
+// the card's own pending row — the `channelId` and the `messageTs` `setPendingActionMessage` wrote
+// — and resolved through the one per-surface seam `channels/surface-message-ops.ts` owns. A surface
+// that mints no per-message URL yields undefined, and the clause falls back to naming the room,
+// which is true everywhere. See {@link routinePermissionCardPointer}.
+//
+// THE TIMED WAIT (OPE-1290 PR 2) hangs off every state that has a card to wait on — a `live` row,
+// and an `absent` or `lapsed` state once the fresh card has really posted. The loop and its budget
+// are `routines/permission-card-wait.ts`; what this file adds for it is {@link routineCardProbe},
+// which reads that card's row beside the grant row a click writes. The card's ID no longer needs a
+// lookup of its own: a `live` state now carries the id of the row it was derived from.
+
+import type { RequestApprovalInput } from "../approvals/flow.js";
+import {
+  ROUTINE_PERMISSION_KIND,
+  routinePermissionCardLines,
+  type RoutinePermissionArgs,
+} from "../approvals/routine-permission.js";
+import { routinePermissionAskedMemo, routinePermissionDeclinedMemo, routinePermissionKind } from "../approvals/session-grant.js";
+import type { RoutineCardProbe } from "./permission-card-wait.js";
+import { ROUTINE_PERMISSION_NO_EXPIRY, namesBundleRaisedTool, namesUnliftableTool } from "./declared-permissions.js";
+import { getOperationalStore } from "../operational/provider.js";
+import type { PendingActionRow } from "../approvals/types.js";
+import { resolveMessagePermalink } from "../channels/surface-message-ops.js";
+import { listAllRoutines, getRoutine } from "./store.js";
+import { isSilentRoutine, routineReportSurfaceKey, type Routine } from "./routine.js";
+import { routinePermissionKeyParts } from "./permission-key.js";
+import { resolveRoutineTarget } from "../schedules/routine-dispatch.js";
+
+/**
+ * What a refusal found.
+ *
+ * `n/a` and `live` are kept apart on purpose. `n/a` means this plane never had a question to
+ * answer — the refused kind is not declarable, the refusal did not come from a routine fire, the
+ * turn was tainted, the routine has no room. `live` means a real row says a card is waiting. They
+ * produce different sentences, and collapsing them is how a refusal ends up pointing at a card
+ * that was never posted.
+ *
+ * 🔴 `live` AND `lapsed` ARE THE SAME MEMO AND DIFFERENT WORLDS (OPE-1359). The ask memo is written
+ * when a card posts and is never removed by a click, so it OUTLIVES the card's pending row. Reading
+ * `live` off the memo alone therefore told a fire that a card was waiting after the card had been
+ * answered and the answer had failed to stick — an approve whose grant write failed, a decline
+ * whose memo write failed, both best-effort by design. The refusal then pointed at nothing, and no
+ * fresh card was planned either, so the routine was stuck for the rest of its generation. `live`
+ * now means the PENDING ROW is there; `lapsed` means the memo is there and the row is not, and it
+ * plans a fresh card — OPE-1290's TTL ruling exactly: "a fresh card posts only if the old row is
+ * actually gone".
+ *
+ * `unreadable` is the third arm the same split forces. `lapsed` ASSERTS the row is gone, and a card
+ * read that threw observed nothing at all; folding the two would post a second card beside a first
+ * one that is still live and clickable. It is the same distinction
+ * `routines/permission-review.ts` makes between `lapsed` and `unreadable`, for the same reason.
+ */
+export type RoutinePermissionCardState = "declined" | "live" | "lapsed" | "unreadable" | "absent" | "n/a";
+
+export { routinePermissionKeyParts };
+
+/**
+ * The grant kind a refused DECLARATION maps onto, or undefined when the declaration is not
+ * declarable.
+ *
+ * 🔴 THE CANDIDATE IS RUN BACK THROUGH THE GRANT PLANE'S OWN PARSER, which is what keeps this
+ * function from being a second vocabulary. Only what `create_routine` may declare may be carded,
+ * because the card's whole promise is "this click writes the row the creation card would have
+ * written". `approvals/session-grant.ts` `routinePermissionKind` IS that vocabulary — `pr.open` and
+ * `tool:<qualified tool>`, and nothing else — so a string it refuses gets no card and its refusal is
+ * unchanged. A declaration a creation card could never carry (`skill.create`, `memory.purge`, every
+ * ticket and spend verb, a bare `tool:notion`) lands there.
+ *
+ * TWO REFUSAL SITES REACH THIS, and they spell their declaration differently for the same reason
+ * they refuse differently. The approvals plane hands its refused ActionKind, and `pr.open` is both
+ * an ActionKind and a declaration. The connector plane (`connections/connector-auth.ts`) hands
+ * `tool:<qualified connector tool>` — the exact string its own refusal already coaches a human to
+ * declare. No ActionKind in the tree carries the `tool:` prefix, so neither site can reach the
+ * other's arm.
+ *
+ * 🔴 A DELETE-TIER VERB IS NEVER CARDED, and this is the second of the two places that says so.
+ * `routines/declared-permissions.ts` `namesUnliftableTool` is the tier test the DECLARE layer applies, and it is
+ * imported rather than re-spelled: a card offering a declaration the arming path would refuse would
+ * put a promise on a human's screen that the fence breaks on every fire. The connector fence refuses
+ * a destructive op whatever row exists, so the card could only ever be theatre.
+ *
+ * 🔴 NEITHER IS A BUNDLE-RAISED VERB (OPE-1307), and it reaches this arm by a different route. The
+ * static test above cannot see it — the tool classifies `write` and the DEPLOYMENT's bundle raises
+ * it to the delete tier — so the fence refuses it, this planner was asked to card it, and a click
+ * would have written a row the very next fire refuses again. `namesBundleRaisedTool` asks the SEAM
+ * the fence itself reads, which is the only test that can tell the two apart.
+ */
+export function declarableRoutinePermission(declaration: string): { grantKind: string; declaration: string } | undefined {
+  const grantKind = routinePermissionKind(declaration);
+  if (grantKind === null || namesUnliftableTool(declaration) || namesBundleRaisedTool(declaration)) return undefined;
+  return { grantKind, declaration };
+}
+
+/** The state, plus the card row id that a `live` answer is derived from. The id rides the answer
+ *  rather than being looked up again: the read that PROVED the card is pending is the read that
+ *  found it, so a caller can never wait on, or point at, a different row than the one the state
+ *  asserts. Undefined on every other state — there is no card. */
+export interface RoutinePermissionCardRead {
+  readonly state: RoutinePermissionCardState;
+  readonly cardId?: string;
+}
+
+/**
+ * Read the two memos, and — where a memo says this permission was asked for — the CARD ROW itself.
+ * Fail-soft to `n/a` on an unreadable memo store: a store this cannot read is a store it cannot
+ * write an ask-memo to either, so the honest answer is that nothing is known — never an invented
+ * card.
+ *
+ * 🔴 THE ASK MEMO IS NOT THE CARD (OPE-1359). It says a card was POSTED for this (routine
+ * generation, permission), and it cannot say the row is still pending — nothing removes it when a
+ * card is answered. So a memo alone buys `lapsed`, and only a pending row buys `live`. See
+ * {@link RoutinePermissionCardState} for what each of the three then does.
+ */
+export async function readRoutinePermissionCardState(
+  org: string,
+  grantKey: string,
+  grantKind: string,
+  nowIso: string,
+): Promise<RoutinePermissionCardRead> {
+  const store = getOperationalStore();
+  let asked: unknown;
+  try {
+    const declined = await store.getSessionApproval(org, grantKey, routinePermissionDeclinedMemo(grantKind), nowIso);
+    if (declined) return { state: "declined" };
+    asked = await store.getSessionApproval(org, grantKey, routinePermissionAskedMemo(grantKind), nowIso);
+  } catch {
+    return { state: "n/a" };
+  }
+  if (!asked) return { state: "absent" };
+  // The CONFIRMING read. Its own failure is `unreadable` and never `lapsed`: see the state doc.
+  const probe = await probeRoutinePermissionCard(org, grantKey, grantKind);
+  if (!probe.read) return { state: "unreadable" };
+  return probe.cardId === undefined ? { state: "lapsed" } : { state: "live", cardId: probe.cardId };
+}
+
+/** What a refusal needs to hand the planner. Every field is host-derived: the grant key comes off
+ *  the fire's own stamp, the kind off the registry. */
+export interface RoutinePermissionOffer {
+  readonly org: string;
+  /** The refused permission as a human would DECLARE it — `pr.open` from the approvals plane, or
+   *  `tool:<qualified connector tool>` from the connector plane. See
+   *  {@link declarableRoutinePermission} for why the two sites spell it differently. */
+  readonly declaration: string;
+  /** The routine's declared-permission key, off the fire's bag / the proposal's frozen sessionId.
+   *  🔴 `grantKey` is the PERSISTED wire spelling and does not move (OPE-1303) — a live card's frozen
+   *  `argsJson` already carries it, and `approvals/routine-permission.ts` parses that name back. */
+  readonly grantKey: string;
+  /** The proposing surfaceKey — the audit scope frozen on the card. */
+  readonly scopeKey: string;
+  readonly domain?: string | null;
+  /** Who the refused proposal was attributed to (a fire's attested creator). */
+  readonly requestedBy: string;
+  /** Did this turn ingest untrusted content? A tainted refusal NEVER plans a card — see below. */
+  readonly tainted: boolean;
+  readonly nowIso: string;
+}
+
+/** The planner's answer. `card` is present only for `state: "absent"`, and only when the routine
+ *  really resolves to a room. */
+export interface RoutinePermissionPlan {
+  readonly state: RoutinePermissionCardState;
+  /** The `requestApproval` input the caller should post, if any. */
+  readonly card?: RequestApprovalInput;
+  /** The pending card a `live` state found. The caller waits on this row and points at it; it never
+   *  looks the row up a second time, so the card it names is the card the state was derived from. */
+  readonly cardId?: string;
+  /** The platform the card's room lives on — the caller resolves its poster from this. */
+  readonly platform?: string;
+  /** The memo the caller writes once the card has actually posted. */
+  readonly askedMemoKind?: string;
+  /** The grant kind the card decides (also the ask-memo's subject). */
+  readonly grantKind?: string;
+}
+
+/** Find the routine a permission key names. The cheap keyed read first (the fire's own surface is the
+ *  routine's surface in every ordinary case); the scan only when that misses, which a report
+ *  destination can cause. Null rather than a guess — a card posted into the wrong conversation is
+ *  worse than no card, the same call routines/disable-notice.ts makes. */
+async function routineForPermissionKey(org: string, scopeKey: string, routineId: string): Promise<Routine | null> {
+  const keyed = await getRoutine(org, scopeKey, routineId).catch(() => null);
+  if (keyed) return keyed;
+  const all = await listAllRoutines().catch(() => [] as Routine[]);
+  return all.find((r) => r.org === org && r.id === routineId) ?? null;
+}
+
+/**
+ * Plan the card for one refusal. Never throws — a planner that throws would turn an honest refusal
+ * into a crash, and the refusal is the part that must always survive.
+ *
+ * 🔴 A TAINTED TURN PLANS NOTHING. TAINTED-NEVER is the routine plane's standing invariant
+ * (routines/declared-permissions.ts writes no row for a tainted proposal; the unattended connector fence lifts
+ * nothing on a tainted turn). A card is a request for a STANDING grant, so a turn that has read
+ * external content must not be able to raise one — otherwise fetched content chooses which
+ * permission a human is asked to arm. The refusal's own taint sentence already says no standing
+ * grant lifts it, and that stays the whole answer.
+ */
+export async function planRoutinePermissionCard(offer: RoutinePermissionOffer): Promise<RoutinePermissionPlan> {
+  try {
+    if (offer.tainted) return { state: "n/a" };
+    const declarable = declarableRoutinePermission(offer.declaration);
+    if (!declarable) return { state: "n/a" };
+    const parts = routinePermissionKeyParts(offer.grantKey);
+    if (!parts) return { state: "n/a" };
+
+    const read = await readRoutinePermissionCardState(offer.org, offer.grantKey, declarable.grantKind, offer.nowIso);
+    // `grantKind` rides EVERY state that got as far as reading a row, not just the one that plans a
+    // card: a `live` state is the other state with a card to wait on, and the wait needs the same
+    // (grantKey, grantKind) pair to read what a click would write.
+    //
+    // 🔴 TWO STATES PLAN A CARD (OPE-1359), and they are the two that agree no row is there:
+    // `absent` (never asked) and `lapsed` (asked, and the card is gone). `unreadable` plans nothing
+    // — a card this could not see is very likely still in the room, and a second one beside it is
+    // the outcome the confirming read exists to prevent.
+    if (read.state !== "absent" && read.state !== "lapsed") {
+      return { state: read.state, grantKind: declarable.grantKind, ...(read.cardId !== undefined ? { cardId: read.cardId } : {}) };
+    }
+
+    const routine = await routineForPermissionKey(offer.org, offer.scopeKey, parts.routineId);
+    if (!routine) return { state: "n/a" };
+    // 🔴 A SILENT ROUTINE GETS NO CARD. `report: {kind:"silent"}` is a human's declaration that this
+    // routine's product is an ACTION and it posts nothing into its room — `list_routines` and its
+    // own creation card both say "posts nothing". A card is a post. The self-disable notice does
+    // bypass that gate, and the reason it may is stated at routines/routine.ts: it is terminal news
+    // about the routine's own death, which a human must receive or the routine is silently gone.
+    // This is not that — a permission the routine lacks is a want, the run already refused honestly,
+    // and the owner can still declare it with `edit_routine`. So the silence holds, and the model's
+    // refusal is the whole answer.
+    if (isSilentRoutine(routine)) return { state: "n/a" };
+    // THE ROOM. `resolveRoutineTarget` is the SAME seam a fire's own reply and the self-disable
+    // notice resolve through, so the card lands exactly where this routine's output lands. The
+    // channel id is read off the resolved TARGET (`{ channelId }` on both card-carrying platforms)
+    // rather than off `origin`, whose shape is per-platform. A routine whose surface resolves to no
+    // target gets NO card rather than a guessed room — the same call disable-notice.ts makes.
+    const dest = resolveRoutineTarget(routine);
+    const channelId = readChannelId(dest?.target);
+    const surfaceKey = routineReportSurfaceKey(routine);
+    const platform = surfaceKey.split("/")[0];
+    if (!dest || channelId === undefined || platform === undefined || platform.length === 0) return { state: "n/a" };
+
+    const args: RoutinePermissionArgs = {
+      org: offer.org,
+      scopeKey: offer.scopeKey,
+      grantKey: offer.grantKey,
+      routineId: routine.id,
+      routineSurfaceKey: routine.surfaceKey,
+      grantKind: declarable.grantKind,
+      declaration: declarable.declaration,
+      prompt: routine.prompt,
+      // OPE-1627 — frozen onto the card so the clicker sees WHICH MODEL ROLE they are granting this
+      // permission for. Absent means the routine inherits the deployment's stack, and the card says
+      // so in words rather than leaving the reader to infer it from a missing line.
+      ...(routine.modelRole === undefined ? {} : { modelRole: routine.modelRole }),
+    };
+    return {
+      // The state the READ found, kept rather than flattened to `absent`: the caller's telemetry and
+      // this run's report both distinguish "it never asked" from "its last card is gone".
+      state: read.state,
+      platform,
+      grantKind: declarable.grantKind,
+      askedMemoKind: routinePermissionAskedMemo(declarable.grantKind),
+      card: {
+        org: offer.org,
+        kind: ROUTINE_PERMISSION_KIND,
+        args,
+        scopeKey: offer.scopeKey,
+        domain: offer.domain ?? null,
+        requestedBy: offer.requestedBy,
+        channelId,
+        // Top level, never a thread: the routine's room is where the card belongs, and a fire that
+        // was refused may have no thread of its own at all.
+        threadTs: null,
+        // The routine's REPORT surface — the surface this card is actually posted to, which is what
+        // this field freezes.
+        postedTo: surfaceKey,
+        summaryLines: routinePermissionCardLines(args),
+        // No clock: the routine generation is this card's bound. See the header of
+        // approvals/routine-permission.ts for why a timer would break the routines it serves, and
+        // RequestApprovalInput.noClockExpiry for what that does NOT reclaim.
+        noClockExpiry: true,
+      },
+    };
+  } catch {
+    return { state: "n/a" };
+  }
+}
+
+/** The channel id inside a resolved dispatch target, or undefined. `DispatchTarget.target` is a
+ *  per-platform shape, so this reads the one field both card-carrying platforms share and refuses
+ *  anything else — a missing id must never become an empty-string channel. */
+function readChannelId(target: unknown): string | undefined {
+  if (typeof target !== "object" || target === null) return undefined;
+  const id = (target as { channelId?: unknown }).channelId;
+  return typeof id === "string" && id.length > 0 ? id : undefined;
+}
+
+/**
+ * The pending card a `live` state is derived from, and whether the look HAPPENED at all.
+ *
+ * 🔴 `read: false` IS NOT "NO CARD IS PENDING". A store that threw observed nothing, and the two
+ * answers leave the world in opposite states: one leaves a live card in the room, the other asserts
+ * there is none. The state read turns the first into `unreadable` and the second into `lapsed`, and
+ * collapsing them would post a second card beside a first that is still clickable.
+ *
+ * The match is on the FROZEN args, never on the memo: `listPendingActions` returns only pending
+ * rows, and the (grantKey, grantKind) pair inside a `routine.permission` row's args is the same
+ * pair the memo is keyed on.
+ */
+async function probeRoutinePermissionCard(
+  org: string,
+  grantKey: string,
+  grantKind: string,
+): Promise<{ read: boolean; cardId?: string }> {
+  let rows: readonly PendingActionRow[];
+  try {
+    rows = await getOperationalStore().listPendingActions(org);
+  } catch {
+    return { read: false };
+  }
+  for (const row of rows) {
+    if (row.kind !== ROUTINE_PERMISSION_KIND) continue;
+    let args: Partial<RoutinePermissionArgs> | null;
+    try {
+      args = JSON.parse(row.argsJson) as Partial<RoutinePermissionArgs> | null;
+    } catch {
+      // 🔴 A ROW THIS CANNOT READ MAKES THE WHOLE LOOK INCONCLUSIVE, because it might be THIS
+      // permission's own card. Answering `read: true` past it would say "no card is pending" on the
+      // strength of a row nobody could read, and the planner would post a second card beside a first
+      // that is still clickable. The cost is the fail-safe direction: one corrupt row suppresses new
+      // cards for every routine that has already asked, until it is gone. The review surface
+      // (routines/permission-review.ts) drops such a row instead, and may: it only REPORTS.
+      return { read: false };
+    }
+    if (args?.grantKey === grantKey && args.grantKind === grantKind) return { read: true, cardId: row.id };
+  }
+  return { read: true };
+}
+
+/**
+ * Where one posted permission card is. Both fields are absent when the card's row cannot be read at
+ * all; `room` alone is the honest answer on a surface that mints no per-message URL, and it is the
+ * one the refusal copy already used before there was a permalink to prefer.
+ */
+export interface RoutineCardPointer {
+  /** The card's own message URL, where the surface can express one. */
+  readonly permalink?: string;
+  /** The surface the card was posted to (`platform/workspace/channel`), off its frozen row. */
+  readonly room?: string;
+}
+
+/**
+ * Where one posted permission card is — a human-openable URL where the platform mints one, and the
+ * room it was posted to either way (OPE-1356).
+ *
+ * 🔴 THE REFERENCE IS READ BACK, NEVER CARRIED. The card's own pending row holds the `channelId`
+ * the card went to and the `messageTs` `setPendingActionMessage` wrote after the post, and
+ * `postedTo` names the surface it landed on. So one row read addresses the message on the surface
+ * that has it, and the SAME call serves both the fire that just posted the card and a later fire
+ * pointing at the card that fire left behind — there is no captured value to go stale.
+ *
+ * NO PERMALINK on every honest absence: no `messageTs` (a card that never posted), a `postedTo`
+ * this cannot parse, or a platform that mints no per-message URL
+ * (`channels/surface-message-ops.ts` — Teams and Linear are two). The refusal copy then names the
+ * ROOM, which is true on every surface. Never throws, and answers `{}` when the row itself is
+ * unreadable: a pointer is a courtesy beside a refusal that has already been decided.
+ */
+export async function routinePermissionCardPointer(org: string, cardId: string): Promise<RoutineCardPointer> {
+  try {
+    const row = await getOperationalStore().getPendingAction(org, cardId);
+    if (!row || row.postedTo === null) return {};
+    const room = row.postedTo;
+    if (row.messageTs === null) return { room };
+    // `platform/workspace/channel` — the workspace segment is what a permalink needs beside the ids
+    // (Slack team, Discord guild), and it is only ever read from the row the card was posted to.
+    const [platform, workspace] = room.split("/");
+    if (platform === undefined || platform.length === 0) return { room };
+    const permalink = await resolveMessagePermalink(platform, {
+      channelId: row.channelId,
+      messageId: row.messageTs,
+      ...(workspace !== undefined && workspace.length > 0 ? { workspace } : {}),
+    });
+    return { room, ...(permalink !== undefined && permalink.length > 0 ? { permalink } : {}) };
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * One read of a permission card's world for the timed wait: what the pending row says, and whether
+ * the standing grant row a click writes is really there.
+ *
+ * 🔴 THE TWO READS ARE NOT REDUNDANT. `resolveApprovalClick` CASes the row to `approved` BEFORE it
+ * runs the kind, and this kind's `execute` refuses outright when the routine has been edited since
+ * the card was posted. So an `approved` row proves a human clicked, and NOTHING about whether the
+ * routine may now act. The permission read is what the run actually needs, and it is taken only on the
+ * `approved` branch — on any other status there is no click to have written one.
+ */
+export async function routineCardProbe(org: string, cardId: string, grantKey: string, grantKind: string): Promise<RoutineCardProbe> {
+  const store = getOperationalStore();
+  const row = await store.getPendingAction(org, cardId);
+  if (!row) return { status: "gone", armed: false };
+  if (row.status !== "approved") return { status: row.status, armed: false };
+  const grant = await store.getSessionApproval(org, grantKey, grantKind, new Date().toISOString());
+  return { status: "approved", armed: grant !== null };
+}
+
+/** Who armed the standing grant, for attribution on the run that proceeds off their click. The act
+ *  is recorded against the HUMAN who approved, never against the fire — the same attribution
+ *  `open_pull_request`'s session skip takes off `memo.grantedBy`. Undefined when no row is there. */
+export async function routineCardArmedBy(org: string, grantKey: string, grantKind: string): Promise<string | undefined> {
+  const grant = await getOperationalStore()
+    .getSessionApproval(org, grantKey, grantKind, new Date().toISOString())
+    .catch(() => null);
+  return grant?.grantedBy;
+}
+
+/** Mark the card live, AFTER it has actually posted. Written second on purpose: a memo written
+ *  before a failed post would suppress the card forever, so the failure direction is one retry on
+ *  the next fire rather than permanent silence — the same order spend/checkpoint.ts takes. */
+export async function markRoutinePermissionAsked(
+  org: string,
+  grantKey: string,
+  askedMemoKind: string,
+  askedBy: string,
+  nowIso: string,
+): Promise<void> {
+  await getOperationalStore()
+    .setSessionApproval({
+      org,
+      sessionId: grantKey,
+      kind: askedMemoKind,
+      grantedBy: askedBy,
+      createdAt: nowIso,
+      expiresAt: ROUTINE_PERMISSION_NO_EXPIRY,
+    })
+    .catch(() => undefined);
+}
+
+/**
+ * The clause a refusal appends. Every arm is derived from a ROW the planner actually read, so a
+ * sentence can never describe a card that is not there.
+ *
+ * `n/a` says nothing: this plane had no question to answer, and inventing a sentence about a
+ * permission it never considered is exactly the overclaim the state split exists to prevent.
+ * `absent` and `lapsed` without a post say nothing either — the card failed to post, so there is
+ * nothing to point at and the next fire retries.
+ *
+ * THE PERMALINK (OPE-1356) is appended by the two arms that have a card to point at, and ONLY when
+ * the surface really returned one. It is host-resolved from the card's own row
+ * ({@link routinePermissionCardPointer}), never composed here — a URL this function assembled
+ * would be a guess, and a wrong pointer is worse than the room name it replaced.
+ */
+export function routinePermissionRefusalClause(state: RoutinePermissionCardState, posted: boolean, permalink?: string): string {
+  const at = permalink !== undefined && permalink.length > 0 ? `: ${permalink}` : "";
+  switch (state) {
+    case "declined":
+      return " A person already declined this permission for this routine, so no card was posted — it will not be asked again until the routine's instruction is edited.";
+    case "live":
+      return ` A permission card for this is already waiting in the routine's own room; nobody has decided it yet${at}.`;
+    case "unreadable":
+      // 🔴 IT CLAIMS NOTHING ABOUT THE CARD, because nothing was observed. The routine's OWN ask is
+      // a row this read did see, so that half is stated; where the card stands is not.
+      return " This routine has already asked for this permission. Whether its card is still waiting in the routine's own room could not be read just now.";
+    case "absent":
+    case "lapsed":
+      return posted
+        ? ` A permission card for this is now waiting in the routine's own room — approving it lets future runs do this without asking${at}.`
+        : "";
+    default:
+      return "";
+  }
+}

package/agent/routines/permission-key.ts

@@ -0,0 +1,54 @@
+// THE ROUTINE PERMISSION KEY — its spelling, and the two ways to read one back.
+//
+// WHY A LEAF MODULE. The key is written by `routines/routine.ts` and read by three planes that must
+// not depend on each other: the card planner (routines/permission-card.ts), the review surface
+// (routines/permission-review.ts), and the permission-fit evidence reader
+// (access/permission-evidence.ts, which is pure math over audit rows and imports nothing else).
+// Before OPE-1361 the parser sat on the planner, so the evidence reader could not reach it without
+// pulling the operational store and the dispatch registry into a pure module. It got no parser at
+// all instead, and that is the defect OPE-1361 records: it joined on the WHOLE key, generation
+// included, so a permission a human armed on a new generation answered nothing.
+//
+// This file imports NOTHING. That is the property that lets every plane share one grammar for the
+// key rather than each carrying its own regex.
+//
+// THE WORD IS "DECLARED PERMISSION", NEVER "GRANT" (OPE-1303, Tommy ruling 2026-08-29). What this
+// key addresses is what a human declared on a routine's creation card, or approved later on a
+// permission card. "Grant" belongs to the credential plane (access/credential-grant*), where a
+// person lends a chat their own authority — nothing is lent here. See docs/glossary.md.
+
+/** The prefix every routine-scoped declared-permission key carries. A key without it is a session
+ *  or window token, and must never be read as a routine's.
+ *
+ *  🔴 THE VALUE IS PERSISTED AND DOES NOT MOVE. Live rows in deployed databases carry it, so the
+ *  OPE-1303 vocabulary sweep renamed this constant and left `"oe-routine:"` alone. */
+export const ROUTINE_PERMISSION_PREFIX = "oe-routine:";
+
+/** `oe-routine:<id>:g<n>` — the id itself never contains ":" (routines/store.ts newRoutineId), so a
+ *  single strict pattern reads the whole key rather than a prefix of it. */
+const KEY_PATTERN = /^oe-routine:([^:]+):g([1-9][0-9]*)$/;
+
+/** The routine a permission key names. Undefined for anything that is not one — a session/window token,
+ *  a hand-set string, a key from a build that spelled them differently. FAIL-CLOSED on purpose:
+ *  this value chooses which routine a card would arm, so an unparseable key must plan nothing. */
+export function routinePermissionKeyParts(key: string): { routineId: string; generation: number } | undefined {
+  if (!key.startsWith(ROUTINE_PERMISSION_PREFIX)) return undefined;
+  const m = KEY_PATTERN.exec(key);
+  if (!m || m[1] === undefined || m[2] === undefined) return undefined;
+  return { routineId: m[1], generation: Number(m[2]) };
+}
+
+/**
+ * The key WITHOUT its generation — `oe-routine:<id>` — or undefined when the key is not a routine's.
+ *
+ * 🔴 THIS IS NOT AN ADDRESS AND NOTHING MAY BE STORED UNDER IT. No permission row, no memo and no
+ * card is ever keyed on this value: the generation is the routine plane's death mechanism, and a row
+ * keyed without one would outlive the instruction it was declared for. It exists for exactly one
+ * job — joining two audit rows that name the SAME ROUTINE across an `edit_routine`
+ * (access/permission-evidence.ts). Read {@link routinePermissionKeyParts} for anything that decides
+ * authority.
+ */
+export function routinePermissionKeyIdentity(key: string): string | undefined {
+  const parts = routinePermissionKeyParts(key);
+  return parts === undefined ? undefined : `${ROUTINE_PERMISSION_PREFIX}${parts.routineId}`;
+}