aiden-runtime 4.1.5 → 4.6.0

package/dist/core/v4/daemon/cleanShutdown.js

@@ -0,0 +1,154 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/daemon/cleanShutdown.ts — v4.5 Phase 1: clean-shutdown marker.
+ *
+ * Two-tier crash safety net (paired with `restartFailureCounter.ts`):
+ *
+ *   - Marker file `<daemonDir>/.clean_shutdown` — touched as the
+ *     LAST step of a graceful drain. Empty file; the presence is
+ *     the signal.
+ *   - On boot: if the marker exists, consume + unlink it. Boot is
+ *     "clean," meaning the previous instance exited gracefully and
+ *     any active sessions can be considered for normal resume.
+ *   - On boot: if the marker is ABSENT, scan `daemon_instances` for
+ *     rows with `shutdown_at IS NULL` and stale `last_heartbeat`
+ *     (default > 30s). Each such row is a crash candidate; we
+ *     write a `crash_reports` entry, mark the row's
+ *     `shutdown_reason='crash'`, and increment
+ *     `restart_failure_counts` for every still-active session that
+ *     was owned by the crashed instance.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.touchCleanShutdownMarker = touchCleanShutdownMarker;
+exports.isCleanShutdown = isCleanShutdown;
+exports.consumeCleanShutdownMarker = consumeCleanShutdownMarker;
+exports.evaluateBootState = evaluateBootState;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const CRASH_STALE_HEARTBEAT_MS = 30000;
+/** Touch the marker. Call from the final step of `drain()`. */
+function touchCleanShutdownMarker(markerPath) {
+    try {
+        node_fs_1.default.mkdirSync(node_path_1.default.dirname(markerPath), { recursive: true });
+        const fd = node_fs_1.default.openSync(markerPath, 'w');
+        node_fs_1.default.closeSync(fd);
+    }
+    catch { /* best-effort */ }
+}
+/** True when the marker file currently exists on disk. */
+function isCleanShutdown(markerPath) {
+    try {
+        return node_fs_1.default.existsSync(markerPath);
+    }
+    catch {
+        return false;
+    }
+}
+/** Atomic "read + delete" of the marker. Returns true iff present. */
+function consumeCleanShutdownMarker(markerPath) {
+    if (!isCleanShutdown(markerPath))
+        return false;
+    try {
+        node_fs_1.default.unlinkSync(markerPath);
+    }
+    catch { /* best-effort */ }
+    return true;
+}
+/**
+ * Top-level boot-state evaluator. Returns the decision the caller
+ * should act on, AND writes any required crash-report + instance-row
+ * cleanup to the database.
+ *
+ * Idempotent: rerunning on the same boot is safe (the marker is
+ * already consumed, and crashed rows already have `shutdown_at`
+ * filled).
+ */
+function evaluateBootState(opts) {
+    const now = opts.now ?? Date.now();
+    const staleMs = opts.staleHeartbeatMs ?? CRASH_STALE_HEARTBEAT_MS;
+    // Marker check first — it's the fast happy path.
+    if (consumeCleanShutdownMarker(opts.markerPath)) {
+        return {
+            cleanShutdown: true,
+            suspendActiveSessions: false,
+            crashDetected: false,
+        };
+    }
+    // Find every prior instance that didn't mark shutdown_at and whose
+    // heartbeat is stale enough to be considered crashed. The newly-
+    // booted instance is excluded (instance_id mismatch).
+    const cutoff = now - staleMs;
+    const candidates = opts.db
+        .prepare(`SELECT instance_id, pid, started_at, last_heartbeat
+         FROM daemon_instances
+        WHERE shutdown_at IS NULL
+          AND instance_id != ?
+          AND last_heartbeat < ?`)
+        .all(opts.instanceId, cutoff);
+    if (candidates.length === 0) {
+        // No marker AND no crashed siblings — could be the very first
+        // boot OR a quick restart that didn't generate a stale row yet.
+        // Treat as dirty boot to be safe (no active sessions to suspend
+        // when the table is empty, so this is harmless on a fresh
+        // install).
+        return {
+            cleanShutdown: false,
+            suspendActiveSessions: true,
+            crashDetected: false,
+        };
+    }
+    const tx = opts.db.transaction(() => {
+        for (const c of candidates) {
+            // Affected sessions: any run in 'queued' or 'running' status
+            // owned by the crashed instance.
+            const sessions = opts.db
+                .prepare(`SELECT DISTINCT session_id
+             FROM runs
+            WHERE instance_id = ?
+              AND status IN ('queued','running')`)
+                .all(c.instance_id);
+            const sessionIds = sessions.map((s) => s.session_id);
+            opts.db
+                .prepare(`INSERT INTO crash_reports
+             (instance_id, detected_at, prev_started_at,
+              prev_last_heartbeat, prev_pid,
+              affected_sessions, ps_snapshot, details)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+                .run(opts.instanceId, now, c.started_at, c.last_heartbeat, c.pid, JSON.stringify(sessionIds), opts.psSnapshot ?? null, JSON.stringify({
+                dirty_shutdown: true,
+                stuck_loop_sessions: sessionIds,
+            }));
+            opts.db
+                .prepare(`UPDATE daemon_instances
+              SET shutdown_at     = COALESCE(shutdown_at, ?),
+                  shutdown_reason = COALESCE(shutdown_reason, ?)
+            WHERE instance_id = ?`)
+                .run(now, 'crash', c.instance_id);
+            // Mark interrupted runs (they shouldn't appear "running" forever).
+            opts.db
+                .prepare(`UPDATE runs
+              SET status         = 'interrupted',
+                  resume_pending = 1,
+                  resume_reason  = 'crash_recovery',
+                  completed_at   = ?
+            WHERE instance_id = ?
+              AND status IN ('queued','running')`)
+                .run(now, c.instance_id);
+        }
+    });
+    tx();
+    return {
+        cleanShutdown: false,
+        suspendActiveSessions: true,
+        crashDetected: true,
+    };
+}

package/dist/core/v4/daemon/cron/cronBridge.js

@@ -0,0 +1,126 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/daemon/cron/cronBridge.ts — v4.5 Phase 5b.
+ *
+ * Bidirectional converter between the existing `CronJobV2` shape
+ * (JSON-backed, see core/v4/cron/cronState.ts) and the SQLite
+ * `scheduled_workflows` row shape introduced in schema v5.
+ *
+ * Used in two places:
+ *   1. cron migration (one-shot on first v5 boot) — CronJobV2 →
+ *      ScheduledWorkflowRow → INSERT.
+ *   2. cron emitter — when the cron heartbeat ticks, reads
+ *      scheduled_workflows rows + maps back to CronJobV2-ish
+ *      shape for the existing fire pipeline (until cron's storage
+ *      layer fully migrates).
+ *
+ * Schedule expression encoding:
+ *   - interval → "interval:<intervalMs>" (e.g. "interval:300000")
+ *   - cron     → "cron:<expr>"           (e.g. "cron:0 9 * * *")
+ *   - oneshot  → "oneshot:<isoTimestamp>"
+ *
+ * This keeps `schedule_expression` a single text column that's
+ * round-trippable + greppable.
+ *
+ * Pure conversion — no I/O.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jobToRow = jobToRow;
+exports.encodeScheduleExpression = encodeScheduleExpression;
+exports.decodeScheduleExpression = decodeScheduleExpression;
+// ── Encoders ───────────────────────────────────────────────────────────────
+/**
+ * CronJobV2 → ScheduledWorkflowRow. Used by the one-shot migration
+ * from cron_jobs.json. The action string lands in payload_json as
+ * `{ action: "<cmd>" }` so the existing fire pipeline can recover
+ * it; future phases may add structured payload fields without
+ * breaking the round-trip.
+ */
+function jobToRow(job, nowMs = Date.now()) {
+    const scheduleExpression = encodeScheduleExpression(job);
+    const payloadJson = JSON.stringify({
+        action: job.action,
+        description: job.description,
+        runCount: job.runCount,
+        legacyState: job.state,
+        pausedAt: job.pausedAt ?? null,
+        pausedReason: job.pausedReason ?? null,
+    });
+    const createdAt = parseIsoToMs(job.createdAt) ?? nowMs;
+    const lastFiredAt = job.lastRun ? parseIsoToMs(job.lastRun) : null;
+    const nextFireAt = job.nextRun ? parseIsoToMs(job.nextRun) : null;
+    return {
+        id: job.id,
+        name: job.description || `cron-${job.id}`,
+        schedule_expression: scheduleExpression,
+        timezone: 'UTC',
+        enabled: job.enabled ? 1 : 0,
+        payload_json: payloadJson,
+        prompt_template: null,
+        deliver_only: 0,
+        misfire_policy: 'skip_stale',
+        fire_rate_limit: null,
+        catch_up_limit: null,
+        grace_ms: null,
+        last_fired_at: lastFiredAt,
+        next_fire_at: nextFireAt,
+        created_at: createdAt,
+        updated_at: nowMs,
+    };
+}
+/**
+ * Encode the schedule into a single text column. The decoder
+ * recovers kind + ms / expr / iso.
+ */
+function encodeScheduleExpression(job) {
+    if (job.kind === 'interval' && typeof job.intervalMs === 'number') {
+        return `interval:${job.intervalMs}`;
+    }
+    if (job.kind === 'cron' && typeof job.cronExpr === 'string' && job.cronExpr.length > 0) {
+        return `cron:${job.cronExpr}`;
+    }
+    if (job.kind === 'oneshot' && typeof job.oneshotIso === 'string') {
+        return `oneshot:${job.oneshotIso}`;
+    }
+    // Defensive — should never hit when migrating valid jobs.
+    return job.schedule || 'interval:0';
+}
+function decodeScheduleExpression(expr) {
+    if (typeof expr !== 'string' || expr.length === 0)
+        return null;
+    const colon = expr.indexOf(':');
+    if (colon <= 0)
+        return null;
+    const kind = expr.slice(0, colon);
+    const rest = expr.slice(colon + 1);
+    if (kind === 'interval') {
+        const ms = Number.parseInt(rest, 10);
+        if (!Number.isFinite(ms) || ms <= 0)
+            return null;
+        return { kind: 'interval', intervalMs: ms };
+    }
+    if (kind === 'cron') {
+        if (rest.length === 0)
+            return null;
+        return { kind: 'cron', cronExpr: rest };
+    }
+    if (kind === 'oneshot') {
+        if (rest.length === 0)
+            return null;
+        return { kind: 'oneshot', iso: rest };
+    }
+    return null;
+}
+// ── Helpers ────────────────────────────────────────────────────────────────
+function parseIsoToMs(iso) {
+    if (!iso)
+        return null;
+    const t = Date.parse(iso);
+    return Number.isFinite(t) ? t : null;
+}

package/dist/core/v4/daemon/cron/cronEmitter.js

@@ -0,0 +1,173 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/daemon/cron/cronEmitter.ts — v4.5 Phase 5b.
+ *
+ * The cron-mode trigger producer.
+ *
+ * When `AIDEN_DAEMON=1`, the existing cron heartbeat fires through
+ * a daemon-mode action runner that DOESN'T shell-out. Instead, it
+ * inserts a `trigger_event` into the bus + updates last_fired_at
+ * on the corresponding `scheduled_workflows` row. The Phase 5a
+ * dispatcher consumes the event and routes it through the agent
+ * loop (or the deliverOnly stub) just like every other trigger
+ * source.
+ *
+ * The misfire policy fires HERE, not in the dispatcher — the
+ * dispatcher should never see a stale event for a cron that the
+ * policy said to skip.
+ *
+ * Backward compat: `AIDEN_DAEMON=0` keeps the legacy
+ * `defaultRunAction` shell-exec path untouched. This module is a
+ * separate emitter the bootstrap installs as `cronManager`'s
+ * runAction override.
+ *
+ * Public API:
+ *   - `createCronEmitter({triggerBus, db, log})` → RunActionFn
+ *     compatible with `core/v4/cron/cronExecute.ts::RunActionFn`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCronEmitter = createCronEmitter;
+const misfirePolicy_1 = require("./misfirePolicy");
+/**
+ * Build a daemon-mode runAction. Returns a function with the same
+ * signature as `core/v4/cron/cronExecute.ts::RunActionFn` so the
+ * existing cron firing pipeline (`fireJob`) can swap it in.
+ *
+ * Logic per fire:
+ *   1. Resolve the scheduled_workflows row by job.id.
+ *   2. Read misfire policy + scheduled-for instant.
+ *   3. Apply the policy. When fire=false → return immediately
+ *      (the cron tick will not record an output but also won't
+ *      treat it as a fire).
+ *   4. When fire=true, emit `fireCount` trigger_events into the
+ *      bus (each with a distinct idempotency key so the dispatcher
+ *      processes them as separate runs).
+ *   5. Update last_fired_at on the row.
+ *
+ * The cron pipeline records `last_status='ok'` when the action
+ * resolves without throwing. Daemon-mode insertion is fast (one
+ * SQL statement per fire) and synchronous — no actual work
+ * happens here.
+ */
+function createCronEmitter(opts) {
+    const log = opts.log ?? (() => { });
+    const now = opts.now ?? Date.now;
+    return async (job, _signal) => {
+        void _signal; // cron emitter is fast + sync; no cancellation needed
+        try {
+            const row = readWorkflowRow(opts.db, job.id);
+            if (!row) {
+                // Workflow missing from SQLite — fall back to a single-fire emit so
+                // operations that ran during the migration window aren't lost.
+                emitSingle(opts.triggerBus, job, now(), 'workflow_row_missing');
+                log('warn', `[cron-emitter] no scheduled_workflows row for job ${job.id} — falling back to single fire`);
+                return { output: 'enqueued (workflow row missing — single fire)', failed: false };
+            }
+            const policy = (0, misfirePolicy_1.isMisfirePolicy)(row.misfire_policy) ? row.misfire_policy : 'skip_stale';
+            const scheduledFor = row.next_fire_at ?? now();
+            // Decode interval (for catch_up_with_limit period math).
+            const periodMs = decodePeriodMs(row.schedule_expression);
+            const decision = (0, misfirePolicy_1.applyMisfirePolicy)({
+                policy: policy,
+                scheduledFor,
+                now: now(),
+                graceMs: row.grace_ms ?? undefined,
+                catchUpLimit: row.catch_up_limit ?? undefined,
+                periodMs: periodMs ?? undefined,
+            });
+            if (!decision.fire) {
+                log('info', `[cron-emitter] job ${job.id} ${decision.reason}`);
+                return { output: `skipped (${decision.reason})`, failed: false };
+            }
+            // Emit `fireCount` events. For catch_up_with_limit > 1, the
+            // idempotency key encodes the iteration index so each fire
+            // produces a distinct trigger_event row.
+            let inserted = 0;
+            for (let i = 0; i < decision.fireCount; i++) {
+                const idemKey = decision.fireCount === 1
+                    ? new Date(scheduledFor).toISOString()
+                    : `${new Date(scheduledFor).toISOString()}#${i}`;
+                const r = opts.triggerBus.insert({
+                    source: 'schedule',
+                    sourceKey: job.id,
+                    idempotencyKey: idemKey,
+                    payload: {
+                        workflowId: job.id,
+                        name: row.name,
+                        scheduledFor,
+                        scheduledForIso: new Date(scheduledFor).toISOString(),
+                        action: job.action,
+                        description: job.description,
+                        misfirePolicy: policy,
+                        iteration: i,
+                        fireCount: decision.fireCount,
+                        fireReason: decision.reason,
+                        promptTemplate: row.prompt_template,
+                        deliverOnly: row.deliver_only === 1,
+                    },
+                });
+                if (r.inserted)
+                    inserted += 1;
+            }
+            // Update last_fired_at. next_fire_at is recomputed by the
+            // existing cron pipeline (`computeNextFire` in cronExecute.ts)
+            // before this runAction is called, so we don't touch it here.
+            try {
+                opts.db.prepare(`UPDATE scheduled_workflows SET last_fired_at = ?, updated_at = ? WHERE id = ?`).run(now(), now(), job.id);
+            }
+            catch (e) {
+                log('warn', `[cron-emitter] failed to update last_fired_at for ${job.id}: ${e instanceof Error ? e.message : String(e)}`);
+            }
+            const msg = decision.fireCount === 1
+                ? `enqueued 1 event for job ${job.id}`
+                : `enqueued ${inserted}/${decision.fireCount} events for job ${job.id} (catch_up)`;
+            log('info', `[cron-emitter] ${msg}`);
+            return { output: msg, failed: false };
+        }
+        catch (e) {
+            const msg = e instanceof Error ? (e.stack ?? e.message) : String(e);
+            log('error', `[cron-emitter] job ${job.id} emit failed: ${msg}`);
+            return { output: msg, failed: true };
+        }
+    };
+}
+// ── Helpers ────────────────────────────────────────────────────────────────
+function readWorkflowRow(db, jobId) {
+    try {
+        const row = db
+            .prepare('SELECT * FROM scheduled_workflows WHERE id = ?')
+            .get(jobId);
+        return row ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function emitSingle(bus, job, scheduledFor, reason) {
+    bus.insert({
+        source: 'schedule',
+        sourceKey: job.id,
+        idempotencyKey: new Date(scheduledFor).toISOString(),
+        payload: {
+            workflowId: job.id,
+            scheduledFor,
+            scheduledForIso: new Date(scheduledFor).toISOString(),
+            action: job.action,
+            description: job.description,
+            fireReason: reason,
+        },
+    });
+}
+/** Decode `interval:<ms>` → number. Returns null for other kinds. */
+function decodePeriodMs(scheduleExpression) {
+    if (!scheduleExpression.startsWith('interval:'))
+        return null;
+    const n = Number.parseInt(scheduleExpression.slice('interval:'.length), 10);
+    return Number.isFinite(n) && n > 0 ? n : null;
+}

package/dist/core/v4/daemon/cron/migration.js

@@ -0,0 +1,199 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/daemon/cron/migration.ts — v4.5 Phase 5b.
+ *
+ * One-shot data migration: read `cron_jobs.json` (existing JSON-
+ * backed cron store) → `scheduled_workflows` table (SQLite, schema
+ * v5). Runs on first daemon boot AFTER the v5 DDL migration applies.
+ *
+ * Behaviour (Q-P5-3a — automatic):
+ *   1. Skip if `scheduled_workflows` already has rows (idempotent).
+ *   2. Skip if `cron_jobs.json` doesn't exist (first boot, no cron).
+ *   3. Read the JSON via the existing `readCronState` reader (handles
+ *      v1/v2 schema + corruption auto-repair).
+ *   4. Map each `CronJobV2` to a `scheduled_workflows` row via
+ *      `cronBridge.jobToRow`.
+ *   5. Insert all rows in a single transaction.
+ *   6. Back up the source file: `cron_jobs.json.pre-v5-migration.<ts>.bak`.
+ *      ORIGINAL FILE LEFT IN PLACE — non-daemon mode keeps working.
+ *   7. Log: `[cron] migrated <N> jobs to SQLite, backup at <path>`.
+ *
+ * Never throws. Migration failures log loudly but the daemon
+ * continues booting (cron will be empty in daemon mode; the
+ * operator can re-run the migration manually via a CLI command
+ * shipped in Phase 6).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCronMigration = runCronMigration;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const cronState_1 = require("../../cron/cronState");
+const cronState_2 = require("../../cron/cronState");
+const cronBridge_1 = require("./cronBridge");
+/**
+ * Run the one-shot migration. Returns a structured result so the
+ * caller can surface the outcome via daemon health endpoints.
+ *
+ * Synchronous by design — the bootstrap path is already sync and
+ * the migration touches one small JSON file + one batched SQL
+ * insert transaction. Keeping it sync avoids an async-edge in the
+ * daemon's deterministic boot ordering.
+ */
+function runCronMigration(opts) {
+    const log = opts.log ?? (() => { });
+    const now = opts.now ?? Date.now;
+    const errors = [];
+    // ── Step 1: idempotency check on the SQLite side ──────────────────────
+    let existingCount;
+    try {
+        existingCount = opts.db
+            .prepare('SELECT COUNT(*) AS c FROM scheduled_workflows')
+            .get().c;
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        log('error', `[cron-migration] count check failed: ${msg}`);
+        return {
+            ran: false,
+            migrated: 0,
+            skipped: 0,
+            backupPath: null,
+            reason: 'sqlite_count_failed',
+            errors: [msg],
+        };
+    }
+    if (existingCount > 0) {
+        log('info', `[cron-migration] skipped — scheduled_workflows already has ${existingCount} rows`);
+        return {
+            ran: false,
+            migrated: 0,
+            skipped: existingCount,
+            backupPath: null,
+            reason: 'already_migrated',
+            errors,
+        };
+    }
+    // ── Step 2: source-file existence ─────────────────────────────────────
+    const sourcePath = opts.sourcePath ?? (0, cronState_1.defaultCronPaths)().stateFile;
+    if (!node_fs_1.default.existsSync(sourcePath)) {
+        log('info', `[cron-migration] skipped — no cron_jobs.json at ${sourcePath}`);
+        return {
+            ran: false,
+            migrated: 0,
+            skipped: 0,
+            backupPath: null,
+            reason: 'no_source_file',
+            errors,
+        };
+    }
+    // ── Step 3: read existing JSON (sync — small file) ────────────────────
+    let jobs;
+    try {
+        const raw = node_fs_1.default.readFileSync(sourcePath, 'utf-8');
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            // Same auto-repair fallback as readCronState: strip trailing commas.
+            const stripped = raw
+                .replace(/,(\s*[}\]])/g, '$1')
+                .replace(/^\s*\/\/.*$/gm, '');
+            parsed = JSON.parse(stripped);
+        }
+        const state = (0, cronState_2.migrateToV2)(parsed);
+        jobs = state.jobs;
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        log('error', `[cron-migration] failed to read ${sourcePath}: ${msg}`);
+        return {
+            ran: false,
+            migrated: 0,
+            skipped: 0,
+            backupPath: null,
+            reason: 'read_failed',
+            errors: [msg],
+        };
+    }
+    if (jobs.length === 0) {
+        log('info', `[cron-migration] no jobs in ${sourcePath} — nothing to migrate`);
+        // Still create a backup so the operator has a clear "migration
+        // ran" signal (zero-row migrations are still events).
+        return {
+            ran: true,
+            migrated: 0,
+            skipped: 0,
+            backupPath: null,
+            errors,
+        };
+    }
+    // ── Step 4 + 5: map + insert in one transaction ───────────────────────
+    const rows = [];
+    for (const job of jobs) {
+        try {
+            rows.push((0, cronBridge_1.jobToRow)(job, now()));
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            errors.push(`job ${job.id}: ${msg}`);
+            log('warn', `[cron-migration] skipping malformed job ${job.id}: ${msg}`);
+        }
+    }
+    let migrated = 0;
+    try {
+        const insert = opts.db.prepare(`INSERT INTO scheduled_workflows
+      (id, name, schedule_expression, timezone, enabled, payload_json,
+       prompt_template, deliver_only, misfire_policy, fire_rate_limit,
+       catch_up_limit, grace_ms, last_fired_at, next_fire_at,
+       created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+        const tx = opts.db.transaction((batch) => {
+            for (const r of batch) {
+                insert.run(r.id, r.name, r.schedule_expression, r.timezone, r.enabled, r.payload_json, r.prompt_template, r.deliver_only, r.misfire_policy, r.fire_rate_limit, r.catch_up_limit, r.grace_ms, r.last_fired_at, r.next_fire_at, r.created_at, r.updated_at);
+                migrated += 1;
+            }
+        });
+        tx(rows);
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        log('error', `[cron-migration] SQL insert failed: ${msg}`);
+        return {
+            ran: false,
+            migrated: 0,
+            skipped: rows.length,
+            backupPath: null,
+            reason: 'insert_failed',
+            errors: [...errors, msg],
+        };
+    }
+    // ── Step 6: backup ────────────────────────────────────────────────────
+    const backupPath = `${sourcePath}.pre-v5-migration.${now()}.bak`;
+    try {
+        node_fs_1.default.copyFileSync(sourcePath, backupPath);
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        log('warn', `[cron-migration] backup copy failed (migration still applied): ${msg}`);
+        errors.push(`backup: ${msg}`);
+    }
+    // ── Step 7: log ───────────────────────────────────────────────────────
+    log('info', `[cron-migration] migrated ${migrated} job${migrated === 1 ? '' : 's'} to SQLite, backup at ${node_path_1.default.basename(backupPath)}`);
+    return {
+        ran: true,
+        migrated,
+        skipped: rows.length - migrated,
+        backupPath: backupPath,
+        errors,
+    };
+}