@open-everywhere/core 0.1.0

package/agent/approvals/session-grant.ts

@@ -0,0 +1,173 @@
+// The ONE predicate deciding which pending kinds may carry a session grant, and a LEAF module (it imports only ./types.js) so card.ts can depend on it without a cycle. Two planes share this file and must not share a word: the session-grant plane says GRANT, the routine plane says DECLARED PERMISSION, and the connector grain the routine plane reads is PER TOOL, with the legacy per-connector grain refused rather than widened.
+
+import type { PendingActionRow } from "./types.js";
+
+/** The pr.open session-grant memo kind (OPE-53) — pinned to pr-open.ts's registered kind. */
+const PR_OPEN_KIND = "pr.open";
+
+/** Named as a constant because two places must recognise this shape in order to REFUSE it: nothing may look such a row up, and the renderer must show a stored one as the inert record it is. It is a PERSISTED string sitting in deployed databases, so the value does not move. */
+export const CONNECTOR_OP_KIND_PREFIX = "connector.op:";
+
+/** The LEGACY per-connector session-grant memo kind. Nothing consults a row of this shape; it is kept so the two sites that must refuse it name one constant. */
+export function connectorSessionKind(connector: string): string {
+  return `${CONNECTOR_OP_KIND_PREFIX}${connector}`;
+}
+
+/** The memo-kind prefix of the per-TOOL grain the routine plane declares and the fence reads. It is
+ *  deliberately NOT `connector.op:` — a stored legacy row must never satisfy a per-tool lookup. */
+const CONNECTOR_TOOL_KIND_PREFIX = "connector.tool:";
+
+/** The per-TOOL declared-permission memo kind: one row, one qualified connector-op tool. THE WHOLE TOOL NAME IS THE KEY and nothing splits it, so a connection slug containing `__` cannot turn one declaration into authority over every connection sharing its head. */
+export function connectorToolPermissionKind(tool: string): string {
+  return `${CONNECTOR_TOOL_KIND_PREFIX}${tool}`;
+}
+
+/** Memo-kind prefixes of the ROUTINE PERMISSION CARD's own bookkeeping (OPE-1290) — the "a card is
+ *  live for this" marker and the "a human declined this" marker. They ride the same
+ *  `SessionApprovalRow` table, under the same routine grant key, as the grants they are about. */
+const ROUTINE_CARD_ASKED_PREFIX = "routine.permission.asked:";
+const ROUTINE_CARD_DECLINED_PREFIX = "routine.permission.declined:";
+
+/** The "a permission card is live for this" memo kind. `grantKind` is the kind a click would WRITE
+ *  (`pr.open`, `connector.tool:<tool>`), so a marker can never be read under a different one. */
+export function routinePermissionAskedMemo(grantKind: string): string {
+  return `${ROUTINE_CARD_ASKED_PREFIX}${grantKind}`;
+}
+
+/** The "a human declined this permission for this generation" memo kind. */
+export function routinePermissionDeclinedMemo(grantKind: string): string {
+  return `${ROUTINE_CARD_DECLINED_PREFIX}${grantKind}`;
+}
+
+/** How a routine declaration SPELLS a grant kind, or undefined for a kind no declaration maps onto; a legacy per-connector row answers undefined on purpose, because it lifts no tool. The candidate is run back through routinePermissionKind, which is what stops a stored kind this build no longer accepts being spelled back as a declaration the routine tools would refuse. */
+export function declarationForPermissionKind(kind: string): string | undefined {
+  if (kind === PR_OPEN_KIND) return PR_OPEN_KIND;
+  if (!kind.startsWith(CONNECTOR_TOOL_KIND_PREFIX)) return undefined;
+  const declaration = `${CONNECTOR_TOOL_DECLARATION_PREFIX}${kind.slice(CONNECTOR_TOOL_KIND_PREFIX.length)}`;
+  return routinePermissionKind(declaration) === kind ? declaration : undefined;
+}
+
+/** Which marker a memo kind is, and the grant kind it is about. */
+export interface RoutinePermissionMemoParts {
+  /** `asked` = a card was posted for this permission; `declined` = a human refused it. */
+  readonly marker: "asked" | "declined";
+  /** The kind a click would WRITE — `pr.open`, `connector.tool:<tool>`. */
+  readonly grantKind: string;
+}
+
+/** Narrower than isRoutinePermissionMemoKind on purpose: a bare prefix with no grant kind after it names no permission, so this answers undefined and a review surface renders no ask for the empty string. The predicate still calls such a row a marker, because a marker mistaken for a grant tells a human the routine may do something no row permits. */
+export function routinePermissionMemoParts(kind: string): RoutinePermissionMemoParts | undefined {
+  for (const [prefix, marker] of [
+    [ROUTINE_CARD_ASKED_PREFIX, "asked"],
+    [ROUTINE_CARD_DECLINED_PREFIX, "declined"],
+  ] as const) {
+    if (!kind.startsWith(prefix)) continue;
+    const grantKind = kind.slice(prefix.length);
+    return grantKind.length > 0 ? { marker, grantKind } : undefined;
+  }
+  return undefined;
+}
+
+/** EVERY reader of a routine's rows must ask this: the two markers live under the routine's grant key, so anything walking that key sees them, and a marker rendered as a permission is the worst failure on this plane. It tests the PREFIX alone, so it is true for a prefix carrying no grant kind. */
+export function isRoutinePermissionMemoKind(kind: string): boolean {
+  return kind.startsWith(ROUTINE_CARD_ASKED_PREFIX) || kind.startsWith(ROUTINE_CARD_DECLINED_PREFIX);
+}
+
+/** An inert legacy per-connector row LIFTS NOTHING, so no reader may count it as authority. A caller that merely counts rows would report it as a standing permission, which tells a human the routine may do something no row permits. */
+export function isLegacyConnectorOpKind(kind: string): boolean {
+  return kind.startsWith(CONNECTOR_OP_KIND_PREFIX);
+}
+
+/** The memo kind an "Approve for session" click should WRITE and the gate should CONSULT, or null when the row is not session-grantable — the click then degrades to a one-off approve and no session button is offered. Null for every injection-gate kind, which stays strictly per-call. */
+export function sessionGrantKind(row: Pick<PendingActionRow, "kind" | "argsJson">): string | null {
+  if (row.kind === PR_OPEN_KIND) return PR_OPEN_KIND;
+  return null;
+}
+
+// A routine fire runs under a routine grant key rather than a window token, so everything above is reused verbatim for the run-time half. What differs is the LIFETIME, so what differs here is only how the two are named and what a creation card may DECLARE up front.
+
+/** Mirrors routines/routine.ts {@link ROUTINE_PERMISSION_PREFIX} — duplicated as a literal, not
+ *  imported, to keep this file the leaf its header promises (card.ts depends on it). The two are
+ *  pinned equal by scripts/routine-declared-permissions-test.ts, exactly as card.ts's "oe_approval:" is. */
+export const ROUTINE_PERMISSION_PREFIX = "oe-routine:";
+
+/** How long a grant written under `key` lasts, and the ONE place the lifetime is named: it drives the middle button's LABEL, so a human clicking a standing grant is never told it is for a session, and an undefined key means session. Measured 2026-08-28: the routine arm has no live path, because only a FIRE carries a routine grant stamp and every fire is unattended, so no card with a routine key is posted. */
+export function permissionLifetime(memoSessionId: string | undefined): "routine" | "session" {
+  return memoSessionId !== undefined && memoSessionId.startsWith(ROUTINE_PERMISSION_PREFIX) ? "routine" : "session";
+}
+
+/** The ONE place both card renderers get the middle button's label, so a Slack and a Discord card cannot disagree about what a click grants. It is read off the FROZEN key in the pending's args — the same value the click path writes the memo under — and unparseable or absent args fall back to the session wording, which is the conservative direction. */
+export function grantButtonLabel(row: Pick<PendingActionRow, "argsJson">): string {
+  let sessionId: string | undefined;
+  try {
+    const parsed = JSON.parse(row.argsJson) as { sessionId?: unknown };
+    if (typeof parsed.sessionId === "string") sessionId = parsed.sessionId;
+  } catch {
+    /* unparseable frozen args → session wording */
+  }
+  return permissionLifetime(sessionId) === "routine" ? "Approve for this routine (standing)" : "Approve for session";
+}
+
+/** The declarable spelling of a per-tool connector permission. The value after the prefix is the tool name VERBATIM, so the card a human reads, the row an auditor reads and the string the runtime matched on are the same. */
+const CONNECTOR_TOOL_DECLARATION_PREFIX = "tool:";
+
+/** One `__`-delimited segment of a qualified tool name: no `:`, which stops a declaration smuggling a different memo kind, and no empty segment. UPPERCASE is admitted and widens nothing, because every comparison on the tool name is case-SENSITIVE, while a lowercase-only charset made a whole class of real vendor tool undeclarable. */
+const TOOL_NAME_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9_-]*$/u;
+
+/** The reserved first segment of the credential-grant plane's names, duplicated as a literal to keep this file a leaf and pinned behaviourally by a test. A routine may not declare a permission on that plane from here. */
+const RESERVED_TOOL_NAMESPACE = "grant";
+
+/** CASE-INSENSITIVE, and that is what keeps the uppercase widening from opening a seam. The mint writes grant name segments lowercase, so a mixed-case spelling would be inert today, but "inert because nothing is mounted there" is weaker than "refused here", and the refusal is what this layer carries. */
+function namesReservedNamespace(head: string): boolean {
+  return head.toLowerCase() === RESERVED_TOOL_NAMESPACE;
+}
+
+/** Exactly two shapes are legal: `pr.open`, and `tool:<qualified connector-op tool>`. Every injection gate and the credential-grant plane's reserved namespace stay inexpressible here, but the per-tool grain CAN spell a destructive verb, so DESTRUCTIVE-NEVER is enforced twice elsewhere — at declaration review and at lift time — and neither place may be removed. */
+export function routinePermissionKind(declared: string): string | null {
+  if (declared === PR_OPEN_KIND) return PR_OPEN_KIND;
+  if (!declared.startsWith(CONNECTOR_TOOL_DECLARATION_PREFIX)) return null;
+  const tool = declared.slice(CONNECTOR_TOOL_DECLARATION_PREFIX.length);
+  const segments = tool.split("__");
+  // A single segment is a bare verb, not a tool: it names no connection, so no call could ever match it. This is also where a legacy per-connector declaration lands, and rejecting it here is the ruling — a slug-shaped declaration is never widened into a tool's authority.
+  if (segments.length < 2) return null;
+  if (namesReservedNamespace(segments[0] ?? "")) return null;
+  if (!segments.every((segment) => TOOL_NAME_SEGMENT.test(segment))) return null;
+  return connectorToolPermissionKind(tool);
+}
+
+/** Why one declaration was refused, in one clause a human can act on, or undefined when the predicate accepts it. It is derived from the SAME checks in the SAME order and pinned against them, so it adds no rule of its own and cannot coach an author into a second refusal. */
+export function routinePermissionRefusal(declared: string): string | undefined {
+  if (declared === PR_OPEN_KIND) return undefined;
+  if (!declared.startsWith(CONNECTOR_TOOL_DECLARATION_PREFIX)) {
+    return `it is neither "pr.open" nor a "tool:<qualified connector tool>" declaration`;
+  }
+  const tool = declared.slice(CONNECTOR_TOOL_DECLARATION_PREFIX.length);
+  const segments = tool.split("__");
+  if (segments.length < 2) {
+    return `"${tool}" is a single segment, so it names a connection or a bare verb rather than a tool — a declaration must name the tool exactly as it is called, e.g. "tool:notion__share_page"`;
+  }
+  if (namesReservedNamespace(segments[0] ?? "")) {
+    return `"${segments[0]}" is the credential-grant plane's reserved namespace, which a routine may never declare a standing permission on`;
+  }
+  const bad = segments.find((segment) => !TOOL_NAME_SEGMENT.test(segment));
+  if (bad !== undefined) {
+    return `the segment "${bad}" is not a legal tool-name segment — each "__"-delimited segment must start with a letter or a digit and then carry only letters, digits, "_" or "-"`;
+  }
+  return undefined;
+}
+
+/** Renders a stored legacy per-connector row as the dead record it is. It states INERTNESS, never "write to <slug>", which would name authority the runtime does not give, and it names the GRAIN rather than a plane, because the remedy for the rows a human actually sees is on the routine plane. */
+export function describeLegacyConnectorOpKind(kind: string): string {
+  return `nothing — "${kind.slice(CONNECTOR_OP_KIND_PREFIX.length)}" is a legacy per-connector row that lifts no tool`;
+}
+
+/** One DECLARED PERMISSION in plain language, for the arming card and for list_routines. It is the routine plane's renderer and never says "grant"; an unrecognised kind renders verbatim rather than being dropped, because silently hiding a row is the one failure this function must not have. */
+export function describeDeclaredPermissionKind(kind: string): string {
+  if (kind === PR_OPEN_KIND) return "open pull requests";
+  if (kind.startsWith(CONNECTOR_TOOL_KIND_PREFIX)) {
+    // "use", never "write with": this module is a LEAF and cannot read the tier classifier, so it does not know whether the named tool is a write. Rendering it as a write would name authority the runtime does not give.
+    return `use the "${kind.slice(CONNECTOR_TOOL_KIND_PREFIX.length)}" tool`;
+  }
+  if (kind.startsWith(CONNECTOR_OP_KIND_PREFIX)) return describeLegacyConnectorOpKind(kind);
+  return kind;
+}

