@hasna/loops 0.3.49 → 0.3.51

package/README.md

@@ -251,6 +251,67 @@ loops templates render deterministic-check-create-task \
   --var checkCommand='your deterministic check and todos upsert command'
 ```
 
+Custom reusable workflow templates live under the OpenLoops app data directory:
+`~/.hasna/loops/templates` by default, or `$LOOPS_DATA_DIR/templates` when
+`LOOPS_DATA_DIR` is set. Store templates as declarative JSON files; listing,
+showing, and rendering templates never executes workflow steps or mutates the
+registry.
+
+```json
+{
+  "id": "custom-report",
+  "name": "Custom Report",
+  "description": "Run a custom report workflow from the local template registry.",
+  "kind": "workflow",
+  "variables": [
+    { "name": "objective", "required": true, "description": "Report objective." },
+    { "name": "projectPath", "required": true, "description": "Working directory." },
+    { "name": "timeoutMs", "default": "300000", "type": "number" }
+  ],
+  "workflow": {
+    "name": "custom-report-${objective}",
+    "steps": [
+      {
+        "id": "worker",
+        "target": {
+          "type": "agent",
+          "provider": "codewith",
+          "prompt": "/goal ${objective}\nProduce the requested report only.",
+          "cwd": "${projectPath}",
+          "configIsolation": "safe",
+          "permissionMode": "bypass",
+          "sandbox": "workspace-write",
+          "timeoutMs": "${timeoutMs}"
+        },
+        "timeoutMs": "${timeoutMs}"
+      }
+    ]
+  }
+}
+```
+
+```bash
+loops templates validate ./custom-report.json
+loops templates import ./custom-report.json
+loops templates list --source custom
+loops templates show custom-report
+loops templates render custom-report \
+  --var objective="Check docs drift" \
+  --var projectPath=/path/to/repo
+loops templates create-workflow custom-report \
+  --var objective="Check docs drift" \
+  --var projectPath=/path/to/repo
+```
+
+Use `--source builtin`, `--source custom`, or `--source all` on
+`list`, `show`, `render`, and `create-workflow` when automation needs an
+explicit source. Custom template ids and names cannot override built-ins.
+Custom templates fail closed for `danger-full-access`, dangerous passthrough
+arguments, and implicit Codewith/Codex full-access defaults. If a custom
+Codewith/Codex template uses `permissionMode: "bypass"`, it must also set
+`sandbox` to `workspace-write` or `read-only`. Use built-in templates with
+explicit break-glass handling for emergency workflows that need full access.
+
 For event-driven task automation, `loops events handle todos-task` reads a
 Hasna event envelope from stdin or `HASNA_EVENT_JSON`, records a
 `WorkflowInvocation`, upserts an admission work item, and admits that work item
@@ -421,6 +482,7 @@ loops runs <id-or-name>
 loops pause <id-or-name>
 loops resume <id-or-name>
 loops stop <id-or-name>
+loops rename <id-or-name> <new-name>
 loops archive <id-or-name>
 loops unarchive <id-or-name>
 loops remove <id-or-name>
@@ -468,6 +530,20 @@ package-managed cursor under `<LOOPS_DATA_DIR>/route-cursors.json` so bounded
 `--max-actions` runs advance through all findings over repeated scheduled runs
 instead of reprocessing only the first batch.
 
+Use `loops rename` for deliberate operator naming changes that should not be
+encoded as automatic hygiene policy:
+
+```bash
+loops rename machine-todos-drain-oss-repos-strict-5m machine-todos-drain-oss-repos
+loops --json rename <loop-id> machine-ops-loop-health-route-tasks
+```
+
+`rename` preserves the loop id, schedule, run history, archive state, and target
+configuration. It rejects empty or duplicate names and writes a SQLite backup
+under `<LOOPS_DATA_DIR>/backups` before mutating the loop row. Keep cadence in
+schedule metadata and operator tables rather than in the loop name when the name
+is meant for humans.
+
 Archive loops when retiring old automation but preserving history:
 
 ```bash

package/dist/cli/index.js

@@ -2855,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";
@@ -5908,7 +5908,7 @@ function buildScriptInventoryReport(store, opts = {}) {
 // package.json
 var package_default = {
   name: "@hasna/loops",
-  version: "0.3.49",
+  version: "0.3.51",
   description: "Persistent local loop and workflow runner for deterministic commands and headless AI coding agents",
   type: "module",
   main: "dist/index.js",
@@ -5998,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";
@@ -6199,6 +6199,16 @@ 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_]*)\}$/;
+var CUSTOM_TEMPLATE_DANGEROUS_ARG_PATTERNS = [
+  "danger-full-access",
+  "dangerously-bypass",
+  "dangerously-skip"
+];
 function compactJson(value) {
   return JSON.stringify(value);
 }
