@open-everywhere/core 0.1.0

package/agent/routines/outcome-fold.ts

@@ -0,0 +1,302 @@
+// FOLDING A RUN OUTCOME BACK ONTO THE ROUTINE — the one place that reads the routine,
+// settles the outcome, persists the fold, and writes the forensic rows. Extracted in
+// OPE-146 because there are now TWO ingresses for the same fact and they must not drift:
+//
+//   1. hooks/routine-outcome.ts — the fire's own TURN ended (eve turn.completed/turn.failed).
+//      Carries a session id, so it writes the `routine.fire` join row. It was `session.completed`/
+//      `session.failed` until OPE-611, which measured that eve emits `session.completed` for no
+//      session on this build. That hook latches per fire, so one fire reaches this function once
+//      however many turns it runs for.
+//   2. schedules/dispatch.ts — the fire's DELIVERY was REJECTED. No session ever started,
+//      so there is no session id and no `routine.fire` row (the dispatcher writes
+//      `routine.fire_lost` instead, which is the same fact told from the only end that
+//      knows it).
+//
+// THE DEFECT THIS CLOSES (audit §S3). Before OPE-146 the delivery-failure path was a bare
+// `.catch(log)` — later a `.catch(auditRoutineFireLost)`. Either way NO session started, so
+// the outcome hook never ran, so `consecutiveFailures` stayed 0 FOREVER. The three-strike
+// self-disable therefore only ever counted eve session crashes: a routine on an archived
+// channel, or one the bot was kicked from, retried on every tick indefinitely, consuming a
+// per-tick concurrency slot and leaving nothing but a log line. A rejected delivery is a
+// FAILED RUN by any reading — this makes the counter see it.
+//
+// It is also what makes `docs/capabilities/proactivity-and-routines.md`'s "removing it from
+// the surface ends it" TRUE, by the only mechanism the deployment actually has. There is no
+// membership enumerator anywhere in the tree (the never-wired `gcOrphaned` that used to sit
+// in lifecycle.ts asserted one and was deleted in the same ticket) — but a surface the agent
+// has been removed from rejects the delivery, and three rejections now disable the routine.
+//
+// Everything here is best-effort by CONTRACT for the audit legs (fire-audit.ts swallows its
+// own failures) but NOT for the store: a store error propagates so the caller can log it
+// with its own context, exactly as the hook did before the extraction.
+
+import { applyOutcome, settleOutcome } from "./lifecycle.js";
+import { boundExhaustedPatch, type BoundVerdict } from "./bound.js";
+import { auditRoutineDisabled, auditRoutineFire, auditRoutineStalled } from "./fire-audit.js";
+import { announceBoundExhausted, announceSelfDisable } from "./disable-notice.js";
+import { stallFoldPatch } from "./stall.js";
+import { getRoutine, updateRoutine } from "./store.js";
+import type { Routine, RunOutcome } from "./routine.js";
+
+/** The routine link a fold is keyed on — exactly what `routineMarker` yields. */
+export interface RoutineOutcomeMarker {
+  readonly id: string;
+  readonly surfaceKey: string;
+  readonly org: string;
+}
+
+/** What the fold did, for the caller's log line. `folded: false` means the routine was gone
+ *  (cancelled between the fire and the outcome) — a no-op, not an error. */
+export interface RoutineOutcomeFold {
+  readonly folded: boolean;
+  readonly outcome?: RunOutcome;
+  readonly consecutiveFailures?: number;
+  /** True only on the DISABLE TRANSITION — the fold that flipped it, never a later one. */
+  readonly disabled?: boolean;
+}
+
+/**
+ * Fold one run's outcome onto its routine and persist it, writing the forensic rows.
+ *
+ * `sessionId` present ⇒ a real session ran ⇒ the `routine.fire` join row is written (it is
+ * the ONLY row that can carry both the routine id and the session id, which is what makes
+ * `GET /control/v1/session/:id/transcript` reachable from a routine id). Absent ⇒ no join
+ * row: there is genuinely no session, and the caller has already recorded the loss.
+ *
+ * `routine.disabled` is written on the TRANSITION only, from whichever ingress caused it —
+ * so a self-disable driven by repeated DELIVERY failures is as visible as one driven by
+ * repeated session failures.
+ */
+export async function foldRoutineOutcome(opts: {
+  readonly marker: RoutineOutcomeMarker;
+  readonly sessionOutcome: "ok" | "failed";
+  readonly at?: Date;
+  readonly sessionId?: string;
+  /** OPE-147: was this fire asked for OFF-SCHEDULE by a human (`run_routine_now`)? Read off the
+   *  host-set {@link ROUTINE_MARKER.manual} stamp by the session-end hook — the only ingress that
+   *  can know it, since the delivery-rejected path has no session to read attributes from. Rides
+   *  onto the `routine.fire` join row so "why did this run at 14:07 when it is a 03:00 cron?" is
+   *  answerable from the audit trail instead of from someone's memory. */
+  readonly manual?: boolean;
+  /**
+   * OPE-625: this is the SECOND settlement of one fire — a `report_run_failed` declared by a later
+   * turn of a fire that already folded non-failed. Only hooks/routine-outcome.ts sets it, and only
+   * once per fire.
+   *
+   * It changes two things, and nothing else:
+   *   • 🔴 THE STALL ARITHMETIC IS SKIPPED. `stallFoldPatch` counts a stall whenever `lastStallAt`
+   *     is set, and nothing clears that field until the NEXT fire (schedules/dispatch.ts). So the
+   *     first fold already counted this fire's stall and a second call would count it again,
+   *     retiring a job at its stall ceiling for one blocked fire.
+   *   • the `routine.fire` row is STAMPED `late`. One fire then leaves two rows, and a reader has to
+   *     be able to tell that from two fires — otherwise "how many times did this run?" is wrong by
+   *     one for every late declaration.
+   */
+  readonly late?: boolean;
+}): Promise<RoutineOutcomeFold> {
+  const { marker, sessionOutcome } = opts;
+  const at = opts.at ?? new Date();
+  const routine = await getRoutine(marker.org, marker.surfaceKey, marker.id);
+  if (!routine) return { folded: false }; // cancelled meanwhile
+
+  // A run can have recorded its OWN verdict mid-turn, and a clean session end must keep it rather
+  // than claim "ok": a watch that saw no change recorded `skipped` (record_watch_state), and since
+  // OPE-177 a turn whose work did not work recorded `failed` + a reason (report_run_failed). The
+  // dispatcher clears BOTH fields at fire, so anything present here was written during THIS run.
+  const settled = settleOutcome(sessionOutcome, routine.lastOutcome);
+  const updated = applyOutcome(routine, settled, at);
+  await updateRoutine(marker.org, marker.surfaceKey, marker.id, {
+    lastRunAt: updated.lastRunAt,
+    lastOutcome: updated.lastOutcome,
+    // Cleared by applyOutcome on any non-`failed` settlement — patched explicitly so the store
+    // actually drops it, rather than leaving a previous run's reason on the row.
+    lastFailureReason: updated.lastFailureReason,
+    consecutiveFailures: updated.consecutiveFailures,
+    // OPE-506: the streak's own start instant — cleared alongside consecutiveFailures on any
+    // non-failed settlement (applyOutcome), carried forward on every failure in between. Without
+    // patching it explicitly here it is computed and then silently discarded, and every fold after
+    // the first reads it back as absent — which applyOutcome's own back-compat fallback then reads
+    // as an ALREADY-SPANNED legacy streak, disabling on the bare 3-strike count regardless of how
+    // close together the failures actually were. Measured: this exact defect shipped in the first
+    // draft of this ticket and was caught by routine-reliability-test.ts §3 going red.
+    firstFailureAt: updated.firstFailureAt,
+    status: updated.status,
+    disabledReason: updated.disabledReason,
+    nextRunAt: updated.nextRunAt,
+    // THE STALL ARITHMETIC (OPE-253) — folded in the SAME write as the outcome, because it is the same
+    // question about the same fire ("what happened on this run?") and two writes could disagree.
+    //
+    // It rides HERE rather than in applyOutcome because a stall is NOT an outcome: the fire settles
+    // `ok` (a soft-blocked tool is a recoverable tool-error the model works around), and threading it
+    // through the outcome would either make a blocked fire read as failed — three-strike-disabling a
+    // job whose only problem is an unanswered card — or need a fourth RunOutcome that nothing else
+    // means. `{}` for a routine that never stalled, so its patch is byte-identical to before.
+    //
+    // OPE-625: a LATE fold skips it entirely — see the `late` option's own note. This fire's stall
+    // was counted by its first fold, and `lastStallAt` is still on the row because only the next
+    // fire clears it.
+    ...(opts.late === true ? {} : stallFoldPatch(routine)),
+  });
+
+  // The DECLARED reason (OPE-177), for the forensic rows below. Read off the settled routine so it
+  // is present exactly when the run actually settled as failed. It goes on the audit rows and
+  // NOWHERE else: `disabledReason` stays host-composed because announceSelfDisable posts it into
+  // the room past the silent-routine delivery gate (routines/disable-notice.ts), and model text has
+  // no business riding that path.
+  const declared = updated.lastFailureReason;
+
+  // Written AFTER the store update so the rows' counters match what a reader will then see
+  // on the row itself. fire-audit.ts swallows its own failures: an audit hiccup must never
+  // undo the fold above.
+  if (opts.sessionId !== undefined) {
+    await auditRoutineFire(routine, opts.sessionId, settled, {
+      consecutiveFailures: updated.consecutiveFailures,
+      ...(updated.disabledReason ? { disabledReason: updated.disabledReason } : {}),
+      // Positive-only (OPE-147): absent means "the clock", which is what every row before this
+      // ticket meant, so no reader has to be taught a new default.
+      ...(opts.manual === true ? { manual: true } : {}),
+      // OPE-177: absent means "nobody declared anything" — either the run was fine, or it failed at
+      // the session level, which is a different (and already legible) story. Present means the turn
+      // itself said the work did not happen, in its own words. This is the field that answers "why
+      // is this thing about to disable itself" from the fire rows, one run at a time.
+      ...(declared !== undefined ? { declaredFailure: declared } : {}),
+      // OPE-625: positive-only, like `manual`. Absent means "this fire's own settlement", which is
+      // what every row before this ticket meant. Present means a SECOND row for a fire whose first
+      // row already exists — so a reader counting fires subtracts it, and a reader asking "why did
+      // this routine disable after a clean run?" reads it as the answer.
+      ...(opts.late === true ? { late: true } : {}),
+    });
+  }
+  // OPE-506: a `once` routine goes terminal on EVERY outcome now (applyOutcome), not only on
+  // failure — a successful one-shot completing on schedule is not a self-disable, and must not
+  // post the 🛑 "disabled after N consecutive failures" notice or write a routine.disabled row
+  // that would misreport a clean run as a breakage. `settled === "failed"` is what a genuine
+  // self-disable (the recurring three-strike, or a once's first failure) always is, and what an
+  // ordinary once completion never is — so it is the second half of the transition test, not a
+  // narrowing of it: every pre-existing disable this fold could produce already satisfied it.
+  const disabled = updated.status === "disabled" && routine.status !== "disabled" && settled === "failed";
+  if (disabled) {
+    await auditRoutineDisabled(
+      routine,
+      updated.disabledReason ?? "auto-disabled",
+      updated.consecutiveFailures,
+      opts.sessionId,
+      // OPE-177: the LAST run's declared reason on the row that says it stopped. `reason` above only
+      // ever says "it hit the threshold"; this is the nearest thing to a diagnosis the mechanism can
+      // honestly produce, and it is the field an operator reads before deciding to `enable_routine`.
+      declared !== undefined ? { declaredFailure: declared } : {},
+    );
+    // ANNOUNCE IT (OPE-149, visibility leg 3). The audit row above is durable but PASSIVE — it only
+    // answers a question someone thought to ask. A routine stopping itself is a state change with
+    // lasting consequence taken with no human present, and for a SILENT routine it is unobservable
+    // from the room by construction (its healthy state is also "you hear nothing").
+    //
+    // It lives HERE rather than in the session-end hook (where OPE-149 first put it) because the
+    // fold has two ingresses. The delivery-rejected path never starts a session, so a hook-side
+    // announcement could not reach the case that needs it MOST: three rejected deliveries is
+    // precisely the archived-channel / kicked-bot story, where nobody has seen anything at all.
+    // Fail-soft inside, and after the row: a surface that can't be posted into never costs us the
+    // fold or the row. See routines/disable-notice.ts.
+    await announceSelfDisable(routine, updated.disabledReason ?? "auto-disabled", updated.consecutiveFailures);
+  }
+  return { folded: true, outcome: settled, consecutiveFailures: updated.consecutiveFailures, disabled };
+}
+
+/**
+ * RETIRE A ROUTINE THAT HIT ITS CEILING (OPE-248) — the SECOND reason a routine stops itself, and
+ * the reason it lives in this file rather than beside the pure verdict in routines/bound.ts.
+ *
+ * Stopping a routine is three acts that must always happen together: persist the terminal status,
+ * write the `routine.disabled` forensic row, and POST the host-composed notice. `foldRoutineOutcome`
+ * above already does exactly those three for the three-strike case, and the one thing worse than
+ * having no ceiling would be having one whose stop drifts out of step with the other stop — a
+ * ceiling that disabled the row but never announced it would be strictly WORSE than no ceiling at
+ * all, because the routine would go quiet with nothing anywhere to read.
+ *
+ * ORDER MATCHES THE FOLD, for the same reasons: the store write first (so the row is terminal even
+ * if everything after it fails — an exhausted routine must not fire again under any circumstances),
+ * then the audit row (fire-audit.ts swallows its own failures), then the notice (fail-soft inside
+ * disable-notice.ts).
+ *
+ * `consecutiveFailures` rides the audit row unchanged and is USUALLY 0 — which is the point of this
+ * row existing at all: `routine.disabled` carrying a `boundDimension` and zero failures is a routine
+ * that was working the whole time and simply never finished, and that is a different incident from
+ * one that broke three times.
+ */
+export async function retireExhaustedRoutine(opts: {
+  readonly routine: Routine;
+  readonly verdict: Extract<BoundVerdict, { exhausted: true }>;
+}): Promise<boolean> {
+  const { routine, verdict } = opts;
+  const patch = boundExhaustedPatch(verdict);
+  const updated = await updateRoutine(routine.org, routine.surfaceKey, routine.id, patch);
+  if (!updated) return false; // cancelled between the read and here — nothing to retire
+
+  await auditRoutineDisabled(routine, patch.disabledReason ?? "stopped at its ceiling", routine.consecutiveFailures, undefined, {
+    // The DIMENSION, not just the sentence: "ran out of tries", "ran out of time" and "was never
+    // allowed to work" lead an operator to three different next moves (raise the cap / re-arm as-is /
+    // answer the checkpoint card FIRST), and a reader of the audit trail should not have to parse
+    // prose to tell them apart.
+    boundDimension: verdict.dimension,
+    fireCount: routine.fireCount ?? 0,
+    ...(routine.bound?.maxFires !== undefined ? { maxFires: routine.bound.maxFires } : {}),
+    ...(routine.bound?.until !== undefined ? { boundUntil: routine.bound.until } : {}),
+    // OPE-253: present exactly when there is a stall run to report, so an operator reading a
+    // `boundDimension: "stalled"` row gets the count that produced it without a second lookup — and a
+    // FIRES/DEADLINE row that ALSO carries a non-zero count is the tell that the ceiling was partly
+    // burned by fires that could not act.
+    ...(routine.stalledFires ? { stalledFires: routine.stalledFires } : {}),
+    ...(routine.lastStallAt !== undefined ? { lastStallAt: routine.lastStallAt } : {}),
+  });
+  return announceBoundExhausted(routine, verdict);
+}
+
+/**
+ * RECORD THAT THIS FIRE WAS BLOCKED (OPE-253) — called from spend/checkpoint.ts's block path when the
+ * refused session turns out to be a routine fire. Returns whether this call was the one that recorded
+ * the stall (false = already recorded for this fire, or the routine is gone).
+ *
+ * IT RECORDS A FACT AND DOES NO ARITHMETIC. `lastStallAt` is the per-fire fact; the COUNT is applied
+ * by {@link foldRoutineOutcome} at session end via routines/stall.ts stallFoldPatch. That is the exact
+ * split OPE-177 uses (`report_run_failed` records `lastFailureReason` mid-turn, `applyOutcome` counts
+ * it into `consecutiveFailures`), and it buys three things a counter-here design would not:
+ *
+ *   • PER-FIRE IDEMPOTENCE for free. A blocked tool throws a RECOVERABLE error, so the model takes
+ *     another step and may reach for a second consequential tool in the same fire — three refusals is
+ *     still ONE stalled fire. The dispatcher clears `lastStallAt` at fire, so "already set" is a
+ *     reliable "this fire is already counted", and the early return below is what keeps the audit row
+ *     one-per-fire without a throttle.
+ *   • the RUN can be broken by a fire that got its hands, which is what makes the counter consecutive.
+ *     Only the fold knows a fire ended without stalling.
+ *   • no double-count across a durable-replay of the same tool step.
+ *
+ * FAIL-SOFT BY CONTRACT, and it must be: this runs INSIDE a guard whose whole job is to throw a
+ * recoverable tool-error, on a path the guard already documents as fail-OPEN. A store hiccup while
+ * recording the stall must never change whether the tool was blocked, nor replace the guard's error
+ * with a store error the model would read as something else entirely. Every failure logs and returns
+ * false; the checkpoint's own `checkpoint.trip` row is unaffected.
+ */
+export async function recordCheckpointStall(opts: {
+  readonly marker: RoutineOutcomeMarker;
+  readonly tool: string;
+  readonly reason: string;
+  readonly at?: Date;
+}): Promise<boolean> {
+  const { marker, tool, reason } = opts;
+  try {
+    const routine = await getRoutine(marker.org, marker.surfaceKey, marker.id);
+    if (!routine) return false; // cancelled between the fire and the refusal
+    if (routine.lastStallAt !== undefined) return false; // this fire is already recorded — see above
+    const at = (opts.at ?? new Date()).toISOString();
+    const updated = await updateRoutine(marker.org, marker.surfaceKey, marker.id, { lastStallAt: at });
+    if (!updated) return false;
+    // AFTER the row, so the count on the row and the count on the row's row agree for a reader. The
+    // fold has not run yet, so the run this fire EXTENDS is the stored count plus this one — stated
+    // that way rather than reported as the stored value, which would be off by one for every reader.
+    await auditRoutineStalled(routine, { tool, reason, stalledFires: (routine.stalledFires ?? 0) + 1 });
+    return true;
+  } catch (err) {
+    console.log(`[open-everywhere:routines] stall record skipped for ${marker.id}: ${String(err)}`);
+    return false;
+  }
+}

