@sjawhar/opencode-legion-envoy 0.8.0 → 0.9.0

package/package.json

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

package/skills/AGENTS.md

@@ -8,6 +8,7 @@ event intake, process lifecycle, credentials, and role delivery.
 
 ```
 skills/
+├── dispatch/            # Raising a durable human question as a GitHub-issue thread
 ├── github/              # GitHub issue and pull-request operations
 ├── linear/              # Linear adapter instructions
 ├── legion-architect/    # Tree ownership, decomposition, gates, and scheduling

package/skills/dispatch/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: dispatch
+description: Use when you need a human decision from Sami or the user — asking a question, waiting on approval, saying "let me know", writing an end-of-message question block, picking between options with tradeoffs, or starting unattended/long-running work that will need input later. Raises the question as a durable GitHub-issue thread instead of a transcript question nobody will see.
+---
+
+# Dispatch
+
+`dispatch` turns a question into a durable, dashboard-visible GitHub-issue thread instead
+of a line buried in a transcript. Use it any time you would otherwise leave a question for
+a human to notice on their own.
+
+## When to dispatch
+
+- Any question not answerable at the keyboard in seconds.
+- Anything decision-shaped: a fork in approach, a tradeoff only the human can weigh, an
+  approval gate.
+- Anything you would otherwise write as an end-of-message question block and hope someone
+  reads.
+- Before you park on a blocker. Never leave a session idle on an unasked question.
+- Unattended or long-running work (Legion roles, background agents) that will need input
+  later — dispatch the question as soon as you know you'll need it, don't wait to be asked.
+
+## When NOT to dispatch
+
+- A one-word clarification the human is actively typing with you right now, in the same
+  turn — use the built-in `ask` tool instead. `dispatch` is for questions the reader has
+  not seen your transcript for; `ask` is for questions inside a live conversation.
+- Anything you can resolve yourself from tools or repo context. Dispatch is for genuine
+  human decisions, not a substitute for research.
+
+## How
+
+```
+dispatch({
+  subject:  "Postgres migration: run online or take a maintenance window?",
+  context:  "Implementing the users-table index migration for issue #482. The table has
+             40M rows; a plain CREATE INDEX locks writes for ~6 minutes in the staging
+             timing test I just ran.",
+  question: "Current: no online-migration tooling wired into this repo's deploy pipeline.
+             Desired: index added without a customer-visible write outage.
+             Option A — CREATE INDEX CONCURRENTLY, no lock, ~25 min, can't run inside a
+             transaction (rules out the existing migration runner without a change).
+             Option B — take a 6-minute maintenance window during the 03:00 UTC low-traffic
+             slot, keep the existing runner unchanged.
+             Recommendation: B — smaller blast radius, no migration-runner change, and the
+             window is well inside the existing maintenance SLA.",
+  urgency:  "med"
+})
+```
+
+- `subject`: one line, the decision — this is the issue title and the dashboard row.
+- `context` (required): what you are doing, what you found, why you are stuck. **The
+  reader has not seen your transcript** — never write "the list above," "those items," or
+  anything that assumes shared context. State it fresh.
+- `question` (required): current state → desired state → proposed change, then options
+  with tradeoffs, then your own recommendation. Don't just describe the fork — say which
+  branch you'd take and why.
+- `ask` (optional): a list of `{ question, header?, options: [{ label, description? }] }`
+  when the decision is a discrete set of choices. These render as buttons on the dashboard
+  — use this instead of asking the human to type a free-text answer when the answer really
+  is "pick one of N."
+- `urgency` (optional, default `med`):
+  - `low` — whenever it's convenient, no deadline pressure.
+  - `med` — needed today.
+  - `high` — blocking something that will stall soon if unanswered.
+  - `blocking` — you cannot proceed at all right now.
+- `repo` (optional): only pass this to target a **different** repo than your current
+  working directory's GitHub remote. The shim fills `repo` from cwd automatically —
+  omit it in the common case.
+- `parent` (optional): only set this when a real issue already exists to attach to —
+  `<n>` for an issue in the resolved repo, or `owner/name#<n>` to point at a specific
+  issue in another repo. For Legion roles, `parent` is the root issue you're working
+  under. Omitting it creates a standalone top-level thread; don't invent a parent that
+  doesn't exist.
+
+## After dispatching
+
+The reply arrives back in your own session as a steer — you do not fetch it. Keep every
+other non-blocked lane of work moving while you wait; a dispatch is not a reason to go
+idle. Never poll GitHub for the reply and never set up a watcher, cron, or retry loop to
+check on it — the delivery mechanism is already push-based. The issue URL returned by the
+tool (`{"thread": N, "url": "..."}`) is the durable record; you don't need to keep it
+anywhere else.
+
+If the tool errors because it can't resolve a repo (cwd has no GitHub remote and no
+qualified `parent`), pass `repo=owner/name` explicitly and retry.
+
+**Named risk:** a thread created in a repo where the Envoy GitHub App is not installed
+gets created successfully, but replies to it never route back to your session — you'll
+wait forever for a steer that can't arrive. Coverage is every repo under `sjawhar`, plus
+`acme-org/example-repo` and `acme-org/example-e2e` — the App is
+deliberately not installed org-wide. That list can change; to check a repo before relying
+on a reply, `gh api /repos/<owner>/<name>/installation` returns 200 when the App is
+installed there and 404 when it is not.

