shraga 0.1.30 → 0.1.32

package/defaults/skills/mcp-server.md

@@ -56,6 +56,7 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (uses s
 | `put_skills_write` | Create/update a skill |
 | `get_schedules` | List scheduled jobs |
 | `post_schedules_run` | Trigger a schedule run |
+| `get_downtime` | "What did I miss?" — outage ranges + missed schedule windows + Slack backfill (reports/proposes only, fires nothing) |
 | `post_chat` | Talk to the agent — conversational, multi-turn via sessionId |
 | `get_config` | Read agent configuration |
 

package/defaults/skills/scheduler.md

@@ -134,9 +134,78 @@ Task:
   { kind: "prompt", prompt: "<text>" }
   { kind: "bash", command: "<cmd>" }
 
-Schedule: { id, name, enabled, trigger, task, scope, createdBy, nextRun?, lastRun?, runCount }
+Schedule: { id, name, enabled, trigger, task, scope, createdBy, nextRun?, lastRun?, runCount,
+            onMissed?, missedRun? }
 ```
 
+## 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`:
+
+| `onMissed` | Behaviour |
+|---|---|
+| `run` (default) | Replay the missed window — the pre-existing behaviour. |
+| `skip` | Never replay. The window is simply lost. |
+| `offer` | Don't auto-fire, but **record** it so a human/agent can run it on demand. |
+
+```bash
+curl -s -X PUT -H "Content-Type: application/json" -H "x-internal-token: $INTERNAL_API_TOKEN" \
+  http://localhost:$PORT/api/schedules/{id} -d '{ "onMissed": "offer" }' | jq .
+```
+
+- **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).
+- 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,
+  then `POST /api/schedules/{id}/run` to run the missed work on demand. It clears the moment the
+  schedule next starts a run.
+- `POST /api/schedules/{id}/run` returns **409** `{ error, reason }` when a run can't start
+  (`locked` — a run is already in flight, incl. one held across a restart; `already-completed` /
+  `already-attempted`). A `404` there really does mean the schedule doesn't exist.
+
+## "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.
+
+```bash
+curl -s -H "x-internal-token: $INTERNAL_API_TOKEN" "http://localhost:$PORT/api/downtime" | jq .
+curl -s -H "x-internal-token: $INTERNAL_API_TOKEN" "http://localhost:$PORT/api/downtime?slack=0" | jq .   # skip the Slack read
+```
+
+Returns `{ heartbeat, downtime[], lastDowntime, missedSchedules[], slack }`:
+
+- **`missedSchedules[]`** — the `missedRun` records above, joined to the outage that covers them,
+  each with a `proposal` string. It does **not** re-derive which windows were missed; the
+  scheduler owns that.
+- **`slack`** — messages that arrived during the last outage, fetched **on demand only** (never at
+  boot) via `conversations.history`, deduped by `client_msg_id`. History, not event replay: Slack's
+  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
+    `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
+    `SLACK_AGENT_CHANNEL` — so a first deploy, or a channel quiet before the outage, is not
+    invisible.
+  - **`channels[].truncated: true`** means the page cap (5 × 200 per channel) was hit with more
+    still waiting. `conversations.history` returns newest-first, so what's missing is the
+    **start** of the outage. The report's `note` also says `INCOMPLETE` — treat it as such.
+
+**It reports and proposes — nothing auto-fires.** Acting on an item is always an explicit second
+call: `POST /api/schedules/{id}/run` (409 + `reason` if it can't start). Same data is exposed as
+the MCP `get_downtime` tool when `MCP_ALL_TOOLS=true`.
+
 ## Emitting events (to fire event-triggered schedules)
 
 Any caller that can present shraga auth can push an event onto the bus:

package/defaults/skills/self-aware.md

@@ -123,7 +123,16 @@ 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`.
+- **Time**: `cron` / `interval` / `once`. A window missed while you were down 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
+    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
+    08:00 job is the incident this exists to prevent. Details: the **scheduler** skill.
 - **Event** (`{ kind:'event', source, match? }`) — fires when a matching event hits the event bus. `match` is an AND-filter of payload dot-paths → values. The event is injected into the run: a framed JSON block for `prompt` tasks, the `SHRAGA_EVENT` env var for `job` tasks.
 - Events arrive via `POST /api/events/:source` (auth-gated) or `ctx.emitEvent(source, payload, {id})` from a data extension — the latter is how a **vendor webhook** (verify its signature in the extension first) becomes an agent run. Bus + dispatcher: `src/server/events/`; fire path: `scheduler/engine.ts` `fireEvent()`. Full how-to (create / match / emit): the **scheduler** skill.
 - **Built-in lifecycle source**: the system auto-emits `schedule.finished` (`{ scheduleId, name, status, sessionId, sessionUrl?, error? }`) when a time/manual run completes — react to your own runs (e.g. `match: { status: "error" }` → notify). Event-triggered runs don't emit it (loop guard). More internal sources can be added with one `emitEvent()` at the milestone.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shraga",
-  "version": "0.1.30",
+  "version": "0.1.32",
   "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

@@ -41,6 +41,7 @@ import { registerModuleRoutes, reconcileInstalledModules } from './modules/index
 import { hydrateSlackUserToken } from './slack/oauth.ts';
 import { registerMcpOAuthRoutes } from './mcp-oauth.ts';
 import { registerEventRoutes } from './events/routes.ts';
+import { startHeartbeat, recordBootGap, buildReport } from './downtime.ts';
 import { registerWebhook } from './events/webhook.ts';
 import { startEventDispatcher } from './events/dispatcher.ts';
 import { seedOperators } from './contacts.ts';
@@ -390,6 +391,20 @@ function scheduleIfVisible(id: string, uid: string, isOwner = false): Schedule |
   return undefined;
 }
 
