@hasna/loops 0.3.53 → 0.3.55

package/dist/sdk/index.js

@@ -312,6 +312,8 @@ function updateReadyFlags(nodes, planStatus) {
 }
 
 // src/lib/workflow-spec.ts
+import { readFileSync } from "fs";
+import { isAbsolute, resolve } from "path";
 function assertObject(value, label) {
   if (!value || typeof value !== "object" || Array.isArray(value))
     throw new Error(`${label} must be an object`);
@@ -327,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;
@@ -357,6 +368,38 @@ function optionalAccountRef(value, label) {
     tool: typeof value.tool === "string" ? value.tool.trim() : undefined
   };
 }
+function promptFilePath(rawPath, opts) {
+  return isAbsolute(rawPath) ? resolve(rawPath) : resolve(opts.baseDir ?? process.cwd(), rawPath);
+}
+function readPromptFile(rawPath, label, opts) {
+  assertString(rawPath, `${label}.promptFile`);
+  const path = promptFilePath(rawPath.trim(), opts);
+  let prompt;
+  try {
+    prompt = readFileSync(path, "utf8");
+  } catch (error) {
+    const code = error && typeof error === "object" && "code" in error ? String(error.code) : undefined;
+    throw new Error(`${label}.promptFile could not be read${code ? `: ${code}` : ""}`);
+  }
+  if (prompt.trim() === "")
+    throw new Error(`${label}.promptFile must contain a non-empty prompt`);
+  return { prompt, promptSource: { type: "file", path } };
+}
+function matchingPromptSource(value, prompt, opts) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return;
+  if (value.type !== "file")
+    return;
+  const rawPath = value.path;
+  if (typeof rawPath !== "string" || rawPath.trim() === "")
+    return;
+  const path = promptFilePath(rawPath.trim(), opts);
+  try {
+    return readFileSync(path, "utf8") === prompt ? { type: "file", path } : undefined;
+  } catch {
+    return;
+  }
+}
 function normalizeGoalSpec(value, label = "goal") {
   if (value === undefined)
     return;
@@ -379,11 +422,11 @@ function normalizeGoalSpec(value, label = "goal") {
     autoExecute
   };
 }
-function validateTarget(value, label) {
+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`);
@@ -392,11 +435,17 @@ function validateTarget(value, label) {
   }
   if (value.type === "agent") {
     assertString(value.provider, `${label}.provider`);
-    assertString(value.prompt, `${label}.prompt`);
+    const hasPrompt = typeof value.prompt === "string" && value.prompt.trim() !== "";
+    const hasPromptFile = typeof value.promptFile === "string" && value.promptFile.trim() !== "";
+    if (hasPrompt && hasPromptFile)
+      throw new Error(`${label} must use either prompt or promptFile, not both`);
+    if (!hasPrompt && !hasPromptFile)
+      throw new Error(`${label}.prompt must be a non-empty string or ${label}.promptFile must be set`);
+    const promptFields = hasPrompt ? { prompt: value.prompt, promptSource: matchingPromptSource(value.promptSource, value.prompt, opts) } : readPromptFile(value.promptFile, 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`);
@@ -493,11 +542,14 @@ function validateTarget(value, label) {
       if (value.routing.eventSource !== undefined)
         assertString(value.routing.eventSource, `${label}.routing.eventSource`);
     }
-    return value;
+    const target = { ...value };
+    delete target.promptFile;
+    delete target.promptSource;
+    return { ...target, ...promptFields };
   }
   throw new Error(`${label}.type must be command or agent`);
 }
-function normalizeCreateWorkflowInput(input) {
+function normalizeCreateWorkflowInput(input, opts = {}) {
   assertString(input.name, "workflow.name");
   const goal = normalizeGoalSpec(input.goal, "goal");
   if (!Array.isArray(input.steps) || input.steps.length === 0)
@@ -513,10 +565,10 @@ function normalizeCreateWorkflowInput(input) {
       ...step,
       id: step.id,
       goal: normalizeGoalSpec(step.goal, `workflow.steps[${index}].goal`),
-      target: validateTarget(step.target, `workflow.steps[${index}].target`),
+      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`)
     };
   });
@@ -556,7 +608,7 @@ function workflowExecutionOrder(workflow) {
     visit(step);
   return order;
 }
-function workflowBodyFromJson(value, fallbackName) {
+function workflowBodyFromJson(value, fallbackName, opts = {}) {
   assertObject(value, "workflow file");
   const rawName = fallbackName ?? value.name;
   assertString(rawName, "workflow.name");
@@ -568,7 +620,7 @@ function workflowBodyFromJson(value, fallbackName) {
     goal: normalizeGoalSpec(value.goal, "goal"),
     version: typeof value.version === "number" ? value.version : undefined,
     steps: value.steps
-  });
+  }, opts);
 }
 
 // src/lib/run-artifacts.ts
@@ -1205,13 +1257,17 @@ class Store {
   }
   createLoop(input, from = new Date) {
     const now = nowIso();
+    const target = input.target.type === "workflow" ? input.target : normalizeCreateWorkflowInput({
+      name: "loop-target-validation",
+      steps: [{ id: "target", target: input.target }]
+    }).steps[0].target;
     const loop = {
       id: genId(),
       name: input.name,
       description: input.description,
       status: "active",
       schedule: input.schedule,
-      target: input.target,
+      target,
       goal: input.goal,
       machine: input.machine,
       nextRunAt: initialNextRun(input.schedule, from),
@@ -1258,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}`);
@@ -1332,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)
@@ -3433,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
@@ -3444,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),
@@ -3632,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)
@@ -3669,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);
@@ -3811,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)
@@ -3848,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);
@@ -4273,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 };
@@ -4569,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)
@@ -4579,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";
@@ -104,10 +105,13 @@ export interface AgentRoutingSpec {
     eventType?: string;
     eventSource?: string;
 }
