opencode-herdr-orchestration 0.1.5 → 0.2.0

package/README.md

@@ -1,11 +1,227 @@
 # opencode-herdr-orchestration
 
-Capability-separated OpenCode agents for planning, implementation, independent review, and delivery through Herdr.
+Capability-separated OpenCode agents for planning, implementation, independent review, and delivery through Herdr, organized as **Developer → Shepherd → Flock**.
 
 This package registers the agents, provides complete structured worker-response retrieval, injects session-specific orchestration mode into shell environments, and ships a reproducible Git `pre-push` policy for new and existing repositories.
 
 Requires Node.js 20 or newer when running the package CLI or tests.
 
+## Philosophy
+
+There is exactly **one Developer: the human operator**, and the Developer sits above the Shepherd. The Developer owns intent, product judgment, risk tolerance, and every final approval. No agent replaces the Developer; the Shepherd and every agent below it only prepare decisions for the Developer.
+
+The Developer works through the Shepherd's two **technical phases**, each a registered agent:
+
+- `shepherd` — the **planning** phase. Researches the repository through read-only workers and presents implementation-ready plans. It never implements.
+- `shepherd-governor` — the **governance** phase. Approves plans by taking over the session, contracts bounded work, judges semantics — integrated results, review verdicts, and escalations — and owns everything remote: pushes, merges, PRs, and delivery.
+
+The **Flock** is the bounded workforce herded under those phases:
+
+- `sheepdog` — herds the working flock: prepares worker branches and worktrees, drives worker delegation, watches progress, retries and re-contracts leaves, runs deterministic validation, selects the shearer review tier, recovers conflicts by re-scoping ownership, and performs local integration of worker output under the governor's contracts.
+- `grazer` — read-only research workers that graze the repository for evidence.
+- `sheep` — bounded implementation workers that produce verified local commits.
+- `shearer-low` / `shearer-medium` — independent read-only reviewers.
+
+Three invariants govern the whole system:
+
+1. **Authority flows down, never sideways or up.** Each role may mutate only what its authority permits. A worker cannot delegate beyond its assignment; a reviewer cannot mutate; the flock cannot deliver.
+2. **Results flow up through structured channels.** Shepherd-phase agents act on settled, paginated responses and committed artifacts — never on terminal scrollback, partial state, or a worker's reasoning transcript.
+3. **Approval never flows down implicitly.** Reaching a milestone never grants authority, and the Developer's acknowledgement of a plan is a separate, explicit control.
+
+## Topology
+
+```text
+Developer (the human operator, one per flock)
+│
+├── Planning phase: shepherd
+│   └── grazer                          read-only research
+│
+└── Governance phase: shepherd-governor
+    ├── grazer                          read-only research
+    └── sheepdog                        herds the working flock
+        ├── sheep                       bounded implementation
+        ├── shearer-low                 independent review, low reasoning
+        └── shearer-medium              independent review, medium reasoning
+```
+
+## Roles and authorities
+
+| Agent | Tier | Direct mutation | Spawns | Git authority |
+| --- | --- | --- | --- | --- |
+| `shepherd` | Strong (inherits active model) | Markdown plans, research notes, task briefs, handoffs | `grazer` only | Local Markdown commits only; no push |
+| `shepherd-governor` | Strong (inherits active model) | Markdown briefs, handoffs, review notes | `grazer`, `sheepdog` | Integration, push, PR, merge, delivery |
+| `sheepdog` | Fast worker (`litellm/glm-5.3-flash`) | None | `grazer`, `sheep`, `shearer-low`, `shearer-medium` | Local integration of worker output; no push |
+| `grazer` | Fast worker (`litellm/glm-5.3-flash`) | None | None | Read-only inspection |
+| `sheep` | Fast worker (`litellm/glm-5.3-flash`) | Assigned implementation | None | Local task commit only |
+| `shearer-low` | Reviewer (`litellm-responses/gpt-5.6-terra`, low) | None | None | Read-only inspection |
+| `shearer-medium` | Reviewer (`litellm-responses/gpt-5.6-terra`, medium) | None | None | Read-only inspection |
+
+Model tiers are deliberate. The two shepherd-phase agents run on the active strong model and inherit its reasoning behavior, because planning and governance are the judgment-heavy work. Flock workers run on a fast, cheap model because their tasks are bounded and their outputs are validated. Shearers run a dedicated independent model at fixed `low` and `medium` reasoning so review is never the same model grading its own family's homework.
+
+Sheepdog chooses `shearer-low` for localized mechanical changes with strong deterministic coverage. It chooses `shearer-medium` for security, architecture, migrations, public APIs, deployment, concurrency, cross-component work, weak coverage, or material uncertainty.
+
+## Governing controls
+
+### Separate acknowledgement and milestone controls
+
+Acknowledgement and progress are intentionally different mechanisms:
+
+- **Acknowledgement** is the act of selecting `shepherd-governor` in the session. Switching from the planning phase to the governance phase approves the latest presented plan. Nothing else — not a worker finishing, not a check passing, not time passing — approves a plan.
+- **Milestones** track progress: the plan header (`Plan-ID`, `Base-Commit`, `Status`), each `task_id` contract, each verified local task commit, and each review verdict.
+
+Milestones never imply acknowledgement, and acknowledgement never auto-advances a milestone. Governance-phase startup reports the plan ID, approved base, and current HEAD, then inspects divergence from the approved base before delegating.
+
+Before acknowledging any task contract, the sheepdog reads the authoritative plan artifact itself with `herdr_plan_read` using the contract's plan ID — never a secondhand summary — and replans when the contract contradicts what the plan artifact says.
+
+Final plans carry:
+
+```text
+Plan-ID: <short-project-topic>-<YYYYMMDD>-<sequence>
+Base-Commit: <full commit hash>
+Status: PROPOSED
+```
+
+### Worker reply protocol
+
+Worker replies are keyword-prefixed structured messages with two distinct channels:
+
+- **Acknowledgement replies** open a coordinator's first response to a task contract: `ACK` (contract accepted, work starting), `CORRECT` (contract must be corrected first), `REPLAN` (contract conflicts with the approved plan or repository evidence), or `STOP` (blocked outright). Only the sheepdog — a squad lead, not a leaf — sends an acknowledgement turn, and only to the governor.
+- **Leaf workers work directly.** Grazer, sheep, and shearers start their assignments without an acknowledgement turn. If a leaf cannot start, its first reply begins with `CORRECT`, `REPLAN`, or `STOP`.
+- **Milestone replies** report completed milestones: `CONTINUE` (ready for the next milestone), `CORRECT` (defects need correction within the current task), `REPLAN` (evidence invalidates the plan; escalation for re-planning), `STOP` (blocked after a milestone), or `FINALIZE` (all milestones complete, final report follows).
+
+`FINALIZE` closes a task and is never an acknowledgement. `CORRECT`, `REPLAN`, and `STOP` are legal on either channel.
+
+### No chain of thought
+
+Shepherd-phase agents govern by contracts and results, not by reading worker reasoning. The `herdr_agent_response` tool returns only the latest completed final assistant message: intermediate tool-call steps, errors, ignored text, reasoning, and terminal rendering are excluded at the source. Shearers likewise receive fresh bounded context — user goal, approved plan, task contract, base and implementation commits, diff, and verification results — never the worker conversation.
+
+This keeps delegation bounded, keeps review independent, and keeps a shepherd-phase agent's context small enough to govern many workers.
+
+### Deterministic validation
+
+Before requesting semantic review, sheepdog runs or delegates deterministic repository-native checks (the repository's own check and test commands) and owns retrying deterministic failures back to the responsible sheep. Shearers judge semantics and defects; deterministic coverage is confirmed first so review cycles are never spent discovering what a test would have caught.
+
+### Review
+
+Shearer verdicts are:
+
+- `PASS`: integrate after governor checks.
+- `REWORK`: return actionable findings to the responsible sheep and review the correction.
+- `ESCALATE`: research, re-plan, or request Shepherd judgment.
+
+Two failed semantic review cycles for the same task escalate instead of looping indefinitely.
+
+### Escalation
+
+Task contracts carry explicit `escalate_if` conditions. Flock workers must escalate rather than guess when evidence contradicts the assignment, ownership must expand, a public API or migration changes unexpectedly, a product or architecture decision is needed, permissions block required work, or repeated attempts fail. Shepherd-phase agents resolve what repository evidence permits and surface unresolved product choices to the Developer — the human — for judgment. `unknown` is treated as inconclusive, never complete.
+
+### Local integration and conflict delegation
+
+Sheepdog owns the execution mechanics end to end: it prepares each parallel `sheep` worker a dedicated branch and worktree with non-overlapping ownership and an explicit integration order, performs local integration of worker output under the governor's contracts using a narrow merge and cherry-pick lifecycle (`git merge --ff-only`, `git merge --no-ff --no-edit`, `git cherry-pick`, and their continue/abort/quit forms), and owns conflict recovery: on any conflict it aborts immediately, re-inspects, recovers by re-scoping ownership or issuing bounded recovery tasks to the responsible sheep, and escalates when conflicts invalidate the plan, repeat, or exceed its authority. Sheepdog never hand-edits a conflicted file. The governor judges the result semantically — mechanical drift is reported as deviations, and it returns defects to sheepdog rather than editing implementation itself. No flock role pushes, opens PRs, or delivers; all integration stays local until the delivery authority pushes.
+
+## State storage
+
+All durable orchestration state lives outside agent memory and plugin process state, in two places:
+
+- **The constrained orchestration state API.** Four plugin tools store and retrieve Markdown artifacts with JSON frontmatter under the repository's shared Git common directory: `herdr_plan_write` for plan artifacts (the planning shepherd only), `herdr_plan_read` for plan artifacts (shepherd, shepherd-governor, and sheepdog), and `herdr_execution_write` and `herdr_execution_read` for execution artifacts (sheepdog). Sheepdog and the governor may read the authoritative plan but never write one; plan authorship stays with the planning shepherd. Artifacts live at `<git-common-dir>/herdr/plans/<planId>.md` and `<git-common-dir>/herdr/executions/<planId>.md`. Writes are atomic; the service invokes only read-only `git rev-parse`; Markdown bodies are capped at 1 MiB; plan IDs are 1–64 characters of letters, digits, dot, underscore, or hyphen.
+- **Git history.** Shepherd-phase agents may commit intended Markdown planning artifacts locally, and worker output is a verified local commit; progress is Git history, reviewable and revertable.
+
+Every worker worktree sheepdog creates — including worktrees created from other worktrees — is a **peer that shares the same Git common repository**, never a nested checkout. Because the state API stores artifacts under the common directory, a plan written in one worktree governs workers in all of them, and orchestration state survives session ends, process restarts, and machine reboots. Separate clones never share this state.
+
+Everything not stored this way is explicitly ephemeral: `SHEPHERD_MODE` is injected per OpenCode session and dies with the session; response cursors are HMAC-signed with a per-plugin-process secret, expire after six hours, and do not survive a restart of the shepherd's OpenCode plugin process.
+
+## Git authority
+
+| Mode | Hook behavior |
+| --- | --- |
+| Planning phase (`shepherd`) | Denies every push; delivery belongs to the governance phase |
+| Governance phase (`governor`) | Allows only the current attached branch pushed to the same remote branch |
+| Flock workers (sheepdog, grazer, sheep) | Denies every push |
+| Shearers (shearer-low, shearer-medium) | Denies every push |
+| Missing/unknown | Does not interfere with normal human Git use |
+
+The hook rejects pushes from detached HEAD in governance mode, protected branches, ref renames, unrelated refs, and remote ref deletions. In governance mode `main` and `master` are always protected; add repository-specific branches:
+
+```bash
+git config --add orchestration.protectedBranch production
+git config --add orchestration.protectedBranch release
+```
+
+### Security boundary
+
+The hook and OpenCode Bash matchers are defense in depth, not a security sandbox. A process with arbitrary local command execution may be able to alter environment variables, Git configuration, hooks, or invoke remote protocols outside ordinary `git push`. Keep server-side protected branches and repository permissions as the authoritative control. A future integration can strengthen mode provenance with signed, session-scoped policy data, but cannot replace remote authorization.
+
+## Response topology
+
+The `herdr_agent_response` OpenCode tool retrieves completed responses from Herdr-managed OpenCode workers without reading terminal scrollback or creating response files. Only `shepherd`, `shepherd-governor`, and `sheepdog` may call it, with a second role allowlist check inside the tool, and only for settled Herdr targets with a trusted `herdr:opencode` session mapping and an approved role. Each caller may retrieve only from its own workers: `shepherd` from `grazer`; `shepherd-governor` from `grazer` and `sheepdog`; `sheepdog` from `grazer`, `sheep`, `shearer-low`, and `shearer-medium`.
+
+Initial call:
+
+```json
+{
+  "target": "frontend_worker",
+  "maxBytes": 8192
+}
+```
+
+Continuation call:
+
+```json
+{
+  "cursor": "<opaque-signed-cursor>",
+  "maxBytes": 8192
+}
+```
+
+Successful page:
+
+```json
+{
+  "ok": true,
+  "target": "frontend_worker",
+  "sessionID": "ses_...",
+  "messageID": "msg_...",
+  "role": "sheep",
+  "finish": "stop",
+  "offset": 0,
+  "nextOffset": 8192,
+  "totalBytes": 24500,
+  "complete": false,
+  "cursor": "<opaque-signed-cursor>",
+  "text": "..."
+}
+```
+
+Shepherd-phase agents must continue until `complete` is true before acting on the response. Pages use UTF-8 byte offsets and never split a multibyte character.
+
+The tool:
+
+- resolves Herdr's tracked OpenCode session ID;
+- runs `opencode export <sessionID>` with an argv API rather than shell interpolation;
+- selects the latest completed final assistant message after the latest user prompt;
+- excludes intermediate tool-call steps, errors, ignored text, reasoning, and terminal rendering;
+- pins continuation reads to the original session, message, response digest, and offset;
+- HMAC-signs opaque cursors with a random per-plugin-process secret;
+- paginates on UTF-8-safe boundaries with a bounded tool-output budget;
+- supports concurrent shepherds without response files or shared mutable retrieval state.
+
+The export backend is intentional. Herdr starts each worker as a separate OpenCode process, so the shepherd plugin's SDK client may be tied to a different OpenCode server. `opencode export` reads the shared OpenCode session store across those process boundaries.
+
+Normal lifecycle failures return structured errors such as:
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "AGENT_NOT_SETTLED",
+    "message": "Herdr agent frontend_worker is working; wait for idle or done.",
+    "retryable": true
+  }
+}
+```
+
+Cursor continuations do not query Herdr again, so a worker may begin another turn or leave the live agent list after the initial page. The response remains pinned as long as the OpenCode session and message still exist and are unchanged. Cursors expire after six hours by default and do not survive a restart of the shepherd's OpenCode plugin process.
+
 ## Installation
 
 Install or update the plugin with the cross-platform npm CLI:
@@ -19,11 +235,11 @@ The installer:
 
 - locates the global OpenCode config directory;
 - installs an exact package version there;
-- interactively asks which models the shepherd, sheep worker, and shearer reviewer roles should use when run in a terminal;
+- interactively asks which models the shepherd, sheepdog, flock worker, and shearer reviewer roles should use when run in a terminal;
 - preserves existing JSONC comments, trailing commas, plugins, and tuple options;
 - adds the stable file URL required by current OpenCode npm plugin loading;
 - creates timestamped backups of changed config and npm manifest files;
-- validates `shepherd-build` through a short-lived OpenCode debug process;
+- validates every agent role through a short-lived OpenCode debug process;
 - never restarts or signals a running OpenCode process.
 
 The shared Git push policy remains opt-in:
@@ -43,7 +259,7 @@ npx -y opencode-herdr-orchestration@latest uninstall --with-hooks
 
 After installation or update, quit and restart OpenCode intentionally when ready. Existing processes keep their already-loaded configuration.
 
-`configure-agents` updates the same model choices after installation. Press Enter to keep the displayed value, or enter `-` to restore that role's package default. Model names must include their provider prefix, such as `anthropic/claude-sonnet-4-6`.
+`configure-agents` updates the same model choices after installation. Press Enter to keep the displayed value, or enter `-` to restore that role's package default. Model names must include their provider prefix, such as `anthropic/claude-sonnet-4-6`. The sheepdog and flock worker reasoning efforts accept the provider's variant names, such as `low`, `medium`, or `high`; leaving either unset uses the model's default reasoning behavior. Shepherd-phase agents always inherit the active model and its reasoning behavior, and shearer reasoning stays fixed at `low` and `medium`.
 
 ## Manual Installation
 
@@ -89,39 +305,25 @@ Confirm the installed agents:
 opencode agent list
 ```
 
