@sjawhar/pi-legion-envoy 1.42.2 → 1.43.0

package/dist/envoy.js

@@ -30345,6 +30345,12 @@ var stateTreeLocator = discriminatedUnion("runtime", [
   stateTmuxLocator.extend({ ompSessionFile: nonEmptyString.optional() }),
   stateK8sLocator.extend({ ompSessionFile: nonEmptyString.optional() })
 ]);
+var stateExternalControllerLocator = strictObject({
+  runtime: literal("kubernetes"),
+  external: literal(true),
+  sessionId: nonEmptyString,
+  registeredAt: number2().int().nonnegative()
+});
 var stateIssue = strictObject({
   key: nonEmptyString,
   title: string2(),
@@ -30400,7 +30406,7 @@ var LegionDaemonApi = {
         queue: array(nonEmptyString)
       }),
       gates: record(string2(), stateGate),
-      controllerLocator: stateTreeLocator.optional(),
+      controllerLocator: union([stateTreeLocator, stateExternalControllerLocator]).optional(),
       roles: record(string2(), stateRole),
       controllerPendingNotices: number2().int().nonnegative(),
       pendingStatusWrites: array(nonEmptyString),
@@ -30415,6 +30421,10 @@ var LegionDaemonApi = {
     }),
     response: object({})
   },