package/skills/envoy/SKILL.md

@@ -119,9 +119,9 @@ GitHub topics are **resource-scoped** — every event includes the resource type
 
 Examples:
 
-- `notifications.github.trajectory-labs-pbc.agent-c.pr.9880` (PR #9880 state changes)
-- `notifications.github.trajectory-labs-pbc.agent-c.pr.9880.comment` (comments on PR #9880)
-- `notifications.github.trajectory-labs-pbc.agent-c.issue.9909.>` (all events on issue #9909)
+- `notifications.github.example-org.example-repo.pr.9880` (PR #9880 state changes)
+- `notifications.github.example-org.example-repo.pr.9880.comment` (comments on PR #9880)
+- `notifications.github.example-org.example-repo.issue.9909.>` (all events on issue #9909)
 - `notifications.github.sjawhar.legion.pr.>` (all PR events across all PRs)
 - `notifications.github.sjawhar.legion.mention` (all @mentions repo-wide)
 - `notifications.github.sjawhar.legion.push.branch.main` (pushes to main)
@@ -143,10 +143,10 @@ Thread timestamps are normalized: `1234567890.123456` → `1234567890_123456`
 
 Examples:
 
-- `notifications.slack.T09FRELLTS8.C0A0DHVU8HE.message`
-- `notifications.slack.T09FRELLTS8.C0A0DHVU8HE.mention`
-- `notifications.slack.T09FRELLTS8.C0A0DHVU8HE.thread.1234567890_123456.message`
-- `notifications.slack.T09FRELLTS8.C0A0DHVU8HE.thread.1234567890_123456.mention`
+- `notifications.slack.T01234567.C0A0DHVU8HE.message`
+- `notifications.slack.T01234567.C0A0DHVU8HE.mention`
+- `notifications.slack.T01234567.C0A0DHVU8HE.thread.1234567890_123456.message`
+- `notifications.slack.T01234567.C0A0DHVU8HE.thread.1234567890_123456.mention`
 
 ### Ghost Wispr
 
@@ -200,6 +200,14 @@ Examples:
 
 You do NOT need to subscribe in order to send or publish.
 
+**Session ids are not stable for the life of a conversation.** On OMP, `/fork` and `/handoff`
+re-mint the session id while the conversation continues (esc-esc rewinds also did, on omp
+18.1.0–18.1.2 only); the extension rebinds automatically and injects an `envoy` notice naming
+the previous and new ids. When that notice arrives, any id you shared earlier (an
+`envoy_whoami` result quoted in a message, an id a peer saved) is stale — re-run
+`envoy_whoami` and re-announce yourself. Never treat a whoami result from earlier in the
+transcript as current when identifying yourself to peers.
+
 ### To wait for CI, PR checks, or other async work
 
 **Don't `sleep`-poll. Don't "check back in N minutes."** Subscribe to the event and continue with productive work — the system will wake the session when the event arrives.
@@ -226,7 +234,7 @@ If you have nothing else to do, end the response. The user is not your alarm clo
 
 ```text
 envoy_subscribe([
-  "notifications.slack.T09FRELLTS8.C0A0DHVU8HE.mention"
+  "notifications.slack.T01234567.C0A0DHVU8HE.mention"
 ])
 ```
 
@@ -234,7 +242,7 @@ envoy_subscribe([
 
 ```text
 envoy_subscribe([
-  "notifications.slack.T09FRELLTS8.C0A0DHVU8HE.thread.1234567890_123456.>"
+  "notifications.slack.T01234567.C0A0DHVU8HE.thread.1234567890_123456.>"
 ])
 ```
 
@@ -242,7 +250,7 @@ envoy_subscribe([
 
 ```text
 envoy_subscribe([
-  "notifications.slack.T09FRELLTS8.C0A0DHVU8HE.thread.1234567890_123456.message"
+  "notifications.slack.T01234567.C0A0DHVU8HE.thread.1234567890_123456.message"
 ])
 ```
 
@@ -250,23 +258,23 @@ envoy_subscribe([
 
 ```text
 envoy_subscribe([
-  "notifications.slack.T09FRELLTS8.C0A0DHVU8HE.thread.>"
+  "notifications.slack.T01234567.C0A0DHVU8HE.thread.>"
 ])
 ```
 
-### Subscribe to all PR events for agent-c
+### Subscribe to all PR events for example-repo
 
 ```text
 envoy_subscribe([
-  "notifications.github.trajectory-labs-pbc.agent-c.pr.>"
+  "notifications.github.example-org.example-repo.pr.>"
 ])
 ```
 
-### Subscribe controller to GitHub @mentions for agent-c
+### Subscribe controller to GitHub @mentions for example-repo
 
 ```text
 envoy_subscribe([
-  "notifications.github.trajectory-labs-pbc.agent-c.mention"
+  "notifications.github.example-org.example-repo.mention"
 ])
 ```
 
@@ -318,7 +326,7 @@ Catches all conversations and event kinds for the specified phone number.
 - Different sessions can subscribe to different channels/repos
 - Agent-to-agent delivery uses exact session IDs
 - `envoy_list()` distinguishes `live`, `registry`, and `both`; a `live` topic is receiving now even when the listener registry has not caught up.
-- For Slack, use the real `team_id` in topics (for example `T09FRELLTS8`), not a workspace slug like `trajectorylabs`
+- For Slack, use the real `team_id` in topics (for example `T01234567`), not a workspace slug like `acme`
 - GitHub mention routing is body-based because GitHub has no dedicated app mention webhook event
 
 ## Synthetic Smoke Test (WhatsApp — NATS Routing Only)

package/skills/legion-architect/SKILL.md

@@ -62,7 +62,8 @@ legion({ op: "label_add", issue: "<root issue>", label: "needs-approval" })
 dispatch({
   parent: "<root issue>",
   subject: "Legion design approval requested",
-  body: "<summary, specification, and requested decision>"
+  context: "<what the tree is, what triggered the gate>",
+  question: "<specification summary and the decision requested>"
 })
 ```
 

package/src/config/index.ts

@@ -2,32 +2,38 @@ import { existsSync, readFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { messageFor } from "@legion/envoy-client/errors";
-import { logger } from "../log";
 import { type EnvoyConfig, EnvoyConfigSchema } from "./schema";
 
 export interface LoadEnvoyConfigOptions {
   homeDir?: string;
 }
 
+/** A present but unusable envoy.json. The plugin refuses to load rather than run with dispatch silently off. */
+export class EnvoyConfigError extends Error {
+  readonly filePath: string;
+  constructor(filePath: string, detail: string) {
+    super(`[envoy-plugin] invalid config at ${filePath}: ${detail}`);
+    this.name = "EnvoyConfigError";
+    this.filePath = filePath;
+  }
+}
+
 function readConfigFile(filePath: string): EnvoyConfig | null {
   if (!existsSync(filePath)) return null;
+  let raw: unknown;
   try {
-    const content = readFileSync(filePath, "utf-8");
-    const raw = JSON.parse(content) as unknown;
-    const parsed = EnvoyConfigSchema.safeParse(raw);
-    if (!parsed.success) {
-      const issues = parsed.error.issues
-        .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
-        .join(", ");
-      logger.warn(`[envoy-plugin] Invalid config at ${filePath}: ${issues}`);
-      return null;
-    }
-    return parsed.data as EnvoyConfig;
+    raw = JSON.parse(readFileSync(filePath, "utf-8")) as unknown;
   } catch (error) {
-    const message = messageFor(error);
-    logger.warn(`[envoy-plugin] Failed to load config at ${filePath}: ${message}`);
-    return null;
+    throw new EnvoyConfigError(filePath, messageFor(error));
+  }
+  const parsed = EnvoyConfigSchema.safeParse(raw);
+  if (!parsed.success) {
+    const issues = parsed.error.issues
+      .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+      .join(", ");
+    throw new EnvoyConfigError(filePath, issues);
   }
+  return parsed.data;
 }
 
 function mergeConfig(base: EnvoyConfig, override: EnvoyConfig): EnvoyConfig {

package/src/config/schema.ts

@@ -6,11 +6,6 @@ export const DispatchConfigSchema = z
   .object({
     enabled: z.boolean().optional(),
     serverUrl: z.string().url().optional(),
-    defaultRepo: z
-      .string()
-      .regex(/^[^/]+\/[^/]+$/)
-      .optional(),
-    appClientId: z.string().optional(),
   })
   .strict();