@hasna/loops 0.1.0 → 0.3.0

package/dist/cli/index.js

@@ -236,6 +236,103 @@ function parseDuration(input) {
   return Math.round(value * multiplier);
 }
 
+// src/lib/workflow-spec.ts
+function assertObject(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error(`${label} must be an object`);
+}
+function assertString(value, label) {
+  if (typeof value !== "string" || value.trim() === "")
+    throw new Error(`${label} must be a non-empty string`);
+}
+function validateTarget(value, label) {
+  assertObject(value, label);
+  if (value.type === "command") {
+    assertString(value.command, `${label}.command`);
+    if (value.shell !== true && /\s/.test(value.command.trim())) {
+      throw new Error(`${label}.command must be an executable without spaces when shell is false; put flags in args or set shell true`);
+    }
+    return value;
+  }
+  if (value.type === "agent") {
+    assertString(value.provider, `${label}.provider`);
+    assertString(value.prompt, `${label}.prompt`);
+    const providers = ["claude", "cursor", "codewith", "aicopilot", "opencode", "codex"];
+    if (!providers.includes(value.provider))
+      throw new Error(`${label}.provider must be one of ${providers.join(", ")}`);
+    return value;
+  }
+  throw new Error(`${label}.type must be command or agent`);
+}
+function normalizeCreateWorkflowInput(input) {
+  assertString(input.name, "workflow.name");
+  if (!Array.isArray(input.steps) || input.steps.length === 0)
+    throw new Error("workflow.steps must contain at least one step");
+  const seen = new Set;
+  const steps = input.steps.map((step, index) => {
+    assertObject(step, `workflow.steps[${index}]`);
+    assertString(step.id, `workflow.steps[${index}].id`);
+    if (seen.has(step.id))
+      throw new Error(`duplicate workflow step id: ${step.id}`);
+    seen.add(step.id);
+    return {
+      ...step,
+      id: step.id,
+      target: validateTarget(step.target, `workflow.steps[${index}].target`),
+      dependsOn: step.dependsOn ?? [],
+      continueOnFailure: step.continueOnFailure ?? false
+    };
+  });
+  for (const step of steps) {
+    for (const dependency of step.dependsOn ?? []) {
+      if (!seen.has(dependency))
+        throw new Error(`step ${step.id} depends on missing step ${dependency}`);
+      if (dependency === step.id)
+        throw new Error(`step ${step.id} cannot depend on itself`);
+    }
+  }
+  workflowExecutionOrder({ steps });
+  return { ...input, name: input.name.trim(), version: input.version ?? 1, steps };
+}
+function workflowExecutionOrder(workflow) {
+  const byId = new Map(workflow.steps.map((step) => [step.id, step]));
+  const visiting = new Set;
+  const visited = new Set;
+  const order = [];
+  function visit(step) {
+    if (visited.has(step.id))
+      return;
+    if (visiting.has(step.id))
+      throw new Error(`workflow dependency cycle includes step ${step.id}`);
+    visiting.add(step.id);
+    for (const dependencyId of step.dependsOn ?? []) {
+      const dependency = byId.get(dependencyId);
+      if (!dependency)
+        throw new Error(`step ${step.id} depends on missing step ${dependencyId}`);
+      visit(dependency);
+    }
+    visiting.delete(step.id);
+    visited.add(step.id);
+    order.push(step);
+  }
+  for (const step of workflow.steps)
+    visit(step);
+  return order;
+}
+function workflowBodyFromJson(value, fallbackName) {
+  assertObject(value, "workflow file");
+  const rawName = fallbackName ?? value.name;
+  assertString(rawName, "workflow.name");
+  if (!Array.isArray(value.steps))
+    throw new Error("workflow.steps must be an array");
+  return normalizeCreateWorkflowInput({
+    name: rawName,
+    description: typeof value.description === "string" ? value.description : undefined,
+    version: typeof value.version === "number" ? value.version : undefined,
+    steps: value.steps
+  });
+}
+
 // src/lib/store.ts
 function rowToLoop(row) {
   return {
@@ -280,6 +377,76 @@ function rowToRun(row) {
     updatedAt: row.updated_at
   };
 }
+function rowToWorkflow(row) {
+  return {
+    id: row.id,
+    name: row.name,
+    description: row.description ?? undefined,
+    version: row.version,
+    status: row.status,
+    steps: JSON.parse(row.steps_json),
+    createdAt: row.created_at,
+    updatedAt: row.updated_at
+  };
+}
+function rowToWorkflowRun(row) {
+  return {
+    id: row.id,
+    workflowId: row.workflow_id,
+    workflowName: row.workflow_name,
+    loopId: row.loop_id ?? undefined,
+    loopRunId: row.loop_run_id ?? undefined,
+    scheduledFor: row.scheduled_for ?? undefined,
+    idempotencyKey: row.idempotency_key ?? undefined,
+    status: row.status,
+    startedAt: row.started_at ?? undefined,
+    finishedAt: row.finished_at ?? undefined,
+    durationMs: row.duration_ms ?? undefined,
+    error: row.error ?? undefined,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at
+  };
+}
+function rowToWorkflowStepRun(row) {
+  return {
+    id: row.id,
+    workflowRunId: row.workflow_run_id,
+    stepId: row.step_id,
+    sequence: row.sequence,
+    status: row.status,
+    startedAt: row.started_at ?? undefined,
+    finishedAt: row.finished_at ?? undefined,
+    exitCode: row.exit_code ?? undefined,
+    pid: row.pid ?? undefined,
+    durationMs: row.duration_ms ?? undefined,
+    stdout: row.stdout ?? undefined,
+    stderr: row.stderr ?? undefined,
+    error: row.error ?? undefined,
+    accountProfile: row.account_profile ?? undefined,
+    accountTool: row.account_tool ?? undefined,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at
+  };
+}
+function rowToWorkflowEvent(row) {
+  return {
+    id: row.id,
+    workflowRunId: row.workflow_run_id,
+    sequence: row.sequence,
+    eventType: row.event_type,
+    stepId: row.step_id ?? undefined,
+    payload: row.payload_json ? JSON.parse(row.payload_json) : undefined,
+    createdAt: row.created_at
+  };
+}
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
 function rowToLease(row) {
   return {
     id: row.id,
@@ -305,6 +472,11 @@ class Store {
   }
   migrate() {
     this.db.exec(`
+      CREATE TABLE IF NOT EXISTS schema_migrations (
+        id TEXT PRIMARY KEY,
+        applied_at TEXT NOT NULL
+      );
+
       CREATE TABLE IF NOT EXISTS loops (
         id TEXT PRIMARY KEY,
         name TEXT NOT NULL,
@@ -361,7 +533,82 @@ class Store {
         created_at TEXT NOT NULL,
         updated_at TEXT NOT NULL
       );
+
+      CREATE TABLE IF NOT EXISTS workflow_specs (
+        id TEXT PRIMARY KEY,
+        name TEXT NOT NULL,
+        description TEXT,
+        version INTEGER NOT NULL,
+        status TEXT NOT NULL,
+        steps_json TEXT NOT NULL,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_workflows_status_name ON workflow_specs(status, name);
+      CREATE UNIQUE INDEX IF NOT EXISTS idx_workflows_name_active ON workflow_specs(name) WHERE status = 'active';
+
+      CREATE TABLE IF NOT EXISTS workflow_runs (
+        id TEXT PRIMARY KEY,
+        workflow_id TEXT NOT NULL REFERENCES workflow_specs(id) ON DELETE CASCADE,
+        workflow_name TEXT NOT NULL,
+        loop_id TEXT REFERENCES loops(id) ON DELETE SET NULL,
+        loop_run_id TEXT REFERENCES loop_runs(id) ON DELETE SET NULL,
+        scheduled_for TEXT,
+        idempotency_key TEXT,
+        status TEXT NOT NULL,
+        started_at TEXT,
+        finished_at TEXT,
+        duration_ms INTEGER,
+        error TEXT,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      );
+      CREATE UNIQUE INDEX IF NOT EXISTS idx_workflow_runs_idempotency
+        ON workflow_runs(workflow_id, idempotency_key)
+        WHERE idempotency_key IS NOT NULL;
+      CREATE INDEX IF NOT EXISTS idx_workflow_runs_workflow_created ON workflow_runs(workflow_id, created_at DESC);
+      CREATE INDEX IF NOT EXISTS idx_workflow_runs_loop_run ON workflow_runs(loop_run_id);
+      CREATE INDEX IF NOT EXISTS idx_workflow_runs_status ON workflow_runs(status);
+
+      CREATE TABLE IF NOT EXISTS workflow_step_runs (
+        id TEXT PRIMARY KEY,
+        workflow_run_id TEXT NOT NULL REFERENCES workflow_runs(id) ON DELETE CASCADE,
+        step_id TEXT NOT NULL,
+        sequence INTEGER NOT NULL,
+        status TEXT NOT NULL,
+        started_at TEXT,
+        finished_at TEXT,
+        exit_code INTEGER,
+        pid INTEGER,
+        duration_ms INTEGER,
+        stdout TEXT,
+        stderr TEXT,
+        error TEXT,
+        account_profile TEXT,
+        account_tool TEXT,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL,
+        UNIQUE(workflow_run_id, step_id)
+      );
+      CREATE INDEX IF NOT EXISTS idx_workflow_step_runs_run_sequence ON workflow_step_runs(workflow_run_id, sequence);
+      CREATE INDEX IF NOT EXISTS idx_workflow_step_runs_status ON workflow_step_runs(status);
+
+      CREATE TABLE IF NOT EXISTS workflow_events (
+        id TEXT PRIMARY KEY,
+        workflow_run_id TEXT NOT NULL REFERENCES workflow_runs(id) ON DELETE CASCADE,
+        sequence INTEGER NOT NULL,
+        event_type TEXT NOT NULL,
+        step_id TEXT,
+        payload_json TEXT,
+        created_at TEXT NOT NULL,
+        UNIQUE(workflow_run_id, sequence)
+      );
+      CREATE INDEX IF NOT EXISTS idx_workflow_events_run_sequence ON workflow_events(workflow_run_id, sequence);
     `);
+    try {
+      this.db.query("ALTER TABLE workflow_step_runs ADD COLUMN pid INTEGER").run();
+    } catch {}
+    this.db.query("INSERT OR IGNORE INTO schema_migrations (id, applied_at) VALUES (?, ?)").run("0001_initial_and_workflows", nowIso());
   }
   createLoop(input, from = new Date) {
     const now = nowIso();
@@ -453,10 +700,343 @@ class Store {
     const res = this.db.query("DELETE FROM loops WHERE id = ?").run(loop.id);
     return res.changes > 0;
   }
+  createWorkflow(input) {
+    const normalized = normalizeCreateWorkflowInput(input);
+    const now = nowIso();
+    const workflow = {
+      id: genId(),
+      name: normalized.name,
+      description: normalized.description,
+      version: normalized.version ?? 1,
+      status: "active",
+      steps: normalized.steps,
+      createdAt: now,
+      updatedAt: now
+    };
+    this.db.query(`INSERT INTO workflow_specs (id, name, description, version, status, steps_json, created_at, updated_at)
+         VALUES ($id, $name, $description, $version, $status, $steps, $created, $updated)`).run({
+      $id: workflow.id,
+      $name: workflow.name,
+      $description: workflow.description ?? null,
+      $version: workflow.version,
+      $status: workflow.status,
+      $steps: JSON.stringify(workflow.steps),
+      $created: workflow.createdAt,
+      $updated: workflow.updatedAt
+    });
+    return workflow;
+  }
+  getWorkflow(id) {
+    const row = this.db.query("SELECT * FROM workflow_specs WHERE id = ?").get(id);
+    return row ? rowToWorkflow(row) : undefined;
+  }
+  findWorkflowByName(name) {
+    const row = this.db.query("SELECT * FROM workflow_specs WHERE name = ? AND status = 'active' ORDER BY updated_at DESC LIMIT 1").get(name);
+    return row ? rowToWorkflow(row) : undefined;
+  }
+  requireWorkflow(idOrName) {
+    return this.getWorkflow(idOrName) ?? this.findWorkflowByName(idOrName) ?? (() => {
+      throw new Error(`workflow not found: ${idOrName}`);
+    })();
+  }
+  listWorkflows(opts = {}) {
+    const limit = opts.limit ?? 200;
+    const rows = opts.status ? this.db.query("SELECT * FROM workflow_specs WHERE status = ? ORDER BY updated_at DESC LIMIT ?").all(opts.status, limit) : this.db.query("SELECT * FROM workflow_specs ORDER BY status ASC, updated_at DESC LIMIT ?").all(limit);
+    return rows.map(rowToWorkflow);
+  }
+  archiveWorkflow(idOrName) {
+    const workflow = this.requireWorkflow(idOrName);
+    const updated = nowIso();
+    this.db.query("UPDATE workflow_specs SET status='archived', updated_at=? WHERE id=?").run(updated, workflow.id);
+    const archived = this.getWorkflow(workflow.id);
+    if (!archived)
+      throw new Error(`workflow not found after archive: ${workflow.id}`);
+    return archived;
+  }
+  createWorkflowRun(input) {
+    const now = nowIso();
+    if (input.idempotencyKey) {
+      const existing = this.db.query("SELECT * FROM workflow_runs WHERE workflow_id = ? AND idempotency_key = ? LIMIT 1").get(input.workflow.id, input.idempotencyKey);
+      if (existing)
+        return rowToWorkflowRun(existing);
+    }
+    this.db.exec("BEGIN IMMEDIATE");
+    try {
+      if (input.idempotencyKey) {
+        const existing = this.db.query("SELECT * FROM workflow_runs WHERE workflow_id = ? AND idempotency_key = ? LIMIT 1").get(input.workflow.id, input.idempotencyKey);
+        if (existing) {
+          this.db.exec("COMMIT");
+          return rowToWorkflowRun(existing);
+        }
+      }
+      const runId = genId();
+      this.db.query(`INSERT INTO workflow_runs (id, workflow_id, workflow_name, loop_id, loop_run_id, scheduled_for, idempotency_key,
+            status, started_at, finished_at, duration_ms, error, created_at, updated_at)
+           VALUES ($id, $workflowId, $workflowName, $loopId, $loopRunId, $scheduledFor, $idempotencyKey,
+            'running', $started, NULL, NULL, NULL, $created, $updated)`).run({
+        $id: runId,
+        $workflowId: input.workflow.id,
+        $workflowName: input.workflow.name,
+        $loopId: input.loop?.id ?? null,
+        $loopRunId: input.loopRun?.id ?? null,
+        $scheduledFor: input.scheduledFor ?? input.loopRun?.scheduledFor ?? null,
+        $idempotencyKey: input.idempotencyKey ?? null,
+        $started: now,
+        $created: now,
+        $updated: now
+      });
+      input.workflow.steps.forEach((step, sequence) => {
+        const account = step.account ?? step.target.account;
+        this.db.query(`INSERT INTO workflow_step_runs (id, workflow_run_id, step_id, sequence, status, started_at, finished_at,
+              exit_code, pid, duration_ms, stdout, stderr, error, account_profile, account_tool, created_at, updated_at)
+             VALUES ($id, $workflowRunId, $stepId, $sequence, 'pending', NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL,
+              $accountProfile, $accountTool, $created, $updated)`).run({
+          $id: genId(),
+          $workflowRunId: runId,
+          $stepId: step.id,
+          $sequence: sequence,
+          $accountProfile: account?.profile ?? null,
+          $accountTool: account?.tool ?? null,
+          $created: now,
+          $updated: now
+        });
+      });
+      this.db.query(`INSERT INTO workflow_events (id, workflow_run_id, sequence, event_type, step_id, payload_json, created_at)
+           VALUES ($id, $workflowRunId, 1, 'created', NULL, $payload, $created)`).run({
+        $id: genId(),
+        $workflowRunId: runId,
+        $payload: JSON.stringify({
+          workflowId: input.workflow.id,
+          workflowName: input.workflow.name,
+          stepCount: input.workflow.steps.length,
+          loopId: input.loop?.id,
+          loopRunId: input.loopRun?.id
+        }),
+        $created: now
+      });
+      this.db.exec("COMMIT");
+      const run = this.getWorkflowRun(runId);
+      if (!run)
+        throw new Error(`workflow run not found after create: ${runId}`);
+      return run;
+    } catch (error) {
+      try {
+        this.db.exec("ROLLBACK");
+      } catch {}
+      throw error;
+    }
+  }
+  getWorkflowRun(id) {
+    const row = this.db.query("SELECT * FROM workflow_runs WHERE id = ?").get(id);
+    return row ? rowToWorkflowRun(row) : undefined;
+  }
+  requireWorkflowRun(id) {
+    const run = this.getWorkflowRun(id);
+    if (!run)
+      throw new Error(`workflow run not found: ${id}`);
+    return run;
+  }
+  listWorkflowRuns(opts = {}) {
+    const limit = opts.limit ?? 100;
+    let rows;
+    if (opts.workflowId) {
+      rows = this.db.query("SELECT * FROM workflow_runs WHERE workflow_id = ? ORDER BY created_at DESC LIMIT ?").all(opts.workflowId, limit);
+    } else if (opts.loopRunId) {
+      rows = this.db.query("SELECT * FROM workflow_runs WHERE loop_run_id = ? ORDER BY created_at DESC LIMIT ?").all(opts.loopRunId, limit);
+    } else {
+      rows = this.db.query("SELECT * FROM workflow_runs ORDER BY created_at DESC LIMIT ?").all(limit);
+    }
+    return rows.map(rowToWorkflowRun);
+  }
+  listWorkflowStepRuns(workflowRunId) {
+    const rows = this.db.query("SELECT * FROM workflow_step_runs WHERE workflow_run_id = ? ORDER BY sequence ASC").all(workflowRunId);
+    return rows.map(rowToWorkflowStepRun);
+  }
+  getWorkflowStepRun(workflowRunId, stepId) {
+    const row = this.db.query("SELECT * FROM workflow_step_runs WHERE workflow_run_id = ? AND step_id = ?").get(workflowRunId, stepId);
+    return row ? rowToWorkflowStepRun(row) : undefined;
+  }
+  isWorkflowRunTerminal(workflowRunId) {
+    const run = this.getWorkflowRun(workflowRunId);
+    return Boolean(run && ["succeeded", "failed", "timed_out", "cancelled"].includes(run.status));
+  }
+  startWorkflowStepRun(workflowRunId, stepId) {
+    const now = nowIso();
+    const res = this.db.query(`UPDATE workflow_step_runs
+         SET status='running', started_at=$started, finished_at=NULL, exit_code=NULL, duration_ms=NULL,
+          pid=NULL, stdout=NULL, stderr=NULL, error=NULL, updated_at=$updated
+         WHERE workflow_run_id=$workflowRunId
+           AND step_id=$stepId
+           AND status IN ('pending', 'failed', 'timed_out')
+           AND EXISTS (
+             SELECT 1 FROM workflow_runs
+             WHERE id=$workflowRunId AND status='running'
+           )`).run({ $workflowRunId: workflowRunId, $stepId: stepId, $started: now, $updated: now });
+    const run = this.getWorkflowStepRun(workflowRunId, stepId);
+    if (!run)
+      throw new Error(`workflow step run not found: ${workflowRunId}/${stepId}`);
+    if (res.changes !== 1) {
+      throw new Error(`workflow step is not claimable: ${workflowRunId}/${stepId} status=${run.status}`);
+    }
+    this.appendWorkflowEvent(workflowRunId, "step_started", stepId);
+    return run;
+  }
+  markWorkflowStepPid(workflowRunId, stepId, pid) {
+    const now = nowIso();
+    this.db.query(`UPDATE workflow_step_runs SET pid=$pid, updated_at=$updated
+         WHERE workflow_run_id=$workflowRunId AND step_id=$stepId AND status='running'`).run({ $workflowRunId: workflowRunId, $stepId: stepId, $pid: pid, $updated: now });
+    const run = this.getWorkflowStepRun(workflowRunId, stepId);
+    if (!run)
+      throw new Error(`workflow step run not found after pid update: ${workflowRunId}/${stepId}`);
+    return run;
+  }
+  recoverWorkflowRun(workflowRunId, reason = "workflow run recovered for retry") {
+    const now = nowIso();
+    const before = this.listWorkflowStepRuns(workflowRunId).filter((step) => step.status === "running");
+    const live = before.filter((step) => step.pid !== undefined && isProcessAlive(step.pid));
+    if (live.length > 0) {
+      throw new Error(`cannot recover workflow run while step processes are still alive: ${live.map((step) => `${step.stepId} pid=${step.pid}`).join(", ")}`);
+    }
+    this.db.query(`UPDATE workflow_step_runs
+         SET status='pending', started_at=NULL, finished_at=NULL, exit_code=NULL, pid=NULL, duration_ms=NULL,
+          stdout=NULL, stderr=NULL, error=$reason, updated_at=$updated
+         WHERE workflow_run_id=$workflowRunId AND status='running'`).run({ $workflowRunId: workflowRunId, $reason: reason, $updated: now });
+    if (before.length > 0) {
+      this.appendWorkflowEvent(workflowRunId, "recovered", undefined, {
+        reason,
+        recoveredSteps: before.map((step) => step.stepId)
+      });
+    }
+    return {
+      run: this.requireWorkflowRun(workflowRunId),
+      recoveredSteps: before.map((step) => this.getWorkflowStepRun(workflowRunId, step.stepId)).filter(Boolean)
+    };
+  }
+  finalizeWorkflowStepRun(workflowRunId, stepId, patch) {
+    const finishedAt = patch.finishedAt ?? nowIso();
+    const res = this.db.query(`UPDATE workflow_step_runs SET status=$status, finished_at=$finished, exit_code=$exitCode, duration_ms=$durationMs,
+         pid=NULL, stdout=$stdout, stderr=$stderr, error=$error, updated_at=$updated
+         WHERE workflow_run_id=$workflowRunId AND step_id=$stepId AND status='running'`).run({
+      $workflowRunId: workflowRunId,
+      $stepId: stepId,
+      $status: patch.status,
+      $finished: finishedAt,
+      $exitCode: patch.exitCode ?? null,
+      $durationMs: patch.durationMs ?? null,
+      $stdout: patch.stdout ?? null,
+      $stderr: patch.stderr ?? null,
+      $error: patch.error ?? null,
+      $updated: finishedAt
+    });
+    if (res.changes === 1) {
+      this.appendWorkflowEvent(workflowRunId, `step_${patch.status}`, stepId, {
+        exitCode: patch.exitCode,
+        error: patch.error
+      });
+    }
+    const run = this.getWorkflowStepRun(workflowRunId, stepId);
+    if (!run)
+      throw new Error(`workflow step run not found after finalize: ${workflowRunId}/${stepId}`);
+    return run;
+  }
+  skipWorkflowStepRun(workflowRunId, stepId, reason) {
+    const now = nowIso();
+    const res = this.db.query(`UPDATE workflow_step_runs SET status='skipped', finished_at=$finished, pid=NULL, error=$error, updated_at=$updated
+         WHERE workflow_run_id=$workflowRunId AND step_id=$stepId AND status IN ('pending', 'running')`).run({ $workflowRunId: workflowRunId, $stepId: stepId, $finished: now, $error: reason, $updated: now });
+    if (res.changes === 1)
+      this.appendWorkflowEvent(workflowRunId, "step_skipped", stepId, { reason });
+    const run = this.getWorkflowStepRun(workflowRunId, stepId);
+    if (!run)
+      throw new Error(`workflow step run not found after skip: ${workflowRunId}/${stepId}`);
+    return run;
+  }
+  finalizeWorkflowRun(workflowRunId, status, patch = {}) {
+    const finishedAt = patch.finishedAt ?? nowIso();
+    const res = this.db.query(`UPDATE workflow_runs SET status=$status, finished_at=$finished, duration_ms=$durationMs, error=$error, updated_at=$updated
+         WHERE id=$id AND status NOT IN ('succeeded', 'failed', 'timed_out', 'cancelled')`).run({
+      $id: workflowRunId,
+      $status: status,
+      $finished: finishedAt,
+      $durationMs: patch.durationMs ?? null,
+      $error: patch.error ?? null,
+      $updated: finishedAt
+    });
+    const run = this.getWorkflowRun(workflowRunId);
+    if (!run)
+      throw new Error(`workflow run not found after finalize: ${workflowRunId}`);
+    if (res.changes === 1)
+      this.appendWorkflowEvent(workflowRunId, status, undefined, { error: patch.error });
+    return run;
+  }
+  cancelWorkflowRun(workflowRunId, reason = "cancelled by user") {
+    const now = nowIso();
+    this.db.exec("BEGIN IMMEDIATE");
+    try {
+      const run = this.requireWorkflowRun(workflowRunId);
+      if (!["succeeded", "failed", "timed_out", "cancelled"].includes(run.status)) {
+        this.db.query(`UPDATE workflow_runs
+             SET status='cancelled', finished_at=$finished, error=$reason, updated_at=$updated
+             WHERE id=$id AND status NOT IN ('succeeded', 'failed', 'timed_out', 'cancelled')`).run({ $id: workflowRunId, $finished: now, $reason: reason, $updated: now });
+        this.db.query(`UPDATE workflow_step_runs
+             SET status='cancelled', finished_at=$finished, pid=NULL, error=$reason, updated_at=$updated
+             WHERE workflow_run_id=$workflowRunId AND status IN ('pending', 'running')`).run({ $workflowRunId: workflowRunId, $finished: now, $reason: reason, $updated: now });
+        this.appendWorkflowEvent(workflowRunId, "cancelled", undefined, { reason });
+      }
+      this.db.exec("COMMIT");
+      return this.requireWorkflowRun(workflowRunId);
+    } catch (error) {
+      try {
+        this.db.exec("ROLLBACK");
+      } catch {}
+      throw error;
+    }
+  }
+  appendWorkflowEvent(workflowRunId, eventType, stepId, payload) {
+    const now = nowIso();
+    const current = this.db.query("SELECT MAX(sequence) AS sequence FROM workflow_events WHERE workflow_run_id = ?").get(workflowRunId);
+    const sequence = (current?.sequence ?? 0) + 1;
+    const id = genId();
+    this.db.query(`INSERT INTO workflow_events (id, workflow_run_id, sequence, event_type, step_id, payload_json, created_at)
+         VALUES ($id, $workflowRunId, $sequence, $eventType, $stepId, $payload, $created)`).run({
+      $id: id,
+      $workflowRunId: workflowRunId,
+      $sequence: sequence,
+      $eventType: eventType,
+      $stepId: stepId ?? null,
+      $payload: payload ? JSON.stringify(payload) : null,
+      $created: now
+    });
+    const event = this.db.query("SELECT * FROM workflow_events WHERE id = ?").get(id);
+    if (!event)
+      throw new Error(`workflow event not found after append: ${id}`);
+    return rowToWorkflowEvent(event);
+  }
+  listWorkflowEvents(workflowRunId, limit = 200) {
+    const rows = this.db.query("SELECT * FROM workflow_events WHERE workflow_run_id = ? ORDER BY sequence ASC LIMIT ?").all(workflowRunId, limit);
+    return rows.map(rowToWorkflowEvent);
+  }
   hasRunningRun(loopId) {
     const row = this.db.query("SELECT COUNT(*) AS count FROM loop_runs WHERE loop_id = ? AND status = 'running'").get(loopId);
     return (row?.count ?? 0) > 0;
   }
+  markRunPid(id, pid, claimedBy) {
+    const now = nowIso();
+    const res = claimedBy ? this.db.query(`UPDATE loop_runs SET pid=$pid, updated_at=$updated
+             WHERE id=$id AND status='running' AND claimed_by=$claimedBy`).run({ $id: id, $pid: pid, $updated: now, $claimedBy: claimedBy }) : this.db.query("UPDATE loop_runs SET pid=$pid, updated_at=$updated WHERE id=$id AND status='running'").run({ $id: id, $pid: pid, $updated: now });
+    if (res.changes !== 1)
+      return;
+    return this.getRun(id);
+  }
+  hasLiveWorkflowStepProcesses(loopRunId) {
+    const liveWorkflowSteps = this.db.query(`SELECT wr.id AS workflow_run_id, wsr.step_id AS step_id, wsr.pid AS pid
+         FROM workflow_runs wr
+         JOIN workflow_step_runs wsr ON wsr.workflow_run_id = wr.id
+         WHERE wr.loop_run_id = ?
+           AND wr.status NOT IN ('succeeded', 'failed', 'timed_out', 'cancelled')
+           AND wsr.status = 'running'
+           AND wsr.pid IS NOT NULL`).all(loopRunId);
+    return liveWorkflowSteps.some((step) => isProcessAlive(step.pid));
+  }
   createSkippedRun(loop, scheduledFor, reason) {
     const now = nowIso();
     const run = {
@@ -504,6 +1084,14 @@ class Store {
       const existing = this.getRunBySlot(loop.id, scheduledFor);
       if (existing) {
         if (existing.status === "running") {
+          if (existing.leaseExpiresAt && existing.leaseExpiresAt <= startedAt && existing.pid && isProcessAlive(existing.pid)) {
+            this.db.exec("COMMIT");
+            return;
+          }
+          if (existing.leaseExpiresAt && existing.leaseExpiresAt <= startedAt && this.hasLiveWorkflowStepProcesses(existing.id)) {
+            this.db.exec("COMMIT");
+            return;
+          }
           const res3 = this.db.query(`UPDATE loop_runs SET status='running', started_at=$started, finished_at=NULL,
                claimed_by=$claimedBy, lease_expires_at=$lease, pid=NULL, exit_code=NULL,
                duration_ms=NULL, stdout=NULL, stderr=NULL, error=NULL, updated_at=$updated
@@ -573,10 +1161,9 @@ class Store {
       throw error;
     }
   }
-  finalizeRun(id, patch) {
+  finalizeRun(id, patch, opts = {}) {
     const finishedAt = patch.finishedAt ?? nowIso();
-    this.db.query(`UPDATE loop_runs SET status=$status, finished_at=$finished, lease_expires_at=NULL, pid=$pid, exit_code=$exitCode,
-         duration_ms=$durationMs, stdout=$stdout, stderr=$stderr, error=$error, updated_at=$updated WHERE id=$id`).run({
+    const params = {
       $id: id,
       $status: patch.status,
       $finished: finishedAt,
@@ -586,13 +1173,29 @@ class Store {
       $stdout: patch.stdout ?? null,
       $stderr: patch.stderr ?? null,
       $error: patch.error ?? null,
-      $updated: finishedAt
-    });
+      $updated: finishedAt,
+      $claimedBy: opts.claimedBy ?? null,
+      $now: (opts.now ?? new Date).toISOString()
+    };
+    const res = opts.claimedBy ? this.db.query(`UPDATE loop_runs SET status=$status, finished_at=$finished, lease_expires_at=NULL, pid=$pid, exit_code=$exitCode,
+             duration_ms=$durationMs, stdout=$stdout, stderr=$stderr, error=$error, updated_at=$updated
+             WHERE id=$id AND status='running' AND claimed_by=$claimedBy AND lease_expires_at > $now`).run(params) : this.db.query(`UPDATE loop_runs SET status=$status, finished_at=$finished, lease_expires_at=NULL, pid=$pid, exit_code=$exitCode,
+             duration_ms=$durationMs, stdout=$stdout, stderr=$stderr, error=$error, updated_at=$updated WHERE id=$id`).run(params);
     const run = this.getRun(id);
     if (!run)
       throw new Error(`run not found after finalize: ${id}`);
+    if (opts.claimedBy && res.changes !== 1)
+      return run;
     return run;
   }
+  heartbeatRunLease(id, claimedBy, leaseMs, now = new Date) {
+    const expiresAt = new Date(now.getTime() + leaseMs).toISOString();
+    const res = this.db.query(`UPDATE loop_runs SET lease_expires_at=$expires, updated_at=$updated
+         WHERE id=$id AND status='running' AND claimed_by=$claimedBy`).run({ $id: id, $claimedBy: claimedBy, $expires: expiresAt, $updated: now.toISOString() });
+    if (res.changes !== 1)
+      return;
+    return this.getRun(id);
+  }
   listRuns(opts = {}) {
     const limit = opts.limit ?? 100;
     let rows;
@@ -611,8 +1214,26 @@ class Store {
     const rows = this.db.query("SELECT * FROM loop_runs WHERE status = 'running' AND lease_expires_at <= ?").all(now.toISOString());
     const recovered = [];
     for (const row of rows) {
+      if (row.pid && isProcessAlive(row.pid))
+        continue;
+      if (this.hasLiveWorkflowStepProcesses(row.id))
+        continue;
+      const finished = now.toISOString();
       this.db.query(`UPDATE loop_runs SET status='abandoned', finished_at=$finished, lease_expires_at=NULL,
-           error='run lease expired before completion', updated_at=$updated WHERE id=$id`).run({ $id: row.id, $finished: now.toISOString(), $updated: now.toISOString() });
+           error='run lease expired before completion', updated_at=$updated WHERE id=$id`).run({ $id: row.id, $finished: finished, $updated: finished });
+      const workflowRows = this.db.query("SELECT * FROM workflow_runs WHERE loop_run_id = ? AND status NOT IN ('succeeded', 'failed', 'timed_out', 'cancelled')").all(row.id);
+      for (const workflowRow of workflowRows) {
+        this.db.query(`UPDATE workflow_runs
+             SET status='failed', finished_at=$finished, error='parent loop run lease expired before completion', updated_at=$updated
+             WHERE id=$id AND status NOT IN ('succeeded', 'failed', 'timed_out', 'cancelled')`).run({ $id: workflowRow.id, $finished: finished, $updated: finished });
+        this.db.query(`UPDATE workflow_step_runs
+             SET status='skipped', finished_at=$finished, pid=NULL, error='parent loop run lease expired before completion', updated_at=$updated
+             WHERE workflow_run_id=$workflowRunId AND status IN ('pending', 'running')`).run({ $workflowRunId: workflowRow.id, $finished: finished, $updated: finished });
+        this.appendWorkflowEvent(workflowRow.id, "failed", undefined, {
+          error: "parent loop run lease expired before completion",
+          loopRunId: row.id
+        });
+      }
       const run = this.getRun(row.id);
       if (run)
         recovered.push(run);
@@ -684,7 +1305,7 @@ class Store {
 }
 
 // src/cli/index.ts
-import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { existsSync as existsSync4, readFileSync as readFileSync2 } from "fs";
 import { Command } from "commander";
 
 // src/lib/format.ts
@@ -696,7 +1317,7 @@ function redact(value, visible = 80) {
   return `${value.slice(0, visible)}... [redacted ${value.length - visible} chars]`;
 }
 function publicLoop(loop) {
-  const target = loop.target.type === "command" ? { ...loop.target, env: loop.target.env ? "[redacted]" : undefined } : { ...loop.target, prompt: redact(loop.target.prompt) };
+  const target = loop.target.type === "command" ? { ...loop.target, env: loop.target.env ? "[redacted]" : undefined } : loop.target.type === "agent" ? { ...loop.target, prompt: redact(loop.target.prompt) } : loop.target;
   return {
     ...loop,
     target
@@ -709,12 +1330,150 @@ function publicRun(run, showOutput = false) {
     stderr: showOutput ? run.stderr : run.stderr ? `[redacted ${run.stderr.length} chars]` : undefined
   };
 }
+function publicWorkflow(workflow) {
+  return {
+    ...workflow,
+    steps: workflow.steps.map((step) => ({
+      ...step,
+      target: step.target.type === "agent" ? { ...step.target, prompt: redact(step.target.prompt) } : step.target.type === "command" && step.target.env ? { ...step.target, env: "[redacted]" } : step.target
+    }))
+  };
+}
+function publicWorkflowRun(run) {
+  return { ...run };
+}
+function publicWorkflowStepRun(run, showOutput = false) {
+  return {
+    ...run,
+    stdout: showOutput ? run.stdout : run.stdout ? `[redacted ${run.stdout.length} chars]` : undefined,
+    stderr: showOutput ? run.stderr : run.stderr ? `[redacted ${run.stderr.length} chars]` : undefined
+  };
+}
+function publicWorkflowEvent(event) {
+  return { ...event };
+}
+
+// src/lib/executor.ts
+import { spawn, spawnSync as spawnSync2 } from "child_process";
+import { once } from "events";
+import { existsSync as existsSync2 } from "fs";
+
+// src/lib/accounts.ts
+import { spawnSync } from "child_process";
+import { existsSync } from "fs";
+var EXPORT_RE = /^export\s+([A-Za-z_][A-Za-z0-9_]*)=(.*)$/;
+function accountToolForProvider(provider) {
+  switch (provider) {
+    case "claude":
+      return "claude";
+    case "cursor":
+      return "cursor";
+    case "codewith":
+      return "codewith";
+    case "aicopilot":
+      return "aicopilot";
+    case "opencode":
+      return "opencode";
+    case "codex":
+      return "codex";
+  }
+}
+function parseExportValue(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return raw.replace(/^['"]|['"]$/g, "");
+  }
+}
+function parseAccountExportLines(output) {
+  const env = {};
+  for (const line of output.split(/\r?\n/)) {
+    const match = EXPORT_RE.exec(line.trim());
+    if (!match)
+      continue;
+    env[match[1]] = parseExportValue(match[2]);
+  }
+  return env;
+}
+function primaryAccountDir(output) {
+  for (const line of output.split(/\r?\n/)) {
+    const match = EXPORT_RE.exec(line.trim());
+    if (!match)
+      continue;
+    return parseExportValue(match[2]);
+  }
+  return;
+}
+function accountDirEnvVar(tool) {
+  switch (tool) {
+    case "claude":
+      return "CLAUDE_CONFIG_DIR";
+    case "codex":
+    case "codex-app":
+      return "CODEX_HOME";
+    case "cursor":
+      return "CURSOR_CONFIG_DIR";
+    case "opencode":
+      return "OPENCODE_CONFIG_DIR";
+    case "codewith":
+      return "CODEWITH_HOME";
+    case "aicopilot":
+      return "AICOPILOT_CONFIG_DIR";
+    default:
+      return;
+  }
+}
+function resolveAccountEnv(account, toolHint, env) {
+  if (!account)
+    return {};
+  const tool = account.tool ?? toolHint;
+  if (!tool)
+    throw new Error("account.tool is required when no provider tool can be inferred");
+  const result = spawnSync("accounts", ["env", account.profile, "--tool", tool], {
+    encoding: "utf8",
+    env,
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  if (result.error) {
+    throw new Error(`failed to run accounts env for ${account.profile}/${tool}: ${result.error.message}`);
+  }
+  if ((result.status ?? 0) !== 0) {
+    const stderr = result.stderr.trim();
+    throw new Error(`accounts env failed for ${account.profile}/${tool}${stderr ? `: ${stderr}` : ""}`);
+  }
+  const accountEnv = parseAccountExportLines(result.stdout);
+  const profileDir = (accountDirEnvVar(tool) ? accountEnv[accountDirEnvVar(tool)] : undefined) ?? primaryAccountDir(result.stdout);
+  if (!profileDir)
+    throw new Error(`accounts env returned no profile directory for ${account.profile}/${tool}`);
+  if (!existsSync(profileDir))
+    throw new Error(`account profile directory does not exist for ${account.profile}/${tool}: ${profileDir}`);
+  return {
+    ...accountEnv,
+    LOOPS_ACCOUNT_PROFILE: account.profile,
+    LOOPS_ACCOUNT_TOOL: tool
+  };
+}
 
 // src/lib/executor.ts
-import { spawn } from "child_process";
-import { once } from "events";
 var DEFAULT_TIMEOUT_MS = 30 * 60000;
 var DEFAULT_MAX_OUTPUT_BYTES = 256 * 1024;
+var AUTH_ENV_KEYS = [
+  "CLAUDE_CONFIG_DIR",
+  "CODEWITH_HOME",
+  "CODEX_HOME",
+  "CURSOR_CONFIG_DIR",
+  "OPENCODE_CONFIG_DIR",
+  "AICOPILOT_CONFIG_DIR",
+  "ANTHROPIC_API_KEY",
+  "OPENAI_API_KEY",
+  "OPENROUTER_API_KEY",
+  "GITHUB_TOKEN",
+  "GH_TOKEN",
+  "XDG_CONFIG_HOME",
+  "XDG_DATA_HOME",
+  "XDG_STATE_HOME",
+  "XDG_CACHE_HOME"
+];
 function appendBounded(current, chunk, maxBytes) {
   const next = current + chunk.toString("utf8");
   if (Buffer.byteLength(next, "utf8") <= maxBytes)
@@ -753,6 +1512,8 @@ function providerCommand(provider) {
       return "aicopilot";
     case "opencode":
       return "opencode";
+    case "codex":
+      return "codex";
   }
 }
 function agentArgs(target) {
@@ -789,6 +1550,16 @@ function agentArgs(target) {
         args.push("--agent", target.agent);
       args.push(...target.extraArgs ?? [], target.prompt);
       return args;
+    case "codex":
+      args.push("exec", "--json", "--ephemeral", "--ask-for-approval", "never", "--sandbox", "workspace-write");
+      if (isolation === "safe")
+        args.push("--ignore-rules");
+      if (target.cwd)
+        args.push("--cd", target.cwd);
+      if (target.model)
+        args.push("--model", target.model);
+      args.push(...target.extraArgs ?? [], target.prompt);
+      return args;
     case "aicopilot":
       args.push("run", "--format", "json");
       if (isolation === "safe")
@@ -815,8 +1586,7 @@ function agentArgs(target) {
       return args;
   }
 }
-function commandSpec(loop) {
-  const target = loop.target;
+function commandSpec(target) {
   if (target.type === "command") {
     const commandTarget = target;
     return {
@@ -825,7 +1595,9 @@ function commandSpec(loop) {
       cwd: commandTarget.cwd,
       shell: commandTarget.shell,
       env: commandTarget.env,
-      timeoutMs: commandTarget.timeoutMs ?? DEFAULT_TIMEOUT_MS
+      timeoutMs: commandTarget.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      account: commandTarget.account,
+      accountTool: commandTarget.account?.tool
     };
   }
   const agentTarget = target;
@@ -833,11 +1605,61 @@ function commandSpec(loop) {
     command: providerCommand(agentTarget.provider),
     args: agentArgs(agentTarget),
     cwd: agentTarget.cwd,
-    timeoutMs: agentTarget.timeoutMs ?? DEFAULT_TIMEOUT_MS
+    timeoutMs: agentTarget.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    account: agentTarget.account,
+    accountTool: agentTarget.account?.tool ?? accountToolForProvider(agentTarget.provider)
   };
 }
-async function executeLoop(loop, run, opts = {}) {
-  const spec = commandSpec(loop);
+function executionEnv(spec, metadata, opts) {
+  const env = { ...opts.env ?? process.env };
+  if (spec.account) {
+    const accountEnv = resolveAccountEnv(spec.account, spec.accountTool, env);
+    for (const key of AUTH_ENV_KEYS)
+      delete env[key];
+    Object.assign(env, accountEnv);
+  }
+  Object.assign(env, spec.env ?? {});
+  if (metadata.loopId)
+    env.LOOPS_LOOP_ID = metadata.loopId;
+  if (metadata.loopName)
+    env.LOOPS_LOOP_NAME = metadata.loopName;
+  if (metadata.runId)
+    env.LOOPS_RUN_ID = metadata.runId;
+  if (metadata.scheduledFor)
+    env.LOOPS_SCHEDULED_FOR = metadata.scheduledFor;
+  if (metadata.workflowId)
+    env.LOOPS_WORKFLOW_ID = metadata.workflowId;
+  if (metadata.workflowName)
+    env.LOOPS_WORKFLOW_NAME = metadata.workflowName;
+  if (metadata.workflowRunId)
+    env.LOOPS_WORKFLOW_RUN_ID = metadata.workflowRunId;
+  if (metadata.workflowStepId)
+    env.LOOPS_WORKFLOW_STEP_ID = metadata.workflowStepId;
+  return env;
+}
+function commandExists(command, env) {
+  if (command.includes("/") && existsSync2(command))
+    return true;
+  const result = spawnSync2("sh", ["-c", 'command -v "$1" >/dev/null', "sh", command], {
+    env,
+    stdio: "ignore"
+  });
+  return (result.status ?? 1) === 0;
+}
+function preflightTarget(target, metadata = {}, opts = {}) {
+  const spec = commandSpec(target);
+  const env = executionEnv(spec, metadata, opts);
+  if (!spec.shell && !commandExists(spec.command, env)) {
+    throw new Error(`Executable not found in PATH: ${spec.command}`);
+  }
+  return {
+    command: spec.command,
+    accountProfile: spec.account?.profile,
+    accountTool: spec.accountTool
+  };
+}
+async function executeTarget(target, metadata = {}, opts = {}) {
+  const spec = commandSpec(target);
   const maxOutputBytes = opts.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
   const startedAt = nowIso();
   let stdout = "";
@@ -845,14 +1667,18 @@ async function executeLoop(loop, run, opts = {}) {
   let timedOut = false;
   let exitCode;
   let error;
-  const env = {
-    ...opts.env ?? process.env,
-    ...spec.env ?? {},
-    LOOPS_LOOP_ID: loop.id,
-    LOOPS_LOOP_NAME: loop.name,
-    LOOPS_RUN_ID: run.id,
-    LOOPS_SCHEDULED_FOR: run.scheduledFor
-  };
+  const env = executionEnv(spec, metadata, opts);
+  if (!spec.shell && !commandExists(spec.command, env)) {
+    return {
+      status: "failed",
+      stdout: "",
+      stderr: "",
+      error: `Executable not found in PATH: ${spec.command}`,
+      startedAt,
+      finishedAt: nowIso(),
+      durationMs: 0
+    };
+  }
   const child = spawn(spec.command, spec.args, {
     cwd: spec.cwd,
     env,
@@ -860,6 +1686,16 @@ async function executeLoop(loop, run, opts = {}) {
     detached: true,
     stdio: ["ignore", "pipe", "pipe"]
   });
+  if (child.pid)
+    opts.onSpawn?.(child.pid);
+  const abortHandler = () => {
+    error = "cancelled";
+    if (child.pid)
+      killProcessGroup(child.pid);
+  };
+  if (opts.signal?.aborted)
+    abortHandler();
+  opts.signal?.addEventListener("abort", abortHandler, { once: true });
   child.stdout.on("data", (chunk) => {
     stdout = appendBounded(stdout, chunk, maxOutputBytes);
   });
@@ -882,6 +1718,7 @@ async function executeLoop(loop, run, opts = {}) {
     error = err instanceof Error ? err.message : String(err);
   } finally {
     clearTimeout(timer);
+    opts.signal?.removeEventListener("abort", abortHandler);
   }
   const finishedAt = nowIso();
   const durationMs = new Date(finishedAt).getTime() - new Date(startedAt).getTime();
@@ -922,12 +1759,243 @@ async function executeLoop(loop, run, opts = {}) {
     durationMs
   };
 }
+async function executeLoop(loop, run, opts = {}) {
+  if (loop.target.type === "workflow") {
+    throw new Error("workflow loop targets must be executed with executeLoopTarget");
+  }
+  return executeTarget(loop.target, {
+    loopId: loop.id,
+    loopName: loop.name,
+    runId: run.id,
+    scheduledFor: run.scheduledFor
+  }, opts);
+}
+
+// src/lib/workflow-runner.ts
+function targetWithStepAccount(step) {
+  const account = step.account ?? step.target.account;
+  const timeoutMs = step.timeoutMs ?? step.target.timeoutMs;
+  if (!account && timeoutMs === step.target.timeoutMs)
+    return step.target;
+  return { ...step.target, account, timeoutMs };
+}
+function workflowResult(workflowRun, status, startedAt, finishedAt, stdout, error) {
+  const executorStatus = status === "succeeded" ? "succeeded" : status === "timed_out" ? "timed_out" : "failed";
+  return {
+    status: executorStatus,
+    exitCode: executorStatus === "succeeded" ? 0 : 1,
+    stdout,
+    stderr: "",
+    error,
+    startedAt,
+    finishedAt,
+    durationMs: new Date(finishedAt).getTime() - new Date(startedAt).getTime()
+  };
+}
+async function executeWorkflow(store, workflow, opts = {}) {
+  const run = store.createWorkflowRun({
+    workflow,
+    loop: opts.loop,
+    loopRun: opts.loopRun,
+    scheduledFor: opts.scheduledFor,
+    idempotencyKey: opts.idempotencyKey
+  });
+  const startedAt = run.startedAt ?? nowIso();
+  if (run.status === "succeeded" || run.status === "failed" || run.status === "timed_out" || run.status === "cancelled") {
+    const steps2 = store.listWorkflowStepRuns(run.id);
+    return workflowResult(run, run.status, startedAt, run.finishedAt ?? nowIso(), JSON.stringify({ workflowRun: run, steps: steps2 }, null, 2), run.error);
+  }
+  const ordered = workflowExecutionOrder(workflow);
+  const byId = new Map(workflow.steps.map((step) => [step.id, step]));
+  let blockingError;
+  let terminalStatus = "succeeded";
+  for (const step of ordered) {
+    if (store.isWorkflowRunTerminal(run.id)) {
+      terminalStatus = store.requireWorkflowRun(run.id).status;
+      blockingError = "workflow run was cancelled";
+      break;
+    }
+    const pendingTimeout = opts.signal?.aborted ? opts.signalTimeoutMessage?.() : undefined;
+    if (pendingTimeout) {
+      terminalStatus = "timed_out";
+      blockingError = pendingTimeout;
+      break;
+    }
+    const existing = store.getWorkflowStepRun(run.id, step.id);
+    if (existing?.status === "succeeded" || existing?.status === "skipped" || existing?.status === "cancelled")
+      continue;
+    const blockedBy = (step.dependsOn ?? []).find((dependencyId) => {
+      const dependencyRun = store.getWorkflowStepRun(run.id, dependencyId);
+      const dependencyStep = byId.get(dependencyId);
+      if (dependencyRun?.status === "succeeded")
+        return false;
+      return !dependencyStep?.continueOnFailure;
+    });
+    if (blockedBy) {
+      store.skipWorkflowStepRun(run.id, step.id, `dependency did not succeed: ${blockedBy}`);
+      blockingError ??= `step ${step.id} blocked by dependency ${blockedBy}`;
+      terminalStatus = "failed";
+      continue;
+    }
+    const startedStep = store.startWorkflowStepRun(run.id, step.id);
+    if (startedStep.status !== "running") {
+      terminalStatus = "failed";
+      blockingError = `step ${step.id} could not start because workflow is no longer running`;
+      break;
+    }
+    const metadata = {
+      loopId: opts.loop?.id,
+      loopName: opts.loop?.name,
+      runId: opts.loopRun?.id,
+      scheduledFor: opts.loopRun?.scheduledFor ?? opts.scheduledFor,
+      workflowId: workflow.id,
+      workflowName: workflow.name,
+      workflowRunId: run.id,
+      workflowStepId: step.id
+    };
+    let result;
+    const controller = new AbortController;
+    const externalAbort = () => controller.abort();
+    if (opts.signal?.aborted)
+      controller.abort();
+    opts.signal?.addEventListener("abort", externalAbort, { once: true });
+    const cancelTimer = setInterval(() => {
+      if (store.getWorkflowRun(run.id)?.status === "cancelled")
+        controller.abort();
+    }, opts.cancelPollMs ?? 500);
+    cancelTimer.unref();
+    try {
+      result = await executeTarget(targetWithStepAccount(step), metadata, {
+        ...opts,
+        signal: controller.signal,
+        onSpawn: (pid) => {
+          store.markWorkflowStepPid(run.id, step.id, pid);
+          opts.onSpawn?.(pid);
+        }
+      });
+    } catch (error) {
+      const finishedAt2 = nowIso();
+      result = {
+        status: "failed",
+        stdout: "",
+        stderr: "",
+        error: error instanceof Error ? error.message : String(error),
+        startedAt: startedStep.startedAt ?? finishedAt2,
+        finishedAt: finishedAt2,
+        durationMs: new Date(finishedAt2).getTime() - new Date(startedStep.startedAt ?? finishedAt2).getTime()
+      };
+    } finally {
+      clearInterval(cancelTimer);
+      opts.signal?.removeEventListener("abort", externalAbort);
+    }
+    const timeoutMessage = opts.signal?.aborted ? opts.signalTimeoutMessage?.() : undefined;
+    if (timeoutMessage && result.status === "failed") {
+      result = { ...result, status: "timed_out", error: timeoutMessage };
+    }
+    if (store.isWorkflowRunTerminal(run.id)) {
+      terminalStatus = store.requireWorkflowRun(run.id).status;
+      blockingError = "workflow run was cancelled";
+      break;
+    }
+    store.finalizeWorkflowStepRun(run.id, step.id, {
+      status: result.status,
+      finishedAt: result.finishedAt,
+      durationMs: result.durationMs,
+      stdout: result.stdout,
+      stderr: result.stderr,
+      exitCode: result.exitCode,
+      error: result.error
+    });
+    if (result.status !== "succeeded" && !step.continueOnFailure) {
+      terminalStatus = result.status;
+      blockingError = `step ${step.id} ${result.status}${result.error ? `: ${result.error}` : ""}`;
+      break;
+    }
+  }
+  if (terminalStatus !== "succeeded") {
+    for (const step of ordered) {
+      const existing = store.getWorkflowStepRun(run.id, step.id);
+      if (existing?.status === "pending" || existing?.status === "running") {
+        store.skipWorkflowStepRun(run.id, step.id, blockingError ?? "workflow stopped before step could run");
+      }
+    }
+  }
+  const finishedAt = nowIso();
+  if (store.isWorkflowRunTerminal(run.id)) {
+    const terminalRun = store.requireWorkflowRun(run.id);
+    const steps2 = store.listWorkflowStepRuns(run.id);
+    return workflowResult(terminalRun, terminalRun.status, startedAt, terminalRun.finishedAt ?? finishedAt, JSON.stringify({ workflowRun: terminalRun, steps: steps2 }, null, 2), terminalRun.error ?? blockingError);
+  }
+  const finalRun = store.finalizeWorkflowRun(run.id, terminalStatus, {
+    finishedAt,
+    durationMs: new Date(finishedAt).getTime() - new Date(startedAt).getTime(),
+    error: blockingError
+  });
+  const steps = store.listWorkflowStepRuns(run.id);
+  return workflowResult(finalRun, terminalStatus, startedAt, finishedAt, JSON.stringify({ workflowRun: finalRun, steps }, null, 2), blockingError);
+}
+function preflightWorkflow(workflow, opts = {}) {
+  return workflowExecutionOrder(workflow).map((step) => preflightTarget(targetWithStepAccount(step), {
+    workflowId: workflow.id,
+    workflowName: workflow.name,
+    workflowStepId: step.id
+  }, opts));
+}
+async function executeLoopTarget(store, loop, run, opts = {}) {
+  if (loop.target.type !== "workflow")
+    return executeLoop(loop, run, opts);
+  const workflow = store.requireWorkflow(loop.target.workflowId);
+  const controller = loop.target.timeoutMs ? new AbortController : undefined;
+  let workflowTimedOut = false;
+  const externalAbort = () => controller?.abort();
+  if (controller && opts.signal?.aborted)
+    controller.abort();
+  if (controller)
+    opts.signal?.addEventListener("abort", externalAbort, { once: true });
+  const timer = controller ? setTimeout(() => {
+    workflowTimedOut = true;
+    controller.abort();
+  }, loop.target.timeoutMs) : undefined;
+  timer?.unref();
+  try {
+    return await executeWorkflow(store, workflow, {
+      ...opts,
+      signal: controller?.signal ?? opts.signal,
+      signalTimeoutMessage: () => workflowTimedOut && loop.target.type === "workflow" ? `workflow timed out after ${loop.target.timeoutMs}ms` : undefined,
+      loop,
+      loopRun: run,
+      scheduledFor: run.scheduledFor,
+      idempotencyKey: `${loop.id}:${run.scheduledFor}:attempt:${run.attempt}`
+    });
+  } finally {
+    if (timer)
+      clearTimeout(timer);
+    if (controller)
+      opts.signal?.removeEventListener("abort", externalAbort);
+  }
+}
 
 // src/lib/scheduler.ts
+function manualRunScheduledFor(loop, now = new Date) {
+  if (loop.nextRunAt && new Date(loop.nextRunAt).getTime() <= now.getTime()) {
+    return loop.retryScheduledFor ?? loop.nextRunAt;
+  }
+  return now.toISOString();
+}
+function shouldAdvanceManualRun(loop, scheduledFor, now = new Date) {
+  if (!loop.nextRunAt || new Date(loop.nextRunAt).getTime() > now.getTime())
+    return false;
+  return scheduledFor === (loop.retryScheduledFor ?? loop.nextRunAt);
+}
 function nextAfterRetry(loop, now) {
   return new Date(now.getTime() + loop.retryDelayMs).toISOString();
 }
 function advanceLoop(store, loop, run, finishedAt, succeeded) {
+  if (run.status === "running")
+    return;
+  const current = store.getLoop(loop.id);
+  if (!current || current.status !== "active")
+    return;
   const shouldRetry = !succeeded && run.attempt < loop.maxAttempts;
   if (shouldRetry) {
     store.updateLoop(loop.id, {
@@ -944,21 +2012,18 @@ function advanceLoop(store, loop, run, finishedAt, succeeded) {
     retryScheduledFor: undefined
   });
 }
-async function runSlot(deps, loop, scheduledFor) {
-  const now = deps.now?.() ?? new Date;
-  if (loop.overlap === "skip" && deps.store.hasRunningRun(loop.id)) {
-    const skipped = deps.store.createSkippedRun(loop, scheduledFor, "previous run still active");
-    advanceLoop(deps.store, loop, skipped, now, true);
-    deps.onRun?.(skipped);
-    return skipped;
-  }
-  const claim = deps.store.claimRun(loop, scheduledFor, deps.runnerId, now);
-  if (!claim)
-    return;
-  deps.onRun?.(claim.run);
+async function executeClaimedRun(deps) {
+  let heartbeat;
+  const heartbeatEveryMs = Math.max(10, Math.min(60000, Math.floor(deps.loop.leaseMs / 3)));
+  heartbeat = setInterval(() => {
+    deps.store.heartbeatRunLease(deps.run.id, deps.runnerId, deps.loop.leaseMs);
+  }, heartbeatEveryMs);
+  heartbeat.unref();
   try {
-    const result = await (deps.execute ?? executeLoop)(claim.loop, claim.run);
-    const finalRun = deps.store.finalizeRun(claim.run.id, {
+    const result = await (deps.execute ?? ((loop, run) => executeLoopTarget(deps.store, loop, run, {
+      onSpawn: (pid) => deps.store.markRunPid(run.id, pid, deps.runnerId)
+    })))(deps.loop, deps.run);
+    return deps.store.finalizeRun(deps.run.id, {
       status: result.status,
       finishedAt: result.finishedAt,
       durationMs: result.durationMs,
@@ -967,25 +2032,53 @@ async function runSlot(deps, loop, scheduledFor) {
       exitCode: result.exitCode,
       error: result.error,
       pid: result.pid
+    }, {
+      claimedBy: deps.runnerId,
+      now: deps.now?.() ?? new Date(result.finishedAt)
     });
-    advanceLoop(deps.store, claim.loop, finalRun, new Date(result.finishedAt), result.status === "succeeded");
-    deps.onRun?.(finalRun);
-    return finalRun;
   } catch (err) {
-    deps.onError?.(claim.loop, err);
+    deps.onError?.(deps.loop, err);
     const finishedAt = new Date;
-    const finalRun = deps.store.finalizeRun(claim.run.id, {
+    return deps.store.finalizeRun(deps.run.id, {
       status: "failed",
       finishedAt: finishedAt.toISOString(),
-      durationMs: finishedAt.getTime() - new Date(claim.run.startedAt ?? claim.run.createdAt).getTime(),
+      durationMs: finishedAt.getTime() - new Date(deps.run.startedAt ?? deps.run.createdAt).getTime(),
       stdout: "",
       stderr: "",
       error: err instanceof Error ? err.message : String(err)
+    }, {
+      claimedBy: deps.runnerId,
+      now: deps.now?.() ?? finishedAt
     });
-    advanceLoop(deps.store, claim.loop, finalRun, finishedAt, false);
-    deps.onRun?.(finalRun);
-    return finalRun;
+  } finally {
+    if (heartbeat)
+      clearInterval(heartbeat);
+  }
+}
+async function runSlot(deps, loop, scheduledFor) {
+  const now = deps.now?.() ?? new Date;
+  if (loop.overlap === "skip" && deps.store.hasRunningRun(loop.id)) {
+    const skipped = deps.store.createSkippedRun(loop, scheduledFor, "previous run still active");
+    advanceLoop(deps.store, loop, skipped, now, true);
+    deps.onRun?.(skipped);
+    return skipped;
   }
+  const claim = deps.store.claimRun(loop, scheduledFor, deps.runnerId, now);
+  if (!claim)
+    return;
+  deps.onRun?.(claim.run);
+  const finalRun = await executeClaimedRun({
+    store: deps.store,
+    runnerId: deps.runnerId,
+    loop: claim.loop,
+    run: claim.run,
+    now: deps.now,
+    execute: deps.execute,
+    onError: deps.onError
+  });
+  advanceLoop(deps.store, claim.loop, finalRun, new Date(finalRun.finishedAt ?? new Date), finalRun.status === "succeeded");
+  deps.onRun?.(finalRun);
+  return finalRun;
 }
 async function tick(deps) {
   const now = deps.now?.() ?? new Date;
@@ -1011,13 +2104,15 @@ async function tick(deps) {
         skipped.push(run);
       else
         completed.push(run);
+      if (["failed", "timed_out", "abandoned"].includes(run.status) && run.attempt < loop.maxAttempts)
+        break;
     }
   }
   return { claimed, completed, skipped, recovered, expired };
 }
 
 // src/daemon/control.ts
-import { existsSync, mkdirSync as mkdirSync3, readFileSync, rmSync, writeFileSync } from "fs";
+import { existsSync as existsSync3, mkdirSync as mkdirSync3, readFileSync, rmSync, writeFileSync } from "fs";
 import { hostname } from "os";
 import { dirname as dirname2 } from "path";
 
@@ -1045,7 +2140,7 @@ async function runLoop(opts) {
 
 // src/daemon/control.ts
 function readPid(path = pidFilePath()) {
-  if (!existsSync(path))
+  if (!existsSync3(path))
     return;
   try {
     const pid = Number(readFileSync(path, "utf8").trim());
@@ -1163,6 +2258,7 @@ async function runDaemon(opts = {}) {
   const ownStore = !opts.store;
   const store = opts.store ?? new Store;
   const leaseId = genId();
+  const runnerId = `${hostname2()}:${process.pid}:${leaseId}`;
   const intervalMs = opts.intervalMs ?? intervalFromEnv() ?? 1000;
   const leaseTtlMs = opts.leaseTtlMs ?? Math.max(60000, intervalMs * 10);
   const log = opts.log ?? ((message) => console.error(`[loops-daemon] ${message}`));
@@ -1178,18 +2274,28 @@ async function runDaemon(opts = {}) {
   log(`started pid=${process.pid} interval=${intervalMs}ms lease=${leaseId}`);
   let stopFlag = false;
   let leaseLost = false;
+  const runAbort = new AbortController;
+  const requestStop = (message) => {
+    stopFlag = true;
+    if (!runAbort.signal.aborted)
+      runAbort.abort();
+    if (message)
+      log(message);
+  };
   const ensureLease = () => {
     const current = store.heartbeatDaemonLease(leaseId, leaseTtlMs);
     if (!current || current.id !== leaseId) {
       leaseLost = true;
-      stopFlag = true;
+      requestStop("daemon lease lost");
       throw new Error("daemon lease lost");
     }
   };
   const onSignal = () => {
-    stopFlag = true;
-    log("stop signal received");
+    requestStop("stop signal received");
   };
+  if (opts.signal?.aborted)
+    onSignal();
+  opts.signal?.addEventListener("abort", onSignal, { once: true });
   process.on("SIGINT", onSignal);
   process.on("SIGTERM", onSignal);
   try {
@@ -1202,7 +2308,7 @@ async function runDaemon(opts = {}) {
         ensureLease();
         const result = await tick({
           store,
-          runnerId: `${hostname2()}:${process.pid}:${leaseId}`,
+          runnerId,
           execute: async (loop, run) => {
             const heartbeatMs = Math.max(1000, Math.floor(leaseTtlMs / 3));
             const timer = setInterval(() => {
@@ -1214,7 +2320,10 @@ async function runDaemon(opts = {}) {
             }, heartbeatMs);
             timer.unref();
             try {
-              const result2 = await executeLoop(loop, run);
+              const result2 = await executeLoopTarget(store, loop, run, {
+                signal: runAbort.signal,
+                onSpawn: (pid) => store.markRunPid(run.id, pid, runnerId)
+              });
               if (leaseLost)
                 throw new Error("daemon lease lost during run");
               return result2;
@@ -1231,6 +2340,7 @@ async function runDaemon(opts = {}) {
       }
     });
   } finally {
+    opts.signal?.removeEventListener("abort", onSignal);
     process.off("SIGINT", onSignal);
     process.off("SIGTERM", onSignal);
     store.releaseDaemonLease(leaseId);
@@ -1266,6 +2376,7 @@ async function startDaemon(opts) {
 
 // src/daemon/install.ts
 import { chmodSync, mkdirSync as mkdirSync4, writeFileSync as writeFileSync2 } from "fs";
+import { spawnSync as spawnSync3 } from "child_process";
 import { dirname as dirname3 } from "path";
 function installStartup(cliEntry, execPath = process.execPath, args = ["daemon", "run"]) {
   const command = [execPath, cliEntry, ...args].join(" ");
@@ -1327,10 +2438,100 @@ ${args.map((arg) => `    <string>${arg}</string>`).join(`
   }
   throw new Error(`startup install is not implemented for ${process.platform}`);
 }
+function enableStartup(result) {
+  const commands = result.platform === "linux" ? ["systemctl --user daemon-reload", "systemctl --user enable --now loops-daemon.service"] : result.platform === "darwin" ? [`launchctl load -w ${result.path}`] : [];
+  return commands.map((command) => {
+    const run = spawnSync3("sh", ["-c", command], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    return {
+      command,
+      status: run.status,
+      stdout: run.stdout.trim(),
+      stderr: run.stderr.trim()
+    };
+  });
+}
+
+// src/lib/doctor.ts
+import { spawnSync as spawnSync4 } from "child_process";
+import { accessSync, constants } from "fs";
+var PROVIDER_COMMANDS = [
+  "claude",
+  "cursor-agent",
+  "codewith",
+  "aicopilot",
+  "opencode",
+  "codex"
+];
+function hasCommand(command) {
+  const result = spawnSync4("sh", ["-c", 'command -v "$1" >/dev/null', "sh", command], { stdio: "ignore" });
+  return (result.status ?? 1) === 0;
+}
+function commandVersion(command) {
+  const result = spawnSync4(command, ["--version"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  if ((result.status ?? 1) !== 0)
+    return;
+  return (result.stdout || result.stderr).trim().split(/\r?\n/)[0];
+}
+function runDoctor(store) {
+  const checks = [];
+  try {
+    const dir = ensureDataDir();
+    accessSync(dir, constants.R_OK | constants.W_OK);
+    checks.push({ id: "data-dir", status: "ok", message: "data directory is writable", detail: dir });
+  } catch (error) {
+    checks.push({
+      id: "data-dir",
+      status: "fail",
+      message: "data directory is not writable",
+      detail: error instanceof Error ? error.message : String(error)
+    });
+  }
+  const bunVersion = commandVersion("bun");
+  checks.push(bunVersion ? { id: "bun", status: "ok", message: "bun is available", detail: bunVersion } : { id: "bun", status: "fail", message: "bun is not available on PATH" });
+  const accountsVersion = commandVersion("accounts");
+  checks.push(accountsVersion ? { id: "accounts", status: "ok", message: "accounts is available", detail: accountsVersion } : { id: "accounts", status: "warn", message: "accounts CLI is not available; account-routed steps will fail" });
+  for (const command of PROVIDER_COMMANDS) {
+    checks.push(hasCommand(command) ? { id: `provider:${command}`, status: "ok", message: `${command} is available` } : { id: `provider:${command}`, status: "warn", message: `${command} is not on PATH` });
+  }
+  const status = daemonStatus(store);
+  checks.push(status.running ? { id: "daemon", status: "ok", message: `daemon is running pid=${status.pid}` } : { id: "daemon", status: status.stale ? "warn" : "ok", message: status.stale ? "daemon pid file is stale" : "daemon is not running" });
+  const failedRuns = store.countRuns("failed");
+  checks.push(failedRuns === 0 ? { id: "loop-runs", status: "ok", message: "no failed loop runs recorded" } : { id: "loop-runs", status: "warn", message: `${failedRuns} failed loop run(s) recorded` });
+  for (const loop of store.listLoops({ status: "active" })) {
+    try {
+      if (loop.target.type === "workflow") {
+        const workflow = store.requireWorkflow(loop.target.workflowId);
+        for (const step of workflowExecutionOrder(workflow)) {
+          preflightTarget({ ...step.target, account: step.account ?? step.target.account, timeoutMs: step.timeoutMs ?? step.target.timeoutMs }, { loopId: loop.id, loopName: loop.name, workflowId: workflow.id, workflowName: workflow.name, workflowStepId: step.id });
+        }
+      } else {
+        preflightTarget(loop.target, { loopId: loop.id, loopName: loop.name });
+      }
+      checks.push({ id: `loop:${loop.id}:preflight`, status: "ok", message: `active loop target is ready: ${loop.name}` });
+    } catch (error) {
+      checks.push({
+        id: `loop:${loop.id}:preflight`,
+        status: "warn",
+        message: `active loop target preflight failed: ${loop.name}`,
+        detail: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+  return {
+    ok: checks.every((check) => check.status !== "fail"),
+    checks
+  };
+}
 
 // src/cli/index.ts
 var program = new Command;
-program.name("loops").description("Persistent local loops for commands and headless coding agents").version("0.1.0");
+program.name("loops").description("Persistent local loops for commands and headless coding agents").version("0.3.0");
 program.option("-j, --json", "print JSON");
 function isJson() {
   return Boolean(program.opts().json);
@@ -1412,8 +2613,16 @@ function baseCreateInput(name, opts, target) {
 function addScheduleOptions(command) {
   return command.option("--at <time>", "run once at an absolute time").option("--every <duration>", "run at a fixed interval, e.g. 15m, 1h, 30s").option("--cron <expr>", "run on a 5-field cron expression").option("--dynamic", "run on the default dynamic one-minute cadence").option("--catch-up <policy>", "none, latest, or all", "latest").option("--catch-up-limit <n>", "maximum missed slots to run when --catch-up all").option("--overlap <policy>", "skip or allow", "skip").option("--attempts <n>", "max attempts per scheduled slot").option("--retry-delay <duration>", "delay between retries", "1m").option("--lease <duration>", "running lease timeout", "30m").option("--expires-at <time>", "stop scheduling after this time").option("-d, --description <text>", "description");
 }
+function addAccountOptions(command) {
+  return command.option("--account <profile>", "OpenAccounts profile name for this target").option("--account-tool <tool>", "OpenAccounts tool id; defaults from provider for agents");
+}
+function accountFromOpts(opts) {
+  if (!opts.account && opts.accountTool)
+    throw new Error("--account-tool requires --account");
+  return opts.account ? { profile: opts.account, tool: opts.accountTool } : undefined;
+}
 var create = program.command("create").description("create loops");
-addScheduleOptions(create.command("command <name>").description("create a deterministic shell command loop").requiredOption("--cmd <command>", "command string to execute").option("--cwd <dir>", "working directory").option("--timeout <duration>", "run timeout").option("--no-shell", "execute without a shell")).action((name, opts) => {
+addAccountOptions(addScheduleOptions(create.command("command <name>").description("create a deterministic shell command loop").requiredOption("--cmd <command>", "command string to execute").option("--cwd <dir>", "working directory").option("--timeout <duration>", "run timeout").option("--no-shell", "execute without a shell"))).action((name, opts) => {
   const store = new Store;
   try {
     const target = {
@@ -1421,7 +2630,8 @@ addScheduleOptions(create.command("command <name>").description("create a determ
       command: opts.cmd,
       cwd: opts.cwd,
       shell: opts.shell,
-      timeoutMs: opts.timeout ? parseDuration(opts.timeout) : undefined
+      timeoutMs: opts.timeout ? parseDuration(opts.timeout) : undefined,
+      account: accountFromOpts(opts)
     };
     const loop = store.createLoop(baseCreateInput(name, opts, target));
     print(publicLoop(loop), `created loop ${loop.id} (${loop.name}) next=${loop.nextRunAt}`);
@@ -1429,9 +2639,9 @@ addScheduleOptions(create.command("command <name>").description("create a determ
     store.close();
   }
 });
-addScheduleOptions(create.command("agent <name>").description("create a headless coding-agent loop").requiredOption("--provider <provider>", "claude, cursor, codewith, aicopilot, or opencode").requiredOption("--prompt <prompt>", "agent prompt").option("--cwd <dir>", "working directory").option("--model <model>", "model").option("--agent <agent>", "provider-specific agent").option("--timeout <duration>", "run timeout").option("--config-isolation <mode>", "safe or none", "safe")).action((name, opts) => {
+addAccountOptions(addScheduleOptions(create.command("agent <name>").description("create a headless coding-agent loop").requiredOption("--provider <provider>", "claude, cursor, codewith, aicopilot, opencode, or codex").requiredOption("--prompt <prompt>", "agent prompt").option("--cwd <dir>", "working directory").option("--model <model>", "model").option("--agent <agent>", "provider-specific agent").option("--timeout <duration>", "run timeout").option("--config-isolation <mode>", "safe or none", "safe"))).action((name, opts) => {
   const provider = opts.provider;
-  if (!["claude", "cursor", "codewith", "aicopilot", "opencode"].includes(provider)) {
+  if (!["claude", "cursor", "codewith", "aicopilot", "opencode", "codex"].includes(provider)) {
     throw new Error("unsupported provider");
   }
   if (!["safe", "none"].includes(opts.configIsolation)) {
@@ -1447,7 +2657,8 @@ addScheduleOptions(create.command("agent <name>").description("create a headless
       model: opts.model,
       agent: opts.agent,
       timeoutMs: opts.timeout ? parseDuration(opts.timeout) : undefined,
-      configIsolation: opts.configIsolation
+      configIsolation: opts.configIsolation,
+      account: accountFromOpts(opts)
     };
     const loop = store.createLoop(baseCreateInput(name, opts, target));
     print(publicLoop(loop), `created loop ${loop.id} (${loop.name}) next=${loop.nextRunAt}`);
@@ -1455,6 +2666,179 @@ addScheduleOptions(create.command("agent <name>").description("create a headless
     store.close();
   }
 });
+addScheduleOptions(create.command("workflow <name>").description("schedule a stored workflow").requiredOption("--workflow <idOrName>", "workflow id or name")).action((name, opts) => {
+  const store = new Store;
+  try {
+    const workflow = store.requireWorkflow(opts.workflow);
+    const target = {
+      type: "workflow",
+      workflowId: workflow.id
+    };
+    const loop = store.createLoop(baseCreateInput(name, opts, target));
+    print(publicLoop(loop), `created workflow loop ${loop.id} (${loop.name}) workflow=${workflow.name} next=${loop.nextRunAt}`);
+  } finally {
+    store.close();
+  }
+});
+var workflows = program.command("workflows").alias("workflow").description("manage workflow specs and runs");
+workflows.command("validate <file>").description("validate a workflow JSON file without storing or running it").option("--name <name>", "override workflow name from the file").option("--preflight", "also check account env and target executables").action((file, opts) => {
+  const body = workflowBodyFromJson(JSON.parse(readFileSync2(file, "utf8")), opts.name);
+  const now = new Date().toISOString();
+  const workflow = {
+    id: "validation",
+    name: body.name,
+    description: body.description,
+    version: body.version ?? 1,
+    status: "active",
+    steps: body.steps,
+    createdAt: now,
+    updatedAt: now
+  };
+  const preflight = opts.preflight ? preflightWorkflow(workflow) : undefined;
+  print({ valid: true, workflow: publicWorkflow(workflow), preflight }, `valid workflow ${workflow.name} steps=${workflow.steps.length}`);
+});
+workflows.command("create <file>").description("validate and store a workflow JSON file").option("--name <name>", "override workflow name from the file").action((file, opts) => {
+  const store = new Store;
+  try {
+    const body = workflowBodyFromJson(JSON.parse(readFileSync2(file, "utf8")), opts.name);
+    const workflow = store.createWorkflow(body);
+    print(publicWorkflow(workflow), `created workflow ${workflow.id} (${workflow.name}) steps=${workflow.steps.length}`);
+  } finally {
+    store.close();
+  }
+});
+workflows.command("list").alias("ls").option("--status <status>", "active or archived", "active").action((opts) => {
+  const store = new Store;
+  try {
+    const workflowsList = store.listWorkflows({ status: opts.status });
+    if (isJson())
+      print(workflowsList.map(publicWorkflow));
+    else {
+      for (const workflow of workflowsList) {
+        console.log(`${workflow.id}  ${workflow.status.padEnd(8)}  steps=${workflow.steps.length}  ${workflow.name}`);
+      }
+    }
+  } finally {
+    store.close();
+  }
+});
+workflows.command("show <idOrName>").action((idOrName) => {
+  const store = new Store;
+  try {
+    print(publicWorkflow(store.requireWorkflow(idOrName)));
+  } finally {
+    store.close();
+  }
+});
+workflows.command("inspect <runId>").description("show a workflow run with steps and events").action((runId) => {
+  const store = new Store;
+  try {
+    const run = store.requireWorkflowRun(runId);
+    const steps = store.listWorkflowStepRuns(run.id);
+    const events = store.listWorkflowEvents(run.id);
+    const value = {
+      workflowRun: publicWorkflowRun(run),
+      steps: steps.map((step) => publicWorkflowStepRun(step, isJson())),
+      events: events.map(publicWorkflowEvent)
+    };
+    if (isJson())
+      print(value);
+    else {
+      console.log(`${run.id}  ${run.status}  ${run.workflowName}`);
+      for (const step of steps) {
+        console.log(`  ${String(step.sequence).padStart(2, "0")}  ${step.status.padEnd(10)}  ${step.stepId}  ${step.error ?? ""}`);
+      }
+      console.log(`  events=${events.length}`);
+    }
+  } finally {
+    store.close();
+  }
+});
+workflows.command("run <idOrName>").option("--show-output", "show step stdout/stderr").action(async (idOrName, opts) => {
+  const store = new Store;
+  try {
+    const workflow = store.requireWorkflow(idOrName);
+    const result = await executeWorkflow(store, workflow);
+    const run = store.listWorkflowRuns({ workflowId: workflow.id, limit: 1 })[0];
+    const steps = run ? store.listWorkflowStepRuns(run.id) : [];
+    const value = {
+      result,
+      workflowRun: run ? publicWorkflowRun(run) : undefined,
+      steps: steps.map((step) => publicWorkflowStepRun(step, opts.showOutput))
+    };
+    if (isJson())
+      print(value);
+    else {
+      console.log(`${run?.id ?? workflow.id} ${result.status}`);
+      for (const step of steps) {
+        console.log(`  ${String(step.sequence).padStart(2, "0")}  ${step.status.padEnd(10)}  ${step.stepId}  ${step.error ?? ""}`);
+      }
+    }
+  } finally {
+    store.close();
+  }
+});
+workflows.command("runs [idOrName]").option("--limit <n>", "limit", "50").action((idOrName, opts) => {
+  const store = new Store;
+  try {
+    const workflow = idOrName ? store.requireWorkflow(idOrName) : undefined;
+    const runs = store.listWorkflowRuns({ workflowId: workflow?.id, limit: Number(opts.limit) });
+    if (isJson())
+      print(runs.map(publicWorkflowRun));
+    else {
+      for (const run of runs) {
+        console.log(`${run.id}  ${run.status.padEnd(10)}  ${run.workflowName}  started=${run.startedAt ?? "-"}`);
+      }
+    }
+  } finally {
+    store.close();
+  }
+});
+workflows.command("events <runId>").option("--limit <n>", "limit", "200").action((runId, opts) => {
+  const store = new Store;
+  try {
+    const events = store.listWorkflowEvents(runId, Number(opts.limit));
+    if (isJson())
+      print(events.map(publicWorkflowEvent));
+    else {
+      for (const event of events) {
+        console.log(`${String(event.sequence).padStart(3, "0")}  ${event.eventType.padEnd(14)}  ${event.stepId ?? "-"}  ${event.createdAt}`);
+      }
+    }
+  } finally {
+    store.close();
+  }
+});
+workflows.command("cancel <runId>").description("mark a workflow run cancelled and cancel pending/running steps").option("--reason <reason>", "cancellation reason", "cancelled by user").action((runId, opts) => {
+  const store = new Store;
+  try {
+    const run = store.cancelWorkflowRun(runId, opts.reason);
+    print(publicWorkflowRun(run), `${run.id} ${run.status}`);
+  } finally {
+    store.close();
+  }
+});
+workflows.command("recover <runId>").description("reset interrupted running workflow steps to pending").option("--reason <reason>", "recovery reason", "manual recovery").action((runId, opts) => {
+  const store = new Store;
+  try {
+    const result = store.recoverWorkflowRun(runId, opts.reason);
+    print({
+      workflowRun: publicWorkflowRun(result.run),
+      recoveredSteps: result.recoveredSteps.map((step) => publicWorkflowStepRun(step))
+    }, `${result.run.id} recovered=${result.recoveredSteps.length}`);
+  } finally {
+    store.close();
+  }
+});
+workflows.command("archive <idOrName>").action((idOrName) => {
+  const store = new Store;
+  try {
+    const workflow = store.archiveWorkflow(idOrName);
+    print(publicWorkflow(workflow), `${workflow.id} ${workflow.status}`);
+  } finally {
+    store.close();
+  }
+});
 program.command("list").alias("ls").option("--status <status>", "filter by status").action((opts) => {
   const store = new Store;
   try {
@@ -1520,20 +2904,17 @@ program.command("run-now <idOrName>").option("--show-output", "show stdout/stder
   const store = new Store;
   try {
     const loop = store.requireLoop(idOrName);
-    const claim = store.claimRun(loop, new Date().toISOString(), `manual:${process.pid}`);
+    const runnerId = `manual:${process.pid}`;
+    const now = new Date;
+    const scheduledFor = manualRunScheduledFor(loop, now);
+    const shouldAdvance = shouldAdvanceManualRun(loop, scheduledFor, now);
+    const claim = store.claimRun(loop, scheduledFor, runnerId, now);
     if (!claim)
       throw new Error("could not claim manual run");
-    const result = await executeLoop(loop, claim.run);
-    const run = store.finalizeRun(claim.run.id, {
-      status: result.status,
-      finishedAt: result.finishedAt,
-      durationMs: result.durationMs,
-      stdout: result.stdout,
-      stderr: result.stderr,
-      exitCode: result.exitCode,
-      error: result.error,
-      pid: result.pid
-    });
+    const run = await executeClaimedRun({ store, runnerId, loop: claim.loop, run: claim.run });
+    if (shouldAdvance) {
+      advanceLoop(store, claim.loop, run, new Date(run.finishedAt ?? new Date), run.status === "succeeded");
+    }
     print(publicRun(run, opts.showOutput), `${run.id} ${run.status}`);
   } finally {
     store.close();
@@ -1548,6 +2929,24 @@ program.command("tick").description("run one scheduler tick").action(async () =>
     store.close();
   }
 });
+program.command("doctor").description("check local OpenLoops runtime dependencies and state").action(() => {
+  const store = new Store;
+  try {
+    const report = runDoctor(store);
+    if (isJson())
+      print(report);
+    else {
+      for (const check of report.checks) {
+        const marker = check.status === "ok" ? "ok" : check.status === "warn" ? "warn" : "fail";
+        console.log(`${marker.padEnd(4)} ${check.id.padEnd(22)} ${check.message}${check.detail ? ` (${check.detail})` : ""}`);
+      }
+      if (!report.ok)
+        process.exitCode = 1;
+    }
+  } finally {
+    store.close();
+  }
+});
 var daemon = program.command("daemon").description("manage the local daemon");
 daemon.command("run").option("--interval-ms <ms>", "tick interval", (value) => Number(value)).action(async (opts) => runDaemon({ intervalMs: opts.intervalMs }));
 daemon.command("start").action(async () => {
@@ -1566,15 +2965,20 @@ daemon.command("status").action(() => {
     store.close();
   }
 });
-daemon.command("install").description("write a systemd user service or launchd plist").action(() => {
+daemon.command("install").description("write a systemd user service or launchd plist").option("--enable", "also enable/start the user service when supported").action((opts) => {
   const result = installStartup(process.argv[1] ?? "loops");
+  if (opts.enable)
+    result.enableResults = enableStartup(result);
+  const enableText = result.enableResults ? `
+${result.enableResults.map((item) => `${item.command} -> ${item.status === 0 ? "ok" : `exit ${item.status}`}`).join(`
+`)}` : "";
   print(result, `wrote ${result.path}
 ${result.instructions.join(`
-`)}`);
+`)}${enableText}`);
 });
 daemon.command("logs").option("-n, --lines <n>", "lines", "80").action((opts) => {
   const path = daemonLogPath();
-  if (!existsSync2(path)) {
+  if (!existsSync4(path)) {
     console.log("");
     return;
   }