@open-everywhere/core 0.1.0

package/agent/routines/schedule.ts

@@ -0,0 +1,209 @@
+// Pure scheduling math for routines — no I/O, no framework, fully deterministic
+// so it's unit-testable (scripts/routines-test.ts). All times are UTC.
+//
+// We use a **nextRunAt** model rather than matching "is now a cron minute":
+// each routine stores the next instant it's due, and the dispatcher fires when
+// `nextRunAt <= now`, then recomputes. This is robust to tick cadence — a routine
+// can't be missed or double-fired just because the dispatcher ticks every minute
+// vs every five. `computeNextRun` is the one function that turns a trigger + a
+// "from" instant into the next due instant.
+//
+// Tick-cadence independence is only real if the recompute is anchored on the instant the
+// routine was DUE rather than the instant it was DISPATCHED — otherwise every tick's
+// lateness compounds into the period (OPE-146; see nextIntervalAfter). That is what
+// `computeNextRun`'s second/third arguments separate, and what DISPATCH_TICK_MINUTES
+// bounds: a routine fires at most once per tick, whatever cadence it asks for.
+//
+// The cron parser is a dependency-free standard 5-field implementation
+// (minute hour day-of-month month day-of-week), enough for the real cases and
+// the documented escape hatch. Day-of-month vs day-of-week uses Vixie/Cron
+// semantics: when BOTH are restricted, a tick matches if EITHER matches.
+
+export interface CronField {
+  readonly star: boolean;
+  has(n: number): boolean;
+}
+
+export interface ParsedCron {
+  readonly minute: CronField;
+  readonly hour: CronField;
+  readonly dom: CronField;
+  readonly month: CronField;
+  readonly dow: CronField;
+}
+
+const MIN = 60_000;
+
+/**
+ * The routine dispatcher's tick cadence, in minutes — the ONE source of truth for it
+ * (schedules/dispatch.ts builds its cron from this, spend/reporting.ts floors its
+ * cadence predictions at it). A routine can be dispatched at most once per tick, so
+ * this is also the finest cadence any routine can actually achieve, whatever its
+ * trigger asks for. Changing it changes both the schedule and every prediction that
+ * reads it, together — which is the point of it living here rather than as a literal
+ * in two files that could drift.
+ */
+export const DISPATCH_TICK_MINUTES = 10;
+
+function field(values: ReadonlySet<number>, star: boolean): CronField {
+  return { star, has: (n) => star || values.has(n) };
+}
+
+// Parse one cron field over [lo, hi]: `*`, `*/n`, `a`, `a-b`, `a-b/n`, and
+// comma lists of those. Throws on anything out of range or malformed.
+function parseField(spec: string, lo: number, hi: number): CronField {
+  const raw = spec.trim();
+  if (raw === "*") return field(new Set(), true);
+
+  const out = new Set<number>();
+  for (const part of raw.split(",")) {
+    const [rangePart, stepPart] = part.split("/");
+    const step = stepPart === undefined ? 1 : Number(stepPart);
+    if (!Number.isInteger(step) || step < 1) throw new Error(`bad step in "${part}"`);
+
+    let start = lo;
+    let end = hi;
+    if (rangePart !== "*" && rangePart !== "") {
+      const bounds = rangePart.split("-");
+      if (bounds.length === 1) {
+        start = end = Number(bounds[0]);
+      } else if (bounds.length === 2) {
+        start = Number(bounds[0]);
+        end = Number(bounds[1]);
+      } else {
+        throw new Error(`bad range in "${part}"`);
+      }
+    }
+    if (!Number.isInteger(start) || !Number.isInteger(end) || start < lo || end > hi || start > end) {
+      throw new Error(`out-of-range field "${part}" (allowed ${lo}-${hi})`);
+    }
+    for (let n = start; n <= end; n += step) out.add(n);
+  }
+  return field(out, false);
+}
+
+/** Parse a standard 5-field cron expression. Throws on malformed input. */
+export function parseCron(expr: string): ParsedCron {
+  const parts = expr.trim().split(/\s+/);
+  if (parts.length !== 5) {
+    throw new Error(`cron must have 5 fields (min hour dom mon dow), got ${parts.length}: "${expr}"`);
+  }
+  return {
+    minute: parseField(parts[0], 0, 59),
+    hour: parseField(parts[1], 0, 23),
+    dom: parseField(parts[2], 1, 31),
+    month: parseField(parts[3], 1, 12),
+    dow: parseField(parts[4], 0, 6), // 0 = Sunday
+  };
+}
+
+/** Does a UTC instant satisfy a parsed cron expression (to minute resolution)? */
+export function cronMatches(c: ParsedCron, date: Date): boolean {
+  if (!c.minute.has(date.getUTCMinutes())) return false;
+  if (!c.hour.has(date.getUTCHours())) return false;
+  if (!c.month.has(date.getUTCMonth() + 1)) return false;
+
+  const dom = date.getUTCDate();
+  const dow = date.getUTCDay(); // 0-6, Sun=0
+  // Vixie cron: if both DOM and DOW are restricted, match on EITHER; otherwise
+  // both (effectively) the restricted one must match.
+  if (!c.dom.star && !c.dow.star) return c.dom.has(dom) || c.dow.has(dow);
+  return c.dom.has(dom) && c.dow.has(dow);
+}
+
+function floorToMinute(date: Date): Date {
+  return new Date(Math.floor(date.getTime() / MIN) * MIN);
+}
+
+/**
+ * The first cron-matching minute strictly AFTER `from`. Scans minute-by-minute
+ * up to a bound (~13 months) to cover yearly schedules; returns null if nothing
+ * matches in range (treat as a malformed/never-firing routine).
+ */
+export function nextCronAfter(c: ParsedCron, from: Date): Date | null {
+  const start = floorToMinute(from).getTime() + MIN;
+  const limit = 367 * 24 * 60; // minutes to scan
+  for (let i = 0; i < limit; i++) {
+    const t = new Date(start + i * MIN);
+    if (cronMatches(c, t)) return t;
+  }
+  return null;
+}
+
+// A structural subset of Routine's trigger — kept local so this module stays
+// import-light. Matches RoutineTrigger from routine.ts.
+type Trigger =
+  | { kind: "cron"; expr: string }
+  | { kind: "interval"; everyMinutes: number }
+  | { kind: "watch"; everyMinutes?: number; expr?: string }
+  | { kind: "once"; at: string }
+  | { kind: "event"; source: string };
+
+/**
+ * The next interval instant strictly after `notBefore`, stepping in WHOLE periods from
+ * the schedule ANCHOR — the instant the routine was due, not the instant it happened to
+ * be dispatched.
+ *
+ * WHY THE ANCHOR MATTERS (OPE-146 / audit §S11). The dispatcher ticks every
+ * {@link DISPATCH_TICK_MINUTES} minutes, so a fire always lands somewhere in
+ * `[due, due + tick)`. Advancing from the FIRE instant compounds that lateness into the
+ * cadence itself: an `everyMinutes: 15` routine due at T is dispatched at T+5 (the next
+ * tick), schedules T+20, is dispatched at T+20, schedules T+35 → dispatched T+40. It
+ * drifts to a 20-minute period — 33% dilation — and the module header's
+ * "tick-cadence-independent" claim is false for exactly this trigger kind. Stepping from
+ * the anchor keeps the period exact.
+ *
+ * CATCH-UP, not backlog: if the anchor is far in the past (a deploy gap, a store outage),
+ * whole periods are skipped until the result is strictly in the future. A missed window
+ * is never replayed as a burst of back-to-back fires — the routine simply resumes on its
+ * own grid.
+ */
+function nextIntervalAfter(anchor: Date, everyMinutes: number, notBefore: Date): Date {
+  const period = Math.max(1, everyMinutes) * MIN;
+  const base = anchor.getTime();
+  const floor = notBefore.getTime();
+  if (base + period > floor) return new Date(base + period);
+  // Whole periods forward from the anchor, landing strictly after `notBefore`.
+  return new Date(base + (Math.floor((floor - base) / period) + 1) * period);
+}
+
+/**
+ * The next instant a trigger is due, given a "from" instant and (optionally) a "not
+ * before" floor. Null for `event` triggers (not clock-scheduled), for a cron that
+ * never fires in range, for a watch with neither cadence nor cron (which
+ * create_routine refuses to store), and ALWAYS for `once` — a one-shot's due
+ * instant is fixed at creation (create_routine sets nextRunAt = `at` directly,
+ * bypassing this function) and never recomputed: there is no "next" occurrence
+ * after it fires, which is what makes the dispatcher's advance-the-schedule step
+ * naturally retire it (nextRunAt -> null) whether it fires or is declined.
+ *
+ * `from` is the schedule ANCHOR — at creation, "now"; at dispatch, the instant the
+ * routine was DUE. `notBefore` is the instant the result must be strictly after, i.e.
+ * the dispatcher's tick instant; it defaults to `from`, which is the creation-time
+ * call and leaves that path byte-identical. See {@link nextIntervalAfter} for why the
+ * two are separated. Cron is anchored to the wall clock by construction, so it simply
+ * takes the later of the two — unchanged behaviour at either call site.
+ */
+export function computeNextRun(trigger: Trigger, from: Date, notBefore: Date = from): Date | null {
+  const cronFrom = notBefore.getTime() > from.getTime() ? notBefore : from;
+  switch (trigger.kind) {
+    case "cron":
+      return nextCronAfter(parseCron(trigger.expr), cronFrom);
+    case "watch":
+      if (trigger.expr !== undefined) return nextCronAfter(parseCron(trigger.expr), cronFrom);
+      return trigger.everyMinutes === undefined ? null : nextIntervalAfter(from, trigger.everyMinutes, notBefore);
+    case "interval":
+      return nextIntervalAfter(from, trigger.everyMinutes, notBefore);
+    case "once":
+      return null;
+    case "event":
+      return null;
+  }
+}
+
+/** Is a routine with this `nextRunAt` due at `now`? */
+export function isDue(nextRunAt: string | null | undefined, now: Date): boolean {
+  if (!nextRunAt) return false;
+  const t = Date.parse(nextRunAt);
+  return Number.isFinite(t) && t <= now.getTime();
+}