-The expected package agents are `shepherd-plan`, `shepherd-build`, `sheep-plan`, `sheep-build`, `shearer-review-low`, and `shearer-review-medium`.
-
-### Migrating from standalone agent files
-
-Agent definitions are merged by agent name. A local file with the same name as a package agent overrides the corresponding package fields, including its prompt and permissions.
+The expected package agents are `shepherd`, `shepherd-governor`, `sheepdog`, `grazer`, `sheep`, `shearer-low`, and `shearer-medium`.
 
-Before switching completely, archive or remove standalone files named `sheep-plan.md`, `sheep-build.md`, `shepherd-plan.md`, or `shepherd-build.md` after any existing OpenCode processes that depend on them have ended. Older misspelled files such as `sheperd-plan.md` and `sheperd-build.md` do not override the correctly named package agents; they load as additional legacy agents until removed.
+## Breaking migration: remove stale agent files
 
-Do not remove agent files merely to affect an already-running process. Complete or stop that process first, update the files, then start a new OpenCode process and verify the effective agent list.
+**Before updating to the current package, remove stale standalone agent files from the previous architecture.** Agent definitions are merged by agent name, so a leftover local file with a colliding name silently overrides the corresponding package fields, including its prompt and permissions.
 
-## Architecture
+Archive or remove these standalone files after any existing OpenCode processes that depend on them have ended:
 
