@hasna/loops 0.3.25 → 0.3.26

package/README.md

@@ -318,6 +318,16 @@ 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.
 
+Add `--evidence-dir <dir>` to `health route-tasks` or `hygiene route-tasks`
+when the deterministic loop should write a durable JSON heartbeat/report in
+addition to loop stdout. Add `--auto-route` only for task lists that are
+intentionally connected to task-created worker/verifier automation; it appends
+`auto:route`, sets route metadata, and lets OpenTodos/OpenEvents trigger the
+existing headless workflow path when the finding has a cwd or
+`--route-project-path` is provided. Findings with no routeable working
+directory stay as tasks and record an `auto_route_skipped_reason`. Without
+`--auto-route`, the command only creates or updates deduped tasks.
+
 `hygiene names` reports canonical `machine-*` or `repo-<name>-*` loop names and
 renames only with `--apply`. Apply mode writes a SQLite backup under
 `<LOOPS_DATA_DIR>/backups` before changing loop names. `hygiene duplicates`

package/dist/cli/index.js

@@ -2195,7 +2195,7 @@ class Store {
 }
 
 // src/cli/index.ts
-import { createHash as createHash2 } from "crypto";
+import { createHash as createHash2, randomUUID } from "crypto";
 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";
@@ -5204,7 +5204,7 @@ function buildScriptInventoryReport(store, opts = {}) {
 // package.json
 var package_default = {
   name: "@hasna/loops",
-  version: "0.3.25",
+  version: "0.3.26",
   description: "Persistent local loop and workflow runner for deterministic commands and headless AI coding agents",
   type: "module",
   main: "dist/index.js",
@@ -5958,6 +5958,15 @@ function writeRouteCursor(key, lastFingerprint) {
   cursors[key] = { lastFingerprint, updatedAt: new Date().toISOString() };
   writeFileSync3(routeCursorsPath(), JSON.stringify(cursors, null, 2), { mode: 384 });
 }
+function writeRouteEvidence(kind, value, evidenceDir) {
+  if (!evidenceDir)
+    return;
+  mkdirSync5(evidenceDir, { recursive: true, mode: 448 });
+  const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\./g, "");
+  const evidencePath = join3(evidenceDir, `${kind}-${stamp}-${randomUUID().slice(0, 8)}.json`);
+  writeFileSync3(evidencePath, JSON.stringify(value, null, 2), { mode: 384, flag: "wx" });
+  return evidencePath;
+}
 function selectRouteItems(items, maxActions, cursorKey, fingerprintOf) {
   const total = items.length;
   const boundedMax = Math.max(0, Math.floor(Number.isFinite(maxActions) ? maxActions : 0));
@@ -5984,6 +5993,77 @@ function selectRouteItems(items, maxActions, cursorKey, fingerprintOf) {
     }
   };
 }
