@hasna/loops 0.3.48 → 0.3.49

package/README.md

@@ -315,6 +315,38 @@ loops routes show <work-item-id>
 loops routes invocations
 ```
 
+For Hasna OSS task-created routing, use a deterministic drain instead of tmux
+dispatch:
+
+```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 route tasks that explicitly opt in with `auto:route`, `route_enabled=true`,
+or `automation.allowed=true`. Use Codewith account pools, required worktrees,
+max-active throttles, and bounded evidence directories. Do not dispatch or paste
+task prompts into tmux panes. Keep `--scan-limit` large enough for the local
+ready-task backlog; otherwise low-priority or newly-created tasks can sit beyond
+the scanned window. Generated one-shot task/event route workflow specs are
+archived automatically when their workflow run reaches a terminal state;
+workflow run history and manifests are preserved.
+
 Workflow run manifests are written under
 `.hasna/loops/runs/<project-slug>/<subject-key>/<run-id>/manifest.json`.
 `subject-key` is a safe derived path segment, not the raw subject reference.

package/dist/cli/index.js

@@ -623,6 +623,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,
@@ -1443,10 +1445,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();
@@ -1456,6 +1471,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;
@@ -2241,6 +2314,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) {
@@ -2268,6 +2342,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);
@@ -2520,8 +2595,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 = {}) {
@@ -2642,6 +2729,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);
@@ -2649,6 +2737,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) {
@@ -5811,7 +5908,7 @@ function buildScriptInventoryReport(store, opts = {}) {
 // package.json
 var package_default = {
   name: "@hasna/loops",
-  version: "0.3.48",
+  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",
@@ -6961,6 +7058,14 @@ function positiveInteger(raw, label) {
     throw new Error(`${label} must be a positive integer`);
   return value;
 }
+function nonNegativeInteger(raw, label) {
+  if (raw === undefined)
+    return;
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 0)
+    throw new Error(`${label} must be a non-negative integer`);
+  return value;
+}
 function positiveDuration(raw, label) {
   if (raw === undefined)
     return;
@@ -7442,6 +7547,23 @@ function taskRouteEligibility(data, metadata) {
   }
   return { eligible: true, tags };
 }
+function skippedDrainTask(task, event, reason) {
+  const taskId = taskField(task, ["id", "task_id", "taskId"]) ?? event?.subject ?? "unknown";
+  return {
+    kind: "skipped",
+    value: {
+      skipped: true,
+      reason,
+      taskId,
+      event,
+      routeError: true
+    },
+    human: `skipped task ${taskId}: ${reason}`
+  };
+}
+function isSkippableDrainRouteError(message) {
+  return message.startsWith("worktreeMode=required but projectPath is not an existing git repository:");
+}
 function generatedRouteSandboxPreflight(workflow) {
   const checks = [];
   for (const step of workflow.steps) {
@@ -8401,8 +8523,17 @@ function drainTodosTaskRoutes(opts) {
   for (const task of candidates) {
     if (created >= maxDispatch)
       break;
-    const event = taskDrainEvent(task);
-    const result = routeTodosTaskEvent(event, opts);
+    let event;
+    let result;
+    try {
+      event = taskDrainEvent(task);
+      result = routeTodosTaskEvent(event, opts);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (!isSkippableDrainRouteError(message))
+        throw error;
+      result = skippedDrainTask(task, event, redact(message, 640) ?? "route task failed");
+    }
     results.push(result);
     if (result.kind === "created" && !opts.dryRun)
       created += 1;
@@ -8463,6 +8594,57 @@ function drainTodosTaskRoutes(opts) {
   } : { ...report, evidencePath };
   print(output, `drained todos ready queue: considered=${report.considered} created=${report.created} deduped=${report.deduped} throttled=${report.throttled} skipped=${report.skipped}`);
 }
+function formatTemplateVariable(template, name) {
+  const variable = template.variables.find((entry) => entry.name === name);
+  const placeholder = variable?.default ? variable.default : `<${name}>`;
+  return `  --var ${name}=${placeholder}`;
+}
+function printTemplateDetails(template) {
+  console.log(`${template.id} (${template.kind})`);
+  console.log(template.name);
+  console.log("");
+  console.log(template.description);
+  console.log("");
+  console.log("Variables:");
+  const nameWidth = Math.max(...template.variables.map((variable) => variable.name.length), 4);
+  for (const variable of template.variables) {
+    const required = variable.required ? "required" : "optional";
+    const defaultValue = variable.default ? ` default=${variable.default}` : "";
+    const description = variable.description ? `  ${variable.description}` : "";
+    console.log(`  ${variable.name.padEnd(nameWidth)}  ${required}${defaultValue}${description}`);
+  }
+  const requiredVariables = template.variables.filter((variable) => variable.required).map((variable) => variable.name);
+  const hintVariables = requiredVariables.length ? requiredVariables : template.variables.slice(0, 2).map((variable) => variable.name);
+  const renderArgs = hintVariables.map((name) => formatTemplateVariable(template, name));
+  const renderHint = renderArgs.length ? ` \\
+${renderArgs.join(" \\\n")}` : "";
+  console.log("");
+  console.log("Usage:");
+  console.log(`  loops templates render ${template.id}${renderHint}`);
+  if (template.kind === "workflow")
+    console.log(`  loops templates create-workflow ${template.id}${renderHint}`);
+}
+function workflowStatusFromOpts(status, all) {
+  if (all) {
+    if (status && status !== "active")
+      throw new Error("use either --all or --status, not both");
+    return;
+  }
+  const value = status ?? "active";
+  if (value === "all")
+    return;
+  if (value === "active" || value === "archived")
+    return value;
+  throw new Error("--status must be active, archived, or all");
+}
+function printWorkflowListWarning(args) {
+  if (args.shown + args.offset >= args.total && args.offset === 0)
+    return;
+  const scope = args.status ?? "all";
+  const nextOffset = args.offset + args.shown;
+  const next = args.limit && nextOffset < args.total ? ` next page: --limit ${args.limit} --offset ${nextOffset}` : "";
+  console.error(`showing ${args.offset + args.shown} of ${args.total} ${scope} workflows.${next}`);
+}
 templates.command("list").alias("ls").description("list built-in OpenLoops templates").action(() => {
   const values = listLoopTemplates();
   if (isJson())
@@ -8477,7 +8659,10 @@ templates.command("show <id>").description("show a built-in template").action((i
   const template = getLoopTemplate(id);
   if (!template)
     throw new Error(`template not found: ${id}`);
-  print(template, `${template.id} ${template.kind}`);
+  if (isJson())
+    print(template);
+  else
+    printTemplateDetails(template);
 });
 templates.command("render <id>").description("render a template as workflow JSON").option("--var <key=value>", "template variable; may be repeated", collectValues, []).action((id, opts) => {
   const workflow = renderLoopTemplate(id, parseVars(opts.var));
@@ -8677,10 +8862,14 @@ workflows.command("create <file>").description("validate and store a workflow JS
     store.close();
   }
 });
-workflows.command("list").alias("ls").option("--status <status>", "active or archived", "active").action((opts) => {
+workflows.command("list").alias("ls").option("--status <status>", "active, archived, or all", "active").option("--all", "include active and archived workflows").option("--limit <n>", "maximum rows to print; omitted means all matching workflows").option("--offset <n>", "number of matching rows to skip before printing", "0").action((opts) => {
   const store = new Store;
   try {
-    const workflowsList = store.listWorkflows({ status: opts.status });
+    const status = workflowStatusFromOpts(opts.status, opts.all);
+    const limit = positiveInteger(opts.limit, "--limit");
+    const offset = nonNegativeInteger(opts.offset, "--offset") ?? 0;
+    const workflowsList = store.listWorkflows({ status, limit, offset });
+    const total = store.countWorkflows({ status });
     if (isJson())
       print(workflowsList.map(publicWorkflow));
     else {
@@ -8688,6 +8877,8 @@ workflows.command("list").alias("ls").option("--status <status>", "active or arc
         console.log(`${workflow.id}  ${workflow.status.padEnd(8)}  steps=${workflow.steps.length}  ${workflow.name}`);
       }
     }
+    if (limit !== undefined || offset > 0)
+      printWorkflowListWarning({ shown: workflowsList.length, total, status, offset, limit });
   } finally {
     store.close();
   }

package/dist/daemon/index.js

@@ -623,6 +623,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,
@@ -1443,10 +1445,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();
@@ -1456,6 +1471,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;
@@ -2241,6 +2314,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) {
@@ -2268,6 +2342,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);
@@ -2520,8 +2595,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 = {}) {
@@ -2642,6 +2729,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);
@@ -2649,6 +2737,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) {
@@ -5143,7 +5240,7 @@ function enableStartup(result) {
 // package.json
 var package_default = {
   name: "@hasna/loops",
-  version: "0.3.48",
+  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",

package/dist/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/lib/store.d.ts

@@ -94,8 +94,15 @@ export declare class Store {
     listWorkflows(opts?: {
         status?: WorkflowSpec["status"];
         limit?: number;
+        offset?: number;
     }): WorkflowSpec[];
+    countWorkflows(opts?: {
+        status?: WorkflowSpec["status"];
+    }): number;
     archiveWorkflow(idOrName: string): WorkflowSpec;
+    private generatedRouteArchiveContext;
+    private maybeArchiveGeneratedRouteWorkflow;
+    private maybeArchiveTerminalGeneratedRouteWorkflow;
     createWorkflowInvocation(input: CreateWorkflowInvocationInput): WorkflowInvocation;
     getWorkflowInvocation(id: string): WorkflowInvocation | undefined;
     listWorkflowInvocations(opts?: {

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/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/docs/USAGE.md

@@ -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:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/loops",
-  "version": "0.3.48",
+  "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",