@sjawhar/pi-legion-envoy 0.13.0 → 0.14.0

package/README.md

@@ -92,8 +92,9 @@ stateless request to the dispatch service, which writes the issue or comment. Th
 `dispatch` skill (shipped in `skills/`) says when and how to ask. Replies route back to the
 asking session, which is auto-subscribed to the thread's GitHub topic on every successful
 call; a Legion role's session survives kill/resume because Legion resurrection resumes the
-same OMP session file. Lifecycle and scope decisions still go through `hub` to the owning
-architect — Dispatch is for durable questions to the human, not for coordination between roles.
+same OMP session file. Lifecycle and scope decisions go through `envoy_publish` to the owning
+architect's role topic — Dispatch is for durable questions to the human, not for coordination
+between roles.
 
 The tool's model-facing schema is the shared contract's zod shape
 (`@legion/envoy-client/dispatch-contract`) serialised to JSON Schema, so OMP shows the model

package/dist/legion.js

@@ -32487,7 +32487,34 @@ async function persistedTranscript(context) {
     throw new Error("Legion session transcript has no agent id");
   return { sessionFile, agentId };
 }
+function isSingleLegionCommand(command) {
+  if (typeof command !== "string")
+    return false;
+  const trimmed = command.trim();
+  if (trimmed.length === 0)
+    return false;
+  let quote;
+  for (const char of trimmed) {
+    if (quote !== undefined) {
+      if (char === quote)
+        quote = undefined;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      continue;
+    }
+    if (char === `
+` || char === ";" || char === "&" || char === "|")
+      return false;
+  }
+  if (quote !== undefined)
+    return false;
+  return trimmed.split(/\s+/, 1)[0] === "legion";
+}
 var LEGION_LOADED_MARKER = Symbol.for("legion.pi-envoy.legion-loaded");
