@hasna/loops 0.3.54 → 0.3.55

package/dist/lib/store.js

@@ -329,6 +329,15 @@ function optionalPositiveInteger(value, label) {
     throw new Error(`${label} must be a positive integer`);
   return value;
 }
+function optionalTimeoutMs(value, label) {
+  if (value === undefined)
+    return;
+  if (value === null)
+    return null;
+  if (!Number.isInteger(value) || value <= 0)
+    throw new Error(`${label} must be a positive integer or null for unlimited`);
+  return value;
+}
 function optionalBoolean(value, label) {
   if (value === undefined)
     return;
@@ -417,7 +426,7 @@ function validateTarget(value, label, opts) {
   assertObject(value, label);
   if (value.type === "command") {
     assertString(value.command, `${label}.command`);
-    optionalPositiveInteger(value.timeoutMs, `${label}.timeoutMs`);
+    optionalTimeoutMs(value.timeoutMs, `${label}.timeoutMs`);
     optionalPositiveInteger(value.idleTimeoutMs, `${label}.idleTimeoutMs`);
     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`);
@@ -436,7 +445,7 @@ function validateTarget(value, label, opts) {
     const providers = ["claude", "cursor", "codewith", "aicopilot", "opencode", "codex"];
     if (!providers.includes(value.provider))
       throw new Error(`${label}.provider must be one of ${providers.join(", ")}`);
-    optionalPositiveInteger(value.timeoutMs, `${label}.timeoutMs`);
+    optionalTimeoutMs(value.timeoutMs, `${label}.timeoutMs`);
     optionalPositiveInteger(value.idleTimeoutMs, `${label}.idleTimeoutMs`);
     if (value.authProfile !== undefined) {
       assertString(value.authProfile, `${label}.authProfile`);
@@ -559,7 +568,7 @@ function normalizeCreateWorkflowInput(input, opts = {}) {
       target: validateTarget(step.target, `workflow.steps[${index}].target`, opts),
       dependsOn: optionalStringArray(step.dependsOn, `workflow.steps[${index}].dependsOn`) ?? [],
       continueOnFailure: optionalBoolean(step.continueOnFailure, `workflow.steps[${index}].continueOnFailure`) ?? false,
-      timeoutMs: optionalPositiveInteger(step.timeoutMs, `workflow.steps[${index}].timeoutMs`),
+      timeoutMs: optionalTimeoutMs(step.timeoutMs, `workflow.steps[${index}].timeoutMs`),
       account: optionalAccountRef(step.account, `workflow.steps[${index}].account`)
     };
   });
@@ -1305,6 +1314,17 @@ class Store {
     const row = this.db.query("SELECT * FROM loops WHERE name = ? ORDER BY created_at DESC LIMIT 1").get(name);
     return row ? rowToLoop(row) : undefined;
   }
+  requireUniqueLoop(idOrName) {
+    const byId = this.getLoop(idOrName);
+    if (byId)
+      return byId;
+    const rows = this.db.query("SELECT * FROM loops WHERE name = ? ORDER BY created_at DESC LIMIT 2").all(idOrName);
+    if (rows.length === 0)
+      throw new Error(`loop not found: ${idOrName}`);
+    if (rows.length > 1)
+      throw new Error(`ambiguous loop name: ${idOrName}; use a loop id`);
+    return rowToLoop(rows[0]);
+  }
   requireLoop(idOrName) {
     return this.getLoop(idOrName) ?? this.findLoopByName(idOrName) ?? (() => {
       throw new Error(`loop not found: ${idOrName}`);
@@ -1379,6 +1399,130 @@ class Store {
       throw new Error(`loop not found after update: ${id}`);
     return after;
   }
+  activeLoopReferenceCount(workflowId) {
+    const rows = this.db.query("SELECT target_json FROM loops WHERE archived_at IS NULL").all();
+    let count = 0;
+    for (const row of rows) {
+      try {
+        const target = JSON.parse(row.target_json);
+        if (target.type === "workflow" && target.workflowId === workflowId)
+          count += 1;
+      } catch {}
+    }
+    return count;
+  }
+  archiveWorkflowIfUnreferenced(workflowId, updated) {
+    if (this.activeLoopReferenceCount(workflowId) > 0)
+      return;
+    const workflow = this.getWorkflow(workflowId);
+    if (!workflow || workflow.status !== "active")
+      return;
+    const res = this.db.query("UPDATE workflow_specs SET status='archived', updated_at=? WHERE id=? AND status='active'").run(updated, workflowId);
+    if (res.changes !== 1)
+      return;
+    return this.getWorkflow(workflowId);
+  }
+  retargetWorkflowLoop(idOrName, workflowId, opts = {}) {
+    const updated = (opts.now ?? new Date).toISOString();
+    this.db.exec("BEGIN IMMEDIATE");
+    try {
+      const current = this.requireLoop(idOrName);
+      if (current.target.type !== "workflow")
+        throw new Error(`loop is not a workflow loop: ${idOrName}`);
+      if (this.hasRunningRun(current.id))
+        throw new Error(`refusing to retarget running loop: ${current.id}`);
+      const workflow = this.requireWorkflow(workflowId);
+      const target = { ...current.target, workflowId: workflow.id };
+      if (opts.workflowTimeoutMs !== undefined)
+        target.timeoutMs = opts.workflowTimeoutMs;
+      const res = this.db.query(`UPDATE loops SET target_json=$target, updated_at=$updated
+           WHERE id=$id
+             AND ($daemonLeaseId IS NULL OR EXISTS (
+               SELECT 1 FROM daemon_lease WHERE id=$daemonLeaseId AND expires_at > $now
+             ))`).run({
+        $id: current.id,
+        $target: JSON.stringify(target),
+        $updated: updated,
+        $daemonLeaseId: opts.daemonLeaseId ?? null,
+        $now: updated
+      });
+      if (res.changes !== 1)
+        throw new Error("daemon lease lost");
+      this.db.exec("COMMIT");
+      const after = this.getLoop(current.id);
+      if (!after)
+        throw new Error(`loop not found after retarget: ${current.id}`);
+      return after;
+    } catch (error) {
+      try {
+        this.db.exec("ROLLBACK");
+      } catch {}
+      throw error;
+    }
+  }
+  createAndRetargetWorkflowLoop(idOrName, workflowInput, opts = {}) {
+    const normalized = normalizeCreateWorkflowInput(workflowInput);
+    const updated = (opts.now ?? new Date).toISOString();
+    this.db.exec("BEGIN IMMEDIATE");
+    try {
+      const current = this.requireUniqueLoop(idOrName);
+      if (current.target.type !== "workflow")
+        throw new Error(`loop is not a workflow loop: ${idOrName}`);
+      if (this.hasRunningRun(current.id))
+        throw new Error(`refusing to retarget running loop: ${current.id}`);
+      const previousWorkflow = this.requireWorkflow(current.target.workflowId);
+      const workflow = {
+        id: genId(),
+        name: normalized.name,
+        description: normalized.description,
+        version: normalized.version ?? 1,
+        status: "active",
+        goal: normalized.goal,
+        steps: normalized.steps,
+        createdAt: updated,
+        updatedAt: updated
+      };
+      this.db.query(`INSERT INTO workflow_specs (id, name, description, version, status, goal_json, steps_json, created_at, updated_at)
+           VALUES ($id, $name, $description, $version, $status, $goal, $steps, $created, $updated)`).run({
+        $id: workflow.id,
+        $name: workflow.name,
+        $description: workflow.description ?? null,
+        $version: workflow.version,
+        $status: workflow.status,
+        $goal: workflow.goal ? JSON.stringify(workflow.goal) : null,
+        $steps: JSON.stringify(workflow.steps),
+        $created: workflow.createdAt,
+        $updated: workflow.updatedAt
+      });
+      const target = { ...current.target, workflowId: workflow.id };
+      if (opts.workflowTimeoutMs !== undefined)
+        target.timeoutMs = opts.workflowTimeoutMs;
+      const res = this.db.query(`UPDATE loops SET target_json=$target, updated_at=$updated
+           WHERE id=$id
+             AND ($daemonLeaseId IS NULL OR EXISTS (
+               SELECT 1 FROM daemon_lease WHERE id=$daemonLeaseId AND expires_at > $now
+             ))`).run({
+        $id: current.id,
+        $target: JSON.stringify(target),
+        $updated: updated,
+        $daemonLeaseId: opts.daemonLeaseId ?? null,
+        $now: updated
+      });
+      if (res.changes !== 1)
+        throw new Error("daemon lease lost");
+      const archivedOld = opts.archiveOld ? this.archiveWorkflowIfUnreferenced(previousWorkflow.id, updated) : undefined;
+      this.db.exec("COMMIT");
+      const loop = this.getLoop(current.id);
+      if (!loop)
+        throw new Error(`loop not found after retarget: ${current.id}`);
+      return { loop, workflow, previousWorkflow, archivedOld };
+    } catch (error) {
+      try {
+        this.db.exec("ROLLBACK");
+      } catch {}
+      throw error;
+    }
+  }
   renameLoop(id, name, opts = {}) {
     const current = this.getLoop(id);
     if (!current)

package/dist/lib/templates.d.ts

@@ -1,4 +1,4 @@
-import type { AccountRef, AgentPermissionMode, AgentProvider, AgentSandbox, AgentWorktreeMode, CreateWorkflowInput, LoopTemplateSource, LoopTemplateSummary } from "../types.js";
+import type { AccountRef, AgentPermissionMode, AgentProvider, AgentSandbox, AgentWorktreeMode, CreateWorkflowInput, LoopTemplateSource, LoopTemplateSummary, TimeoutMs } from "../types.js";
 export declare const TODOS_TASK_WORKER_VERIFIER_TEMPLATE_ID = "todos-task-worker-verifier";
 export declare const EVENT_WORKER_VERIFIER_TEMPLATE_ID = "event-worker-verifier";
 export declare const BOUNDED_AGENT_WORKER_VERIFIER_TEMPLATE_ID = "bounded-agent-worker-verifier";
@@ -40,6 +40,7 @@ export interface TodosTaskWorkflowTemplateInput {
     worktreeMode?: AgentWorktreeMode;
     worktreeRoot?: string;
     worktreeBranchPrefix?: string;
+    timeoutMs?: TimeoutMs;
     eventId?: string;
     eventType?: string;
 }
@@ -76,6 +77,7 @@ export interface EventWorkflowTemplateInput {
     worktreeMode?: AgentWorktreeMode;
     worktreeRoot?: string;
     worktreeBranchPrefix?: string;
+    timeoutMs?: TimeoutMs;
 }
 export interface BoundedAgentWorkflowTemplateInput {
     name?: string;
@@ -107,7 +109,7 @@ export interface BoundedAgentWorkflowTemplateInput {
     worktreeMode?: AgentWorktreeMode;
     worktreeRoot?: string;
     worktreeBranchPrefix?: string;
-    timeoutMs?: number;
+    timeoutMs?: TimeoutMs;
 }
 export type LoopTemplateSourceFilter = LoopTemplateSource | "all";
 export interface ListLoopTemplatesOptions {

package/dist/sdk/index.js

@@ -329,6 +329,15 @@ function optionalPositiveInteger(value, label) {
     throw new Error(`${label} must be a positive integer`);
   return value;
 }
+function optionalTimeoutMs(value, label) {
+  if (value === undefined)
+    return;
+  if (value === null)
+    return null;
+  if (!Number.isInteger(value) || value <= 0)
+    throw new Error(`${label} must be a positive integer or null for unlimited`);
+  return value;
+}
 function optionalBoolean(value, label) {
   if (value === undefined)
     return;
@@ -417,7 +426,7 @@ function validateTarget(value, label, opts) {
   assertObject(value, label);
   if (value.type === "command") {
     assertString(value.command, `${label}.command`);
-    optionalPositiveInteger(value.timeoutMs, `${label}.timeoutMs`);
+    optionalTimeoutMs(value.timeoutMs, `${label}.timeoutMs`);
     optionalPositiveInteger(value.idleTimeoutMs, `${label}.idleTimeoutMs`);
     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`);
@@ -436,7 +445,7 @@ function validateTarget(value, label, opts) {
     const providers = ["claude", "cursor", "codewith", "aicopilot", "opencode", "codex"];
     if (!providers.includes(value.provider))
       throw new Error(`${label}.provider must be one of ${providers.join(", ")}`);
-    optionalPositiveInteger(value.timeoutMs, `${label}.timeoutMs`);
+    optionalTimeoutMs(value.timeoutMs, `${label}.timeoutMs`);
     optionalPositiveInteger(value.idleTimeoutMs, `${label}.idleTimeoutMs`);
     if (value.authProfile !== undefined) {
       assertString(value.authProfile, `${label}.authProfile`);
@@ -559,7 +568,7 @@ function normalizeCreateWorkflowInput(input, opts = {}) {
       target: validateTarget(step.target, `workflow.steps[${index}].target`, opts),
       dependsOn: optionalStringArray(step.dependsOn, `workflow.steps[${index}].dependsOn`) ?? [],
       continueOnFailure: optionalBoolean(step.continueOnFailure, `workflow.steps[${index}].continueOnFailure`) ?? false,
-      timeoutMs: optionalPositiveInteger(step.timeoutMs, `workflow.steps[${index}].timeoutMs`),
+      timeoutMs: optionalTimeoutMs(step.timeoutMs, `workflow.steps[${index}].timeoutMs`),
       account: optionalAccountRef(step.account, `workflow.steps[${index}].account`)
     };
   });
@@ -1305,6 +1314,17 @@ class Store {
     const row = this.db.query("SELECT * FROM loops WHERE name = ? ORDER BY created_at DESC LIMIT 1").get(name);
     return row ? rowToLoop(row) : undefined;
   }
+  requireUniqueLoop(idOrName) {
+    const byId = this.getLoop(idOrName);
+    if (byId)
+      return byId;
+    const rows = this.db.query("SELECT * FROM loops WHERE name = ? ORDER BY created_at DESC LIMIT 2").all(idOrName);
+    if (rows.length === 0)
+      throw new Error(`loop not found: ${idOrName}`);
+    if (rows.length > 1)
+      throw new Error(`ambiguous loop name: ${idOrName}; use a loop id`);
+    return rowToLoop(rows[0]);
+  }
   requireLoop(idOrName) {
     return this.getLoop(idOrName) ?? this.findLoopByName(idOrName) ?? (() => {
       throw new Error(`loop not found: ${idOrName}`);
@@ -1379,6 +1399,130 @@ class Store {
       throw new Error(`loop not found after update: ${id}`);
     return after;
   }
+  activeLoopReferenceCount(workflowId) {
+    const rows = this.db.query("SELECT target_json FROM loops WHERE archived_at IS NULL").all();
+    let count = 0;
+    for (const row of rows) {
+      try {
+        const target = JSON.parse(row.target_json);
+        if (target.type === "workflow" && target.workflowId === workflowId)
+          count += 1;
+      } catch {}
+    }
+    return count;
+  }
+  archiveWorkflowIfUnreferenced(workflowId, updated) {
+    if (this.activeLoopReferenceCount(workflowId) > 0)
+      return;
+    const workflow = this.getWorkflow(workflowId);
+    if (!workflow || workflow.status !== "active")
+      return;
+    const res = this.db.query("UPDATE workflow_specs SET status='archived', updated_at=? WHERE id=? AND status='active'").run(updated, workflowId);
+    if (res.changes !== 1)
+      return;
+    return this.getWorkflow(workflowId);
+  }
+  retargetWorkflowLoop(idOrName, workflowId, opts = {}) {
+    const updated = (opts.now ?? new Date).toISOString();
+    this.db.exec("BEGIN IMMEDIATE");
+    try {
+      const current = this.requireLoop(idOrName);
+      if (current.target.type !== "workflow")
+        throw new Error(`loop is not a workflow loop: ${idOrName}`);
+      if (this.hasRunningRun(current.id))
+        throw new Error(`refusing to retarget running loop: ${current.id}`);
+      const workflow = this.requireWorkflow(workflowId);
+      const target = { ...current.target, workflowId: workflow.id };
+      if (opts.workflowTimeoutMs !== undefined)
+        target.timeoutMs = opts.workflowTimeoutMs;
+      const res = this.db.query(`UPDATE loops SET target_json=$target, updated_at=$updated
+           WHERE id=$id
+             AND ($daemonLeaseId IS NULL OR EXISTS (
+               SELECT 1 FROM daemon_lease WHERE id=$daemonLeaseId AND expires_at > $now
+             ))`).run({
+        $id: current.id,
+        $target: JSON.stringify(target),
+        $updated: updated,
+        $daemonLeaseId: opts.daemonLeaseId ?? null,
+        $now: updated
+      });
+      if (res.changes !== 1)
+        throw new Error("daemon lease lost");
+      this.db.exec("COMMIT");
+      const after = this.getLoop(current.id);
+      if (!after)
+        throw new Error(`loop not found after retarget: ${current.id}`);
+      return after;
+    } catch (error) {
+      try {
+        this.db.exec("ROLLBACK");
+      } catch {}
+      throw error;
+    }
+  }
+  createAndRetargetWorkflowLoop(idOrName, workflowInput, opts = {}) {
+    const normalized = normalizeCreateWorkflowInput(workflowInput);
+    const updated = (opts.now ?? new Date).toISOString();
+    this.db.exec("BEGIN IMMEDIATE");
+    try {
+      const current = this.requireUniqueLoop(idOrName);
+      if (current.target.type !== "workflow")
+        throw new Error(`loop is not a workflow loop: ${idOrName}`);
+      if (this.hasRunningRun(current.id))
+        throw new Error(`refusing to retarget running loop: ${current.id}`);
+      const previousWorkflow = this.requireWorkflow(current.target.workflowId);
+      const workflow = {
+        id: genId(),
+        name: normalized.name,
+        description: normalized.description,
+        version: normalized.version ?? 1,
+        status: "active",
+        goal: normalized.goal,
+        steps: normalized.steps,
+        createdAt: updated,
+        updatedAt: updated
+      };
+      this.db.query(`INSERT INTO workflow_specs (id, name, description, version, status, goal_json, steps_json, created_at, updated_at)
+           VALUES ($id, $name, $description, $version, $status, $goal, $steps, $created, $updated)`).run({
+        $id: workflow.id,
+        $name: workflow.name,
+        $description: workflow.description ?? null,
+        $version: workflow.version,
+        $status: workflow.status,
+        $goal: workflow.goal ? JSON.stringify(workflow.goal) : null,
+        $steps: JSON.stringify(workflow.steps),
+        $created: workflow.createdAt,
+        $updated: workflow.updatedAt
+      });
+      const target = { ...current.target, workflowId: workflow.id };
+      if (opts.workflowTimeoutMs !== undefined)
+        target.timeoutMs = opts.workflowTimeoutMs;
+      const res = this.db.query(`UPDATE loops SET target_json=$target, updated_at=$updated
+           WHERE id=$id
+             AND ($daemonLeaseId IS NULL OR EXISTS (
+               SELECT 1 FROM daemon_lease WHERE id=$daemonLeaseId AND expires_at > $now
+             ))`).run({
+        $id: current.id,
+        $target: JSON.stringify(target),
+        $updated: updated,
+        $daemonLeaseId: opts.daemonLeaseId ?? null,
+        $now: updated
+      });
+      if (res.changes !== 1)
+        throw new Error("daemon lease lost");
+      const archivedOld = opts.archiveOld ? this.archiveWorkflowIfUnreferenced(previousWorkflow.id, updated) : undefined;
+      this.db.exec("COMMIT");
+      const loop = this.getLoop(current.id);
+      if (!loop)
+        throw new Error(`loop not found after retarget: ${current.id}`);
+      return { loop, workflow, previousWorkflow, archivedOld };
+    } catch (error) {
+      try {
+        this.db.exec("ROLLBACK");
+      } catch {}
+      throw error;
+    }
+  }
   renameLoop(id, name, opts = {}) {
     const current = this.getLoop(id);
     if (!current)
@@ -3480,7 +3624,7 @@ function commandSpec(target) {
       cwd: commandTarget.cwd,
       shell: commandTarget.shell,
       env: commandTarget.env,
-      timeoutMs: commandTarget.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      timeoutMs: commandTarget.timeoutMs === undefined ? DEFAULT_TIMEOUT_MS : commandTarget.timeoutMs,
       idleTimeoutMs: commandTarget.idleTimeoutMs,
       account: commandTarget.account,
       accountTool: commandTarget.account?.tool
@@ -3491,7 +3635,7 @@ function commandSpec(target) {
     command: providerCommand(agentTarget.provider),
     args: agentArgs(agentTarget),
     cwd: agentTarget.cwd,
-    timeoutMs: agentTarget.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    timeoutMs: agentTarget.timeoutMs ?? null,
     idleTimeoutMs: agentTarget.idleTimeoutMs,
     account: agentTarget.account,
     accountTool: agentTarget.account?.tool ?? accountToolForProvider(agentTarget.provider),
@@ -3679,12 +3823,12 @@ async function executeRemoteSpec(spec, machine, metadata, opts) {
   if (opts.signal?.aborted)
     abortHandler();
   opts.signal?.addEventListener("abort", abortHandler, { once: true });
-  const timer = setTimeout(() => {
+  const timer = typeof spec.timeoutMs === "number" ? setTimeout(() => {
     timedOut = true;
     if (child.pid)
       killProcessGroup(child.pid);
-  }, spec.timeoutMs);
-  timer.unref();
+  }, spec.timeoutMs) : undefined;
+  timer?.unref();
   let idleTimer;
   const resetIdleTimer = () => {
     if (!spec.idleTimeoutMs)
@@ -3716,7 +3860,8 @@ async function executeRemoteSpec(spec, machine, metadata, opts) {
   } catch (err) {
     error = err instanceof Error ? err.message : String(err);
   } finally {
-    clearTimeout(timer);
+    if (timer)
+      clearTimeout(timer);
     if (idleTimer)
       clearTimeout(idleTimer);
     opts.signal?.removeEventListener("abort", abortHandler);
@@ -3858,12 +4003,12 @@ async function executeTarget(target, metadata = {}, opts = {}) {
   if (opts.signal?.aborted)
     abortHandler();
   opts.signal?.addEventListener("abort", abortHandler, { once: true });
-  const timer = setTimeout(() => {
+  const timer = typeof spec.timeoutMs === "number" ? setTimeout(() => {
     timedOut = true;
     if (child.pid)
       killProcessGroup(child.pid);
-  }, spec.timeoutMs);
-  timer.unref();
+  }, spec.timeoutMs) : undefined;
+  timer?.unref();
   let idleTimer;
   const resetIdleTimer = () => {
     if (!spec.idleTimeoutMs)
@@ -3895,7 +4040,8 @@ async function executeTarget(target, metadata = {}, opts = {}) {
   } catch (err) {
     error = err instanceof Error ? err.message : String(err);
   } finally {
-    clearTimeout(timer);
+    if (timer)
+      clearTimeout(timer);
     if (idleTimer)
       clearTimeout(idleTimer);
     opts.signal?.removeEventListener("abort", abortHandler);
@@ -4320,7 +4466,7 @@ ${result.stderr}`);
 // src/lib/workflow-runner.ts
 function targetWithStepAccount(step) {
   const account = step.account ?? step.target.account;
-  const timeoutMs = step.timeoutMs ?? step.target.timeoutMs;
+  const timeoutMs = step.timeoutMs !== undefined ? step.timeoutMs : step.target.timeoutMs;
   if (!account && timeoutMs === step.target.timeoutMs)
     return step.target;
   return { ...step.target, account, timeoutMs };
@@ -4616,7 +4762,8 @@ async function executeLoopTarget(store, loop, run, opts = {}) {
       })
     });
   }
-  const controller = loop.target.timeoutMs ? new AbortController : undefined;
+  const workflowTimeoutMs = typeof loop.target.timeoutMs === "number" ? loop.target.timeoutMs : undefined;
+  const controller = workflowTimeoutMs !== undefined ? new AbortController : undefined;
   let workflowTimedOut = false;
   const externalAbort = () => controller?.abort();
   if (controller && opts.signal?.aborted)
@@ -4626,13 +4773,13 @@ async function executeLoopTarget(store, loop, run, opts = {}) {
   const timer = controller ? setTimeout(() => {
     workflowTimedOut = true;
     controller.abort();
-  }, loop.target.timeoutMs) : undefined;
+  }, workflowTimeoutMs) : 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,
+      signalTimeoutMessage: () => workflowTimedOut && loop.target.type === "workflow" ? `workflow timed out after ${workflowTimeoutMs}ms` : undefined,
       loop,
       loopRun: run,
       scheduledFor: run.scheduledFor,

package/dist/types.d.ts

@@ -70,11 +70,12 @@ export interface CommandTarget {
     cwd?: string;
     shell?: boolean;
     env?: Record<string, string>;
-    timeoutMs?: number;
+    timeoutMs?: TimeoutMs;
     idleTimeoutMs?: number;
     account?: AccountRef;
     preflight?: RuntimePreflightPolicy;
 }
+export type TimeoutMs = number | null;
 export type AgentProvider = "claude" | "cursor" | "codewith" | "aicopilot" | "opencode" | "codex";
 export type AgentConfigIsolation = "safe" | "none";
 export type AgentPermissionMode = "default" | "plan" | "auto" | "bypass";
@@ -118,7 +119,7 @@ export interface AgentTargetBase {
     authProfile?: string;
     extraArgs?: string[];
     addDirs?: string[];
-    timeoutMs?: number;
+    timeoutMs?: TimeoutMs;
     idleTimeoutMs?: number;
     configIsolation?: AgentConfigIsolation;
     permissionMode?: AgentPermissionMode;
@@ -140,7 +141,7 @@ export interface WorkflowTarget {
     type: "workflow";
     workflowId: string;
     input?: Record<string, string>;
-    timeoutMs?: number;
+    timeoutMs?: TimeoutMs;
     preflight?: RuntimePreflightPolicy;
 }
 export type ExecutableTarget = CommandTarget | AgentTarget;
@@ -242,7 +243,7 @@ export interface WorkflowStep {
     goal?: GoalSpec;
     dependsOn?: string[];
     continueOnFailure?: boolean;
-    timeoutMs?: number;
+    timeoutMs?: TimeoutMs;
     account?: AccountRef;
 }
 export interface WorkflowStepInput extends Omit<WorkflowStep, "target"> {

package/docs/USAGE.md

@@ -245,6 +245,11 @@ loops workflows recover <workflow-run-id>
 loops create workflow repo-morning-loop --workflow repo-morning --cron "0 8 * * *"
 ```
 
+Use `recover` only for interrupted `running` workflow runs whose recorded child
+process is gone. Terminal `timed_out` task/event workflow runs are audit
+history; requeue them through the original task/event route after fixing the
+cause.
+
 Workflow specs are stored separately from loops. A loop can schedule a workflow, but workflow runs and step runs have their own durable rows and events. Steps run in dependency order and a scheduled workflow run is idempotent per loop slot.
 
 For command steps, `command` is the executable when `shell` is not true. Put flags in `args`:
@@ -310,6 +315,30 @@ Custom reusable workflow templates live under the OpenLoops app data directory:
 showing, and rendering templates never executes workflow steps or mutates the
 registry.
 
+Timeout policy is explicit. Deterministic command/check steps should normally
+keep finite `timeoutMs`/`idleTimeoutMs` guards so broken shell work cannot run
+forever. Agentic work steps default to no timeout in built-in worker/verifier
+and task-lifecycle templates; use `timeoutMs: null` in workflow JSON, or
+`--timeout none` / `--timeout unlimited` for CLI-created targets, when a step
+may need hours or days. Use a positive numeric `timeoutMs` only when an agentic
+step is intentionally bounded.
+
+To migrate existing workflow loops, do not edit `workflow_specs.steps_json`
+directly because historical workflow runs must keep pointing at their original
+spec. Use the append-only migrator:
+
+```bash
+loops workflows migrate-agent-timeouts --loop <loop-id-or-name>
+loops workflows migrate-agent-timeouts --loop <loop-id-or-name> --apply
+```
+
+The command dry-runs by default. With `--apply`, it creates a new workflow spec
+with the requested agent timeout policy, retargets only future executions of
+eligible non-running workflow loops, and leaves terminal timed-out workflow runs
+as audit history. Use `loops workflows recover` only for interrupted `running`
+workflow runs whose recorded child process is gone; terminal `timed_out` runs
+must be requeued by re-delivering or draining the original task/event route.
+
 ```json
 {
   "id": "custom-report",
@@ -318,8 +347,7 @@ registry.
   "kind": "workflow",
   "variables": [
     { "name": "objective", "required": true, "description": "Report objective." },
-    { "name": "projectPath", "required": true, "description": "Working directory." },
-    { "name": "timeoutMs", "default": "300000", "type": "number" }
+    { "name": "projectPath", "required": true, "description": "Working directory." }
   ],
   "workflow": {
     "name": "custom-report-${objective}",
@@ -334,9 +362,9 @@ registry.
           "configIsolation": "safe",
           "permissionMode": "bypass",
           "sandbox": "workspace-write",
-          "timeoutMs": "${timeoutMs}"
+          "timeoutMs": null
         },
-        "timeoutMs": "${timeoutMs}"
+        "timeoutMs": null
       }
     ]
   }

package/docs/workflows/transcript-feedback-to-loops.json

@@ -48,7 +48,7 @@
         "type": "agent",
         "provider": "codewith",
         "cwd": "/path/to/repo",
-        "timeoutMs": 1800000,
+        "timeoutMs": null,
         "prompt": "Read .openloops/transcripts/latest-transcript.json and create or update docs/loop-backlog.md. Extract only recurring work that is useful enough to schedule through OpenLoops. For each candidate include cadence, target provider, allowed write scope, expected artifacts, verification command, stop condition, and the specific transcript insight that justifies it. Prefer loops for code review/security, customer feedback triage, maintenance PRs, CI optimization, knowledge capture, and workflow hygiene."
       }
     },
@@ -60,7 +60,7 @@
         "type": "agent",
         "provider": "codewith",
         "cwd": "/path/to/repo",
-        "timeoutMs": 1800000,
+        "timeoutMs": null,
         "prompt": "Use docs/loop-backlog.md to author or update workflow JSON specs under docs/workflows/generated. Each workflow must use deterministic command steps for checks, agent steps for judgment or code changes, and workflow or step goals only when the outcome needs planning. Keep prompts scoped to the target repo, name allowed paths, and include validation evidence."
       }
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/loops",
-  "version": "0.3.54",
+  "version": "0.3.55",
   "description": "Persistent local loop and workflow runner for deterministic commands and headless AI coding agents",
   "type": "module",
   "main": "dist/index.js",