@open-everywhere/core 0.1.0

package/agent/approvals/routine-permission.ts

@@ -0,0 +1,214 @@
+// The routine PERMISSION card. An unattended fire's refused ask posts one card into the routine's own room; a click writes exactly the row the declare layer writes, and the next fire lifts. Approve, decline and ignore are three distinct states, and a decline is remembered.
+// The card's life is the routine GENERATION, never a clock, and `execute` re-reads the routine first, so a late click cannot arm an instruction the human never read. It is a LEAF and must never reach approvals/flow.ts.
+
+import { getOperationalStore } from "../operational/provider.js";
+import { appendAudit } from "../audit/audit.js";
+import { emitTelemetry } from "../observability/telemetry.js";
+import { registerActionKind, whereFromScope } from "./actions.js";
+import { getRoutine } from "../routines/store.js";
+import { ROUTINE_PERMISSION_NO_EXPIRY } from "../routines/declared-permissions.js";
+import { routinePermissionGeneration, routinePermissionKey, type Routine } from "../routines/routine.js";
+import type { ModelRole } from "../memory/domain.js";
+import { routineCardWaitSeconds } from "../routines/permission-card-wait.js";
+import { routinePermissionDeclinedMemo } from "./session-grant.js";
+import type { ActionKind } from "./types.js";
+
+/** The ActionKind / pending-row / card kind string. Pinned in `access/consequence.ts`. */
+export const ROUTINE_PERMISSION_KIND = "routine.permission";
+
+/** Frozen args for a `routine.permission` pending action. IDS AND VERBS ONLY — the refused action's
+ *  own arguments are never frozen here, because this card decides a STANDING permission, not that
+ *  one call. */
+export interface RoutinePermissionArgs {
+  readonly org: string;
+  /** The proposing surfaceKey ("platform/workspace/surface") — audit scope, as on every kind. */
+  readonly scopeKey: string;
+  /** The routine's generation-scoped permission key. The FIELD NAME is the persisted wire spelling and does not move: live cards carry it in their frozen `argsJson`, and the generation inside it is this card's real expiry. */
+  readonly grantKey: string;
+  /** The routine's own id and surface — what {@link execute} re-reads the row by. */
+  readonly routineId: string;
+  readonly routineSurfaceKey: string;
+  /** The memo kind a click writes: `pr.open`, or `connector.tool:<qualified tool>`. */
+  readonly grantKind: string;
+  /** The DECLARATION as a human reads it and as `create_routine` would have spelled it —
+   *  `pr.open` or `tool:<qualified tool>`. Rendered on the card so the reader can see that this
+   *  click buys exactly what the creation card would have. */
+  readonly declaration: string;
+  /** The routine's instruction, clipped host-side. A permission means nothing without the standing
+   *  instruction it serves, so the card shows both. */
+  readonly prompt: string;
+  /** The MODEL ROLE this routine's fires resolve, or absent for a routine that inherits the deployment's stack. It is on the card because a cheaper role degrades judgement in silence; optional, so every card frozen before the field still parses. */
+  readonly modelRole?: ModelRole;
+}
+
+/** Hard cap on the prompt line, for the same reason routine-lifecycle.ts caps its own: a card a
+ *  human will not read is not a gate. */
+const CARD_PROMPT_CHARS = 600;
+
+function clip(s: string): string {
+  const t = s.trim();
+  return t.length > CARD_PROMPT_CHARS ? `${t.slice(0, CARD_PROMPT_CHARS)}…` : t;
+}
+
+/** The card body, code-rendered from the frozen args. The second line reads the wait setting, because at the shipped `routineCardWaitSeconds: 0` the asking run is already over and armed it may still be waiting; a setting changed between post and re-render flips only the wording, never the card's authority. */
+export function routinePermissionCardLines(args: RoutinePermissionArgs): string[] {
+  const waitArmed = routineCardWaitSeconds() > 0;
+  return [
+    `Let routine ${args.routineId} use \`${args.declaration}\` on its own, from now on?`,
+    // "ANY run still waiting", never "the run that asked": this card is posted by a generation's
+    // FIRST refusal, and every later fire re-points at this same card. So the run holding on it when
+    // a human finally clicks is usually NOT the one that raised it.
+    waitArmed
+      ? "It asked for this while running unattended, and was refused. This decides FUTURE runs — and any run still waiting on this card when you answer."
+      : "It asked for this while running unattended, so the run was refused and has already finished. This decides FUTURE runs.",
+    "🔑 approving writes the same standing permission the routine's creation card would have declared — it is revoked the moment the routine's instruction is edited, and `revoke_routine_permissions` withdraws it at any time.",
+    "⛔ declining is remembered: this routine stops asking for this permission until its instruction is edited.",
+    `Routine says:\n> ${clip(args.prompt)}`,
+    `Target: ${args.routineSurfaceKey}`,
+    // OPE-1627 — ALWAYS RENDERED, in both states. A card that showed the line only when a role was
+    // named would make inheritance invisible, and "no line" is not something a reader can tell apart
+    // from "this build does not show the model".
+    args.modelRole === undefined
+      ? "Model: inherits this deployment's model stack."
+      : `Model: this routine — and the work it delegates — runs the \`${args.modelRole}\` role of this deployment's model stack, not the default \`primary\` one.`,
+  ];
+}
+
+/** The click-time re-check, and it is what makes a card with no clock safe. Without it on the approve path, a card posted against one instruction could arm a different one months later; without it on the decline path the row would land under a dead generation and never be read. */
+async function recheckedRoutine(args: RoutinePermissionArgs): Promise<{ ok: true } | { ok: false; why: string }> {
+  const state = await routineCardGenerationState(args);
+  switch (state.state) {
+    case "current":
+      return { ok: true };
+    case "gone":
+      return { ok: false, why: `routine ${args.routineId} no longer exists` };
+    case "superseded":
+      return {
+        ok: false,
+        why:
+          `routine ${args.routineId} has been edited since this card was posted ` +
+          `(it is now on generation ${state.generation}), so its new instruction has to ask again`,
+      };
+    default:
+      // 🔴 NOT "no longer exists". The read FAILED — the routine may be perfectly alive and this
+      // click simply could not see it. Saying it is gone would be an overclaim on the one surface
+      // a human reads their own click back from.
+      return { ok: false, why: `routine ${args.routineId} could not be read` };
+  }
+}
+
+/** What {@link routineCardGenerationState} answers. `superseded` carries the generation the routine
+ *  is on NOW, which is the number the clicker needs to make sense of the refusal. */
+export type RoutineCardGenerationState =
+  | { readonly state: "current" }
+  /** The routine still exists, on a LATER generation — the card was posted before an `edit_routine`. */
+  | { readonly state: "superseded"; readonly generation: number }
+  | { readonly state: "gone" }
+  /** The routine could not be READ. Nothing about the card is known — see the callers. */
+  | { readonly state: "unreadable" };
+
+/** ONE rule, two readers - the click and the pending sweep - so the sweep can never expire a card a click would have honoured, or leave alive a card whose every click refuses. `unreadable` is kept apart from `gone`: the sweep decides a row on the first and must leave it alone on the second. */
+export async function routineCardGenerationState(args: RoutinePermissionArgs): Promise<RoutineCardGenerationState> {
+  let routine: Awaited<ReturnType<typeof getRoutine>>;
+  try {
+    routine = await getRoutine(args.org, args.routineSurfaceKey, args.routineId);
+  } catch {
+    return { state: "unreadable" };
+  }
+  if (!routine) return { state: "gone" };
+  if (routinePermissionKey(routine) !== args.grantKey) return { state: "superseded", generation: routinePermissionGeneration(routine) };
+  return { state: "current" };
+}
+
+/** The frozen args of a `routine.permission` pending row, or undefined when the row does not carry
+ *  a readable pair. FAIL-CLOSED: an unparseable row is never acted on — see the sweep's use. */
+export function parseRoutinePermissionArgs(argsJson: string): RoutinePermissionArgs | undefined {
+  try {
+    const parsed = JSON.parse(argsJson) as Partial<RoutinePermissionArgs> | null;
+    if (!parsed || typeof parsed.org !== "string" || typeof parsed.routineId !== "string") return undefined;
+    if (typeof parsed.routineSurfaceKey !== "string" || typeof parsed.grantKey !== "string") return undefined;
+    return parsed as RoutinePermissionArgs;
+  } catch {
+    return undefined;
+  }
+}
+
+const routinePermission: ActionKind<RoutinePermissionArgs> = {
+  kind: ROUTINE_PERMISSION_KIND,
+  // "member", the same bar `routine.create` and `routine.edit` carry: what a human may arm on a
+  // creation card, a human may arm here. A higher bar would make this card the ONE way to give a
+  // routine a permission that needs an admin, which is a different decision from this ticket's.
+  policy: "member",
+  summarize(args) {
+    return routinePermissionCardLines(args);
+  },
+  async execute(args, decidedBy) {
+    const recheck = await recheckedRoutine(args);
+    if (!recheck.ok) {
+      // A THROW, not a quiet no-op: the click path turns it into `FAILED: …` on the card and an
+      // `approval.failed` audit row, so the clicker reads why their click bought nothing. A
+      // silently-dropped arm would leave them believing the routine can now do this.
+      throw new Error(`nothing was armed — ${recheck.why}`);
+    }
+    const now = new Date();
+    await getOperationalStore().setSessionApproval({
+      org: args.org,
+      sessionId: args.grantKey,
+      kind: args.grantKind,
+      grantedBy: decidedBy,
+      createdAt: now.toISOString(),
+      // No TTL — the generation in `grantKey` is the death mechanism, exactly as
+      // routines/declared-permissions.ts writes the declared set.
+      expiresAt: ROUTINE_PERMISSION_NO_EXPIRY,
+    });
+    await appendAudit({
+      ...whereFromScope(args.org, args.scopeKey),
+      principalId: decidedBy,
+      // 🔴 A PERSISTED ACTION STRING, FROZEN (OPE-1303). The plane's word is "declared permission",
+      // but this value names rows already in deployed audit chains and is read back verbatim by
+      // access/permission-evidence.ts and tools/permission_fit_report.ts, so it does not move.
+      action: "routine.permission_granted",
+      detail: { routine: args.routineId, grant: args.grantKind, declaration: args.declaration, key: args.grantKey },
+    });
+    emitTelemetry("oe.feature.used", { "oe.feature": "routine_permission_card", "oe.outcome": "granted" });
+    // Setting-conditional for the same reason the card body is. At the shipped wait of 0 "from its next run" is exactly right, and armed it is false, because the click may have just lifted a run holding on this card right now.
+    return routineCardWaitSeconds() > 0
+      ? `routine ${args.routineId} may now use \`${args.declaration}\` on its own — from now on, including any run still waiting on this card, until its instruction is edited`
+      : `routine ${args.routineId} may now use \`${args.declaration}\` on its own — from its next run, until its instruction is edited`;
+  },
+  async declined(args, decidedBy) {
+    // The decline path runs the SAME click-time re-check: on a card posted before an edit the row would land under a dead generation, nothing would read it, and the clicker would be told their "never ask again" was recorded. It records nothing and says so instead.
+    const recheck = await recheckedRoutine(args);
+    if (!recheck.ok) {
+      await appendAudit({
+        ...whereFromScope(args.org, args.scopeKey),
+        principalId: decidedBy,
+        action: "routine.permission_declined_stale",
+        detail: { routine: args.routineId, grant: args.grantKind, declaration: args.declaration, key: args.grantKey },
+      }).catch(() => undefined);
+      return `nothing was remembered — ${recheck.why}`;
+    }
+    // A decline that wrote nothing would re-card on the very next fire, so it is written under the SAME generation key and an edit clears it with everything else. Best-effort: the direction of a lost row is one more card, never an unasked-for grant.
+    const now = new Date();
+    await getOperationalStore()
+      .setSessionApproval({
+        org: args.org,
+        sessionId: args.grantKey,
+        kind: routinePermissionDeclinedMemo(args.grantKind),
+        grantedBy: decidedBy,
+        createdAt: now.toISOString(),
+        expiresAt: ROUTINE_PERMISSION_NO_EXPIRY,
+      })
+      .catch(() => undefined);
+    await appendAudit({
+      ...whereFromScope(args.org, args.scopeKey),
+      principalId: decidedBy,
+      action: "routine.permission_declined",
+      detail: { routine: args.routineId, grant: args.grantKind, declaration: args.declaration, key: args.grantKey },
+    }).catch(() => undefined);
+    emitTelemetry("oe.feature.used", { "oe.feature": "routine_permission_card", "oe.outcome": "declined" });
+    return `routine ${args.routineId} will not ask for \`${args.declaration}\` again until its instruction is edited`;
+  },
+};
+
+registerActionKind(routinePermission);