+  ControllerSecret: {
+    request: strictObject({}),
+    response: object({ secret: nonEmptyString })
+  },
   ProcessStarted: {
     request: strictObject({
       tree: nonEmptyString,

package/dist/legion.js

@@ -29619,6 +29619,12 @@ var stateTreeLocator = discriminatedUnion("runtime", [
   stateTmuxLocator.extend({ ompSessionFile: nonEmptyString.optional() }),
   stateK8sLocator.extend({ ompSessionFile: nonEmptyString.optional() })
 ]);
+var stateExternalControllerLocator = strictObject({
+  runtime: literal("kubernetes"),
+  external: literal(true),
+  sessionId: nonEmptyString,
+  registeredAt: number2().int().nonnegative()
+});
 var stateIssue = strictObject({
   key: nonEmptyString,
   title: string2(),
@@ -29674,7 +29680,7 @@ var LegionDaemonApi = {
         queue: array(nonEmptyString)
       }),
       gates: record(string2(), stateGate),
-      controllerLocator: stateTreeLocator.optional(),
+      controllerLocator: union([stateTreeLocator, stateExternalControllerLocator]).optional(),
       roles: record(string2(), stateRole),
       controllerPendingNotices: number2().int().nonnegative(),
       pendingStatusWrites: array(nonEmptyString),
@@ -29689,6 +29695,10 @@ var LegionDaemonApi = {
     }),
     response: object({})
   },
+  ControllerSecret: {
+    request: strictObject({}),
+    response: object({ secret: nonEmptyString })
+  },
   ProcessStarted: {
     request: strictObject({
       tree: nonEmptyString,

package/dist/skills/dispatch/SKILL.md

@@ -183,6 +183,10 @@ passage with `anchor`. Follow up on an ask or comment with `dispatch_comment`; c
 with a `dispatch://` reference (see [References](#references)). Never write "see above", "the
 message above", or "as attached".
 
+**A decision about an uploaded artifact links it.** If the human must read an artifact to answer,
+the question carries `dispatch://KEY/artifact/<slug>` (or `ref`), never just its filename. Text
+they must read to decide belongs in the spec in the first place — see [Artifacts](#artifacts).
+
 Before saying you are waiting for human input, call `dispatch_open_asks`. It lists this session's active asks across open issues and project documents, including whether the human or agent owes the next reply.
 
 **Anything that needs the human is an ask, or it does not exist.** An approval, a credential,
@@ -431,6 +435,15 @@ with your text. Never do that: the spec is edited in place with `dispatch_doc_ed
 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.
 
+**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
+artifact is for a real file: something sent as-is, a long report, a binary, a screenshot.
+
+When you do upload one, the spec links it as `dispatch://KEY/artifact/<slug>` (the `slug` from the
+upload result; it renders as a link) at the place the reader needs it, and the ask that needs the
+decision carries the same reference. A heading or a sentence naming the filename is not a
+reference.
+
 Documents are CommonMark. A bare `<https://example.com|text>` is a CommonMark autolink and is normalised: the angle brackets are
 dropped and the URL keeps `|text`. A backslash-escaped `\<https://example.com|text>` displays as `<https://example.com|text>` in the
 document but comes back re-escaped (`\<`) from `dispatch_doc_read`. A Slack mrkdwn draft, or any other payload that is not Markdown,
@@ -607,3 +620,38 @@ dispatch_message({
   body: "Release 1.4 is live on the devbox (dispatch://LEGION-815/artifact/release-notes). Nothing needed from you.",
 })
 ```
+
+Before — a draft the human must read is uploaded as a separate file, the spec only names it, and
+the ask does not point at it, so the reader has to go looking:
+
+```ts
+dispatch_artifact({ issue: "OPS-52", name: "cu-update-2026-09-15.md", content: "Hi team, ..." })
+dispatch_doc_edit({ issue: "OPS-52", artifact: "spec", ops: [
+  { op: "insert", after: "## Context", markdown: "## Draft (artifact cu-update-2026-09-15.md)" },
+]})
+dispatch_ask({ issue: "OPS-52", question: "Send the customer update as drafted?", options: [...] })
+```
+
+After — the draft is a section of the spec, and the ask anchors there. If it really must be a
+file (something to send as-is), the spec and the ask both link the slug from the upload result:
+
+```ts
+dispatch_doc_edit({ issue: "OPS-52", artifact: "spec", ops: [
+  { op: "insert", after: "## Context", markdown: "## Draft\n\nHi team, ..." },
+]})
+dispatch_ask({
+  issue: "OPS-52",
+  question: "Send the customer update as drafted?",
+  options: [...],
+  anchor: { artifact: "spec", quote: "Hi team," },
+})
+// or, for a real file — the spec links it where the reader needs it, and so does the ask:
+dispatch_doc_edit({ issue: "OPS-52", artifact: "spec", ops: [
+  { op: "insert", after: "## Context", markdown: "## Draft\n\nThe update to send as-is: dispatch://OPS-52/artifact/cu-update-2026-09-15-md" },
+]})
+dispatch_ask({
+  issue: "OPS-52",
+  question: "Send this customer update as-is? dispatch://OPS-52/artifact/cu-update-2026-09-15-md",
+  options: [...],
+})
+```

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

@@ -64,6 +64,26 @@ 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.
 
+### Started by the operator (runtime: kubernetes)
+
+When the daemon runs inside a Kubernetes cluster it cannot open a terminal anywhere, so nobody
+launched your pane: the operator ran `legion controller start --config controller.yaml
+[--daemon-url <port-forward>]` on their own machine, and you are that foreground OMP session.
+The command fetched a fresh controller secret from the daemon with the operator's token, wrote it
+to a 0600 file under `LEGION_STATE_DIR` (`~/.local/state/legion/<project>-controller` by default)
+beside the `gh` shim and the `legion` launcher, and started you with `LEGION_CONTROLLER=1` and
+the same environment a tmux controller pane carries — so the extension claims the role and calls
+`/controller/ready` exactly as under tmux, and nothing changes in how you handle wakes. The
+daemon records you as `controllerLocator: {runtime: "kubernetes", external: true, sessionId,
+registeredAt}` and 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 daemon logs `controller not registered; run legion controller start` once per boot-timeout
+interval and launches nothing itself. `legion state`, `legion gh -- <args>`, and
+`legion status <KEY> <status>` work here over `LEGION_DAEMON_URL` (the port-forward). 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.
+
 ## Deployment instructions
 
 Deployment instructions, when present, are the operator's standing rules for this repository —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/pi-legion-envoy",
-  "version": "1.42.2",
+  "version": "1.43.0",
   "type": "module",
   "omp": {
     "extensions": [
@@ -12,7 +12,7 @@
     ]
   },
   "legion": {
-    "daemonApiVersion": 5
+    "daemonApiVersion": 6
   },
   "repository": {
     "type": "git",