@hasna/loops 0.3.25 → 0.3.27

package/dist/lib/store.js

@@ -416,6 +416,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`);
@@ -2187,6 +2223,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();
   }

package/dist/lib/templates.d.ts

@@ -1,4 +1,4 @@
-import type { AccountRef, AgentPermissionMode, AgentProvider, AgentSandbox, CreateWorkflowInput, LoopTemplateSummary } from "../types.js";
+import type { AccountRef, AgentPermissionMode, AgentProvider, AgentSandbox, AgentWorktreeMode, CreateWorkflowInput, LoopTemplateSummary } from "../types.js";
 export declare const TODOS_TASK_WORKER_VERIFIER_TEMPLATE_ID = "todos-task-worker-verifier";
 export declare const EVENT_WORKER_VERIFIER_TEMPLATE_ID = "event-worker-verifier";
 export declare const BOUNDED_AGENT_WORKER_VERIFIER_TEMPLATE_ID = "bounded-agent-worker-verifier";
@@ -7,6 +7,8 @@ export interface TodosTaskWorkflowTemplateInput {
     taskTitle?: string;
     taskDescription?: string;
     projectPath: string;
+    routeProjectPath?: string;
+    projectGroup?: string;
     provider?: AgentProvider;
     authProfile?: string;
     authProfilePool?: string[];
@@ -21,6 +23,9 @@ export interface TodosTaskWorkflowTemplateInput {
     agent?: string;
     permissionMode?: AgentPermissionMode;
     sandbox?: AgentSandbox;
+    worktreeMode?: AgentWorktreeMode;
+    worktreeRoot?: string;
+    worktreeBranchPrefix?: string;
     eventId?: string;
     eventType?: string;
 }
@@ -32,6 +37,8 @@ export interface EventWorkflowTemplateInput {
     eventMessage?: string;
     eventJson: string;
     projectPath: string;
+    routeProjectPath?: string;
+    projectGroup?: string;
     provider?: AgentProvider;
     authProfile?: string;
     authProfilePool?: string[];
@@ -46,12 +53,17 @@ export interface EventWorkflowTemplateInput {
     agent?: string;
     permissionMode?: AgentPermissionMode;
     sandbox?: AgentSandbox;
+    worktreeMode?: AgentWorktreeMode;
+    worktreeRoot?: string;
+    worktreeBranchPrefix?: string;
 }
 export interface BoundedAgentWorkflowTemplateInput {
     name?: string;
     objective: string;
     prompt?: string;
     projectPath: string;
+    routeProjectPath?: string;
+    projectGroup?: string;
     provider?: AgentProvider;
     authProfile?: string;
     authProfilePool?: string[];
@@ -66,6 +78,9 @@ export interface BoundedAgentWorkflowTemplateInput {
     agent?: string;
     permissionMode?: AgentPermissionMode;
     sandbox?: AgentSandbox;
+    worktreeMode?: AgentWorktreeMode;
+    worktreeRoot?: string;
+    worktreeBranchPrefix?: string;
     timeoutMs?: number;
 }
 export declare function listLoopTemplates(): LoopTemplateSummary[];

package/dist/sdk/index.js

@@ -416,6 +416,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`);
@@ -2187,6 +2223,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();
   }

package/dist/types.d.ts

@@ -63,6 +63,26 @@ export interface AgentAllowlistSpec {
     commands?: string[];
     enforcement?: "metadata_only";
 }