package/agent/routines/scheme-name.ts

@@ -0,0 +1,96 @@
+// THE SCHEME/NAME CODEC (OPE-198 S2) — the ONE place the two halves of an ingress identity are
+// derived from a row, a delivery or an event.
+//
+// 🔴 WHAT PROBLEM THIS SOLVES. One string, `source`, was doing NINE jobs at once: verifier-registry
+// key, normalizer-registry key, scope-grant-registry key, the hook-id uniqueness check, the
+// model-facing handle every webhook tool addresses a hook by, the routine subscription join, the
+// trigger-only summary text, the audit principal / vault label, and half of `deliveryDedupeKey`.
+// Those are TWO concepts wearing one name:
+//
+//   • the SCHEME — WHICH CONTRACT authenticates and interprets a delivery. It is a registry key on
+//     three registries (webhooks/verifier.ts, routines/event-model.ts, routines/event-authz.ts) and
+//     it is a property of the SENDING SYSTEM's contract, not of this deployment.
+//   • the NAME — WHICH HOOK this is, here. Unique per deployment, model-facing, what an `event`
+//     routine subscribes to, and what a merged PR is authoritative for.
+//
+// Today every hook has `scheme === name` (a `github` hook is named "github"), which is exactly why
+// one field could do both jobs for as long as it did. It stops being true the moment two hooks want
+// the same contract under different handles — one scheme, many senders, each independently
+// subscribable.
+//
+// ⭐ BACKWARD COMPATIBILITY IS THE ABSENCE RULE, NOT A MIGRATION: `scheme` ABSENT ⇒ `scheme = source`.
+// Every stored row, every in-flight delivery and every normalizer's output predates the field and is
+// therefore correct under that rule without being rewritten — the same `provisioning?: absent ⇒
+// mint` / `redactPayload?` posture this tree uses everywhere else: additive optional field on a
+// JSON row, read forward.
+//
+// ⭐ THE NAME IS SPELLED `source`, DELIBERATELY, AND IS NOT BEING RENAMED. It is the spelling on the
+// wire and in the model's mouth: the field on a delivery, on a normalized event and on a routine's
+// subscription, and the parameter every webhook tool addresses a hook by. Renaming it would rewrite
+// stored routine subscriptions and every normalizer's output to buy nothing a comment cannot — so
+// the field keeps its spelling and this module supplies the vocabulary. Read `source` as "the NAME"
+// everywhere the two could differ, and go through {@link webhookScheme} rather than `.source`
+// anywhere a REGISTRY is being resolved.
+//
+// PURE LEAF, ZERO IMPORTS — and it lives under `routines/` rather than `webhooks/` for a structural
+// reason, not a taxonomic one: the import direction in this tree is `webhooks/* → routines/*` and
+// never the reverse (webhooks/source-vocabulary.ts and webhooks/dispatch.ts both reach into
+// routines/; nothing goes back). The ingress and the routing plane both need this codec, so it has
+// to sit on the side that both can already reach.
+
+/**
+ * Anything carrying an ingress identity: a declared hook ({@link
+ * import("../webhooks/config.js").WebhookHook}), the gate-shaped view of one, a {@link
+ * import("./event-model.js").TriggerDelivery}, or a normalized event. All four have the same two
+ * fields for the same two reasons, so one structural type serves all of them and there is exactly
+ * one derivation to keep honest.
+ */
+export interface SchemeNamed {
+  /** THE NAME (the handle). See the module header for why it is spelled `source`. */
+  readonly source: string;
+  /** THE SCHEME (the registry key). ABSENT ⇒ the name — see the module header. */
+  readonly scheme?: string;
+}
+
+/** Both halves, derived. The shape a caller wants when it needs to name both in one sentence. */
+export interface WebhookIdentity {
+  readonly name: string;
+  readonly scheme: string;
+}
+
+/**
+ * THE REGISTRY KEY. Use this — never `.source` — wherever a verifier, a normalizer or a scope grant
+ * is looked up. The three sites are `webhooks/gate.ts` (verifier), `routines/event-model.ts`
+ * (normalizer, inside `normalizeDelivery` and `declaredDeliveryId`) and `routines/event-authz.ts`
+ * (scope grant), plus the fire-time vocabulary re-check in `routines/event-match.ts`.
+ */
+export function webhookScheme(x: SchemeNamed): string {
+  return x.scheme ?? x.source;
+}
+
+/**
+ * THE HANDLE. A trivial projection today, and named anyway: the point of this module is that a
+ * reader who wants the handle asks for the handle. `.source` reads as "the registry key" to anyone
+ * who has not read the header, and that misreading is the whole bug class this split closes.
+ */
+export function webhookName(x: SchemeNamed): string {
+  return x.source;
+}
+
+/** Both halves at once. */
+export function webhookIdentity(x: SchemeNamed): WebhookIdentity {
+  return { name: webhookName(x), scheme: webhookScheme(x) };
+}
+
+/**
+ * Does this identity still have the pre-split single-string property (`scheme === name`)?
+ *
+ * Exported for the differential golden (`scripts/webhook-scheme-name-test.ts`), which asserts it
+ * holds for EVERY hook shape that exists today — i.e. that the split is a no-op on the shipped
+ * world. It is a MEASUREMENT, not an invariant: the day a category-(b) hook is created it becomes
+ * false, and that is the point. Nothing may branch on it.
+ */
+export function isSingleStringIdentity(x: SchemeNamed): boolean {
+  const id = webhookIdentity(x);
+  return id.name === id.scheme;
+}

