@open-everywhere/core 0.1.0

package/dist/agent/routines/permission-card.js

@@ -0,0 +1,397 @@
+// 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 { ROUTINE_PERMISSION_KIND, routinePermissionCardLines, } from "../approvals/routine-permission.js";
+import { routinePermissionAskedMemo, routinePermissionDeclinedMemo, routinePermissionKind } from "../approvals/session-grant.js";
+import { ROUTINE_PERMISSION_NO_EXPIRY, namesBundleRaisedTool, namesUnliftableTool } from "./declared-permissions.js";
+import { getOperationalStore } from "../operational/provider.js";
+import { resolveMessagePermalink } from "../channels/surface-message-ops.js";
+import { listAllRoutines, getRoutine } from "./store.js";
+import { isSilentRoutine, routineReportSurfaceKey } from "./routine.js";
+import { routinePermissionKeyParts } from "./permission-key.js";
+import { resolveRoutineTarget } from "../schedules/routine-dispatch.js";
+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) {
+    const grantKind = routinePermissionKind(declaration);
+    if (grantKind === null || namesUnliftableTool(declaration) || namesBundleRaisedTool(declaration))
+        return undefined;
+    return { grantKind, declaration };
+}
+/**
+ * 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, grantKey, grantKind, nowIso) {
+    const store = getOperationalStore();
+    let asked;
+    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 };
+}
+/** 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, scopeKey, routineId) {
+    const keyed = await getRoutine(org, scopeKey, routineId).catch(() => null);
+    if (keyed)
+        return keyed;
+    const all = await listAllRoutines().catch(() => []);
+    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) {
+    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 = {
+            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) {
+    if (typeof target !== "object" || target === null)
+        return undefined;
+    const id = target.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, grantKey, grantKind) {
+    let rows;
+    try {
+        rows = await getOperationalStore().listPendingActions(org);
+    }
+    catch {
+        return { read: false };
+    }
+    for (const row of rows) {
+        if (row.kind !== ROUTINE_PERMISSION_KIND)
+            continue;
+        let args;
+        try {
+            args = JSON.parse(row.argsJson);
+        }
+        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 — 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, cardId) {
+    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, cardId, grantKey, grantKind) {
+    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, grantKey, grantKind) {
+    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, grantKey, askedMemoKind, askedBy, nowIso) {
+    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, posted, permalink) {
+    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 "";
+    }
+}
+//# sourceMappingURL=permission-card.js.map

package/dist/agent/routines/permission-card.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-card.js","sourceRoot":"","sources":["../../../agent/routines/permission-card.ts"],"names":[],"mappings":"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"}

package/dist/agent/routines/permission-key.d.ts

@@ -0,0 +1,25 @@
+/** 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 declare const ROUTINE_PERMISSION_PREFIX = "oe-routine:";
+/** 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 declare function routinePermissionKeyParts(key: string): {
+    routineId: string;
+    generation: number;
+} | undefined;
+/**
+ * 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 declare function routinePermissionKeyIdentity(key: string): string | undefined;
+//# sourceMappingURL=permission-key.d.ts.map

package/dist/agent/routines/permission-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-key.d.ts","sourceRoot":"","sources":["../../../agent/routines/permission-key.ts"],"names":[],"mappings":"AAmBA;;;;sFAIsF;AACtF,eAAO,MAAM,yBAAyB,gBAAgB,CAAC;AAMvD;;kGAEkG;AAClG,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAK5G;AAED;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG5E"}

package/dist/agent/routines/permission-key.js

@@ -0,0 +1,53 @@
+// 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) {
+    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) {
+    const parts = routinePermissionKeyParts(key);
+    return parts === undefined ? undefined : `${ROUTINE_PERMISSION_PREFIX}${parts.routineId}`;
+}
+//# sourceMappingURL=permission-key.js.map

package/dist/agent/routines/permission-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-key.js","sourceRoot":"","sources":["../../../agent/routines/permission-key.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,EAAE;AACF,oGAAoG;AACpG,+FAA+F;AAC/F,0EAA0E;AAC1E,gGAAgG;AAChG,mGAAmG;AACnG,kGAAkG;AAClG,+FAA+F;AAC/F,gFAAgF;AAChF,EAAE;AACF,kGAAkG;AAClG,+CAA+C;AAC/C,EAAE;AACF,kGAAkG;AAClG,8FAA8F;AAC9F,+FAA+F;AAC/F,wFAAwF;AAExF;;;;sFAIsF;AACtF,MAAM,CAAC,MAAM,yBAAyB,GAAG,aAAa,CAAC;AAEvD;4EAC4E;AAC5E,MAAM,WAAW,GAAG,qCAAqC,CAAC;AAE1D;;kGAEkG;AAClG,MAAM,UAAU,yBAAyB,CAAC,GAAW;IACnD,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,yBAAyB,CAAC;QAAE,OAAO,SAAS,CAAC;IACjE,MAAM,CAAC,GAAG,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAChC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,SAAS,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACrE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACvD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,4BAA4B,CAAC,GAAW;IACtD,MAAM,KAAK,GAAG,yBAAyB,CAAC,GAAG,CAAC,CAAC;IAC7C,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,yBAAyB,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC;AAC5F,CAAC"}

package/dist/agent/routines/permission-review.d.ts

@@ -0,0 +1,108 @@
+import { type Routine } from "./routine.js";
+/** The routine a review reads — id and generation make the key, the report surface names the room. */
+type ReviewedRoutine = Pick<Routine, "id" | "promptGeneration" | "surfaceKey" | "report">;
+/**
+ * What became of one permission a routine asked for. Every arm is derived from a row that exists,
+ * or — for `unreadable` — from a read that failed and says so.
+ *
+ * The arms are kept apart because a person acting on this record does something DIFFERENT in each,
+ * and because each is easy to state as another one and be wrong. 🔴 EVERY CONSUMER MUST HANDLE THEM
+ * ALL: `list_routines`'s zod enum is one such site, and a switch that omits an arm reports a state
+ * as something it is not. Count the arms below rather than a number in this sentence.
+ */
+export type RoutinePermissionAskState = 
+/** A card for it is pending in the routine's room right now. Clicking it arms every future fire. */
+"waiting"
+/** A person declined it. Future fires refuse quietly and post no card, until the instruction is
+ *  edited. */
+ | "declined"
+/** A card was posted under an EARLIER instruction and is still in the room. Its click-time
+ *  re-check refuses now, so answering it records nothing either way (OPE-1339 reaps it). */
+ | "superseded"
+/**
+ * The routine asked, and no row records an answer: no card is pending, no permission was written,
+ * no decline was remembered.
+ *
+ * 🔴 IT IS A REAL STATE, NOT A GAP IN THE READ — and {@link RoutinePermissionAskState.unreadable}
+ * is what keeps that true. The ask marker is written when the card posts and outlives the card's
+ * row, so this is what a card ANSWERED WITHOUT ANYTHING STICKING looks like — an approve whose
+ * grant write failed, or a decline whose memo write failed (both are best-effort by design).
+ *
+ * Since OPE-1359 a later fire reads the card row before believing the marker, so it posts a FRESH
+ * card rather than pointing at the one that is gone. This state is what a reader sees between
+ * those two fires, and it still names the thing to fix.
+ */
+ | "lapsed"
+/**
+ * The routine asked, and the card store could not be read, so what became of the card is unknown.
+ *
+ * 🔴 WITHOUT THIS ARM A STORE BLIP READS AS `lapsed`, WHICH IS A LIE. `lapsed` asserts an absence
+ * — no card is pending — and a read that failed observed nothing at all. The card is very likely
+ * still sitting in the room, clickable, and telling its owner to edit the instruction instead
+ * would bump the generation and kill exactly that card. The same split the timed wait had to make
+ * between `deadline` and `unreadable`: any reader that swallows an error needs its empty answer to
+ * know whether the last look saw anything.
+ */
+ | "unreadable";
+/** One permission a routine asked for, and where its answer stands. */
+export interface RoutinePermissionAsk {
+    /** The permission in plain language — the same words `list_routines` uses for a live permission. */
+    readonly permission: string;
+    /** How `create_routine` / `edit_routine` spell it: `pr.open`, `tool:<qualified tool>`. Null for a
+     *  permission kind no declaration maps onto — a legacy row that lifts nothing. */
+    readonly declaration: string | null;
+    readonly state: RoutinePermissionAskState;
+    /** When the card was posted. Null when no card row survives to say. */
+    readonly askedAt: string | null;
+    /** The surface the card was posted to (`platform/workspace/channel`), or null when no card row
+     *  survives to say. */
+    readonly room: string | null;
+    /** What a person does next, through the door that is already open. */
+    readonly nextStep: string;
+}
+/** One routine's permission picture: what it MAY do, and what it ASKED to do and did not get. */
+export interface RoutinePermissionView {
+    /** The live standing grants, in plain language — never a card marker (see the header). */
+    readonly permissions: string[];
+    /** The asks, oldest card first, then the ones with no card row left. */
+    readonly asks: RoutinePermissionAsk[];
+    /**
+     * The PERMISSION read for this routine failed, so {@link permissions} and every marker-derived ask are
+     * unknown rather than absent (OPE-1360).
+     *
+     * 🔴 IT IS THE PERMISSION LEG'S {@link RoutinePermissionAskState.unreadable}, and it exists for the
+     * identical reason. An empty `permissions` asserts "this routine holds nothing"; a read that threw
+     * observed nothing at all, and the two produce opposite advice — the first says arm it, the second
+     * says look again before deciding. The card leg has said which of the two it means since it
+     * shipped; this leg swallowed the failure to `[]` and could not.
+     *
+     * WHY A PER-ROUTINE FLAG AND NOT A SIXTH ASK STATE. The failure is about the WHOLE routine — its
+     * grants and every marker on its key at once — not about one permission. A sixth ask state would
+     * have to be invented per permission the reader could not enumerate, which is a list it does not
+     * have.
+     */
+    readonly permissionsUnreadable: boolean;
+}
+/** Nothing known — the fail-soft answer, and the shape a caller with no rows gets. `false` is right
+ *  here: a caller that never asked for a routine's rows has not had a read FAIL. */
+export declare function emptyRoutinePermissionView(): RoutinePermissionView;
+/**
+ * The permission picture for each supplied routine, keyed by routine id.
+ *
+ * ONE org-wide card read for the whole call, then one keyed permission read per routine — the same
+ * shape `list_routines` already uses for its forensics.
+ *
+ * Fails SOFT PER LEG rather than failing the listing, and THE TWO LEGS FAIL DIFFERENTLY.
+ *
+ * A failed CARD read is SAID: every ask it would have answered becomes `unreadable`, never
+ * `lapsed`, because `lapsed` asserts an absence that a failed read never observed.
+ *
+ * A failed PERMISSION read is SAID TOO (OPE-1360): the routine's {@link
+ * RoutinePermissionView.permissionsUnreadable} is set, its standing set is empty, and the two
+ * together mean "unknown" rather than "holds nothing". It still under-reports — no grant is
+ * invented, which is the direction that matters — but a reader can now tell an empty answer from a
+ * failed one.
+ */
+export declare function readRoutinePermissionViews(org: string, routines: readonly ReviewedRoutine[], nowIso: string): Promise<Map<string, RoutinePermissionView>>;
+export {};
+//# sourceMappingURL=permission-review.d.ts.map