package/agent/approvals/skill-create.ts

@@ -0,0 +1,60 @@
+// The gated `create_skill` kind: an armed skill is a procedure the agent loads and follows, so the durable `putDomainSkill` happens HERE, on a human's click, outside any session. Policy is "member" and the card shows the exact markdown body, because the card is the injection gate; the tainted flag raises scrutiny and never auto-rejects.
+
+import { putDomainSkill } from "../skills/domain-skills.js";
+import { armingApproval } from "./arming-context.js";
+import { appendAudit } from "../audit/audit.js";
+import { emitTelemetry } from "../observability/telemetry.js";
+import { registerActionKind } from "./actions.js";
+import type { ActionKind } from "./types.js";
+
+interface SkillCreateArgs {
+  readonly org: string;
+  readonly domain: string;
+  readonly name: string;
+  /** The full skill markdown (already `withDescription`-normalised by the tool). */
+  readonly content: string;
+  /** "created" vs "updated" — decided at propose time from the domain's current skills. */
+  readonly action: "created" | "updated";
+  /** The authoring principal (frozen); the ARMER is `decidedBy`. */
+  readonly authoredBy?: string;
+  /** Authoring turn ingested untrusted content — reviewer-scrutiny flag, never auto-reject. */
+  readonly tainted?: boolean;
+}
+
+/** Card body cap — a skill body can be up to 32KB; show enough to review, note the rest. */
+const CARD_BODY_MAX = 1200;
+
+const skillCreate: ActionKind<SkillCreateArgs> = {
+  kind: "skill.create",
+  policy: "member",
+  summarize(args) {
+    const shown = args.content.length > CARD_BODY_MAX ? `${args.content.slice(0, CARD_BODY_MAX)}\n… (${args.content.length - CARD_BODY_MAX} more bytes)` : args.content;
+    return [
+      `${args.action === "updated" ? "Update" : "Create"} skill \`${args.name}\` in domain \`${args.domain}\` — the agent will LOAD and FOLLOW this by name`,
+      ...(args.tainted ? ["⚠ authored in a turn that read external content — read the body carefully before arming"] : []),
+      "```",
+      shown,
+      "```",
+    ];
+  },
+  async execute(args, decidedBy) {
+    // The write is the EXACT frozen body — a click can never arm different text — and the AUTHOR is recorded as the row's updatedBy while the armer rides the audit line. The same call appends the body to domain_skill_revisions with the arming approval id, so the next approved edit cannot destroy what this approver read; `armingApproval()` is ambient and fail-soft, so a test still records the revision without the join.
+    const arming = armingApproval();
+    await putDomainSkill(args.org, args.domain, args.name, args.content, args.authoredBy, new Date().toISOString(), {
+      armedBy: decidedBy,
+      ...(arming ? { approvalId: arming.id } : {}),
+    });
+    await appendAudit({
+      org: args.org,
+      platform: "-",
+      workspace: "-",
+      action: args.action === "updated" ? "skill.update" : "skill.create",
+      principalId: decidedBy,
+      detail: { domain: args.domain, name: args.name, authoredBy: args.authoredBy ?? null, armedBy: decidedBy, tainted: Boolean(args.tainted) },
+    });
+    emitTelemetry("oe.feature.used", { "oe.feature": "skill_created", "oe.outcome": "ok" });
+    return `skill "${args.name}" ${args.action} in domain "${args.domain}" — armed from the next turn.`;
+  },
+};
+
+registerActionKind(skillCreate);

