@hasna/loops 0.4.1 → 0.4.2

package/dist/cli/index.js

@@ -1205,7 +1205,7 @@ function discardWorkflowRunManifest(staged) {
 var DEFAULT_RECOVERY_BATCH_LIMIT = 100;
 var DEFAULT_RECOVERY_SCAN_MULTIPLIER = 5;
 var LIVE_EXPIRED_RUN_GRACE_MS = 60000;
-var SCHEMA_USER_VERSION = 6;
+var SCHEMA_USER_VERSION = 7;
 var TERMINAL_RUN_STATUSES = ["succeeded", "failed", "timed_out", "abandoned", "skipped"];
 var PRUNE_BATCH_SIZE = 400;
 var GENERATED_ROUTE_TEMPLATE_IDS = new Set(["todos-task-worker-verifier", "task-lifecycle", "event-worker-verifier"]);
@@ -1575,6 +1575,13 @@ class Store {
           this.addColumnIfMissing("loop_runs", "pgid", "INTEGER");
           this.addColumnIfMissing("loop_runs", "process_started_at", "TEXT");
         }
+      },
+      {
+        id: "0007_run_claim_tokens",
+        apply: () => {
+          this.addColumnIfMissing("loop_runs", "claim_token", "TEXT");
+          this.db.exec("CREATE INDEX IF NOT EXISTS idx_runs_claim_token ON loop_runs(claim_token) WHERE claim_token IS NOT NULL");
+        }
       }
     ];
   }
