@open-everywhere/core 0.1.0

package/agent/access/credential-grant-card.ts

@@ -0,0 +1,521 @@
+// The owner's grant card goes to the OWNER'S OWN DM and never to the requesting room, so a refusal is not a public act in front of colleagues. It is host-rendered from frozen arguments with the one model-authored field quoted as data, carries no host identifier, and a button tap is the only thing that can answer it — credential-grant-click.ts is the only path to approval and nothing parses a typed reply.
+
+import { canDeliverDirectMessage, type DirectMessageAction } from "../channels/post-arms.js";
+import {
+  deliverProactiveDm,
+  dmDeliveryFooter,
+  personAddress,
+  ProactiveDmRefusedError,
+  type DmDeliveryWhere,
+} from "../channels/dm-audience.js";
+import { editSurfaceText } from "../channels/surface-message-ops.js";
+import { GRANT_STANDING_MAX_MS } from "./credential-grant.js";
+import { connectorDisplayName, grantActionIsReviewed, grantActionPhrase, grantConversationPhrase, grantExpiryPhrase, grantRequesterPhrase } from "./credential-grant-copy.js";
+import { grantScopeReachOf, type GrantScopeReach } from "./credential-grant-key-shape.js";
+import {
+  flatDisplayName,
+  grantResourceTargetLabel,
+  quotedPurpose,
+  type CredentialGrantAskRow,
+  type CredentialGrantMode,
+  type CredentialGrantRow,
+  type GrantJsonObject,
+} from "../operational/credential-grant-rows.js";
+
+/** The standing button's own label, in days, DERIVED from the ceiling rather than spelled twice. A
+ *  label that names a different span than `credentialGrantExpiry` clamps to is a lie on a card whose
+ *  whole job is to state exactly what is being approved. */
+const STANDING_DAYS = Math.round(GRANT_STANDING_MAX_MS / (24 * 60 * 60 * 1000));
+
+/** How many times one "once" grant can be attempted in a turn: one burn plus the broker's cap of three refunds, because the burn happens before the vendor call and a call the host can prove never left is refunded. The value is duplicated rather than imported to avoid an import cycle, and a test pins the two equal. */
+export const GRANT_ONCE_MAX_ATTEMPTS_PER_TURN = 4;
+
+/** One reader-facing word per mode, spent by every surface that names a mode, so a person who taps one word never reads another and cannot tell whether they got what they tapped. These are READER words only: the wire values stay once/session/standing in the column, the action id and the audit row. */
+export const GRANT_MODE_WORDS: Readonly<Record<CredentialGrantMode, string>> = {
+  once: "once",
+  session: "this conversation",
+  standing: `${String(STANDING_DAYS)} days`,
+};
+
+const GRANT_MODE_BREADTH: Readonly<Record<CredentialGrantMode, number>> = { once: 0, session: 1, standing: 2 };
+
+/** True when mode admits more than thanMode — one call, then one conversation, then a span of days. An approval may legitimately be wider than the ask because the owner chooses breadth, and the room notice uses this to say so rather than let a room read the ask's breadth as the grant's. */
+export function grantModeIsBroader(mode: CredentialGrantMode, thanMode: CredentialGrantMode): boolean {
+  return GRANT_MODE_BREADTH[mode] > GRANT_MODE_BREADTH[thanMode];
+}
+
+/** The prefix every grant-card button id carries. A surface's interaction router classifies "ours" on exactly this string, so it must not collide with the approval, credential-intake, connector-card or identity-consent prefixes, or with eve's own. */
+export const OE_GRANT_ACTION_PREFIX = "oe_grant:";
+
+/** What a tap MEANS. A closed set: the id is PARSED, never interpreted. */
+export type GrantCardAnswer = CredentialGrantMode | "decline";
+
+/** The action id grammar oe_grant:<answer>:<askId>. The mode rides the id because the owner's answer must be a click on host-rendered copy, and the click route reads nothing else off the payload but the CLICKER. An ask id is not a bearer token: holding one lets you name an ask, not answer one, because every click whose verified clicker is not the ask's owner is refused. */
+export function grantCardActionId(askId: string, answer: GrantCardAnswer): string {
+  return `${OE_GRANT_ACTION_PREFIX}${answer}:${askId}`;
+}
+
+/** Parse one grant-card button id, or undefined when it is not ours or not well-formed. The answer is peeled off the FRONT because an ask id is our own store key and could contain a colon, so a grammar that split from the end would mis-read one. */
+export function parseGrantCardActionId(raw: string | undefined): { readonly askId: string; readonly answer: GrantCardAnswer } | undefined {
+  if (typeof raw !== "string" || !raw.startsWith(OE_GRANT_ACTION_PREFIX)) return undefined;
+  const body = raw.slice(OE_GRANT_ACTION_PREFIX.length);
+  const cut = body.indexOf(":");
+  if (cut <= 0) return undefined;
+  const answer = body.slice(0, cut);
+  const askId = body.slice(cut + 1);
+  if (askId.length === 0) return undefined;
+  if (answer !== "once" && answer !== "session" && answer !== "standing" && answer !== "decline") return undefined;
+  return { answer, askId };
+}
+
+/** One mode spelled the way a sentence takes it: the single-sourced word plus the preposition that word needs, so a card that reads a decision back cannot drift from the button that made it. */
+export function grantModePhrase(mode: CredentialGrantMode): string {
+  return mode === "once" ? GRANT_MODE_WORDS.once : `for ${GRANT_MODE_WORDS[mode]}`;
+}
+
+/**
+ * WHICH STANDING ARM THIS ASK OFFERS, or `undefined` when it offers none (OPE-2160).
+ *
+ * 🔴 A 30-DAY BUTTON IS A 30-DAY PROMISE, SO IT IS RENDERED ONLY WHERE THE MECHANISM CAN KEEP ONE.
+ * A standing grant binds to the ask's own `domainScopeKey`, and an ask that carries none has nothing
+ * conversation-stable to bind to. Before this, such a tap bound the row to the ASKING SESSION and
+ * still stamped a 30-day expiry: the owner read "30 days" and the row became unreachable at the next
+ * seat rotation — 7 days, a 12-hour quiet gap, a turn or token backstop, or any deploy that changes
+ * the eve build. Nobody was told, and the audit trail showed a live grant nobody could spend for
+ * another 29 days. `grantScopeKeyForMode` refuses the same case at the mint, so the button and the
+ * row agree.
+ *
+ * ONE READER, THREE USES — the buttons, the card body's bullet and the line that reads the ASK's own
+ * mode back must never disagree about what is on offer. It answers the REACH rather than a boolean so
+ * the bullet's own arms stay exhaustive over what is left.
+ */
+export function grantCardStandingReach(ask: Pick<CredentialGrantAskRow, "domainScopeKey">): Exclude<GrantScopeReach, "session"> | undefined {
+  const reach = grantScopeReachOf(ask.domainScopeKey);
+  return reach === "session" ? undefined : reach;
+}
+
+export function grantCardActions(ask: CredentialGrantAskRow): readonly DirectMessageAction[] {
+  const standing: readonly DirectMessageAction[] =
+    grantCardStandingReach(ask) === undefined ? [] : [{ id: grantCardActionId(ask.id, "standing"), intent: "affirm", label: `Approve ${grantModePhrase("standing")}` }];
+  return [
+    { id: grantCardActionId(ask.id, "once"), intent: "affirm", label: `Approve ${grantModePhrase("once")}` },
+    { id: grantCardActionId(ask.id, "session"), intent: "affirm", label: `Approve ${grantModePhrase("session")}` },
+    ...standing,
+    { id: grantCardActionId(ask.id, "decline"), intent: "reject", label: "Decline" },
+  ];
+}
+
+/** Present only when a DELEGATED WORKER raised the ask. It is deliberately not on the row: it changes the card's copy and nothing else, so the owner's decision, the anti-nag key and the audit join are unchanged. seatLabel is the deployment's own configured agent name, resolved by the caller and never model input. */
+export interface GrantAskWorkerOrigin {
+  readonly seatLabel: string;
+}
+
+/** The card text, HOST-AUTHORED throughout except the quoted purpose. A caller that resolved no display name passes an empty string and never a principal key; an absent conversation label makes the card say "that conversation" and never an id. A worker-raised card names the AGENT the owner knows, then states the worker context beneath it. */
+export function grantCardText(ask: CredentialGrantAskRow, requesterLabel: string, workerOrigin?: GrantAskWorkerOrigin, conversationLabel?: string): string {
+  // Every display name goes through the sanitiser: these are identity-plane strings, not host copy, and a name carrying a newline can forge one of the bullets that tell the owner what they are agreeing to.
+  const who = flatDisplayName(grantRequesterPhrase(requesterLabel));
+  const seat = workerOrigin === undefined ? undefined : flatDisplayName(workerOrigin.seatLabel);
+  const vendor = connectorDisplayName(ask.connector);
+  const where = flatDisplayName(grantConversationPhrase(conversationLabel));
+  // HOW WIDE IS THE KEY THIS ASK CARRIES? It is what a STANDING tap on this card will bind to, so it
+  // is what the standing button and the closing line may promise. `session` ⇒ no key, and a standing
+  // tap binds to the asking conversation alone (OPE-1972). `room` ⇒ every conversation in this one
+  // room, threads included, for as long as the grant lives (OPE-2012). `domain` ⇒ the main
+  // conversation of every room declared into this room's domain. THREE arms, because the middle one is
+  // neither of the other two: folding it into `domain` would claim a thread exclusion the row has not
+  // got, and folding it into `session` would hide that it outlives this conversation.
+  const reach = grantScopeReachOf(ask.domainScopeKey);
+  // 🔴 THE BODY AND THE BUTTONS READ ONE ANSWER (OPE-2160). A bullet describing an arm that is not
+  // rendered is the same defect in the other direction — it offers a span this ask cannot carry.
+  const standingReach = grantCardStandingReach(ask);
+  return [
+    `*${seat ?? who}* asks to use your ${vendor} account, for ${where}.`,
+    "",
+    // THE WORKER CONTEXT, in full and host-authored. Nothing here quotes the worker's brief: that
+    // string is MODEL-authored, and the purpose line below is the one model-authored thing this card
+    // shows on purpose.
+    ...(workerOrigin === undefined
+      ? []
+      : [
+          `• Who it is for: ${who}, in their conversation with ${seat}.`,
+          `• How it was raised: ${seat} gave the work to a background task, and the task raised this ask. The task ends when its work does, and it never sees your answer.`,
+          `• What a grant reaches: that conversation, never the background task.`,
+          "",
+        ]),
+    // What the tool DOES, never what it is called: the vendor tool id, the composed resource column and the mounted grant name all named the borrow and none of them said what it would do. The mounted name is unchanged on the row — it is the mint contract — and is simply not shown.
+    askActionSentence(ask, "want"),
+    `Their reason: "${quotedPurpose(ask.purpose)}"`,
+    // 🔴 THE CAUTION SITS WITH THE PINNED VALUES, NOT ABOVE THE REASON (cold review, 2026-09-08). It
+    // tells the owner where the real answer is, and the line under it must therefore BE that answer —
+    // above `Their reason` it pointed them at the requester's own prose.
+    ...unreviewedToolLines(ask),
+    ...frozenLines(ask),
+    // 🔴 AN ASK FOR AN ARM THIS CARD DOES NOT OFFER IS SAID OUT LOUD (OPE-2160). Printing "They asked
+    // for: 30 days. You choose the answer." over three buttons that hold no 30-day answer reads as a
+    // broken card, and an owner hunting for the missing button is an owner who taps the wrong one.
+    standingReach !== undefined || ask.requestedMode !== "standing"
+      ? `They asked for: ${GRANT_MODE_WORDS[ask.requestedMode]}. You choose the answer.`
+      : `They asked for: ${GRANT_MODE_WORDS.standing}. That is not on offer here — see below. You choose from the answers that are.`,
+    "",
+    // No route in this deployment parses a typed answer, so the copy must never offer one: an owner who replied to the old copy got silence and their request then lapsed.
+    "Tap one button to answer:",
+    // A "once" grant spends one call that actually GOES OUT: the burn happens before the vendor call, and a call the host can prove never left is refunded. This card is the only surface the owner ever reads, so it must state that bound rather than the comfortable one.
+    `• *Approve ${GRANT_MODE_WORDS.once}* — one call that actually reaches ${vendor}. An attempt blocked before it is sent costs nothing and can be retried — at most ${String(GRANT_ONCE_MAX_ATTEMPTS_PER_TURN)} attempts in one turn.`,
+    `• *Approve for ${GRANT_MODE_WORDS.session}* — every call that conversation makes, until the grant expires.`,
+    // 🔴 THE STANDING BUTTON NAMES THE REACH THIS ASK WILL ACTUALLY MINT (OPE-1950, narrowed by
+    // OPE-1972, given its third arm by OPE-2012), and that is why it BRANCHES. A standing tap binds to
+    // the ask's own `domainScopeKey` when it carries one and to the ASKING SESSION otherwise
+    // (`credential-grant.ts` → `grantScopeKeyForMode`), and since OPE-1972 that key is absent on every
+    // ask a thread seat raised — a seat `mayRaiseGrantAsk` still admits. Rendering the domain sentence
+    // unconditionally told such an owner "it does NOT reach a thread" about a row that would be
+    // spendable in exactly that thread and nowhere else: the one boundary on the consent surface,
+    // false in the permissive direction. The ROOM arm is the same hazard in the other direction — its
+    // row reaches one room, and the domain sentence would have an owner believe they had lent their
+    // account to every room of a group. The card is the only place the owner learns any of this before
+    // they tap, so each arm says what is wider than the session button AND what is excluded.
+    standingReach === undefined ? standingWithheldLine() : standingButtonLine(standingReach),
+    "• *Decline* — nothing is granted.",
+    "",
+    // The copy promises nothing about the buttons working: on a surface whose interaction router does not claim this prefix, even a tap does not arrive. It says only what holds everywhere — an answer that does not reach us grants nothing and the ask lapses — and must never tell a reader their tap worked.
+    "A button is the only thing that can answer this. If the buttons are missing, or a tap seems to do nothing, nothing has been granted — the request then lapses on its own and they can raise a fresh one.",
+    closingReassurance(ask, where, vendor, reach),
+  ].join("\n");
+}
+
+/** What this ask would let the conversation do, in one sentence. The action clause is host copy from a reviewed table; the target label is the requester's own model-authored name and renders as quoted data, and a row whose label cannot be recovered names the action alone. */
+function askActionSentence(ask: CredentialGrantAskRow, lead: "want" | "wanted"): string {
+  const opening = lead === "want" ? "They want to" : "They asked to";
+  return `${opening} ${grantBorrowPhrase(ask)}.`;
+}
+
+/** What was borrowed, in one clause: the reviewed action phrase plus the requester's own target label, rendered as quoted data. Shared with the room's resolution notice rather than inlined twice, so the owner's card and the room's answer name one borrow and not two. */
+export function grantBorrowPhrase(row: {
+  readonly connector: string;
+  readonly mcpTool?: string;
+  readonly resource: string;
+  readonly frozenArgs?: GrantJsonObject;
+}): string {
+  const action = grantActionPhrase(row.connector, row.mcpTool);
+  const target = grantResourceTargetLabel(row);
+  return target === undefined ? action : `${action} — "${quotedPurpose(target)}"`;
+}
+
+/**
+ * The STANDING button's own sentence, one arm per reach the ask can mint (OPE-2012). Each arm names
+ * what the button buys over the two above it AND what it is still excluded from, because those two
+ * facts are the whole of what the owner is choosing between.
+ *
+ * 🔴 THE `room` ARM NAMES THE ROOM, THREADS INCLUDED, AND MAY NOT BORROW EITHER NEIGHBOUR'S SENTENCE.
+ * Its row is reachable from every wake in that one room, because an unseated deployment stamps no
+ * grain and `domainKeyOf` collapses a thread onto its parent room — so the domain arm's "does NOT
+ * reach a thread" would be a boundary the row has not got, and the session arm's "this one
+ * conversation" would have the owner believe it dies with the conversation when outliving it is the
+ * entire point. What the arm may promise is the ROOM and the TIME, and it promises exactly those.
+ */
+function standingButtonLine(reach: Exclude<GrantScopeReach, "session">): string {
+  const head = `• *Approve for ${GRANT_MODE_WORDS.standing}*`;
+  const days = String(STANDING_DAYS);
+  if (reach === "domain") {
+    return `${head} — the main conversation of this room and of the rooms declared into this room's domain, for ${days} days. Wider than the two above: those other rooms can spend it too, for this one tool with the values below. It does NOT reach a thread of those rooms, and no scheduled run can spend it — a person has to be here asking.`;
+  }
+  return `${head} — this room, for ${days} days: every conversation here, threads included, and it keeps working after this one ends and a new one takes its place. Wider than the two above: anyone talking to me in this room can spend it, for this one tool with the values below. No OTHER room gets it, and no scheduled run can spend it — a person has to be here asking.`;
+}
+
+/**
+ * THE LINE THAT STANDS IN FOR THE ABSENT STANDING ARM (OPE-2160).
+ *
+ * 🔴 THE CARD SAYS WHY, RATHER THAN SIMPLY DROPPING A BUTTON. The owner may have been asked for
+ * {@link GRANT_MODE_WORDS.standing} and is reading a card that cannot answer it, so silence there
+ * reads as a broken card and sends them hunting for a button that was never rendered. The sentence
+ * names the reason and the remedy, and it promises nothing: the arm is absent because a grant of that
+ * length has to bind to a room this deployment can name, and this ask carries no such room.
+ *
+ * 🔴 IT NEVER OFFERS A NARROWER 30 DAYS. That is precisely the row OPE-2160 forbids — a 30-day clock
+ * on a key that dies with the asking conversation.
+ */
+function standingWithheldLine(): string {
+  return (
+    `• *${String(STANDING_DAYS)} days* is NOT offered for this request. A grant that long has to belong to a room this deployment can name, ` +
+    "and this request did not come from one — so it would stop working as soon as this conversation ends, without telling anyone. " +
+    "An operator can declare that room into a domain if this should be lendable for longer."
+  );
+}
+
+/**
+ * The last line is CONDITIONAL ON THE FREEZE: an unpinned grant reaches whatever the tool reaches, and frozenArgs = {} is a state the flow fully supports. An unconditional reassurance would let an owner approve a session-wide read of their whole account believing it was one page.
+ * 🔴 IT STATES THE BOUND THE CODE ENFORCES, NOT A NARROWER ONE (OPE-1950, narrowed by OPE-1972). The
+ * card is rendered BEFORE the owner picks a mode, so its closing promise has to hold for the WIDEST
+ * button, which is the standing one — and how wide THAT is depends on the key this ask carries. On a
+ * domain-keyed ask it reaches the main conversation of every room grouped with this one, so both "No
+ * other conversation gets it" and its first replacement "No other room gets it" are false there. What
+ * is true of all three modes, and is what the lookup actually enforces, is the rest of the row: this
+ * one account, this one tool, and the pinned values — so the sentence names those, and claims a room
+ * boundary only on the arms whose key really has one. It does carry the one boundary that holds for
+ * every mode and every key: nobody here, nobody spends it.
+ */
+function closingReassurance(ask: CredentialGrantAskRow, where: string, vendor: string, reach: GrantScopeReach): string {
+  const action = grantActionPhrase(ask.connector, ask.mcpTool);
+  const pinned = Object.keys(ask.frozenArgs ?? {}).length > 0;
+  // The reach clause BRANCHES with the standing button above and for the same reason: this sentence
+  // has to hold for the WIDEST button, and the widest button is narrower on an ask that carries a room
+  // key, narrower again on one that carries no key at all.
+  const reachClause = {
+    domain: "Only the main conversation of the asker's room and of the rooms declared into its domain can spend it",
+    room: "Only conversations in the asker's own room can spend it",
+    session: "Only the conversation they asked from can spend it",
+  }[reach];
+  const bound = `Whichever button you press, this lends ONE thing: your ${vendor} account doing that one job, and nothing else you can reach in ${vendor}. ${reachClause}, only while somebody is there asking, and only until it ends.`;
+  return pinned
+    ? `Approving lets ${where} ${action} with your account — the pinned values above, and nothing else in ${vendor}. ${bound}`
+    : `Approving lets ${where} ${action} with your account, choosing for itself which one, every time. Nothing is pinned, so this reaches whatever that tool can read in your ${vendor} account. ${bound}`;
+}
+
+/** The caution an UNREVIEWED tool earns — see {@link grantActionIsReviewed}. Empty for a reviewed
+ *  one, so the line means something on the cards that carry it. */
+function unreviewedToolLines(ask: CredentialGrantAskRow): readonly string[] {
+  if (grantActionIsReviewed(ask.connector, ask.mcpTool)) return [];
+  return [
+    `⚠️ This deployment has no plain description of what they asked for. It can only READ — a write is refused before any card is ever sent — but exactly what it reads in ${connectorDisplayName(ask.connector)} is decided by the pinned values on the next line. Read them, and decline unless you know what this is.`,
+  ];
+}
+
+/** Every key gets its own line and the cap is applied PER VALUE, so a requester cannot pad the first value until the real target falls past the cut — the owner is the review of these values, and a card that can hide one is not a review. A truncated value says so, and an empty object says so out loud, because an unfrozen borrow is wider than a frozen one and must never read as narrower by saying nothing. */
+function frozenLines(ask: CredentialGrantAskRow): readonly string[] {
+  const frozen = ask.frozenArgs;
+  if (frozen === undefined) return [];
+  const keys = Object.keys(frozen).sort();
+  if (keys.length === 0) {
+    return ["Nothing is pinned down: that conversation would choose every detail of the call, which is a wider ask than pinning one thing."];
+  }
+  const shown = keys.slice(0, FROZEN_KEYS_SHOWN);
+  const lines = [
+    keys.length === 1 ? "It is pinned to this one value, which they cannot change:" : `It is pinned to these ${String(keys.length)} values, which they cannot change:`,
+    ...shown.map((key) => {
+      const k = cardData(key, FROZEN_KEY_MAX);
+      const name = k.truncated ? `\`${k.text}\` \u26a0\ufe0f (name truncated)` : `\`${k.text}\``;
+      return `    \u00b7 ${name} = ${frozenValueLine(frozen[key])}`;
+    }),
+  ];
+  if (keys.length > shown.length) {
+    // 🔴 THE COPY STEERS TO DECLINE, because that is the safe answer to "there is more here than I
+    // can show you". It never implies the unshown ones are minor.
+    lines.push(
+      `    \u00b7 \u26a0\ufe0f ${String(keys.length - shown.length)} more pinned value(s) are NOT shown here. Decline unless you know exactly what this asks for.`,
+    );
+  }
+  return lines;
+}
+
+/** How many fixed arguments the card lists before it stops and SAYS it stopped. A bound rather than
+ *  a taste: a surface caps a message, and a card truncated by the PLATFORM would drop keys silently,
+ *  which is the defect this whole function exists to close. */
+const FROZEN_KEYS_SHOWN = 25;
+/** Per-value and per-key caps, applied to each LINE rather than to the whole object. */
+const FROZEN_VALUE_MAX = 120;
+const FROZEN_KEY_MAX = 60;
+
+/** One fixed argument's value, rendered as quoted data, with any truncation SAID OUT LOUD. */
+function frozenValueLine(value: unknown): string {
+  const rendered = cardData(JSON.stringify(value) ?? "null", FROZEN_VALUE_MAX);
+  return rendered.truncated
+    ? `\`${rendered.text}\` \u26a0\ufe0f (value truncated \u2014 the grant fixes the FULL value, which is longer than this)`
+    : `\`${rendered.text}\``;
+}
+
+/** Render model-authored text as one line of card data — quote characters and newlines stripped so the string cannot escape its span — with a caller-chosen cap and no appended ellipsis. truncated compares against the CAP and never against the input, because stripping a quote is not truncation and a warning that fires on everything is one an owner learns to ignore. */
+function cardData(raw: string, max: number): { readonly text: string; readonly truncated: boolean } {
+  const flat = raw.replace(/[\r\n]+/gu, " ").replace(/["'`]/gu, "").trim();
+  return flat.length > max ? { text: flat.slice(0, max), truncated: true } : { text: flat, truncated: false };
+}
+
+/** The lapsed card speaks to what a tap would DO — nothing, because the approve CAS carries an unexpired conjunct — and says nothing about whether the buttons are still rendered, which is a property of today's two arms rather than of the seam. requesterNotified is a parameter rather than an assumption, because the lapse notice genuinely may not go out. */
+export function expiredGrantCardText(ask: CredentialGrantAskRow, requesterNotified: boolean): string {
+  return [
+    `⌛ EXPIRED — this request timed out.`,
+    "",
+    askActionSentence(ask, "wanted"),
+    "",
+    "Nothing was granted and nothing was spent. Tapping a button on this card now does nothing.",
+    requesterNotified
+      ? "The person who asked has been told the request lapsed, and they can ask again if they still need it."
+      : "This deployment could not reach the conversation they asked from, so they have NOT been told — they may still be waiting on an answer.",
+  ].join("\n");
+}
+
+/** The card an owner is left with when the approve-time catalogue read refused the ask: they pressed a button and nothing happened, and silence there reads as a broken button. It names no vendor error text, because what the connection published is data from outside and a card is host-authored copy. */
+export function refusedGrantCardText(ask: CredentialGrantAskRow, gate: GrantApproveGate): string {
+  const vendor = connectorDisplayName(ask.connector);
+  return [
+    `🚫 NOT GRANTED — your ${vendor} account could not lend this.`,
+    "",
+    askActionSentence(ask, "wanted"),
+    "",
+    // A row that names NO vendor tool reaches the tool_absent gate too, so it gets its own sentence: telling that owner their connection publishes no tool by that name would state something about their account that is not true of it.
+    ask.mcpTool === undefined
+      ? "This request was raised by an older build and this one cannot complete it. Nothing was granted and nothing was spent."
+      : gate === "tool_absent"
+        ? `Your ${vendor} account does not offer what they asked for, so there was nothing to lend. Nothing was granted and nothing was spent.`
+        : `That request pins values the ${vendor} tool does not take, so the grant could never have been spent. Nothing was granted and nothing was spent.`,
+    "This request is closed. Ask them to raise a fresh one if it is still needed.",
+  ].join("\n");
+}
+
+/** Why an approve-time catalogue read refused an ask. A closed set: each arm is a boundary the card,
+ *  the requester's notice and the audit row all name with the same word. */
+export type GrantApproveGate = "tool_absent" | "frozen_args_unknown";
+
+/** The card an owner is left with after they approved — it replaces the open question with what was answered, so four live-looking buttons no longer sit under a closed request. mode is the mode the owner actually TAPPED, which may be broader than what was asked. */
+export function approvedGrantCardText(ask: CredentialGrantAskRow, grant: Pick<CredentialGrantRow, "mode" | "expiresAt">, nowMs: number): string {
+  return [
+    `✅ APPROVED — you approved this request.`,
+    "",
+    askActionSentence(ask, "wanted"),
+    "",
+    // A duration and a clock time, never the raw ISO column, which told the owner neither how long they had granted nor when it ends. nowMs is the caller's clock, and it is what makes the duration half sayable at all.
+    `You approved ${grantModePhrase(grant.mode)}, ${grantExpiryPhrase(grant.expiresAt, nowMs)}.`,
+    "Tapping a button on this card now does nothing.",
+  ].join("\n");
+}
+
+/** The card an owner is left with after they declined. It names no reason: a person's reason for refusing their own credential is theirs. */
+export function declinedGrantCardText(ask: CredentialGrantAskRow): string {
+  return [
+    `🚫 DECLINED — you declined this request.`,
+    "",
+    askActionSentence(ask, "wanted"),
+    "",
+    "Nothing was granted and nothing was spent. Tapping a button on this card now does nothing.",
+  ].join("\n");
+}
+
+/** The ask stays PENDING and nothing is spent — connecting is a step, not a refusal, so the copy sends the owner back to the card. The URL is CAPABILITY-BEARING, since whoever opens it binds that account: it goes to the owner's own DM, and it is never logged, never audited and never posted into the requesting room. */
+export function grantConsentPromptText(ask: CredentialGrantAskRow, url: string): string {
+  const vendor = connectorDisplayName(ask.connector);
+  return [
+    // Two texts still land: the surface answers the tap with an ephemeral of its own, and suppressing that is a delivery change rather than a copy one. What changed is that the second text no longer repeats the step.
+    `You need to connect your ${vendor} account first.`,
+    "",
+    "Open this link (it connects your account only, do not forward it), then press Approve again:",
+    url,
+    "",
+    "Nothing has been granted and nothing has been spent.",
+  ].join("\n");
+}
+
+/** Why a grant DM did not go out. `owner_stopped_dms` and `owner_dm_unreadable` are the recipient's own plane (OPE-1855): the first is their decision, the second is a store that did not answer, and the two are never folded together — reporting an outage as a person's decision states a fact about them that nobody established. */
+export type GrantCardRefusal = "no_dm_arm" | "send_failed" | "owner_stopped_dms" | "owner_dm_unreadable";
+
+export type GrantCardDelivery =
+  | { readonly delivered: true; readonly surfaceId: string; readonly messageId: string }
+  | { readonly delivered: false; readonly reason: GrantCardRefusal };
+
+/** The person address the OWNER's stop is keyed on — `set_dm_delivery` writes this exact spelling from the owner's own DM, so the ask row's platform and native id must compose it the same way or a stop would key on a string no grant can name. */
+export function grantOwnerDmAddress(ask: Pick<CredentialGrantAskRow, "ownerPlatform" | "ownerNativeId">): string {
+  return personAddress(ask.ownerPlatform, ask.ownerNativeId);
+}
+
+/** The footer every grant DM carries — the SAME host-authored line `dm_person` appends, naming who asked, which conversation it came from, and how to stop it. The owner is being cold-addressed about somebody else's errand, so the line that tells them how to stop it belongs on this plane exactly as much as on the chat one. */
+function grantDmFooter(ask: CredentialGrantAskRow): string {
+  return dmDeliveryFooter({ requestedBy: ask.requesterPrincipalId, fromContainer: ask.scopeKey });
+}
+
+/** The refusal a {@link ProactiveDmRefusedError} maps to, or a rethrow for anything else — a transport
+ *  error is the caller's `send_failed`, and a bug must not be laundered into a boundary. */
+function grantDmRefusal(err: unknown): GrantCardRefusal {
+  if (!(err instanceof ProactiveDmRefusedError)) return "send_failed";
+  return err.boundary === "stopped" ? "owner_stopped_dms" : "owner_dm_unreadable";
+}
+
+/**
+ * Deliver one ask's card to its owner. An unreachable owner is an HONEST REFUSAL, never a queued ask: a platform with no DM arm cannot cold-address a person, so the caller must tell the requester so rather than write a pending row nobody will ever see.
+ * 🔴 IT TAKES THE PROACTIVE-DM ROAD (OPE-1855), so the owner's own stop refuses it, the message carries the stop line, and one audit row names the plane. This plane used to address the post arm directly, which is how a person who had told the agent to stop still received this card.
+ */
+export async function deliverGrantCard(
+  ask: CredentialGrantAskRow,
+  where: DmDeliveryWhere,
+  requesterLabel: string,
+  workerOrigin?: GrantAskWorkerOrigin,
+  conversationLabel?: string,
+): Promise<GrantCardDelivery> {
+  if (!canDeliverDirectMessage(ask.ownerPlatform)) return { delivered: false, reason: "no_dm_arm" };
+  try {
+    const landed = await deliverProactiveDm({
+      where,
+      plane: "credential.grant.card",
+      platform: ask.ownerPlatform,
+      recipientId: ask.ownerNativeId,
+      address: grantOwnerDmAddress(ask),
+      text: grantCardText(ask, requesterLabel, workerOrigin, conversationLabel),
+      footer: grantDmFooter(ask),
+      requestedBy: ask.requesterPrincipalId,
+      attributedTo: ask.requesterPrincipalId,
+      // NO `first` and no delivery record: this plane has no carded/flowing split to tell apart, and
+      // the record belongs to `chat.dm` alone (see `recordsDelivery` in the manifest).
+      actions: grantCardActions(ask),
+    });
+    return { delivered: true, messageId: landed.messageId, surfaceId: landed.surfaceId };
+  } catch (err) {
+    // The owner stopped, the stop could not be read, or the send genuinely failed (a revoked bot
+    // token, a closed DM). The caller reports it as a refusal to the requester; it must NOT leave a
+    // pending ask that nobody was ever shown.
+    const reason = grantDmRefusal(err);
+    // OPE-2063: the failure used to vanish here. The line names the owner key, the reason and the
+    // error's own message (capped) — never a token or a vendor body.
+    const status = typeof (err as { status?: unknown })?.status === "number" ? ` status=${String((err as { status: number }).status)}` : "";
+    const message = err instanceof Error ? err.message : String(err);
+    console.warn(`[open-everywhere:grant] grant card DM to ${ask.ownerPrincipalId} not delivered (${reason})${status}: ${message.slice(0, 200)}`);
+    return { delivered: false, reason };
+  }
+}
+
+/** Rewrite one lapsed ask's card to say expired. TRUE when it landed; FALSE means the card was not rewritten and is never an error — the CAS has already closed the ask, and the rewrite is cosmetic. */
+export async function expireGrantCard(ask: CredentialGrantAskRow, requesterNotified: boolean): Promise<boolean> {
+  return await rewriteGrantCard(ask, expiredGrantCardText(ask, requesterNotified));
+}
+
+/** Rewrite one ask's card to say the approve-time catalogue read refused it. TRUE when it landed; FALSE is never an error — see rewriteGrantCard. */
+export async function refuseGrantCard(ask: CredentialGrantAskRow, gate: GrantApproveGate): Promise<boolean> {
+  return await rewriteGrantCard(ask, refusedGrantCardText(ask, gate));
+}
+
+/** Rewrite one ask's card to say the OWNER approved it. TRUE when it landed; FALSE is never an error — see rewriteGrantCard. */
+export async function approveGrantCard(ask: CredentialGrantAskRow, grant: Pick<CredentialGrantRow, "mode" | "expiresAt">, nowMs: number): Promise<boolean> {
+  return await rewriteGrantCard(ask, approvedGrantCardText(ask, grant, nowMs));
+}
+
+/** Rewrite one ask's card to say the OWNER declined it. TRUE when it landed; FALSE is never an error — see rewriteGrantCard. */
+export async function declineGrantCard(ask: CredentialGrantAskRow): Promise<boolean> {
+  return await rewriteGrantCard(ask, declinedGrantCardText(ask));
+}
+
+/** Replace one ask's card body in the owner's DM. FALSE means the card was not rewritten and is never an error: the row carries no card locus, or the owner's surface has no edit transport. The row's own terminal state is the control, and the rewrite is cosmetic. */
+async function rewriteGrantCard(ask: CredentialGrantAskRow, text: string): Promise<boolean> {
+  if (ask.cardSurfaceId === undefined || ask.cardMessageId === undefined) return false;
+  return await editSurfaceText(ask.ownerPlatform, { channelId: ask.cardSurfaceId, messageId: ask.cardMessageId }, text);
+}
+
+/**
+ * DM the owner the link that connects their own account, with no buttons. FALSE means this deployment cannot cold-address the owner on their platform — no DM arm, their own stop, an unreadable stop, or a failed send — which the caller reports rather than leaving them staring at a card that will not move.
+ * 🔴 IT TAKES THE ROAD for the same reason the card does (OPE-1855): it is a DM this agent starts, so the owner's stop answers it. 🔴 THE URL IS CAPABILITY-BEARING and must never reach an audit row — the road writes ids only, never the text, which is what keeps that true.
+ */
+export async function deliverGrantConsentPrompt(ask: CredentialGrantAskRow, where: DmDeliveryWhere, url: string): Promise<boolean> {
+  if (!canDeliverDirectMessage(ask.ownerPlatform)) return false;
+  try {
+    await deliverProactiveDm({
+      where,
+      plane: "credential.grant.consent",
+      platform: ask.ownerPlatform,
+      recipientId: ask.ownerNativeId,
+      address: grantOwnerDmAddress(ask),
+      text: grantConsentPromptText(ask, url),
+      footer: grantDmFooter(ask),
+      requestedBy: ask.requesterPrincipalId,
+      attributedTo: ask.requesterPrincipalId,
+    });
+    return true;
+  } catch {
+    // The owner stopped, the stop could not be read, or the send genuinely failed. The caller
+    // reports it; it must NOT claim the owner was shown a link they never received.
+    return false;
+  }
+}