-export interface AgentTarget {
+export interface AgentPromptSource {
+    type: "file";
+    path: string;
+}
+export interface AgentTargetBase {
     type: "agent";
     provider: AgentProvider;
-    prompt: string;
     cwd?: string;
     model?: string;
     variant?: string;
@@ -115,7 +119,7 @@ export interface AgentTarget {
     authProfile?: string;
     extraArgs?: string[];
     addDirs?: string[];
-    timeoutMs?: number;
+    timeoutMs?: TimeoutMs;
     idleTimeoutMs?: number;
     configIsolation?: AgentConfigIsolation;
     permissionMode?: AgentPermissionMode;
@@ -126,15 +130,24 @@ export interface AgentTarget {
     account?: AccountRef;
     preflight?: RuntimePreflightPolicy;
 }
+export interface AgentTarget extends AgentTargetBase {
+    prompt: string;
+    promptSource?: AgentPromptSource;
+}
+export interface PromptFileAgentTarget extends AgentTargetBase {
+    promptFile: string;
+}
 export interface WorkflowTarget {
     type: "workflow";
     workflowId: string;
     input?: Record<string, string>;
-    timeoutMs?: number;
+    timeoutMs?: TimeoutMs;
     preflight?: RuntimePreflightPolicy;
 }
 export type ExecutableTarget = CommandTarget | AgentTarget;
+export type ExecutableTargetInput = CommandTarget | AgentTarget | PromptFileAgentTarget;
 export type LoopTarget = ExecutableTarget | WorkflowTarget;
+export type LoopTargetInput = ExecutableTargetInput | WorkflowTarget;
 export type WorkflowStatus = "active" | "archived";
 export type WorkflowRunStatus = "running" | "succeeded" | "failed" | "timed_out" | "cancelled";
 export type WorkflowStepRunStatus = "pending" | "running" | "succeeded" | "failed" | "timed_out" | "skipped" | "cancelled";
@@ -230,9 +243,12 @@ export interface WorkflowStep {
     goal?: GoalSpec;
     dependsOn?: string[];
     continueOnFailure?: boolean;
-    timeoutMs?: number;
+    timeoutMs?: TimeoutMs;
     account?: AccountRef;
 }
+export interface WorkflowStepInput extends Omit<WorkflowStep, "target"> {
+    target: ExecutableTargetInput;
+}
 export interface WorkflowSpec {
     id: string;
     name: string;
@@ -248,7 +264,7 @@ export interface CreateWorkflowInput {
     name: string;
     description?: string;
     goal?: GoalSpec;
-    steps: WorkflowStep[];
+    steps: WorkflowStepInput[];
     version?: number;
 }
 export type LoopTemplateKind = "workflow" | "loop";
@@ -367,7 +383,7 @@ export interface CreateLoopInput {
     name: string;
     description?: string;
     schedule: ScheduleSpec;
-    target: LoopTarget;
+    target: LoopTargetInput;
     goal?: GoalSpec;
     machine?: LoopMachineRef;
     catchUp?: CatchUpPolicy;

package/docs/USAGE.md

@@ -148,6 +148,56 @@ accounts tools add codewith --label "Codewith" --env-var CODEWITH_HOME --bin cod
 accounts tools add aicopilot --label "AI Copilot" --env-var AICOPILOT_CONFIG_DIR --bin aicopilot
 ```
 
+## Prompt Files
+
+Use prompt files for production agent prompts instead of long inline strings.
+This keeps the durable prompt source reviewable and prevents shell history from
+becoming the only copy of the prompt.
+
+```bash
+mkdir -p ~/.hasna/loops/prompts
+$EDITOR ~/.hasna/loops/prompts/repo-morning-check.md
+
+loops create agent morning-check \
+  --provider codewith \
+  --auth-profile account001 \
+  --cron "0 8 * * *" \
+  --cwd /path/to/repo \
+  --prompt-file ~/.hasna/loops/prompts/repo-morning-check.md
+```
+
+Workflow JSON supports `promptFile` on agent targets. Relative paths resolve
+from the workflow JSON file's directory:
+
+```json
+{
+  "name": "repo-morning",
+  "steps": [
+    {
+      "id": "review",
+      "target": {
+        "type": "agent",
+        "provider": "codewith",
+        "cwd": "/path/to/repo",
+        "promptFile": "prompts/repo-morning-review.md"
+      }
+    }
+  ]
+}
+```
+
+OpenLoops stores the resolved prompt text for execution and records
+`promptSource` metadata with the absolute file path. Public CLI output from
+`show`, `list`, `workflows list`, `workflows show`, `workflows validate`,
+`workflows create`, and `templates render` redacts prompt bodies by default
+while keeping `promptSource` visible. Use
+`~/.hasna/loops/prompts/<stable-name>.md` as the default prompt store for local
+production loops.
+
+Reusable custom templates cannot contain `promptFile`. Keep prompt files in
+direct workflow JSON or agent loop creation; use template variables only for
+non-secret routing/configuration data.
+
 ## Workflows
 
 Create a workflow JSON file:
@@ -195,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`:
@@ -260,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",
@@ -268,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}",
@@ -284,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.53",
+  "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",