@hasna/loops 0.3.26 → 0.3.27

package/dist/cli/index.js

@@ -418,6 +418,42 @@ function validateTarget(value, label) {
         throw new Error(`${label}.allowlist.enforcement must be metadata_only`);
       }
     }
+    if (value.worktree !== undefined) {
+      assertObject(value.worktree, `${label}.worktree`);
+      assertString(value.worktree.mode, `${label}.worktree.mode`);
+      const modes = ["auto", "required", "off", "main"];
+      if (!modes.includes(value.worktree.mode))
+        throw new Error(`${label}.worktree.mode must be one of ${modes.join(", ")}`);
+      if (typeof value.worktree.enabled !== "boolean")
+        throw new Error(`${label}.worktree.enabled must be a boolean`);
+      assertString(value.worktree.originalCwd, `${label}.worktree.originalCwd`);
+      assertString(value.worktree.cwd, `${label}.worktree.cwd`);
+      if (value.worktree.repoRoot !== undefined)
+        assertString(value.worktree.repoRoot, `${label}.worktree.repoRoot`);
+      if (value.worktree.root !== undefined)
+        assertString(value.worktree.root, `${label}.worktree.root`);
+      if (value.worktree.path !== undefined)
+        assertString(value.worktree.path, `${label}.worktree.path`);
+      if (value.worktree.branch !== undefined)
+        assertString(value.worktree.branch, `${label}.worktree.branch`);
+      if (value.worktree.reason !== undefined)
+        assertString(value.worktree.reason, `${label}.worktree.reason`);
+    }
+    if (value.routing !== undefined) {
+      assertObject(value.routing, `${label}.routing`);
+      if (value.routing.projectPath !== undefined)
+        assertString(value.routing.projectPath, `${label}.routing.projectPath`);
+      if (value.routing.projectGroup !== undefined)
+        assertString(value.routing.projectGroup, `${label}.routing.projectGroup`);
+      if (value.routing.taskId !== undefined)
+        assertString(value.routing.taskId, `${label}.routing.taskId`);
+      if (value.routing.eventId !== undefined)
+        assertString(value.routing.eventId, `${label}.routing.eventId`);
+      if (value.routing.eventType !== undefined)
+        assertString(value.routing.eventType, `${label}.routing.eventType`);
+      if (value.routing.eventSource !== undefined)
+        assertString(value.routing.eventSource, `${label}.routing.eventSource`);
+    }
     return value;
   }
   throw new Error(`${label}.type must be command or agent`);
@@ -2189,6 +2225,19 @@ class Store {
     const row = this.db.query("SELECT * FROM daemon_lease LIMIT 1").get();
     return row ? rowToLease(row) : undefined;
   }
+  writeTransaction(fn) {
+    this.db.exec("BEGIN IMMEDIATE;");
+    try {
+      const result = fn();
+      this.db.exec("COMMIT;");
+      return result;
+    } catch (error) {
+      try {
+        this.db.exec("ROLLBACK;");
+      } catch {}
+      throw error;
+    }
+  }
   close() {
     this.db.close();
   }
