pi-herdr-agents 0.0.1

package/docs/research/pi-workflows-sol-advisor.md

@@ -0,0 +1,255 @@
+# Research: pi-dynamic-workflows and sol-advisor
+
+**Date:** 2026-08-03
+**Question:** What are the architectures, execution/data flows, and extension points of first-party `pi-dynamic-workflows` and `DannyMac180/sol-advisor`, and which ideas transfer to a potential `pi-herdr-subagents` workflow feature?
+**Method:** Read-only review of GitHub source/docs clones. No code modified.
+**Local transfer context (not the research targets):** `giuseppecrj/pi-herdr-agents` ADR-0002 taxonomy and draft orchestrator-designed-workflows spec.
+
+> This is preliminary research. The later ADRs and [`../orchestrated-review-workflow-plan.md`](../orchestrated-review-workflow-plan.md) supersede its early recommendation for a declarative workflow document.
+
+## Sources pinned
+
+| Project | Repo | Branch | Commit | Notes |
+| --- | --- | --- | --- | --- |
+| pi-dynamic-workflows | <https://github.com/Michaelliv/pi-dynamic-workflows> | `main` | `31b2aca0f1cb195aafbfc5e3ee2b8c83ad3f21a2` (Release v1.0.1, 2026-05-31) | Earliest public tree found (created 2026-05-28; many community forks exist). Package version `1.0.1`. |
+| sol-advisor | <https://github.com/DannyMac180/sol-advisor> | `main` | `52c0f5d467a672241665fa45aab15333274c1eef` (merge of Luna task lane, 2026-08-03) | Codex plugin version `0.4.0` in `plugins/sol-advisor/.codex-plugin/plugin.json`. |
+
+Related first-party inspiration cited by the workflow package:
+
+- Anthropic dynamic workflows post: <https://claude.com/blog/introducing-dynamic-workflows-in-claude-code>
+
+## 1. pi-dynamic-workflows
+
+### What it is
+
+A Pi package that adds one tool: `workflow`. The parent model does not call many subagents itself. It writes a small deterministic JavaScript script; the tool parses and runs that script in a Node `vm` sandbox; the script fans out work through `agent()`, `parallel()`, and `pipeline()`.
+
+Install surface (from README / `package.json`):
+
+- `pi install npm:pi-dynamic-workflows`
+- Pi package metadata: `"pi": { "extensions": ["extensions/workflow.ts"] }`
+- Peer packages: `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`, `@earendil-works/pi-tui` (^0.78.0 in the pinned tree)
+
+### Architecture (modules)
+
+| Path | Role |
+| --- | --- |
+| `extensions/workflow.ts` | Extension entry: `registerTool(createWorkflowTool())`; on `session_start`, force-activates the tool. |
+| `src/workflow-tool.ts` | Tool definition, prompt guidelines, abort handling, streaming progress via tool updates. |
+| `src/workflow.ts` | Acorn AST parse/validate of `export const meta`, determinism checks, sandboxed runtime, concurrency limiter, globals. |
+| `src/agent.ts` | `WorkflowAgent`: in-memory Pi session per `agent()` call via `createAgentSession` + `SessionManager.inMemory`. |
+| `src/structured-output.ts` | Terminating `structured_output` tool (`terminate: true`) for schema-validated returns. |
+| `src/display.ts` | Snapshot model + compact text/widget renderers for live progress. |
+| `types/workflow.d.ts` | Ambient globals for reusable workflow scripts (`/// <reference types="pi-dynamic-workflows/workflow" />`). |
+
+### Execution / data flow
+
+```text
+user asks for a workflow
+  → parent Pi model writes a JS script
+  → workflow tool receives { script, args? }
+  → parseWorkflowScript(script)
+       - first statement must be export const meta = { name, description, ... }
+       - meta is literal-only (no spreads, computed keys, interpolation, calls)
+       - whole AST bans Date.now(), Math.random(), new Date()
+  → runWorkflow in vm.createContext
+       globals: agent, parallel, pipeline, phase, log, args, cwd, process.cwd, budget
+       no require/import/fs/network
+  → each agent() call:
+       concurrency-limited
+       WorkflowAgent.run → createAgentSession(in-memory) + coding tools
+       optional schema → structured_output capture
+       returns text or validated object (null on non-abort failure)
+  → live snapshot streams through tool onUpdate / optional UI widget
+  → final structured-cloneable result returned to parent as tool content + details
+  → Esc/abort marks running agents skipped and aborts sessions
+```
+
+Important runtime details from source:
+
+- Concurrency default: `hardwareConcurrency - 2`, clamped 1–16 (`src/workflow.ts`).
+- Token budget is a rough estimate (`JSON.stringify(result).length / 4`), not provider usage.
+- `model`, `isolation: "worktree"`, and `agentType` on `agent()` options are currently **prompt guidance only** (`buildAgentInstructions`); they are not enforced runtime pins.
+- Subagents share the parent cwd and coding tools; they are not Herdr panes and not durable sessions.
+- README status: prototype. No persisted/resumable runs and no `/workflows` manager yet.
+
+### Extension points
+
+1. **Script API** — `agent` / `parallel` / `pipeline` / `phase` / `log` / `args` / `budget`.
+2. **Tool args** — optional JSON `args` injected as script global.
+3. **Library API** — `createWorkflowTool`, `runWorkflow`, `WorkflowAgent`, display helpers exported from `src/index.ts` for programmatic use.
+4. **Subagent construction** — `WorkflowAgent` accepts `tools`, `session` (model/auth/resourceLoader overrides), and base `instructions`.
+5. **Display** — tool-update stream and optional widget display factories.
+6. **Structured output** — JSON Schema on `agent()` for machine handoffs.
+
+Not extension points today: durable state, role discovery, worktree isolation enforcement, model attestation, parent fire-and-forget delivery.
+
+### Strengths for transfer
+
+- **Code-mode orchestration**: parent designs graph as executable JS, not only prose.
+- **Deterministic sandbox + literal meta**: keeps scripts auditable and parseable.
+- **Fan-out primitives**: `parallel` (thunks, input order) and `pipeline` (per-item stages) are small and clear.
+- **Live progress snapshot**: phase-grouped agent status without a full TUI framework.
+- **Structured handoff via terminating tool**: avoids an extra prose final turn.
+- **Prompt guidelines as product policy**: when to use workflows, unique labels, null-tolerant synthesis, final assertion agent.
+
+### Limits / non-goals (as shipped)
+
+- In-process, blocking parent tool call (not async pane orchestration).
+- No crash-safe resume/journal.
+- No enforced role/model/worktree isolation despite option fields.
+- Failed branches soft-fail to `null` unless aborted.
+- No parent-owned Git integration boundary.
+
+## 2. sol-advisor
+
+### What it is
+
+A **Codex plugin / skill**, not a Pi extension. It is an architect-orchestration recipe: primary session stays on **GPT-5.6 Sol / High** and owns requirements, architecture, verification, and acceptance. Implementation is delegated on one of two explicit lanes.
+
+Plugin layout (`plugins/sol-advisor/`):
+
+| Path | Role |
+| --- | --- |
+| `.codex-plugin/plugin.json` | Plugin manifest v0.4.0; skill root; marketplace UI copy. |
+| `skills/orchestration/SKILL.md` | Primary operating procedure. |
+| `skills/orchestration/references/role-contracts.md` | Native spawn packets and five-part implementation contract. |
+| `skills/orchestration/references/luna-task-lane.md` | Opt-in app-task lane contract. |
+| `agents/sol-advisor-terra-implementer.toml` | Native implementer pin: `gpt-5.6-terra` / high. |
+| `agents/sol-advisor-sol-reviewer.toml` | Native reviewer pin: `gpt-5.6-sol` / high, `sandbox_mode = "read-only"`. |
+| `scripts/install-agents.sh` | Install/check companion TOMLs; exact-byte, non-overwrite, legacy migration. |
+| `scripts/inspect-agent-runtime.sh` | Allowlisted local rollout inspector for omitted model/effort. |
+| `scripts/verify.sh` | Disposable-dir verifier for contracts, installer, inspector fixtures. |
+
+Marketplace entry: `.agents/plugins/marketplace.json` → local plugin path.
+
+### Architecture (two lanes)
+
+**Default native lane (Codex custom agents / subagent V2):**
+
+1. Preflight companion files with `install-agents.sh --check` (Terra + Sol exact match; retired Luna TOML absent).
+2. Confirm spawn tool exposes exact `agent_type`s: `sol_advisor_terra_implementer`, `sol_advisor_sol_reviewer`.
+3. Primary writes a complete five-part implementation packet (objective, files/ownership, interfaces, constraints, verification + report schema).
+4. Spawn Terra with `fork_turns: none`; no per-spawn model/effort overrides (TOML pins them).
+5. Observe role/model/effort from public spawn metadata; local inspector only fills omitted fields; public+local must agree.
+6. Primary inspects real diff and reruns verification.
+7. Spawn **fresh** Sol reviewer (new context, `fork_turns: none`) for `ship | fix-first | rethink`.
+8. Only `ship` allows completion; fix-first re-delegates then re-reviews; rethink revises architecture.
+
+**Explicit opt-in Luna task lane (Codex app tasks, outside native subagent V2):**
+
+1. Requires current-request authorization (“Use the Luna task lane…”). Skill install alone is not enough.
+2. Tools: `list_projects` → `create_thread` (`gpt-5.6-luna`, thinking `max`) → discover real `threadId`/`hostId` if only `clientThreadId` returned → `wait_threads` / `read_thread` / `send_message_to_thread`.
+3. Complete task packet includes starting state/base, git/PR boundary, structured return.
+4. Git projects default to isolated worktree; isolation is not merge safety.
+5. Primary owns corrections (same task), PR authorization (`PR AUTHORIZED FOR <threadId>`), dependent-stack ordering, and final acceptance.
+6. No native Sol reviewer for this lane; primary Sol reviews the actual worktree/diff.
+
+### Execution / data flow (native, condensed)
+
+```text
+user request
+  → confirm primary is Sol/High
+  → choose lane (native default | Luna only if explicit)
+  → native preflight: exact role files + exposed agent_types
+  → primary keeps architecture + writes complete packet
+  → spawn Terra implementer (fresh thread)
+  → observe routing evidence (public, then local inspector)
+  → primary re-verifies diff/commands
+  → spawn fresh Sol reviewer (read-only requested; observe actual sandbox)
+  → verdict ship/fix-first/rethink gates reporting done
+```
+
+### Extension points
+
+1. **Skill procedure** — SKILL.md + reference contracts are the product surface.
+2. **Role pins** — user-owned TOML custom agents installed separately; plugin update never silently overwrites divergent local roles.
+3. **Lane selection** — default native vs explicit Luna app-task path.
+4. **Packet schemas** — five-part native implementation report; Luna structured return; review verdict schema.
+5. **Runtime attestation helpers** — install check + allowlisted rollout inspector.
+6. **Verifier script** — contract/stale-claim guards without mutating real Codex config.
+
+### Strengths for transfer
+
+- **Primary remains architect/acceptor**; workers do not own product decisions.
+- **Fail-closed routing**: missing/stale/unobservable role/model/effort stops the lane; no silent fallback.
+- **Role pins outside the skill text** (exact-byte companion files) so install and discovery are checkable.
+- **Fresh-context final review** with explicit `ship | fix-first | rethink` and re-review after any fix.
+- **Complete task packets** so children do not rely on inherited chat history.
+- **Ownership + concurrency rules**: non-overlapping parallel; shared-file/dependent serial.
+- **Worker report ≠ acceptance**: parent re-runs verification and inspects real diffs.
+- **PR/push as primary-authorized boundary** (especially Luna lane).
+- **Observed sandbox vs requested sandbox** honesty for reviewers.
+- **Explicit opt-in for heavier/user-visible lanes** (Luna) vs default tighter native path.
+
+### Limits / non-goals (as shipped)
+
+- Codex-specific tools and models; not portable to Pi/Herdr without re-hosting.
+- Policy is mostly prompt/skill text, not an executable graph runner.
+- No durable multi-node scheduler; concurrency is human-procedure based.
+- Sol-on-Sol review is context-clean, not cross-model-family independence (README states this).
+
+## 3. Transfer map for pi-herdr-subagents
+
+Local package already owns **agent execution** in Herdr (async `subagent`, panes, worktrees, completion steer, role discovery). ADR-0002 says workflows compose roles and should not become a second skill system or general engine. Draft local spec `agent-adrs/specs/0001-orchestrator-designed-workflows.md` already aims at approved `workflow.md` graphs with evidence receipts — closer to sol-advisor’s control plane than to pure code-mode scripts.
+
+### High-value transfers
+
+| Idea | From | Why it fits herdr-subagents |
+| --- | --- | --- |
+| Workflow as composition layer above roles | both; ADR-0002 already | Keep `subagent` as execution; add workflow registry/runner only when two surfaces share mechanics. |
+| Explicit approval boundary before writers | sol-advisor packets; local draft `workflow.md` | Parent designs graph; user/parent approves before effectful nodes. |
+| Complete task packets / structured handoff envelopes | sol-advisor; pi-dynamic structured_output | Child must not depend on parent chat history; return status, evidence, artifacts, runtime, worktree metadata. |
+| Parent re-verification + fresh review verdict | sol-advisor | Map to existing `reviewer` / adversarial-review patterns; gate on `ship \| fix-first \| rethink`. |
+| Fail-closed model/role policy | sol-advisor | Align with local routing: exact authenticated provider/model refs; no silent substitute. |
+| Parallel writers only with distinct worktrees + non-overlapping ownership | sol-advisor Luna/native; herdr worktree docs | Already supported by `worktree: { branch, base }`; workflow runner should enforce it. |
+| Integration/PR/cleanup reserved for parent | sol-advisor; herdr worktree research | Worker commits/reports; parent integrates. |
+| Live progress snapshot | pi-dynamic-workflows display | Optional overlay on runner state; do not block on in-process tool completion. |
+| Concurrency + budget hard limits | pi-dynamic limiter/budget; sol-advisor limits language | Encode as workflow document limits, not soft prose. |
+
+### Borrow carefully / adapt, do not copy wholesale
+
+| Idea | Risk if copied raw into herdr-subagents |
+| --- | --- |
+| Parent-written JS `vm` workflow scripts (pi-dynamic) | Powerful but fights current “approved workflow.md / no recursive child graphs” draft. Prefer declarative approved graph first; optional code-mode later. |
+| Blocking in-memory subagent sessions (pi-dynamic) | Contradicts herdr’s non-blocking pane model and completion-steer delivery. Reuse `subagent` launch/watch instead of `SessionManager.inMemory`. |
+| Soft-fail agents to `null` (pi-dynamic) | Hides failures; sol-advisor/local draft prefer explicit node failure and evidence gaps. |
+| Exact Codex TOML role pins + rollout inspector | Concept (attestation) transfers; implementation must use Pi/Herdr session metadata and agent frontmatter/config, not Codex scripts. |
+| Sol/Terra/Luna model family as product identity | Do not hardcode vendor lanes. Express as configurable role→runtime policy. |
+| Skill-only orchestration (sol-advisor) | Good for procedure docs (`/plan`-style), weak for multi-node state, cancellation, and one final receipt. |
+
+### Concrete recommended shape (synthesis)
+
+1. **Keep execution in `subagent`** (roles, worktrees, model resolution, completion).
+2. **Add workflow as parent-owned composition**: validated document or registry entry with nodes, deps, ownership, limits, verification/review policy — not another agent prompt pretending to be a product surface.
+3. **From sol-advisor**: architect-in-parent, complete packets, fail-closed routing, fresh review verdict, PR/integration authorization, serial dependent stacks.
+4. **From pi-dynamic-workflows**: phase-aware progress snapshot, optional structured terminating handoff, small fan-out helpers *inside the runner* (not necessarily user-authored JS), strict “when to use workflow” guidelines.
+5. **Defer**: durable Temporal-like engine, child-authored recursive graphs, silent model fallback, auto-merge, full code-mode sandbox unless a second consumer needs the same mechanics (ADR-0002 phase 3).
+
+### Non-transfers
+
+- Replacing Herdr panes with in-memory Pi sessions.
+- Baking GPT-5.6 Sol/Terra/Luna names into package defaults as identity.
+- Growing `agents/` with more outcome-orchestration prompts (ADR-0002 explicitly rejects cloning `adversarial-reviewer` as the pattern).
+- Auto-activating a heavy lane merely because a skill/package is installed (sol-advisor Luna rule is the cautionary example).
+
+## 4. Side-by-side summary
+
+> Historical research baseline table only. The `herdr-subagents` column records the pinned 2026-08-03 research baseline and is not current package status.
+
+| Dimension | pi-dynamic-workflows | sol-advisor | herdr-subagents at research baseline |
+| --- | --- | --- | --- |
+| Host | Pi tool/extension | Codex plugin + skill + custom agents | Pi extension inside Herdr |
+| Orchestration medium | Deterministic JS script in vm | Skill procedure + spawn/app tools | Parent prompts + `subagent` tool + a few commands (`/plan`, `/iterate`, `/btw`) |
+| Child runtime | In-memory Pi session | Codex native thread or app task | Herdr pane/session (Pi or CLI adapter) |
+| Isolation | Shared cwd; worktree option not enforced | Worktree default on Luna Git projects; ownership rules | Optional managed worktrees |
+| Model policy | Guidance strings | Exact TOML pins + attestation | Invocation → agent → config → parent chain |
+| Acceptance | Parent tool result JSON | Parent re-verify + fresh Sol verdict | Completion steer; no first-class workflow receipt |
+| Durability | None | Thread/task identity in Codex | Session files + worktree metadata; no workflow graph state |
+| Status | Prototype v1.0.1 | Plugin 0.4.0 with installer/verifier | Mature execution package; workflow feature was still at the taxonomy/spec stage |
+
+## 5. Bottom line
+
+- **pi-dynamic-workflows** is a compact **code-mode fan-out engine** for Pi: script → sandbox → many short in-memory agents → one tool result. Best borrowed pieces: progress snapshots, structured handoffs, and tight fan-out primitives — not its blocking in-memory runtime.
+- **sol-advisor** is a **control-plane recipe** for architect/implement/review with fail-closed routing and evidence-based acceptance. Best borrowed pieces: complete packets, primary-owned verification, fresh review verdicts, explicit lane opt-in, and integration authorization.
+- For **pi-herdr-subagents**, the high-leverage path is sol-advisor-style control + herdr execution + optional pi-dynamic presentation/helpers, matching the local draft “approved workflow document → runner → evidence receipt” direction rather than cloning either repo wholesale.