-```text
-shepherd-plan
-└── sheep-plan
-
-shepherd-build
-├── sheep-plan
-├── sheep-build
-├── shearer-review-low
-└── shearer-review-medium
-```
+- `shepherd-plan.md`
+- `shepherd-build.md`
+- `sheep-plan.md`
+- `sheep-build.md`
+- `shearer-review-low.md`
+- `shearer-review-medium.md`
+- Older misspelled files such as `sheperd-plan.md` and `sheperd-build.md`, which load as additional legacy agents until removed.
 
-| Agent | Direct mutation | Delegation | Git authority | Model |
-| --- | --- | --- | --- | --- |
-| `shepherd-plan` | Markdown planning artifacts | `sheep-plan` only | Markdown commits; current non-protected branch push | Active strong model |
-| `shepherd-build` | Markdown handoffs/review notes | All four leaf roles | Integration, push, PR, merge, delivery | Active strong model |
-| `sheep-plan` | None | None | Read-only inspection | `litellm/glm-5.3-flash` |
-| `sheep-build` | Assigned implementation | None | Local task commit only | `litellm/glm-5.3-flash` |
-| `shearer-review-low` | None | None | Read-only inspection | GPT-5.6 Terra, low |
-| `shearer-review-medium` | None | None | Read-only inspection | GPT-5.6 Terra, medium |
+Do not remove agent files merely to affect an already-running process. Complete or stop that process first, update the files, then start a new OpenCode process and verify the effective agent list with `opencode agent list`.
 
