hivehq 2.0.0

package/dist/src/server/workflow-runner.js

@@ -0,0 +1,411 @@
+import { randomUUID } from 'node:crypto';
+import { cpus } from 'node:os';
+import { dirname, join } from 'node:path';
+import { assertWindowsSafeFilename } from './windows-filename.js';
+import { resolveWorkflowCli } from './workflow-cli-policy.js';
+import { buildSchemaInstruction, extractJsonBlock } from './workflow-output-schema.js';
+import { loadWorkflowScriptFile, loadWorkflowScriptSource } from './workflow-script-loader.js';
+import { getWorkflowAgentId } from './workspace-store-support.js';
+// TIER 2 #2 + #11 — runtime caps. Match Claude Code's documented caps
+// (1000 lifetime calls, min(16, cores-2) concurrent) so scripts copied
+// from CC docs behave the same way. The duration default is Hive's own
+// choice; CC docs don't specify one but workflows that run >60min are
+// almost always a runaway loop in practice.
+const DEFAULT_MAX_AGENTS_PER_RUN = 1000;
+const DEFAULT_MAX_DURATION_MS = 60 * 60 * 1000;
+const DEFAULT_MAX_CONCURRENT_AGENTS = Math.min(16, Math.max(2, cpus().length - 2));
+const BUILT_IN_WORKER_ROLES = new Set(['coder', 'reviewer', 'tester', 'custom']);
+const isBuiltInWorkerRole = (value) => BUILT_IN_WORKER_ROLES.has(value);
+const buildModelArgs = (_cli, model) => {
+    if (!model?.trim())
+        return [];
+    /* All supported CLIs (claude / codex / opencode / gemini / hermes) accept
+       `--model <id>` as a positional flag. Keeping the mapping centralised
+       here so future CLI quirks (e.g. opencode wanting `-m` instead) can
+       be patched without touching the runner body. */
+    return ['--model', model];
+};
+const toNestedWorkflowFilename = (scriptName) => {
+    const trimmed = scriptName.trim();
+    if (!trimmed)
+        throw new Error('workflow(scriptName): scriptName must be a non-empty string');
+    const filename = trimmed.toLowerCase().endsWith('.ts') ? trimmed : `${trimmed}.ts`;
+    assertWindowsSafeFilename(filename);
+    return filename;
+};
+export const createWorkflowRunner = (deps) => {
+    const { store, workflowRunStore, awaiter, dispatchPort, resolveWorkspacePath, roleTemplateResolver, logStore, getWorkflowCliPolicy, } = deps;
+    const stoppedRuns = new Set();
+    // In-memory map: runId → triggering agent. Lost on restart; the spec already
+    // doesn't auto-resume interrupted runs, so this is consistent.
+    const triggeringAgentByRun = new Map();
+    const executeWorkflow = async (run, loaded, args, hivePort) => {
+        const workspaceId = run.workspaceId;
+        const workflowAgentId = getWorkflowAgentId(workspaceId);
+        let stepCounter = 0;
+        const spawnedWorkers = [];
+        // Read the CLI policy once per run so a 1000-way fan-out doesn't hit the
+        // app_state table per agent() call.
+        const cliPolicy = getWorkflowCliPolicy();
+        // TIER 2 #2 + #11 — runtime caps. Per-run agent ceiling, per-call
+        // concurrency throttle, and a hard wall-clock budget. meta can
+        // override the defaults per script. The budget timer arms here and
+        // gets cleared in the finally branch so a fast-completing run
+        // doesn't leave a dangling timer in the event loop.
+        const maxAgents = typeof loaded.meta.maxAgentCalls === 'number' && loaded.meta.maxAgentCalls > 0
+            ? loaded.meta.maxAgentCalls
+            : DEFAULT_MAX_AGENTS_PER_RUN;
+        const maxDurationMs = typeof loaded.meta.maxDurationMs === 'number' && loaded.meta.maxDurationMs > 0
+            ? loaded.meta.maxDurationMs
+            : DEFAULT_MAX_DURATION_MS;
+        // Simple semaphore — a FIFO queue of resolvers. Each acquire() returns
+        // a release() callback that pumps the next waiter. Default
+        // concurrency is min(16, cores-2), matching CC's documented cap;
+        // intentionally shared across all parallel/pipeline calls in this
+        // run so nested fan-outs don't blow through the cap.
+        const concurrencyLimit = DEFAULT_MAX_CONCURRENT_AGENTS;
+        let inFlight = 0;
+        const waitQueue = [];
+        const acquireSlot = async () => {
+            if (inFlight < concurrencyLimit) {
+                inFlight++;
+                return () => {
+                    inFlight--;
+                    waitQueue.shift()?.();
+                };
+            }
+            await new Promise((resolve) => waitQueue.push(resolve));
+            inFlight++;
+            return () => {
+                inFlight--;
+                waitQueue.shift()?.();
+            };
+        };
+        // R1/R2 auto-rounding: a phase('Find') called twice in the same run gets
+        // rendered as "Find" then "Find R2" etc. Mirrors Claude Code's /workflows
+        // view — keeps the UI readable when a workflow loops phases.
+        const phaseEntryCount = new Map();
+        let currentPhaseTitle = null;
+        const phase = (title) => {
+            const trimmed = (title ?? '').toString().trim() || 'default';
+            const next = (phaseEntryCount.get(trimmed) ?? 0) + 1;
+            phaseEntryCount.set(trimmed, next);
+            currentPhaseTitle = next > 1 ? `${trimmed} R${next}` : trimmed;
+            workflowRunStore.updateRun(run.id, { phase: currentPhaseTitle });
+        };
+        const agent = async (prompt, opts = {}) => {
+            // TIER 2 #11 — hard ceiling so a runaway `while (true) await agent()`
+            // can't spawn unbounded PTY subprocesses. The check is BEFORE the
+            // step counter increments so the error message names the cap, not
+            // the over-cap step.
+            if (stepCounter >= maxAgents) {
+                throw new Error(`Workflow agent cap exceeded: ${maxAgents} calls (set meta.maxAgentCalls to raise)`);
+            }
+            const myStep = ++stepCounter;
+            // TIER 2 #4 — resolve agentType. If it's a built-in WorkerRole
+            // (coder/reviewer/tester/custom) we honour it directly with the
+            // CLI default. Otherwise look up a workspace custom role template
+            // by name: on hit we clone its command + args; on miss we throw a
+            // clear error (silent fallback to 'coder' would mask typos and
+            // make the Hive-distinctive custom-role library invisible).
+            const requestedType = opts.agentType ?? 'coder';
+            let role;
+            let command;
+            let templateArgs = [];
+            if (typeof requestedType === 'string' && !isBuiltInWorkerRole(requestedType)) {
+                const template = roleTemplateResolver.findByName(requestedType);
+                if (!template) {
+                    throw new Error(`Workflow agentType '${requestedType}' is not a built-in role (coder/reviewer/tester/custom) and no matching role template exists in this workspace. ` +
+                        `Create one via Add Worker → custom role, or use a built-in role.`);
+                }
+                /* Templates can carry roleType='orchestrator' for the system-level
+                   Orchestrator template; that's not a valid workflow worker role,
+                   so we collapse it to 'custom'. Anything else maps through as-is. */
+                role = template.roleType === 'orchestrator' ? 'custom' : template.roleType;
+                command = resolveWorkflowCli({
+                    ...(opts.cli !== undefined ? { requestedCli: opts.cli } : {}),
+                    isCustomTemplate: true,
+                    templateDefaultCommand: template.defaultCommand,
+                    policy: cliPolicy,
+                });
+                templateArgs = template.defaultArgs;
+            }
+            else {
+                role = requestedType;
+                command = resolveWorkflowCli({
+                    ...(opts.cli !== undefined ? { requestedCli: opts.cli } : {}),
+                    isCustomTemplate: false,
+                    policy: cliPolicy,
+                });
+            }
+            const name = opts.label ?? `${requestedType}-${myStep}-${randomUUID()}`;
+            /* Model flag goes AFTER the template's own args so an explicit
+               opts.model overrides any --model the template baked in. */
+            const launchArgs = [...templateArgs, ...buildModelArgs(command, opts.model)];
+            // TIER 2 #2 — semaphore. Holding the slot across the full
+            // dispatch+await means a parallel(100) fan-out gets paced at
+            // min(16, cores-2) concurrent PTYs instead of 100 simultaneous
+            // process spawns.
+            const releaseSlot = await acquireSlot();
+            const worker = store.addWorkerWithLaunch(workspaceId, { name, role, ephemeral: true, spawnedBy: 'workflow' }, { command, args: launchArgs });
+            spawnedWorkers.push(worker.id);
+            try {
+                await store.startAgent(workspaceId, worker.id, { hivePort });
+                const dispatchPrompt = opts.outputSchema
+                    ? prompt + buildSchemaInstruction(opts.outputSchema)
+                    : prompt;
+                const dispatch = await store.dispatchTaskByWorkerName(workspaceId, name, dispatchPrompt, {
+                    fromAgentId: workflowAgentId,
+                    hivePort,
+                    workflowRunId: run.id,
+                    stepIndex: myStep,
+                    ...(currentPhaseTitle ? { phase: currentPhaseTitle } : {}),
+                    label: opts.label ?? name,
+                });
+                const report = await awaiter.awaitReport(dispatch.id, opts.timeoutMs);
+                // Structured output: hand back the parsed object, or { text } on a
+                // parse miss so the script can still branch (treating an absent field
+                // as the safe default).
+                if (opts.outputSchema) {
+                    return extractJsonBlock(report.text) ?? { text: report.text };
+                }
+                return report.text;
+            }
+            finally {
+                try {
+                    store.deleteWorker(workspaceId, worker.id);
+                }
+                catch {
+                    /* idempotent — worker may already be gone via cascade or boot cleanup */
+                }
+                const idx = spawnedWorkers.indexOf(worker.id);
+                if (idx !== -1)
+                    spawnedWorkers.splice(idx, 1);
+                releaseSlot();
+            }
+        };
+        // TIER 1 #3 — per-item rejections become null (preserves the
+        // documented contract: callers use `.filter(Boolean)` patterns), BUT
+        // if the run is being stopped we re-throw so the outer catch handles
+        // it as `status='stopped'` instead of silently completing with a
+        // result array full of nulls. Per-item failures still get logged so
+        // they're not entirely invisible (TIER 2 #3 will pipe these into the
+        // run timeline via log()).
+        const catchPerItem = (value) => {
+            if (stoppedRuns.has(run.id))
+                throw value;
+            console.warn(`[workflow ${loaded.meta.name}] item failed:`, value);
+            return null;
+        };
+        const parallel = async (thunks) => {
+            return Promise.all(thunks.map((thunk) => thunk().catch((err) => catchPerItem(err))));
+        };
+        const pipeline = async (items, ...stages) => {
+            return Promise.all(items.map((item, index) => {
+                let chain = Promise.resolve(item);
+                for (const stage of stages) {
+                    chain = chain.then((prev) => stage(prev, item, index));
+                }
+                return chain.catch((err) => catchPerItem(err));
+            }));
+        };
+        const log = (message) => {
+            // TIER 2 #3 — persist + still echo to stdout for server-log
+            // visibility. Authors expect `log()` to surface in the Drawer's
+            // narrator lane and in the orchestrator's completion reminder.
+            // The console.log retains the server-side breadcrumb for ops.
+            const text = typeof message === 'string' ? message : String(message);
+            try {
+                logStore.append(run.id, text);
+            }
+            catch (error) {
+                console.error('[hive] swallowed:workflow.log.append', error);
+            }
+            console.log(`[workflow ${loaded.meta.name}] ${text}`);
+        };
+        // Nested workflow: look up a sibling script in the same .hive/workflows/
+        // directory and run it through THIS runner instance. The child run gets
+        // its own row in workflow_runs and shares the dispatch-await machinery
+        // (so its `agent()` calls work the same way the parent's do).
+        //
+        // TIER 1 #7 — when the parent was fired inline (`team workflow run
+        // --stdin`), its scriptPath is the synthetic token `<inline>` /
+        // `<inline:name>`. `dirname('<inline>')` collapses to `.` and the
+        // child would resolve against the runtime's CWD — wrong directory,
+        // reliably broken. Detect the synthetic prefix and fall back to the
+        // workspace's `.hive/workflows/` directory, which is the canonical
+        // sibling-script location.
+        const isSyntheticParentPath = run.scriptPath.startsWith('<inline');
+        const workflow = async (scriptName, childArgs) => {
+            if (typeof scriptName !== 'string' || !scriptName.trim()) {
+                throw new Error('workflow(scriptName): scriptName must be a non-empty string');
+            }
+            const filename = toNestedWorkflowFilename(scriptName);
+            const childPath = isSyntheticParentPath
+                ? join(resolveWorkspacePath(workspaceId), '.hive', 'workflows', filename)
+                : join(dirname(run.scriptPath), filename);
+            return runWorkflow({
+                workspaceId,
+                scriptPath: childPath,
+                hivePort,
+                // TIER 2 #5 — stamp the parent run id so the UI can render the
+                // nested workflow tree.
+                parentRunId: run.id,
+                ...(childArgs !== undefined ? { args: childArgs } : {}),
+            });
+        };
+        // TIER 2 #11 — wall-clock budget timer. Triggers stopRun on
+        // expiry, which routes through the same path as a user-initiated
+        // stop (in-flight awaiters reject; outer catch records 'stopped').
+        // The setTimeout is unref'd so a forgotten timer can't keep the
+        // Node process alive after shutdown. stopRun is declared further
+        // down the file but exists by the time this timer fires, so the
+        // closure reference is safe.
+        const budgetTimer = setTimeout(() => {
+            log(`[hive] maxDurationMs (${maxDurationMs}ms) exceeded — stopping run`);
+            stopRun(run.id);
+        }, maxDurationMs);
+        budgetTimer.unref?.();
+        try {
+            const factory = new Function(`${loaded.compiledFunctionSource}; return __wf`);
+            const fn = factory();
+            const returnValue = await fn(agent, parallel, pipeline, phase, log, workflow, args);
+            // TIER 1 #2 — if stop was called DURING the run, parallel/pipeline may
+            // have caught the cancel rejections (one per in-flight thunk) before
+            // the per-item catch could re-throw, e.g. when the user stops AFTER
+            // the inner Promise.all has already started but BEFORE any thunk
+            // rejects. In that race we'd otherwise write 'completed' with a
+            // degraded result (often a list of nulls), which both lies to the UI
+            // and lies to the orchestrator's completion notification. Check the
+            // marker after fn returns and record the truth instead.
+            if (stoppedRuns.has(run.id)) {
+                stoppedRuns.delete(run.id);
+                workflowRunStore.updateRun(run.id, {
+                    status: 'stopped',
+                    finishedAt: Date.now(),
+                    error: 'Stopped by user',
+                });
+            }
+            else {
+                stoppedRuns.delete(run.id);
+                // M10: capture the script's return value so the UI can render a single
+                // canonical "Result" panel and the orchestrator notification can quote
+                // it. `undefined` (no explicit return) stays null on the row.
+                workflowRunStore.updateRun(run.id, {
+                    status: 'completed',
+                    finishedAt: Date.now(),
+                    ...(returnValue !== undefined ? { result: returnValue } : {}),
+                });
+            }
+        }
+        catch (error) {
+            const wasStopped = stoppedRuns.has(run.id);
+            const message = error instanceof Error ? error.message : String(error);
+            workflowRunStore.updateRun(run.id, {
+                status: wasStopped ? 'stopped' : 'failed',
+                finishedAt: Date.now(),
+                error: wasStopped ? 'Stopped by user' : message,
+            });
+            stoppedRuns.delete(run.id);
+        }
+        finally {
+            clearTimeout(budgetTimer);
+            // Belt-and-suspenders: dismiss any ephemeral worker still alive. The
+            // per-call try/finally should already have cleaned each one up; this is
+            // an idempotent safety net for unexpected paths.
+            for (const workerId of spawnedWorkers.splice(0)) {
+                try {
+                    store.deleteWorker(workspaceId, workerId);
+                }
+                catch {
+                    /* swallow */
+                }
+            }
+            // Notify the triggering agent (orchestrator) that the run reached a
+            // terminal state. Mirrors Claude Code's <task-notification> envelope.
+            const triggeredByAgentId = triggeringAgentByRun.get(run.id);
+            triggeringAgentByRun.delete(run.id);
+            if (triggeredByAgentId && deps.onRunFinished) {
+                const finalRecord = workflowRunStore.getRun(run.id);
+                if (finalRecord) {
+                    try {
+                        deps.onRunFinished({ runId: run.id, triggeredByAgentId, finalRecord });
+                    }
+                    catch (error) {
+                        console.error('[hive] swallowed:workflow.onRunFinished', error);
+                    }
+                }
+            }
+        }
+    };
+    const buildCreateInput = (input, loaded) => {
+        const createInput = {
+            workspaceId: input.workspaceId,
+            scriptPath: input.scriptPath,
+            name: loaded.meta.name,
+            scriptHash: loaded.scriptHash,
+        };
+        if (input.args !== undefined)
+            createInput.args = input.args;
+        if (input.parentRunId !== undefined)
+            createInput.parentRunId = input.parentRunId;
+        return createInput;
+    };
+    const rememberTrigger = (runId, triggeredByAgentId) => {
+        if (triggeredByAgentId)
+            triggeringAgentByRun.set(runId, triggeredByAgentId);
+    };
+    const runWorkflow = async (input) => {
+        const loaded = await loadWorkflowScriptFile(input.scriptPath);
+        const run = workflowRunStore.createRun(buildCreateInput(input, loaded));
+        rememberTrigger(run.id, input.triggeredByAgentId);
+        await executeWorkflow(run, loaded, input.args, input.hivePort);
+        const finalized = workflowRunStore.getRun(run.id);
+        if (!finalized)
+            throw new Error(`workflow run vanished mid-flight: ${run.id}`);
+        return finalized;
+    };
+    const startWorkflow = async (input) => {
+        const loaded = await loadWorkflowScriptFile(input.scriptPath);
+        const run = workflowRunStore.createRun(buildCreateInput(input, loaded));
+        rememberTrigger(run.id, input.triggeredByAgentId);
+        queueMicrotask(() => {
+            executeWorkflow(run, loaded, input.args, input.hivePort).catch((error) => {
+                console.error('[hive] swallowed:workflow.background', error);
+            });
+        });
+        return run;
+    };
+    const startWorkflowInline = async (input) => {
+        const scriptPath = input.scriptPath ?? '<inline>';
+        const loaded = await loadWorkflowScriptSource(input.source, scriptPath);
+        const run = workflowRunStore.createRun(buildCreateInput({ ...input, scriptPath }, loaded));
+        rememberTrigger(run.id, input.triggeredByAgentId);
+        queueMicrotask(() => {
+            executeWorkflow(run, loaded, input.args, input.hivePort).catch((error) => {
+                console.error('[hive] swallowed:workflow.background', error);
+            });
+        });
+        return run;
+    };
+    const stopRun = (runId) => {
+        const current = workflowRunStore.getRun(runId);
+        if (!current || current.status !== 'running')
+            return false;
+        stoppedRuns.add(runId);
+        // Cancel every open workflow dispatch tied to this run; this rejects the
+        // runner's pending `awaitReport` promises, which propagates up the
+        // executeWorkflow try → its catch sets status='stopped'.
+        for (const dispatchId of dispatchPort.listOpenDispatchIdsForRun(runId)) {
+            awaiter.notifyCancel(dispatchId, 'Stopped by user');
+        }
+        // If the script had no in-flight agent() call when stop was requested,
+        // the workflow may simply continue to its natural end. We still record
+        // the intent so a subsequent agent() call rejects immediately. To make
+        // single-step or no-agent() scripts also reflect 'stopped', mark the row
+        // synchronously as a hint to UI — the runner will overwrite to 'stopped'
+        // (or 'completed' if it really did finish) when executeWorkflow exits.
+        return true;
+    };
+    return { runWorkflow, startWorkflow, startWorkflowInline, stopRun };
+};

