@sjawhar/opencode-legion-envoy 1.37.0 → 1.38.1

package/dist/src/server.js

@@ -13552,6 +13552,7 @@ function date4(params) {
 // ../../node_modules/.bun/zod@4.3.6/node_modules/zod/v4/classic/external.js
 config(en_default());
 // ../contracts/src/dispatch-api.ts
+var ASK_TURNS = ["human", "agent"];
 var DELIVERY_CAPABILITIES = ["aside", "btw", "steer"];
 var DispatchEventSchema = object({
   issue_key: string2().nullable(),
@@ -13632,8 +13633,8 @@ var CommentEventPayloadSchema = object({
   ask_id: string2().nullish(),
   ask_question: string2().optional(),
   ask_state: _enum2(["open", "answered", "resolved"]).optional(),
-  ask_waiting_on: _enum2(["human", "agent"]).optional(),
-  turn: _enum2(["human", "agent"]).nullish(),
+  ask_waiting_on: _enum2(ASK_TURNS).optional(),
+  turn: _enum2(ASK_TURNS).nullish(),
   anchor: object({ block_id: string2().nullable().optional(), quote: string2().optional() }).nullish(),
   suggestion: object({ replace_with: string2().optional() }).nullish(),
   author: object({ kind: string2(), id: string2() }).optional(),
@@ -13756,16 +13757,22 @@ function documentOwnerValidation(requireArtifact, alwaysRequireArtifact = false)
     message: alwaysRequireArtifact ? "Exactly one of issue and project is required; artifact or ref must name the document." : "Exactly one of issue and project is required; with project, artifact names the document."
   };
 }
-var commentValidation = (() => {
-  const owner = documentOwnerValidation(true);
-  return {
-    check: (value) => {
-      const input = value;
-      return owner.check(value) && (input.turn === undefined || typeof input.reply_to_ask === "string");
-    },
-    message: `${owner.message} turn requires reply_to_ask.`
-  };
-})();
+var commentOwner = documentOwnerValidation(true);
+var commentValidation = {
+  check: (value) => {
+    const input = value;
+    return commentOwner.check(value) && (input.turn === undefined || typeof input.reply_to_ask === "string");
+  },
+  message: `${commentOwner.message} turn requires reply_to_ask.`
+};
+var ISSUE_COMPONENTS_MODES = ["inherit", "explicit", "none"];
+function componentsArgument(z) {
+  return z.object({
+    mode: z.enum(ISSUE_COMPONENTS_MODES).describe("inherit: take the parent chain's attachment (the default; deletes this issue's own). explicit: attach to ids. none: not architectural work, with reason."),
+    ids: z.array(z.string({ min: 1 }), { min: 1, max: 50 }).describe("For mode explicit: bare component ids from the project's architecture model (web, dispatch-server), not external ones.").optional(),
+    reason: z.string({ min: 1 }).describe("For mode none: why this issue is not architectural (process, hiring, ops).").optional()
+  }).describe("Attach the issue to architecture components. Attach the root before decomposing it; children inherit unless they choose.");
+}
 var SPEC_SECTIONS = [
   "Summary",
   "Decisions needed",
@@ -13779,6 +13786,7 @@ var SPEC_SECTIONS = [
 ];
 var SPEC_WRITING_GUIDANCE = `When writing a spec, use these sections in order: ${SPEC_SECTIONS.join(", ")}. ` + "Write for a reader who has not seen the code: plain sentences, every identifier expanded on " + "first use, no coined shorthand; see skills/dispatch Writing for the human and Writing a spec.";
 var ASK_URGENCIES = ["low", "med", "high", "blocking"];
+var ASK_QUESTION_MAX = 800;
 var ISSUE_STATUSES = [
   "triage",
   "icebox",
@@ -13804,12 +13812,13 @@ var dispatchToolSpecs = [
       spec: z.string().describe(`Optional initial primary-document markdown. ${SPEC_WRITING_GUIDANCE}`).optional(),
       labels: z.array(z.string({ min: 1, max: 40 }), { max: 20 }).describe("Optional initial labels, at most 20 labels of up to 40 characters.").optional(),
       priority: z.number({ int: true, min: 0, max: 3 }).describe("Optional coarse priority: P0 is highest and P3 is lowest.").optional(),
-      assignee: z.string().describe("GitHub login of the human who answers this issue's asks; defaults to your owner when you act for a person, else the parent's assignee, else unassigned.").optional()
+      assignee: z.string().describe("GitHub login of the human who answers this issue's asks; defaults to your owner when you act for a person, else the parent's assignee, else unassigned.").optional(),
+      components: componentsArgument(z).optional()
     })
   },
   {
     name: "dispatch_issue_update",
-    description: "Update an existing issue: move its lifecycle status, retitle it, replace its labels, link a URL " + "(the pull request that delivers it, a run, a document), set its route, or set or clear its parent. " + "Status is one of " + `${ISSUE_STATUSES.join(", ")}; outside Legion, move it yourself as the work advances; inside ` + "Legion the daemon moves it. external_links are " + "merged into the issue's existing links by URL, so linking the pull request you just opened " + "keeps every earlier link. Priority is the human's and is not settable here. At least one " + `field besides issue is required. ${ISSUE_REFERENCE}`,
+    description: "Update an existing issue: move its lifecycle status, retitle it, replace its labels, link a URL " + "(the pull request that delivers it, a run, a document), set its route, set or clear its parent, " + "or attach it to architecture components. Status is one of " + `${ISSUE_STATUSES.join(", ")}; outside Legion, move it yourself as the work advances; inside ` + "Legion the daemon moves it. external_links are " + "merged into the issue's existing links by URL, so linking the pull request you just opened " + "keeps every earlier link. components replaces the issue's own attachment and is allowed on a " + "closed issue. Priority is the human's and is not settable here. At least one " + `field besides issue is required. ${ISSUE_REFERENCE}`,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE),
       status: z.enum(ISSUE_STATUSES).describe("New lifecycle status.").optional(),
@@ -13817,26 +13826,27 @@ var dispatchToolSpecs = [
       labels: z.array(z.string({ min: 1, max: 40 }), { max: 20 }).describe("Replacement label set, at most 20 labels of up to 40 characters; replaces every existing label.").optional(),
       external_links: z.array(z.string({ min: 1 })).describe("URLs to link; merged into the issue's existing external links by URL.").optional(),
       route: z.string().describe("Route the issue to role:<name> or session:<id>; an empty string clears it.").optional(),
-      parent: z.string().describe("Parent issue key in the same project; an empty string clears the parent.").optional()
+      parent: z.string().describe("Parent issue key in the same project; an empty string clears the parent.").optional(),
+      components: componentsArgument(z).optional()
     }),
     validation: {
       check: (value) => {
         const input = value;
-        return typeof input.status === "string" || typeof input.title === "string" || Array.isArray(input.labels) || Array.isArray(input.external_links) || typeof input.route === "string" || typeof input.parent === "string";
+        return typeof input.status === "string" || typeof input.title === "string" || Array.isArray(input.labels) || Array.isArray(input.external_links) || typeof input.route === "string" || typeof input.parent === "string" || typeof input.components === "object" && input.components !== null;
       },
-      message: "Issue update requires at least one field besides issue: status, title, labels, external_links, route, or parent."
+      message: "Issue update requires at least one field besides issue: status, title, labels, external_links, route, parent, or components."
     },
     strict: true
   },
   {
     name: "dispatch_ask",
-    description: "Open a durable, answerable decision on an issue or project document. Do not use it for a status update or discussion; " + "use dispatch_message instead. A to-do a human must complete is a question phrased as that to-do, with the options you want (for example Done / Can't). " + "Anchor a document question, thread reply_to/reply_to_ask, or cite a dispatch:// " + 'reference \u2014 it must be answerable from its own text and anchor alone, never "see above". A quote anchor is pinned to its block. Question is at most 800 ' + `characters and has at most 8 options. ${OWNER_REFERENCE}`,
+    description: "Open a durable, answerable decision on an issue or project document. Do not use it for a status update or discussion; " + "use dispatch_message instead. A to-do a human must complete is a question phrased as that to-do, with the options you want (for example Done / Can't). " + "Anchor a document question, thread reply_to/reply_to_ask, or cite a dispatch:// " + `reference \u2014 it must be answerable from its own text and anchor alone, never "see above". A quote anchor is pinned to its block. Question is at most ${ASK_QUESTION_MAX} ` + `characters and has at most 8 options. ${OWNER_REFERENCE}`,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
       project: z.string().describe("Project key owning the document.").optional(),
       artifact: z.string().describe("Project document artifact id, slug, or filename.").optional(),
       ref: z.string().describe("Optional dispatch:// reference (issue, document, message, or ask); appended to the question and rendered as a link.").optional(),
-      question: z.string({ max: 800 }).describe("Decision question, at most 800 characters."),
+      question: z.string({ max: ASK_QUESTION_MAX }).describe(`Decision question, at most ${ASK_QUESTION_MAX} characters.`),
       options: z.array(z.object({
         label: z.string().describe("Selectable option label."),
         description: z.string().describe("Optional option context.").optional()
@@ -13856,7 +13866,7 @@ var dispatchToolSpecs = [
     description: "Edit an open question in place. Use it to correct or refine the same decision; retract the " + "old ask and open a new one when the decision itself changes. Previous text remains in the " + "event log. Only the asking session can edit it; answered or resolved asks cannot be edited.",
     arguments: (z) => ({
       ask: z.string().describe("Ask id to edit."),
-      question: z.string({ max: 800 }).describe("Replacement decision question, at most 800 characters.").optional(),
+      question: z.string({ max: ASK_QUESTION_MAX }).describe(`Replacement decision question, at most ${ASK_QUESTION_MAX} characters.`).optional(),
       options: z.array(z.object({
         label: z.string().describe("Selectable option label."),
         description: z.string().describe("Optional option context.").optional()
@@ -14690,9 +14700,9 @@ import { resolve as resolvePath } from "path";
 
 // ../envoy-client/src/ask-answer.ts
 var HEAD_LENGTH = 120;
-function textHead(text, limit = HEAD_LENGTH) {
+function textHead(text) {
   const flat = text.replace(/\s+/g, " ").trim();
-  return flat.length > limit ? `${flat.slice(0, limit)}\u2026` : flat;
+  return flat.length > HEAD_LENGTH ? `${flat.slice(0, HEAD_LENGTH)}\u2026` : flat;
 }
 function askAnswerText(answer) {
   if (answer === null || answer === undefined)
@@ -15116,6 +15126,29 @@ class DispatchClient {
   }
 }
 
+// ../envoy-client/src/dispatch-owner.ts
+function documentLabel(project, slug) {
+  return `${project}/${slug}`;
+}
+function issueTopic(key) {
+  return { label: key, topic: dispatchIssueSubject(key, ">") };
+}
+function documentTopicOf(project, slug) {
+  return {
+    label: documentLabel(project, slug),
+    topic: dispatchDocumentSubject(project, slug, ">")
+  };
+}
+function dispatchIssueRef(key) {
+  return `dispatch://${key}`;
+}
+function dispatchDocumentRef(owner, slug) {
+  return `dispatch://${owner}/artifact/${slug}`;
+}
+function dispatchChildRef(ownerRef, kind, id) {
+  return `${ownerRef}/${kind}/${id}`;
+}
+
 // ../envoy-client/src/tool-input-errors.ts
 class ToolInputError extends Error {
   tool;
@@ -15227,14 +15260,8 @@ function formatZodIssues(issues, schema) {
 }
 
 // ../envoy-client/src/dispatch-execute.ts
-function issueTopic(key) {
-  return { label: key, topic: dispatchIssueSubject(key, ">") };
-}
 function documentTopic(artifact) {
-  return {
-    label: `${artifact.project}/${artifact.slug}`,
-    topic: dispatchDocumentSubject(artifact.project, artifact.slug, ">")
-  };
+  return documentTopicOf(artifact.project, artifact.slug);
 }
 function resolvedTopic(resolved) {
   if (resolved.owner.kind === "project")
@@ -15253,7 +15280,7 @@ function documentResultDetails(artifact) {
   return {
     project: artifact.project,
     artifact: artifact.id,
-    document: `${artifact.project}/${artifact.slug}`
+    document: documentLabel(artifact.project, artifact.slug)
   };
 }
 function writeResultDetails(resolved, fields) {
@@ -15264,15 +15291,15 @@ function writeResultDetails(resolved, fields) {
     throw new Error("issue document is missing its issue");
   return { issue: resolved.issue.key, ...fields };
 }
-async function askOwnerDetails(client, ask, resolved) {
+async function askOwnerDetails(client, ask, artifact) {
   if (ask.issue_key !== null) {
     return { issue: ask.issue_key, ask: ask.id };
   }
   if (ask.artifact_id === undefined || ask.artifact_id === null) {
     throw new Error("document ask is missing its artifact ID");
   }
-  const artifact = resolved?.artifact ?? await client.getArtifact(ask.artifact_id);
-  return { ...documentResultDetails(artifact), ask: ask.id };
+  const owner = artifact ?? await client.getArtifact(ask.artifact_id);
+  return { ...documentResultDetails(owner), ask: ask.id };
 }
 async function commentOwnerResult(client, comment, artifact) {
   if (comment.issue_key !== null) {
@@ -15283,12 +15310,12 @@ async function commentOwnerResult(client, comment, artifact) {
   }
   const owner = artifact ?? await client.getArtifact(comment.artifact_id);
   return {
-    label: documentTopic(owner).label,
+    label: documentLabel(owner.project, owner.slug),
     details: { ...documentResultDetails(owner), comment: comment.id }
   };
 }
-async function followedAskDetails(client, ask, resolved) {
-  return { ...await askOwnerDetails(client, ask, resolved), follows: { ask: ask.id } };
+async function followedAskDetails(client, ask, artifact) {
+  return { ...await askOwnerDetails(client, ask, artifact), follows: { ask: ask.id } };
 }
 var nativeIssueKeyPattern = /^[A-Z][A-Z0-9]{1,9}-[0-9]+$/;
 var externalIssueRefPattern = /^([^/\s]+)\/([^/\s#]+)#([1-9][0-9]*)$/;
@@ -15327,6 +15354,27 @@ function optionalNumber(args, name) {
   const value = args[name];
   return typeof value === "number" ? value : undefined;
 }
+function optionalComponents(args, name) {
+  const value = args[name];
+  if (typeof value !== "object" || value === null)
+    return;
+  const input = value;
+  return {
+    mode: input.mode,
+    ...input.ids === undefined ? {} : { ids: input.ids },
+    ...input.reason === undefined ? {} : { reason: input.reason }
+  };
+}
+function componentsChange(input, after) {
+  switch (input.mode) {
+    case "explicit":
+      return `components -> explicit [${after.ids.join(", ")}]`;
+    case "none":
+      return `components -> none (${after.reason ?? input.reason ?? ""})`;
+    case "inherit":
+      return "components -> inherit";
+  }
+}
 function isDuplicateCandidate(value) {
   if (typeof value !== "object" || value === null)
     return false;
@@ -15342,7 +15390,7 @@ function searchResultLine(result, baseUrl) {
   const href = new URL(result.href, baseUrl).toString();
   const { owner } = result;
   if (owner.kind === "document") {
-    const reference = `dispatch://${owner.project}/artifact/${owner.slug}`;
+    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}` : "";
@@ -15353,7 +15401,6 @@ function askUrgency(args) {
   const value = args.urgency;
   return ASK_URGENCIES.find((urgency) => urgency === value);
 }
-var maxAskQuestion16 = 800;
 function questionWithRef(question, ref) {
   return ref === undefined || question.includes(ref) ? question : `${question}
 
@@ -15363,7 +15410,7 @@ function askQuestionWithRef(args) {
   return questionWithRef(stringArg(args, "question"), optionalString(args, "ref"));
 }
 function askQuestionProblem(withRef) {
-  return withRef.length > maxAskQuestion16 ? `question plus ref ${overCapMessage(withRef.length, maxAskQuestion16)}; shorten the question or drop the ref` : undefined;
+  return withRef.length > ASK_QUESTION_MAX ? `question plus ref ${overCapMessage(withRef.length, ASK_QUESTION_MAX)}; shorten the question or drop the ref` : undefined;
 }
 function parseDispatchRef(ref) {
   const projectDocument = ref.match(/^dispatch:\/\/([A-Z][A-Z0-9]{1,9})\/artifact\/([^/@]+)(?:@v(\d+))?(?:\/(ask|comment)\/([^/]+))?$/);
@@ -15418,6 +15465,10 @@ function parseDispatchRef(ref) {
     return { owner, kind: "message", id: message };
   return { owner, kind: "issue", id: issue };
 }
+function refTarget(ref, kind, id) {
+  const ownerRef = ref.owner.kind === "issue" ? dispatchIssueRef(ref.owner.issue) : dispatchDocumentRef(ref.owner.project, `${ref.artifact}`);
+  return dispatchChildRef(ownerRef, kind, id);
+}
 var uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 var askIdProblem = "ask must be a bare ask id or a dispatch://.../ask/<id> reference";
 var commentIdProblem = "comment must be a bare comment id or a dispatch://.../comment/<id> reference";
@@ -15461,7 +15512,7 @@ function argumentProblems(tool, args) {
     case "dispatch_ask": {
       const question = optionalString(args, "question");
       const ref = optionalString(args, "ref");
-      if (question !== undefined && ref !== undefined && question.length <= maxAskQuestion16) {
+      if (question !== undefined && ref !== undefined && question.length <= ASK_QUESTION_MAX) {
         const problem = askQuestionProblem(questionWithRef(question, ref));
         if (problem !== undefined)
           problems.push(problem);
@@ -15551,11 +15602,17 @@ function dispatchRefFromUrl(value, serverUrl) {
 }
 var refGrammarProblem = "ref must be a valid dispatch:// reference such as dispatch://KEY-1, " + "dispatch://KEY-1/ask/<uuid>, dispatch://KEY-1/comment/<uuid>, " + "dispatch://KEY-1/message/<uuid>, dispatch://KEY-1/artifact/<slug>, or " + "dispatch://PROJECT/artifact/<document-ref> (an artifact id, slug, or filename); " + "a dashboard URL on this Dispatch server is accepted too";
 var ownerRequiredProblem = "issue is required; supply issue or set LEGION_ISSUE";
+var toolSchemas = new Map;
 function toolSchema(tool) {
+  const cached = toolSchemas.get(tool);
+  if (cached !== undefined)
+    return cached;
   const spec = dispatchToolSpecs.find((candidate) => candidate.name === tool);
   if (!spec)
     throw new Error(`Unknown Dispatch tool: ${tool}`);
-  return dispatchToolSchema(spec, zodSchemaApi(exports_external), { strict: true });
+  const schema = dispatchToolSchema(spec, zodSchemaApi(exports_external), { strict: true });
+  toolSchemas.set(tool, schema);
+  return schema;
 }
 async function resolveOwnerArguments(tool, input, cwd, env, exec, serverUrl, problems) {
   if (issueFreeTools[tool] === true)
@@ -15710,6 +15767,18 @@ function approvalLine(artifact) {
       return `Approval: changes requested on v${approval.version} by ${approval.by?.id ?? "unknown"}: ${approval.reason ?? ""}`;
   }
 }
+function componentsLine(components) {
+  const inherited = components.inherited_from === null ? "" : ` (inherited from ${components.inherited_from})`;
+  const retired = components.unknown.length === 0 ? "" : ` (retired: ${components.unknown.join(", ")})`;
+  switch (components.mode) {
+    case "explicit":
+      return `Components: ${components.ids.length === 0 ? "none live" : components.ids.join(", ")}${inherited}${retired}`;
+    case "none":
+      return `Components: none \u2014 ${components.reason ?? ""}${inherited}`;
+    case "inherit":
+      return "Components: unassigned";
+  }
+}
 function issueSummary(issue, events, references, graph) {
   const asks = issue.open_asks;
   const spec = issue.artifacts?.find((artifact) => artifact.primary);
@@ -15718,6 +15787,8 @@ function issueSummary(issue, events, references, graph) {
     throw new Error("Dispatch issue is missing priority");
   if (issue.assignee === undefined)
     throw new Error("Dispatch issue is missing assignee");
+  if (issue.components === undefined)
+    throw new Error("Dispatch issue is missing components");
   return [
     `Title: ${issue.title}`,
     `Key: ${issue.key}`,
@@ -15725,6 +15796,7 @@ function issueSummary(issue, events, references, graph) {
     `Assignee: ${issue.assignee ?? "unassigned"}`,
     ...issue.priority === null ? [] : [`Priority: P${issue.priority}`],
     `Labels: ${issue.labels.length === 0 ? "none" : issue.labels.join(", ")}`,
+    componentsLine(issue.components),
     `Route: ${issue.route ?? "none"}`,
     ...specApproval === undefined ? [] : [`Spec ${specApproval.replace(/^Approval/, "approval")}`],
     "Open asks:",
@@ -15748,11 +15820,21 @@ function referenceLines(edges) {
     return `- ${edge.kind} ${edge.node.kind} ${edge.node.ref ?? edge.node.id} (${excerpt}${edge.created_at})`;
   });
 }
+function unavailableReason(error) {
+  return error instanceof DispatchServiceError && error.status === 404 ? "unavailable" : `unavailable: ${messageFor(error)}`;
+}
 async function graphEdges(client, query) {
   try {
     return (await client.getReferences(query)).edges;
   } catch (error) {
-    return error instanceof DispatchServiceError && error.status === 404 ? "unavailable" : `unavailable: ${error instanceof Error ? error.message : String(error)}`;
+    return unavailableReason(error);
+  }
+}
+async function issueReferencesOrUnavailable(client, key) {
+  try {
+    return await client.getIssueReferences(key);
+  } catch (error) {
+    return unavailableReason(error);
   }
 }
 async function graphSections(client, ref) {
@@ -15962,8 +16044,9 @@ async function executeDispatchTool(input) {
   problems.push(...argumentProblems(input.tool, ownerArguments.args));
   if (problems.length > 0)
     throw new ToolInputError(input.tool, problems);
+  const dispatchClient = () => new DispatchClient(configUrl, configToken, fetchImpl, input.signal);
   if (input.tool === "dispatch_open_asks") {
-    const client = new DispatchClient(configUrl, configToken, fetchImpl, input.signal);
+    const client = dispatchClient();
     const project = optionalString(ownerArguments.args, "project");
     if (project !== undefined) {
       const response = await client.openAsksForProject(project);
@@ -15979,7 +16062,7 @@ async function executeDispatchTool(input) {
     const sessionId = input.sessionId?.trim();
     if (!sessionId)
       throw new Error("host session id is required for dispatch_whoami");
-    const client = new DispatchClient(configUrl, configToken, fetchImpl, input.signal);
+    const client = dispatchClient();
     const identity = await client.whoami();
     const owner = identity.kind === "agent" ? identity.owner : identity.login.toLowerCase();
     return {
@@ -15989,7 +16072,7 @@ async function executeDispatchTool(input) {
   }
   const args = parsed.success ? parsed.data : ownerArguments.args;
   const actor = toolActor(await resolveOrigin(env, exec, input.cwd), input);
-  const client = new DispatchClient(configUrl, configToken, fetchImpl, input.signal);
+  const client = dispatchClient();
   const owner = ownerArguments.owner?.kind === "issue" ? {
     kind: "issue",
     issue: await ensureIssue(client, ownerArguments.owner.issue, actor)
@@ -16014,6 +16097,7 @@ async function executeDispatchTool(input) {
       const spec = optionalString(args, "spec");
       const priority = optionalNumber(args, "priority");
       const assignee = optionalString(args, "assignee");
+      const components = optionalComponents(args, "components");
       const labels = args.labels;
       try {
         const created = await client.issue({
@@ -16025,6 +16109,7 @@ async function executeDispatchTool(input) {
           ...spec === undefined ? {} : { spec },
           ...priority === undefined ? {} : { priority },
           ...assignee === undefined ? {} : { assignee },
+          ...components === undefined ? {} : { components },
           ...Array.isArray(labels) ? { labels } : {},
           actor
         });
@@ -16057,6 +16142,7 @@ async function executeDispatchTool(input) {
       const title = optionalString(args, "title");
       const route = optionalString(args, "route");
       const parent = optionalString(args, "parent");
+      const components = optionalComponents(args, "components");
       const labels = Array.isArray(args.labels) ? args.labels : undefined;
       const requestedLinks = Array.isArray(args.external_links) ? [...new Set(args.external_links)] : undefined;
       let newLinks = [];
@@ -16070,6 +16156,7 @@ async function executeDispatchTool(input) {
           ...labels === undefined ? {} : { labels },
           ...route === undefined ? {} : { route },
           ...parent === undefined ? {} : { parent: parent === "" ? null : parent },
+          ...components === undefined ? {} : { components },
           ...requestedLinks === undefined ? {} : { external_links: [...before.external_links, ...newLinks.map((url) => ({ url }))] },
           actor
         });
@@ -16082,7 +16169,8 @@ async function executeDispatchTool(input) {
             newLinks.length === 0 ? `already linked ${requestedLinks.join(", ")} ${linkCount}` : `linked ${newLinks.join(", ")} ${linkCount}`
           ],
           ...route === undefined ? [] : [after.route === null ? "route cleared" : `route ${after.route}`],
-          ...parent === undefined ? [] : [after.parent === null ? "parent cleared" : `parent -> ${after.parent}`]
+          ...parent === undefined ? [] : [after.parent === null ? "parent cleared" : `parent -> ${after.parent}`],
+          ...components === undefined ? [] : [componentsChange(components, after.components)]
         ];
         return {
           text: `${after.key}: ${changes.join("; ")} ${notSubscribed(issueTopic(after.key))}`,
@@ -16223,7 +16311,7 @@ async function executeDispatchTool(input) {
       return {
         text: `Asked ${ask.id} on ${askOwner.label} (urgency ${ask.urgency}): ${ask.question}
 ${followsAsk(askOwner)}`,
-        details: await followedAskDetails(client, ask, resolved)
+        details: await followedAskDetails(client, ask, resolved?.artifact)
       };
     }
     case "dispatch_edit_ask": {
@@ -16305,7 +16393,7 @@ ${followsAsk(askOwner)}`,
         ...inReplyTo === undefined ? {} : { in_reply_to: inReplyTo },
         actor
       });
-      const messageRef = `dispatch://${issueKey}/message/${message.id}`;
+      const messageRef = dispatchChildRef(dispatchIssueRef(issueKey), "message", message.id);
       return {
         text: `Posted message ${message.id} (${messageRef}) ${notSubscribed(issueTopic(issueKey))}`,
         details: { issue: issueKey, message: message.id }
@@ -16367,7 +16455,7 @@ ${trailer.join(`
           }
         };
       }
-      const details = await followedAskDetails(client, result.ask, resolved);
+      const details = await followedAskDetails(client, result.ask, resolved.artifact);
       return {
         text: `Approval requested for ${resolved.artifact.name} (document id ${resolved.artifact.id}) at version ${result.version} (ask ${result.ask.id}). The answer arrives as artifact.approved or artifact.changes_requested; an edit after approval makes it stale, so request again for the new version.`,
         details: { ...details, artifact: resolved.artifact.id, version: result.version }
@@ -16390,7 +16478,7 @@ ${trailer.join(`
       };
       const artifactOwner = documentOwner();
       const result = artifactOwner.kind === "project" ? await client.projectArtifact(artifactOwner.project, artifactInput) : await client.artifact(issue(), artifactInput);
-      const artifactRef = artifactOwner.kind === "project" ? `dispatch://${artifactOwner.project}/artifact/${result.artifact.slug}` : `dispatch://${issue()}/artifact/${result.artifact.slug}`;
+      const artifactRef = dispatchDocumentRef(artifactOwner.kind === "project" ? artifactOwner.project : issue(), result.artifact.slug);
       const uploadOwner = artifactOwner.kind === "project" ? documentTopic(result.artifact) : issueTopic(issue());
       return {
         text: `Uploaded ${result.artifact.name} as version ${result.version.number} (artifact slug ${result.artifact.slug}; ${artifactRef}) ${notSubscribed(uploadOwner)}`,
@@ -16426,7 +16514,7 @@ ${trailer.join(`
         const ref = ownerArguments.ref;
         const id = await resolveIdPrefix(input.tool, "ask", ref, async () => ref.owner.kind === "issue" ? client.listIssueAsks(ref.owner.issue) : client.getArtifactAsks((await resolveArtifact(client, ref.owner, ref.artifact)).artifact.id, "all"));
         const askRead = await client.getAsk(id);
-        const askRef = ref.owner.kind === "issue" ? `dispatch://${ref.owner.issue}/ask/${id}` : `dispatch://${ref.owner.project}/artifact/${ref.artifact}/ask/${id}`;
+        const askRef = refTarget(ref, "ask", id);
         return {
           text: askSummary(askRead, await graphSections(client, askRef)),
           details: ref.owner.kind === "project" ? { project: ref.owner.project } : { issue: ref.owner.issue }
@@ -16436,7 +16524,7 @@ ${trailer.join(`
         const ref = ownerArguments.ref;
         const id = await resolveIdPrefix(input.tool, "comment", ref, async () => ref.owner.kind === "issue" ? client.getComments(ref.owner.issue) : client.getArtifactComments((await resolveArtifact(client, ref.owner, ref.artifact)).artifact.id));
         const comment = await client.getComment(id);
-        const commentRef = ref.owner.kind === "issue" ? `dispatch://${ref.owner.issue}/comment/${id}` : `dispatch://${ref.owner.project}/artifact/${ref.artifact}/comment/${id}`;
+        const commentRef = refTarget(ref, "comment", id);
         return {
           text: commentSummary(comment, await graphSections(client, commentRef)),
           details: ref.owner.kind === "project" ? { project: ref.owner.project } : { issue: comment.comment.issue_key }
@@ -16447,7 +16535,7 @@ ${trailer.join(`
           throw new Error("message references are issue-scoped");
         }
         const messageRead = await client.getMessage(ownerArguments.ref.owner.issue, ownerArguments.ref.id);
-        const messageRef = `dispatch://${ownerArguments.ref.owner.issue}/message/${ownerArguments.ref.id}`;
+        const messageRef = dispatchChildRef(dispatchIssueRef(ownerArguments.ref.owner.issue), "message", ownerArguments.ref.id);
         return {
           text: messageSummary(messageRead, await graphSections(client, messageRef)),
           details: { issue: messageRead.message.issue_key }
@@ -16455,7 +16543,7 @@ ${trailer.join(`
       }
       if (documentOwner().kind === "project") {
         const resolved = await resolveArtifact(client, documentOwner(), stringArg(args, "artifact"));
-        const documentRef = `dispatch://${resolved.artifact.project}/artifact/${resolved.artifact.slug}`;
+        const documentRef = dispatchDocumentRef(resolved.artifact.project, resolved.artifact.slug);
         return {
           text: [
             `Document: ${resolved.artifact.project} / ${resolved.artifact.name}`,
@@ -16467,7 +16555,7 @@ ${trailer.join(`
 `),
           details: {
             project: resolved.artifact.project,
-            document: `${resolved.artifact.project}/${resolved.artifact.slug}`
+            document: documentLabel(resolved.artifact.project, resolved.artifact.slug)
           }
         };
       }
@@ -16484,14 +16572,12 @@ ${trailer.join(`
           details: { issue: read.issue.key }
         };
       }
-      let references;
-      try {
-        references = await client.getIssueReferences(read.issue.key);
-      } catch (error) {
-        references = error instanceof DispatchServiceError && error.status === 404 ? "unavailable" : `unavailable: ${error instanceof Error ? error.message : String(error)}`;
-      }
+      const [references, graph] = await Promise.all([
+        issueReferencesOrUnavailable(client, read.issue.key),
+        graphSections(client, dispatchIssueRef(read.issue.key))
+      ]);
       return {
-        text: issueSummary(read.issue, read.events, references, await graphSections(client, `dispatch://${read.issue.key}`)),
+        text: issueSummary(read.issue, read.events, references, graph),
         details: { issue: read.issue.key }
       };
     }
@@ -16634,6 +16720,7 @@ var envoyToolSpecs = [
     requiresSubscriptionCapability: false
   }
 ];
+var envoyToolSchemas = new Map;
 
 // ../envoy-client/src/transport.ts
 var DEFAULT_TIMEOUT_MS = 5000;

package/package.json

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

package/skills/dispatch/SKILL.md

@@ -30,6 +30,8 @@ vocabulary, and is often on a phone. Write for that person.
   what each costs, and your recommendation with its reason.
 - Before posting, test it: could Sami, reading only this text on his phone, know what he is 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. Inferred from the AGENTC-186 12-hour-cap incident (platform PO, 2026-09-17).
+- 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. Inferred from the astro lane's 2026-09-16 retro (platform PO, 2026-09-17).
 
 ## Agent authentication
 
@@ -248,6 +250,17 @@ that follow from it:
 the question carries `dispatch://KEY/artifact/<slug>` (or `ref`), never just its filename. Text
 they must read to decide belongs in the spec in the first place — see [Artifacts](#artifacts).
 
+Attach an issue to the architecture components it changes, before decomposing it — children inherit the parent's attachment unless they choose their own, so attaching the root once classifies the whole tree:
+
+```
+dispatch_issue({ project: "CORE", title: "...", components: { mode: "explicit", ids: ["dispatch-server", "web"] } })
+dispatch_issue_update({ issue: "CORE-12", components: { mode: "explicit", ids: ["web"] } })   // this issue's own set, replacing what it inherited
+dispatch_issue_update({ issue: "CORE-13", components: { mode: "none", reason: "hiring, not code" } })
+dispatch_issue_update({ issue: "CORE-14", components: { mode: "inherit" } })                  // back to the parent chain's attachment
+```
+
+Component ids are the file names under the repository's `.dispatch/architecture/` (`web.md` → `web`); an id the model lacks, or an `external` component, is refused with `COMPONENTS_INPUT`. A closed issue can be classified without reopening. Two rules: declare and attach before decomposing work, and change code and its architecture description (`.dispatch/architecture/<id>.md`) in the same review — the tree at `GET /api/v1/projects/{key}/architecture` counts every issue whose effective set names a component or anything it contains.
+
 Import a project's architecture model from its configured source repository now (a human configures the source in Settings):
 ```ts
 dispatch_architecture_sync({ project: "CORE" })
@@ -256,6 +269,8 @@ It returns the imported commit, or the recorded error when the model was rejecte
 
 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 audit 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, send a one-line ask before the first implementation commit. A platform-PO schema or contract ruling does not settle product shape. This does not turn a user-specified decision or routine implementation into an approval request; it is inferred from AGENTC-186's 2026-09-16 retro (platform PO, 2026-09-17).
+
 **Anything that needs the human is an ask, or it does not exist.** An approval, a credential,
 a setting only they can change, a review click, a conflict between two of their own rules - if
 your work waits on it, open a `dispatch_ask` the moment you know, the action as the question.

package/skills/legion-architect/SKILL.md

@@ -331,3 +331,7 @@ capacity, and cross-tree conflict. Use the Legion escalation operation for those
 everything else in the tree, or use `dispatch_ask` for a human question; workers may reach
 Sami directly with `dispatch_ask` the same way. Do not create a wait loop for any wake
 source.
+
+## Architecture components
+
+Bootstrap on a root whose project has an architecture source: 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 the sync and the attach below work only once that PR has merged to the source branch: until then leave the root on `inherit` (the attach would answer `400 COMPONENTS_INPUT`, the component does not exist yet). After the merge, `dispatch_architecture_sync({ project })` and attach the root with `dispatch_issue_update({ issue, components: { mode: "explicit", ids: [...] } })`. Children inherit the root's attachment; give a child its own `components` only when it changes a narrower set, and `{ mode: "none", reason }` when it is not architectural work. Attach before decomposing, and require every implementer to change the component file beside the code it describes in the same review.