@sjawhar/opencode-legion-envoy 3.2.1 → 3.2.3

package/dist/src/server.js

@@ -17267,7 +17267,7 @@ var envoyToolSpecs = [
   },
   {
     name: "envoy_whoami",
-    description: "Returns this session's Envoy identity: session ID, machine ID, port, and directory.",
+    description: "Returns this session's Envoy identity: session ID, machine ID, port, and directory. session_id is the address a reply reaches. Where a host runs a task subagent inside its parent's process, such a subagent registers no Envoy session of its own, so its session_id is the parent session that spawned it and the result says so.",
     arguments: () => ({}),
     operation: EnvoyToolOperation.whoami,
     requiresSubscriptionCapability: false
@@ -17435,7 +17435,7 @@ function createEnvoyClient(config2) {
       const idempotencyKey = input.idempotencyKey ?? crypto.randomUUID();
       const response = EnvelopeResponseSchema.parse(JSON.parse(await post("/v1/messages/send", {
         source: input.source ?? "agent",
-        ...input.sourceSessionID === undefined ? {} : { source_session: input.sourceSessionID },
+        ...sourceSession(input.sourceSessionID),
         target_session: input.targetSessionID,
         message: input.message,
         idempotency_key: idempotencyKey,
@@ -17451,7 +17451,7 @@ function createEnvoyClient(config2) {
       const idempotencyKey = input.idempotencyKey ?? crypto.randomUUID();
       const response = EnvelopeResponseSchema.parse(JSON.parse(await post("/v1/messages/publish", {
         source: input.source ?? "agent",
-        ...input.sourceSessionID === undefined ? {} : { source_session: input.sourceSessionID },
+        ...sourceSession(input.sourceSessionID),
         topic: input.topic,
         message: input.message,
         ...input.payload === undefined ? {} : { payload: input.payload },
@@ -17514,6 +17514,9 @@ function messageMetadata(input) {
     ...input.expiresAt === undefined ? {} : { expires_at: input.expiresAt }
   };
 }
+function sourceSession(sessionID) {
+  return sessionID === undefined || sessionID === "" ? {} : { source_session: sessionID };
+}
 
 // src/server.ts
 import { tool } from "@opencode-ai/plugin/tool";

package/package.json

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

package/skills/envoy/SKILL.md

@@ -106,6 +106,25 @@ envoy_send(
 )
 ```
 
+### Your own address, and a subagent's
+
+`envoy_whoami`'s `session_id` is the address a reply to you reaches. Inside a `task` subagent it
+is the session that spawned you: a subagent registers no Envoy session of its own, so a peer
+answering it reaches that session, which relays to you over hub. The `subagent` field in that
+output carries your own host session id — it is not an address, so never hand it to a peer.
+
+`session_id` is empty when nothing can be reached: a process that took no Envoy identity, or a
+subagent whose spawning session this process can no longer place (it forked away, and other
+top-level sessions are running). Then your messages carry no sender either, so say who you are
+in the message body. An empty address is deliberate — being handed an unrelated live session
+would send your peers to an agent that never spawned you.
+
+Your own `envoy_publish` never reaches the agent that spawned you. The listener delivers nothing
+to the session a message names as its source, and inside a subagent that source is your parent,
+so a publish to a role it holds — or to any topic it subscribes to — is accepted and delivered to
+nobody. Use hub for that one hop. `envoy_send` to any other session, including a reply, is
+unaffected.
+
 ### Delivery capabilities
 
 Each session row from `envoy_sessions` carries `capabilities`, the targeted-delivery modes that

package/skills/legion-controller/SKILL.md

@@ -71,9 +71,11 @@ launcher, and started you with `LEGION_CONTROLLER=1` and the same environment a
 carries, so nothing changes in how you handle wakes. Under the TypeScript daemon the extension
 claims the role and calls `/controller/ready` exactly as under tmux; under the Go daemon
 (`LEGION_DAEMON_API=go` in your environment) it registers on `/legion/v1/claims/register` with the
-secret, then claims the role. The daemon records you as `controllerLocator: {runtime, external:
-true, sessionId, registeredAt}`, `runtime` being the daemon's own (`kubernetes`, or `tmux` under the
-Go daemon). The TypeScript daemon reads your liveness from the Envoy role registry (the holder of
+secret, claims the role, then subscribes to `notifications.legion.<project>.controller`, where the
+Go daemon publishes the two Go rows of the wake routing table. The daemon records you as
+`controllerLocator: {runtime, external: true, sessionId, registeredAt}`, `runtime` being the
+daemon's own (`kubernetes`, or `tmux` under the Go daemon). The TypeScript daemon reads your
+liveness from the Envoy role registry (the holder of
 `legion-<project>-controller` and its `last_seen`), not from a pane: keep the session running.
 Exiting it leaves the project without a controller until the operator runs the command again —
 the TypeScript daemon logs `controller not registered; run legion controller start` once per
@@ -81,6 +83,20 @@ boot-timeout interval and launches nothing itself. `legion state` and `legion st
 <status>` work here over `LEGION_DAEMON_URL`. A second `legion controller start` replaces you: it
 mints a new secret, so your grants stop working and the role moves to the new session.
 
+### What happened before you started (Go daemon)
+
+The Go daemon's controller topic is a wake for a session that is running when it is published.
+Envoy hands an Oh My Pi session no retained copy of a notice published before it subscribed, so a
+hold or a tree architect's failed claim from while no controller ran never arrives as a wake. At
+every start, before anything else, read `legion state --json` and handle each issue whose
+`issues.<KEY>.phase` is `held` (its `issues.<KEY>.holdReason` is `escalated` when its architect
+sent it to you, and absent while the architect is still deciding or while its tree lingers or is
+closed, where the hold waits for the tree's re-admission and needs nothing from you), and each
+tree root whose `issues.<KEY>.architect.state` is `failed` and whose `issues.<KEY>.phase` is not
+`done`, exactly as the matching wake below. A parked tree (root phase `done`: it lingers or is
+closed) needs nothing from you: a failed architect ignores the park and reads `failed` until the
+tree closes. The issue record is the truth; the topic is the wake.
+
 ## Deployment instructions
 
 Deployment instructions, when present, are the operator's standing rules for this repository —
@@ -116,6 +132,8 @@ quoted here.
 | Mention | Slack/GitHub PR @mention text | Answer, or route to the owning issue's architect role |
 | READY packet seen on a Dispatch issue (via issue subscription) | READY line + gate facts | No action: a human merges; the merger has already notified the queue role if the project has one |
 | `worker-recovered` (role `architect`) from the daemon | issue, fromRef | A root architect's tree volume was lost; it restarted as a new session. Verify the tree is active in `legion state` and that the architect posts its next step on the issue within one resync interval; otherwise treat it as an anomaly. |
+| `held on <KEY>` from the Go daemon (payload `{kind: "held", phase, role?, reason?}`) | the held issue, the phase it left, and the role whose claim failed, or `reason: "escalated"` | Verify the hold in `legion state` (the issue's phase is `held`). Without `reason`, a phase worker's launches or prompts ran out and the tree's architect decides retry or escalate: no action. With `reason: "escalated"` (on the record, `issues.<KEY>.holdReason` is `escalated`), the architect sent it to you: handle it as an architect escalation below. Parking the tree is `legion status <root> backlog`; setting the root back to `todo` later re-admits it as a new generation, which starts again from its architect |
+| `worker-died on <KEY>` from the Go daemon with `role: "architect"` | the tree root whose architect's claim failed, and the phase the root was in | The tree's architect ran out of launches or prompts and the daemon relaunches nothing; every other notice of the tree goes to that architect, so nobody inside the tree can act. Verify in `legion state` (`issues.<KEY>.architect.state` is `failed`); if the root's phase is `done`, the tree is already parked: no action. Otherwise re-admit the tree (`legion status <root> backlog`, then `todo`: a new generation, whose architect starts again with fresh budgets) or leave it parked and say why on the issue |
 | 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 |