package/dist/src/server/workflow-schedule-create.d.ts

@@ -0,0 +1,14 @@
+import type { createWorkflowScheduleStore } from './workflow-schedule-store.js';
+type ScheduleStore = ReturnType<typeof createWorkflowScheduleStore>;
+export interface PersistWorkflowScheduleInput {
+    workspacePath: string;
+    scheduleStore: ScheduleStore;
+    workspaceId: string;
+    source: string;
+    name: string;
+    cron: string;
+    nextRunAt: number;
+    args?: unknown;
+}
+export declare const persistWorkflowSchedule: (input: PersistWorkflowScheduleInput) => Promise<import("./workflow-schedule-store.js").WorkflowScheduleRecord>;
+export {};

package/dist/src/server/workflow-schedule-create.js

@@ -0,0 +1,41 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { BadRequestError } from './http-errors.js';
+import { getWindowsFilenameError } from './windows-filename.js';
+// Agent-scheduled workflows persist their inline source to a file under
+// <workspace>/.hive/workflows/ so the existing file-based scheduler can load
+// it at fire time — no orchestrator is in the loop when cron fires, so the
+// source must outlive the request. The file is agent-managed and is
+// intentionally NOT surfaced in the UI (workflows are agent-authored, not a
+// human script library).
+const toScriptFilename = (nameRaw) => {
+    const slug = nameRaw
+        .trim()
+        .toLowerCase()
+        .replace(/\.ts$/, '')
+        .replace(/[^a-z0-9._-]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    if (!slug) {
+        throw new BadRequestError('schedule name must contain at least one alphanumeric character');
+    }
+    const windowsNameProbe = `${slug}.ts`;
+    const filenameError = getWindowsFilenameError(windowsNameProbe);
+    if (filenameError)
+        throw new BadRequestError(`Invalid workflow schedule name: ${filenameError}`);
+    return `${slug}-${randomUUID()}.ts`;
+};
+export const persistWorkflowSchedule = async (input) => {
+    const filename = toScriptFilename(input.name);
+    const dir = join(input.workspacePath, '.hive', 'workflows');
+    await mkdir(dir, { recursive: true });
+    const scriptPath = join(dir, filename);
+    await writeFile(scriptPath, input.source, 'utf8');
+    return input.scheduleStore.create({
+        workspaceId: input.workspaceId,
+        scriptPath,
+        cron: input.cron,
+        nextRunAt: input.nextRunAt,
+        ...(input.args !== undefined ? { args: input.args } : {}),
+    });
+};

package/dist/src/server/workflow-schedule-store.d.ts

@@ -0,0 +1,43 @@
+import type { Database } from 'better-sqlite3';
+export interface WorkflowScheduleRecord {
+    id: string;
+    workspaceId: string;
+    scriptPath: string;
+    cron: string;
+    args: unknown;
+    enabled: boolean;
+    lastRunAt: number | null;
+    nextRunAt: number;
+    createdAt: number;
+    updatedAt: number;
+}
+interface CreateInput {
+    workspaceId: string;
+    scriptPath: string;
+    cron: string;
+    nextRunAt: number;
+    args?: unknown;
+    enabled?: boolean;
+}
+interface UpdateInput {
+    cron?: string;
+    args?: unknown;
+    enabled?: boolean;
+    lastRunAt?: number;
+    nextRunAt?: number;
+}
+export declare const createWorkflowScheduleStore: (db: Database) => {
+    create: (input: CreateInput) => WorkflowScheduleRecord;
+    update: (id: string, input: UpdateInput) => void;
+    get: (id: string) => WorkflowScheduleRecord | undefined;
+    listForWorkspace: (workspaceId: string) => WorkflowScheduleRecord[];
+    listDueSchedules: (now: number) => WorkflowScheduleRecord[];
+    deleteSchedule: (id: string) => void;
+    claimDueSchedule: (input: {
+        id: string;
+        expectedNextRunAt: number;
+        newNextRunAt: number;
+        lastRunAt: number;
+    }) => boolean;
+};
+export {};

package/dist/src/server/workflow-schedule-store.js

@@ -0,0 +1,112 @@
+import { randomUUID } from 'node:crypto';
+const parseArgs = (value) => {
+    if (!value)
+        return null;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return null;
+    }
+};
+const toRecord = (row) => ({
+    id: row.id,
+    workspaceId: row.workspace_id,
+    scriptPath: row.script_path,
+    cron: row.cron,
+    args: parseArgs(row.args),
+    enabled: row.enabled === 1,
+    lastRunAt: row.last_run_at,
+    nextRunAt: row.next_run_at,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+});
+export const createWorkflowScheduleStore = (db) => {
+    const create = (input) => {
+        const now = Date.now();
+        const record = {
+            id: randomUUID(),
+            workspaceId: input.workspaceId,
+            scriptPath: input.scriptPath,
+            cron: input.cron,
+            args: input.args ?? null,
+            enabled: input.enabled ?? true,
+            lastRunAt: null,
+            nextRunAt: input.nextRunAt,
+            createdAt: now,
+            updatedAt: now,
+        };
+        db.prepare(`INSERT INTO workflow_schedules (
+        id, workspace_id, script_path, cron, args, enabled,
+        last_run_at, next_run_at, created_at, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(record.id, record.workspaceId, record.scriptPath, record.cron, record.args === null ? null : JSON.stringify(record.args), record.enabled ? 1 : 0, record.lastRunAt, record.nextRunAt, record.createdAt, record.updatedAt);
+        return record;
+    };
+    const update = (id, input) => {
+        const sets = [];
+        const values = [];
+        if (input.cron !== undefined) {
+            sets.push('cron = ?');
+            values.push(input.cron);
+        }
+        if (input.args !== undefined) {
+            sets.push('args = ?');
+            values.push(input.args === null ? null : JSON.stringify(input.args));
+        }
+        if (input.enabled !== undefined) {
+            sets.push('enabled = ?');
+            values.push(input.enabled ? 1 : 0);
+        }
+        if (input.lastRunAt !== undefined) {
+            sets.push('last_run_at = ?');
+            values.push(input.lastRunAt);
+        }
+        if (input.nextRunAt !== undefined) {
+            sets.push('next_run_at = ?');
+            values.push(input.nextRunAt);
+        }
+        if (sets.length === 0)
+            return;
+        sets.push('updated_at = ?');
+        values.push(Date.now());
+        values.push(id);
+        db.prepare(`UPDATE workflow_schedules SET ${sets.join(', ')} WHERE id = ?`).run(...values);
+    };
+    const get = (id) => {
+        const row = db.prepare('SELECT * FROM workflow_schedules WHERE id = ?').get(id);
+        return row ? toRecord(row) : undefined;
+    };
+    const listForWorkspace = (workspaceId) => db
+        .prepare('SELECT * FROM workflow_schedules WHERE workspace_id = ? ORDER BY created_at DESC, id DESC')
+        .all(workspaceId).map(toRecord);
+    // Enabled schedules whose next_run_at has arrived — the scheduler queries
+    // this every tick and fires each.
+    const listDueSchedules = (now) => db
+        .prepare('SELECT * FROM workflow_schedules WHERE enabled = 1 AND next_run_at <= ? ORDER BY next_run_at')
+        .all(now).map(toRecord);
+    const deleteSchedule = (id) => {
+        db.prepare('DELETE FROM workflow_schedules WHERE id = ?').run(id);
+    };
+    // TIER 1 #5 — compare-and-swap claim. If two scheduler ticks see the same
+    // due schedule (overlapping setInterval invocations, slow esbuild
+    // transpile in startWorkflow, or future multi-process), only the one
+    // whose UPDATE matches the still-original next_run_at wins. Returns
+    // true if the caller may proceed to fire the workflow.
+    const claimDueSchedule = (input) => {
+        const result = db
+            .prepare(`UPDATE workflow_schedules
+         SET next_run_at = ?, last_run_at = ?, updated_at = ?
+         WHERE id = ? AND next_run_at = ?`)
+            .run(input.newNextRunAt, input.lastRunAt, Date.now(), input.id, input.expectedNextRunAt);
+        return result.changes === 1;
+    };
+    return {
+        create,
+        update,
+        get,
+        listForWorkspace,
+        listDueSchedules,
+        deleteSchedule,
+        claimDueSchedule,
+    };
+};

package/dist/src/server/workflow-scheduler.d.ts

@@ -0,0 +1,36 @@
+import type { WorkflowRunRecord } from './workflow-run-store.js';
+import type { RunWorkflowInput } from './workflow-runner.js';
+import type { createWorkflowScheduleStore } from './workflow-schedule-store.js';
+type ScheduleStore = ReturnType<typeof createWorkflowScheduleStore>;
+export interface WorkflowSchedulerDeps {
+    schedules: ScheduleStore;
+    startWorkflow: (input: RunWorkflowInput) => Promise<WorkflowRunRecord>;
+    /** Defensive guard against orphan schedules (TIER 1 #4). The workspace
+     *  delete cascade clears workflow_schedules in the same transaction so
+     *  fresh orphans cannot appear; this port catches any pre-existing or
+     *  externally-introduced orphan and self-heals by deleting the schedule
+     *  before it can fire and crash startWorkflow → re-fire next tick. */
+    workspaceExists?: (workspaceId: string) => boolean;
+    /** HivePort to pass into every fired workflow. Resolved lazily so the
+     *  scheduler doesn't need to be reconstructed when the runtime listens
+     *  on a different port (e.g. tests using port 0). */
+    getHivePort?: () => string;
+    /** Test seam: defaults to cron-parser. Returns next fire time in ms-epoch. */
+    computeNextRunAt?: (cron: string, after: Date) => number;
+    /** Experimental workflow gate. When provided and returns false, ticks fire
+     *  nothing (scheduled runs are held, not dropped — they fire once re-enabled).
+     *  Omitted → no gate (the scheduler unit tests rely on this default). */
+    isWorkflowEnabled?: () => boolean;
+}
+export interface WorkflowScheduler {
+    /** Run one tick using the given `now` (ms-epoch). For both production and tests. */
+    tick: (now?: number) => Promise<void>;
+    /** Arm a setInterval that calls tick() every `tickIntervalMs`. Returns void. */
+    start: (input?: {
+        tickIntervalMs?: number;
+    }) => void;
+    /** Clear the timer. Idempotent. */
+    close: () => void;
+}
+export declare const createWorkflowScheduler: (deps: WorkflowSchedulerDeps) => WorkflowScheduler;
+export {};