@@ -6476,11 +6486,350 @@ 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 optionalTemplateBoolean(value, label) {
+  if (value === undefined)
+    return;
+  if (typeof value !== "boolean")
+    throw new Error(`${label} must be a boolean`);
+  return value;
+}
+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 && CUSTOM_TEMPLATE_DANGEROUS_ARG_PATTERNS.some((pattern) => defaultValue.includes(pattern))) {
+      throw new Error(`${entryLabel}.default cannot contain dangerous sandbox or bypass flags in a custom template`);
+    }
+    return {
+      name,
+      description,
+      required: optionalTemplateBoolean(entry.required, `${entryLabel}.required`),
+      default: defaultValue,
+      type
+    };
+  });
+}
+function hasDangerousArg(value) {
+  return CUSTOM_TEMPLATE_DANGEROUS_ARG_PATTERNS.some((pattern) => value.includes(pattern));
+}
+function assertNoDangerousCustomTemplateScalars(value, label) {
+  if (typeof value === "string") {
+    if (hasDangerousArg(value)) {
+      throw new Error(`${label} contains a dangerous sandbox or bypass flag; custom templates must not request danger-full-access`);
+    }
+    return;
+  }
+  if (!value || typeof value !== "object")
+    return;
+  if (Array.isArray(value)) {
+    value.forEach((entry, index) => assertNoDangerousCustomTemplateScalars(entry, `${label}[${index}]`));
+    return;
+  }
+  for (const [key, entry] of Object.entries(value)) {
+    assertNoDangerousCustomTemplateScalars(entry, `${label}.${key}`);
+  }
 }
-function getLoopTemplate(id) {
-  return listLoopTemplates().find((template) => template.id === id || template.name === id);
+function assertNoImplicitDangerFullAccess(value, label) {
+  if (!value || typeof value !== "object")
+    return;
+  if (Array.isArray(value)) {
+    value.forEach((entry, index) => assertNoImplicitDangerFullAccess(entry, `${label}[${index}]`));
+    return;
+  }
+  const object = value;
+  if (object.type === "agent" && (object.provider === "codewith" || object.provider === "codex") && object.permissionMode === "bypass" && object.sandbox === undefined) {
+    throw new Error(`${label} uses permissionMode=bypass for ${object.provider} without an explicit sandbox; set sandbox=workspace-write or read-only`);
+  }
+  for (const [key, entry] of Object.entries(object)) {
+    assertNoImplicitDangerFullAccess(entry, `${label}.${key}`);
+  }
+}
+function assertCustomTemplateSafety(value, label) {
+  assertNoDangerousCustomTemplateScalars(value, label);
+  assertNoImplicitDangerFullAccess(value, label);
+}
+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`);
+  assertCustomTemplateSafety(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 loadCustomLoopTemplatesRaw() {
+  const dir = customLoopTemplatesDir();
+  if (!existsSync4(dir))
+    return [];
+  return 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);
+  });
+}
+function loadCustomLoopTemplates() {
+  const entries = loadCustomLoopTemplatesRaw();
+  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);
+  assertCustomTemplateSafety(rendered, `custom template ${entry.definition.id}.workflow`);
+  const workflow = workflowBodyFromJson(rendered);
+  assertCustomTemplateSafety(workflow, `custom template ${entry.definition.id}.workflow`);
+  return workflow;
+}
+function validateCustomLoopTemplateFile(file) {
+  const source = resolve(file);
+  const entry = readCustomTemplateFile(source);
+  const existing = loadCustomLoopTemplatesRaw().filter((template) => resolve(template.path) !== source);
+  assertNoTemplateCollisions([...existing, entry]);
+  return structuredClone(entry.summary);
+}
+function importCustomLoopTemplate(file, opts = {}) {
+  const source = resolve(file);
+  const entry = readCustomTemplateFile(source);
+  const dir = ensureCustomLoopTemplatesDir();
+  const destination = join5(dir, `${entry.definition.id}.json`);
+  const replaced = existsSync4(destination);
+  const existing = loadCustomLoopTemplatesRaw().filter((template) => resolve(template.path) !== resolve(destination));
+  assertNoTemplateCollisions([...existing, { ...entry, path: destination, summary: customTemplateSummary(entry.definition, 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())
@@ -6825,7 +7174,7 @@ function renderDeterministicCheckCreateTaskWorkflow(values) {
     ]
   };
 }
-function renderLoopTemplate(id, values) {
+function renderBuiltinLoopTemplate(id, values) {
   if (id === DETERMINISTIC_CHECK_CREATE_TASK_TEMPLATE_ID) {
     return renderDeterministicCheckCreateTaskWorkflow(values);
   }
@@ -6939,6 +7288,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;
@@ -7230,7 +7593,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) : ""
     };
@@ -7252,11 +7615,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();
   }
@@ -7274,7 +7637,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 {};
@@ -7285,15 +7648,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) {
@@ -7686,7 +8049,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");
@@ -8599,9 +8962,20 @@ function formatTemplateVariable(template, 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("");
@@ -8645,18 +9019,31 @@ function printWorkflowListWarning(args) {
   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();
+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}`);
   if (isJson())
