@sjawhar/pi-legion-envoy 0.2.0 → 0.3.0

package/README.md

@@ -64,18 +64,18 @@ OMP at extension files it does not contain.
 
 ## Dispatch
 
-Legion sessions use the `envoy_dispatch` tool from `extensions/legion.ts`: it routes through
-the Legion daemon's architect-only, tree-scoped `/legion/v1/dispatch-threads` endpoint, which
-also registers the thread so replies route back to the tree. The raw dispatch MCP tool is
-deliberately not served to Legion sessions — the shared shim exits without serving when it
-sees a Legion environment (`LEGION_TREE`/`LEGION_CONTROLLER`), so phase workers cannot bypass
-the architect gate with ambient GitHub authority.
-
-Interactive OMP sessions get the `dispatch` MCP tool the way OpenCode sessions do: the shared
-`@legion/envoy-client` shim mounts as a stdio MCP server, and it serves only when
-`dispatch.enabled` is true in the shared envoy.json (`~/.config/opencode/envoy.json`,
-shallow-merged with `<cwd>/.opencode/envoy.json`) or `DISPATCH_MCP_URL` is set explicitly.
-The server URL comes from `dispatch.serverUrl` (default `http://localhost:8766`).
+Every OMP session — Legion sessions included — gets the `dispatch` MCP tool the way
+OpenCode sessions do: the shared `@legion/envoy-client` shim mounts as a stdio MCP server,
+and it serves when `dispatch.enabled` is true in the shared envoy.json
+(`~/.config/opencode/envoy.json`, shallow-merged with `<cwd>/.opencode/envoy.json`) or
+`DISPATCH_MCP_URL` is set explicitly. The server URL comes from `dispatch.serverUrl`
+(default `http://localhost:8766`). Dispatch exists so headless unattended agents —
+Legion architects, planners, phase workers — can raise durable questions to the human.
+Replies route back to the asking session, which is auto-subscribed to the thread's
+GitHub topic; a Legion role's session survives kill/resume because Legion resurrection
+resumes the same OMP session file, so the reply still lands. 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.
 
 Mount it in `~/.omp/agent/mcp.json` (user-wide) or `.omp/mcp.json` (per project):
 

package/dist/envoy.js

@@ -29857,21 +29857,6 @@ var LegionDaemonApi = {
     request: architectCapability.extend({ issue: nonEmptyString, comment: exports_external.string().optional() }),
     response: exports_external.object({})
   },
-  DispatchThread: {
-    request: exports_external.strictObject({
-      tree: nonEmptyString,
-      issue: nonEmptyString,
-      role: legionRole,
-      sessionId: nonEmptyString,
-      secret: nonEmptyString,
-      parent: nonEmptyString,
-      subject: nonEmptyString,
-      body: nonEmptyString,
-      ask: exports_external.unknown().optional(),
-      urgency: exports_external.enum(["low", "med", "high", "blocking"]).optional()
-    }),
-    response: exports_external.object({ thread: exports_external.number().int(), url: nonEmptyString })
-  },
   SpawnToken: {
     request: architectCapability.extend({ issue: nonEmptyString, role: legionRole }),
     response: exports_external.object({ spawnToken: nonEmptyString })
@@ -29961,6 +29946,29 @@ function normalizeEnvoyUrl(value) {
   return value.replace(/\/+$/, "");
 }
 
+// ../envoy-client/src/dispatch-subscribe.ts
+var ISSUE_URL_RE = /https?:\/\/github\.com\/([^/\s"]+)\/([^/\s"]+)\/issues\/(\d+)/i;
+var DISPATCH_TOOL_RE = /(^|[-._])dispatch$/i;
+function isDispatchTool(tool) {
+  return DISPATCH_TOOL_RE.test(tool);
+}
+function dispatchThreadTopic(owner, repo, thread) {
+  return `notifications.github.${owner}.${repo}.issue.${thread}.>`;
+}
+function dispatchSubscriptionTopic(tool, output) {
+  if (!isDispatchTool(tool))
+    return null;
+  const match = ISSUE_URL_RE.exec(output);
+  if (!match)
+    return null;
+  const owner = match[1];
+  const repo = match[2];
+  const thread = Number(match[3]);
+  if (!Number.isInteger(thread) || thread <= 0)
+    return null;
+  return dispatchThreadTopic(owner, repo, thread);
+}
+
 // ../envoy-client/src/errors.ts
 function messageFor(error48) {
   return error48 instanceof Error ? error48.message : String(error48);
@@ -30897,6 +30905,18 @@ function envoyExtension(pi) {
     }, defaults.heartbeatMs);
     heartbeatRegistered = true;
   };
