@sjawhar/opencode-legion-envoy 3.15.1 → 3.16.1

package/dist/src/server.js

@@ -13559,6 +13559,8 @@ function serviceSubjectLabel(subject) {
   }
   return subject;
 }
+var MAX_ISSUE_PAGE_LIMIT = 250;
+var DEFAULT_ISSUE_PAGE_LIMIT = 50;
 var ASK_TURNS = ["human", "agent"];
 var DELIVERY_CAPABILITIES = ["aside", "btw", "steer"];
 var DELIVERY_DUPLICATE_WINDOW_MS = 72 * 60 * 60 * 1000;
@@ -14284,7 +14286,7 @@ var dispatchToolSpecs = [
   {
     name: "dispatch_issues",
     example: { project: "AGENTC", limit: 250, offset: 250 },
-    description: "List a project's issues for a roadmap or backlog pass: every issue in one project, each carrying " + "its status, priority, parent, labels, open-ask count, and route with whether it reaches anyone, " + "so you can see backlog shape without opening every issue. Optionally filter by status, parent, " + "label, priority, route status, or how recently it changed; priority takes one or more of 0-3 " + "(P0-P3) and null for an issue with no priority, so an owner's P0/P1 audit is priority [0, 1]. " + 'route_status "no_holder" lists every open issue whose route names a role nobody holds or a ' + "session that is not running at the moment of the read, whatever its priority. A restarting " + "session is absent for minutes, so an issue is unowned only when a read ten minutes later agrees. " + "Do not use it to search by keyword or phrase; dispatch_search remains the keyword surface. " + "Rows are paged after the server returns the full response: limit sets the page size (default 50, " + "max 250) and offset selects where it starts (default 0), so repeat with the next offset to " + "enumerate every matching issue.",
+    description: "List a project's issues for a roadmap or backlog pass: every issue in one project, each carrying " + "its status, priority, parent, labels, open-ask count, and route with whether it reaches anyone, " + "so you can see backlog shape without opening every issue. Optionally filter by status, parent, " + "label, priority, route status, or how recently it changed; priority takes one or more of 0-3 " + "(P0-P3) and null for an issue with no priority, so an owner's P0/P1 audit is priority [0, 1]. " + 'route_status "no_holder" lists every open issue whose route names a role nobody holds or a ' + "session that is not running at the moment of the read, whatever its priority. A restarting " + "session is absent for minutes, so an issue is unowned only when a read ten minutes later agrees. " + "Do not use it to search by keyword or phrase; dispatch_search remains the keyword surface. " + "Dispatch pages the list: limit sets the page size (default " + `${DEFAULT_ISSUE_PAGE_LIMIT}, max ${MAX_ISSUE_PAGE_LIMIT}) and offset selects where it starts ` + "(default 0), and the answer names how many issues match, so repeat with the next offset to " + "walk every matching issue. A walk is exact only while the list does not change: an issue " + "that enters or leaves what the filters match, or whose status or rank changes, between two " + "pages shifts rows across a page boundary, so one issue can come back twice and another never.",
     arguments: (z2) => ({
       project: z2.string().describe("Project key to list issues from."),
       status: z2.enum(ISSUE_STATUSES).describe("Optional lifecycle status filter.").optional(),
@@ -14293,7 +14295,7 @@ var dispatchToolSpecs = [
       priority: z2.array(z2.number({ int: true, min: 0, max: 3 }).nullable(), { min: 1, max: 5 }).describe("Optional priority filter: one or more of 0 (P0, highest) through 3 (P3, lowest), and null " + "for an issue with no priority; an issue matching any listed value is returned.").optional(),
       updated_since: z2.string().describe("Optional RFC3339 timestamp; only issues updated at or after it.").optional(),
       route_status: z2.enum(ISSUE_ROUTE_STATUSES).describe("Optional: only open issues whose route is in this state. live: a running session holds " + "the role or is the routed session. no_holder: nobody running holds the role, or the " + "session is not running, right now. unknown: the Envoy listener did not answer.").optional(),
-      limit: z2.number({ int: true, min: 1, max: 250 }).describe("Maximum rows, 1-250; default 50.").optional(),
+      limit: z2.number({ int: true, min: 1, max: MAX_ISSUE_PAGE_LIMIT }).describe(`Maximum rows, 1-${MAX_ISSUE_PAGE_LIMIT}; default ${DEFAULT_ISSUE_PAGE_LIMIT}.`).optional(),
       offset: z2.number({ int: true, min: 0 }).describe("Rows to skip before the page; nonnegative integer; default 0.").optional()
     })
   },
@@ -15118,8 +15120,26 @@ class DispatchClient {
   async resolveIssue(issueReference) {
     return this.#resolveIssue(issueReference);
   }
-  async listIssues(options = {}) {
-    return this.#json("GET", ["api", "v1", "issues"], undefined, options);
+  async listIssuePage(options, page) {
+    const answer = await this.#json("GET", ["api", "v1", "issues"], undefined, {
+      ...options,
+      limit: page.limit,
+      offset: page.offset
+    });
+    if (Array.isArray(answer)) {
+      const issues = answer;
+      return {
+        issues: issues.slice(page.offset, page.offset + page.limit),
+        total: issues.length,
+        limit: page.limit,
+        offset: page.offset
+      };
+    }
+    const served = answer;
+    if (typeof served !== "object" || served === null || !Array.isArray(served.issues) || typeof served.total !== "number" || typeof served.limit !== "number" || typeof served.offset !== "number") {
+      throw new Error("GET /api/v1/issues answered neither a page ({issues, total, limit, offset}) nor an array of issues");
+    }
+    return served;
   }
   async listProjectArtifacts(project, unlinked = false) {
     return this.#json("GET", ["api", "v1", "projects", project, "artifacts"], undefined, unlinked ? { unlinked: "true" } : undefined);
@@ -16789,9 +16809,7 @@ async function executeDispatchTool(input) {
       const priority = optionalPriorityFilter(args, "priority");
       const updatedSince = optionalString(args, "updated_since");
       const routeStatus = optionalString(args, "route_status");
-      const limit = Math.min(Math.max(optionalNumber(args, "limit") ?? 50, 1), 250);
-      const offset = Math.max(optionalNumber(args, "offset") ?? 0, 0);
-      const issues = await client.listIssues({
+      const page = await client.listIssuePage({
         project,
         ...status === undefined ? {} : { status },
         ...parent === undefined ? {} : { parent },
@@ -16799,9 +16817,12 @@ async function executeDispatchTool(input) {
         ...priority === undefined ? {} : { priority },
         ...updatedSince === undefined ? {} : { updated_since: updatedSince },
         ...routeStatus === undefined ? {} : { route_status: routeStatus }
+      }, {
+        limit: optionalNumber(args, "limit") ?? DEFAULT_ISSUE_PAGE_LIMIT,
+        offset: optionalNumber(args, "offset") ?? 0
       });
-      const total = issues.length;
-      const rows = issues.slice(offset, offset + limit).map((row) => ({
+      const { total, limit, offset } = page;
+      const rows = page.issues.map((row) => ({
         key: row.key,
         title: row.title,
         status: row.status,

package/package.json

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

package/skills/dispatch/references/api.md

@@ -26,3 +26,14 @@ A path Dispatch does not serve under `/api` or `/v1` answers
 route"}`; when you see that, you typed the path wrong — read the index rather than guessing. Every
 `/api/v1` error body carries a `code`; branch on the code, never on the text.
 
+`GET /api/v1/issues` answers every matching issue as an array, or one page when you name `limit`
+(1–250) or `offset` (alone it pages 50): `{issues, total, limit, offset}`, where `total` counts
+every issue your filters match. Walking the pages with the next `offset` is exact only while the
+listing does not change: an issue that enters or leaves what the filters match, or whose status or
+rank changes, between two reads shifts rows across a page boundary, and one issue comes back twice
+and another never, even when you stop at `total`. The unpaged array is the only exact set one read
+gives. `cursor` is `400 INVALID_QUERY`. `dispatch_issues` pages for you.
+The event logs page with `after` or `before` and `limit`, and `GET /api/v1/search` takes a `limit`
+of at most 50 and has no next page. Every other route answers without paging and ignores a paging
+parameter.
+

package/skills/dispatch/references/issues.md

@@ -144,8 +144,11 @@ when it last changed — a roadmap or backlog pass without opening every issue.
 (a lifecycle status), `parent` (one issue's children), `label`, `priority` (a list of `0`–`3`, with
 `null` for an issue with no priority: `[0, 1]` is every P0 and P1), `route_status` (below), or
 `updated_since` (an RFC3339 timestamp, for "what moved this week"). `limit` is the page size, 50 by
-default and 250 at most, and `offset` is where the page starts: repeat with the next offset until a
-page comes back short to list every matching issue.
+default and 250 at most, and `offset` is where the page starts; the answer says how many issues
+match. Repeating with the next offset walks every matching issue only while the list does not
+change: an issue that enters or leaves what your filters match, or whose status or rank changes,
+between two pages shifts rows across a page boundary, and the walk then shows one issue twice and
+misses another.
 
 This is not search: it matches no text. Use `dispatch_search` for a keyword or phrase, and
 `dispatch_issues` when you want every issue in a project and its current state.

package/skills/legion-architect/SKILL.md

@@ -43,8 +43,7 @@ separate coordinator to finish necessary work.
 
 Deployment instructions, when present, are the operator's standing rules for this repository —
 required checks, deploy/smoke commands, code-owner expectations, standing roles you may consult,
-the merge credential. They override this skill's defaults where they conflict; they never
-override a Sami ruling quoted here.
+the merge credential. They override this skill's defaults where they conflict.
 
 ## 1. Decompose or adopt
 

package/skills/legion-controller/SKILL.md

@@ -89,7 +89,10 @@ mints a new secret, so your grants stop working and the role moves to the new se
 The Go daemon's controller topic is a wake for a session that is running when it is published.
 Envoy hands an Oh My Pi session no retained copy of a notice published before it subscribed, so a
 hold, a tree architect's failed claim, a new triage root, or a freed slot from while no controller
-ran never arrives as a wake. At every start, before anything else:
+ran never arrives as a wake. `legion controller start` opens your first turn with a start message
+(`Legion controller start: …`), so every start and restart runs this procedure with nothing typed.
+At every start, after the claim recheck ([Turn discipline](#turn-discipline)) and before anything
+else:
 
 1. Read `legion state --json` and handle each issue whose `issues.<KEY>.phase` is `held` (its
    `issues.<KEY>.holdReason` is `escalated` when its architect sent it to you, and absent while the
@@ -132,15 +135,37 @@ you hand over or file for Legion to run carries it first (`labels` in `dispatch_
 `dispatch_issue`). Taking the label off a waiting root drops it from the waiting line; taking it
 off an admitted tree does not stop it.
 
+## Trees waiting on a root claim (Go daemon)
+
+A Go root architect whose claim on its root issue was refused starts nothing and waits, holding
+its slot, until the claim is free; nothing tells it when a session holder lets go without
+replying. So every turn rechecks them ([Turn discipline](#turn-discipline)), the daemon's `tick`
+included, which comes on its interval even with every slot taken: read each root in
+`admission.active` whose `issues.<KEY>.phase` is still `admitted` with `dispatch_read`. When its
+`Claimed by:` line is `nobody` or ends `· not running`, tell that tree's architect to claim again
+with `envoy_publish` to `notifications.role.` followed by its claim token,
+`issues.<KEY>.architect.locator.claim` in `legion state --json`. A claim that is its architect's
+own, or one that still holds, needs nothing.
+
 ## Keeping the slots full (Go daemon)
 
 Picking the next work is your job: nobody hand-feeds issues to Legion. Keep every admission slot
 filled with the highest-priority concrete issue Legion can take. The unit of Legion work is a
 leaf, an issue with no children, never an umbrella that holds other issues.
 
-**When.** At every start (step 3 above), and on each `slot-free on <KEY>` wake: the daemon
-released `<KEY>`'s slot, because its tree finished or left the workflow, and no waiting root took
-it.
+**When.** At every start (step 3 above), and on each of the Go daemon's walk wakes. The daemon
+sends each only while a controller is registered, and none while one of the same kind is still
+unsent:
+
+- `slot-free on <KEY>`: the daemon released `<KEY>`'s slot, because its tree finished or left the
+  workflow, and the slot is free by **How many** below.
+- `todo on <KEY>`: `<KEY>`, an issue nobody handed to Legion, changed while in `todo` and a slot
+  was free, so it may be a new candidate. The daemon holds it back half a minute and folds the
+  events of that window into it. Walk the whole list, not only `<KEY>`.
+- `tick on <PROJECT>`: the daemon's periodic wake, a minute after it starts and then every
+  `controller_wake_interval_seconds` (an hour by default), whatever the slots. An earlier walk
+  that found nothing, a day with no event, and [a tree waiting on a root
+  claim](#trees-waiting-on-a-root-claim-go-daemon) all get a turn from it.
 
 **Scope first.** The scope the deployment instructions state decides which issues are candidates
 at all, before anything below. When they say you hand Legion no issue yourself, or that Legion
@@ -154,10 +179,10 @@ scope.
 you add). With none free, stop.
 
 **Candidates.** The project's open `todo` issues, roots and children alike, that have no children
-at all and do not carry the `legion` label. `todo` alone, as Sami ruled for choosing work on
-2026-09-27 (`skill://dispatch`, "Choosing what to work on"): take the top ready issue, "status
-`todo`, highest priority first, then board rank"; an issue that waits on a deploy or a decision
-belongs in `backlog`, so the walk takes nothing from `backlog` or `triage`. The Go daemon runs
+at all and do not carry the `legion` label. Ready work is `todo` (`skill://dispatch`, "Choosing
+what to work on"): take the top ready issue, highest priority first, then board rank. An issue that
+waits on a deploy or a decision belongs in `backlog`, so the walk takes nothing from `backlog` or
+`triage`. The Go daemon runs
 only labelled roots, so every root it ran since the daemon required the label carries it: a
 labelled root in `todo` is the daemon's to admit or queue, one in `triage` is yours to triage
 (step 2 above), and one anywhere else was parked by Legion or by a person. A child you take becomes
@@ -208,12 +233,12 @@ leans on `External links:`, and the label row is the one that never depends on h
 
 2. It is already in `todo`, so the label admits it: the daemon records it and gives it the free
    slot, or queues it in `admission.waiting`. It needs no status write.
-3. Post one short comment that says Legion took it and names who is asked at its design gate, from
-   the `Assignee:` line, with the assignee sentence [New issue triage](#new-issue-triage) step 4
-   gives:
+3. Post one short comment that says Legion took it, who is asked at its design gate, and how to
+   undo the take, naming the assignee with the sentence [New issue triage](#new-issue-triage)
+   step 4 gives (which follows the design gate policy):
 
    ```text
-   dispatch_comment({ issue: "<KEY>", body: "Legion took this issue: it was the highest-priority open issue nobody else was working on. Assigned to <login>, who will get this tree's questions and its design approval." })
+   dispatch_comment({ issue: "<KEY>", body: "Legion took this issue: it was the highest-priority open issue nobody else was working on. Assigned to <login>, who will get this tree's questions and its design approval. To stop Legion, move the issue to backlog. To keep Legion off it for good, also take the legion label off; taking the label off alone does not stop a tree that has started." })
    ```
 
 The daemon admits each root when Dispatch's event reaches it; the next `legion state --json`
@@ -237,9 +262,9 @@ legion status <report KEY> icebox
 ```
 
 **When.** On your first turn of each UTC day, whatever it is: your start, or a wake of any kind.
-Read the report issue with `dispatch_read`, and post when its `Events:` show no `message.created`
-from today. You have no clock of your own, so a day with no turn has no report; the next one
-covers it.
+While you are registered, the daemon's `tick` gives you a turn at least every
+`controller_wake_interval_seconds`. After the turn's own work, read the report issue with
+`dispatch_read`, and post when its `Events:` show no `message.created` from today.
 
 **What.** One `dispatch_message({ issue: "<report KEY>", body })` of at most 2,000 characters,
 written as `skill://dispatch`'s "Writing for the human" says: every issue by its key and title,
@@ -253,7 +278,13 @@ every pull request by its URL.
 - **Closed without a change.** Those with no pull request, each with the reason its closing
   message gave (the `message.created` just before `issue.closed` among `Events:`).
 - **Running.** Each root in `admission.active` with its `issues.<KEY>.phase`, and the roots in
-  `admission.waiting`.
+  `admission.waiting`. A root whose architect told you its claim was refused is named as waiting
+  on that holder: its architect started nothing and asked them to release it or take the issue
+  back. Nothing in `legion state` records that, so read the tree's issue (its `Claimed by:` line
+  and the ask or message the architect opened) before you name it.
+- **The slots and the walk.** The free slots, as **How many** counts them, then this turn's walk
+  when it made one: what it took, and how many candidates each row of the table skipped, so a
+  reader can see why a free slot stays empty.
 
 A day with nothing finished says so in one sentence. When the lists do not fit, keep the counts
 and the highest-priority issues.
@@ -262,16 +293,19 @@ and the highest-priority issues.
 
 Deployment instructions, when present, are the operator's standing rules for this repository —
 required checks, deploy/smoke commands, code-owner expectations, and standing roles you may
-consult. They override this skill's defaults where they conflict; they never override a Sami ruling
-quoted here.
+consult. They override this skill's defaults where they conflict, and may narrow which issues the
+walk takes, but never widen it past `todo` issues or change the order it takes them in: highest
+priority first, then board rank ([Keeping the slots full](#keeping-the-slots-full-go-daemon)).
 
 ## Turn discipline
 
 - **Direct user message always first.** If this turn includes a direct user message, answer
   it before handling every other wake.
 - **One wake = one turn.** Handle exactly the wake's implication, then end the turn. Never
-  poll, idle-loop, or wait for another event. The one addition: your first turn of each UTC day,
-  whatever woke you, also posts the day's report ([Daily report](#daily-report-go-daemon)).
+  poll, idle-loop, or wait for another event. Two additions, after any direct user message: every
+  turn under the Go daemon first rechecks the [trees waiting on a root
+  claim](#trees-waiting-on-a-root-claim-go-daemon), and your first turn of each UTC day, whatever
+  woke you, also posts the day's report ([Daily report](#daily-report-go-daemon)).
 - **Wakes are advisory.** Before any side effect, verify the current daemon state and the
   relevant Dispatch issue. A stale or duplicate wake may cost a read, never a wrong action.
 - **Controller state is disposable.** Do not reconstruct or preserve local controller
@@ -288,6 +322,8 @@ quoted here.
 | New issue created in the Dispatch project (`issue.created`, status `triage`; under the TypeScript daemon resync heals misses, under the Go daemon the boot step above does). From the Go daemon: `triage on <KEY>` (payload `{kind: "triage"}`) on the controller topic, for an unrecorded root carrying the `legion` label only ("Issues handed to Legion" above) | issue key + triage context (incl. pre-existing children) | Triage: `legion status <KEY> todo` to admit, or set `backlog`/`icebox` to park |
 | Backlog eligibility (TypeScript daemon) | slot freed / priority change | Reconsider parked items and move the eligible root to `todo` |
 | `slot-free on <KEY>` from the Go daemon (payload `{kind: "slot-free"}`) | the root whose slot the daemon released with no waiting root to take it | Verify a free slot in `legion state --json`, then fill it ([Keeping the slots full](#keeping-the-slots-full-go-daemon)) |
+| `todo on <KEY>` from the Go daemon (payload `{kind: "todo"}`) | an issue not handed to Legion that changed while in `todo` and a slot stood free, sent half a minute later | Verify a free slot, then walk the whole `todo` list ([Keeping the slots full](#keeping-the-slots-full-go-daemon)) |
+| `tick on <PROJECT>` from the Go daemon (payload `{kind: "tick"}`) | the project key; the daemon's periodic wake, whatever the slots | Recheck the trees waiting on a claim, then walk if a slot is free; post the day's report if this is the day's first turn |
 | Architect escalation (controller-actionable only: re-file a child as a root issue, capacity, cross-tree conflicts) | request + context | Judge and act; issue-scoped human Q&A goes through `dispatch_ask` from the owning architect, not here |
 | Resync report | artifact-driven anomaly list (zero-owner trees, untriaged-open, launch-failed, admission-drift) | Verify against fresh state, then heal |
 | Resync report: `admission-drift` entry | issue key + whether the daemon added it to, or removed it from, its admission list (the detail says which) | No action: the daemon already repaired it in the same run. An issue that reappears in consecutive reports is a live leak — file a LEGION issue on Dispatch with both reports pasted as evidence (never a GitHub issue) |
@@ -330,15 +366,19 @@ quoted here.
    why), name who will be asked with the assignee sentence: `Assigned to <login>, who will get
    this tree's questions and its design approval`, or, when the `Assignee:` line says
    `unassigned`, `Unassigned — nobody's Inbox shows this tree's questions or its design approval
-   until someone takes it from the issue header (Assignee, beside Priority)`. An unassigned root
+   until someone takes it from the issue header (Assignee, beside Priority)`. The design approval
+   is promised only when the `Design gate policy:` line of your system prompt, which
+   `legion controller start` writes from the daemon's own configuration, says
+   `gates.design: root-issues`. Under `gates.design: off` nobody approves a design, so drop "and
+   its design approval" (and "or its design approval") from the sentence. An unassigned root
    still runs; the architect's asks wait in every Inbox's Unassigned band.
 
 ## Backlog eligibility
 
 Under the Go daemon nothing reconsiders `backlog` or `icebox` on its own: [Keeping the slots
 full](#keeping-the-slots-full-go-daemon) takes only `todo` issues, since an issue that waits on a
-deploy or a decision belongs in `backlog` (Sami's ruling of 2026-09-27, `skill://dispatch`,
-"Choosing what to work on"). A handed-over root waits for a slot in `todo`, where the daemon's
+deploy or a decision belongs in `backlog` (`skill://dispatch`, "Choosing what to work on"). A
+handed-over root waits for a slot in `todo`, where the daemon's
 admission queue holds it (`admission.waiting`), so a park means "should not run now", and a
 parked root keeps its `legion` label. A parked issue runs again when a person sets it to `todo`,
 or when a wake tells you to re-admit it (`worker-died`, closed-tree activity).