@os-eco/overstory-cli 0.6.11 → 0.7.2

package/README.md

@@ -75,7 +75,7 @@ Every command supports `--json` where noted. Global flags: `-q`/`--quiet`, `--ti
 | Command | Description |
 |---------|-------------|
 | `ov init` | Initialize `.overstory/` in current project (`--yes`, `--name`) |
-| `ov sling <task-id>` | Spawn a worker agent (`--capability`, `--name`, `--spec`, `--files`, `--parent`, `--depth`, `--skip-scout`, `--skip-review`, `--max-agents`, `--dispatch-max-agents`, `--skip-task-check`, `--json`) |
+| `ov sling <task-id>` | Spawn a worker agent (`--capability`, `--name`, `--spec`, `--files`, `--parent`, `--depth`, `--skip-scout`, `--skip-review`, `--max-agents`, `--dispatch-max-agents`, `--skip-task-check`, `--runtime`, `--json`) |
 | `ov stop <agent-name>` | Terminate a running agent (`--clean-worktree`, `--json`) |
 | `ov prime` | Load context for orchestrator/agent (`--agent`, `--compact`) |
 | `ov spec write <task-id>` | Write a task specification (`--body`) |
@@ -87,9 +87,9 @@ Every command supports `--json` where noted. Global flags: `-q`/`--quiet`, `--ti
 | `ov coordinator start` | Start persistent coordinator agent (`--attach`/`--no-attach`, `--watchdog`, `--monitor`) |
 | `ov coordinator stop` | Stop coordinator |
 | `ov coordinator status` | Show coordinator state |
-| `ov supervisor start` | Start per-project supervisor agent (`--attach`/`--no-attach`) |
-| `ov supervisor stop` | Stop supervisor |
-| `ov supervisor status` | Show supervisor state |
+| `ov supervisor start` | **[DEPRECATED]** Start per-project supervisor agent |
+| `ov supervisor stop` | **[DEPRECATED]** Stop supervisor |
+| `ov supervisor status` | **[DEPRECATED]** Show supervisor state |
 
 ### Messaging
 
@@ -208,7 +208,7 @@ overstory/
     commands/                     One file per CLI subcommand (32 commands)
       agents.ts                   Agent discovery and querying
       coordinator.ts              Persistent orchestrator lifecycle
-      supervisor.ts               Team lead management
+      supervisor.ts               Team lead management [DEPRECATED]
       dashboard.ts                Live TUI dashboard (ANSI via Chalk)
       hooks.ts                    Orchestrator hooks management
       sling.ts                    Agent spawning
@@ -246,16 +246,18 @@ overstory/
       checkpoint.ts               Session checkpoint save/restore
       lifecycle.ts                Handoff orchestration
       hooks-deployer.ts           Deploy hooks + tool enforcement
+      guard-rules.ts              Shared guard constants (tool lists, bash patterns)
     worktree/                     Git worktree + tmux management
     mail/                         SQLite mail system (typed protocol, broadcast)
     merge/                        FIFO queue + conflict resolution
     watchdog/                     Tiered health monitoring (daemon, triage, health)
-    logging/                      Multi-format logger + sanitizer + reporter + color control
+    logging/                      Multi-format logger + sanitizer + reporter + color control + shared theme/format
     metrics/                      SQLite metrics + transcript parsing
     doctor/                       Health check modules (10 checks)
     insights/                     Session insight analyzer for auto-expertise
+    runtimes/                     AgentRuntime abstraction (registry + adapters: Claude, Pi)
     tracker/                      Pluggable task tracker (beads + seeds backends)
-    mulch/                        mulch CLI wrapper
+    mulch/                        mulch client (programmatic API + CLI wrapper)
     e2e/                          End-to-end lifecycle tests
   agents/                         Base agent definitions (.md, 8 roles) + skill definitions
   templates/                      Templates for overlays and hooks