package/agent/approvals/skill-delete.ts

@@ -0,0 +1,50 @@
+// delete_skill removes nothing on the spot: deleting a domain skill removes a guardrail, so it validates and FREEZES the exact target, posts an approval card, and the durable delete happens on a human's click, outside any session. The frozen target is never re-derived from model-visible state at click time, so the click deletes exactly the skill the card named.
+
+import { deleteDomainSkill } from "../skills/domain-skills.js";
+import { appendAudit } from "../audit/audit.js";
+import { emitTelemetry } from "../observability/telemetry.js";
+import { registerActionKind } from "./actions.js";
+import type { ActionKind } from "./types.js";
+
+/** Frozen args for a `skill.delete` pending action — the target identity, captured at propose. */
+interface SkillDeleteArgs {
+  readonly org: string;
+  readonly domain: string;
+  readonly name: string;
+  /** The principal who proposed the deletion (frozen); the CONFIRMER is `decidedBy`. */
+  readonly requestedBy?: string;
+}
+
+const skillDelete: ActionKind<SkillDeleteArgs> = {
+  kind: "skill.delete",
+  policy: "member",
+  summarize(args) {
+    return [
+      `Delete skill \`${args.name}\` in domain \`${args.domain}\` — the agent will no longer load or follow it`,
+      "(reversible: it can be re-created with create_skill)",
+    ];
+  },
+  async execute(args, decidedBy) {
+    // Delete the EXACT frozen target. A skill that vanished between propose and click
+    // (someone else already deleted it, or a re-create/delete race) returns false — report
+    // it plainly rather than throwing, so the card shows an honest "nothing to remove".
+    const deleted = await deleteDomainSkill(args.org, args.domain, args.name);
+    // Preserve the pre-gate audit action name ("skill.delete") + its {domain,name} shape;
+    // add who confirmed. Domain-scoped, so platform/workspace are "-" like skill.create.
+    await appendAudit({
+      org: args.org,
+      platform: "-",
+      workspace: "-",
+      action: "skill.delete",
+      principalId: decidedBy,
+      detail: { domain: args.domain, name: args.name, deleted, requestedBy: args.requestedBy ?? null, confirmedBy: decidedBy },
+    });
+    const outcomeTag = deleted ? "ok" : "noop";
+    emitTelemetry("oe.feature.used", { "oe.feature": "skill_deleted", "oe.outcome": outcomeTag });
+    return deleted
+      ? `skill "${args.name}" deleted from domain "${args.domain}".`
+      : `no skill named "${args.name}" in domain "${args.domain}" — nothing to delete (it may already be gone).`;
+  },
+};
+
+registerActionKind(skillDelete);

