@sjawhar/opencode-legion-envoy 8.30.2 → 8.31.0

package/dist/dispatch.js

@@ -14026,6 +14026,7 @@ var SEARCH_QUERY_HINT = "search with a short phrase of a few words, not a passag
 var SEARCH_KIND_DEPTH = 100;
 var PROJECT_KEY_PATTERN = /^[A-Z][A-Z0-9]{1,9}$/;
 var PROJECT_KEY_RULE = "an uppercase letter, then 1 to 9 uppercase letters or digits, such as CORE";
+var ARCHITECTURE_SOURCE_REPO_PATTERN = /^[A-Za-z0-9-]+\/(?!\.\.?$)[A-Za-z0-9._-]+$/;
 var ISSUE_STATUSES = [
   "triage",
   "icebox",
@@ -14391,7 +14392,7 @@ var dispatchToolSpecs = [
   {
     name: "dispatch_issues",
     example: { project: "PROJ", 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, progress (its spec's task-list items and " + "its direct children, each done of total, as `tasks 3/7 \xB7 children 2/5`, each only when it has " + "any), 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.",
+    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, progress (its spec's task-list items and " + "its direct children, each done of total, as `tasks 3/7 \xB7 children 2/5`, each only when it has " + "any), 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. " + "all takes the whole filtered list in one read instead, for a caller that must not miss or " + "repeat a row while other writers change the list, and especially for one whose own writes " + "move issues out of what it filtered on.",
     arguments: (z2) => ({
       project: z2.string().describe("Project key to list issues from."),
       status: z2.enum(ISSUE_STATUSES).describe("Optional lifecycle status filter.").optional(),
@@ -14401,7 +14402,8 @@ var dispatchToolSpecs = [
       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: 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()
+      offset: z2.number({ int: true, min: 0 }).describe("Rows to skip before the page; nonnegative integer; default 0.").optional(),
+      all: z2.boolean().describe("Take every matching issue in one unpaged read, so no row is missed or repeated while " + "the list changes. Refused with limit or offset.").optional()
     })
   },
   {
@@ -14423,11 +14425,19 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_architecture_sync",
-    example: { project: "CORE" },
-    description: "Import a project's architecture model from its configured source repository now, instead of " + "waiting for the server's five-minute schedule. Returns the imported commit and component " + "count, or the recorded error when the model was rejected (the previous model stays up). " + "The source itself is configured by a human in Settings; 404 SOURCE_NOT_FOUND without one.",
+    example: { project: "CORE", repo: "acme/infra" },
+    description: "Import a project's architecture model from its source repositories now, instead of waiting " + "for the server's five-minute schedule. A project may have several sources, one per " + "repository, and its model is every source's components together. Without repo every " + "source imports and each answers on its own line; with repo only that source does. Each " + "line names the imported commit, or the recorded error when that source's model was " + "rejected (its previous components stay up, and every other source is untouched). Sources " + "are saved in Settings or with PUT /api/v1/projects/{key}/architecture-sources/{owner}/{repo}; " + "404 SOURCE_NOT_FOUND when the project has none, or none for that repository.",
     arguments: (z2) => ({
-      project: z2.string().describe("Project key whose architecture source to sync, such as CORE.")
+      project: z2.string().describe("Project key whose architecture sources to sync, such as CORE."),
+      repo: z2.string().describe("One source repository of the project to sync alone, owner/name; omit it to sync every source.").optional()
     }),
+    validation: {
+      check: (value) => {
+        const { repo } = value;
+        return typeof repo !== "string" || ARCHITECTURE_SOURCE_REPO_PATTERN.test(repo);
+      },
+      message: "repo is not a repository: give it as owner/name, such as acme/infra."
+    },
     strict: true
   },
   {
@@ -14805,9 +14815,8 @@ function parseCommand(argv, io) {
     const token = rest[index];
     if (!token.startsWith("--")) {
       if (ISSUE_KEY.test(token) && surface.flags.has("--issue") && !setBy.has("issue")) {
-        const corrected = [command, ...rest.slice(0, index), "--issue", token];
-        corrected.push(...rest.slice(index + 1));
-        problems.push(`unexpected argument ${token}: use --issue <KEY>, as in: dispatch ${corrected.map(quoteWord).join(" ")}`);
+        if (claim("issue", "--issue", false))
+          args.issue = token;
         continue;
       }
       problems.push(`unexpected argument ${quoteWord(token)}: every value follows its flag`);
@@ -15164,6 +15173,9 @@ function asErrorShape(value) {
 function isJson(response) {
   return response.headers.get("content-type")?.includes("application/json") ?? false;
 }
+function isNoRoute(error48) {
+  return error48 instanceof DispatchServiceError && error48.status === 404 && error48.code === "NOT_FOUND" && error48.message.startsWith("no route for ");
+}
 var ISSUE_EVENTS_PAGE_MAX = 200;
 var DISPATCH_TOOL_DEADLINE_MS = 60000;
 function requestSignal(signal) {
@@ -15191,6 +15203,18 @@ function whyNotAPage(answer) {
   }
   return `${what}. Retrying will not help: the same request gets the same answer until that ` + "Dispatch is upgraded or fixed.";
 }
+function whyNotAnArray(answer) {
+  if (typeof answer === "string")
+    return `text that is not JSON, ${GATEWAY_PAGE}, so a retry may succeed`;
+  if (answer === null)
+    return "null";
+  if (typeof answer !== "object")
+    return `a ${typeof answer}`;
+  if ("issues" in answer && Array.isArray(answer.issues)) {
+    return "a page, so this Dispatch pages a request that carries no limit and no offset";
+  }
+  return "an object that is not the listing";
+}
 var GATEWAY_PAGE = "which looks like a proxy or gateway page rather than Dispatch's own answer";
 function gatewayAdvice(method, status) {
   if (!transientStatus(status)) {
@@ -15266,6 +15290,14 @@ class DispatchClient {
       return answer;
     throw new Error(`GET ${this.#url(path, query)} asked for a page ({issues, total, limit, offset}) and got ` + refusal);
   }
+  async listAllIssues(options) {
+    const path = ["api", "v1", "issues"];
+    const query = { ...options };
+    const answer = await this.#json("GET", path, undefined, query);
+    if (Array.isArray(answer))
+      return answer;
+    throw new Error(`GET ${this.#url(path, query)} asked for the unpaged listing and got ${whyNotAnArray(answer)}.`);
+  }
   async listProjectArtifacts(project, unlinked = false) {
     return this.#json("GET", ["api", "v1", "projects", project, "artifacts"], undefined, unlinked ? { unlinked: "true" } : undefined);
   }
@@ -15354,19 +15386,69 @@ class DispatchClient {
   async listProjects() {
     return this.#json("GET", ["api", "v1", "projects"]);
   }
-  async syncArchitectureSource(project) {
-    return this.#json("POST", ["api", "v1", "projects", project, "architecture-source", "sync"]);
-  }
-  async getArchitectureSource(project) {
+  async listArchitectureSources(project) {
     try {
-      return await this.#json("GET", ["api", "v1", "projects", project, "architecture-source"]);
+      return await this.#json("GET", ["api", "v1", "projects", project, "architecture-sources"]);
+    } catch (error48) {
+      if (!isNoRoute(error48))
+        throw error48;
+    }
+    try {
+      const source = await this.#json("GET", [
+        "api",
+        "v1",
+        "projects",
+        project,
+        "architecture-source"
+      ]);
+      return source === null ? [] : [source];
     } catch (error48) {
       if (error48 instanceof DispatchServiceError && error48.status === 404 && error48.code === "SOURCE_NOT_FOUND") {
-        return null;
+        return [];
       }
       throw error48;
     }
   }
+  async syncArchitectureSources(project) {
+    try {
+      return await this.#json("POST", [
+        "api",
+        "v1",
+        "projects",
+        project,
+        "architecture-sources",
+        "sync"
+      ]);
+    } catch (error48) {
+      if (!isNoRoute(error48))
+        throw error48;
+    }
+    const source = await this.#json("POST", [
+      "api",
+      "v1",
+      "projects",
+      project,
+      "architecture-source",
+      "sync"
+    ]);
+    return [source];
+  }
+  async syncArchitectureSource(project, repo2) {
+    const [owner, name, ...rest] = repo2.split("/");
+    if (!owner || !name || rest.length > 0) {
+      throw new Error(`repository must be owner/name, got ${JSON.stringify(repo2)}`);
+    }
+    return this.#json("POST", [
+      "api",
+      "v1",
+      "projects",
+      project,
+      "architecture-sources",
+      owner,
+      name,
+      "sync"
+    ]);
+  }
   async resolveAsk(id, input) {
     return this.#json("POST", ["api", "v1", "asks", id, "resolve"], input);
   }
@@ -16445,14 +16527,31 @@ async function architectureGuidance(client, project, components) {
   if (components.mode === "none" || components.ids.length > 0)
     return;
   try {
-    if (await client.getArchitectureSource(project) === null) {
+    if ((await client.listArchitectureSources(project)).length === 0)
       return;
-    }
     return `Project ${project} has an architecture model, but this issue is not linked to any of its current components. ${architectureComponentsAction}`;
   } catch (error48) {
     return `Could not check whether project ${project} has an architecture model: ${messageFor(error48)}. ${architectureComponentsAction}`;
   }
 }
+function architectureSyncLines(project, source) {
+  if (source.last_error === null) {
+    return `Synced ${project} architecture from ${source.repo}@${source.branch}: commit ${source.last_commit ?? "unknown"} (${source.last_sync_at ?? "unknown time"}).`;
+  }
+  let kept;
+  if (source.last_commit !== null) {
+    kept = `The previous model of ${source.repo} stays up (commit ${source.last_commit}).`;
+  } else if (source.components > 0) {
+    kept = `The previous model of ${source.repo} stays up (${source.components} ${source.components === 1 ? "component" : "components"}).`;
+  } else {
+    kept = `No model has ever imported from ${source.repo}.`;
+  }
+  return [
+    `Sync failed for ${project} (${source.repo}@${source.branch}): ${source.last_error}`,
+    kept
+  ].join(`
+`);
+}
 function isDuplicateCandidate(value) {
   if (typeof value !== "object" || value === null)
     return false;
@@ -16696,6 +16795,18 @@ function argumentProblems(tool, args) {
       }
       break;
     }
+    case "dispatch_issues": {
+      if (optionalBoolean(args, "all") === true) {
+        const paging = [
+          ...optionalNumber(args, "limit") === undefined ? [] : ["--limit"],
+          ...optionalNumber(args, "offset") === undefined ? [] : ["--offset"]
+        ];
+        if (paging.length > 0) {
+          problems.push(`--all takes every matching issue in one unpaged read, so it cannot be combined with ${paging.join(" or ")}: name --all on its own, or page with --limit and --offset`);
+        }
+      }
+      break;
+    }
   }
   return problems;
 }
@@ -18013,7 +18124,7 @@ async function executeDispatchTool(input) {
       const priority = optionalPriorityFilter(args, "priority");
       const updatedSince = optionalString(args, "updated_since");
       const routeStatus = optionalString(args, "route_status");
-      const page = await client.listIssuePage({
+      const filters = {
         project,
         ...status === undefined ? {} : { status },
         ...parent === undefined ? {} : { parent },
@@ -18021,7 +18132,13 @@ async function executeDispatchTool(input) {
         ...priority === undefined ? {} : { priority },
         ...updatedSince === undefined ? {} : { updated_since: updatedSince },
         ...routeStatus === undefined ? {} : { route_status: routeStatus }
-      }, {
+      };
+      const page = optionalBoolean(args, "all") === true ? await client.listAllIssues(filters).then((issues) => ({
+        issues,
+        total: issues.length,
+        limit: issues.length,
+        offset: 0
+      })) : await client.listIssuePage(filters, {
         limit: optionalNumber(args, "limit") ?? DEFAULT_ISSUE_PAGE_LIMIT,
         offset: optionalNumber(args, "offset") ?? 0
       });
@@ -18083,20 +18200,19 @@ async function executeDispatchTool(input) {
     }
     case "dispatch_architecture_sync": {
       const project = stringArg(args, "project");
-      const source = await client.syncArchitectureSource(project);
-      const at = source.last_sync_at ?? "unknown time";
+      const repo2 = optionalString(args, "repo");
+      const sources = repo2 === undefined ? await client.syncArchitectureSources(project) : [await client.syncArchitectureSource(project, repo2)];
       return {
-        text: source.last_error === null ? `Synced ${project} architecture from ${source.repo}@${source.branch}: commit ${source.last_commit ?? "unknown"} (${at}).` : [
-          `Sync failed for ${project} (${source.repo}@${source.branch}): ${source.last_error}`,
-          source.last_commit === null ? "No model has ever imported for this project." : `The previous model stays up (commit ${source.last_commit}).`
-        ].join(`
+        text: sources.map((source) => architectureSyncLines(project, source)).join(`
 `),
         details: {
           project,
-          repo: source.repo,
-          branch: source.branch,
-          commit: source.last_commit,
-          error: source.last_error
+          sources: sources.map((source) => ({
+            repo: source.repo,
+            branch: source.branch,
+            commit: source.last_commit,
+            error: source.last_error
+          }))
         }
       };
     }

package/dist/src/server.js

@@ -13883,6 +13883,7 @@ var SEARCH_QUERY_HINT = "search with a short phrase of a few words, not a passag
 var SEARCH_KIND_DEPTH = 100;
 var PROJECT_KEY_PATTERN = /^[A-Z][A-Z0-9]{1,9}$/;
 var PROJECT_KEY_RULE = "an uppercase letter, then 1 to 9 uppercase letters or digits, such as CORE";
+var ARCHITECTURE_SOURCE_REPO_PATTERN = /^[A-Za-z0-9-]+\/(?!\.\.?$)[A-Za-z0-9._-]+$/;
 var ISSUE_STATUSES = [
   "triage",
   "icebox",
@@ -14248,7 +14249,7 @@ var dispatchToolSpecs = [
   {
     name: "dispatch_issues",
     example: { project: "PROJ", 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, progress (its spec's task-list items and " + "its direct children, each done of total, as `tasks 3/7 \xB7 children 2/5`, each only when it has " + "any), 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.",
+    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, progress (its spec's task-list items and " + "its direct children, each done of total, as `tasks 3/7 \xB7 children 2/5`, each only when it has " + "any), 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. " + "all takes the whole filtered list in one read instead, for a caller that must not miss or " + "repeat a row while other writers change the list, and especially for one whose own writes " + "move issues out of what it filtered on.",
     arguments: (z2) => ({
       project: z2.string().describe("Project key to list issues from."),
       status: z2.enum(ISSUE_STATUSES).describe("Optional lifecycle status filter.").optional(),
@@ -14258,7 +14259,8 @@ var dispatchToolSpecs = [
       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: 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()
+      offset: z2.number({ int: true, min: 0 }).describe("Rows to skip before the page; nonnegative integer; default 0.").optional(),
+      all: z2.boolean().describe("Take every matching issue in one unpaged read, so no row is missed or repeated while " + "the list changes. Refused with limit or offset.").optional()
     })
   },
   {
@@ -14280,11 +14282,19 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_architecture_sync",
-    example: { project: "CORE" },
-    description: "Import a project's architecture model from its configured source repository now, instead of " + "waiting for the server's five-minute schedule. Returns the imported commit and component " + "count, or the recorded error when the model was rejected (the previous model stays up). " + "The source itself is configured by a human in Settings; 404 SOURCE_NOT_FOUND without one.",
+    example: { project: "CORE", repo: "acme/infra" },
+    description: "Import a project's architecture model from its source repositories now, instead of waiting " + "for the server's five-minute schedule. A project may have several sources, one per " + "repository, and its model is every source's components together. Without repo every " + "source imports and each answers on its own line; with repo only that source does. Each " + "line names the imported commit, or the recorded error when that source's model was " + "rejected (its previous components stay up, and every other source is untouched). Sources " + "are saved in Settings or with PUT /api/v1/projects/{key}/architecture-sources/{owner}/{repo}; " + "404 SOURCE_NOT_FOUND when the project has none, or none for that repository.",
     arguments: (z2) => ({
-      project: z2.string().describe("Project key whose architecture source to sync, such as CORE.")
+      project: z2.string().describe("Project key whose architecture sources to sync, such as CORE."),
+      repo: z2.string().describe("One source repository of the project to sync alone, owner/name; omit it to sync every source.").optional()
     }),
+    validation: {
+      check: (value) => {
+        const { repo } = value;
+        return typeof repo !== "string" || ARCHITECTURE_SOURCE_REPO_PATTERN.test(repo);
+      },
+      message: "repo is not a repository: give it as owner/name, such as acme/infra."
+    },
     strict: true
   },
   {
@@ -15232,7 +15242,7 @@ var envoyToolSpecs = [
   },
   {
     name: "envoy_publish",
-    description: `Publish an Envoy message to a notifications. topic. A role or built-in topic is delivered as its guide says; any other notifications. topic you name (a team topic such as notifications.team.deploy-squad.all) is live only: it reaches every subscribed session that holds its own NATS connection, yours included, and is not retained. A session the listener delivers to over a serve port, such as an OpenCode agent, receives nothing on such a topic and is told nothing (dispatch://INFRA-122). ${DELIVERY_CONTRACT}`,
+    description: `Publish an Envoy message to a notifications. topic. A role or built-in topic is delivered as its guide says; any other notifications. topic you name (a team topic such as notifications.team.deploy-squad.all) is live only: it reaches every session subscribed to it when you publish, and is not retained. A session that holds its own NATS connection receives it directly, yours included; a session the listener delivers to over a serve port, such as an OpenCode agent, receives it through its machine's listener when that listener subscribes to every topic (ENVOY_SUBSCRIBE_ALL_TOPICS=1; the shared hub's listener does not). ${DELIVERY_CONTRACT}`,
     arguments: (schema) => ({ topic: schema.string(), ...messageArguments(schema) }),
     operation: EnvoyToolOperation.publish
   },

package/package.json

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

package/skills/dispatch/SKILL.md

@@ -136,7 +136,7 @@ EOF
 
 - Attach every architectural issue to the components it changes. Attach the root before you decompose it: children inherit.
 - `--components-json '{"mode":"explicit","ids":["web"]}'`, `'{"mode":"none","reason":"hiring, not code"}'` (only for non-architectural work, with a concrete reason), or `'{"mode":"inherit"}'`.
-- Component ids: each non-external `components[].id` from `GET /api/v1/projects/{key}/architecture`, or the file names under `.dispatch/architecture/` in its source repository. Others are refused `COMPONENTS_INPUT`. A closed issue can be classified without reopening.
+- Component ids: each non-external `components[].id` from `GET /api/v1/projects/{key}/architecture`, or the file names under `.dispatch/architecture/` in any of the project's source repositories. A project may import from several; ids are project-wide, so one issue can name components of different sources. Others are refused `COMPONENTS_INPUT`. A closed issue can be classified without reopening.
 - Change code and `.dispatch/architecture/<id>.md` in the same review. A stale model: `dispatch architecture-sync` ([issues.md](skill://dispatch/references/issues.md#syncing-a-projects-architecture-model)).
 
 ## Close what you opened

package/skills/dispatch/references/issues.md

@@ -63,4 +63,4 @@ As a surface's owner, run `dispatch issues --project <KEY> --priority 0 --priori
 
 ## Syncing a project's architecture model
 
-`dispatch architecture-sync --project CORE` imports the model now. It prints the commit, or the error, and keeps the old model. No source configured answers `SOURCE_NOT_FOUND`.
+A project imports its model from one or more source repositories, each on its own branch. `dispatch architecture-sync --project CORE` imports every source now and prints a line for each: `Synced CORE architecture from <repo>@<branch>: commit <sha> (<time>).`, or `Sync failed for CORE (<repo>@<branch>): <error>` followed by what of that source still shows: its commit, its component count when the source was re-saved on another branch and has not imported from it yet, or that none ever imported. A failed source keeps its previous components; every other source is untouched. `--repo <owner/name>` imports that one source alone. No source configured, or no source from that repository, answers `SOURCE_NOT_FOUND`. A credential or branch problem is that source's failed line, or with `--repo` an error, `SOURCE_ACCESS`.

package/skills/envoy/SKILL.md

@@ -66,6 +66,6 @@ Every topic starts with `notifications.`.
 
 - Send to one session with `envoy_send`, to the one session that holds a named duty with a role, and to a group with a team topic.
 - Publish to a role with `envoy_publish(topic="notifications.role.<role>", ...)`; never subscribe to a role topic, because the listener forwards a role message to its holder only. A publish returns the live `holder`; an unheld role returns an error. `envoy_role_get(role=...)` finds the holder first.
-- For a team, the group subscribes to `notifications.team.<name>.>`, and any member publishes to `notifications.team.<name>.all`. Envoy treats any other `notifications.` topic that no source in the table uses the same way. It reaches only the sessions subscribed when it is published (yours too, when you subscribe), and is not kept for a session that subscribes later. A topic outside `notifications.` is refused.
+- For a team, the group subscribes to `notifications.team.<name>.>`, and any member publishes to `notifications.team.<name>.all`. Envoy treats any other `notifications.` topic that no source in the table uses the same way. It reaches only the sessions subscribed when it is published (yours too, when you subscribe, unless you are a serve-port session, which receives it only through a listener run with `ENVOY_SUBSCRIBE_ALL_TOPICS=1` and never its own publish), and is not kept for a session that subscribes later. A topic outside `notifications.` is refused.
 - How a role claim survives a resume, a fork or a dead process: `skill://envoy/references/roles.md`.
 - In a Legion pane, the plugin claims your role at session start; read `skill://envoy/references/legion.md` before you claim, release or publish to a role, or answer a role delivery failure there.

package/skills/envoy/references/deliveries.md

@@ -54,7 +54,7 @@ envoy:
 It depends on where a session takes its deliveries, not on whether the topic is built in or your own.
 
 - A session that holds its own NATS connection (every Oh My Pi session, and a Claude Code one) receives every message published on a subject it subscribes to, whoever sent it: its own publish included, and a subagent's publish to a topic the parent subscribes to. This holds for a topic the stream keeps and for a live team topic alike.
-- A session the listener delivers to by push, over a serve port (such as the OpenCode plugin), does not receive its own publish, and receives no team topic at all, since it holds no NATS subscription of its own.
+- A session the listener delivers to by push, over a serve port (such as the OpenCode plugin), does not receive its own publish, and receives a team topic only through the listener that owns it when that listener runs with `ENVOY_SUBSCRIBE_ALL_TOPICS=1` (the shared hub's listener does not).
 - A role is not a subject its holder subscribes to: the listener finds the live holder and forwards the message to it, and drops the message when that holder is the message's source session.
 
 ## Listener API errors

package/skills/legion-architect/references/acceptance.md

@@ -120,8 +120,9 @@ The merge closes the issue: when GitHub reports the pull request merged while th
   `pr-merged` notice names what it waits for and none follows as they depart, so read the pull
   request on GitHub.
 - A child's close reaches you as `child-closed`. The daemon retires five of its six claims and
-  suspends its implementer, session and volume kept, because it still owes the production check
-  (`skill://legion-worker/references/merge-gate.md`, *The production check after the close*).
+  leaves the implementer running, because it still owes the production check. When the issue's
+  pod and Sandbox go is in `skill://legion-worker/references/merge-gate.md`, *The production check
+  after the close*.
 - A root's close writes `done`, frees the tree's admission slot and lingers the tree for
   `linger_hours` with every member suspended. The linger's end, the tree's last step, waits until
   every member's open production check has closed.

package/skills/legion-architect/references/decomposition.md

@@ -61,17 +61,21 @@ repositories with your gh's read-only access (`-R owner/repo`).
 
 ## Architecture components
 
-A project's architecture source is the repository whose `.dispatch/architecture/` files Dispatch
-imports as its components (`skill://dispatch`, "Architecture components").
+A project's architecture sources are the repositories whose `.dispatch/architecture/` files
+Dispatch imports as its components (`skill://dispatch`, "Architecture components").
 
 - **The components exist:** attach the root before you decompose, so every child inherits it:
   `dispatch issue-update --issue <root> --components-json '{"mode":"explicit","ids":[…]}'`.
 - **They do not exist yet (bootstrap):** in the root's first PR (the implement worker pushes it),
   write `.dispatch/architecture/<id>.md` files for the planned components — front matter `title`,
-  `parent`, `depends_on`, `external`; no `paths` yet. The importer reads the source branch's head,
-  so leave the root on `inherit` until that PR has merged: an attach before then answers
+  `parent`, `depends_on`, `external`; no `paths` yet. A project may have several sources, one per
+  repository, and its model is all of their components together: the file goes in the branch of
+  the source whose repository holds it, `parent` and `depends_on` name components of that same
+  source only, and its id must be one no other source of the project uses (a repeated id fails that
+  source's import, naming the repository that has it). The importer reads the source branch's
+  head, so leave the root on `inherit` until that PR has merged: an attach before then answers
   `400 COMPONENTS_INPUT`, since the component does not exist. After the merge, run
-  `dispatch architecture-sync --project <KEY>` and attach the root; children created before then
-  inherit it.
+  `dispatch architecture-sync --project <KEY>` (every source; `--repo <owner/name>` syncs that one
+  alone) and attach the root; children created before then inherit it.
 - Give a child its own `--components-json` only when it changes a narrower set, and
   `{"mode":"none","reason":"…"}` when it changes no code or file a component describes.

package/skills/legion-worker/SKILL.md

@@ -11,7 +11,7 @@ You work one phase of one issue in a jj workspace every role of the issue shares
 
 ## Every phase, in this order
 
-1. **Read first.** Read the issue, then each committed handoff before your phase, with `read` from `$LEGION_WORKSPACE/.legion/<issue>/`, in order: `plan.json`, `implement.json`, `test.json`, `review.json`. Where one disagrees with your memory or a transcript, the file wins: it is the copy that survived. At each later assignment read them again, your own included, since other phases may have committed since. After a `Your workspace was recreated…` message, read `.legion/<issue>/workspace-recovered.json` too, once.
+1. **Read first.** Read the issue, then each committed handoff before your phase, with `read` from `$LEGION_WORKSPACE/.legion/<issue>/`, in order: `plan.json`, `implement.json`, `test.json`, `review.json`. Where one disagrees with your memory or a transcript, the file wins: it is the copy that survived. At each later assignment read them again, your own included, since other phases may have committed since. After a `Your workspace was recreated…` message, anything unpushed is gone, and no file in the workspace says so.
 2. **Commit only your phase's work**, with `jj -R "$LEGION_WORKSPACE" split -m "<message>" <paths…>`, each commit holding only your phase's paths, so the next phase sees what you changed.
 3. **Put back what you copied in.** Before you write the handoff, run `jj -R "$LEGION_WORKSPACE" status` and remove or restore every file you copied or fetched in that is not your phase's work, such as another branch's test rig. With jj the working copy is the commit: the next role's first commit builds on what you left, and its push ships it.
 4. **Write the handoff** your role prompt names. Each `proof` entry, the implementer's or the tester's, is an object of six non-empty strings: `criterion` (the acceptance line it proves), `surface` (where a user reaches the change), `command`, `observed`, `headSha` (the commit it ran at) and `negativeControl` (a deliberately broken input and the refusal seen); `skill://legion-worker/references/pr-body.md#what-a-proof-is` defines each. To add to a handoff already on disk, `read` it, edit it, and `write` it whole with `completed` set to now.

package/skills/legion-worker/references/merge-gate.md

@@ -251,16 +251,17 @@ reviewing until you finish.
     topic, and file no issue. It names this issue, the pull request, the merge commit, what you
     drove and what failed. Name the ask (`dispatch://<REPORT KEY>/ask/<id>`) in the `Production:`
     line and in the summary.
-- **Nothing waits in the session for a deploy.** A `pending` ends the look: the daemon suspends
-  your claim with its session and the issue's volume kept, the pod goes, and the daemon wakes the
-  check (the pod comes back and your session resumes with a new check task) on Dispatch's
+- **Nothing waits in the session for a deploy.** A `pending` ends the look. Where no wake is
+  queued yet, the daemon suspends your claim with its session kept, and the issue's Sandbox goes
+  with its pod and disk; where a wake arrived while the look was open, the next look starts at once
+  on the same pod. Either way the daemon wakes the check (after a suspension a new pod comes back
+  on a fresh disk, and your session resumes with a new check task) on Dispatch's
   `issue.deployed` event for the pull request; when the project's `legion.yaml` names the
   repository's deploy workflow (`projects.<KEY>.deploys`), at each completed run of that workflow
   on the default branch whose named step (such as `Apply`) succeeded after the merge, once per such
   job; or, for `sjawhar/legion`, on a Legion daemon's boot on a build containing the merge, on
   Dispatch's `server.started` naming such a build, or on the build the daemon read from Dispatch at
-  its boot. A wake while a look is open is kept, and a `pending` then starts the next look at once.
-  The woken look's task names the event (`Dispatch's issue.deployed: run <id> completed <t>`,
+  its boot. The woken look's task names the event (`Dispatch's issue.deployed: run <id> completed <t>`,
   `the deploy workflow's run: <repo> <workflow> run <id> attempt <n>, job <job name>: <step> succeeded at <t>`,
   `the Legion daemon's boot on build <sha>`, `Dispatch's start on build <sha>`,
   `Dispatch's build <sha>`), and its `Production:` line names it too, so the pull request carries
@@ -279,5 +280,6 @@ reviewing until you finish.
   on a closed issue (`ISSUE_CLOSED`), so the deployment instructions' "on the pull request and the
   issue" is the pull request for a closed issue, and a defect reaches Dispatch as the ask above.
   The architect accepted the issue before the merge and is asked nothing after it. `pass` or
-  `fail` closes the check: your claim is retired and, for a child, the issue's Sandbox and volume
-  are released.
+  `fail` closes the check: your claim is retired and the issue's Sandbox goes with its pod and
+  disk, for a root as for a child. Neither ending retires or suspends anything of an issue back in
+  the workflow (a root reopened inside its linger): its claim and pod are the new run's.

package/skills/legion-worker/references/tools.md

@@ -86,11 +86,11 @@ for it*.
 
 An install of your own — an interpreter, a browser, a second toolchain, an extraction prefix — is
 on the sanctioned side when both of these hold: what it writes lands on the issue's own volume,
-under `/legion`, which outlives the pod and is shared by the issue's roles — whether through a
-variable the runtime sets for you there or under a path on that volume your harness names
-itself — but outside the issue's workspace (`$LEGION_WORKSPACE`, under `/legion/workspaces`) and
-the runtime's own directories (`/legion/repos`, `/legion/feed`, `/legion/sessions`); and after
-the command exits nothing else resolves differently. The workspace is excluded because its jj
+under `/legion`, which outlives a role's relaunch in its pod and is shared by the issue's roles —
+whether through a variable the runtime sets for you there or under a path on that volume your
+harness names itself — but outside the issue's workspace (`$LEGION_WORKSPACE`, under
+`/legion/workspaces`) and the runtime's own directories (`/legion/repos`, `/legion/feed`); and
+after the command exits nothing else resolves differently. The workspace is excluded because its jj
 working copy tracks every new file under jj's `snapshot.max-new-file-size` (1 MiB in a role
 container), so a root written there is added to the change every role shares, and a larger new
 file is left untracked, every jj command in the workspace then warning `Refused to snapshot some
@@ -122,7 +122,7 @@ What each shape leaves resolving:
   all. `uv sync` or `bun install` in your workspace materialises what that project already
   declares, into that project's own directory, which a process reaches by asking for that project
   and no other way — and the runtime puts `UV_PYTHON_INSTALL_DIR` and the workspace itself on the
-  issue's volume exactly so a later pod reuses it.
+  issue's volume exactly so every role of the issue's pod reuses it.
 - An extraction prefix: whatever you leave resolving through it, which is yours to decide. Unpack
   Debian packages under `$HOME`, export `LD_LIBRARY_PATH` in the shell you go on working in, and
   you change what every later command in that shell — and every subagent that inherits the
@@ -147,8 +147,8 @@ toolchain — is where the first condition does the work. `uv run --with pyyaml=
 passes both: the wheel lands in `UV_CACHE_DIR`, under `wheels-v6/pypi/pyyaml/6.0.2-…`, and
 `UV_PYTHON_INSTALL_DIR` is never created, because the image's own `python3` served the run. The
 interpreter is the other run: a project whose `.python-version` names an interpreter uv must fetch
-puts about 70 MB under `UV_PYTHON_INSTALL_DIR`, where the issue's next pod finds it, while the
-cache holds no wheel. A browser download passes too, and for Playwright — the browser driver this
+puts about 70 MB under `UV_PYTHON_INSTALL_DIR`, where every role of the issue's pod finds it, while
+the cache holds no wheel. A browser download passes too, and for Playwright — the browser driver this
 repository's own Dispatch suite installs (`playwright install`, `packages/dispatch`'s
 `e2e:install`) — it passes as it stands, with nothing pointed anywhere: playwright-core resolves
 its browser registry under `XDG_CACHE_HOME`, which the runtime has already put on the issue's
@@ -164,11 +164,13 @@ here) at a directory under one of the paths above yourself, since an unset one l
 wherever the tool defaults, which is nowhere this runtime chose.
 
 Where it lands is what you pay. Under one of those variables it is on the issue's volume: it
-outlives the pod, and every role of the issue shares it — under every one of those variables but
-`XDG_STATE_HOME`, which is `/legion/scratch/state/<role>`, "the one directory of the issue's
-scratch that is the role's own rather than the issue's" (`roleEnvironment`), because Oh My Pi
-names its browser broker's lock from the state root and an abstract socket name is one name across
-every container of the pod — and a later pod of the issue reuses it. Under `$HOME` —
+outlives a role's relaunch in its pod, and every role of the issue shares it — under every one of
+those variables but `XDG_STATE_HOME`, which is `/legion/scratch/state/<role>`, "the one directory
+of the issue's scratch that is the role's own rather than the issue's" (`roleEnvironment`),
+because Oh My Pi names its browser broker's lock from the state root and an abstract socket name
+is one name across every container of the pod — though not the pod itself: the issue's disk is
+the pod's own and is deleted with it, so a later pod of the issue starts without it. Under
+`$HOME` —
 `/home/legion`, which no volume is mounted on — it is the container's own filesystem: one copy per
 role, per pod, gone when the role relaunches, and charged to the container's ephemeral-storage
 limit, which is per role and smaller than the volume. Moving exactly these writes off that
@@ -178,7 +180,7 @@ under `$HOME` fails the first condition and is outside the sanctioned form, howe
 changes. The three artefacts above are the whole of that line's ground. Disk is not: every cache is
 already relocated onto the issue's volume, which has the room for them (`docs/kubernetes.md`, "The
 tools a role's own work needs", carries the figure), and a sanctioned install is paid once per
-issue, on the issue's own disk, by the issue's roles together.
+issue pod, on the issue's own disk, by the issue's roles together.
 
 **The worked case, and the one a role actually meets: the Dispatch e2e stack.** A change to
 `packages/dispatch` is proved by driving its browser suite, which needs a Postgres with pgvector;