package/agent/routines/partition.ts

@@ -0,0 +1,27 @@
+// A routine's PARTITION, derived without a session. One shape, one place.
+//
+// A routine fires with no live context to bind from — the dispatcher (clock leg) and the fan-out
+// (event leg) both need "which partition is this row's?" before any session exists — so the split
+// is done off the stored `surfaceKey` exactly the way `memory/partition.ts` resolvePartition does
+// it off a binding. This used to be a private copy inside schedules/dispatch.ts, with a second
+// partial copy (`routineAuditScope`) in routines/fire-audit.ts; the read-grant check (event-authz.ts)
+// would have made it a third, which is the point at which a duplicated identity derivation stops
+// being harmless.
+
+import type { Partition } from "../memory/partition.js";
+import type { Routine } from "./routine.js";
+
+/** The partition a routine belongs to and fires back into. */
+export function routinePartition(r: Pick<Routine, "org" | "surfaceKey">): Partition {
+  const [platform = "", workspace = "", ...rest] = r.surfaceKey.split("/");
+  const workspaceKey = `${platform}/${workspace}`;
+  return {
+    org: r.org,
+    platform,
+    workspace,
+    surface: rest.join("/"),
+    workspaceKey,
+    surfaceKey: r.surfaceKey,
+    key: r.surfaceKey,
+  };
+}

