@hasna/loops 0.3.48 → 0.3.50

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) {
@@ -2758,7 +2855,7 @@ class Store {
 
 // src/cli/index.ts
 import { createHash as createHash3, randomUUID } from "crypto";
-import { closeSync, existsSync as existsSync5, mkdirSync as mkdirSync6, mkdtempSync as mkdtempSync2, openSync as openSync2, readFileSync as readFileSync2, realpathSync, rmSync as rmSync3, writeFileSync as writeFileSync4 } from "fs";
+import { closeSync, existsSync as existsSync5, mkdirSync as mkdirSync7, mkdtempSync as mkdtempSync2, openSync as openSync2, readFileSync as readFileSync3, realpathSync, rmSync as rmSync3, writeFileSync as writeFileSync5 } from "fs";
 import { spawnSync as spawnSync5 } from "child_process";
 import { join as join6, resolve as resolve2 } from "path";
 import { tmpdir as tmpdir2 } from "os";
@@ -5811,7 +5908,7 @@ function buildScriptInventoryReport(store, opts = {}) {
 // package.json
 var package_default = {
   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",
@@ -5901,7 +5998,7 @@ function packageVersion() {
 
 // src/lib/templates.ts
 import { execFileSync } from "child_process";
-import { existsSync as existsSync4 } from "fs";
+import { existsSync as existsSync4, lstatSync, mkdirSync as mkdirSync6, readdirSync, readFileSync as readFileSync2, writeFileSync as writeFileSync4 } from "fs";
 import { homedir as homedir3 } from "os";
 import { basename as basename3, isAbsolute, join as join5, relative, resolve } from "path";
 var TODOS_TASK_WORKER_VERIFIER_TEMPLATE_ID = "todos-task-worker-verifier";
@@ -6102,6 +6199,11 @@ var TEMPLATE_SUMMARIES = [
     ]
   }
 ];
+var CUSTOM_TEMPLATE_ID_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$/;
+var CUSTOM_TEMPLATE_VARIABLE_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+var CUSTOM_TEMPLATE_VARIABLE_TYPES = new Set(["string", "number", "boolean", "json", "string[]"]);
+var CUSTOM_TEMPLATE_PLACEHOLDER = /\$\{([a-zA-Z_][a-zA-Z0-9_]*)\}/g;
+var CUSTOM_TEMPLATE_EXACT_PLACEHOLDER = /^\$\{([a-zA-Z_][a-zA-Z0-9_]*)\}$/;
 function compactJson(value) {
   return JSON.stringify(value);
 }
@@ -6379,11 +6481,310 @@ function workflowStepsWithWorktree(plan, steps) {
     ...steps.map((step) => step.id === "worker" ? { ...step, dependsOn: [...new Set([...step.dependsOn ?? [], plan.prepareStep.id])] } : step)
   ];
 }
-function listLoopTemplates() {
-  return TEMPLATE_SUMMARIES.map((template) => structuredClone(template));
+function assertRecord(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error(`${label} must be an object`);
+}
+function assertTemplateString(value, label) {
+  if (typeof value !== "string" || value.trim() === "")
+    throw new Error(`${label} must be a non-empty string`);
+  return value.trim();
+}
+function assertTemplateKind(value, label) {
+  const kind = assertTemplateString(value, label);
+  if (kind !== "workflow")
+    throw new Error(`${label} must be workflow; custom loop templates are not supported yet`);
+  return kind;
+}
+function customLoopTemplatesDir() {
+  return join5(dataDir(), "templates");
+}
+function ensureCustomLoopTemplatesDir() {
+  const dir = customLoopTemplatesDir();
+  mkdirSync6(dir, { recursive: true, mode: 448 });
+  return dir;
+}
+function loopTemplatesDir() {
+  return customLoopTemplatesDir();
+}
+function builtinLoopTemplates() {
+  return TEMPLATE_SUMMARIES.map((template) => ({ ...structuredClone(template), source: "builtin" }));
+}
+function getBuiltinLoopTemplate(id) {
+  return builtinLoopTemplates().find((template) => template.id === id || template.name === id);
+}
+function builtinTemplateKeys() {
+  const keys = new Set;
+  for (const template of TEMPLATE_SUMMARIES) {
+    keys.add(template.id);
+    keys.add(template.name);
+  }
+  return keys;
+}
+function validateCustomTemplateId(id, label) {
+  if (!CUSTOM_TEMPLATE_ID_PATTERN.test(id)) {
+    throw new Error(`${label} must match ${CUSTOM_TEMPLATE_ID_PATTERN.source}`);
+  }
 }
-function getLoopTemplate(id) {
-  return listLoopTemplates().find((template) => template.id === id || template.name === id);
+function validateCustomTemplateVariables(value, label) {
+  if (value === undefined)
+    return [];
+  if (!Array.isArray(value))
+    throw new Error(`${label} must be an array`);
+  const seen = new Set;
+  return value.map((entry, index) => {
+    const entryLabel = `${label}[${index}]`;
+    assertRecord(entry, entryLabel);
+    const name = assertTemplateString(entry.name, `${entryLabel}.name`);
+    if (!CUSTOM_TEMPLATE_VARIABLE_PATTERN.test(name)) {
+      throw new Error(`${entryLabel}.name must match ${CUSTOM_TEMPLATE_VARIABLE_PATTERN.source}`);
+    }
+    if (seen.has(name))
+      throw new Error(`duplicate custom template variable: ${name}`);
+    seen.add(name);
+    const description = entry.description === undefined ? undefined : assertTemplateString(entry.description, `${entryLabel}.description`);
+    const defaultValue = entry.default === undefined ? undefined : assertTemplateString(entry.default, `${entryLabel}.default`);
+    const type = entry.type === undefined ? undefined : assertTemplateString(entry.type, `${entryLabel}.type`);
+    if (type && !CUSTOM_TEMPLATE_VARIABLE_TYPES.has(type)) {
+      throw new Error(`${entryLabel}.type must be one of ${[...CUSTOM_TEMPLATE_VARIABLE_TYPES].join(", ")}`);
+    }
+    if (defaultValue === "danger-full-access") {
+      throw new Error(`${entryLabel}.default cannot be danger-full-access in a custom template`);
+    }
+    return {
+      name,
+      description,
+      required: entry.required === undefined ? undefined : Boolean(entry.required),
+      default: defaultValue,
+      type
+    };
+  });
+}
+function assertNoDangerFullAccess(value, label) {
+  if (!value || typeof value !== "object")
+    return;
+  if (Array.isArray(value)) {
+    value.forEach((entry, index) => assertNoDangerFullAccess(entry, `${label}[${index}]`));
+    return;
+  }
+  for (const [key, entry] of Object.entries(value)) {
+    if (key === "sandbox" && entry === "danger-full-access") {
+      throw new Error(`${label}.${key} uses danger-full-access; custom templates must not request danger-full-access`);
+    }
+    assertNoDangerFullAccess(entry, `${label}.${key}`);
+  }
+}
+function customTemplateDefinitionFromJson(value, sourcePath) {
+  assertRecord(value, sourcePath);
+  const id = assertTemplateString(value.id, `${sourcePath}.id`);
+  validateCustomTemplateId(id, `${sourcePath}.id`);
+  const name = assertTemplateString(value.name, `${sourcePath}.name`);
+  const description = assertTemplateString(value.description, `${sourcePath}.description`);
+  const kind = assertTemplateKind(value.kind ?? "workflow", `${sourcePath}.kind`);
+  const variables = validateCustomTemplateVariables(value.variables, `${sourcePath}.variables`);
+  if (value.workflow === undefined)
+    throw new Error(`${sourcePath}.workflow is required`);
+  assertRecord(value.workflow, `${sourcePath}.workflow`);
+  assertNoDangerFullAccess(value.workflow, `${sourcePath}.workflow`);
+  return { id, name, description, kind, variables, workflow: value.workflow };
+}
+function customTemplateSummary(definition, sourcePath) {
+  return {
+    id: definition.id,
+    name: definition.name,
+    description: definition.description,
+    kind: definition.kind,
+    variables: structuredClone(definition.variables),
+    source: "custom",
+    sourcePath
+  };
+}
+function readCustomTemplateFile(file) {
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync2(file, "utf8"));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`failed to read custom template ${file}: ${message}`);
+  }
+  const definition = customTemplateDefinitionFromJson(parsed, file);
+  return { definition, summary: customTemplateSummary(definition, file), path: file };
+}
+function assertNoTemplateCollisions(entries) {
+  const builtinKeys = builtinTemplateKeys();
+  const seen = new Map;
+  for (const entry of entries) {
+    for (const key of [entry.definition.id, entry.definition.name]) {
+      if (builtinKeys.has(key)) {
+        throw new Error(`custom template ${entry.definition.id} collides with built-in template key ${key}; choose a different id or name`);
+      }
+      const existing = seen.get(key);
+      if (existing) {
+        throw new Error(`custom template ${entry.definition.id} collides with ${existing} on key ${key}`);
+      }
+      seen.set(key, entry.definition.id);
+    }
+  }
+}
+function loadCustomLoopTemplates() {
+  const dir = customLoopTemplatesDir();
+  if (!existsSync4(dir))
+    return [];
+  const entries = readdirSync(dir, { withFileTypes: true }).filter((entry) => entry.name.endsWith(".json")).sort((left, right) => left.name.localeCompare(right.name)).map((entry) => {
+    const file = join5(dir, entry.name);
+    if (entry.isSymbolicLink())
+      throw new Error(`refusing symlinked custom template file: ${file}`);
+    if (!entry.isFile())
+      throw new Error(`custom template registry entry is not a regular file: ${file}`);
+    return readCustomTemplateFile(file);
+  });
+  assertNoTemplateCollisions(entries);
+  return entries;
+}
+function getCustomLoopTemplate(id) {
+  return loadCustomLoopTemplates().find((template) => template.definition.id === id || template.definition.name === id);
+}
+function coerceCustomTemplateValue(raw, type, label) {
+  const normalizedType = type ?? "string";
+  if (normalizedType === "string")
+    return String(raw);
+  if (normalizedType === "number") {
+    const value = typeof raw === "number" ? raw : Number(String(raw));
+    if (!Number.isFinite(value))
+      throw new Error(`${label} must be a finite number`);
+    return value;
+  }
+  if (normalizedType === "boolean") {
+    if (typeof raw === "boolean")
+      return raw;
+    const normalized = String(raw).trim().toLowerCase();
+    if (["1", "true", "yes", "on"].includes(normalized))
+      return true;
+    if (["0", "false", "no", "off"].includes(normalized))
+      return false;
+    throw new Error(`${label} must be a boolean`);
+  }
+  if (normalizedType === "json") {
+    if (typeof raw !== "string")
+      return raw;
+    try {
+      return JSON.parse(raw);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`${label} must be valid JSON: ${message}`);
+    }
+  }
+  if (normalizedType === "string[]") {
+    if (Array.isArray(raw))
+      return raw.map((entry) => String(entry));
+    return String(raw).split(",").map((entry) => entry.trim()).filter(Boolean);
+  }
+  return String(raw);
+}
+function customTemplateValues(definition, values) {
+  const variablesByName = new Map(definition.variables.map((variable) => [variable.name, variable]));
+  for (const [name, value] of Object.entries(values)) {
+    if (value !== undefined && !variablesByName.has(name)) {
+      throw new Error(`unknown variable for custom template ${definition.id}: ${name}`);
+    }
+  }
+  const rendered = {};
+  for (const variable of definition.variables) {
+    const raw = values[variable.name] ?? variable.default;
+    if (raw === undefined || raw === "") {
+      if (variable.required)
+        throw new Error(`${variable.name} is required`);
+      continue;
+    }
+    rendered[variable.name] = coerceCustomTemplateValue(raw, variable.type, variable.name);
+  }
+  return rendered;
+}
+function customTemplateValueForPlaceholder(values, name, templateId) {
+  if (!(name in values))
+    throw new Error(`custom template ${templateId} requires variable ${name}`);
+  return values[name];
+}
+function stringifyCustomTemplateValue(value, name) {
+  if (typeof value === "string")
+    return value;
+  if (typeof value === "number" || typeof value === "boolean")
+    return String(value);
+  if (value === null)
+    return "null";
+  if (Array.isArray(value) || typeof value === "object")
+    return JSON.stringify(value);
+  throw new Error(`custom template variable ${name} cannot be rendered as a string`);
+}
+function renderCustomTemplateNode(value, values, templateId) {
+  if (typeof value === "string") {
+    const exact = CUSTOM_TEMPLATE_EXACT_PLACEHOLDER.exec(value);
+    if (exact)
+      return customTemplateValueForPlaceholder(values, exact[1], templateId);
+    return value.replace(CUSTOM_TEMPLATE_PLACEHOLDER, (_match, name) => stringifyCustomTemplateValue(customTemplateValueForPlaceholder(values, name, templateId), name));
+  }
+  if (Array.isArray(value))
+    return value.map((entry) => renderCustomTemplateNode(entry, values, templateId));
+  if (!value || typeof value !== "object")
+    return value;
+  return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, renderCustomTemplateNode(entry, values, templateId)]));
+}
+function renderCustomLoopTemplate(entry, values) {
+  const renderedValues = customTemplateValues(entry.definition, values);
+  const rendered = renderCustomTemplateNode(entry.definition.workflow, renderedValues, entry.definition.id);
+  assertNoDangerFullAccess(rendered, `custom template ${entry.definition.id}.workflow`);
+  return workflowBodyFromJson(rendered);
+}
+function validateCustomLoopTemplateFile(file) {
+  const entry = readCustomTemplateFile(resolve(file));
+  assertNoTemplateCollisions([entry]);
+  return structuredClone(entry.summary);
+}
+function importCustomLoopTemplate(file, opts = {}) {
+  const source = resolve(file);
+  const entry = readCustomTemplateFile(source);
+  assertNoTemplateCollisions([entry]);
+  const dir = ensureCustomLoopTemplatesDir();
+  const destination = join5(dir, `${entry.definition.id}.json`);
+  const replaced = existsSync4(destination);
+  if (replaced) {
+    const stat = lstatSync(destination);
+    if (!stat.isFile() || stat.isSymbolicLink())
+      throw new Error(`refusing to replace non-regular custom template file: ${destination}`);
+    if (!opts.replace)
+      throw new Error(`custom template already exists: ${entry.definition.id}; use --replace to overwrite it`);
+  }
+  writeFileSync4(destination, `${JSON.stringify(entry.definition, null, 2)}
+`, { mode: 384 });
+  const imported = readCustomTemplateFile(destination);
+  return { template: structuredClone(imported.summary), path: destination, replaced };
+}
+function validateLoopTemplateRegistry(opts = {}) {
+  return {
+    ok: true,
+    templates: listLoopTemplates(opts),
+    customDir: customLoopTemplatesDir()
+  };
+}
+function listLoopTemplates(opts = {}) {
+  const source = opts.source ?? "all";
+  const templates = [];
+  if (source !== "custom")
+    templates.push(...builtinLoopTemplates());
+  if (source !== "builtin")
+    templates.push(...loadCustomLoopTemplates().map((entry) => structuredClone(entry.summary)));
+  return templates;
+}
+function getLoopTemplate(id, opts = {}) {
+  const source = opts.source ?? "all";
+  if (source !== "custom") {
+    const builtin = getBuiltinLoopTemplate(id);
+    if (builtin)
+      return builtin;
+    if (source === "builtin")
+      return;
+  }
+  return getCustomLoopTemplate(id)?.summary;
 }
 function renderTodosTaskWorkerVerifierWorkflow(input) {
   if (!input.taskId?.trim())
@@ -6728,7 +7129,7 @@ function renderDeterministicCheckCreateTaskWorkflow(values) {
     ]
   };
 }
