create-harness-vibe-coding 0.8.19 → 0.9.3

package/src/wf-ui-server/spawn-gate.mjs

@@ -0,0 +1,46 @@
+// spawn-gate.mjs
+//
+// Bounds concurrent PTY spawns. Each spawn boots a heavy CLI process
+// (claude/codex/opencode — hundreds of MB each), and clients can request many
+// starts at once (canvas auto-start, CLI batches, agent fan-out). A small
+// sliding window keeps the machine from being stampeded: excess starts queue
+// FIFO and enter as earlier spawns settle.
+
+export const DEFAULT_MAX_CONCURRENT_SPAWNS = 2;
+export const DEFAULT_SPAWN_TIMEOUT_MS = 120_000;
+
+export function createSpawnGate({
+  maxConcurrent = DEFAULT_MAX_CONCURRENT_SPAWNS,
+  timeoutMs = DEFAULT_SPAWN_TIMEOUT_MS,
+} = {}) {
+  let active = 0;
+  const waiters = [];
+
+  const release = () => {
+    const next = waiters.shift();
+    if (next) next();
+  };
+
+  return async function withSlot(fn) {
+    if (active >= maxConcurrent) {
+      await new Promise((resolve) => waiters.push(resolve));
+    }
+    active += 1;
+    let timer = null;
+    try {
+      // Deadlock breaker: a hung spawn must not hold the window forever. On
+      // timeout the caller gets an error and the slot frees; the abandoned
+      // spawn settles (or not) in the background.
+      return await Promise.race([
+        fn(),
+        new Promise((_, reject) => {
+          timer = setTimeout(() => reject(new Error(`PTY spawn timed out after ${timeoutMs}ms`)), timeoutMs);
+        }),
+      ]);
+    } finally {
+      if (timer) clearTimeout(timer);
+      active -= 1;
+      release();
+    }
+  };
+}

package/src/wf-ui-server/task-parser.mjs

@@ -1,6 +1,28 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+export const OPEN_TASK_STATUSES = new Set(['active', 'blocked']);
+const STATUS_ALIASES = new Map([
+  ['in-progress', 'active'], ['inprogress', 'active'], ['in_progress', 'active'],
+  ['running', 'active'], ['pending', 'active'],
+  ['needs-user-decision', 'blocked'], ['needs_user_decision', 'blocked'], ['failed', 'blocked'],
+  ['complete', 'closed'], ['completed', 'closed'], ['verified', 'closed'], ['archived', 'closed'],
+  ['abandoned', 'closed'], ['obsolete', 'closed'], ['done', 'closed'], ['closeout', 'closed'],
+  ['skipped', 'closed'],
+]);
+// Only task-owning modes participate in durable WF lifecycle resume.
+export const WF_MANAGED_MODES = new Set(['wf', 'wf-max']);
+
+export function canonicalTaskStatus(value) {
+  const raw = String(value || '').trim().toLowerCase();
+  return STATUS_ALIASES.get(raw) || (OPEN_TASK_STATUSES.has(raw) || raw === 'closed' ? raw : '');
+}
+
+function canonicalMode(value) {
+  const mode = String(value || '').trim().toLowerCase();
+  return mode || 'direct';
+}
+
 function readState(taskDir) {
   const statePath = path.join(taskDir, 'STATE.json');
   if (!fs.existsSync(statePath)) return null;
@@ -8,16 +30,56 @@ function readState(taskDir) {
   catch (err) { throw new Error(`STATE.json at ${statePath} contains malformed JSON: ${err.message}`); }
 }
 
+function readJson(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) return null;
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function pushRuntime(runtimes, runtime) {
+  const value = String(runtime || '').trim();
+  if (!value) return;
+  if (!runtimes.some(item => item.toLowerCase() === value.toLowerCase())) {
+    runtimes.push(value);
+  }
+}
+
+function runtimeHistoryForTask(state, taskDir) {
+  const runtimes = [];
+  for (const key of ['defaultRuntime', 'defaultAgentRuntime', 'agentRuntime', 'cliAgent']) {
+    pushRuntime(runtimes, state?.[key]);
+  }
+  for (const key of ['runtimeHistory', 'runtimes', 'terminalRuntimes']) {
+    if (Array.isArray(state?.[key])) {
+      for (const runtime of state[key]) pushRuntime(runtimes, runtime);
+    }
+  }
+
+  const sessionsDir = path.join(taskDir, 'sessions');
+  let entries = [];
+  try { entries = fs.readdirSync(sessionsDir, { withFileTypes: true }); }
+  catch { entries = []; }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const sessionState = readJson(path.join(sessionsDir, entry.name, 'STATE.json'));
+    pushRuntime(runtimes, sessionState?.runtime);
+  }
+  return runtimes;
+}
+
 function normalizeAcceptance(acceptance) {
   if (!Array.isArray(acceptance)) return [];
   return acceptance.map((ac) => {
-    if (typeof ac === 'string') return { id: '', text: ac, status: 'pending' };
+    if (typeof ac === 'string') return { id: ac, text: '', status: 'tracked' };
     if (ac && typeof ac === 'object') return {
       id: ac.id || '',
       text: ac.text || JSON.stringify(ac),
-      status: ac.status || 'pending',
+      status: ac.status || 'tracked',
     };
-    return { id: '', text: String(ac), status: 'pending' };
+    return { id: String(ac), text: '', status: 'tracked' };
   });
 }
 
