@hasna/loops 0.3.48 → 0.3.50

package/dist/lib/store.js

@@ -621,6 +621,8 @@ function writeWorkflowRunManifest(args) {
 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,
@@ -1441,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();
@@ -1454,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;
@@ -2239,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) {
@@ -2266,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);
@@ -2518,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 = {}) {
@@ -2640,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);
@@ -2647,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) {

package/dist/lib/templates.d.ts

@@ -1,4 +1,4 @@
-import type { AccountRef, AgentPermissionMode, AgentProvider, AgentSandbox, AgentWorktreeMode, CreateWorkflowInput, LoopTemplateSummary } from "../types.js";
+import type { AccountRef, AgentPermissionMode, AgentProvider, AgentSandbox, AgentWorktreeMode, CreateWorkflowInput, LoopTemplateSource, LoopTemplateSummary } 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";
@@ -97,9 +97,29 @@ export interface BoundedAgentWorkflowTemplateInput {
     worktreeBranchPrefix?: string;
     timeoutMs?: number;
 }
-export declare function listLoopTemplates(): LoopTemplateSummary[];
-export declare function getLoopTemplate(id: string): LoopTemplateSummary | undefined;
+export type LoopTemplateSourceFilter = LoopTemplateSource | "all";
+export interface ListLoopTemplatesOptions {
+    source?: LoopTemplateSourceFilter;
+}
+export interface CustomLoopTemplateImportOptions {
+    replace?: boolean;
+}
+export interface CustomLoopTemplateImportResult {
+    template: LoopTemplateSummary;
+    path: string;
+    replaced: boolean;
+}
+export declare function loopTemplatesDir(): string;
+export declare function validateCustomLoopTemplateFile(file: string): LoopTemplateSummary;
+export declare function importCustomLoopTemplate(file: string, opts?: CustomLoopTemplateImportOptions): CustomLoopTemplateImportResult;
+export declare function validateLoopTemplateRegistry(opts?: ListLoopTemplatesOptions): {
+    ok: true;
+    templates: LoopTemplateSummary[];
+    customDir: string;
+};
+export declare function listLoopTemplates(opts?: ListLoopTemplatesOptions): LoopTemplateSummary[];
+export declare function getLoopTemplate(id: string, opts?: ListLoopTemplatesOptions): LoopTemplateSummary | undefined;
 export declare function renderTodosTaskWorkerVerifierWorkflow(input: TodosTaskWorkflowTemplateInput): CreateWorkflowInput;
 export declare function renderEventWorkerVerifierWorkflow(input: EventWorkflowTemplateInput): CreateWorkflowInput;
 export declare function renderBoundedAgentWorkerVerifierWorkflow(input: BoundedAgentWorkflowTemplateInput): CreateWorkflowInput;
-export declare function renderLoopTemplate(id: string, values: Record<string, string | undefined>): CreateWorkflowInput;
+export declare function renderLoopTemplate(id: string, values: Record<string, string | undefined>, opts?: ListLoopTemplatesOptions): CreateWorkflowInput;

package/dist/sdk/index.js

@@ -621,6 +621,8 @@ function writeWorkflowRunManifest(args) {
 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,
@@ -1441,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();
@@ -1454,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;
@@ -2239,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) {
@@ -2266,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);
@@ -2518,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 = {}) {
@@ -2640,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);
@@ -2647,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) {

package/dist/types.d.ts

@@ -252,11 +252,14 @@ export interface CreateWorkflowInput {
     version?: number;
 }
 export type LoopTemplateKind = "workflow" | "loop";
+export type LoopTemplateSource = "builtin" | "custom";
+export type LoopTemplateVariableType = "string" | "number" | "boolean" | "json" | "string[]";
 export interface LoopTemplateVariable {
     name: string;
     description?: string;
     required?: boolean;
     default?: string;
+    type?: LoopTemplateVariableType;
 }
 export interface LoopTemplateSummary {
     id: string;
@@ -264,6 +267,8 @@ export interface LoopTemplateSummary {
     description: string;
     kind: LoopTemplateKind;
     variables: LoopTemplateVariable[];
+    source?: LoopTemplateSource;
+    sourcePath?: string;
 }
 export interface WorkflowRun {
     id: string;

package/docs/USAGE.md

@@ -254,6 +254,65 @@ loops templates render deterministic-check-create-task \
   --var checkCommand='your deterministic check and todos upsert command'
 ```
 
+Custom reusable workflow templates live under the OpenLoops app data directory:
+`~/.hasna/loops/templates` by default, or `$LOOPS_DATA_DIR/templates` when
+`LOOPS_DATA_DIR` is set. Store templates as declarative JSON files; listing,
+showing, and rendering templates never executes workflow steps or mutates the
+registry.
+
+```json
+{
+  "id": "custom-report",
+  "name": "Custom Report",
+  "description": "Run a custom report workflow from the local template registry.",
+  "kind": "workflow",
+  "variables": [
+    { "name": "objective", "required": true, "description": "Report objective." },
+    { "name": "projectPath", "required": true, "description": "Working directory." },
+    { "name": "timeoutMs", "default": "300000", "type": "number" }
+  ],
+  "workflow": {
+    "name": "custom-report-${objective}",
+    "steps": [
+      {
+        "id": "worker",
+        "target": {
+          "type": "agent",
+          "provider": "codewith",
+          "prompt": "/goal ${objective}\nProduce the requested report only.",
+          "cwd": "${projectPath}",
+          "configIsolation": "safe",
+          "permissionMode": "bypass",
+          "sandbox": "workspace-write",
+          "timeoutMs": "${timeoutMs}"
+        },
+        "timeoutMs": "${timeoutMs}"
+      }
+    ]
+  }
+}
+```
+
+```bash
+loops templates validate ./custom-report.json
+loops templates import ./custom-report.json
+loops templates list --source custom
+loops templates show custom-report
+loops templates render custom-report \
+  --var objective="Check docs drift" \
+  --var projectPath=/path/to/repo
+loops templates create-workflow custom-report \
+  --var objective="Check docs drift" \
+  --var projectPath=/path/to/repo
+```
+
+Use `--source builtin`, `--source custom`, or `--source all` on
+`list`, `show`, `render`, and `create-workflow` when automation needs an
+explicit source. Custom template ids and names cannot override built-ins.
+Custom templates fail closed for `danger-full-access`; use built-in templates
+with explicit break-glass handling for emergency workflows that need that
+sandbox.
+
 Repo-mutating task/event routes should set `worktreeMode=required` so the
 workflow fails fast instead of falling back to the main checkout. When
 `projectPath` is an existing git repository, OpenLoops inserts a
@@ -367,13 +426,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 +453,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:
 
@@ -515,6 +613,20 @@ production loop. Route commands store a small cursor in
 through all findings over repeated scheduled runs instead of reprocessing only
 the first batch.
 
+For a deliberate operator rename, use the first-class rename command instead of
+turning a one-off naming preference into hygiene policy:
+
+```bash
+loops rename machine-todos-drain-oss-repos-strict-5m machine-todos-drain-oss-repos
+loops --json rename <loop-id> machine-ops-loop-health-route-tasks
+```
+
+`rename` preserves the loop id, schedule, run history, archive state, and target
+configuration. It rejects empty or duplicate names and writes a SQLite backup
+under `<LOOPS_DATA_DIR>/backups` before mutating the loop row. Human-facing
+names should describe scope and responsibility; cadence belongs in schedule
+metadata and operator tables.
+
 Archive loops when retiring old automation but preserving history:
 
 ```bash

package/package.json

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