@@ -1616,6 +1623,7 @@ class Store {
         started_at TEXT,
         finished_at TEXT,
         claimed_by TEXT,
+        claim_token TEXT,
         lease_expires_at TEXT,
         pid INTEGER,
         pgid INTEGER,
@@ -1634,6 +1642,7 @@ class Store {
       CREATE INDEX IF NOT EXISTS idx_runs_status ON loop_runs(status);
       CREATE INDEX IF NOT EXISTS idx_runs_status_lease ON loop_runs(status, lease_expires_at);
       CREATE INDEX IF NOT EXISTS idx_runs_scheduled ON loop_runs(scheduled_for);
+      CREATE INDEX IF NOT EXISTS idx_runs_claim_token ON loop_runs(claim_token) WHERE claim_token IS NOT NULL;
 
       CREATE TABLE IF NOT EXISTS daemon_lease (
         id TEXT PRIMARY KEY,
@@ -3505,6 +3514,7 @@ class Store {
   }
   claimRun(loop, scheduledFor, runnerId, now = new Date, opts = {}) {
     const startedAt = now.toISOString();
+    const claimToken = opts.claimToken ?? genId();
     this.db.exec("BEGIN IMMEDIATE");
     try {
       this.assertDaemonLeaseFence(opts, startedAt);
@@ -3527,12 +3537,13 @@ class Store {
             return;
           }
           const res3 = this.db.query(`UPDATE loop_runs SET status='running', started_at=$started, finished_at=NULL,
-               claimed_by=$claimedBy, lease_expires_at=$lease, pid=NULL, pgid=NULL, process_started_at=NULL, exit_code=NULL,
+               claimed_by=$claimedBy, claim_token=$claimToken, lease_expires_at=$lease, pid=NULL, pgid=NULL, process_started_at=NULL, exit_code=NULL,
                duration_ms=NULL, stdout=NULL, stderr=NULL, error=NULL, updated_at=$updated
                WHERE id=$id AND status='running' AND lease_expires_at <= $now`).run({
             $id: existing.id,
             $started: startedAt,
             $claimedBy: runnerId,
+            $claimToken: claimToken,
             $lease: leaseExpiresAt,
             $updated: startedAt,
             $now: startedAt
@@ -3541,7 +3552,7 @@ class Store {
           if (res3.changes !== 1)
             return;
           const run3 = this.getRun(existing.id);
-          return run3 ? { run: run3, loop } : undefined;
+          return run3 ? { run: run3, loop, claimToken } : undefined;
         }
         if (existing.status === "succeeded" || existing.status === "skipped") {
           this.db.exec("COMMIT");
@@ -3549,7 +3560,7 @@ class Store {
         }
         const attempt = existing.attempt + 1;
         const res2 = this.db.query(`UPDATE loop_runs SET attempt=$attempt, status='running', started_at=$started, finished_at=NULL,
-             claimed_by=$claimedBy, lease_expires_at=$lease, pid=NULL, pgid=NULL, process_started_at=NULL, exit_code=NULL,
+             claimed_by=$claimedBy, claim_token=$claimToken, lease_expires_at=$lease, pid=NULL, pgid=NULL, process_started_at=NULL, exit_code=NULL,
              duration_ms=NULL, stdout=NULL, stderr=NULL, error=NULL, updated_at=$updated
              WHERE id=$id
                AND status IN ('failed', 'timed_out', 'abandoned')
@@ -3558,6 +3569,7 @@ class Store {
           $attempt: attempt,
           $started: startedAt,
           $claimedBy: runnerId,
+          $claimToken: claimToken,
           $lease: leaseExpiresAt,
           $updated: startedAt,
           $maxAttempts: loop.maxAttempts
@@ -3566,12 +3578,12 @@ class Store {
         if (res2.changes !== 1)
           return;
         const run2 = this.getRun(existing.id);
-        return run2 ? { run: run2, loop } : undefined;
+        return run2 ? { run: run2, loop, claimToken } : undefined;
       }
       const id = genId();
       const res = this.db.query(`INSERT OR IGNORE INTO loop_runs (id, loop_id, loop_name, scheduled_for, attempt, status, started_at, finished_at,
-            claimed_by, lease_expires_at, pid, exit_code, duration_ms, stdout, stderr, error, created_at, updated_at)
-           VALUES ($id, $loopId, $loopName, $scheduledFor, 1, 'running', $started, NULL, $claimedBy, $lease,
+            claimed_by, claim_token, lease_expires_at, pid, exit_code, duration_ms, stdout, stderr, error, created_at, updated_at)
+           VALUES ($id, $loopId, $loopName, $scheduledFor, 1, 'running', $started, NULL, $claimedBy, $claimToken, $lease,
             NULL, NULL, NULL, NULL, NULL, NULL, $created, $updated)`).run({
         $id: id,
         $loopId: loop.id,
@@ -3579,6 +3591,7 @@ class Store {
         $scheduledFor: scheduledFor,
         $started: startedAt,
         $claimedBy: runnerId,
+        $claimToken: claimToken,
         $lease: leaseExpiresAt,
         $created: startedAt,
         $updated: startedAt
@@ -3587,7 +3600,7 @@ class Store {
       if (res.changes !== 1)
         return;
       const run = this.getRun(id);
-      return run ? { run, loop } : undefined;
+      return run ? { run, loop, claimToken } : undefined;
     } catch (error) {
       try {
         this.db.exec("ROLLBACK");
@@ -3610,16 +3623,18 @@ class Store {
       $error: error ?? null,
       $updated: finishedAt,
       $claimedBy: opts.claimedBy ?? null,
+      $claimToken: opts.claimToken ?? null,
       $now: (opts.now ?? new Date).toISOString(),
       $daemonLeaseId: opts.daemonLeaseId ?? null
     };
     return this.transact(() => {
-      const res = opts.claimedBy ? this.db.query(`UPDATE loop_runs SET status=$status, finished_at=$finished, lease_expires_at=NULL, pid=$pid, exit_code=$exitCode,
+      const res = opts.claimedBy ? this.db.query(`UPDATE loop_runs SET status=$status, finished_at=$finished, claim_token=NULL, lease_expires_at=NULL, pid=$pid, exit_code=$exitCode,
                duration_ms=$durationMs, stdout=$stdout, stderr=$stderr, error=$error, updated_at=$updated
                WHERE id=$id AND status='running' AND claimed_by=$claimedBy AND lease_expires_at > $now
+                 AND ($claimToken IS NULL OR claim_token=$claimToken)
                  AND ($daemonLeaseId IS NULL OR EXISTS (
                    SELECT 1 FROM daemon_lease WHERE id=$daemonLeaseId AND expires_at > $now
-                 ))`).run(params) : this.db.query(`UPDATE loop_runs SET status=$status, finished_at=$finished, lease_expires_at=NULL, pid=$pid, exit_code=$exitCode,
+                 ))`).run(params) : this.db.query(`UPDATE loop_runs SET status=$status, finished_at=$finished, claim_token=NULL, lease_expires_at=NULL, pid=$pid, exit_code=$exitCode,
                duration_ms=$durationMs, stdout=$stdout, stderr=$stderr, error=$error, updated_at=$updated WHERE id=$id`).run(params);
       const run = this.getRun(id);
       if (!run)
@@ -3647,11 +3662,13 @@ class Store {
     const expiresAt = new Date(now.getTime() + leaseMs).toISOString();
     const res = this.db.query(`UPDATE loop_runs SET lease_expires_at=$expires, updated_at=$updated
          WHERE id=$id AND status='running' AND claimed_by=$claimedBy AND lease_expires_at > $now
+           AND ($claimToken IS NULL OR claim_token=$claimToken)
            AND ($daemonLeaseId IS NULL OR EXISTS (
              SELECT 1 FROM daemon_lease WHERE id=$daemonLeaseId AND expires_at > $now
            ))`).run({
       $id: id,
       $claimedBy: claimedBy,
+      $claimToken: opts.claimToken ?? null,
       $expires: expiresAt,
       $updated: now.toISOString(),
       $now: now.toISOString(),
@@ -3967,7 +3984,7 @@ class Store {
 // package.json
 var package_default = {
   name: "@hasna/loops",
-  version: "0.4.1",
+  version: "0.4.2",
   description: "Persistent local loop and workflow runner for deterministic commands and headless AI coding agents",
   type: "module",
   main: "dist/index.js",
@@ -4007,6 +4024,22 @@ var package_default = {
     "./storage": {
       types: "./dist/lib/store.d.ts",
       import: "./dist/lib/store.js"
+    },
+    "./storage/contract": {
+      types: "./dist/lib/storage/contract.d.ts",
+      import: "./dist/lib/storage/contract.js"
+    },
+    "./storage/sqlite": {
+      types: "./dist/lib/storage/sqlite.d.ts",
+      import: "./dist/lib/storage/sqlite.js"
+    },
+    "./storage/postgres": {
+      types: "./dist/lib/storage/postgres.d.ts",
+      import: "./dist/lib/storage/postgres.js"
+    },
+    "./storage/postgres-schema": {
+      types: "./dist/lib/storage/postgres-schema.d.ts",
+      import: "./dist/lib/storage/postgres-schema.js"
     }
   },
   files: [
@@ -4017,7 +4050,7 @@ var package_default = {
     "LICENSE"
   ],
   scripts: {
-    build: "rm -rf dist && bun build src/cli/index.ts src/daemon/index.ts src/api/index.ts src/runner/index.ts src/mcp/index.ts src/index.ts src/sdk/index.ts src/lib/store.ts src/lib/mode.ts --root src --outdir dist --target bun --packages external && chmod +x dist/cli/index.js dist/daemon/index.js dist/api/index.js dist/runner/index.js dist/mcp/index.js && tsc -p tsconfig.build.json --emitDeclarationOnly --outDir dist",
+    build: "rm -rf dist && bun build src/cli/index.ts src/daemon/index.ts src/api/index.ts src/runner/index.ts src/mcp/index.ts src/index.ts src/sdk/index.ts src/lib/store.ts src/lib/mode.ts src/lib/storage/index.ts src/lib/storage/contract.ts src/lib/storage/sqlite.ts src/lib/storage/postgres.ts src/lib/storage/postgres-schema.ts --root src --outdir dist --target bun --packages external && chmod +x dist/cli/index.js dist/daemon/index.js dist/api/index.js dist/runner/index.js dist/mcp/index.js && tsc -p tsconfig.build.json --emitDeclarationOnly --outDir dist",
     "build:bin": "bun build src/cli/index.ts --compile --outfile dist/loops",
     typecheck: "tsc --noEmit",
     test: "bun test",
@@ -4280,11 +4313,12 @@ function publicLoop(loop) {
     target
   };
 }
-function publicRun(run, showOutput = false) {
+function publicRun(run, showOutput = false, opts = {}) {
   return {
     ...run,
     stdout: showOutput ? run.stdout : run.stdout ? `[redacted ${run.stdout.length} chars]` : undefined,
-    stderr: showOutput ? run.stderr : run.stderr ? `[redacted ${run.stderr.length} chars]` : undefined
+    stderr: showOutput ? run.stderr : run.stderr ? `[redacted ${run.stderr.length} chars]` : undefined,
+    error: opts.redactError ? redact(run.error) : run.error
   };
 }
 function publicExecutorResult(result, showOutput = false) {
@@ -8287,6 +8321,7 @@ var BUILTIN_TEMPLATE_SUMMARIES = [
       { name: "taskTitle", description: "Human-readable task title." },
       projectPathVariable(),
       { name: "todosProjectPath", description: "Todos storage project path used in worker/verifier commands." },
+      { name: "todosDbPath", description: "Optional exact Todos DB path used via TODOS_DB_PATH/HASNA_TODOS_DB_PATH." },
       ...routeScopeVariables(),
       ...workerVerifierAgentVariables({ addDirs: true, branchNoun: "task/event" })
     ]
@@ -8327,6 +8362,8 @@ var BUILTIN_TEMPLATE_SUMMARIES = [
     variables: [
       { name: "taskId", required: true, description: "Todos task id." },
       projectPathVariable(),
+      { name: "todosProjectPath", description: "Todos storage project path used in lifecycle commands." },
+      { name: "todosDbPath", description: "Optional exact Todos DB path used via TODOS_DB_PATH/HASNA_TODOS_DB_PATH." },
       { name: "authProfilePool", description: "Comma-separated Codewith profiles for worker/verifier rotation." },
       roleAuthProfileVariable("triage"),
       roleAuthProfileVariable("planner"),
@@ -8457,28 +8494,29 @@ function verifierRuntimeGuidance(input) {
   ].join(`
 `);
 }
-function todosInspectLine(todosProjectPath, taskId) {
-  return `- Inspect first: todos --project ${todosProjectPath} inspect ${taskId}`;
+function todosInspectLine(todosProjectPath, taskId, todosDbPath) {
+  return `- Inspect first: ${todosCommand(todosProjectPath, todosDbPath)} inspect ${taskId}`;
 }
-function todosStartLine(todosProjectPath, taskId) {
-  return `- Claim/start if appropriate: todos --project ${todosProjectPath} start ${taskId}`;
+function todosStartLine(todosProjectPath, taskId, todosDbPath) {
+  return `- Claim/start if appropriate: ${todosCommand(todosProjectPath, todosDbPath)} start ${taskId}`;
 }
-function todosEvidenceLine(todosProjectPath, taskId, placeholder) {
-  return `- Record evidence: todos --project ${todosProjectPath} comment ${taskId} "<${placeholder}>"`;
+function todosEvidenceLine(todosProjectPath, taskId, placeholder, todosDbPath) {
+  return `- Record evidence: ${todosCommand(todosProjectPath, todosDbPath)} comment ${taskId} "<${placeholder}>"`;
 }
-function todosVerificationLine(todosProjectPath, taskId) {
-  return `- Record verification: todos --project ${todosProjectPath} comment ${taskId} "<verification evidence or blocker>"`;
+function todosVerificationLine(todosProjectPath, taskId, todosDbPath) {
+  return `- Record verification: ${todosCommand(todosProjectPath, todosDbPath)} comment ${taskId} "<verification evidence or blocker>"`;
 }
-function todosDoneLine(todosProjectPath, taskId) {
-  return `- If valid and complete: todos --project ${todosProjectPath} done ${taskId}`;
+function todosDoneLine(todosProjectPath, taskId, todosDbPath) {
+  return `- If valid and complete: ${todosCommand(todosProjectPath, todosDbPath)} done ${taskId}`;
 }
-function todosExactCommandsFragment(todosProjectPath, taskId, commandLines) {
+function todosExactCommandsFragment(todosProjectPath, taskId, commandLines, todosDbPath) {
   return [
     `Todos project path: ${todosProjectPath}`,
+    todosDbPath ? `Todos DB path: ${todosDbPath}` : undefined,
     "Use these exact todos commands so worktree cwd inference cannot attach to the wrong project:",
-    todosInspectLine(todosProjectPath, taskId),
+    todosInspectLine(todosProjectPath, taskId, todosDbPath),
     ...commandLines
-  ];
+  ].filter((line) => Boolean(line));
 }
 function worktreePrompt(plan) {
   if (plan.enabled) {
@@ -8515,10 +8553,19 @@ function worktreeContextFragment(plan) {
 function shellQuote3(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
-function sourceTaskGateCommand(todosProjectPath, taskId) {
+function todosEnvPrefix(todosDbPath) {
+  return todosDbPath ? `TODOS_DB_PATH=${shellQuote3(todosDbPath)} HASNA_TODOS_DB_PATH=${shellQuote3(todosDbPath)} ` : "";
+}
+function todosCommand(todosProjectPath, todosDbPath) {
+  return `${todosEnvPrefix(todosDbPath)}todos --project ${todosProjectPath}`;
+}
+function shellTodosCommand(todosProjectPath, todosDbPath) {
+  return `${todosEnvPrefix(todosDbPath)}todos --project ${shellQuote3(todosProjectPath)}`;
+}
+function sourceTaskGateCommand(todosProjectPath, taskId, todosDbPath) {
   return [
     "set -euo pipefail",
-    `todos --project ${shellQuote3(todosProjectPath)} --json inspect ${shellQuote3(taskId)} >/dev/null`,
+    `${shellTodosCommand(todosProjectPath, todosDbPath)} --json inspect ${shellQuote3(taskId)} >/dev/null`,
     `printf "source task %s resolved in todos project %s\\n" ${shellQuote3(taskId)} ${shellQuote3(todosProjectPath)}`
   ].join(`
 `);
@@ -8578,10 +8625,10 @@ var LIFECYCLE_GATE_SCRIPT_TAIL = [
   "console.log(`task lifecycle ${stage} gate passed for ${task.id || task.taskId || 'task'} status=${status || 'unknown'}`);"
 ].join(`
 `);
-function lifecycleGateCommand(todosProjectPath, taskId, stage, goMarker, blockedMarker) {
+function lifecycleGateCommand(todosProjectPath, taskId, stage, goMarker, blockedMarker, todosDbPath) {
   return [
     "set -euo pipefail",
-    `task_json="$(todos --project ${shellQuote3(todosProjectPath)} --json inspect ${shellQuote3(taskId)})"`,
+    `task_json="$(${shellTodosCommand(todosProjectPath, todosDbPath)} --json inspect ${shellQuote3(taskId)})"`,
     `TASK_JSON="$task_json" STAGE=${shellQuote3(stage)} bun - <<'BUN'`,
     LIFECYCLE_GATE_SCRIPT_HEAD,
     `const goMarker = ${JSON.stringify(goMarker)};`,
@@ -8597,6 +8644,7 @@ var PR_HANDOFF_SCRIPT = [
   "const artifactPath = process.env.OPENLOOPS_PR_HANDOFF_ARTIFACT || '';",
   "const taskId = process.env.OPENLOOPS_PR_HANDOFF_TASK_ID || '';",
   "const todosProject = process.env.OPENLOOPS_PR_HANDOFF_TODOS_PROJECT || '';",
+  "const todosDbPath = process.env.OPENLOOPS_PR_HANDOFF_TODOS_DB_PATH || '';",
   "const fallbackWorktree = process.env.OPENLOOPS_PR_HANDOFF_WORKTREE || process.cwd();",
   "const expectedRoot = process.env.OPENLOOPS_PR_HANDOFF_WORKTREE_ROOT || fallbackWorktree;",
   "const expectedBranch = process.env.OPENLOOPS_PR_HANDOFF_EXPECTED_BRANCH || '';",
@@ -8614,7 +8662,8 @@ var PR_HANDOFF_SCRIPT = [
   "};",
   "const run = (command, args, options = {}) => spawnSync(command, args, { encoding: 'utf8', ...options });",
   "const todosArgs = (...args) => todosProject ? ['--project', todosProject, ...args] : args;",
-  "const todos = (...args) => run(todosBin, todosArgs(...args));",
+  "const todosEnv = todosDbPath ? { ...process.env, TODOS_DB_PATH: todosDbPath, HASNA_TODOS_DB_PATH: todosDbPath } : process.env;",
+  "const todos = (...args) => run(todosBin, todosArgs(...args), { env: todosEnv });",
   "const comment = (text) => {",
   "  const result = todos('comment', taskId, text);",
   "  if (result.status !== 0) console.error(`failed to comment original task: ${result.stderr || result.stdout || result.status}`);",
@@ -8743,6 +8792,7 @@ function prHandoffCommand(opts) {
     `export OPENLOOPS_PR_HANDOFF_ARTIFACT=${shellQuote3(opts.artifactPath)}`,
     `export OPENLOOPS_PR_HANDOFF_TASK_ID=${shellQuote3(opts.taskId)}`,
     `export OPENLOOPS_PR_HANDOFF_TODOS_PROJECT=${shellQuote3(opts.todosProjectPath)}`,
+    opts.todosDbPath ? `export OPENLOOPS_PR_HANDOFF_TODOS_DB_PATH=${shellQuote3(opts.todosDbPath)}` : undefined,
     `export OPENLOOPS_PR_HANDOFF_WORKTREE=${shellQuote3(opts.worktreeCwd)}`,
     `export OPENLOOPS_PR_HANDOFF_WORKTREE_ROOT=${shellQuote3(opts.worktreeRoot)}`,
     `export OPENLOOPS_PR_HANDOFF_EXPECTED_BRANCH=${shellQuote3(opts.expectedBranch)}`,
@@ -8753,7 +8803,7 @@ function prHandoffCommand(opts) {
     "bun - <<'BUN'",
     PR_HANDOFF_SCRIPT,
     "BUN"
-  ].join(`
+  ].filter((line) => Boolean(line)).join(`
 `);
 }
 // src/lib/templates-custom.ts
@@ -9343,12 +9393,12 @@ function commandStep(opts) {
     ...opts.blockedExitCodes ? { blockedExitCodes: opts.blockedExitCodes } : {}
   };
 }
-function sourceTaskGateStep(todosProjectPath, taskId, plan, description) {
+function sourceTaskGateStep(todosProjectPath, taskId, plan, description, todosDbPath) {
   return commandStep({
     id: "source-task-gate",
     name: "Source Task Gate",
     description,
-    command: sourceTaskGateCommand(todosProjectPath, taskId),
+    command: sourceTaskGateCommand(todosProjectPath, taskId, todosDbPath),
     cwd: plan.originalCwd,
     timeoutMs: 60000,
     blockedExitCodes: GATE_BLOCKED_EXIT_CODES
@@ -9360,7 +9410,7 @@ function lifecycleGateStep(opts) {
     name: opts.stage === "triage" ? "Triage Gate" : "Planner Gate",
     description: opts.description,
     dependsOn: opts.dependsOn,
-    command: lifecycleGateCommand(opts.todosProjectPath, opts.taskId, opts.stage, opts.goMarker, opts.blockedMarker),
+    command: lifecycleGateCommand(opts.todosProjectPath, opts.taskId, opts.stage, opts.goMarker, opts.blockedMarker, opts.todosDbPath),
     cwd: opts.plan.originalCwd,
     timeoutMs: 2 * 60000,
     blockedExitCodes: GATE_BLOCKED_EXIT_CODES
@@ -9369,7 +9419,7 @@ function lifecycleGateStep(opts) {
 function prHandoffArtifactPath(plan, taskId) {
   return join7(plan.cwd, ".openloops", "pr-handoff", `${slugSegment(taskId, "task")}.json`);
 }
-function prHandoffStep(input, plan, todosProjectPath) {
+function prHandoffStep(input, plan, todosProjectPath, todosDbPath) {
   return commandStep({
     id: "pr-handoff",
     name: "PR Handoff",
@@ -9379,6 +9429,7 @@ function prHandoffStep(input, plan, todosProjectPath) {
       artifactPath: prHandoffArtifactPath(plan, input.taskId),
       taskId: input.taskId,
       todosProjectPath,
+      todosDbPath,
       worktreeCwd: plan.cwd,
       worktreeRoot: plan.path ?? plan.cwd,
       expectedBranch: plan.branch ?? ""
@@ -9465,6 +9516,7 @@ function renderTodosTaskWorkerVerifierWorkflow(input) {
   if (!input.projectPath?.trim())
     throw new Error("projectPath is required");
   const todosProjectPath = input.todosProjectPath ?? input.routeProjectPath ?? input.projectPath;
+  const todosDbPath = input.todosDbPath;
   const plan = worktreePlan(input, input.taskId);
   const taskContext = {
     taskId: input.taskId,
@@ -9475,15 +9527,17 @@ function renderTodosTaskWorkerVerifierWorkflow(input) {
     projectPath: input.projectPath,
     routeProjectPath: input.routeProjectPath,
     projectGroup: input.projectGroup,
+    todosProjectPath: input.todosProjectPath ?? (input.todosDbPath ? todosProjectPath : undefined),
+    todosDbPath,
     worktree: worktreeContextFragment(plan)
   };
   const workerPrompt = [
     ...goalHeaderFragment(`Complete todos task ${input.taskId} in ${input.projectPath}.`, "worker", "task"),
     worktreePrompt(plan),
     ...todosExactCommandsFragment(todosProjectPath, input.taskId, [
-      todosStartLine(todosProjectPath, input.taskId),
-      todosEvidenceLine(todosProjectPath, input.taskId, "concise evidence and blockers")
-    ]),
+      todosStartLine(todosProjectPath, input.taskId, todosDbPath),
+      todosEvidenceLine(todosProjectPath, input.taskId, "concise evidence and blockers", todosDbPath)
+    ], todosDbPath),
     "Investigate first before changing files. Use the todos CLI as the source of truth for the task.",
     "Inspect the repository/project state, implement only the task scope, run focused validation, preserve unrelated user changes, and update the task with comments, evidence, changed files, commits, and blockers.",
     NO_TMUX_DISPATCH_FRAGMENT,
@@ -9496,9 +9550,9 @@ function renderTodosTaskWorkerVerifierWorkflow(input) {
     ...goalHeaderFragment(`Verify todos task ${input.taskId} after the worker step.`, "verifier", "task"),
     worktreePrompt(plan),
     ...todosExactCommandsFragment(todosProjectPath, input.taskId, [
-      todosVerificationLine(todosProjectPath, input.taskId),
-      todosDoneLine(todosProjectPath, input.taskId)
-    ]),
+      todosVerificationLine(todosProjectPath, input.taskId, todosDbPath),
+      todosDoneLine(todosProjectPath, input.taskId, todosDbPath)
+    ], todosDbPath),
     adversarialReviewFragment("the task, repository state, commits, tests, and worker evidence", TASK_REVIEW_FOCUS),
     verifierRuntimeGuidance(input),
     TASK_VERIFIER_DECISION_FRAGMENT,
@@ -9513,7 +9567,7 @@ function renderTodosTaskWorkerVerifierWorkflow(input) {
     description: `Task-triggered worker/verifier workflow for ${taskLabel(input)}`,
     version: 1,
     steps: [
-      sourceTaskGateStep(todosProjectPath, input.taskId, plan, "Fail before worker execution when the source todos task is not resolvable."),
+      sourceTaskGateStep(todosProjectPath, input.taskId, plan, "Fail before worker execution when the source todos task is not resolvable.", todosDbPath),
       ...workerVerifierSteps({
         input,
         seed: input.taskId,
@@ -9533,6 +9587,7 @@ function renderTaskLifecycleWorkflow(input) {
   if (!input.projectPath?.trim())
     throw new Error("projectPath is required");
   const todosProjectPath = input.todosProjectPath ?? input.routeProjectPath ?? input.projectPath;
+  const todosDbPath = input.todosDbPath;
   const plan = worktreePlan(input, input.taskId);
   const taskContext = {
     taskId: input.taskId,
@@ -9544,6 +9599,7 @@ function renderTaskLifecycleWorkflow(input) {
     routeProjectPath: input.routeProjectPath,
     projectGroup: input.projectGroup,
     todosProjectPath,
+    todosDbPath,
     worktree: worktreeContextFragment(plan)
   };
   const handoffArtifactPath = prHandoffArtifactPath(plan, input.taskId);
@@ -9557,8 +9613,8 @@ function renderTaskLifecycleWorkflow(input) {
   const shared = [
     worktreePrompt(plan),
     ...todosExactCommandsFragment(todosProjectPath, input.taskId, [
-      todosEvidenceLine(todosProjectPath, input.taskId, "concise evidence, decision, or blocker")
-    ]),
+      todosEvidenceLine(todosProjectPath, input.taskId, "concise evidence, decision, or blocker", todosDbPath)
+    ], todosDbPath),
     NO_TMUX_DISPATCH_FRAGMENT,
     "Preserve unrelated user changes and keep scope tied to the task acceptance criteria.",
     "",
@@ -9567,7 +9623,7 @@ function renderTaskLifecycleWorkflow(input) {
   ].join(`
 `);
   const gateMarker = (stage, state) => `openloops:${stage}=${state} task=${input.taskId}${input.eventId ? ` event=${input.eventId}` : ""}`;
-  const blockTaskCommand = `todos --project ${todosProjectPath} update ${input.taskId} --status blocked`;
+  const blockTaskCommand = `${todosEnvPrefix(todosDbPath)}todos --project ${todosProjectPath} update ${input.taskId} --status blocked`;
   const gateStopFragment = (stage, stops) => `The deterministic ${stage} gate will stop ${stops} unless the latest ${stage} marker is the exact go marker and the task has no blocked/completed/done/cancelled/failed/archived/no-auto/manual/approval-required state.`;
   const triagePrompt = [
     ...goalHeaderFragment(`Triage todos task ${input.taskId} for safe automated execution.`, "triage", "lifecycle"),
@@ -9595,7 +9651,7 @@ function renderTaskLifecycleWorkflow(input) {
   const workerPrompt = [
     ...goalHeaderFragment(`Complete todos task ${input.taskId} according to the planner evidence.`, "worker", "lifecycle"),
     shared,
-    todosStartLine(todosProjectPath, input.taskId),
+    todosStartLine(todosProjectPath, input.taskId, todosDbPath),
     "Read the triage and planner comments first. Implement only the scoped task, run focused validation, and record changed files, commits, evidence, blockers, and residual risks.",
     input.prHandoff ? `When only GitHub network access is blocked after a successful commit/validation, record the handoff artifact at ${handoffArtifactPath} instead of repeatedly retrying push/PR creation.` : undefined,
     WORKER_LEAVES_COMPLETION_FRAGMENT
@@ -9604,8 +9660,8 @@ function renderTaskLifecycleWorkflow(input) {
   const verifierPrompt = [
     ...goalHeaderFragment(`Verify todos task ${input.taskId} after the full lifecycle worker step.`, "verifier", "lifecycle"),
     shared,
-    todosVerificationLine(todosProjectPath, input.taskId),
-    todosDoneLine(todosProjectPath, input.taskId),
+    todosVerificationLine(todosProjectPath, input.taskId, todosDbPath),
+    todosDoneLine(todosProjectPath, input.taskId, todosDbPath),
     adversarialReviewFragment("triage, plan, worker evidence, repo state, commits, tests, and acceptance criteria", TASK_REVIEW_FOCUS),
     verifierRuntimeGuidance(input),
     input.prHandoff ? `If ${handoffArtifactPath} exists and there is no PR URL evidence, verify that the PR handoff step queued or completed a bounded handoff; leave the original task open or blocked until PR evidence is recorded.` : undefined,
@@ -9614,7 +9670,7 @@ function renderTaskLifecycleWorkflow(input) {
   ].filter(Boolean).join(`
 `);
   const steps = [
-    sourceTaskGateStep(todosProjectPath, input.taskId, plan, "Fail before lifecycle agents execute when the source todos task is not resolvable."),
+    sourceTaskGateStep(todosProjectPath, input.taskId, plan, "Fail before lifecycle agents execute when the source todos task is not resolvable.", todosDbPath),
     {
       id: "triage",
       name: "Triage",
@@ -9628,6 +9684,7 @@ function renderTaskLifecycleWorkflow(input) {
       description: "Stop the lifecycle before planning when triage blocked or disallowed automation.",
       dependsOn: ["triage"],
       todosProjectPath,
+      todosDbPath,
       taskId: input.taskId,
       goMarker: gateMarker("triage", "go"),
       blockedMarker: gateMarker("triage", "blocked"),
@@ -9646,6 +9703,7 @@ function renderTaskLifecycleWorkflow(input) {
       description: "Stop the lifecycle before implementation when planning blocked or disallowed automation.",
       dependsOn: ["planner"],
       todosProjectPath,
+      todosDbPath,
       taskId: input.taskId,
       goMarker: gateMarker("planner", "go"),
       blockedMarker: gateMarker("planner", "blocked"),
@@ -9661,7 +9719,7 @@ function renderTaskLifecycleWorkflow(input) {
     }
   ];
   if (input.prHandoff) {
-    steps.push(prHandoffStep(input, plan, todosProjectPath));
+    steps.push(prHandoffStep(input, plan, todosProjectPath, todosDbPath));
   }
   steps.push({
     id: "verifier",
@@ -9886,6 +9944,7 @@ function renderLifecycleBoundedTemplate(id, values) {
       taskTitle: values.taskTitle,
       taskDescription: values.taskDescription,
       todosProjectPath: values.todosProjectPath ?? values.todosProject,
+      todosDbPath: values.todosDbPath,
       triageAuthProfile: values.triageAuthProfile,
       plannerAuthProfile: values.plannerAuthProfile,
       triageAccount: accountVar(values.triageAccount, values.accountTool),
@@ -9950,6 +10009,7 @@ function renderBuiltinLoopTemplate(id, values) {
       taskTitle: values.taskTitle,
       taskDescription: values.taskDescription,
       todosProjectPath: values.todosProjectPath ?? values.todosProject,
+      todosDbPath: values.todosDbPath,
       eventId: values.eventId,
       eventType: values.eventType
     });
@@ -10397,7 +10457,8 @@ function writeRouteEvidence(kind, value, evidenceDir) {
   mkdirSync9(evidenceDir, { recursive: true, mode: 448 });
   const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\./g, "");
   const evidencePath = join9(evidenceDir, `${kind}-${stamp}-${randomUUID().slice(0, 8)}.json`);
-  writeFileSync5(evidencePath, JSON.stringify(value, null, 2), { mode: 384, flag: "wx" });
+  const encoded = scrubSecrets(JSON.stringify(scrubSecretsDeep(value), null, 2));
+  writeFileSync5(evidencePath, encoded, { mode: 384, flag: "wx" });
   return evidencePath;
 }
 function selectRouteItems(items, maxActions, cursorKey, fingerprintOf) {
@@ -10993,6 +11054,70 @@ function todosTaskRouteTemplateId(opts) {
   }
   return id;
 }
+function sourceCandidateRecords(data, metadata) {
+  const records = [data, metadata];
+  for (const record of [data, metadata]) {
+    const sourceTask = objectField2(record.source_task) ?? objectField2(record.sourceTask);
+    if (sourceTask)
+      records.push(sourceTask);
+  }
+  return records;
+}
+function sourceStringField(records, keys) {
+  for (const record of records) {
+    for (const key of keys) {
+      const value = stringField2(record[key]);
+      if (value)
+        return value;
+    }
+  }
+  return;
+}
+function sourceBooleanField(records, keys) {
+  for (const record of records) {
+    for (const key of keys) {
+      const value = record[key];
+      if (typeof value === "boolean")
+        return value;
+      if (value === "true" || value === "1" || value === 1)
+        return true;
+      if (value === "false" || value === "0" || value === 0)
+        return false;
+    }
+  }
+  return;
+}
+function todosTaskSourceRef(data, metadata, taskId) {
+  const records = sourceCandidateRecords(data, metadata);
+  const sourceTaskKey = sourceStringField(records, ["source_task_key", "sourceTaskKey"]);
+  const sourceStoreId = sourceStringField(records, ["source_store_id", "sourceStoreId"]);
+  const sourceRepoPath = sourceStringField(records, ["source_repo_path", "sourceRepoPath"]);
+  const sourceDbPath = sourceStringField(records, ["source_db_path", "sourceDbPath"]);
+  const sourceSelectedByInput = sourceBooleanField(records, ["source_selected_by_input", "sourceSelectedByInput"]);
+  const idempotencySource = sourceTaskKey ? "source_task_key" : sourceStoreId ? "source_store_id" : "legacy_task_id";
+  return {
+    sourceTaskKey,
+    sourceStoreId,
+    sourceRepoPath,
+    sourceDbPath,
+    sourceSelectedByInput,
+    idempotencySource,
+    idempotencyKey: sourceTaskKey ? `todos-task:${sourceTaskKey}` : sourceStoreId ? `todos-task:${sourceStoreId}:${taskId}` : `todos-task:${taskId}`
+  };
+}
+function publicSourceTask(sourceTask) {
+  if (!sourceTask.sourceTaskKey && !sourceTask.sourceStoreId && !sourceTask.sourceRepoPath && !sourceTask.sourceDbPath && sourceTask.sourceSelectedByInput === undefined) {
+    return;
+  }
+  return {
+    source_task_key: sourceTask.sourceTaskKey,
+    source_store_id: sourceTask.sourceStoreId,
+    source_repo_path: sourceTask.sourceRepoPath,
+    source_db_path: sourceTask.sourceDbPath,
+    source_selected_by_input: sourceTask.sourceSelectedByInput,
+    idempotency_source: sourceTask.idempotencySource
+  };
+}
 async function readEventEnvelopeInput(opts = {}) {
   const raw = opts.eventJson ?? (opts.eventFile ? readFileSync8(opts.eventFile, "utf8") : process.env.HASNA_EVENT_JSON || await Bun.stdin.text());
   const event = JSON.parse(raw);
@@ -11169,11 +11294,13 @@ function routeTodosTaskEvent(event, opts) {
   const taskId = taskEventField(data, ["id", "task_id", "taskId"]);
   if (!taskId)
     throw new ValidationError("todos task event is missing task id in data.id, data.task_id, data.task.id, or data.payload.id");
+  const sourceTask = todosTaskSourceRef(data, metadata, taskId);
+  const sourceTaskPublic = publicSourceTask(sourceTask);
   const eligibility = taskRouteEligibility(data, metadata);
   if (!eligibility.eligible) {
     return {
       kind: "skipped",
-      value: { skipped: true, reason: eligibility.reason, event, taskId, eligibility },
+      value: { skipped: true, reason: eligibility.reason, event, taskId, eligibility, sourceTask: sourceTaskPublic },
       human: `skipped task ${taskId}: ${eligibility.reason}`
     };
   }
@@ -11188,11 +11315,11 @@ function routeTodosTaskEvent(event, opts) {
     "project_canonical_path",
     "cwd"
   ]);
-  const projectPath = dataProjectPath ?? metadataProjectPath ?? opts.projectPath ?? process.cwd();
+  const projectPath = dataProjectPath ?? metadataProjectPath ?? sourceTask.sourceRepoPath ?? opts.projectPath ?? process.cwd();
   const routeProjectPath = normalizeRoutePath(projectPath) ?? resolve7(projectPath);
   const projectGroup = routeProjectGroup(opts.projectGroup, data, metadata);
   const throttleLimits = routeThrottleLimitsFromOpts(opts);
-  const idempotencyKey = `todos-task:${taskId}`;
+  const idempotencyKey = sourceTask.idempotencyKey;
   const idempotencySuffix = stableSuffix(idempotencyKey);
   const namePrefix = opts.namePrefix ?? "event:todos-task";
   const workflowName = `${namePrefix}:${taskId.slice(0, 8)}:${idempotencySuffix}:workflow`;
@@ -11205,7 +11332,7 @@ function routeTodosTaskEvent(event, opts) {
         const existingLoop = existingItem.loopId ? store.getLoop(existingItem.loopId) : undefined;
         const existingWorkflow = existingItem.workflowId ? store.getWorkflow(existingItem.workflowId) : undefined;
         const existingInvocation = store.getWorkflowInvocation(existingItem.invocationId);
-        return dedupedRoutePrint({ event, idempotencyKey, dedupeValueExtras: {} }, { existingItem, existingLoop, existingWorkflow, invocation: existingInvocation });
+        return dedupedRoutePrint({ event, idempotencyKey, dedupeValueExtras: sourceTaskPublic ? { sourceTask: sourceTaskPublic } : {} }, { existingItem, existingLoop, existingWorkflow, invocation: existingInvocation });
       }
     } finally {
       store.close();
@@ -11268,12 +11395,14 @@ function routeTodosTaskEvent(event, opts) {
     prHandoff: templateId === TASK_LIFECYCLE_TEMPLATE_ID ? Boolean(opts.prHandoff) : false,
     eventId: event.id,
     eventType: event.type,
-    todosProjectPath: opts.todosProject
+    todosProjectPath: sourceTask.sourceRepoPath ?? opts.todosProject,
+    todosDbPath: sourceTask.sourceDbPath
   };
   const workflowContext = {
     name: workflowName,
     type: "todos-task-event-workflow",
-    event: event.id
+    event: event.id,
+    sourceTask: sourceTaskPublic
   };
   let workflowBody = templateId === TASK_LIFECYCLE_TEMPLATE_ID ? renderTaskLifecycleWorkflow(workflowInput) : renderTodosTaskWorkerVerifierWorkflow(workflowInput);
   workflowBody.name = workflowName;
@@ -11286,13 +11415,13 @@ function routeTodosTaskEvent(event, opts) {
       kind: "event",
       id: event.id,
       dedupeKey: idempotencyKey,
-      raw: { type: event.type, source: event.source, subject: event.subject }
+      raw: { type: event.type, source: event.source, subject: event.subject, sourceTask: sourceTaskPublic }
     },
     subjectRef: {
       kind: "task",
       id: taskId,
       path: routeProjectPath,
-      raw: { title: taskTitle, description: taskDescription }
+      raw: { title: taskTitle, description: taskDescription, sourceTask: sourceTaskPublic }
     },
     intent: "route",
     scope: {
@@ -11305,7 +11434,8 @@ function routeTodosTaskEvent(event, opts) {
       accountPolicy: providerRouting.authProfilePool?.length || providerRouting.accountPool?.length ? "pool" : hasExplicitRoleAccount ? "role-explicit" : "single",
       providerRouting: providerRoutingPublic(providerRouting),
       prReviewRouting: prReviewRouting.required ? prReviewRouting : undefined,
-      concurrencyGroup: projectGroup ?? routeProjectPath
+      concurrencyGroup: projectGroup ?? routeProjectPath,
+      sourceTask: sourceTaskPublic
     },
     outputPolicy: {
       report: "always",
@@ -11330,9 +11460,10 @@ function routeTodosTaskEvent(event, opts) {
     humanSubject: `task ${taskId}`,
     valueExtras: {
       providerRouting: providerRoutingPublic(providerRouting),
-      prReviewRouting: prReviewRouting.required ? prReviewRouting : undefined
+      prReviewRouting: prReviewRouting.required ? prReviewRouting : undefined,
+      sourceTask: sourceTaskPublic
     },
-    dedupeValueExtras: {}
+    dedupeValueExtras: sourceTaskPublic ? { sourceTask: sourceTaskPublic } : {}
   });
 }
 function routeGenericEvent(event, opts) {
@@ -11469,7 +11600,7 @@ function runLocalCommand(command, args, opts = {}) {
     encoding: "utf8",
     timeout: opts.timeoutMs ?? 30000,
     maxBuffer: opts.maxBuffer ?? 8 * 1024 * 1024,
-    env: process.env
+    env: { ...process.env, ...opts.env }
   });
   return {
     ok: result.status === 0,
@@ -11536,8 +11667,66 @@ function taskField(task, keys) {
   }
   return;
 }
-function taskListId(task) {
-  return taskField(task, ["task_list_id", "taskListId"]) ?? stringField2(task.task_list?.id);
+function booleanTaskField(task, keys) {
+  for (const key of keys) {
+    const value = task[key];
+    if (typeof value === "boolean")
+      return value;
+    if (value === "true" || value === "1" || value === 1)
+      return true;
+    if (value === "false" || value === "0" || value === 0)
+      return false;
+  }
+  return;
+}
+function normalizedSourceRoots(opts) {
+  return listFromRepeatedOpts(opts.todosSourceRoot) ?? [];
+}
+function normalizedSourceStores(opts) {
+  return listFromRepeatedOpts(opts.todosSourceStore) ?? [];
+}
+function normalizedSourceIncludes(opts) {
+  return listFromRepeatedOpts(opts.todosSourceInclude) ?? [];
+}
+function normalizedSourceExcludes(opts) {
+  return listFromRepeatedOpts(opts.todosSourceExclude) ?? [];
+}
+function hasTodosSourceOptions(opts) {
+  return Boolean(normalizedSourceRoots(opts).length || normalizedSourceStores(opts).length || normalizedSourceIncludes(opts).length || normalizedSourceExcludes(opts).length);
+}
+function taskSourceIdentity(task, taskId) {
+  const sourceTaskKey = taskField(task, ["source_task_key", "sourceTaskKey"]);
+  const sourceStoreId = taskField(task, ["source_store_id", "sourceStoreId"]);
+  const identity = sourceTaskKey ?? (sourceStoreId && taskId ? `${sourceStoreId}:${taskId}` : undefined);
+  return {
+    sourceTaskKey,
+    sourceStoreId,
+    sourceRepoPath: taskField(task, ["source_repo_path", "sourceRepoPath"]),
+    sourceDbPath: taskField(task, ["source_db_path", "sourceDbPath"]),
+    sourceSelectedByInput: booleanTaskField(task, ["source_selected_by_input", "sourceSelectedByInput"]),
+    idempotencyIdentity: identity
+  };
+}
+function publicSourceTaskIdentity(source) {
+  if (!source.sourceTaskKey && !source.sourceStoreId && !source.sourceRepoPath && !source.sourceDbPath && source.sourceSelectedByInput === undefined) {
+    return;
+  }
+  return {
+    source_task_key: source.sourceTaskKey,
+    source_store_id: source.sourceStoreId,
+    source_repo_path: source.sourceRepoPath,
+    source_db_path: source.sourceDbPath,
+    source_selected_by_input: source.sourceSelectedByInput
+  };
+}
+function taskListValues(task) {
+  const values = [
+    taskField(task, ["task_list_id", "taskListId", "task_list_slug", "taskListSlug", "task_list_name", "taskListName"]),
+    stringField2(task.task_list?.id),
+    stringField2(task.task_list?.slug),
+    stringField2(task.task_list?.name)
+  ].filter((value) => Boolean(value));
+  return [...new Set(values)];
 }
 function taskProjectId(task) {
   return taskField(task, ["project_id", "projectId"]);
@@ -11551,12 +11740,14 @@ function taskProjectPath(task) {
   const metadata = objectField2(task.metadata) ?? {};
   return taskField(task, ["project_path", "projectPath"]) ?? taskEventField(metadata, ["project_path", "projectPath", "project_canonical_path"]) ?? taskDescriptionProjectPath(task) ?? taskField(task, ["working_dir", "workingDir", "cwd"]) ?? taskEventField(metadata, ["working_dir", "workingDir", "cwd"]);
 }
-function taskDrainEvent(task) {
+function taskDrainEvent(task, opts = {}) {
   const taskId = taskField(task, ["id", "task_id", "taskId"]);
   if (!taskId)
     throw new Error("todos ready returned a task without an id");
   const metadata = objectField2(task.metadata) ?? {};
   const workingDir = taskProjectPath(task);
+  const sourceIdentity = taskSourceIdentity(task, taskId);
+  const sourceTask = publicSourceTaskIdentity(sourceIdentity);
   const data = {
     ...task,
     id: taskId,
@@ -11566,14 +11757,21 @@ function taskDrainEvent(task) {
     tags: tagsFromValue2(task.tags),
     metadata
   };
+  if (opts.sourceRouteEligible) {
+    data.route_enabled = true;
+    data.route_enabled_by = "source_route_state";
+  }
   if (workingDir) {
     data.working_dir = workingDir;
     data.project_path = taskField(task, ["project_path", "projectPath"]) ?? workingDir;
     data.cwd = taskField(task, ["cwd"]) ?? workingDir;
   }
+  if (sourceTask)
+    data.source_task = sourceTask;
+  const eventId = sourceIdentity.idempotencyIdentity ? `drain-todos-task-${slugSegment2(taskId, "task")}-${stableSuffix(sourceIdentity.idempotencyIdentity)}` : `drain-todos-task-${taskId}`;
   const time = new Date().toISOString();
   return {
-    id: `drain-todos-task-${taskId}`,
+    id: eventId,
     type: "task.created",
     source: "@hasna/todos",
     subject: taskId,
@@ -11584,6 +11782,8 @@ function taskDrainEvent(task) {
     metadata: {
       ...metadata,
       ...workingDir ? { working_dir: workingDir, project_path: data.project_path, cwd: data.cwd } : {},
+      ...sourceTask,
+      ...sourceTask ? { source_task: sourceTask } : {},
       drained_by: "@hasna/loops",
       drained_from: "todos ready"
     }
@@ -11592,6 +11792,7 @@ function taskDrainEvent(task) {
 function compactDrainResult(result) {
   const value = result.value;
   const event = objectField2(value.event);
+  const sourceTask = objectField2(value.sourceTask) ?? objectField2(objectField2(event?.metadata)?.source_task) ?? objectField2(objectField2(event?.data)?.source_task);
   const loop = objectField2(value.loop);
   const workflow = objectField2(value.workflow);
   const throttle = objectField2(value.throttle);
@@ -11608,26 +11809,75 @@ function compactDrainResult(result) {
     workflowId: stringField2(workflow?.id),
     workflowName: stringField2(workflow?.name),
     providerRouting,
+    sourceTask,
     requeue,
     queuedAtSource: value.queuedAtSource
   };
 }
-function loadReadyTodosTasks(opts, scanLimit) {
-  const todosProject = opts.todosProject ?? defaultLoopsProject();
-  const args = ["--project", todosProject, "--json", "ready", "--limit", String(scanLimit)];
-  const result = runLocalCommandWithStdoutFile("todos", args, { timeoutMs: 60000, maxBuffer: 64 * 1024 * 1024 });
-  if (!result.ok)
-    throw new Error(result.stderr || result.error || "todos ready failed");
-  let parsed;
+function numberField2(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function parseTodosReadyJson(stdout) {
   try {
-    parsed = JSON.parse(result.stdout || "[]");
+    return JSON.parse(stdout || "[]");
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    throw new Error(`failed to parse todos ready --json output (${result.stdout.length} bytes): ${message}`);
-  }
-  if (!Array.isArray(parsed))
-    throw new Error("todos ready --json returned a non-array value");
-  return parsed;
+    throw new Error(`failed to parse todos ready --json output (${stdout.length} bytes): ${message}`);
+  }
+}
+function loadReadyTodosTasks(opts, scanLimit, sourceMode) {
+  const sourceRoots = normalizedSourceRoots(opts);
+  const sourceStores = normalizedSourceStores(opts);
+  const sourceIncludes = normalizedSourceIncludes(opts);
+  const sourceExcludes = normalizedSourceExcludes(opts);
+  if (sourceMode && !sourceRoots.length && !sourceStores.length) {
+    throw new ValidationError("source discovery requires at least one --todos-source-root or --todos-source-store");
+  }
+  const args = sourceMode ? ["--json", "ready"] : ["--project", opts.todosProject ?? defaultLoopsProject(), "--json", "ready"];
+  if (sourceMode) {
+    for (const root of sourceRoots)
+      args.push("--source-root", root);
+    for (const store of sourceStores)
+      args.push("--source-store", store);
+    for (const pattern of sourceIncludes)
+      args.push("--include", pattern);
+    for (const pattern of sourceExcludes)
+      args.push("--exclude", pattern);
+  }
+  args.push("--limit", String(scanLimit));
+  const result = runLocalCommandWithStdoutFile("todos", args, { timeoutMs: 60000, maxBuffer: 64 * 1024 * 1024 });
+  if (!result.ok)
+    throw new Error(result.stderr || result.error || "todos ready failed");
+  const parsed = parseTodosReadyJson(result.stdout);
+  if (!sourceMode) {
+    if (!Array.isArray(parsed))
+      throw new Error("todos ready --json returned a non-array value");
+    return { tasks: parsed, sourceMode, sourceRoots, sourceStores, sourceIncludes, sourceExcludes };
+  }
+  const response = objectField2(parsed);
+  if (!response)
+    throw new Error("todos ready --json source discovery returned a non-object value");
+  if (response.schema_version !== "todos.task_route_sources.v1") {
+    throw new Error(`todos ready source discovery returned unsupported schema_version: ${String(response.schema_version)}`);
+  }
+  if (!Array.isArray(response.candidates))
+    throw new Error("todos ready source discovery returned missing candidates array");
+  return {
+    tasks: response.candidates,
+    sourceMode,
+    sourceRoots,
+    sourceStores,
+    sourceIncludes,
+    sourceExcludes,
+    sourceDiscovery: {
+      schemaVersion: "todos.task_route_sources.v1",
+      stores: Array.isArray(response.stores) ? response.stores : undefined,
+      errors: Array.isArray(response.errors) ? response.errors : undefined,
+      totalCandidateCount: numberField2(response.total_candidate_count),
+      returnedCandidateCount: numberField2(response.returned_candidate_count),
+      truncated: typeof response.truncated === "boolean" ? response.truncated : undefined
+    }
+  };
 }
 function resolveTaskListFilter(todosProject, filter) {
   const wanted = filter?.trim();
@@ -11643,7 +11893,7 @@ function resolveTaskListFilter(todosProject, filter) {
 function taskMatchesDrainFilters(task, filters) {
   if (filters.projectId && taskProjectId(task) !== filters.projectId)
     return false;
-  if (filters.taskListId && taskListId(task) !== filters.taskListId)
+  if (filters.taskList && !taskListValues(task).includes(filters.taskList))
     return false;
   if (filters.projectPathPrefix) {
     const path = taskProjectPath(task);
@@ -11681,19 +11931,77 @@ function skippedDrainTask(task, event, reason, extra = {}) {
 function isSkippableDrainRouteError(message) {
   return message.startsWith("worktreeMode=required but projectPath is not an existing git repository:");
 }
-function markInvalidDrainTaskNonRouteable(todosProject, task, reason) {
+function sourceRouteState(task) {
+  return objectField2(task.route_state) ?? objectField2(task.routeState);
+}
+function sourceRouteReason(routeState) {
+  const reasons = routeState?.reasons;
+  const firstReason = Array.isArray(reasons) ? stringField2(reasons[0]) : undefined;
+  return stringField2(routeState?.reason) ?? stringField2(routeState?.eligibility_reason) ?? stringField2(routeState?.eligibilityReason) ?? firstReason;
+}
+function sourceRouteEligibility(task) {
+  const routeState = sourceRouteState(task);
+  if (routeState?.eligible === true)
+    return { eligible: true, routeState };
+  const reason = sourceRouteReason(routeState) ?? "source route_state.eligible is not true";
+  return { eligible: false, reason, routeState };
+}
+function sourceTaskMutationTarget(todosProject, task, opts = {}) {
+  const source = taskSourceIdentity(task, taskField(task, ["id", "task_id", "taskId"]));
+  if (source.sourceDbPath) {
+    return {
+      argsPrefix: source.sourceRepoPath ? ["--project", source.sourceRepoPath] : [],
+      env: {
+        TODOS_DB_PATH: source.sourceDbPath,
+        HASNA_TODOS_DB_PATH: source.sourceDbPath
+      },
+      project: source.sourceRepoPath,
+      sourceDbPath: source.sourceDbPath,
+      sourceRepoPath: source.sourceRepoPath,
+      sourceStoreId: source.sourceStoreId
+    };
+  }
+  if (source.sourceRepoPath) {
+    return {
+      argsPrefix: ["--project", source.sourceRepoPath],
+      project: source.sourceRepoPath,
+      sourceRepoPath: source.sourceRepoPath,
+      sourceStoreId: source.sourceStoreId
+    };
+  }
+  if (opts.sourceMode)
+    return;
+  const project = todosProject ?? defaultLoopsProject();
+  return { argsPrefix: ["--project", project], project };
+}
+function markInvalidDrainTaskNonRouteable(todosProject, task, reason, opts = {}) {
   const taskId = taskField(task, ["id", "task_id", "taskId"]);
   if (!taskId)
     return { attempted: false, reason: "task id missing" };
   const comment = `OpenLoops route blocked for task ${taskId}: ${reason}. Added no-auto and removed auto:route so route drains do not repeatedly route this task until its project path is fixed.`;
-  const commentResult = runLocalCommand("todos", ["--project", todosProject, "comment", taskId, comment], { timeoutMs: 30000 });
-  const tagResult = runLocalCommand("todos", ["--project", todosProject, "tag", taskId, "no-auto"], { timeoutMs: 30000 });
-  const untagResult = runLocalCommand("todos", ["--project", todosProject, "untag", taskId, "auto:route"], { timeoutMs: 30000 });
+  const target = sourceTaskMutationTarget(todosProject, task, { sourceMode: opts.sourceMode });
+  if (!target) {
+    return {
+      attempted: false,
+      taskId,
+      reason: "source task missing source_db_path or source_repo_path; refusing to update router/default Todos store"
+    };
+  }
+  const commentResult = runLocalCommand("todos", [...target.argsPrefix, "comment", taskId, comment], { timeoutMs: 30000, env: target.env });
+  const tagResult = runLocalCommand("todos", [...target.argsPrefix, "tag", taskId, "no-auto"], { timeoutMs: 30000, env: target.env });
+  const untagResult = runLocalCommand("todos", [...target.argsPrefix, "untag", taskId, "auto:route"], { timeoutMs: 30000, env: target.env });
   const ok = commentResult.ok && tagResult.ok && untagResult.ok;
   return {
     ok,
     attempted: true,
     taskId,
+    target: {
+      project: target.project,
+      source_db_path: target.sourceDbPath,
+      source_repo_path: target.sourceRepoPath,
+      source_store_id: target.sourceStoreId,
+      used_db_env: Boolean(target.sourceDbPath)
+    },
     error: ok ? undefined : "one or more source task updates failed; inspect per-command results",
     comment: todosMutationSummary(commentResult),
     tagNoAuto: todosMutationSummary(tagResult),
@@ -11702,17 +12010,19 @@ function markInvalidDrainTaskNonRouteable(todosProject, task, reason) {
 }
 function drainTodosTaskRoutes(opts) {
   const maxDispatch = positiveInteger(opts.maxDispatch ?? "1", "--max-dispatch") ?? 1;
-  const todosProject = opts.todosProject ?? defaultLoopsProject();
+  const sourceMode = hasTodosSourceOptions(opts);
+  const todosProject = sourceMode ? opts.todosProject : opts.todosProject ?? defaultLoopsProject();
   const requiredTags = splitList(opts.tags ?? opts.tag) ?? [];
-  const taskListFilter = resolveTaskListFilter(todosProject, opts.taskList);
+  const taskListFilter = sourceMode ? opts.taskList?.trim() : resolveTaskListFilter(todosProject ?? defaultLoopsProject(), opts.taskList);
   const candidateLimit = positiveInteger(opts.limit ?? "50", "--limit") ?? 50;
   const hasPostFilters = Boolean(opts.todosProjectId || taskListFilter || opts.projectPathPrefix || requiredTags.length);
   const defaultScanLimit = hasPostFilters ? Math.max(candidateLimit, 500) : candidateLimit;
   const scanLimit = positiveInteger(opts.scanLimit ?? String(defaultScanLimit), "--scan-limit") ?? defaultScanLimit;
-  const ready = loadReadyTodosTasks(opts, scanLimit);
+  const loaded = loadReadyTodosTasks(opts, scanLimit, sourceMode);
+  const ready = loaded.tasks;
   const filteredCandidates = ready.filter((task) => taskMatchesDrainFilters(task, {
     projectId: opts.todosProjectId,
-    taskListId: taskListFilter,
+    taskList: taskListFilter,
     projectPathPrefix: opts.projectPathPrefix,
     tags: requiredTags
   }));
@@ -11725,13 +12035,25 @@ function drainTodosTaskRoutes(opts) {
     let event;
     let result;
     try {
-      event = taskDrainEvent(task);
+      let sourceEligibility;
+      if (sourceMode) {
+        sourceEligibility = sourceRouteEligibility(task);
+        if (!sourceEligibility.eligible) {
+          result = skippedDrainTask(task, undefined, sourceEligibility.reason ?? "source route_state.eligible is not true", {
+            sourceRouteState: sourceEligibility.routeState,
+            sourceTask: publicSourceTaskIdentity(taskSourceIdentity(task, taskField(task, ["id", "task_id", "taskId"])))
+          });
+          results.push(result);
+          continue;
+        }
+      }
+      event = taskDrainEvent(task, { sourceRouteEligible: sourceEligibility?.eligible === true });
       result = routeTodosTaskEvent(event, opts);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       if (!isSkippableDrainRouteError(message))
         throw error;
-      const sourceTaskUpdate = opts.dryRun ? { attempted: false, reason: "dry-run" } : markInvalidDrainTaskNonRouteable(todosProject, task, message);
+      const sourceTaskUpdate = opts.dryRun ? { attempted: false, reason: "dry-run" } : markInvalidDrainTaskNonRouteable(todosProject, task, message, { sourceMode });
       result = skippedDrainTask(task, event, redact(message, 640) ?? "route task failed", { sourceTaskUpdate });
     }
     results.push(result);
@@ -11741,6 +12063,12 @@ function drainTodosTaskRoutes(opts) {
   const report = {
     drainedAt: new Date().toISOString(),
     todosProject,
+    sourceMode,
+    sourceRoots: loaded.sourceRoots,
+    sourceStores: loaded.sourceStores,
+    sourceIncludes: loaded.sourceIncludes,
+    sourceExcludes: loaded.sourceExcludes,
+    sourceDiscovery: loaded.sourceDiscovery,
     templateId: todosTaskRouteTemplateId(opts),
     todosProjectId: opts.todosProjectId,
     taskList: opts.taskList,
@@ -11753,14 +12081,14 @@ function drainTodosTaskRoutes(opts) {
     scanned: ready.length,
     candidates: candidates.length,
     filteredCandidates: filteredCandidates.length,
-    scanExhausted: ready.length >= scanLimit && filteredCandidates.length < candidateLimit,
+    scanExhausted: sourceMode ? Boolean(loaded.sourceDiscovery?.truncated) || ready.length >= scanLimit && filteredCandidates.length < candidateLimit : ready.length >= scanLimit && filteredCandidates.length < candidateLimit,
     considered: results.length,
     created: results.filter((result) => result.kind === "created" && !result.value.deduped).length,
     deduped: results.filter((result) => result.kind === "deduped").length,
     throttled: results.filter((result) => result.kind === "throttled").length,
     skipped: results.filter((result) => result.kind === "skipped").length,
     maxDispatch,
-    source: "todos ready",
+    source: sourceMode ? "todos ready source discovery" : "todos ready",
     dryRun: Boolean(opts.dryRun),
     results: results.map((result) => ({ kind: result.kind, ...result.value }))
   };
@@ -11768,6 +12096,12 @@ function drainTodosTaskRoutes(opts) {
   const value = opts.compact ? {
     drainedAt: report.drainedAt,
     todosProject: report.todosProject,
+    sourceMode: report.sourceMode,
+    sourceRoots: report.sourceRoots,
+    sourceStores: report.sourceStores,
+    sourceIncludes: report.sourceIncludes,
+    sourceExcludes: report.sourceExcludes,
+    sourceDiscovery: report.sourceDiscovery,
     templateId: report.templateId,
     todosProjectId: report.todosProjectId,
     taskList: report.taskList,
@@ -11793,7 +12127,7 @@ function drainTodosTaskRoutes(opts) {
     results: results.map(compactDrainResult)
   } : { ...report, evidencePath };
   return {
-    value,
+    value: scrubSecretsDeep(value),
     human: `drained todos ready queue: considered=${report.considered} created=${report.created} deduped=${report.deduped} throttled=${report.throttled} skipped=${report.skipped}`
   };
 }
@@ -12071,6 +12405,34 @@ var EVENT_INPUT_OPTION_SPECS = [
   { flags: "--event-json <json>", key: "eventJson", kind: "value", description: "read event envelope JSON from this string instead of stdin/HASNA_EVENT_JSON" }
 ];
 var DRAIN_FILTER_OPTION_SPECS = [
+  {
+    flags: "--todos-source-root <path>",
+    key: "todosSourceRoot",
+    kind: "repeat",
+    description: "scan todos route candidates discovered under this source root; may be repeated",
+    serializeValue: (opts) => listFromRepeatedOpts(opts.todosSourceRoot)
+  },
+  {
+    flags: "--todos-source-store <path>",
+    key: "todosSourceStore",
+    kind: "repeat",
+    description: "scan this explicit todos source store path; may be repeated",
+    serializeValue: (opts) => listFromRepeatedOpts(opts.todosSourceStore)
+  },
+  {
+    flags: "--todos-source-include <pattern>",
+    key: "todosSourceInclude",
+    kind: "repeat",
+    description: "include source discovery entries matching this pattern; may be repeated",
+    serializeValue: (opts) => listFromRepeatedOpts(opts.todosSourceInclude)
+  },
+  {
+    flags: "--todos-source-exclude <pattern>",
+    key: "todosSourceExclude",
+    kind: "repeat",
+    description: "exclude source discovery entries matching this pattern; may be repeated",
+    serializeValue: (opts) => listFromRepeatedOpts(opts.todosSourceExclude)
+  },
   { flags: "--todos-project-id <id>", key: "todosProjectId", kind: "value", description: "filter todos ready output to one todos project id" },
   { flags: "--task-list <id-or-slug>", key: "taskList", kind: "value", description: "filter ready tasks to one task-list id, slug, or name" },
   { flags: "--project-path-prefix <path>", key: "projectPathPrefix", kind: "value", description: "filter ready tasks to a project/repo path prefix" },