-The build shepherd chooses low review for localized mechanical changes with strong deterministic coverage. It chooses medium review for security, architecture, migrations, public APIs, deployment, concurrency, cross-component work, weak coverage, or material uncertainty.
+Local agent definitions with the same names are merged over plugin defaults. This permits deliberate user customization without losing unspecified plugin permissions or prompts — but only if the local file is intentionally maintained, not a stale leftover.
 
 ## Plugin configuration
 
@@ -140,6 +342,7 @@ For the published package, use:
 
 ```jsonc
 {
+  "$schema": "https://opencode.ai/config.json",
   "plugin": ["opencode-herdr-orchestration"]
 }
 ```
@@ -153,7 +356,10 @@ Plugin tuple options can override model defaults:
       "opencode-herdr-orchestration",
       {
         "shepherdModel": "anthropic/claude-sonnet-4-6",
+        "sheepdogModel": "litellm/glm-5.3-flash",
+        "sheepdogVariant": "medium",
         "workerModel": "litellm/glm-5.3-flash",
+        "workerVariant": "medium",
         "reviewerModel": "litellm-responses/gpt-5.6-terra"
       }
     ]
@@ -161,7 +367,9 @@ Plugin tuple options can override model defaults:
 }
 ```
 
-Machine-specific `shepherd-build` permissions and instructions can also be added declaratively without a local JavaScript wrapper:
+The sheepdog has its own model and reasoning effort options, separate from the sheep workers it supervises.
+
+Machine-specific governance permissions and instructions can also be added declaratively without a local JavaScript wrapper:
 
 ```jsonc
 {
@@ -169,21 +377,19 @@ Machine-specific `shepherd-build` permissions and instructions can also be added
     [
       "opencode-herdr-orchestration",
       {
-        "shepherdBuildPermissions": {
+        "shepherdPermissions": {
           "private_deployment_status": "allow"
         },
-        "shepherdBuildPromptAppend": "Use private deployment tools according to local policy."
+        "shepherdPromptAppend": "Use private deployment tools according to local policy."
       }
     ]
   ]
 }
 ```
 
-`shepherdBuildPermissions` is merged over the package's `shepherd-build` permissions. `shepherdBuildPromptAppend` is appended as a separate final paragraph. Keep secrets out of plugin options because configuration may be displayed by diagnostics.
-
-Local agent definitions with the same names are merged over plugin defaults. This permits deliberate user customization without losing unspecified plugin permissions or prompts.
+`shepherdPermissions` is merged over the planning `shepherd` agent's permissions. `shepherdPromptAppend` is appended as a separate final paragraph to the `shepherd` agent's prompt. Keep secrets out of plugin options because configuration may be displayed by diagnostics.
 
-Machine- or organization-specific MCP tools, deployment rules, and private service instructions should stay in a local `shepherd-build` override rather than this public package. Add only the private permissions and prompt additions required by your environment; unspecified package defaults remain intact through deep merging.
+Machine- or organization-specific MCP tools, deployment rules, and private service instructions should stay in a local governance-agent override rather than this public package. Add only the private permissions and prompt additions required by your environment; unspecified package defaults remain intact through deep merging.
 
 OpenCode loads plugins and agent definitions at startup. Restart OpenCode when intentionally enabling or updating the plugin. The installer never stops or restarts an OpenCode process.
 
@@ -225,137 +431,12 @@ node .\bin\orchestration.js status
 node .\bin\orchestration.js uninstall-hooks
 ```
 