package/agent/routines/stall.ts

@@ -0,0 +1,153 @@
+// THE STALL (OPE-253) — the THIRD state a durable job can be in, and until now the only one nothing
+// in the tree could see or reap. PURE, deterministic, unit-tested (scripts/routine-bound-test.ts §6).
+// The impure half (persist the stamp, write the forensic row) is routines/outcome-fold.ts
+// recordCheckpointStall + the stall arithmetic in foldRoutineOutcome — the same pure/impure split
+// bound.ts / outcome-fold.ts already take for the ceiling.
+//
+// ── WHAT THIS CLOSES ────────────────────────────────────────────────────────────────────────────
+// OPE-248 gave a durable job a fire-count + deadline ceiling, so a job that SUCCEEDS forever retires
+// with a host-composed notice. That covers *runs-forever*. It does not cover *stalls-silently*.
+//
+// A configured session cost checkpoint (spend/checkpoint.ts) soft-blocks CONSEQUENTIAL tools at their
+// execute() top and posts a "keep going?" card. The failure DIRECTION is right — stopping is correct
+// — but on a routine fire it stalls in silence, because a fire has no human present by construction:
+// the card lands in a room nobody is watching at the hour a cron fire runs. That left the job in a
+// state nothing reaped:
+//
+//   • NOT FAILED, so `consecutiveFailures` never counts it. A soft-blocked tool throws a RECOVERABLE
+//     tool-error the model reads and works around; the fire then replies and settles `ok`
+//     (lifecycle.ts applyOutcome resets the counter to 0 on any non-failed settlement).
+//   • NOT COMPLETE, so `complete_job` never fires — the job could not do the work that would let it
+//     conclude anything.
+//   • and it BURNED the OPE-248 ceiling while doing nothing useful: the dispatcher counts fires
+//     ATTEMPTED, so 200 fires of "wake, poll, get refused, reply" retire the job a week later under
+//     a notice that says *"nothing failed: it just never finished"* — which is a FALSE diagnosis
+//     here, and points the operator at the wrong next move (re-arm, when the truth is unblock).
+//
+// ── WHY A JOB AND NOT EVERY ROUTINE (the asymmetry is in the code, not in taste) ─────────────────
+// A stateless routine gets a FRESH eve session per fire, so `sessionUsage(org, ctx.session.id)` sums
+// that fire's rows only: a crossing dies with the session and the next fire starts at zero. It
+// self-heals, and its stall run below never gets past 1.
+//
+// A DURABLE JOB resumes ONE session across fires (routine.ts jobSessionAnchor), so the SAME session
+// id accumulates every fire's usage monotonically. Once such a session crosses a threshold it is
+// crossed FOREVER — every later fire evaluates the same ever-growing total against the same
+// threshold. Worse, both checkpoint memos are TTL'd (24h by default, approvals/session-checkpoint.ts
+// checkpointTtlHours): the "asked" marker expiring means a fresh card per day, and the GRANT expiring
+// means a job a human DID approve re-stalls a day later. A job cannot get out of this by itself.
+//
+// So the reap below is keyed on carrying a {@link Routine.bound} — the same key `fireCount` is
+// written under (schedules/dispatch.ts) — which today is exactly the set of durable jobs. The stall
+// bound is a TIGHTENING of the ceiling, so it binds precisely where a ceiling exists; widening it
+// later is a changed default, not a new column. The COUNTER is kept for every routine either way,
+// because "why did my 03:00 routine reply but never file the ticket?" deserves an answer on any row.
+//
+// ── WHERE THE NUMBER COMES FROM ─────────────────────────────────────────────────────────────────
+// {@link MAX_STALLED_FIRES} is a straight REUSE of lifecycle.ts MAX_CONSECUTIVE_FAILURES, exactly as
+// OPE-248's MIN_FIRES_BEFORE_DEADLINE is. This codebase already holds that three tries is the number
+// before you may conclude anything about a routine, and a stall run is that same question asked of a
+// different failure. Inventing a second constant would be inventing a second answer.
+//
+// It is deliberately NOT env-overridable, unlike routines.jobMaxFires / routines.jobMaxDays. There is already
+// an off switch with the right shape: the whole mechanism only engages when an operator has CONFIGURED
+// a spend checkpoint, which is opt-in and empty by default. A knob here would be a third answer to
+// "how many attempts is a fair sample" with nothing to derive it from.
+//
+// ── WHY A COUNT AND NOT ALSO A DEADLINE ─────────────────────────────────────────────────────────
+// OPE-248 needs BOTH dimensions because a count is meaningless for a slow cadence (200 runs is 200
+// days). A stall bound needs only the count, because the slow-cadence case is ALREADY covered: three
+// stalled fires of a weekly job is three weeks, and that job's OPE-248 deadline (stretched to three
+// periods) trips at the same time regardless. The stall bound exists to trip FASTER than the ceiling
+// for a fast cadence — 3 fires instead of 200 — and a count is the only dimension that does that.
+//
+// ── THE HONEST LIMIT ────────────────────────────────────────────────────────────────────────────
+// A fire is counted as stalled when it was actually REFUSED a consequential tool, not when its
+// session merely holds a crossed checkpoint. So a job whose fires mostly poll-and-reply, reaching for
+// a consequential hand only occasionally, resets its run on the clean fires and may never reach three
+// in a row. That is deliberate and it errs the right way: such a job is DOING its work, and retiring
+// working automation because a hand it is not currently using is held would be the same defect the
+// `grant_drift` / `audience_floor` skips exist to avoid (fire-audit.ts) — a deployment's own state
+// change silently disabling a fleet. Those jobs remain bounded by their OPE-248 ceiling, which is
+// exactly the pre-OPE-253 behaviour, now with the stall visible on the row and in the audit trail.
+
+import { MAX_CONSECUTIVE_FAILURES } from "./lifecycle.js";
+import type { Routine } from "./routine.js";
+
+/**
+ * Consecutive checkpoint-stalled fires a bounded routine may accumulate before it retires itself.
+ * REUSES the three-strike constant rather than inventing a second answer to "how many attempts is a
+ * fair sample" — see the header for why it is not env-overridable.
+ */
+// Annotated `number`, not left to infer the literal `3`: it is a THRESHOLD, and the pluralisation in
+// the prose below has to stay honest if the constant it reuses ever moves.
+export const MAX_STALLED_FIRES: number = MAX_CONSECUTIVE_FAILURES;
+
+/** Has this routine stalled on a cost checkpoint too many fires running? PURE.
+ *
+ *  An absent or non-positive counter reads as "not stalling", which is every pre-OPE-253 row, every
+ *  routine on a deployment with no configured checkpoint, and every fire that got its hands. The
+ *  comparison is `>=`, so `MAX_STALLED_FIRES` stalled fires is the last one — the caller checks
+ *  BEFORE dispatching, so the run that trips it has already happened. */
+export function stallExhausted(r: Pick<Routine, "stalledFires">): boolean {
+  const n = r.stalledFires;
+  return Number.isInteger(n) && (n as number) >= MAX_STALLED_FIRES;
+}
+
+/** HOST-COMPOSED reason for the row, the forensic detail and the notice — built from the row's own
+ *  numbers, never from model text (see disable-notice.ts on why nothing else may ride that path). */
+export function stallReason(r: Pick<Routine, "stalledFires">): string {
+  const n = Number.isInteger(r.stalledFires) ? (r.stalledFires as number) : 0;
+  return (
+    `it was blocked on ${n} run${n === 1 ? "" : "s"} in a row by a session cost checkpoint whose ` +
+    `confirmation nobody gave (its limit is ${MAX_STALLED_FIRES} blocked run${MAX_STALLED_FIRES === 1 ? "" : "s"})`
+  );
+}
+
+/**
+ * The stall, in the terms `list_routines` reports it — "blocked on a cost checkpoint: 2/3 runs (last
+ * 2026-07-30T03:00:00.000Z)". Null for a routine that is not stalling, so the list view says nothing
+ * at all about stalls for the rows that have none.
+ *
+ * It belongs on that read for the reason the ceiling and the standing permissions do: a state nobody
+ * can enumerate from the room is not governable from the room — and until now "waiting on a human
+ * click" and "running fine" were the SAME reading of a job, from every surface OE ships.
+ */
+export function describeStall(r: Pick<Routine, "stalledFires" | "lastStallAt">): string | null {
+  const n = Number.isInteger(r.stalledFires) ? (r.stalledFires as number) : 0;
+  if (n <= 0) return null;
+  return (
+    `blocked on a cost checkpoint: ${n}/${MAX_STALLED_FIRES} run${n === 1 ? "" : "s"}` +
+    (r.lastStallAt !== undefined ? ` (last ${r.lastStallAt})` : "")
+  );
+}
+
+/**
+ * The stall arithmetic ONE fire's fold applies, as a patch. PURE — routines/outcome-fold.ts persists
+ * it inside the same write that folds the outcome.
+ *
+ * `lastStallAt` is the per-fire FACT, recorded mid-turn by the refused tool; this is the ARITHMETIC
+ * over it. That split is not new: it is exactly how OPE-177's `report_run_failed` records a fact the
+ * fold then counts into `consecutiveFailures`, and it inherits that field's lifetime invariant — the
+ * dispatcher CLEARS `lastStallAt` on every fire, so a value present when a fold reads the row was
+ * written by THAT run and the count can never drift onto a fire that got its hands.
+ *
+ * Returns `{}` — a byte-identical patch — for a routine that has never stalled and did not stall this
+ * fire, which is every routine on a deployment with no configured checkpoint.
+ */
+export function stallFoldPatch(r: Pick<Routine, "stalledFires" | "lastStallAt">): Partial<Routine> {
+  if (r.lastStallAt !== undefined) {
+    const n = Number.isInteger(r.stalledFires) && (r.stalledFires as number) > 0 ? (r.stalledFires as number) : 0;
+    return { stalledFires: n + 1 };
+  }
+  // This fire got its hands, so the RUN is broken: the counter means "consecutive", the same way
+  // `consecutiveFailures` does, and a monotonic total would retire a job that stalled three times
+  // across months of healthy work.
+  return r.stalledFires !== undefined ? { stalledFires: undefined } : {};
+}
+
+/** The patch that clears a stall run outright — used by the re-arm click, which is a human acting on
+ *  the notice. Both fields go: leaving `lastStallAt` behind would have the NEXT fold count a stall
+ *  that belonged to the run before the re-arm. */
+export function stallResetPatch(): Partial<Routine> {
+  return { stalledFires: undefined, lastStallAt: undefined };
+}

