@hasna/loops 0.3.16 → 0.3.18

package/README.md

@@ -210,7 +210,8 @@ Use `shell: true` only when you intentionally want shell parsing:
 Built-in templates turn common orchestration flows into reusable workflow JSON.
 `todos-task-worker-verifier` performs one todos task and then verifies it.
 `event-worker-verifier` handles any Hasna event envelope and then verifies the
-handling.
+handling. `bounded-agent-worker-verifier` is for recurring bounded agent work:
+one worker runs a narrow objective, then a fresh verifier audits the result.
 
 ```bash
 loops templates list
@@ -230,6 +231,12 @@ loops templates render event-worker-verifier \
   --var eventSource=knowledge \
   --var eventJson='{"id":"<event-id>"}' \
   --var projectPath=/path/to/repo
+loops templates render bounded-agent-worker-verifier \
+  --var objective="Check docs drift and queue tasks for gaps" \
+  --var projectPath=/path/to/repo \
+  --var provider=codewith \
+  --var authProfilePool=account004,account005 \
+  --var sandbox=danger-full-access
 ```
 
 For event-driven task automation, `loops events handle todos-task` reads a
@@ -293,6 +300,28 @@ loops run-now <id-or-name>
 
 Use `--json` for machine-readable output. Prompt bodies and run stdout/stderr are redacted by default in status output. `loops run-now` exits non-zero when the recorded run fails or times out.
 