+// "What did I miss?" — the on-demand downtime report. Read-only and INERT: it returns outage
+// ranges, the windows phase 1 deliberately did not replay (`missedRun`), and the Slack messages
+// that arrived while we were down, each with a PROPOSAL. Running any of it is a separate,
+// explicit call (POST /api/schedules/:id/run). `?slack=0` skips the Slack read.
+app.get('/api/downtime', requireAuth, async (req, res) => {
+  try {
+    const slack = String(req.query.slack ?? '1') !== '0';
+    res.json(await buildReport({ slack }));
+  } catch (err) {
+    console.error('[downtime] report failed:', err);
+    res.status(500).json({ error: (err as Error).message });
+  }
+});
+
 app.get('/api/schedules', requireAuth, (req, res) => {
   const user = (req as any).user;
   const schedules = scheduler.listSchedules().filter((s) => user.isOwner || s.scope === 'system' || s.createdBy.uid === user.uid);
@@ -414,6 +429,7 @@ app.post('/api/schedules', requireAuth, (req, res) => {
     enabled: body.enabled ?? true,
     trigger: body.trigger as Schedule['trigger'],
     task: body.task as Schedule['task'],
+    onMissed: body.onMissed,
     scope: 'user',
     createdBy: { uid: user.uid, email: user.email },
     createdAt: now,
@@ -438,6 +454,7 @@ app.put('/api/schedules/:id', requireAuth, (req, res) => {
     enabled: body.enabled ?? existing.enabled,
     trigger: (body.trigger ?? existing.trigger) as Schedule['trigger'],
     task: (body.task ?? existing.task) as Schedule['task'],
+    onMissed: body.onMissed ?? existing.onMissed,
   };
   const result = scheduler.upsertSchedule(updated);
   if (!result.ok) return res.status(400).json({ error: result.error });
@@ -469,9 +486,15 @@ app.post('/api/schedules/:id/run', requireAuth, (req, res) => {
   const id = String(req.params.id);
   if (!scheduleIfVisible(id, user.uid, user.isOwner)) return res.status(404).json({ error: 'Not found' });
   const override = typeof req.body?.override === 'string' ? req.body.override.trim() || undefined : undefined;
-  const sessionId = scheduler.runNow(id, override);
-  if (!sessionId) return res.status(404).json({ error: 'Not found' });
-  res.json({ sessionId });
+  const outcome = scheduler.runNow(id, override);
+  // A refusal here is a CONFLICT with the schedule's current state (a run already holds the
+  // cross-restart lock, the period is already done), not a missing resource — 404 sent operators
+  // hunting for a schedule that plainly exists.
+  if (!outcome.ok) {
+    if (outcome.reason === 'unknown-schedule') return res.status(404).json({ error: 'Not found' });
+    return res.status(409).json({ error: outcome.message, reason: outcome.reason });
+  }
+  res.json({ sessionId: outcome.sessionId, queued: outcome.queued ?? false });
 });
 
 app.post('/api/schedules/:id/cancel', requireAuth, (req, res) => {
@@ -1042,6 +1065,13 @@ setBroadcaster(broadcast); // let session-bus push async events (e.g. an add-on'
 ensureWorkspaceDir();
 watchWorkspace((event) => broadcast({ type: 'workspace_change', ...event }));
 if (!PASSIVE) {
+  // BEFORE anything that could take time: the gap is measured as (now - last heartbeat), so it must
+  // be read and re-stamped while "now" still means boot — a slow start would otherwise inflate the
+  // gap, or (once startHeartbeat is running) erase it. Order vs the scheduler's catch-up doesn't
+  // matter for the join: missedSchedules() reads the two files independently, at report time.
+  // Passive twins never write here — single-active-writer, same rule as the scheduler.
+  recordBootGap();
+  startHeartbeat();
   scheduler.start(broadcast);
   startEventDispatcher();
   // Modules reconcile MUST follow scheduler.start(): upsertSchedule mutates the engine's
@@ -1102,6 +1132,8 @@ async function activateConsumers() {
   console.log('[server] ACTIVATING — starting consumers and background writers');
   await dataSync.init();
   syncVendorRepos().catch(err => console.warn('[vendor-sync] error:', (err as Error).message));
+  recordBootGap();
+  startHeartbeat();
   scheduler.start(broadcast);
   startEventDispatcher();
   mountFeatures({ app, requireAuth, broadcast, passive: false });
@@ -1806,7 +1838,22 @@ async function recoverInterruptedSessions() {
       });
       const resumePrompt = 'Your previous response was cut off by a server restart. The partial response has been preserved above. Continue from where you left off, and avoid repeating any side-effects (e.g. messages already sent) that may have completed before the interruption.';
       setRunStatus(s.sessionId, 'idle');
-      scheduler.resumeRun(s.scheduleId!, s.sessionId, resumePrompt);
+      const outcome = scheduler.resumeRun(s.scheduleId!, s.sessionId, resumePrompt);
+      if (!outcome.ok) {
+        // The refusal is now the EXPECTED outcome after a long outage (stale window / onMissed).
+        // Close the session out exactly like the not-resumable branch above — otherwise
+        // scheduleRunStatus stays 'running', the sidebar shows it busy forever, and it can never
+        // self-heal because getRunningSessions() filters on runStatus, which is already idle.
+        appendMessage(s.sessionId, {
+          id: crypto.randomUUID(),
+          role: 'assistant',
+          blocks: [{ type: 'error', text: `Not resumed after the server restart — ${outcome.message} (${outcome.reason}).` }],
+        });
+        updateScheduledSessionStatus(s.sessionId, 'error');
+        scheduler.clearRunningMarker(s.scheduleId!);
+        console.log(`[recovery] scheduler session ${s.sessionId.slice(0, 8)} (${s.scheduleId}) — resume refused (${outcome.reason}): ${outcome.message}`);
+        continue;
+      }
       console.log(`[recovery] resuming scheduler session ${s.sessionId.slice(0, 8)} (${s.scheduleId}) in-place`);
       continue;
     }

package/src/server/downtime.ts

@@ -0,0 +1,366 @@
+/**
+ * Downtime recovery — "what happened while I was down?"
+ *
+ * This box is deliberately NOT always-on. When it comes back, the honest question is not "what
+ * should I replay?" but "what did I miss, and what do you want me to do about it?". Phase 1
+ * (scheduler run lock + `onMissed`) already stopped the blind replay that finished an 08:00 job at
+ * 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.
+ * Acting on a finding is always an explicit follow-up (`POST /api/schedules/:id/run`).
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync } from 'node:fs';
+import { dataPath } from './paths.ts';
+import { loadSchedules } from './scheduler/storage.ts';
+import type { MissedRun } from './scheduler/types.ts';
+
+const HEARTBEAT_FILE = dataPath('state/heartbeat.json');
+const DOWNTIME_FILE = dataPath('state/downtime.json');
+const SLACK_CURSORS_FILE = dataPath('state/slack-cursors.json');
+
+/** How often liveness is stamped to disk. */
+export const HEARTBEAT_INTERVAL_MS = Number(process.env.HEARTBEAT_INTERVAL_MS ?? 60_000);
+
+/**
+ * Gap above which an absence counts as downtime — 3 heartbeat intervals (3m by default).
+ *
+ * The worst case for a CLEAN restart is: the last heartbeat landed a tick before shutdown (up to
+ * 1 interval stale) + the process restart itself. One interval is therefore already "normal", and
+ * two leaves no margin for a slow boot, a loaded box, or clock/write skew — either would log
+ * phantom downtime on every deploy, which is worse than useless (it would drown the real outage).
+ * Three intervals is comfortably above every clean-restart case and still far below anything a
+ * human would call an outage: a real power cut is minutes-to-hours, not 3 minutes.
+ */
+export const DOWNTIME_THRESHOLD_MS = Number(process.env.DOWNTIME_THRESHOLD_MS ?? 3 * HEARTBEAT_INTERVAL_MS);
+
+/**
+ * Bounded history: the last 20 outages. This is a "what did I miss" aid, not an uptime archive —
+ * the report only ever reads the recent tail, and the joins that make an entry actionable
+ * (`missedRun`, Slack history) age out long before 20 outages do. 20 keeps the file trivially
+ * small while still covering many months on a box that is off occasionally.
+ */
+export const DOWNTIME_HISTORY_MAX = 20;
+
+export interface DowntimeEntry {
+  /** Last proven-alive moment (the final heartbeat before the gap). */
+  from: number;
+  /** When the process came back. */
+  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.
+   */
+  slackCursors?: Record<string, string>;
+}
+
+interface DowntimeFile { entries: DowntimeEntry[] }
+
+// ── storage (same conventions as scheduler/storage.ts: tmp file + rename) ──────────────────────
+
+function readJson<T>(file: string, fallback: T): T {
+  if (!existsSync(file)) return fallback;
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf-8'));
+    return parsed && typeof parsed === 'object' ? (parsed as T) : fallback;
+  } catch (err) {
+    console.error(`[downtime] failed to parse ${file}, starting fresh:`, err);
+    return fallback;
+  }
+}
+
+function writeJsonAtomic(file: string, value: unknown): void {
+  mkdirSync(dataPath('state'), { recursive: true });
+  const tmp = `${file}.tmp`;
+  writeFileSync(tmp, JSON.stringify(value, null, 2));
+  renameSync(tmp, file);
+}
+
+// ── heartbeat ─────────────────────────────────────────────────────────────────────────────────
+
+export function readHeartbeat(): number | null {
+  const hb = readJson<{ at?: number }>(HEARTBEAT_FILE, {});
+  return Number.isFinite(hb.at) ? (hb.at as number) : null;
+}
+
+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. */
+export function startHeartbeat(intervalMs = HEARTBEAT_INTERVAL_MS): () => void {
+  writeHeartbeat();
+  const timer = setInterval(() => {
+    try { writeHeartbeat(); } catch (err) { console.error('[downtime] heartbeat write failed:', err); }
+  }, intervalMs);
+  timer.unref?.();
+  return () => clearInterval(timer);
+}
+
+// ── downtime ledger ───────────────────────────────────────────────────────────────────────────
+
+export function listDowntime(): DowntimeEntry[] {
+  return readJson<DowntimeFile>(DOWNTIME_FILE, { entries: [] }).entries ?? [];
+}
+
+/**
+ * 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
+ * measure from) records NOTHING, so the ledger only ever contains genuine outages.
+ */
+export function recordBootGap(bootTime = Date.now()): DowntimeEntry | null {
+  const last = readHeartbeat();
+  // 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;
+
+  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;
+}
+
+// ── Slack last-seen cursors ───────────────────────────────────────────────────────────────────
+
+/** channelId → { ts: last message ts we observed, at: when we observed it }. */
+export interface SlackCursor { ts: string; at: number }
+type SlackCursors = Record<string, SlackCursor>;
+
+export function listSlackCursors(): SlackCursors {
+  return readJson<SlackCursors>(SLACK_CURSORS_FILE, {});
+}
+
+/**
+ * Record that we saw `ts` in `channel`. Called for every inbound Slack message the ingress hands
+ * us (whether or not the agent chose to answer it) — it is a LIVE TAIL pointer: it says where the
+ * stream is now, not what was handled, and after a recovery it runs ahead of the outage backlog
+ * within one message (which is why an outage snapshots it, see `DowntimeEntry.slackCursors`).
+ * Monotonic: an out-of-order event can't rewind the cursor and cause a re-fetch of already-seen
+ * history. Slack ts values carry 16 significant digits, so they are compared as STRINGS — `Number`
+ * rounds them to a double and makes same-second messages compare equal.
+ */
+export function noteSlackSeen(channel: string, ts: string): void {
+  if (!channel || !ts) return;
+  try {
+    const cursors = listSlackCursors();
+    const prev = cursors[channel];
+    if (prev && prev.ts >= ts) return;
+    cursors[channel] = { ts, at: Date.now() };
+    writeJsonAtomic(SLACK_CURSORS_FILE, cursors);
+  } catch (err) {
+    console.error('[downtime] failed to record Slack cursor:', err);
+  }
+}
+
+export interface BackfilledMessage {
+  channel: string;
+  ts: string;
+  user?: string;
+  botId?: string;
+  text: string;
+  clientMsgId?: string;
+  /** True when the text mentions the agent (bot or user id) — the subset most likely to need action. */
+  mentionsAgent: boolean;
+}
+
+export interface SlackBackfill {
+  /** `truncated` = the page cap was hit with more still waiting, so the OLDEST part of the outage is missing. */
+  channels: { channel: string; from: string; fetched: number; truncated?: boolean; error?: string }[];
+  messages: BackfilledMessage[];
+  skipped?: string;
+}
+
+/** Injected so tests (and any future caller) can drive the join without a live Slack workspace. */
+export type SlackHistoryFn = (method: string, body: Record<string, unknown>) => Promise<any>;
+
+export interface BackfillOptions {
+  /** Defaults to the shared mcp-slack-use client (`slackPost`) — the app's ONE Slack seam. */
+  history?: SlackHistoryFn;
+  /** Agent ids to flag mentions against. */
+  agentIds?: string[];
+  /** Safety valve on a very long outage: pages of 200 per channel. */
+  maxPages?: number;
+  /**
+   * channelId → last-seen ts AS OF the outage (`DowntimeEntry.slackCursors`). The live cursors are
+   * deliberately NOT used as a floor: they advance with the stream and would skip the backlog.
+   */
+  cursors?: Record<string, string>;
+}
+
+/**
+ * Fetch what arrived during `range` from each channel we know about, on demand.
+ *
+ * Why history and not event replay: Slack's Events API retries a failed delivery for only ~30
+ * minutes and then drops the event PERMANENTLY — after a multi-hour outage there is nothing left
+ * to redeliver. `conversations.history` keeps the same messages readable for days (retention), so
+ * it, not the event stream, is the durable recovery source. This is also why it is on-demand only
+ * and never runs at boot: it is a paid, rate-limited read of someone else's system, and its result
+ * is a REPORT, not a work queue.
+ */
+export async function fetchSlackBackfill(range: { from: number; to?: number }, opts: BackfillOptions = {}): Promise<SlackBackfill> {
+  // Which channels to ask about: the ones seen at the time of the outage, the ones seen since
+  // (a channel that only became active during/after the outage still has missed history), and the
+  // agent's own channel — which must be readable on a first deploy, before any traffic at all.
+  const snapshot = opts.cursors ?? {};
+  const channels = [...new Set([
+    ...Object.keys(snapshot),
+    ...Object.keys(listSlackCursors()),
+    ...(process.env.SLACK_AGENT_CHANNEL ? [process.env.SLACK_AGENT_CHANNEL] : []),
+  ])];
+  if (!channels.length) return { channels: [], messages: [], skipped: 'no channels seen yet (no cursor recorded, no SLACK_AGENT_CHANNEL)' };
+
+  let history = opts.history;
+  let agentIds = (opts.agentIds ?? []).filter(Boolean);
+  if (!history) {
+    try {
+      // The app's ONE Slack seam (slack/api.ts re-exports the mcp-slack-use client). No new HTTP
+      // client, no second token-resolution path.
+      const api = await import('./slack/api.ts');
+      history = (method, body) => api.slackPost(method, body);
+      if (!agentIds.length) {
+        const ids = await Promise.all([api.getBotUserId().catch(() => null), api.getAgentUserId().catch(() => null)]);
+        agentIds = ids.filter((id): id is string => !!id);
+      }
+    } catch (err) {
+      return { channels: [], messages: [], skipped: `Slack client unavailable: ${(err as Error).message}` };
+    }
+  }
+
+  const maxPages = opts.maxPages ?? 5;
+  const out: SlackBackfill = { channels: [], messages: [] };
+  const seen = new Set<string>();
+
+  for (const channel of channels) {
+    // Start at the outage start, raised only by a SNAPSHOT cursor that is later still (a channel
+    // whose last-seen message post-dates `range.from` — we already saw those). Never raised by the
+    // live cursor: that one has moved on with the stream and would hide the whole backlog.
+    const oldest = Math.max(Number(snapshot[channel]) || 0, range.from / 1000);
+    let fetched = 0;
+    let pageCursor: string | undefined;
+    let error: string | undefined;
+    let truncated = false;
+    try {
+      for (let page = 0; page < maxPages; page++) {
+        const body: Record<string, unknown> = { channel, oldest: String(oldest), limit: 200 };
+        if (range.to) body.latest = String(range.to / 1000);
+        if (pageCursor) body.cursor = pageCursor;
+        const res = await history('conversations.history', body);
+        if (!res?.ok) { error = String(res?.error ?? 'unknown Slack error'); break; }
+        for (const m of (res.messages ?? []) as any[]) {
+          // Dedupe on client_msg_id (Slack's own idempotency key), falling back to channel+ts for
+          // messages that carry none (bot posts, joins). Paging overlap and a re-run of this
+          // report must not double-report the same message.
+          const key = m.client_msg_id ?? `${channel}:${m.ts}`;
+          if (seen.has(key)) continue;
+          seen.add(key);
+          const text = String(m.text ?? '');
+          out.messages.push({
+            channel,
+            ts: String(m.ts),
+            user: m.user,
+            botId: m.bot_id,
+            text,
+            clientMsgId: m.client_msg_id,
+            mentionsAgent: agentIds.some(id => text.includes(id)),
+          });
+          fetched++;
+        }
+        pageCursor = res.response_metadata?.next_cursor || undefined;
+        if (!res.has_more || !pageCursor) break;
+        // Still more waiting when the cap is reached: say so. conversations.history returns
+        // NEWEST-first, so what we dropped is the START of the outage — the oldest and most likely
+        // to have been missed. A silently short report would read as "that's everything".
+        if (page === maxPages - 1) truncated = true;
+      }
+    } catch (err) {
+      error = (err as Error).message;
+    }
+    out.channels.push({ channel, from: String(oldest), fetched, ...(truncated ? { truncated } : {}), ...(error ? { error } : {}) });
+  }
+  out.messages.sort((a, b) => Number(a.ts) - Number(b.ts));
+  return out;
+}
+
+// ── the on-demand report ──────────────────────────────────────────────────────────────────────
+
+export interface MissedScheduleReport {
+  id: string;
+  name: string;
+  missedRun: MissedRun;
+  /** The outage this window falls inside, if any. */
+  downtime: DowntimeEntry | null;
+  /** What the USER can choose to do. Nothing here runs it. */
+  proposal: string;
+}
+
+export interface DowntimeReport {
+  now: number;
+  heartbeat: { at: number; ageMs: number } | null;
+  downtime: DowntimeEntry[];
+  lastDowntime: DowntimeEntry | null;
+  missedSchedules: MissedScheduleReport[];
+  slack?: SlackBackfill;
+  note: string;
+}
+
+/**
+ * Join phase 1's `missedRun` records to the outage that covers them.
+ *
+ * It does NOT recompute which windows were missed — the scheduler owns that decision (policy +
+ * staleness ceiling) and re-deriving it here would be a second, silently-diverging opinion.
+ *
+ * Read from schedules.json rather than the engine's in-memory list: the engine `saveSchedules()`
+ * on every mutation (incl. `noteMissed`), so disk is current, and reading it keeps this module
+ * independent of whether the engine has been started — which matters because a passive twin and
+ * this report both need the answer without owning the scheduler.
+ */
+export function missedSchedules(entries = listDowntime()): MissedScheduleReport[] {
+  return loadSchedules()
+    .filter((s): s is typeof s & { missedRun: MissedRun } => !!s.missedRun)
+    .map((s) => ({
+      id: s.id,
+      name: s.name,
+      missedRun: s.missedRun,
+      downtime: entries.find(e => s.missedRun.at >= e.from && s.missedRun.at <= e.to) ?? null,
+      proposal: `POST /api/schedules/${s.id}/run to run this window now (nothing has run it)`,
+    }));
+}
+
+/**
+ * Build the "what did I miss?" answer. Read-only apart from the Slack fetch, which is a read of
+ * Slack. Callers pass `slack: false` to skip the network entirely.
+ */
+export async function buildReport(opts: { slack?: boolean; backfill?: BackfillOptions } = {}): Promise<DowntimeReport> {
+  const now = Date.now();
+  const entries = listDowntime();
+  const last = entries[entries.length - 1] ?? null;
+  const hb = readHeartbeat();
+  const report: DowntimeReport = {
+    now,
+    heartbeat: hb === null ? null : { at: hb, ageMs: now - hb },
+    downtime: entries,
+    lastDowntime: last,
+    missedSchedules: missedSchedules(entries),
+    note: 'Report only — nothing here has been run, answered, or replayed. Act on an item explicitly.',
+  };
+  if (opts.slack !== false) {
+    report.slack = last
+      // The snapshot frozen at boot, not the live cursors — see DowntimeEntry.slackCursors.
+      ? await fetchSlackBackfill({ from: last.from }, { cursors: last.slackCursors, ...opts.backfill })
+      : { channels: [], messages: [], skipped: 'no recorded downtime to backfill' };
+    const cut = report.slack.channels.filter(c => c.truncated).map(c => c.channel);
+    if (cut.length) report.note += ` INCOMPLETE: hit the page cap on ${cut.join(', ')} — the OLDEST part of the outage is missing from this report.`;
+  }
+  return report;
+}

package/src/server/mcp-server.ts

@@ -9,6 +9,7 @@ import { listWorkspaceTree, readWorkspaceFile, safeResolve, searchWorkspace } fr
 import { listSkills, getSkill, saveSkill } from './skills.ts';
 import { getAllSessions, loadConversation, isSessionLocked } from './sessions.ts';
 import * as scheduler from './scheduler/index.ts';
+import { buildReport } from './downtime.ts';
 import { getAgentConfig } from './claude.ts';
 import { validateApiKey } from './api-keys.ts';
 import { verifyMcpToken } from './auth.ts';
@@ -247,8 +248,24 @@ export function createShragaMcp(deps: McpServerDeps) {
       if (!id) return json({ error: 'id required' }, { status: 400 });
       const schedule = scheduler.getSchedule(id);
       if (!schedule) return json({ error: 'Schedule not found' }, { status: 404 });
-      scheduler.runNow(id);
-      return json({ ok: true, id });
+      const outcome = scheduler.runNow(id);
+      if (!outcome.ok) return json({ error: outcome.message, reason: outcome.reason }, { status: 409 });
+      return json({ ok: true, id, sessionId: outcome.sessionId, queued: outcome.queued ?? false });
+    } catch (e) { return json({ error: errMessage(e) }, { status: 500 }); }
+  });
+
+  // ── Downtime ─────────────────────────────────────────────────────────────
+
+  base.describeMCP('/downtime', 'GET', {
+    description: 'Answer "what did I miss while I was down?". Returns recorded downtime ranges, the schedule windows that were deliberately NOT replayed (missedRun), and the Slack messages that arrived during the last outage. Reports and proposes only — it never runs, replays, or answers anything; act on an item with the schedules/run tool.',
+    params: {
+      slack: { description: 'Set "0" to skip the Slack history read (no network).', type: 'string' },
+    },
+    annotations: { readOnlyHint: true },
+  });
+  router.get('/downtime', async (req: any) => {
+    try {
+      return json(await buildReport({ slack: str(req.query.slack) !== '0' }));
     } catch (e) { return json({ error: errMessage(e) }, { status: 500 }); }
   });
 

package/src/server/scheduler/engine.ts

@@ -1,10 +1,10 @@
-import { loadSchedules, saveSchedules, readCompletionMarker, writeCompletionMarker, readRunningMarker, isProcessAlive, loadThrottleState, saveThrottleState } from './storage.ts';
+import { loadSchedules, saveSchedules, readCompletionMarker, writeCompletionMarker, readRunningMarker, isProcessAlive, loadThrottleState, saveThrottleState, acquireRunLock, clearRunningMarker, markRunStarted } from './storage.ts';
 import { computeNextRun, computePrevRun, validateTrigger } from './timing.ts';
 import { runSchedule, type ResumeOptions, type EventContext } from './runner.ts';
 import { backfillScope, ensureBuiltinSchedules } from './builtins.ts';
 import { emitEvent } from '../events/bus.ts';
 import { getSessionUrl } from '../shraga-config.ts';
-import type { Schedule } from './types.ts';
+import type { Schedule, MissedPolicy, RunOutcome, RunRefusal } from './types.ts';
 
 type Broadcast = (data: object) => void;
 
@@ -26,6 +26,18 @@ interface RuntimeState {
 }
 
 const QUEUE_CAP = 5;
+/** Catch-up fires are delayed so MCP servers finish initializing first. Read per call so tests
+ *  (and an operator) can shorten it. */
+const catchupDelayMs = () => Number(process.env.SCHEDULER_CATCHUP_DELAY_MS ?? 10_000);
+/** Hard ceiling on how late a missed window may still be replayed, regardless of `onMissed`.
+ *  A missed window is never more than one period old, so a period-relative bound alone can never
+ *  suppress anything — yet replaying an 08:00 report at 22:00 is not the job the schedule
+ *  describes. This absolute cap is therefore the entire rule.
+ *
+ *  Deliberately NOT `min(period, cap)`: a cron missed window comes from `computePrevRun`, so its
+ *  age is always strictly less than one period — a period-relative term can never suppress
+ *  anything, and `min(period, cap)` is provably identical to `cap`. */
+const maxMissedAgeMs = () => Number(process.env.SCHEDULER_MAX_MISSED_AGE_MS ?? 6 * 60 * 60 * 1000);
 /** Max setTimeout delay (2^31-1 ms ≈ 24.8 days); longer delays overflow and fire immediately. */
 const MAX_TIMER_MS = 2_147_483_647;
 /** Only the designated instance fires schedules (DATA_SYNC_SCHEDULER_ACTIVE=true).
@@ -71,38 +83,67 @@ export function start(broadcast: Broadcast): void {
     }
   }
   // Catch up missed cron fires (e.g. process was down when cron should have fired)
-  const catchUps: string[] = [];
+  const catchUps: { id: string; window: number }[] = [];
   for (const s of state.schedules) {
     if (!s.enabled || s.trigger.kind !== 'cron') continue;
     const prev = computePrevRun(s.trigger);
     if (prev === null) continue;
     const lastAt = s.lastRun?.at;
     if (lastAt === undefined) continue; // never ran — nothing to catch up
-    if (lastAt < prev) {
-      const marker = readCompletionMarker(s.id);
-      if (marker && marker.completedAt >= prev) {
-        console.log(`[scheduler] skipping catch-up for ${s.id} — already completed at ${new Date(marker.completedAt).toISOString()} by ${marker.triggeredBy}`);
-        continue;
-      }
-      const running = readRunningMarker(s.id);
-      if (running && isProcessAlive(running.pid)) {
-        console.log(`[scheduler] skipping catch-up for ${s.id} — still running (pid ${running.pid}, started ${new Date(running.startedAt).toISOString()})`);
-        continue;
-      }
-      catchUps.push(s.id);
+    if (lastAt >= prev) continue;
+
+    const marker = readCompletionMarker(s.id);
+    if (marker && marker.completedAt >= prev) {
+      console.log(`[scheduler] skipping catch-up for ${s.id} — already completed at ${new Date(marker.completedAt).toISOString()} by ${marker.triggeredBy}`);
+      continue;
+    }
+    // An ATTEMPT on this window counts too: a run that errored or was killed already had its
+    // shot. Replaying it on the next boot is exactly the duplicate-fire this guards.
+    if (marker?.attemptWindow !== undefined && marker.attemptWindow >= prev) {
+      console.log(`[scheduler] skipping catch-up for ${s.id} — window ${new Date(prev).toISOString()} already attempted (${marker.status ?? 'started'})`);
+      continue;
+    }
+    // Someone is already on it — either another instance, or (far more common) the recovery
+    // path that resumed the interrupted run in-place moments ago.
+    const running = readRunningMarker(s.id);
+    if (running && isProcessAlive(running.pid)) {
+      console.log(`[scheduler] skipping catch-up for ${s.id} — still running (pid ${running.pid}, started ${new Date(running.startedAt).toISOString()})`);
+      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');
+      continue;
+    }
+    catchUps.push({ id: s.id, window: prev });
   }
   if (catchUps.length) {
-    console.log(`[scheduler] catch-up: ${catchUps.join(', ')} (delayed 10s for MCP init)`);
+    console.log(`[scheduler] catch-up: ${catchUps.map((c) => c.id).join(', ')} (delayed ${catchupDelayMs()}ms for MCP init)`);
     setTimeout(() => {
-      for (const id of catchUps) {
+      for (const { id, window } of catchUps) {
         const s = getSchedule(id);
-        if (s?.enabled) {
-          console.log(`[scheduler] catch-up: firing ${id}`);
-          runNow(id);
-        }
+        if (!s?.enabled) continue;
+        console.log(`[scheduler] catch-up: firing ${id}`);
+        // NOT runNow(): a catch-up is not a manual run. It must go through the same
+        // completion/attempt/lock guards as any timer fire, so that whatever claimed this
+        // window first (typically the in-place resume) makes this a no-op.
+        enqueueFire(s, window);
       }
-    }, 10_000);
+    }, catchupDelayMs());
   }
 
   saveSchedules(state.schedules);
@@ -125,6 +166,9 @@ export function getSchedule(id: string): Schedule | undefined {
 export function upsertSchedule(s: Schedule): { ok: true; schedule: Schedule } | { ok: false; error: string } {
   const err = validateTrigger(s.trigger);
   if (err) return { ok: false, error: err };
+  if (s.onMissed !== undefined && !MISSED_POLICIES.includes(s.onMissed)) {
+    return { ok: false, error: `Invalid onMissed "${s.onMissed}" (expected ${MISSED_POLICIES.join(' | ')})` };
+  }
 
   s.updatedAt = Date.now();
   if (s.enabled) {
@@ -180,9 +224,9 @@ export function toggleSchedule(id: string, enabled: boolean): Schedule | null {
   return s;
 }
 
-export function runNow(id: string, override?: string): string | null {
+export function runNow(id: string, override?: string): RunOutcome {
   const s = getSchedule(id);
-  if (!s) return null;
+  if (!s) return refuse('unknown-schedule', `No schedule ${id}`);
   return enqueueFire(s, Date.now(), override, true);
 }
 
@@ -275,22 +319,116 @@ export function cancelRun(id: string): boolean {
  * side-effects, e.g. a second Slack post). Mirrors the web/slack restart-resume path.
  * No-op if the schedule is unknown or already running.
  */
-export function resumeRun(scheduleId: string, sessionId: string, prompt: string): string | null {
+export function resumeRun(scheduleId: string, sessionId: string, prompt: string): RunOutcome {
   const s = getSchedule(scheduleId);
   if (!s) {
     console.warn(`[scheduler] resumeRun: unknown schedule ${scheduleId}`);
-    return null;
+    return refuse('unknown-schedule', `No schedule ${scheduleId}`);
   }
   if (state.running.has(scheduleId)) {
     console.log(`[scheduler] resumeRun: ${scheduleId} already running — skipping resume`);
-    return null;
+    return refuse('already-running', `${s.name} is already running`);
+  }
+  const window = interruptedWindow(s);
+  // A resume continues an existing conversation rather than starting a fresh one, so it dodges
+  // the duplicate-side-effect problem — but it does NOT dodge the "is this work still the work
+  // the schedule asked for" problem. Finishing the 08:00 report at 22:00 is the incident. So the
+  // resume path answers to the same onMissed policy and the same staleness ceiling as catch-up —
+  // for EVERY trigger kind, not just cron (interval/once/event have no catch-up path at all, so
+  // resume is their only gate).
+  if (window !== null) {
+    // Someone already finished this window — typically a catch-up that won the boot race and has
+    // since completed, so the run lock it held is gone. Resuming now would redo work that is
+    // already done: the duplicate fire, one step later. (An *attempt* on this window is NOT a
+    // refusal — the interrupted run we are resuming recorded one itself.)
+    const marker = readCompletionMarker(scheduleId);
+    if (marker && marker.completedAt >= window) {
+      const msg = `window ${new Date(window).toISOString()} already completed at ${new Date(marker.completedAt).toISOString()} by ${marker.triggeredBy}`;
+      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);
+    }
   }
   console.log(`[scheduler] resuming ${scheduleId} in-place on session ${sessionId.slice(0, 30)}…`);
-  return startRun(s, Date.now(), undefined, { sessionId, prompt });
+  return startRun(s, window ?? Date.now(), undefined, { sessionId, prompt });
 }
 
 // ── Internals ───────────────────────────────────────────────────────────────
 
+const MISSED_POLICIES: MissedPolicy[] = ['run', 'skip', 'offer'];
+
+function refuse(reason: RunRefusal, message: string): RunOutcome {
+  return { ok: false, reason, message };
+}
+
+/**
+ * The window the interrupted run was covering — what "how late is this?" is measured against.
+ *
+ * For `cron` the window is derivable from the expression itself (`computePrevRun`), and that is
+ * preferred: it is correct even for legacy state written before markers recorded a window.
+ *
+ * `interval`/`once`/`event` have no schedule-derivable grid — but they are not therefore timeless.
+ * An interval run interrupted 14h ago is exactly as stale as a cron one, and it has no catch-up
+ * path to be caught by. So for those the window is the one the interrupted run ITSELF claimed,
+ * read back off the markers already on disk: the run lock's `window` (stamped by `acquireRunLock`
+ * at fire time), else its `startedAt`, else the attempt ledger, else the at-start `lastRun.at`.
+ * Only a schedule with no trace of ever having started has no window — and nothing to resume.
+ */
+function interruptedWindow(s: Schedule): number | null {
+  const prev = computePrevRun(s.trigger);
+  if (prev !== null) return prev;
+  const running = readRunningMarker(s.id);
+  if (running?.window !== undefined) return running.window;
+  if (running?.startedAt) return running.startedAt;
+  const marker = readCompletionMarker(s.id);
+  if (marker?.attemptWindow !== undefined) return marker.attemptWindow;
+  if (marker?.lastAttemptAt) return marker.lastAttemptAt;
+  return s.lastRun?.at ?? null;
+}
+
+/** Persist the terminal outcome of an attempt without touching the last SUCCESSFUL completion.
+ *  Every non-ok exit — reported failure or unexpected throw — must land here, else the marker
+ *  stays `started` forever and a crash is indistinguishable from a throw. */
+function recordAttemptOutcome(scheduleId: string, firedAt: number, at: number, status: 'error' | 'aborted' | 'started'): void {
+  const prev = readCompletionMarker(scheduleId);
+  writeCompletionMarker({
+    completedAt: prev?.completedAt ?? 0,
+    triggeredBy: 'scheduler',
+    scheduleId,
+    lastAttemptAt: prev?.lastAttemptAt ?? at,
+    attemptWindow: prev?.attemptWindow ?? firedAt,
+    status,
+  });
+}
+
+/** Default is `run`: it is what every existing schedule already does, and schedules.json has no
+ *  `onMissed` field on any of them — defaulting to anything else would silently change the
+ *  behaviour of live automations on upgrade. The unbounded-replay hazard that made `run`
+ *  dangerous is fixed by the staleness ceiling below, which applies to `run` too. */
+function missedPolicy(s: Schedule): MissedPolicy {
+  return s.onMissed ?? 'run';
+}
+
+function noteMissed(s: Schedule, at: number, reason: 'skip' | 'offer' | 'stale'): void {
+  s.missedRun = { at, reason, noticedAt: Date.now() };
+  saveSchedules(state.schedules);
+  state.broadcast({ type: 'schedule:updated', schedule: s });
+}
+
 function replan(): void {
   if (!schedulerActive) return;
   if (state.timer) { clearTimeout(state.timer); state.timer = null; }
@@ -336,21 +474,22 @@ function fireDue(): void {
   replan();
 }
 
-function enqueueFire(s: Schedule, firedAt: number, override?: string, manual = false, eventCtx?: EventContext): string | null {
-  // Skip if this cron period was already completed or still running from a prior server instance.
-  // Manual runs (runNow from UI/API) always proceed.
+function enqueueFire(s: Schedule, firedAt: number, override?: string, manual = false, eventCtx?: EventContext): RunOutcome {
+  // Skip if this cron period was already completed/attempted. Manual runs (runNow from UI/API)
+  // always proceed past the period guard — but never past the run lock in startRun().
   if (!manual && s.trigger.kind === 'cron') {
     const prev = computePrevRun(s.trigger, firedAt + 1);
     if (prev !== null) {
       const marker = readCompletionMarker(s.id);
       if (marker && marker.completedAt >= prev) {
-        console.log(`[scheduler] skipping fire for ${s.id} — already completed this period (at ${new Date(marker.completedAt).toISOString()})`);
-        return null;
+        const msg = `already completed this period (at ${new Date(marker.completedAt).toISOString()})`;
+        console.log(`[scheduler] skipping fire for ${s.id} — ${msg}`);
+        return refuse('already-completed', msg);
       }
-      const running = readRunningMarker(s.id);
-      if (running && isProcessAlive(running.pid)) {
-        console.log(`[scheduler] skipping fire for ${s.id} — still running (pid ${running.pid})`);
-        return null;
+      if (marker?.attemptWindow !== undefined && marker.attemptWindow >= prev) {
+        const msg = `this period was already attempted (${marker.status ?? 'started'})`;
+        console.log(`[scheduler] skipping fire for ${s.id} — ${msg}`);
+        return refuse('already-attempted', msg);
       }
     }
   }
@@ -369,10 +508,36 @@ function enqueueFire(s: Schedule, firedAt: number, override?: string, manual = f
     console.warn(`[scheduler] queue overflow for ${s.id} (cap=${QUEUE_CAP}), dropped fire @ ${dropped?.firedAt}`);
   }
   state.queues.set(s.id, q);
-  return null;
+  return { ok: true, sessionId: null, queued: true };
 }
 
-function startRun(s: Schedule, _firedAt: number, override?: string, resume?: ResumeOptions, eventCtx?: EventContext): string | null {
+/**
+ * Start one run, holding the cross-restart run lock for its whole life.
+ *
+ * Every path that can start a run funnels through here — timer fire, catch-up, event, manual
+ * runNow, and the in-place resume from crash recovery — so the lock is the single place that
+ * enforces "one live run per schedule". It is also what makes catch-up and recovery mutually
+ * exclusive: whichever reaches this first holds a live pid, and the other's acquire fails.
+ */
+function startRun(s: Schedule, firedAt: number, override?: string, resume?: ResumeOptions, eventCtx?: EventContext): RunOutcome {
+  const lock = acquireRunLock(s.id, firedAt);
+  if (!lock) {
+    const held = readRunningMarker(s.id);
+    const msg = `run lock held by pid ${held?.pid} since ${new Date(held?.startedAt ?? 0).toISOString()}`;
+    console.log(`[scheduler] not starting ${s.id} — ${msg}`);
+    return refuse('locked', msg);
+  }
+  // Record the attempt BEFORE running: a crash from here on must not look like "never tried".
+  markRunStarted(s.id, firedAt);
+  const pre = getSchedule(s.id);
+  if (pre) {
+    // Advance lastRun at start, not only on success. start() turns a leftover 'running' into
+    // 'error' on the next boot, so the distinction survives while the timestamp still blocks a
+    // replay of this window.
+    pre.lastRun = { at: Date.now(), sessionId: resume?.sessionId ?? '', status: 'running' };
+    pre.missedRun = undefined;
+    saveSchedules(state.schedules);
+  }
   // Deep-copy task so edits mid-run don't affect the in-flight execution
   const snapshot: Schedule = JSON.parse(JSON.stringify(s));
   let sessionId: string | null = null;
@@ -380,6 +545,14 @@ function startRun(s: Schedule, _firedAt: number, override?: string, resume?: Res
   const register = (sid: string, ac: AbortController) => {
     sessionId = sid;
     state.running.set(s.id, ac);
+    // Backfill the session link onto the at-start lastRun. Without this a crash mid-run persists
+    // an errored run with sessionId '' — no way back to the conversation that was interrupted,
+    // which is exactly what the recovery path needs.
+    const live = getSchedule(s.id);
+    if (live?.lastRun && live.lastRun.status === 'running' && !live.lastRun.sessionId) {
+      live.lastRun.sessionId = sid;
+      saveSchedules(state.schedules);
+    }
   };
 
   state.broadcast({ type: 'schedule:fired', scheduleId: s.id });
@@ -393,8 +566,13 @@ function startRun(s: Schedule, _firedAt: number, override?: string, resume?: Res
         saveSchedules(state.schedules);
         state.broadcast({ type: 'schedule:updated', schedule: live });
       }
+      if (summary.status !== 'ok') {
+        // Keep the attempt on record with its real outcome — the next boot must see that this
+        // window was tried and failed, not that it never ran.
+        recordAttemptOutcome(s.id, firedAt, summary.at, summary.status === 'running' ? 'started' : summary.status);
+      }
       if (summary.status === 'ok') {
-        writeCompletionMarker({ completedAt: summary.at, triggeredBy: 'scheduler', scheduleId: s.id });
+        writeCompletionMarker({ completedAt: summary.at, triggeredBy: 'scheduler', scheduleId: s.id, lastAttemptAt: summary.at, attemptWindow: firedAt, status: 'ok' });
         if (live && live.trigger.kind === 'once') {
           console.log(`[scheduler] auto-deleting completed once-schedule ${s.id}`);
           deleteSchedule(s.id);
@@ -422,9 +600,23 @@ function startRun(s: Schedule, _firedAt: number, override?: string, resume?: Res
     })
     .catch((err) => {
       console.error(`[scheduler] unexpected run failure for ${s.id}:`, err);
+      // A rejection never reaches the .then above, so without this the attempt marker stays
+      // 'started' forever and an unexpected throw is indistinguishable from a power cut.
+      const at = Date.now();
+      recordAttemptOutcome(s.id, firedAt, at, 'error');
+      const live = getSchedule(s.id);
+      if (live) {
+        live.lastRun = { at, sessionId: live.lastRun?.sessionId ?? '', status: 'error', error: `unexpected run failure: ${err?.message ?? String(err)}` };
+        saveSchedules(state.schedules);
+        state.broadcast({ type: 'schedule:updated', schedule: live });
+      }
     })
     .finally(() => {
       state.running.delete(s.id);
+      // Release the lock on EVERY exit path — ok, error, abort, or an unexpected throw. The
+      // runner already clears it on its own terminal states; this is idempotent and covers the
+      // paths that never reach the runner's finally.
+      clearRunningMarker(s.id);
       const q = state.queues.get(s.id);
       if (q && q.length > 0) {
         const next = q.shift()!;
@@ -434,5 +626,5 @@ function startRun(s: Schedule, _firedAt: number, override?: string, resume?: Res
       }
     });
 
-  return sessionId;
+  return { ok: true, sessionId };
 }

package/src/server/scheduler/runner.ts

@@ -6,7 +6,7 @@ import { streamChat, type PermissionHandler } from '../claude.ts';
 import { getMcpConfig } from '../mcp.ts';
 import { appendMessage, createScheduledSession, updateScheduledSessionStatus, setRunStatus, registerLivePartial, unregisterLivePartial, writePartial, clearPartial, acquireSessionLock, releaseSessionLock, type ConvBlock } from '../sessions.ts';
 import type { Schedule, ScheduleRunSummary } from './types.ts';
-import { writeRunningMarker, clearRunningMarker } from './storage.ts';
+import { updateRunLockPid, clearRunningMarker } from './storage.ts';
 import { addUnread } from '../unread.ts';
 
 export interface RunContext {
@@ -114,8 +114,8 @@ export async function runSchedule(
   acquireSessionLock(sessionId, 'scheduler', abortController);
   setRunStatus(sessionId, 'running', 'scheduler');
   onEvent({ type: 'session_busy', sessionId, busy: true });
-  // Mark this period as running with the live pid so startup catch-up won't double-fire it.
-  writeRunningMarker({ pid: process.pid, startedAt: now, scheduleId: schedule.id });
+  // The run lock (running marker) is acquired by the engine BEFORE this point — see
+  // engine.startRun. Writing it here too would let a direct runSchedule() call bypass the lock.
 
   const task = schedule.task;
   if (task.kind === 'job') {
@@ -414,9 +414,9 @@ function runCommandWithMarker(command: string, abortController: AbortController,
       stdio: ['ignore', 'pipe', 'pipe'],
     });
 
-    if (child.pid) {
-      writeRunningMarker({ pid: child.pid, startedAt: Date.now(), scheduleId });
-    }
+    // Re-point the held lock at the child: the job outlives nothing here, but if the server dies
+    // the child may still be alive, and a live pid must keep the schedule locked.
+    if (child.pid) updateRunLockPid(scheduleId, child.pid);
 
     let output = '';
     const handleData = (chunk: Buffer) => {

package/src/server/scheduler/storage.ts

@@ -96,3 +96,77 @@ export function clearRunningMarker(scheduleId: string): void {
 export function isProcessAlive(pid: number): boolean {
   try { process.kill(pid, 0); return true; } catch { return false; }
 }
+
+/** How long a held run lock is believed, before it is treated as abandoned regardless of whether
+ *  its pid answers. Bounds the blast radius of pid reuse: after a power cut the OS restarts pid
+ *  allocation low, so a persisted pid can plausibly be live again under the same uid — and a
+ *  liveness check alone would then wedge the schedule forever. Generous vs any real run (agent
+ *  runs are minutes, not hours) while capping the wedge at one window's worth of a daily job. */
+const runLockMaxAgeMs = () => Number(process.env.SCHEDULER_RUN_LOCK_MAX_AGE_MS ?? 6 * 60 * 60 * 1000);
+
+/**
+ * Claim the single live-run slot for a schedule.
+ *
+ * The lock IS the running marker — same file, same conventions — so it survives a process
+ * restart: after a crash the marker is still on disk but its pid is dead, and a dead pid is
+ * reclaimable (otherwise a power cut would wedge the schedule forever). A LIVE pid, ours or
+ * another instance's, means someone is already running this schedule: the caller must back off —
+ * UNLESS the claim is older than `runLockMaxAgeMs`, which is the escape hatch for a lock wedged
+ * by pid reuse. A live, in-ceiling claim is never stolen, not even by a manual run: on this
+ * single-active-instance design that pid is a real run (an agent session, or a spawned job the
+ * lock was re-pointed at), and starting a second one is the duplicate-fire we are preventing.
+ *
+ * Single-writer by design (only the DATA_SYNC_SCHEDULER_ACTIVE instance fires), so this is a
+ * read-then-write, not an atomic CAS.
+ */
+export function acquireRunLock(scheduleId: string, window: number): RunningMarker | null {
+  const existing = readRunningMarker(scheduleId);
+  if (existing) {
+    const alive = isProcessAlive(existing.pid);
+    const age = Date.now() - (Number.isFinite(existing.startedAt) ? existing.startedAt : 0);
+    const maxAge = runLockMaxAgeMs();
+    if (alive && age <= maxAge) return null;
+    const why = !alive
+      ? `dead pid ${existing.pid}`
+      : `held ${Math.round(age / 60_000)}m by live pid ${existing.pid}, past the ${Math.round(maxAge / 60_000)}m lock ceiling — assuming pid reuse`;
+    console.log(`[scheduler] reclaiming run lock for ${scheduleId} — ${why} (window ${new Date(existing.window ?? existing.startedAt).toISOString()})`);
+  }
+  const marker: RunningMarker = { pid: process.pid, startedAt: Date.now(), scheduleId, window };
+  writeRunningMarker(marker);
+  return marker;
+}
+
+/** Re-point a held lock at a spawned child process. Only ever touches a lock THIS process holds,
+ *  and preserves `startedAt` so re-pointing can't refresh the age ceiling above. */
+export function updateRunLockPid(scheduleId: string, pid: number): void {
+  const existing = readRunningMarker(scheduleId);
+  if (!existing) {
+    console.warn(`[scheduler] updateRunLockPid(${scheduleId}): no lock held — not creating one`);
+    return;
+  }
+  if (existing.pid !== process.pid) {
+    console.warn(`[scheduler] updateRunLockPid(${scheduleId}): lock is held by pid ${existing.pid}, not us — leaving it alone`);
+    return;
+  }
+  writeRunningMarker({ ...existing, scheduleId, pid });
+}
+
+/**
+ * Record that a run STARTED for `window`, before it can succeed or fail.
+ *
+ * Without this a run that errors or is killed leaves no trace on disk, so the next boot sees an
+ * un-completed window and replays it — the double-fire this ledger exists to prevent. The
+ * successful-completion timestamp is preserved untouched so "started" stays distinguishable
+ * from "completed ok".
+ */
+export function markRunStarted(scheduleId: string, window: number, triggeredBy: CompletionMarker['triggeredBy'] = 'scheduler'): void {
+  const prev = readCompletionMarker(scheduleId);
+  writeCompletionMarker({
+    completedAt: prev?.completedAt ?? 0,
+    triggeredBy,
+    scheduleId,
+    lastAttemptAt: Date.now(),
+    attemptWindow: window,
+    status: 'started',
+  });
+}

package/src/server/scheduler/types.ts

@@ -34,16 +34,77 @@ export interface ScheduleRunSummary {
   error?: string;
 }
 
+/** What the scheduler did about a window it found already elapsed at boot.
+ *  - `run`   replay it (today's behaviour, and the default — see engine.ts).
+ *  - `skip`  never replay; the window is simply lost.
+ *  - `offer` don't auto-fire, but record it on the schedule (`missedRun`) so a human can
+ *            see it was missed and run it on demand. */
+export type MissedPolicy = 'run' | 'skip' | 'offer';
+
+/** A window that elapsed while nothing was running and was NOT replayed.
+ *  Persisted on the schedule and returned verbatim by `GET /api/schedules[/:id]` — that read
+ *  path IS the affordance `offer` promises: a human (or the agent, via the scheduler skill) sees
+ *  the missed window and can `POST /api/schedules/:id/run` it on demand. */
+export interface MissedRun {
+  /** The window (fire time) that was missed. */
+  at: number;
+  reason: 'skip' | 'offer' | 'stale';
+  /** When the scheduler noticed — i.e. boot time. Read by whoever acts on the miss: `at` alone
+   *  can't tell "missed 20m ago, still worth running" from "found on a boot two days later". */
+  noticedAt: number;
+}
+
+/** Why a start request did not start a run. */
+export type RunRefusal =
+  | 'unknown-schedule'
+  | 'already-running'
+  | 'already-completed'
+  | 'already-attempted'
+  | 'policy-skip'
+  | 'policy-offer'
+  | 'stale'
+  | 'locked';
+
+/**
+ * Result of asking the engine to start a run (timer fire, catch-up, manual, event, resume).
+ * A refusal carries WHY, so the caller can record a truthful error and map a real HTTP status
+ * instead of collapsing every outcome into "null".
+ */
+export type RunOutcome =
+  | { ok: true; sessionId: string | null; queued?: boolean }
+  | { ok: false; reason: RunRefusal; message: string };
+
+/**
+ * Per-schedule attempt/completion ledger. `completedAt` records the last SUCCESSFUL run;
+ * `lastAttemptAt`/`attemptWindow` record the last run that STARTED, whether or not it finished.
+ * Both are needed: completion drives "this period is done", attempt drives "this period was
+ * already tried, don't replay it after a crash".
+ */
 export interface CompletionMarker {
+  /** Last successful completion; 0 when the schedule has never completed. */
   completedAt: number;
   triggeredBy: 'scheduler' | 'ssh' | 'api' | 'manual';
   scheduleId: string;
+  /** Wall-clock time the last attempt began. */
+  lastAttemptAt?: number;
+  /** The window (fire time) that attempt was covering. */
+  attemptWindow?: number;
+  /** Terminal state of the last attempt; `started` means it never reported back (crash). */
+  status?: 'started' | 'ok' | 'error' | 'aborted';
 }
 
+/**
+ * The run lock: at most one live run per scheduleId, across process restarts.
+ * Written by `acquireRunLock` before a run starts, removed when it reaches a terminal state.
+ * A lock whose `pid` is dead (crash / power loss) is reclaimable — see `acquireRunLock`.
+ */
 export interface RunningMarker {
   pid: number;
   startedAt: number;
   scheduleId: string;
+  /** The window (fire time) this run covers — lets a claimer see WHAT is held, not just that
+   *  something is. */
+  window?: number;
 }
 
 export interface Schedule {
@@ -59,6 +120,10 @@ export interface Schedule {
   nextRun?: number;
   lastRun?: ScheduleRunSummary;
   runCount: number;
+  /** What to do with a window that elapsed while the process was down. Absent ⇒ 'run'. */
+  onMissed?: MissedPolicy;
+  /** Last window that elapsed and was deliberately not replayed (policy or staleness). */
+  missedRun?: MissedRun;
   /** Set when a data-plane module owns this schedule (module name). Module reconcile
    *  updates trigger/task; enable/disable snapshots live in the module's state entry. */
   managedBy?: string;

package/src/server/slack/bot.ts

@@ -21,6 +21,7 @@ import { pipeAgentReply, type AgentEvent, type IngressMessage } from 'mcp-slack-
 import { makeSlackQuestionHandler } from './questions.ts';
 import * as contacts from '../contacts.ts';
 import { getChannelContext, invalidateChannelContext } from './context-cache.ts';
+import { noteSlackSeen } from '../downtime.ts';
 import { getOrCreateSession, registerThreadAlias, setLastMessageTs, setUseUserToken, findSlackSessionBySessionId, getProactiveOrigin, hasSessionForThread, isSlackBotPlaceholderEmail } from './sessions.ts';
 
 const MAX_DOWNLOAD_SIZE = 25 * 1024 * 1024;
@@ -45,6 +46,10 @@ const mdText = (b: ConvBlock): b is { type: 'text'; text: string } => b.type ===
 // half: agent-channel summon rules + threads the agent already owns. Referenced app session state
 // (proactive origins, known threads) is why it can't live in the package.
 export function shouldRespond(msg: IngressMessage): boolean {
+  // Advance the per-channel last-seen cursor for EVERY message we're handed, answered or not:
+  // "seen" is the honest baseline for downtime backfill, and it is also how we learn which
+  // channels exist at all. Purely a bookkeeping write — it never affects the gate below.
+  noteSlackSeen(msg.channel, msg.ts);
   const isAgentChannel = msg.channel === AGENT_CHANNEL;
   const isAgentOriginatedThread = msg.isThreadReply && !!(msg.rawThreadTs && getProactiveOrigin(msg.channel, msg.rawThreadTs));
   const isKnownAgentChannelThread = isAgentChannel && msg.isThreadReply && !!(msg.rawThreadTs && hasSessionForThread(msg.channel, msg.rawThreadTs));