package/agent/approvals/routine-policy.ts

@@ -0,0 +1,174 @@
+// Both kinds are `policy: "member"`: a rule CONSTRAINS a routine, so it cannot need a higher bar than creating the routine it constrains. A rule change deliberately does not bump `promptGeneration`, so this card's frozen args and the audit rows below are the only durable copies of the rule text.
+
+import { appendAudit } from "../audit/audit.js";
+import type { Partition } from "../memory/partition.js";
+import { getRoutine, updateRoutine } from "../routines/store.js";
+import { applyPolicyAdd, applyPolicyRemove, POLICY_MAX_RULES, type RoutinePolicyRule } from "../routines/policy.js";
+import { armingApproval } from "./arming-context.js";
+import { registerActionKind } from "./actions.js";
+import type { ActionKind } from "./types.js";
+
+/** The rule id is minted at PROPOSE time, so the id on the card is the id in the rule and in the audit row. */
+interface RoutinePolicyAddArgs {
+  readonly org: string;
+  readonly partition: Partition;
+  readonly surfaceKey: string;
+  readonly routineId: string;
+  readonly description: string;
+  readonly ruleId: string;
+  readonly rule: string;
+  readonly why: string;
+  readonly source: "human" | "learned";
+  readonly incidentRunAt?: string;
+  readonly countBefore: number;
+  readonly requestedBy: string;
+}
+
+const routinePolicyAdd: ActionKind<RoutinePolicyAddArgs> = {
+  kind: "routine.policy.add",
+  policy: "member",
+  summarize(args) {
+    return [
+      `Add a standing rule to routine ${args.routineId} — ${args.description}`,
+      `Rule: ${args.rule}`,
+      `Why: ${args.why}`,
+      // The authorship warning is unconditional: even a rule a human dictated is a string the MODEL typed, and a warning that appears only sometimes trains people to skim it.
+      "✍️ the agent wrote the text above — read it as written, not as what you asked for",
+      ...(args.source === "learned"
+        ? ["⚠ the agent proposed this ITSELF after a run, rather than being asked for it by anyone"]
+        : []),
+      ...(args.incidentRunAt ? [`Prompted by the run at ${args.incidentRunAt}`] : []),
+      `It becomes TRUSTED text in every future fire of this routine, including unattended ones, until someone removes it (${args.countBefore} → ${args.countBefore + 1} of ${POLICY_MAX_RULES} rules)`,
+      `Target: ${args.surfaceKey}`,
+    ];
+  },
+  async execute(args, decidedBy) {
+    // Re-read at CLICK time. The routine may have moved (another rule armed, an edit landed) between
+    // propose and click, and the cap + duplicate checks have to run against the set that actually
+    // exists — a card proposed at 19 rules must not arm a 21st because two were pending at once.
+    const routine = await getRoutine(args.org, args.surfaceKey, args.routineId);
+    if (!routine) {
+      return `routine ${args.routineId} is gone — it was cancelled before this rule was confirmed, so nothing changed.`;
+    }
+    // `addedBy` is the CLICKER, never the requester and never the model: the rule's authority comes
+    // from the click, so that is whose name it carries. `addedAt` is click time for the same reason.
+    const rule: RoutinePolicyRule = {
+      id: args.ruleId,
+      rule: args.rule,
+      why: args.why,
+      addedAt: new Date().toISOString(),
+      addedBy: decidedBy,
+      source: args.source,
+      ...(args.incidentRunAt ? { incidentRunAt: args.incidentRunAt } : {}),
+    };
+    const result = applyPolicyAdd(routine, rule);
+    if (!result.accepted) {
+      return `rule not added to routine ${args.routineId} — ${result.reason}`;
+    }
+    const updated = await updateRoutine(args.org, args.surfaceKey, args.routineId, result.patch);
+    if (!updated) {
+      return `routine ${args.routineId} is gone — it was cancelled before this rule was confirmed, so nothing changed.`;
+    }
+    // The audit row carries the rule VERBATIM, because a rule has no durable home of its own: this row and the card's frozen args ARE the record of what was armed. It is one capped line.
+    const arming = armingApproval();
+    await appendAudit({
+      org: args.partition.org,
+      platform: args.partition.platform,
+      workspace: args.partition.workspace,
+      surface: args.partition.surface,
+      principalId: decidedBy,
+      action: "routine.policy.add",
+      detail: {
+        routineId: args.routineId,
+        ruleId: rule.id,
+        rule: rule.rule,
+        why: rule.why,
+        source: rule.source,
+        armedBy: decidedBy,
+        requestedBy: args.requestedBy,
+        ...(rule.incidentRunAt ? { incidentRunAt: rule.incidentRunAt } : {}),
+        ...(arming ? { approvalId: arming.id } : {}),
+        rules: result.count,
+      },
+    });
+    return (
+      `rule ${rule.id} added to routine ${args.routineId} (${result.count} of ${POLICY_MAX_RULES}). ` +
+      `Every fire from now on is told: “${rule.rule}”. Remove it with \`remove_routine_rule\` — that asks for a confirmation too.`
+    );
+  },
+};
+
+/** Frozen args for a `routine.policy.remove` pending action. The rule's TEXT is frozen at propose
+ *  time — the execute below deletes the only live copy, so a card that re-derived it at click would
+ *  be describing something it can no longer prove. */
+interface RoutinePolicyRemoveArgs {
+  readonly org: string;
+  readonly partition: Partition;
+  readonly surfaceKey: string;
+  readonly routineId: string;
+  readonly description: string;
+  readonly ruleId: string;
+  readonly ruleText: string;
+  readonly why: string;
+  readonly addedAt: string;
+  readonly addedBy: string;
+  readonly countBefore: number;
+  readonly requestedBy: string;
+}
+
+const routinePolicyRemove: ActionKind<RoutinePolicyRemoveArgs> = {
+  kind: "routine.policy.remove",
+  policy: "member",
+  summarize(args) {
+    return [
+      `Remove a standing rule from routine ${args.routineId} — ${args.description}`,
+      `Rule (${args.ruleId}): ${args.ruleText}`,
+      `Added ${args.addedAt} by ${args.addedBy} because: ${args.why}`,
+      "🛡️ this is a guardrail someone armed after an incident — future fires stop following it, with no further notice",
+      `${args.countBefore} → ${args.countBefore - 1} of ${POLICY_MAX_RULES} rules`,
+      `Target: ${args.surfaceKey}`,
+    ];
+  },
+  async execute(args, decidedBy) {
+    const routine = await getRoutine(args.org, args.surfaceKey, args.routineId);
+    if (!routine) {
+      return `routine ${args.routineId} is gone — it was cancelled before this removal was confirmed, so nothing changed.`;
+    }
+    const result = applyPolicyRemove(routine, args.ruleId);
+    if (!result.removed) {
+      return `rule ${args.ruleId} is no longer on routine ${args.routineId} — it was already removed, so nothing changed.`;
+    }
+    const updated = await updateRoutine(args.org, args.surfaceKey, args.routineId, result.patch);
+    if (!updated) {
+      return `routine ${args.routineId} is gone — it was cancelled before this removal was confirmed, so nothing changed.`;
+    }
+    const arming = armingApproval();
+    await appendAudit({
+      org: args.partition.org,
+      platform: args.partition.platform,
+      workspace: args.partition.workspace,
+      surface: args.partition.surface,
+      principalId: decidedBy,
+      action: "routine.policy.remove",
+      detail: {
+        routineId: args.routineId,
+        ruleId: result.removed.id,
+        // The destroyed text comes from the LIVE row, not the frozen args, so the audit records what actually went and a divergence from the card is visible.
+        rule: result.removed.rule,
+        why: result.removed.why,
+        source: result.removed.source,
+        originallyAddedBy: result.removed.addedBy,
+        originallyAddedAt: result.removed.addedAt,
+        armedBy: decidedBy,
+        requestedBy: args.requestedBy,
+        ...(arming ? { approvalId: arming.id } : {}),
+        rules: result.count,
+      },
+    });
+    const left = result.count === 0 ? "it now has no standing rules" : `${result.count} of ${POLICY_MAX_RULES} left`;
+    return `rule ${result.removed.id} removed from routine ${args.routineId} — ${left}. Future fires are no longer told “${result.removed.rule}”.`;
+  },
+};
+
+registerActionKind(routinePolicyAdd);
+registerActionKind(routinePolicyRemove);