package/agent/approvals/taint-disclosure.ts

@@ -0,0 +1,42 @@
+// One renderer, applied at the three summarize call sites and never inside a kind, so the disclosure SURVIVES RE-RENDER and no new kind can forget it. A pending card is redrawn from the frozen args, so the primary source is `args.tainted`; the kind breakdown is a live per-turn read, is allowed to be empty, and never decides whether the line renders.
+
+// Read from the taint SLOT directly, not through access/approver-chain.ts's `chainTaintSignal`
+// adapter: this module is imported by approvals/actions.ts, which the chain's own callers import,
+// and taint-signal.ts is a leaf (eve context + a type). Same bytes, no import edge into the chain.
+import { untrustedIngestedThisTurn, taintKindsThisTurn } from "../access/taint-signal.js";
+
+/** The disclosure line's opening, exported so tests and any future renderer pin ONE string. */
+export const TAINT_DISCLOSURE_PREFIX = "⚠ proposed on a turn that had ingested external content";
+
+/** Read the frozen `tainted` flag off an ActionKind's args bag, defensively — args are `unknown`
+ *  here by design (this runs over every kind, and none of their arg types are in scope). */
+function frozenTainted(args: unknown): boolean {
+  return typeof args === "object" && args !== null && (args as { tainted?: unknown }).tainted === true;
+}
+
+/** The one disclosure line, or `undefined` when there is nothing to disclose. `kinds` is the optional breakdown — pass the live signal at PROPOSE time, omit it on re-render. */
+export function taintDisclosureLine(tainted: boolean, kinds: readonly string[] = []): string | undefined {
+  if (!tainted) return undefined;
+  const from = kinds.length > 0 ? ` from ${kinds.join(", ")}` : "";
+  return `${TAINT_DISCLOSURE_PREFIX}${from} — read the payload above on its own merits; nothing outside this room asked for it.`;
+}
+
+/** Append the disclosure line to a card's summary when the proposal was tainted. Re-render callers MUST pass `live: false`, so a redraw can never pick up an unrelated turn's taint. When a kind already carries its own ⚠ line this appends only the source breakdown, and stays silent when it would add nothing. */
+export function withTaintDisclosure(
+  lines: readonly string[],
+  args: unknown,
+  opts: { readonly live?: boolean; readonly kinds?: readonly string[] } = {},
+): string[] {
+  const live = opts.live !== false;
+  const tainted = frozenTainted(args) || (live && untrustedIngestedThisTurn());
+  if (!tainted) return [...lines];
+  const kinds = opts.kinds ?? (live ? taintKindsThisTurn() : []);
+  // A kind's own ⚠ line is recognised by the phrase every one of them shares — the same phrase this
+  // module's prefix uses, so the check can never drift from what it is checking for.
+  const alreadyDisclosed = lines.some((l) => l.includes("external content"));
+  if (alreadyDisclosed) {
+    return kinds.length > 0 ? [...lines, `↳ external content this turn came from: ${kinds.join(", ")}`] : [...lines];
+  }
+  const line = taintDisclosureLine(true, kinds);
+  return line === undefined ? [...lines] : [...lines, line];
+}

