@open-everywhere/core 0.1.0

package/agent/routines/routine.ts

@@ -0,0 +1,949 @@
+// The Routine model — the unit of OpenEverywhere's proactivity (Phase 3). A routine is
+// a durable, surface-owned instruction that fires WITHOUT a fresh @-mention:
+// the agent does work on a schedule, on a state change, or on an external event.
+//
+// Three trigger kinds, matching the plan's "3 routine types":
+//   - cron / interval  -> a SCHEDULED JOB (run at times / every N minutes).
+//   - watch            -> a CHANNEL WATCH: re-evaluated on a cadence, but posts
+//                         only when the watched state CHANGES (post-on-diff). The
+//                         routine carries `lastStateHash`; the fired turn records
+//                         its observation via the `record_watch_state` tool, which
+//                         hashes + compares host-side (see routines/watch.ts).
+//   - event            -> an EVENT SUBSCRIPTION (a PR opened, CI failed, …),
+//                         matched against inbound events rather than the clock.
+//
+// This module is framework-free (no eve / zod imports) so the store, the pure
+// schedule logic, and the tests can use it without pulling the runtime. The zod
+// input shape lives with the `create_routine` tool; the dispatcher lives in
+// agent/schedules/. Time/scheduling math is in schedule.ts; GC in lifecycle.ts.
+
+// STORED trigger shapes. Note the model-facing API (tools/create_routine.ts) is
+// deliberately DIFFERENT: one "scheduled" kind with a required postPolicy
+// ("every-run" | "only-on-change"), mapped onto these three at creation — the
+// stored kinds are an implementation detail (and pre-2026-07-04 rows exist), the
+// policy choice is the API. "watch" simply means only-on-change.
+//
+// The filter TYPES come from routines/event-model.ts (the pure registry leaf), not from
+// event-match.ts (the evaluator, which imports Routine) — a leaf, not a cycle.
+import { describeFilter, storedFilter } from "./event-model.js";
+import { ROUTINE_PERMISSION_PREFIX } from "./permission-key.js";
+// TYPE-ONLY, both ways: policy.ts imports `Routine` from here and this imports `RoutinePolicyRule`
+// from there. `import type` erases at compile time, so neither direction is a runtime edge — the
+// same shape the event-model leaf above relies on.
+import type { RoutinePolicyRule } from "./policy.js";
+// TYPE-ONLY, for the same reason: follow-ups.ts imports `Routine` from here and this imports
+// `RoutineFollowUp` from there. `import type` erases at compile time, so neither direction is a
+// runtime edge.
+import type { RoutineFollowUp } from "./follow-ups.js";
+// TYPE-ONLY: `ModelRole` is the routable role vocabulary (memory/domain.ts ModelRoutes), and this
+// module stays framework-free. `import type` erases at compile time, so the pure store/schedule
+// tests keep importing this file with nothing new pulled in behind it.
+import type { ModelRole } from "../memory/domain.js";
+
+export type RoutineTrigger =
+  // Standard 5-field UTC cron ("min hour dom mon dow"). The general scheduler.
+  | { readonly kind: "cron"; readonly expr: string }
+  // Convenience: every N minutes from creation.
+  | { readonly kind: "interval"; readonly everyMinutes: number }
+  // Only-on-change ("watch"): wake on the cadence (everyMinutes) or cron (expr) —
+  // exactly one — but only POST when the observed state changed since last fire.
+  | { readonly kind: "watch"; readonly everyMinutes?: number; readonly expr?: string }
+  // One-shot ("send_later" analogue, design notes item 3): fires exactly ONCE at `at`
+  // (ISO 8601 UTC), then the dispatcher DISABLES the routine (kept for audit/list
+  // visibility, never deleted). Unlike cron/interval/watch there is no recurrence to
+  // compute — schedule.ts's computeNextRun always returns null for "once", which is
+  // what makes it a one-shot rather than a routine the dispatcher would keep re-firing.
+  | { readonly kind: "once"; readonly at: string }
+  // External event subscription (GitHub PR/CI, etc.) — matched, not timed.
+  | {
+      readonly kind: "event";
+      readonly source: string; // e.g. "github"
+      /**
+       * ⭐ THE SUBSCRIPTION PREDICATE (OPE-210) — a **jq expression** over the event, which must
+       * evaluate to exactly `true` or `false`, e.g.
+       * `.scope.container == "acme/web" and (.fields.action | IN("opened","reopened"))`.
+       *
+       * The ONLY shape anything writes. Evaluated in-process over the vendored `just-bash`
+       * (`routines/jq-filter.ts`), fail-closed and NON-THROWING at fire time; validated, compiled and
+       * cost-probed at CREATE time (`routines/event-match.ts` + `jq-filter.ts probeFilter`).
+       */
+      readonly jq?: string;
+    };
+
+/**
+ * WHERE A FIRE'S OUTPUT GOES (OPE-149). Absent — the default, and every pre-2026-07-26 row — means
+ * "post the turn's answer into the routine's target", which is what every routine did until now.
+ *
+ * `{kind:"silent"}` is the SECOND shape: the routine's product is an ACTION (a ticket updated,
+ * memory written), not a message, so a post would be pure noise. It is set ONLY by the model-facing
+ * `postPolicy: "never"` (tools/create_routine.ts) and it is deliberately a RECORD, not a boolean:
+ * a future `{kind:"digest", …}` is an added arm, not a second flag that has to agree with the first.
+ *
+ * SILENCE IS THE DEFAULT; FAILURE IS LOUD. Two halves enforce that, and both are needed:
+ *   • the instruction half — routines/watch.ts renderSilentBlock, rendered trusted right after the
+ *     fire preamble ("end the turn with exactly NO_REPLY; the ONE exception is a problem you cannot
+ *     resolve, which WILL post");
+ *   • the MECHANICAL half, which is never prompt-reliant — routines/report.ts's per-turn signal,
+ *     seeded from the {@link ROUTINE_MARKER}.silent stamp by hooks/routine-silence.ts and consulted
+ *     by channels/turn-delivery.ts finalMessageActionForTurn, which DROPS the terminal prose.
+ * The escape hatch is a POSITIVE act: a mid-turn `reply` posts as it always did (the gate only ever
+ * touches the terminal completion), so "I hit a problem" still reaches the humans.
+ *
+ * `{kind:"surface"}` is the THIRD shape (OPE-148): the fire's output goes to a DIFFERENT surface
+ * from the one that owns the routine. It exists because `surfaceKey` conflated three concerns —
+ * tenancy (whose budget, whose memory, whose trust), ownership (whose room may list and cancel it),
+ * and DESTINATION (who reads it) — and only the third has a different right answer on a surface
+ * that cannot post proactively at all. Ownership and tenancy stay fused to {@link Routine.surfaceKey}
+ * and are NOT redirected; only `schedules/routine-dispatch.ts` resolveRoutineTarget reads this.
+ *
+ * 🔴 IT IS NEVER MODEL-AUTHORED. The destination comes from `Domain.reportChannel` — operator
+ * config, in code, in the routine's OWN domain — resolved host-side at ARM time and frozen onto the
+ * row. A creator naming an arbitrary destination would be a model-authored cross-surface post
+ * primitive (a new audience-expansion vector with no gate), and `reportTo: "slack/T…/C…"` would put
+ * hosting topology and surface identity into a core tool param, which this codebase refuses on
+ * principle. The precedent followed is `Domain.governance` + `governanceChannelFor`.
+ */
+export type RoutineReport =
+  | { readonly kind: "silent" }
+  | {
+      readonly kind: "surface";
+      /** Fully-qualified `platform/workspace/surface` of the DESTINATION. Config-sourced. */
+      readonly surfaceKey: string;
+      /** The post-back target for that surface, derived host-side by
+       *  `schedules/routine-dispatch.ts` reportTargetForSurface at arm time. */
+      readonly target: Readonly<Record<string, unknown>>;
+    };
+
+/**
+ * THE TWO DIMENSIONS OF A JOB'S CEILING (OPE-248) — see {@link Routine.bound} for why the ceiling
+ * exists at all, and routines/bound.ts for where the default numbers come from.
+ *
+ * BOTH ARE REQUIRED, and neither is sufficient, because "how long is too long" has two independent
+ * denominations and a routine's cadence decides which one is meaningful:
+ *
+ *   • a COUNT alone is wrong for a slow cadence — a daily job with a 200-fire cap is a 200-DAY job,
+ *     which is not a bound anybody would recognise as one;
+ *   • a DEADLINE alone is wrong for a fast cadence — the dispatcher floor is
+ *     {@link import("./schedule.js").DISPATCH_TICK_MINUTES} = 10 minutes, so a week's grace is up
+ *     to ~1,000 unattended fires.
+ *
+ * So the routine stops at WHICHEVER TRIPS FIRST. The two cross over at an hourly cadence, and each
+ * governs the side it is honest about (bound.ts, §the crossover).
+ */
+export interface RoutineBound {
+  /** ISO instant at/after which the routine stops of its own accord. */
+  readonly until?: string;
+  /** Hard cap on fires attempted under this bound — the runaway backstop for fast cadences. */
+  readonly maxFires?: number;
+}
+
+/**
+ * THE report/target substitution — the whole of the OPE-148 destination split, as a pure function
+ * so that {@link import("../schedules/routine-dispatch.js").resolveRoutineTarget} needs exactly one
+ * line for it.
+ *
+ * Returns the routine UNCHANGED for every row that has no `{kind:"surface"}` report — which is
+ * every pre-OPE-148 row, every silent one, and every routine that reports where it lives. A silent
+ * routine deliberately does NOT redirect: it still dispatches into its own surface to run the
+ * turn at all, and its silence is a DELIVERY gate (channels/turn-delivery.ts), not a destination.
+ */
+export function reportDestinationOf(r: Routine): Routine {
+  const rep = r.report;
+  return rep?.kind === "surface" ? { ...r, surfaceKey: rep.surfaceKey, target: rep.target } : r;
+}
+
+/** Where this routine's fires POST — the report destination's surfaceKey when one is configured,
+ *  else the surface that owns it. NOT the tenancy/ownership key: use {@link Routine.surfaceKey}
+ *  for spend, GC reach, `list_routines` and the fire marker. */
+export function routineReportSurfaceKey(r: Pick<Routine, "surfaceKey" | "report">): string {
+  return r.report?.kind === "surface" ? r.report.surfaceKey : r.surfaceKey;
+}
+
+// "done" is the JOB-only TERMINAL status (OPE-55): a job routine's own fired session reaches
+// completion and calls `complete_job`, flipping it here. Distinct from `disabled` (a
+// governance/failure stop — 3-strike self-disable, once-fired, human cancel): `done` means the
+// multi-step work the job was chasing is FINISHED, not that the routine broke. Both are terminal
+// (the dispatcher fires only `active`); the row is kept for audit/list visibility, never deleted.
+export type RoutineStatus = "active" | "disabled" | "done";
+export type RunOutcome = "ok" | "failed" | "skipped";
+
+/** Hard cap on a job routine's working-state blob (OPE-55), matching OpenClaw's `trigger.state`
+ *  16 KB ceiling — a progress ledger, not a document store; oversize is rejected at the tool. */
+export const JOB_STATE_MAX_BYTES = 16 * 1024;
+
+/** Hard cap on a DECLARED failure reason (OPE-177, {@link Routine.lastFailureReason}). One line, not
+ *  a report: it exists to be read in an audit row next to a routine id, and it is MODEL-authored, so
+ *  it is truncated host-side rather than rejected — a declaration that fails on length would leave
+ *  the run recorded as a success, which is the exact defect the tool closes. */
+export const RUN_FAILURE_REASON_MAX_CHARS = 300;
+
+export interface Routine {
+  readonly id: string;
+  /** Tenant the routine belongs to — the OUTERMOST partition (at-rest isolation).
+   *  A routine fires back under this org; the dispatcher carries it in the marker. */
+  readonly org: string;
+  /** `platform/workspace/surface` the routine belongs to AND posts back to. */
+  readonly surfaceKey: string;
+  /**
+   * Post-back target, captured from the surface binding at creation
+   * (identity/binding.ts — each platform's mapper documents its shape: Slack/Discord
+   * `{ channelId, … }`, Teams the Bot Framework
+   * conversation reference `{ serviceUrl, conversationId, … }`). The dispatcher
+   * (schedules/dispatch.ts resolveTarget) validates it per platform, hands the
+   * adapter-shaped subset to `to(channel, target)`, and stamps the raw-fact
+   * extras (guild id, chat type, scope, …) back onto the fired session's auth so
+   * bindFrom re-derives the routine's real partition. Missing/incomplete ⇒ the
+   * routine runs dry-run (fail-closed, schedule not advanced).
+   */
+  readonly target?: Readonly<Record<string, unknown>>;
+  readonly trigger: RoutineTrigger;
+  /** Where this routine's output goes — see {@link RoutineReport}. Absent = post every fire's
+   *  answer into {@link target}, which is what every routine did before OPE-149 and what every
+   *  stored row that predates it means. Additive + optional: it rides the existing JSON row, no
+   *  migration, exactly like {@link taintedAtCreation} and {@link prWatch}. */
+  readonly report?: RoutineReport;
+  /** What the agent should DO when this fires (an instruction, in NL). */
+  readonly prompt: string;
+  /**
+   * Principal who created it, for audit. Routines are **surface-owned**, not
+   * principal-owned: the creator leaving the org does NOT GC the routine (it
+   * belongs to the channel). Removal from the surface is what stops it.
+   */
+  readonly createdBy?: string;
+  readonly createdAt: string; // ISO
+  /**
+   * Was the turn that AUTHORED this routine one that had ingested untrusted external content
+   * (OPE-145)? Frozen at propose time (tools/create_routine.ts untrustedIngestedThisTurn), carried
+   * through the approval card's warning line, and stamped here at ARM time so it survives on the
+   * row. Additive + optional — it rides the existing JSON row, no migration, exactly like
+   * {@link jobTainted} and {@link prWatch}.
+   *
+   * WHY IT HAS TO BE ON THE ROW. The taint verdict existed only in the propose-time card and the
+   * `routine.create` audit row, so `list_routines` could never tell an operator WHICH standing
+   * autonomy was born inside an injected turn — the single most useful thing to know when auditing
+   * a fleet of routines after an incident. Unlike {@link jobTainted} this one is NOT monotonic:
+   * it is a fact about creation, and creation happens once.
+   */
+  readonly taintedAtCreation?: boolean;
+  /**
+   * STANDING RULES this routine has accumulated (OPE-141) — see {@link RoutinePolicyRule} and
+   * routines/policy.ts, which holds the whole argument. Rendered as a TRUSTED block into every one
+   * of this routine's fires, by all four fire shapes. Additive + optional: it rides the existing
+   * JSON row, no migration, exactly like {@link jobTainted} and {@link prWatch}.
+   *
+   * 🔴 WRITTEN ONLY BY THE TWO CARDED ActionKinds (`routine.policy.add` / `routine.policy.remove`,
+   * approvals/routine-policy.ts). Deliberately NOT reachable from any ungated per-fire write — that
+   * separation from {@link jobState}, which IS an ungated model-owned per-fire write, is the entire
+   * governance argument for policy being a second field rather than part of the ledger.
+   *
+   * A rule change does NOT bump {@link promptGeneration}, and must not: bumping revokes every
+   * standing grant and rotates a durable job's seat, so adding one rule would silently reset what
+   * the routine may do and throw away its session. That is also why these do not ride
+   * `routine_prompt_revisions`, whose index IS that generation (policy.ts, §where the text lives).
+   */
+  readonly policy?: readonly RoutinePolicyRule[];
+  /**
+   * PRE-RUN DATA COLLECTION (OPE-151 §1) — the names of the declared reads the host runs BEFORE this
+   * routine's fire, whose output is handed to the session as part of the fire payload. Additive +
+   * optional: it rides the existing JSON row, no migration, exactly like {@link jobTainted} and
+   * {@link prWatch}.
+   *
+   * 🔴 A NAME, AND NOTHING MORE. What each name DOES — which tool, which arguments — is a TRACKED
+   * LITERAL in the deployment's own config (`agent/routines/collectors.ts`), registered at boot
+   * (routines/collector.ts). So a routine chooses from a menu written in Git and can never compose a
+   * read of its own, and a collector runs under the routine's DECLARED PERMISSION and nothing wider:
+   * the permission a collector needs is the ordinary per-tool declaration `tool:<the tool>`, checked
+   * against the routine's LIVE permission set at fire time. A collector the routine cannot pay for is
+   * refused, and the refusal is named in the fire's own message — never a silent empty read.
+   */
+  readonly collectors?: readonly string[];
+  /**
+   * THE CONDITION GATE (OPE-151 §2) — the name of the declared predicate that decides whether this
+   * routine fires at all, read over {@link collectors}' output. Additive + optional, same as above.
+   *
+   * A `no` costs one `routine.skip` audit row (reason `condition_gate`): no session, no delivery, no
+   * spend. The predicate is a tracked literal registered at boot (routines/gate.ts) and it FAILS
+   * CLOSED — an unknown name or a throwing predicate skips the run — because the whole point of a
+   * gate is to withhold a claim until a condition is verifiably true.
+   */
+  readonly gate?: string;
+  /**
+   * PER-ROUTINE MODEL CHOICE (OPE-1627) — the {@link ModelRole} this routine's fires resolve
+   * instead of `primary`. Additive + optional: it rides the existing JSON row, no migration,
+   * exactly like {@link collectors} and {@link gate}.
+   *
+   * 🔴 ABSENT MEANS INHERIT, AND INHERIT IS THE DEFAULT. A routine never has to name a role, and a
+   * row that names none resolves exactly what it resolved before this field existed. The field is
+   * stated in the type as optional for that reason: inheritance is not a fallback the code stumbles
+   * into, it is the answer for every routine that does not care.
+   *
+   * 🔴 INHERIT IS NOT THE SAME ANSWER ON BOTH DELIVERY PATHS, AND THAT IS WHY THIS FIELD IS USEFUL.
+   * A fire on the NATIVE path resolves `primary`; a fire delivered through the unified window
+   * carries a window token, which `isSupervisorSession` answers TRUE for, so it resolves
+   * `supervisor` — the cheap ambient tier. Naming a role is what makes the two paths agree, and
+   * that pre-existing split is the reason the declared role must win over the supervisor branch in
+   * `model/routing.ts` rather than sit under it.
+   *
+   * 🔴 IT NAMES A ROLE, NEVER A MODEL ID. A role is what this deployment's config already routes
+   * (`memory/domain.ts` ModelRoutes), so a routine that names `utility` follows the stack wherever
+   * the stack goes, and `npm run lint:model-ids` keeps a bare id out of `agent/**` in the first
+   * place. A pinned id would rot the day the deployment changed stacks, silently, on a routine
+   * nobody re-reads.
+   *
+   * 🔴 A ROLE THE DEPLOYMENT DOES NOT ROUTE IS INERT, NOT AN ERROR. `resolveRoute` falls back to
+   * `primary` when the merged route for a role is unset — the same contract the `supervisor` role
+   * has had since it was added. So naming `utility` on a deployment whose domains route no
+   * `utility` changes nothing at all; it does not downgrade the routine and it does not fail it.
+   * `docs/capabilities/proactivity-and-routines.md` states that plainly, because a reader who
+   * expects a cheaper run and gets the same one deserves to know why.
+   *
+   * 🔴 IT REACHES THE FIRE'S DELEGATED WORKERS TOO, AND THAT IS THE INTENT. The stamp rides the
+   * whole auth bag: `channels/unified.ts` `dispatchTaskWindow` forwards the parent's attributes
+   * verbatim, and a native subagent takes the parent's slot by reference. So a routine's declared
+   * role covers the work it delegates, not only its own turn — which is the coherent reading, since
+   * the delegated work IS the routine's work. Two consequences worth stating rather than
+   * discovering: a routine that names no role leaves its workers exactly where they were (a `t/`
+   * task token is supervisor-shaped, so they resolve `supervisor`), and a routine that names
+   * `primary` moves its workers ONTO `primary` — a deliberate widening, not a leak. Both cards say
+   * "this routine and the work it delegates" for that reason.
+   *
+   * The risk this field carries is real and is why the permission card shows it: a routine moved to
+   * a cheaper role can degrade its judgement in silence, and a human approving a standing
+   * permission should see which role they are approving it for.
+   */
+  readonly modelRole?: ModelRole;
+
+  // --- mutable runtime state (the dispatcher/lifecycle update these) ---------
+  status: RoutineStatus;
+  disabledReason?: string;
+  /**
+   * AUTHORITY GENERATION (OPE-147) — bumped by `edit_routine` every time the routine's frozen
+   * TEXT changes, and by nothing else. Absent ⇒ generation 1, so every pre-OPE-147 row is
+   * unchanged and no migration is implied.
+   *
+   * WHY A COUNTER AND NOT A DELETE SWEEP. Two things must stop believing in a routine whose
+   * prompt was rewritten, and both are keyed rather than enumerated:
+   *
+   *   1. A DURABLE JOB'S SEAT. A `sessionMode:"job"` routine resumes ONE eve session across fires,
+   *      keyed by {@link routines/fire-window.ts jobFireSeatKey}. Its transcript holds the OLD
+   *      prompt, and a long-lived seat answers from its own backscroll — so an edited job would
+   *      keep doing the pre-edit thing no matter what the row says. The generation is part of the
+   *      seat key, so an edit rotates the seat: a FRESH session, with {@link jobState} (deliberately
+   *      preserved) as the hand-off, which is exactly the "session was replaced, restart from the
+   *      ledger" case renderJobMessage already documents.
+   *   2. DECLARED PERMISSIONS (OPE-152). A routine-scoped "approve for this routine" memo rides
+   *      the EXISTING `SessionApprovalRow` table under {@link routinePermissionKey} — no schema
+   *      change — and that key embeds this generation, exactly as a session grant's key embeds the
+   *      window's rotation generation ("a new generation is a different sessionId and misses",
+   *      operational/store.ts). So `edit_routine` invalidating every declared permission is a
+   *      PROPERTY OF THE KEY, not a sweep somebody has to remember to run. That matters because the
+   *      operational store seam has no delete for those rows at all, and because "declare pr.open,
+   *      then rewrite the prompt" is otherwise a clean laundering path around the gate.
+   */
+  promptGeneration?: number;
+  /**
+   * MANUAL RUN REQUEST (OPE-147 `run_routine_now`) — the ISO instant a human asked for an
+   * off-schedule run, set by the tool and CLEARED by the dispatcher on the fire it causes.
+   *
+   * It is a REQUEST FLAG, not a second fire path. `run_routine_now` makes the routine DUE
+   * ({@link nextRunAt} = now) and lets the ordinary dispatcher tick fire it, so the manual run
+   * gets the spend gate, the live trust recheck, the concurrency cap, the job anchor, the window
+   * divert and the forensic rows by CONSTRUCTION rather than by a parallel implementation. This
+   * field is the only thing that survives the hop from the requesting turn to that tick, and its
+   * sole effect is to stamp {@link ROUTINE_MARKER.manual} on the fire so the `routine.fire` join
+   * row can say the run was off-schedule.
+   */
+  manualRunAt?: string;
+  /** Next time this is due (ISO). Null for `event` (not clock-scheduled). */
+  nextRunAt?: string | null;
+  lastRunAt?: string;
+  lastOutcome?: RunOutcome;
+  /**
+   * DECLARED SEMANTIC FAILURE (OPE-177) — the one line the fired turn gave when it called
+   * `report_run_failed`, capped at {@link RUN_FAILURE_REASON_MAX_CHARS}. Additive + optional: it
+   * rides the existing JSON row, no migration, exactly like {@link jobTainted} and {@link prWatch}.
+   *
+   * WHY IT HAS TO EXIST AT ALL. The three-strike fold only ever saw the SESSION outcome (`ok` /
+   * `failed` as eve reports it, plus a rejected delivery since OPE-146). A routine whose prompt is
+   * "check the payments API and report" can hit a 500 on every single fire, post "I couldn't reach
+   * the API", and complete cleanly — `consecutiveFailures` stays 0 and it runs forever. Only the
+   * model knows the work didn't work, so it has to SAY so; this field is where it says it, and
+   * lifecycle.ts settleOutcome is what makes the fold honour it (the same shape as a watch run's
+   * mid-turn `skipped`, which is the existing precedent for "this run recorded its own outcome").
+   *
+   * LIFETIME, and why it can't go stale: the dispatcher CLEARS it on every fire alongside
+   * `lastOutcome`, and {@link import("./lifecycle.js").applyOutcome} clears it on any non-`failed`
+   * settlement. So a reason present when a fold reads the row was written by THAT run — the same
+   * invariant `lastOutcome` rests on, for the same reason.
+   *
+   * MODEL TEXT, DELIBERATELY QUARANTINED. It reaches the `routine.fire` / `routine.disabled` audit
+   * rows and nothing else. It is NOT folded into {@link disabledReason}, which routines/
+   * disable-notice.ts POSTS INTO THE ROOM host-side — that message bypasses the silent-routine
+   * delivery gate precisely because it is host-composed, and threading model text through it would
+   * hand a silent routine a three-fire path to posting arbitrary prose past its own gate.
+   */
+  lastFailureReason?: string;
+  /** Consecutive failures; self-disables past a threshold (see lifecycle.ts). */
+  consecutiveFailures: number;
+  /**
+   * OPE-506: the instant the CURRENT consecutive-failure streak began (ISO). Stamped on the first
+   * failure of a streak, carried forward on every failure after it, and cleared on any non-failed
+   * settlement — the same lifetime `lastFailureReason` has, for the same reason: a value present at
+   * a fold was written by the streak this fold is still part of. It is what lets the self-disable
+   * threshold ask "how LONG has this been failing", not only "how MANY times" (lifecycle.ts
+   * applyOutcome, MIN_CONSECUTIVE_FAILURE_SPAN_MS). Additive + optional: it rides the existing JSON
+   * row, no migration — a row with `consecutiveFailures > 0` and no stamp (every pre-OPE-506 row) is
+   * read as an already-running streak, never as a fresh one (see applyOutcome's fallback).
+   */
+  firstFailureAt?: string;
+  /** `watch` only: hash of the last-seen state, so we post only on a diff. */
+  lastStateHash?: string;
+  /**
+   * THE FOLLOW-UPS LEDGER (OPE-151 §3) — named notes a run leaves for the NEXT run of this same
+   * routine. Additive + optional: it rides the existing JSON row, no migration, exactly like
+   * {@link jobState} and {@link prWatch}.
+   *
+   * WHY IT IS NOT {@link jobState}. That field is JOB-ONLY — `record_job_state` refuses a routine
+   * whose `sessionMode` is not `"job"` — and the ORDINARY stateless routine is the one with nowhere
+   * to leave a note: its fire starts on a fresh session every time, so a `todo` dies with the turn.
+   * It is also not the same SHAPE: `jobState` is one blob rewritten whole each fire, which loses
+   * every entry the writing run was not thinking about. These are addressed entries, written and
+   * resolved one at a time.
+   *
+   * 🔴 SCOPED TO THIS ROUTINE BY CONSTRUCTION. `record_follow_up` locates the row from the
+   * dispatcher-stamped {@link ROUTINE_MARKER}, never from a caller-supplied id — the same mechanism
+   * `record_watch_state` uses — so no fire can read or write another routine's ledger.
+   *
+   * Taint rides the ENTRY, not the row: see routines/follow-ups.ts on why a monotonic row flag would
+   * be wrong for a list of independent notes.
+   */
+  followUps?: readonly RoutineFollowUp[];
+
+  // --- SUBSCRIPTION LIVENESS (OPE-184) — `event` only ------------------------
+  /**
+   * The FIRST time this subscription's filter ever matched a delivery (ISO), and the most recent
+   * (ISO). Written by routines/match-stamp.ts from the fan-out's match loop. Additive + optional:
+   * both ride the existing JSON row, no migration, exactly like {@link jobTainted} and
+   * {@link prWatch}.
+   *
+   * WHY THEY EXIST. An `event` routine has no clock — `computeNextRun` returns nothing for it — so
+   * `nextRunAt`/`lastRunAt` are structurally empty and every existing liveness signal on this row is
+   * about FIRING. That leaves the author's commonest question with no answer at all: a filter that
+   * MATCHES NOTHING and a filter that HAS NOT FIRED YET look identical, both from the room and from
+   * the audit log, because neither writes anything. These two fields are the missing half — "the
+   * expression is a working predicate over real traffic" — stated separately from "and the fire
+   * completed", which the `routine.fire` forensics already answer.
+   *
+   * 🔴 THEY ARE STAMPED ON *MATCH*, STRICTLY BEFORE THE PERMISSION / TARGET / CAP CHECKS, AND THAT
+   * ORDER
+   * IS THE ENTIRE POINT. Stamping after any of them would re-merge the two states this field exists
+   * to separate: "your filter matches nothing" would become indistinguishable from "your filter
+   * matches, and something downstream stopped it" — and the downstream reasons already have their
+   * own visible vocabulary (`routine.skip`, reason `grant_refused` / `unresolved_target` /
+   * `fanout_cap`). Read together the pair is diagnostic: a `lastMatchAt` with no fires means the
+   * filter is fine and the plumbing is not; an absent `firstMatchAt` means the filter is the
+   * problem. Collapse them and you get back the single ambiguous silence.
+   *
+   * NOT A FIRE COUNT, and deliberately not one. There is no `matches7d` here: a count is a per-
+   * delivery write, and this pair is coalesced precisely so a busy subscription does not turn every
+   * inbound delivery into a row update (routines/match-stamp.ts MATCH_STAMP_WINDOW_MS). So a
+   * `lastMatchAt` is accurate to within that window, and is never a volume signal.
+   */
+  firstMatchAt?: string;
+  lastMatchAt?: string;
+
+  // --- JOB persistence (OPE-55) — the "join" today's routines lack ------------
+  /**
+   * DURABLE-JOB mode. Absent (the default) = today's stateless routine: every fire starts a
+   * FRESH session (eve keys a routine send by `slackContinuationToken(channelId, randomUUID())`
+   * when the target carries no thread — a new session each fire). `"job"` gives the routine its
+   * OWN persistent session: successive fires resume ONE durable eve session so multi-step
+   * proactive work ("chase this until it's resolved") ACCUMULATES context instead of starting
+   * cold each fire. The join is the session token, pinned by {@link jobSessionAnchor} — NO new
+   * continuation-token grammar (the frozen-grammar invariant, channels/window-key.ts): a job
+   * session is a plain surface-native token with a STABLE thread anchor, exactly how the DM seat
+   * (OPE-90) gives a long-lived DM one durable session. Slack-only in v1 (the surface whose token
+   * derivation OE fully controls and can host-post an anchor into).
+   */
+  sessionMode?: "job";
+  /**
+   * `job` only: the DURABLE thread anchor that pins the job's continuation token. On the FIRST
+   * job fire the dispatcher host-posts a kickoff message and stores its ts here; every later fire
+   * passes it as the receive target's `threadTs`, so `slackContinuationToken(channelId, anchor)`
+   * is STABLE across fires ⇒ eve resumes the SAME session (the join), and every fire + reply
+   * threads under the one job thread. A real Slack ts (replies thread correctly), never synthetic.
+   */
+  jobSessionAnchor?: string;
+  /**
+   * `job` only: the WORKING-STATE ledger (OPE-55, generalizing `lastStateHash` from a diff hash to
+   * a real progress document; ≤ {@link JOB_STATE_MAX_BYTES}). The fired job session writes it via
+   * `record_job_state`; the dispatcher renders it into every fire's preamble as the trusted "where
+   * you were" block. This is the belt to the resumed session's braces: if the durable session ever
+   * dies (rotation past eve's token ceiling, expiry), the next fire RE-ATTACHES to the same anchor
+   * and — even if the transcript is gone — restarts WITH this note rather than cold. Failed runs
+   * don't persist it (OpenClaw's rule; a crashed turn never corrupts the ledger).
+   */
+  jobState?: string;
+  /**
+   * `job` only: has this job's LEDGER ever been written on a turn that ingested untrusted content
+   * (OPE-111)? Additive + optional — it rides the existing JSON row, no migration, exactly like
+   * {@link prWatch}. MONOTONIC: set true by `record_job_state` when the writing turn was tainted,
+   * never cleared, because every later ledger builds on the one before it.
+   *
+   * WHY IT HAS TO BE ON THE ROW AND NOT JUST IN THE SESSION. The taint signal
+   * (access/taint-signal.ts) is PER TURN — it is cleared at each turn boundary, so fire N+1 does not
+   * inherit fire N's taint from the session even when both run in the SAME session, and a REPLACED
+   * session (rotation past eve's token ceiling, expiry) obviously inherits nothing either. Without a
+   * row flag both are a clean laundering path: inject → the model writes it into its own ledger →
+   * the next fire reads the ledger back as TRUSTED with a clean taint bit. So the flag rides the
+   * ledger it describes, and it is the ONLY thing that carries the taint forward: the dispatcher
+   * stamps it onto EVERY fire off the stored row (routines/fire-auth.ts → access/job-posture.ts
+   * JOB_TAINT_ATTR), the fired turn re-seeds its taint signal from that stamp (hooks/spawn-taint.ts's
+   * TAINT_SEED_ATTRS, the same one consumer the spawn and completion taint-forwards use), and
+   * renderJobMessage stops presenting the ledger as trusted.
+   *
+   * ⚠️ This paragraph used to argue the row flag only mattered for a REPLACED session, because
+   * session state "survives steps AND turns" so a live session carried taint fire-to-fire for free.
+   * That was true of the old session-durable slot and is false since OPE-299 §A. The stamp already
+   * rode every fire, so nothing had to change here — but the reason it is load-bearing did.
+   */
+  jobTainted?: boolean;
+  /**
+   * PR-SUBSCRIPTION bookkeeping (OPE-61) — present only on the `once` checks subscribe_pr arms.
+   * A subscription is a CHAIN of one-shots (each fired check arms the next), so there is no single
+   * row to count on; the budget is handed forward here instead. `checksRemaining` is how many
+   * checks may still be armed AFTER this one, and the fired check reads it back off its OWN row via
+   * the dispatcher-stamped marker — never off its prompt, which the model could rewrite. Zero means
+   * the chain retires and tells the channel to re-subscribe.
+   */
+  prWatch?: { readonly repo: string; readonly number: number; readonly checksRemaining: number };
+  /**
+   * THE CEILING (OPE-248) — the bound a durable job stops itself at when it never calls
+   * `complete_job`. Additive + optional: it rides the existing JSON row, no migration, exactly like
+   * {@link jobTainted} and {@link prWatch}. Stamped HOST-SIDE at ARM time (approvals/routine-create.ts)
+   * and renewed host-side on a re-arm (approvals/routine-lifecycle.ts) — never model-authored, for
+   * the same reason `report:{kind:"surface"}` is not: a ceiling a fire could name is not a ceiling.
+   *
+   * WHY IT HAS TO EXIST. A `sessionMode:"job"` routine runs until its OWN session calls
+   * `complete_job` ({@link import("./lifecycle.js").completeJob}), and nothing else bounds it. Every
+   * other stop this codebase has counts FAILURE: {@link Routine.consecutiveFailures} resets to 0 on
+   * any non-failed settlement (lifecycle.ts applyOutcome), and OPE-177's `report_run_failed` only
+   * closes the case where the run KNOWS its work didn't work. A monitor that SUCCEEDS forever —
+   * polls, finds nothing, replies, repeats — is a correct run every single time, so it is invisible
+   * to all of them, and it runs until somebody happens to notice.
+   *
+   * AND WHY IT IS NOT A COST THRESHOLD. The obvious reach is spend/checkpoint.ts, and it structurally
+   * cannot do this job: the checkpoint gates only CONSEQUENTIAL tools at their execute() top
+   * (`requireSessionContinuation`), and its own card says "reads and replies are unaffected either
+   * way" — which is the entire surface area of a polling monitor. A cheap poll never crosses it at
+   * ANY threshold, and it is opt-in and uncapped by default besides. So the bound is on the ROUTINE,
+   * denominated in fires and wall-clock, not on the session in tokens.
+   *
+   * See routines/bound.ts for the two dimensions, why BOTH are needed, and where each number comes
+   * from. Absent ⇒ unbounded, which is every pre-OPE-248 row and every non-job routine (a daily
+   * digest is SUPPOSED to run forever — that is the feature, not the defect).
+   */
+  bound?: RoutineBound;
+  /**
+   * Fires ATTEMPTED under the current {@link Routine.bound} — incremented by the dispatcher in the
+   * same optimistic advance that guards against a double-fire, and ONLY for a routine that carries a
+   * bound (an unbounded row stays byte-identical). Reset to 0 when a re-arm mints a fresh bound, so
+   * it always means "fires against THIS ceiling" — which is what makes the reset correct rather than
+   * a laundering path: re-arming is a carded, member-gated act performed by a human who has just
+   * read the notice saying the job hit its ceiling.
+   */
+  fireCount?: number;
+  /**
+   * THE STALL FACT (OPE-253) — the ISO instant THIS fire was refused a consequential tool by a
+   * configured session cost checkpoint (spend/checkpoint.ts requireSessionContinuation). Additive +
+   * optional: it rides the existing JSON row, no migration, exactly like {@link jobTainted} and
+   * {@link prWatch}.
+   *
+   * WHY IT HAS TO EXIST. A soft-blocked fire is not a FAILED fire — the block is a recoverable
+   * tool-error the model reads and works around, so the fire replies and settles `ok`, and
+   * {@link consecutiveFailures} resets to 0. It is not a COMPLETE fire either: the job could not do
+   * the work that would let it call `complete_job`. So "waiting on a human click" and "running fine"
+   * were the same reading of a job from every surface OE ships, while the OPE-248 ceiling burned down
+   * underneath it. This field is where a fire says which of the two it was.
+   *
+   * LIFETIME, and why it can't go stale — identical to {@link lastFailureReason}'s, deliberately: the
+   * dispatcher CLEARS it on every fire alongside `lastOutcome`, and only the refused tool sets it. So
+   * a value present when a fold reads the row was written by THAT run. Its absence at the fold is what
+   * BREAKS a stall run (routines/stall.ts stallFoldPatch), which is what keeps `stalledFires`
+   * consecutive rather than a lifetime total.
+   *
+   * It survives past the fold on purpose (the fold does not clear it), so between fires the row can
+   * answer "when did it last get blocked?" — the same window `lastOutcome` is readable in.
+   */
+  lastStallAt?: string;
+  /**
+   * CONSECUTIVE checkpoint-stalled fires (OPE-253) — the arithmetic over {@link lastStallAt}, applied
+   * by the fold, and the dimension {@link Routine.bound} retires a job on when nobody ever answers the
+   * card. Additive + optional, same as everything above it.
+   *
+   * See routines/stall.ts for where the limit comes from, why a stateless routine's crossing
+   * self-heals while a durable job's cannot, and the one case it deliberately does not reach.
+   */
+  stalledFires?: number;
+  /** `job` only: when the job reached its `done` terminal status (ISO), via `complete_job`. */
+  completedAt?: string;
+  /** `job` only: the one-line reason the job declared itself done (audit/list visibility). */
+  completedReason?: string;
+}
+
+/** Is this a DURABLE-JOB routine (OPE-55) — one that keeps its own persistent session across
+ *  fires — as opposed to a today's-default stateless routine? */
+export function isJobRoutine(r: Pick<Routine, "sessionMode">): boolean {
+  return r.sessionMode === "job";
+}
+
+/** This routine's current authority generation — see {@link Routine.promptGeneration}. Absent,
+ *  zero, negative and non-integer all read as 1, so a hand-edited or migrated row can never
+ *  produce a key that collides with a DIFFERENT generation's. */
+export function routinePermissionGeneration(r: Pick<Routine, "promptGeneration">): number {
+  const g = r.promptGeneration;
+  return Number.isInteger(g) && (g as number) > 0 ? (g as number) : 1;
+}
+
+/** The generation an EDIT moves the routine to — always strictly greater than the current one,
+ *  so no edit can ever re-enter a generation whose grants/seat are already out there. */
+export function nextPromptGeneration(r: Pick<Routine, "promptGeneration">): number {
+  return routinePermissionGeneration(r) + 1;
+}
+
+/**
+ * The namespace every {@link routinePermissionKey} carries. It is what makes a routine's permission
+ * key UNCONFUSABLE with a session/window token: `channels/window-key.ts`'s tokens are surface-native
+ * (`slack:…`, a bare provider id), never this, so no session grant can ever be read as a declared
+ * permission or vice versa even though both live in the one `SessionApprovalRow` table.
+ *
+ * Declared by `routines/permission-key.ts`, the zero-import leaf that also holds the two readers for
+ * the key. Re-exported here because this module WRITES the key, so every consumer that spells one
+ * finds the prefix beside {@link routinePermissionKey}.
+ */
+export { ROUTINE_PERMISSION_PREFIX };
+
+/**
+ * The key a routine's DECLARED PERMISSIONS are stored under (OPE-152). It rides the existing
+ * `SessionApprovalRow.sessionId` column — a declared permission is the same fact as a session grant
+ * with a different lifetime, so it gets the same table and the same death mechanism rather than a
+ * second approval plane.
+ *
+ * 🔴 EVERY consumer MUST derive the key through this function. Keying a permission on the bare
+ * routine id would make `edit_routine` a laundering path: approve a write for the routine, then
+ * rewrite the prompt, and the permission a human gave to one instruction is inherited by another one
+ * they never read. Because the generation is IN the key, an edit invalidates the whole declared set with no
+ * sweep, which is essential given the store seam exposes no delete for these rows. (The declared
+ * set is not the whole set since OPE-1290: a refused fire posts a permission card into the routine's
+ * room, and a click there writes another row under this SAME key — so an edit still invalidates
+ * everything at once, which is exactly why the card is keyed here rather than on the bare id.) The
+ * callers are `routines/declared-permissions.ts` (the read/write/revoke seam),
+ * `approvals/routine-permission.ts` (the card's click) and the fire stamp below, so "derive it
+ * through this function" is structural, not a convention.
+ */
+export function routinePermissionKey(r: Pick<Routine, "id" | "promptGeneration">): string {
+  return `${ROUTINE_PERMISSION_PREFIX}${r.id}:g${routinePermissionGeneration(r)}`;
+}
+
+/** Does this routine report NOTHING into its surface (OPE-149)? — see {@link RoutineReport}. */
+export function isSilentRoutine(r: Pick<Routine, "report">): boolean {
+  return r.report?.kind === "silent";
+}
+
+/**
+ * REFUSE the two contradictions the (trigger, report, sessionMode) triple can express:
+ *
+ *   1. A SILENT routine whose stored trigger is `watch`. `watch` IS the only-on-change post
+ *      policy — its whole mechanism is "post when the observed state differs" (routines/watch.ts)
+ *      — so pairing it with "never post" asks the host to run a diff whose only consumer has been
+ *      removed. A silent watch is just a silent cron, so the shape is refused rather than quietly
+ *      reinterpreted.
+ *
+ *   2. A DURABLE JOB (`sessionMode: "job"`) whose stored trigger is `watch`. `renderFireMessage`
+ *      (routines/fire-message.ts) checks `isJobRoutine` FIRST and returns before the watch arm ever
+ *      runs — the job protocol supersedes the watch protocol unconditionally. So a job+watch
+ *      routine's diff step never executes, and every fire posts, no matter what `only-on-change`
+ *      told the human it would do. `describeTrigger` has no job awareness either, so the
+ *      confirmation card would read "durable job every 15 min (posts only on change)" while the
+ *      routine posts on every single fire — the confirmation string would be a lie. Refused for the
+ *      same reason as (1): the field would exist on the schema and do nothing.
+ *
+ * Called at every boundary a routine's (trigger, report, sessionMode) triple can be formed or
+ * re-enter through — the model-facing tool (tools/create_routine.ts, where the job/watch pair is
+ * refused earlier too but this is the one place the invariant is asserted rather than merely
+ * implied), the durable store write (routines/store.ts addRoutine, which a hand-built or migrated
+ * row also passes through), and the edit lifecycle (approvals/routine-lifecycle.ts routine.edit,
+ * which cannot change either field but re-asserts anyway on the standing store-boundary discipline
+ * that no caller is trusted to have checked it). The store check is the load-bearing one: a schema
+ * can be widened, a stored row can be edited, and the invariant has to hold for whatever actually
+ * reaches the dispatcher.
+ */
+export function assertReportConsistent(
+  trigger: RoutineTrigger,
+  report: RoutineReport | undefined,
+  sessionMode?: "job",
+): void {
+  if (report?.kind === "silent" && trigger.kind === "watch") {
+    throw new Error(
+      "A routine can't be both `never` (posts nothing) and only-on-change — a silent watch is just a silent cron. Pick one.",
+    );
+  }
+  if (sessionMode === "job" && trigger.kind === "watch") {
+    throw new Error(
+      "A durable job can't use only-on-change — a job's fire always gets the job protocol (its own accumulated thread context), which supersedes the watch protocol entirely, so the diff step that would post only on change never runs and the job posts on EVERY fire instead. Drop `job`, or use `every-run` or `never` instead of `only-on-change`.",
+    );
+  }
+}
+
+/**
+ * THROWS if an `event` trigger carries a stored filter shape this build cannot read (OPE-1145) —
+ * a surviving pre-OPE-210 `filter` / `match`, or any other key a hand-edit invented.
+ *
+ * WHY IT THROWS AT THE DURABLE WRITE AND NOT AT EVERY READ. The store is where an unreadable row
+ * can still be STOPPED; a read-path throw would abort `listAllRoutines` for the whole dispatcher
+ * tick, so one hand-edited row would silence every OTHER tenant's schedules — the same fleet-wide
+ * blast radius `event-match.ts` refuses a fire-time throw for. A row already at rest is caught on
+ * the other two surfaces instead, and both are loud: `evaluateSubscription` reports it `invalid`
+ * (a `routine.skip` audit row, reason `filter_invalid`, and NO fire), and `describeFilter` renders
+ * it as unreadable wherever a human reads the subscription back.
+ *
+ * The TypeScript type already forbids the shape, which is exactly why this exists: the rows this
+ * catches are the ones that never passed through the compiler — a migrated row, a hand-edited row,
+ * a row written by an older build.
+ */
+export function assertKnownSubscription(trigger: RoutineTrigger): void {
+  if (trigger.kind !== "event") return;
+  const f = storedFilter(trigger);
+  if (f.kind !== "unknown") return;
+  throw new Error(
+    `This event subscription carries a filter shape this build cannot read: ${f.keys.join(", ")}. ` +
+      "A subscription filter is a jq expression (`jq`) and has been since OPE-210; the retired `filter` and `match` " +
+      "languages were deleted by OPE-1145. Rewrite the filter as jq rather than storing a shape nothing can evaluate — " +
+      "a row like this can never fire.",
+  );
+}
+
+/** Trigger kinds the clock-driven dispatcher evaluates (vs event-driven). */
+export function isClockScheduled(t: RoutineTrigger): boolean {
+  return t.kind === "cron" || t.kind === "interval" || t.kind === "watch" || t.kind === "once";
+}
+
+// Auth-attribute keys the dispatcher stamps onto a fired routine's session, so a
+// session-end hook can attribute the real outcome (ok/failed) back to the routine
+// and let it self-disable. (The dispatcher advances the schedule optimistically;
+// the OUTCOME is only known when the fired session finishes — this carries the link.)
+export const ROUTINE_MARKER = {
+  id: "open_everywhere_routine_id",
+  surface: "open_everywhere_routine_surface",
+  org: "open_everywhere_routine_org",
+  /** OPE-149: this fire REPORTS NOTHING — host-set, model-unforgeable (channels/unified-window.ts
+   *  §AUTH-ATTRIBUTE PROVENANCE), stamped only by routines/fire-auth.ts off the stored
+   *  {@link RoutineReport}. hooks/routine-silence.ts turns it into the per-turn signal that drops
+   *  the turn's terminal prose. Stamped ONLY when silent — a normal fire's bag is byte-identical. */
+  silent: "open_everywhere_routine_silent",
+  /** OPE-147: this fire was asked for OFF-SCHEDULE by a human (`run_routine_now`) — host-set,
+   *  model-unforgeable (channels/unified-window.ts §AUTH-ATTRIBUTE PROVENANCE), stamped only by
+   *  routines/fire-auth.ts off the stored {@link Routine.manualRunAt}. hooks/routine-outcome.ts
+   *  reads it back so the `routine.fire` join row can carry `manual: true`. Stamped ONLY on a
+   *  manual fire — a scheduled fire's bag is byte-identical. */
+  manual: "open_everywhere_routine_manual",
+  /** OPE-152: the DECLARED-PERMISSION KEY this fire's approvals are keyed under — host-set,
+   *  model-unforgeable (channels/unified-window.ts §AUTH-ATTRIBUTE PROVENANCE), stamped only by
+   *  routines/fire-auth.ts from {@link routinePermissionKey} off the STORED row (so it carries the
+   *  row's live {@link Routine.promptGeneration}, not one the fired session could name).
+   *
+   *  It is what makes "approve for this routine" the SAME mechanism as "approve for session"
+   *  rather than a second approval plane: `identity/binding.ts` proposingSessionId returns this key
+   *  in place of the window token for a fire, so the consult site (open_pull_request's session
+   *  skip) and the click path's memo write (approvals/flow.ts, off the frozen `sessionId` arg)
+   *  land on the routine's key with NO branch of their own.
+   *
+   *  Unlike the silent/manual stamps this one is NOT positive-only — every routine fire carries it,
+   *  because a fire with no key would silently fall back to its window token and write a permission
+   *  row that outlives nothing and revokes with nothing.
+   *
+   *  🔴 THE VALUE IS A WIRE STRING AND DOES NOT MOVE (OPE-1303). It is the attribute key a live
+   *  fire's auth bag already carries, so the vocabulary sweep renamed this field and left
+   *  `"open_everywhere_routine_grant_key"` alone. Renaming the value would make an in-flight fire
+   *  fall back to its window token — exactly the failure the paragraph above rules out. */
+  permissionKey: "open_everywhere_routine_grant_key",
+  /** OPE-626: THE PER-FIRE ID — host-minted once per fire by the dispatcher (`fireWakeId`), stamped
+   *  by routines/fire-auth.ts, and carried by every turn of that fire.
+   *
+   *  It exists because `oe_wake_id` — the value hooks/routine-outcome.ts latched on — is stamped by
+   *  the UNIFIED-WINDOW divert (routines/fire-window.ts) and by nothing else. A fire that stays on
+   *  the NATIVE path carries none, so every fire in one session collapsed to the hook's shared
+   *  `no-wake` sentinel. For a per-run fire seat that is harmless (one session, one fire); for a
+   *  native-path JOB seat, which is ONE session across MANY fires, it meant the first fire latched
+   *  the sentinel and every later fire in that seat folded nothing, silently, for the life of the
+   *  seat. This stamp is on BOTH paths, so the latch has a real per-fire key on either.
+   *
+   *  Its value is the SAME uuid the divert stamps as `oe_wake_id` on the windowed path — the
+   *  dispatcher mints one id and passes it to both — so a windowed fire's latch key does not change.
+   *
+   *  It is DELIBERATELY NOT `oe_wake_id` itself, which is the other id the dispatcher already holds.
+   *  That stamp is the REPLY ADDRESS (identity/binding.ts `currentWakeId`) and the delivery nonce's
+   *  fallback (`deliveryStampOf`). A native fire registers no `wakeId → origin` row, so stamping it
+   *  there would hand the session a live-looking address that resolves to nothing, and would change
+   *  the task-wake comparison — both outside the fold this ticket is about. A routine-scoped key has
+   *  exactly one reader.
+   *
+   *  Every ROUTINE ingress stamps it: the clock dispatcher (schedules/dispatch.ts) and the event
+   *  fan-out (routines/ingress.ts). A WEBHOOK fire builds `webhookFireAttributes` instead and
+   *  carries no routine marker at all, so the outcome fold never arms for one and it needs no key. */
+  fire: "open_everywhere_routine_fire_id",
+  /** OPE-1627: the {@link ModelRole} this fire resolves instead of `primary` — host-set,
+   *  model-unforgeable (channels/unified-window.ts §AUTH-ATTRIBUTE PROVENANCE), stamped only by
+   *  routines/fire-auth.ts off the STORED {@link Routine.modelRole}.
+   *
+   *  POSITIVE-ONLY, and that is what makes inheritance the default at the wire as well as in the
+   *  type: a routine that names no role stamps nothing, so its bag is byte-identical to before this
+   *  field existed and `model/routing.ts` resolves exactly the role it always did. A fire cannot
+   *  ask for a cheaper model by talking — the value comes off the row the dispatcher read. */
+  modelRole: "open_everywhere_routine_model_role",
+} as const;
+
+type Attrs = Readonly<Record<string, string | readonly string[]>> | undefined;
+/** One string off an eve attribute bag, which holds either a value or a single-element array.
+ *  Exported because hooks/routine-outcome.ts reads the fire's `oe_wake_id` off the SAME bag and a
+ *  second copy of this three-line shape is a place for the two readers to drift. */
+export function oneAttrValue(v: string | readonly string[] | undefined): string | undefined {
+  if (typeof v === "string") return v;
+  if (Array.isArray(v) && typeof v[0] === "string") return v[0];
+  return undefined;
+}
+
+/** Extract the routine link from a session's auth attributes, or null. `org`
+ *  defaults to "default" for markers written before org was carried (back-compat). */
+export function routineMarker(attributes: Attrs): { id: string; surfaceKey: string; org: string } | null {
+  const id = oneAttrValue(attributes?.[ROUTINE_MARKER.id]);
+  const surfaceKey = oneAttrValue(attributes?.[ROUTINE_MARKER.surface]);
+  const org = oneAttrValue(attributes?.[ROUTINE_MARKER.org]) ?? "default";
+  return id && surfaceKey ? { id, surfaceKey, org } : null;
+}
+
+/** Extract the SILENT fire stamp from a session's auth attributes (OPE-149). Positive-only: the
+ *  attribute is written only for a silent fire, so anything else — absent, empty, a different
+ *  value — reads as "this fire posts", the pre-OPE-149 behaviour. */
+export function routineSilentStamped(attributes: Attrs): boolean {
+  return oneAttrValue(attributes?.[ROUTINE_MARKER.silent]) === "true";
+}
+
+/** The model roles a routine may name (OPE-1627) — the routable set, and nothing else.
+ *
+ *  🔴 IT IS THE `ModelRoutes` KEY SET AND IS PINNED TO IT. A role a domain cannot route resolves
+ *  nothing, so accepting one would let a routine name a role that can never take effect and never
+ *  say so. `npm run lint:model-ids` (RULE 6) joins this list to the roles `agent/model/models.ts`
+ *  resolves, so a role added to the stack and forgotten here — or listed here and absent from the
+ *  stack — reds rather than drifting. */
+export const ROUTINE_MODEL_ROLES: readonly ModelRole[] = ["primary", "utility", "supervisor"] as const;
+
+/** Is `value` a role a routine may name? The runtime half of {@link Routine.modelRole}: the TYPE
+ *  forbids the shape, which is exactly why this exists — a migrated row, a hand-edited row, or a
+ *  row written by a newer build never passed through the compiler. */
+export function isRoutineModelRole(value: unknown): value is ModelRole {
+  return typeof value === "string" && (ROUTINE_MODEL_ROLES as readonly string[]).includes(value);
+}
+
+/** Extract the MODEL-ROLE stamp from a session's auth attributes (OPE-1627), or undefined.
+ *
+ *  🔴 UNDEFINED MEANS INHERIT, and every rejection lands there. Positive-only like the silent and
+ *  manual stamps beside it, and VALIDATED on the way out: a bag carrying an unknown role reads as
+ *  "inherit" rather than being passed to the router, so the worst a broken or hand-set value can do
+ *  is leave the routine on the model it would have run anyway. */
+export function routineModelRoleStamped(attributes: Attrs): ModelRole | undefined {
+  const role = oneAttrValue(attributes?.[ROUTINE_MARKER.modelRole]);
+  return isRoutineModelRole(role) ? role : undefined;
+}
+
+/**
+ * Refuse a routine row whose {@link Routine.modelRole} is not a role anything can route.
+ *
+ * Called from `routines/store.ts addRoutine` beside {@link assertKnownSubscription}, for the same
+ * reason that one exists: the TypeScript type already forbids the shape, so the rows this catches
+ * are the ones that never passed through the compiler. It sits on the CREATE path only, exactly
+ * where its two siblings sit — `updateRoutine` takes a `Partial<Routine>` and runs none of the
+ * three, and moving one of them there without the others would be a half-invariant.
+ *
+ * 🔴 IT REFUSES AT THE WRITE, NOT AT THE FIRE. A fire that met an unknown role would have to choose
+ * between failing the run and running the wrong model, and both are worse than never storing the
+ * row. {@link routineModelRoleStamped} still degrades to inherit at the fire, because a row written
+ * by an older build must never break a deployment that rolls back.
+ */
+export function assertKnownModelRole(r: Pick<Routine, "modelRole">): void {
+  if (r.modelRole === undefined) return; // absent = inherit, the default
+  if (isRoutineModelRole(r.modelRole)) return;
+  throw new Error(
+    `This routine names the model role ${JSON.stringify(r.modelRole)}, which nothing can route. ` +
+      `A routine names one of: ${ROUTINE_MODEL_ROLES.join(", ")} — or names none, which inherits the deployment's model stack ` +
+      "(routines/routine.ts Routine.modelRole).",
+  );
+}
+
+/**
+ * Extract the DECLARED-PERMISSION KEY stamped onto a routine fire (OPE-152), or undefined off a
+ * fire. The value must carry {@link ROUTINE_PERMISSION_PREFIX} to be honoured: that is what stops a
+ * bag with a hand-set/garbage value from redirecting a permission lookup at an arbitrary session
+ * token, and it keeps the "a routine key is unconfusable with a window token" property a CHECK
+ * rather than a comment.
+ */
+export function routinePermissionKeyStamped(attributes: Attrs): string | undefined {
+  const key = oneAttrValue(attributes?.[ROUTINE_MARKER.permissionKey]);
+  return key !== undefined && key.startsWith(ROUTINE_PERMISSION_PREFIX) ? key : undefined;
+}
+
+/** Extract the MANUAL fire stamp from a session's auth attributes (OPE-147). Positive-only, for
+ *  the same reason {@link routineSilentStamped} is: the attribute is written only for a fire a
+ *  human asked for off-schedule, so anything else reads as "this was the clock", the default. */
+export function routineManualStamped(attributes: Attrs): boolean {
+  return oneAttrValue(attributes?.[ROUTINE_MARKER.manual]) === "true";
+}
+
+/**
+ * Extract the PER-FIRE ID stamped onto a routine fire (OPE-626, {@link ROUTINE_MARKER.fire}), or
+ * undefined when the bag carries none.
+ *
+ * `undefined` is a real answer, not a failure: a fire dispatched by a deployment older than this
+ * stamp carries no id, and hooks/routine-outcome.ts falls back to `oe_wake_id` and then to its
+ * fail-closed sentinel. An empty string reads as absent, so a blank stamp can never become a latch
+ * key every fire in a session would share.
+ */
+export function routineFireIdStamped(attributes: Attrs): string | undefined {
+  const id = oneAttrValue(attributes?.[ROUTINE_MARKER.fire]);
+  return id !== undefined && id.length > 0 ? id : undefined;
+}
+
+/** One-line human description of a trigger, for `list_routines` / the CLI.
+ *  Post policy is spelled out, never jargon ("watch").
+ *
+ *  `report` (OPE-149) is the routine's post policy where the TRIGGER can't carry it: a silent
+ *  routine's stored trigger is an ordinary `cron`/`interval`, so without this the whole list view
+ *  would claim a routine "posts every run" while it is structurally incapable of posting. That is
+ *  visibility leg 1 of three (the others: the `routine.fire` audit row, and the self-disable
+ *  announcement) — a silent routine is only legible if every surface that describes it says so. */
+export function describeTrigger(t: RoutineTrigger, report?: RoutineReport): string {
+  const silent = report?.kind === "silent";
+  // OPE-148 — a REDIRECTED routine names its destination in the SAME string, for the same reason a
+  // silent one names its silence: `list_routines` and the approval card both render this, and a
+  // routine that will post somewhere other than the room reading the card is exactly the fact that
+  // must not have to be inferred. Byte-identical for every row without a `surface` report.
+  const where = report?.kind === "surface" ? ` → posts into ${report.surfaceKey}` : "";
+  return describeTriggerCore(t, silent) + where;
+}
+
+function describeTriggerCore(t: RoutineTrigger, silent: boolean): string {
+  switch (t.kind) {
+    case "cron":
+      return `cron "${t.expr}" (UTC; ${silent ? "posts nothing" : "posts every run"})`;
+    case "interval":
+      return `every ${t.everyMinutes} min (${silent ? "posts nothing" : "posts every run"})`;
+    case "watch":
+      return t.expr !== undefined
+        ? `cron "${t.expr}" (UTC; posts only on change)`
+        : `every ${t.everyMinutes} min (posts only on change)`;
+    case "once":
+      return `once at ${t.at} (fires once, then disables)`;
+    case "event":
+      return describeFilter(t.source, t);
+  }
+}