package/agent/approvals/scope-label.ts

@@ -0,0 +1,48 @@
+// Friendly display labels for approval-card scope keys — DISPLAY ONLY, never an access or execution input; the exact scope key stays the source of truth in the frozen args, the pending row, the execute path and the audit record. Resolution is best-effort and FAIL-OPEN: any lookup failure returns undefined and the card falls back to the raw key.
+
+import { bridgeFetchChannelDisplayName } from "../channels/slack-bridge.js";
+import { admitProviderRegistration } from "../access/provider-selection.js";
+import { getConfig } from "../access/config.js";
+import { displayTitle } from "../identity/display-title.js";
+import { parseScopeKey } from "../access/scope-key.js";
+
+// A non-Slack surface's friendly-label lookup lives in its provider bundle and registers here keyed by platform; Slack's arm stays inline below. An unregistered platform resolves undefined, so the card renders the raw key.
+
+/** Resolve a friendly label for a scope's `{ workspace, surface? }`, or undefined (→ raw key). MUST
+ *  NOT throw (friendlyScopeLabel's try/catch is a backstop, but the resolver is fail-open too). */
+export type ScopeLabelResolver = (parsed: { workspace: string; surface?: string }) => Promise<string | undefined>;
+
+const SCOPE_LABEL_RESOLVERS = new Map<string, ScopeLabelResolver>();
+
+/** Register (or replace) a platform's scope-label resolver. Called once per bundle at boot. */
+export function registerScopeLabelResolver(platform: string, resolver: ScopeLabelResolver): void {
+  if (!admitProviderRegistration(platform, "scope-label-resolver")) return;
+  SCOPE_LABEL_RESOLVERS.set(platform, resolver);
+}
+
+/** Resolve a human label for a scope key, or undefined so the card renders the raw key. Workspace-level Slack keys and unknown platforms stay raw, and a thread is labelled by its PARENT channel because an auto-thread's own name is derived from the triggering message. NEVER throws. */
+export async function friendlyScopeLabel(scopeKey: string): Promise<string | undefined> {
+  try {
+    // The scope-key grammar is read ONCE, by access/scope-key.ts — never re-derived here.
+    const parsed = parseScopeKey(scopeKey);
+    // A DOMAIN-level scope key is a bare domain NAME, an immutable identifier. The optional display `title` is what the card shows, while the frozen args, the row and the audit record keep the name.
+    if (parsed.kind === "domain") {
+      const domain = getConfig().loadDomains().find((d) => d.name === parsed.name);
+      return domain?.title?.trim() ? displayTitle(domain) : undefined;
+    }
+    // A PERSON scope renders the platform's own mention syntax, which Slack and Discord share — an approver cannot decide about a raw member id they cannot read as a person. Fail-open like every arm: an unknown platform renders no label.
+    if (parsed.kind === "principal") {
+      return parsed.platform === "slack" || parsed.platform === "discord" ? `<@${parsed.id}>` : undefined;
+    }
+    if (parsed.kind === "malformed") return undefined;
+    if (parsed.platform === "slack" && parsed.kind === "surface") {
+      const name = await bridgeFetchChannelDisplayName(parsed.surface);
+      return name ? `#${name}` : undefined;
+    }
+    const resolver = SCOPE_LABEL_RESOLVERS.get(parsed.platform);
+    if (resolver) return await resolver({ workspace: parsed.workspace, surface: parsed.kind === "surface" ? parsed.surface : undefined });
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}

package/agent/approvals/session-checkpoint.ts

@@ -0,0 +1,80 @@
+// The SOFT session cost checkpoint: an approve click writes a session-continue memo the guard consults for the rest of the session, a decline writes nothing and the soft-block persists, and reads and replies are unaffected either way. Policy is "member" because it is a cost circuit-breaker, not a privilege gate. A DURABLE session's grant carries NO expiry (OPE-261): its `createdAt` is the approved HIGH-WATER MARK, and the guard cards again only on a fresh increment of spend.
+
+import { getOperationalStore } from "../operational/provider.js";
+import { appendAudit } from "../audit/audit.js";
+import { emitTelemetry } from "../observability/telemetry.js";
+import { registerActionKind, whereFromScope } from "./actions.js";
+import { getSettings } from "../settings/settings.js";
+import { ROUTINE_PERMISSION_NO_EXPIRY } from "../routines/declared-permissions.js";
+import type { ActionKind } from "./types.js";
+
+export const CHECKPOINT_KIND = "session.checkpoint";
+/** The session-approval memo kind written on APPROVE — the guard consults it to proceed. */
+export const CHECKPOINT_GRANT_MEMO = "session.checkpoint.grant";
+/** The session-approval memo kind written when the card is first posted — the "already asked this
+ *  session" marker that keeps a DECLINE soft-blocking WITHOUT re-carding every later attempt. */
+export const CHECKPOINT_ASK_MEMO = "session.checkpoint.asked";
+
+/** What a member is told BEFORE they approve a DURABLE session's checkpoint: approving sets a mark rather than a timer. ONE string, shared by this kind's `summarize()` and the live card lines, because a member must never grant something the card they read did not describe. */
+export const DURABLE_GRANT_DISCLOSURE =
+  "This job keeps one running total, so approving sets a mark rather than a timer: it asks again once it has spent that much again, and the approval does not lapse on its own.";
+
+/** TTL hours for a LIVE session's continue/asked memos — a GC bound, NOT the death mechanism, since the memo's sessionId embeds the window generation. A garbage or non-positive value falls back to the default, and it does NOT bound a DURABLE session's grant, which carries no expiry. */
+export function checkpointTtlHours(): number {
+  return getSettings().approvals.checkpointTtlHours;
+}
+
+interface SessionCheckpointArgs {
+  readonly org: string;
+  /** The proposing surfaceKey ("platform/workspace/surface") — audit + card scope. */
+  readonly scopeKey: string;
+  /** The bare session/window token the grant memo is written under (the guard's memoKey). */
+  readonly sessionId: string;
+  /** True when {@link sessionId} names a session whose cost does NOT reset; present means the grant is written with NO EXPIRY and the guard rebases the threshold on its `createdAt`. Frozen at propose, because execute() runs in the CLICKER's context, which carries no routine marker of its own — it is a property of the memo KEY, not of the turn. */
+  readonly durableSession?: true;
+  /** Display-only friendly label for {@link scopeKey} ("#proj-chat"), frozen at propose so the
+   *  pending and decided renders agree. Absent ⇒ the render falls back to the key. */
+  readonly scopeLabel?: string;
+}
+
+const sessionCheckpoint: ActionKind<SessionCheckpointArgs> = {
+  kind: CHECKPOINT_KIND,
+  policy: "member",
+  summarize(args) {
+    // Plain product copy, and the room's NAME where one was frozen at propose — a card is what a
+    // person reads, not a row (Tommy, 2026-09-08). The key is the fail-open fallback only.
+    return [
+      "Keep this session going past its cost checkpoint?",
+      `In ${args.scopeLabel ?? args.scopeKey}.`,
+      "Approve to let the agent do consequential work again — pull requests, memory writes and the like. Decline to keep that paused. Reading and replying carry on either way.",
+      // A durable session's grant does not expire, so the card says so before the click — the same
+      // sentence the live card lines carry.
+      ...(args.durableSession ? [DURABLE_GRANT_DISCLOSURE] : []),
+    ];
+  },
+  async execute(args, decidedBy) {
+    const store = getOperationalStore();
+    const now = new Date();
+    await store.setSessionApproval({
+      org: args.org,
+      sessionId: args.sessionId,
+      kind: CHECKPOINT_GRANT_MEMO,
+      grantedBy: decidedBy,
+      createdAt: now.toISOString(),
+      // A durable session's grant carries no expiry and this `createdAt` becomes the high-water mark the guard rebases on; it is not a lost control, because spend/checkpoint.ts cards again on a fresh increment. A LIVE session keeps the TTL, whose real death mechanism is the window rotation the memo key embeds.
+      expiresAt: args.durableSession ? ROUTINE_PERMISSION_NO_EXPIRY : new Date(now.getTime() + checkpointTtlHours() * 3_600_000).toISOString(),
+    });
+    await appendAudit({
+      ...whereFromScope(args.org, args.scopeKey),
+      principalId: decidedBy,
+      action: "checkpoint.continue",
+      detail: { scopeKey: args.scopeKey },
+    });
+    emitTelemetry("oe.feature.used", { "oe.feature": "spend_checkpoint", "oe.outcome": "continued" });
+    return args.durableSession
+      ? "cost checkpoint cleared — the agent may do consequential work again, and asks again only once it has spent as much a second time"
+      : "cost checkpoint cleared — the agent may do consequential work again for the rest of this session";
+  },
+};
+
+registerActionKind(sessionCheckpoint);