+## Health And Hygiene
+
+```bash
+loops health --json
+loops expectations <loop-id-or-name> --json
+loops health route-tasks --project ~/.hasna/loops --task-list loop-error-self-heal --max-actions 5
+loops hygiene names --json
+loops hygiene duplicates --json
+loops hygiene scripts --json
+```
+
+`health` and `expectations` classify latest-run failures with stable
+fingerprints and bounded evidence. `health route-tasks` is the explicit
+mutating path: it upserts deduped Todos tasks for failed expectations and marks
+them with `no_tmux_dispatch=true` metadata. Use `--dry-run --json` before
+turning it into a production loop.
+
+`hygiene names` reports canonical `machine-*` or `repo-<name>-*` loop names and
+renames only with `--apply`. `hygiene duplicates` groups loops with the same
+normalized name, cwd, and schedule. `hygiene scripts` inventories loops whose
+command still references `~/.hasna/loops/scripts`.
+
 Archive loops when retiring old automation but preserving history:
 
 ```bash

package/dist/cli/index.js

@@ -1052,6 +1052,30 @@ class Store {
       throw new Error(`loop not found after update: ${id}`);
     return after;
   }
+  renameLoop(id, name, opts = {}) {
+    const current = this.getLoop(id);
+    if (!current)
+      throw new Error(`loop not found: ${id}`);
+    const trimmed = name.trim();
+    if (!trimmed)
+      throw new Error("loop name must not be empty");
+    const updated = (opts.now ?? new Date).toISOString();
+    this.db.query(`UPDATE loops SET name=$name, updated_at=$updated
+         WHERE id=$id
+           AND ($daemonLeaseId IS NULL OR EXISTS (
+             SELECT 1 FROM daemon_lease WHERE id=$daemonLeaseId AND expires_at > $now
+           ))`).run({
+      $id: id,
+      $name: trimmed,
+      $updated: updated,
+      $daemonLeaseId: opts.daemonLeaseId ?? null,
+      $now: updated
+    });
+    const after = this.getLoop(id);
+    if (!after)
+      throw new Error(`loop not found after rename: ${id}`);
+    return after;
+  }
   archiveLoop(idOrName) {
     const loop = this.requireLoop(idOrName);
     if (loop.archivedAt)
@@ -2173,6 +2197,7 @@ class Store {
 // src/cli/index.ts
 import { createHash as createHash2 } from "crypto";
 import { existsSync as existsSync3, readFileSync as readFileSync2 } from "fs";
+import { spawnSync as spawnSync5 } from "child_process";
 import { Command } from "commander";
 
 // src/lib/format.ts
@@ -4615,6 +4640,7 @@ function runDoctor(store) {
 // src/lib/health.ts
 import { createHash } from "crypto";
 var EVIDENCE_CHARS = 2000;
+var FINGERPRINT_EVIDENCE_CHARS = 120;
 var CLASSIFICATIONS = [
   "rate_limit",
   "auth",
@@ -4643,6 +4669,15 @@ function stableFingerprint(parts) {
   return createHash("sha256").update(parts.join(`
 `)).digest("hex").slice(0, 16);
 }
+function stableFailureFingerprint(run, classification) {
+  return stableFingerprint([
+    run.loopId,
+    classification,
+    String(run.status),
+    String(run.exitCode ?? ""),
+    (run.error ?? run.stderr ?? run.stdout ?? "").replace(/\d{4}-\d{2}-\d{2}T\S+/g, "<timestamp>").slice(0, FINGERPRINT_EVIDENCE_CHARS)
+  ]);
+}
 function healthRun(run) {
   return {
     ...run,
@@ -4676,14 +4711,7 @@ function classifyRunFailure(run) {
     classification = "sigsegv";
   return {
     classification,
-    fingerprint: stableFingerprint([
-      run.loopId,
-      run.loopName,
-      run.status,
-      classification,
-      String(run.exitCode ?? ""),
-      (run.error ?? run.stderr ?? run.stdout ?? "").slice(0, 500)
-    ]),
+    fingerprint: stableFailureFingerprint(run, classification),
     evidence: {
       error: bounded(run.error),
       stdout: bounded(run.stdout),
@@ -4799,7 +4827,7 @@ function expectationForLoop(store, loop) {
   };
 }
 function buildHealthReport(store, opts = {}) {
-  const loops = store.listLoops({ includeArchived: opts.includeArchived, limit: opts.limit ?? 200 });
+  const loops = store.listLoops({ includeArchived: opts.includeArchived, limit: opts.limit ?? 200 }).filter((loop) => opts.includeInactive || loop.status === "active" || loop.status === "paused");
   const expectations = loops.map((loop) => expectationForLoop(store, loop));
   const classifications = Object.fromEntries(CLASSIFICATIONS.map((key) => [key, 0]));
   for (const expectation of expectations) {
@@ -4821,10 +4849,247 @@ function buildHealthReport(store, opts = {}) {
     expectations
   };
 }
+
+// src/lib/hygiene.ts
+import { basename } from "path";
+var PROVIDER_TOKENS = new Set([
+  "codewith",
+  "claude",
+  "command",
+  "tmux",
+  "codex",
+  "cursor",
+  "opencode",
+  "aicopilot",
+  "agent"
+]);
+var REPO_GENERIC_TOKENS = new Set(["repo", "repoops"]);
+function slugify(value) {
+  return value.normalize("NFKD").replace(/[^\w\s.-]/g, "-").replace(/[_\s.:/]+/g, "-").replace(/[^a-zA-Z0-9-]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "").toLowerCase();
+}
+function repoSlugFromCwd(cwd) {
+  if (!cwd || cwd === process.env.HOME || cwd === "/home/hasna")
+    return "";
+  if (cwd.includes("/.hasna/loops/"))
+    return "";
+  return slugify(basename(cwd));
+}
+function scopeForLoop(loop) {
+  const cwd = loop.target.type === "command" || loop.target.type === "agent" ? loop.target.cwd : undefined;
+  const repoSlug = repoSlugFromCwd(cwd);
+  if (repoSlug)
+    return { scope: "repo", prefix: `repo-${repoSlug}`, scopeSlug: repoSlug };
+  return { scope: "machine", prefix: "machine", scopeSlug: "machine" };
+}
+function taskSlug(loop, scope) {
+  const oldName = loop.name;
+  let nameForParsing = oldName;
+  if (!oldName.includes(":")) {
+    const slug = slugify(oldName);
+    if (scope.scope === "machine" && slug.startsWith("machine-"))
+      nameForParsing = slug.slice("machine-".length);
+    else if (scope.scope === "repo" && slug.startsWith(`repo-${scope.scopeSlug}-`)) {
+      nameForParsing = slug.slice(`repo-${scope.scopeSlug}-`.length);
+    } else
+      nameForParsing = slug;
+  }
+  const parts = [];
+  for (const rawPart of oldName.includes(":") ? oldName.split(":") : [nameForParsing]) {
+    const part = slugify(rawPart);
+    if (!part)
+      continue;
+    if (PROVIDER_TOKENS.has(part) || /^account\d+$/.test(part))
+      continue;
+    if (scope.scope === "repo" && REPO_GENERIC_TOKENS.has(part))
+      continue;
+    let normalized = part;
+    if (scope.scope === "repo" && normalized === scope.scopeSlug)
+      continue;
+    if (scope.scope === "repo" && normalized.startsWith(`${scope.scopeSlug}-`)) {
+      normalized = normalized.slice(scope.scopeSlug.length + 1);
+    }
+    if (normalized)
+      parts.push(normalized);
+  }
+  const deduped = [];
+  for (const token of parts.join("-").split("-").filter(Boolean)) {
+    if (deduped[deduped.length - 1] !== token)
+      deduped.push(token);
+  }
+  return deduped.join("-") || "loop";
+}
+function canonicalName(loop) {
+  const scope = scopeForLoop(loop);
+  let name = `${scope.prefix}-${taskSlug(loop, scope)}`.replace(/-+/g, "-").replace(/^-|-$/g, "");
+  if (name.length > 120)
+    name = `${name.slice(0, 111).replace(/-+$/g, "")}-${loop.id.slice(0, 8)}`;
+  return {
+    id: loop.id,
+    status: loop.status,
+    scope: scope.scope,
+    scopeSlug: scope.scopeSlug,
+    newName: name
+  };
+}
+function ensureUnique(changes, existingNames = []) {
+  const oldNames = new Set(changes.map((change) => change.oldName));
+  const used = new Set([...existingNames].filter((name) => !oldNames.has(name)));
+  for (const change of changes) {
+    let candidate = change.newName;
+    if (!used.has(candidate)) {
+      used.add(candidate);
+      change.newName = candidate;
+      change.changed = change.oldName !== candidate;
+      continue;
+    }
+    const base = candidate.slice(0, 111).replace(/-+$/g, "");
+    candidate = `${base}-${change.id.slice(0, 8)}`;
+    let suffix = 2;
+    while (used.has(candidate)) {
+      const extra = `-${change.id.slice(0, 6)}-${suffix++}`;
+      candidate = `${base.slice(0, 120 - extra.length)}${extra}`;
+    }
+    used.add(candidate);
+    change.newName = candidate;
+    change.changed = change.oldName !== candidate;
+  }
+}
+function managedLoops(store, opts) {
+  const loops = store.listLoops({ includeArchived: Boolean(opts.includeInactive), limit: opts.limit ?? 1000 });
+  if (opts.includeInactive)
+    return loops;
+  if (opts.includeStopped)
+    return loops.filter((loop) => loop.status !== "expired");
+  return loops.filter((loop) => loop.status === "active" || loop.status === "paused");
+}
+function buildNameHygieneReport(store, opts = {}) {
+  const allLoops = store.listLoops({ includeArchived: true, limit: 1e4 });
+  const changes = managedLoops(store, opts).map((loop) => {
+    const canonical = canonicalName(loop);
+    return {
+      ...canonical,
+      oldName: loop.name,
+      changed: loop.name !== canonical.newName
+    };
+  });
+  ensureUnique(changes, allLoops.map((loop) => loop.name));
+  const changed = changes.filter((change) => change.changed);
+  const conflicts = changes.filter((change) => allLoops.some((loop) => loop.name === change.newName && loop.id !== change.id));
+  if (opts.apply) {
+    for (const change of changed)
+      store.renameLoop(change.id, change.newName);
+  }
+  return {
+    ok: changed.length === 0,
+    generatedAt: new Date().toISOString(),
+    applied: Boolean(opts.apply),
+    checked: changes.length,
+    changed: changed.length,
+    changes,
+    conflicts
+  };
+}
+function baseName(name) {
+  return name.replace(/-(bounded|compact|native)?-?low(?:-\d+m)?$/g, "").replace(/-\d+[mhd]$/g, "").replace(/-(bounded|compact)$/g, "");
+}
+function scheduleKey(schedule) {
+  if (schedule.type === "cron")
+    return `cron:${schedule.expression}`;
+  if (schedule.type === "interval")
+    return `interval:${schedule.everyMs}`;
+  if (schedule.type === "once")
+    return `once:${schedule.at}`;
+  return `dynamic:${schedule.minIntervalMs ?? ""}`;
+}
+function targetCwd(loop) {
+  return loop.target.type === "command" || loop.target.type === "agent" ? loop.target.cwd ?? "" : "";
+}
+function buildDuplicateOverlapReport(store, opts = {}) {
+  const loops = managedLoops(store, { includeInactive: opts.includeInactive, includeStopped: true, limit: opts.limit });
+  const groups = new Map;
+  for (const loop of loops) {
+    const base = baseName(loop.name);
+    const cwd = targetCwd(loop) || undefined;
+    const schedule = scheduleKey(loop.schedule);
+    const key = `${base}|${cwd ?? ""}|${schedule}`;
+    const existing = groups.get(key) ?? { baseName: base, cwd, schedule, loops: [] };
+    existing.loops.push(loop);
+    groups.set(key, existing);
+  }
+  const duplicateGroups = [...groups.entries()].filter(([, group]) => group.loops.length > 1).map(([key, group]) => ({
+    key,
+    baseName: group.baseName,
+    cwd: group.cwd,
+    schedule: group.schedule,
+    loops: group.loops.map((loop) => ({
+      id: loop.id,
+      name: loop.name,
+      status: loop.status,
+      nextRunAt: loop.nextRunAt
+    }))
+  }));
+  return {
+    ok: duplicateGroups.length === 0,
+    generatedAt: new Date().toISOString(),
+    checked: loops.length,
+    groups: duplicateGroups
+  };
+}
+function commandText(loop) {
+  if (loop.target.type !== "command")
+    return "";
+  return [loop.target.command, ...loop.target.args ?? []].join(" ");
+}
+function scriptNeedles(scriptsDir) {
+  const home = process.env.HOME ?? "/home/hasna";
+  const normalized = scriptsDir.replace(/\/+$/g, "");
+  const values = [
+    normalized,
+    `${normalized}/`,
+    "~/.hasna/loops/scripts",
+    "~/.hasna/loops/scripts/",
+    "$HOME/.hasna/loops/scripts",
+    "$HOME/.hasna/loops/scripts/",
+    "${HOME}/.hasna/loops/scripts",
+    "${HOME}/.hasna/loops/scripts/",
+    `${home}/.hasna/loops/scripts`,
+    `${home}/.hasna/loops/scripts/`,
+    "/.hasna/loops/scripts/"
+  ];
+  return [...new Set(values)];
+}
+function buildScriptInventoryReport(store, opts = {}) {
+  const scriptsDir = opts.scriptsDir ?? `${process.env.HOME ?? "/home/hasna"}/.hasna/loops/scripts`;
+  const needles = scriptNeedles(scriptsDir);
+  const loops = managedLoops(store, { includeInactive: opts.includeInactive, includeStopped: true, limit: opts.limit });
+  const scriptBacked = loops.map((loop) => {
+    const text = commandText(loop);
+    if (!text)
+      return;
+    const matches = needles.filter((needle) => text.includes(needle));
+    if (!matches.length)
+      return;
+    return {
+      id: loop.id,
+      name: loop.name,
+      status: loop.status,
+      cwd: targetCwd(loop) || undefined,
+      command: text.length > 500 ? `${text.slice(0, 500)}...` : text,
+      scriptMatches: [...new Set(matches)]
+    };
+  }).filter((value) => Boolean(value));
+  return {
+    ok: scriptBacked.length === 0,
+    generatedAt: new Date().toISOString(),
+    checked: loops.length,
+    scriptBacked: scriptBacked.length,
+    loops: scriptBacked
+  };
+}
 // package.json
 var package_default = {
   name: "@hasna/loops",
-  version: "0.3.16",
+  version: "0.3.18",
   description: "Persistent local loop and workflow runner for deterministic commands and headless AI coding agents",
   type: "module",
   main: "dist/index.js",
@@ -4915,6 +5180,7 @@ function packageVersion() {
 // src/lib/templates.ts
 var TODOS_TASK_WORKER_VERIFIER_TEMPLATE_ID = "todos-task-worker-verifier";
 var EVENT_WORKER_VERIFIER_TEMPLATE_ID = "event-worker-verifier";
+var BOUNDED_AGENT_WORKER_VERIFIER_TEMPLATE_ID = "bounded-agent-worker-verifier";
 var TEMPLATE_SUMMARIES = [
   {
     id: TODOS_TASK_WORKER_VERIFIER_TEMPLATE_ID,
@@ -4959,6 +5225,28 @@ var TEMPLATE_SUMMARIES = [
       { name: "permissionMode", default: "bypass", description: "Provider permission mode: default, plan, auto, or bypass." },
       { name: "sandbox", default: "danger-full-access", description: "Provider sandbox mode." }
     ]
+  },
+  {
+    id: BOUNDED_AGENT_WORKER_VERIFIER_TEMPLATE_ID,
+    name: "Bounded Agent Worker + Verifier",
+    description: "Create a bounded recurring-agent workflow: one agent performs a narrow objective, then a fresh verifier audits the result with separate account/profile selection.",
+    kind: "workflow",
+    variables: [
+      { name: "objective", required: true, description: "Narrow goal-mode objective for the worker." },
+      { name: "prompt", description: "Optional extra worker prompt details." },
+      { name: "projectPath", required: true, description: "Repository or project working directory." },
+      { name: "provider", default: "codewith", description: "Agent provider: codewith, claude, cursor, opencode, aicopilot, or codex." },
+      { name: "authProfile", description: "Provider-native auth profile, currently Codewith." },
+      { name: "authProfilePool", description: "Comma-separated provider-native auth profiles; worker/verifier are selected deterministically." },
+      { name: "workerAuthProfile", description: "Provider-native auth profile for the worker step." },
+      { name: "verifierAuthProfile", description: "Provider-native auth profile for the verifier step." },
+      { name: "accountPool", description: "Comma-separated OpenAccounts profiles; worker/verifier are selected deterministically." },
+      { name: "model", description: "Provider model." },
+      { name: "variant", description: "Provider reasoning/model effort variant." },
+      { name: "permissionMode", default: "bypass", description: "Provider permission mode: default, plan, auto, or bypass." },
+      { name: "sandbox", default: "danger-full-access", description: "Provider sandbox mode." },
+      { name: "timeoutMs", default: "2700000", description: "Step timeout in milliseconds." }
+    ]
   }
 ];
 function compactJson(value) {
@@ -5145,6 +5433,54 @@ function renderEventWorkerVerifierWorkflow(input) {
     ]
   };
 }
+function renderBoundedAgentWorkerVerifierWorkflow(input) {
+  if (!input.objective?.trim())
+    throw new Error("objective is required");
+  if (!input.projectPath?.trim())
+    throw new Error("projectPath is required");
+  const seed = `${input.projectPath}:${input.objective}`;
+  const timeoutMs = input.timeoutMs && Number.isFinite(input.timeoutMs) ? input.timeoutMs : 45 * 60000;
+  const workerPrompt = [
+    `/goal ${input.objective}`,
+    "",
+    "You are the worker step for a bounded OpenLoops agent workflow.",
+    "Investigate first. Keep scope narrow, use local project/task systems as the source of truth when relevant, preserve unrelated changes, run focused validation, and record concise evidence.",
+    "Do not dispatch or paste prompts into tmux panes. If additional work is required, create or update deduped todos tasks so task-created routing can start a fresh headless workflow.",
+    input.prompt ? "" : undefined,
+    input.prompt
+  ].filter(Boolean).join(`
+`);
+  const verifierPrompt = [
+    `/goal Adversarially verify: ${input.objective}`,
+    "",
+    "You are the verifier step for a bounded OpenLoops agent workflow.",
+    "Use fresh context. Review the worker result for correctness, regressions, missing tests, safety, runaway-agent risk, output bounds, and incomplete evidence.",
+    "If valid, record verification evidence. If invalid, create precise follow-up tasks or comments and leave the original work open. Do not make broad unrelated changes."
+  ].join(`
+`);
+  return {
+    name: input.name ?? `bounded-agent-${stableIndex(seed, 4294967295).toString(16).padStart(8, "0")}-worker-verifier`,
+    description: `Bounded worker/verifier workflow for ${input.objective.slice(0, 180)}`,
+    version: 1,
+    steps: [
+      {
+        id: "worker",
+        name: "Worker",
+        description: "Execute the bounded objective and record evidence.",
+        target: agentTarget(input, workerPrompt, "worker", seed),
+        timeoutMs
+      },
+      {
+        id: "verifier",
+        name: "Verifier",
+        description: "Adversarially verify the bounded objective result.",
+        dependsOn: ["worker"],
+        target: agentTarget(input, verifierPrompt, "verifier", seed),
+        timeoutMs: Math.min(timeoutMs, 30 * 60000)
+      }
+    ]
+  };
+}
 function renderLoopTemplate(id, values) {
   if (id === TODOS_TASK_WORKER_VERIFIER_TEMPLATE_ID) {
     return renderTodosTaskWorkerVerifierWorkflow({
@@ -5191,6 +5527,27 @@ function renderLoopTemplate(id, values) {
       sandbox: values.sandbox
     });
   }
+  if (id === BOUNDED_AGENT_WORKER_VERIFIER_TEMPLATE_ID) {
+    return renderBoundedAgentWorkerVerifierWorkflow({
+      name: values.name,
+      objective: values.objective ?? "",
+      prompt: values.prompt,
+      projectPath: values.projectPath ?? values.cwd ?? process.cwd(),
+      provider: values.provider,
+      authProfile: values.authProfile,
+      authProfilePool: listVar(values.authProfilePool),
+      workerAuthProfile: values.workerAuthProfile,
+      verifierAuthProfile: values.verifierAuthProfile,
+      account: values.account ? { profile: values.account, tool: values.accountTool } : undefined,
+      accountPool: accountPoolVar(values.accountPool, values.accountTool),
+      model: values.model,
+      variant: values.variant,
+      agent: values.agent,
+      permissionMode: values.permissionMode,
+      sandbox: values.sandbox,
+      timeoutMs: values.timeoutMs ? Number(values.timeoutMs) : undefined
+    });
+  }
   throw new Error(`unknown template: ${id}`);
 }
 function listVar(value) {
@@ -5355,6 +5712,36 @@ function collectValues(value, previous = []) {
   previous.push(value);
   return previous;
 }
+function defaultLoopsProject() {
+  return process.env.LOOPS_TASK_PROJECT || process.env.LOOPS_DATA_DIR || `${process.env.HOME ?? "/home/hasna"}/.hasna/loops`;
+}
+function runLocalCommand(command, args, opts = {}) {
+  const result = spawnSync5(command, args, {
+    input: opts.input,
+    encoding: "utf8",
+    timeout: opts.timeoutMs ?? 30000,
+    maxBuffer: 8 * 1024 * 1024,
+    env: process.env
+  });
+  return {
+    ok: result.status === 0,
+    status: result.status,
+    stdout: result.stdout || "",
+    stderr: result.stderr || "",
+    error: result.error ? String(result.error.message || result.error) : ""
+  };
+}
+function ensureTodosTaskList(project, slug, name, description) {
+  runLocalCommand("todos", ["--project", project, "task-lists", "--add", name, "--slug", slug, "-d", description]);
+  const list = runLocalCommand("todos", ["--project", project, "--json", "task-lists"]);
+  if (!list.ok)
+    throw new Error(list.stderr || list.error || "failed to list todos task lists");
+  const values = JSON.parse(list.stdout || "[]");
+  const found = values.find((entry) => entry.slug === slug);
+  if (!found)
+    throw new Error(`todos task list not found after ensure: ${slug}`);
+  return found.id;
+}
 function eventData(event) {
   const data = event.data;
   if (data && typeof data === "object" && !Array.isArray(data))
@@ -6089,7 +6476,7 @@ program.command("expectations [idOrName]").description("evaluate deterministic l
     store.close();
   }
 });
-program.command("health").description("summarize loop health and latest-run expectation status").option("--json", "print JSON").action((opts) => {
+var health = program.command("health").description("summarize loop health and latest-run expectation status").option("--json", "print JSON").action((opts) => {
   const store = new Store;
   try {
     const report = buildHealthReport(store);
@@ -6107,6 +6494,134 @@ program.command("health").description("summarize loop health and latest-run expe
     store.close();
   }
 });
+health.command("route-tasks").description("upsert deduped todos tasks for failed loop health expectations").option("--project <path>", "todos project path", defaultLoopsProject()).option("--task-list <slug>", "todos task-list slug", "loop-error-self-heal").option("--limit <n>", "maximum loops to inspect", "200").option("--max-actions <n>", "maximum todos tasks to upsert", "5").option("--include-inactive", "also route stopped or expired loops").option("--dry-run", "print intended task upserts without mutating todos").option("--json", "print JSON").action((opts) => {
+  const store = new Store;
+  try {
+    const report = buildHealthReport(store, { limit: Number(opts.limit), includeInactive: Boolean(opts.includeInactive) });
+    const failures = report.expectations.filter((entry) => !entry.ok && entry.recommendedTask).slice(0, Number(opts.maxActions));
+    const listId = opts.dryRun ? undefined : ensureTodosTaskList(opts.project, opts.taskList, "Loop Error Self Heal", "Deduped OpenLoops health expectation failures routed by loops health route-tasks.");
+    const actions = failures.map((expectation) => {
+      const task = expectation.recommendedTask;
+      const metadata = {
+        source: "openloops.health.route-tasks",
+        loop_id: expectation.loop.id,
+        loop_name: expectation.loop.name,
+        run_id: expectation.latestRun?.id,
+        classification: expectation.failure?.classification,
+        fingerprint: task.dedupeKey,
+        no_tmux_dispatch: true
+      };
+      if (opts.dryRun) {
+        return { action: "would-upsert", title: task.title, fingerprint: task.dedupeKey, priority: task.priority, metadata };
+      }
+      const result = runLocalCommand("todos", [
+        "--project",
+        opts.project,
+        "--json",
+        "task",
+        "upsert",
+        "--fingerprint",
+        task.dedupeKey,
+        "--title",
+        task.title,
+        "-d",
+        task.description,
+        "--priority",
+        task.priority,
+        "--status",
+        "pending",
+        "--list",
+        listId,
+        "--tags",
+        task.tags.join(","),
+        "--metadata-json",
+        JSON.stringify(metadata)
+      ]);
+      if (!result.ok) {
+        return { action: "upsert-failed", fingerprint: task.dedupeKey, error: result.stderr || result.error || result.stdout };
+      }
+      return { action: "upserted", fingerprint: task.dedupeKey, task: JSON.parse(result.stdout || "{}") };
+    });
+    const routed = { ok: actions.every((action) => action.action !== "upsert-failed"), inspected: report.summary.loops, failures: failures.length, actions };
+    if (isJson() || opts.json)
+      console.log(JSON.stringify(routed, null, 2));
+    else {
+      console.log(`health_route_tasks inspected=${routed.inspected} failures=${routed.failures} actions=${actions.length}`);
+      for (const action of actions)
+        console.log(`${action.action} ${action.fingerprint}`);
+    }
+    if (!routed.ok)
+      process.exitCode = 1;
+  } finally {
+    store.close();
+  }
+});
+var hygiene = program.command("hygiene").description("deterministic OpenLoops hygiene checks and safe repairs");
+hygiene.command("names").description("check or apply canonical machine-/repo-prefixed loop names").option("--apply", "rename loops in-place").option("--include-stopped", "include stopped loops").option("--include-inactive", "include stopped, expired, and archived loops").option("--limit <n>", "maximum loops to inspect", "1000").option("--json", "print JSON").action((opts) => {
+  const store = new Store;
+  try {
+    const report = buildNameHygieneReport(store, {
+      apply: Boolean(opts.apply),
+      includeStopped: Boolean(opts.includeStopped),
+      includeInactive: Boolean(opts.includeInactive),
+      limit: Number(opts.limit)
+    });
+    if (isJson() || opts.json)
+      console.log(JSON.stringify(report, null, 2));
+    else {
+      console.log(`hygiene_names checked=${report.checked} changed=${report.changed} applied=${report.applied}`);
+      for (const change of report.changes.filter((entry) => entry.changed)) {
+        console.log(`${report.applied ? "renamed" : "would-rename"} ${change.id} ${change.oldName} -> ${change.newName}`);
+      }
+    }
+    if (!report.ok && !report.applied)
+      process.exitCode = 1;
+  } finally {
+    store.close();
+  }
+});
+hygiene.command("duplicates").description("detect duplicate/overlapping loops with the same canonical name, cwd, and schedule").option("--include-inactive", "include stopped, expired, and archived loops").option("--limit <n>", "maximum loops to inspect", "1000").option("--json", "print JSON").action((opts) => {
+  const store = new Store;
+  try {
+    const report = buildDuplicateOverlapReport(store, {
+      includeInactive: Boolean(opts.includeInactive),
+      limit: Number(opts.limit)
+    });
+    if (isJson() || opts.json)
+      console.log(JSON.stringify(report, null, 2));
+    else {
+      console.log(`hygiene_duplicates checked=${report.checked} groups=${report.groups.length}`);
+      for (const group of report.groups) {
+        console.log(`${group.key}	${group.loops.map((loop) => `${loop.id}:${loop.status}:${loop.name}`).join(",")}`);
+      }
+    }
+    if (!report.ok)
+      process.exitCode = 1;
+  } finally {
+    store.close();
+  }
+});
+hygiene.command("scripts").description("inventory loops still backed by local ~/.hasna/loops/scripts commands").option("--scripts-dir <path>", "script directory to detect").option("--include-inactive", "include stopped, expired, and archived loops").option("--limit <n>", "maximum loops to inspect", "1000").option("--json", "print JSON").action((opts) => {
+  const store = new Store;
+  try {
+    const report = buildScriptInventoryReport(store, {
+      scriptsDir: opts.scriptsDir,
+      includeInactive: Boolean(opts.includeInactive),
+      limit: Number(opts.limit)
+    });
+    if (isJson() || opts.json)
+      console.log(JSON.stringify(report, null, 2));
+    else {
+      console.log(`hygiene_scripts checked=${report.checked} script_backed=${report.scriptBacked}`);
+      for (const loop of report.loops)
+        console.log(`${loop.id}	${loop.status}	${loop.name}	${loop.command}`);
+    }
+    if (!report.ok)
+      process.exitCode = 1;
+  } finally {
+    store.close();
+  }
+});
 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"));