@sjawhar/opencode-legion-envoy 5.5.1 → 5.6.0

package/dist/src/server.js

@@ -13962,6 +13962,7 @@ var ASK_URGENCIES = ["low", "med", "high", "blocking"];
 var ASK_QUESTION_MAX = 800;
 var SEARCH_QUERY_MAX = 1000;
 var SEARCH_QUERY_HINT = "search with a short phrase of a few words, not a passage";
+var SEARCH_KIND_DEPTH = 100;
 var PROJECT_KEY_PATTERN = /^[A-Z][A-Z0-9]{1,9}$/;
 var ISSUE_STATUSES = [
   "triage",
@@ -14297,7 +14298,7 @@ var dispatchToolSpecs = [
   {
     name: "dispatch_search",
     example: { query: "astrolabe" },
-    description: "Search every issue, document, comment, ask, and message for a keyword or phrase and get deep links. " + "Use it before creating an issue or a design document, and to find where a word was written. " + 'Websearch syntax: "quoted phrase", -excluded, OR.',
+    description: "Search every issue, document, comment, ask, and message for a keyword or phrase and get deep links. " + "Use it before creating an issue or a design document, and to find where a word was written. " + 'Websearch syntax: "quoted phrase", -excluded, OR. ' + "Each kind of content is ranked on its own and the lists are merged, so the top holds the best " + "issue, document, ask, comment and message; an issue key searched alone lists that issue first. " + `The answer names how many results match; offset pages through them, and each kind lists at most its best ${SEARCH_KIND_DEPTH}, ` + "so narrow the query or name a project to reach the rest. Paging is exact only while the " + "corpus holds still: content added, changed, or removed between two offsets can shift rows " + "across a page boundary, so one hit can come back twice and another never.",
     arguments: (z2) => ({
       query: z2.string({
         min: 2,
@@ -14305,7 +14306,8 @@ var dispatchToolSpecs = [
         maxHint: SEARCH_QUERY_HINT
       }).describe(`Keyword, phrase, or websearch expression; 2 to ${SEARCH_QUERY_MAX} characters.`),
       project: z2.string().describe("Optional project key to search within.").optional(),
-      limit: z2.number({ int: true, min: 1, max: 50 }).describe("Maximum results, 1-50; default 20.").optional()
+      limit: z2.number({ int: true, min: 1, max: 50 }).describe("Maximum results, 1-50; default 20.").optional(),
+      offset: z2.number({ int: true, min: 0 }).describe("Results to skip before the page; nonnegative integer; default 0.").optional()
     }),
     validation: {
       check: (value) => {
@@ -15206,6 +15208,71 @@ function dispatchChildRef(ownerRef, kind, id) {
   return `${ownerRef}/${kind}/${id}`;
 }
 
+// ../envoy-client/src/search-answer.ts
+function pageSummaryText(offset, count, total) {
+  return `showing ${offset + 1}-${offset + count} of ${total}`;
+}
+function searchResultLine(result, baseUrl) {
+  const href = new URL(result.href, baseUrl).toString();
+  const { owner } = result;
+  if (owner.kind === "document") {
+    const reference = dispatchDocumentRef(owner.project, owner.slug);
+    return `${reference} [document] ${owner.name} - ${result.kind}: ${snippetText(result.snippet)} -> ${href}`;
+  }
+  const artifactName = result.artifact ? ` ${result.artifact.name}` : "";
+  const label = `${owner.key} [${owner.status}] ${owner.title} - ${result.kind}${artifactName}`;
+  return `${label}: ${snippetText(result.snippet)} -> ${href}`;
+}
+function searchAnswer(search, query, offset, configUrl) {
+  const results = search.results;
+  const count = results.length;
+  const lines = results.map((result) => searchResultLine(result, configUrl));
+  const noun = count === 1 ? "result" : "results";
+  const noResults = `No results for "${query}".`;
+  if (typeof search.total !== "number") {
+    if (offset !== undefined && offset > 0) {
+      throw new Error(`Dispatch answered without a total: it predates search paging and ignored offset ${offset}, so this would be its first page again.`);
+    }
+    return {
+      text: count === 0 ? noResults : [`${count} ${noun} for "${query}" (${search.took_ms} ms)`, ...lines].join(`
+`),
+      details: { query, results }
+    };
+  }
+  const { total, reachable, offset: pageOffset } = search;
+  const end = pageOffset + count;
+  const cut = reachable < total ? `Each kind lists only its best ${SEARCH_KIND_DEPTH} matches, so ${reachable} of the ${total} can be paged to; narrow the query or name a project to reach the rest.` : undefined;
+  const details = {
+    query,
+    results,
+    total,
+    reachable,
+    offset: pageOffset,
+    limit: search.limit
+  };
+  if (count === 0) {
+    return {
+      text: total === 0 ? noResults : [
+        `No results for "${query}" at offset ${pageOffset}: it matches ${total}, and the pages reach the first ${reachable}.`,
+        ...cut === undefined ? [] : [cut]
+      ].join(`
+`),
+      details
+    };
+  }
+  const showing = pageOffset === 0 && count === total ? "" : `${pageSummaryText(pageOffset, count, total)}, `;
+  return {
+    text: [
+      `${count} ${noun} for "${query}" (${showing}${search.took_ms} ms)`,
+      ...cut === undefined ? [] : [cut],
+      ...lines,
+      ...end < reachable ? [`Next page: offset ${end}.`] : []
+    ].join(`
+`),
+    details
+  };
+}
+
 // ../envoy-client/src/tool-input-errors.ts
 class ToolInputError extends Error {
   tool;
@@ -15515,17 +15582,6 @@ function duplicateCandidates(error48) {
     throw error48;
   return error48.candidates;
 }
-function searchResultLine(result, baseUrl) {
-  const href = new URL(result.href, baseUrl).toString();
-  const { owner } = result;
-  if (owner.kind === "document") {
-    const reference = dispatchDocumentRef(owner.project, owner.slug);
-    return `${reference} [document] ${owner.name} - ${result.kind}: ${snippetText(result.snippet)} -> ${href}`;
-  }
-  const artifactName = result.artifact ? ` ${result.artifact.name}` : "";
-  const label = `${owner.key} [${owner.status}] ${owner.title} - ${result.kind}${artifactName}`;
-  return `${label}: ${snippetText(result.snippet)} -> ${href}`;
-}
 function askUrgency(args) {
   const value = args.urgency;
   return ASK_URGENCIES.find((urgency) => urgency === value);
@@ -16721,20 +16777,13 @@ async function executeDispatchTool(input) {
       const query = stringArg(args, "query");
       const project = optionalString(args, "project");
       const limit = optionalNumber(args, "limit");
+      const offset = optionalNumber(args, "offset");
       const search = await client.search(query, {
         ...project === undefined ? {} : { project },
-        ...limit === undefined ? {} : { limit }
+        ...limit === undefined ? {} : { limit },
+        ...offset === undefined ? {} : { offset }
       });
-      const results = search.results;
-      const count = results.length;
-      return {
-        text: count === 0 ? `No results for "${query}".` : [
-          `${count} ${count === 1 ? "result" : "results"} for "${query}" (${search.took_ms} ms)`,
-          ...results.map((result) => searchResultLine(result, configUrl))
-        ].join(`
-`),
-        details: { query, results }
-      };
+      return searchAnswer(search, query, offset, configUrl);
     }
     case "dispatch_issues": {
       const project = stringArg(args, "project");
@@ -16774,7 +16823,7 @@ async function executeDispatchTool(input) {
       }));
       const titles = await liveSessionTitles(client, rows.some((row) => holdsSession(row.claim)));
       const isPartial = offset !== 0 || rows.length !== total;
-      const showing = !isPartial ? "" : rows.length === 0 ? `showing 0-0 of ${total}` : `showing ${offset + 1}-${offset + rows.length} of ${total}`;
+      const showing = !isPartial ? "" : rows.length === 0 ? `showing 0-0 of ${total}` : pageSummaryText(offset, rows.length, total);
       return {
         text: rows.length === 0 ? `No issues in ${project}.${isPartial ? ` (${showing})` : ""}` : [
           `${rows.length} ${rows.length === 1 ? "issue" : "issues"} in ${project}` + (isPartial ? ` (${showing})` : ""),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/opencode-legion-envoy",
-  "version": "5.5.1",
+  "version": "5.6.0",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/src/server.js",

package/skills/dispatch/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dispatch
-description: "Use before posting a message, a status update, or a periodic status update; before asking a question that references another message, artifact, or eval; before asking a design question or brainstorming a change; and when asking Sami a question, updating the spec, commenting on a document, attaching an artifact, or calling a dispatch_* tool."
+description: "Use before posting a message, a status update, or a periodic status update; before asking a question that references another message, artifact, or eval; before asking a design question or brainstorming a change; and when asking the human a question, updating the spec, commenting on a document, attaching an artifact, or calling a dispatch_* tool."
 ---
 
 # Dispatch
@@ -66,7 +66,7 @@ not share this session's vocabulary, and is often on a phone. Write for that per
   has a human subject, even on a sentence you already simplified; a lead naming what a change does
   inside a system leaves the reader nothing to act on. Where the judgment rule below applies, the
   judgment leads and this rule shapes the sentence under it.
-- Before posting, test it: could Sami, reading only this text on his phone, know what he is being
+- Before posting, test it: could the human, reading only this text on their phone, know what they are being
   told or asked? If not, rewrite it. Length is not the problem; density is.
 - When an ask or message communicates a judgment, lead with that judgment in one sentence and put the mechanism underneath it. Do not make the reader ask a second time whether the result is a win. This shapes communication only when a judgment exists; it does not pre-decide an open question or remove its genuine options.
 - When a Dispatch message states a root cause, include the reproducing command or test in that same message. Without it, label the diagnosis a hypothesis; a diagnosis still in progress may say so plainly. This boundary applies to causal claims, not to reporting that an investigation has started.
@@ -160,15 +160,14 @@ follow [Writing a spec](#writing-a-spec).
 you plan, start a design document, file an issue, ask, post a finding or start work, and what to
 do with each hit. What it leaves out:
 ```ts
-dispatch_search({ query, project?, limit? })
+dispatch_search({ query, project?, limit?, offset? })
 ```
-Websearch syntax applies: `"merge queue"`, `-daemon`, `OR`. It returns the best `limit` hits (20
-by default, 50 at most) across issues, documents, comments, asks, and messages. A query over
-1,000 characters is refused before it is sent: search with the few words `skill://dispatch-first`
-describes, never a pasted passage. Issue-owned hit lines start with the issue key; standalone
-project-document hit lines start with `dispatch://PROJECT/artifact/<slug>`, followed by the
-absolute link. Cite the hit you build on (`dispatch://KEY` or the document reference), or state
-"no prior issue" in the spec.
+Websearch syntax applies: `"merge queue"`, `-daemon`, `OR`. Issues, documents, asks, comments, and messages rank separately; the
+merged page orders each kind's best in turn — issue, document, ask, comment, message — and a bare issue key ranks first. A page
+holds `limit` hits (20 default, 50 max); the first line gives the total (`showing 1-20 of 312`); see
+[Search paging](skill://dispatch/references/issues.md#search-paging) for more. Queries over 1,000 characters are refused: use the
+few words `skill://dispatch-first` names, never a pasted passage. Issue hits start with the issue key; document hits start with
+`dispatch://PROJECT/artifact/<slug>`, then the link. Cite the hit (`dispatch://KEY` or the doc ref) or say "no prior issue".
 
 `dispatch_issue` refuses a title that near-duplicates an issue in the same project and returns the candidates (`POSSIBLE_DUPLICATE`).
 Read them; reference the existing issue, or repeat the call with `force: true` when it is genuinely new work.
@@ -228,7 +227,7 @@ Every `dispatch_ask` passes four gates first:
    internals are your lane's to decide where the work happens, in the plan or the code, not in the
    spec. A contract between two lanes is settled by those two lanes over Envoy, and you open no ask
    for it. A halt condition (a change to IAM, deletion or exposure of production data, anything
-   that reaches a customer) passes this gate: it is your own `dispatch_ask` to Sami on your own
+   that reaches a customer) passes this gate: it is your own `dispatch_ask` to the human on your own
    issue.
 2. **Is there genuine uncertainty, and have you measured what you can?** If there is none, it is
    a plan you execute. The one legitimate ask without uncertainty is permission for an action
@@ -323,7 +322,7 @@ they must read to decide belongs in the spec in the first place — see [Artifac
 
 Before saying you are waiting for human input, call `dispatch_open_asks`. With no arguments it lists this session's active asks across open issues and project documents, including whether the human or agent owes the next reply. With `dispatch_open_asks({ project })` it lists every open ask in that project — on its issues and on its documents, whoever authored them — which is how you see what a whole project is waiting on rather than just your own asks.
 
-**Unsettled product shape needs a decision before implementation.** When a page, navigation entry, table key, customer-scoping rule, or persisted sidecar would set product shape that Sami has not already settled, write a decision block in the document that records the work before the first implementation commit; in a Legion tree the architect writes it, and a phase worker sends the decision to its architect. A lane's schema decision or a contract two lanes agree does not settle product shape. This does not turn a user-specified decision or routine implementation into an approval request. A control or behaviour the human asked for in words is settled by those words, together with every choice inside it that his words do not make (where it sits, its defaults, its options): build it without a block, as gate 4 of [Before you ask](#before-you-ask) says. This rule covers only product shape outside what he asked for, and its block comes before the commit that sets that shape.
+**Unsettled product shape needs a decision before implementation.** When a page, navigation entry, table key, customer-scoping rule, or persisted sidecar would set product shape that the human has not already settled, write a decision block in the document that records the work before the first implementation commit; in a Legion tree the architect writes it, and a phase worker sends the decision to its architect. A lane's schema decision or a contract two lanes agree does not settle product shape. This does not turn a user-specified decision or routine implementation into an approval request. A control or behaviour the human asked for in words is settled by those words, together with every choice inside it that his words do not make (where it sits, its defaults, …
 
 **Anything you are blocked on a human for is visible in Dispatch.** An agent waits on a human only
 through an open ask. A to-do, permission, credential or grant renewal, setting only they can
@@ -359,7 +358,7 @@ Use `mode: "none"` with a concrete reason only when the work is genuinely non-ar
 ## Close what you opened
 
 An ask you opened is yours until it is answered or you resolve it. When the answer arrives some
-other way — Sami said it live, a later comment settled it, or the question became moot because the
+other way — the human said it live, a later comment settled it, or the question became moot because the
 design moved — resolve it yourself with `dispatch_resolve_ask` in the same turn you learn that.
 Never leave it for the human to clear.
 

package/skills/dispatch/references/issues.md

@@ -9,13 +9,12 @@ project's architecture model, or list or audit a project's backlog.
 When you finish an issue, or are told to work on the next thing, take the top ready issue of the
 whole backlog, across every project: status `todo`, highest priority first, then board rank. There
 are no areas: a standing role, a product owner and a lane each take the top issue like everyone
-else (Sami's ruling). `todo` means ready: specced, unblocked, and waiting on neither a deploy nor a
+else. `todo` means ready: specced, unblocked, and waiting on neither a deploy nor a
 decision. An issue that waits on one belongs in `backlog`, with what it waits on said on the issue.
 
 Hold at most three issues in flight (`in_progress`, `testing`, `needs_review` or `retro`), of any
-kind (Sami's ruling). The limit is per agent and has nothing to do with the week's priorities
-(Sami, correcting a reading that tied the two together): the priorities decide only what you pull
-next. Past three:
+kind. The limit is per agent and has nothing to do with the week's priorities: the priorities
+decide only what you pull next. Past three:
 push any unfinished work, say where in one comment on the issue, move it to `backlog` and clear
 its route. Each issue counts on its own; a child does not ride under its parent's slot.
 In-flight issues with no owner at all go
@@ -27,7 +26,7 @@ writes on the root of a tree Legion is running is set back and the tree's archit
 it; only a person in the dashboard, or `legion status`, stops that tree. On an issue under one, a
 status that takes it out of the flow parks that issue and stops its workers.
 
-One agent keeps the backlog's order against those priorities, with Sami, as he ruled. Setting an
+One agent keeps the backlog's order against those priorities. Setting an
 issue's priority stays yours ([Priority is yours to set](#priority-is-yours-to-set)); reordering
 the board does not.
 When the top of the backlog looks wrong, or a priority's next step is not yet a ready issue,
@@ -118,7 +117,7 @@ when work has started.
 Priority is the coarse bucket a backlog is read by: `0` is P0, the highest, through `3`, P3, the
 lowest, and `null` clears it. Agents set it (`dispatch://LEGION/artifact/issue-status-conventions-md`)
 — on creation, and on a grooming pass over issues that have none — and say what you set and why;
-Sami overrides anything he disagrees with from the dashboard. A closed
+the human overrides anything they disagree with from the dashboard. A closed
 issue takes only `rank`, `components`, and a reopening `status` (any status but `done`);
 everything else, `priority` included, waits for the reopen (`409 ISSUE_CLOSED`). So reopen it
 first, then set the priority — the two cannot go in one call. `rank` itself is not a tool field:
@@ -194,6 +193,16 @@ The audit finds four shapes:
 Run the audit as a step of a coordinator's loop, at each checkpoint, not as a habit: these shapes
 are found by running the check, not by noticing them.
 
+## Search paging
+
+`skill://dispatch` sends you here when a `dispatch_search` page is not enough: more hits remain,
+or a kind runs out before the page does.
+
+A page holds `limit` hits (20 by default, 50 at most); the first line names how many match
+(`showing 1-20 of 312`), and, while more can be reached, the last line names the next `offset`.
+Each kind lists at most its best 100, so when the result says the rest cannot be paged to, narrow
+the query or name a `project`.
+
 ## Syncing a project's architecture model
 
 Import a project's architecture model from its configured source repository now (a human configures the source in Settings):

package/skills/legion-architect/SKILL.md

@@ -79,7 +79,7 @@ exercise a criterion end to end, building that path is a child issue of this tre
 
 Specifications written into Dispatch follow `skill://dispatch`'s [Writing a spec](../dispatch/SKILL.md#writing-a-spec).
 Wave releases, child closures, and your own status are visible from the issue tree and the
-handoffs; do not narrate them into the spec or a `dispatch_message`. A to-do only Sami can clear
+handoffs; do not narrate them into the spec or a `dispatch_message`. A to-do only a human can clear
 is a `dispatch_ask`.
 
 The issue's primary document **is** the root specification. Extend it in place: a new version
@@ -338,7 +338,7 @@ cross-tree conflict. Report those to the controller with `envoy_publish` to the
 your `Legion addressing` line names. Handle everything else in the
 tree. A product, scope, or design decision that needs the human, yours or one a worker escalated,
 is a decision block you write (section 1 says what one does to the root spec's gate). A standalone
-human to-do may use `dispatch_ask`; workers may reach Sami directly with it the same way. Do not
+human to-do may use `dispatch_ask`; workers may reach the human directly with it the same way. Do not
 create a wait loop for any wake source.
 
 Never yield while waiting on a human. A human is waiting on you only where an open ask sits in

package/skills/legion-controller/SKILL.md

@@ -16,10 +16,10 @@ The Legion extension claims `legion-<project>-controller` and registers controll
 with the daemon during session startup. Do not handle a wake unless that startup succeeded.
 
 The daemon runs the controller as an interactive OMP terminal session in its private tmux
-server (the pane runs plain `omp`, not `--mode rpc`, and no `legion worker-shim`; Sami reaches
+server (the pane runs plain `omp`, not `--mode rpc`, and no `legion worker-shim`; the operator reaches
 it with `tmux -L legion-<project> select-window -t <window id> \; attach -t legion-<project>`,
 the window id being `controllerLocator.tmuxWindowId` in `legion state --json` — every window
-opens detached, so a bare `attach` lands on whichever window is current). Sami may attach and
+opens detached, so a bare `attach` lands on whichever window is current). The operator may attach and
 type into this session at any time. The pane carries no GitHub credential: its GitHub token
 variables are emptied, and both `legion gh -- <args>` and `legion threads resolve` are refused.
 The controller reads Dispatch and applies its controller capability with `legion status <KEY>

package/skills/legion-retro/SKILL.md

@@ -29,9 +29,8 @@ retrospective's durable output.
    role when configured. A human merges under the repository's GitHub branch-protection and
    CODEOWNERS requirements; GitHub's merge queue participates only when the repository enables it.
 5. After that merge, the implementer — not the reviewer or merger — verifies the change in production
-   and records it on the PR and the issue (Sami, 2026-09-13, verbatim:
-   "the agent that developed it should be responsible for testing in production"). The
-   architect's sign-off waits for that record.
+   and records it on the PR and the issue: the agent that developed it is responsible for testing
+   in production. The architect's sign-off waits for that record.
    The record is the pull request's `Production:` line, one pull-request comment, and a
    `dispatch_message` on the issue, each naming what was driven, how, what was observed, and the
    merge commit. A defect the production check finds becomes a corrective child issue of the same tree,