@sjawhar/opencode-legion-envoy 1.24.0 → 1.26.0

package/dist/src/server.js

@@ -13806,7 +13806,7 @@ var dispatchToolSpecs = [
       options: z.array(z.object({
         label: z.string().describe("Selectable option label."),
         description: z.string().describe("Optional option context.").optional()
-      }), { max: 8 }).describe("Optional choices, at most 8.").optional(),
+      }), { max: 8 }).describe("Up to 8 choices, each an object { label, description? } (never a bare string).").optional(),
       multiple: z.boolean().describe("Whether multiple choices may be selected.").optional(),
       urgency: z.enum(ASK_URGENCIES).describe("Optional decision urgency.").optional(),
       anchor: z.object({
@@ -13858,7 +13858,7 @@ var dispatchToolSpecs = [
       quote: z.string().describe("Optional exact quoted document text.").optional(),
       occurrence: z.number({ int: true, min: 0 }).describe("Optional zero-based occurrence of quote.").optional(),
       body: z.string({ max: 2000 }).describe("Review comment, at most 2,000 characters."),
-      reply_to: z.string().describe("Full id of a comment to reply to; replying to any comment in a thread continues that " + "thread (an ask's clarification thread included).").optional(),
+      reply_to: z.string().describe("A comment id (uuid); replying to any comment in a thread continues that thread (an " + "ask's clarification thread included). To reply to an ask, use reply_to_ask with the " + "ask id instead.").optional(),
       reply_to_ask: z.string().describe("Optional ask id to reply to, threading this comment under that question. Mutually " + "exclusive with reply_to.").optional(),
       turn: z.enum(["agent", "human"]).describe("Only with reply_to_ask: who holds the turn after this reply. agent: a progress note - " + "you keep the turn and the ask stays 'Waiting on agents' for the human; human (default): " + "you need the human to act - the ask returns to 'Waiting on you'.").optional()
     }),
@@ -13890,7 +13890,7 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_doc_edit",
-    description: "Apply deterministic document edits, including retyping an identified paragraph into a schema-declared typed block. " + "Do not use it for review feedback or for reading; use dispatch_comment, dispatch_suggest, or dispatch_doc_read instead. " + "For replace, delete, and quote insert anchors, find text exactly as rendered: omit Markdown markers such as backticks or asterisks. " + `The spec (or any document) holds requirements, design, and decisions - never progress, status, or timestamps. ${OWNER_REFERENCE} ${SPEC_WRITING_GUIDANCE}`,
+    description: "Apply deterministic document edits, including retyping an identified paragraph into a schema-declared typed block. " + "Do not use it for review feedback or for reading; use dispatch_comment, dispatch_suggest, or dispatch_doc_read instead. " + 'For replace, delete, and quote insert anchors, find text as rendered: inline Markdown (**bold**, `code`) is tolerated; a leading \'# \' matches a heading. Insert anchors also accept "start", "end", and "heading:<exact heading text>". ' + `The spec (or any document) holds requirements, design, and decisions - never progress, status, or timestamps. ${OWNER_REFERENCE} ${SPEC_WRITING_GUIDANCE}`,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
       project: z.string().describe("Project key owning the document.").optional(),
@@ -13898,12 +13898,12 @@ var dispatchToolSpecs = [
       ref: z.string().describe("Optional dispatch:// issue or document reference.").optional(),
       ops: z.array(z.object({
         op: z.enum(DOC_EDIT_OPS).describe("Edit operation."),
-        find: z.string().describe("Text to find for replace or delete.").optional(),
+        find: z.string().describe("Text of the target block as rendered, for replace or delete; inline markdown (**bold**, `code`) is tolerated; a leading '# ' matches a heading.").optional(),
         with: z.string().describe("Replacement text for replace.").optional(),
         occurrence: z.number({ int: true, min: 0 }).describe("Optional zero-based match occurrence.").optional(),
         markdown: z.string().describe("Markdown to insert.").optional(),
-        after: z.string().describe("Anchor after which to insert.").optional(),
-        before: z.string().describe("Anchor before which to insert.").optional(),
+        after: z.string().describe(`Insert after this anchor: a quote of the neighbouring block's text, or one of "start", "end", "heading:<exact heading text>".`).optional(),
+        before: z.string().describe(`Insert before this anchor: a quote of the neighbouring block's text, or one of "start", "end", "heading:<exact heading text>".`).optional(),
         block: z.string().describe("Block id to retype.").optional(),
         type: z.string().describe("Typed block name for retype.").optional(),
         attributes: z.unknown().describe("Typed block attributes for retype.").optional()
@@ -14234,7 +14234,7 @@ var LegionDaemonApi = {
         queue: array(nonEmptyString)
       }),
       gates: record(string2(), stateGate),
-      controllerLocator: stateLocator.optional(),
+      controllerLocator: stateTreeLocator.optional(),
       roles: record(string2(), stateRole),
       controllerPendingNotices: number2().int().nonnegative(),
       pendingStatusWrites: array(nonEmptyString),
@@ -14242,7 +14242,11 @@ var LegionDaemonApi = {
     })
   },
   ControllerReady: {
-    request: strictObject({ secret: nonEmptyString, sessionId: nonEmptyString }),
+    request: strictObject({
+      secret: nonEmptyString,
+      sessionId: nonEmptyString,
+      ompSessionFile: nonEmptyString.optional()
+    }),
     response: object({})
   },
   ProcessStarted: {
@@ -14362,17 +14366,23 @@ var LegionDaemonApi = {
     response: object({})
   },
   Grant: {
-    request: strictObject({
-      tree: nonEmptyString,
-      issue: nonEmptyString,
-      sessionId: nonEmptyString,
-      secret: nonEmptyString
-    }),
+    request: union([
+      strictObject({
+        sessionId: nonEmptyString,
+        secret: nonEmptyString,
+        tree: nonEmptyString,
+        issue: nonEmptyString
+      }),
+      strictObject({ sessionId: nonEmptyString, secret: nonEmptyString })
+    ]),
     response: object({ grantId: nonEmptyString, expiresAt: nonEmptyString })
   },
   GitHubToken: {
-    request: strictObject({ grantId: nonEmptyString }),
+    request: strictObject({ grantId: nonEmptyString, merge: literal(true).optional() }),
     response: object({ token: nonEmptyString, appLogin: string2().endsWith("[bot]") })
+  },
+  GitCredential: {
+    request: strictObject({ grantId: nonEmptyString })
   }
 };
 // ../contracts/src/repo.ts
@@ -14380,6 +14390,9 @@ function canonicalRepo(owner, repo) {
   return `${owner.trim().toLowerCase()}/${repo.trim().toLowerCase().replace(/\.git$/, "")}`;
 }
 // ../contracts/src/tool-schema.ts
+function overCapMessage(length, max) {
+  return `is ${length - max} characters over the ${max}-character limit (${length}/${max})`;
+}
 function zodSchemaApi(zod) {
   const api = zod;
   return {
@@ -14387,8 +14400,12 @@ function zodSchemaApi(zod) {
       let schema = api.string();
       if (opts.min !== undefined)
         schema = schema.min(opts.min);
-      if (opts.max !== undefined)
-        schema = schema.max(opts.max);
+      if (opts.max !== undefined) {
+        const max = opts.max;
+        schema = schema.max(max, {
+          error: (issue) => overCapMessage(typeof issue.input === "string" ? issue.input.length : max + 1, max)
+        });
+      }
       return schema;
     },
     number: (opts = {}) => {
@@ -14587,6 +14604,24 @@ function resolveDispatchConfig(env, options = {}) {
 // ../envoy-client/src/dispatch-execute.ts
 import { resolve as resolvePath } from "path";
 
+// ../envoy-client/src/ask-answer.ts
+var HEAD_LENGTH = 120;
+function textHead(text, limit = HEAD_LENGTH) {
+  const flat = text.replace(/\s+/g, " ").trim();
+  return flat.length > limit ? `${flat.slice(0, limit)}\u2026` : flat;
+}
+function askAnswerText(answer) {
+  if (answer === null || answer === undefined)
+    return "";
+  const selected = (answer.selected ?? []).join(", ");
+  const text = answer.text ?? "";
+  if (text === "")
+    return selected;
+  if (selected === "")
+    return text;
+  return `${selected} - ${text}`;
+}
+
 // ../envoy-client/src/dispatch-cwd.ts
 import { execFile } from "child_process";
 import { promisify } from "util";
@@ -14768,6 +14803,9 @@ class DispatchClient {
   async comment(issue, input) {
     return this.#json("POST", ["api", "v1", "issues", await this.#resolveIssue(issue), "comments"], input);
   }
+  async listIssueAsks(issue, state) {
+    return this.#json("GET", ["api", "v1", "issues", await this.#resolveIssue(issue), "asks"], undefined, state === undefined ? undefined : { state });
+  }
   async getArtifactAsks(id, state) {
     return this.#json("GET", ["api", "v1", "artifacts", id, "asks"], undefined, state === undefined ? undefined : { state });
   }
@@ -14966,6 +15004,116 @@ class DispatchClient {
   }
 }
 
+// ../envoy-client/src/tool-input-errors.ts
+class ToolInputError extends Error {
+  tool;
+  problems;
+  constructor(tool, problems) {
+    const count = problems.length;
+    super([
+      `${tool} was not called: ${count} problem${count === 1 ? "" : "s"}`,
+      ...problems.map((problem) => `- ${problem}`)
+    ].join(`
+`));
+    this.name = "ToolInputError";
+    this.tool = tool;
+    this.problems = problems;
+  }
+}
+function unwrap(schema) {
+  let current = schema;
+  while (current !== undefined) {
+    const def = current.def;
+    if (!("innerType" in def) || !(def.type === "optional" || def.type === "nullable" || def.type === "default"))
+      break;
+    current = def.innerType;
+  }
+  return current;
+}
+function shapeOf(schema) {
+  const unwrapped = unwrap(schema);
+  if (unwrapped === undefined)
+    return;
+  const def = unwrapped.def;
+  return def.type === "object" && "shape" in def ? def.shape : undefined;
+}
+function schemaAt(schema, path) {
+  let current = schema;
+  for (const key of path) {
+    const unwrapped = unwrap(current);
+    if (unwrapped === undefined)
+      return;
+    const def = unwrapped.def;
+    if (def.type === "object" && "shape" in def) {
+      current = shapeOf(unwrapped)?.[String(key)];
+    } else if (def.type === "array" && "element" in def) {
+      current = def.element;
+    } else {
+      return;
+    }
+  }
+  return unwrap(current);
+}
+function describeInput(value) {
+  if (value === null)
+    return "null";
+  if (Array.isArray(value))
+    return "an array";
+  switch (typeof value) {
+    case "number":
+    case "boolean":
+      return String(value);
+    case "string":
+      return "a string";
+    case "object":
+      return "an object";
+    default:
+      return typeof value;
+  }
+}
+function describeExpected(expected, schema) {
+  switch (expected) {
+    case "int":
+      return "an integer";
+    case "object": {
+      const shape = shapeOf(schema);
+      const keys = shape === undefined ? [] : Object.entries(shape).map(([key, field]) => `${key}${field.def.type === "optional" ? "?" : ""}`);
+      return keys.length === 0 ? "an object" : `an object {${keys.join(", ")}}`;
+    }
+    case "array":
+      return "an array";
+    default:
+      return `a ${expected}`;
+  }
+}
+function formatZodIssues(issues, schema) {
+  const allowed = Object.keys(shapeOf(schema) ?? {}).join(", ");
+  return issues.flatMap((issue) => {
+    const path = issue.path.map(String).join(".");
+    switch (issue.code) {
+      case "invalid_type":
+        return issue.input === undefined ? [`${path} is required (${issue.expected})`] : [
+          `${path} must be ${describeExpected(issue.expected, schemaAt(schema, issue.path))}, not ${describeInput(issue.input)}`
+        ];
+      case "unrecognized_keys":
+        return issue.keys.map((key) => `unknown field "${key}"; allowed: ${allowed}`);
+      case "invalid_value":
+        return [
+          `${path} must be one of ${issue.values.map(String).join("|")}; got ${JSON.stringify(issue.input)}`
+        ];
+      case "too_big":
+        if (issue.origin === "array" && Array.isArray(issue.input)) {
+          return [`${path} has ${issue.input.length} items; the limit is ${issue.maximum}`];
+        }
+        return [`${path} ${issue.message}`];
+      case "custom":
+        return [issue.message];
+      default:
+        return [path === "" ? issue.message : `${path}: ${issue.message}`];
+    }
+  });
+}
+
 // ../envoy-client/src/dispatch-execute.ts
 function documentResultDetails(artifact) {
   return {
@@ -15060,23 +15208,19 @@ function askUrgency(args) {
   return ASK_URGENCIES.find((urgency) => urgency === value);
 }
 function askKind(args) {
-  const value = optionalString(args, "kind");
-  if (value === undefined || value === "action")
-    return value;
-  throw new Error("kind must be action");
+  return optionalString(args, "kind") === "action" ? "action" : undefined;
 }
-function askQuestionWithRef(args) {
-  const question = stringArg(args, "question");
-  const ref = optionalString(args, "ref");
-  if (ref === undefined || question.includes(ref))
-    return question;
-  const withRef = `${question}
+var maxAskQuestion16 = 800;
+function questionWithRef(question, ref) {
+  return ref === undefined || question.includes(ref) ? question : `${question}
 
 Ref: ${ref}`;
-  if (withRef.length > 800) {
-    throw new Error("question plus ref must be at most 800 characters");
-  }
-  return withRef;
+}
+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;
 }
 function parseDispatchRef(ref) {
   const projectDocument = ref.match(/^dispatch:\/\/([A-Z][A-Z0-9]{1,9})\/artifact\/([^/@]+)(?:@v(\d+))?(?:\/(ask|comment)\/([^/]+))?$/);
@@ -15098,7 +15242,8 @@ function parseDispatchRef(ref) {
     return {
       owner: { kind: "project", project },
       kind: targetKind,
-      id: targetID
+      id: targetID,
+      artifact
     };
   }
   const issueReference = ref.match(/^dispatch:\/\/([A-Z][A-Z0-9]{1,9}-[1-9][0-9]*)(?:\/(spec)|\/(log)|\/(children)|\/artifact\/([^/@]+)(?:@v(\d+))?|\/ask\/([^/]+)|\/comment\/([^/]+)|\/message\/([^/]+))?$/);
@@ -15130,60 +15275,171 @@ function parseDispatchRef(ref) {
     return { owner, kind: "message", id: message };
   return { owner, kind: "issue", id: issue };
 }
+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 messageIdProblem = "in_reply_to must be a full message id (uuid) or a dispatch://KEY/message/<id> reference";
 function askId(args) {
   const ask = stringArg(args, "ask");
-  if (!ask.startsWith("dispatch://"))
-    return ask;
-  const reference = parseDispatchRef(ask);
-  if (reference?.kind !== "ask") {
-    throw new Error("ask must be a bare ask id or a dispatch://.../ask/<id> reference");
+  return ask.startsWith("dispatch://") ? parseDispatchRef(ask)?.id ?? ask : ask;
+}
+function messageIdOf(value) {
+  const id = value.startsWith("dispatch://") ? (() => {
+    const reference = parseDispatchRef(value);
+    return reference?.kind === "message" ? reference.id : undefined;
+  })() : value;
+  return id !== undefined && uuidPattern.test(id) ? id : undefined;
+}
+var idPrefixPattern = /^[0-9a-f][0-9a-f-]{7,}$/i;
+async function resolveIdPrefix(tool, kind, ref, list) {
+  if (uuidPattern.test(ref.id))
+    return ref.id;
+  const ownerName = ref.owner.kind === "issue" ? ref.owner.issue : `${ref.owner.project}/${ref.artifact}`;
+  if (!idPrefixPattern.test(ref.id)) {
+    throw new ToolInputError(tool, [
+      `${kind} id ${ref.id} must be a full uuid or a prefix of at least 8 hex characters`
+    ]);
   }
-  return reference.id;
+  const prefix = ref.id.toLowerCase();
+  const matches = (await list()).filter((item) => item.id.toLowerCase().startsWith(prefix));
+  if (matches.length === 1 && matches[0] !== undefined)
+    return matches[0].id;
+  throw new ToolInputError(tool, [
+    matches.length === 0 ? `${kind} id ${ref.id} matches none of the ${kind}s on ${ownerName}; use the full id` : `${kind} id ${ref.id} matches ${matches.length} ${kind}s on ${ownerName}; use the full id`
+  ]);
 }
 function messageInReplyTo(args) {
   const inReplyTo = optionalString(args, "in_reply_to");
-  if (inReplyTo === undefined || !inReplyTo.startsWith("dispatch://"))
-    return inReplyTo;
-  const reference = parseDispatchRef(inReplyTo);
-  if (reference?.kind !== "message") {
-    throw new Error("in_reply_to must be a bare message id or a dispatch://.../message/<id> reference");
+  return inReplyTo === undefined ? undefined : messageIdOf(inReplyTo);
+}
+function argumentProblems(tool, args) {
+  const problems = [];
+  switch (tool) {
+    case "dispatch_ask": {
+      const question = optionalString(args, "question");
+      const ref = optionalString(args, "ref");
+      if (question !== undefined && ref !== undefined && question.length <= maxAskQuestion16) {
+        const problem = askQuestionProblem(questionWithRef(question, ref));
+        if (problem !== undefined)
+          problems.push(problem);
+      }
+      break;
+    }
+    case "dispatch_edit_ask":
+    case "dispatch_resolve_ask": {
+      const ask = optionalString(args, "ask");
+      if (ask?.startsWith("dispatch://") && parseDispatchRef(ask)?.kind !== "ask") {
+        problems.push(askIdProblem);
+      }
+      break;
+    }
+    case "dispatch_comment": {
+      if (optionalString(args, "quote") !== undefined && optionalString(args, "artifact") === undefined) {
+        problems.push("artifact is required when quote is supplied");
+      }
+      if (optionalString(args, "reply_to") !== undefined && optionalString(args, "reply_to_ask") !== undefined) {
+        problems.push("reply_to and reply_to_ask cannot both be set");
+      }
+      break;
+    }
+    case "dispatch_message": {
+      const inReplyTo = optionalString(args, "in_reply_to");
+      if (inReplyTo !== undefined && messageIdOf(inReplyTo) === undefined) {
+        problems.push(messageIdProblem);
+      }
+      break;
+    }
   }
-  return reference.id;
+  return problems;
 }
+function dispatchRefFromUrl(value, serverUrl) {
+  let url;
+  let origin;
+  try {
+    url = new URL(value);
+    origin = new URL(serverUrl).origin;
+  } catch {
+    return;
+  }
+  if (url.origin !== origin)
+    return;
+  const versionOf = (name) => {
+    const value = url.searchParams.get(name);
+    return value !== null && /^[1-9][0-9]*$/.test(value) ? `@v${value}` : "";
+  };
+  const issuePage = url.pathname.match(/^\/issues\/([A-Z][A-Z0-9]{1,9}-[1-9][0-9]*)(?:\/(spec|log|conversation|children)|\/artifacts\/([^/]+)|\/asks\/([^/]+)|\/comments\/([^/]+)|\/messages\/([^/]+))?\/?$/);
+  if (issuePage) {
+    const [, key, page, artifact, ask, comment, message] = issuePage;
+    const version = versionOf("v");
+    if (page === "spec" && version !== "")
+      return `dispatch://${key}/artifact/spec${version}`;
+    if (page !== undefined)
+      return `dispatch://${key}/${page === "conversation" ? "log" : page}`;
+    if (artifact !== undefined) {
+      return `dispatch://${key}/artifact/${decodeURIComponent(artifact)}${version}`;
+    }
+    if (ask !== undefined)
+      return `dispatch://${key}/ask/${ask}`;
+    if (comment !== undefined)
+      return `dispatch://${key}/comment/${comment}`;
+    if (message !== undefined)
+      return `dispatch://${key}/message/${message}`;
+    return `dispatch://${key}`;
+  }
+  const documentPage = url.pathname.match(/^\/projects\/([A-Z][A-Z0-9]{1,9})\/documents\/([^/]+)\/?$/);
+  if (!documentPage)
+    return;
+  const [, project, slug] = documentPage;
+  const document = `dispatch://${project}/artifact/${decodeURIComponent(slug ?? "")}${versionOf("version")}`;
+  const ask = url.searchParams.get("ask");
+  if (ask !== null)
+    return `${document}/ask/${ask}`;
+  const comment = url.searchParams.get("comment");
+  if (comment !== null)
+    return `${document}/comment/${comment}`;
+  return document;
+}
+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";
 function toolSchema(tool) {
   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 });
 }
-async function resolveOwnerArguments(tool, args, cwd, env, exec) {
+async function resolveOwnerArguments(tool, input, cwd, env, exec, serverUrl, problems) {
   if (issueFreeTools[tool] === true)
-    return { args, ref: null, owner: null };
-  const refArgument = args.ref;
-  if (tool === "dispatch_ask" && typeof refArgument === "string" && !refArgument.startsWith("dispatch://")) {
-    throw new Error("ref must be a dispatch:// reference");
-  }
-  const ref = typeof refArgument === "string" ? parseDispatchRef(refArgument) ?? (() => {
-    throw new Error("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)");
-  })() : null;
+    return { args: input, ref: null, owner: null };
+  const refArgument = input.ref;
+  let ref = null;
+  let args = input;
+  if (typeof refArgument === "string") {
+    const refText = dispatchRefFromUrl(refArgument, serverUrl) ?? refArgument;
+    if (refText !== refArgument)
+      args = { ...input, ref: refText };
+    ref = parseDispatchRef(refText);
+    if (ref === null) {
+      problems.push(tool === "dispatch_ask" && !refText.startsWith("dispatch://") ? "ref must be a dispatch:// reference" : refGrammarProblem);
+    }
+  }
   const issueArgument = args.issue;
   const projectArgument = args.project;
   const artifactArgument = args.artifact;
   const versionArgument = args.version;
   if (issueArgument !== undefined && projectArgument !== undefined) {
-    throw new Error("exactly one of issue and project is required");
+    problems.push("exactly one of issue and project is required");
   }
   if (typeof projectArgument === "string") {
     if (!/^[A-Z][A-Z0-9]{1,9}$/.test(projectArgument)) {
-      throw new Error("project must be a project key such as CORE");
+      problems.push("project must be a project key such as CORE");
     }
-    if (ref?.owner.kind === "project" && (ref.owner.project !== projectArgument || artifactArgument !== undefined && artifactArgument !== ref.id)) {
-      throw new Error("project and ref must name the same document");
+    const refDocument = ref?.owner.kind === "project" ? ref.artifact ?? ref.id : undefined;
+    if (ref?.owner.kind === "project" && (ref.owner.project !== projectArgument || artifactArgument !== undefined && artifactArgument !== refDocument)) {
+      problems.push("project and ref must name the same document");
     }
     return {
       args: {
         ...args,
-        ...artifactArgument === undefined && ref?.owner.kind === "project" ? { artifact: ref.id } : {},
+        ...artifactArgument === undefined && refDocument !== undefined ? { artifact: refDocument } : {},
         ...versionArgument === undefined && ref?.version !== undefined ? { version: ref.version } : {}
       },
       ref,
@@ -15195,7 +15451,7 @@ async function resolveOwnerArguments(tool, args, cwd, env, exec) {
       args: {
         ...args,
         project: ref.owner.project,
-        ...artifactArgument === undefined ? { artifact: ref.id } : {},
+        ...artifactArgument === undefined ? { artifact: ref.artifact ?? ref.id } : {},
         ...versionArgument === undefined && ref.version !== undefined ? { version: ref.version } : {}
       },
       ref,
@@ -15216,20 +15472,25 @@ async function resolveOwnerArguments(tool, args, cwd, env, exec) {
     };
   }
   const legionIssue = env.LEGION_ISSUE;
-  if (!legionIssue)
-    throw new Error("issue is required; supply issue or set LEGION_ISSUE");
+  if (!legionIssue) {
+    problems.push(ownerRequiredProblem);
+    return { args, ref, owner: null };
+  }
   if (nativeIssueKeyPattern.test(legionIssue) || externalIssueRefPattern.test(legionIssue)) {
     const issue = canonicalExternalIssueRef(legionIssue);
-    return { args: { ...args, issue }, ref: null, owner: { kind: "issue", issue } };
+    return { args: { ...args, issue }, ref, owner: { kind: "issue", issue } };
   }
   if (!bareIssueNumberPattern.test(legionIssue)) {
-    throw new Error("LEGION_ISSUE must be a native issue key (e.g. LEGION-3), an external owner/repo#n reference, or a bare positive issue number");
+    problems.push("LEGION_ISSUE must be a native issue key (e.g. LEGION-3), an external owner/repo#n reference, or a bare positive issue number");
+    return { args, ref, owner: null };
   }
   const repo = await resolveCwdRepo(cwd, exec);
-  if (!repo)
-    throw new Error("issue is required; LEGION_ISSUE needs a GitHub repository in cwd");
+  if (!repo) {
+    problems.push("issue is required; LEGION_ISSUE needs a GitHub repository in cwd");
+    return { args, ref, owner: null };
+  }
   const issue = `${repo}#${legionIssue}`;
-  return { args: { ...args, issue }, ref: null, owner: { kind: "issue", issue } };
+  return { args: { ...args, issue }, ref, owner: { kind: "issue", issue } };
 }
 async function resolveArtifact(client, owner, artifactReference) {
   if (owner.kind === "project") {
@@ -15260,7 +15521,8 @@ async function resolveArtifact(client, owner, artifactReference) {
   const issue = await client.getIssue(owner.issue);
   const artifact = artifactReference === undefined || artifactReference === "spec" ? issue.artifacts.find((candidate) => candidate.primary || candidate.id === issue.primary_artifact_id) : issue.artifacts.find((candidate) => candidate.id === artifactReference || candidate.slug === artifactReference || candidate.name === artifactReference);
   if (!artifact) {
-    throw new Error(`artifact ${artifactReference ?? "spec"} was not found on issue ${issue.key}`);
+    const slugs = issue.artifacts.map((candidate) => `${candidate.slug}${candidate.primary || candidate.id === issue.primary_artifact_id ? " (primary)" : ""}`);
+    throw new Error(`artifact "${artifactReference ?? "spec"}" was not found on issue ${issue.key}; artifacts: ${slugs.length === 0 ? "none" : slugs.join(", ")}`);
   }
   return { owner, issue, artifact };
 }
@@ -15317,7 +15579,7 @@ function issueSummary(issue, events, references) {
     ...typeof references === "string" ? [`- ${references}`] : references.members.length === 0 ? ["- none"] : references.members.map(({ artifact, depth, via }) => `- ${artifact.project}/${artifact.slug} \xB7 depth ${depth} via ${via.kind} ${via.id}`),
     ...typeof references === "string" || !references.truncated ? [] : ["- more references beyond 8 hops"],
     "Events:",
-    ...events.length === 0 ? ["- none"] : events.map((event) => `- #${event.seq} ${event.type} \xB7 ${event.actor.kind} ${event.actor.id} \xB7 ${event.created_at}`)
+    ...events.length === 0 ? ["- none"] : events.map(eventLine)
   ].join(`
 `);
 }
@@ -15325,10 +15587,41 @@ function logSummary(issue, events) {
   return [
     `Key: ${issue.key}`,
     "Events:",
-    ...events.length === 0 ? ["- none"] : events.map((event) => `- #${event.seq} ${event.type} \xB7 ${event.actor.kind} ${event.actor.id} \xB7 ${event.created_at}`)
+    ...events.length === 0 ? ["- none"] : events.map(eventLine)
   ].join(`
 `);
 }
+function eventHead(event) {
+  switch (event.type) {
+    case "ask.opened":
+    case "ask.edited":
+    case "ask.resolved":
+      return textHead(event.payload.question);
+    case "ask.answered":
+      return `${textHead(event.payload.question)} -> ${textHead(askAnswerText(event.payload.answer))}`;
+    case "comment.created":
+    case "comment.edited":
+    case "comment.resolved":
+    case "comment.reopened":
+    case "suggestion.accepted":
+    case "suggestion.rejected":
+    case "message.created":
+    case "message.answered":
+      return textHead(event.payload.body);
+    case "artifact.version":
+      return textHead(`${event.payload.name} v${event.payload.version.number}${event.payload.version.summary ? `: ${event.payload.version.summary}` : ""}`);
+    case "issue.created":
+    case "issue.updated":
+    case "issue.closed":
+      return `status ${event.payload.status}`;
+    default:
+      return;
+  }
+}
+function eventLine(event) {
+  const head = eventHead(event);
+  return `- #${event.seq} ${event.type} \xB7 ${event.actor.kind} ${event.actor.id} \xB7 ${event.created_at}${head === undefined || head === "" ? "" : ` \xB7 ${head}`}`;
+}
 function childrenSummary(issue) {
   return [
     `Key: ${issue.key}`,
@@ -15463,19 +15756,29 @@ async function executeDispatchTool(input) {
       throw error;
     }
   }, { preconnect: baseFetch.preconnect });
+  const env = input.env ?? process.env;
+  const exec = input.exec ?? defaultExec;
+  const problems = [];
+  const ownerArguments = await resolveOwnerArguments(input.tool, input.args, input.cwd, env, exec, configUrl, problems);
+  const ownerMissing = issueFreeTools[input.tool] !== true && ownerArguments.owner === null;
+  const schema = toolSchema(input.tool);
+  const parsed = schema.safeParse(ownerArguments.args, { reportInput: true });
+  if (!parsed.success) {
+    const issues = parsed.error.issues.filter((issue) => !ownerMissing || !(issue.code === "invalid_type" && issue.path.length === 1 && issue.path[0] === "issue" && issue.input === undefined || issue.code === "custom" && issue.path.length === 0 && issue.message.startsWith("Exactly one of issue and project is required")));
+    problems.push(...formatZodIssues(issues, schema));
+  }
+  problems.push(...argumentProblems(input.tool, ownerArguments.args));
+  if (problems.length > 0)
+    throw new ToolInputError(input.tool, problems);
   if (input.tool === "dispatch_open_asks") {
     const sessionId = input.sessionId?.trim();
     if (!sessionId)
       throw new Error("host session id is required for dispatch_open_asks");
-    toolSchema(input.tool).parse(input.args);
     const client = new DispatchClient(configUrl, configToken, fetchImpl, input.signal);
     const response = await client.openAsks(sessionId);
     return { text: formatOpenAsksSummary(response, configUrl), details: { ...response } };
   }
-  const env = input.env ?? process.env;
-  const exec = input.exec ?? defaultExec;
-  const ownerArguments = await resolveOwnerArguments(input.tool, input.args, input.cwd, env, exec);
-  const args = toolSchema(input.tool).parse(ownerArguments.args);
+  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 owner = ownerArguments.owner?.kind === "issue" ? {
@@ -15558,8 +15861,6 @@ async function executeDispatchTool(input) {
     }
     case "dispatch_resolve_ask": {
       const kind = stringArg(args, "kind");
-      if (kind !== "retracted" && kind !== "resolved")
-        throw new Error("kind must be retracted or resolved");
       const ask = await client.resolveAsk(stringArg(args, "ask"), {
         kind,
         reason: stringArg(args, "reason"),
@@ -15616,24 +15917,12 @@ async function executeDispatchTool(input) {
     }
     case "dispatch_comment": {
       const artifactReference = optionalString(args, "artifact");
-      if (optionalString(args, "quote") !== undefined && artifactReference === undefined) {
-        throw new Error("artifact is required when quote is supplied");
-      }
       const owner = documentOwner();
       const resolved = owner.kind === "project" || artifactReference === undefined ? owner.kind === "project" ? await resolveArtifact(client, owner, artifactReference) : undefined : await resolveArtifact(client, owner, artifactReference);
       const anchored = resolved ? anchor(resolved.artifact, args) : undefined;
       const replyTo = optionalString(args, "reply_to");
       const replyToAsk = optionalString(args, "reply_to_ask");
-      if (replyTo !== undefined && replyToAsk !== undefined) {
-        throw new Error("reply_to and reply_to_ask cannot both be set");
-      }
       const requestedTurn = optionalString(args, "turn");
-      if (requestedTurn !== undefined && replyToAsk === undefined) {
-        throw new Error("turn requires reply_to_ask");
-      }
-      if (requestedTurn !== undefined && requestedTurn !== "agent" && requestedTurn !== "human") {
-        throw new Error("turn must be agent or human");
-      }
       const commentInput = {
         body: stringArg(args, "body"),
         ...anchored === undefined ? {} : { anchor: anchored },
@@ -15787,17 +16076,21 @@ ${trailer.join(`
     }
     case "dispatch_read": {
       if (ownerArguments.ref?.kind === "ask") {
-        const askRead = await client.getAsk(ownerArguments.ref.id);
+        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);
         return {
           text: askSummary(askRead),
-          details: ownerArguments.ref.owner.kind === "project" ? { project: ownerArguments.ref.owner.project } : { issue: ownerArguments.ref.owner.issue }
+          details: ref.owner.kind === "project" ? { project: ref.owner.project } : { issue: ref.owner.issue }
         };
       }
       if (ownerArguments.ref?.kind === "comment") {
-        const comment = await client.getComment(ownerArguments.ref.id);
+        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);
         return {
           text: commentSummary(comment),
-          details: ownerArguments.ref.owner.kind === "project" ? { project: ownerArguments.ref.owner.project } : { issue: comment.comment.issue_key }
+          details: ref.owner.kind === "project" ? { project: ref.owner.project } : { issue: comment.comment.issue_key }
         };
       }
       if (ownerArguments.ref?.kind === "message") {
@@ -15886,8 +16179,8 @@ function messageMetadataShape(schema) {
   return {
     in_reply_to: schema.string().optional(),
     supersedes: schema.string().optional(),
-    urgency: schema.enum(URGENCY_VALUES).optional(),
-    expects_reply: schema.enum(EXPECTS_REPLY_VALUES).optional(),
+    urgency: schema.enum(URGENCY_VALUES).describe("low | med | high | blocking").optional(),
+    expects_reply: schema.enum(EXPECTS_REPLY_VALUES).describe("none | optional | required").optional(),
     expires_at: schema.number({ int: true }).optional()
   };
 }

package/package.json

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

package/skills/dispatch/SKILL.md

@@ -10,7 +10,9 @@ decide, never a log of your work. The transcript is your scratch pad; progress a
 goes through a `dispatch_*` tool.
 
 The server enforces high signal: an ask question is at most 800 characters with at most eight options; comment and message bodies are at
-most 2,000 characters; an artifact is at most 25 MiB. It refuses over-limit input; it never truncates it. GitHub threads and markers no
+most 2,000 characters; an artifact is at most 25 MiB. It refuses over-limit input with the number to trim (`question is 50 characters over
+the 800-character limit (850/800)`); it never truncates it. A tool call with several problems is refused once, every problem listed
+(`<tool> was not called: N problems`), so one corrected call lands. GitHub threads and markers no
 longer exist.
 
 ## Writing for the human
@@ -273,7 +275,8 @@ within one textblock; split changes that span separate blocks into separate oper
 insert anchor is a quote, `"start"`, `"end"`, or `"heading:Title"`. Ordinary inserts create a sibling block before or after the quote or
 heading's enclosing document block; `"start"` and `"end"` select the document edges. At a table-cell quote, a body-row fragment (no
 header or delimiter rows) extends that table before or after the matched row instead; short rows are padded, wider rows are rejected,
-and deleting a cell's quoted text removes only that text.
+and deleting a cell's quoted text removes only that text. A `find` or quote anchor tolerates inline Markdown (`**bold**`, `` `code` ``)
+and a leading `# ` selects a heading by its text; a miss names the three nearest blocks so the next quote lands.
 
 Use `replace` for inline continuation. Use zero-based `occurrence` for a repeated target; re-read a missing or ambiguous target before
 retrying. Pass `summary` to name the version when recording a decision.
@@ -400,7 +403,7 @@ It returns `details` `{ issue, topic, message }`. `body` is capped at 2,000 char
 
 A human — or any bearer caller over HTTP, such as a test rig — can target the issue message at a
 live Envoy session or role as **BTW**, **Aside**, or **Steer**. The incoming Dispatch frame names
-the issue and includes a `reply_with` instruction; reply on the same open issue with the existing
+the issue and includes a `reply_with` hint (`{ tool, args }`, ready to issue on any host); reply on the same open issue with the existing
 tool, never a new targeted send:
 
 ```ts
@@ -458,7 +461,11 @@ dispatch://PROJECT/artifact/<document-ref>/ask/<id>
 dispatch://PROJECT/artifact/<document-ref>/comment/<id>
 ```
 
-A bare UUID or `KEY#seq` is not a reference; the `dispatch://` form is what Dispatch links and records.
+A bare UUID or `KEY#seq` is not a reference; the `dispatch://` form is what Dispatch links and records. `dispatch_read` also
+accepts the dashboard URL of an issue, spec, artifact, ask, comment, or project document on the configured server (it maps to the
+`dispatch://` form above), and an ask or comment id may be a unique prefix of at least 8 hex characters; a message id is always the
+full uuid. A non-uuid id on `GET /asks/{id}`, `/comments/{id}`, or `/issues/{key}/messages/{id}` is a 400 `ASK_ID_INPUT` /
+`COMMENT_ID_INPUT` / `MESSAGE_ID_INPUT`, never a 500.
 
 ## Before / after
 

package/skills/envoy/SKILL.md

@@ -47,8 +47,17 @@ envoy:
   expects_reply: required
   re: agent-message-1
   supersedes: agent-message-0
-  reply_with: "envoy_send(session_id=\"01a0bbbb-cccc-7ddd-eeee-0123456789ab\", message=\"...\")"
-  reply_role: "envoy_publish(topic=\"notifications.role.legion-reviewer\", message=\"...\")"
+  reply_with:
+    tool: envoy_send
+    args:
+      session_id: 01a0bbbb-cccc-7ddd-eeee-0123456789ab
+      in_reply_to: agent-message-2
+      message: ...
+  reply_role:
+    tool: envoy_publish
+    args:
+      topic: notifications.role.legion-reviewer
+      message: ...
   summary: Deployment needs confirmation.
   message: "Confirm the listener health check passed.\n\nThen publish the release."
   note: body names session 01a0cccc-dddd-7eee-ffff-0123456789ab; the sender is 01a0bbbb-cccc-7ddd-eeee-0123456789ab
@@ -62,7 +71,10 @@ envoy:
 - `by` is the expiry deadline, when the sender supplied one.
 - `urgency` is the sender's priority classification.
 - `expects_reply` states whether a reply is `none`, `optional`, or `required`.
-- `re` names the delivery this message replies to.
+- `re` names the delivery this message replies to. A Dispatch frame names it as a `dispatch://`
+  ref — the ask (`dispatch://KEY/ask/<id>`, or `dispatch://PROJECT/artifact/<slug>/ask/<id>` for a
+  document ask) or the message (`dispatch://KEY/message/<id>`) — never the quoted text; the
+  question head, when there is one, is `dispatch.question`.
 - `supersedes` names an earlier delivery this one replaces.
 - `reply_with` is the direct-reply call for the sender.
 - `reply_role` is the role-publish reply call when the sender has a role.

package/skills/legion-architect/SKILL.md

@@ -28,9 +28,9 @@ separate coordinator to finish necessary work.
   asking session.
 - The daemon spawns each role as its own process with the issue's context already in its
   environment. Never hand-format a role token: the daemon encodes one as
-  `legion-<project>-<KEY>-<role>`; for example, project `acme`, issue `LEGION-41`, role
-  `architect` encodes to `legion-acme-LEGION-41-architect`. Reuse a token you already
-  hold (your own, or one `spawn_worker` returned) or compute another with the
+  `legion-<project>-<key>-<role>` with the issue key lower-cased; for example, project `acme`,
+  issue `LEGION-41`, role `architect` encodes to `legion-acme-legion-41-architect`. Reuse a
+  token you already hold (your own, or one `spawn_worker` returned) or compute another with the
   `roleToken` helper from `@legion/contracts` exactly the way the daemon does.
 - There is no label vocabulary. Dispatch status replaces the board, and the design gate
   is a human approving the root spec document at a version in Dispatch, requested with
@@ -240,11 +240,18 @@ Preserve this order exactly:
    commit does not void the approval and never returns the tree to the tester or reviewer;
 4. the merger verifies the current head is the reviewer-approved head plus only commits that
    change `docs/solutions/` (`jj diff --from <approved-sha> --to <tip-sha> --summary`, quoted in READY)
-   and publishes `READY #<n> at <sha>` to `notifications.role.pr-queue`; it never
-   merges. The merge queue merges under its own authority and the repository's own rules
-   (branch protection, CODEOWNERS); whether a human must approve first is that repository's
-   setting, not Legion's, and you never ask for or wait on such an approval.
-5. the merge queue merges; you then `spawn_worker` the **implementer** once more with the
+   and publishes `READY #<n> at <current sha> (approved at <approved sha>) for <KEY> (<pr url>)`
+   to the project's controller topic (the merge queue; named in its `Legion addressing` line);
+   it never merges. The controller verifies the gates against live GitHub — the current head,
+   required checks, review threads, mergeability, that only `.legion/` deletions lie between the
+   head the `## Verification` block names and the approved sha, that only `docs/solutions/`
+   changed between the approved and current shas, and that the block is complete at the head it
+   names — and merges the current sha, pinned, under the implement App's identity and the
+   repository's own rules (branch protection, CODEOWNERS); it does not check the approval itself,
+   and whether a human must approve first is that repository's setting, not Legion's, so you never
+   ask for or wait on such an approval. If the controller reports a failed gate to you, treat it
+   like `pr-blocked`: fix through the phases, never bypass.
+5. the controller merges; you then `spawn_worker` the **implementer** once more with the
    production-check task. It drives the changed path in production through the user's own access
    path and records what it saw on the pull request and on this issue. Close only after the implementer's production report exists.
    A defect it finds is a corrective child issue of this tree, not a note on a closed one; a deploy
@@ -306,7 +313,7 @@ active phase worker.
 | `pr-ready` | Verify the live PR head, green status, and review state. Continue the review/retro/merger order only for that current head. |
 | `pr-review` | Payload `{type:"pr-review", state, author, body}`. Delivered to whichever role is currently active for the issue, falling back to you when no worker phase is active. Follows the same verdict rule as a reviewer's `phase-complete`: `state: "changes_requested"` sends the implementer back in with the review findings, then tester, then reviewer — never the reviewer again and never retro; that `spawn_worker` returns the issue to `in_progress` on its own (the daemon writes it for a corrective implementer whenever the PR's latest recorded review is changes requested, a human's after approval included), so you set nothing by hand; `state: "approved"` proceeds toward retro (step 5) once the step 6 integration/merge-gate conditions are met. `state: "approved"` on a rebased head whose body names an unchanged fingerprint is that confirmation: proceed to retro if it has not run, otherwise to the merger — never to a second retro or test round. |
 | `pr-blocked` | Payload `{type:"pr-blocked", pr, attempts}`. `attempts` counts heads pushed onto a red verdict that changed something outside `.legion/` — handoff-only pushes (`.legion/` paths only) never count; a push the daemon cannot classify (a listener without `changed_paths`, a list capped at 100, a push listing no commits) does. Published once per exhausted count, not on every later red verdict for that count. Read the failed CI evidence and recovery attempts. Assign a focused implementer or corrective child, then return it through testing and review; do not treat the blocked PR as final. |
-| `pr-merged` | Payload `{type:"pr-merged", pr, mergeCommitSha}`. The merge queue landed the PR. `spawn_worker` the **implementer** with the production-check task naming that merge commit (it resumes the same agent; a retired role has no live holder, so never `envoy_publish` for this). Its `phase-complete` is what brings you to step 7: verify the record on the pull request and this issue first, then sign off naming it and set the issue `done`. A merge is not the close. |
+| `pr-merged` | Payload `{type:"pr-merged", pr, mergeCommitSha}`. The controller merged the PR. `spawn_worker` the **implementer** with the production-check task naming that merge commit (it resumes the same agent; a retired role has no live holder, so never `envoy_publish` for this). Its `phase-complete` is what brings you to step 7: verify the record on the pull request and this issue first, then sign off naming it and set the issue `done`. A merge is not the close. |
 | `pr-closed-unmerged` | Decide from current scope whether to reopen the work, send a fresh implementer, or cancel it with a reason. Delegate the repository action to the responsible phase worker and keep ownership. |
 | `issue-comment` | Interpret the comment in the issue's design context. Answer it, adjust the plan, or relay it via `envoy_publish` to the responsible worker's role token; scope and product decisions remain with you. |
 | `catchup-overseer` | Verify its child counts and PR verdicts against current artifacts, then resume the applicable lifecycle step. This is a current-state snapshot, not a raw-event replay. A root architect uses `gates[LEGION_TREE].open`: `true` means the root spec is approved and section 2 may continue; `false`, or no `open` key, means section 1 still applies. A resumed sub-architect receives `overseerCatchup(state, LEGION_ISSUE)` for its own subtree: its `gates` intentionally omits the root gate because a child spec is never gated. Do not request or register a gate; resume at section 2. Handle each `phaseCompletions` entry exactly as a `phase-complete` wake, then compare `childCounts[LEGION_ISSUE].open` with `legion state` and Dispatch before deciding the next action. |

package/skills/legion-controller/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: legion-controller
-description: Use when handling Legion controller wakes for root-issue triage, backlog admission, architect escalation, resync healing, or human interaction.
+description: Use when handling Legion controller wakes for root-issue triage, backlog admission, architect escalation, resync healing, merge-queue READY handling, or human interaction.
 ---
 
 # Legion Controller
@@ -14,21 +14,52 @@ routes raw events into an architect.
 The Legion extension claims `legion-<project>-controller` and registers controller readiness
 with the daemon during session startup. Do not handle a wake unless that startup succeeded.
 
-For an interactive takeover, start OMP with `LEGION_CONTROLLER_SECRET` (or
-`LEGION_CONTROLLER_SECRET_FILE`, a path to a file holding it) and `LEGION_DAEMON_URL` in its
-environment, then run:
+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
+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
+type into this session at any time. The pane carries the same credential environment as a
+worker's — `LEGION_GRANT_FILE`, `GH_CONFIG_DIR`, the GitHub token variables emptied; the
+`<state_dir>/worker-bin`-first `PATH` the daemon renders reaches no pane today (tmux drops the
+`-e PATH=` pair at pane creation, LEGION-91), so a bare `gh` is whatever the box has — so
+`legion gh -- <args>` works here exactly as it does for a phase worker (`legion` resolves through
+`<state_dir>/bin`, which the pane inherits from the daemon's own `PATH`):
+before every `bash` call the extension mints a short-lived controller grant and writes it to
+the file `LEGION_GRANT_FILE` names (never into the command text or the tool's `env`), `legion`
+reads it from there, and that grant is the only one the daemon lets merge a pull request.
+
+For an interactive takeover from a hand-started OMP session, start OMP with
+`LEGION_CONTROLLER_SECRET` (or `LEGION_CONTROLLER_SECRET_FILE`, a path to a file holding it),
+`LEGION_DAEMON_URL`, `LEGION_STATE_DIR` (the daemon's state directory), and `LEGION_GRANT_FILE`
+(an absolute path to a file only you can read, under a 0700 directory; the extension writes
+each command's grant there and every `bash` call is blocked without it) in its environment. Do
+not set `LEGION_CONTROLLER=1` — that marker is the daemon pane's own, and a session carrying it
+claims at startup and reports its transcript as the pane's. Then run:
 
 ```text
 /legion-claim-controller
 ```
 
 The command resolves the project from daemon state, claims the Envoy role for the current
-session, and posts readiness before controller commands can act. It retains the environment
-capability for `legion({ op: "set_status", issue, status })`. Never pass a secret as a command argument
-or copy it into a transcript. The claim is kept alive automatically afterwards: the Envoy
-registration heartbeat re-asserts it and re-posts readiness whenever the listener loses sight of
-this session, so `/legion-claim-controller` is the manual override, not a routine step after a
-listener restart.
+session, and posts readiness before controller commands can act. From then on this session's
+shell commands are wrapped with a controller grant exactly like the daemon pane's, so
+`legion gh -- <args>` works here; `legion status <KEY> <status>` works too, but through the
+controller secret in this session's environment (`LEGION_CONTROLLER_SECRET` or its `_FILE`),
+not the grant — if it fails, that is the variable to check. The takeover moves the role
+and the daemon's recorded session id to this session; it never replaces the transcript the
+daemon recorded for its own pane, so a later respawn of that pane resumes the pane's own
+conversation, not yours. Never pass a secret as a command argument or copy it into a transcript.
+The claim is kept alive automatically afterwards: the Envoy registration heartbeat re-asserts it
+and re-posts readiness whenever the listener loses sight of this session, so
+`/legion-claim-controller` is the manual override, not a routine step after a listener restart.
+
+Two limits of a takeover session. It caches the controller secret it started with: after the
+daemon respawns its own pane the secret rotates, every `bash` call in the takeover session then
+fails with a 403 from the grant mint, and the fix is to start a fresh OMP with the new secret,
+not to retry. And the role does not follow `/new` or `/fork` in a takeover session — without
+`LEGION_CONTROLLER=1` the new session is not a Legion session to the extension — so after either
+command run `/legion-claim-controller` again.
 
 This handshake lets the daemon redeliver held controller work. It does not turn the controller
 into a state holder: daemon state and the Dispatch project remain authoritative.
@@ -59,14 +90,16 @@ override a Sami ruling quoted here.
 
 | Wake | Content | Controller action |
 |---|---|---|
-| New issue created in the Dispatch project (`issue.created`, status `triage`; resync heals misses) | issue key + triage context (incl. pre-existing children) | Triage: `legion({ op: "set_status", issue, status: "todo" })` to admit, or set `backlog`/`icebox` to park |
+| New issue created in the Dispatch project (`issue.created`, status `triage`; resync heals misses) | issue key + triage context (incl. pre-existing children) | Triage: `legion status <KEY> todo` to admit, or set `backlog`/`icebox` to park |
 | Backlog eligibility | slot freed / priority change | Reconsider parked items and move the eligible root to `todo` |
 | Architect escalation (controller-actionable only: re-file a child as a root issue, capacity, cross-tree conflicts) | request + context | Judge and act; issue-scoped human Q&A goes through `dispatch_ask` from the owning architect, not here |
 | Resync report | artifact-driven anomaly list (zero-owner trees, untriaged-open, launch-failed, admission-drift) | Verify against fresh state, then heal |
 | Resync report: `admission-drift` entry | issue key + whether the daemon added it to, or removed it from, its admission list (the detail says which) | No action: the daemon already repaired it in the same run. An issue that reappears in consecutive reports is a live leak — file a LEGION issue on Dispatch with both reports pasted as evidence (never a GitHub issue) |
 | `child-status` | child key + status transition | Not controller-actionable by default; if the daemon could not route it to the parent's architect role, verify the transition and forward it with `envoy_publish` |
 | Mention | Slack/GitHub PR @mention text | Answer, or route to the owning issue's architect role |
-| Closed-tree activity (comment, review, CI on a closed tree) | issue, root, event summary | Read the artifact; if work should resume, `legion({ op: "set_status", issue: root, status: "todo" })`; otherwise no action — the event is not held or redelivered |
+| READY from a merger (`notifications.role.<controller token>`) | `READY #<n> at <current sha> (approved at <approved sha>) for <KEY> (<pr url>)` + gate facts | Run the Merge queue gates against live GitHub; merge, or report the failed gate to the tree's architect |
+| `pr.<n>.checks` settled on a PR with a pending READY | check rollup for the head | Re-run the Merge queue gates for that READY; merge, report, or keep waiting only if still pending |
+| Closed-tree activity (comment, review, CI on a closed tree) | issue, root, event summary | Read the artifact; if work should resume, `legion status <root> todo`; otherwise no action — the event is not held or redelivered |
 | Direct user message | — | Always first |
 
 ## New issue triage
@@ -77,17 +110,17 @@ override a Sami ruling quoted here.
 2. If it should run now, admit the root issue:
 
    ```text
-   legion({ op: "set_status", issue: "<issue>", status: "todo" })
+   legion status <issue> todo
    ```
 
 3. If it should deliberately wait, move it to a parked status instead of leaving it in
    `triage`:
 
    ```text
-   legion({ op: "set_status", issue: "<issue>", status: "backlog" })
+   legion status <issue> backlog
    ```
 
-   (or `status: "icebox"` for longer-term deferral). Dispatch status is the durable record;
+   (or `icebox` for longer-term deferral). Dispatch status is the durable record;
    there is no separate marker to maintain. Do not triage a system-created child as a root
    issue.
 
@@ -95,7 +128,7 @@ override a Sami ruling quoted here.
 
 When a slot frees or priority changes, use `legion state --json` and the current Dispatch
 issue to reconsider parked roots. Admit the selected root with
-`legion({ op: "set_status", issue, status: "todo" })`. Moving an item to or from `backlog`/
+`legion status <KEY> todo`. Moving an item to or from `backlog`/
 `icebox` is a deliberate controller decision, not a no-op.
 
 ## Architect escalation
@@ -110,7 +143,7 @@ and the Dispatch issue. If the work belongs in an independent root:
 1. File a **fresh root issue** with `dispatch_issue({ project, title, spec })` (no `parent`).
    `project` is the issue key's prefix before `-<n>` (e.g. `LEGSMOKE-3` → `LEGSMOKE`) — not
    the role-token `<project>` (the daemon's own project, e.g. `acme`), a different string.
-2. Park the child (`legion({ op: "set_status", issue: child, status: "icebox" })`) and leave
+2. Park the child (`legion status <child> icebox`) and leave
    a pointer to the new root issue. The controller's capability is `todo`/`backlog`/`icebox`
    only — only the owning architect or the daemon closes an issue as `done`.
 3. Admit or deliberately backlog the new root through the normal triage procedure.
@@ -141,3 +174,188 @@ gate at all runs `gates.design: off` in its `legion.yaml`. Otherwise resolve the
 owning architect role and route the verified context with `envoy_publish`. Do not route raw
 event traffic or invent a role token from a partial issue reference.
 
+## Merge queue
+
+The controller is the project's merge queue. A merger reports a pull request ready by
+publishing to the controller topic; the controller re-reads every gate from live GitHub and
+merges, or tells the tree's architect exactly which gate failed. The merger's report is a
+claim, never evidence.
+
+**READY message shape.** Defined once in `packages/pi-envoy/roles/merger.md` and mirrored here
+verbatim. The first line is
+`READY #<n> at <current sha> (approved at <approved sha>) for <KEY> (<pr url>)`: the pull
+request number, the sha of the pull request's current head, the sha the reviewer's head-pinned
+approval names, the issue key, and the pull request URL. The rest of the message is the PR
+body's gate facts (the `## Verification` block). You need every field: the URL addresses the
+pull request from this pane's working directory (which is not a checkout), the key finds the
+tree's architect (below), the current sha is the only head you may merge, and the approved sha
+anchors the two path-only compares in gates 5 and 6. The controller never verifies the
+approval itself: whether a review must exist before merge is the repository's own
+branch-protection or CODEOWNERS rule, which GitHub enforces at `pr merge` time and Legion
+neither reads nor writes.
+
+**Three shas.** This repository's flow leaves three commits that matter, and they are normally
+all different. The *verified* sha is the head the tester and the reviewer worked at: the
+`## Verification` block's own `CI`, `Thermo`, and `E2E` lines name it, and they must agree. After
+that head is found clean the implementer pushes the `.legion/` handoff deletion and the reviewer
+approves *that* head by name — the *approved* sha, one commit later. Retro then commits its
+`docs/solutions/` learning on top — the *current* sha. READY carries the current and approved
+shas; the verified sha you read from the block. The gates check the block at the verified sha
+and prove, with two compares, that nothing but the `.legion/` deletion lies between verified and
+approved, and nothing but `docs/solutions/` between approved and current.
+
+**Gates.** Read them from live GitHub, never from the message or the PR body alone. Every `gh`
+command takes the pull request URL, or `--repo <owner>/<repo>` taken from it, because this
+session's working directory has no git remote to resolve a bare number against:
+
+```text
+legion gh -- pr view <pr url> --json headRefOid,baseRefName,mergeable,body,files
+legion gh -- pr checks <pr url> --required --json name,state,bucket,link
+legion gh -- api repos/<owner>/<repo>/rules/branches/<baseRefName from pr view> --jq '[.[] | select(.type=="required_status_checks") | .parameters.required_status_checks[].context]'
+legion gh -- api repos/<owner>/<repo>/branches/<baseRefName from pr view> --jq '.protection.required_status_checks.contexts'
+legion gh -- api graphql -f query='query($owner:String!,$repo:String!,$n:Int!,$after:String){repository(owner:$owner,name:$repo){pullRequest(number:$n){reviewThreads(first:100,after:$after){pageInfo{hasNextPage endCursor}nodes{isResolved}}}}}' -F owner=<owner> -F repo=<repo> -F n=<n> -F after=<null for the first page>
+legion gh -- api repos/<owner>/<repo>/compare/<verified sha>...<approved sha> --jq '{status, files: [.files[].filename]}'
+legion gh -- api repos/<owner>/<repo>/compare/<approved sha>...<current sha> --jq '{status, files: [.files[].filename]}'
+```
+
+1. **head**: `headRefOid` equals the `<current sha>` in the READY. Any other head is a different
+   pull request as far as this READY is concerned.
+2. **checks**: `pr checks --required --json …` exits 0 with at least one row, and every row's
+   `bucket` is `pass` or `skipping`. That is the only green. The five buckets the CLI emits
+   (`gh pr checks --help`): `pass` and `skipping` are green — a job skipped by its `if:` (a
+   path-filtered workflow skips the jobs whose paths a pull request does not touch, and GitHub
+   treats a skipped job as satisfying a required check);
+   `pending` is pending; `fail` and `cancel` never merge (the Flake rule applies to both). With
+   `--json` the command exits 0 whenever rows exist, whatever their buckets, so the buckets
+   decide, never the exit code. Exit 1 comes only with no rows: `no checks reported on the
+   '<branch>' branch` when nothing has reported at the head yet (a freshly pushed head has no
+   check runs for a few seconds; a head that conflicts with the base never gets any, but that
+   head fails gate 4 — report it, do not subscribe), or `no required checks reported on the
+   '<branch>' branch` when checks exist but none is required. Either message is **pending**,
+   never green: subscribe to the pull request's `pr.<n>` and `pr.<n>.checks` topics exactly as
+   the Pending READY paragraph below says, and re-run the gates on that wake. (Without `--json`
+   the CLI exits 8 for pending rows and 1 for a failing row or no rows; you never run it that
+   way — the rows are what you read.) Two exceptions, both read from the repository, never from
+   the absence of rows:
+   - A repository that genuinely requires no checks. Required checks live in two places, and
+     both must be empty: the `rules/branches/<baseRefName>` query above (rulesets) returns `[]`
+     **and** the `branches/<baseRefName>` query above (the classic branch-protection summary,
+     which the implement App can read; the admin endpoint
+     `branches/<baseRefName>/protection/required_status_checks` is not readable under your credentials
+     and is not used) returns `[]`. Only then does the `no required checks reported` exit let
+     this gate hold with no check rows. A repository whose required checks are classic
+     protection answers `[]` for rulesets and the check names in the classic summary; `null`
+     from the classic query (no `protection` object in the answer) is not `[]` and leaves this
+     gate pending.
+   - A private repository on GitHub's free plan cannot define required checks at all: the
+     rulesets query answers HTTP 403 with a JSON body whose `message` **contains** the phrase
+     `make this repository public to enable this feature` (`gh` prints the whole message with
+     `(HTTP 403)` appended). Match that phrase as a substring — it is the stable tail; the head
+     names the plan (`Upgrade to GitHub Pro` for a user-owned repository, `Upgrade to GitHub
+     Team` for an organization-owned one) and the sentence ends with a period inside a JSON
+     wrapper, so literal equality never matches. Any other 403 — `Resource not accessible by
+     integration` included — is a permission error and stays an error, never "no required
+     checks". Under this exception gate 2 requires every check reported on the head to be green
+     instead: `legion gh -- pr checks <pr url> --json name,state,bucket,link` (without
+     `--required`) exits 0 with at least one row and every row's `bucket` is `pass` or
+     `skipping`. A `pending` row is pending, a `fail` or `cancel` row never merges, and no rows
+     (the exit-1 `no checks reported`) stays pending exactly as above. This is stricter than
+     "no required checks, merge", and GitHub still enforces whatever protection the repository
+     does have at `pr merge` time, so a wrong read costs a refused merge reported to the
+     architect, never an unprotected one.
+   Where each of these reads was observed — the CLI version, the two repositories, the exact
+   answers — is recorded in
+   `docs/solutions/legion/controller-gate-2-required-checks-live-reads.md`. The rule above is
+   what you execute; the live answers are what you read.
+3. **threads**: zero unresolved review threads across every page. Start with `after: null`, then
+   repeat the query with the prior page's `pageInfo.endCursor` until `hasNextPage` is false; the
+   count of `isResolved: false` across all pages must be 0. A missing `pageInfo`, a missing cursor
+   while `hasNextPage` is true, or any failed page is a failed gate: do not merge. This follows the
+   pagination `legion threads resolve` uses, but the controller reads only and never resolves a
+   review thread.
+4. **mergeable**: `mergeable` is not `CONFLICTING` and not `UNKNOWN`.
+5. **cleanup only**: `compare/<verified sha>...<approved sha>` reports `status` `identical` or
+   `ahead`, and every path in `files` starts with `.legion/` — the handoff deletion the reviewer
+   directed, and nothing else. Anything else between the two is the failed gate
+   `cleanup changed more than .legion`.
+6. **retro only**: `compare/<approved sha>...<current sha>` reports `status` `identical` or
+   `ahead`, and every path in `files` starts with `docs/solutions/`. Anything else between the
+   two is the failed gate `head moved beyond retro`: the approval no longer covers the head.
+7. **verification block**: the PR body's `## Verification` block (the template in
+   `skills/legion-worker/SKILL.md`) is complete and current at the verified sha. The tester
+   fills the `E2E` line before review; the reviewer writes the `Thermo` line at the head it
+   audited; approval lands one commit later on the cleanup head; so the block names the verified
+   sha, never the approved or the current one. Line by line: the `CI` line names a run and
+   reports success at one sha; the `Thermo` line names the same sha and a verdict, unless the
+   pull request is docs-only, in which case the template omits that line entirely — docs-only
+   is a fact you read, never one you take from the omission itself: every `path` in the `files`
+   list of the `pr view` command above starts with `docs/` or ends with `.md`
+   (`--jq '[.files[].path | select((startswith("docs/") or endswith(".md")) | not)]'` is `[]`);
+   a missing `Thermo` line on any other pull request fails this gate; the `E2E`
+   line names the same sha and has a `Negative control` line — those lines agreeing on one sha
+   is what defines the verified sha; the `Threads` line reports `0 unresolved` (its per-thread
+   lines name fixing commits, never the head — do not look for a sha there); the `Fast-follow`
+   and `Chain` lines are filled in. No `<placeholder>` text remains anywhere in the block.
+
+When all seven hold, merge:
+`legion gh -- pr merge <pr url> --squash --match-head-commit <current sha>`. The head pin makes
+GitHub refuse the merge if a push landed after gate 1 read the head; that refusal is a failed
+`head` gate, reported like any other. The grant your `bash` call carries is the controller's
+own, the only grant the daemon honours for a merge; the merge runs under the implement App's
+identity and the repository's own rules (branch protection, CODEOWNERS). Whether a human must
+approve first is that repository's setting — you neither read nor bypass it, and you never
+admin-merge without an explicit deployment grant from Sami for that specific merge.
+
+**Failed gate.** Reply to the tree's architect naming the gate (`head`, `checks`, `threads`,
+`mergeable`, `cleanup changed more than .legion`, `head moved beyond retro`, or
+`verification block`) and the evidence you read (the shas, the check name and run link, the
+thread count, the `mergeable` value, the offending paths from the compare). Do not merge, do not
+retry on a timer. The architect fixes through the phases.
+
+**Flake.** A required check that failed or was cancelled (`bucket` `fail` or `cancel`) for a
+reason unrelated to the change (a runner outage, a rate limit, a known-flaky job) may be rerun
+once: `legion gh -- run rerun <run-id> --failed --repo <owner>/<repo>`, the run id taken from
+the failing row's `link` (`https://github.com/<owner>/<repo>/actions/runs/<run-id>/job/<job-id>`).
+Then stop. The rerun's result reaches you as a `pr.<n>.checks` wake; re-run the gates then.
+A second failure is a failed gate, reported as above.
+
+**Conflicts and unknown mergeability.** `mergeable == CONFLICTING` is the only reason to ask
+for a rebase: reply to the tree's architect asking for one. Never request a rebase for any other
+reason — the CI queue is long and slow, and an unnecessary rebase clogs it for every other pull
+request. `mergeable == UNKNOWN` means GitHub has not finished computing it: do not merge, do
+not poll; re-read on the next `pr.<n>.checks` wake.
+
+**Pending READY.** A READY that cannot merge yet only because checks are still running (a
+`pending` row), none has reported at the head yet (gate 2's `no checks reported` exit), a flake
+rerun was issued, or `mergeable` is `UNKNOWN` is pending. Subscribe to that pull request's
+events so its settlement wakes you:
+
+```text
+envoy_subscribe({ topics: ["notifications.github.<owner>.<repo>.pr.<n>", "notifications.github.<owner>.<repo>.pr.<n>.checks"] })
+```
+
+On that wake, re-run the gates against the shas from the READY in your conversation, then
+`envoy_unsubscribe` those topics once you have merged or reported a failed gate. The controller
+never polls; READY and `pr.<n>.checks` are the only wakes. If you were resumed and no longer
+have the READY in your conversation, ask that issue's merger (its token is the `roles` key in
+`legion state --json` whose `issue` is `<KEY>` and whose `role` is `merger`; publish to
+`notifications.role.` followed by that key) to republish it; never guess a sha.
+
+**Finding the tree's architect.** Never hand-format a role token: the daemon lower-cases the
+issue key inside it (`LEGION-16` becomes `legion-16`) and rejects any other shape, so a token
+you assemble from `<KEY>` never matches a live role. Read it instead: `legion state --json`
+gives `issues[<KEY>].parent`; follow `parent` until it is absent — that key is the root (the
+`trees` map lists the same roots). Then take the `roles` key whose `issue` equals that root and
+whose `role` is `architect`, and publish to `notifications.role.` followed by that exact key.
+Every registered root architect and phase worker appears in `roles`, so the lookup is
+unambiguous. (Phase workers get an addressing line in their system prompt; the controller does
+not, so state is your only source.)
+
+**After a successful merge, publish nothing to the architect.** The daemon derives
+`{type:"pr-merged", pr, mergeCommitSha}` from GitHub's own merged webhook and routes it to the
+tree's architect itself. A second copy from you would make the architect run its sign-off twice.
+
+**Policy questions go to Sami.** Whether a pull request should merge at all, whether an admin
+merge is warranted, or a gate that looks wrong for this repository is not a controller judgment:
+ask with `dispatch_ask` on the issue, in plain sentences, and leave the READY pending until the
+answer arrives.

package/skills/legion-worker/SKILL.md

@@ -404,11 +404,15 @@ Verified the implementer's proof by <re-running its command | driving the same s
   `cd -- "$LEGION_WORKSPACE" && jj -R "$LEGION_WORKSPACE" git fetch && jj -R "$LEGION_WORKSPACE" diff --from <approved-sha> --to <tip-sha> --summary`,
   whose output is quoted in READY (an empty output is quoted as
   `no file changes above the approved head`); then the same with `'~docs/solutions'` appended,
-  which must print nothing. Then it publishes `READY #<n> at <tip-sha>` naming the approved
-  head, the tip, and that summary, plus the PR body's gate facts, to the merge queue's role
-  (`notifications.role.pr-queue`) with `envoy_publish`. The READY packet names both the
-  implementer's and the tester's `E2E` lines; a missing one is reported to the architect instead
-  of published. The merger never merges; the queue merges under its own authority.
+  which must print nothing. Then it publishes
+  `READY #<n> at <current sha> (approved at <approved sha>) for <KEY> (<pr url>)` (the shape
+  `packages/pi-envoy/roles/merger.md` defines) with that summary and the PR body's gate facts to
+  the project's controller topic (the merge queue, named in the `Legion addressing` line at the
+  end of the system prompt) with `envoy_publish`; on a 404 no-holder it publishes the same `READY`
+  to the architect's topic and stays idle. The READY packet names both the implementer's and the
+  tester's `E2E` lines; a missing one is reported to the architect instead of published. The
+  merger never merges; the controller verifies the
+  gates against live GitHub and merges under its own authority.
 - **After the queue merges, the implementer verifies in production.** Sami, 2026-09-13,
   verbatim: "the agent that developed it should be responsible for testing in production."
   The architect sends the implementer back once the merge lands; the implementer watches the