@hasna/loops 0.3.18 → 0.3.20

package/README.md

@@ -309,6 +309,7 @@ loops health route-tasks --project ~/.hasna/loops --task-list loop-error-self-he
 loops hygiene names --json
 loops hygiene duplicates --json
 loops hygiene scripts --json
+loops hygiene route-tasks --checks duplicates,scripts --project ~/.hasna/loops --task-list openloops-hygiene
 ```
 
 `health` and `expectations` classify latest-run failures with stable
@@ -318,9 +319,12 @@ 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`.
+renames only with `--apply`. Apply mode writes a SQLite backup under
+`<LOOPS_DATA_DIR>/backups` before changing loop names. `hygiene duplicates`
+groups loops with the same normalized name, cwd, and schedule. `hygiene scripts`
+inventories loops whose command still references `~/.hasna/loops/scripts`.
+`hygiene route-tasks` upserts deduped Todos tasks for hygiene findings with
+stable fingerprints and `no_tmux_dispatch=true` metadata.
 
 Archive loops when retiring old automation but preserving history:
 

package/dist/cli/index.js

@@ -2196,8 +2196,10 @@ class Store {
 
 // src/cli/index.ts
 import { createHash as createHash2 } from "crypto";
-import { existsSync as existsSync3, readFileSync as readFileSync2 } from "fs";
+import { existsSync as existsSync3, mkdirSync as mkdirSync5, readFileSync as readFileSync2, writeFileSync as writeFileSync3 } from "fs";
 import { spawnSync as spawnSync5 } from "child_process";
+import { join as join3 } from "path";
+import { Database as Database2 } from "bun:sqlite";
 import { Command } from "commander";
 
 // src/lib/format.ts
@@ -5089,7 +5091,7 @@ function buildScriptInventoryReport(store, opts = {}) {
 // package.json
 var package_default = {
   name: "@hasna/loops",
-  version: "0.3.18",
+  version: "0.3.20",
   description: "Persistent local loop and workflow runner for deterministic commands and headless AI coding agents",
   type: "module",
   main: "dist/index.js",
@@ -5742,6 +5744,23 @@ function ensureTodosTaskList(project, slug, name, description) {
     throw new Error(`todos task list not found after ensure: ${slug}`);
   return found.id;
 }
+function backupLoopsDatabase(reason) {
+  const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\..+$/, "Z");
+  const backupDir = join3(dataDir(), "backups");
+  mkdirSync5(backupDir, { recursive: true, mode: 448 });
+  const backupPath = join3(backupDir, `loops.db.bak-${reason}-${stamp}`);
+  const db = new Database2(dbPath(), { readonly: true });
+  try {
+    writeFileSync3(backupPath, db.serialize(), { mode: 384 });
+  } finally {
+    db.close();
+  }
+  return backupPath;
+}
+function stableHash(parts) {
+  return createHash2("sha256").update(parts.map((part) => JSON.stringify(part)).join(`
+`)).digest("hex").slice(0, 16);
+}
 function eventData(event) {
   const data = event.data;
   if (data && typeof data === "object" && !Array.isArray(data))
@@ -6557,19 +6576,155 @@ health.command("route-tasks").description("upsert deduped todos tasks for failed
   }
 });
 var hygiene = program.command("hygiene").description("deterministic OpenLoops hygiene checks and safe repairs");
+var HYGIENE_CHECKS = ["names", "duplicates", "scripts"];
+function parseHygieneChecks(value) {
+  if (!value || value === "all")
+    return HYGIENE_CHECKS;
+  const checks = value.split(",").map((entry) => entry.trim()).filter(Boolean);
+  const invalid = checks.filter((entry) => !HYGIENE_CHECKS.includes(entry));
+  if (invalid.length > 0)
+    throw new Error(`invalid hygiene check(s): ${invalid.join(", ")}`);
+  return [...new Set(checks)];
+}
+function buildHygieneRouteTasks(store, opts) {
+  const checked = { names: 0, duplicates: 0, scripts: 0 };
+  const tasks = [];
+  const limit = opts.limit ?? 1000;
+  if (opts.checks.includes("names")) {
+    const report = buildNameHygieneReport(store, { includeInactive: opts.includeInactive, limit });
+    checked.names = report.checked;
+    for (const change of report.changes.filter((entry) => entry.changed)) {
+      const fingerprint = `openloops:hygiene:names:${change.id}:${stableHash([change.oldName, change.newName])}`;
+      tasks.push({
+        check: "names",
+        title: `OpenLoops hygiene: rename loop ${change.oldName}`,
+        description: [
+          `OpenLoops name hygiene found a non-canonical loop name.`,
+          `Loop: ${change.oldName} (${change.id})`,
+          `Expected name: ${change.newName}`,
+          `Scope: ${change.scope} / ${change.scopeSlug}`,
+          `Fingerprint: ${fingerprint}`,
+          "",
+          "Acceptance:",
+          "- Confirm the canonical name is correct for the loop scope.",
+          "- Rename through OpenLoops CLI/API so ids, schedules, run history, and metadata are preserved.",
+          "- Do not dispatch work by tmux."
+        ].join(`
+`),
+        priority: "low",
+        tags: ["openloops", "hygiene", "name-hygiene"],
+        fingerprint,
+        metadata: {
+          source: "openloops.hygiene.route-tasks",
+          check: "names",
+          loop_id: change.id,
+          old_name: change.oldName,
+          new_name: change.newName,
+          scope: change.scope,
+          scope_slug: change.scopeSlug,
+          no_tmux_dispatch: true
+        }
+      });
+    }
+  }
+  if (opts.checks.includes("duplicates")) {
+    const report = buildDuplicateOverlapReport(store, { includeInactive: opts.includeInactive, limit });
+    checked.duplicates = report.checked;
+    for (const group of report.groups) {
+      const loopIds = group.loops.map((loop) => loop.id).sort();
+      const fingerprint = `openloops:hygiene:duplicates:${stableHash([group.key, loopIds])}`;
+      tasks.push({
+        check: "duplicates",
+        title: `OpenLoops hygiene: duplicate/overlapping loops - ${group.baseName}`,
+        description: [
+          `OpenLoops duplicate/overlap hygiene found multiple loops with the same normalized name, cwd, and schedule.`,
+          `Base name: ${group.baseName}`,
+          group.cwd ? `Cwd: ${group.cwd}` : undefined,
+          `Schedule: ${group.schedule}`,
+          `Fingerprint: ${fingerprint}`,
+          "",
+          "Loops:",
+          ...group.loops.map((loop) => `- ${loop.id} ${loop.status} ${loop.name}`),
+          "",
+          "Acceptance:",
+          "- Decide the authoritative active loop.",
+          "- Archive or retarget superseded loops through OpenLoops CLI/API while preserving history.",
+          "- Do not dispatch work by tmux."
+        ].filter(Boolean).join(`
+`),
+        priority: group.loops.some((loop) => loop.status === "active") ? "medium" : "low",
+        tags: ["openloops", "hygiene", "duplicate-overlap"],
+        fingerprint,
+        metadata: {
+          source: "openloops.hygiene.route-tasks",
+          check: "duplicates",
+          base_name: group.baseName,
+          cwd: group.cwd,
+          schedule: group.schedule,
+          loop_ids: loopIds,
+          no_tmux_dispatch: true
+        }
+      });
+    }
+  }
+  if (opts.checks.includes("scripts")) {
+    const report = buildScriptInventoryReport(store, { includeInactive: opts.includeInactive, limit, scriptsDir: opts.scriptsDir });
+    checked.scripts = report.checked;
+    for (const loop of report.loops) {
+      const fingerprint = `openloops:hygiene:scripts:${loop.id}:${stableHash([loop.command])}`;
+      tasks.push({
+        check: "scripts",
+        title: `OpenLoops hygiene: replace script-backed loop ${loop.name}`,
+        description: [
+          `OpenLoops script inventory found a loop still backed by a local script command.`,
+          `Loop: ${loop.name} (${loop.id})`,
+          `Status: ${loop.status}`,
+          loop.cwd ? `Cwd: ${loop.cwd}` : undefined,
+          `Command: ${loop.command}`,
+          `Fingerprint: ${fingerprint}`,
+          "",
+          "Acceptance:",
+          "- Replace this loop with a package-level CLI/API/template abstraction when one exists.",
+          "- If no abstraction exists, create/update the owning repo task instead of adding another local script.",
+          "- Archive superseded loops through OpenLoops CLI/API and preserve history.",
+          "- Do not dispatch work by tmux."
+        ].filter(Boolean).join(`
+`),
+        priority: loop.status === "active" ? "medium" : "low",
+        tags: ["openloops", "hygiene", "script-backed-loop"],
+        fingerprint,
+        metadata: {
+          source: "openloops.hygiene.route-tasks",
+          check: "scripts",
+          loop_id: loop.id,
+          loop_name: loop.name,
+          loop_status: loop.status,
+          cwd: loop.cwd,
+          script_matches: loop.scriptMatches,
+          no_tmux_dispatch: true
+        }
+      });
+    }
+  }
+  return { checked, findings: tasks.length, tasks };
+}
 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 backupPath = opts.apply ? backupLoopsDatabase("name-hygiene") : undefined;
     const report = buildNameHygieneReport(store, {
       apply: Boolean(opts.apply),
       includeStopped: Boolean(opts.includeStopped),
       includeInactive: Boolean(opts.includeInactive),
       limit: Number(opts.limit)
     });
+    const output = backupPath ? { ...report, backupPath } : report;
     if (isJson() || opts.json)
-      console.log(JSON.stringify(report, null, 2));
+      console.log(JSON.stringify(output, null, 2));
     else {
       console.log(`hygiene_names checked=${report.checked} changed=${report.changed} applied=${report.applied}`);
+      if (backupPath)
+        console.log(`backup=${backupPath}`);
       for (const change of report.changes.filter((entry) => entry.changed)) {
         console.log(`${report.applied ? "renamed" : "would-rename"} ${change.id} ${change.oldName} -> ${change.newName}`);
       }
@@ -6622,6 +6777,70 @@ hygiene.command("scripts").description("inventory loops still backed by local ~/
     store.close();
   }
 });