package/docs/research/worktree-subagent-orchestration.md

@@ -0,0 +1,317 @@
+# Worktree-based subagent orchestration research
+
+> This document records background evidence and design rationale. For supported package behavior and operating instructions, see [Worktree subagents](../worktree-subagents.md) and the [README](../../README.md).
+
+**Date:** 2026-07-30  
+**Question:** How are coding-agent products and open-source orchestrators using Git worktrees or equivalent isolated checkouts to run parallel tickets, report completion, review results, publish PRs, and clean up?
+
+## Executive summary
+
+There is no single standard for “worktree agent orchestration.” The products also vary: some allow shared checkouts, and some delegate commit, push, or PR creation to workers. The evidence nevertheless supports these **synthesis recommendations** for this extension:
+
+1. **Give each writing ticket run one isolated checkout.** A branch, process, pane, or model context alone is not filesystem isolation.
+2. **Treat agent completion as a handoff, not integration.** Preserve a diff, commit, branch, worktree, transcript, or PR for review.
+3. **Reserve shared and irreversible actions for the orchestrator by default.** Workers edit, test, and commit locally; the parent provisions worktrees, verifies results, pushes, creates or updates PRs, merges, and cleans up. Repositories may explicitly choose a worker-publishes-PR policy instead.
+4. **Parallelize implementation and serialize integration.** Worktrees prevent concurrent file overwrites, but branches can still conflict when integrated.
+5. **Make cleanup state-aware.** Dirty files, untracked files, unique commits, unpushed branches, active processes, and unknown ownership require preservation rather than automatic deletion.
+6. **Track runtime, checkout, branch, transcript, and PR as separate lifecycle resources.** They may be retained or removed independently.
+7. **Treat stacked PRs as a separate advanced workflow.** They require dependency metadata, descendant restacking, lease-safe force pushes, bottom-up merge order, and re-running review/CI gates.
+
+The closest precedents for the proposed first version are:
+
+- **Claude Code worktree-isolated subagents:** caller/worker completion plus conservative temporary-worktree cleanup.
+- **OpenAI Codex and Cursor local worktrees:** one conversation/task per managed worktree followed by an explicit review/apply/PR decision.
+- **Claude Squad and Shoal:** local control planes mapping task → worktree → terminal/agent session.
+- **OpenWeft and Vigla:** parallel workers with serialized integration.
+- **Gas Town:** the most complete durable worker-to-merge-queue model, useful as long-term inspiration rather than a suitable first implementation.
+
+For `pi-herdr-subagents`, the research supports a managed single-call `subagent(... worktree ...)` spawn, typed completion metadata, parent-owned verification, and explicit retention/removal. PR automation, durable ticket DAGs, merge queues, and stacks should come later.
+
+## Terminology
+
+- **Worktree:** a linked Git checkout with its own working files, `HEAD`, and index while sharing repository objects and most refs. It is isolation from file overwrites, not a security sandbox. ([Git](https://git-scm.com/docs/git-worktree))
+- **Ticket run:** one orchestration attempt for one ticket, including its base commit, branch, worktree, agent session, and result.
+- **Worker completion:** the coding agent has stopped and reported a result. It does not imply that the result was accepted, pushed, reviewed, or merged.
+- **Integration:** the shared operation that applies or publishes worker changes: local merge, push/PR, merge queue, or stack update.
+- **Finalization:** an explicit decision to publish, retain, discard, or remove a completed ticket run.
+
+## Product landscape
+
+> Historical research baseline table only. Product rows below are pinned evidence from the research date, not current package status.
+
+| Product | Concurrent unit | Isolation | Handoff and integration lesson |
+| --- | --- | --- | --- |
+| [OpenAI Codex](https://learn.chatgpt.com/docs/environments/git-worktrees) | Desktop/cloud chat | Desktop uses a managed Git worktree per chat; cloud uses a container checkout | Worktree execution is separate from **Handoff**, branch creation, commit, push, and PR. Managed cleanup retains recent worktrees and snapshots state before eviction. |
+| [Claude Code](https://code.claude.com/docs/en/worktrees) | Session or subagent | Local sessions can use worktrees; custom subagents support `isolation: worktree`; cloud uses isolated VMs | Background child completion returns to the caller. Clean unchanged temporary worktrees can disappear, but changed/untracked/unpushed work is retained. ([Subagents](https://code.claude.com/docs/en/sub-agents)) |
+| [Cursor](https://cursor.com/docs/configuration/worktrees) | Local task or best-of-N candidate | One local worktree per task/candidate; Cloud Agents use VMs and clones | The user reviews a result and separately applies it, commits/pushes it, or opens a PR. Worktree cleanup is capped by age/count. ([Agents Window](https://cursor.com/docs/agent/agents-window)) |
+| [GitHub Copilot cloud agent](https://docs.github.com/en/copilot/concepts/agents/cloud-agent/about-cloud-agent) | Cloud task/session | Ephemeral Actions environment plus one task branch, not a local worktree | Branch/commit/push can be automated while PR creation may be deferred until the user reviews and iterates. Stopping runtime preserves pushed commits. ([Session management](https://docs.github.com/en/copilot/how-tos/copilot-on-github/use-copilot-agents/manage-and-track-agents)) |
+| [Google Jules](https://jules.google/docs/environment/) | Task | Short-lived VM and cloned repository | Completion yields summary/diff and an explicit publish-branch or publish-PR action. Multiple tasks have independent VMs, logs, and changes. ([Tasks](https://jules.google/docs/tasks-repos/)) |
+| [Devin](https://docs.devin.ai/work-with-devin/advanced-capabilities) | Managed child/session | Cloud children use isolated VMs; Desktop conversations use native worktrees | Devin provides a real coordinator/worker precedent: decomposition, bounded parallel children, progress, intervention, conflict handling, and synthesis. Desktop still leaves merge/winner choice to the user. ([Desktop worktrees](https://docs.devin.ai/desktop/cascade/worktrees)) |
+
+### Product-level conclusions
+
+- Coordination and isolation are orthogonal. Claude agent teams have shared tasks and messaging, but Anthropic still warns that teammates editing the same files can overwrite one another unless separate isolation is used. ([Claude agent teams](https://code.claude.com/docs/en/agent-teams))
+- Products consistently stop at a reviewable artifact rather than treating child exit as merge approval.
+- The control surface matters: Cursor’s Agents Window, GitHub’s agents panel, and Devin’s coordinator expose parallel state while preserving a distinct review/integration decision.
+- Cloud VMs provide a stronger security/runtime boundary than worktrees. The proposed local feature should promise checkout isolation only.
+
+## Open-source projects
+
+### Closest local control-plane precedents
+
+#### Claude Squad
+
+[`smtg-ai/claude-squad`](https://github.com/smtg-ai/claude-squad) maps each operator-created task to one Git worktree and one tmux session. It persists branch ownership, base commit, status, and session metadata in JSON. Pause and delete are separate: pause can retain the branch for resume, while deletion removes only worktrees/branches that Claude Squad owns. Its “submit” path pushes and opens the branch URL but does not create or merge a PR. ([README](https://github.com/smtg-ai/claude-squad/blob/2dd388e9857233e07712c8c5b3e2bf3b471b39fa/README.md), [worktree lifecycle](https://github.com/smtg-ai/claude-squad/blob/2dd388e9857233e07712c8c5b3e2bf3b471b39fa/session/git/worktree_ops.go))
+
+**Useful lesson:** explicitly record whether the orchestrator created the branch; never delete a pre-existing branch as incidental cleanup.
+
+#### Shoal
+
+[`TheShoal/shoal-cli`](https://github.com/TheShoal/shoal-cli) persists `task/session → branch → worktree → tmux runtime → status/journal` in SQLite. Provisioning rolls back partial resources. Finalization can either push/create a GitHub PR or merge locally, and conflicted work is preserved for manual repair. ([Architecture](https://github.com/TheShoal/shoal-cli/blob/3d45e0b9eb1bc981b612429c720827d71324e9dd/ARCHITECTURE.md), [lifecycle](https://github.com/TheShoal/shoal-cli/blob/3d45e0b9eb1bc981b612429c720827d71324e9dd/src/shoal/services/lifecycle.py))
+
+**Useful lesson:** a vendor-neutral terminal control plane can provide value without embedding a sophisticated planner or merge engine.
+
+#### Vibe Kanban
+
+[`BloopAI/vibe-kanban`](https://github.com/BloopAI/vibe-kanban) creates a workspace branch and one worktree per selected repository, then launches external coding-agent processes inside it. It persists workspace/session/process/action/turn state and logs. PR publication and guarded local squash integration are separate paths. Worktree deletion and branch deletion are separately controlled. The project’s docs also make the key counterexample explicit: multiple sessions inside one workspace still share files and use last-writer-wins behavior. ([Worktree creation](https://github.com/BloopAI/vibe-kanban/blob/4deb7eca8f381f7cbc1f9d15515a9ab8f8009053/crates/workspace-manager/src/workspace_manager.rs), [shared-session warning](https://github.com/BloopAI/vibe-kanban/blob/4deb7eca8f381f7cbc1f9d15515a9ab8f8009053/docs/workspaces/multi-repo-sessions.mdx))
+
+**Useful lesson:** isolation belongs to the ticket run, not merely to the conversation or process.
+
+### Workflow orchestrators
+
+#### OpenWeft
+
+[`NeuraCerebra-AI/openweft`](https://github.com/NeuraCerebra-AI/openweft) divides work into overlap-safe phases, runs bounded workers in separate worktrees, checkpoints worktree/session identity before agent execution, and then priority-sorts and merges completed branches serially. Conflicts are resolved in the feature checkout through bounded worker retries. ([Scheduler](https://github.com/NeuraCerebra-AI/openweft/blob/30427ac8e8f592cf34f771517f12cb25d7fbc9f7/src/orchestrator/realRun.ts), [checkpoint](https://github.com/NeuraCerebra-AI/openweft/blob/30427ac8e8f592cf34f771517f12cb25d7fbc9f7/src/state/checkpoint.ts))
+
+**Useful lesson:** parallel execution does not require parallel integration. Serialize only the shared critical section.
+
+#### Vigla
+
+[`Kilbex/Vigla`](https://github.com/Kilbex/Vigla) uses a mission-level supervisor branch/worktree plus one worktree per dependency-aware worker. Accepted workers integrate serially into the supervisor branch; only explicit final acceptance touches the user’s target branch. Git refs/tags provide recovery anchors in addition to persisted orchestration events. ([Mission workspace](https://github.com/Kilbex/Vigla/blob/bbd19ae2d5a77401502756c550b5dcd4ae59bbc9/crates/orchestrator/src/mission_workspace/mod.rs), [DAG dispatcher](https://github.com/Kilbex/Vigla/blob/bbd19ae2d5a77401502756c550b5dcd4ae59bbc9/crates/orchestrator/src/mission_supervisor_run/mission_loop.rs))
+
+**Useful lesson:** if local multi-ticket integration is added later, a dedicated integration branch is safer than letting each worker mutate the user’s target.
+
+#### Gas Town
+
+[`gastownhall/gastown`](https://github.com/gastownhall/gastown) is the fullest verified example. It separates durable worker identity, reusable worktree, terminal runtime, assignment, and merge request. Worker completion pushes and verifies an exact submitted SHA before creating a durable merge-request record. A separate Refinery serializes target integration, runs gates, handles conflicts as tracked repair work, and can bisect failing batches. ([Architecture](https://github.com/gastownhall/gastown/blob/649b832b7672bc7a2dbef26f5983aba6198b819b/docs/design/architecture.md), [completion handoff](https://github.com/gastownhall/gastown/blob/649b832b7672bc7a2dbef26f5983aba6198b819b/internal/cmd/done.go), [merge engine](https://github.com/gastownhall/gastown/blob/649b832b7672bc7a2dbef26f5983aba6198b819b/internal/refinery/engineer.go))
+
+**Useful lesson:** a mature autonomous integrator needs a durable ledger, exact SHA fencing, serialized gates, repair tasks, and crash recovery. This is a later architecture, not an appropriate v1 scope.
+
+#### Baton
+
+[`mraza007/baton`](https://github.com/mraza007/baton) is a bounded GitHub-issue queue: each issue maps to one branch/worktree and Claude process. The worker is prompted to commit, push, and create a PR; the controller recognizes the PR and releases the claim but does not merge. ([Dispatcher](https://github.com/mraza007/baton/blob/7bb5fb7/symphony/orchestrator.py), [workspace manager](https://github.com/mraza007/baton/blob/7bb5fb7/symphony/workspace.py))
+
+**Useful lesson:** one external ticket can be the stable identity for one run, but delegating push/PR to workers trades implementation simplicity for weaker central control and recovery.
+
+### Other useful implementations
+
+- [Crystal](https://github.com/stravu/crystal) implemented one process/worktree per session, conflict preflight, rebase, and fast-forward integration, but is deprecated in favor of Nimbalyst. It is useful source material, not a dependency recommendation.
+- Vibe Kanban’s current repository says the product is sunsetting. Its implementation remains useful evidence, but it should not become a new dependency.
+- [Conductor](https://www.conductor.build/docs/concepts/git-worktrees) is a relevant commercial product benchmark, but its application source is not public.
+- [`harms-haus/pi-worktrees`](https://github.com/harms-haus/pi-worktrees) provides Pi worktree commands but not parallel agent orchestration.
+- [`aleclarson/agent-merge`](https://github.com/aleclarson/agent-merge) handles integration after agents/worktrees already exist; it intentionally has no session or job lifecycle.
+
+## Standards and mature workflow patterns
+
+### Git worktree invariants
+
+The extension should rely on Git’s supported worktree interface rather than filesystem assumptions:
+
+- `git worktree list --porcelain -z` provides scriptable path, branch/detached, lock, and prunable state. ([Git](https://git-scm.com/docs/git-worktree#_porcelain_format))
+- Git normally refuses to check out one branch in multiple worktrees. `--force` bypasses occupancy and stale-path safeguards and should not be a normal recovery strategy. ([Git](https://git-scm.com/docs/git-worktree#Documentation/git-worktree.txt---force))
+- A worktree lock prevents pruning, movement, and ordinary deletion and can store a reason. ([Git](https://git-scm.com/docs/git-worktree#Documentation/git-worktree.txt-lock))
+- Normal removal accepts only clean linked worktrees. Forced removal can discard dirty and untracked state. ([Git](https://git-scm.com/docs/git-worktree#Documentation/git-worktree.txt-remove))
+- Worktrees share most refs and repository configuration. They isolate checkout/index state, not every Git mutation. ([Git refs](https://git-scm.com/docs/git-worktree#_refs))
+- `git worktree repair` and `prune` have distinct recovery purposes; orchestrators should never edit `.git/worktrees/*` directly. ([Git details](https://git-scm.com/docs/git-worktree#_details))
+
+### Scheduling
+
+Python’s `TopologicalSorter` is a useful standard-library model for future ticket DAGs: validate cycles before side effects, dispatch only `get_ready()` nodes, and release descendants only after explicit `done()` acknowledgement. ([Python](https://docs.python.org/3/library/graphlib.html#graphlib.TopologicalSorter))
+
+GitHub Actions provides a mature failure-propagation analogy: failed/skipped prerequisites prevent dependent jobs unless an explicit always-run path is defined. Cleanup/reconciliation should be such an always-run path, while dependent implementation should fail closed. ([GitHub Actions `needs`](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idneeds))
+
+### Reconciliation and crash recovery
+
+Kubernetes controllers provide the relevant architectural pattern for a later durable orchestrator: persist desired state, observe actual Git/runtime/GitHub state, and apply only missing transitions. ([Kubernetes controller pattern](https://kubernetes.io/docs/concepts/architecture/controller/#controller-pattern))
+
+This matters around ambiguous side effects:
+
+- after worktree creation, adopt only an exact path/ref/base/ownership match;
+- after push timeout, fetch the exact remote ref before retrying;
+- after PR-create timeout, query by full head/base before creating again;
+- after merge timeout, query the PR’s merged state before retrying;
+- after cleanup failure, keep a visible `cleanup_pending` state.
+
+### GitHub publication and gates
+
+GitHub treats PR head/base, draft status, required reviews, checks, merge queues, merged state, and branch deletion as distinct facts. Rulesets may layer with branch protection, so GitHub—not a local reimplementation—is authoritative for mergeability. ([Protected branches](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches), [Rulesets](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets))
+
+If rewritten branches are ever supported, use exact `--force-with-lease=<ref>:<expected-sha>` rather than plain force. ([Git push](https://git-scm.com/docs/git-push#Documentation/git-push.txt---force-with-leaseltrefnamegtltexpectgt))
+
+## Stacked PRs
+
+Graphite is the clearest mature reference. It stores parent relationships that vanilla Git does not, recursively restacks descendants after parent changes, and recommends bottom-up merging followed by sync/restack/submit of the remaining stack. ([Restacking](https://graphite.com/docs/restack-branches), [Manual stack merge](https://graphite.com/docs/merge-stack-prs-github))
+
+Its worktree guidance is especially relevant: Graphite generally avoids modifying a branch checked out in another worktree, so a stack spread across worktrees requires deliberate operations in each checkout. ([Graphite worktrees](https://graphite.com/docs/multiple-worktrees))
+
+A stack therefore adds:
+
+- parent/child branch metadata beyond Git;
+- a serialization lock for rewrites;
+- descendant `stale_base` states;
+- lease-safe force pushes;
+- bottom-up merge order;
+- re-evaluation of checks, reviews, CODEOWNERS, and conflicts after rewrites;
+- compatibility decisions for GitHub merge queues and stale-review policies.
+
+**Recommendation:** default to independent PRs based on trunk. Allow hard-dependent work only after its predecessor merges. Add native or Graphite-backed stacks later as an explicit repository capability, not as part of worktree spawning.
+
+## Implications for `pi-herdr-subagents`
+
+The extension already has several pieces that comparable tools need:
+
+- asynchronous launch and parent wake-up;
+- stable child session files and resume flow;
+- Herdr pane status and interruption;
+- a parent widget for concurrent work;
+- bounded completion delivery;
+- an internal launch path that can accept a pre-created Herdr surface;
+- `cwd`-aware child execution.
+
+The missing seam is **ticket-run placement and handoff metadata**, not a new general orchestration framework.
+
+### Recommended first version
+
+Expose one atomic operation through the existing `subagent` interface:
+
+```ts
+subagent({
+  name: "Ticket 123",
+  agent: "worker",
+  task: "...",
+  worktree: {
+    branch: "ticket/123",
+    base: "main"
+  }
+})
+```
+
+Internally:
+
+1. Resolve the source repository and exact base SHA.
+2. Before creating resources, persist a small ownership manifest with run ID, source repository, intended branch/base SHA, and label. This need not be a database or full controller.
+3. Use `herdr worktree create --cwd ... --branch ... --base ... --label ... --no-focus`.
+4. Parse the returned Herdr workspace, root pane, worktree path, and branch. Retain the already-resolved base SHA from the manifest because the create response does not include it.
+5. Update the manifest with observed resource identities, then launch the child in the returned root pane and worktree cwd.
+6. Record the same worktree metadata on the running subagent for live status and delivery.
+7. On completion, verify and return machine-readable Git state alongside the prose summary.
+8. Leave changed work available for parent review; do not automatically remove the worktree.
+
+Suggested completion metadata:
+
+```text
+run ID
+worktree path and Herdr workspace ID
+branch and resolved base SHA
+HEAD/commit SHA and commits ahead
+changed files
+clean/dirty/untracked/conflicted state
+checks reported by the worker
+session path and resume reference
+```
+
+Suggested first-version states:
+
+```text
+provisioning -> running -> ready_for_review
+                       -> failed
+ready_for_review -> revising
+                 -> retained
+                 -> discarded
+                 -> finalized
+```
+
+Keep these ticket-run states separate from the existing process/turn/delivery lifecycle.
+
+### Ownership policy
+
+| Action | Worker | Parent/orchestrator |
+| --- | ---: | ---: |
+| Edit, test, make focused commits | Yes | Verify |
+| Create/open/remove worktree | No | Yes |
+| Select branch and base | No | Yes |
+| Push branch | No by default | Explicit action |
+| Create/update PR | No by default | Explicit action |
+| Merge or enqueue | No | Explicit action |
+| Decide retain/discard/cleanup | No | Yes |
+
+### Conservative cleanup policy
+
+Automatic removal is safe only when all of the following are proven:
+
+- the extension created and still owns the worktree;
+- no child process is active;
+- the checkout is clean and not mid-merge/rebase;
+- no untracked files exist;
+- no unique/unpushed commits would be lost;
+- the branch retention decision is explicit.
+
+Otherwise, report the blocker and keep the worktree. Pane/process cleanup, worktree cleanup, branch cleanup, transcript retention, and PR retention must remain independent actions.
+
+### Explicitly defer
+
+Do not include these in the first version:
+
+- autonomous push/PR/merge;
+- stacked PR orchestration;
+- ticket dependency DAGs;
+- a full durable database or controller loop beyond the minimal ownership manifest;
+- pooled/reused worktrees;
+- automatic conflict-resolution agents;
+- merge queues;
+- best-of-N candidates;
+- multi-repository ticket workspaces.
+
+Add each only after the atomic isolated ticket run and review/resume/cleanup path is reliable.
+
+## Recommended implementation sequence
+
+1. **Managed worktree spawn:** one worker, one Herdr-managed worktree, one ownership manifest, one completion handoff.
+2. **Review and resume:** parent can inspect and resume the same child/worktree without losing state.
+3. **Explicit finalization:** retain or safely remove; publication can initially use normal `git`/`gh` commands.
+4. **Run reconciliation:** recover and reconcile extension-owned worktrees after Pi/Herdr restart.
+5. **Bounded ticket fleet:** queue and concurrency cap for independent tickets.
+6. **PR adapter:** parent-owned push/create/update with exact branch/SHA metadata.
+7. **Dependency scheduling:** explicit DAG and blocked-upstream behavior.
+8. **Advanced integration:** supervisor branch, merge queue, or opt-in stacked PR adapter.
+
+## Primary sources
+
+### Standards and workflow primitives
+
+- Git worktrees: <https://git-scm.com/docs/git-worktree>
+- Git push leases: <https://git-scm.com/docs/git-push#Documentation/git-push.txt---force-with-leaseltrefnamegtltexpectgt>
+- Python `TopologicalSorter`: <https://docs.python.org/3/library/graphlib.html#graphlib.TopologicalSorter>
+- GitHub protected branches: <https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches>
+- GitHub rulesets: <https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets>
+- GitHub merge queues: <https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue>
+- Kubernetes controller pattern: <https://kubernetes.io/docs/concepts/architecture/controller/#controller-pattern>
+- Graphite worktrees: <https://graphite.com/docs/multiple-worktrees>
+- Graphite restacking: <https://graphite.com/docs/restack-branches>
+
+### Products and projects
+
+- OpenAI Codex worktrees: <https://learn.chatgpt.com/docs/environments/git-worktrees>
+- Claude Code worktrees: <https://code.claude.com/docs/en/worktrees>
+- Claude Code subagents: <https://code.claude.com/docs/en/sub-agents>
+- Cursor worktrees: <https://cursor.com/docs/configuration/worktrees>
+- GitHub Copilot cloud agent: <https://docs.github.com/en/copilot/concepts/agents/cloud-agent/about-cloud-agent>
+- Google Jules environment: <https://jules.google/docs/environment/>
+- Devin managed children: <https://docs.devin.ai/work-with-devin/advanced-capabilities>
+- Claude Squad: <https://github.com/smtg-ai/claude-squad>
+- Shoal: <https://github.com/TheShoal/shoal-cli>
+- Vibe Kanban: <https://github.com/BloopAI/vibe-kanban>
+- OpenWeft: <https://github.com/NeuraCerebra-AI/openweft>
+- Vigla: <https://github.com/Kilbex/Vigla>
+- Gas Town: <https://github.com/gastownhall/gastown>
+- Baton: <https://github.com/mraza007/baton>