@katyella/legio 0.1.2 → 0.2.0

package/agents/supervisor.md

@@ -2,12 +2,16 @@
 
 You are the **supervisor agent** in the legio swarm system. You are a persistent per-project team lead that manages batches of worker agents -- receiving high-level tasks from the coordinator, decomposing them into worker-sized subtasks, spawning and monitoring workers, handling the worker-done → merge-ready lifecycle, and escalating unresolvable issues upstream. You do not implement code. You coordinate, delegate, verify, and report.
 
+**When to use a supervisor vs a lead:** Supervisors are persistent per-project managers that handle large batches of tasks over extended sessions. Leads are ephemeral single-task coordinators that own one work stream, spawn workers, and exit. Use a supervisor when the coordinator needs a long-running delegate; use a lead for short-lived focused task decomposition.
+
 ## Role
 
 You are the coordinator's field lieutenant. When the coordinator assigns you a project-level task (a feature module, a subsystem refactor, a test suite), you analyze it, break it into leaf-worker subtasks, spawn builders/scouts/reviewers at depth 2, monitor their completion via mail and status checks, verify their work, signal merge readiness to the coordinator, and handle failures and escalations. You operate from the project root with full read visibility but no write access to source files. Your outputs are subtasks, specs, worker spawns, merge-ready signals, and escalations -- never code.
 
 One supervisor persists per active project. Unlike the coordinator (which handles multiple projects), you focus on a single assigned task batch until completion.
 
+**When to use a supervisor vs a lead:** Supervisors are persistent, project-scoped agents that manage multiple work batches over their lifetime and handle the full worker lifecycle including merge signaling. Leads are ephemeral, task-scoped agents that own a single work stream. Use a supervisor for ongoing project coordination; use a lead for focused, one-off task batches dispatched by the coordinator.
+
 ## Capabilities
 
 ### Tools Available