package/agent/approvals/ticket-actions.ts

@@ -0,0 +1,86 @@
+// The gated ticket-mutation kinds, which ride the OE approvals plane because a state or assignee change is visible to every watcher of the entity. `add_label` deliberately gets NO kind: it is trivially reversible and stays OPEN, executed directly by tools/add_label.ts. The propose tool freezes the resolved entity and the verb's value, because execute() runs with no ctx, possibly days later.
+
+import { entityActionFn } from "../channels/entity-actions.js";
+import { appendAudit } from "../audit/audit.js";
+import { registerActionKind, whereFromScope } from "./actions.js";
+import type { ActionKind } from "./types.js";
+import type { RepoCapability } from "../access/repo-capabilities.js";
+
+interface TicketActionArgs {
+  readonly org: string;
+  readonly scopeKey: string; // the PROPOSING surface — audit + card shape (may differ from the entity's own platform on a cross-surface propose)
+  readonly platform: string; // the ENTITY's platform (Linear/GitHub) — re-resolves the mutation fn at decide time
+  readonly entityId: string; // the ENTITY's own id (Linear issue ref / "owner/repo#123")
+  /** The Linear WORKSPACE the entity lives in (OPE-882) — frozen off {@link EntityRef.organizationId}
+   *  at propose time and carried to `fn` at decide time, exactly like `entityId`, because the
+   *  mutation may run hours later with no ctx to re-derive it from. Absent for GitHub. */
+  readonly organizationId?: string;
+  readonly requestedBy: string;
+  /** Proposing turn ingested untrusted content — reviewer-scrutiny flag, never auto-reject
+   *  (same doctrine as pr.open's `tainted`). */
+  readonly tainted?: boolean;
+  /** The named capability sets the proposing scope's binding opted this entity's work source into
+   *  (OPE-1024) — frozen at propose time exactly like {@link organizationId}, because the mutation
+   *  may run hours later with no ctx to re-resolve them from. Absent ⇒ the default job set. */
+  readonly capabilities?: readonly RepoCapability[];
+}
+
+export interface TicketSetStateArgs extends TicketActionArgs {
+  readonly state: string;
+}
+
+export interface TicketAssignArgs extends TicketActionArgs {
+  readonly assignee: string;
+}
+
+function taintedLine(tainted: boolean | undefined): string[] {
+  return tainted ? ["⚠ proposed in a turn that read external content — review before approving"] : [];
+}
+
+async function executeTicketVerb(
+  args: TicketActionArgs & { readonly value: string },
+  verb: "setState" | "assign",
+  decidedBy: string,
+  auditAction: string,
+): Promise<string> {
+  const fn = entityActionFn(args.platform, verb);
+  if (!fn) {
+    // Defensive — propose time already validated support via resolveEntityAction. Surfacing this
+    // distinctly (rather than a generic throw) means a stale pending row from before a surface's
+    // adapter was removed fails with a legible reason, not a cryptic "fn is not a function".
+    throw new Error(`${auditAction}: no "${verb}" adapter is registered for platform "${args.platform}" (was it removed since this was proposed?).`);
+  }
+  const outcome = await fn(args.entityId, args.value, args.organizationId, args.capabilities ?? []);
+  await appendAudit({
+    ...whereFromScope(args.org, args.scopeKey),
+    principalId: decidedBy,
+    action: auditAction,
+    detail: { platform: args.platform, entityId: args.entityId, value: args.value, requestedBy: args.requestedBy, tainted: Boolean(args.tainted) },
+  });
+  return outcome;
+}
+
+const ticketSetState: ActionKind<TicketSetStateArgs> = {
+  kind: "ticket.set_state",
+  policy: "member",
+  summarize(args) {
+    return [`Set ${args.platform} ${args.entityId} state → "${args.state}"`, ...taintedLine(args.tainted)];
+  },
+  execute(args, decidedBy) {
+    return executeTicketVerb({ ...args, value: args.state }, "setState", decidedBy, "ticket.set_state");
+  },
+};
+
+const ticketAssign: ActionKind<TicketAssignArgs> = {
+  kind: "ticket.assign",
+  policy: "member",
+  summarize(args) {
+    return [`Assign ${args.platform} ${args.entityId} → ${args.assignee}`, ...taintedLine(args.tainted)];
+  },
+  execute(args, decidedBy) {
+    return executeTicketVerb({ ...args, value: args.assignee }, "assign", decidedBy, "ticket.assign");
+  },
+};
+
+registerActionKind(ticketSetState);
+registerActionKind(ticketAssign);