+hygiene.command("route-tasks").description("upsert deduped todos tasks for hygiene findings").option("--checks <list>", "comma-separated hygiene checks: names,duplicates,scripts,all", "all").option("--project <path>", "todos project path", defaultLoopsProject()).option("--task-list <slug>", "todos task-list slug", "openloops-hygiene").option("--limit <n>", "maximum loops to inspect", "1000").option("--max-actions <n>", "maximum todos tasks to upsert", "10").option("--scripts-dir <path>", "script directory to detect for script inventory").option("--include-inactive", "also route stopped, expired, or archived loops").option("--dry-run", "print intended task upserts without mutating todos").option("--json", "print JSON").action((opts) => {
+  const store = new Store;
+  try {
+    const checks = parseHygieneChecks(opts.checks);
+    const route = buildHygieneRouteTasks(store, {
+      checks,
+      includeInactive: Boolean(opts.includeInactive),
+      limit: Number(opts.limit),
+      scriptsDir: opts.scriptsDir
+    });
+    const tasks = route.tasks.slice(0, Number(opts.maxActions));
+    const listId = opts.dryRun ? undefined : ensureTodosTaskList(opts.project, opts.taskList, "OpenLoops Hygiene", "Deduped OpenLoops hygiene findings routed by loops hygiene route-tasks.");
+    const actions = tasks.map((task) => {
+      if (opts.dryRun) {
+        return { action: "would-upsert", check: task.check, title: task.title, fingerprint: task.fingerprint, priority: task.priority, metadata: task.metadata };
+      }
+      const result = runLocalCommand("todos", [
+        "--project",
+        opts.project,
+        "--json",
+        "task",
+        "upsert",
+        "--fingerprint",
+        task.fingerprint,
+        "--title",
+        task.title,
+        "-d",
+        task.description,
+        "--priority",
+        task.priority,
+        "--status",
+        "pending",
+        "--list",
+        listId,
+        "--tags",
+        task.tags.join(","),
+        "--metadata-json",
+        JSON.stringify(task.metadata)
+      ]);
+      if (!result.ok) {
+        return { action: "upsert-failed", check: task.check, fingerprint: task.fingerprint, error: result.stderr || result.error || result.stdout };
+      }
+      return { action: "upserted", check: task.check, fingerprint: task.fingerprint, task: JSON.parse(result.stdout || "{}") };
+    });
+    const routed = {
+      ok: actions.every((action) => action.action !== "upsert-failed"),
+      checks,
+      checked: route.checked,
+      findings: route.findings,
+      actions
+    };
+    if (isJson() || opts.json)
+      console.log(JSON.stringify(routed, null, 2));
+    else {
+      console.log(`hygiene_route_tasks checks=${checks.join(",")} findings=${routed.findings} actions=${actions.length}`);
+      for (const action of actions)
+        console.log(`${action.action} ${action.fingerprint}`);
+    }
+    if (!routed.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"));

package/dist/daemon/index.js

@@ -4419,7 +4419,7 @@ function enableStartup(result) {
 // package.json
 var package_default = {
   name: "@hasna/loops",
-  version: "0.3.18",
+  version: "0.3.20",
   description: "Persistent local loop and workflow runner for deterministic commands and headless AI coding agents",
   type: "module",
   main: "dist/index.js",

package/docs/USAGE.md

@@ -322,13 +322,18 @@ loops hygiene names --json
 loops hygiene names --apply
 loops hygiene duplicates --json
 loops hygiene scripts --json
+loops hygiene route-tasks --checks names,duplicates,scripts --dry-run --json
 ```
 
 `hygiene names` reports canonical `machine-*` or `repo-<name>-*` loop names and
-only renames when `--apply` is present. `hygiene duplicates` groups loops with
-the same normalized name, cwd, and schedule. `hygiene scripts` inventories loops
-whose command still references `~/.hasna/loops/scripts`; use it as a migration
-gate before deleting local scripts.
+only renames when `--apply` is present. Apply mode writes a SQLite backup under
+`<LOOPS_DATA_DIR>/backups` before changing loop names. `hygiene duplicates`
+groups loops with the same normalized name, cwd, and schedule. `hygiene scripts`
+inventories loops whose command still references `~/.hasna/loops/scripts`; use
+it as a migration gate before deleting local scripts. `hygiene route-tasks`
+upserts deduped Todos tasks for hygiene findings with stable fingerprints and
+`no_tmux_dispatch=true` metadata; use `--dry-run --json` before enabling it as a
+production loop.
 
 Archive loops when retiring old automation but preserving history:
 

package/package.json

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