@open-everywhere/core 0.1.0

package/agent/review/zip.ts

@@ -0,0 +1,154 @@
+// A MINIMAL, READ-ONLY ZIP reader — enough to pull one named entry out of a GitHub Actions
+// artifact download and nothing more.
+//
+// WHY THIS EXISTS AT ALL. The Actions artifact API has exactly one download shape:
+// `GET /repos/{repo}/actions/artifacts/{id}/zip` returns a zip. There is no JSON alternative and
+// no per-file endpoint. The PR-walkthrough flow's whole trust argument rests on reading the
+// config-diff facts from the workflow's own ARTIFACT rather than from a PR comment (see
+// review/facts-artifact.ts), so "we cannot unzip" would collapse into "read the comment
+// instead" — which is the one source anybody who can comment on a PR can forge. Hence ~80 lines
+// of zip rather than a dependency.
+//
+// WHAT IT DELIBERATELY DOES NOT DO: no zip64, no encryption, no compression method other than
+// STORE (0) and DEFLATE (8), no directory traversal, no streaming, no writing. Every one of
+// those is a LOUD refusal (`ZipReadError`), never a silent partial read — a half-parsed artifact
+// that yielded an empty facts document would render as "nothing changed", which is exactly the
+// green-produced-by-blindness this whole feature is built to refuse.
+//
+// PURE: no filesystem, no network, no clock. The caller hands it bytes.
+
+import { inflateRawSync } from "node:zlib";
+
+/** Thrown for any malformed / unsupported archive. Never a partial result. */
+export class ZipReadError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ZipReadError";
+  }
+}
+
+/** End-of-central-directory signature `PK\x05\x06`. */
+const EOCD_SIG = 0x06054b50;
+/** Central-directory file-header signature `PK\x01\x02`. */
+const CD_SIG = 0x02014b50;
+/** Local file-header signature `PK\x03\x04`. */
+const LOCAL_SIG = 0x04034b50;
+
+/** The EOCD's variable-length comment means it must be FOUND, not indexed — scan back from the
+ *  end over the maximum comment length (0xffff) plus the 22-byte fixed record. */
+const MAX_EOCD_SCAN = 0xffff + 22;
+
+/** Hard cap on an entry's uncompressed size, so a zip-bomb entry is refused rather than inflated. */
+export const MAX_ENTRY_BYTES = 32 * 1024 * 1024;
+
+/**
+ * Read every entry of a zip into a name → bytes map.
+ *
+ * Entries are read via the CENTRAL DIRECTORY (the authoritative index), and each entry's data
+ * offset is then re-derived from its own LOCAL header — the local header's name/extra lengths
+ * are what actually position the payload, and trusting the central directory's copy of them is
+ * the classic way to read the wrong bytes out of a crafted archive.
+ */
+export function readZipEntries(buf: Buffer): Map<string, Buffer> {
+  if (buf.length < 22) throw new ZipReadError(`not a zip archive: ${buf.length} byte(s) is shorter than the smallest possible one`);
+
+  // ── locate the EOCD ──────────────────────────────────────────────────────────────────────
+  let eocd = -1;
+  const from = Math.max(0, buf.length - MAX_EOCD_SCAN);
+  for (let i = buf.length - 22; i >= from; i--) {
+    if (buf.readUInt32LE(i) === EOCD_SIG) {
+      eocd = i;
+      break;
+    }
+  }
+  if (eocd < 0) throw new ZipReadError("not a zip archive: no end-of-central-directory record found");
+
+  const entryCount = buf.readUInt16LE(eocd + 10);
+  const cdSize = buf.readUInt32LE(eocd + 12);
+  const cdOffset = buf.readUInt32LE(eocd + 16);
+
+  // ZIP64 sentinels. Refuse loudly — a zip64 archive read as zip32 lands on garbage offsets, and
+  // "garbage offsets" is indistinguishable from "the entry is empty" once inflate fails open.
+  if (entryCount === 0xffff || cdSize === 0xffffffff || cdOffset === 0xffffffff) {
+    throw new ZipReadError("zip64 archive — this reader is deliberately zip32-only; refusing rather than reading the wrong offsets");
+  }
+  if (cdOffset + cdSize > buf.length) {
+    throw new ZipReadError(`truncated zip: the central directory claims to end at ${cdOffset + cdSize} but the archive is ${buf.length} byte(s)`);
+  }
+
+  const out = new Map<string, Buffer>();
+  let p = cdOffset;
+  for (let n = 0; n < entryCount; n++) {
+    if (p + 46 > buf.length || buf.readUInt32LE(p) !== CD_SIG) {
+      throw new ZipReadError(`malformed zip: expected a central-directory header for entry ${n + 1}/${entryCount} at offset ${p}`);
+    }
+    const method = buf.readUInt16LE(p + 10);
+    const compressedSize = buf.readUInt32LE(p + 20);
+    const uncompressedSize = buf.readUInt32LE(p + 24);
+    const nameLen = buf.readUInt16LE(p + 28);
+    const extraLen = buf.readUInt16LE(p + 30);
+    const commentLen = buf.readUInt16LE(p + 32);
+    const localOffset = buf.readUInt32LE(p + 42);
+    const name = buf.subarray(p + 46, p + 46 + nameLen).toString("utf8");
+    p += 46 + nameLen + extraLen + commentLen;
+
+    if (name.endsWith("/")) continue; // a directory entry carries no data
+
+    if (uncompressedSize > MAX_ENTRY_BYTES) {
+      throw new ZipReadError(`zip entry "${name}" declares ${uncompressedSize} uncompressed byte(s), over the ${MAX_ENTRY_BYTES}-byte cap`);
+    }
+    if (localOffset + 30 > buf.length || buf.readUInt32LE(localOffset) !== LOCAL_SIG) {
+      throw new ZipReadError(`malformed zip: entry "${name}" has no local file header at offset ${localOffset}`);
+    }
+    // Re-derive the data offset from the LOCAL header's own lengths, not the central directory's.
+    const localNameLen = buf.readUInt16LE(localOffset + 26);
+    const localExtraLen = buf.readUInt16LE(localOffset + 28);
+    const dataStart = localOffset + 30 + localNameLen + localExtraLen;
+    const dataEnd = dataStart + compressedSize;
+    if (dataEnd > buf.length) {
+      throw new ZipReadError(`truncated zip: entry "${name}" claims data through offset ${dataEnd} but the archive is ${buf.length} byte(s)`);
+    }
+    const raw = buf.subarray(dataStart, dataEnd);
+
+    let data: Buffer;
+    if (method === 0) {
+      data = Buffer.from(raw);
+    } else if (method === 8) {
+      try {
+        data = inflateRawSync(raw, { maxOutputLength: MAX_ENTRY_BYTES });
+      } catch (err) {
+        throw new ZipReadError(`zip entry "${name}" could not be inflated: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    } else {
+      throw new ZipReadError(`zip entry "${name}" uses compression method ${method}; only STORE (0) and DEFLATE (8) are supported`);
+    }
+    if (data.length !== uncompressedSize) {
+      // A size disagreement means we are not reading what the index describes. Refuse: a short
+      // read here would surface downstream as a truncated JSON document, i.e. as "no facts".
+      throw new ZipReadError(`zip entry "${name}" inflated to ${data.length} byte(s) but the index declares ${uncompressedSize}`);
+    }
+    out.set(name, data);
+  }
+  return out;
+}
+
+/**
+ * Read ONE named entry as UTF-8, matching on the entry's BASENAME.
+ *
+ * Basename-matching is deliberate: `actions/upload-artifact` computes the archive root from the
+ * least-common-ancestor of the uploaded paths, so the same workflow step yields `config-diff.json`
+ * for one path list and `tmp/config-diff.json` for another. Keying off the basename makes the
+ * reader insensitive to a change in the workflow's path list that has no bearing on the contents.
+ * Ambiguity (two entries with the same basename) is an error, not a first-wins guess.
+ */
+export function readZipTextEntry(buf: Buffer, basename: string): string {
+  const entries = readZipEntries(buf);
+  const hits = [...entries.keys()].filter((k) => k.split("/").pop() === basename);
+  if (hits.length === 0) {
+    throw new ZipReadError(`the archive has no entry named "${basename}" (it contains: ${[...entries.keys()].join(", ") || "nothing"})`);
+  }
+  if (hits.length > 1) {
+    throw new ZipReadError(`the archive has ${hits.length} entries named "${basename}" (${hits.join(", ")}) — refusing to guess which is the real one`);
+  }
+  return entries.get(hits[0])!.toString("utf8");
+}

package/agent/roles/role.ts

@@ -0,0 +1,228 @@
+// Role — a NAMED PRESET across the per-domain knobs a Domain already has (models,
+// statusVerbs, memory, sandbox) plus ONE new primitive: an `instructions`
+// prompt block injected per-turn into the system prompt of every surface whose domain
+// resolves to that role. A domain opts in with `role: "qa-engineer"`; anything the
+// domain sets explicitly WINS over the role's value, field by field — the same merge
+// doctrine as model routes (memory/domain.ts modelRouteFor).
+//
+//   defineRole({
+//     name: "qa-engineer",
+//     instructions: "You are the team's QA engineer. Hunt for edge cases…",
+//     persona: "Precise and a little skeptical.",       // the tone dimension
+//     statusVerbs: ["Probing", "Breaking"],             // same knobs a Domain has…
+//     models: { primary: { reasoning: "high" } },        // …preset once, reused
+//   })
+//   defineDomain({ name: "qa", reach: […], role: "qa-engineer" })
+//
+// PERSONA is not a separate concept: it is the tone/voice dimension of a role, so a
+// voice-only role (pirate, butler) is just a Role with `persona` and nothing else.
+//
+// TWO RESOLUTION MODES, deliberately:
+//   - `memory` / `sandbox` are SINGLE-VALUED knobs → overlaid onto the domain ONCE
+//     at config load (applyRoleDefaults). Downstream — the memory resolver, spend,
+//     control — sees a plain Domain and runs the EXACT same code path as if the
+//     deployer wrote the field on the domain directly. A role presets no access knob
+//     at all: capability comes only from a binding in agent/access/bundles.ts, which
+//     names a scope rather than being named by one. A role is sugar, never a grant.
+//   - `statusVerbs` / `models` are LAYERED knobs → the role joins the existing merge
+//     as its own rung (framework ← org ← ROLE ← domain; memory/domain.ts), so a
+//     domain can still EXTEND its role's verbs rather than clobber them.
+//   - `instructions` / `persona` stay on the Role and are rendered per-turn by the
+//     dynamic instructions resolver (instructions/access.ts) — prompt text, not a
+//     Domain knob.
+//
+// FAILURE POSTURE: a typo'd `role:` must be impossible to ship silently —
+// applyRoleDefaults throws at config load (fail loud, like assertDomainsValid). At
+// RUNTIME everything here is cosmetic/tuning, so resolution is fail-open: an unknown
+// role, a missing config, a broken binding → no role, never a dead turn.
+//
+// DESIGN-FOR (multi-bot future, item 27): a Role knows nothing about domains — the
+// domain references the role by name, never the reverse — so the same registry can
+// later be bound to a bot IDENTITY (one deployment, several named teammates) without
+// reshaping the type.
+
+import {
+  criteriaDomain,
+  domainForChannel,
+  type Domain,
+  type ModelRoutes,
+  type SandboxPreset,
+} from "../memory/domain.js";
+import { domainKeyOf, type Partition } from "../memory/partition.js";
+import type { SurfaceBinding } from "../identity/binding.js";
+
+export interface Role {
+  /**
+   * Stable id, referenced by `Domain.role`.
+   *
+   * ⚠️ IMMUTABLE ONCE REFERENCED (OPE-218). Renaming it breaks every `role:` that points
+   * here — `applyRoleDefaults` throws at config load, so this one fails LOUD rather than
+   * silently (unlike a domain name, which is persisted into rows). Still an identifier,
+   * not a label: change {@link Role.title} for anything a human reads.
+   */
+  readonly name: string;
+  /** Optional human-facing display label. Cosmetic only — nothing resolves on it. Absent → `name`. */
+  readonly title?: string;
+  /**
+   * The prompt block injected per-turn for surfaces whose domain resolves to this
+   * role — WHAT the agent is acting as (responsibilities, priorities, how to work).
+   * Markdown; keep it tight — it rides every turn's system prompt.
+   */
+  readonly instructions?: string;
+  /**
+   * The TONE dimension — how the agent should sound (voice, register, quirks).
+   * Injected alongside `instructions`; a voice-only fun role sets just this.
+   */
+  readonly persona?: string;
+  /** Working-status vocabulary rung (see Domain.statusVerbs; merged framework ← org ← role ← domain). */
+  readonly statusVerbs?: readonly string[];
+  /** How this role's verbs combine with what it inherits. Default "extend". */
+  readonly statusVerbsMode?: "extend" | "replace";
+  /** Model-route rung, merged field-by-field beneath the domain's own `models`. */
+  readonly models?: ModelRoutes;
+  /** Memory default (silo name or list) — used iff the domain doesn't set `memory`. */
+  readonly memory?: string | readonly string[];
+  /** Sandbox-size default — used iff the domain doesn't set its own `sandbox`. */
+  readonly sandbox?: SandboxPreset;
+}
+
+/** Identity-with-types helper (Eve's define* convention; returns unchanged). */
+export function defineRole(role: Role): Role {
+  return role;
+}
+
+/** The role a name refers to, or undefined (runtime lookups are fail-open). */
+function roleByName(name: string | undefined, roles: readonly Role[]): Role | undefined {
+  if (!name) return undefined;
+  return roles.find((r) => r.name === name);
+}
+
+/**
+ * Validate the role set at config load (fail loud): non-empty unique names, and at
+ * least one facet per role (a role that presets nothing is a config mistake — likely
+ * a half-written entry).
+ */
+export function assertRolesValid(roles: readonly Role[]): void {
+  const bad: string[] = [];
+  const seen = new Set<string>();
+  for (const r of roles) {
+    const name = typeof r.name === "string" ? r.name.trim() : "";
+    if (name.length === 0) bad.push(`  a role has no name — every role needs a stable name`);
+    else if (seen.has(name)) bad.push(`  role "${name}" is defined twice — names must be unique`);
+    else seen.add(name);
+    const hasFacet =
+      r.instructions !== undefined ||
+      r.persona !== undefined ||
+      r.statusVerbs !== undefined ||
+      r.models !== undefined ||
+      r.memory !== undefined ||
+      r.sandbox !== undefined;
+    if (!hasFacet) bad.push(`  role "${name || "(unnamed)"}" presets nothing — give it instructions/persona or at least one knob`);
+  }
+  if (bad.length > 0) {
+    throw new Error("open-everywhere: invalid role(s):\n" + bad.join("\n") + "\n(roles/role.ts / docs/capabilities/roles.md)");
+  }
+}
+
+/**
+ * Overlay each domain's role DEFAULTS for the single-valued knobs (`memory`,
+ * `sandbox`) — the domain's own field wins, field by field. Run ONCE at config load,
+ * so every downstream consumer (memory resolver, spend, control) sees a plain Domain
+ * and resolves through the unchanged code path. Neither knob touches access: a role
+ * has no capability field to overlay, so it cannot open a route at all.
+ *
+ * THROWS on an unknown role name (fail loud at load): a typo'd `role:` silently
+ * presetting nothing is exactly the bug class this kills. The layered knobs
+ * (statusVerbs/models) are NOT flattened here — they merge at resolution time so the
+ * domain can extend rather than replace (memory/domain.ts).
+ */
+export function applyRoleDefaults(domains: readonly Domain[], roles: readonly Role[]): Domain[] {
+  const bad: string[] = [];
+  const out = domains.map((d) => {
+    if (!d.role) return d;
+    const role = roleByName(d.role, roles);
+    if (!role) {
+      bad.push(`  domain "${d.name}" references unknown role "${d.role}" — define it with defineRole({ name: "${d.role}", … }) or fix the name`);
+      return d;
+    }
+    return {
+      ...d,
+      memory: d.memory ?? role.memory,
+      sandbox: d.sandbox ?? role.sandbox,
+    };
+  });
+  if (bad.length > 0) {
+    throw new Error("open-everywhere: invalid role reference(s):\n" + bad.join("\n") + "\n(roles/role.ts / docs/capabilities/roles.md)");
+  }
+  return out;
+}
+
+/**
+ * The domain whose ROLE governs a session — the same single-hop chain the rest of the
+ * system resolves by (memory/resolve.ts, skills/domain-skills.ts), at DOMAIN grain
+ * (domainKeyOf: a Discord thread asks its parent channel; item 22):
+ *   mpim                → none (execution-only surfaces stay role-less)
+ *   dm                  → the `dm` (internal partner) / `public` (external) pseudo-domain
+ *   channel, external   → the `public` pseudo-domain (fail-closed, same as memory)
+ *   channel in a domain → that domain
+ *   channel, unassigned → the `org` pseudo-domain
+ * PURE — testable with fabricated binding/partition.
+ */
+export function roleScopeDomain(binding: SurfaceBinding, partition: Partition, domains: readonly Domain[]): Domain | undefined {
+  if (binding.mode === "mpim") return undefined;
+  if (binding.mode === "dm") return criteriaDomain(binding.trust === "internal" ? "dm" : "public", domains);
+  if (binding.trust === "external") return criteriaDomain("public", domains);
+  return domainForChannel(domainKeyOf(partition), domains) ?? criteriaDomain("org", domains);
+}
+
+/**
+ * The EFFECTIVE role for a session's prompt/sandbox: the scope domain's role; an
+ * explicit channel domain WITHOUT its own role falls through to the `org`
+ * pseudo-domain's role (a role is a tuning default you usually want workspace-wide —
+ * same fall-through doctrine as `models`, unlike the deliberate non-inheritance of
+ * `nameDropWake`). The shared-by-trust scopes (dm/public) do NOT fall through to org:
+ * an org-wide persona must not leak onto external or personal surfaces uninvited.
+ * Unknown names resolve to undefined (fail-open at runtime; load already failed loud).
+ */
+export function effectiveRoleFor(
+  binding: SurfaceBinding,
+  partition: Partition,
+  domains: readonly Domain[],
+  roles: readonly Role[],
+): Role | undefined {
+  const scope = roleScopeDomain(binding, partition, domains);
+  if (!scope) return undefined;
+  const own = roleByName(scope.role, roles);
+  if (own) return own;
+  // Only an EXPLICIT channel domain inherits the org role; dm/public/org scopes stop here.
+  if (scope.match !== undefined) return undefined;
+  return roleByName(criteriaDomain("org", domains)?.role, roles);
+}
+
+/**
+ * The sandbox-size preset for a session, if any — read from the load-time-resolved
+ * domain (applyRoleDefaults already overlaid the role's default), same scope chain as
+ * the prompt block (explicit domain falls through to org's preset; dm/public don't).
+ * Consumed by the app's sandbox `onSession` hook; fail-open there (any error →
+ * default size, never a blocked turn).
+ */
+export function sandboxPresetFor(binding: SurfaceBinding, partition: Partition, domains: readonly Domain[]): SandboxPreset | undefined {
+  const scope = roleScopeDomain(binding, partition, domains);
+  if (scope?.sandbox) return scope.sandbox;
+  if (scope && scope.match === undefined) return criteriaDomain("org", domains)?.sandbox;
+  return undefined;
+}
+
+/**
+ * Render a role's per-turn prompt block. Instructions first (what to do), persona
+ * after (how to sound); either may stand alone. Empty string when the role carries
+ * neither — a knob-only role injects nothing.
+ */
+export function renderRoleInstructions(role: Role): string {
+  const parts: string[] = [];
+  if (role.instructions && role.instructions.trim().length > 0) parts.push(role.instructions.trim());
+  if (role.persona && role.persona.trim().length > 0) parts.push(`Voice: ${role.persona.trim()}`);
+  if (parts.length === 0) return "";
+  return `## Your role: ${role.name}\n` + parts.join("\n\n");
+}
+

package/agent/routines/bound.ts

@@ -0,0 +1,262 @@
+// THE JOB CEILING (OPE-248) — pure, deterministic, unit-tested (scripts/routine-bound-test.ts).
+// The impure half (persist the stop, write the forensic row, post the notice) is
+// routines/outcome-fold.ts retireExhaustedRoutine, exactly the lifecycle.ts / outcome-fold.ts split
+// the three-strike self-disable already uses.
+//
+// ── WHAT THIS CLOSES ────────────────────────────────────────────────────────────────────────────
+// A durable job (`sessionMode:"job"`) runs until its OWN session calls `complete_job`. NOTHING else
+// bounds it. Every other stop in the tree counts FAILURE:
+//
+//   • `consecutiveFailures` resets to 0 on any non-failed settlement (lifecycle.ts applyOutcome:51);
+//   • OPE-177's `report_run_failed` only reaches a run that KNOWS its work didn't work;
+//   • OPE-146's delivery-rejected fold only reaches a fire that could not be DELIVERED.
+//
+// A monitor that succeeds forever — polls, finds nothing, replies, repeats — is a correct run every
+// single time, so all three are structurally blind to it. It runs until somebody notices.
+//
+// ── WHY NOT A COST / TOKEN THRESHOLD ────────────────────────────────────────────────────────────
+// spend/checkpoint.ts is the obvious reach and it cannot do this. It gates CONSEQUENTIAL tools at
+// their execute() top (`requireSessionContinuation`), and its own card says so verbatim: "reads and
+// replies are unaffected either way". Reads and replies are the ENTIRE surface area of a polling
+// monitor, so a cheap poll never crosses it at any threshold — and it is opt-in, uncapped by default,
+// besides. The bound therefore lives on the ROUTINE and is denominated in fires and wall-clock, which
+// are the two things a monitor unavoidably consumes.
+//
+// ⚠️ THE CHECKPOINT IS STILL NOT IRRELEVANT HERE, and reading the paragraph above as "the checkpoint
+// has nothing to do with the ceiling" is what OPE-253 had to fix. A checkpoint cannot STOP a monitor,
+// but it can STALL one indefinitely — and a stalled job kept burning this ceiling while doing nothing,
+// then retired under a notice that said nothing had failed. So the verdict below carries a THIRD
+// dimension, `stalled`, evaluated first. routines/stall.ts holds that whole argument.
+//
+// ── WHERE THE NUMBERS COME FROM ─────────────────────────────────────────────────────────────────
+// An unjustified constant defended by a causal story nobody measured is the failure class this
+// repo has been burned by most, so each one below is DERIVED from something already in the tree,
+// and each is overridable by env (the `approvalTtlHours` fail-soft convention).
+//
+//   DEFAULT_JOB_MAX_DAYS = 7  — the deadline.
+//     Anchored on routines/fire-audit.ts FORENSIC_WINDOW_MS, which is 7 days and is the window
+//     EVERY routine-history read in the product uses (`list_routines`' fires7d/tokens7d, the
+//     operator CLI, the MCP view). Past it, a job's own run history has aged out of every reader
+//     OE ships — so the evidence a human needs to decide "re-arm this or not?" no longer exists.
+//     A ceiling that trips after its own evidence is gone is not a ceiling anybody can act on.
+//     It also has to be strictly INSIDE one billing period: the hard cap (spend/spend.ts) is a
+//     per-MONTH budget, so a job bound longer than a month would leave the cap as the only thing
+//     that ever stops a runaway — and the cap stops the whole SCOPE, not the runaway. 7 days is
+//     the human review period that sits comfortably inside that, spanning a full working week.
+//
+//   MIN_FIRES_BEFORE_DEADLINE = MAX_CONSECUTIVE_FAILURES (3) — the deadline's cadence floor.
+//     A flat 7 days would give a WEEKLY job exactly one fire, i.e. silently turn it into a `once`.
+//     So the deadline is stretched to at least this many periods. Three, because this codebase
+//     already holds that three tries is the number before you may conclude anything about a
+//     routine (lifecycle.ts MAX_CONSECUTIVE_FAILURES) — reusing it keeps ONE answer to "how many
+//     attempts is a fair sample" instead of inventing a second.
+//
+//   DEFAULT_JOB_MAX_FIRES = 200 — the runaway backstop.
+//     Derived from the deadline, not chosen. It must NOT bind a reasonably-configured job before
+//     the deadline does, and the fastest cadence anyone would call reasonable for an unattended
+//     monitor is hourly: 24 × 7 = 168 fires in the default week. 200 is the smallest round number
+//     strictly above that, so every cadence at or slower than hourly retires on its DEADLINE (the
+//     dimension that is meaningful there) and only faster ones retire on the COUNT. At the
+//     dispatcher floor (DISPATCH_TICK_MINUTES = 10 ⇒ 144 fires/day) 200 fires is ~33 hours, so the
+//     fastest job OE can physically run is bounded in under a day and a half rather than a week.
+//
+// ── THE CROSSOVER ───────────────────────────────────────────────────────────────────────────────
+//   every 10 min  → 200 fires in ~33h   → COUNT trips
+//   hourly        → 168 fires in 7d     → DEADLINE trips (at 168, just under the cap)
+//   daily         → 7 fires in 7d       → DEADLINE trips
+//   weekly        → deadline stretched to 21d, 3 fires → DEADLINE trips
+//
+// ── SCOPE ───────────────────────────────────────────────────────────────────────────────────────
+// Bounds are minted for DURABLE JOBS only. A plain `cron`/`interval` routine is SUPPOSED to run
+// forever — a daily digest that retired itself after a week would be a defect, not a fence. The
+// field is generic on the row so widening it later is a changed default, not a new column.
+// `once` needs none (it retires itself), and a job can never be `event`-triggered — create_routine
+// refuses that pairing outright — so the clock dispatcher is the COMPLETE evaluation site, not
+// merely the main one.
+
+import { MAX_CONSECUTIVE_FAILURES } from "./lifecycle.js";
+import { computeNextRun } from "./schedule.js";
+import { stallExhausted, stallReason } from "./stall.js";
+import type { Routine, RoutineBound, RoutineTrigger } from "./routine.js";
+import { SETTINGS, getSettings } from "../settings/settings.js";
+
+/** Default wall-clock grace for a durable job, in days — see the header for the derivation.
+ *  IS the `routines.jobMaxDays` shipped default (override: `routines.jobMaxDays`). */
+export const DEFAULT_JOB_MAX_DAYS = SETTINGS.routines.jobMaxDays.shipped;
+
+/** Default cap on fires under one bound — see the header. IS the `routines.jobMaxFires` shipped
+ *  default (override: `routines.jobMaxFires`). */
+export const DEFAULT_JOB_MAX_FIRES = SETTINGS.routines.jobMaxFires.shipped;
+
+/** The deadline is stretched so a slow cadence still gets a fair sample of runs. Reuses the
+ *  three-strike constant rather than inventing a second answer to "how many attempts is fair". */
+export const MIN_FIRES_BEFORE_DEADLINE = MAX_CONSECUTIVE_FAILURES;
+
+const DAY_MS = 24 * 60 * 60_000;
+
+/** Wall-clock grace for a fresh job bound, in days. */
+export function jobBoundMaxDays(): number {
+  return getSettings().routines.jobMaxDays;
+}
+
+/** Fire cap for a fresh job bound. */
+export function jobBoundMaxFires(): number {
+  return getSettings().routines.jobMaxFires;
+}
+
+/**
+ * The trigger's period in ms, or undefined when it has none / can't be derived.
+ *
+ * Derived by asking {@link computeNextRun} for the next TWO instants and differencing them, rather
+ * than by reading `everyMinutes` and re-implementing cron — so a cron job's cadence comes from the
+ * same tested math the dispatcher schedules on, and there is no second parser to drift. `once` and
+ * `event` have no period by construction (computeNextRun returns null), which is the correct answer
+ * for both: a one-shot retires itself, and a job can never be event-triggered.
+ */
+export function triggerPeriodMs(trigger: RoutineTrigger, from: Date): number | undefined {
+  const first = computeNextRun(trigger, from);
+  if (!first) return undefined;
+  const second = computeNextRun(trigger, first);
+  if (!second) return undefined;
+  const period = second.getTime() - first.getTime();
+  return period > 0 ? period : undefined;
+}
+
+/**
+ * Mint the bound a durable job is armed with. HOST-SIDE ONLY — called from the arm click
+ * (approvals/routine-create.ts) and the re-arm click (approvals/routine-lifecycle.ts), never from a
+ * tool input, so no model can name its own ceiling.
+ *
+ * The deadline is the flat default, STRETCHED to {@link MIN_FIRES_BEFORE_DEADLINE} periods when the
+ * cadence is slower than that — otherwise a weekly job would get exactly one fire and be a `once`
+ * wearing a job's clothes. A trigger with no derivable period (a cron that never matches again)
+ * gets the flat default: refusing to mint a bound there would leave the unbounded hole open in
+ * exactly the case least likely to be noticed.
+ */
+export function mintJobBound(trigger: RoutineTrigger, from: Date): RoutineBound {
+  const flat = jobBoundMaxDays() * DAY_MS;
+  const period = triggerPeriodMs(trigger, from);
+  const spanMs = Math.max(flat, period !== undefined ? period * MIN_FIRES_BEFORE_DEADLINE : 0);
+  return { until: new Date(from.getTime() + spanMs).toISOString(), maxFires: jobBoundMaxFires() };
+}
+
+/**
+ * The ceiling in RELATIVE terms, for the arming card — "after up to 200 runs or 7 days, whichever
+ * comes first". Relative rather than absolute ON PURPOSE: the card is frozen at PROPOSE time and the
+ * bound is minted at CLICK time (the same freshness split `nextRunAt` already takes in
+ * approvals/routine-create.ts), so an absolute date on the card would be falsified by any gap
+ * between the two. The SPAN is what the human is agreeing to, and the span does not move.
+ */
+export function describeBoundPolicy(trigger: RoutineTrigger, from: Date): string {
+  const bound = mintJobBound(trigger, from);
+  const days = Math.round((Date.parse(bound.until ?? "") - from.getTime()) / DAY_MS);
+  return `stops itself after ${bound.maxFires} runs or ${days} day${days === 1 ? "" : "s"}, whichever comes first`;
+}
+
+/**
+ * A stored bound plus progress, for `list_routines` — "125/200 runs, or by 2026-08-05". Null for an
+ * unbounded routine, so the list view says nothing at all about ceilings for the rows that have
+ * none. A ceiling nobody can enumerate from the room is not governable from the room, which is the
+ * same argument the standing-rules and permissions fields on that view already rest on.
+ */
+export function describeBound(r: Pick<Routine, "bound" | "fireCount">): string | null {
+  const bound = r.bound;
+  if (!bound) return null;
+  const parts: string[] = [];
+  if (bound.maxFires !== undefined) parts.push(`${r.fireCount ?? 0}/${bound.maxFires} runs`);
+  if (bound.until !== undefined) parts.push(`until ${bound.until}`);
+  return parts.length > 0 ? parts.join(", or ") : null;
+}
+
+/** Which dimension stopped it — the notice and the audit row both name it, because "it ran out of
+ *  time", "it ran out of tries" and "it was never allowed to work" lead a human to three different
+ *  next moves. `stalled` is OPE-253's; see routines/stall.ts. */
+export type BoundDimension = "fires" | "deadline" | "stalled";
+
+export type BoundVerdict =
+  | { readonly exhausted: false }
+  | {
+      readonly exhausted: true;
+      readonly dimension: BoundDimension;
+      /** HOST-COMPOSED one-liner for `disabledReason` — see disable-notice.ts on why no model text
+       *  may ride this path. */
+      readonly reason: string;
+    };
+
+/**
+ * Has this routine exhausted its bound at `now`? PURE. An absent bound, an absent dimension, and a
+ * bound with neither component set all read as "not exhausted" — a routine with no ceiling is
+ * unbounded, which is what every pre-OPE-248 row and every plain routine is.
+ *
+ * FIRES ARE CHECKED FIRST because the count is the dimension that can be stated exactly ("it ran
+ * 200 times"), whereas a deadline reads as "it has been a week" — the same most-specific-first
+ * ordering spend/checkpoint.ts checkCheckpoint uses.
+ *
+ * The comparison is `>=` on both, so a bound of `maxFires: 1` means one fire happens and then the
+ * routine retires — never zero. The dispatcher increments the counter as part of the fire it is
+ * about to make, so a row read here has already been counted for every fire it actually got.
+ */
+export function checkBound(
+  r: Pick<Routine, "bound" | "fireCount" | "stalledFires">,
+  now: Date,
+): BoundVerdict {
+  const bound = r.bound;
+  if (!bound) return { exhausted: false };
+
+  // THE STALL (OPE-253) IS CHECKED FIRST, and that INVERTS the most-specific-first ordering the two
+  // dimensions below use — on purpose, because specificity is not the ranking criterion here,
+  // ACTIONABILITY is. A ceiling stop asks the operator for one thing (re-arm); a stall stop asks for
+  // that PLUS the thing that has to happen before it (answer the checkpoint card, or raise the
+  // checkpoint for this scope). A job can trip both — three stalled fires while also sitting at 200
+  // fires — and reporting "it ran 200 times" there sends the operator to re-arm a job that will stall
+  // again on its very next fire, which is "enable didn't work" in the one case we can see coming.
+  //
+  // It lives INSIDE the `bound` guard, so stall-reaping is keyed on carrying a ceiling — the same key
+  // `fireCount` is written under (schedules/dispatch.ts), which today is exactly the durable jobs. A
+  // plain routine still ACCUMULATES the counter (it is visible on the row and in `list_routines`), it
+  // just is not retired by it: its checkpoint crossing dies with its per-fire session anyway, and a
+  // daily digest is SUPPOSED to run forever. See routines/stall.ts for the whole asymmetry.
+  if (stallExhausted(r)) {
+    return { exhausted: true, dimension: "stalled", reason: stallReason(r) };
+  }
+
+  const fires = Number.isInteger(r.fireCount) && (r.fireCount as number) > 0 ? (r.fireCount as number) : 0;
+  if (bound.maxFires !== undefined && fires >= bound.maxFires) {
+    return {
+      exhausted: true,
+      dimension: "fires",
+      reason: `it ran ${fires} time${fires === 1 ? "" : "s"} without finishing (its ceiling is ${bound.maxFires} run${bound.maxFires === 1 ? "" : "s"})`,
+    };
+  }
+
+  if (bound.until !== undefined) {
+    const until = Date.parse(bound.until);
+    // A GARBAGE deadline is ignored rather than treated as expired: a hand-edited or migrated row
+    // must not be able to retire a live job by being unparseable. The fire cap above still binds.
+    if (Number.isFinite(until) && now.getTime() >= until) {
+      return {
+        exhausted: true,
+        dimension: "deadline",
+        reason: `it has been running since before ${bound.until} without finishing (its ceiling is that date)`,
+      };
+    }
+  }
+
+  return { exhausted: false };
+}
+
+/**
+ * The patch that retires an exhausted routine. Terminal in the same way the three-strike
+ * self-disable is — `status:"disabled"`, `nextRunAt:null`, kept for audit/list visibility, never
+ * deleted — and deliberately NOT `"done"`: `done` means the job declared its objective FINISHED
+ * (`complete_job`), and a job that hit a ceiling is precisely one that did not. Conflating them
+ * would make `enable_routine`'s "a completed job is terminal" refusal fire on the one case where
+ * re-arming is the correct move.
+ */
+export function boundExhaustedPatch(verdict: Extract<BoundVerdict, { exhausted: true }>): Partial<Routine> {
+  // The PREFIX names the class of stop, because `disabledReason` is what `list_routines`, the operator
+  // CLI, the `routine.disabled` row and the re-arm card all show, and "stopped at its ceiling" would
+  // be an actively wrong summary of a stall — the job never got to spend its ceiling.
+  const prefix = verdict.dimension === "stalled" ? "stopped because it was blocked" : "stopped at its ceiling";
+  return { status: "disabled", disabledReason: `${prefix} — ${verdict.reason}`, nextRunAt: null };
+}