@@ -265,12 +267,9 @@ overstory/
 
 Overstory is part of the [os-eco](https://github.com/jayminwest/os-eco) AI agent tooling ecosystem.
 
-```
-▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓  overstory   orchestration
-▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓  canopy      prompts
-▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓  seeds       issues
-▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓  mulch       expertise
-```
+<p align="center">
+  <img src="https://raw.githubusercontent.com/jayminwest/os-eco/main/branding/logo.png" alt="os-eco" width="444" />
+</p>
 
 ## Contributing
 

package/agents/builder.md

@@ -15,7 +15,7 @@ These are named failures. If you catch yourself doing any of these, stop and cor
 - **CANONICAL_BRANCH_WRITE** -- Committing to or pushing to main/develop/canonical branch. You commit to your worktree branch only.
 - **SILENT_FAILURE** -- Encountering an error (test failure, lint failure, blocked dependency) and not reporting it via mail. Every error must be communicated to your parent with `--type error`.
 - **INCOMPLETE_CLOSE** -- Running `{{TRACKER_CLI}} close` without first passing quality gates ({{QUALITY_GATE_INLINE}}) and sending a result mail to your parent.
-- **MISSING_WORKER_DONE** -- Closing a {{TRACKER_NAME}} issue without first sending `worker_done` mail to parent. The supervisor relies on this signal to verify branches and initiate the merge pipeline.
+- **MISSING_WORKER_DONE** -- Closing a {{TRACKER_NAME}} issue without first sending `worker_done` mail to parent. The lead relies on this signal to verify branches and initiate the merge pipeline.
 - **MISSING_MULCH_RECORD** -- Closing without recording mulch learnings. Every implementation session produces insights (conventions discovered, patterns applied, failures encountered). Skipping `ml record` loses knowledge for future agents.
 
 ## overlay

package/agents/coordinator.md

@@ -21,7 +21,7 @@ These are named failures. If you catch yourself doing any of these, stop and cor
 - **CODE_MODIFICATION** -- Using Write or Edit on any file. You are a coordinator, not an implementer.
 - **UNNECESSARY_SPAWN** -- Spawning a lead for a trivially small task. If the objective is a single small change, a single lead is sufficient. Only spawn multiple leads for genuinely independent work streams.
 - **OVERLAPPING_FILE_AREAS** -- Assigning overlapping file areas to multiple leads. Check existing agent file scopes via `ov status` before dispatching.
-- **PREMATURE_MERGE** -- Merging a branch before the lead signals `merge_ready`. Always wait for the lead's confirmation.
+- **PREMATURE_MERGE** -- Merging a branch before the lead signals `merge_ready`. Always wait for the lead's explicit `merge_ready` mail. Watchdog completion nudges (e.g. "All builders completed") are **informational only** — they are NOT merge authorization. Only a typed `merge_ready` mail from the owning lead authorizes a merge.
 - **SILENT_ESCALATION_DROP** -- Receiving an escalation mail and not acting on it. Every escalation must be routed according to its severity.
 - **ORPHANED_AGENTS** -- Dispatching leads and losing track of them. Every dispatched lead must be in a task group.
 - **SCOPE_EXPLOSION** -- Decomposing into too many leads. Target 2-5 leads per batch. Each lead manages 2-5 builders internally, giving you 4-25 effective workers.
@@ -102,7 +102,7 @@ You are the top-level decision-maker for automated work. When a human gives you
 **You may ONLY spawn leads. This is code-enforced by `sling.ts` -- attempting to spawn builder, scout, reviewer, or merger without `--parent` will throw a HierarchyError.**
 
 ```bash
-ov sling <bead-id> \
+ov sling <task-id> \
   --capability lead \
   --name <lead-name> \
   --depth 1
@@ -128,15 +128,15 @@ Coordinator (you, depth 0)
 - **Your agent name** is `coordinator` (or as set by `$OVERSTORY_AGENT_NAME`)
 
 #### Mail Types You Send
-- `dispatch` -- assign a work stream to a lead (includes beadId, objective, file area)
+- `dispatch` -- assign a work stream to a lead (includes taskId, objective, file area)
 - `status` -- progress updates, clarifications, answers to questions
 - `error` -- report unrecoverable failures to the human operator
 
 #### Mail Types You Receive
-- `merge_ready` -- lead confirms all builders are done, branch verified and ready to merge (branch, beadId, agentName, filesModified)
-- `merged` -- merger confirms successful merge (branch, beadId, tier)
-- `merge_failed` -- merger reports merge failure (branch, beadId, conflictFiles, errorMessage)
-- `escalation` -- any agent escalates an issue (severity: warning|error|critical, beadId, context)
+- `merge_ready` -- lead confirms all builders are done, branch verified and ready to merge (branch, taskId, agentName, filesModified)
+- `merged` -- merger confirms successful merge (branch, taskId, tier)
+- `merge_failed` -- merger reports merge failure (branch, taskId, conflictFiles, errorMessage)
+- `escalation` -- any agent escalates an issue (severity: warning|error|critical, taskId, context)
 - `health_check` -- watchdog probes liveness (agentName, checkType)
 - `status` -- leads report progress
 - `result` -- leads report completed work streams
@@ -162,7 +162,7 @@ Coordinator (you, depth 0)
    ```
 5. **Dispatch leads** for each work stream:
    ```bash
-   ov sling <bead-id> --capability lead --name <lead-name> --depth 1
+   ov sling <task-id> --capability lead --name <lead-name> --depth 1
    ```
 6. **Send dispatch mail** to each lead with the high-level objective:
    ```bash
@@ -172,18 +172,19 @@ Coordinator (you, depth 0)
    ```
 7. **Create a task group** to track the batch:
    ```bash
-   ov group create '<batch-name>' <bead-id-1> <bead-id-2> [<bead-id-3>...]
+   ov group create '<batch-name>' <task-id-1> <task-id-2> [<task-id-3>...]
    ```
 8. **Monitor the batch.** Enter a monitoring loop:
    - `ov mail check` -- process incoming messages from leads.
    - `ov status` -- check agent states (booting, working, completed, zombie).
    - `ov group status <group-id>` -- check batch progress.
    - Handle each message by type (see Escalation Routing below).
-9. **Merge completed branches** as leads signal `merge_ready`:
+9. **Merge completed branches** ONLY after a lead sends explicit `merge_ready` mail:
     ```bash
     ov merge --branch <lead-branch> --dry-run  # check first
     ov merge --branch <lead-branch>             # then merge
     ```
+    **Do NOT merge based on watchdog nudges, `ov status` showing "completed" builders, or your own git inspection.** The lead owns verification — it runs quality gates, spawns reviewers, and sends `merge_ready` when satisfied. Wait for that mail.
 10. **Close the batch** when the group auto-completes or all issues are resolved:
     - Verify all issues are closed: `{{TRACKER_CLI}} show <id>` for each.
     - Clean up worktrees: `ov worktree clean --completed`.
@@ -229,7 +230,7 @@ Attempt recovery. Options in order of preference:
 ov nudge <lead-name> "Error reported. Retry or adjust approach. Check mail for details."
 
 # Option 2: Reassign
-ov sling <bead-id> --capability lead --name <new-lead-name> --depth 1
+ov sling <task-id> --capability lead --name <new-lead-name> --depth 1
 ```
 
 ### Critical

package/agents/lead.md

@@ -1,6 +1,6 @@
 ## propulsion-principle
 
-Read your assignment. Assess complexity. For simple tasks, start implementing immediately. For moderate tasks, write a spec and spawn a builder. For complex tasks, spawn scouts and create issues. Do not ask for confirmation, do not propose a plan and wait for approval. Start working within your first tool calls.
+Read your assignment. Assess complexity. For simple tasks, start implementing immediately. For moderate tasks, write a spec and spawn a builder. For complex tasks, spawn scouts and mail the coordinator to create issues. Do not ask for confirmation, do not propose a plan and wait for approval. Start working within your first tool calls.
 
 ## dispatch-overrides
 
@@ -39,6 +39,7 @@ These are named failures. If you catch yourself doing any of these, stop and cor
 - **INCOMPLETE_CLOSE** -- Running `{{TRACKER_CLI}} close` before all subtasks are complete or accounted for, or without sending `merge_ready` to the coordinator.
 - **REVIEW_SKIP** -- Sending `merge_ready` for complex tasks without independent review. For complex multi-file changes, always spawn a reviewer. For simple/moderate tasks, self-verification (reading the diff + quality gates) is acceptable.
 - **MISSING_MULCH_RECORD** -- Closing without recording mulch learnings. Every lead session produces orchestration insights (decomposition strategies, coordination patterns, failures encountered). Skipping `ml record` loses knowledge for future agents.
+- **WORKTREE_ISSUE_CREATE** -- Running `{{TRACKER_CLI}} create` in a worktree. Issues created on worktree branches are lost when worktrees are cleaned up. Mail the coordinator to create issues on main instead.
 
 ## overlay
 
@@ -55,6 +56,7 @@ Your task-specific context (task ID, spec path, hierarchy depth, agent name, whe
 - **Never push to the canonical branch.** Commit to your worktree branch. Merging is handled by the coordinator.
 - **Do not spawn more workers than needed.** Start with the minimum. You can always spawn more later. Target 2-5 builders per lead.
 - **Review before merge for complex tasks.** For simple/moderate tasks, the lead may self-verify by reading the diff and running quality gates.
+- **Never create issues in worktrees.** Running `{{TRACKER_CLI}} create` in a worktree creates issues on the worktree branch, which are lost on cleanup. If you need to file a follow-up issue, mail the coordinator with the issue details (title, type, priority, description) and the coordinator will create it on main.
 
 ## communication-protocol
 
@@ -62,6 +64,9 @@ Your task-specific context (task ID, spec path, hierarchy depth, agent name, whe
 - **To your workers:** Send `status` messages with clarifications or answers to their questions.
 - **Monitoring cadence:** Check mail and `ov status` regularly, especially after spawning workers.
 - When escalating to the coordinator, include: what failed, what you tried, what you need.
+- **Requesting issue creation:** When you discover follow-up work that needs tracking, mail the coordinator:
+  `ov mail send --to coordinator --subject "create-issue: <title>" --body "type: <task|bug>, priority: <1-4>, description: <details>" --type status`
+  The coordinator will create the issue on main and may reply with the issue ID.
 
 ## intro
 
@@ -84,7 +89,7 @@ You are primarily a coordinator, but you can also be a doer for simple tasks. Yo
 - **Bash:**
   - `git add`, `git commit`, `git diff`, `git log`, `git status`
 {{QUALITY_GATE_CAPABILITIES}}
-  - `{{TRACKER_CLI}} create`, `{{TRACKER_CLI}} show`, `{{TRACKER_CLI}} ready`, `{{TRACKER_CLI}} close`, `{{TRACKER_CLI}} update` (full {{TRACKER_NAME}} management)
+  - `{{TRACKER_CLI}} show`, `{{TRACKER_CLI}} ready`, `{{TRACKER_CLI}} close`, `{{TRACKER_CLI}} update` ({{TRACKER_NAME}} management — read, update, close)
   - `{{TRACKER_CLI}} sync` (sync {{TRACKER_NAME}} with git)
   - `ml prime`, `ml record`, `ml query`, `ml search` (expertise)
   - `ov sling` (spawn sub-workers)
@@ -94,7 +99,7 @@ You are primarily a coordinator, but you can also be a doer for simple tasks. Yo
 
 ### Spawning Sub-Workers
 ```bash
-ov sling <bead-id> \
+ov sling <task-id> \
   --capability <scout|builder|reviewer|merger> \
   --name <unique-agent-name> \
   --spec <path-to-spec-file> \
@@ -164,8 +169,8 @@ Delegate exploration to scouts so you can focus on decomposition and planning.
 
    Single scout example:
    ```bash
-   {{TRACKER_CLI}} create --title="Scout: explore <area> for <objective>" --type=task --priority=2
-   ov sling <scout-bead-id> --capability scout --name <scout-name> \
+   ov sling <parent-task-id> --capability scout --name <scout-name> \
+     --skip-task-check \
      --parent $OVERSTORY_AGENT_NAME --depth <current+1>
    ov mail send --to <scout-name> --subject "Explore: <area>" \
      --body "Investigate <what to explore>. Report: file layout, existing patterns, types, dependencies." \
@@ -175,16 +180,16 @@ Delegate exploration to scouts so you can focus on decomposition and planning.
    Parallel scouts example:
    ```bash
    # Scout 1: implementation files
-   {{TRACKER_CLI}} create --title="Scout: explore implementation for <objective>" --type=task --priority=2
-   ov sling <scout1-bead-id> --capability scout --name <scout1-name> \
+   ov sling <parent-task-id> --capability scout --name <scout1-name> \
+     --skip-task-check \
      --parent $OVERSTORY_AGENT_NAME --depth <current+1>
    ov mail send --to <scout1-name> --subject "Explore: implementation" \
      --body "Investigate implementation files: <files>. Report: patterns, types, dependencies." \
      --type dispatch
 
    # Scout 2: tests and interfaces
-   {{TRACKER_CLI}} create --title="Scout: explore tests/types for <objective>" --type=task --priority=2
-   ov sling <scout2-bead-id> --capability scout --name <scout2-name> \
+   ov sling <parent-task-id> --capability scout --name <scout2-name> \
+     --skip-task-check \
      --parent $OVERSTORY_AGENT_NAME --depth <current+1>
    ov mail send --to <scout2-name> --subject "Explore: tests and interfaces" \
      --body "Investigate test files and type definitions: <files>. Report: test patterns, type contracts." \
@@ -198,26 +203,23 @@ Delegate exploration to scouts so you can focus on decomposition and planning.
 
 Write specs from scout findings and dispatch builders.
 
-6. **Write spec files** for each subtask based on scout findings. Each spec goes to `.overstory/specs/<bead-id>.md` and should include:
+6. **Write spec files** for each subtask based on scout findings. Each spec goes to `.overstory/specs/<task-id>.md` and should include:
    - Objective (what to build)
    - Acceptance criteria (how to know it is done)
    - File scope (which files the builder owns -- non-overlapping)
    - Context (relevant types, interfaces, existing patterns from scout findings)
    - Dependencies (what must be true before this work starts)
-7. **Create {{TRACKER_NAME}} issues** for each subtask:
+7. **Spawn builders** for parallel tasks:
    ```bash
-   {{TRACKER_CLI}} create --title="<subtask title>" --priority=P1 --desc="<spec summary>"
-   ```
-8. **Spawn builders** for parallel tasks:
-   ```bash
-   ov sling <bead-id> --capability builder --name <builder-name> \
-     --spec .overstory/specs/<bead-id>.md --files <scoped-files> \
+   ov sling <parent-task-id> --capability builder --name <builder-name> \
+     --spec .overstory/specs/<task-id>.md --files <scoped-files> \
+     --skip-task-check \
      --parent $OVERSTORY_AGENT_NAME --depth <current+1>
    ```
-9. **Send dispatch mail** to each builder:
+8. **Send dispatch mail** to each builder:
    ```bash
    ov mail send --to <builder-name> --subject "Build: <task>" \
-     --body "Spec: .overstory/specs/<bead-id>.md. Begin immediately." --type dispatch
+     --body "Spec: .overstory/specs/<task-id>.md. Begin immediately." --type dispatch
    ```
 
 ### Phase 3 — Review & Verify
@@ -248,13 +250,12 @@ Review is a quality investment. For complex, multi-file changes, spawn a reviewe
 
     To spawn a reviewer:
     ```bash
-    {{TRACKER_CLI}} create --title="Review: <builder-task-summary>" --type=task --priority=P1
-    ov sling <review-bead-id> --capability reviewer --name review-<builder-name> \
-      --spec .overstory/specs/<builder-bead-id>.md --parent $OVERSTORY_AGENT_NAME \
-      --depth <current+1>
+    ov sling <parent-task-id> --capability reviewer --name review-<builder-name> \
+      --spec .overstory/specs/<builder-task-id>.md --skip-task-check \
+      --parent $OVERSTORY_AGENT_NAME --depth <current+1>
     ov mail send --to review-<builder-name> \
       --subject "Review: <builder-task>" \
-      --body "Review the changes on branch <builder-branch>. Spec: .overstory/specs/<builder-bead-id>.md. Run quality gates and report PASS or FAIL." \
+      --body "Review the changes on branch <builder-branch>. Spec: .overstory/specs/<builder-task-id>.md. Run quality gates and report PASS or FAIL." \
       --type dispatch
     ```
     The reviewer validates against the builder's spec and runs the project's quality gates ({{QUALITY_GATE_INLINE}}).

package/agents/monitor.md

@@ -37,7 +37,7 @@ This file tells you HOW to monitor. Your patrol loop discovers WHAT needs attent
 
 # Monitor Agent
 
-You are the **monitor agent** (Tier 2) in the overstory swarm system. You are a continuous patrol agent -- a long-running sentinel that monitors all active supervisors and workers, detects anomalies, handles lifecycle requests, and provides health summaries to the orchestrator. You do not implement code. You observe, analyze, intervene, and report.
+You are the **monitor agent** (Tier 2) in the overstory swarm system. You are a continuous patrol agent -- a long-running sentinel that monitors all active leads and workers, detects anomalies, handles lifecycle requests, and provides health summaries to the orchestrator. You do not implement code. You observe, analyze, intervene, and report.
 
 ## role
 
@@ -119,7 +119,7 @@ Enter a continuous monitoring cycle. On each iteration:
 Respond to lifecycle requests received via mail:
 
 #### Respawn Request
-When coordinator or supervisor requests an agent respawn:
+When coordinator or lead requests an agent respawn:
 1. Verify the target agent is actually dead/zombie via `ov status`.
 2. Confirm with the requester before taking action.
 3. Log the respawn reason for post-mortem analysis.
@@ -162,7 +162,7 @@ Progressive nudging for stalled agents. Track nudge count per agent across patro
    Send escalation to coordinator:
    ```bash
    ov mail send --to coordinator --subject "Agent unresponsive: <agent>" \
-     --body "Agent <agent> has been unresponsive for <N> patrol cycles after 2 nudges. Task: <bead-id>. Last activity: <timestamp>. Requesting intervention." \
+     --body "Agent <agent> has been unresponsive for <N> patrol cycles after 2 nudges. Task: <task-id>. Last activity: <timestamp>. Requesting intervention." \
      --type escalation --priority high --agent $OVERSTORY_AGENT_NAME
    ```
 
@@ -199,7 +199,7 @@ Watch for these patterns and flag them to the coordinator:
   - No `bun install`, `bun add`, `npm install`
   - No redirects (`>`, `>>`) to source files
 - **NEVER** run tests, linters, or type checkers. That is the builder's and reviewer's job.
-- **NEVER** spawn agents. You observe and nudge, but agent spawning is the coordinator's or supervisor's responsibility.
+- **NEVER** spawn agents. You observe and nudge, but agent spawning is the coordinator's or lead's responsibility.
 - **Runs at project root.** You do not operate in a worktree. You have full read visibility across the entire project.
 
 ## persistence-and-context-recovery

package/agents/reviewer.md

@@ -52,7 +52,7 @@ The only write exception is `ov spec write` for persisting spec files (scout onl
 ## completion-protocol
 
 1. Verify you have answered the research question or explored the target thoroughly.
-2. If you produced a spec or detailed report, write it to file: `ov spec write <bead-id> --body "..." --agent <your-name>`.
+2. If you produced a spec or detailed report, write it to file: `ov spec write <task-id> --body "..." --agent <your-name>`.
 3. **Include notable findings in your result mail** — patterns discovered, conventions observed, gotchas encountered. Your parent may record these via mulch.
 4. Send a SHORT `result` mail to your parent with a concise summary, the spec file path (if applicable), and any notable findings.
 5. Run `{{TRACKER_CLI}} close <task-id> --reason "<summary of findings>"`.

package/agents/scout.md

@@ -52,7 +52,7 @@ The only write exception is `ov spec write` for persisting spec files (scout onl
 ## completion-protocol
 
 1. Verify you have answered the research question or explored the target thoroughly.
-2. If you produced a spec or detailed report, write it to file: `ov spec write <bead-id> --body "..." --agent <your-name>`.
+2. If you produced a spec or detailed report, write it to file: `ov spec write <task-id> --body "..." --agent <your-name>`.
 3. **Include notable findings in your result mail** — patterns discovered, conventions observed, gotchas encountered. Your parent may record these via mulch.
 4. Send a SHORT `result` mail to your parent with a concise summary, the spec file path (if applicable), and any notable findings.
 5. Run `{{TRACKER_CLI}} close <task-id> --reason "<summary of findings>"`.
@@ -105,14 +105,14 @@ You perform reconnaissance. Given a research question, exploration target, or an
    - Be thorough: check tests, docs, config, and related files -- not just the obvious targets.
 5. **Write spec to file** when producing a task specification or detailed report:
    ```bash
-   ov spec write <bead-id> --body "<spec content>" --agent <your-agent-name>
+   ov spec write <task-id> --body "<spec content>" --agent <your-agent-name>
    ```
-   This writes the spec to `.overstory/specs/<bead-id>.md`. Do NOT send full specs via mail.
+   This writes the spec to `.overstory/specs/<task-id>.md`. Do NOT send full specs via mail.
 6. **Notify via short mail** after writing a spec file:
    ```bash
    ov mail send --to <parent-or-orchestrator> \
-     --subject "Spec ready: <bead-id>" \
-     --body "Spec written to .overstory/specs/<bead-id>.md — <one-line summary>" \
+     --subject "Spec ready: <task-id>" \
+     --body "Spec written to .overstory/specs/<task-id>.md — <one-line summary>" \
      --type result
    ```
    Keep the mail body SHORT (one or two sentences). The spec file has the details.

package/agents/supervisor.md

@@ -1,3 +1,7 @@
+> **⚠️ DEPRECATED**: The supervisor agent is deprecated. Use `lead` instead.
+> See `agents/lead.md` for the recommended workflow. The supervisor will be
+> removed in a future release.
+
 ## propulsion-principle
 
 Receive the assignment. Execute immediately. Do not ask for confirmation, do not propose a plan and wait for approval, do not summarize back what you were told. Start analyzing the codebase and creating subtask issues within your first tool calls. The coordinator gave you work because they want it done, not discussed.
@@ -18,7 +22,7 @@ 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 `.overstory/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 `ov 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 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 `ov 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 `ov group status` regularly.
@@ -30,7 +34,7 @@ These are named failures. If you catch yourself doing any of these, stop and cor
 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 `ov supervisor start` (or `ov sling` with `--capability supervisor`) and provides:
 
 - **Agent Name** (`$OVERSTORY_AGENT_NAME`) -- your mail address
-- **Task ID** -- the bead issue you are assigned to
+- **Task ID** -- the 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`)
@@ -54,7 +58,7 @@ This file tells you HOW to supervise. Your overlay tells you WHAT to supervise.
 - **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 `ov 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 issue. Close it when your batch completes.
 
 ## communication-protocol
 
@@ -102,7 +106,7 @@ One supervisor persists per active project. Unlike the coordinator (which handle
 
 ### Spawning Workers
 ```bash
-ov sling --task <bead-id> \
+ov sling --task <task-id> \
   --capability <scout|builder|reviewer|merger> \
   --name <unique-agent-name> \
   --spec <path-to-spec-file> \
@@ -133,18 +137,18 @@ Before spawning, check `ov status` to ensure non-overlapping file scope across a
 - **Read message:** `ov mail read <id> --agent $OVERSTORY_AGENT_NAME`
 
 #### 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
@@ -171,7 +175,7 @@ Before spawning, check `ov status` to ensure non-overlapping file scope across a
    ```bash
    {{TRACKER_CLI}} create "<subtask title>" --priority P1 --desc "<scope and acceptance criteria>"
    ```
-6. **Write spec files** for each issue at `.overstory/specs/<bead-id>.md`:
+6. **Write spec files** for each issue at `.overstory/specs/<task-id>.md`:
    ```bash
    # Use Write tool to create the spec file
    ```
@@ -183,18 +187,18 @@ Before spawning, check `ov status` to ensure non-overlapping file scope across a
    - Dependencies (what must be true before this work starts)
 7. **Dispatch workers** for parallel work streams:
    ```bash
-   ov sling --task <bead-id> --capability builder --name <descriptive-name> \
-     --spec .overstory/specs/<bead-id>.md --files <scoped-files> \
+   ov sling --task <task-id> --capability builder --name <descriptive-name> \
+     --spec .overstory/specs/<task-id>.md --files <scoped-files> \
      --parent $OVERSTORY_AGENT_NAME --depth 2
    ```
 8. **Create a task group** to track the worker batch:
    ```bash
-   ov group create '<batch-name>' <bead-id-1> <bead-id-2> [<bead-id-3>...]
+   ov group create '<batch-name>' <task-id-1> <task-id-2> [<task-id-3>...]
    ```
 9. **Send assign mail** to each spawned worker:
    ```bash
    ov mail send --to <worker-name> --subject "Assignment: <task>" \
-     --body "Spec: .overstory/specs/<bead-id>.md. Begin immediately." \
+     --body "Spec: .overstory/specs/<task-id>.md. Begin immediately." \
      --type assign --agent $OVERSTORY_AGENT_NAME
    ```
 10. **Monitor the batch.** Enter a monitoring loop:
@@ -218,7 +222,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
@@ -226,9 +230,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 issue:**
    ```bash
-   {{TRACKER_CLI}} 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.
 
@@ -237,20 +241,20 @@ When a worker sends `worker_done` mail (beadId, branch, exitCode, filesModified)
 4. **If branch looks good,** send `merge_ready` to coordinator:
    ```bash
    ov 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 $OVERSTORY_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 issue as closed** (if not already):
    ```bash
-   {{TRACKER_CLI}} 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:**
@@ -266,7 +270,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.
 
@@ -314,7 +318,7 @@ When a worker appears stalled (no mail or activity for a configurable threshold,
    AND send escalation to coordinator with severity `warning`:
    ```bash
    ov 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 $OVERSTORY_AGENT_NAME
    ```
 
@@ -322,7 +326,7 @@ When a worker appears stalled (no mail or activity for a configurable threshold,
    Escalate to coordinator with severity `error`:
    ```bash
    ov 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 $OVERSTORY_AGENT_NAME
    ```
 
@@ -354,7 +358,7 @@ ov mail send --to coordinator --subject "Warning: <brief-description>" \
   --body "<context and current state>" \
   --type escalation --priority normal --agent $OVERSTORY_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:
@@ -368,7 +372,7 @@ ov mail send --to coordinator --subject "Error: <brief-description>" \
   --body "<what failed, what was tried, what is needed>" \
   --type escalation --priority high --agent $OVERSTORY_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:
@@ -382,7 +386,7 @@ ov mail send --to coordinator --subject "CRITICAL: <brief-description>" \
   --body "<what broke, impact scope, manual intervention needed>" \
   --type escalation --priority urgent --agent $OVERSTORY_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.
 
@@ -397,7 +401,7 @@ When your batch is complete (task group auto-closed, all issues resolved):
 5. **Send result mail to coordinator:**
    ```bash
    ov 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 $OVERSTORY_AGENT_NAME
    ```
 6. **Close your own task:**
@@ -411,7 +415,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 `.overstory/agents/$OVERSTORY_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 `.overstory/agents/$OVERSTORY_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: `.overstory/agents/$OVERSTORY_AGENT_NAME/checkpoint.json`
   2. Reading your overlay: `.claude/CLAUDE.md` (task ID, spec path, depth, parent)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@os-eco/overstory-cli",
-	"version": "0.6.11",
+	"version": "0.7.2",
 	"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",
 	"license": "MIT",
@@ -44,12 +44,14 @@
 		"version:bump": "bun scripts/version-bump.ts"
 	},
 	"dependencies": {
+		"@os-eco/mulch-cli": "^0.6.2",
 		"chalk": "^5.6.2",
 		"commander": "^14.0.3"
 	},
 	"devDependencies": {
+		"@biomejs/biome": "^2.3.15",
 		"@types/bun": "latest",
-		"typescript": "^5.9.0",
-		"@biomejs/biome": "^2.3.15"
+		"@types/js-yaml": "^4.0.9",
+		"typescript": "^5.9.0"
 	}
 }