@open-everywhere/core 0.1.0

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

@@ -0,0 +1,213 @@
+// THE EVERY-FIRE TIMED WAIT on a routine permission card (OPE-1290, PR 2 of 3).
+//
+// WHAT THIS FILE DECIDES. A routine fire has just been refused, and `routines/permission-card.ts`
+// has either posted a fresh card into the routine's room or found one already live there. PR 1 threw
+// the refusal at that instant. This file adds the bounded pause in between: the refusing tool call
+// polls that card's own pending row, and if a person answers it while the run is still up, the run
+// gets the answer instead of the refusal.
+//
+// 🔴 WHY THE WAIT LIVES IN OUR CODE. eve has no timeout arm on an approval — nothing suspends a turn
+// and resumes it on a click. So the only place a run can wait is INSIDE the tool body that is about
+// to refuse, against the function's own wall clock. That is what {@link waitForRoutineCardDecision}
+// is: a poll loop with one budget, spent by the caller who would otherwise have thrown already.
+//
+// 🔴 THE DEADLINE IS A TURN OUTCOME, NEVER A CARD DEATH. When the budget runs out this returns
+// `deadline` and DECIDES NOTHING — no CAS, no expiry, no row written. The card is still pending, it
+// still has live buttons, and approving it still arms every future fire. Two different questions
+// live here and collapsing them is the defect this note exists to prevent:
+//   • the RUN's question — "may I use this right now?" — which the deadline answers "no, because
+//     nobody was here", honestly, to the model;
+//   • the CARD's question — "may this routine use this in general?" — which stays open.
+// The fence deciding the pending row itself would answer the second question with the first one's
+// evidence, and a routine whose 03:00 card auto-rejected because nobody was awake at 03:00 is
+// exactly the failure the no-clock TTL ruling already refused once.
+//
+// 🔴 WHY AN APPROVAL IS NOT TAKEN ON THE PENDING ROW ALONE. `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 (the click-time re-check that makes a clockless card
+// safe). So `status: "approved"` means a human clicked, not that anything was armed. The probe reads
+// BOTH — the row's status and the standing grant row itself — and only a click that really wrote the
+// grant lets the run proceed. Everything else refuses, naming what happened.
+//
+// A LEAF: the settings read, the turn clock read, and pure arithmetic over an injected clock. The
+// probe, the sleep and the clock are all supplied by the caller, which is what lets the deadline
+// legs be tested without spending 120 seconds of wall time.
+import { getSettings } from "../settings/settings.js";
+import { turnElapsedSeconds } from "../observability/turn-clock.js";
+/**
+ * The deployed function's wall ceiling, in seconds (measured on ship #148, config-read, three
+ * sources agreeing: the platform default under fluid compute, with no app pin). Everything below is
+ * arithmetic off this number, and it is stated here rather than in the setting so the code that
+ * enforces the bound and the doc that explains it cannot drift apart.
+ */
+export const FUNCTION_WALL_CEILING_SECONDS = 300;
+/**
+ * The FALLBACK for what the turn has already spent by the time a gated tool call reaches its
+ * refusal — the wake, the model's first passes, and whatever tools ran before this one.
+ *
+ * 🔴 IT IS THE "OTHERWISE" ARM, NOT THE ONLY ARM (OPE-1347). The bound is
+ * `min(configured, ceiling − elapsed − reserve)`, and `elapsed` is READ from the turn's own
+ * `startedAt` through {@link turnElapsedSeconds}. This number is what stands in when there is no
+ * turn to read: a schedule, an eval, a CLI, a unit test. It is deliberately generous — assuming a
+ * turn is further along than it is shortens the wait, which costs a run its window; assuming it is
+ * younger than it is lets the wall clock kill the turn mid-report, which costs the run its report.
+ */
+export const ASSUMED_TURN_ELAPSED_SECONDS = 120;
+/**
+ * What must still fit AFTER the wait: telling the model, its next passes, and posting the run's
+ * report to the routine's surface. A wait that consumed the whole remainder would turn a refusal
+ * the model could report into a turn that is killed mid-sentence.
+ */
+export const TURN_TAIL_RESERVE_SECONDS = 60;
+/** The clamp on the FALLBACK arm: 300 − 120 − 60. Also the recommended armed value, because it is
+ *  what a turn that reached its refusal at the assumed elapsed can still afford. It is NOT a floor
+ *  on {@link routineCardWaitCeilingSeconds}, which goes to 0 and below on a longer turn — that is
+ *  the clamp OPE-1347 exists for. */
+export const ROUTINE_CARD_WAIT_CEILING_SECONDS = FUNCTION_WALL_CEILING_SECONDS - ASSUMED_TURN_ELAPSED_SECONDS - TURN_TAIL_RESERVE_SECONDS;
+/**
+ * The wait this turn may still afford, in seconds: `300 − elapsed − 60`.
+ *
+ * 🔴 IT CAN BE ZERO OR NEGATIVE, AND THAT IS THE POINT (OPE-1347). A turn that reached its refusal
+ * 250 seconds in has 300 − 250 − 60 = −10 seconds of room. Before the elapsed read that same turn
+ * was handed the flat 120-second budget and was killed by the wall clock mid-report — the refusal
+ * never reached the model and the routine's room learned nothing. A non-positive ceiling now
+ * disarms the wait instead: the refusal is immediate and the card still decides every future fire.
+ * {@link routineCardWaitBudgetMs} is where that clamp is applied.
+ *
+ * An unreadable elapsed (no turn context, or a clock that moved backwards) falls back to
+ * {@link ASSUMED_TURN_ELAPSED_SECONDS}, which reproduces the pre-OPE-1347 number exactly.
+ */
+export function routineCardWaitCeilingSeconds(elapsedSeconds = turnElapsedSeconds()) {
+    const elapsed = elapsedSeconds !== undefined && Number.isFinite(elapsedSeconds) && elapsedSeconds >= 0 ? elapsedSeconds : ASSUMED_TURN_ELAPSED_SECONDS;
+    return FUNCTION_WALL_CEILING_SECONDS - elapsed - TURN_TAIL_RESERVE_SECONDS;
+}
+/**
+ * How often the pending row is re-read. A click is a human action, so a two-second granularity
+ * costs the clicker nothing they can perceive and keeps a 120-second wait at ~60 store reads rather
+ * than thousands.
+ */
+const ROUTINE_CARD_POLL_INTERVAL_MS = 2_000;
+/** The configured wait, in seconds, before the ceiling clamp. */
+export function routineCardWaitSeconds() {
+    return getSettings().approvals.routineCardWaitSeconds;
+}
+/**
+ * The budget this run may actually spend, in milliseconds — `min(configured, ceiling)`, and 0 for
+ * anything non-positive or unreadable. 0 means NO WAIT: the caller refuses immediately, exactly as
+ * it did before this file existed.
+ *
+ * The clamp is not defensive decoration. The setting's validator refuses a value above 300, but it
+ * admits every value up to it — an operator who authors 200 gets what the turn can still afford,
+ * not a turn killed mid-report. And since OPE-1347 the ceiling is derived from the turn's OWN
+ * elapsed time rather than an assumed 120 seconds, so a long turn is clamped harder (down to no
+ * wait at all) and a young one is allowed the whole configured window.
+ */
+export function routineCardWaitBudgetMs(configuredSeconds = routineCardWaitSeconds(), ceilingSeconds = routineCardWaitCeilingSeconds()) {
+    if (!Number.isFinite(configuredSeconds) || configuredSeconds <= 0)
+        return 0;
+    if (!Number.isFinite(ceilingSeconds) || ceilingSeconds <= 0)
+        return 0;
+    return Math.min(configuredSeconds, ceilingSeconds) * 1_000;
+}
+/**
+ * Poll the card until it is answered or the budget is spent.
+ *
+ * ORDER IS LOAD-BEARING: probe, then test the deadline, then sleep. A click that landed between the
+ * card's post and the first tick is therefore seen without waiting for one, and the last sleep is
+ * always followed by one final probe rather than an immediate give-up.
+ *
+ * A probe that THROWS is swallowed and the loop continues. A store blip must not read as "nobody
+ * answered" — the budget still bounds the whole thing, so the cost of a broken store is the full
+ * wait and then an honest deadline, never an early wrong answer.
+ */
+export async function waitForRoutineCardDecision(budgetMs, deps) {
+    if (!(budgetMs > 0))
+        return "disarmed";
+    const interval = deps.pollIntervalMs ?? ROUTINE_CARD_POLL_INTERVAL_MS;
+    const endsAt = deps.nowMs() + budgetMs;
+    // 🔴 AN UNARMED APPROVAL IS NOT YET A VERDICT — IT IS USUALLY A RACE. `resolveApprovalClick` CASes
+    // the row to `approved`, THEN re-reads the routine, THEN writes the permission row: several store round
+    // trips during which the row reads `approved` and no grant exists. Returning `stale` on the first
+    // such probe would refuse a run whose permission lands milliseconds later, and would tell the
+    // model the instruction had been edited when nothing was edited. So an unarmed approval is
+    // REMEMBERED and the loop keeps going; only the deadline turns it into `stale`.
+    let sawUnarmedApproval = false;
+    // 🔴 DID THE LAST LOOK ACTUALLY SEE ANYTHING? The probe's rejection is swallowed just below, which
+    // is right — one store blip must not auto-decline a run. The cost is that a store down for the
+    // WHOLE window arrives at the same place as a card nobody touched, and only this flag can tell the
+    // refusal which of the two to report. It tracks the FINAL look rather than "was there ever a
+    // failure", because what the run is about to assert is the card's state at the moment it gave up.
+    let lastProbeFailed = false;
+    for (;;) {
+        const probe = await deps.probe().catch(() => undefined);
+        lastProbeFailed = probe === undefined;
+        switch (probe?.status) {
+            case "approved":
+                if (probe.armed)
+                    return "approved";
+                sawUnarmedApproval = true;
+                break;
+            case "rejected":
+                // Terminal at once, and deliberately without a second read: a person said no, which answers
+                // this run whatever the card's own bookkeeping then records. See the `declined` doc.
+                return "declined";
+            case "expired":
+            case "gone":
+                return "gone";
+            default:
+                break;
+        }
+        const left = endsAt - deps.nowMs();
+        // ORDER: an unreadable final look wins over BOTH remaining arms. `stale` asserts that no
+        // permission was written, and `deadline` that nobody answered — neither is knowable when the
+        // last thing this run did was fail to read the card.
+        if (left <= 0)
+            return lastProbeFailed ? "unreadable" : sawUnarmedApproval ? "stale" : "deadline";
+        await deps.sleep(Math.min(interval, left));
+    }
+}
+/**
+ * The clause the refusal appends for a wait that did not end in an approval. Every arm names what
+ * really happened, and every arm states only what a row actually said.
+ *
+ * 🔴 EVERY ARM IS SELF-CONTAINED, AND THAT IS LOAD-BEARING. The caller composes this with the
+ * PRE-WAIT card-state clause ("a card is now waiting" / "a card is already waiting"), which
+ * describes the card at wait START. Only {@link routineCardKeepsStateClause} says when that is still
+ * true at wait END — everywhere else the pre-wait sentence is DROPPED, because "nobody has decided
+ * it yet" followed by "a person declined it" is one paragraph contradicting itself. So each arm here
+ * has to introduce the card itself rather than lean on a sentence that may not be there.
+ *
+ * `approved` returns "" — that run does not refuse, so it has no refusal to append to.
+ */
+export function routineCardWaitRefusalClause(outcome, waitedSeconds) {
+    switch (outcome) {
+        case "declined":
+            // No durability claim: whether the decline is REMEMBERED is the card's business and is
+            // decided after this read. See the `declined` outcome's own doc.
+            return " A permission card for this was waiting in the routine's own room, and a person declined it while this run waited — so this run does not get it.";
+        case "deadline":
+            return ` This run waited ${waitedSeconds}s for someone to answer that card and nobody did, so it was declined for THIS RUN ONLY because nobody was present to action it. The card is still waiting and still clickable — approving it lets future runs do this without asking.`;
+        case "stale":
+            // States the OBSERVED fact and names the likely cause as something to check, never as
+            // something this code verified — it read no routine and no generation.
+            return ` A person approved the permission card in the routine's own room while this run waited, but no standing permission was written behind their click in the ${waitedSeconds}s this run had, so nothing was armed. A click on a card posted before an \`edit_routine\` records nothing — check whether the instruction changed.`;
+        case "gone":
+            return " The permission card for this is no longer answerable, so the next run will post a fresh one.";
+        case "unreadable":
+            return ` A permission card for this is waiting in the routine's own room, but this run could not read it for the last of the ${waitedSeconds}s it waited, so it gave up without knowing whether anyone answered. Nothing here says nobody did. The card is unaffected — approving it still lets future runs do this without asking.`;
+        default:
+            return "";
+    }
+}
+/**
+ * May the caller keep its PRE-WAIT card-state clause alongside {@link routineCardWaitRefusalClause}?
+ *
+ * Only at the deadline. There the card really is untouched — still pending, still where the earlier
+ * sentence said it was — so "a card is waiting in the routine's own room" is as true at wait end as
+ * it was at wait start, and the two sentences read as one paragraph. Every other outcome moved the
+ * card out from under that sentence.
+ */
+export function routineCardKeepsStateClause(outcome) {
+    return outcome === "deadline";
+}
+//# sourceMappingURL=permission-card-wait.js.map

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

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

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