+var CODE_MUTATION_TOOLS = ["edit", "write", "apply_patch"];
+var MERGER_BLOCKED_TOOLS = [...CODE_MUTATION_TOOLS, "task"];
 function legionExtension(pi) {
   logger2.debug("extension instance loaded", { extension: import.meta.url });
   globalThis[LEGION_LOADED_MARKER] = import.meta.url;
@@ -32731,20 +32758,24 @@ function legionExtension(pi) {
   });
   pi.on("tool_call", async (toolCall, context) => {
     const sessionID = context.sessionManager.getSessionId();
-    if (capability !== undefined && capability.kind === "root-architect" && capability.sessionID === sessionID && ["edit", "write", "bash", "apply_patch"].includes(toolCall.toolName)) {
+    const active = capability?.sessionID === sessionID ? capability : undefined;
+    if (active?.role === "architect" && (CODE_MUTATION_TOOLS.includes(toolCall.toolName) || toolCall.toolName === "bash" && !isSingleLegionCommand(toolCall.input.command))) {
       return { block: true, reason: "the architect delegates all code work to phase workers" };
     }
-    if (capability !== undefined && capability.kind === "phase-worker" && capability.sessionID === sessionID) {
-      if (capability.role === "reviewer" && ["edit", "write", "apply_patch"].includes(toolCall.toolName)) {
-        return { block: true, reason: "the reviewer does not modify the branch" };
+    if (active?.kind === "phase-worker") {
+      if (active.role === "reviewer" && CODE_MUTATION_TOOLS.includes(toolCall.toolName)) {
+        return {
+          block: true,
+          reason: "the reviewer edits nothing except the final .legion/ cleanup commit via bash"
+        };
       }
-      if (capability.role === "merger" && ["edit", "write", "apply_patch", "task"].includes(toolCall.toolName)) {
+      if (active.role === "merger" && MERGER_BLOCKED_TOOLS.includes(toolCall.toolName)) {
         return { block: true, reason: "the merger only verifies and reports" };
       }
     }
     if (toolCall.toolName !== "bash" || typeof toolCall.input.command !== "string")
       return;
-    if (capability === undefined || capability.sessionID !== sessionID) {
+    if (active === undefined) {
       if (process.env.LEGION_ROLE !== undefined && process.env.LEGION_CONTROLLER !== "1") {
         return {
           block: true,
@@ -32755,10 +32786,10 @@ function legionExtension(pi) {
     }
     try {
       const grant = await roleDaemon().grant({
-        tree: capability.tree,
-        issue: capability.issue,
+        tree: active.tree,
+        issue: active.issue,
         sessionId: sessionID,
-        secret: capability.secret
+        secret: active.secret
       });
       const stateDir = requiredEnvironment(process.env, "LEGION_STATE_DIR");
       const workerBin = await installWorkerGhShim(stateDir);

package/dist/skills/legion-architect/SKILL.md

@@ -14,12 +14,22 @@ separate coordinator to finish necessary work.
 
 - Use the `legion` tool for lifecycle writes. Its issue key format is
   `owner/repo#number`.
-- Use `task` for every Legion role spawn and `hub` to direct or revive a known phase
-  worker. Phase workers escalate lifecycle, scope, and cross-phase matters inward to you
-  through hub. Any role may use `dispatch` directly for a standalone human question;
-  replies return to the asking session.
-- The runtime, not you, appends a machine `<legion-spawn>` block. Each Legion `task`
-  text must start with `Legion-Issue: <owner/repo#n>` on its first line.
+- Use `legion({ op: "spawn_worker", issue, role, task })` for every Legion role spawn.
+  Message a known phase worker with `envoy_publish` to `notifications.role.` followed by
+  its encoded role token (the token `spawn_worker` returned for it); re-assign it by
+  calling `spawn_worker` again on the same existing role, which resumes the same process
+  instead of starting a fresh one. Phase workers escalate lifecycle, scope, and
+  cross-phase matters the same way: `envoy_publish` to your own encoded token. Any role
+  may use `dispatch` directly for a standalone human question; replies return to the
+  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>-<encoded-owner>__<encoded-repo>-<number>-<role>` (escaping `_`, `.`,
+  and `-` within the owner/repo names); for example, project `acme`, issue
+  `sjawhar/legion#41`, role `architect` encodes to `legion-acme-sjawhar__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.
 - Use only the live label vocabulary: `needs-approval`, `human-approved`,
   `legion-child`, and `legion-backlog`. Do not attempt to apply a label whose ownership
   belongs to the controller or Sami.
@@ -30,12 +40,16 @@ separate coordinator to finish necessary work.
 ## 1. Decompose or adopt
 
 Inspect the root issue, acceptance criteria, existing children, and current handoffs.
+Decomposition is complete only when every child issue names the real surface its acceptance
+criteria are proven on and the repository skill that drives it; if the repository cannot
+exercise a criterion end to end, building that path is a child issue of this tree.
 
 - **Existing children:** adopt them. Do not replace or re-decompose human-created work.
   Put every adopted child into the initial wave. **You MUST call**
   `legion({ op: "wave_release", children: ["owner/repo#41", "owner/repo#42"] })`
-  **before any `task` spawn for an adopted child.** Until release, the daemon holds that
-  child's role activity. Then spawn each child's in-process `legion-architect` owner.
+  **before any `spawn_worker` call for an adopted child.** Until release, the daemon
+  holds that child's role activity. Then spawn each child's daemon-managed sub-architect
+  owner.
 - **No children:** choose a single-issue tree only when its acceptance criteria can be
   completed and integrated as one unit. Otherwise create complete child issues with:
 
@@ -81,32 +95,37 @@ explicit lifecycle write:
 legion({ op: "wave_release", children: ["owner/repo#41", "owner/repo#42"] })
 ```
 
-After release, spawn each relevant owner with an issue-prefixed task; for example:
+After release, spawn each relevant owner; for example:
 
 ```text
- task({
-   agent: "legion-architect",
-   task: "Legion-Issue: owner/repo#41\nOwn this child through its lifecycle and report its evidence."
- })
+legion({
+  op: "spawn_worker",
+  issue: "owner/repo#41",
+  role: "architect",
+  task: "Own this child through its lifecycle and report its evidence."
+})
 ```
 
-Do not add a `<legion-spawn>` block. Keep the child agent IDs and session identifiers
-returned by `task`, because retro and adjustment use those live sessions. Park while
-children are in flight. On each child closure, re-scope open work, close obsolete work
-with a reason, and release the next wave only when it now makes sense. There is no
-inter-child dependency mechanism to encode.
+The daemon spawns that sub-architect as its own process with the child's context already
+in its environment; a resume of an existing role continues the same process instead of
+starting a fresh one. Keep the returned session identifiers, because retro and adjustment
+use those live sessions. Park while children are in flight. On each child closure,
+re-scope open work, close obsolete work with a reason, and release the next wave only
+when it now makes sense. There is no inter-child dependency mechanism to encode.
 
 ## 3. Children complete
 
 Treat `children-complete` as the edge into the end-game, not as a reason to close the
-parent. Launch one **fresh** `legion-tester` for the parent, scoped to the parent's own
-acceptance criteria and current `main` integration surface:
+parent. Spawn the parent's `tester` role, scoped to the parent's own acceptance criteria
+and current `main` integration surface:
 
 ```text
- task({
-   agent: "legion-tester",
-   task: "Legion-Issue: owner/repo#40\nFreshly verify this parent issue against its acceptance criteria on current main; return reproducible integration evidence."
- })
+legion({
+  op: "spawn_worker",
+  issue: "owner/repo#40",
+  role: "tester",
+  task: "Verify this parent issue against its acceptance criteria on current main; return reproducible integration evidence."
+})
 ```
 
 If that tester finds a failure, create and release a new corrective child wave, then
@@ -115,25 +134,25 @@ failure forward.
 
 ## 4. Integration verification
 
-Read the fresh tester's evidence, not merely a child PR's check status. The parent test
+Read the tester's evidence, not merely a child PR's check status. The parent test
 is successful only when every parent acceptance criterion has evidence against current
 main. Route a failed criterion into a corrective child wave; route a passing result to
 review and the merge-gate sequence.
 
 ## 5. Retro
 
-Retro is mandatory for every issue that passed review, before merge. Revive the parked
-implementer that owns the reviewed work through `hub`, naming the skill in the message:
+Retro is mandatory for every issue that passed review, before merge. Message the
+implementer's live session (idle since it completed its phase; the daemon never tears
+it down) with `envoy_publish` to its role token, naming the skill:
 
 ```text
-hub({
-  op: "send",
-  to: "<implementer agent identifier>",
+envoy_publish({
+  topic: "notifications.role.<implementer's encoded token>",
   message: "Run the legion-retro skill now. Capture durable learnings and post the issue comment; do not create a .legion handoff file."
 })
 ```
 
-Wait for the revived implementer to report its durable retro result. Retro output is
+Wait for the messaged implementer to report its durable retro result. Retro output is
 `docs/solutions/` plus an issue comment; it must not create a `.legion` file or change
 the reviewer-approved head after cleanup.
 
@@ -154,10 +173,11 @@ When the config-armed final merge gate applies, preserve this order exactly:
    approval already satisfies the gate and you immediately continue to the merger; do not
    wait for a new wake. If it returns `approved: false`, request or retain Sami approval
    and park for a later `pr-ready` wake. Do not poll or retry this check;
-5. `legion-merger` verifies the approved head and squash-merges without pushing.
+5. The merger verifies the approved head and publishes `READY #<n> at <sha>` to
+   `notifications.role.pr-queue`; it never merges. The merge queue approves and merges under its own authority.
 
-If anything changes the approved head, return to review; do not ask the merger to merge
-an obsolete approval.
+If anything changes the approved head, return to review; do not let the merger publish
+`READY` for an obsolete approval.
 
 ## 7. Close
 
@@ -183,14 +203,17 @@ corresponding lifecycle procedure.
 | Wake | Procedure |
 | --- | --- |
 | `child-closed` | Read the child completion and remaining open children. Re-scope or close obsolete open work; release an appropriate next wave, or await `children-complete`. |
-| `children-complete` | Execute steps 3–4: fresh parent integration verification; failures become a new child wave, success advances to review and retro. |
+| `children-complete` | Execute steps 3–4: parent integration verification; failures become a new child wave, success advances to review and retro. |
 | `child-reopened` | Treat the completion edge as reset. Reassess the reopened child and return the tree to children-in-flight; do not continue an already-started end-game. |
+| `phase-complete` | Payload `{type:"phase-complete", issue, role, summary}`. May arrive live or via `catchup-overseer`'s `phaseCompletions`. Read the committed handoff for that phase, then spawn the next phase's owner, or `spawn_worker` on the same role again to resume it with corrections if the handoff shows unresolved gaps. |
+| `worker-queued` | Payload `{type:"worker-queued", issue, role}`. The deployment's worker cap is full; this role's spawn is queued. Do not respawn or retry — wait for `worker-started`. |
+| `worker-started` | Payload `{type:"worker-started", issue, role}`. A previously queued role has been promoted and is now running. Treat it exactly as a normal spawn: resume tracking that role's live session. |
 | `pr-ready` | Verify the live PR head, green status, and review state. Continue the review/retro/Sami/merger order only for that current head. |
 | `pr-blocked` | 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-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 through `hub` to the responsible worker; scope and product decisions remain with you. |
-| `catchup-overseer` | Verify its gates, child counts, and PR verdicts against current artifacts, then resume the applicable numbered lifecycle step. It is a current-state snapshot, not a raw-event replay. |
-| `revive-worker` | The extension has revived the backed worker. Do not create a duplicate; direct the restored worker through `hub` if action is needed and rely on its committed handoff over recollection. |
+| `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 gates, child counts, and PR verdicts against current artifacts, then resume the applicable numbered lifecycle step. It is a current-state snapshot, not a raw-event replay. For each entry in its `phaseCompletions` (`{issue, role, summary, at}`, phases that completed while you were not live), handle it exactly as a `phase-complete` wake. |
+| `revive-worker` | The extension has revived the backed worker. Do not create a duplicate; message the restored worker via `envoy_publish` to its role token if action is needed and rely on its committed handoff over recollection. |
 | `reopened` | Reopen the root lifecycle: inspect the reason and current artifacts, reassess scope and children, and resume at the first applicable numbered step. |
 
 ## Escalation judgment

package/dist/skills/legion-retro/SKILL.md

@@ -19,7 +19,7 @@ retrospective's durable output.
 3. Run this retro: commit durable learnings to `docs/solutions/` and post the issue comment.
    Retro writes **no `.legion` file**, so it never re-dirties the cleaned handoff tree.
 4. Sami approves the final reviewed head.
-5. The merger squash-merges and pushes nothing.
+5. The merger verifies the approved head, publishes `READY`, and pushes nothing; the merge queue merges.
 
 Do not start retro before step 2, skip it because the change seems mechanical, or merge before
 steps 3 and 4. The design gate is not a substitute for this final merge gate.

package/dist/skills/legion-worker/SKILL.md

@@ -24,10 +24,12 @@ Your role token is not the issue key spelled out literally. The daemon encodes i
 `legion-<project>-<encoded-owner>__<encoded-repo>-<number>-<role>`, escaping `_`, `.`, and
 `-` within the owner and repo names (`_u`, `_d`, `_h`) so `__` is always the one safe
 separator. For example, project `acme`, issue `sjawhar/legion#41`, role `architect` encodes
-to `legion-acme-sjawhar__legion-41-architect`. Never hand-format one for another role: the
-daemon's boot response already gives you your own token, and the `roleToken` helper in
-`@legion/contracts` computes any other one exactly the way the daemon does — reuse a token
-you've already been given before recomputing it.
+to `legion-acme-sjawhar__legion-41-architect`. Never hand-format one for another role: your
+own role topic and your tree's architect's topic are stated at the end of your system
+prompt (a "Legion addressing" line the daemon appends), a sibling role's topic is yours
+with the trailing `-<role>` replaced, and the `roleToken` helper in `@legion/contracts`
+computes any other one exactly the way the daemon does — prefer a topic you've already
+been given before recomputing one.
 
 If the handshake fails (a rejected boot token, or a bootstrap failure after your role
 registered), the extension logs it and exits the process outright — it does not retry, and
@@ -165,10 +167,9 @@ The provisioned issue workspace configures `credential.helper` with the daemon's
 credential command, so `jj -R "$LEGION_WORKSPACE" git push` authenticates transparently
 through the same session capability. Never handle a token.
 
-Then create the pull request with the `github` tool's `pr_create` operation. The credential
-helper and `legion gh` provide the GitHub identity; never export, fetch, or replace a
-token. Other phases advance the existing branch rather than creating a replacement
-bookmark or PR.
+Then open the pull request with `legion gh -- pr create`. The credential helper and
+`legion gh` provide the GitHub identity; never export, fetch, or replace a token. Other
+phases advance the existing branch rather than creating a replacement bookmark or PR.
 
 ## PR body and merge-queue discipline
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/pi-legion-envoy",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "type": "module",
   "omp": {
     "extensions": [