package/dist/agent/routines/permission-review.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-review.d.ts","sourceRoot":"","sources":["../../../agent/routines/permission-review.ts"],"names":[],"mappings":"AAsCA,OAAO,EAAiD,KAAK,OAAO,EAAE,MAAM,cAAc,CAAC;AAG3F,sGAAsG;AACtG,KAAK,eAAe,GAAG,IAAI,CAAC,OAAO,EAAE,IAAI,GAAG,kBAAkB,GAAG,YAAY,GAAG,QAAQ,CAAC,CAAC;AAE1F;;;;;;;;GAQG;AACH,MAAM,MAAM,yBAAyB;AACnC,oGAAoG;AAClG,SAAS;AACX;cACc;GACZ,UAAU;AACZ;4FAC4F;GAC1F,YAAY;AACd;;;;;;;;;;;;GAYG;GACD,QAAQ;AACV;;;;;;;;;GASG;GACD,YAAY,CAAC;AAEjB,uEAAuE;AACvE,MAAM,WAAW,oBAAoB;IACnC,oGAAoG;IACpG,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;sFACkF;IAClF,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,yBAAyB,CAAC;IAC1C,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC;2BACuB;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,iGAAiG;AACjG,MAAM,WAAW,qBAAqB;IACpC,0FAA0F;IAC1F,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,CAAC;IAC/B,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,oBAAoB,EAAE,CAAC;IACtC;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,qBAAqB,EAAE,OAAO,CAAC;CACzC;AAED;oFACoF;AACpF,wBAAgB,0BAA0B,IAAI,qBAAqB,CAElE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,0BAA0B,CAC9C,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,SAAS,eAAe,EAAE,EACpC,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC,CAK7C"}