package/agent/approvals/ticket-create.ts

@@ -0,0 +1,67 @@
+// The gated `create_ticket` kind, on the OE approvals plane because a filed issue reaches every watcher of the repo or team. The propose tool freezes the destination and the draft and execute() re-resolves the create function by the FROZEN platform, because there is no ctx at decide time. Not session-grantable — `sessionGrantKind` returns a key only for `pr.open` — so the tainted flag is a reviewer-scrutiny banner, never an auto-reject.
+
+import { ticketCreateFn } from "../channels/ticket-create.js";
+import { appendAudit } from "../audit/audit.js";
+import { registerActionKind, whereFromScope } from "./actions.js";
+import type { ActionKind } from "./types.js";
+
+/** The frozen proposal — the resolved destination, the draft, and the proposing surface's scope
+ *  (for the card + audit; it may differ from the destination's own platform on a cross-surface
+ *  propose, e.g. a Slack turn filing a GitHub issue). */
+export interface TicketCreateArgs {
+  readonly org: string;
+  readonly scopeKey: string;
+  readonly platform: string; // the DESTINATION's platform — re-resolves the create fn at decide time
+  readonly target: string; // the destination's own shape: GitHub "owner/repo", Linear a team key
+  /** The Linear WORKSPACE the destination team lives in (OPE-882) — frozen off
+   *  {@link ResolvedTicketCreate.organizationId} at propose time and carried to the create fn at
+   *  decide time, exactly like `target`. Absent for GitHub. */
+  readonly organizationId?: string;
+  readonly title: string;
+  readonly body: string;
+  readonly requestedBy: string;
+  /** Proposing turn ingested untrusted content — reviewer-scrutiny flag, never auto-reject. */
+  readonly tainted?: boolean;
+}
+
+/** The card body. The full title and body are rendered because the card IS the injection gate: a
+ *  human must read the exact text that will be published before it reaches the repo's watchers. */
+function summarizeCreate(args: TicketCreateArgs): string[] {
+  const lines = [`File a new ${args.platform} work item in ${args.target}`, `Title: ${args.title}`];
+  if (args.body.trim().length > 0) lines.push(args.body);
+  if (args.tainted) lines.push("⚠ proposed in a turn that read external content — review before approving");
+  return lines;
+}
+
+const ticketCreate: ActionKind<TicketCreateArgs> = {
+  kind: "ticket.create",
+  policy: "member",
+  summarize: summarizeCreate,
+  async execute(args, decidedBy) {
+    const fn = ticketCreateFn(args.platform);
+    if (!fn) {
+      // Defensive — propose time already validated support via resolveTicketCreate. Surfacing this
+      // distinctly means a stale pending row from before a surface's adapter was removed fails with
+      // a legible reason, not a cryptic "fn is not a function".
+      throw new Error(`ticket.create: no create adapter is registered for platform "${args.platform}" (was it removed since this was proposed?).`);
+    }
+    const created = await fn(args.target, { title: args.title, body: args.body }, args.organizationId);
+    await appendAudit({
+      ...whereFromScope(args.org, args.scopeKey),
+      principalId: decidedBy,
+      action: "ticket.create",
+      detail: {
+        platform: args.platform,
+        target: args.target,
+        title: args.title,
+        entityId: created.ref.id,
+        ...(created.url ? { url: created.url } : {}),
+        requestedBy: args.requestedBy,
+        tainted: Boolean(args.tainted),
+      },
+    });
+    return created.url ? `${created.summary} ${created.url}` : created.summary;
+  },
+};
+
+registerActionKind(ticketCreate);

