@sjawhar/opencode-legion-envoy 3.9.0 → 3.10.1

package/dist/src/server.js

@@ -15150,7 +15150,14 @@ class DispatchClient {
     return this.#json("POST", ["api", "v1", "projects", project, "architecture-source", "sync"]);
   }
   async getArchitectureSource(project) {
-    return this.#json("GET", ["api", "v1", "projects", project, "architecture-source"]);
+    try {
+      return await this.#json("GET", ["api", "v1", "projects", project, "architecture-source"]);
+    } catch (error48) {
+      if (error48 instanceof DispatchServiceError && error48.status === 404 && error48.code === "SOURCE_NOT_FOUND") {
+        return null;
+      }
+      throw error48;
+    }
   }
   async resolveAsk(id, input) {
     return this.#json("POST", ["api", "v1", "asks", id, "resolve"], input);
@@ -16041,13 +16048,23 @@ async function resolveOwnerArguments(tool, input, cwd, env, exec, serverUrl, pro
   const issue2 = `${repo2}#${legionIssue}`;
   return { args: { ...args, issue: issue2 }, ref, owner: { kind: "issue", issue: issue2 } };
 }
-function artifactByReference(artifacts, artifactReference, owner) {
-  const byIdOrSlug = artifacts.find((candidate) => candidate.id === artifactReference) ?? artifacts.find((candidate) => candidate.slug === artifactReference);
-  if (byIdOrSlug !== undefined)
-    return byIdOrSlug;
+function artifactByReference(artifacts, artifactReference, owner, canonical) {
+  const bySlug = artifacts.find((candidate) => candidate.slug === artifactReference);
+  if (canonical && bySlug !== undefined)
+    return bySlug;
+  const byId = artifacts.find((candidate) => candidate.id === artifactReference);
+  if (byId !== undefined)
+    return byId;
   const byName = artifacts.filter((candidate) => candidate.name === artifactReference);
+  if (bySlug !== undefined) {
+    const named = byName.filter((candidate) => candidate.id !== bySlug.id && candidate.kind === "doc");
+    if (named.length > 0) {
+      throw new Error(documentReferenceProblem(artifactReference, [bySlug, ...named], owner, "id"));
+    }
+    return bySlug;
+  }
   if (byName.length > 1) {
-    throw new Error(documentReferenceProblem(artifactReference, byName, owner, true));
+    throw new Error(documentReferenceProblem(artifactReference, byName, owner, "slug"));
   }
   const [artifact] = byName;
   if (artifact === undefined) {
@@ -16055,32 +16072,31 @@ function artifactByReference(artifacts, artifactReference, owner) {
   }
   return artifact;
 }
-async function resolveArtifact(client, owner, artifactReference) {
+async function resolveArtifact(client, owner, artifactReference, { canonical = false } = {}) {
   if (owner.kind === "project") {
     if (artifactReference === undefined) {
       throw new Error("artifact is required for a project document");
     }
-    try {
-      return {
-        owner,
-        artifact: await client.getProjectArtifact(owner.project, artifactReference)
-      };
-    } catch (error48) {
+    const routed = await client.getProjectArtifact(owner.project, artifactReference).catch((error48) => {
       if (!(error48 instanceof DispatchServiceError) || error48.status !== 404)
         throw error48;
-      const artifacts = await client.listProjectArtifacts(owner.project, true);
-      return {
-        owner,
-        artifact: artifactByReference(artifacts, artifactReference, "project")
-      };
-    }
+      return;
+    });
+    if (canonical && routed !== undefined)
+      return { owner, artifact: routed };
+    const unlinked = await client.listProjectArtifacts(owner.project, true);
+    const artifacts = routed === undefined ? unlinked : [routed, ...unlinked.filter((candidate) => candidate.id !== routed.id)];
+    return {
+      owner,
+      artifact: artifactByReference(artifacts, artifactReference, "project", canonical)
+    };
   }
   const issue2 = await client.getIssue(owner.issue);
   let artifact;
   if (artifactReference === undefined || artifactReference === "spec") {
     artifact = issue2.artifacts.find((candidate) => candidate.primary || candidate.id === issue2.primary_artifact_id);
   } else {
-    artifact = artifactByReference(issue2.artifacts, artifactReference, "issue");
+    artifact = artifactByReference(issue2.artifacts, artifactReference, "issue", canonical);
   }
   if (!artifact) {
     throw new Error(documentReferenceProblem(artifactReference ?? "spec", issue2.artifacts, "issue"));
@@ -16088,10 +16104,10 @@ async function resolveArtifact(client, owner, artifactReference) {
   return { owner, issue: issue2, artifact };
 }
 var documentHintLimit = 8;
-function documentReferenceProblem(reference, documents, owner, ambiguous = false) {
-  const hints = documents.slice(0, documentHintLimit).map((document) => `${document.slug} (${document.name})`);
+function documentReferenceProblem(reference, documents, owner, use) {
+  const hints = documents.slice(0, documentHintLimit).map((document) => use === "id" ? `${document.id} (${document.slug}, ${document.name})` : `${document.slug} (${document.name})`);
   const list = hints.length === 0 ? "none" : hints.join(", ");
-  return ambiguous ? `"${reference}" names ${documents.length} documents on this ${owner}; use a slug: ${list}` : `document "${reference}" not found by slug; this ${owner}'s documents: ${list}`;
+  return use === undefined ? `document "${reference}" not found by slug; this ${owner}'s documents: ${list}` : `"${reference}" names ${documents.length} documents on this ${owner}; use ${use === "id" ? "the id" : "a slug"}: ${list}`;
 }
 var askHintLimit = 8;
 function askIDInputProblem(asks, scope) {
@@ -16481,6 +16497,10 @@ async function executeDispatchTool(input) {
   const args = parsed.success ? parsed.data : ownerArguments.args;
   const actor = toolActor(await resolveOrigin(env, exec, input.cwd), input);
   const client = dispatchClient();
+  const refDocument = ownerArguments.ref?.kind === "artifact" ? ownerArguments.ref.id : ownerArguments.ref?.artifact;
+  const resolveDocument = (documentOwner2, reference) => resolveArtifact(client, documentOwner2, reference, {
+    canonical: reference !== undefined && reference === refDocument
+  });
   const owner = ownerArguments.owner?.kind === "issue" ? {
     kind: "issue",
     issue: await resolveExistingIssue(client, ownerArguments.owner.issue)
@@ -16771,7 +16791,7 @@ async function executeDispatchTool(input) {
         const issueKey = ref.owner.issue;
         id = await resolveIdPrefix(input.tool, "comment", ref.id, refOwnerName(ref), () => client.getComments(issueKey));
       } else if (ref !== null) {
-        const artifact = (await resolveArtifact(client, ref.owner, ref.artifact)).artifact;
+        const artifact = (await resolveArtifact(client, ref.owner, ref.artifact, { canonical: true })).artifact;
         document = artifact;
         id = await resolveIdPrefix(input.tool, "comment", ref.id, refOwnerName(ref), () => client.getArtifactComments(artifact.id));
       }
@@ -16783,7 +16803,7 @@ async function executeDispatchTool(input) {
       const anchorArgs = asObject(args.anchor);
       const owner2 = documentOwner();
       const artifactReference = optionalString(args, "artifact") ?? (anchorArgs === null ? undefined : optionalString(anchorArgs, "artifact"));
-      const resolved = owner2.kind === "project" || artifactReference === undefined ? owner2.kind === "project" ? await resolveArtifact(client, owner2, artifactReference) : undefined : await resolveArtifact(client, owner2, artifactReference);
+      const resolved = owner2.kind === "project" || artifactReference === undefined ? owner2.kind === "project" ? await resolveDocument(owner2, artifactReference) : undefined : await resolveDocument(owner2, artifactReference);
       const options = args.options;
       const multiple = optionalBoolean(args, "multiple");
       const urgency = askUrgency(args);
@@ -16833,7 +16853,7 @@ ${followsAsk(askOwner)}`,
     case "dispatch_comment": {
       const artifactReference = optionalString(args, "artifact");
       const owner2 = documentOwner();
-      const resolved = owner2.kind === "project" || artifactReference === undefined ? owner2.kind === "project" ? await resolveArtifact(client, owner2, artifactReference) : undefined : await resolveArtifact(client, owner2, artifactReference);
+      const resolved = owner2.kind === "project" || artifactReference === undefined ? owner2.kind === "project" ? await resolveDocument(owner2, artifactReference) : undefined : await resolveDocument(owner2, artifactReference);
       const anchored = resolved ? anchor(resolved.artifact, args) : undefined;
       const replyTo = optionalString(args, "reply_to");
       const replyToAskReference = optionalString(args, "reply_to_ask");
@@ -16886,7 +16906,7 @@ ${followsAsk(askOwner)}`,
       };
     }
     case "dispatch_suggest": {
-      const resolved = await resolveArtifact(client, documentOwner(), stringArg(args, "artifact"));
+      const resolved = await resolveDocument(documentOwner(), stringArg(args, "artifact"));
       const anchored = anchor(resolved.artifact, args);
       if (anchored === undefined)
         throw new Error("quote is required");
@@ -16941,7 +16961,7 @@ ${followsAsk(askOwner)}`,
       };
     }
     case "dispatch_doc_edit": {
-      const resolved = await resolveArtifact(client, documentOwner(), stringArg(args, "artifact"));
+      const resolved = await resolveDocument(documentOwner(), stringArg(args, "artifact"));
       const ops = args.ops;
       const summary = optionalString(args, "summary");
       const { precondition: rawPrecondition } = args;
@@ -16983,7 +17003,7 @@ ${followsAsk(askOwner)}`,
     }
     case "dispatch_doc_read": {
       const artifactReference = optionalString(args, "artifact") ?? (ownerArguments.ref?.kind === "spec" || ownerArguments.ref?.kind === "artifact" ? ownerArguments.ref.id : undefined);
-      const resolved = await resolveArtifact(client, documentOwner(), artifactReference);
+      const resolved = await resolveDocument(documentOwner(), artifactReference);
       const version2 = optionalNumber(args, "version") ?? ownerArguments.ref?.version;
       const documentPromise = client.docRead(resolved.artifact.id, version2);
       const marksPromise = openArtifactMarks(client, resolved);
@@ -17012,7 +17032,7 @@ ${trailer.join(`
     }
     case "dispatch_request_approval": {
       const artifactReference = optionalString(args, "artifact") ?? (ownerArguments.ref?.kind === "spec" || ownerArguments.ref?.kind === "artifact" ? ownerArguments.ref.id : undefined);
-      const resolved = await resolveArtifact(client, documentOwner(), artifactReference);
+      const resolved = await resolveDocument(documentOwner(), artifactReference);
       const result = await client.requestApproval(resolved.artifact.id, { actor });
       if (result.ask === null) {
         return {
@@ -17090,7 +17110,7 @@ ${trailer.join(`
     case "dispatch_read": {
       if (ownerArguments.ref?.kind === "ask") {
         const ref = ownerArguments.ref;
-        const id = await resolveIdPrefix(input.tool, "ask", ref.id, refOwnerName(ref), async () => ref.owner.kind === "issue" ? client.listIssueAsks(ref.owner.issue) : client.getArtifactAsks((await resolveArtifact(client, ref.owner, ref.artifact)).artifact.id, "all"));
+        const id = await resolveIdPrefix(input.tool, "ask", ref.id, refOwnerName(ref), async () => ref.owner.kind === "issue" ? client.listIssueAsks(ref.owner.issue) : client.getArtifactAsks((await resolveDocument(ref.owner, ref.artifact)).artifact.id, "all"));
         const askRead = await client.getAsk(id);
         const askRef = refTarget(ref, "ask", id);
         return {
@@ -17100,7 +17120,7 @@ ${trailer.join(`
       }
       if (ownerArguments.ref?.kind === "comment") {
         const ref = ownerArguments.ref;
-        const id = await resolveIdPrefix(input.tool, "comment", ref.id, refOwnerName(ref), async () => ref.owner.kind === "issue" ? client.getComments(ref.owner.issue) : client.getArtifactComments((await resolveArtifact(client, ref.owner, ref.artifact)).artifact.id));
+        const id = await resolveIdPrefix(input.tool, "comment", ref.id, refOwnerName(ref), async () => ref.owner.kind === "issue" ? client.getComments(ref.owner.issue) : client.getArtifactComments((await resolveDocument(ref.owner, ref.artifact)).artifact.id));
         const comment = await client.getComment(id);
         const commentRef = refTarget(ref, "comment", id);
         return {
@@ -17120,7 +17140,7 @@ ${trailer.join(`
         };
       }
       if (documentOwner().kind === "project") {
-        const resolved = await resolveArtifact(client, documentOwner(), stringArg(args, "artifact"));
+        const resolved = await resolveDocument(documentOwner(), stringArg(args, "artifact"));
         const documentRef = dispatchDocumentRef(resolved.artifact.project, resolved.artifact.slug);
         return {
           text: [

package/package.json

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

package/skills/dispatch/SKILL.md

@@ -603,7 +603,8 @@ dispatch_doc_read({ issue?, project?, artifact?, version?, ref? })
 ```
 It returns live or versioned markdown with open marks. A live read ends with a document token; `issue` with an
 omitted `artifact` reads the issue specification; a project needs `artifact`; and a
-`dispatch://PROJECT/artifact/<document-ref>` ref supplies both, where `document-ref` is the id, slug, or filename.
+`dispatch://PROJECT/artifact/<document-ref>` ref supplies both, where `document-ref` is the slug (an id or a
+filename resolves when no document has that slug).
 
 Editing one is [Editing a document](references/document-edits.md): the shape of `dispatch_doc_edit`,
 how to quote the text you mean, one `replace` per paragraph, preconditions against a stale edit, and
@@ -741,7 +742,9 @@ Exactly one of `path` and `content` is required. It returns issue or project-doc
 Uploading the same `name` creates its next version — so uploading `spec.md` **replaces the issue's own specification**
 with your text. Never do that: the spec is edited in place with `dispatch_doc_edit` (see [Editing a document](references/document-edits.md)). Address an existing
 artifact by the slug shown in the upload result or by its filename, and a project document by its artifact id, slug, or filename; the
-slug also arrives on `artifact.created` events.
+slug also arrives on `artifact.created` events. Dispatch suffixes a slug two documents would share, so one document's
+filename can be another's slug (`plan v2` takes `plan-v2`, then a document named `plan-v2` takes `plan-v2-2`): a bare
+`artifact` that names both is refused with each one's id, while a `dispatch://` reference's document part is always the slug.
 
 **Where a deliverable goes.** Text the human must read to decide — a draft message, a proposal,
 a summary — goes in the spec as a section: the spec is the one document they open. A separate

package/skills/legion-architect/SKILL.md

@@ -255,16 +255,20 @@ Preserve this order exactly:
    with options for its outcomes, and the issue waits for it.
 
 What returns the tree to review: a changed diff — a commit above the approved head that
-touches anything outside `docs/solutions/`, or a rebase whose fingerprint
+touches anything outside `docs/solutions/`, or a conflict-resolution merge whose fingerprint
 (`skill://legion-worker`'s unchanged-diff check) differs from the approved head's. What does not: retro's
-`docs/solutions/` commit, and a rebase forced by a GitHub-reported conflict whose fingerprint
-is unchanged. For that rebase the order is: the implementer rebases, pushes the rebased chain with
-`legion-worker`'s procedure for rewritten commits, and posts the before/after fingerprints; the tester re-runs the bare gates only; the reviewer confirms and approves the new
-head by SHA (or continues its round if it had not approved); the merger republishes READY.
-Retro does not re-run. A rebase happens only when GitHub reports `CONFLICTING`
+`docs/solutions/` commit, and a merge forced by a GitHub-reported conflict whose fingerprint
+is unchanged. For that merge the order is: the implementer merges the bookmark forward with the
+destination (`legion-worker`'s forward-merge procedure — `jj new legion/<KEY> <destination>`,
+never a rebase, since a rebase rewrites every descendant of the chain's fork point, including
+another tree's branch stacked on it), pushes it with the ordinary push procedure (a genuine
+fast-forward), and posts the before/after fingerprints; the tester re-runs the bare gates only;
+the reviewer confirms and approves the new head by SHA (or continues its round if it had not
+approved); the merger republishes READY. Retro does not re-run. This merge happens only when
+GitHub reports `CONFLICTING`
 (`legion gh -- pr view <n> --json mergeable,mergeStateStatus`); read that on every end-game
 wake — `pr-ready`, `pr-review`, `phase-complete`, `catchup-overseer` — because a `CONFLICTING`
-PR gets no CI and no wake announces it, and send the implementer to rebase the moment you see
+PR gets no CI and no wake announces it, and send the implementer to resolve it the moment you see
 it. Do not let the merger publish `READY` for an obsolete approval.
 
 If a worker reports that `legion threads resolve` exited 1 naming a review thread GitHub refused

package/skills/legion-worker/SKILL.md

@@ -280,7 +280,7 @@ Verified the implementer's proof by <re-running its command | driving the same s
 **Fast-follow:** <one named cleanup item and where it will land>, or "none".
 
 **Chain:** stacked on <base bookmark> frozen at <sha> / not stacked.
-**Retarget:** Retargeting a pull request to a new base does not re-run Tests; after a retarget, record the pushed tip, rebase onto the new base, and push with `legion-worker`'s procedure for rewritten commits — the new head runs Tests against the new merge result — and cite that run in the PR body.
+**Retarget:** Retargeting a pull request to a new base does not re-run Tests; after a retarget, merge the bookmark onto the new base (`jj new legion/<KEY> <new base> -m "<message>"`) and push with `legion-worker`'s ordinary push procedure — a genuine fast-forward, never the procedure for rewritten commits — the new head runs Tests against the new merge result — and cite that run in the PR body.
 ```
 
 **A proof** is the changed behaviour exercised on the surface a user reaches it through, recorded
@@ -362,9 +362,30 @@ this proof.
   the fingerprint at the current tip; after pushing the rebased branch, record it at the new
   tip; post one PR comment (Legion footer):
   `rebase <old-tip-sha> → <new-tip-sha>; fingerprint <before> → <after>; unchanged|changed`.
-  Rebase the whole chain — `jj -R "$LEGION_WORKSPACE" rebase -s 'roots(main@origin..@)' -d main@origin` —
-  so the tester's and reviewer's commits move with yours. Record the pushed tip before it and
-  push the rebased chain with the push procedure (*Rewriting pushed commits*, below).
+  Every issue workspace is a `jj workspace` of the same shared repository and operation log, and
+  jj always rebases every descendant of any commit it rewrites — a revset naming the root of your
+  own chain and rewriting it in place also rewrites whatever another tree has stacked on that root,
+  whichever selector chose it (`-s`, `-b`, and `-r` all rewrite descendants; `-r` only re-parents
+  them to fill the hole, which is worse). This is what happened in LEGION-118: one issue's own
+  conflict step moved a second issue's twelve commits and its bookmark onto a conflicted copy.
+  Resolve the conflict with a forward merge instead of a rewrite — merge the branch's own
+  bookmark with the destination in one new commit, so nothing existing is rewritten and nothing
+  built on your prior commits, in this tree or another, ever moves:
+
+  ```bash
+  jj -R "$LEGION_WORKSPACE" new legion/<KEY> main@origin -m "merge: resolve conflict against main@origin"
+  ```
+
+  Merge from the bookmark, never from `@`: a handoff split leaves `@` an empty, undescribed
+  commit above the described one the bookmark already names, and `jj git push` refuses to push
+  any commit without a description — merging from `@` drags that undescribed commit into the
+  ancestry and the push fails (`Won't push commit … since it has no description`); the bookmark
+  is always on a described, already-pushed commit. If the merge conflicts, resolve it in that
+  one commit — edit the markers directly; there is nothing to squash, since the merge is the
+  only new commit. Then `jj -R "$LEGION_WORKSPACE" new` to move off it, and push with the one
+  push procedure (*Every role pushes its own commits*, below): the merge descends from both the
+  bookmark's old position and the destination, so it is a genuine fast-forward and *Rewriting
+  pushed commits* never applies — nothing was rewritten, so there is no tip to record first.
 - **No deferrals.** Sami, 2026-09-11, verbatim: "My rule is no deferrals." The `Fast-follow:`
   field names naming, duplication, or wording cleanup only; anything that changes behaviour,
   hides an error, or breaks a gate lands in this PR.
@@ -586,8 +607,8 @@ remote branch sideways onto your commit and drops theirs (jj 0.45.1:
 `bookmark: legion/K [move sideways from <theirs> to <yours>]`). A clone that has not seen the other
 push is refused by jj itself (`unexpectedly moved on the remote`).
 
-**Rewriting pushed commits** — the conflict-forced rebase, the rebase after a retarget, or a
-`jj squash --into` a commit already on GitHub — leaves the pushed tip outside `::@-`, so record
+**Rewriting pushed commits** — a `jj squash --into` a commit already on GitHub, or any other
+rewrite of a commit you already pushed — leaves the pushed tip outside `::@-`, so record
 that tip first, after a fetch and while your chain still descends from it:
 
 ```bash