+function taskAutoRoute(tags, base, opts) {
+  if (!opts.autoRoute) {
+    return {
+      tags,
+      metadata: {
+        ...base,
+        route_enabled: false,
+        project_path: null,
+        working_dir: null,
+        auto_route_requested: false,
+        auto_route_enabled: false,
+        automation: {
+          allowed: false,
+          source: opts.source,
+          kind: "task-created-worker-verifier"
+        }
+      },
+      autoRoute: { requested: false, enabled: false }
+    };
+  }
+  const projectPath = typeof base.cwd === "string" && base.cwd.trim() || typeof opts.routeProjectPath === "string" && opts.routeProjectPath.trim() || undefined;
+  if (!projectPath) {
+    return {
+      tags,
+      metadata: {
+        ...base,
+        route_enabled: false,
+        project_path: null,
+        working_dir: null,
+        auto_route_requested: true,
+        auto_route_enabled: false,
+        auto_route_skipped_reason: "missing cwd or --route-project-path",
+        automation: {
+          allowed: false,
+          source: opts.source,
+          kind: "task-created-worker-verifier"
+        }
+      },
+      autoRoute: {
+        requested: true,
+        enabled: false,
+        skippedReason: "missing cwd or --route-project-path"
+      }
+    };
+  }
+  return {
+    tags: [...new Set([...tags, "auto:route"])],
+    metadata: {
+      ...base,
+      route_enabled: true,
+      project_path: projectPath,
+      working_dir: projectPath,
+      auto_route_requested: true,
+      auto_route_enabled: true,
+      automation: {
+        allowed: true,
+        source: opts.source,
+        kind: "task-created-worker-verifier"
+      }
+    },
+    autoRoute: { requested: true, enabled: true }
+  };
+}
+function routeTaskWorkingDirArgs(routeTask) {
+  const workingDir = routeTask.autoRoute.enabled && typeof routeTask.metadata.working_dir === "string" ? routeTask.metadata.working_dir : undefined;
+  return workingDir ? ["--working-dir", workingDir] : [];
+}
+function routeCursorKey(kind, parts, opts) {
+  const routeMode = opts.autoRoute ? ["auto-route", opts.routeProjectPath ?? "cwd"] : [];
+  return `${kind}:${stableHash([...parts, ...routeMode])}`;
+}
 function eventData(event) {
   const data = event.data;
   if (data && typeof data === "object" && !Array.isArray(data))
@@ -6790,26 +6870,43 @@ var health = program.command("health").description("summarize loop health and la
     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) => {
+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("--auto-route", "opt routed tasks into task-created headless worker/verifier automation").option("--route-project-path <path>", "fallback project path for --auto-route when the failed loop has no cwd").option("--evidence-dir <path>", "write the route result JSON to this directory").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);
-    const selection = selectRouteItems(failures, Number(opts.maxActions), `health:${stableHash([opts.project, opts.taskList, opts.limit, Boolean(opts.includeInactive)])}`, (expectation) => expectation.recommendedTask.dedupeKey);
+    const selection = selectRouteItems(failures, Number(opts.maxActions), routeCursorKey("health", [opts.project, opts.taskList, opts.limit, Boolean(opts.includeInactive)], {
+      autoRoute: Boolean(opts.autoRoute),
+      routeProjectPath: opts.routeProjectPath
+    }), (expectation) => expectation.recommendedTask.dedupeKey);
     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 = selection.selected.map((expectation) => {
       const task = expectation.recommendedTask;
-      const metadata = {
+      const routeTask = taskAutoRoute(task.tags, {
         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,
+        cwd: expectation.route.cwd,
+        provider: expectation.route.provider,
         no_tmux_dispatch: true
-      };
+      }, {
+        autoRoute: Boolean(opts.autoRoute),
+        routeProjectPath: opts.routeProjectPath,
+        source: "openloops.health.route-tasks"
+      });
       if (opts.dryRun) {
-        return { action: "would-upsert", title: task.title, fingerprint: task.dedupeKey, priority: task.priority, metadata };
+        return {
+          action: "would-upsert",
+          title: task.title,
+          fingerprint: task.dedupeKey,
+          priority: task.priority,
+          tags: routeTask.tags,
+          metadata: routeTask.metadata,
+          autoRoute: routeTask.autoRoute
+        };
       }
       const result = runLocalCommand("todos", [
         "--project",
@@ -6830,9 +6927,10 @@ health.command("route-tasks").description("upsert deduped todos tasks for failed
         "--list",
         listId,
         "--tags",
-        task.tags.join(","),
+        routeTask.tags.join(","),
+        ...routeTaskWorkingDirArgs(routeTask),
         "--metadata-json",
-        JSON.stringify(metadata)
+        JSON.stringify(routeTask.metadata)
       ]);
       if (!result.ok) {
         return { action: "upsert-failed", fingerprint: task.dedupeKey, error: result.stderr || result.error || result.stdout };
@@ -6846,12 +6944,16 @@ health.command("route-tasks").description("upsert deduped todos tasks for failed
       routing: selection.cursor,
       actions
     };
+    const evidencePath = writeRouteEvidence("health-route-tasks", routed, opts.evidenceDir);
+    const output = evidencePath ? { ...routed, evidencePath } : routed;
     if (!opts.dryRun && routed.ok)
       writeRouteCursor(selection.cursor.key, selection.cursor.lastFingerprint);
     if (isJson() || opts.json)
-      console.log(JSON.stringify(routed, null, 2));
+      console.log(JSON.stringify(output, null, 2));
     else {
-      console.log(`health_route_tasks inspected=${routed.inspected} failures=${routed.failures} actions=${actions.length}`);
+      console.log(`health_route_tasks inspected=${output.inspected} failures=${output.failures} actions=${actions.length}`);
+      if (evidencePath)
+        console.log(`evidence=${evidencePath}`);
       for (const action of actions)
         console.log(`${action.action} ${action.fingerprint}`);
     }
@@ -7074,7 +7176,7 @@ 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) => {
+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("--auto-route", "opt routed tasks into task-created headless worker/verifier automation").option("--route-project-path <path>", "fallback project path for --auto-route when the hygiene finding has no cwd").option("--evidence-dir <path>", "write the route result JSON to this directory").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);
@@ -7084,11 +7186,28 @@ hygiene.command("route-tasks").description("upsert deduped todos tasks for hygie
       limit: Number(opts.limit),
       scriptsDir: opts.scriptsDir
     });
-    const selection = selectRouteItems(route.tasks, Number(opts.maxActions), `hygiene:${stableHash([opts.project, opts.taskList, checks, opts.limit, Boolean(opts.includeInactive), opts.scriptsDir ?? ""])}`, (task) => task.fingerprint);
+    const selection = selectRouteItems(route.tasks, Number(opts.maxActions), routeCursorKey("hygiene", [opts.project, opts.taskList, checks, opts.limit, Boolean(opts.includeInactive), opts.scriptsDir ?? ""], {
+      autoRoute: Boolean(opts.autoRoute),
+      routeProjectPath: opts.routeProjectPath
+    }), (task) => task.fingerprint);
     const listId = opts.dryRun ? undefined : ensureTodosTaskList(opts.project, opts.taskList, "OpenLoops Hygiene", "Deduped OpenLoops hygiene findings routed by loops hygiene route-tasks.");
     const actions = selection.selected.map((task) => {
+      const routeTask = taskAutoRoute(task.tags, task.metadata, {
+        autoRoute: Boolean(opts.autoRoute),
+        routeProjectPath: opts.routeProjectPath,
+        source: "openloops.hygiene.route-tasks"
+      });
       if (opts.dryRun) {
-        return { action: "would-upsert", check: task.check, title: task.title, fingerprint: task.fingerprint, priority: task.priority, metadata: task.metadata };
+        return {
+          action: "would-upsert",
+          check: task.check,
+          title: task.title,
+          fingerprint: task.fingerprint,
+          priority: task.priority,
+          tags: routeTask.tags,
+          metadata: routeTask.metadata,
+          autoRoute: routeTask.autoRoute
+        };
       }
       const result = runLocalCommand("todos", [
         "--project",
@@ -7109,9 +7228,10 @@ hygiene.command("route-tasks").description("upsert deduped todos tasks for hygie
         "--list",
         listId,
         "--tags",
-        task.tags.join(","),
+        routeTask.tags.join(","),
+        ...routeTaskWorkingDirArgs(routeTask),
         "--metadata-json",
-        JSON.stringify(task.metadata)
+        JSON.stringify(routeTask.metadata)
       ]);
       if (!result.ok) {
         return { action: "upsert-failed", check: task.check, fingerprint: task.fingerprint, error: result.stderr || result.error || result.stdout };
@@ -7126,12 +7246,16 @@ hygiene.command("route-tasks").description("upsert deduped todos tasks for hygie
       routing: selection.cursor,
       actions
     };
+    const evidencePath = writeRouteEvidence("hygiene-route-tasks", routed, opts.evidenceDir);
+    const output = evidencePath ? { ...routed, evidencePath } : routed;
     if (!opts.dryRun && routed.ok)
       writeRouteCursor(selection.cursor.key, selection.cursor.lastFingerprint);
     if (isJson() || opts.json)
-      console.log(JSON.stringify(routed, null, 2));
+      console.log(JSON.stringify(output, null, 2));
     else {
-      console.log(`hygiene_route_tasks checks=${checks.join(",")} findings=${routed.findings} actions=${actions.length}`);
+      console.log(`hygiene_route_tasks checks=${checks.join(",")} findings=${output.findings} actions=${actions.length}`);
+      if (evidencePath)
+        console.log(`evidence=${evidencePath}`);
       for (const action of actions)
         console.log(`${action.action} ${action.fingerprint}`);
     }

package/dist/daemon/index.js

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

@@ -338,6 +338,14 @@ Use `--dry-run --json` first when testing a new automation path. Routed tasks
 include the stable failure fingerprint, classification, loop id/name, and
 `no_tmux_dispatch=true` metadata.
 
+Use `--evidence-dir <dir>` when a deterministic loop needs a compact JSON
+heartbeat/report on disk. Use `--auto-route` only on task lists that should feed
+the task-created headless worker/verifier workflow; it adds the `auto:route`
+tag and route metadata when the finding has a cwd or `--route-project-path` is
+provided. Findings with no routeable working directory remain plain tasks and
+record an `auto_route_skipped_reason`. Without `--auto-route`, route commands
+only upsert deduped tasks and do not launch agents.
+
 Failure classifications are: `rate_limit`, `auth`, `model_not_found`,
 `context_length`, `schema_response_format`, `node_init`, `timeout`, `sigsegv`,
 `skipped_previous_active`, and `unknown`.

package/package.json

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