-Add repository-specific protected branches:
-
-```bash
-git config --add orchestration.protectedBranch production
-git config --add orchestration.protectedBranch release
-```
-
-`main` and `master` are always protected in planning mode.
-
-## Push policy
-
-The plugin tracks the selected agent per OpenCode session and injects `SHEPHERD_MODE` into that session's shell environment.
-
-| Mode | Hook behavior |
-| --- | --- |
-| `plan` | Allows only the attached current branch to the same non-protected remote branch |
-| `build` | Does not add planning restrictions; shepherd-build owns delivery |
-| `sheep-plan` | Denies every push |
-| `sheep-build` | Denies every push |
-| `review` | Denies every push |
-| Missing/unknown | Does not interfere with normal human Git use |
-
-The hook rejects detached-HEAD planning pushes, protected branches, ref renames, unrelated refs, and deletions.
-
-### Security boundary
-
-The hook and OpenCode Bash matchers are defense in depth, not a security sandbox. A process with arbitrary local command execution may be able to alter environment variables, Git configuration, hooks, or invoke remote protocols outside ordinary `git push`. Keep server-side protected branches and repository permissions as the authoritative control. A future integration can strengthen mode provenance with signed, session-scoped policy data, but cannot replace remote authorization.
-
-## Planning handoff
-
-Final plans include:
-
-```text
-Plan-ID: <topic>-<YYYYMMDD>-<sequence>
-Base-Commit: <full commit hash>
-Status: PROPOSED
-```
-
-Switching the session to `shepherd-build` approves that plan. Build startup reports the plan ID, approved base, and current HEAD, then inspects divergence before delegation.
-
-Implementation contracts include the objective, ownership and forbidden paths, dependencies, acceptance criteria, verification, escalation conditions, and required deliverables. `sheep-build` hands a verified local commit upward. `shepherd-build` runs deterministic checks before requesting semantic review.
-
-Reviewer verdicts are:
-
-- `PASS`: integrate after shepherd checks.
-- `REWORK`: return actionable findings to the responsible sheep and review the correction.
-- `ESCALATE`: research, re-plan, or request user judgment.
-
-Two failed semantic review cycles escalate instead of looping indefinitely.
-
 ## Worker interruption
 