@@ -2196,9 +2245,9 @@ class Store {
 
 // src/cli/index.ts
 import { createHash as createHash2, randomUUID } from "crypto";
-import { existsSync as existsSync3, mkdirSync as mkdirSync5, readFileSync as readFileSync2, writeFileSync as writeFileSync3 } from "fs";
+import { existsSync as existsSync4, mkdirSync as mkdirSync5, readFileSync as readFileSync2, realpathSync, writeFileSync as writeFileSync3 } from "fs";
 import { spawnSync as spawnSync5 } from "child_process";
-import { join as join3 } from "path";
+import { join as join4, resolve as resolve2 } from "path";
 import { Database as Database2 } from "bun:sqlite";
 import { Command } from "commander";
 
@@ -5204,7 +5253,7 @@ function buildScriptInventoryReport(store, opts = {}) {
 // package.json
 var package_default = {
   name: "@hasna/loops",
-  version: "0.3.26",
+  version: "0.3.27",
   description: "Persistent local loop and workflow runner for deterministic commands and headless AI coding agents",
   type: "module",
   main: "dist/index.js",
@@ -5293,6 +5342,10 @@ function packageVersion() {
 }
 
 // src/lib/templates.ts
+import { execFileSync } from "child_process";
+import { existsSync as existsSync3 } from "fs";
+import { homedir as homedir3 } from "os";
+import { basename as basename2, isAbsolute, join as join3, relative, resolve } from "path";
 var TODOS_TASK_WORKER_VERIFIER_TEMPLATE_ID = "todos-task-worker-verifier";
 var EVENT_WORKER_VERIFIER_TEMPLATE_ID = "event-worker-verifier";
 var BOUNDED_AGENT_WORKER_VERIFIER_TEMPLATE_ID = "bounded-agent-worker-verifier";
@@ -5306,6 +5359,8 @@ var TEMPLATE_SUMMARIES = [
       { name: "taskId", required: true, description: "Todos task id to execute." },
       { name: "taskTitle", description: "Human-readable task title." },
       { name: "projectPath", required: true, description: "Repository or project working directory." },
+      { name: "routeProjectPath", description: "Canonical project path used for scheduler concurrency limits." },
+      { name: "projectGroup", description: "Optional project group used for scheduler concurrency limits." },
       { name: "provider", default: "codewith", description: "Agent provider: codewith, claude, cursor, opencode, aicopilot, or codex." },
       { name: "authProfile", description: "Provider-native auth profile, currently Codewith." },
       { name: "authProfilePool", description: "Comma-separated provider-native auth profiles; worker/verifier are selected deterministically." },
@@ -5315,7 +5370,10 @@ var TEMPLATE_SUMMARIES = [
       { name: "model", description: "Provider model." },
       { name: "variant", description: "Provider reasoning/model effort variant." },
       { name: "permissionMode", default: "bypass", description: "Provider permission mode: default, plan, auto, or bypass." },
-      { name: "sandbox", default: "danger-full-access", description: "Provider sandbox mode." }
+      { name: "sandbox", default: "danger-full-access", description: "Provider sandbox mode." },
+      { name: "worktreeMode", default: "auto", description: "Worktree isolation mode: auto, required, off, or main." },
+      { name: "worktreeRoot", default: "~/.hasna/loops/worktrees", description: "Base directory for OpenLoops-managed git worktrees." },
+      { name: "worktreeBranchPrefix", default: "openloops", description: "Branch prefix for generated task/event worktree branches." }
     ]
   },
   {
@@ -5329,6 +5387,8 @@ var TEMPLATE_SUMMARIES = [
       { name: "eventSource", required: true, description: "Hasna event source." },
       { name: "eventJson", required: true, description: "Full event envelope JSON." },
       { name: "projectPath", required: true, description: "Repository or project working directory." },
+      { name: "routeProjectPath", description: "Canonical project path used for scheduler concurrency limits." },
+      { name: "projectGroup", description: "Optional project group used for scheduler concurrency limits." },
       { name: "provider", default: "codewith", description: "Agent provider: codewith, claude, cursor, opencode, aicopilot, or codex." },
       { name: "authProfile", description: "Provider-native auth profile, currently Codewith." },
       { name: "authProfilePool", description: "Comma-separated provider-native auth profiles; worker/verifier are selected deterministically." },
@@ -5338,7 +5398,10 @@ var TEMPLATE_SUMMARIES = [
       { name: "model", description: "Provider model." },
       { name: "variant", description: "Provider reasoning/model effort variant." },
       { name: "permissionMode", default: "bypass", description: "Provider permission mode: default, plan, auto, or bypass." },
-      { name: "sandbox", default: "danger-full-access", description: "Provider sandbox mode." }
+      { name: "sandbox", default: "danger-full-access", description: "Provider sandbox mode." },
+      { name: "worktreeMode", default: "auto", description: "Worktree isolation mode: auto, required, off, or main." },
+      { name: "worktreeRoot", default: "~/.hasna/loops/worktrees", description: "Base directory for OpenLoops-managed git worktrees." },
+      { name: "worktreeBranchPrefix", default: "openloops", description: "Branch prefix for generated event worktree branches." }
     ]
   },
   {
@@ -5350,6 +5413,8 @@ var TEMPLATE_SUMMARIES = [
       { name: "objective", required: true, description: "Narrow goal-mode objective for the worker." },
       { name: "prompt", description: "Optional extra worker prompt details." },
       { name: "projectPath", required: true, description: "Repository or project working directory." },
+      { name: "routeProjectPath", description: "Canonical project path used for scheduler concurrency limits." },
+      { name: "projectGroup", description: "Optional project group used for scheduler concurrency limits." },
       { name: "provider", default: "codewith", description: "Agent provider: codewith, claude, cursor, opencode, aicopilot, or codex." },
       { name: "authProfile", description: "Provider-native auth profile, currently Codewith." },
       { name: "authProfilePool", description: "Comma-separated provider-native auth profiles; worker/verifier are selected deterministically." },
@@ -5360,6 +5425,9 @@ var TEMPLATE_SUMMARIES = [
       { name: "variant", description: "Provider reasoning/model effort variant." },
       { name: "permissionMode", default: "bypass", description: "Provider permission mode: default, plan, auto, or bypass." },
       { name: "sandbox", default: "danger-full-access", description: "Provider sandbox mode." },
+      { name: "worktreeMode", default: "auto", description: "Worktree isolation mode: auto, required, off, or main." },
+      { name: "worktreeRoot", default: "~/.hasna/loops/worktrees", description: "Base directory for OpenLoops-managed git worktrees." },
+      { name: "worktreeBranchPrefix", default: "openloops", description: "Branch prefix for generated bounded-agent worktree branches." },
       { name: "timeoutMs", default: "2700000", description: "Step timeout in milliseconds." }
     ]
   }
@@ -5401,6 +5469,183 @@ function accountForRole(input, role, seed) {
     return input.verifierAccount;
   return rolePoolValue(input.accountPool, seed, role) ?? input.account;
 }
+function slugSegment(value, fallback = "item") {
+  const slug = (value ?? "").toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 72);
+  return slug || fallback;
+}
+function stableHex(seed) {
+  return stableIndex(seed, 4294967295).toString(16).padStart(8, "0");
+}
+function shellQuote2(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function normalizeWorktreeMode(mode) {
+  const value = mode ?? "auto";
+  if (!["auto", "required", "off", "main"].includes(value)) {
+    throw new Error(`worktreeMode must be one of auto, required, off, or main`);
+  }
+  return value;
+}
+function defaultWorktreeRoot(root) {
+  if (root?.trim()) {
+    const expanded = root.trim().replace(/^~(?=$|\/)/, homedir3());
+    return isAbsolute(expanded) ? expanded : resolve(expanded);
+  }
+  return join3(homedir3(), ".hasna", "loops", "worktrees");
+}
+function gitRootFor(path) {
+  if (!existsSync3(path))
+    return;
+  try {
+    return execFileSync("git", ["-C", path, "rev-parse", "--show-toplevel"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+  } catch {
+    return;
+  }
+}
+function prepareWorktreeCommand(plan) {
+  const repo = shellQuote2(plan.repoRoot);
+  const path = shellQuote2(plan.path);
+  const branch = shellQuote2(plan.branch);
+  return [
+    "set -euo pipefail",
+    `repo=${repo}`,
+    `path=${path}`,
+    `branch=${branch}`,
+    'resolve_path() { cd "$1" && pwd -P; }',
+    "git_common_dir() {",
+    '  local base="$1"',
+    "  local common",
+    '  common="$(git -C "$base" rev-parse --git-common-dir)"',
+    '  case "$common" in',
+    '    /*) printf "%s\\n" "$common" ;;',
+    '    *) (cd "$base" && cd "$common" && pwd -P) ;;',
+    "  esac",
+    "}",
+    'mkdir -p "$(dirname "$path")"',
+    'if [ -e "$path" ]; then',
+    '  if [ -L "$path" ]; then',
+    '    printf "refusing symlinked worktree path %s\\n" "$path" >&2',
+    "    exit 1",
+    "  fi",
+    '  if git -C "$path" rev-parse --is-inside-work-tree >/dev/null 2>&1; then',
+    '    expected_common="$(git_common_dir "$repo")"',
+    '    actual_common="$(git_common_dir "$path")"',
+    '    if [ "$actual_common" != "$expected_common" ]; then',
+    '      printf "existing worktree %s belongs to different git common dir\\n" "$path" >&2',
+    '      printf "expected %s got %s\\n" "$expected_common" "$actual_common" >&2',
+    "      exit 1",
+    "    fi",
+    '    actual_top="$(git -C "$path" rev-parse --show-toplevel)"',
+    '    actual_top="$(resolve_path "$actual_top")"',
+    '    expected_top="$(resolve_path "$path")"',
+    '    if [ "$actual_top" != "$expected_top" ]; then',
+    '      printf "existing worktree top-level mismatch for %s: %s\\n" "$path" "$actual_top" >&2',
+    "      exit 1",
+    "    fi",
+    '    actual_branch="$(git -C "$path" branch --show-current)"',
+    '    if [ "$actual_branch" != "$branch" ]; then',
+    '      printf "existing worktree %s is on branch %s, expected %s\\n" "$path" "$actual_branch" "$branch" >&2',
+    "      exit 1",
+    "    fi",
+    '    printf "existing worktree %s branch %s\\n" "$path" "$branch"',
+    "    exit 0",
+    "  fi",
+    '  printf "refusing to overwrite non-git path: %s\\n" "$path" >&2',
+    "  exit 1",
+    "fi",
+    'git -C "$repo" rev-parse --is-inside-work-tree >/dev/null',
+    'if git -C "$repo" show-ref --verify --quiet "refs/heads/$branch"; then',
+    '  git -C "$repo" worktree add "$path" "$branch"',
+    "else",
+    '  git -C "$repo" worktree add -b "$branch" "$path" HEAD',
+    "fi",
+    'printf "prepared worktree %s branch %s\\n" "$path" "$branch"'
+  ].join(`
+`);
+}
+function worktreePlan(input, seed) {
+  const mode = normalizeWorktreeMode(input.worktreeMode);
+  const originalCwd = input.projectPath;
+  if (mode === "off" || mode === "main") {
+    return {
+      mode,
+      enabled: false,
+      originalCwd,
+      cwd: originalCwd,
+      reason: mode === "main" ? "explicit main/default checkout mode" : "worktree mode disabled"
+    };
+  }
+  const repoRoot = gitRootFor(originalCwd);
+  if (!repoRoot) {
+    if (mode === "required") {
+      throw new Error(`worktreeMode=required but projectPath is not an existing git repository: ${originalCwd}`);
+    }
+    return {
+      mode,
+      enabled: false,
+      originalCwd,
+      cwd: originalCwd,
+      reason: "projectPath is not an existing git repository"
+    };
+  }
+  const root = defaultWorktreeRoot(input.worktreeRoot);
+  const repoSlug = slugSegment(basename2(repoRoot), "repo");
+  const seedSlug = `${slugSegment(seed, "run").slice(0, 48)}-${stableHex(`${repoRoot}:${seed}`)}`;
+  const worktreePath = join3(root, repoSlug, seedSlug);
+  const relativeCwd = relative(repoRoot, originalCwd);
+  const cwd = relativeCwd && !relativeCwd.startsWith("..") && !isAbsolute(relativeCwd) ? join3(worktreePath, relativeCwd) : worktreePath;
+  const branchPrefix = (input.worktreeBranchPrefix?.trim() || "openloops").replace(/^\/+|\/+$/g, "") || "openloops";
+  const branch = `${branchPrefix}/${repoSlug}/${seedSlug}`;
+  const prepareStep = {
+    id: "prepare-worktree",
+    name: "Prepare Worktree",
+    description: "Create or reuse the isolated OpenLoops git worktree for this workflow run.",
+    target: {
+      type: "command",
+      command: "bash",
+      args: ["-lc", prepareWorktreeCommand({ repoRoot, path: worktreePath, branch })],
+      cwd: repoRoot,
+      timeoutMs: 5 * 60000
+    },
+    timeoutMs: 5 * 60000
+  };
+  return {
+    mode,
+    enabled: true,
+    originalCwd,
+    cwd,
+    repoRoot,
+    root,
+    path: worktreePath,
+    branch,
+    prepareStep
+  };
+}
+function worktreePrompt(plan) {
+  if (plan.enabled) {
+    return [
+      "OpenLoops worktree policy:",
+      "- Use the isolated git worktree as the only writeable repository checkout for this task/event.",
+      `- Worktree cwd: ${plan.cwd}`,
+      `- Worktree root: ${plan.path}`,
+      `- Branch: ${plan.branch}`,
+      `- Original checkout: ${plan.originalCwd}`,
+      "- Do not mutate the original checkout/main branch except for read-only inspection.",
+      "- Preserve unrelated changes in both the original checkout and this worktree."
+    ].join(`
+`);
+  }
+  return [
+    "OpenLoops worktree policy:",
+    `- Worktree mode ${plan.mode} did not select an isolated worktree: ${plan.reason ?? "not enabled"}.`,
+    `- Cwd: ${plan.cwd}`,
+    "- Do not create ad hoc worktrees unless the task itself explicitly requires one."
+  ].join(`
+`);
+}
 function assertNativeAuthProfileSupport(input, provider) {
   if (provider === "codewith")
     return;
@@ -5409,7 +5654,7 @@ function assertNativeAuthProfileSupport(input, provider) {
     return;
   throw new Error(`authProfile, authProfilePool, workerAuthProfile, and verifierAuthProfile are supported only for provider codewith; use account/accountPool for ${provider} profile isolation`);
 }
-function agentTarget(input, prompt, role, seed) {
+function agentTarget(input, prompt, role, seed, plan) {
   const provider = input.provider ?? "codewith";
   assertNativeAuthProfileSupport(input, provider);
   const sandbox = input.sandbox ?? (provider === "codewith" || provider === "codex" ? "danger-full-access" : provider === "cursor" ? "disabled" : undefined);
@@ -5417,7 +5662,7 @@ function agentTarget(input, prompt, role, seed) {
     type: "agent",
     provider,
     prompt,
-    cwd: input.projectPath,
+    cwd: plan.cwd,
     model: input.model,
     variant: input.variant,
     agent: input.agent,
@@ -5425,10 +5670,33 @@ function agentTarget(input, prompt, role, seed) {
     configIsolation: "safe",
     permissionMode: input.permissionMode ?? "bypass",
     sandbox,
+    worktree: {
+      mode: plan.mode,
+      enabled: plan.enabled,
+      originalCwd: plan.originalCwd,
+      cwd: plan.cwd,
+      repoRoot: plan.repoRoot,
+      root: plan.root,
+      path: plan.path,
+      branch: plan.branch,
+      reason: plan.reason
+    },
+    routing: {
+      projectPath: input.routeProjectPath ?? input.projectPath,
+      ...input.projectGroup ? { projectGroup: input.projectGroup } : {}
+    },
     account: accountForRole(input, role, seed),
     timeoutMs: 45 * 60000
   };
 }
+function workflowStepsWithWorktree(plan, steps) {
+  if (!plan.prepareStep)
+    return steps;
+  return [
+    plan.prepareStep,
+    ...steps.map((step) => step.id === "worker" ? { ...step, dependsOn: [...new Set([...step.dependsOn ?? [], plan.prepareStep.id])] } : step)
+  ];
+}
 function listLoopTemplates() {
   return TEMPLATE_SUMMARIES.map((template) => structuredClone(template));
 }
@@ -5440,18 +5708,30 @@ function renderTodosTaskWorkerVerifierWorkflow(input) {
     throw new Error("taskId is required");
   if (!input.projectPath?.trim())
     throw new Error("projectPath is required");
+  const plan = worktreePlan(input, input.taskId);
   const taskContext = {
     taskId: input.taskId,
     taskTitle: input.taskTitle,
     taskDescription: input.taskDescription,
     eventId: input.eventId,
     eventType: input.eventType,
-    projectPath: input.projectPath
+    projectPath: input.projectPath,
+    routeProjectPath: input.routeProjectPath,
+    projectGroup: input.projectGroup,
+    worktree: {
+      mode: plan.mode,
+      enabled: plan.enabled,
+      cwd: plan.cwd,
+      path: plan.path,
+      branch: plan.branch,
+      reason: plan.reason
+    }
   };
   const workerPrompt = [
     `/goal Complete todos task ${input.taskId} in ${input.projectPath}.`,
     "",
     "You are the worker agent for a task-triggered OpenLoops workflow.",
+    worktreePrompt(plan),
     "Investigate first before changing files. Use the todos CLI as the source of truth for the task.",
     "Claim/start the task if appropriate, 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.",
     "Do not dispatch or paste prompts into tmux panes. If additional work is required, create or update deduped todos tasks so task-created routing can start a fresh headless workflow.",
@@ -5464,6 +5744,7 @@ function renderTodosTaskWorkerVerifierWorkflow(input) {
     `/goal Verify todos task ${input.taskId} after the worker step.`,
     "",
     "You are the verifier agent for a task-triggered OpenLoops workflow.",
+    worktreePrompt(plan),
     "Use fresh context. Inspect the task, repository state, commits, tests, and worker evidence. Act as an adversarial reviewer focused on correctness, regressions, missing tests, security, and incomplete requirements.",
     "If the work is valid, record verification evidence in todos and mark/leave the task in the correct completed state according to the todos CLI. If it is not valid, add precise follow-up tasks or comments and leave the original task open or blocked with clear evidence.",
     "Do not dispatch or paste prompts into tmux panes. If additional work is required, create or update deduped todos tasks so task-created routing can start a fresh headless workflow.",
@@ -5476,12 +5757,12 @@ function renderTodosTaskWorkerVerifierWorkflow(input) {
     name: `todos-task-${input.taskId.slice(0, 8)}-worker-verifier`,
     description: `Task-triggered worker/verifier workflow for ${taskLabel(input)}`,
     version: 1,
-    steps: [
+    steps: workflowStepsWithWorktree(plan, [
       {
         id: "worker",
         name: "Worker",
         description: "Implement the todos task and record evidence.",
-        target: agentTarget(input, workerPrompt, "worker", input.taskId),
+        target: agentTarget(input, workerPrompt, "worker", input.taskId, plan),
         timeoutMs: 45 * 60000
       },
       {
@@ -5489,10 +5770,10 @@ function renderTodosTaskWorkerVerifierWorkflow(input) {
         name: "Verifier",
         description: "Adversarially verify worker output and update todos.",
         dependsOn: ["worker"],
-        target: agentTarget(input, verifierPrompt, "verifier", input.taskId),
+        target: agentTarget(input, verifierPrompt, "verifier", input.taskId, plan),
         timeoutMs: 30 * 60000
       }
-    ]
+    ])
   };
 }
 function renderEventWorkerVerifierWorkflow(input) {
@@ -5506,18 +5787,31 @@ function renderEventWorkerVerifierWorkflow(input) {
     throw new Error("eventJson is required");
   if (!input.projectPath?.trim())
     throw new Error("projectPath is required");
+  const seed = `${input.eventSource}:${input.eventType}:${input.eventId}`;
+  const plan = worktreePlan(input, seed);
   const eventContext = {
     eventId: input.eventId,
     eventType: input.eventType,
     eventSource: input.eventSource,
     eventSubject: input.eventSubject,
     eventMessage: input.eventMessage,
-    projectPath: input.projectPath
+    projectPath: input.projectPath,
+    routeProjectPath: input.routeProjectPath,
+    projectGroup: input.projectGroup,
+    worktree: {
+      mode: plan.mode,
+      enabled: plan.enabled,
+      cwd: plan.cwd,
+      path: plan.path,
+      branch: plan.branch,
+      reason: plan.reason
+    }
   };
   const workerPrompt = [
     `/goal Handle Hasna event ${input.eventSource}/${input.eventType} (${input.eventId}) in ${input.projectPath}.`,
     "",
     "You are the worker agent for an event-triggered OpenLoops workflow.",
+    worktreePrompt(plan),
     "Investigate first before changing files. Read the full event envelope and decide the narrow action required by that event. Preserve unrelated user changes and update the relevant local CLI/task/knowledge system with evidence, changed files, commits, and blockers.",
     "If the event is informational or does not require action, record that finding and stop without making changes.",
     "",
@@ -5529,6 +5823,7 @@ function renderEventWorkerVerifierWorkflow(input) {
     `/goal Verify handling of Hasna event ${input.eventSource}/${input.eventType} (${input.eventId}).`,
     "",
     "You are the verifier agent for an event-triggered OpenLoops workflow.",
+    worktreePrompt(plan),
     "Use fresh context. Inspect the event, repository/project state, worker evidence, tests, and any created tasks or notes. Act as an adversarial reviewer focused on correctness, regressions, security, missing evidence, and incomplete requirements.",
     "If the work is valid, record verification evidence in the relevant local system. If it is not valid, add precise follow-up tasks/comments and leave the event handling state open or blocked with clear evidence.",
     "",
@@ -5540,12 +5835,12 @@ function renderEventWorkerVerifierWorkflow(input) {
     name: `event-${input.eventSource}-${input.eventType}-${input.eventId.slice(0, 8)}-worker-verifier`.replace(/[^a-zA-Z0-9._:-]+/g, "-"),
     description: `Event-triggered worker/verifier workflow for ${input.eventSource}/${input.eventType}`,
     version: 1,
-    steps: [
+    steps: workflowStepsWithWorktree(plan, [
       {
         id: "worker",
         name: "Worker",
         description: "Handle the Hasna event and record evidence.",
-        target: agentTarget(input, workerPrompt, "worker", `${input.eventSource}:${input.eventType}:${input.eventId}`),
+        target: agentTarget(input, workerPrompt, "worker", seed, plan),
         timeoutMs: 45 * 60000
       },
       {
@@ -5553,10 +5848,10 @@ function renderEventWorkerVerifierWorkflow(input) {
         name: "Verifier",
         description: "Adversarially verify event handling.",
         dependsOn: ["worker"],
-        target: agentTarget(input, verifierPrompt, "verifier", `${input.eventSource}:${input.eventType}:${input.eventId}`),
+        target: agentTarget(input, verifierPrompt, "verifier", seed, plan),
         timeoutMs: 30 * 60000
       }
-    ]
+    ])
   };
 }
 function renderBoundedAgentWorkerVerifierWorkflow(input) {
@@ -5565,11 +5860,13 @@ function renderBoundedAgentWorkerVerifierWorkflow(input) {
   if (!input.projectPath?.trim())
     throw new Error("projectPath is required");
   const seed = `${input.projectPath}:${input.objective}`;
+  const plan = worktreePlan(input, seed);
   const timeoutMs = input.timeoutMs && Number.isFinite(input.timeoutMs) ? input.timeoutMs : 45 * 60000;
   const workerPrompt = [
     `/goal ${input.objective}`,
     "",
     "You are the worker step for a bounded OpenLoops agent workflow.",
+    worktreePrompt(plan),
     "Investigate first. Keep scope narrow, use local project/task systems as the source of truth when relevant, preserve unrelated changes, run focused validation, and record concise evidence.",
     "Do not dispatch or paste prompts into tmux panes. If additional work is required, create or update deduped todos tasks so task-created routing can start a fresh headless workflow.",
     input.prompt ? "" : undefined,
@@ -5580,6 +5877,7 @@ function renderBoundedAgentWorkerVerifierWorkflow(input) {
     `/goal Adversarially verify: ${input.objective}`,
     "",
     "You are the verifier step for a bounded OpenLoops agent workflow.",
+    worktreePrompt(plan),
     "Use fresh context. Review the worker result for correctness, regressions, missing tests, safety, runaway-agent risk, output bounds, and incomplete evidence.",
     "If valid, record verification evidence. If invalid, create precise follow-up tasks or comments and leave the original work open. Do not make broad unrelated changes."
   ].join(`
@@ -5588,12 +5886,12 @@ function renderBoundedAgentWorkerVerifierWorkflow(input) {
     name: input.name ?? `bounded-agent-${stableIndex(seed, 4294967295).toString(16).padStart(8, "0")}-worker-verifier`,
     description: `Bounded worker/verifier workflow for ${input.objective.slice(0, 180)}`,
     version: 1,
-    steps: [
+    steps: workflowStepsWithWorktree(plan, [
       {
         id: "worker",
         name: "Worker",
         description: "Execute the bounded objective and record evidence.",
-        target: agentTarget(input, workerPrompt, "worker", seed),
+        target: agentTarget(input, workerPrompt, "worker", seed, plan),
         timeoutMs
       },
       {
@@ -5601,10 +5899,10 @@ function renderBoundedAgentWorkerVerifierWorkflow(input) {
         name: "Verifier",
         description: "Adversarially verify the bounded objective result.",
         dependsOn: ["worker"],
-        target: agentTarget(input, verifierPrompt, "verifier", seed),
+        target: agentTarget(input, verifierPrompt, "verifier", seed, plan),
         timeoutMs: Math.min(timeoutMs, 30 * 60000)
       }
-    ]
+    ])
   };
 }
 function renderLoopTemplate(id, values) {
@@ -5614,6 +5912,8 @@ function renderLoopTemplate(id, values) {
       taskTitle: values.taskTitle,
       taskDescription: values.taskDescription,
       projectPath: values.projectPath ?? values.cwd ?? process.cwd(),
+      routeProjectPath: values.routeProjectPath,
+      projectGroup: values.projectGroup,
       provider: values.provider,
       authProfile: values.authProfile,
       authProfilePool: listVar(values.authProfilePool),
@@ -5626,6 +5926,9 @@ function renderLoopTemplate(id, values) {
       agent: values.agent,
       permissionMode: values.permissionMode,
       sandbox: values.sandbox,
+      worktreeMode: values.worktreeMode,
+      worktreeRoot: values.worktreeRoot,
+      worktreeBranchPrefix: values.worktreeBranchPrefix,
       eventId: values.eventId,
       eventType: values.eventType
     });
@@ -5639,6 +5942,8 @@ function renderLoopTemplate(id, values) {
       eventMessage: values.eventMessage,
       eventJson: values.eventJson ?? "",
       projectPath: values.projectPath ?? values.cwd ?? process.cwd(),
+      routeProjectPath: values.routeProjectPath,
+      projectGroup: values.projectGroup,
       provider: values.provider,
       authProfile: values.authProfile,
       authProfilePool: listVar(values.authProfilePool),
@@ -5650,7 +5955,10 @@ function renderLoopTemplate(id, values) {
       variant: values.variant,
       agent: values.agent,
       permissionMode: values.permissionMode,
-      sandbox: values.sandbox
+      sandbox: values.sandbox,
+      worktreeMode: values.worktreeMode,
+      worktreeRoot: values.worktreeRoot,
+      worktreeBranchPrefix: values.worktreeBranchPrefix
     });
   }
   if (id === BOUNDED_AGENT_WORKER_VERIFIER_TEMPLATE_ID) {
@@ -5659,6 +5967,8 @@ function renderLoopTemplate(id, values) {
       objective: values.objective ?? "",
       prompt: values.prompt,
       projectPath: values.projectPath ?? values.cwd ?? process.cwd(),
+      routeProjectPath: values.routeProjectPath,
+      projectGroup: values.projectGroup,
       provider: values.provider,
       authProfile: values.authProfile,
       authProfilePool: listVar(values.authProfilePool),
@@ -5671,6 +5981,9 @@ function renderLoopTemplate(id, values) {
       agent: values.agent,
       permissionMode: values.permissionMode,
       sandbox: values.sandbox,
+      worktreeMode: values.worktreeMode,
+      worktreeRoot: values.worktreeRoot,
+      worktreeBranchPrefix: values.worktreeBranchPrefix,
       timeoutMs: values.timeoutMs ? Number(values.timeoutMs) : undefined
     });
   }
@@ -5922,9 +6235,9 @@ function ensureTodosTaskList(project, slug, name, description) {
 }
 function backupLoopsDatabase(reason) {
   const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\..+$/, "Z");
-  const backupDir = join3(dataDir(), "backups");
+  const backupDir = join4(dataDir(), "backups");
   mkdirSync5(backupDir, { recursive: true, mode: 448 });
-  const backupPath = join3(backupDir, `loops.db.bak-${reason}-${stamp}`);
+  const backupPath = join4(backupDir, `loops.db.bak-${reason}-${stamp}`);
   const db = new Database2(dbPath(), { readonly: true });
   try {
     writeFileSync3(backupPath, db.serialize(), { mode: 384 });
@@ -5938,11 +6251,11 @@ function stableHash(parts) {
 `)).digest("hex").slice(0, 16);
 }
 function routeCursorsPath() {
-  return join3(dataDir(), "route-cursors.json");
+  return join4(dataDir(), "route-cursors.json");
 }
 function readRouteCursors() {
   const path = routeCursorsPath();
-  if (!existsSync3(path))
+  if (!existsSync4(path))
     return {};
   try {
     const parsed = JSON.parse(readFileSync2(path, "utf8"));
@@ -5963,7 +6276,7 @@ function writeRouteEvidence(kind, value, 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`);
+  const evidencePath = join4(evidenceDir, `${kind}-${stamp}-${randomUUID().slice(0, 8)}.json`);
   writeFileSync3(evidencePath, JSON.stringify(value, null, 2), { mode: 384, flag: "wx" });
   return evidencePath;
 }
@@ -6079,7 +6392,7 @@ function eventMetadata(event) {
 function stringField(value) {
   return typeof value === "string" && value.trim() ? value.trim() : undefined;
 }
-function slugSegment(value, fallback = "event") {
+function slugSegment2(value, fallback = "event") {
   return value.toLowerCase().replace(/[^a-z0-9._:-]+/g, "-").replace(/^-|-$/g, "").slice(0, 80) || fallback;
 }
 function stableSuffix(value) {
@@ -6218,6 +6531,111 @@ function taskRouteEligibility(data, metadata) {
   }
   return { eligible: true, tags };
 }
+function routeThrottleLimitsFromOpts(opts) {
+  return {
+    maxActive: positiveInteger(opts.maxActive, "--max-active"),
+    maxActivePerProject: positiveInteger(opts.maxActivePerProject, "--max-active-per-project"),
+    maxActivePerProjectGroup: positiveInteger(opts.maxActivePerProjectGroup, "--max-active-per-project-group")
+  };
+}
+function hasThrottleLimits(limits) {
+  return limits.maxActive !== undefined || limits.maxActivePerProject !== undefined || limits.maxActivePerProjectGroup !== undefined;
+}
+function normalizeRoutePath(value) {
+  if (!value?.trim())
+    return;
+  const resolved = resolve2(value.trim());
+  let canonical = resolved;
+  try {
+    canonical = realpathSync(resolved);
+  } catch {
+    return canonical;
+  }
+  const gitRoot = spawnSync5("git", ["-C", canonical, "rev-parse", "--show-toplevel"], { encoding: "utf8" });
+  if (gitRoot.status === 0 && gitRoot.stdout.trim()) {
+    try {
+      return realpathSync(gitRoot.stdout.trim());
+    } catch {
+      return resolve2(gitRoot.stdout.trim());
+    }
+  }
+  return canonical;
+}
+function routeProjectGroup(optsGroup, data, metadata) {
+  return optsGroup?.trim() || taskEventField(data, ["project_group", "projectGroup", "repo_group", "repoGroup", "workspace_group", "workspaceGroup"]) || taskEventField(metadata, ["project_group", "projectGroup", "repo_group", "repoGroup", "workspace_group", "workspaceGroup"]);
+}
+function firstWorkflowRouting(workflow) {
+  for (const step of workflow.steps) {
+    if (step.target.type !== "agent")
+      continue;
+    const target = step.target;
+    const projectPath = normalizeRoutePath(target.routing?.projectPath ?? target.worktree?.originalCwd ?? target.cwd);
+    const projectGroup = target.routing?.projectGroup?.trim();
+    if (projectPath || projectGroup) {
+      return {
+        ...projectPath ? { projectPath } : {},
+        ...projectGroup ? { projectGroup } : {}
+      };
+    }
+  }
+  return;
+}
+function activeWorkflowLoopRoutes(store) {
+  const values = [];
+  for (const loop of store.listLoops({ status: "active", limit: 1e4 })) {
+    if (loop.target.type !== "workflow")
+      continue;
+    const workflow = store.getWorkflow(loop.target.workflowId);
+    if (!workflow || workflow.status !== "active")
+      continue;
+    const routing = firstWorkflowRouting(workflow);
+    if (routing)
+      values.push({ loop, routing });
+  }
+  return values;
+}
+function routeThrottleDecision(store, args) {
+  const projectPath = normalizeRoutePath(args.projectPath) ?? resolve2(args.projectPath);
+  const projectGroup = args.projectGroup?.trim() || undefined;
+  const active = activeWorkflowLoopRoutes(store);
+  const counts = {
+    global: active.length,
+    project: active.filter((entry) => normalizeRoutePath(entry.routing.projectPath) === projectPath).length
+  };
+  if (projectGroup)
+    counts.projectGroup = active.filter((entry) => entry.routing.projectGroup?.trim() === projectGroup).length;
+  const base = {
+    projectPath,
+    ...projectGroup ? { projectGroup } : {},
+    limits: args.limits,
+    counts
+  };
+  if (args.limits.maxActive !== undefined && counts.global >= args.limits.maxActive) {
+    return { ...base, allowed: false, reason: `global active workflow limit reached (${counts.global}/${args.limits.maxActive})` };
+  }
+  if (args.limits.maxActivePerProject !== undefined && counts.project >= args.limits.maxActivePerProject) {
+    return { ...base, allowed: false, reason: `project active workflow limit reached (${counts.project}/${args.limits.maxActivePerProject})` };
+  }
+  if (projectGroup && args.limits.maxActivePerProjectGroup !== undefined && counts.projectGroup !== undefined && counts.projectGroup >= args.limits.maxActivePerProjectGroup) {
+    return {
+      ...base,
+      allowed: false,
+      reason: `project-group active workflow limit reached (${counts.projectGroup}/${args.limits.maxActivePerProjectGroup})`
+    };
+  }
+  return { ...base, allowed: true };
+}
+function routeThrottleDryRunPreview(args) {
+  const projectPath = normalizeRoutePath(args.projectPath) ?? resolve2(args.projectPath);
+  const projectGroup = args.projectGroup?.trim() || undefined;
+  return {
+    evaluated: false,
+    reason: "not evaluated in dry-run because opening the live loop store may create or migrate the database",
+    projectPath,
+    ...projectGroup ? { projectGroup } : {},
+    limits: args.limits
+  };
+}
 async function readEventEnvelopeFromStdin() {
   const raw = process.env.HASNA_EVENT_JSON || await Bun.stdin.text();
   const event = JSON.parse(raw);
@@ -6381,7 +6799,7 @@ templates.command("create-workflow <id>").description("render and store a templa
   }
 });
 var eventsHandle = events.command("handle").description("handle a Hasna event envelope");
-eventsHandle.command("todos-task").description("create a one-shot worker/verifier workflow loop for a todos task event").option("--provider <provider>", "agent provider", "codewith").option("--auth-profile <profile>", "provider-native auth profile; currently supported for codewith").option("--auth-profile-pool <profiles>", "comma-separated provider-native auth profile pool").option("--worker-auth-profile <profile>", "provider-native auth profile for worker step").option("--verifier-auth-profile <profile>", "provider-native auth profile for verifier step").option("--account <profile>", "OpenAccounts profile name").option("--account-pool <profiles>", "comma-separated OpenAccounts profile pool").option("--worker-account <profile>", "OpenAccounts profile for worker step").option("--verifier-account <profile>", "OpenAccounts profile for verifier step").option("--account-tool <tool>", "OpenAccounts tool id").option("--model <model>", "provider model").option("--variant <variant>", "provider-specific model variant or reasoning effort").option("--agent <agent>", "provider-specific agent").option("--permission-mode <mode>", "provider permission mode: default, plan, auto, or bypass", "bypass").option("--sandbox <mode>", "provider sandbox").option("--project-path <path>", "fallback project/repo working directory").option("--name-prefix <prefix>", "workflow/loop name prefix", "event:todos-task").option("--preflight", "check generated workflow steps before storing the workflow loop").option("--dry-run", "print the workflow and loop input without storing anything").action(async (opts) => {
+eventsHandle.command("todos-task").description("create a one-shot worker/verifier workflow loop for a todos task event").option("--provider <provider>", "agent provider", "codewith").option("--auth-profile <profile>", "provider-native auth profile; currently supported for codewith").option("--auth-profile-pool <profiles>", "comma-separated provider-native auth profile pool").option("--worker-auth-profile <profile>", "provider-native auth profile for worker step").option("--verifier-auth-profile <profile>", "provider-native auth profile for verifier step").option("--account <profile>", "OpenAccounts profile name").option("--account-pool <profiles>", "comma-separated OpenAccounts profile pool").option("--worker-account <profile>", "OpenAccounts profile for worker step").option("--verifier-account <profile>", "OpenAccounts profile for verifier step").option("--account-tool <tool>", "OpenAccounts tool id").option("--model <model>", "provider model").option("--variant <variant>", "provider-specific model variant or reasoning effort").option("--agent <agent>", "provider-specific agent").option("--permission-mode <mode>", "provider permission mode: default, plan, auto, or bypass", "bypass").option("--sandbox <mode>", "provider sandbox").option("--project-path <path>", "fallback project/repo working directory").option("--project-group <name>", "optional project group for concurrency limits").option("--max-active <n>", "skip creating a workflow when this many active routed workflows already exist globally").option("--max-active-per-project <n>", "skip creating a workflow when this many active routed workflows already exist for the project").option("--max-active-per-project-group <n>", "skip creating a workflow when this many active routed workflows already exist for the project group").option("--worktree-mode <mode>", "worktree isolation mode: auto, required, off, or main", "auto").option("--worktree-root <path>", "base directory for OpenLoops-managed git worktrees").option("--worktree-branch-prefix <prefix>", "branch prefix for generated task worktrees", "openloops").option("--name-prefix <prefix>", "workflow/loop name prefix", "event:todos-task").option("--preflight", "check generated workflow steps before storing the workflow loop").option("--dry-run", "print the workflow and loop input without storing anything").action(async (opts) => {
   const event = await readEventEnvelopeFromStdin();
   const data = eventData(event);
   const metadata = eventMetadata(event);
@@ -6405,7 +6823,34 @@ eventsHandle.command("todos-task").description("create a one-shot worker/verifie
     "cwd"
   ]);
   const projectPath = opts.projectPath ?? dataProjectPath ?? metadataProjectPath ?? process.cwd();
+  const routeProjectPath = normalizeRoutePath(projectPath) ?? resolve2(projectPath);
+  const projectGroup = routeProjectGroup(opts.projectGroup, data, metadata);
+  const throttleLimits = routeThrottleLimitsFromOpts(opts);
   const idempotencyKey = `todos-task:${taskId}:${event.type}`;
+  const idempotencySuffix = stableSuffix(idempotencyKey);
+  const workflowName = `${opts.namePrefix}:${taskId.slice(0, 8)}:${idempotencySuffix}:workflow`;
+  const loopName = `${opts.namePrefix}:${taskId.slice(0, 8)}:${idempotencySuffix}:run`;
+  const legacyLoopName = `${opts.namePrefix}:${taskId.slice(0, 8)}:${event.id.slice(0, 8)}:run`;
+  if (!opts.dryRun) {
+    const store2 = new Store;
+    try {
+      const existingLoop = store2.findLoopByName(loopName) ?? store2.findLoopByName(legacyLoopName);
+      if (existingLoop) {
+        const existingWorkflow = existingLoop.target.type === "workflow" ? store2.getWorkflow(existingLoop.target.workflowId) : undefined;
+        print({
+          deduped: true,
+          idempotencyKey,
+          dedupedBy: existingLoop.name === loopName ? "idempotency" : "legacy-event-name",
+          event,
+          workflow: existingWorkflow ? publicWorkflow(existingWorkflow) : undefined,
+          loop: publicLoop(existingLoop)
+        }, `deduped existing loop ${existingLoop.id} (${existingLoop.name}) for event=${event.id} idempotency=${idempotencyKey}`);
+        return;
+      }
+    } finally {
+      store2.close();
+    }
+  }
   const provider = opts.provider;
   if (!["claude", "cursor", "codewith", "aicopilot", "opencode", "codex"].includes(provider))
     throw new Error("unsupported provider");
@@ -6417,6 +6862,8 @@ eventsHandle.command("todos-task").description("create a one-shot worker/verifie
     taskTitle,
     taskDescription,
     projectPath,
+    routeProjectPath,
+    projectGroup,
     provider,
     authProfile,
     authProfilePool: splitList(opts.authProfilePool),
@@ -6431,14 +6878,14 @@ eventsHandle.command("todos-task").description("create a one-shot worker/verifie
     agent: opts.agent,
     permissionMode,
     sandbox,
+    worktreeMode: opts.worktreeMode,
+    worktreeRoot: opts.worktreeRoot,
+    worktreeBranchPrefix: opts.worktreeBranchPrefix,
     eventId: event.id,
     eventType: event.type
   });
-  const idempotencySuffix = stableSuffix(idempotencyKey);
-  workflowBody.name = `${opts.namePrefix}:${taskId.slice(0, 8)}:${idempotencySuffix}:workflow`;
-  workflowBody.description = `Task-triggered worker/verifier workflow for ${taskTitle ?? taskId} from ${event.source}/${event.type}; ` + `idempotency=${idempotencyKey}; event=${event.id}`;
-  const loopName = `${opts.namePrefix}:${taskId.slice(0, 8)}:${idempotencySuffix}:run`;
-  const legacyLoopName = `${opts.namePrefix}:${taskId.slice(0, 8)}:${event.id.slice(0, 8)}:run`;
+  workflowBody.name = workflowName;
+  workflowBody.description = `Task-triggered worker/verifier workflow for ${taskTitle ?? taskId} from ${event.source}/${event.type}; ` + `idempotency=${idempotencyKey}; event=${event.id}; project=${projectPath}; projectGroup=${projectGroup ?? "-"}`;
   const loopInput = {
     name: loopName,
     description: `Run ${workflowBody.name} once for task ${taskId}; idempotency=${idempotencyKey}; event=${event.id}`,
@@ -6450,50 +6897,96 @@ eventsHandle.command("todos-task").description("create a one-shot worker/verifie
     leaseMs: 90 * 60000
   };
   if (opts.dryRun) {
+    const throttle = hasThrottleLimits(throttleLimits) ? routeThrottleDryRunPreview({ projectPath: routeProjectPath, projectGroup, limits: throttleLimits }) : undefined;
     const preflight = opts.preflight ? preflightStoredWorkflow(workflowSpecForPreflight(workflowBody, "event-preflight"), {
       name: workflowBody.name,
       type: "todos-task-event-workflow",
       event: event.id
     }, {}) : undefined;
-    print({ deduped: false, idempotencyKey, event, workflow: workflowBody, loop: loopInput, preflight }, `dry-run ${loopName}`);
+    print({ deduped: false, idempotencyKey, event, workflow: workflowBody, loop: loopInput, throttle, preflight }, `dry-run ${loopName}`);
     return;
   }
   const store = new Store;
   try {
-    const existingLoop = store.findLoopByName(loopName) ?? store.findLoopByName(legacyLoopName);
-    if (existingLoop) {
-      const existingWorkflow2 = existingLoop.target.type === "workflow" ? store.getWorkflow(existingLoop.target.workflowId) : undefined;
-      print({
-        deduped: true,
-        idempotencyKey,
-        dedupedBy: existingLoop.name === loopName ? "idempotency" : "legacy-event-name",
-        event,
-        workflow: existingWorkflow2 ? publicWorkflow(existingWorkflow2) : undefined,
-        loop: publicLoop(existingLoop)
-      }, `deduped existing loop ${existingLoop.id} (${existingLoop.name}) for event=${event.id} idempotency=${idempotencyKey}`);
-      return;
-    }
-    const existingWorkflow = store.findWorkflowByName(workflowBody.name);
-    const workflowPreflightSpec = existingWorkflow ?? workflowSpecForPreflight(workflowBody, "event-preflight");
+    const existingWorkflowForPreflight = store.findWorkflowByName(workflowBody.name);
+    const workflowPreflightSpec = existingWorkflowForPreflight ?? workflowSpecForPreflight(workflowBody, "event-preflight");
     const preflight = opts.preflight ? preflightStoredWorkflow(workflowPreflightSpec, {
       name: workflowBody.name,
       type: "todos-task-event-workflow",
       event: event.id
     }, {}) : undefined;
-    const workflow = existingWorkflow ?? store.createWorkflow(workflowBody);
-    const loop = store.createLoop({
-      ...loopInput,
-      target: { type: "workflow", workflowId: workflow.id }
+    const outcome = store.writeTransaction(() => {
+      const existingLoop = store.findLoopByName(loopName) ?? store.findLoopByName(legacyLoopName);
+      if (existingLoop) {
+        const existingWorkflow2 = existingLoop.target.type === "workflow" ? store.getWorkflow(existingLoop.target.workflowId) : undefined;
+        return { kind: "deduped", existingLoop, existingWorkflow: existingWorkflow2 };
+      }
+      const throttle = hasThrottleLimits(throttleLimits) ? routeThrottleDecision(store, { projectPath: routeProjectPath, projectGroup, limits: throttleLimits }) : undefined;
+      if (throttle && !throttle.allowed)
+        return { kind: "throttled", throttle };
+      const existingWorkflow = store.findWorkflowByName(workflowBody.name);
+      const workflow = existingWorkflow ?? store.createWorkflow(workflowBody);
+      const loop = store.createLoop({
+        ...loopInput,
+        target: { type: "workflow", workflowId: workflow.id }
+      });
+      return { kind: "created", workflow, loop, throttle };
     });
-    print({ deduped: false, idempotencyKey, event, workflow: publicWorkflow(workflow), loop: publicLoop(loop), preflight }, `created ${loop.id} (${loop.name}) workflow=${workflow.name} event=${event.id} idempotency=${idempotencyKey}`);
+    if (outcome.kind === "deduped") {
+      print({
+        deduped: true,
+        idempotencyKey,
+        dedupedBy: outcome.existingLoop.name === loopName ? "idempotency" : "legacy-event-name",
+        event,
+        workflow: outcome.existingWorkflow ? publicWorkflow(outcome.existingWorkflow) : undefined,
+        loop: publicLoop(outcome.existingLoop)
+      }, `deduped existing loop ${outcome.existingLoop.id} (${outcome.existingLoop.name}) for event=${event.id} idempotency=${idempotencyKey}`);
+      return;
+    }
+    if (outcome.kind === "throttled") {
+      print({
+        skipped: true,
+        queuedAtSource: true,
+        reason: outcome.throttle.reason,
+        idempotencyKey,
+        event,
+        throttle: outcome.throttle,
+        workflow: workflowBody,
+        loop: loopInput
+      }, `skipped task ${taskId}: ${outcome.throttle.reason}`);
+      return;
+    }
+    print({ deduped: false, idempotencyKey, event, workflow: publicWorkflow(outcome.workflow), loop: publicLoop(outcome.loop), throttle: outcome.throttle, preflight }, `created ${outcome.loop.id} (${outcome.loop.name}) workflow=${outcome.workflow.name} event=${event.id} idempotency=${idempotencyKey}`);
   } finally {
     store.close();
   }
 });
-eventsHandle.command("generic").description("create a one-shot worker/verifier workflow loop for any Hasna event").option("--provider <provider>", "agent provider", "codewith").option("--auth-profile <profile>", "provider-native auth profile; currently supported for codewith").option("--auth-profile-pool <profiles>", "comma-separated provider-native auth profile pool").option("--worker-auth-profile <profile>", "provider-native auth profile for worker step").option("--verifier-auth-profile <profile>", "provider-native auth profile for verifier step").option("--account <profile>", "OpenAccounts profile name").option("--account-pool <profiles>", "comma-separated OpenAccounts profile pool").option("--worker-account <profile>", "OpenAccounts profile for worker step").option("--verifier-account <profile>", "OpenAccounts profile for verifier step").option("--account-tool <tool>", "OpenAccounts tool id").option("--model <model>", "provider model").option("--variant <variant>", "provider-specific model variant or reasoning effort").option("--agent <agent>", "provider-specific agent").option("--permission-mode <mode>", "provider permission mode: default, plan, auto, or bypass", "bypass").option("--sandbox <mode>", "provider sandbox").option("--project-path <path>", "fallback project/repo working directory").option("--name-prefix <prefix>", "workflow/loop name prefix", "event:generic").option("--preflight", "check generated workflow steps before storing the workflow loop").option("--dry-run", "print the workflow and loop input without storing anything").action(async (opts) => {
+eventsHandle.command("generic").description("create a one-shot worker/verifier workflow loop for any Hasna event").option("--provider <provider>", "agent provider", "codewith").option("--auth-profile <profile>", "provider-native auth profile; currently supported for codewith").option("--auth-profile-pool <profiles>", "comma-separated provider-native auth profile pool").option("--worker-auth-profile <profile>", "provider-native auth profile for worker step").option("--verifier-auth-profile <profile>", "provider-native auth profile for verifier step").option("--account <profile>", "OpenAccounts profile name").option("--account-pool <profiles>", "comma-separated OpenAccounts profile pool").option("--worker-account <profile>", "OpenAccounts profile for worker step").option("--verifier-account <profile>", "OpenAccounts profile for verifier step").option("--account-tool <tool>", "OpenAccounts tool id").option("--model <model>", "provider model").option("--variant <variant>", "provider-specific model variant or reasoning effort").option("--agent <agent>", "provider-specific agent").option("--permission-mode <mode>", "provider permission mode: default, plan, auto, or bypass", "bypass").option("--sandbox <mode>", "provider sandbox").option("--project-path <path>", "fallback project/repo working directory").option("--project-group <name>", "optional project group for concurrency limits").option("--max-active <n>", "skip creating a workflow when this many active routed workflows already exist globally").option("--max-active-per-project <n>", "skip creating a workflow when this many active routed workflows already exist for the project").option("--max-active-per-project-group <n>", "skip creating a workflow when this many active routed workflows already exist for the project group").option("--worktree-mode <mode>", "worktree isolation mode: auto, required, off, or main", "auto").option("--worktree-root <path>", "base directory for OpenLoops-managed git worktrees").option("--worktree-branch-prefix <prefix>", "branch prefix for generated event worktrees", "openloops").option("--name-prefix <prefix>", "workflow/loop name prefix", "event:generic").option("--preflight", "check generated workflow steps before storing the workflow loop").option("--dry-run", "print the workflow and loop input without storing anything").action(async (opts) => {
   const event = await readEventEnvelopeFromStdin();
   const data = eventData(event);
-  const projectPath = opts.projectPath ?? taskEventField(data, ["working_dir", "workingDir", "project_path", "projectPath", "cwd", "repo_path", "repoPath"]) ?? process.cwd();
+  const metadata = eventMetadata(event);
+  const projectPath = opts.projectPath ?? taskEventField(data, ["working_dir", "workingDir", "project_path", "projectPath", "cwd", "repo_path", "repoPath"]) ?? taskEventField(metadata, ["working_dir", "workingDir", "project_path", "projectPath", "project_canonical_path", "cwd", "repo_path", "repoPath"]) ?? process.cwd();
+  const routeProjectPath = normalizeRoutePath(projectPath) ?? resolve2(projectPath);
+  const projectGroup = routeProjectGroup(opts.projectGroup, data, metadata);
+  const throttleLimits = routeThrottleLimitsFromOpts(opts);
+  const eventSuffix = event.id.slice(0, 8);
+  const source = slugSegment2(event.source, "source");
+  const type = slugSegment2(event.type, "type");
+  const workflowName = `${opts.namePrefix}:${source}:${type}:${eventSuffix}:workflow`;
+  const loopName = `${opts.namePrefix}:${source}:${type}:${eventSuffix}:run`;
+  if (!opts.dryRun) {
+    const store2 = new Store;
+    try {
+      const existingLoop = store2.findLoopByName(loopName);
+      if (existingLoop) {
+        const existingWorkflow = existingLoop.target.type === "workflow" ? store2.getWorkflow(existingLoop.target.workflowId) : undefined;
+        print({ deduped: true, event, workflow: existingWorkflow ? publicWorkflow(existingWorkflow) : undefined, loop: publicLoop(existingLoop) }, `deduped existing loop ${existingLoop.id} (${existingLoop.name})`);
+        return;
+      }
+    } finally {
+      store2.close();
+    }
+  }
   const provider = opts.provider;
   if (!["claude", "cursor", "codewith", "aicopilot", "opencode", "codex"].includes(provider))
     throw new Error("unsupported provider");
@@ -6508,6 +7001,8 @@ eventsHandle.command("generic").description("create a one-shot worker/verifier w
     eventMessage: stringField(event.message),
     eventJson: JSON.stringify(event),
     projectPath,
+    routeProjectPath,
+    projectGroup,
     provider,
     authProfile,
     authProfilePool: splitList(opts.authProfilePool),
@@ -6521,14 +7016,13 @@ eventsHandle.command("generic").description("create a one-shot worker/verifier w
     variant: opts.variant,
     agent: opts.agent,
     permissionMode,
-    sandbox
+    sandbox,
+    worktreeMode: opts.worktreeMode,
+    worktreeRoot: opts.worktreeRoot,
+    worktreeBranchPrefix: opts.worktreeBranchPrefix
   });
-  const eventSuffix = event.id.slice(0, 8);
-  const source = slugSegment(event.source, "source");
-  const type = slugSegment(event.type, "type");
-  workflowBody.name = `${opts.namePrefix}:${source}:${type}:${eventSuffix}:workflow`;
-  workflowBody.description = `Event-triggered worker/verifier workflow for ${event.source}/${event.type}`;
-  const loopName = `${opts.namePrefix}:${source}:${type}:${eventSuffix}:run`;
+  workflowBody.name = workflowName;
+  workflowBody.description = `Event-triggered worker/verifier workflow for ${event.source}/${event.type}; project=${projectPath}; projectGroup=${projectGroup ?? "-"}`;
   const loopInput = {
     name: loopName,
     description: `Run ${workflowBody.name} once for event ${event.id}`,
@@ -6540,35 +7034,50 @@ eventsHandle.command("generic").description("create a one-shot worker/verifier w
     leaseMs: 90 * 60000
   };
   if (opts.dryRun) {
+    const throttle = hasThrottleLimits(throttleLimits) ? routeThrottleDryRunPreview({ projectPath: routeProjectPath, projectGroup, limits: throttleLimits }) : undefined;
     const preflight = opts.preflight ? preflightStoredWorkflow(workflowSpecForPreflight(workflowBody, "event-preflight"), {
       name: workflowBody.name,
       type: "generic-event-workflow",
       event: event.id
     }, {}) : undefined;
-    print({ event, workflow: workflowBody, loop: loopInput, preflight }, `dry-run ${loopName}`);
+    print({ event, workflow: workflowBody, loop: loopInput, throttle, preflight }, `dry-run ${loopName}`);
     return;
   }
   const store = new Store;
   try {
-    const existingLoop = store.findLoopByName(loopName);
-    if (existingLoop) {
-      const existingWorkflow2 = existingLoop.target.type === "workflow" ? store.getWorkflow(existingLoop.target.workflowId) : undefined;
-      print({ deduped: true, event, workflow: existingWorkflow2 ? publicWorkflow(existingWorkflow2) : undefined, loop: publicLoop(existingLoop) }, `deduped existing loop ${existingLoop.id} (${existingLoop.name})`);
-      return;
-    }
-    const existingWorkflow = store.findWorkflowByName(workflowBody.name);
-    const workflowPreflightSpec = existingWorkflow ?? workflowSpecForPreflight(workflowBody, "event-preflight");
+    const existingWorkflowForPreflight = store.findWorkflowByName(workflowBody.name);
+    const workflowPreflightSpec = existingWorkflowForPreflight ?? workflowSpecForPreflight(workflowBody, "event-preflight");
     const preflight = opts.preflight ? preflightStoredWorkflow(workflowPreflightSpec, {
       name: workflowBody.name,
       type: "generic-event-workflow",
       event: event.id
     }, {}) : undefined;
-    const workflow = existingWorkflow ?? store.createWorkflow(workflowBody);
-    const loop = store.createLoop({
-      ...loopInput,
-      target: { type: "workflow", workflowId: workflow.id }
+    const outcome = store.writeTransaction(() => {
+      const existingLoop = store.findLoopByName(loopName);
+      if (existingLoop) {
+        const existingWorkflow2 = existingLoop.target.type === "workflow" ? store.getWorkflow(existingLoop.target.workflowId) : undefined;
+        return { kind: "deduped", existingLoop, existingWorkflow: existingWorkflow2 };
+      }
+      const throttle = hasThrottleLimits(throttleLimits) ? routeThrottleDecision(store, { projectPath: routeProjectPath, projectGroup, limits: throttleLimits }) : undefined;
+      if (throttle && !throttle.allowed)
+        return { kind: "throttled", throttle };
+      const existingWorkflow = store.findWorkflowByName(workflowBody.name);
+      const workflow = existingWorkflow ?? store.createWorkflow(workflowBody);
+      const loop = store.createLoop({
+        ...loopInput,
+        target: { type: "workflow", workflowId: workflow.id }
+      });
+      return { kind: "created", workflow, loop, throttle };
     });
-    print({ deduped: false, event, workflow: publicWorkflow(workflow), loop: publicLoop(loop), preflight }, `created ${loop.id} (${loop.name}) workflow=${workflow.name}`);
+    if (outcome.kind === "deduped") {
+      print({ deduped: true, event, workflow: outcome.existingWorkflow ? publicWorkflow(outcome.existingWorkflow) : undefined, loop: publicLoop(outcome.existingLoop) }, `deduped existing loop ${outcome.existingLoop.id} (${outcome.existingLoop.name})`);
+      return;
+    }
+    if (outcome.kind === "throttled") {
+      print({ skipped: true, queuedAtSource: true, reason: outcome.throttle.reason, event, throttle: outcome.throttle, workflow: workflowBody, loop: loopInput }, `skipped event ${event.id}: ${outcome.throttle.reason}`);
+      return;
+    }
+    print({ deduped: false, event, workflow: publicWorkflow(outcome.workflow), loop: publicLoop(outcome.loop), throttle: outcome.throttle, preflight }, `created ${outcome.loop.id} (${outcome.loop.name}) workflow=${outcome.workflow.name}`);
   } finally {
     store.close();
   }
@@ -7402,7 +7911,7 @@ ${result.instructions.join(`
 });
 daemon.command("logs").option("-n, --lines <n>", "lines", "80").action((opts) => {
   const path = daemonLogPath();
-  if (!existsSync3(path)) {
+  if (!existsSync4(path)) {
     console.log("");
     return;
   }