@hasna/loops 0.3.47 → 0.3.49

package/dist/sdk/index.js

@@ -327,6 +327,13 @@ function optionalPositiveInteger(value, label) {
     throw new Error(`${label} must be a positive integer`);
   return value;
 }
+function optionalBoolean(value, label) {
+  if (value === undefined)
+    return;
+  if (typeof value !== "boolean")
+    throw new Error(`${label} must be a boolean`);
+  return value;
+}
 function optionalStringArray(value, label) {
   if (value === undefined)
     return;
@@ -338,6 +345,18 @@ function optionalStringArray(value, label) {
   }).filter(Boolean);
   return values.length ? values : undefined;
 }
+function optionalAccountRef(value, label) {
+  if (value === undefined)
+    return;
+  assertObject(value, label);
+  assertString(value.profile, `${label}.profile`);
+  if (value.tool !== undefined)
+    assertString(value.tool, `${label}.tool`);
+  return {
+    profile: value.profile.trim(),
+    tool: typeof value.tool === "string" ? value.tool.trim() : undefined
+  };
+}
 function normalizeGoalSpec(value, label = "goal") {
   if (value === undefined)
     return;
@@ -384,8 +403,21 @@ function validateTarget(value, label) {
       if (value.provider !== "codewith")
         throw new Error(`${label}.authProfile is currently supported only for provider codewith`);
     }
+    if (value.configIsolation !== undefined) {
+      assertString(value.configIsolation, `${label}.configIsolation`);
+      if (!["safe", "none"].includes(value.configIsolation))
+        throw new Error(`${label}.configIsolation must be safe or none`);
+    }
+    if (value.model !== undefined)
+      assertString(value.model, `${label}.model`);
     if (value.variant !== undefined)
       assertString(value.variant, `${label}.variant`);
+    if (value.agent !== undefined)
+      assertString(value.agent, `${label}.agent`);
+    if (value.provider === "cursor" && value.variant !== undefined)
+      throw new Error(`${label}.variant is not supported for provider cursor`);
+    if (value.provider === "codex" && value.agent !== undefined)
+      throw new Error(`${label}.agent is not supported for provider codex`);
     optionalStringArray(value.addDirs, `${label}.addDirs`);
     if (Array.isArray(value.addDirs) && value.addDirs.length > 0 && !["codewith", "codex"].includes(value.provider)) {
       throw new Error(`${label}.addDirs is currently supported only for provider codewith or codex`);
@@ -482,8 +514,10 @@ function normalizeCreateWorkflowInput(input) {
       id: step.id,
       goal: normalizeGoalSpec(step.goal, `workflow.steps[${index}].goal`),
       target: validateTarget(step.target, `workflow.steps[${index}].target`),
-      dependsOn: step.dependsOn ?? [],
-      continueOnFailure: step.continueOnFailure ?? false
+      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`),
+      account: optionalAccountRef(step.account, `workflow.steps[${index}].account`)
     };
   });
   for (const step of steps) {
@@ -584,6 +618,11 @@ function writeWorkflowRunManifest(args) {
 }
 
 // src/lib/store.ts
+var DEFAULT_RECOVERY_BATCH_LIMIT = 100;
+var DEFAULT_RECOVERY_SCAN_MULTIPLIER = 5;
+var LIVE_EXPIRED_RUN_GRACE_MS = 60000;
+var GENERATED_ROUTE_TEMPLATE_IDS = new Set(["todos-task-worker-verifier", "event-worker-verifier"]);
+var GENERATED_ROUTE_KEYS = new Set(["todos-task", "generic-event"]);
 function rowToLoop(row) {
   return {
     id: row.id,
@@ -850,6 +889,7 @@ class Store {
       ensurePrivateStorePath(file);
     this.rootDir = file === ":memory:" ? mkdtempSync(join3(tmpdir(), "open-loops-store-")) : dirname(file);
     this.db = new Database(file);
+    this.db.exec("PRAGMA foreign_keys = ON;");
     this.db.exec("PRAGMA busy_timeout = 5000;");
     this.db.exec("PRAGMA journal_mode = WAL;");
     if (file !== ":memory:")
@@ -913,6 +953,7 @@ class Store {
       );
       CREATE INDEX IF NOT EXISTS idx_runs_loop ON loop_runs(loop_id, created_at);
       CREATE INDEX IF NOT EXISTS idx_runs_status ON loop_runs(status);
+      CREATE INDEX IF NOT EXISTS idx_runs_status_lease ON loop_runs(status, lease_expires_at);
       CREATE INDEX IF NOT EXISTS idx_runs_scheduled ON loop_runs(scheduled_for);
 
       CREATE TABLE IF NOT EXISTS daemon_lease (
@@ -1240,39 +1281,51 @@ class Store {
     }
     return rows.map(rowToLoop);
   }
-  dueLoops(now) {
+  dueLoops(now, limit = 500) {
     const rows = this.db.query(`SELECT * FROM loops
          WHERE status = 'active'
            AND archived_at IS NULL
            AND next_run_at IS NOT NULL
            AND next_run_at <= ?
-         ORDER BY next_run_at ASC`).all(now.toISOString());
+         ORDER BY next_run_at ASC
+         LIMIT ?`).all(now.toISOString(), limit);
     return rows.map(rowToLoop);
   }
   updateLoop(id, patch, opts = {}) {
-    const current = this.getLoop(id);
-    if (!current)
-      throw new Error(`loop not found: ${id}`);
     const updated = (opts.now ?? new Date).toISOString();
-    const merged = { ...current, ...patch, updatedAt: updated };
-    this.db.query(`UPDATE loops SET status=$status, next_run_at=$nextRun, retry_scheduled_for=$retrySlot,
-         expires_at=$expiresAt, 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: id,
-      $status: merged.status,
-      $nextRun: merged.nextRunAt ?? null,
-      $retrySlot: merged.retryScheduledFor ?? null,
-      $expiresAt: merged.expiresAt ?? null,
-      $updated: merged.updatedAt,
-      $daemonLeaseId: opts.daemonLeaseId ?? null,
-      $now: updated
-    });
-    if (patch.status && patch.status !== "active") {
-      const status = patch.status === "paused" ? "deferred" : "cancelled";
-      this.setWorkflowWorkItemsForLoop(id, status, `loop ${patch.status}`, updated);
+    this.db.exec("BEGIN IMMEDIATE");
+    try {
+      const current = this.getLoop(id);
+      if (!current)
+        throw new Error(`loop not found: ${id}`);
+      const merged = { ...current, ...patch, updatedAt: updated };
+      const res = this.db.query(`UPDATE loops SET status=$status, next_run_at=$nextRun, retry_scheduled_for=$retrySlot,
+           expires_at=$expiresAt, 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: id,
+        $status: merged.status,
+        $nextRun: merged.nextRunAt ?? null,
+        $retrySlot: merged.retryScheduledFor ?? null,
+        $expiresAt: merged.expiresAt ?? null,
+        $updated: merged.updatedAt,
+        $daemonLeaseId: opts.daemonLeaseId ?? null,
+        $now: updated
+      });
+      if (res.changes !== 1)
+        throw new Error("daemon lease lost");
+      if (patch.status && patch.status !== "active") {
+        const status = patch.status === "paused" ? "deferred" : "cancelled";
+        this.setWorkflowWorkItemsForLoop(id, status, `loop ${patch.status}`, updated);
+      }
+      this.db.exec("COMMIT");
+    } catch (error) {
+      try {
+        this.db.exec("ROLLBACK");
+      } catch {}
+      throw error;
     }
     const after = this.getLoop(id);
     if (!after)