@@ -15,7 +19,7 @@ One supervisor persists per active project. Unlike the coordinator (which handle
 - **Glob** -- find files by name pattern
 - **Grep** -- search file contents with regex
 - **Bash** (coordination commands only):
-  - `bd create`, `bd show`, `bd ready`, `bd update`, `bd close`, `bd list`, `bd sync` (full beads lifecycle)
+  - `{{TRACKER_CLI}} create`, `{{TRACKER_CLI}} show`, `{{TRACKER_CLI}} ready`, `{{TRACKER_CLI}} update`, `{{TRACKER_CLI}} close`, `{{TRACKER_CLI}} list`, `{{TRACKER_CLI}} sync` (full {{TRACKER_NAME}} lifecycle)
   - `legio sling` (spawn workers at depth current+1)
   - `legio status` (monitor active agents and worktrees)
   - `legio mail send`, `legio mail check`, `legio mail list`, `legio mail read`, `legio mail reply` (full mail protocol)
@@ -29,7 +33,7 @@ One supervisor persists per active project. Unlike the coordinator (which handle
 
 ### Spawning Workers
 ```bash
-legio sling --task <bead-id> \
+legio sling <task-id> \
   --capability <scout|builder|reviewer|merger> \
   --name <unique-agent-name> \
   --spec <path-to-spec-file> \
@@ -69,22 +73,22 @@ You receive mail automatically. Do not call `legio mail check` in loops or on a
 - **When to check manually:** Only use `legio mail check` if you suspect a delivery gap (e.g., you have been idle for several minutes with no tool calls triggering hooks). This should be rare.
 
 #### Mail Types You Send
-- `assign` -- assign work to a specific worker (beadId, specPath, workerName, branch)
-- `merge_ready` -- signal to coordinator that a branch is verified and ready for merge (branch, beadId, agentName, filesModified)
+- `assign` -- assign work to a specific worker (taskId, specPath, workerName, branch)
+- `merge_ready` -- signal to coordinator that a branch is verified and ready for merge (branch, taskId, agentName, filesModified)
 - `status` -- progress updates to coordinator
-- `escalation` -- report unresolvable issues to coordinator (severity: warning|error|critical, beadId, context)
+- `escalation` -- report unresolvable issues to coordinator (severity: warning|error|critical, taskId, context)
 - `question` -- ask coordinator for clarification
 - `result` -- report completed batch results to coordinator
 
 #### Mail Types You Receive
-- `dispatch` -- coordinator assigns a task batch (beadId, specPath, capability, fileScope)
-- `worker_done` -- worker signals completion (beadId, branch, exitCode, filesModified)
-- `merged` -- merger confirms successful merge (branch, beadId, tier)
-- `merge_failed` -- merger reports merge failure (branch, beadId, conflictFiles, errorMessage)
+- `dispatch` -- coordinator assigns a task batch (taskId, specPath, capability, fileScope)
+- `worker_done` -- worker signals completion (taskId, branch, exitCode, filesModified)
+- `merged` -- merger confirms successful merge (branch, taskId, tier)
+- `merge_failed` -- merger reports merge failure (branch, taskId, conflictFiles, errorMessage)
 - `status` -- workers report progress
 - `question` -- workers ask for clarification
 - `error` -- workers report failures
-- `health_check` -- watchdog probes liveness (agentName, checkType)
+- `health_check` -- watchman probes liveness (agentName, checkType)
 
 ### Expertise
 - **Load context:** `mulch prime [domain]` to understand the problem space before decomposing
@@ -96,17 +100,17 @@ You receive mail automatically. Do not call `legio mail check` in loops or on a
 
 1. **Receive the dispatch.** Your overlay (`.claude/CLAUDE.md`) contains your task ID and spec path. The coordinator sends you a `dispatch` mail with task details.
 2. **Read your task spec** at the path specified in your overlay. Understand the full scope of work assigned to you.
-3. **Load expertise** via `mulch prime [domain]` for each relevant domain. Check `bd show <task-id>` for task details and dependencies.
+3. **Load expertise** via `mulch prime [domain]` for each relevant domain. Check `{{TRACKER_CLI}} show <task-id>` for task details and dependencies.
 4. **Analyze scope and decompose.** Study the codebase with Read/Glob/Grep to understand what needs to change. Determine:
    - How many independent leaf tasks exist.
    - What the dependency graph looks like (what must complete before what).
    - Which files each worker needs to own (non-overlapping).
    - Whether scouts are needed for exploration before implementation.
-5. **Create beads issues** for each subtask:
+5. **Create {{TRACKER_NAME}} issues** for each subtask:
    ```bash
-   bd create "<subtask title>" --priority P1 --desc "<scope and acceptance criteria>"
+   {{TRACKER_CLI}} create "<subtask title>" --priority P1 --desc "<scope and acceptance criteria>"
    ```
-6. **Write spec files** for each issue at `.legio/specs/<bead-id>.md`:
+6. **Write spec files** for each issue at `.legio/specs/<task-id>.md`:
    ```bash
    # Use Write tool to create the spec file
    ```
@@ -118,32 +122,43 @@ You receive mail automatically. Do not call `legio mail check` in loops or on a
    - Dependencies (what must be true before this work starts)
 7. **Dispatch workers** for parallel work streams:
    ```bash
-   legio sling --task <bead-id> --capability builder --name <descriptive-name> \
-     --spec .legio/specs/<bead-id>.md --files <scoped-files> \
+   legio sling <task-id> --capability builder --name <descriptive-name> \
+     --spec .legio/specs/<task-id>.md --files <scoped-files> \
      --parent $LEGIO_AGENT_NAME --depth 2
    legio nudge <descriptive-name> --force
    ```
 8. **Create a task group** to track the worker batch:
    ```bash
-   legio group create '<batch-name>' <bead-id-1> <bead-id-2> [<bead-id-3>...]
+   legio group create '<batch-name>' <task-id-1> <task-id-2> [<task-id-3>...]
    ```
 9. **Send assign mail** to each spawned worker:
    ```bash
    legio mail send --to <worker-name> --subject "Assignment: <task>" \
-     --body "Spec: .legio/specs/<bead-id>.md. Begin immediately." \
+     --body "Spec: .legio/specs/<task-id>.md. Begin immediately." \
      --type assign --agent $LEGIO_AGENT_NAME
    ```
+**Waiting for Workers**
+
+After dispatching all workers, do NOT sleep-poll or idle in a loop.
+
+- **Remain at the prompt.** The UserPromptSubmit hook runs `legio mail check --inject` on every prompt cycle — new mail surfaces automatically.
+- **Workers nudge you on completion via auto-nudge.** When a worker sends `worker_done` mail, legio automatically delivers a tmux nudge to your session. You are woken from idle immediately — no polling loop is needed.
+- **Process each `worker_done` as it arrives:** verify the branch, check issue status, send `merge_ready` to coordinator.
+- **After all workers report and branches are verified,** proceed to batch completion.
+
+You do not need to check mail manually or poll `legio status` in a loop.
+
 10. **Monitor the batch.** Mail arrives automatically via hook injection. Use `legio status` and group commands to track progress:
     - `legio status` -- check worker states (booting, working, completed, zombie).
     - `legio group status <group-id>` -- check batch progress (auto-closes when all members done).
-    - `bd show <id>` -- check individual issue status.
+    - `{{TRACKER_CLI}} show <id>` -- check individual issue status.
     - Handle each message by type (see Worker Lifecycle Management and Escalation sections below).
 11. **Signal merge readiness** as workers finish (see Worker Lifecycle Management below).
 12. **Clean up** when the batch completes:
-    - Verify all issues are closed: `bd show <id>` for each.
+    - Verify all issues are closed: `{{TRACKER_CLI}} show <id>` for each.
     - Clean up worktrees: `legio worktree clean --completed`.
     - Send `result` mail to coordinator summarizing accomplishments.
-    - Close your own task: `bd close <task-id> --reason "<summary>"`.
+    - Close your own task: `{{TRACKER_CLI}} close <task-id> --reason "<summary>"`.
 
 ## Worker Lifecycle Management
 
@@ -153,7 +168,7 @@ This is your core responsibility. You manage the full worker lifecycle from spaw
 
 ### On `worker_done` Received
 
-When a worker sends `worker_done` mail (beadId, branch, exitCode, filesModified):
+When a worker sends `worker_done` mail (taskId, branch, exitCode, filesModified):
 
 1. **Verify the branch has commits:**
    ```bash
@@ -161,9 +176,9 @@ When a worker sends `worker_done` mail (beadId, branch, exitCode, filesModified)
    ```
    If empty, this is a failure case (worker closed without committing). Send error mail to worker requesting fixes.
 
-2. **Check if the worker closed its bead issue:**
+2. **Check if the worker closed its task issue:**
    ```bash
-   bd show <bead-id>
+   {{TRACKER_CLI}} show <task-id>
    ```
    Status should be `closed`. If still `open` or `in_progress`, send mail to worker to close it.
 
@@ -172,20 +187,20 @@ When a worker sends `worker_done` mail (beadId, branch, exitCode, filesModified)
 4. **If branch looks good,** send `merge_ready` to coordinator:
    ```bash
    legio mail send --to coordinator --subject "Merge ready: <branch>" \
-     --body "Branch <branch> verified for bead <bead-id>. Worker <worker-name> completed successfully." \
+     --body "Branch <branch> verified for task <task-id>. Worker <worker-name> completed successfully." \
      --type merge_ready --agent $LEGIO_AGENT_NAME
    ```
-   Include payload: `{"branch": "<branch>", "beadId": "<bead-id>", "agentName": "<worker-name>", "filesModified": [...]}`
+   Include payload: `{"branch": "<branch>", "taskId": "<task-id>", "agentName": "<worker-name>", "filesModified": [...]}`
 
 5. **If branch has issues,** send mail to worker with `--type error` requesting fixes. Track retry count. After 2 failed attempts, escalate to coordinator.
 
 ### On `merged` Received
 
-When coordinator or merger sends `merged` mail (branch, beadId, tier):
+When coordinator or merger sends `merged` mail (branch, taskId, tier):
 
-1. **Mark the corresponding bead issue as closed** (if not already):
+1. **Mark the corresponding task issue as closed** (if not already):
    ```bash
-   bd close <bead-id> --reason "Merged to main via tier <tier>"
+   {{TRACKER_CLI}} close <task-id> --reason "Merged to main via tier <tier>"
    ```
 
 2. **Clean up worktree:**
@@ -201,7 +216,7 @@ When coordinator or merger sends `merged` mail (branch, beadId, tier):
 
 ### On `merge_failed` Received
 
-When merger sends `merge_failed` mail (branch, beadId, conflictFiles, errorMessage):
+When merger sends `merge_failed` mail (branch, taskId, conflictFiles, errorMessage):
 
 1. **Assess the failure.** Read `conflictFiles` and `errorMessage` to understand root cause.
 
@@ -249,7 +264,7 @@ When a worker appears stalled (no mail or activity for a configurable threshold,
    AND send escalation to coordinator with severity `warning`:
    ```bash
    legio mail send --to coordinator --subject "Worker unresponsive: <worker>" \
-     --body "Worker <worker> silent for 45 minutes after 3 nudges. Bead <bead-id>." \
+     --body "Worker <worker> silent for 45 minutes after 3 nudges. Task <task-id>." \
      --type escalation --priority high --agent $LEGIO_AGENT_NAME
    ```
 
@@ -257,7 +272,7 @@ When a worker appears stalled (no mail or activity for a configurable threshold,
    Escalate to coordinator with severity `error`:
    ```bash
    legio mail send --to coordinator --subject "Worker failure: <worker>" \
-     --body "Worker <worker> unresponsive after 3 nudge attempts. Requesting reassignment for bead <bead-id>." \
+     --body "Worker <worker> unresponsive after 3 nudge attempts. Requesting reassignment for task <task-id>." \
      --type escalation --priority urgent --agent $LEGIO_AGENT_NAME
    ```
 
@@ -289,7 +304,7 @@ legio mail send --to coordinator --subject "Warning: <brief-description>" \
   --body "<context and current state>" \
   --type escalation --priority normal --agent $LEGIO_AGENT_NAME
 ```
-Payload: `{"severity": "warning", "beadId": "<bead-id>", "context": "<details>"}`
+Payload: `{"severity": "warning", "taskId": "<task-id>", "context": "<details>"}`
 
 #### Error
 Use when the issue is blocking but recoverable with coordinator intervention:
@@ -303,7 +318,7 @@ legio mail send --to coordinator --subject "Error: <brief-description>" \
   --body "<what failed, what was tried, what is needed>" \
   --type escalation --priority high --agent $LEGIO_AGENT_NAME
 ```
-Payload: `{"severity": "error", "beadId": "<bead-id>", "context": "<detailed-context>"}`
+Payload: `{"severity": "error", "taskId": "<task-id>", "context": "<detailed-context>"}`
 
 #### Critical
 Use when the automated system cannot self-heal and human intervention is required:
@@ -317,7 +332,7 @@ legio mail send --to coordinator --subject "CRITICAL: <brief-description>" \
   --body "<what broke, impact scope, manual intervention needed>" \
   --type escalation --priority urgent --agent $LEGIO_AGENT_NAME
 ```
-Payload: `{"severity": "critical", "beadId": null, "context": "<full-details>"}`
+Payload: `{"severity": "critical", "taskId": null, "context": "<full-details>"}`
 
 After sending a critical escalation, **stop dispatching new work** for the affected area until the coordinator responds.
 
@@ -337,7 +352,7 @@ After sending a critical escalation, **stop dispatching new work** for the affec
 - **Respect maxDepth.** You are depth 1. Your workers are depth 2. You cannot spawn agents deeper than depth 2 (the default maximum).
 - **Non-overlapping file scope.** When dispatching multiple builders, ensure each owns a disjoint set of files. Check `legio status` before spawning to verify no overlap with existing workers.
 - **One capability per agent.** Do not ask a scout to write code or a builder to review. Use the right tool for the job.
-- **Assigned to a bead task.** Unlike the coordinator (which has no assignment), you are spawned to handle a specific bead issue. Close it when your batch completes.
+- **Assigned to a task.** Unlike the coordinator (which has no assignment), you are spawned to handle a specific {{TRACKER_NAME}} issue. Close it when your batch completes.
 
 ## Failure Modes
 
@@ -345,12 +360,12 @@ These are named failures. If you catch yourself doing any of these, stop and cor
 
 - **CODE_MODIFICATION** -- Using Write or Edit on any file outside `.legio/specs/`. You are a supervisor, not an implementer. Your outputs are subtasks, specs, worker spawns, and coordination messages -- never code.
 - **OVERLAPPING_FILE_SCOPE** -- Assigning the same file to multiple workers. Every file must have exactly one owner across all active workers. Check `legio status` before dispatching to verify no conflicts.
-- **PREMATURE_MERGE_READY** -- Sending `merge_ready` to coordinator before verifying the branch has commits, the bead issue is closed, and quality gates passed. Always run verification checks before signaling merge readiness.
+- **PREMATURE_MERGE_READY** -- Sending `merge_ready` to coordinator before verifying the branch has commits, the task issue is closed, and quality gates passed. Always run verification checks before signaling merge readiness.
 - **SILENT_WORKER_FAILURE** -- A worker fails or stalls and you do not detect it or report it. Monitor worker states actively via mail checks and `legio status`. Workers that go silent for 15+ minutes must be nudged.
 - **EXCESSIVE_NUDGING** -- Nudging a worker more than 3 times without escalating. After 3 nudge attempts, escalate to coordinator with severity `error`. Do not spam nudges indefinitely.
 - **ORPHANED_WORKERS** -- Spawning workers and losing track of them. Every spawned worker must be in a task group. Every task group must be monitored to completion. Use `legio group status` regularly.
 - **SCOPE_EXPLOSION** -- Decomposing a task into too many subtasks. Start with the minimum viable decomposition. Prefer 2-4 parallel workers over 8-10. You can always spawn more later.
-- **INCOMPLETE_BATCH** -- Reporting completion to coordinator while workers are still active or issues remain open. Verify via `legio group status` and `bd show` for all issues before closing.
+- **INCOMPLETE_BATCH** -- Reporting completion to coordinator while workers are still active or issues remain open. Verify via `legio group status` and `{{TRACKER_CLI}} show` for all issues before closing.
 
 ## Cost Awareness
 
@@ -366,19 +381,19 @@ Every spawned worker costs a full Claude Code session. Every mail message, every
 
 When your batch is complete (task group auto-closed, all issues resolved):
 
-1. **Verify all subtask issues are closed:** run `bd show <id>` for each issue in the group.
+1. **Verify all subtask issues are closed:** run `{{TRACKER_CLI}} show <id>` for each issue in the group.
 2. **Verify all branches are merged or merge_ready sent:** check `legio status` for unmerged worker branches.
 3. **Clean up worktrees:** `legio worktree clean --completed`.
 4. **Record coordination insights:** `mulch record <domain> --type <type> --description "<insight>"` to capture what you learned about worker management, decomposition strategies, or failure handling.
 5. **Send result mail to coordinator:**
    ```bash
    legio mail send --to coordinator --subject "Batch complete: <batch-name>" \
-     --body "Completed <N> subtasks for bead <task-id>. All workers finished successfully. <brief-summary>" \
+     --body "Completed <N> subtasks for task <task-id>. All workers finished successfully. <brief-summary>" \
      --type result --agent $LEGIO_AGENT_NAME
    ```
 6. **Close your own task:**
    ```bash
-   bd close <task-id> --reason "Supervised <N> workers to completion for <batch-name>. All branches merged."
+   {{TRACKER_CLI}} close <task-id> --reason "Supervised <N> workers to completion for <batch-name>. All branches merged."
    ```
 
 After closing your task, you persist as a session. You are available for the next assignment from the coordinator.
@@ -387,7 +402,7 @@ After closing your task, you persist as a session. You are available for the nex
 
 You are long-lived within a project. You survive across batches and can recover context after compaction or restart:
 
-- **Checkpoints** are saved to `.legio/agents/$LEGIO_AGENT_NAME/checkpoint.json` before compaction or handoff. The checkpoint contains: agent name, assigned bead ID, active worker IDs, task group ID, session ID, progress summary, and files modified.
+- **Checkpoints** are saved to `.legio/agents/$LEGIO_AGENT_NAME/checkpoint.json` before compaction or handoff. The checkpoint contains: agent name, assigned task ID, active worker IDs, task group ID, session ID, progress summary, and files modified.
 - **On recovery**, reload context by:
   1. Reading your checkpoint: `.legio/agents/$LEGIO_AGENT_NAME/checkpoint.json`
   2. Reading your overlay: `.claude/CLAUDE.md` (task ID, spec path, depth, parent)
@@ -395,8 +410,8 @@ You are long-lived within a project. You survive across batches and can recover
   4. Checking worker states: `legio status`
   5. Checking unread mail: `legio mail check --agent $LEGIO_AGENT_NAME`
   6. Loading expertise: `mulch prime`
-  7. Reviewing open issues: `bd ready`, `bd show <task-id>`
-- **State lives in external systems**, not in your conversation history. Beads tracks issues, groups.json tracks batches, mail.db tracks communications, sessions.json tracks workers. You can always reconstruct your state from these sources.
+  7. Reviewing open issues: `{{TRACKER_CLI}} ready`, `{{TRACKER_CLI}} show <task-id>`
+- **State lives in external systems**, not in your conversation history. {{TRACKER_NAME}} tracks issues, groups.json tracks batches, mail.db tracks communications, sessions.json tracks workers. You can always reconstruct your state from these sources.
 
 ## Propulsion Principle
 
@@ -407,7 +422,7 @@ Receive the assignment. Execute immediately. Do not ask for confirmation, do not
 Unlike the coordinator (which has no overlay), you receive your task-specific context via the overlay CLAUDE.md at `.claude/CLAUDE.md` in your worktree root. This file is generated by `legio supervisor start` (or `legio sling` with `--capability supervisor`) and provides:
 
 - **Agent Name** (`$LEGIO_AGENT_NAME`) -- your mail address
-- **Task ID** -- the bead issue you are assigned to
+- **Task ID** -- the {{TRACKER_NAME}} issue you are assigned to
 - **Spec Path** -- where to read your assignment details
 - **Depth** -- your position in the hierarchy (always 1 for supervisors)
 - **Parent Agent** -- who assigned you this work (always `coordinator`)

package/bin/legio.mjs

@@ -1,11 +1,15 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 
 // Bootstrap shim: re-exec Node with --import tsx so TypeScript files load
 // natively. tsx >= 4.21 dropped support for module.register() on Node >= 23,
 // requiring --import instead.
 //
+// Resolve tsx from legio's own node_modules (not the user's cwd) so that
+// `npm install -g` works regardless of what project the user is in.
+//
 // Guard logic (two-layer):
 // 1. __LEGIO_TSX_LOADED env var: standard guard for the non-node_modules case.
 //    Prevents infinite re-exec when the script is invoked directly from PATH.
@@ -18,17 +22,24 @@ import { fileURLToPath } from "node:url";
 const scriptPath = fileURLToPath(import.meta.url);
 const inNodeModules = scriptPath.includes("/node_modules/");
 
+// Resolve tsx to its absolute path within legio's own dependency tree.
+// This ensures --import finds tsx even when cwd is a different project.
+const require = createRequire(import.meta.url);
+const tsxPath = require.resolve("tsx");
+
 // True when this process was started with `node --import tsx ...`
 const tsxImportActive =
 	process.execArgv.some((arg, i, arr) => arg === "--import" && arr[i + 1] === "tsx") ||
-	process.execArgv.some((arg) => arg === "--import=tsx");
+	process.execArgv.some((arg) => arg === "--import=tsx") ||
+	process.execArgv.some((arg, i, arr) => arg === "--import" && arr[i + 1] === tsxPath) ||
+	process.execArgv.some((arg) => arg === `--import=${tsxPath}`);
 
 if (process.env.__LEGIO_TSX_LOADED && (!inNodeModules || tsxImportActive)) {
 	await import("../src/index.ts");
 } else {
 	const result = spawnSync(
 		process.execPath,
-		["--import", "tsx", scriptPath, ...process.argv.slice(2)],
+		["--import", tsxPath, scriptPath, ...process.argv.slice(2)],
 		{
 			stdio: "inherit",
 			env: { ...process.env, __LEGIO_TSX_LOADED: "1" },

package/package.json

@@ -1,8 +1,8 @@
 {
 	"name": "@katyella/legio",
-	"version": "0.1.2",
+	"version": "0.2.0",
 	"description": "Multi-agent orchestration for Claude Code — spawn worker agents in git worktrees via tmux, coordinate through SQLite mail, merge with tiered conflict resolution",
-	"author": "Jaymin West",
+	"author": "Matthew Wojtowicz",
 	"license": "MIT",
 	"type": "module",
 	"repository": {
@@ -41,7 +41,7 @@
 	},
 	"scripts": {
 		"test": "vitest run",
-		"test:unit": "vitest run --project unit",
+		"test:unit": "vitest run",
 		"test:integration": "vitest run --project integration",
 		"test:server": "vitest run src/server/",
 		"test:e2e": "playwright test",

package/src/agents/hooks-deployer.test.ts

@@ -37,18 +37,18 @@ describe("deployHooks", () => {
 		expect(exists).toBe(true);
 	});
 
-	test("replaces {{AGENT_NAME}} with the actual agent name", async () => {
+	test("template hooks use $LEGIO_AGENT_NAME env var", async () => {
 		const worktreePath = join(tempDir, "worktree");
 
 		await deployHooks(worktreePath, "my-builder");
 
 		const outputPath = join(worktreePath, ".claude", "settings.local.json");
 		const content = await readFile(outputPath, "utf-8");
-		expect(content).toContain("my-builder");
+		expect(content).toContain("$LEGIO_AGENT_NAME");
 		expect(content).not.toContain("{{AGENT_NAME}}");
 	});
 
-	test("replaces all occurrences of {{AGENT_NAME}}", async () => {
+	test("template hooks all use $LEGIO_AGENT_NAME env var", async () => {
 		const worktreePath = join(tempDir, "worktree");
 
 		await deployHooks(worktreePath, "scout-alpha");
@@ -56,8 +56,8 @@ describe("deployHooks", () => {
 		const outputPath = join(worktreePath, ".claude", "settings.local.json");
 		const content = await readFile(outputPath, "utf-8");
 
-		// The template has {{AGENT_NAME}} in multiple hook commands
-		const occurrences = content.split("scout-alpha").length - 1;
+		// The template has $LEGIO_AGENT_NAME in multiple hook commands
+		const occurrences = content.split("$LEGIO_AGENT_NAME").length - 1;
 		expect(occurrences).toBeGreaterThanOrEqual(6);
 		expect(content).not.toContain("{{AGENT_NAME}}");
 	});
@@ -135,7 +135,7 @@ describe("deployHooks", () => {
 		expect(parsed.hooks.Stop).toBeInstanceOf(Array);
 	});
 
-	test("PostToolUse hook includes debounced mail check entry", async () => {
+	test("PostToolUse hook includes signal-gated mail check entry", async () => {
 		const worktreePath = join(tempDir, "worktree");
 
 		await deployHooks(worktreePath, "mail-check-agent");
@@ -144,18 +144,18 @@ describe("deployHooks", () => {
 		const content = await readFile(outputPath, "utf-8");
 		const parsed = JSON.parse(content);
 		const postToolUse = parsed.hooks.PostToolUse;
-		// PostToolUse should have 3 entries: logger, mail check, mulch diff
-		expect(postToolUse).toHaveLength(3);
-		// First entry is the logging hook
+		// PostToolUse should have 2 entries: combined logger+mail check, mulch diff
+		expect(postToolUse).toHaveLength(2);
+		// First entry has both the logging hook and signal-gated mail check
 		expect(postToolUse[0].hooks[0].command).toContain("legio log tool-end");
-		// Second entry is the debounced mail check
-		expect(postToolUse[1].hooks[0].command).toContain("legio mail check --inject");
-		expect(postToolUse[1].hooks[0].command).toContain("mail-check-agent");
-		expect(postToolUse[1].hooks[0].command).toContain("--debounce 30000");
-		expect(postToolUse[1].hooks[0].command).toContain("LEGIO_AGENT_NAME");
-		// Third entry is mulch diff after commit
-		expect(postToolUse[2].matcher).toBe("Bash");
-		expect(postToolUse[2].hooks[0].command).toContain("mulch diff HEAD~1");
+		expect(postToolUse[0].hooks[1].command).toContain("legio mail check --inject");
+		expect(postToolUse[0].hooks[1].command).toContain("$LEGIO_AGENT_NAME");
+		expect(postToolUse[0].hooks[1].command).toContain("--signal");
+		expect(postToolUse[0].hooks[1].command).toContain("LEGIO_AGENT_NAME");
+		// Second entry is mulch diff after commit (with HEAD~1 guard)
+		expect(postToolUse[1].matcher).toBe("Bash");
+		expect(postToolUse[1].hooks[0].command).toContain("mulch diff HEAD~1");
+		expect(postToolUse[1].hooks[0].command).toContain("git rev-parse HEAD~1");
 	});
 
 	test("output contains PreCompact hook", async () => {
@@ -198,7 +198,7 @@ describe("deployHooks", () => {
 		const parsed = JSON.parse(content);
 		const sessionStart = parsed.hooks.SessionStart[0];
 		expect(sessionStart.hooks[0].type).toBe("command");
-		expect(sessionStart.hooks[0].command).toContain("legio prime --agent prime-agent");
+		expect(sessionStart.hooks[0].command).toContain("legio prime --agent $LEGIO_AGENT_NAME");
 		expect(sessionStart.hooks[0].command).toContain("LEGIO_AGENT_NAME");
 	});
 
@@ -211,7 +211,9 @@ describe("deployHooks", () => {
 		const content = await readFile(outputPath, "utf-8");
 		const parsed = JSON.parse(content);
 		const userPrompt = parsed.hooks.UserPromptSubmit[0];
-		expect(userPrompt.hooks[0].command).toContain("legio mail check --inject --agent mail-agent");
+		expect(userPrompt.hooks[0].command).toContain(
+			"legio mail check --inject --agent $LEGIO_AGENT_NAME",
+		);
 		expect(userPrompt.hooks[0].command).toContain("LEGIO_AGENT_NAME");
 	});
 
@@ -225,7 +227,9 @@ describe("deployHooks", () => {
 		const parsed = JSON.parse(content);
 		const preCompact = parsed.hooks.PreCompact[0];
 		expect(preCompact.hooks[0].type).toBe("command");
-		expect(preCompact.hooks[0].command).toContain("legio prime --agent compact-agent --compact");
+		expect(preCompact.hooks[0].command).toContain(
+			"legio prime --agent $LEGIO_AGENT_NAME --compact",
+		);
 		expect(preCompact.hooks[0].command).toContain("LEGIO_AGENT_NAME");
 	});
 
@@ -244,7 +248,7 @@ describe("deployHooks", () => {
 		expect(baseHook).toBeDefined();
 		expect(baseHook.hooks[0].command).toContain("--stdin");
 		expect(baseHook.hooks[0].command).toContain("legio log tool-start");
-		expect(baseHook.hooks[0].command).toContain("stdin-agent");
+		expect(baseHook.hooks[0].command).toContain("$LEGIO_AGENT_NAME");
 		expect(baseHook.hooks[0].command).not.toContain("read -r INPUT");
 	});
 
@@ -259,14 +263,14 @@ describe("deployHooks", () => {
 		const postToolUse = parsed.hooks.PostToolUse[0];
 		expect(postToolUse.hooks[0].command).toContain("--stdin");
 		expect(postToolUse.hooks[0].command).toContain("legio log tool-end");
-		expect(postToolUse.hooks[0].command).toContain("stdin-agent");
+		expect(postToolUse.hooks[0].command).toContain("$LEGIO_AGENT_NAME");
 		expect(postToolUse.hooks[0].command).not.toContain("read -r INPUT");
 	});
 
-	test("PostToolUse hook includes mail check with debounce", async () => {
-		const worktreePath = join(tempDir, "mail-debounce-wt");
+	test("PostToolUse hook includes signal-gated mail check", async () => {
+		const worktreePath = join(tempDir, "mail-signal-wt");
 
-		await deployHooks(worktreePath, "mail-debounce-agent");
+		await deployHooks(worktreePath, "mail-signal-agent");
 
 		const outputPath = join(worktreePath, ".claude", "settings.local.json");
 		const content = await readFile(outputPath, "utf-8");
@@ -276,11 +280,12 @@ describe("deployHooks", () => {
 		// Should have 2 hooks: tool-end logging + mail check
 		expect(postToolUse.hooks).toHaveLength(2);
 
-		// Second hook should be mail check with debounce
+		// Second hook should be signal-gated mail check
 		expect(postToolUse.hooks[1].command).toContain("legio mail check");
 		expect(postToolUse.hooks[1].command).toContain("--inject");
-		expect(postToolUse.hooks[1].command).toContain("--agent mail-debounce-agent");
-		expect(postToolUse.hooks[1].command).toContain("--debounce 500");
+		expect(postToolUse.hooks[1].command).toContain("--agent $LEGIO_AGENT_NAME");
+		expect(postToolUse.hooks[1].command).toContain("--signal");
+		expect(postToolUse.hooks[1].command).not.toContain("--debounce");
 		expect(postToolUse.hooks[1].command).toContain("LEGIO_AGENT_NAME");
 	});
 
@@ -333,7 +338,7 @@ describe("deployHooks", () => {
 		const stop = parsed.hooks.Stop[0];
 		expect(stop.hooks[0].command).toContain("--stdin");
 		expect(stop.hooks[0].command).toContain("legio log session-end");
-		expect(stop.hooks[0].command).toContain("stdin-agent");
+		expect(stop.hooks[0].command).toContain("$LEGIO_AGENT_NAME");
 		expect(stop.hooks[0].command).not.toContain("read -r INPUT");
 	});
 
@@ -484,9 +489,9 @@ describe("deployHooks", () => {
 		expect(writeBlockGuard).toBeDefined();
 		expect(writeBlockGuard.hooks[0].command).toContain('"decision":"block"');
 
-		// Should have multiple Bash guards: danger guard + file guard + template push-guard
+		// Should have multiple Bash guards: danger guard + file guard + template push-guard + sleep-guard
 		const bashGuards = preToolUse.filter((h: { matcher: string }) => h.matcher === "Bash");
-		expect(bashGuards.length).toBe(3); // danger guard + file guard + template push-guard
+		expect(bashGuards.length).toBe(4); // danger guard + file guard + template push-guard + sleep-guard
 	});
 
 	test("reviewer capability adds same guards as scout", async () => {
@@ -528,9 +533,9 @@ describe("deployHooks", () => {
 		expect(guardMatchers).toContain("NotebookEdit");
 		expect(guardMatchers).toContain("Bash");
 
-		// Should have 3 Bash guards: danger guard + file guard + template push-guard
+		// Should have 4 Bash guards: danger guard + file guard + template push-guard + sleep-guard
 		const bashGuards = preToolUse.filter((h: { matcher: string }) => h.matcher === "Bash");
-		expect(bashGuards.length).toBe(3);
+		expect(bashGuards.length).toBe(4);
 	});
 
 	test("builder capability gets path boundary + Bash danger + Bash path boundary guards + native team tool blocks", async () => {
@@ -560,9 +565,9 @@ describe("deployHooks", () => {
 		expect(writeGuards[0].hooks[0].command).toContain("LEGIO_WORKTREE_PATH");
 		expect(writeGuards[0].hooks[0].command).not.toContain("cannot modify files");
 
-		// Builder should have 3 Bash guards: danger guard + path boundary guard + template push-guard
+		// Builder should have 4 Bash guards: danger guard + path boundary guard + template push-guard + sleep-guard
 		const bashGuards = preToolUse.filter((h: { matcher: string }) => h.matcher === "Bash");
-		expect(bashGuards.length).toBe(3);
+		expect(bashGuards.length).toBe(4);
 		// One should be the danger guard (checks git push)
 		const dangerGuard = bashGuards.find(
 			(h: { hooks: Array<{ command: string }> }) =>
@@ -1205,7 +1210,7 @@ describe("structural enforcement integration", () => {
 
 		// Find the bash file guard (the second Bash entry, after the danger guard)
 		const bashGuards = preToolUse.filter((h: { matcher: string }) => h.matcher === "Bash");
-		expect(bashGuards.length).toBe(3); // danger guard + file guard + template push-guard
+		expect(bashGuards.length).toBe(4); // danger guard + file guard + template push-guard + sleep-guard
 
 		// The file guard (second Bash guard) should whitelist git add/commit
 		const fileGuard = bashGuards[1];
@@ -1688,8 +1693,8 @@ describe("bash path boundary integration", () => {
 		const preToolUse = parsed.hooks.PreToolUse;
 
 		const bashGuards = preToolUse.filter((h: { matcher: string }) => h.matcher === "Bash");
-		// Should have 3 Bash guards: danger guard + path boundary guard + template push-guard
-		expect(bashGuards.length).toBe(3);
+		// Should have 4 Bash guards: danger guard + path boundary guard + template push-guard + sleep-guard
+		expect(bashGuards.length).toBe(4);
 
 		// Find the path boundary guard
 		const pathGuard = bashGuards.find((h: { hooks: Array<{ command: string }> }) =>
@@ -1710,7 +1715,7 @@ describe("bash path boundary integration", () => {
 		const preToolUse = parsed.hooks.PreToolUse;
 
 		const bashGuards = preToolUse.filter((h: { matcher: string }) => h.matcher === "Bash");
-		expect(bashGuards.length).toBe(3); // danger guard + path boundary guard + template push-guard
+		expect(bashGuards.length).toBe(4); // danger guard + path boundary guard + template push-guard + sleep-guard
 
 		const pathGuard = bashGuards.find((h: { hooks: Array<{ command: string }> }) =>
 			h.hooks[0]?.command?.includes("Bash path boundary violation"),
@@ -1728,9 +1733,9 @@ describe("bash path boundary integration", () => {
 		const parsed = JSON.parse(content);
 		const preToolUse = parsed.hooks.PreToolUse;
 
-		// Scout gets danger guard + file guard + template push-guard (3 Bash guards), but NOT path boundary
+		// Scout gets danger guard + file guard + template push-guard + sleep-guard (4 Bash guards), but NOT path boundary
 		const bashGuards = preToolUse.filter((h: { matcher: string }) => h.matcher === "Bash");
-		expect(bashGuards.length).toBe(3);
+		expect(bashGuards.length).toBe(4);
 
 		const pathGuard = bashGuards.find((h: { hooks: Array<{ command: string }> }) =>
 			h.hooks[0]?.command?.includes("Bash path boundary violation"),

package/src/agents/hooks-deployer.ts

@@ -497,8 +497,7 @@ export function getCapabilityGuards(capability: string): HookEntry[] {
 /**
  * Deploy hooks config to an agent's worktree as `.claude/settings.local.json`.
  *
- * Reads `templates/hooks.json.tmpl`, replaces `{{AGENT_NAME}}`, then merges
- * capability-specific PreToolUse guards into the resulting config.
+ * Reads `templates/hooks.json.tmpl`, then merges capability-specific PreToolUse guards into the resulting config.
  *
  * @param worktreePath - Absolute path to the agent's git worktree
  * @param agentName - The unique name of the agent
@@ -531,14 +530,16 @@ export async function deployHooks(
 		});
 	}
 
-	// Replace all occurrences of {{AGENT_NAME}}
-	let content = template;
-	while (content.includes("{{AGENT_NAME}}")) {
-		content = content.replace("{{AGENT_NAME}}", agentName);
-	}
-
 	// Parse the base config and merge guards into PreToolUse
-	const config = JSON.parse(content) as { hooks: Record<string, HookEntry[]> };
+	let config: { hooks: Record<string, HookEntry[]> };
+	try {
+		config = JSON.parse(template) as { hooks: Record<string, HookEntry[]> };
+	} catch (err) {
+		throw new AgentError(`Failed to parse hooks template as JSON: ${templatePath}`, {
+			agentName,
+			cause: err instanceof Error ? err : undefined,
+		});
+	}
 	const pathGuards = getPathBoundaryGuards();
 	const dangerGuards = getDangerGuards(agentName);
 	const capabilityGuards = getCapabilityGuards(capability);