+  const recoverRegisteredInterests = async () => {
+    const registry2 = await client.getInterest(sessionID).catch(() => {
+      return;
+    });
+    if (registry2 === undefined)
+      return;
+    for (const topic of registry2.topics) {
+      if (topic === agentSubject(sessionID) || topic.startsWith(ROLE_TOPIC_PREFIX))
+        continue;
+      await subscribe(topic);
+    }
+  };
   const establishSession = async (context) => {
     const previousTopic = sessionID === "" ? undefined : agentSubject(sessionID);
     sessionDirectory = context.cwd;
@@ -30908,6 +30928,9 @@ function envoyExtension(pi) {
     }
     await ensureConnection();
     await subscribe(currentTopic);
+    if ((context.sessionManager.getBranch?.() ?? []).length > 0) {
+      await recoverRegisteredInterests();
+    }
     if (registrationRequired()) {
       await registerSession();
       ensureHeartbeat(context);
@@ -31003,6 +31026,19 @@ function envoyExtension(pi) {
     });
   }
   registerEnvoyWhoamiCommand(pi, () => sessionID);
+  pi.on("tool_result", async (event) => {
+    if (event.isError)
+      return;
+    const topic = dispatchSubscriptionTopic(event.toolName, JSON.stringify(event.details) ?? "");
+    if (topic === null)
+      return;
+    try {
+      if (await subscribe(topic))
+        await registerSession();
+    } catch (error48) {
+      activeSessionContext?.ui.notify(`envoy: dispatch reply auto-subscribe failed (${messageFor(error48)}); run envoy_subscribe ${topic}`, "warning");
+    }
+  });
   async function execute(operation, parameters) {
     try {
       switch (operation) {

package/dist/skills/AGENTS.md

@@ -25,9 +25,10 @@ returns that schema to the architect. It writes the same phase-specific payload
 `.legion/<phase>.json`, verifies it exists, and commits the handoff before reporting completion.
 The committed predecessor handoff wins after revival or re-creation.
 
-Workers do not run a controller loop, mutate lifecycle labels, or create human dispatch threads.
-When an issue needs a product, scope, cross-phase, or human decision, they send the owning
-architect the verified observation and decision needed through hub.
+Workers do not run a controller loop or mutate lifecycle labels. Workers coordinate
+lifecycle, scope, and cross-phase decisions with the owning architect through hub, sending
+the verified observation and decision needed. A worker may use the `dispatch` MCP tool
+directly for a durable human question; replies come back to the worker's own session.
 
 ## Durable artifacts
 

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

@@ -15,7 +15,9 @@ 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 inward to you; only you open `envoy_dispatch` threads.
+  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 only the live label vocabulary: `needs-approval`, `human-approved`,
@@ -57,7 +59,7 @@ sub-architect:
 ```text
 legion({ op: "post_spec", issue: "<root issue>", body: "<root specification>" })
 legion({ op: "label_add", issue: "<root issue>", label: "needs-approval" })
-envoy_dispatch({
+dispatch({
   parent: "<root issue>",
   subject: "Legion design approval requested",
   body: "<summary, specification, and requested decision>"
@@ -186,7 +188,6 @@ corresponding lifecycle procedure.
 | `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. |
-| `dispatch-reply` | Resolve the question that opened the thread, record the resulting decision in the tree's work, and direct the affected worker through `hub`. |
 | `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. |
 | `reopened` | Reopen the root lifecycle: inspect the reason and current artifacts, reassess scope and children, and resume at the first applicable numbered step. |
@@ -195,5 +196,6 @@ corresponding lifecycle procedure.
 
 Controller-actionable matters are exactly re-filing a genuinely independent child,
 capacity, and cross-tree conflict. Use the Legion escalation operation for those. Handle
-everything else in the tree or, for a human question, use `envoy_dispatch`; workers never
-open dispatch threads. Do not create a wait loop for any wake source.
+everything else in the tree, or use `dispatch` for a human question; workers may reach
+Sami directly with `dispatch` the same way. Do not create a wait loop for any wake
+source.

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

@@ -46,7 +46,7 @@ into a state holder: daemon state and GitHub artifacts remain authoritative.
 |---|---|---|
 | New issue added to the project board (webhook: issue opened / project item added; resync heals misses) | issue ref + triage context (incl. pre-existing children) | Triage: spawn root process via daemon admission, or park in the daemon-state backlog |
 | Backlog eligibility | slot freed / priority change | Reconsider parked items; deliberately-backlogged issues carry a marker so resync doesn't re-flag them |
-| Architect escalation (controller-actionable only: re-file a child as a root issue, capacity, cross-tree conflicts) | request + context | Judge and act; human Q&A never routes here — architects open dispatch threads |
+| 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` from the owning architect, not here |
 | Resync report | artifact-driven anomaly list (zero-owner trees, erroring issues) | Verify against fresh state, then dispatch/heal |
 | Mention | Slack/GitHub @mention text | Answer, or route to the owning issue's architect role |
 | Approval interpretation | ambiguous human comment on a gated issue | Decide whether it's an approval; if so, apply `human-approved` via the daemon |
@@ -82,8 +82,8 @@ is a deliberate controller decision, not a no-op.
 ## Architect escalation
 
 Only decide controller-actionable escalations: re-filing independent work, capacity, and
-cross-tree conflicts. Architects handle ordinary human Q&A through their own dispatch
-threads.
+cross-tree conflicts. Issue-scoped human Q&A goes through `dispatch` from the owning
+architect, not the controller.
 
 For an independence judgment, verify the child and its parent against GitHub and current
 daemon state. If the work belongs in an independent root:

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

@@ -19,9 +19,10 @@ its own role again.
 
 Read the current issue and its acceptance criteria before changing the workspace. Work only
 on this phase's artifact. You may use ordinary scouts, reviewers, and oracle subagents for
-phase work; never spawn legion-role workers or open human dispatch threads. Escalate a product,
-scope, cross-phase, or human decision to the owning architect through hub, with the verified
-facts and the decision needed.
+phase work; never spawn legion-role workers. Escalate a product, scope, cross-phase, or
+lifecycle decision to the owning architect through hub, with the verified facts and the
+decision needed. For a durable question that needs Sami directly, you may use the raw
+`dispatch` MCP tool yourself; replies return to your own session.
 
 ## Workspace and handoff precedence
 
@@ -171,5 +172,6 @@ pipeline labels, run a controller loop, or notify a controller with an invented
 protocol. A direct worker delivery belongs to its role; overseers receive only derived
 verdicts.
 
-When blocked, send the owning architect a concise hub message: issue, phase, verified
-observation, what you tried, and the decision required. Do not dispatch a human thread yourself.
+When blocked on lifecycle, scope, or cross-phase matters, send the owning architect a concise
+hub message: issue, phase, verified observation, what you tried, and the decision required.
+Reach for `dispatch` yourself only for a standalone human question outside that coordination.

package/package.json

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