aiden-runtime 4.1.5 → 4.5.0

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

@@ -0,0 +1,115 @@
+"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/misfirePolicy.ts — v4.5 Phase 5b.
+ *
+ * What to do when a scheduled workflow's `next_fire_at` is in the
+ * past at tick time. Four policies, configurable per workflow.
+ *
+ * Default `skip_stale` per Q-P5-6(a) — matches the prior-systems
+ * lesson that "missing one run beats firing dozens of stale runs"
+ * after a long suspend or laptop sleep.
+ *
+ *   skip_stale          — skip the run when scheduled > graceMs ago.
+ *                         Fire ONLY when scheduledFor is within the
+ *                         grace window (or in the future).
+ *   run_once_if_late    — fire ONCE if missed, regardless of how
+ *                         stale. Useful for one-shots that MUST run.
+ *   catch_up_with_limit — fire N times (capped at catchUpLimit) to
+ *                         walk forward through the missed schedule.
+ *                         For interval jobs that want to backfill.
+ *   manual_review       — DON'T fire. Log + leave next_fire_at in
+ *                         the past so the operator notices and
+ *                         decides via the upcoming CLI surface.
+ *
+ * Pure module — no I/O, no Date.now(). Both `now` and `scheduledFor`
+ * are passed by the caller. Returns a deterministic decision so
+ * unit tests can assert exact firing behaviour.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyMisfirePolicy = applyMisfirePolicy;
+exports.isMisfirePolicy = isMisfirePolicy;
+const DEFAULT_GRACE_MS = 60000;
+const DEFAULT_CATCH_UP_LIMIT = 10;
+/**
+ * Pure policy resolver. The caller owns the side-effects (insert
+ * trigger_event, advance next_fire_at, log).
+ *
+ * Edge cases handled:
+ *   - scheduledFor in the FUTURE → always `fire:false` ("not yet").
+ *   - scheduledFor within graceMs of now → always fires once.
+ *   - catch_up_with_limit with missing periodMs/limit → safe
+ *     fallback to single fire.
+ */
+function applyMisfirePolicy(input) {
+    const graceMs = input.graceMs ?? DEFAULT_GRACE_MS;
+    const lateBy = input.now - input.scheduledFor;
+    // Future-scheduled — never fire this tick (the heartbeat will
+    // come back around when the time arrives).
+    if (lateBy < 0) {
+        return { fire: false, fireCount: 0, reason: 'not_yet_due' };
+    }
+    // Within grace window — every policy honours the standard fire.
+    if (lateBy <= graceMs) {
+        return { fire: true, fireCount: 1, reason: 'on_time' };
+    }
+    // Past the grace window → policy decides.
+    switch (input.policy) {
+        case 'skip_stale':
+            return {
+                fire: false,
+                fireCount: 0,
+                reason: `skip_stale: late by ${Math.round(lateBy / 1000)}s`,
+            };
+        case 'run_once_if_late':
+            return {
+                fire: true,
+                fireCount: 1,
+                reason: `run_once_if_late: late by ${Math.round(lateBy / 1000)}s`,
+            };
+        case 'catch_up_with_limit': {
+            const limit = input.catchUpLimit ?? DEFAULT_CATCH_UP_LIMIT;
+            const period = input.periodMs;
+            if (!period || period <= 0) {
+                // No period info — safe fallback: single fire.
+                return { fire: true, fireCount: 1, reason: 'catch_up: no period info, firing once' };
+            }
+            // Number of full periods between scheduledFor and now, plus one
+            // for the original missed slot. Capped at `limit`.
+            const missed = Math.floor(lateBy / period) + 1;
+            const fireCount = Math.min(missed, limit);
+            return {
+                fire: true,
+                fireCount,
+                reason: fireCount === missed
+                    ? `catch_up: ${fireCount} missed slot${fireCount === 1 ? '' : 's'}`
+                    : `catch_up: ${missed} missed, capped at ${limit}`,
+            };
+        }
+        case 'manual_review':
+            return {
+                fire: false,
+                fireCount: 0,
+                reason: `manual_review: late by ${Math.round(lateBy / 1000)}s, awaiting operator action`,
+            };
+        default:
+            // Defensive — unknown policy. Be conservative: don't fire.
+            return {
+                fire: false,
+                fireCount: 0,
+                reason: `unknown_policy: ${input.policy}`,
+            };
+    }
+}
+/** Type guard for runtime spec validation. */
+function isMisfirePolicy(s) {
+    return s === 'skip_stale'
+        || s === 'run_once_if_late'
+        || s === 'catch_up_with_limit'
+        || s === 'manual_review';
+}

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