-Herdr currently exposes `send-keys`, not a narrower agent interrupt command. Shepherds retain it to send Ctrl+C only after confirming that a worker is genuinely stuck. Prompts prohibit using worker terminals to type implementation commands or bypass shepherd permissions.
+Herdr currently exposes `send-keys`, not a narrower agent interrupt command. Shepherd-phase agents retain it to send Ctrl+C only after confirming that a worker is genuinely stuck. Prompts prohibit using worker terminals to type implementation commands or bypass shepherd permissions.
 
 This restriction is not hard-enforced by Herdr. A native `herdr agent interrupt <target>` command would close that capability gap.
 
-## Worker response retrieval
-
-The `herdr_agent_response` OpenCode tool retrieves completed responses from Herdr-managed OpenCode workers without reading terminal scrollback or creating response files.
-
-Initial call:
-
-```json
-{
-  "target": "frontend_worker",
-  "maxBytes": 8192
-}
-```
-
-Continuation call:
-
-```json
-{
-  "cursor": "<opaque-signed-cursor>",
-  "maxBytes": 8192
-}
-```
-
-Successful page:
-
-```json
-{
-  "ok": true,
-  "target": "frontend_worker",
-  "sessionID": "ses_...",
-  "messageID": "msg_...",
-  "role": "sheep-build",
-  "finish": "stop",
-  "offset": 0,
-  "nextOffset": 8192,
-  "totalBytes": 24500,
-  "complete": false,
-  "cursor": "<opaque-signed-cursor>",
-  "text": "..."
-}
-```
-
-Shepherds must continue until `complete` is true before acting on the response. Pages use UTF-8 byte offsets and never split a multibyte character.
-
-The tool:
-
-- resolves Herdr's tracked OpenCode session ID;
-- runs `opencode export <sessionID>` with an argv API rather than shell interpolation;
-- selects the latest completed final assistant message after the latest user prompt;
-- excludes intermediate tool-call steps, errors, ignored text, reasoning, and terminal rendering;
-- pins continuation reads to the original session, message, response digest, and offset;
-- HMAC-signs opaque cursors with a random per-plugin-process secret;
-- paginates on UTF-8-safe boundaries with a bounded tool-output budget;
-- supports concurrent shepherds without response files or shared mutable retrieval state;
-- allows only `shepherd-plan` and `shepherd-build`, with a second authorization check inside the tool;
-- accepts only settled Herdr targets with a trusted `herdr:opencode` session mapping and an approved leaf role.
-
-The export backend is intentional. Herdr starts each worker as a separate OpenCode process, so the shepherd plugin's SDK client may be tied to a different OpenCode server. `opencode export` reads the shared OpenCode session store across those process boundaries.
-
-Normal lifecycle failures return structured errors such as:
-
-```json
-{
-  "ok": false,
-  "error": {
-    "code": "AGENT_NOT_SETTLED",
-    "message": "Herdr agent frontend_worker is working; wait for idle or done.",
-    "retryable": true
-  }
-}
-```
-
-Cursor continuations do not query Herdr again, so a worker may begin another turn or leave the live agent list after the initial page. The response remains pinned as long as the OpenCode session and message still exist and are unchanged. Cursors expire after six hours by default and do not survive a restart of the shepherd's OpenCode plugin process.
-
-The previous file helper may remain for already-running OpenCode sessions. Once those processes end and this plugin is active, it is no longer needed by new sessions.
-
 ## Development
 
 ```bash
@@ -363,7 +444,7 @@ npm run check
 npm test
 ```
 
-Tests cover topology, model variants, permissions, override merging, session mode isolation, response selection, signed cursors, UTF-8 pagination, concurrent response reads, tool authorization, and Git hook behavior on protected, worker, review, build, and planning pushes.
+Tests cover topology, model variants, permissions, override merging, session mode isolation, response selection, signed cursors, UTF-8 pagination, concurrent response reads, tool authorization, orchestration state storage and access, and Git hook behavior on protected, worker, review, governance, and planning pushes.
 
 ## Releases
 
@@ -393,6 +474,6 @@ For stronger release control, configure required reviewers on the `npm` environm
 - OpenCode command patterns cannot prove semantic Git intent; the hook adds checks but server-side protection is still required.
 - `herdr agent send-keys` is broader than interrupt-only authority.
 - Global `core.hooksPath` is singular. Existing hook frameworks must be composed rather than overwritten.
-- PR commands are narrowly available to `shepherd-build`, but work only in GitHub repositories with an authenticated `gh` installation.
+- PR commands are narrowly available to the governance phase, but work only in GitHub repositories with an authenticated `gh` installation.
 - Agent registration and environment hooks take effect only in newly started OpenCode processes.
 - Worker session exports are capped at 64 MiB by default to bound host memory use. The response tool returns `SESSION_EXPORT_TOO_LARGE` rather than loading a larger session.

package/bin/orchestration.js

@@ -14,10 +14,13 @@ import {
   PACKAGE_NAME,
   packageVersion,
   orchestrationOptions,
+  reconcileAgentFiles,
+  removeAgentFilesManifest,
   restoreBackup,
   status as installationStatus,
   uninstallPackage,
   validateOpenCode,
+  writeAgentFilesManifest,
   writePluginConfig,
 } from "../src/installer.js";
 
@@ -28,9 +31,12 @@ const installedHook = join(hooksPath, "pre-push");
 const [command, ...flags] = process.argv.slice(2);
 
 const MODEL_ROLES = [
-  ["shepherdModel", "Shepherd agents", "OpenCode active model"],
-  ["workerModel", "Sheep worker agents", "litellm/glm-5.3-flash"],
-  ["reviewerModel", "Shearer review agents", "litellm-responses/gpt-5.6-terra"],
+  ["shepherdModel", "Shepherd agents", "OpenCode active model", "model"],
+  ["sheepdogModel", "Sheepdog agents", "litellm/glm-5.3-flash", "model"],
+  ["sheepdogVariant", "Sheepdog reasoning effort", "model default", "variant"],
+  ["workerModel", "Sheep worker agents", "litellm/glm-5.3-flash", "model"],
+  ["workerVariant", "Sheep worker reasoning effort", "model default", "variant"],
+  ["reviewerModel", "Shearer review agents", "litellm-responses/gpt-5.6-terra", "model"],
 ];
 
 function git(args, options = {}) {
@@ -82,11 +88,13 @@ async function promptForModels(configDir) {
   const prompt = createInterface({ input: process.stdin, output: process.stdout });
   process.stdout.write("Configure agent models. Press Enter to keep the shown value; enter - to restore the package default.\n");
   try {
-    for (const [key, label, packageDefault] of MODEL_ROLES) {
+    for (const [key, label, packageDefault, kind] of MODEL_ROLES) {
       const shown = existing[key] || packageDefault;
       const answer = (await prompt.question(`${label} [${shown}]: `)).trim();
       const value = answer === "-" ? "" : (answer || existing[key] || "");
-      if (value && !value.includes("/")) throw new Error(`${label} model must include a provider prefix, for example provider/model.`);
+      if (value && kind === "model" && !value.includes("/")) {
+        throw new Error(`${label} model must include a provider prefix, for example provider/model.`);
+      }
       answers[key] = value;
     }
   } finally {
@@ -95,6 +103,15 @@ async function promptForModels(configDir) {
   return answers;
 }
 
+function reportReconciliation(reconciliation) {
+  for (const relPath of reconciliation.deleted) {
+    process.stdout.write(`Removed obsolete package-owned agent file: ${relPath}\n`);
+  }
+  for (const item of reconciliation.remediation) {
+    process.stdout.write(`Action required (${item.reason}): ${item.remediation}\n`);
+  }
+}
+
 async function installOrUpdate(useLatest) {
   const configDir = configDirectory();
   const models = command === "install" && process.stdin.isTTY && process.stdout.isTTY
@@ -109,8 +126,11 @@ async function installOrUpdate(useLatest) {
     restoreBackup(result.file, result.backup, result.existed);
     throw new Error(`OpenCode validation failed; restored the previous config. ${error.message}`);
   }
+  const reconciliation = reconcileAgentFiles(configDir, { remove: false });
+  writeAgentFilesManifest(configDir, reconciliation.manifestEntries, version);
   if (flags.includes("--with-hooks")) installHooks();
   process.stdout.write(`Configured ${PACKAGE_NAME}@${version} in ${result.file}\n`);
+  reportReconciliation(reconciliation);
   if (result.backup) process.stdout.write(`Backup: ${result.backup}\n`);
   for (const backup of packageBackups) process.stdout.write(`Backup: ${backup}\n`);
   process.stdout.write("Restart OpenCode intentionally to load the new configuration.\n");
@@ -138,8 +158,14 @@ function uninstallOrchestration() {
   const configDir = configDirectory();
   const result = writePluginConfig(configDir, true);
   const packageBackups = uninstallPackage(configDir);
+  const reconciliation = reconcileAgentFiles(configDir, { remove: true });
+  removeAgentFilesManifest(configDir);
   if (flags.includes("--with-hooks")) uninstallHooks();
   process.stdout.write(`Removed orchestration plugin configuration from ${result.file}\n`);
+  for (const relPath of reconciliation.deleted) {
+    process.stdout.write(`Removed package-owned agent file: ${relPath}\n`);
+  }
+  reportReconciliation(reconciliation);
   if (result.backup) process.stdout.write(`Backup: ${result.backup}\n`);
   for (const backup of packageBackups) process.stdout.write(`Backup: ${backup}\n`);
 }