@loicngr/kobo 1.7.4 → 1.7.6

package/dist/server/services/agent/orchestrator.js

@@ -4,7 +4,10 @@ import { getDb } from '../../db/index.js';
 import { ensureKoboHome, getCompiledMcpServerPath, getDbPath, getKoboHome, getMcpServerSourcePath, getSettingsPath, getSkillsPath, } from '../../utils/paths.js';
 import { unregisterProcess } from '../../utils/process-tracker.js';
 import * as autoLoopService from '../auto-loop-service.js';
+import * as cronService from '../cron-service.js';
+import * as quotaBackoffService from '../quota-backoff-service.js';
 import { getEffectiveSettings } from '../settings-service.js';
+import { refreshNow } from '../usage/poller.js';
 import * as wakeupService from '../wakeup-service.js';
 import { emit, emitEphemeral } from '../websocket-service.js';
 import { getWorkspace as getWs, markWorkspaceUnread, updateWorkspaceStatus, } from '../workspace-service.js';
@@ -137,8 +140,6 @@ let availableSkills = (() => {
 const retryCounts = new Map();
 /** Tracks workspaces where the current session failed due to a stale --resume session ID. */
 const resumeFailedSet = new Set();
-/** workspaceId -> backoff timer */
-const backoffTimers = new Map();
 // ── Watchdog ──────────────────────────────────────────────────────────────────
 const WATCHDOG_INTERVAL_MS = 30_000;
 let watchdogTimer = null;
@@ -447,6 +448,46 @@ function handleEvent(workspaceId, agentSessionId, ev) {
             wakeupService.schedule(workspaceId, delay, prompt, reason, agentSessionId);
         }
     }
+    // Same legacy bridge for the SDK's native `CronCreate`. The native tool is
+    // session-only (the cron dies when the agent session exits and is not
+    // persisted to disk), which makes it useless for any real "schedule a
+    // recurring trigger" need. We intercept the tool:call and arm an equivalent
+    // kobo cron in parallel — persistent across restarts, owned by the backend.
+    if (ev.kind === 'tool:call' && ev.name === 'CronCreate') {
+        const input = ev.input;
+        const prompt = typeof input?.prompt === 'string' ? input.prompt : '';
+        // The SDK's exact field name has drifted across versions — try the most
+        // likely candidates. If none match we log the input shape so the user
+        // can extend this list.
+        const expression = (typeof input?.cron === 'string' && input.cron) ||
+            (typeof input?.schedule === 'string' && input.schedule) ||
+            (typeof input?.expression === 'string' && input.expression) ||
+            '';
+        if (prompt && expression) {
+            console.warn(`[orchestrator] Native CronCreate intercepted for workspace '${workspaceId}' — armed equivalent kobo cron. Prefer kobo__cron_create.`);
+            try {
+                cronService.arm(workspaceId, {
+                    expression,
+                    prompt,
+                    label: 'from-native-CronCreate',
+                    agentSessionId,
+                });
+            }
+            catch (err) {
+                console.error('[orchestrator] Failed to mirror native CronCreate as kobo cron:', err);
+            }
+        }
+        else if (prompt || input) {
+            console.warn(`[orchestrator] Native CronCreate intercepted but unrecognised input shape (workspace '${workspaceId}'):`, Object.keys(input ?? {}));
+        }
+    }
+    // Native `CronDelete` and `CronList` are noisy but harmless to ignore.
+    // The native cron is session-only so deletion is moot once the session
+    // ends; the kobo equivalents (kobo__cron_delete / kobo__cron_list) are
+    // the persistent path. Log to track usage and avoid silent confusion.
+    if (ev.kind === 'tool:call' && (ev.name === 'CronDelete' || ev.name === 'CronList')) {
+        console.warn(`[orchestrator] Native ${ev.name} called on workspace '${workspaceId}' — has no effect on kobo crons. Use kobo__${ev.name === 'CronDelete' ? 'cron_delete' : 'cron_list'} instead.`);
+    }
     if (ev.kind === 'skills:discovered') {
         availableSkills = ev.skills;
         try {
@@ -469,7 +510,7 @@ function handleEvent(workspaceId, agentSessionId, ev) {
         }
     }
     if (ev.kind === 'error' && ev.category === 'quota') {
-        handleQuota(workspaceId, agentSessionId);
+        void handleQuota(workspaceId, agentSessionId);
     }
     if (ev.kind === 'error' && ev.category === 'resume_failed') {
         resumeFailedSet.add(workspaceId);
@@ -569,14 +610,11 @@ function onSessionEnded(workspaceId, agentSessionId, exitCode, reason, resumeFai
     if (wasStopping)
         return;
     // When the session hit quota, handleQuota() already transitioned the
-    // workspace to `quota` and armed the retry timer. Keep that timer alive
-    // and preserve the `quota` status so auto-loop can resume after reset.
+    // workspace to `quota` and armed the retry via quotaBackoffService.
+    // Preserve that pending backoff in the quota path; otherwise clear any
+    // stale entry (defensive — shouldn't normally exist on a non-quota end).
     if (!preserveQuotaBackoff) {
-        const pendingBackoff = backoffTimers.get(workspaceId);
-        if (pendingBackoff) {
-            clearTimeout(pendingBackoff);
-            backoffTimers.delete(workspaceId);
-        }
+        quotaBackoffService.cancel(workspaceId, 'completed');
     }
     if (preserveQuotaBackoff) {
         try {
@@ -774,11 +812,8 @@ export function stopAgent(workspaceId) {
     // session:ended handler checks identity before removing, so a new controller
     // started in the meantime is preserved.
     controllers.delete(workspaceId);
-    const timer = backoffTimers.get(workspaceId);
-    if (timer) {
-        clearTimeout(timer);
-        backoffTimers.delete(workspaceId);
-    }
+    // Manual stop should also drop any pending quota auto-resume.
+    quotaBackoffService.cancel(workspaceId, 'user');
     // Fire-and-forget: controller.stop is async but we don't block callers.
     void ctrl.stop().catch((err) => {
         console.error('[orchestrator] controller.stop failed:', err);
@@ -1098,12 +1133,14 @@ const QUOTA_FALLBACK_LADDER_MINUTES = [15, 30, 60, 180, 300];
 /**
  * Compute the delay before retrying a workspace hit by quota.
  *
- * Prefers the `resetsAt` of the saturated bucket with the furthest-future
- * reset (a tighter bucket will unlock by then anyway). Falls back to a
- * fixed ladder (15 → 30 → 60 → 180 → 300 min) whenever the rate_limit
- * info is missing, malformed, or implausible.
+ * Prefers (1) the `resetsAt` of the saturated bucket with the furthest-future
+ * reset reported by the agent's `rate_limit` event, then (1.5) the official
+ * Anthropic usage API (`five_hour` bucket) when it reports saturation, and
+ * finally (2) a fixed ladder (15 → 30 → 60 → 180 → 300 min) whenever neither
+ * source is usable.
  */
-export function computeQuotaBackoffMs(workspaceId, retryCount) {
+export async function computeQuotaBackoffMs(workspaceId, retryCount) {
+    // 1. Prefer the rate_limit event from the agent stream — most recent + most precise.
     const info = latestRateLimitInfo.get(workspaceId);
     if (info?.buckets?.length) {
         const candidates = info.buckets
@@ -1119,15 +1156,38 @@ export function computeQuotaBackoffMs(workspaceId, retryCount) {
             }
         }
     }
+    // 1.5. Try the official usage API (Claude subscription). Best-effort; never throws.
+    try {
+        const snap = await refreshNow('claude-code');
+        if (snap) {
+            const fiveHour = snap.buckets.find((b) => b.id === 'five_hour');
+            if (fiveHour &&
+                typeof fiveHour.usedPct === 'number' &&
+                fiveHour.usedPct >= QUOTA_SATURATION_THRESHOLD_PCT &&
+                typeof fiveHour.resetsAt === 'string') {
+                const resetTs = Date.parse(fiveHour.resetsAt);
+                const delta = resetTs - Date.now() + QUOTA_SAFETY_MARGIN_MS;
+                if (delta > 0 && delta <= QUOTA_MAX_BACKOFF_MS) {
+                    return { delayMs: delta, resetsAt: fiveHour.resetsAt, source: 'usage_api' };
+                }
+            }
+        }
+    }
+    catch (err) {
+        console.warn('[orchestrator] computeQuotaBackoffMs — usage API call failed:', err);
+    }
+    // 2. Hard-coded ladder.
     const idx = Math.min(Math.max(0, retryCount), QUOTA_FALLBACK_LADDER_MINUTES.length - 1);
     const backoffMinutes = QUOTA_FALLBACK_LADDER_MINUTES[idx];
-    return { delayMs: backoffMinutes * 60 * 1000, source: 'exponential_fallback' };
+    return { delayMs: backoffMinutes * 60 * 1000, source: 'fallback_ladder' };
 }
+/** @internal test-only — re-export of `computeQuotaBackoffMs` to anchor a stable seam. */
+export const _computeQuotaBackoffMs = computeQuotaBackoffMs;
 /** @internal Test-only. */
 export function _test_setRateLimitInfo(workspaceId, info) {
     latestRateLimitInfo.set(workspaceId, info);
 }
-function handleQuota(workspaceId, _agentSessionId) {
+async function handleQuota(workspaceId, _agentSessionId) {
     try {
         updateWorkspaceStatus(workspaceId, 'quota');
     }
@@ -1135,53 +1195,39 @@ function handleQuota(workspaceId, _agentSessionId) {
         // May fail if transition is not valid
     }
     const retryCount = retryCounts.get(workspaceId) ?? 0;
-    const { delayMs, resetsAt, source } = computeQuotaBackoffMs(workspaceId, retryCount);
-    const backoffMs = delayMs;
+    const { delayMs, resetsAt, source } = await computeQuotaBackoffMs(workspaceId, retryCount);
     retryCounts.set(workspaceId, retryCount + 1);
-    // Surface the backoff schedule as an ephemeral event so the UI can display
-    // retry count / wait time without polluting the persistent event log.
-    emitEphemeral(workspaceId, 'agent:quota-backoff', {
-        retryCount: retryCount + 1,
-        backoffMinutes: Math.round(delayMs / 60_000),
-        resetsAt,
-        source,
-    });
-    const timer = setTimeout(() => {
-        backoffTimers.delete(workspaceId);
-        if (!controllers.has(workspaceId)) {
-            const freshWs = getWs(workspaceId);
-            if (!freshWs || freshWs.archivedAt !== null || freshWs.status !== 'quota') {
-                return;
-            }
-            try {
-                if (freshWs.autoLoop) {
-                    autoLoopService.onQuotaBackoffExpired(workspaceId);
-                }
-                else {
-                    const freshWorkingDir = freshWs.worktreePath;
-                    startAgent(workspaceId, freshWorkingDir, 'Continue the previous task where you left off.', undefined, true);
-                }
-            }
-            catch (err) {
-                console.error(`[orchestrator] Quota retry for workspace '${workspaceId}' failed:`, err);
-                const msg = err instanceof Error ? err.message : String(err);
-                try {
-                    updateWorkspaceStatus(workspaceId, 'error');
-                }
-                catch {
-                    // transition may not be valid
-                }
-                routeEvent(workspaceId, '', {
-                    kind: 'error',
-                    category: 'other',
-                    message: `Quota retry failed: ${msg}`,
-                });
-            }
-        }
-    }, backoffMs);
-    timer.unref?.();
-    backoffTimers.set(workspaceId, timer);
+    // The quotaBackoffService owns the timer + the persistent row + the
+    // 'agent:quota-backoff' WS emit. Hand off everything to it.
+    quotaBackoffService.arm(workspaceId, delayMs, { resetsAt: resetsAt ?? null, source });
 }
+/** @internal test-only — re-export of `handleQuota` for direct testing. */
+export const _handleQuota = handleQuota;
+/**
+ * Rebuild the in-memory `retryCounts` map from the persisted `pending_quota_backoffs`
+ * rows. Called from `index.ts` at boot, before `quotaBackoffService.restoreOnBoot`.
+ * Without this, an arm() after restart would compute the next backoff from
+ * `retryCount=0`, undoing the ladder progression.
+ */
+export function restoreRetryCountsFromDb() {
+    for (const pending of quotaBackoffService.listPending()) {
+        retryCounts.set(pending.workspaceId, pending.retryCount);
+    }
+}
+// One-time wire: when the persisted backoff timer fires (or a row is
+// restored at boot), hand the workspace off to auto-loop. The auto-loop
+// service decides whether to spawn the next iteration or fall back to a
+// manual resume.
+//
+// IMPORTANT — behavioural contract: only auto-loop workspaces auto-resume
+// after a quota backoff. `onQuotaBackoffExpired` no-ops if `auto_loop !== 1`
+// (see auto-loop-service). Workspaces hit by quota WITHOUT auto-loop stay
+// in `quota` status and require manual user action (resume / new message)
+// to leave that state. This is intentional: without an auto-loop intent,
+// firing a fresh agent run in the user's absence would surprise them.
+quotaBackoffService.setOnFireCallback((workspaceId) => {
+    autoLoopService.onQuotaBackoffExpired(workspaceId);
+});
 // ── Testing utilities ─────────────────────────────────────────────────────────
 /** @internal test-only */
 export function _getControllers() {
@@ -1192,10 +1238,6 @@ export function _getRetryCounts() {
     return retryCounts;
 }
 /** @internal test-only */
-export function _getBackoffTimers() {
-    return backoffTimers;
-}
-/** @internal test-only */
 export function _getSessionIds() {
     return sessionIds;
 }

package/dist/server/services/auto-loop-service.js

@@ -54,12 +54,17 @@ export function enable(workspaceId) {
     if (row.auto_loop_ready !== 1) {
         throw new Error(`Workspace '${workspaceId}' is not ready for auto-loop (run grooming first)`);
     }
+    // Refuse to enable when there is nothing to spawn — without this, auto_loop
+    // would flip to 1 silently with no iteration running, locking the chat input
+    // (auto-loop banner) without doing any work. The user must add a task or
+    // unmark a done task before re-enabling.
+    const pending = countPendingTasks(workspaceId);
+    if (pending === 0) {
+        throw new Error(`Workspace '${workspaceId}' has no pending tasks; add or unmark a task before enabling auto-loop`);
+    }
     const db = getDb();
     db.prepare('UPDATE workspaces SET auto_loop = 1, no_progress_streak = 0 WHERE id = ?').run(workspaceId);
     emitEphemeral(workspaceId, 'autoloop:enabled', {});
-    const pending = countPendingTasks(workspaceId);
-    if (pending === 0)
-        return;
     if (orchestrator.hasController(workspaceId))
         return;
     // spawnNextIteration throws on initial spawn failure (see flag).
@@ -309,6 +314,14 @@ function spawnNextIteration(workspaceId, opts = {}) {
  * Called by orchestrator.handleQuota's backoff timer when auto-loop is enabled.
  * Spawns the next auto-loop iteration if the workspace is still in quota status
  * with auto_loop active; no-ops otherwise (race-safe).
+ *
+ * No-op cases — these all leave the workspace in `quota` status awaiting
+ * manual user action:
+ *   - workspace was deleted between arm and fire
+ *   - `auto_loop !== 1` (workspace was never an auto-loop target, OR the user
+ *     toggled the loop off during the backoff window)
+ *   - `status !== 'quota'` (user already manually resumed, or another path
+ *     transitioned the workspace)
  */
 export function onQuotaBackoffExpired(workspaceId) {
     const row = getRow(workspaceId);

package/dist/server/services/cron-service.js

@@ -0,0 +1,279 @@
+import { CronExpressionParser } from 'cron-parser';
+import { nanoid } from 'nanoid';
+import { getDb } from '../db/index.js';
+import { slugifyProjectName } from '../utils/project-slug.js';
+import { resolveWorkspaceWorktreePath } from '../utils/worktree-paths.js';
+import * as orchestrator from './agent/orchestrator.js';
+import * as settingsService from './settings-service.js';
+import { emitEphemeral } from './websocket-service.js';
+export const MIN_DELAY_BETWEEN_FIRES_SECONDS = 60;
+// Node `setTimeout` stores the delay as a 32-bit signed int. Anything above
+// 2^31-1 ms (~24.8 days) triggers `TimeoutOverflowWarning` and silently
+// truncates to 1ms — which causes the timer to fire instantly and loop
+// when the real target is years away (e.g. `@yearly` or `0 0 1 1 *`).
+// We cap each setTimeout at this max and re-arm in the callback if the
+// real fire time hasn't been reached yet.
+const MAX_SETTIMEOUT_MS = 2_000_000_000; // ~23 days, with margin under 2^31-1
+const timers = new Map();
+/**
+ * Arm a setTimeout that fires `fireOrSkip(id)` when `fireAt` is reached.
+ * Replaces any existing timer for this id. Handles long horizons by
+ * chaining capped timeouts, since Node's setTimeout overflows past ~24.8
+ * days.
+ */
+function scheduleAt(id, fireAt) {
+    const previous = timers.get(id);
+    if (previous)
+        clearTimeout(previous);
+    const deltaMs = Math.max(0, fireAt.getTime() - Date.now());
+    const cappedMs = Math.min(deltaMs, MAX_SETTIMEOUT_MS);
+    const timer = setTimeout(() => {
+        timers.delete(id);
+        if (Date.now() >= fireAt.getTime()) {
+            fireOrSkip(id);
+        }
+        else {
+            // Long-horizon cron: hop forward another chunk and re-check.
+            scheduleAt(id, fireAt);
+        }
+    }, cappedMs);
+    timer.unref?.();
+    timers.set(id, timer);
+}
+function rowToCron(row) {
+    return {
+        id: row.id,
+        workspaceId: row.workspace_id,
+        expression: row.expression,
+        prompt: row.prompt,
+        label: row.label,
+        agentSessionId: row.agent_session_id,
+        nextFireAt: row.next_fire_at,
+        lastFiredAt: row.last_fired_at,
+        oneShot: row.one_shot === 1,
+        createdAt: row.created_at,
+    };
+}
+/**
+ * Compute the next fire time for an expression strictly after `from`.
+ * Uses cron-parser 5.x API. Throws with a descriptive error if the
+ * expression is invalid. Helpers `@hourly` / `@daily` / `@weekly` /
+ * `@monthly` / `@yearly` are accepted natively.
+ */
+function nextAfter(expression, from) {
+    try {
+        const it = CronExpressionParser.parse(expression, { currentDate: from });
+        return it.next().toDate();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`Invalid cron expression: ${expression} — ${msg}`);
+    }
+}
+/**
+ * Validate the expression, persist the row, arm a setTimeout for the next
+ * fire, emit `cron:created`. Throws on invalid expression OR when the next
+ * fire is < MIN_DELAY_BETWEEN_FIRES_SECONDS seconds in the future.
+ */
+export function arm(workspaceId, args) {
+    const now = new Date();
+    const next = nextAfter(args.expression, now);
+    const deltaMs = next.getTime() - now.getTime();
+    if (deltaMs < MIN_DELAY_BETWEEN_FIRES_SECONDS * 1000) {
+        throw new Error(`Cron expression resolves too close to now (minimum ${MIN_DELAY_BETWEEN_FIRES_SECONDS}s); use a longer interval`);
+    }
+    const id = nanoid();
+    const db = getDb();
+    db.prepare(`INSERT INTO pending_crons (id, workspace_id, expression, prompt, label, agent_session_id, next_fire_at, last_fired_at, one_shot, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, NULL, ?, ?)`).run(id, workspaceId, args.expression, args.prompt, args.label ?? null, args.agentSessionId ?? null, next.toISOString(), args.oneShot ? 1 : 0, now.toISOString());
+    scheduleAt(id, next);
+    const cron = rowToCron(db.prepare('SELECT * FROM pending_crons WHERE id = ?').get(id));
+    emitEphemeral(workspaceId, 'cron:created', { cron });
+    return cron;
+}
+/**
+ * Remove a single cron by id. Idempotent — returns false if no row matched.
+ * Emits `cron:cancelled` only when a row was actually deleted.
+ */
+export function cancel(id, reason) {
+    const db = getDb();
+    const row = db.prepare('SELECT workspace_id FROM pending_crons WHERE id = ?').get(id);
+    if (!row)
+        return false;
+    db.prepare('DELETE FROM pending_crons WHERE id = ?').run(id);
+    const previous = timers.get(id);
+    if (previous) {
+        clearTimeout(previous);
+        timers.delete(id);
+    }
+    emitEphemeral(row.workspace_id, 'cron:cancelled', { id, reason });
+    return true;
+}
+/**
+ * Remove every cron for a workspace. Returns the number of rows deleted.
+ * Used by archive + delete cascades.
+ */
+export function cancelAllForWorkspace(workspaceId, reason) {
+    const db = getDb();
+    const rows = db.prepare('SELECT id FROM pending_crons WHERE workspace_id = ?').all(workspaceId);
+    let deleted = 0;
+    for (const r of rows) {
+        if (cancel(r.id, reason))
+            deleted++;
+    }
+    return deleted;
+}
+export function getCron(id) {
+    const db = getDb();
+    const row = db.prepare('SELECT * FROM pending_crons WHERE id = ?').get(id);
+    return row ? rowToCron(row) : null;
+}
+export function listForWorkspace(workspaceId) {
+    const db = getDb();
+    const rows = db
+        .prepare('SELECT * FROM pending_crons WHERE workspace_id = ? ORDER BY next_fire_at ASC')
+        .all(workspaceId);
+    return rows.map(rowToCron);
+}
+export function listAll() {
+    const db = getDb();
+    const rows = db.prepare('SELECT * FROM pending_crons ORDER BY next_fire_at ASC').all();
+    return rows.map(rowToCron);
+}
+/**
+ * Internal — invoked by setTimeout when a cron's `next_fire_at` elapses.
+ * Either fires (calls orchestrator.startAgent with resume=true) or skips
+ * (when a controller is already active for the workspace), then recomputes
+ * the next occurrence and re-arms a fresh setTimeout. Best-effort: any
+ * unexpected error is logged and the cron is preserved when possible.
+ */
+function fireOrSkip(id) {
+    try {
+        timers.delete(id);
+        const db = getDb();
+        const row = db.prepare('SELECT * FROM pending_crons WHERE id = ?').get(id);
+        if (!row)
+            return; // cancelled in flight
+        const wsRow = db
+            .prepare(`SELECT project_path, working_branch, worktree_path, model, agent_permission_mode, reasoning_effort, archived_at
+           FROM workspaces WHERE id = ?`)
+            .get(row.workspace_id);
+        if (!wsRow || wsRow.archived_at !== null) {
+            cancel(id, wsRow ? 'archive' : 'deleted');
+            return;
+        }
+        let status = 'skipped-active';
+        if (!orchestrator.hasController(row.workspace_id)) {
+            status = 'fired';
+            try {
+                const globalSettings = settingsService.getGlobalSettings();
+                const projectSettings = settingsService.getProjectSettings(wsRow.project_path);
+                const projectSlug = globalSettings.worktreesPrefixByProject
+                    ? slugifyProjectName(projectSettings?.displayName ?? '', wsRow.project_path)
+                    : undefined;
+                const worktreePath = wsRow.worktree_path ??
+                    resolveWorkspaceWorktreePath(wsRow.project_path, wsRow.working_branch, globalSettings.worktreesPath, projectSlug);
+                const stored = wsRow.agent_permission_mode;
+                const agentPermissionMode = stored === 'plan' || stored === 'strict' || stored === 'interactive' ? stored : 'bypass';
+                // agent_session_id encodes the cron's mode: non-NULL means "resume
+                // that session" (pinned at create time); NULL means "fresh session
+                // every fire" (clean context, no conversation continuity).
+                const resumeMode = row.agent_session_id !== null;
+                orchestrator.startAgent(row.workspace_id, worktreePath, row.prompt, wsRow.model, resumeMode, agentPermissionMode, row.agent_session_id ?? undefined, wsRow.reasoning_effort);
+            }
+            catch (err) {
+                console.error(`[cron-service] startAgent at fire time failed for cron '${id}':`, err);
+            }
+        }
+        const now = new Date();
+        let nextFire;
+        try {
+            nextFire = nextAfter(row.expression, now);
+        }
+        catch (err) {
+            // Defensive — the expression validated at create time, so reaching here
+            // means cron-parser changed its acceptance rules between the original
+            // arm and this fire. Cancel as 'completed' (the cron self-terminates)
+            // rather than 'user' which would imply the user requested it.
+            console.error(`[cron-service] failed to recompute next fire for cron '${id}':`, err);
+            cancel(id, 'completed');
+            return;
+        }
+        // One-shot crons cancel themselves after a real fire (not on skip-active —
+        // the user expects the cron to actually run once, so a skipped tick must
+        // be retried at the next occurrence). Recurring crons re-arm normally.
+        if (status === 'fired' && row.one_shot === 1) {
+            db.prepare(`UPDATE pending_crons SET last_fired_at = ? WHERE id = ?`).run(now.toISOString(), id);
+            emitEphemeral(row.workspace_id, 'cron:fired', {
+                id,
+                status,
+                nextFireAt: null,
+                lastFiredAt: now.toISOString(),
+                oneShotConsumed: true,
+            });
+            cancel(id, 'completed');
+            return;
+        }
+        db.prepare(`UPDATE pending_crons SET next_fire_at = ?, last_fired_at = ? WHERE id = ?`).run(nextFire.toISOString(), now.toISOString(), id);
+        scheduleAt(id, nextFire);
+        emitEphemeral(row.workspace_id, 'cron:fired', {
+            id,
+            status,
+            nextFireAt: nextFire.toISOString(),
+            lastFiredAt: now.toISOString(),
+        });
+    }
+    catch (err) {
+        console.error(`[cron-service] fireOrSkip uncaught error for cron '${id}':`, err);
+        timers.delete(id);
+    }
+}
+/**
+ * Re-arm timers for rows persisted across restart. Skip-missed semantics:
+ * if the stored next_fire_at is in the past, recompute next() based on the
+ * current time and update the row before arming (mirror of POSIX crontab —
+ * no catchup spam after server downtime).
+ *
+ * Rows pointing at deleted/archived workspaces are removed without firing.
+ */
+export function restoreOnBoot() {
+    try {
+        // Boot semantics: clear any existing in-memory timers before rearming.
+        for (const t of timers.values())
+            clearTimeout(t);
+        timers.clear();
+        const db = getDb();
+        const rows = db.prepare('SELECT * FROM pending_crons').all();
+        const now = new Date();
+        for (const row of rows) {
+            try {
+                const wsRow = db.prepare('SELECT archived_at FROM workspaces WHERE id = ?').get(row.workspace_id);
+                if (!wsRow || wsRow.archived_at !== null) {
+                    db.prepare('DELETE FROM pending_crons WHERE id = ?').run(row.id);
+                    continue;
+                }
+                const storedDate = new Date(row.next_fire_at);
+                let nextFireAt;
+                if (storedDate.getTime() <= now.getTime()) {
+                    // Skip-missed semantics — no catchup spam after downtime.
+                    const next = nextAfter(row.expression, now);
+                    nextFireAt = next.toISOString();
+                }
+                else {
+                    // Future row: normalise the persisted ISO format.
+                    nextFireAt = storedDate.toISOString();
+                }
+                db.prepare('UPDATE pending_crons SET next_fire_at = ? WHERE id = ?').run(nextFireAt, row.id);
+                scheduleAt(row.id, new Date(nextFireAt));
+            }
+            catch (err) {
+                console.error(`[cron-service] restoreOnBoot row failed for cron '${row.id}':`, err);
+            }
+        }
+    }
+    catch (err) {
+        console.error('[cron-service] restoreOnBoot failed:', err);
+    }
+}
+/** @internal test-only */
+export const _timers = timers;