@@ -0,0 +1,90 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/daemon/daemonConfig.ts — v4.5 Phase 1: daemon configuration.
+ *
+ * Env-driven config (same pattern as v4.4 sandboxConfig). Strict
+ * `=== '1'` opt-in for AIDEN_DAEMON in Phases 1-5; Phase 6 will
+ * flip to `!== '0'` (default-on).
+ *
+ * Sub-flags:
+ *   AIDEN_DAEMON_PORT             — daemon API port (default reuses AIDEN_PORT)
+ *   AIDEN_DAEMON_AUTO_RESTART     — '0' disables the internal supervisor
+ *                                   (use when running under systemd/launchd)
+ *   AIDEN_DAEMON_DRAIN_TIMEOUT_MS — drain timeout for in-flight runs (default 30000)
+ *   AIDEN_DAEMON_RESTART_FAILURE_THRESHOLD — per-session stuck-loop threshold (default 3)
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readDaemonConfig = readDaemonConfig;
+exports.getDaemonConfig = getDaemonConfig;
+exports._resetDaemonConfigForTests = _resetDaemonConfigForTests;
+exports.daemonDir = daemonDir;
+exports.daemonDbPath = daemonDbPath;
+exports.daemonRuntimeLockPath = daemonRuntimeLockPath;
+exports.daemonCleanShutdownMarkerPath = daemonCleanShutdownMarkerPath;
+exports.getHostname = getHostname;
+const node_path_1 = __importDefault(require("node:path"));
+const node_os_1 = __importDefault(require("node:os"));
+const DEFAULT_PORT = 4200;
+const DEFAULT_DRAIN_TIMEOUT_MS = 30000;
+const DEFAULT_RESTART_FAILURE_LIMIT = 3;
+function parseIntSafe(raw, fallback) {
+    if (raw === undefined || raw === null || raw === '')
+        return fallback;
+    const n = Number.parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+function readDaemonConfig(env = process.env) {
+    // Phase 1-5 strict opt-in. Phase 6 will flip to `!== '0'`.
+    const enabled = env.AIDEN_DAEMON === '1';
+    const port = parseIntSafe(env.AIDEN_DAEMON_PORT ?? env.AIDEN_PORT, DEFAULT_PORT);
+    const autoRestart = env.AIDEN_DAEMON_AUTO_RESTART !== '0'; // default true
+    const drainTimeoutMs = parseIntSafe(env.AIDEN_DAEMON_DRAIN_TIMEOUT_MS, DEFAULT_DRAIN_TIMEOUT_MS);
+    const restartFailureThreshold = parseIntSafe(env.AIDEN_DAEMON_RESTART_FAILURE_THRESHOLD, DEFAULT_RESTART_FAILURE_LIMIT);
+    return { enabled, port, autoRestart, drainTimeoutMs, restartFailureThreshold };
+}
+let _singleton = null;
+function getDaemonConfig() {
+    if (!_singleton)
+        _singleton = readDaemonConfig();
+    return _singleton;
+}
+function _resetDaemonConfigForTests() {
+    _singleton = null;
+}
+/**
+ * Resolve the daemon's on-disk root directory:
+ *   <aidenHome>/daemon/
+ * Caller passes the resolved Aiden root (from `core/v4/paths.ts`);
+ * we don't import paths.ts here to keep the dependency graph clean.
+ */
+function daemonDir(aidenRoot) {
+    return node_path_1.default.join(aidenRoot, 'daemon');
+}
+function daemonDbPath(aidenRoot) {
+    return node_path_1.default.join(daemonDir(aidenRoot), 'daemon.db');
+}
+function daemonRuntimeLockPath(aidenRoot) {
+    return node_path_1.default.join(daemonDir(aidenRoot), 'runtime.lock');
+}
+function daemonCleanShutdownMarkerPath(aidenRoot) {
+    return node_path_1.default.join(daemonDir(aidenRoot), '.clean_shutdown');
+}
+/** Hostname for instance records — short, never empty. */
+function getHostname() {
+    try {
+        const h = node_os_1.default.hostname();
+        return h && h.length > 0 ? h : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}

package/dist/core/v4/daemon/db/connection.js

@@ -0,0 +1,106 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/daemon/db/connection.ts — v4.5 Phase 1: SQLite handle.
+ *
+ * Single better-sqlite3 connection per process keyed by db path.
+ * Synchronous — better-sqlite3 is sync by design. Wraps the
+ * connection with the daemon's standard pragma set:
+ *
+ *   journal_mode = WAL      — durable + concurrent reads with one writer
+ *   synchronous  = NORMAL   — fsync at WAL checkpoint, not per commit
+ *                             (durable across process crash, may lose
+ *                             last commits on OS crash — acceptable)
+ *   foreign_keys = ON       — enforce FK constraints
+ *   busy_timeout = 5000     — auto-retry on SQLITE_BUSY for 5s
+ *
+ * On test isolation: use `:memory:` to get a per-test database.
+ *
+ * The connection is registered with the resource registry (Phase 1)
+ * so shutdown drain closes it via the standard reap path.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openDaemonDb = openDaemonDb;
+exports.closeDaemonDb = closeDaemonDb;
+exports._closeAllDaemonDbsForTests = _closeAllDaemonDbsForTests;
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const migrations_1 = require("./migrations");
+const _open = new Map();
+/**
+ * Open (or return cached) database at `dbPath`. Creates parent dirs
+ * if missing. Runs migrations to latest version. Idempotent for a
+ * given path.
+ *
+ * Pass ':memory:' for tests.
+ */
+function openDaemonDb(dbPath) {
+    const cached = _open.get(dbPath);
+    if (cached && cached.open)
+        return cached;
+    if (dbPath !== ':memory:') {
+        try {
+            node_fs_1.default.mkdirSync(node_path_1.default.dirname(dbPath), { recursive: true });
+        }
+        catch { /* tolerate — open will surface a clearer error */ }
+    }
+    const db = new better_sqlite3_1.default(dbPath);
+    db.pragma('journal_mode = WAL');
+    db.pragma('synchronous = NORMAL');
+    db.pragma('foreign_keys = ON');
+    db.pragma('busy_timeout = 5000');
+    (0, migrations_1.runMigrations)(db);
+    _open.set(dbPath, db);
+    // v4.5 Phase 3 — daemon.db stores webhook secrets (raw, required
+    // for HMAC computation). Lock the file mode to user-only on POSIX
+    // so a co-tenant on the same machine can't read the secrets out.
+    // On Windows the file already lives in user-private
+    // %LOCALAPPDATA%; chmod is a no-op there (Node ignores Unix bits).
+    // Idempotent — safe to call on every boot.
+    if (dbPath !== ':memory:' && process.platform !== 'win32') {
+        try {
+            node_fs_1.default.chmodSync(dbPath, 0o600);
+        }
+        catch { /* best-effort */ }
+        // WAL/SHM siblings receive identical protection.
+        for (const ext of ['-wal', '-shm']) {
+            try {
+                node_fs_1.default.chmodSync(dbPath + ext, 0o600);
+            }
+            catch { /* may not exist yet */ }
+        }
+    }
+    return db;
+}
+/** Close the cached connection at `dbPath`. Idempotent. */
+function closeDaemonDb(dbPath) {
+    const db = _open.get(dbPath);
+    if (!db)
+        return;
+    try {
+        if (db.open)
+            db.close();
+    }
+    catch { /* best-effort */ }
+    _open.delete(dbPath);
+}
+/** Test-only — close every open handle. */
+function _closeAllDaemonDbsForTests() {
+    for (const [p, db] of _open) {
+        try {
+            if (db.open)
+                db.close();
+        }
+        catch { /* noop */ }
+        _open.delete(p);
+    }
+}

package/dist/core/v4/daemon/db/migrations.js

@@ -0,0 +1,296 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/daemon/db/migrations.ts — v4.5 Phase 1: schema migration runner.
+ *
+ * Version-tracked. Idempotent. Each migration is a string of DDL
+ * statements (CREATE TABLE IF NOT EXISTS / CREATE INDEX IF NOT EXISTS)
+ * wrapped in a transaction. The runner reads the current version
+ * from `schema_version` and applies every migration with a higher
+ * version number.
+ *
+ * Phase 1 ships v1 (`v1.sql`). Future phases append migrations:
+ *
+ *   const MIGRATIONS: ReadonlyArray<Migration> = [
+ *     { version: 1, name: 'phase 1 — daemon foundation', sql: V1_SQL },
+ *     { version: 2, name: 'phase 2 — file watcher trigger', sql: V2_SQL },
+ *     ...
+ *   ];
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LATEST_SCHEMA_VERSION = void 0;
+exports.runMigrations = runMigrations;
+// Embedded v1 schema. Source of truth lives at
+// `core/v4/daemon/db/schema/v1.sql` — kept in sync via the
+// `tests/v4/daemon/db/migrations.test.ts` snapshot check.
+const V1_SQL = `
+CREATE TABLE IF NOT EXISTS schema_version (
+  id              INTEGER PRIMARY KEY CHECK (id = 1),
+  version         INTEGER NOT NULL,
+  applied_at      INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS daemon_instances (
+  instance_id     TEXT PRIMARY KEY,
+  pid             INTEGER NOT NULL,
+  hostname        TEXT NOT NULL,
+  started_at      INTEGER NOT NULL,
+  last_heartbeat  INTEGER NOT NULL,
+  shutdown_at     INTEGER,
+  shutdown_reason TEXT,
+  exit_code       INTEGER,
+  version         TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_daemon_instances_alive
+  ON daemon_instances(shutdown_at) WHERE shutdown_at IS NULL;
+
+CREATE TABLE IF NOT EXISTS runs (
+  id               INTEGER PRIMARY KEY AUTOINCREMENT,
+  trigger_event_id INTEGER,
+  session_id       TEXT NOT NULL,
+  instance_id      TEXT NOT NULL,
+  status           TEXT NOT NULL,
+  finish_reason    TEXT,
+  started_at       INTEGER NOT NULL,
+  completed_at     INTEGER,
+  resume_pending   INTEGER NOT NULL DEFAULT 0,
+  resume_reason    TEXT,
+  FOREIGN KEY (instance_id) REFERENCES daemon_instances(instance_id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_runs_session ON runs(session_id, started_at);
+CREATE INDEX IF NOT EXISTS idx_runs_active
+  ON runs(status) WHERE status IN ('queued','running');
+
+CREATE TABLE IF NOT EXISTS trigger_events (
+  id                INTEGER PRIMARY KEY AUTOINCREMENT,
+  source            TEXT NOT NULL,
+  source_key        TEXT NOT NULL,
+  idempotency_key   TEXT,
+  payload_json      TEXT NOT NULL,
+  status            TEXT NOT NULL,
+  attempts          INTEGER NOT NULL DEFAULT 0,
+  claim_owner       TEXT,
+  claim_expires_at  INTEGER,
+  last_error        TEXT,
+  created_at        INTEGER NOT NULL,
+  updated_at        INTEGER NOT NULL,
+  completed_at      INTEGER,
+  run_id            INTEGER,
+  FOREIGN KEY (run_id) REFERENCES runs(id) ON DELETE SET NULL
+);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_trigger_events_idem
+  ON trigger_events(source, idempotency_key) WHERE idempotency_key IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_trigger_events_pending
+  ON trigger_events(status, created_at) WHERE status IN ('pending','claimed');
+CREATE INDEX IF NOT EXISTS idx_trigger_events_claim_expiry
+  ON trigger_events(claim_expires_at) WHERE status = 'claimed';
+
+CREATE TABLE IF NOT EXISTS run_events (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  run_id      INTEGER NOT NULL,
+  ts          INTEGER NOT NULL,
+  kind        TEXT NOT NULL,
+  payload     TEXT NOT NULL,
+  FOREIGN KEY (run_id) REFERENCES runs(id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_run_events_run ON run_events(run_id, ts);
+
+CREATE TABLE IF NOT EXISTS idempotency_keys (
+  scope           TEXT NOT NULL,
+  key             TEXT NOT NULL,
+  fingerprint     TEXT,
+  response_json   TEXT NOT NULL,
+  status_code     INTEGER NOT NULL DEFAULT 200,
+  created_at      INTEGER NOT NULL,
+  expires_at      INTEGER NOT NULL,
+  PRIMARY KEY (scope, key)
+);
+CREATE INDEX IF NOT EXISTS idx_idem_expiry ON idempotency_keys(expires_at);
+
+CREATE TABLE IF NOT EXISTS crash_reports (
+  id                  INTEGER PRIMARY KEY AUTOINCREMENT,
+  instance_id         TEXT NOT NULL,
+  detected_at         INTEGER NOT NULL,
+  prev_started_at     INTEGER,
+  prev_last_heartbeat INTEGER,
+  prev_pid            INTEGER,
+  affected_sessions   TEXT NOT NULL,
+  ps_snapshot         TEXT,
+  details             TEXT NOT NULL,
+  FOREIGN KEY (instance_id) REFERENCES daemon_instances(instance_id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS restart_failure_counts (
+  session_id      TEXT PRIMARY KEY,
+  count           INTEGER NOT NULL,
+  last_failure    INTEGER NOT NULL,
+  auto_suspended  INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE TABLE IF NOT EXISTS triggers (
+  id              TEXT PRIMARY KEY,
+  source          TEXT NOT NULL,
+  name            TEXT NOT NULL,
+  spec_json       TEXT NOT NULL,
+  enabled         INTEGER NOT NULL DEFAULT 1,
+  fire_rate_limit INTEGER,
+  prompt_template TEXT,
+  deliver_only    INTEGER NOT NULL DEFAULT 0,
+  created_at      INTEGER NOT NULL,
+  updated_at      INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_triggers_source_enabled ON triggers(source, enabled);
+`;
+// v4.5 Phase 2 — file_observations table. Source of truth lives at
+// `core/v4/daemon/db/schema/v2.sql`; kept in sync via the migrations
+// test snapshot check.
+const V2_SQL = `
+CREATE TABLE IF NOT EXISTS file_observations (
+  id                  INTEGER PRIMARY KEY AUTOINCREMENT,
+  watcher_id          TEXT    NOT NULL,
+  abs_path            TEXT    NOT NULL,
+  file_key            TEXT    NOT NULL DEFAULT '',
+  size                INTEGER,
+  mtime_ms            INTEGER NOT NULL,
+  content_hash        TEXT,
+  last_event_type     TEXT,
+  last_seen_at        INTEGER NOT NULL,
+  last_processed_at   INTEGER,
+  last_event_id       INTEGER,
+  last_status         TEXT    NOT NULL DEFAULT 'pending',
+  coalesced_count     INTEGER NOT NULL DEFAULT 0,
+  FOREIGN KEY (watcher_id)   REFERENCES triggers(id)        ON DELETE CASCADE,
+  FOREIGN KEY (last_event_id) REFERENCES trigger_events(id) ON DELETE SET NULL
+);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_file_obs_watcher_path
+  ON file_observations(watcher_id, abs_path);
+CREATE INDEX IF NOT EXISTS idx_file_obs_last_seen
+  ON file_observations(last_seen_at);
+CREATE INDEX IF NOT EXISTS idx_file_obs_pending
+  ON file_observations(watcher_id, last_status) WHERE last_status = 'pending';
+`;
+// v4.5 Phase 3 — webhook_deliveries log.
+const V3_SQL = `
+CREATE TABLE IF NOT EXISTS webhook_deliveries (
+  id                  INTEGER PRIMARY KEY AUTOINCREMENT,
+  route_id            TEXT    NOT NULL,
+  delivery_id         TEXT,
+  signature_verified  INTEGER NOT NULL,
+  status_code         INTEGER NOT NULL,
+  response_body       TEXT,
+  client_ip           TEXT,
+  headers_json        TEXT,
+  body_hash           TEXT    NOT NULL,
+  received_at         INTEGER NOT NULL,
+  processed_at        INTEGER,
+  trigger_event_id    INTEGER,
+  FOREIGN KEY (route_id)         REFERENCES triggers(id)        ON DELETE CASCADE,
+  FOREIGN KEY (trigger_event_id) REFERENCES trigger_events(id)  ON DELETE SET NULL
+);
+CREATE INDEX IF NOT EXISTS idx_webhook_deliveries_route_time
+  ON webhook_deliveries(route_id, received_at);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_webhook_deliveries_delivery
+  ON webhook_deliveries(route_id, delivery_id) WHERE delivery_id IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_webhook_deliveries_received
+  ON webhook_deliveries(received_at);
+`;
+// v4.5 Phase 4a — email_seen forensic table.
+const V4_SQL = `
+CREATE TABLE IF NOT EXISTS email_seen (
+  id                  INTEGER PRIMARY KEY AUTOINCREMENT,
+  route_id            TEXT    NOT NULL,
+  mailbox             TEXT    NOT NULL,
+  uid_validity        INTEGER NOT NULL,
+  uid                 INTEGER NOT NULL,
+  message_id          TEXT,
+  from_address        TEXT,
+  subject             TEXT,
+  received_at         INTEGER NOT NULL,
+  processed_at        INTEGER,
+  trigger_event_id    INTEGER,
+  status              TEXT    NOT NULL,
+  FOREIGN KEY (route_id)         REFERENCES triggers(id)        ON DELETE CASCADE,
+  FOREIGN KEY (trigger_event_id) REFERENCES trigger_events(id)  ON DELETE SET NULL
+);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_email_seen_route_uid
+  ON email_seen(route_id, uid_validity, uid);
+CREATE INDEX IF NOT EXISTS idx_email_seen_received
+  ON email_seen(received_at);
+CREATE INDEX IF NOT EXISTS idx_email_seen_message_id
+  ON email_seen(message_id) WHERE message_id IS NOT NULL;
+`;
+// v4.5 Phase 5b — scheduled_workflows table (cron migration from JSON
+// to SQLite). One-shot data migration from `cron_jobs.json` runs from
+// the daemon bootstrap after this schema applies, not from inside the
+// DDL transaction itself — keeps schema-only migrations idempotent.
+const V5_SQL = `
+CREATE TABLE IF NOT EXISTS scheduled_workflows (
+  id                  TEXT    PRIMARY KEY,
+  name                TEXT    NOT NULL,
+  schedule_expression TEXT    NOT NULL,
+  timezone            TEXT    NOT NULL DEFAULT 'UTC',
+  enabled             INTEGER NOT NULL DEFAULT 1,
+  payload_json        TEXT    NOT NULL,
+  prompt_template     TEXT,
+  deliver_only        INTEGER NOT NULL DEFAULT 0,
+  misfire_policy      TEXT    NOT NULL DEFAULT 'skip_stale',
+  fire_rate_limit     INTEGER,
+  catch_up_limit      INTEGER,
+  grace_ms            INTEGER,
+  last_fired_at       INTEGER,
+  next_fire_at        INTEGER,
+  created_at          INTEGER NOT NULL,
+  updated_at          INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_scheduled_workflows_next_fire
+  ON scheduled_workflows(next_fire_at) WHERE enabled = 1;
+CREATE INDEX IF NOT EXISTS idx_scheduled_workflows_enabled
+  ON scheduled_workflows(enabled);
+`;
+const MIGRATIONS = [
+    { version: 1, name: 'phase 1 — daemon foundation', sql: V1_SQL },
+    { version: 2, name: 'phase 2 — file watcher observations', sql: V2_SQL },
+    { version: 3, name: 'phase 3 — webhook deliveries log', sql: V3_SQL },
+    { version: 4, name: 'phase 4a — email seen forensic table', sql: V4_SQL },
+    { version: 5, name: 'phase 5b — scheduled workflows', sql: V5_SQL },
+];
+exports.LATEST_SCHEMA_VERSION = MIGRATIONS[MIGRATIONS.length - 1].version;
+function getCurrentVersion(db) {
+    // The schema_version table may not exist yet on first boot. Detect
+    // via sqlite_master so we don't trip the migration runner on a
+    // fresh database.
+    const row = db
+        .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='schema_version'")
+        .get();
+    if (!row?.name)
+        return 0;
+    const verRow = db
+        .prepare('SELECT version FROM schema_version WHERE id = 1')
+        .get();
+    return verRow?.version ?? 0;
+}
+/**
+ * Apply every pending migration. Idempotent: re-running a database
+ * already at the latest version is a no-op.
+ */
+function runMigrations(db) {
+    const from = getCurrentVersion(db);
+    const pending = MIGRATIONS.filter((m) => m.version > from);
+    if (pending.length === 0)
+        return { from, to: from };
+    const apply = db.transaction((m) => {
+        db.exec(m.sql);
+        db.prepare('INSERT OR REPLACE INTO schema_version (id, version, applied_at) VALUES (1, ?, ?)').run(m.version, Date.now());
+    });
+    let to = from;
+    for (const m of pending) {
+        apply(m);
+        to = m.version;
+    }
+    return { from, to };
+}

package/dist/core/v4/daemon/db/schema/v1.spec.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/daemon/db/schema/v1.spec.ts — v4.5 Phase 1: typed shapes
+ * matching the columns in `v1.sql`. Used by the daemon modules
+ * that read/write SQLite rows so we have one type per table that
+ * stays in sync with the DDL.
+ *
+ * Naming convention: column names from SQL stay snake_case; TS
+ * row interfaces use camelCase aliases via the mapping helpers
+ * inside each module. These raw interfaces match the wire shape.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });