@sjawhar/opencode-legion-envoy 1.7.0 → 1.9.0

package/dist/src/server.js

@@ -14706,6 +14706,9 @@ class DispatchClient {
   async docRead(id, version) {
     return version === undefined ? this.#json("GET", ["api", "v1", "artifacts", id, "text"]) : this.#json("GET", ["api", "v1", "artifacts", id, "versions", String(version)]);
   }
+  async artifactBlocks(id) {
+    return this.#json("GET", ["api", "v1", "artifacts", id, "blocks"]);
+  }
   async docEdit(id, input) {
     return this.#json("POST", ["api", "v1", "artifacts", id, "edits"], input);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/opencode-legion-envoy",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "type": "module",
   "main": "dist/src/server.js",
   "exports": {

package/skills/AGENTS.md

@@ -8,9 +8,8 @@ event intake, process lifecycle, credentials, and role delivery.
 
 ```
 skills/
-├── dispatch/            # Raising a durable human question as a GitHub-issue thread
-├── github/              # GitHub issue and pull-request operations
-├── linear/              # Linear adapter instructions
+├── dispatch/            # Writing specs, asks, comments, and artifacts on native Dispatch
+├── envoy/               # Envoy subscriptions, agent-to-agent messages, and topic formats
 ├── legion-architect/    # Tree ownership, decomposition, gates, and scheduling
 ├── legion-controller/   # Derived-verdict control-plane operation
 ├── legion-oracle/       # Repository-grounded research
@@ -27,9 +26,10 @@ returns that schema to the architect. It writes the same phase-specific payload
 The committed predecessor handoff wins after revival or re-creation.
 
 Workers do not run a controller loop or mutate lifecycle labels. Workers coordinate
-lifecycle, scope, and cross-phase decisions with the owning architect through hub, sending
-the verified observation and decision needed. A worker may use the `dispatch` MCP tool
-directly for a durable human question; replies come back to the worker's own session.
+lifecycle, scope, and cross-phase decisions with the owning architect by `envoy_publish` to its
+role topic, sending the verified observation and decision needed (`hub` reaches only subagents
+inside the worker's own process). A worker may call the native `dispatch_*` tools directly for a
+durable human question; replies come back to the worker's own session.
 
 ## Durable artifacts
 

package/skills/dispatch/SKILL.md

@@ -222,6 +222,20 @@ and deleting a cell's quoted text removes only that text.
 Use `replace` for inline continuation. Use zero-based `occurrence` for a repeated target; re-read a missing or ambiguous target before
 retrying. Pass `summary` to name the version when recording a decision.
 
+## Typed blocks
+
+The server declares typed document blocks at `GET /api/v1/schema/blocks`. Write one only with the
+container-directive form `:::name{#block-id key="value"}` on its own line, ordinary block children,
+and a closing `:::` at the same nesting. An unclosed typed block at document level is rejected. For
+a new typed block, omit `#block-id`; Dispatch mints it. When editing an existing typed block, retain
+its id and every rendered attribute.
+
+Use only the type names, content rule, attributes, and enum values returned by the schema. Values are
+quoted: `:::callout{kind="warning" title="Risk"}`. Do not write Pandoc-style `::: {.callout}`, leaf
+`::name` directives, or text `:name` directives; those strings are literal when quoted inside a code
+block. Do not set attributes the schema marks `server: true`; the server ignores them and reasserts
+its authoritative value at settlement.
+
 ## Comments and suggestions
 
 Add feedback with:

package/skills/legion-architect/SKILL.md

@@ -10,11 +10,6 @@ with human-created children; either way you own its complete outcome. Work from
 wakes and current artifacts. Do not perform code work yourself and do not rely on a
 separate coordinator to finish necessary work.
 
-This skill documents the target Dispatch-native contract. The `legion` tool's
-`register_gate`/`release_wave`/`set_status` ops, the Dispatch key format, and the
-`dispatch_*` tool family land with PR B (#TBD); until that PR merges, this skill's contract
-is not yet runnable on `main`.
-
 ## Tool and ownership boundaries
 
 - Use the `legion` tool for lifecycle writes. Its issue key is the Dispatch key
@@ -105,9 +100,10 @@ idea what the fuck you're talking about."
 Then park. Do not release a wave or spawn a Legion role until a later delivered wake
 shows `design-approved` on the root. On a deployment whose design gate is off
 (`gates.design: off` in its `legion.yaml`), the daemon satisfies the gate as you register it
-and `design-approved` arrives immediately — proceed; the ask remains open on Dispatch as the
-record and needs no answer. Approval covers the entire tree: later waves, re-scopes, and
-integration-failure children do not repeat this sequence.
+and `design-approved` arrives immediately — proceed. The daemon then closes the ask on Dispatch
+(you will see `ask.resolved` for it); that is expected and needs nothing from you. Approval
+covers the entire tree: later waves, re-scopes, and integration-failure children do not repeat
+this sequence.
 
 ## 2. Children in flight
 

package/skills/legion-controller/SKILL.md

@@ -9,10 +9,6 @@ The controller is the one persistent, wake-driven session for a Legion project.
 triage, escalation, and human-interaction judgments; it never does phase-worker work or
 routes raw events into an architect.
 
-This skill documents the target Dispatch-native contract. The `legion` tool's `set_status`
-op, `dispatch_read`/`dispatch_issue`, and the Dispatch key format land with PR B (#TBD);
-until that PR merges, this skill's contract is not yet runnable on `main`.
-
 ## Start and claim the controller role
 
 The Legion extension claims `legion-<project>-controller` and registers controller readiness

package/skills/legion-oracle/SKILL.md

@@ -36,14 +36,18 @@ digraph oracle_decision {
 
 ## Research Strategy
 
-Run steps 1-2 first (parallel OK), then 3-4 if needed:
+If the deployment instructions name a librarian role, ask it first (publish to its
+`notifications.role.<name>` topic with `expects_reply: required`). Then run steps 1-2 (parallel
+OK), and 3-4 if needed, with tools a Legion pane actually has: `read`, `grep`, `web_search`, and
+`task(agent="scout")` (fast read-only codebase search) or `task(agent="oracle")` (deeper
+read-only analysis when the answer needs judgment across many files). Do not name any other agent.
 
 | Step | Tool | Query |
 |------|------|-------|
-| 1. Institutional learnings | `Task learnings-researcher` | Search docs/solutions/ for [question] |
-| 2. Codebase patterns | `Task Explore` | Find how src/ handles [topic] |
-| 3. Framework docs | Context7 MCP | resolve-library-id → query-docs |
-| 4. External practices | `Task best-practices-researcher` or `WebSearch` | Current best practices for [topic] |
+| 1. Institutional learnings | `grep` then `read` over `docs/solutions/` (front-matter `tags`, then the body) | [question]'s keywords |
+| 2. Codebase patterns | `task(agent="scout")`; `task(agent="oracle")` when judgment across many files is needed | Find how [module] handles [topic] |
+| 3. Framework docs | `read` the library's documentation URL | [library] [topic] |
+| 4. External practices | `web_search`, then `read` the primary source | Current best practices for [topic] |
 
 ## Output
 
@@ -54,10 +58,11 @@ Run steps 1-2 first (parallel OK), then 3-4 if needed:
 ## Example
 
 ```
-/legion-oracle How should I handle GraphQL pagination?
+Question: How should I paginate a GraphQL connection?
 
-[learnings-researcher] → No matches
-[Explore] → Found src/legion/state/fetch.py uses cursor-based pagination
+grep pagination docs/solutions/   → no matches
+task(agent="scout")               → packages/daemon/src/state/fetch.ts loops on
+                                    pageInfo.hasNextPage / endCursor (contextsPage)
 
-Answer: Use cursor-based pagination per src/legion/state/fetch.py:42
+Answer: cursor-based, per the `while (page.hasNextPage)` loop in packages/daemon/src/state/fetch.ts
 ```

package/skills/legion-worker/SKILL.md

@@ -11,10 +11,6 @@ phase gets its own long-lived process against the same jj workspace, run in turn
 the phase assigned to you, report its completion to the architect, and leave the durable
 copy the next phase can trust.
 
-This skill documents the target Dispatch-native contract. `LEGION_ISSUE` as a Dispatch key,
-the `dispatch_ask` tool, and the `Dispatch: <KEY>` PR-body linkage land with PR B (#TBD);
-until that PR merges, this skill's contract is not yet runnable on `main`.
-
 ## Identity, scope, and role
 
 The daemon spawns you as a separate `omp --mode rpc` process (behind `legion worker-shim`,
@@ -95,12 +91,15 @@ committed predecessor handoffs in lifecycle order from `$LEGION_WORKSPACE/.legio
 4. `test.json`
 5. `review.json`
 
-Read only files that precede the assigned phase. There is no handoff schema (rejected
-design — no schema validation runs anywhere in this pipeline): write the phase-specific
-fields the next phase and the architect need, consistent with what predecessor phases
-already wrote. The durable copy lives in `$LEGION_WORKSPACE/.legion/<phase>.json`. If a
-committed handoff conflicts with memory or a prior transcript, the committed file wins: it
-is the copy that survived.
+Read only files that precede the assigned phase. Every handoff is validated when it is read:
+`validatePhaseHandoff` (`packages/contracts/src/handoff-schema.ts`) checks the file, and the
+ledger (`packages/daemon/src/handoff/ledger.ts`) treats a file that fails validation as missing.
+Undeclared fields pass validation untouched and reach the next worker; a declared field of the
+wrong type fails the whole file, so `legion handoff read` returns null for that phase.
+Write the phase-specific fields the next phase and the architect need, consistent with what
+predecessor phases already wrote. The durable copy lives in
+`$LEGION_WORKSPACE/.legion/<phase>.json`. If a committed handoff conflicts with memory or a prior
+transcript, the committed file wins: it is the copy that survived.
 
 ## jj Safety Rules
 
@@ -138,6 +137,14 @@ capability it needs; invoke GitHub through the credential helper:
 legion gh -- <gh args…>
 ```
 
+Three facts about `gh` in a worker pane. The `gh` on your `PATH` is a shim
+(`packages/pi-envoy/src/legion/gh-shim.ts`) that execs `legion gh -- "$@"`, so `gh …` and
+`legion gh -- …` are the same call, and each call redeems a fresh token from your session's
+grant — identity is supplied per call, never stored. Never run `gh auth login` or
+`gh auth setup-git`; there is no login state to create. The shim refuses `pr merge` (and a raw
+`gh api …/merge`): no worker role merges a pull request — the merge queue does, under its own
+authority.
+
 ## GitHub PR comment attribution
 
 Append this exact structured footer to **every** pull-request comment and review that this
@@ -158,6 +165,15 @@ legion gh -- pr comment <pr-number> \
   --repo <owner>/<repo>
 ```
 
+## Planner artifact
+
+The plan lives in `.legion/plan.json` and the Dispatch issue document; never commit a plan or spec file to the repository.
+No `docs/plans/*`, `docs/superpowers/plans/*`, or spec markdown goes into the pull request: plan
+and spec content goes into the issue, never into a PR (the root `AGENTS.md`'s `docs/plans/` row
+is human-authored design history, not a Legion artifact). A skill step that says "save the plan
+to a file" is satisfied by the handoff write in the completion gate below; the planner's only
+commit is `plan: record handoff`.
+
 ## Implementer push and pull request
 
 Only the implementer creates the issue bookmark, pushes it, and opens the pull request.
@@ -212,17 +228,36 @@ Negative control: <deliberately broken input> → <refusal or failure observed>.
   changes behavior, hides an error, or breaks a gate is fixed here — never deferred.
   Findings about naming, duplication, or wording are batched into the single `Fast-follow`
   line instead of iterating per push.
+- **Rebase only on a real conflict.** Sami, 2026-09-11, verbatim:
+  "Please don't do unnecessary rebases (i.e. unless there are merge conflicts). The CI queue is too long and slow."
+  The implementer rebases the issue branch only when GitHub reports it `CONFLICTING` or the
+  controller asks because of a conflict — never to pick up `main` or to refresh CI. A single
+  failed CI job is re-run on its own with `legion gh -- run rerun <run-id> --failed`, never by
+  pushing a new commit.
+- **No deferrals.** Sami, 2026-09-11, verbatim: "My rule is no deferrals." The `Fast-follow:`
+  field names naming, duplication, or wording cleanup only; anything that changes behaviour,
+  hides an error, or breaks a gate lands in this PR.
 - The tester fills in the `E2E` section: the real surface a user reaches the criterion
   through, the exact command or run id, what was observed, the head SHA, and one negative
   control — a deliberately broken input and the refusal or failure it produced. A unit or
-  integration test is a regression lock, never proof of a criterion.
+  integration test is a regression lock, never proof of a criterion. Environment or
+  secret-scrub evidence (e.g. "`LEGION_*`/`DISPATCH_*`/`ENVOY_*` unset") is recorded once, in
+  `.legion/test.json`, and only when the issue's acceptance criteria call for it — never
+  re-pasted into the PR body each round.
 - The reviewer verifies the `CI`, `Threads`, and `E2E` facts against GitHub directly —
   never from a handoff — then runs `task(agent="thermonuclear-deep-review")` and
   `task(agent="thermonuclear-code-quality")` once at that head and records the verdict.
-  Skip the `Thermo` line entirely on a docs-only PR. Post every correctness finding as a
-  PR review comment and return the issue to the architect; when clean, have the architect send
-  the implementer back to push the `.legion/` deletion (the review App cannot push), then
-  review **that** head and approve it by name.
+  Skip the `Thermo` line entirely on a docs-only PR. Submit **one review per round** —
+  `REQUEST_CHANGES` when any correctness finding stands, otherwise `COMMENT` while the head
+  still carries `.legion/`; `APPROVE` only for the head that differs from the reviewed one by
+  the `.legion/` deletion alone, named by SHA — carrying every inline comment in that single
+  call: `legion gh -- api --method POST repos/{owner}/{repo}/pulls/{number}/reviews --input body.json`
+  with `commit_id`, `event` (`REQUEST_CHANGES`, `COMMENT`, or `APPROVE`), `body` (with the
+  Legion footer), and a `comments[]` array of `{path, line, side, body}`, one entry per
+  finding — never one `pr review` call per finding (each submission fires a `pr-review` wake).
+  Then return the issue to the architect; when clean, have the architect send the implementer
+  back to push the `.legion/` deletion (the review App cannot push), then review **that** head
+  and approve it by name.
 - Once a base is frozen for others to stack on, never rewrite it — fixes land as new
   commits on top, and the `Chain` line records what is frozen.
 - The merger confirms the approved head still equals the current head, then publishes

package/skills/github/SKILL.md

@@ -1,208 +0,0 @@
----
-name: github
-description: Manage GitHub issues via Projects V2. Use when LEGION_ISSUE_BACKEND=github.
----
-
-# GitHub (gh CLI)
-
-Direct CLI operations via `gh`. No embedded MCP — all commands are shell invocations.
-
-## Setup
-
-Requires `gh` CLI installed and authenticated:
-```bash
-gh auth login
-```
-
-**Inside a Legion worker workspace**, skip `gh auth login`/`gh auth setup-git`: `gh` on `PATH`
-is a shim that execs `legion gh -- <args>` (`packages/pi-envoy/src/legion/gh-shim.ts`), which
-redeems a fresh token from the daemon's grant on every invocation and hands it straight to the
-real `gh` binary — it is already authenticated per call, independent of any local login state.
-
-## Operations
-
-### Search/List Issues (via project)
-
-List all items in a GitHub Project V2:
-
-```bash
-gh project item-list $PROJECT_NUM --owner $OWNER --format json
-```
-
-**Parameters:**
-- `$PROJECT_NUM`: Project number (from `LEGION_ID` format: `owner/project-number`)
-- `$OWNER`: Repository owner
-- `--format json`: Returns structured data for parsing
-
-**Example:**
-```bash
-gh project item-list 42 --owner acme --format json | jq '.items[] | {id, title, status}'
-```
-
-### Get Issue Details
-
-Fetch full issue metadata:
-
-```bash
-gh issue view $ISSUE_NUMBER --json title,body,labels,comments,state -R $OWNER/$REPO
-```
-
-**Parameters:**
-- `$ISSUE_NUMBER`: Issue number (e.g., `123`)
-- `-R $OWNER/$REPO`: Repository (required for multi-repo support)
-- `--json`: Fields to return (title, body, labels, comments, state, etc.)
-
-**Example:**
-```bash
-gh issue view 123 --json title,body,labels,state -R acme/backend
-```
-
-### Update Status (Projects V2 — GraphQL)
-
-Update issue status in a GitHub Project V2. Requires field and option IDs from project schema:
-
-```bash
-gh api graphql -f query='mutation {
-  updateProjectV2ItemFieldValue(input: {
-    projectId: "$PROJECT_ID"
-    itemId: "$ITEM_ID"
-    fieldId: "$STATUS_FIELD_ID"
-    value: { singleSelectOptionId: "$OPTION_ID" }
-  }) { projectV2Item { id } }
-}'
-```
-
-**Parameters:**
-- `$PROJECT_ID`: GraphQL ID of the project (not the number)
-- `$ITEM_ID`: GraphQL ID of the issue in the project
-- `$STATUS_FIELD_ID`: GraphQL ID of the Status field
-- `$OPTION_ID`: GraphQL ID of the status option (e.g., "In Progress", "Done")
-
-**Note:** Field and option IDs must be resolved from the project schema. The controller caches these after first query.
-
-**Resolve IDs (one-time):**
-```bash
-gh api graphql -f query='query {
-  repository(owner: "$OWNER", name: "$REPO") {
-    projectV2(number: $PROJECT_NUM) {
-      fields(first: 20) {
-        nodes {
-          ... on ProjectV2SingleSelectField {
-            id
-            name
-            options { id name }
-          }
-        }
-      }
-    }
-  }
-}'
-```
-
-### Add Label
-
-Add a label to an issue (additive — does not remove existing labels):
-
-```bash
-gh issue edit $ISSUE_NUMBER --add-label "bug" -R $OWNER/$REPO
-```
-
-**Parameters:**
-- `$ISSUE_NUMBER`: Issue number
-- `--add-label`: Label to add (can be used multiple times)
-- `-R $OWNER/$REPO`: Repository
-
-**Example:**
-```bash
-gh issue edit 123 --add-label "bug" -R acme/backend
-```
-
-### Remove Label
-
-Remove a label from an issue:
-
-```bash
-gh issue edit $ISSUE_NUMBER --remove-label "wontfix" -R $OWNER/$REPO
-```
-
-**Parameters:**
-- `$ISSUE_NUMBER`: Issue number
-- `--remove-label`: Label to remove (can be used multiple times)
-- `-R $OWNER/$REPO`: Repository
-
-**Example:**
-```bash
-gh issue edit 123 --remove-label "wontfix" -R acme/backend
-```
-
-### Comment on Issue
-
-Add a comment to an issue:
-
-```bash
-gh issue comment $ISSUE_NUMBER --body "Fixed in commit abc123" -R $OWNER/$REPO
-```
-
-**Parameters:**
-- `$ISSUE_NUMBER`: Issue number
-- `--body`: Comment text (supports Markdown)
-- `-R $OWNER/$REPO`: Repository
-
-**Example:**
-```bash
-gh issue comment 123 --body "Implemented in PR #456" -R acme/backend
-```
-
-### Create Issue
-
-Create a new issue:
-
-```bash
-gh issue create --title "Bug: Login fails" --body "Details" -R $OWNER/$REPO
-```
-
-**Parameters:**
-- `--title`: Issue title (required)
-- `--body`: Issue description (optional, supports Markdown)
-- `-R $OWNER/$REPO`: Repository
-
-**Example:**
-```bash
-gh issue create --title "Feature: Add dark mode" --body "User request from #789" -R acme/backend
-```
-
-## Key Differences from Linear
-
-| Aspect | Linear | GitHub |
-|--------|--------|--------|
-| **Labels** | Replace all (read-modify-write) | Additive (`--add-label`, `--remove-label`) |
-| **Status** | Direct field update | Projects V2 GraphQL mutation |
-| **PR Association** | Attachment field | Native (issue ↔ PR link) |
-| **API** | MCP tool dispatch | Direct `gh` CLI |
-| **Multi-repo** | Single team | `-R owner/repo` per command |
-
-## Important Notes
-
-- **Always specify `-R $OWNER/$REPO`** for multi-repo project support
-- **Labels are additive**: Use `--add-label` and `--remove-label` separately (unlike Linear which replaces all)
-- **Status updates require Projects V2 GraphQL** — not just issue labels
-- **PR association is automatic** — GitHub links issues and PRs natively
-- **`$OWNER` and `$REPO` come from `LEGION_ID`** (format: `owner/project-number`)
-- **Field/option IDs must be cached** by the controller after first resolution
-
-## Error Handling
-
-Common errors and solutions:
-
-| Error | Cause | Solution |
-|-------|-------|----------|
-| `Could not resolve to a Repository` | Wrong `-R` format | Use `-R owner/repo` (not `owner-repo`) |
-| `Could not resolve to an Issue` | Issue doesn't exist | Verify issue number is correct |
-| `GraphQL error: Field not found` | Wrong field ID | Re-resolve field IDs from project schema |
-| `Not authenticated` | `gh` not logged in | Run `gh auth login` |
-
-## Reference
-
-- **Project number**: Visible in GitHub UI (e.g., `https://github.com/orgs/acme/projects/42` → `42`)
-- **Issue number**: Visible in URL (e.g., `https://github.com/acme/backend/issues/123` → `123`)
-- **GraphQL IDs**: Base64-encoded, returned by GraphQL queries (not human-readable)

package/skills/linear/SKILL.md

@@ -1,76 +0,0 @@
----
-name: linear
-description: Manage Linear issues. Use when working with tasks, tickets, bugs, or Linear.
-mcp:
-  linear:
-    command: npx
-    args: ["-y", "github:obra/streamlinear"]
-    env:
-      LINEAR_API_TOKEN: ${LINEAR_API_TOKEN}
----
-
-# Linear (Stream Linear)
-
-Single-tool MCP with action dispatch. All operations go through `linear_linear`.
-
-## Actions
-
-### Search Issues
-
-```
-linear_linear(action="search")                          # Your active issues
-linear_linear(action="search", query="auth bug")        # Text search
-linear_linear(action="search", query={state: "In Progress"})  # Filter
-linear_linear(action="search", query={team: "ENG", assignee: "me"})
-```
-
-### Get Issue Details
-
-```
-linear_linear(action="get", id="ABC-123")               # By short ID
-linear_linear(action="get", id="https://linear.app/...")  # By URL
-```
-
-Returns: title, description, status, labels, comments, attachments.
-
-### Update Issue
-
-```
-linear_linear(action="update", id="ABC-123", state="Done")
-linear_linear(action="update", id="ABC-123", priority=1)
-linear_linear(action="update", id="ABC-123", assignee="me")
-linear_linear(action="update", id="ABC-123", labels=["bug", "existing-label"])
-```
-
-**Labels array replaces all labels.** Fetch current labels first, then append.
-
-### Comment on Issue
-
-```
-linear_linear(action="comment", id="ABC-123", body="Fixed in commit abc123")
-```
-
-### Create Issue
-
-```
-linear_linear(action="create", title="Bug: Login fails", team="ENG")
-linear_linear(action="create", title="Bug", team="ENG", body="Details", priority=2)
-```
-
-### Raw GraphQL
-
-```
-linear_linear(action="graphql", graphql="query { viewer { name } }")
-```
-
-### Help
-
-```
-linear_linear(action="help")
-```
-
-## Reference
-
-- Priority: 0=None, 1=Urgent, 2=High, 3=Medium, 4=Low
-- State matching is fuzzy: "done" → "Done", "in prog" → "In Progress"
-- IDs accept: `ABC-123`, Linear URLs, or UUIDs