@@ -0,0 +1,196 @@
+import type { RequestApprovalInput } from "../approvals/flow.js";
+import type { RoutineCardProbe } from "./permission-card-wait.js";
+import { routinePermissionKeyParts } from "./permission-key.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 declare function declarableRoutinePermission(declaration: string): {
+    grantKind: string;
+    declaration: string;
+} | undefined;
+/** 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 declare function readRoutinePermissionCardState(org: string, grantKey: string, grantKind: string, nowIso: string): Promise<RoutinePermissionCardRead>;
+/** 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;
+}
+/**
+ * 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 declare function planRoutinePermissionCard(offer: RoutinePermissionOffer): Promise<RoutinePermissionPlan>;
+/**
+ * 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 declare function routinePermissionCardPointer(org: string, cardId: string): Promise<RoutineCardPointer>;
+/**
+ * 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 declare function routineCardProbe(org: string, cardId: string, grantKey: string, grantKind: string): Promise<RoutineCardProbe>;
+/** 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 declare function routineCardArmedBy(org: string, grantKey: string, grantKind: string): Promise<string | undefined>;
+/** 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 declare function markRoutinePermissionAsked(org: string, grantKey: string, askedMemoKind: string, askedBy: string, nowIso: string): Promise<void>;
+/**
+ * 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 declare function routinePermissionRefusalClause(state: RoutinePermissionCardState, posted: boolean, permalink?: string): string;
+//# sourceMappingURL=permission-card.d.ts.map

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

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