@@ -28,6 +90,8 @@ export function parseTaskCapsule(taskDir) {
     throw new Error(`STATE.json at ${taskDir} is missing required field: schemaVersion`);
   }
   const links = state.links || { dependsOn: [], blocks: [], related: [] };
+  const mode = canonicalMode(state.mode);
+  const status = canonicalTaskStatus(state.status) || 'active';
   return {
     taskId: state.taskId || path.basename(taskDir),
     status: state.status || 'unknown',
@@ -35,10 +99,19 @@ export function parseTaskCapsule(taskDir) {
     gate: state.gate || null,
     tier: state.tier || null,
     mode: state.mode || null,
+    project: String(state.project || state.group || 'default').trim() || 'default',
+    group: state.group || null,
+    tags: Array.isArray(state.tags) ? state.tags.map(tag => String(tag).trim()).filter(Boolean) : [],
+    createdAt: state.createdAt || null,
+    startedAt: state.startedAt || null,
     updatedAt: state.updatedAt || null,
+    closedAt: state.closedAt || null,
+    wfManaged: WF_MANAGED_MODES.has(mode),
+    resumeRequired: WF_MANAGED_MODES.has(mode) && OPEN_TASK_STATUSES.has(status),
     activeQuestion: state.activeQuestion || null,
     nextAction: state.nextAction || null,
     defaultRuntime: state.defaultRuntime || state.defaultAgentRuntime || state.agentRuntime || state.cliAgent || null,
+    runtimeHistory: runtimeHistoryForTask(state, taskDir),
     acceptance: normalizeAcceptance(state.acceptance),
     dependsOn: Array.isArray(links.dependsOn) ? links.dependsOn : [],
     blocks: Array.isArray(links.blocks) ? links.blocks : [],
@@ -67,6 +140,18 @@ export function parseTaskList(tasksRoot) {
   return capsules;
 }
 
+/** Read the single durable Harness focus pointer without selecting a task. */
+export function readActiveTaskId(projectRoot) {
+  try {
+    const content = fs.readFileSync(path.join(projectRoot, 'Harness', 'PROGRESS.md'), 'utf8');
+    const match = content.match(/## Active Task\s+^- ([^\r\n]+)/m);
+    const taskId = match?.[1]?.trim() || '';
+    return taskId && !/^none$/i.test(taskId) ? taskId : null;
+  } catch {
+    return null;
+  }
+}
+
 /** Parse archived tasks from _archive/YYYY/task-name/ */
 export function parseArchivedTasks(tasksRoot) {
   const archiveRoot = path.join(tasksRoot, '_archive');

package/src/wf-ui-server/terminal-store.mjs

@@ -3,6 +3,8 @@ import path from 'node:path';
 import { validateTaskId } from './security.mjs';
 
 const MAX_READ_LIMIT = 2000;
+const MAX_DROPPED_FILES = 12;
+const MAX_DROPPED_FILE_BYTES = 10 * 1024 * 1024;
 
 function validateSessionId(sessionId) {
   return validateTaskId(sessionId);
@@ -56,6 +58,83 @@ function appendJsonl(filePath, data) {
   fs.appendFileSync(filePath, `${JSON.stringify(data)}\n`, 'utf8');
 }
 
+// ── In-memory session index ──────────────────────────────────────────────────
+// Maintained by every persistSession/appendTerminalData call and rebuilt once at
+// backend startup. Snapshot fingerprinting (P1a) and the startup orphan
+// downgrade (P1b) read this instead of scanning every session dir per request.
+const sessionIndex = new Map();
+
+export function touchSessionIndex(record, { activityOnly = false } = {}) {
+  if (!record?.sessionId) return;
+  const entry = sessionIndex.get(record.sessionId) || {};
+  // activityOnly (terminal chunks/flushes) updates seq but NOT updatedAt: the
+  // snapshot fingerprint must not churn with streamed output, or every 5s
+  // poll rebuilds the snapshot and re-renders the canvas while any terminal
+  // is active.
+  const updatedAt = activityOnly
+    ? (entry.updatedAt || new Date().toISOString())
+    : (record.updatedAt ?? entry.updatedAt ?? new Date().toISOString());
+  sessionIndex.set(record.sessionId, {
+    ...entry,
+    sessionId: record.sessionId,
+    taskId: record.taskId ?? entry.taskId ?? null,
+    runtime: record.runtime ?? entry.runtime,
+    status: record.status ?? entry.status,
+    updatedAt,
+    terminalSeq: Number(record.terminalSeq ?? entry.terminalSeq ?? 0),
+  });
+}
+
+export function getSessionIndexSummary() {
+  let latestUpdatedAt = '';
+  for (const entry of sessionIndex.values()) {
+    if (String(entry.updatedAt || '') > latestUpdatedAt) latestUpdatedAt = String(entry.updatedAt);
+  }
+  return { count: sessionIndex.size, latestUpdatedAt };
+}
+
+export function getSessionIndexRecord(sessionId) {
+  return sessionIndex.get(sessionId) || null;
+}
+
+// Rebuilds the index with a single scan of all session dirs. Called once at
+// backend startup; per-request scans are gone.
+export function buildSessionIndex(projectRoot) {
+  sessionIndex.clear();
+  for (const found of allSessionDirs(projectRoot)) {
+    const state = readJson(path.join(found.dir, 'STATE.json'), null);
+    if (state) touchSessionIndex({ ...state, taskId: found.taskId });
+  }
+  return sessionIndex.size;
+}
+
+// ── One-time startup migration: orphaned live sessions ───────────────────────
+// At backend startup the in-memory registry manages nothing, so every disk
+// record with a live status is orphaned by definition (its PTY died with the
+// previous server). Persist the downgrade so snapshot, delete guards, and the
+// UI all see one consistent truth instead of "fake-live" sessions.
+export function downgradeOrphanedDiskSessions(projectRoot) {
+  const downgraded = [];
+  for (const found of allSessionDirs(projectRoot)) {
+    const state = readJson(path.join(found.dir, 'STATE.json'), null);
+    if (!state || !['running', 'starting'].includes(state.status)) continue;
+    const updated = {
+      ...state,
+      status: 'stopped',
+      blockedReason: state.blockedReason || 'not-managed-by-current-wf-ui',
+      orphanedAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+      // No clients can be attached right after a restart.
+      wsClientCount: 0,
+      attachMode: false,
+    };
+    writeJson(path.join(found.dir, 'STATE.json'), updated);
+    touchSessionIndex({ ...updated, taskId: found.taskId });
+    downgraded.push(found.sessionId);
+  }
+  return downgraded;
+}
+
 export function persistSession(projectRoot, session, patch = {}) {
   const dir = sessionDir(projectRoot, session.taskId, session.sessionId);
   const current = readJson(path.join(dir, 'STATE.json'), {});
@@ -66,6 +145,7 @@ export function persistSession(projectRoot, session, patch = {}) {
     updatedAt: new Date().toISOString(),
   };
   writeJson(path.join(dir, 'STATE.json'), state);
+  touchSessionIndex(state);
   return state;
 }
 
@@ -80,11 +160,51 @@ export function appendSessionEvent(projectRoot, session, event) {
   });
 }
 
-export function appendTerminalData(projectRoot, session, data, stream = 'stdout') {
-  const dir = sessionDir(projectRoot, session.taskId, session.sessionId);
+// ── Batched terminal writes ──────────────────────────────────────────────────
+// Per-chunk sync file I/O (read STATE.json + append terminal.jsonl + rewrite
+// STATE.json per chunk) saturated the event loop when many terminals streamed
+// at once. Entries now buffer per session and flush as ONE append + ONE state
+// write every 500ms (or at 64 entries / 64KB, whichever first). Readers flush
+// before reading, so disk reads always see the latest entry.
+const TERMINAL_FLUSH_DELAY_MS = 500;
+const TERMINAL_FLUSH_MAX_ENTRIES = 64;
+const TERMINAL_FLUSH_MAX_BYTES = 64 * 1024;
+const terminalFlushTimers = new Map();
+const terminalBuffers = new Map();
+
+export function flushTerminalBuffer(projectRoot, sessionId) {
+  const pending = terminalBuffers.get(sessionId);
+  if (!pending) return 0;
+  terminalBuffers.delete(sessionId);
+  const timer = terminalFlushTimers.get(sessionId);
+  if (timer) {
+    clearTimeout(timer);
+    terminalFlushTimers.delete(sessionId);
+  }
+  const dir = sessionDir(projectRoot, pending.taskId, sessionId);
   const statePath = path.join(dir, 'STATE.json');
-  const state = readJson(statePath, session);
-  const nextSeq = Number(state.terminalSeq || 0) + 1;
+  const state = readJson(statePath, pending.session);
+  const lines = pending.entries.map((entry) => `${JSON.stringify(entry)}\n`).join('');
+  fs.mkdirSync(dir, { recursive: true });
+  fs.appendFileSync(path.join(dir, 'terminal.jsonl'), lines, 'utf8');
+  const last = pending.entries[pending.entries.length - 1];
+  const updatedState = {
+    ...state,
+    terminalSeq: last.seq,
+    lastActivityAt: last.ts,
+    updatedAt: last.ts,
+  };
+  writeJson(statePath, updatedState);
+  touchSessionIndex(updatedState, { activityOnly: true });
+  return pending.entries.length;
+}
+
+export function appendTerminalData(projectRoot, session, data, stream = 'stdout') {
+  const indexRecord = getSessionIndexRecord(session.sessionId);
+  const baseSeq = indexRecord
+    ? Number(indexRecord.terminalSeq || 0)
+    : Number(readJson(path.join(sessionDir(projectRoot, session.taskId, session.sessionId), 'STATE.json'), {}).terminalSeq || 0);
+  const nextSeq = baseSeq + 1;
   const entry = {
     seq: nextSeq,
     ts: new Date().toISOString(),
@@ -94,13 +214,27 @@ export function appendTerminalData(projectRoot, session, data, stream = 'stdout'
     stream,
     data: String(data || ''),
   };
-  appendJsonl(path.join(dir, 'terminal.jsonl'), entry);
-  writeJson(statePath, {
-    ...state,
-    terminalSeq: nextSeq,
-    lastActivityAt: entry.ts,
-    updatedAt: entry.ts,
-  });
+  const pending = terminalBuffers.get(session.sessionId) || {
+    taskId: session.taskId,
+    session,
+    entries: [],
+    bytes: 0,
+  };
+  pending.entries.push(entry);
+  pending.bytes += entry.data.length;
+  terminalBuffers.set(session.sessionId, pending);
+  touchSessionIndex({ ...session, terminalSeq: nextSeq, updatedAt: entry.ts }, { activityOnly: true });
+
+  if (pending.entries.length >= TERMINAL_FLUSH_MAX_ENTRIES || pending.bytes >= TERMINAL_FLUSH_MAX_BYTES) {
+    flushTerminalBuffer(projectRoot, session.sessionId);
+  } else if (!terminalFlushTimers.has(session.sessionId)) {
+    const timer = setTimeout(() => {
+      terminalFlushTimers.delete(session.sessionId);
+      flushTerminalBuffer(projectRoot, session.sessionId);
+    }, TERMINAL_FLUSH_DELAY_MS);
+    timer.unref?.();
+    terminalFlushTimers.set(session.sessionId, timer);
+  }
   return entry;
 }
 
@@ -165,6 +299,8 @@ export function findTerminalSession(projectRoot, sessionId) {
 }
 
 export function readTerminalRange(projectRoot, { sessionId, fromSeq, toSeq, tail } = {}) {
+  // Disk reads always see the latest entry: flush the pending buffer first.
+  flushTerminalBuffer(projectRoot, sessionId);
   const found = findTerminalSession(projectRoot, sessionId);
   if (!found) return { sessionId, entries: [] };
   let entries = readJsonl(path.join(found.dir, 'terminal.jsonl'));
@@ -223,3 +359,81 @@ export function recordInputRequest(projectRoot, sessionId, text) {
   appendJsonl(path.join(found.dir, 'input-requests.jsonl'), event);
   return event;
 }
+
+export function writeDroppedTerminalFiles(projectRoot, sessionId, files = []) {
+  const found = findTerminalSession(projectRoot, sessionId);
+  if (!found) {
+    const err = new Error(`Session not found: ${sessionId}`);
+    err.code = 'NOT_FOUND';
+    throw err;
+  }
+  if (!Array.isArray(files)) throw new Error('files must be an array');
+  if (files.length > MAX_DROPPED_FILES) throw new Error(`Too many dropped files; max ${MAX_DROPPED_FILES}`);
+
+  const dropRoot = path.join(found.dir, 'drops');
+  fs.mkdirSync(dropRoot, { recursive: true });
+
+  const written = files.map((file, index) => {
+    const name = safeDropFileName(file?.name, index);
+    const buffer = decodeDropContent(file?.contentBase64);
+    if (buffer.byteLength > MAX_DROPPED_FILE_BYTES) {
+      throw new Error(`Dropped file is too large: ${name}`);
+    }
+    const targetPath = uniqueDropPath(dropRoot, name);
+    fs.writeFileSync(targetPath, buffer);
+    return {
+      name: path.basename(targetPath),
+      path: targetPath,
+      size: buffer.byteLength,
+      terminalText: quoteTerminalPath(targetPath),
+    };
+  });
+
+  const state = readJson(path.join(found.dir, 'STATE.json'), { sessionId, taskId: found.taskId });
+  appendSessionEvent(projectRoot, state, {
+    type: 'terminal.files.dropped',
+    count: written.length,
+    files: written.map(file => ({ name: file.name, path: file.path, size: file.size })),
+  });
+  return {
+    files: written,
+    terminalInput: written.map(file => file.terminalText).join(' '),
+  };
+}
+
+function safeDropFileName(value, index) {
+  const raw = String(value || `dropped-file-${index + 1}`);
+  const basename = raw.split(/[\\/]+/).pop() || `dropped-file-${index + 1}`;
+  const cleaned = basename
+    .replace(/[<>:"/\\|?*\x00-\x1f]/g, '_')
+    .replace(/^\.+/, '')
+    .trim();
+  return (cleaned || `dropped-file-${index + 1}`).slice(0, 160);
+}
+
+function decodeDropContent(value) {
+  const encoded = String(value || '');
+  if (encoded.length > Math.ceil(MAX_DROPPED_FILE_BYTES * 1.4)) {
+    throw new Error('Dropped file payload is too large');
+  }
+  return Buffer.from(encoded, 'base64');
+}
+
+function uniqueDropPath(dropRoot, filename) {
+  const ext = path.extname(filename);
+  const stem = path.basename(filename, ext) || 'dropped-file';
+  let candidate = path.join(dropRoot, filename);
+  for (let i = 2; fs.existsSync(candidate); i++) {
+    candidate = path.join(dropRoot, `${stem}-${i}${ext}`);
+  }
+  const resolvedRoot = path.resolve(dropRoot);
+  const resolvedCandidate = path.resolve(candidate);
+  if (resolvedCandidate !== resolvedRoot && !resolvedCandidate.startsWith(`${resolvedRoot}${path.sep}`)) {
+    throw new Error('Dropped file path escapes drop directory');
+  }
+  return resolvedCandidate;
+}
+
+function quoteTerminalPath(filePath) {
+  return `'${String(filePath).replace(/'/g, "''")}'`;
+}

package/src/wf-ui-server/timer-wakeup-scheduler.mjs

@@ -0,0 +1,226 @@
+import { fire as fireTimer, dispatchWakeup as dispatchTimerWakeup } from './workflow-node-types/timer-node.mjs'
+import { getEventNode, listEventNodes, updateEventNode } from './workflow-event-node-store.mjs'
+
+// Bounded timer wakeup scheduler (D1, M5, AC-011/AC-012, T10/T11 backend part).
+//
+// The loop is bounded, never resident:
+//  - it runs only while at least one enabled timer exists (syncTimerScheduler
+//    starts/stops it from event-node mutations, and the tick self-stops when
+//    getTimers() returns no enabled timers);
+//  - the interval handle is unref'd, so it never keeps a closed server
+//    process alive;
+//  - stopTimerScheduler() clears the handle; server.mjs stopServer() invokes
+//    it on server close, and tests call it directly on teardown.
+//
+// Each tick: for every enabled timer whose heartbeat.base.nextDueAt is due,
+// run the timer.fire flow, then dispatch a wakeup envelope into the message
+// queues of the connected/magnetic-group agent nodes (never PTY stdin).
+
+const DEFAULT_INTERVAL_MS = 1000
+
+let activeHandle = null
+
+// Set while the scheduler itself performs a store update (nextDueAt advance),
+// so event-node-store mutations made by the scheduler do not re-sync/re-arm
+// the loop and clobber the caller-chosen intervalMs config.
+let suppressingSync = false
+
+function parseTime(value) {
+  const time = Date.parse(String(value || ''))
+  return Number.isFinite(time) ? time : 0
+}
+
+function clampInteger(value, { min = 0, max = Number.MAX_SAFE_INTEGER, fallback = 0 } = {}) {
+  const number = Number(value)
+  if (!Number.isFinite(number)) return fallback
+  return Math.max(min, Math.min(max, Math.floor(number)))
+}
+
+// Builds the due-check data + bound fire flow for every enabled timer in the
+// project. Read-only apart from the `fire` closure, which is invoked by the
+// scheduler tick and advances the runtime clock after firing.
+//
+// Bounded loop semantics (F14/D11): a timer whose `loop.maxIterations` is set
+// stops advancing once `loop.runCount` reaches it — the entry is skipped and
+// the loop is marked complete (loop.enabled=false) through the event-node
+// store API, never by mutating state files directly. `loop.stopOnFailure`
+// marks the loop complete when a fire throws. Timers without a bounded loop
+// keep the existing interval behavior.
+function enabledTimerEntries(projectRoot) {
+  const entries = []
+  for (const node of listEventNodes(projectRoot)) {
+    if (String(node.type || '') !== 'timer') continue
+    const timerNodeId = node.nodeId
+    const current = getEventNode(projectRoot, timerNodeId)
+    const state = current.state
+    if (!state.enabled) continue
+    const loop = state.loop || {}
+    const maxIterations = clampInteger(loop.maxIterations, { min: 0, fallback: 0 })
+    const runCount = clampInteger(loop.runCount, { min: 0, fallback: 0 })
+    if (maxIterations > 0 && runCount >= maxIterations) continue // loop exhausted — stop advancing (F14)
+    const base = state.heartbeat?.base || {}
+    const nextDueAt = String(base.nextDueAt || '')
+    const dueAt = parseTime(nextDueAt)
+    if (!dueAt) continue // base lane not armed (disabled or not running)
+    const intervalSeconds = clampInteger(
+      base.intervalSeconds ?? state.schedule?.intervalSeconds,
+      { min: 1, fallback: 60 },
+    )
+    const mode = String(state.schedule?.mode || 'manual').toLowerCase()
+    const stopOnFailure = loop.stopOnFailure !== false
+    entries.push({
+      timerNodeId,
+      projectRoot,
+      enabled: true,
+      nextDueAt,
+      dueAt,
+      intervalSeconds,
+      mode,
+      fire: (firedAt) => {
+        try {
+          const fired = fireTimer(timerNodeId, projectRoot, {})
+          const heartbeat = current.state.heartbeat || {}
+          const nextRunCount = maxIterations > 0 ? runCount + 1 : runCount
+          const loopComplete = maxIterations > 0 && nextRunCount >= maxIterations
+          const advancePatch = {
+            revision: fired.revision,
+            heartbeat: {
+              ...heartbeat,
+              base: { ...(heartbeat.base || {}), nextDueAt: new Date(parseTime(firedAt) + intervalSeconds * 1000).toISOString() },
+            },
+          }
+          if (maxIterations > 0) {
+            advancePatch.loop = {
+              ...loop,
+              runCount: nextRunCount,
+              // Loop-complete marker persisted through the store API (F14).
+              enabled: loopComplete ? false : loop.enabled,
+            }
+          }
+          if (mode === 'once') advancePatch.enabled = false
+          suppressingSync = true
+          try {
+            updateEventNode(projectRoot, timerNodeId, advancePatch)
+          } finally {
+            suppressingSync = false
+          }
+          return fired
+        } catch (error) {
+          if (stopOnFailure && maxIterations > 0) {
+            try {
+              const failed = getEventNode(projectRoot, timerNodeId)
+              suppressingSync = true
+              try {
+                updateEventNode(projectRoot, timerNodeId, {
+                  revision: failed.node.revision,
+                  loop: { ...(failed.state.loop || {}), enabled: false },
+                })
+              } finally {
+                suppressingSync = false
+              }
+            } catch {
+              // A failed loop-complete marker must never crash the server loop.
+            }
+          }
+          throw error
+        }
+      },
+    })
+  }
+  return entries
+}
+
+function runTick({ getTimers, dispatchWakeup }) {
+  let timers
+  try {
+    timers = Array.isArray(getTimers()) ? getTimers() : []
+  } catch {
+    return
+  }
+  if (timers.length === 0) {
+    stopTimerScheduler()
+    return
+  }
+  const now = Date.now()
+  for (const timer of timers) {
+    if (!timer.enabled || !timer.dueAt || timer.dueAt > now) continue
+    const firedAt = new Date().toISOString()
+    const scheduledAt = timer.nextDueAt
+    let fired = null
+    try {
+      if (typeof timer.fire === 'function') fired = timer.fire(firedAt)
+    } catch {
+      // A failed fire must never crash the server loop; the next tick retries.
+      continue
+    }
+    if (!fired) continue
+    try {
+      dispatchWakeup({
+        projectRoot: timer.projectRoot,
+        timerNodeId: timer.timerNodeId,
+        scheduledAt,
+        firedAt,
+        intervalSeconds: timer.intervalSeconds,
+      })
+    } catch {
+      // Wakeup delivery must never crash the server loop.
+    }
+  }
+}
+
+export function startTimerScheduler({ getTimers, dispatchWakeup, intervalMs = DEFAULT_INTERVAL_MS } = {}) {
+  if (typeof getTimers !== 'function' || typeof dispatchWakeup !== 'function') return null
+  stopTimerScheduler()
+  const interval = setInterval(() => runTick({ getTimers, dispatchWakeup }), Math.max(Number(intervalMs) || DEFAULT_INTERVAL_MS, 5))
+  interval.unref?.()
+  activeHandle = { interval, getTimers, dispatchWakeup, intervalMs: Math.max(Number(intervalMs) || DEFAULT_INTERVAL_MS, 5) }
+  return activeHandle
+}
+
+export function stopTimerScheduler() {
+  if (!activeHandle) return { stopped: true, wasActive: false }
+  clearInterval(activeHandle.interval)
+  activeHandle = null
+  return { stopped: true, wasActive: true }
+}
+
+export function isTimerSchedulerActive() {
+  return activeHandle !== null
+}
+
+export function isTimerSchedulerSyncSuppressed() {
+  return suppressingSync
+}
+
+// Hook wired by workflow-event-node-store.mjs on event-node create/update/
+// delete/restore. Starts the bounded loop when any enabled timer exists,
+// stops it when none remain, and keeps the running configuration intact when
+// nothing changed (so scheduler-internal store updates do not re-arm the loop).
+export function syncTimerScheduler(projectRoot, opts = {}) {
+  if (suppressingSync) return { active: isTimerSchedulerActive() }
+  const intervalMs = Number(opts.intervalMs ?? DEFAULT_INTERVAL_MS)
+  let timers = []
+  try {
+    timers = enabledTimerEntries(projectRoot)
+  } catch {
+    return { active: isTimerSchedulerActive() }
+  }
+  if (timers.length === 0) {
+    stopTimerScheduler()
+    return { active: false, timers: 0 }
+  }
+  if (
+    activeHandle
+    && activeHandle.projectRoot === projectRoot
+    && Number(activeHandle.intervalMs) === intervalMs
+  ) {
+    return { active: true, timers: timers.length }
+  }
+  const handle = startTimerScheduler({
+    getTimers: () => enabledTimerEntries(projectRoot),
+    dispatchWakeup: (envelope) => dispatchTimerWakeup(envelope.timerNodeId, envelope.projectRoot, envelope),
+    intervalMs,
+  })
+  if (handle) handle.projectRoot = projectRoot
+  return { active: isTimerSchedulerActive(), timers: timers.length }
+}