@@ -1390,10 +1443,23 @@ class Store {
     })();
   }
   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);
+    const offset = Math.max(0, opts.offset ?? 0);
+    let rows;
+    if (opts.status && opts.limit !== undefined) {
+      rows = this.db.query("SELECT * FROM workflow_specs WHERE status = ? ORDER BY updated_at DESC LIMIT ? OFFSET ?").all(opts.status, opts.limit, offset);
+    } else if (opts.status) {
+      rows = this.db.query("SELECT * FROM workflow_specs WHERE status = ? ORDER BY updated_at DESC LIMIT -1 OFFSET ?").all(opts.status, offset);
+    } else if (opts.limit !== undefined) {
+      rows = this.db.query("SELECT * FROM workflow_specs ORDER BY status ASC, updated_at DESC LIMIT ? OFFSET ?").all(opts.limit, offset);
+    } else {
+      rows = this.db.query("SELECT * FROM workflow_specs ORDER BY status ASC, updated_at DESC LIMIT -1 OFFSET ?").all(offset);
+    }
     return rows.map(rowToWorkflow);
   }
+  countWorkflows(opts = {}) {
+    const row = opts.status ? this.db.query("SELECT COUNT(*) AS count FROM workflow_specs WHERE status = ?").get(opts.status) : this.db.query("SELECT COUNT(*) AS count FROM workflow_specs").get();
+    return row?.count ?? 0;
+  }
   archiveWorkflow(idOrName) {
     const workflow = this.requireWorkflow(idOrName);
     const updated = nowIso();
@@ -1403,6 +1469,64 @@ class Store {
       throw new Error(`workflow not found after archive: ${workflow.id}`);
     return archived;
   }
+  generatedRouteArchiveContext(args) {
+    if (!args.loopId || !args.workItemId)
+      return;
+    const workItem = this.getWorkflowWorkItem(args.workItemId);
+    if (!workItem || !GENERATED_ROUTE_KEYS.has(workItem.routeKey))
+      return;
+    const invocation = this.getWorkflowInvocation(workItem.invocationId);
+    if (!invocation?.templateId || !GENERATED_ROUTE_TEMPLATE_IDS.has(invocation.templateId))
+      return;
+    const loop = this.getLoop(args.loopId);
+    if (!loop || loop.schedule.type !== "once" || loop.target.type !== "workflow" || loop.target.workflowId !== args.workflowId)
+      return;
+    const input = loop.target.input ?? {};
+    if (input.workflowWorkItemId && input.workflowWorkItemId !== workItem.id)
+      return;
+    if (input.workflowInvocationId && input.workflowInvocationId !== invocation.id)
+      return;
+    if (workItem.workflowId && workItem.workflowId !== args.workflowId)
+      return;
+    const workflow = this.getWorkflow(args.workflowId);
+    if (!workflow)
+      return;
+    return { workflow, loop, workItem, invocation };
+  }
+  maybeArchiveGeneratedRouteWorkflow(args) {
+    const context = this.generatedRouteArchiveContext(args);
+    if (!context)
+      return;
+    const { workflow, loop, workItem } = context;
+    if (!workflow || workflow.status !== "active")
+      return;
+    const nonTerminal = this.db.query(`SELECT COUNT(*) AS count FROM workflow_runs
+         WHERE workflow_id = ? AND status NOT IN ('succeeded', 'failed', 'timed_out', 'cancelled')`).get(args.workflowId)?.count ?? 0;
+    if (nonTerminal > 0)
+      return;
+    const res = this.db.query("UPDATE workflow_specs SET status='archived', updated_at=? WHERE id=? AND status='active'").run(args.updated, args.workflowId);
+    if (res.changes === 1 && args.workflowRunId) {
+      this.appendWorkflowEvent(args.workflowRunId, "workflow_archived", undefined, {
+        workflowId: args.workflowId,
+        loopId: loop.id,
+        workItemId: workItem.id,
+        routeKey: workItem.routeKey,
+        reason: "terminal generated one-shot route workflow"
+      });
+    }
+  }
+  maybeArchiveTerminalGeneratedRouteWorkflow(workflowRunId, updated) {
+    const run = this.getWorkflowRun(workflowRunId);
+    if (!run)
+      return;
+    this.maybeArchiveGeneratedRouteWorkflow({
+      workflowId: run.workflowId,
+      loopId: run.loopId,
+      workItemId: run.workItemId,
+      workflowRunId,
+      updated
+    });
+  }
   createWorkflowInvocation(input) {
     const now = nowIso();
     const sourceDedupeKey = input.sourceRef.dedupeKey ?? undefined;
@@ -2188,6 +2312,7 @@ class Store {
       if (changed) {
         const itemStatus = status === "succeeded" ? "succeeded" : status === "cancelled" ? "cancelled" : "failed";
         this.setWorkflowWorkItemsForWorkflowRun(workflowRunId, itemStatus, patch.error, finishedAt);
+        this.maybeArchiveTerminalGeneratedRouteWorkflow(workflowRunId, finishedAt);
       }
       this.db.exec("COMMIT");
     } catch (error) {
@@ -2215,6 +2340,7 @@ class Store {
              WHERE workflow_run_id=$workflowRunId AND status IN ('pending', 'running')`).run({ $workflowRunId: workflowRunId, $finished: now, $reason: reason, $updated: now });
         this.setWorkflowWorkItemsForWorkflowRun(workflowRunId, "cancelled", reason, now);
         this.appendWorkflowEvent(workflowRunId, "cancelled", undefined, { reason });
+        this.maybeArchiveTerminalGeneratedRouteWorkflow(workflowRunId, now);
       }
       this.db.exec("COMMIT");
       return this.requireWorkflowRun(workflowRunId);
@@ -2467,8 +2593,20 @@ class Store {
       throw new Error(`run not found after finalize: ${id}`);
     if (opts.claimedBy && res.changes !== 1)
       return run;
-    if (res.changes === 1)
+    if (res.changes === 1) {
       this.setWorkflowWorkItemsForLoopRun(run, patch.error, finishedAt);
+      const loop = this.getLoop(run.loopId);
+      const itemStatus = workItemStatusForLoopRun(run.status, run.attempt, loop?.maxAttempts);
+      if (loop?.target.type === "workflow" && itemStatus && itemStatus !== "admitted") {
+        const workItemId = loop.target.input?.workflowWorkItemId ?? loop.target.input?.workItemId;
+        this.maybeArchiveGeneratedRouteWorkflow({
+          workflowId: loop.target.workflowId,
+          loopId: loop.id,
+          workItemId,
+          updated: finishedAt
+        });
+      }
+    }
     return run;
   }
   heartbeatRunLease(id, claimedBy, leaseMs, now = new Date, opts = {}) {
@@ -2503,14 +2641,40 @@ class Store {
     }
     return rows.map(rowToRun);
   }
+  deferLiveExpiredRun(id, now, opts = {}) {
+    const updated = now.toISOString();
+    const deferredUntil = new Date(now.getTime() + LIVE_EXPIRED_RUN_GRACE_MS).toISOString();
+    this.db.query(`UPDATE loop_runs SET lease_expires_at=$deferredUntil, updated_at=$updated
+         WHERE id=$id AND status='running' AND lease_expires_at <= $now
+           AND ($daemonLeaseId IS NULL OR EXISTS (
+             SELECT 1 FROM daemon_lease WHERE id=$daemonLeaseId AND expires_at > $now
+           ))`).run({
+      $id: id,
+      $deferredUntil: deferredUntil,
+      $updated: updated,
+      $now: updated,
+      $daemonLeaseId: opts.daemonLeaseId ?? null
+    });
+  }
   recoverExpiredRunLeases(now = new Date, opts = {}) {
-    const rows = this.db.query("SELECT * FROM loop_runs WHERE status = 'running' AND lease_expires_at <= ?").all(now.toISOString());
+    const limit = Math.max(1, Math.min(1000, Math.floor(opts.limit ?? DEFAULT_RECOVERY_BATCH_LIMIT)));
+    const scanLimit = Math.max(limit, Math.min(5000, Math.floor(opts.scanLimit ?? limit * DEFAULT_RECOVERY_SCAN_MULTIPLIER)));
+    const rows = this.db.query(`SELECT * FROM loop_runs
+         WHERE status = 'running' AND lease_expires_at <= ?
+         ORDER BY lease_expires_at ASC
+         LIMIT ?`).all(now.toISOString(), scanLimit);
     const recovered = [];
     for (const row of rows) {
-      if (row.pid && isProcessAlive(row.pid))
+      if (recovered.length >= limit)
+        break;
+      if (row.pid && isProcessAlive(row.pid)) {
+        this.deferLiveExpiredRun(row.id, now, opts);
         continue;
-      if (this.hasLiveWorkflowStepProcesses(row.id))
+      }
+      if (this.hasLiveWorkflowStepProcesses(row.id)) {
+        this.deferLiveExpiredRun(row.id, now, opts);
         continue;
+      }
       const finished = now.toISOString();
       this.db.exec("BEGIN IMMEDIATE");
       try {
@@ -2563,6 +2727,7 @@ class Store {
             loopRunId: row.id
           });
           this.setWorkflowWorkItemsForWorkflowRun(workflowRow.id, "failed", "parent loop run lease expired before completion", finished);
+          this.maybeArchiveTerminalGeneratedRouteWorkflow(workflowRow.id, finished);
         }
         const loop = this.getLoop(row.loop_id);
         const itemStatus = workItemStatusForLoopRun("abandoned", row.attempt, loop?.maxAttempts);
@@ -2570,6 +2735,15 @@ class Store {
           const statuses = itemStatus === "admitted" ? ["admitted", "running", "failed"] : ["admitted", "running"];
           const reason = itemStatus === "admitted" ? "run lease expired before completion; retry pending" : "run lease expired before completion";
           this.setWorkflowWorkItemsForLoop(row.loop_id, itemStatus, reason, finished, statuses);
+          if (loop?.target.type === "workflow" && itemStatus !== "admitted") {
+            const workItemId = loop.target.input?.workflowWorkItemId ?? loop.target.input?.workItemId;
+            this.maybeArchiveGeneratedRouteWorkflow({
+              workflowId: loop.target.workflowId,
+              loopId: loop.id,
+              workItemId,
+              updated: finished
+            });
+          }
         }
         this.db.exec("COMMIT");
       } catch (error) {
@@ -2899,6 +3073,7 @@ var AUTH_ENV_KEYS = [
   "CODEWITH_HOME",
   "CODEX_HOME",
   "CURSOR_CONFIG_DIR",
+  "CURSOR_API_KEY",
   "OPENCODE_CONFIG_DIR",
   "AICOPILOT_CONFIG_DIR",
   "ANTHROPIC_API_KEY",
@@ -3028,6 +3203,10 @@ function assertSupportedAgentOptions(target) {
   assertStringOption(target.model, `${target.provider}.model`);
   assertStringOption(target.agent, `${target.provider}.agent`);
   assertStringOption(target.authProfile, `${target.provider}.authProfile`);
+  assertStringOption(target.configIsolation, `${target.provider}.configIsolation`);
+  if (target.configIsolation !== undefined && target.configIsolation !== "safe" && target.configIsolation !== "none") {
+    throw new Error(`${target.provider}.configIsolation must be safe or none`);
+  }
   if (target.authProfile !== undefined && target.provider !== "codewith") {
     throw new Error(`${target.provider}.authProfile is supported only for codewith`);
   }
@@ -3040,6 +3219,8 @@ function assertSupportedAgentOptions(target) {
   if (target.sandbox && !["read-only", "workspace-write", "danger-full-access", "enabled", "disabled"].includes(target.sandbox)) {
     throw new Error(`${target.provider}.sandbox is not supported: ${target.sandbox}`);
   }
+  if (target.provider === "codex" && target.agent !== undefined)
+    throw new Error("codex.agent is not supported");
   if (["codewith", "codex"].includes(target.provider)) {
     if (target.permissionMode && !["default", "bypass"].includes(target.permissionMode)) {
       throw new Error(`${target.provider}.permissionMode supports only default or bypass`);
@@ -3054,6 +3235,8 @@ function assertSupportedAgentOptions(target) {
     return;
   }
   if (target.provider === "cursor") {
+    if (target.variant !== undefined)
+      throw new Error("cursor.variant is not supported");
     if (target.permissionMode === "auto")
       throw new Error("cursor.permissionMode auto is not supported; use provider-specific extraArgs for Cursor auto-review");
     if (target.sandbox !== undefined && target.sandbox !== "enabled" && target.sandbox !== "disabled") {
@@ -3095,10 +3278,8 @@ function agentArgs(target) {
         "set -eu",
         "if command -v agent >/dev/null 2>&1; then",
         '  exec agent "$@"',
-        "elif command -v cursor >/dev/null 2>&1; then",
-        '  exec cursor agent "$@"',
         "else",
-        "  echo 'Executable not found in PATH: cursor agent or agent' >&2",
+        "  echo 'Executable not found in PATH: agent' >&2",
         "  exit 127",
         "fi"
       ].join(`
@@ -3139,7 +3320,7 @@ function agentArgs(target) {
     case "codex":
       if (target.variant)
         args.push("-c", `model_reasoning_effort=${configStringValue(target.variant)}`);
-      args.push("exec", "--json", "--ephemeral", "--sandbox", codewithLikeSandbox(target), "--skip-git-repo-check");
+      args.push("--ask-for-approval", "never", "exec", "--json", "--ephemeral", "--sandbox", codewithLikeSandbox(target), "--skip-git-repo-check");
       if (isolation === "safe")
         args.push("--ignore-rules");
       if (target.cwd)
@@ -3209,7 +3390,7 @@ function commandSpec(target) {
     account: agentTarget.account,
     accountTool: agentTarget.account?.tool ?? accountToolForProvider(agentTarget.provider),
     nativeAuthProfile: agentTarget.authProfile ? { provider: agentTarget.provider, profile: agentTarget.authProfile } : undefined,
-    preflightAnyOf: agentTarget.provider === "cursor" ? ["cursor", "agent"] : undefined,
+    preflightAnyOf: agentTarget.provider === "cursor" ? ["agent"] : undefined,
     stdin: agentTarget.prompt,
     allowlist: agentTarget.allowlist
   };
@@ -4592,12 +4773,14 @@ function claimDueRuns(deps) {
   const claimed = [];
   const skipped = [];
   const maxClaims = Math.max(0, deps.maxClaims ?? Number.POSITIVE_INFINITY);
+  if (maxClaims === 0)
+    return { claims, claimed, completed: [], skipped, recovered, expired };
   for (const loop of deps.store.dueLoops(now)) {
-    if (claims.length >= maxClaims)
+    if (claims.length + skipped.length >= maxClaims)
       break;
     const plan = dueSlots(loop, now);
     for (const slot of plan.slots) {
-      if (claims.length >= maxClaims)
+      if (claims.length + skipped.length >= maxClaims)
         break;
       const run = claimSlot(deps, loop, slot);
       if (!run)

package/docs/USAGE.md

@@ -5,7 +5,7 @@ OpenLoops is a local CLI and daemon for persistent loops and workflows: schedule
 It supports deterministic command loops, JSON-defined workflows, and guarded CLI adapters for headless coding agents:
 
 - `claude`
-- `cursor agent` or `agent`
+- `agent` (Cursor Agent CLI)
 - `codewith exec`
 - `aicopilot run`
 - `opencode run`
@@ -367,13 +367,13 @@ loops events drain todos-task \
   --todos-project "$HOME/.hasna/loops" \
   --task-list repoops-pr-queue \
   --tags auto:route \
-  --project-path-prefix "$HOME/workspace/hasna/opensource" \
+  --project-path-prefix /home/hasna/workspace/hasna/opensource \
   --provider codewith \
   --auth-profile-pool account004,account005,account006 \
   --add-dir "$HOME/.hasna/todos,$HOME/.hasna/loops" \
   --project-group oss \
   --max-dispatch 2 \
-  --scan-limit 500 \
+  --scan-limit 5000 \
   --max-active-per-project 1 \
   --max-active-per-project-group 4 \
   --max-active 12 \
@@ -394,6 +394,45 @@ when requested, and leaves excess ready tasks in todos for a later drain pass.
 Use `--dry-run` to preview candidates and rendered workflows without mutating
 OpenLoops state.
 
+For the Hasna OSS task-created route, keep the drain deterministic and narrow:
+
+```bash
+loops routes schedule todos-task oss-task-route-drain \
+  --every 5m \
+  --todos-project "$HOME/.hasna/loops" \
+  --project-path-prefix /home/hasna/workspace/hasna/opensource \
+  --tags auto:route \
+  --provider codewith \
+  --auth-profile-pool account004,account005,account006 \
+  --add-dir "$HOME/.hasna/todos,$HOME/.hasna/loops" \
+  --project-group oss \
+  --max-dispatch 2 \
+  --scan-limit 5000 \
+  --max-active-per-project 1 \
+  --max-active-per-project-group 4 \
+  --max-active 12 \
+  --worktree-mode required \
+  --evidence-dir "$HOME/.hasna/loops/reports/oss-task-route-drain" \
+  --compact
+```
+
+Only tasks under `/home/hasna/workspace/hasna/opensource` that explicitly opt
+in with the `auto:route` tag, `route_enabled=true`, or
+`automation.allowed=true` should be routed. Keep repo-mutating worker/verifier
+runs on a Codewith account pool with `--worktree-mode required`. Do not dispatch
+or paste task prompts into tmux panes. Use max-active throttles and
+`--max-dispatch` to bound agent fan-out, and write compact evidence into a
+bounded reports directory so operators can audit each drain without unbounded
+stdout or loop history growth. Keep `--scan-limit` large enough for the current
+ready-task backlog; if the scan is exhausted before matching tasks appear, the
+drain will correctly do no work.
+
+Generated task/event route workflow specs are lifecycle-managed. After a
+generated one-shot route workflow run reaches `succeeded`, `failed`,
+`timed_out`, or `cancelled`, OpenLoops archives the generated workflow spec while
+preserving workflow run, step, event, manifest, loop, invocation, and work-item
+history.
+
 For other Hasna apps that expose `@hasna/events` webhooks, use the generic
 handler:
 
@@ -578,8 +617,8 @@ The adapters intentionally use provider command surfaces instead of pretending e
 - Claude uses `claude -p --output-format json` and safe-mode/local setting sources by default.
 - Codewith uses `codewith --ask-for-approval never exec --json --ephemeral --skip-git-repo-check`, with `--add-dir` for explicit extra writable directories.
 - AI Copilot and OpenCode use `run --format json --pure`.
-- Cursor is CLI-first for now via standalone `agent -p` when available, with `cursor agent -p` as a compatibility fallback; treat output as less stable until a stronger public SDK contract is selected.
-- Codex uses `codex exec --json --ephemeral --skip-git-repo-check`, with `--add-dir` for explicit extra writable directories where supported.
+- Cursor is CLI-first for now via the standalone `agent -p` binary. OpenLoops no longer falls back to `cursor agent`; install the standalone Cursor Agent CLI so preflight and scheduled runs use the same executable.
+- Codex uses `codex --ask-for-approval never exec --json --ephemeral --skip-git-repo-check`, with `--add-dir` for explicit extra writable directories where supported.
 - Agent prompts are sent through child stdin instead of argv so prompt bodies do not appear in process listings.
 - When `--account` or a step `account` is set, OpenLoops resolves `accounts env <profile> --tool <tool>` before spawning the target, strips inherited tool home/API-key variables, and applies the selected profile only to that process. Missing account profiles fail before the provider binary receives the prompt.
 - `--auth-profile` and step `authProfile` are provider-native auth selectors. They currently apply to Codewith and are passed to Codewith as `--auth-profile <name>` before `exec`; they do not call OpenAccounts.

package/package.json

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