amalgm 0.1.48 → 0.1.50

package/runtime/scripts/amalgm-mcp/tasks/store.js

@@ -1,19 +1,18 @@
 /**
- * Tasks storage — ~/.amalgm/tasks.json + ~/.amalgm/task-runs/{id}.jsonl
+ * Tasks storage — SQLite-backed scheduled task definitions and run receipts.
  *
- * Single writer, atomic rename. No dual-write to /persist (local-first).
+ * tasks.json and task-runs/*.jsonl are imported once as a compatibility
+ * migration. After that, SQLite is the source of truth.
  */
 
+const crypto = require('crypto');
+const fs = require('fs');
 const path = require('path');
 const { TASKS_FILE, TASK_RUNS_DIR, STORAGE_DIR } = require('../config');
-const {
-  ensureDir,
-  readJson,
-  writeJsonAtomic,
-  cleanupStaleTmp,
-  appendJsonl,
-  tailJsonl,
-} = require('../lib/storage');
+const { ensureDir, readJson, cleanupStaleTmp, tailJsonl } = require('../lib/storage');
+const { openLocalDb } = require('../state/db');
+const { insertStateEvent, publishStateEvent } = require('../state/events');
+const { loadCronParser } = require('../deps');
 const {
   chatInputToLegacyFields,
   getChatInputText,
@@ -22,9 +21,127 @@ const {
 const { normalizeTaskSchedule } = require('./schedule-normalization');
 const { DEFAULT_SELECTED_MODELS, getSelectedModel } = require('../lib/prefs');
 const credentialAdapter = require('../../credential-adapter');
-const { appendStateEvent } = require('../state/events');
+
+const TASKS_JSON_MIGRATION_KEY = 'tasks_json_migrated_v1';
+const TASK_CLAIM_TTL_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_RUN_LIMIT = 50;
+
+let _cronParser = null;
+
+function cron() {
+  if (!_cronParser) _cronParser = loadCronParser();
+  return _cronParser;
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function parseJson(value, fallback = null) {
+  if (typeof value !== 'string' || !value) return fallback;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return fallback;
+  }
+}
+
+function validDate(value) {
+  if (!value) return null;
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? null : date;
+}
+
+function isoOrNull(value) {
+  const date = validDate(value);
+  return date ? date.toISOString() : null;
+}
+
+function addMs(date, ms) {
+  return new Date(date.getTime() + ms);
+}
+
+function computeNextRunAt(task, afterDate) {
+  if (!task || task.enabled === false || !task.schedule) return null;
+  const schedule = task.schedule;
+  const after = validDate(afterDate) || new Date();
+  const endsAt = validDate(task.endsAt);
+  if (endsAt && endsAt <= after) return null;
+
+  if (schedule.kind === 'once') {
+    const runAt = validDate(schedule.at);
+    if (!runAt) return null;
+    const lastRunAt = validDate(task.lastRunAt);
+    if (lastRunAt && lastRunAt >= runAt) return null;
+    if (endsAt && runAt > endsAt) return null;
+    return runAt.toISOString();
+  }
+
+  if (schedule.kind === 'interval') {
+    const ms = Number(schedule.ms);
+    if (!Number.isFinite(ms) || ms < 60_000) return null;
+    const next = addMs(after, ms);
+    if (endsAt && next > endsAt) return null;
+    return next.toISOString();
+  }
+
+  if (schedule.kind === 'cron') {
+    try {
+      const interval = cron().CronExpressionParser.parse(schedule.expr, {
+        currentDate: after,
+        tz: schedule.tz || 'UTC',
+      });
+      const next = interval.next().toDate();
+      if (endsAt && next > endsAt) return null;
+      return next.toISOString();
+    } catch {
+      return null;
+    }
+  }
+
+  return null;
+}
+
+function nextRunBaseline(task) {
+  return validDate(task.lastRunAt) || validDate(task.createdAt) || new Date();
+}
+
+function scheduledInstantForTask(task, now = new Date()) {
+  const schedule = task?.schedule;
+  if (!schedule) return null;
+
+  if (schedule.kind === 'once') {
+    return isoOrNull(schedule.at);
+  }
+
+  if (schedule.kind === 'interval') {
+    return isoOrNull(task.nextRunAt) || computeNextRunAt(task, nextRunBaseline(task));
+  }
+
+  if (schedule.kind === 'cron') {
+    try {
+      const currentDate = validDate(now) || new Date();
+      const interval = cron().CronExpressionParser.parse(schedule.expr, {
+        currentDate,
+        tz: schedule.tz || 'UTC',
+      });
+      const prev = interval.includesDate(currentDate)
+        ? new Date(Math.floor(currentDate.getTime() / 1000) * 1000)
+        : interval.prev().toDate();
+      const createdAt = validDate(task.createdAt);
+      if (createdAt && prev <= createdAt) return isoOrNull(task.nextRunAt);
+      return prev.toISOString();
+    } catch {
+      return isoOrNull(task.nextRunAt);
+    }
+  }
+
+  return null;
+}
 
 function normalizeStoredTask(task) {
+  const createdAt = isoOrNull(task.createdAt || task.created_at) || nowIso();
+  const updatedAt = isoOrNull(task.updatedAt || task.updated_at) || createdAt;
   const harness =
     (task.chatInput && task.chatInput.agent && task.chatInput.agent.harness)
     || task.harness
@@ -62,93 +179,704 @@ function normalizeStoredTask(task) {
 
   return {
     ...task,
+    id: task.id || crypto.randomUUID(),
+    name: String(task.name || 'Scheduled task'),
+    description: task.description || '',
+    enabled: task.enabled !== false,
     schedule,
     chatInput,
     prompt: getChatInputText(chatInput, task.prompt) || legacy.prompt,
+    endsAt: isoOrNull(task.endsAt || task.ends_at),
+    maxConcurrentRuns: Math.max(1, Number(task.maxConcurrentRuns || task.max_concurrent_runs || 1)),
     harness: legacy.harness || harness,
     model: legacy.modelId || model,
+    modelSettings: task.modelSettings || task.model_settings || null,
     authMethod: legacy.authMethod || authMethod,
     projectPath: legacy.cwd || task.projectPath || null,
+    createdAt,
+    updatedAt,
+    lastRunAt: isoOrNull(task.lastRunAt || task.last_run_at),
+    lastStatus: task.lastStatus || task.last_status || null,
+    nextRunAt: isoOrNull(task.nextRunAt || task.next_run_at),
   };
 }
 
-function migrateTasksData(data) {
-  let changed = false;
-  const tasks = Array.isArray(data.tasks)
-    ? data.tasks.map((task) => {
-        const normalizedTask = normalizeStoredTask(task);
-        if (JSON.stringify(normalizedTask) !== JSON.stringify(task)) {
-          changed = true;
+function taskForStorage(task, options = {}) {
+  const normalized = normalizeStoredTask(task);
+  if (options.preserveNextRunAt && normalized.nextRunAt) {
+    return normalized;
+  }
+  normalized.nextRunAt = computeNextRunAt(normalized, nextRunBaseline(normalized));
+  return normalized;
+}
+
+function rowToTask(row) {
+  if (!row) return null;
+  const parsed = parseJson(row.task_json, {});
+  return normalizeStoredTask({
+    ...parsed,
+    id: row.id,
+    name: row.name,
+    enabled: row.enabled === 1,
+    schedule: parseJson(row.schedule_json, parsed.schedule || {}),
+    nextRunAt: row.next_run_at,
+    lastRunAt: row.last_run_at,
+    lastStatus: row.last_status,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  });
+}
+
+function taskRowParams(task) {
+  const taskJson = JSON.stringify(task);
+  return {
+    id: task.id,
+    name: task.name,
+    enabled: task.enabled ? 1 : 0,
+    schedule_kind: task.schedule?.kind || 'unknown',
+    schedule_json: JSON.stringify(task.schedule || {}),
+    next_run_at: task.nextRunAt || null,
+    last_run_at: task.lastRunAt || null,
+    last_status: task.lastStatus || null,
+    created_at: task.createdAt || nowIso(),
+    updated_at: task.updatedAt || nowIso(),
+    task_json: taskJson,
+  };
+}
+
+function upsertTaskRow(db, task) {
+  const params = taskRowParams(task);
+  db.prepare(`
+    INSERT INTO scheduled_tasks (
+      id,
+      name,
+      enabled,
+      schedule_kind,
+      schedule_json,
+      next_run_at,
+      last_run_at,
+      last_status,
+      created_at,
+      updated_at,
+      task_json
+    )
+    VALUES (
+      @id,
+      @name,
+      @enabled,
+      @schedule_kind,
+      @schedule_json,
+      @next_run_at,
+      @last_run_at,
+      @last_status,
+      @created_at,
+      @updated_at,
+      @task_json
+    )
+    ON CONFLICT(id) DO UPDATE SET
+      name = excluded.name,
+      enabled = excluded.enabled,
+      schedule_kind = excluded.schedule_kind,
+      schedule_json = excluded.schedule_json,
+      next_run_at = excluded.next_run_at,
+      last_run_at = excluded.last_run_at,
+      last_status = excluded.last_status,
+      updated_at = excluded.updated_at,
+      task_json = excluded.task_json
+  `).run(params);
+  return params;
+}
+
+function publishEvents(events) {
+  for (const event of events) publishStateEvent(event);
+}
+
+function metaValue(db, key) {
+  return db.prepare('SELECT value FROM local_meta WHERE key = ?').get(key)?.value || null;
+}
+
+function setMetaValue(db, key, value) {
+  db.prepare(`
+    INSERT INTO local_meta (key, value, updated_at)
+    VALUES (?, ?, ?)
+    ON CONFLICT(key) DO UPDATE SET
+      value = excluded.value,
+      updated_at = excluded.updated_at
+  `).run(key, value, nowIso());
+}
+
+function readLegacyRunEntries(taskId) {
+  const file = path.join(TASK_RUNS_DIR, `${taskId}.jsonl`);
+  if (!fs.existsSync(file)) return [];
+  try {
+    const lines = fs.readFileSync(file, 'utf8').split('\n').filter(Boolean);
+    return lines
+      .map((line) => {
+        try {
+          return JSON.parse(line);
+        } catch {
+          return null;
         }
-        return normalizedTask;
       })
-    : [];
+      .filter(Boolean);
+  } catch {
+    return tailJsonl(file, 5000);
+  }
+}
+
+function rowToTaskRun(row) {
+  if (!row) return null;
+  const parsed = parseJson(row.run_json, {});
+  return {
+    ...parsed,
+    id: row.id,
+    runId: row.id,
+    taskId: row.task_id,
+    scheduledFor: row.scheduled_for,
+    status: row.status,
+    startedAt: row.started_at || parsed.startedAt || null,
+    finishedAt: row.finished_at || parsed.finishedAt || null,
+    claimedAt: row.claimed_at || parsed.claimedAt || null,
+    claimExpiresAt: row.claim_expires_at || parsed.claimExpiresAt || null,
+    runnerId: row.runner_id || parsed.runnerId || null,
+    sessionId: row.session_id || parsed.sessionId || null,
+    error: row.error || parsed.error || null,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+function taskRunRowParams(run) {
+  const timestamp = nowIso();
+  const createdAt = run.createdAt || timestamp;
+  const updatedAt = run.updatedAt || timestamp;
+  const runJson = {
+    ...run,
+    id: run.id,
+    runId: run.id,
+    taskId: run.taskId,
+    scheduledFor: run.scheduledFor,
+    status: run.status,
+    startedAt: run.startedAt || null,
+    finishedAt: run.finishedAt || null,
+    claimedAt: run.claimedAt || null,
+    claimExpiresAt: run.claimExpiresAt || null,
+    runnerId: run.runnerId || null,
+    sessionId: run.sessionId || null,
+    error: run.error || null,
+    createdAt,
+    updatedAt,
+  };
+  return {
+    id: run.id,
+    task_id: run.taskId,
+    scheduled_for: run.scheduledFor,
+    status: run.status || 'running',
+    started_at: run.startedAt || null,
+    finished_at: run.finishedAt || null,
+    claimed_at: run.claimedAt || null,
+    claim_expires_at: run.claimExpiresAt || null,
+    runner_id: run.runnerId || null,
+    session_id: run.sessionId || null,
+    error: run.error || null,
+    run_json: JSON.stringify(runJson),
+    created_at: createdAt,
+    updated_at: updatedAt,
+  };
+}
+
+function upsertTaskRunRow(db, run) {
+  const params = taskRunRowParams(run);
+  const existingBySchedule = db.prepare(`
+    SELECT id FROM task_runs WHERE task_id = ? AND scheduled_for = ?
+  `).get(params.task_id, params.scheduled_for);
+  if (existingBySchedule && existingBySchedule.id !== params.id) {
+    params.id = existingBySchedule.id;
+    const parsed = parseJson(params.run_json, {});
+    params.run_json = JSON.stringify({
+      ...parsed,
+      id: params.id,
+      runId: params.id,
+    });
+  }
+  db.prepare(`
+    INSERT INTO task_runs (
+      id,
+      task_id,
+      scheduled_for,
+      status,
+      started_at,
+      finished_at,
+      claimed_at,
+      claim_expires_at,
+      runner_id,
+      session_id,
+      error,
+      run_json,
+      created_at,
+      updated_at
+    )
+    VALUES (
+      @id,
+      @task_id,
+      @scheduled_for,
+      @status,
+      @started_at,
+      @finished_at,
+      @claimed_at,
+      @claim_expires_at,
+      @runner_id,
+      @session_id,
+      @error,
+      @run_json,
+      @created_at,
+      @updated_at
+    )
+    ON CONFLICT(id) DO UPDATE SET
+      status = excluded.status,
+      started_at = excluded.started_at,
+      finished_at = excluded.finished_at,
+      claimed_at = excluded.claimed_at,
+      claim_expires_at = excluded.claim_expires_at,
+      runner_id = excluded.runner_id,
+      session_id = excluded.session_id,
+      error = excluded.error,
+      run_json = excluded.run_json,
+      updated_at = excluded.updated_at
+  `).run(params);
+}
+
+function mergeRunEntry(existing, taskId, entry) {
+  const timestamp = nowIso();
+  const startedAt = isoOrNull(entry.startedAt) || existing?.startedAt || null;
+  const finishedAt = isoOrNull(entry.finishedAt) || existing?.finishedAt || null;
+  const scheduledFor = isoOrNull(entry.scheduledFor)
+    || existing?.scheduledFor
+    || startedAt
+    || finishedAt
+    || timestamp;
+  const status = entry.status || existing?.status || 'running';
+  const events = Array.isArray(existing?.events) ? existing.events.slice(-99) : [];
+  events.push({ ...entry, recordedAt: timestamp });
 
   return {
-    changed,
-    data: {
-      version: typeof data.version === 'number' ? data.version : 1,
-      tasks,
-    },
+    ...(existing || {}),
+    id: entry.runId || entry.id || existing?.id || crypto.randomUUID(),
+    runId: entry.runId || entry.id || existing?.id || null,
+    taskId,
+    scheduledFor,
+    status,
+    startedAt,
+    finishedAt,
+    claimedAt: isoOrNull(entry.claimedAt) || existing?.claimedAt || startedAt || timestamp,
+    claimExpiresAt: isoOrNull(entry.claimExpiresAt) || existing?.claimExpiresAt || null,
+    runnerId: entry.runnerId || existing?.runnerId || null,
+    sessionId: entry.sessionId || existing?.sessionId || null,
+    error: entry.error || existing?.error || null,
+    stopReason: entry.stopReason || existing?.stopReason || null,
+    durationMs: entry.durationMs ?? existing?.durationMs ?? null,
+    outputLength: entry.outputLength ?? existing?.outputLength ?? null,
+    prompt: entry.prompt || existing?.prompt || null,
+    events,
+    createdAt: existing?.createdAt || startedAt || timestamp,
+    updatedAt: timestamp,
   };
 }
 
+function migrateLegacyRuns(db, tasks) {
+  for (const task of tasks) {
+    const entries = readLegacyRunEntries(task.id);
+    const byRunId = new Map();
+    for (const entry of entries) {
+      const runId = entry.runId || entry.id;
+      if (!runId) continue;
+      byRunId.set(runId, mergeRunEntry(byRunId.get(runId), task.id, { ...entry, runId }));
+    }
+
+    for (const run of byRunId.values()) {
+      const existing = db.prepare('SELECT id FROM task_runs WHERE id = ?').get(run.id);
+      if (!existing) upsertTaskRunRow(db, run);
+    }
+  }
+}
+
+function migrateTasksFromJsonOnce() {
+  const db = openLocalDb();
+  if (metaValue(db, TASKS_JSON_MIGRATION_KEY)) return;
+
+  const raw = readJson(TASKS_FILE, { version: 1, tasks: [] });
+  const legacyTasks = Array.isArray(raw?.tasks)
+    ? raw.tasks.map((task) => taskForStorage(task))
+    : [];
+
+  db.transaction(() => {
+    for (const task of legacyTasks) {
+      const existing = db.prepare('SELECT id FROM scheduled_tasks WHERE id = ?').get(task.id);
+      if (!existing) upsertTaskRow(db, task);
+    }
+    migrateLegacyRuns(db, legacyTasks);
+    setMetaValue(db, TASKS_JSON_MIGRATION_KEY, new Date().toISOString());
+  })();
+}
+
 function ensureTasksDirs() {
   ensureDir(STORAGE_DIR);
   ensureDir(TASK_RUNS_DIR);
   cleanupStaleTmp(STORAGE_DIR, '.tasks.json');
-  if (!readJson(TASKS_FILE, null)) writeJsonAtomic(TASKS_FILE, { version: 1, tasks: [] });
+  openLocalDb();
+  migrateTasksFromJsonOnce();
 }
 
 function loadTasks() {
-  const raw = readJson(TASKS_FILE, { version: 1, tasks: [] });
-  const migrated = migrateTasksData(raw);
-  if (migrated.changed) {
-    writeJsonAtomic(TASKS_FILE, migrated.data);
-  }
-  return migrated.data;
+  ensureTasksDirs();
+  const tasks = openLocalDb()
+    .prepare('SELECT * FROM scheduled_tasks ORDER BY datetime(created_at) DESC, lower(name)')
+    .all()
+    .map(rowToTask)
+    .filter(Boolean);
+  return { version: 2, tasks };
 }
 
-function publishTasksChange(data, source = 'tasks') {
-  try {
-    appendStateEvent({
+function saveTasks(data, options = {}) {
+  ensureTasksDirs();
+  const db = openLocalDb();
+  const incomingTasks = Array.isArray(data?.tasks)
+    ? data.tasks.map((task) => taskForStorage(task, {
+      preserveNextRunAt: options.preserveNextRunAt === true,
+    }))
+    : [];
+  const source = options.source || 'tasks:save';
+  const events = [];
+
+  db.transaction(() => {
+    const existingRows = db.prepare('SELECT * FROM scheduled_tasks').all();
+    const existingById = new Map(existingRows.map((row) => [row.id, row]));
+    const seenIds = new Set();
+
+    for (const task of incomingTasks) {
+      task.updatedAt = nowIso();
+      if (!task.nextRunAt) task.nextRunAt = computeNextRunAt(task, nextRunBaseline(task));
+      const existing = existingById.get(task.id);
+      const params = taskRowParams(task);
+      seenIds.add(task.id);
+      if (!existing || existing.task_json !== params.task_json) {
+        upsertTaskRow(db, task);
+        events.push(insertStateEvent(db, {
+          resource: 'tasks',
+          op: existing ? 'update' : 'insert',
+          id: task.id,
+          value: task,
+          source,
+        }));
+      }
+    }
+
+    for (const row of existingRows) {
+      if (seenIds.has(row.id)) continue;
+      db.prepare('DELETE FROM scheduled_tasks WHERE id = ?').run(row.id);
+      events.push(insertStateEvent(db, {
+        resource: 'tasks',
+        op: 'delete',
+        id: row.id,
+        source,
+      }));
+    }
+  })();
+
+  publishEvents(events);
+}
+
+function updateTaskMeta(taskId, updates, options = {}) {
+  ensureTasksDirs();
+  const db = openLocalDb();
+  const source = options.source || 'tasks:meta';
+  let task = null;
+  let event = null;
+
+  db.transaction(() => {
+    const row = db.prepare('SELECT * FROM scheduled_tasks WHERE id = ?').get(taskId);
+    if (!row) return;
+    task = taskForStorage({
+      ...rowToTask(row),
+      ...updates,
+      updatedAt: nowIso(),
+    });
+    upsertTaskRow(db, task);
+    event = insertStateEvent(db, {
       resource: 'tasks',
-      op: 'replace',
-      value: Array.isArray(data?.tasks) ? data.tasks : [],
+      op: 'update',
+      id: task.id,
+      value: task,
       source,
     });
-  } catch (error) {
-    console.warn('[Tasks] Local Live Store publish failed:', error.message);
-  }
-}
+  })();
 
-function saveTasks(data, options = {}) {
-  writeJsonAtomic(TASKS_FILE, data);
-  publishTasksChange(data, options.source || 'tasks:save');
+  publishEvents(event ? [event] : []);
+  return task;
 }
 
-function updateTaskMeta(taskId, updates) {
-  const data = loadTasks();
-  const task = data.tasks.find((t) => t.id === taskId);
-  if (task) {
-    Object.assign(task, updates);
-    saveTasks(data);
-  }
+function listTaskRuns(options = {}) {
+  ensureTasksDirs();
+  const limit = Math.max(1, Math.min(Number(options.limit) || DEFAULT_RUN_LIMIT, 1000));
+  const db = openLocalDb();
+  const rows = options.taskId
+    ? db.prepare(`
+        SELECT * FROM task_runs
+        WHERE task_id = ?
+        ORDER BY datetime(updated_at) DESC, datetime(started_at) DESC
+        LIMIT ?
+      `).all(options.taskId, limit)
+    : db.prepare(`
+        SELECT * FROM task_runs
+        ORDER BY datetime(updated_at) DESC, datetime(started_at) DESC
+        LIMIT ?
+      `).all(limit);
+  return rows.map(rowToTaskRun).filter(Boolean);
 }
 
 function appendRunLog(taskId, entry) {
-  appendJsonl(path.join(TASK_RUNS_DIR, `${taskId}.jsonl`), entry);
+  if (!entry?.runId && !entry?.id) return null;
+  ensureTasksDirs();
+
+  const db = openLocalDb();
+  let run = null;
+  let event = null;
+
+  db.transaction(() => {
+    const runId = entry.runId || entry.id;
+    const existingRow = db.prepare('SELECT * FROM task_runs WHERE id = ?').get(runId);
+    const existing = rowToTaskRun(existingRow);
+    run = mergeRunEntry(existing, taskId, { ...entry, runId });
+    upsertTaskRunRow(db, run);
+    run = rowToTaskRun(db.prepare(`
+      SELECT * FROM task_runs
+      WHERE id = ? OR (task_id = ? AND scheduled_for = ?)
+      LIMIT 1
+    `).get(run.id, taskId, run.scheduledFor));
+    event = insertStateEvent(db, {
+      resource: 'task_runs',
+      op: existing ? 'update' : 'insert',
+      id: run.id,
+      value: run,
+      source: entry.source || 'task_runs:append',
+    });
+  })();
+
+  publishEvents(event ? [event] : []);
+  return run;
 }
 
 function readRunLog(taskId, limit = 20) {
-  return tailJsonl(path.join(TASK_RUNS_DIR, `${taskId}.jsonl`), limit);
+  return listTaskRuns({ taskId, limit });
+}
+
+function runningRunCount(db, taskId, now) {
+  const row = db.prepare(`
+    SELECT COUNT(*) AS count
+    FROM task_runs
+    WHERE task_id = ?
+      AND status = 'running'
+      AND (claim_expires_at IS NULL OR datetime(claim_expires_at) > datetime(?))
+  `).get(taskId, now.toISOString());
+  return Number(row?.count || 0);
+}
+
+function claimTaskRun(task, options = {}) {
+  ensureTasksDirs();
+  const db = openLocalDb();
+  const now = validDate(options.now) || new Date();
+  const timestamp = now.toISOString();
+  const source = options.source || 'scheduler';
+  const runnerId = options.runnerId || 'amalgm-mcp';
+  let claimed = null;
+  const events = [];
+
+  db.transaction(() => {
+    const latestRow = db.prepare('SELECT * FROM scheduled_tasks WHERE id = ?').get(task.id);
+    if (!latestRow) return;
+    let latestTask = rowToTask(latestRow);
+
+    if (runningRunCount(db, latestTask.id, now) >= Math.max(1, Number(latestTask.maxConcurrentRuns || 1))) {
+      return;
+    }
+
+    const scheduledFor = isoOrNull(options.scheduledFor)
+      || scheduledInstantForTask(latestTask, now)
+      || timestamp;
+    const existingRun = db.prepare(`
+      SELECT * FROM task_runs WHERE task_id = ? AND scheduled_for = ?
+    `).get(latestTask.id, scheduledFor);
+
+    const nextRunAt = computeNextRunAt({
+      ...latestTask,
+      lastRunAt: timestamp,
+    }, now);
+
+    if (existingRun) {
+      latestTask = taskForStorage({
+        ...latestTask,
+        nextRunAt,
+        updatedAt: timestamp,
+      }, { preserveNextRunAt: true });
+      upsertTaskRow(db, latestTask);
+      events.push(insertStateEvent(db, {
+        resource: 'tasks',
+        op: 'update',
+        id: latestTask.id,
+        value: latestTask,
+        source,
+      }));
+      claimed = null;
+      return;
+    }
+
+    latestTask = taskForStorage({
+      ...latestTask,
+      lastRunAt: timestamp,
+      lastStatus: 'running',
+      nextRunAt,
+      updatedAt: timestamp,
+    }, { preserveNextRunAt: true });
+
+    upsertTaskRow(db, latestTask);
+    events.push(insertStateEvent(db, {
+      resource: 'tasks',
+      op: 'update',
+      id: latestTask.id,
+      value: latestTask,
+      source,
+    }));
+
+    const run = {
+      id: options.runId || crypto.randomUUID(),
+      runId: null,
+      taskId: latestTask.id,
+      scheduledFor,
+      status: 'running',
+      startedAt: timestamp,
+      finishedAt: null,
+      claimedAt: timestamp,
+      claimExpiresAt: addMs(now, TASK_CLAIM_TTL_MS).toISOString(),
+      runnerId,
+      sessionId: null,
+      error: null,
+      prompt: latestTask.prompt || null,
+      events: [{ runId: options.runId || null, startedAt: timestamp, status: 'running', recordedAt: timestamp }],
+      createdAt: timestamp,
+      updatedAt: timestamp,
+    };
+    run.runId = run.id;
+    upsertTaskRunRow(db, run);
+    const storedRun = rowToTaskRun(db.prepare('SELECT * FROM task_runs WHERE id = ?').get(run.id));
+    events.push(insertStateEvent(db, {
+      resource: 'task_runs',
+      op: 'insert',
+      id: storedRun.id,
+      value: storedRun,
+      source,
+    }));
+    claimed = { task: latestTask, run: storedRun };
+  })();
+
+  publishEvents(events);
+  return claimed;
+}
+
+function claimDueTaskRuns(now = new Date(), options = {}) {
+  ensureTasksDirs();
+  const db = openLocalDb();
+  const current = validDate(now) || new Date();
+  const limit = Math.max(1, Math.min(Number(options.limit) || 50, 500));
+  const rows = db.prepare(`
+    SELECT * FROM scheduled_tasks
+    WHERE enabled = 1
+      AND next_run_at IS NOT NULL
+      AND datetime(next_run_at) <= datetime(?)
+    ORDER BY datetime(next_run_at) ASC
+    LIMIT ?
+  `).all(current.toISOString(), limit);
+
+  const claims = [];
+  for (const row of rows) {
+    const task = rowToTask(row);
+    if (!task) continue;
+    const claim = claimTaskRun(task, {
+      now: current,
+      scheduledFor: scheduledInstantForTask(task, current),
+      runnerId: options.runnerId,
+      source: options.source || 'scheduler',
+    });
+    if (claim) claims.push(claim);
+  }
+  return claims;
+}
+
+function expireStaleTaskRuns(now = new Date(), options = {}) {
+  ensureTasksDirs();
+  const db = openLocalDb();
+  const current = validDate(now) || new Date();
+  const source = options.source || 'task_runs:expire';
+  const events = [];
+
+  db.transaction(() => {
+    const rows = db.prepare(`
+      SELECT * FROM task_runs
+      WHERE status = 'running'
+        AND claim_expires_at IS NOT NULL
+        AND datetime(claim_expires_at) <= datetime(?)
+    `).all(current.toISOString());
+    for (const row of rows) {
+      const run = {
+        ...rowToTaskRun(row),
+        status: 'failed',
+        finishedAt: current.toISOString(),
+        error: 'Task runner stopped before this run completed.',
+        updatedAt: current.toISOString(),
+      };
+      upsertTaskRunRow(db, run);
+      events.push(insertStateEvent(db, {
+        resource: 'task_runs',
+        op: 'update',
+        id: run.id,
+        value: run,
+        source,
+      }));
+
+      const taskRow = db.prepare('SELECT * FROM scheduled_tasks WHERE id = ?').get(run.taskId);
+      const task = rowToTask(taskRow);
+      if (task && task.lastStatus === 'running') {
+        const updatedTask = taskForStorage({
+          ...task,
+          lastStatus: 'failed',
+          updatedAt: current.toISOString(),
+        }, { preserveNextRunAt: true });
+        upsertTaskRow(db, updatedTask);
+        events.push(insertStateEvent(db, {
+          resource: 'tasks',
+          op: 'update',
+          id: updatedTask.id,
+          value: updatedTask,
+          source,
+        }));
+      }
+    }
+  })();
+
+  publishEvents(events);
+  return events.length;
 }
 
 module.exports = {
+  appendRunLog,
+  claimDueTaskRuns,
+  claimTaskRun,
+  computeNextRunAt,
   ensureTasksDirs,
+  expireStaleTaskRuns,
+  listTaskRuns,
   loadTasks,
+  readRunLog,
   saveTasks,
+  scheduledInstantForTask,
   updateTaskMeta,
-  appendRunLog,
-  readRunLog,
 };