+export type AgentWorktreeMode = "auto" | "required" | "off" | "main";
+export interface AgentWorktreeSpec {
+    mode: AgentWorktreeMode;
+    enabled: boolean;
+    originalCwd: string;
+    cwd: string;
+    repoRoot?: string;
+    root?: string;
+    path?: string;
+    branch?: string;
+    reason?: string;
+}
+export interface AgentRoutingSpec {
+    projectPath?: string;
+    projectGroup?: string;
+    taskId?: string;
+    eventId?: string;
+    eventType?: string;
+    eventSource?: string;
+}
 export interface AgentTarget {
     type: "agent";
     provider: AgentProvider;
@@ -78,6 +98,8 @@ export interface AgentTarget {
     permissionMode?: AgentPermissionMode;
     sandbox?: AgentSandbox;
     allowlist?: AgentAllowlistSpec;
+    worktree?: AgentWorktreeSpec;
+    routing?: AgentRoutingSpec;
     account?: AccountRef;
     preflight?: RuntimePreflightPolicy;
 }

package/docs/USAGE.md

@@ -243,6 +243,26 @@ loops templates render bounded-agent-worker-verifier \
   --var sandbox=danger-full-access
 ```
 
+Task/event agent templates default to `worktreeMode=auto`. When `projectPath`
+is an existing git repository, OpenLoops inserts a `prepare-worktree` command
+step before the worker and runs the worker/verifier from a deterministic
+worktree under `~/.hasna/loops/worktrees/<repo>/<run>`. The generated agent
+target includes worktree metadata (`mode`, `cwd`, `path`, `branch`,
+`originalCwd`) so dry-runs and workflow inspection expose the exact checkout.
+
+Use explicit main/default checkout mode only when the task truly requires it:
+
+```bash
+loops templates render todos-task-worker-verifier \
+  --var taskId=<task-id> \
+  --var projectPath=/path/to/repo \
+  --var worktreeMode=main
+```
+
+Use `worktreeMode=required` when non-worktree execution should fail fast, or
+`worktreeMode=off` for non-git projects. `worktreeRoot` and
+`worktreeBranchPrefix` can override the storage root and branch prefix.
+
 For event-driven task automation, `loops events handle todos-task` reads a
 Hasna event envelope from stdin or `HASNA_EVENT_JSON`, renders the template, and
 schedules a deduped one-shot workflow loop:
@@ -252,7 +272,8 @@ cat task-created-event.json | loops events handle todos-task \
   --provider codewith \
   --auth-profile-pool account004,account005,account006 \
   --permission-mode bypass \
-  --sandbox danger-full-access
+  --sandbox danger-full-access \
+  --worktree-mode auto
 ```
 
 Task routing is explicit opt-in. The handler skips the event without creating a
@@ -263,6 +284,32 @@ approval-required, or `no-auto` tasks. This guard exists even when the upstream
 `@hasna/events` webhook filter is misconfigured, so task existence alone is not
 permission to execute agent work.
 
+Use route throttles to avoid stampeding agents when a producer creates many
+tasks at once:
+
+```bash
+cat task-created-event.json | loops events handle todos-task \
+  --provider codewith \
+  --auth-profile-pool account004,account005,account006 \
+  --project-group oss \
+  --max-active-per-project 1 \
+  --max-active-per-project-group 4 \
+  --max-active 12
+```
+
+The limits count active routed worker/verifier workflow loops once per workflow.
+`--max-active-per-project` gates new work for the same project path,
+`--max-active-per-project-group` shares a pool across related projects such as
+`oss`, and `--max-active` is the global routed-workflow cap. Project matching
+uses the canonical git top-level path when available, so repo subdirectories
+share the same project cap. A throttled event is skipped with JSON evidence and
+`queuedAtSource=true` instead of creating another worker loop; the source task
+remains the durable queue item and should be replayed/drained later by the task
+scheduler. Re-delivering the event later is safe because event handlers dedupe
+by task/event id before rendering worktree plans or checking route limits. In
+dry-run mode, throttle counts are not evaluated because opening the live loop
+store can create or migrate the local database.
+
 For other Hasna apps that expose `@hasna/events` webhooks, use the generic
 handler:
 
@@ -281,7 +328,8 @@ verifier workflow, and the workflow updates todos with evidence. Use account
 pools so worker and verifier steps do not burn the same profile; OpenLoops picks
 deterministically and uses a different verifier profile when the pool has at
 least two entries. Use `--dry-run` to inspect the rendered workflow and loop
-input without storing anything.
+input without storing anything, including the worktree path and branch for
+git-backed tasks.
 
 ## Transcript-Driven Loops
 
@@ -338,6 +386,14 @@ Use `--dry-run --json` first when testing a new automation path. Routed tasks
 include the stable failure fingerprint, classification, loop id/name, and
 `no_tmux_dispatch=true` metadata.
 
+Use `--evidence-dir <dir>` when a deterministic loop needs a compact JSON
+heartbeat/report on disk. Use `--auto-route` only on task lists that should feed
+the task-created headless worker/verifier workflow; it adds the `auto:route`
+tag and route metadata when the finding has a cwd or `--route-project-path` is
+provided. Findings with no routeable working directory remain plain tasks and
+record an `auto_route_skipped_reason`. Without `--auto-route`, route commands
+only upsert deduped tasks and do not launch agents.
+
 Failure classifications are: `rate_limit`, `auth`, `model_not_found`,
 `context_length`, `schema_response_format`, `node_init`, `timeout`, `sigsegv`,
 `skipped_previous_active`, and `unknown`.
@@ -441,4 +497,7 @@ The adapters intentionally use provider command surfaces instead of pretending e
 - `--variant` is provider-specific reasoning/model effort. Claude maps it to `--effort`, Codewith/Codex map it to `model_reasoning_effort`, and OpenCode/AICopilot pass `--variant`.
 - Daemon and scheduled runs prepend common user executable directories such as `~/.local/bin` and `~/.bun/bin` before resolving provider CLIs.
 
-For production loops that can mutate repos, prefer disposable worktrees and explicit prompts that name allowed write scope.
+For production loops that can mutate repos, prefer the built-in
+`worktreeMode=auto`/`required` path and explicit prompts that name allowed write
+scope. Use `main` or `off` only for operations that intentionally need the
+original checkout.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/loops",
-  "version": "0.3.25",
+  "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",