package/agent/routines/permission-card-wait.ts

@@ -0,0 +1,281 @@
+// THE EVERY-FIRE TIMED WAIT on a routine permission card (OPE-1290, PR 2 of 3).
+//
+// WHAT THIS FILE DECIDES. A routine fire has just been refused, and `routines/permission-card.ts`
+// has either posted a fresh card into the routine's room or found one already live there. PR 1 threw
+// the refusal at that instant. This file adds the bounded pause in between: the refusing tool call
+// polls that card's own pending row, and if a person answers it while the run is still up, the run
+// gets the answer instead of the refusal.
+//
+// 🔴 WHY THE WAIT LIVES IN OUR CODE. eve has no timeout arm on an approval — nothing suspends a turn
+// and resumes it on a click. So the only place a run can wait is INSIDE the tool body that is about
+// to refuse, against the function's own wall clock. That is what {@link waitForRoutineCardDecision}
+// is: a poll loop with one budget, spent by the caller who would otherwise have thrown already.
+//
+// 🔴 THE DEADLINE IS A TURN OUTCOME, NEVER A CARD DEATH. When the budget runs out this returns
+// `deadline` and DECIDES NOTHING — no CAS, no expiry, no row written. The card is still pending, it
+// still has live buttons, and approving it still arms every future fire. Two different questions
+// live here and collapsing them is the defect this note exists to prevent:
+//   • the RUN's question — "may I use this right now?" — which the deadline answers "no, because
+//     nobody was here", honestly, to the model;
+//   • the CARD's question — "may this routine use this in general?" — which stays open.
+// The fence deciding the pending row itself would answer the second question with the first one's
+// evidence, and a routine whose 03:00 card auto-rejected because nobody was awake at 03:00 is
+// exactly the failure the no-clock TTL ruling already refused once.
+//
+// 🔴 WHY AN APPROVAL IS NOT TAKEN ON THE PENDING ROW ALONE. `resolveApprovalClick` CASes the row to
+// `approved` BEFORE it runs the kind, and this kind's `execute` refuses outright when the routine
+// has been edited since the card was posted (the click-time re-check that makes a clockless card
+// safe). So `status: "approved"` means a human clicked, not that anything was armed. The probe reads
+// BOTH — the row's status and the standing grant row itself — and only a click that really wrote the
+// grant lets the run proceed. Everything else refuses, naming what happened.
+//
+// A LEAF: the settings read, the turn clock read, and pure arithmetic over an injected clock. The
+// probe, the sleep and the clock are all supplied by the caller, which is what lets the deadline
+// legs be tested without spending 120 seconds of wall time.
+
+import { getSettings } from "../settings/settings.js";
+import { turnElapsedSeconds } from "../observability/turn-clock.js";
+
+/**
+ * The deployed function's wall ceiling, in seconds (measured on ship #148, config-read, three
+ * sources agreeing: the platform default under fluid compute, with no app pin). Everything below is
+ * arithmetic off this number, and it is stated here rather than in the setting so the code that
+ * enforces the bound and the doc that explains it cannot drift apart.
+ */
+export const FUNCTION_WALL_CEILING_SECONDS = 300;
+
+/**
+ * The FALLBACK for what the turn has already spent by the time a gated tool call reaches its
+ * refusal — the wake, the model's first passes, and whatever tools ran before this one.
+ *
+ * 🔴 IT IS THE "OTHERWISE" ARM, NOT THE ONLY ARM (OPE-1347). The bound is
+ * `min(configured, ceiling − elapsed − reserve)`, and `elapsed` is READ from the turn's own
+ * `startedAt` through {@link turnElapsedSeconds}. This number is what stands in when there is no
+ * turn to read: a schedule, an eval, a CLI, a unit test. It is deliberately generous — assuming a
+ * turn is further along than it is shortens the wait, which costs a run its window; assuming it is
+ * younger than it is lets the wall clock kill the turn mid-report, which costs the run its report.
+ */
+export const ASSUMED_TURN_ELAPSED_SECONDS = 120;
+
+/**
+ * What must still fit AFTER the wait: telling the model, its next passes, and posting the run's
+ * report to the routine's surface. A wait that consumed the whole remainder would turn a refusal
+ * the model could report into a turn that is killed mid-sentence.
+ */
+export const TURN_TAIL_RESERVE_SECONDS = 60;
+
+/** The clamp on the FALLBACK arm: 300 − 120 − 60. Also the recommended armed value, because it is
+ *  what a turn that reached its refusal at the assumed elapsed can still afford. It is NOT a floor
+ *  on {@link routineCardWaitCeilingSeconds}, which goes to 0 and below on a longer turn — that is
+ *  the clamp OPE-1347 exists for. */
+export const ROUTINE_CARD_WAIT_CEILING_SECONDS = FUNCTION_WALL_CEILING_SECONDS - ASSUMED_TURN_ELAPSED_SECONDS - TURN_TAIL_RESERVE_SECONDS;
+
+/**
+ * The wait this turn may still afford, in seconds: `300 − elapsed − 60`.
+ *
+ * 🔴 IT CAN BE ZERO OR NEGATIVE, AND THAT IS THE POINT (OPE-1347). A turn that reached its refusal
+ * 250 seconds in has 300 − 250 − 60 = −10 seconds of room. Before the elapsed read that same turn
+ * was handed the flat 120-second budget and was killed by the wall clock mid-report — the refusal
+ * never reached the model and the routine's room learned nothing. A non-positive ceiling now
+ * disarms the wait instead: the refusal is immediate and the card still decides every future fire.
+ * {@link routineCardWaitBudgetMs} is where that clamp is applied.
+ *
+ * An unreadable elapsed (no turn context, or a clock that moved backwards) falls back to
+ * {@link ASSUMED_TURN_ELAPSED_SECONDS}, which reproduces the pre-OPE-1347 number exactly.
+ */
+export function routineCardWaitCeilingSeconds(elapsedSeconds: number | undefined = turnElapsedSeconds()): number {
+  const elapsed = elapsedSeconds !== undefined && Number.isFinite(elapsedSeconds) && elapsedSeconds >= 0 ? elapsedSeconds : ASSUMED_TURN_ELAPSED_SECONDS;
+  return FUNCTION_WALL_CEILING_SECONDS - elapsed - TURN_TAIL_RESERVE_SECONDS;
+}
+
+/**
+ * How often the pending row is re-read. A click is a human action, so a two-second granularity
+ * costs the clicker nothing they can perceive and keeps a 120-second wait at ~60 store reads rather
+ * than thousands.
+ */
+const ROUTINE_CARD_POLL_INTERVAL_MS = 2_000;
+
+/**
+ * What the wait concluded.
+ *
+ * `stale` and `gone` are kept apart from `deadline` on purpose: all three refuse the run, and they
+ * refuse it for three different reasons that a human debugging a routine needs told apart. Saying
+ * "nobody was around" about a card a person actually clicked is the overclaim this split prevents.
+ */
+export type RoutineCardWaitOutcome =
+  /** The setting ships 0 — no wait ran at all, and the refusal is byte-identical to PR 1's. */
+  | "disarmed"
+  /** A person approved inside the window AND the standing grant row is really written. */
+  | "approved"
+  /** A person declined inside the window. The run refuses.
+   *
+   *  🔴 IT SAYS NOTHING ABOUT DURABILITY. `routinePermission.declined` writes the "stop asking" row
+   *  only when its own click-time re-check passes, and that write is best-effort — so whether the
+   *  decline is remembered is a property of the CARD, decided after this outcome is read, and the
+   *  run must not report it. Reading it here would also race the click exactly as `stale` does. */
+  | "declined"
+  /** A person approved, and no standing permission was written behind the click before the budget
+   *  ran out. Reported only at the DEADLINE, never on the first unarmed probe — see the loop. */
+  | "stale"
+  /** The card is no longer answerable (expired, or the row is gone). */
+  | "gone"
+  /**
+   * The budget ran out and the LAST probe of the window could not read the card at all.
+   *
+   * 🔴 IT EXISTS BECAUSE `deadline` WOULD BE A LIE HERE. The loop swallows every probe rejection so a
+   * store blip cannot auto-decline a run early — which means a store that is down for the whole
+   * window reaches the same end state as a card nobody touched. Reporting that as "nobody was
+   * present to action it" states as fact something the code never observed: the owner may have
+   * clicked, and this run simply could not see it. So the two are separated at the one place that
+   * can tell them apart, and this arm says what actually happened.
+   */
+  | "unreadable"
+  /** The budget ran out with the card still pending. The row is untouched and stays clickable. */
+  | "deadline";
+
+/** One read of the card's world: what its row says, and whether the grant really exists. */
+export interface RoutineCardProbe {
+  readonly status: "pending" | "approved" | "rejected" | "expired" | "gone";
+  /** Is the standing grant row actually written? Read only when it could be — see the header. */
+  readonly armed: boolean;
+}
+
+/**
+ * The injected seam. Production passes the real store probe, a real `setTimeout` sleep and
+ * `Date.now`; a test passes a scripted probe, a sleep that resolves immediately and a clock it
+ * advances itself — which is how the deadline legs run in milliseconds and prove the arithmetic
+ * rather than the machine's timer.
+ */
+export interface RoutineCardWaitDeps {
+  readonly probe: () => Promise<RoutineCardProbe>;
+  readonly sleep: (ms: number) => Promise<void>;
+  readonly nowMs: () => number;
+  /** Defaults to {@link ROUTINE_CARD_POLL_INTERVAL_MS}. */
+  readonly pollIntervalMs?: number;
+}
+
+/** The configured wait, in seconds, before the ceiling clamp. */
+export function routineCardWaitSeconds(): number {
+  return getSettings().approvals.routineCardWaitSeconds;
+}
+
+/**
+ * The budget this run may actually spend, in milliseconds — `min(configured, ceiling)`, and 0 for
+ * anything non-positive or unreadable. 0 means NO WAIT: the caller refuses immediately, exactly as
+ * it did before this file existed.
+ *
+ * The clamp is not defensive decoration. The setting's validator refuses a value above 300, but it
+ * admits every value up to it — an operator who authors 200 gets what the turn can still afford,
+ * not a turn killed mid-report. And since OPE-1347 the ceiling is derived from the turn's OWN
+ * elapsed time rather than an assumed 120 seconds, so a long turn is clamped harder (down to no
+ * wait at all) and a young one is allowed the whole configured window.
+ */
+export function routineCardWaitBudgetMs(
+  configuredSeconds: number = routineCardWaitSeconds(),
+  ceilingSeconds: number = routineCardWaitCeilingSeconds(),
+): number {
+  if (!Number.isFinite(configuredSeconds) || configuredSeconds <= 0) return 0;
+  if (!Number.isFinite(ceilingSeconds) || ceilingSeconds <= 0) return 0;
+  return Math.min(configuredSeconds, ceilingSeconds) * 1_000;
+}
+
+/**
+ * Poll the card until it is answered or the budget is spent.
+ *
+ * ORDER IS LOAD-BEARING: probe, then test the deadline, then sleep. A click that landed between the
+ * card's post and the first tick is therefore seen without waiting for one, and the last sleep is
+ * always followed by one final probe rather than an immediate give-up.
+ *
+ * A probe that THROWS is swallowed and the loop continues. A store blip must not read as "nobody
+ * answered" — the budget still bounds the whole thing, so the cost of a broken store is the full
+ * wait and then an honest deadline, never an early wrong answer.
+ */
+export async function waitForRoutineCardDecision(budgetMs: number, deps: RoutineCardWaitDeps): Promise<RoutineCardWaitOutcome> {
+  if (!(budgetMs > 0)) return "disarmed";
+  const interval = deps.pollIntervalMs ?? ROUTINE_CARD_POLL_INTERVAL_MS;
+  const endsAt = deps.nowMs() + budgetMs;
+  // 🔴 AN UNARMED APPROVAL IS NOT YET A VERDICT — IT IS USUALLY A RACE. `resolveApprovalClick` CASes
+  // the row to `approved`, THEN re-reads the routine, THEN writes the permission row: several store round
+  // trips during which the row reads `approved` and no grant exists. Returning `stale` on the first
+  // such probe would refuse a run whose permission lands milliseconds later, and would tell the
+  // model the instruction had been edited when nothing was edited. So an unarmed approval is
+  // REMEMBERED and the loop keeps going; only the deadline turns it into `stale`.
+  let sawUnarmedApproval = false;
+  // 🔴 DID THE LAST LOOK ACTUALLY SEE ANYTHING? The probe's rejection is swallowed just below, which
+  // is right — one store blip must not auto-decline a run. The cost is that a store down for the
+  // WHOLE window arrives at the same place as a card nobody touched, and only this flag can tell the
+  // refusal which of the two to report. It tracks the FINAL look rather than "was there ever a
+  // failure", because what the run is about to assert is the card's state at the moment it gave up.
+  let lastProbeFailed = false;
+  for (;;) {
+    const probe = await deps.probe().catch(() => undefined);
+    lastProbeFailed = probe === undefined;
+    switch (probe?.status) {
+      case "approved":
+        if (probe.armed) return "approved";
+        sawUnarmedApproval = true;
+        break;
+      case "rejected":
+        // Terminal at once, and deliberately without a second read: a person said no, which answers
+        // this run whatever the card's own bookkeeping then records. See the `declined` doc.
+        return "declined";
+      case "expired":
+      case "gone":
+        return "gone";
+      default:
+        break;
+    }
+    const left = endsAt - deps.nowMs();
+    // ORDER: an unreadable final look wins over BOTH remaining arms. `stale` asserts that no
+    // permission was written, and `deadline` that nobody answered — neither is knowable when the
+    // last thing this run did was fail to read the card.
+    if (left <= 0) return lastProbeFailed ? "unreadable" : sawUnarmedApproval ? "stale" : "deadline";
+    await deps.sleep(Math.min(interval, left));
+  }
+}
+
+/**
+ * The clause the refusal appends for a wait that did not end in an approval. Every arm names what
+ * really happened, and every arm states only what a row actually said.
+ *
+ * 🔴 EVERY ARM IS SELF-CONTAINED, AND THAT IS LOAD-BEARING. The caller composes this with the
+ * PRE-WAIT card-state clause ("a card is now waiting" / "a card is already waiting"), which
+ * describes the card at wait START. Only {@link routineCardKeepsStateClause} says when that is still
+ * true at wait END — everywhere else the pre-wait sentence is DROPPED, because "nobody has decided
+ * it yet" followed by "a person declined it" is one paragraph contradicting itself. So each arm here
+ * has to introduce the card itself rather than lean on a sentence that may not be there.
+ *
+ * `approved` returns "" — that run does not refuse, so it has no refusal to append to.
+ */
+export function routineCardWaitRefusalClause(outcome: RoutineCardWaitOutcome, waitedSeconds: number): string {
+  switch (outcome) {
+    case "declined":
+      // No durability claim: whether the decline is REMEMBERED is the card's business and is
+      // decided after this read. See the `declined` outcome's own doc.
+      return " A permission card for this was waiting in the routine's own room, and a person declined it while this run waited — so this run does not get it.";
+    case "deadline":
+      return ` This run waited ${waitedSeconds}s for someone to answer that card and nobody did, so it was declined for THIS RUN ONLY because nobody was present to action it. The card is still waiting and still clickable — approving it lets future runs do this without asking.`;
+    case "stale":
+      // States the OBSERVED fact and names the likely cause as something to check, never as
+      // something this code verified — it read no routine and no generation.
+      return ` A person approved the permission card in the routine's own room while this run waited, but no standing permission was written behind their click in the ${waitedSeconds}s this run had, so nothing was armed. A click on a card posted before an \`edit_routine\` records nothing — check whether the instruction changed.`;
+    case "gone":
+      return " The permission card for this is no longer answerable, so the next run will post a fresh one.";
+    case "unreadable":
+      return ` A permission card for this is waiting in the routine's own room, but this run could not read it for the last of the ${waitedSeconds}s it waited, so it gave up without knowing whether anyone answered. Nothing here says nobody did. The card is unaffected — approving it still lets future runs do this without asking.`;
+    default:
+      return "";
+  }
+}
+
+/**
+ * May the caller keep its PRE-WAIT card-state clause alongside {@link routineCardWaitRefusalClause}?
+ *
+ * Only at the deadline. There the card really is untouched — still pending, still where the earlier
+ * sentence said it was — so "a card is waiting in the routine's own room" is as true at wait end as
+ * it was at wait start, and the two sentences read as one paragraph. Every other outcome moved the
+ * card out from under that sentence.
+ */
+export function routineCardKeepsStateClause(outcome: RoutineCardWaitOutcome): boolean {
+  return outcome === "deadline";
+}