shraga 0.1.32 → 0.1.34

package/defaults/skills/scheduler.md

@@ -140,8 +140,9 @@ Schedule: { id, name, enabled, trigger, task, scope, createdBy, nextRun?, lastRu
 
 ## Missed windows (`onMissed` / `missedRun`)
 
-If the process is down when a window should have fired (deploy, crash, power cut), the scheduler
-decides at the next boot whether to replay it. `onMissed` is settable on `POST`/`PUT`:
+If a window elapses with nothing running (deploy, crash, power cut — or the host **suspending**
+with the process frozen), the scheduler decides whether to replay it. `onMissed` is settable on
+`POST`/`PUT`:
 
 | `onMissed` | Behaviour |
 |---|---|
@@ -157,10 +158,20 @@ curl -s -X PUT -H "Content-Type: application/json" -H "x-internal-token: $INTERN
 - **A staleness ceiling overrides every policy, `run` included**: a window more than
   `SCHEDULER_MAX_MISSED_AGE_MS` (default **6h**) late is never replayed. Finishing an 08:00 report
   at 22:00 is not the job the schedule describes.
-- This applies to **both** paths that could replay a window: the boot catch-up (cron), and the
-  in-place resume of a run interrupted mid-flight (every trigger kind — `interval`/`once`/`event`
-  have no catch-up, so resume is their only gate; their window is the one the interrupted run
-  recorded when it started).
+- One decision (`judgeMissed` in `scheduler/engine.ts`) governs **all three** paths that could
+  replay a window:
+  1. **Boot catch-up** (cron only) — the process was down when the window passed.
+  2. **In-place resume** of a run interrupted mid-flight — every trigger kind
+     (`interval`/`once`/`event` have no catch-up, so resume is their only gate; their window is
+     the one the interrupted run recorded when it started).
+  3. **A late timer fire** — the process was *frozen*, not killed (laptop lid/standby, NTP step,
+     VM pause): same pid, no restart, so catch-up never ran, and the overdue `setTimeout` fires on
+     wake. The window is the schedule's `nextRun` (when it *should* have fired), not the wake time.
+     A punctual fire is untouched — `onMissed` is a missed-window policy, never a mute — the gate
+     engages only once the fire is past the ceiling.
+- After a refusal the schedule is still re-armed normally: an `interval` job loses exactly one
+  cycle and fires again next period; a `once` is retired (disabled, `nextRun` cleared) with its
+  `missedRun` left for an on-demand run. Nothing is left enabled-but-never-firing.
 - Whenever a window is not replayed, the schedule gets
   `missedRun: { at, reason: "skip"|"offer"|"stale", noticedAt }` — visible on
   `GET /api/schedules` and `GET /api/schedules/{id}`. **That is the `offer` affordance**: read it,
@@ -173,9 +184,32 @@ curl -s -X PUT -H "Content-Type: application/json" -H "x-internal-token: $INTERN
 ## "What did I miss?" — downtime recovery (`GET /api/downtime`)
 
 This box is deliberately not always-on. The server heartbeats to `data/state/heartbeat.json` every
-`HEARTBEAT_INTERVAL_MS` (default **60s**); at boot, a gap larger than `DOWNTIME_THRESHOLD_MS`
-(default **3 intervals = 3m**) is appended to `data/state/downtime.json` as
-`{ from, to, ms, slackCursors }` (last **20** kept). A clean restart records nothing.
+`HEARTBEAT_INTERVAL_MS` (default **60s**). A gap larger than `DOWNTIME_THRESHOLD_MS` (default
+**3 intervals = 3m**) is appended to `data/state/downtime.json` as
+`{ from, to, ms, cause, slackCursors? }` (last **20** kept). A clean restart records nothing.
+
+Two `cause`s, one code path:
+
+- **`cause: 'boot'`** — the process died (crash, power cut). The gap is measured at startup, from
+  the last persisted heartbeat.
+- **`cause: 'suspend'`** — the process never died: the **host slept** (lid closed, standby) and the
+  process was *frozen*. Nothing restarts, so a boot check would never see it — instead the next
+  heartbeat tick comes back late by more than the threshold and records the gap itself. One entry
+  per outage, however long (the tick writes the heartbeat forward before the next one compares).
+Two consequences of a `suspend` gap, both flagged in the report's `note`:
+
+- **`missedSchedules[]` is INCOMPLETE, not empty** — the boot-time catch-up scan never ran (nothing
+  restarted), so the only records are the ones the **late timer fire** wrote itself (see "Missed
+  windows" above: a fire past the ceiling is refused and recorded as `missedRun`, at a timestamp
+  *inside* the gap, which the report then joins). Windows still inside the ceiling on wake simply
+  ran; anything else that elapsed in the gap left **no record at all** — check those by hand. The
+  note is emitted for any suspend in the last `SUSPEND_NOTE_MAX_AGE_MS` (**24h**), not just the
+  newest entry: a restart afterwards appends a `boot` entry but rescans nothing.
+- **No `slackCursors` snapshot** — the snapshot is only taken on the `boot` path, where it is
+  provably older than any post-recovery traffic. A suspend gap is recorded from a heartbeat tick up
+  to 60s *after* the wake, by which time the reconnected socket may already have pushed the cursor
+  past the whole backlog. So the entry carries none and the backfill floors at the gap's `from` —
+  it may re-report a few already-seen messages, never skip unseen ones.
 
 ```bash
 curl -s -H "x-internal-token: $INTERNAL_API_TOKEN" "http://localhost:$PORT/api/downtime" | jq .
@@ -192,7 +226,8 @@ Returns `{ heartbeat, downtime[], lastDowntime, missedSchedules[], slack }`:
   Events API retries a dropped delivery for only ~30 minutes then discards it forever, while
   `conversations.history` stays readable for days.
   - **Where it starts:** the outage's `from`, raised only by the last-seen cursor **as
-    snapshotted into the downtime entry at boot** (`slackCursors`). The live cursors in
+    snapshotted into the downtime entry at boot** (`slackCursors`, `cause: 'boot'` only — a
+    `suspend` entry has none, so it starts at `from`). The live cursors in
     `data/state/slack-cursors.json` are a tail pointer — one message after recovery pushes them
     past the whole backlog — so they are never used as the floor.
   - **Which channels:** every channel with a cursor (at the time of the outage or since), plus

package/defaults/skills/self-aware.md

@@ -123,12 +123,14 @@ Schedules sync across all envs but only **execute** where `DATA_SYNC_SCHEDULER_A
 Two layers cause you to run — know both, and which to reach for:
 
 **Schedules (`schedules.json`)** — a schedule is `trigger` + `task` (`prompt`/`bash`/`job`). One execution path, two trigger families:
-- **Time**: `cron` / `interval` / `once`. A window missed while you were down obeys `onMissed`
+- **Time**: `cron` / `interval` / `once`. A window missed while you were down — or while the host
+  was **suspended** and you were merely frozen — obeys `onMissed`
   (`run` default / `skip` / `offer`) plus a hard 6h staleness ceiling that overrides *every*
   policy — so an 08:00 job never silently replays at 22:00. Anything not replayed is recorded as
   `missedRun` on the schedule (visible in `GET /api/schedules`) for an on-demand run. See the
   **scheduler** skill.
-  - **Asked "what did I miss?"** (after a power cut / long downtime): `GET /api/downtime`. It
+  - **Asked "what did I miss?"** (after a power cut, or a laptop **suspend** — a slept host is
+    caught too, by a late heartbeat tick, `cause: 'suspend'`): `GET /api/downtime`. It
     joins the recorded outage ranges to those `missedRun` windows and to the Slack messages that
     arrived while you were down, and it **reports and proposes only** — run a missed window with
     an explicit `POST /api/schedules/{id}/run`. Never replay everything you missed; a 14h-late

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shraga",
-  "version": "0.1.32",
+  "version": "0.1.34",
   "description": "The teammate you delegate coding to — a self-hostable, multi-user AI coding agent web UI (Claude Code, with a pluggable engine seam).",
   "type": "module",
   "main": "./src/index.ts",

package/src/server/boot.ts

@@ -2016,6 +2016,20 @@ try {
 
 const PORT = Number(process.env.PORT) || 3032;
 await new Promise<void>((resolve) => {
+  // A listen failure MUST kill the process. Without this the error reaches the `uncaughtException`
+  // handler above, which by design keeps us alive — so the promise never settles and we sit there
+  // forever: process running, port unbound, nothing served. The service manager sees a healthy job
+  // and a port watchdog sees a dead one, so it kickstarts on a loop and shreds in-flight runs.
+  // EADDRINUSE is the common case: `kickstart -k` starts the replacement while the old process is
+  // still draining (up to 90s). Exiting non-zero is the correct answer — the manager restarts us,
+  // and by then the port is free.
+  server.once('error', (err: NodeJS.ErrnoException) => {
+    const why = err.code === 'EADDRINUSE'
+      ? `port ${PORT} is already in use (previous instance still draining?)`
+      : (err.message ?? String(err));
+    console.error(`[server] FATAL: cannot listen on ${PORT} — ${why}. Exiting so the service manager restarts us.`);
+    process.exit(1);
+  });
   server.listen(PORT, () => {
     console.log(`[server] Running on http://0.0.0.0:${PORT}`);
     resolve();

package/src/server/downtime.ts

@@ -7,7 +7,8 @@
  * 22:00; this module supplies the other half — the ledger and the on-demand report.
  *
  * Deliberately inert: nothing here starts a run, answers a Slack message, or mutates a schedule.
- * The only writers are the heartbeat, the boot gap record, and the Slack last-seen cursor.
+ * The only writers are the heartbeat, the gap ledger (boot gap + late-tick/suspend gap), and the
+ * Slack last-seen cursor.
  * Acting on a finding is always an explicit follow-up (`POST /api/schedules/:id/run`).
  */
 import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync } from 'node:fs';
@@ -42,6 +43,18 @@ export const DOWNTIME_THRESHOLD_MS = Number(process.env.DOWNTIME_THRESHOLD_MS ??
  */
 export const DOWNTIME_HISTORY_MAX = 20;
 
+/**
+ * How long a `suspend` gap keeps colouring the report's `note`.
+ *
+ * A suspend is never retroactively scanned — no restart happens, so no catch-up ever covers it, and
+ * a later `boot` entry does not make it honest. The warning therefore cannot be tied to "is the
+ * newest entry a suspend?"; it has to age out on its own. 24h is the horizon of the manual check
+ * the note asks for ("which schedule windows fell in the gap?"): nearly every schedule here is
+ * daily or tighter, so after a day the same window has come round again and run normally, and the
+ * gap is no longer the thing to look at.
+ */
+export const SUSPEND_NOTE_MAX_AGE_MS = Number(process.env.SUSPEND_NOTE_MAX_AGE_MS ?? 24 * 60 * 60 * 1000);
+
 export interface DowntimeEntry {
   /** Last proven-alive moment (the final heartbeat before the gap). */
   from: number;
@@ -49,10 +62,26 @@ export interface DowntimeEntry {
   to: number;
   ms: number;
   /**
-   * channelId → last Slack ts we had seen when this outage was recorded, snapshotted at boot
-   * BEFORE any live traffic can move the cursors. The live cursor is a tail pointer: one normal
-   * message after recovery pushes it past the entire backlog. This frozen copy is the only thing
-   * that still knows where the outage's unseen history begins.
+   * How the gap was noticed. `boot` = the process died (crash, power cut, deploy) and the gap was
+   * measured at startup. `suspend` = the process never died — the host slept (lid closed, standby)
+   * and a heartbeat tick came back late by more than the threshold. Both are real outages; the
+   * distinction matters to the reader, because a `suspend` gap means the process was FROZEN, so
+   * nothing at all ran at boot afterwards (no scheduler catch-up scan — see `missedSchedules`).
+   * Absent on entries written before this field existed.
+   */
+  cause?: 'boot' | 'suspend';
+  /**
+   * channelId → last Slack ts we had seen when this outage was recorded. Present on `boot` entries
+   * ONLY, where it is snapshotted before any live traffic can move the cursors (`recordBootGap()`
+   * runs before the Slack ingress mounts — see boot.ts). The live cursor is a tail pointer: one
+   * normal message after recovery pushes it past the entire backlog, so a snapshot taken after
+   * traffic resumed would hide the outage rather than bound it.
+   *
+   * Absent on `suspend` entries by design: that gap is recorded from a heartbeat tick, up to
+   * HEARTBEAT_INTERVAL_MS after the wake — exactly when the reconnected socket delivers the
+   * backlog — so the cursor is no longer provably pre-gap. With no snapshot the backfill floors at
+   * the outage start (`from`), which can re-report a few already-seen messages but can never skip
+   * unseen ones.
    */
   slackCursors?: Record<string, string>;
 }
@@ -90,11 +119,19 @@ export function writeHeartbeat(at = Date.now()): void {
   writeJsonAtomic(HEARTBEAT_FILE, { at, pid: process.pid });
 }
 
-/** Stamp liveness every interval. Unref'd — a heartbeat must never hold the process open. */
+/**
+ * Stamp liveness every interval, and NOTICE when a tick comes back late.
+ *
+ * A boot-time check only catches an outage that killed the process. The common failure on this box
+ * is the opposite: a MacBook that sleeps with the lid closed. The process is frozen, not killed —
+ * it never restarts, so `recordBootGap()` never runs, and a 2.5h outage was completely invisible.
+ * A late tick is the one signal that survives a suspend, because the timer resumes on wake and the
+ * wall clock has moved on. Unref'd — a heartbeat must never hold the process open.
+ */
 export function startHeartbeat(intervalMs = HEARTBEAT_INTERVAL_MS): () => void {
   writeHeartbeat();
   const timer = setInterval(() => {
-    try { writeHeartbeat(); } catch (err) { console.error('[downtime] heartbeat write failed:', err); }
+    try { recordTickGap(); } catch (err) { console.error('[downtime] heartbeat write failed:', err); }
   }, intervalMs);
   timer.unref?.();
   return () => clearInterval(timer);
@@ -106,6 +143,37 @@ export function listDowntime(): DowntimeEntry[] {
   return readJson<DowntimeFile>(DOWNTIME_FILE, { entries: [] }).entries ?? [];
 }
 
+/**
+ * The one gap-recording path, shared by the boot check and the late-tick check.
+ *
+ * Both ask the same question — "the last proven-alive moment is `last`, it is now `now`, is that a
+ * hole?" — so they share the same threshold, the same bounds, and the same Slack-cursor snapshot.
+ * Writing the heartbeat forward is the caller's job and happens either way (this process is alive
+ * NOW regardless of the verdict), which is also what makes an outage record exactly ONCE: the next
+ * comparison starts from `now`, not from the stale pre-gap stamp.
+ *
+ * Never fires anything. It appends a row to a JSON file and logs — that is the whole contract.
+ */
+function recordGap(last: number, now: number, cause: 'boot' | 'suspend'): DowntimeEntry | null {
+  const ms = now - last;
+  // `<=` also covers a backwards clock jump (negative ms): degrade to "no outage", never invent one.
+  if (ms <= DOWNTIME_THRESHOLD_MS) return null;
+
+  // Freeze the Slack cursors into the entry — but only on the boot path, where they are still
+  // provably pre-gap (recordBootGap runs before the Slack ingress mounts). On the suspend path the
+  // socket has been back for up to a heartbeat interval and may already have pushed the cursor past
+  // the whole backlog; recording that would be worse than recording nothing, so the entry carries
+  // no snapshot and the backfill floors at the gap start instead. See DowntimeEntry.slackCursors.
+  const snapshot: Record<string, string> = {};
+  if (cause === 'boot') for (const [channel, cursor] of Object.entries(listSlackCursors())) snapshot[channel] = cursor.ts;
+
+  const entry: DowntimeEntry = { from: last, to: now, ms, cause, ...(Object.keys(snapshot).length ? { slackCursors: snapshot } : {}) };
+  const entries = [...listDowntime(), entry].slice(-DOWNTIME_HISTORY_MAX);
+  writeJsonAtomic(DOWNTIME_FILE, { entries } satisfies DowntimeFile);
+  console.log(`[downtime] ${cause} gap of ${Math.round(ms / 60_000)}m recorded — down from ${new Date(last).toISOString()} to ${new Date(now).toISOString()}`);
+  return entry;
+}
+
 /**
  * Compare the last heartbeat against boot time and, if the gap is real, record it. Returns the
  * entry it recorded, or null — a clean restart (and a first-ever boot, which has no heartbeat to
@@ -116,19 +184,26 @@ export function recordBootGap(bootTime = Date.now()): DowntimeEntry | null {
   // Write the new heartbeat regardless: whatever we conclude, this process is alive now.
   writeHeartbeat(bootTime);
   if (last === null) return null;
-  const ms = bootTime - last;
-  if (ms <= DOWNTIME_THRESHOLD_MS) return null;
-
-  // Freeze the Slack cursors into the entry now, at boot, before the first inbound message can
-  // advance them past the backlog this outage left behind.
-  const snapshot: Record<string, string> = {};
-  for (const [channel, cursor] of Object.entries(listSlackCursors())) snapshot[channel] = cursor.ts;
+  return recordGap(last, bootTime, 'boot');
+}
 
-  const entry: DowntimeEntry = { from: last, to: bootTime, ms, ...(Object.keys(snapshot).length ? { slackCursors: snapshot } : {}) };
-  const entries = [...listDowntime(), entry].slice(-DOWNTIME_HISTORY_MAX);
-  writeJsonAtomic(DOWNTIME_FILE, { entries } satisfies DowntimeFile);
-  console.log(`[downtime] gap of ${Math.round(ms / 60_000)}m recorded — down from ${new Date(last).toISOString()} to ${new Date(bootTime).toISOString()}`);
-  return entry;
+/**
+ * One heartbeat tick: stamp liveness, and record an outage if the tick is late past the threshold.
+ *
+ * The reference point is the PERSISTED heartbeat — the same value `recordBootGap()` measures from,
+ * so boot and suspend can never disagree about where the last proven-alive moment was, and can
+ * never double-record one outage: whichever check sees the gap first advances the stamp, and the
+ * other then measures from the new one.
+ *
+ * A long suspend yields ONE entry, not one per missed interval, because a frozen process fires no
+ * timers while it sleeps — `setInterval` does not accumulate a backlog of missed ticks — and even
+ * if it did, this writes the heartbeat forward before the next tick can compare.
+ */
+export function recordTickGap(now = Date.now()): DowntimeEntry | null {
+  const last = readHeartbeat();
+  writeHeartbeat(now);
+  if (last === null) return null;
+  return recordGap(last, now, 'suspend');
 }
 
 // ── Slack last-seen cursors ───────────────────────────────────────────────────────────────────
@@ -354,6 +429,16 @@ export async function buildReport(opts: { slack?: boolean; backfill?: BackfillOp
     missedSchedules: missedSchedules(entries),
     note: 'Report only — nothing here has been run, answered, or replayed. Act on an item explicitly.',
   };
+  // A suspend gap froze the process instead of killing it, so the scheduler's boot-time catch-up
+  // scan never ran. The late timer fire on wake DOES record the windows it refuses, so the list is
+  // not empty — it is INCOMPLETE: it holds only what that fire judged. Say that, and say it for
+  // every recent suspend, not just the newest entry: a restart afterwards appends a `boot` entry
+  // but scans nothing retroactively, so gating on `last` would silently drop the warning.
+  const suspends = entries.filter(e => e.cause === 'suspend' && now - e.to <= SUSPEND_NOTE_MAX_AGE_MS);
+  if (suspends.length) {
+    const when = suspends.map(e => `${new Date(e.from).toISOString()}→${new Date(e.to).toISOString()}`).join(', ');
+    report.note += ` NOTE: a recent outage was a host SUSPEND (the process was frozen, not restarted: ${when}), so no scheduler catch-up scan ran. missedSchedules is INCOMPLETE for that gap — it lists only the windows the late timer fire itself judged on wake; any other window that elapsed inside the gap left no record at all. Check schedules whose window falls in the gap by hand.`;
+  }
   if (opts.slack !== false) {
     report.slack = last
       // The snapshot frozen at boot, not the live cursors — see DowntimeEntry.slackCursors.

package/src/server/scheduler/engine.ts

@@ -111,22 +111,10 @@ export function start(broadcast: Broadcast): void {
       continue;
     }
 
-    const policy = missedPolicy(s);
-    if (policy === 'skip') {
-      console.log(`[scheduler] missed window ${new Date(prev).toISOString()} for ${s.id} — onMissed=skip, not replaying`);
-      noteMissed(s, prev, 'skip');
-      continue;
-    }
-    if (policy === 'offer') {
-      console.log(`[scheduler] missed window ${new Date(prev).toISOString()} for ${s.id} — onMissed=offer, recorded for on-demand run`);
-      noteMissed(s, prev, 'offer');
-      continue;
-    }
-    const age = Date.now() - prev;
-    const grace = maxMissedAgeMs();
-    if (age > grace) {
-      console.log(`[scheduler] missed window ${new Date(prev).toISOString()} for ${s.id} is ${Math.round(age / 60_000)}m stale (grace ${Math.round(grace / 60_000)}m) — not replaying`);
-      noteMissed(s, prev, 'stale');
+    const verdict = judgeMissed(s, prev);
+    if (!verdict.replay) {
+      console.log(`[scheduler] not replaying ${s.id} — ${verdict.message}`);
+      noteMissed(s, prev, verdict.reason);
       continue;
     }
     catchUps.push({ id: s.id, window: prev });
@@ -347,20 +335,11 @@ export function resumeRun(scheduleId: string, sessionId: string, prompt: string)
       console.log(`[scheduler] not resuming ${scheduleId} — ${msg}`);
       return refuse('already-completed', msg);
     }
-    const policy = missedPolicy(s);
-    if (policy !== 'run') {
-      const msg = `window ${new Date(window).toISOString()} was missed and onMissed=${policy}`;
-      console.log(`[scheduler] not resuming ${scheduleId} — ${msg}`);
-      noteMissed(s, window, policy);
-      return refuse(policy === 'skip' ? 'policy-skip' : 'policy-offer', msg);
-    }
-    const age = Date.now() - window;
-    const grace = maxMissedAgeMs();
-    if (age > grace) {
-      const msg = `window ${new Date(window).toISOString()} is ${Math.round(age / 60_000)}m stale (ceiling ${Math.round(grace / 60_000)}m)`;
-      console.log(`[scheduler] not resuming ${scheduleId} — ${msg}`);
-      noteMissed(s, window, 'stale');
-      return refuse('stale', msg);
+    const verdict = judgeMissed(s, window);
+    if (!verdict.replay) {
+      console.log(`[scheduler] not resuming ${scheduleId} — ${verdict.message}`);
+      noteMissed(s, window, verdict.reason);
+      return refuse(verdict.refusal, verdict.message);
     }
   }
   console.log(`[scheduler] resuming ${scheduleId} in-place on session ${sessionId.slice(0, 30)}…`);
@@ -423,6 +402,32 @@ function missedPolicy(s: Schedule): MissedPolicy {
   return s.onMissed ?? 'run';
 }
 
+type MissedVerdict =
+  | { replay: true }
+  | { replay: false; reason: 'skip' | 'offer' | 'stale'; refusal: 'policy-skip' | 'policy-offer' | 'stale'; message: string };
+
+/**
+ * The one decision behind "this window already elapsed — may it still run?", shared by all three
+ * replay paths: the boot catch-up scan, the in-place resume, and the late timer fire.
+ *
+ * `onMissed` first (an explicit skip/offer is a standing instruction, not an age question), then
+ * the absolute staleness ceiling, which overrides even `run`. Callers do the recording, because
+ * only they know how to refuse (a return value, or `continue`).
+ */
+function judgeMissed(s: Schedule, window: number, now: number = Date.now()): MissedVerdict {
+  const when = new Date(window).toISOString();
+  const policy = missedPolicy(s);
+  if (policy !== 'run') {
+    return { replay: false, reason: policy, refusal: policy === 'skip' ? 'policy-skip' : 'policy-offer', message: `window ${when} was missed and onMissed=${policy}` };
+  }
+  const age = now - window;
+  const grace = maxMissedAgeMs();
+  if (age > grace) {
+    return { replay: false, reason: 'stale', refusal: 'stale', message: `window ${when} is ${Math.round(age / 60_000)}m stale (ceiling ${Math.round(grace / 60_000)}m)` };
+  }
+  return { replay: true };
+}
+
 function noteMissed(s: Schedule, at: number, reason: 'skip' | 'offer' | 'stale'): void {
   s.missedRun = { at, reason, noticedAt: Date.now() };
   saveSchedules(state.schedules);
@@ -455,7 +460,24 @@ function fireDue(): void {
   const now = Date.now();
   for (const s of state.schedules) {
     if (!s.enabled || s.nextRun === undefined) continue;
-    if (s.nextRun <= now) enqueueFire(s, s.nextRun);
+    if (s.nextRun > now) continue;
+    // A timer fire is normally punctual, so it is NOT treated as a missed window — `onMissed`
+    // must never gate healthy operation. But a setTimeout does not survive a wall-clock jump:
+    // when the host sleeps (lid closed) or NTP steps the clock, the process is FROZEN, not
+    // killed — no restart, so the boot catch-up scan never runs — and the overdue timer fires
+    // the elapsed window the moment the machine wakes. Firing an 08:00 job at 21:36 is exactly
+    // what the catch-up ceiling exists to prevent, reached by the one path it didn't cover.
+    // Past the ceiling we hand the window to the same judgement the other two paths use.
+    // Past the ceiling `judgeMissed` can only refuse (it replays a `run` window only while it is
+    // within the ceiling), so there is no replay branch here — the shared decision is used for WHAT
+    // to record, not whether to fire.
+    if (now - s.nextRun > maxMissedAgeMs()) {
+      const verdict = judgeMissed(s, s.nextRun, now) as Extract<MissedVerdict, { replay: false }>;
+      console.log(`[scheduler] not firing ${s.id} — ${verdict.message} (timer fired late; host suspended or clock jumped)`);
+      noteMissed(s, s.nextRun, verdict.reason);
+      continue; // the advance loop below still re-arms / retires this schedule
+    }
+    enqueueFire(s, s.nextRun);
   }
   // Advance nextRun for recurring triggers; disable fired `once` triggers
   for (const s of state.schedules) {