@@ -8664,14 +9051,14 @@ templates.command("show <id>").description("show a built-in template").action((i
   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 {
@@ -8843,7 +9230,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}`);
@@ -8851,7 +9238,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)
@@ -9485,6 +9872,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 {
@@ -9623,7 +10047,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(`
 `));

package/dist/daemon/index.js

@@ -5240,7 +5240,7 @@ function enableStartup(result) {
 // package.json
 var package_default = {
   name: "@hasna/loops",
-  version: "0.3.49",
+  version: "0.3.51",
   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

@@ -4977,7 +4977,7 @@ function openAutomationsRuntimeBinding(overrides = {}) {
 }
 // src/lib/templates.ts
 import { execFileSync } from "child_process";
-import { existsSync as existsSync3 } from "fs";
+import { existsSync as existsSync3, lstatSync, mkdirSync as mkdirSync4, readdirSync, readFileSync, writeFileSync as writeFileSync2 } from "fs";
 import { homedir as homedir3 } from "os";
 import { basename as basename2, isAbsolute, join as join5, relative, resolve } from "path";
 var TODOS_TASK_WORKER_VERIFIER_TEMPLATE_ID = "todos-task-worker-verifier";
@@ -5178,6 +5178,16 @@ 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_]*)\}$/;
+var CUSTOM_TEMPLATE_DANGEROUS_ARG_PATTERNS = [
+  "danger-full-access",
+  "dangerously-bypass",
+  "dangerously-skip"
+];
 function compactJson(value) {
   return JSON.stringify(value);
 }
@@ -5455,11 +5465,350 @@ 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();
+  mkdirSync4(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 optionalTemplateBoolean(value, label) {
+  if (value === undefined)
+    return;
+  if (typeof value !== "boolean")
+    throw new Error(`${label} must be a boolean`);
+  return value;
+}
+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 && CUSTOM_TEMPLATE_DANGEROUS_ARG_PATTERNS.some((pattern) => defaultValue.includes(pattern))) {
+      throw new Error(`${entryLabel}.default cannot contain dangerous sandbox or bypass flags in a custom template`);
+    }
+    return {
+      name,
+      description,
+      required: optionalTemplateBoolean(entry.required, `${entryLabel}.required`),
+      default: defaultValue,
+      type
+    };
+  });
+}
+function hasDangerousArg(value) {
+  return CUSTOM_TEMPLATE_DANGEROUS_ARG_PATTERNS.some((pattern) => value.includes(pattern));
+}
+function assertNoDangerousCustomTemplateScalars(value, label) {
+  if (typeof value === "string") {
+    if (hasDangerousArg(value)) {
+      throw new Error(`${label} contains a dangerous sandbox or bypass flag; custom templates must not request danger-full-access`);
+    }
+    return;
+  }
+  if (!value || typeof value !== "object")
+    return;
+  if (Array.isArray(value)) {
+    value.forEach((entry, index) => assertNoDangerousCustomTemplateScalars(entry, `${label}[${index}]`));
+    return;
+  }
+  for (const [key, entry] of Object.entries(value)) {
+    assertNoDangerousCustomTemplateScalars(entry, `${label}.${key}`);
+  }
+}
+function assertNoImplicitDangerFullAccess(value, label) {
+  if (!value || typeof value !== "object")
+    return;
+  if (Array.isArray(value)) {
+    value.forEach((entry, index) => assertNoImplicitDangerFullAccess(entry, `${label}[${index}]`));
+    return;
+  }
+  const object = value;
+  if (object.type === "agent" && (object.provider === "codewith" || object.provider === "codex") && object.permissionMode === "bypass" && object.sandbox === undefined) {
+    throw new Error(`${label} uses permissionMode=bypass for ${object.provider} without an explicit sandbox; set sandbox=workspace-write or read-only`);
+  }
+  for (const [key, entry] of Object.entries(object)) {
+    assertNoImplicitDangerFullAccess(entry, `${label}.${key}`);
+  }
+}
+function assertCustomTemplateSafety(value, label) {
+  assertNoDangerousCustomTemplateScalars(value, label);
+  assertNoImplicitDangerFullAccess(value, label);
+}
+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`);
+  assertCustomTemplateSafety(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(readFileSync(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 loadCustomLoopTemplatesRaw() {
+  const dir = customLoopTemplatesDir();
+  if (!existsSync3(dir))
+    return [];
+  return 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);
+  });
+}
+function loadCustomLoopTemplates() {
+  const entries = loadCustomLoopTemplatesRaw();
+  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 getLoopTemplate(id) {
-  return listLoopTemplates().find((template) => template.id === id || template.name === id);
+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);
+  assertCustomTemplateSafety(rendered, `custom template ${entry.definition.id}.workflow`);
+  const workflow = workflowBodyFromJson(rendered);
+  assertCustomTemplateSafety(workflow, `custom template ${entry.definition.id}.workflow`);
+  return workflow;
+}
+function validateCustomLoopTemplateFile(file) {
+  const source = resolve(file);
+  const entry = readCustomTemplateFile(source);
+  const existing = loadCustomLoopTemplatesRaw().filter((template) => resolve(template.path) !== source);
+  assertNoTemplateCollisions([...existing, entry]);
+  return structuredClone(entry.summary);
+}
+function importCustomLoopTemplate(file, opts = {}) {
+  const source = resolve(file);
+  const entry = readCustomTemplateFile(source);
+  const dir = ensureCustomLoopTemplatesDir();
+  const destination = join5(dir, `${entry.definition.id}.json`);
+  const replaced = existsSync3(destination);
+  const existing = loadCustomLoopTemplatesRaw().filter((template) => resolve(template.path) !== resolve(destination));
+  assertNoTemplateCollisions([...existing, { ...entry, path: destination, summary: customTemplateSummary(entry.definition, 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`);
+  }
+  writeFileSync2(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())
@@ -5804,7 +6153,7 @@ function renderDeterministicCheckCreateTaskWorkflow(values) {
     ]
   };
 }
-function renderLoopTemplate(id, values) {
+function renderBuiltinLoopTemplate(id, values) {
   if (id === DETERMINISTIC_CHECK_CREATE_TASK_TEMPLATE_ID) {
     return renderDeterministicCheckCreateTaskWorkflow(values);
   }
@@ -5918,12 +6267,26 @@ 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/lib/doctor.ts
 import { spawnSync as spawnSync3 } from "child_process";
 import { accessSync as accessSync2, constants as constants2 } from "fs";
 
 // src/daemon/control.ts
-import { existsSync as existsSync4, mkdirSync as mkdirSync4, readFileSync, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "fs";
+import { existsSync as existsSync4, mkdirSync as mkdirSync5, readFileSync as readFileSync2, rmSync as rmSync2, writeFileSync as writeFileSync3 } from "fs";
 import { hostname } from "os";
 import { dirname as dirname2 } from "path";
 
@@ -5954,15 +6317,15 @@ function readPid(path = pidFilePath()) {
   if (!existsSync4(path))
     return;
   try {
-    const pid = Number(readFileSync(path, "utf8").trim());
+    const pid = Number(readFileSync2(path, "utf8").trim());
     return Number.isInteger(pid) && pid > 0 ? pid : undefined;
   } catch {
     return;
   }
 }
 function writePid(pid = process.pid, path = pidFilePath()) {
-  mkdirSync4(dirname2(path), { recursive: true, mode: 448 });
-  writeFileSync2(path, String(pid));
+  mkdirSync5(dirname2(path), { recursive: true, mode: 448 });
+  writeFileSync3(path, String(pid));
 }
 function removePid(path = pidFilePath()) {
   rmSync2(path, { force: true });

package/dist/lib/templates.d.ts

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

package/dist/types.d.ts

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

package/docs/USAGE.md

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

package/package.json

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