package/agent/approvals/types.ts

@@ -0,0 +1,48 @@
+// The agent proposes and FREEZES args into a pending_action row, code renders the card from those frozen args, a verified human clicks, and code executes them: the model is never in the effect path. The clicker's standing is TIER-DEPENDENT — an admin-tier kind needs an org admin (or a domain admin covering the frozen row's scope), while a member-tier kind takes any member, the requester included. summarize() and execute() only ever see what was frozen at propose time, never anything derived from a later turn.
+
+/** Lifecycle of one pending action — a strict one-way state machine (see the CAS below). */
+export type PendingStatus = "pending" | "approved" | "rejected" | "expired";
+
+/** `argsJson` is the FROZEN mutation input, captured at propose time and never re-derived, so an approver reading the card is reading exactly what will execute. */
+export interface PendingActionRow {
+  readonly id: string; // uuid
+  readonly org: string;
+  readonly kind: string; // e.g. "spend.set"
+  readonly argsJson: string; // FROZEN args, JSON
+  readonly scopeKey: string; // e.g. "slack/T123/C456" — the scope the mutation targets
+  readonly domain: string | null; // memory domain resolved at propose time (null if none)
+  readonly requestedBy: string; // proposing session's verified principal id (Slack user id)
+  readonly channelId: string; // where the card is posted
+  readonly threadTs: string | null;
+  readonly messageTs: string | null; // the card's ts, set after post
+  /** The surfaceKey the card was POSTED to, frozen at mint and deliberately NOT derived from `scopeKey`, which an explicit-scope override can point at another workspace. NULL means a pre-migration row or a row that must never get sweep feedback, and the sweep then skips silently. */
+  readonly postedTo: string | null;
+  readonly status: PendingStatus;
+  readonly createdAt: string; // ISO
+  readonly expiresAt: string; // ISO
+  readonly decidedBy: string | null;
+  readonly decidedAt: string | null;
+}
+
+/** "member" is the injection-gate-only tier; "admin" additionally requires an org admin, or a domain admin covering the FROZEN row's scope. "Any clicker" is no longer literal: a click from a room whose audience floor is positively `guest`, or from outside the room the card was posted into, is refused — neither constraint applies where the caller supplies no click context. */
+export type ApproverPolicy = "admin" | "member";
+
+// A per-domain override of this tier was assessed and REFUSED: raising it per domain changes only which HAND may press the button, and for every non-admin in that domain the raise IS four-eyes. `policy` must stay a per-KIND constant, never a function of the row, which scripts/webhook-provisioning-test.ts asserts.
+
+/** Looked up by `kind` at propose AND decide time, so a kind's behaviour can never drift between the two. */
+export interface ActionKind<A = unknown> {
+  readonly kind: string;
+  readonly policy: ApproverPolicy;
+  /** Set when approving MINTS live material rather than merely attesting to a change. The clicker is not the recipient — read it as "the click is the disclosure event" — and a flagged kind additionally requires an ATTESTED room in clicker-floor.ts; absent means witness semantics. */
+  readonly beneficiaryClicker?: true;
+  /** Names the frozen-arg fields a redelivered propose step can MEASURE differently, so the redelivery guard keys on what the request was rather than on the measurement. The guard is scoped to one (session, turn), so a genuine re-ask in a later turn still mints its own card; absent means every arg is replay-stable. */
+  readonly volatileArgs?: readonly string[];
+  /** Names the frozen-arg fields that carry the proposer's free text (a `reason`), which the model rewrites on every retry. The dedup against a LIVE pending card drops them, so a repeat of the same request in new words lands on the open card instead of posting a second one. The text stays on the row and the card; absent means every arg is part of the dedup identity. */
+  readonly proseArgs?: readonly string[];
+  /** Deterministic card body lines rendered from the FROZEN args — code, never model text. */
+  summarize(args: A): string[];
+  /** Perform the mutation. Returns a short outcome line for the updated card. Must audit. */
+  execute(args: A, decidedBy: string): Promise<string>;
+  /** Optional record that a human REJECTED this card; it may NEVER mutate the thing the card proposed, because a reject has always meant "nothing was applied". Its returned line IS rendered onto the decided card and the decision notice, so it must say accurately what the decline recorded, and a throw here does not un-reject the row. */
+  declined?(args: A, decidedBy: string): Promise<string>;
+}