package/agent/routines/store.ts

@@ -0,0 +1,100 @@
+// Durable routine store — now DB-backed (operational/), not files. Operational state
+// (routines + their run history) stays SEPARATE from knowledge memory (a different,
+// machine-managed lifecycle), and org is the OUTERMOST partition (org_id column) so a
+// hosted, multi-tenant deployment isolates one tenant's schedules from another's at
+// rest. Each routine carries its `org` so the dispatcher fires it back under the right
+// tenant.
+//
+// Thin adapter over the OperationalStore seam (SQLite local / Postgres deploy) — same
+// public API the dispatcher, tools, and admin views use; only the backing changed (was
+// JSON-on-disk + git, which didn't survive serverless).
+
+import { randomUUID } from "node:crypto";
+import type { Partition } from "../memory/partition.js";
+import { assertKnownModelRole, assertKnownSubscription, assertReportConsistent, type Routine } from "./routine.js";
+import { getOperationalStore } from "../operational/provider.js";
+import type { RoutinePromptProvenance, RoutinePromptRevisionRow } from "../operational/store.js";
+
+/** Inspectable backing location (sqlite path / "postgres") — for logging + views. */
+export function routinesRoot(): string {
+  return getOperationalStore().root();
+}
+
+/** New routine id. node crypto is host-side, so randomUUID is fine here. */
+export function newRoutineId(): string {
+  return `r-${randomUUID().slice(0, 8)}`;
+}
+
+/** New standing-rule id (OPE-141) — the handle a human names in the channel to remove one. Minted
+ *  at PROPOSE time and frozen onto the card, so the id on the card, the id in the audit row and the
+ *  id in the rendered fire block are the same string. Lives here rather than in routines/policy.ts
+ *  to keep that module pure (no id source, no clock) for the renderers and their tests. */
+export function newPolicyRuleId(): string {
+  return `p-${randomUUID().slice(0, 8)}`;
+}
+
+/** All routines for one surface (within its org). */
+export function listRoutines(p: Partition): Promise<Routine[]> {
+  return getOperationalStore().listRoutines(p.org, p.surfaceKey);
+}
+
+/** One routine by (org, surfaceKey, id) (used by the outcome hook), or null. */
+export function getRoutine(org: string, surfaceKey: string, id: string): Promise<Routine | null> {
+  return getOperationalStore().getRoutine(org, surfaceKey, id);
+}
+
+/** Add a routine to its surface's list. Returns the stored routine.
+ *
+ *  THROWS on a contradictory trigger/report pair (OPE-149, routine.ts assertReportConsistent), and
+ *  on an event subscription whose stored filter shape this build cannot read (OPE-1145,
+ *  routine.ts assertKnownSubscription), and on a `modelRole` nothing can route (OPE-1627,
+ *  routine.ts assertKnownModelRole).
+ *  Enforcing all three HERE — at the durable write, not only at the tool that usually produces the
+ *  row — is what makes them invariants of the store rather than properties of one caller's zod enum:
+ *  `subscribe_pr` writes routines directly, and a migrated/hand-edited row enters the same way. */
+export function addRoutine(_p: Partition, routine: Routine): Promise<Routine> {
+  assertReportConsistent(routine.trigger, routine.report, routine.sessionMode);
+  assertKnownSubscription(routine.trigger);
+  assertKnownModelRole(routine);
+  // The routine carries its own org + surfaceKey (the partition is redundant here,
+  // kept in the signature for call-site symmetry with the old store).
+  return getOperationalStore().addRoutine(routine);
+}
+
+/** Apply a patch (or full replacement) to one routine by id. Returns it, or null.
+ *  org/surfaceKey/id are immutable — preserved across the patch.
+ *
+ *  A patch that REPLACES `prompt` also appends to the append-only `routine_prompt_revisions` log,
+ *  inside the store — so no write path can destroy a standing instruction without the superseded
+ *  text being recorded first (OPE-242; the argument is on RoutinePromptRevisionRow in
+ *  operational/store.ts). `provenance` names who asked, who armed it, and the card they clicked;
+ *  every other patch records nothing. */
+export function updateRoutine(
+  org: string,
+  surfaceKey: string,
+  id: string,
+  patch: Partial<Routine>,
+  provenance?: RoutinePromptProvenance,
+): Promise<Routine | null> {
+  return getOperationalStore().updateRoutine(org, surfaceKey, id, patch, provenance);
+}
+
+/** Every recorded prompt for a surface's routines, oldest first; narrow with `routineId`. The
+ *  CURRENT text is on the routine row — this log is what the routine used to say. */
+export function listRoutinePromptRevisions(org: string, surfaceKey: string, routineId?: string): Promise<RoutinePromptRevisionRow[]> {
+  return getOperationalStore().listRoutinePromptRevisions(org, surfaceKey, routineId);
+}
+
+/** Remove a routine by id. Returns true if one was removed. */
+export function removeRoutine(p: Partition, id: string): Promise<boolean> {
+  return getOperationalStore().removeRoutine(p.org, p.surfaceKey, id);
+}
+
+/**
+ * Every routine across every org+surface — for the dispatcher tick and the admin
+ * views. Each routine carries its own `org`, so the dispatcher fires it back under
+ * that tenant.
+ */
+export function listAllRoutines(): Promise<Routine[]> {
+  return getOperationalStore().listAllRoutines();
+}