-function renderLoopTemplate(id, values) {
+function renderBuiltinLoopTemplate(id, values) {
   if (id === DETERMINISTIC_CHECK_CREATE_TASK_TEMPLATE_ID) {
     return renderDeterministicCheckCreateTaskWorkflow(values);
   }
@@ -6842,6 +7243,20 @@ function booleanVar(value) {
 function accountPoolVar(value, tool) {
   return listVar(value)?.map((profile) => ({ profile, tool }));
 }
+function renderLoopTemplate(id, values, opts = {}) {
+  const source = opts.source ?? "all";
+  if (source !== "custom") {
+    const builtin = getBuiltinLoopTemplate(id);
+    if (builtin)
+      return renderBuiltinLoopTemplate(builtin.id, values);
+    if (source === "builtin")
+      throw new Error(`unknown built-in template: ${id}`);
+  }
+  const custom = getCustomLoopTemplate(id);
+  if (custom)
+    return renderCustomLoopTemplate(custom, values);
+  throw new Error(`unknown template: ${id}`);
+}
 
 // src/cli/index.ts
 var program = new Command;
@@ -6961,6 +7376,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;
@@ -7125,7 +7548,7 @@ function runLocalCommandWithStdoutFile(command, args, opts = {}) {
     return {
       ok: result.status === 0,
       status: result.status,
-      stdout: readFileSync2(stdoutPath, "utf8"),
+      stdout: readFileSync3(stdoutPath, "utf8"),
       stderr: typeof result.stderr === "string" ? result.stderr : result.stderr?.toString() || "",
       error: result.error ? String(result.error.message || result.error) : ""
     };
@@ -7147,11 +7570,11 @@ function ensureTodosTaskList(project, slug, name, description) {
 function backupLoopsDatabase(reason) {
   const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\..+$/, "Z");
   const backupDir = join6(dataDir(), "backups");
-  mkdirSync6(backupDir, { recursive: true, mode: 448 });
+  mkdirSync7(backupDir, { recursive: true, mode: 448 });
   const backupPath = join6(backupDir, `loops.db.bak-${reason}-${stamp}`);
   const db = new Database2(dbPath(), { readonly: true });
   try {
-    writeFileSync4(backupPath, db.serialize(), { mode: 384 });
+    writeFileSync5(backupPath, db.serialize(), { mode: 384 });
   } finally {
     db.close();
   }
@@ -7169,7 +7592,7 @@ function readRouteCursors() {
   if (!existsSync5(path))
     return {};
   try {
-    const parsed = JSON.parse(readFileSync2(path, "utf8"));
+    const parsed = JSON.parse(readFileSync3(path, "utf8"));
     return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
   } catch {
     return {};
@@ -7180,15 +7603,15 @@ function writeRouteCursor(key, lastFingerprint) {
     return;
   const cursors = readRouteCursors();
   cursors[key] = { lastFingerprint, updatedAt: new Date().toISOString() };
-  writeFileSync4(routeCursorsPath(), JSON.stringify(cursors, null, 2), { mode: 384 });
+  writeFileSync5(routeCursorsPath(), JSON.stringify(cursors, null, 2), { mode: 384 });
 }
 function writeRouteEvidence(kind, value, evidenceDir) {
   if (!evidenceDir)
     return;
-  mkdirSync6(evidenceDir, { recursive: true, mode: 448 });
+  mkdirSync7(evidenceDir, { recursive: true, mode: 448 });
   const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\./g, "");
   const evidencePath = join6(evidenceDir, `${kind}-${stamp}-${randomUUID().slice(0, 8)}.json`);
-  writeFileSync4(evidencePath, JSON.stringify(value, null, 2), { mode: 384, flag: "wx" });
+  writeFileSync5(evidencePath, JSON.stringify(value, null, 2), { mode: 384, flag: "wx" });
   return evidencePath;
 }
 function selectRouteItems(items, maxActions, cursorKey, fingerprintOf) {
@@ -7442,6 +7865,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) {
@@ -7564,7 +8004,7 @@ function routeThrottleDryRunPreview(args) {
   };
 }
 async function readEventEnvelopeInput(opts = {}) {
-  const raw = opts.eventJson ?? (opts.eventFile ? readFileSync2(opts.eventFile, "utf8") : process.env.HASNA_EVENT_JSON || await Bun.stdin.text());
+  const raw = opts.eventJson ?? (opts.eventFile ? readFileSync3(opts.eventFile, "utf8") : process.env.HASNA_EVENT_JSON || await Bun.stdin.text());
   const event = JSON.parse(raw);
   if (!event || typeof event !== "object" || Array.isArray(event))
     throw new Error("event JSON must be an object");
@@ -8401,8 +8841,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,30 +8912,108 @@ 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}`);
 }
-templates.command("list").alias("ls").description("list built-in OpenLoops templates").action(() => {
-  const values = listLoopTemplates();
+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 templateSource(value) {
+  const source = value ?? "all";
+  if (source === "all" || source === "builtin" || source === "custom")
+    return source;
+  throw new Error("--source must be all, builtin, or custom");
+}
+function addTemplateSourceOption(command, defaultValue = "all") {
+  return command.option("--source <source>", "template source: all, builtin, or custom", defaultValue);
+}
+function printTemplateDetails(template) {
+  console.log(`${template.id} (${template.kind})`);
+  console.log(template.name);
+  if (template.source)
+    console.log(`source: ${template.source}${template.sourcePath ? ` (${template.sourcePath})` : ""}`);
+  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 OpenLoops templates").option("--source <source>", "template source: all, builtin, or custom", "all").action((opts) => {
+  const values = listLoopTemplates({ source: templateSource(opts.source) });
   if (isJson())
     print(values);
   else {
     for (const template of values) {
-      console.log(`${template.id}	${template.kind}	${template.description}`);
+      console.log(`${template.id}	${template.source ?? "builtin"}	${template.kind}	${template.description}`);
     }
   }
 });
-templates.command("show <id>").description("show a built-in template").action((id) => {
-  const template = getLoopTemplate(id);
+templates.command("import <file>").alias("add").description("import a custom workflow template JSON file into the local registry").option("--replace", "replace an existing custom template with the same id").action((file, opts) => {
+  const result = importCustomLoopTemplate(file, { replace: Boolean(opts.replace) });
+  print(result, `${result.replaced ? "replaced" : "imported"} custom template ${result.template.id} -> ${result.path}`);
+});
+templates.command("validate [file]").description("validate a custom template JSON file or the local template registry").option("--source <source>", "template source to validate when no file is given: all, builtin, or custom", "all").action((file, opts) => {
+  if (file) {
+    const template = validateCustomLoopTemplateFile(file);
+    print({ ok: true, template, customDir: loopTemplatesDir() }, `valid custom template ${template.id}`);
+    return;
+  }
+  const result = validateLoopTemplateRegistry({ source: templateSource(opts.source) });
+  print(result, `valid template registry (${result.templates.length} templates) customDir=${result.customDir}`);
+});
+addTemplateSourceOption(templates.command("show <id>").description("show a template")).action((id, opts) => {
+  const template = getLoopTemplate(id, { source: templateSource(opts.source) });
   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));
+addTemplateSourceOption(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), { source: templateSource(opts.source) });
   print(workflow, JSON.stringify(workflow, null, 2));
 });
-templates.command("create-workflow <id>").description("render and store a template as a workflow").option("--var <key=value>", "template variable; may be repeated", collectValues, []).action((id, opts) => {
+addTemplateSourceOption(templates.command("create-workflow <id>").description("render and store a template as a workflow").option("--var <key=value>", "template variable; may be repeated", collectValues, [])).action((id, opts) => {
   const store = new Store;
   try {
-    const body = renderLoopTemplate(id, parseVars(opts.var));
+    const body = renderLoopTemplate(id, parseVars(opts.var), { source: templateSource(opts.source) });
     const workflow = store.createWorkflow(body);
     print(publicWorkflow(workflow), `created workflow ${workflow.id} (${workflow.name}) steps=${workflow.steps.length}`);
   } finally {
@@ -8658,7 +9185,7 @@ machines.command("show <id>").description("resolve a machine assignment").action
   print(resolveLoopMachine(id));
 });
 workflows.command("validate <file>").description("validate a workflow JSON file without storing or running it").option("--name <name>", "override workflow name from the file").option("--preflight", "also check account env and target executables").action((file, opts) => {
-  const body = workflowBodyFromJson(JSON.parse(readFileSync2(file, "utf8")), opts.name);
+  const body = workflowBodyFromJson(JSON.parse(readFileSync3(file, "utf8")), opts.name);
   const workflow = workflowSpecForPreflight(body);
   const preflight = opts.preflight ? preflightWorkflow(workflow) : undefined;
   print({ valid: true, workflow: publicWorkflow(workflow), preflight }, `valid workflow ${workflow.name} steps=${workflow.steps.length}`);
@@ -8666,7 +9193,7 @@ workflows.command("validate <file>").description("validate a workflow JSON file
 workflows.command("create <file>").description("validate and store a workflow JSON file").option("--name <name>", "override workflow name from the file").option("--preflight", "also check account env and target executables before storing").action((file, opts) => {
   const store = new Store;
   try {
-    const body = workflowBodyFromJson(JSON.parse(readFileSync2(file, "utf8")), opts.name);
+    const body = workflowBodyFromJson(JSON.parse(readFileSync3(file, "utf8")), opts.name);
     const preflight = opts.preflight ? preflightStoredWorkflow(workflowSpecForPreflight(body, "creation-preflight"), { name: body.name, type: "workflow" }, {}) : undefined;
     const workflow = store.createWorkflow(body);
     if (preflight !== undefined)
@@ -8677,10 +9204,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 +9219,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();
   }
@@ -9294,6 +9827,43 @@ hygiene.command("route-tasks").description("upsert deduped todos tasks for hygie
 program.command("pause <idOrName>").action((idOrName) => updateStatus(idOrName, "paused"));
 program.command("resume <idOrName>").action((idOrName) => updateStatus(idOrName, "active"));
 program.command("stop <idOrName>").action((idOrName) => updateStatus(idOrName, "stopped"));
+program.command("rename <idOrName> <newName>").description("rename a loop without changing its id, schedule, runs, or history").action((idOrName, newName) => {
+  const store = new Store;
+  try {
+    const loop = store.requireLoop(idOrName);
+    const oldName = loop.name;
+    const trimmed = String(newName).trim();
+    if (!trimmed)
+      throw new Error("loop name must not be empty");
+    const existing = store.findLoopByName(trimmed);
+    if (existing && existing.id !== loop.id) {
+      throw new Error(`loop name already exists: ${trimmed} (${existing.id})`);
+    }
+    if (trimmed === oldName) {
+      print({
+        changed: false,
+        id: loop.id,
+        oldName,
+        newName: oldName,
+        loop: publicLoop(loop)
+      }, `${loop.id} unchanged (${oldName})`);
+      return;
+    }
+    const backupPath = backupLoopsDatabase("rename");
+    const renamed = store.renameLoop(loop.id, trimmed);
+    print({
+      changed: true,
+      id: renamed.id,
+      oldName,
+      newName: renamed.name,
+      backupPath,
+      loop: publicLoop(renamed)
+    }, `${renamed.id} renamed ${oldName} -> ${renamed.name}
+backup=${backupPath}`);
+  } finally {
+    store.close();
+  }
+});
 function updateStatus(idOrName, status) {
   const store = new Store;
   try {
@@ -9432,7 +10002,7 @@ daemon.command("logs").option("-n, --lines <n>", "lines", "80").action((opts) =>
     console.log("");
     return;
   }
-  const lines = readFileSync2(path, "utf8").trimEnd().split(`
+  const lines = readFileSync3(path, "utf8").trimEnd().split(`
 `);
   console.log(lines.slice(-Number(opts.lines)).join(`
 `));