cyberlegion 0.3.2 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cyberlegion",
-  "version": "0.3.2",
+  "version": "0.5.0",
   "description": "Harness-agnostic agent session spawning and messaging over the filesystem",
   "keywords": [
     "agent",
@@ -30,7 +30,13 @@
   },
   "files": [
     "bin",
-    "dist"
+    "dist",
+    "plugin.json",
+    ".claude-plugin",
+    ".codex-plugin",
+    ".plugin",
+    "skills",
+    "agents"
   ],
   "dependencies": {
     "commander": "^14.0.3",
@@ -38,6 +44,7 @@
   },
   "devDependencies": {
     "@types/node": "^24.10.1",
+    "smol-toml": "^1.8.0",
     "tsdown": "^0.22.0",
     "tsx": "^4.22.3",
     "typescript": "^7.0.2",
@@ -53,7 +60,7 @@
   "scripts": {
     "build": "tsdown",
     "check:metaphor-free": "tsx src/check-metaphor-free.ts",
-    "dev": "tsx src/cli.ts",
+    "dev": "tsx src/dev.ts",
     "test": "vitest run src",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit"

package/plugin.json

@@ -0,0 +1,24 @@
+{
+	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+	"name": "cyberlegion",
+	"version": "0.5.0",
+	"description": "Agent session spawning, messaging, and dispatch — the Legion and its Legate.",
+	"author": {
+		"name": "unional"
+	},
+	"homepage": "https://github.com/cyberuni/cyberlegion",
+	"repository": "https://github.com/cyberuni/cyberlegion",
+	"keywords": ["agent", "dispatch", "inter-agent", "multiplexer"],
+	"extensions": {
+		"org.cyberuni.universal-plugin": {
+			"vendors": ["claude-code", "codex"],
+			"packagePath": ".",
+			"skills": "./skills",
+			"agents": ["./agents/headless-legate.md"],
+			"harnesses": {
+				"claude-code": {},
+				"codex": {}
+			}
+		}
+	}
+}

package/readme.md

@@ -98,6 +98,69 @@ Top-level shortcuts are provided for the common verbs: `spawn`, `send`, `inbox`,
 | `--space <path>`    | Isolate the hub root (overrides the global hub / `$CYBERLEGION_ROOT`) |
 | `--format <format>` | Output format: `toon` (default) or `json`                         |
 
+## Agent plugin
+
+Agent session spawning, messaging, and dispatch — harness-agnostic, MCP-free. The foundation both
+SDD and cyberfleet build on: a **Legion** of addressable agent units, mustered and reaped, commanded
+and communicating over the filesystem.
+
+### The console
+
+The `cyberlegion` CLI is the cold, deterministic mechanism: identity (`unit register`, `unit claim`,
+`unit who`), warm peer sessions in their own git worktrees (`unit spawn`, `unit close`,
+`unit prune`), durable mail (`mail send`, `mail inbox`, `mail read`, `mail await`),
+agent-definition resolution (`agent resolve`), hook registration (`init`), and
+admin/diagnostics (`mux doctor`, `admin migrate`). It never decides *when* to spawn a peer
+versus a subagent, and it carries no dispatch/result-slot primitives of its own — a cold subagent
+returns via the caller's own Task-result, a warm peer via `mail await`.
+
+### The Legate
+
+The **Legate** is the routing brain on top of the console — the judgment the CLI deliberately does
+not carry. In an attended session it runs in-session as `dispatch-governance`; with no user channel
+it is realized headless as the `headless-legate` agent. Given an intent (fulfill a role with a brief, expect a
+verdict), it reads the target agent-definition's `warm`/`interactive` tags and the environment's
+multiplexer availability, then picks exactly one strategy:
+
+- **channel** — a warm, interactive peer in its own pane (`unit spawn` + `mail await` on the thread)
+- **run-inline** — no multiplexer to host a peer, so the caller does the work itself, in-session
+- **subagent** — a cold, one-shot unit realized via the caller's own Task tool, taking its
+  Task-result (final returned message) as the verdict
+
+### The gateway
+
+`legate` (the skill) is the thin front door — classify the request (send mail, check inbox,
+spawn/close a unit, wait for a reply, dispatch work) and either run the matching CLI call directly or
+hand routing judgment to `dispatch-governance`. It loads no governance itself and writes no state.
+
+### Onboarding and the owner mailbox
+
+Two more user-facing skills sit beside the gateway:
+
+- **`init-cyberlegion`** — the onboarding front door: probe the environment, register the
+  mail-surfacing hook so incoming mail reaches you mid-session, and (only in a root session, only on
+  an explicit yes) bind this pane as the durable `legate` owner inbox. Every step is a
+  `cyberlegion` CLI call; the skill holds the conversation and the judgment.
+- **`manage-inbox`** — the human's surface for that **owner mailbox**: the hub-level,
+  session-independent inbox a standing identity holds, where frameless agents (cron-started, no
+  parent frame) push their reports. It's how you read and ack those reports from whichever session
+  you happen to be in.
+
+### Installation
+
+```bash
+npx skills add cyberuni/cyberplace --plugin cyberlegion --global
+```
+
+This package doubles as the plugin root: `plugin.json`, the generated `.claude-plugin/` and
+`.codex-plugin/` manifests, `skills/`, and `agents/` all ship in the npm tarball. The bundle
+Each skill that runs the CLI carries a launcher, `scripts/cyberlegion.mjs`, that runs the CLI
+shipped in this same package (`bin/cyberlegion.mjs` over the committed `dist/cli.mjs`), so a skill
+never fetches a copy through npx and always runs the version its own text describes. Where the
+launcher cannot be resolved, a skill names one fallback pinned to the version that shipped it,
+`npx -y cyberlegion@<version>`. `pnpm version` rewrites those pins and `.plugin/pins.json` at every
+release, and the test suite fails on a stale one.
+
 ## License
 
 MIT

package/skills/dispatch-governance/README.md

@@ -0,0 +1,29 @@
+# dispatch-governance
+
+Partial Skill: invoke by name only — the Legate's routing brain. Not user-invocable — loaded by the `legate` gateway
+in-session on a dispatch intent, and by the `headless-legate` agent when there is no user channel.
+
+## When it loads
+
+- The `legate` gateway classified a request as "dispatch work to fulfill a role and expect a
+  verdict back."
+- The `headless-legate` agent realizes the same flow headless.
+
+## What it does
+
+- Resolves the target agent definition's `warm`/`interactive` tags (`cyberlegion agent resolve`).
+- Probes the environment for a multiplexer (`cyberlegion mux doctor`).
+- Picks exactly one of three strategies — **channel** (warm peer: `unit spawn` + `mail await`),
+  **run-inline** (caller does the work itself), or **subagent** (cold, one-shot, via
+  `subagent-backend-governance`) — and executes it by composing the `cyberlegion` CLI primitives.
+- Folds in the wake-matrix decision (bounded await vs doorbell vs run-inline, gated on a verified
+  multiplexer) that the CLI no longer encodes.
+- Defines the `subagent | channel` seam a dependent (SDD, ADR-0023) references by intent, never by
+  a literal command name.
+
+## What it does not do
+
+- Never lets the CLI auto-route — there is no `--backend auto` flag, and no `dispatch` command
+  group at all; `unit spawn`/`mail await`/`unit nudge` are composed here deliberately.
+- Never invokes a harness's Task tool directly (that happens inside `subagent-backend-governance`,
+  using the caller's own tool).

package/skills/dispatch-governance/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: dispatch-governance
+description: "Partial Skill: invoke by name only — the Legate's routing brain — picks and executes a dispatch strategy for a role intent. Loaded in-session by the legate gateway, and by the headless-legate agent headless. Not triggered by users directly."
+user-invocable: false
+---
+
+# Dispatch Governance
+
+The judgment the `cyberlegion` CLI deliberately does not carry. The CLI is dumb hands — it never
+auto-routes, never picks a backend, never invokes a Task tool itself. This governance is the one
+place that judgment lives, loaded in-session by the `legate` gateway on a dispatch intent, and
+realized headless by the `headless-legate` agent. Both loads run the exact same procedure below.
+
+**Input:** an intent to fulfill role `R` with brief `B`, optionally expecting a result that
+satisfies verdict schema `V`.
+
+> **Running the CLI.** Every `node scripts/cyberlegion.mjs …` command below runs the `cyberlegion` CLI
+> this plugin ships. The path is relative to this skill's own directory, not the working directory.
+> If you cannot resolve it, run the published CLI of the version that shipped this skill instead,
+> with the same arguments: `npx -y cyberlegion@0.5.0`.
+
+## 1. Resolve the agent definition
+
+```bash
+node scripts/cyberlegion.mjs agent resolve <R> --format json
+```
+
+Read `model`, `effort`, `harness`, `warm`, `interactive` off the resolved def. `warm` marks a role
+that should run as a live peer session (not a fire-and-forget unit); `interactive` marks a role that
+may need to grill the caller or converse over multiple rounds, not just return one result.
+
+## 2. Probe the environment
+
+```bash
+node scripts/cyberlegion.mjs mux doctor --format json
+```
+
+Read whether a multiplexer was ancestry-discovered (tmux/herdr) — a **channel** strategy needs one
+to open a pane in; its absence rules that strategy out regardless of what the agent def wants.
+
+## 3. Pick exactly one strategy
+
+| `warm` | `interactive` | mux present | Strategy |
+|---|---|---|---|
+| true | true | true | **channel** |
+| true | true | false | **run-inline** |
+| false or true | false | — | **subagent** |
+| false | true | — | **error** — unroutable def |
+
+- **channel** — warm, interactive, and a pane is available: spin up a live peer that can converse
+  and mail back over rounds. Compose the primitives directly — no single CLI command does this:
+
+  mint a thread id, weave it (and an instruction to reply on it) into brief `B`, then:
+
+  ```bash
+  node scripts/cyberlegion.mjs unit spawn --agent <R> --brief-file <B> --at <placement>
+  node scripts/cyberlegion.mjs mail await --thread <the-minted-thread-id> [--timeout <ms>] [--max-wait <s>]
+  ```
+
+  `unit spawn` launches the peer (its brief tells it what thread to reply on); `mail await` then
+  blocks on that reply thread. Use `--at` to place the pane, `--timeout`/`--max-wait` to bound the
+  wait; a `waiting` outcome at `--max-wait` means re-run `mail await` on the same thread to keep
+  polling, not a failure.
+
+  **The wake-matrix decision** (which sub-mode of channel to run) belongs here too, since the CLI
+  carries no `selectWakePath` helper of its own:
+
+  | Environment | Wake mode |
+  |---|---|
+  | Portable default (mux unknown, or nothing verified) | Bounded await — poll `mail await` with `--max-wait`, re-arming on `waiting` ("A-loop"). |
+  | Claude Code, with an observable background task | Bounded await plus a background-task check-in ("A-prime") — same polling, but the harness's own background-task surface can short-circuit a wait. |
+  | A live foreign session behind a **verified** multiplexer (`mux doctor` reports tmux/herdr, not `none`) | Doorbell — `unit nudge` the peer's pane, then `mail await` ("B"). |
+  | Multiplexer is `none` | **Never** pick doorbell (B) — there is no pane to ring. Fall back to bounded await (A). |
+
+- **run-inline** — the role is warm and interactive (needs a live back-and-forth), but there is no
+  multiplexer to host a peer in. **Do not delegate.** Return a `run-inline` verdict and let the
+  caller (the session that loaded this governance — e.g. the SDD conductor) do the work itself,
+  in-session. A cold subagent is the wrong substitute here: it cold-reloads its whole context every
+  round and holds no user channel, so a role that needs to converse cannot be served that way.
+
+- **subagent** — the role is cold and one-shot (no live conversation expected, one result back).
+  Realize it via `subagent-backend-governance`: resolve the agent def → the caller's **own** harness
+  Task/subagent tool → the subagent's Task-result (its own final returned message) is the verdict.
+  The CLI cannot invoke a Task tool itself — that is always the caller's own tool, never
+  `cyberlegion`'s — and it collects nothing on the caller's behalf; there is no result file.
+
+- **error (unroutable def)** — `interactive` with `warm` unset (`false`) has no strategy. A role that
+  needs live back-and-forth (`interactive`) must be a live peer (`warm`); a cold one-shot must not be
+  `interactive` (`subagent-backend-governance` is one-shot by design). So this pair is a **malformed
+  def**, not a routing choice — **fail loud** here, naming the def and the contradictory tags, so the
+  author fixes it. It is **not** a `needsInput` (that is for an under-specified task, not a bad def),
+  and it is **never** silently swept into **subagent**. This is the Legate's judgment, not the CLI's:
+  `agent resolve` reports the raw tags; only this governance holds the table that knows the pair maps
+  to nothing.
+
+The CLI never chooses between these on its own — `unit spawn` + `mail await` only run in this
+sequence when this governance picked **channel**; the caller's Task tool only runs when it picked
+**subagent**; picking **run-inline** means neither runs at all.
+
+## The `subagent | channel` seam
+
+This is the seam a dependent (e.g. SDD, ADR-0023) references **by intent** — "dispatch a role
+fulfillment and expect a verdict" — never by pinning `subagent` or `channel` as a literal command
+name. The dependent states its intent (role, brief, verdict schema) and this governance decides the
+mechanism; a dependent that hardcodes "always subagent" or "always channel" has broken the seam and
+coupled itself to a mechanism instead of an intent.
+
+## Result shape — DispatchResult
+
+Every strategy resolves to one shape the caller can handle uniformly:
+
+```jsonc
+{
+  "strategy": "subagent" | "channel" | "run-inline",
+  "id": "<unit id, when one was spawned>",       // omitted for run-inline
+  "verdict": "matched" | "waiting" | "timed-out" | "run-inline",
+  "result": { /* the subagent's Task-result, or the mail-await reply body, as-is */ },
+  "needsInput": ["<question>", "..."]   // present only when the callee could not complete
+}
+```
+
+`result` is carried through unvalidated today — structured verdict-schema checking against `V` is a
+deferred capability (`mail --verdict-schema`), not present in this CLI.
+
+`waiting` (channel path, `--max-wait` cap hit) and `timed-out` (channel path, `--timeout` elapsed)
+are re-armable and terminal respectively — treat them the same way `mail await`'s own three
+outcomes are treated; never silently retry past a `timed-out`. A `needsInput` result on the subagent
+path means the unit hit its own leash and returned a needs-input result rather than guessing.
+
+**How you relay that `needsInput` (or your own) is `relay-governance`, not this skill.** Report/ask
+transport is keyed on the reporting agent's own lifecycle — a framed callee returns `needsInput` to
+its caller; a bare cron session with no frame pushes mail to the standing owner and exits. Load
+`relay-governance` for the fork; this skill owns **strategy** choice (channel / run-inline /
+subagent), relay owns how the result or an unanswerable question gets home.
+
+## Non-goals
+
+- **No auto-routing in the CLI.** The CLI carries no `dispatch` command group at all — `unit spawn`,
+  `mail await`, `unit nudge`, and the caller's own Task tool are invoked deliberately by this
+  governance (or `subagent-backend-governance`), never by a `--backend auto` flag — no such flag
+  exists.
+- **No mid-flight strategy switch.** Once a strategy is picked for one dispatch, it runs to its one
+  of the three outcomes above; a failed subagent is not silently retried as a channel.

package/skills/dispatch-governance/scripts/cyberlegion.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+// Runs the cyberlegion CLI this plugin ships, so the skill beside it never fetches a copy through npx.
+// The package root is three levels up from this file (skills/<skill>/scripts/), resolved from the
+// file's own location: the working directory is the repository the agent is working on, not the plugin.
+// Arguments, output, and the exit code pass straight through the package's bin.
+//
+// A skill folder installed on its own has no package around it. Then this runs the published CLI of
+// the version that shipped the skill instead, so the skill still works, only slower. The version sync
+// run at release keeps FALLBACK at the package version.
+import { spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+const FALLBACK = 'npx -y cyberlegion@0.5.0'
+const bin = new URL('../../../bin/cyberlegion.mjs', import.meta.url)
+
+if (existsSync(fileURLToPath(bin))) {
+	await import(bin.href)
+} else {
+	process.stderr.write(`cyberlegion: no plugin package around this skill; running ${FALLBACK}\n`)
+	const [command, ...args] = FALLBACK.split(' ')
+	const res = spawnSync(command, [...args, ...process.argv.slice(2)], {
+		stdio: 'inherit',
+		shell: process.platform === 'win32',
+	})
+	if (res.error) {
+		process.stderr.write(`cyberlegion: could not run ${FALLBACK}: ${res.error.message}\n`)
+		process.exit(1)
+	}
+	process.exit(res.status ?? 1)
+}

package/skills/init-cyberlegion/README.md

@@ -0,0 +1,14 @@
+# init-cyberlegion
+
+The onboarding front door to the Legion — walks a session through getting `cyberlegion` working in
+this repo: probe the environment, register the surfacing hook, and (root session only, only on an
+explicit yes) bind this pane as the durable `legate` owner inbox.
+
+User-facing. Triggers on "set up cyberlegion", "onboard the legion", "register the cyberlegion
+surfacing hook", "make this pane my main legion inbox", "get cyberlegion working in this repo". Wraps
+`cyberlegion mux doctor` / `init` / `unit register --standing` / `attach` — every mechanic is a
+CLI call, no filesystem or hub state touched directly.
+
+Distinct from `legate` (spawn/mail/dispatch a peer) and `manage-inbox` (read/ack owner mail once
+bound). See `SKILL.md` for the full flow (probe → register hook → detect root vs spawned →
+consent-gated bind).

package/skills/init-cyberlegion/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: init-cyberlegion
+description: "Use this skill to set up or onboard cyberlegion in this session or repo — probe the environment, register the mail-surfacing hook, and (in a root session, on your yes) bind this pane as the durable legate owner inbox. Triggers: 'set up cyberlegion', 'onboard the legion', 'register the cyberlegion surfacing hook', 'make this pane my main legion inbox', 'get cyberlegion working in this repo'. Not for spawning/messaging/dispatching a peer (that is legate), reading or acking owner mail (that is manage-inbox), or unrelated init like a git repo, npm package, or commit discipline."
+---
+
+# init-cyberlegion
+
+The onboarding front door to the Legion — a thin, user-invocable wrapper that walks a session through
+getting `cyberlegion` working in this repo: probe the environment, register the surfacing hook, and
+(only in a root session, only on an explicit yes) bind this pane as the durable `legate` owner inbox.
+It is a **thin wrapper**: every mechanic is a `cyberlegion` CLI call. The skill holds the *conversation
+and the judgment* — is this a root session? should we ask to bind? what does the environment look
+like? — the CLI holds all the *mechanism*.
+
+> **Running the CLI.** Every `node scripts/cyberlegion.mjs …` command below runs the `cyberlegion` CLI
+> this plugin ships. The path is relative to this skill's own directory, not the working directory.
+>
+> **Version pin.** Resolve the CLI version **once, before the flow**, by reading the plugin's bundled
+> map at `${CLAUDE_PLUGIN_ROOT}/.plugin/pins.json` — a flat `{ "<package>": "<version>" }` map the
+> release version flow keeps equal to the shipped package version. Look up the `cyberlegion` key:
+>
+> - **A version is found** → pass it to the hook registration in step 2 as `init --pin <version>`
+>   so the installed surfacing hook is pinned to the same shipped version. If you cannot resolve
+>   `scripts/cyberlegion.mjs`, run `npx -y cyberlegion@<version>` in its place, with the same arguments.
+> - **No `pins.json`, no `cyberlegion` key, or a malformed map** (an unbundled workspace checkout) →
+>   pass **no** `--pin`; if you cannot resolve `scripts/cyberlegion.mjs`, fall back to the unpinned
+>   `npx -y cyberlegion` form. **Never invent a version number.**
+>
+> Do not scrape the version from prose.
+
+## Flow
+
+### 1. Probe the environment
+
+```bash
+node scripts/cyberlegion.mjs mux doctor
+```
+
+Run this **before** touching the hook or any identity. It reports `harness`, `mux`, `pane`,
+`hubRoot`, and `selfId` — read it to learn the environment (is there a multiplexer? a pane?) and to
+detect root vs spawned (see step 3). Narrate a short, grounded summary of what it found — do not
+invent facts the probe did not report.
+
+### 2. Register the surfacing hook
+
+```bash
+node scripts/cyberlegion.mjs init --pin <version>
+```
+
+Pass `--pin <version>` with the version resolved above so the installed hook is pinned to the shipped
+version; **omit `--pin`** when the map yielded no version.
+
+Auto-detect is the default — no `--agent` flag. Pass `--agent <name>` **only** when `mux doctor` could
+not auto-detect the harness, or the user named one explicitly (it composes with `--pin`):
+
+```bash
+node scripts/cyberlegion.mjs init --pin <version> --agent <name>
+```
+
+This step is **idempotent**: if the hook is already registered, `init` reports `already present` —
+that is a clean no-op, never a duplicate registration and never an error.
+
+### 3. Detect root vs spawned — derived, never asked
+
+Read the probe's `selfId` from step 1. A **root** session has `spawnedBy` unset; a **spawned** unit
+has it set. Derive this from the probe — never ask the user to declare it.
+
+- **Spawned (non-root) unit** — stop here, right after the hook. Do not offer to bind; a spawned unit
+  is never the owner inbox.
+- **A hook-only request in a root session** ("just register the surfacing hook") — also stop here.
+  Registering the hook satisfies the ask; do not proceed to the bind offer unasked.
+- **Root session, broader onboarding intent, no `legate` owner bound yet** — continue to step 4.
+- **Root session where a `legate` owner is already bound** — stop; do not re-ask, do not re-mint.
+
+### 4. Ask before binding — never silent
+
+Only a root session with no `legate` owner bound is offered the bind. Ask plainly, e.g.:
+
+> "This looks like a root session with no legate owner bound yet. Bind this pane as the main legate
+> owner inbox?"
+
+- **User declines** — the registered hook stays in place; nothing else runs. Do not mint or bind.
+- **User agrees explicitly** — proceed to step 5.
+- **Already bound** — never reach this ask (see step 3).
+
+### 5. On an explicit yes — mint and bind
+
+```bash
+node scripts/cyberlegion.mjs unit register --standing --handle legate
+node scripts/cyberlegion.mjs attach
+```
+
+Run these **in this order** and only after the explicit yes: mint the durable, session-independent
+`legate` owner inbox first, then bind the current pane as that owner's live presence.
+
+**Non-mux parity.** If the probe reported no multiplexer or pane, `attach` is a no-op —
+that is expected, not a failure. Still run `unit register --standing --handle legate` on yes, and complete
+**without erroring**. The root session surfaces owner mail via the `!spawnedBy` fallback instead of a
+bound pane.
+
+## Boundaries
+
+- Every mechanic here is a `cyberlegion` CLI call — this skill writes no hub state and invents no
+  config format. Its only filesystem read is the plugin's own bundled `${CLAUDE_PLUGIN_ROOT}/.plugin/pins.json`
+  version map, to resolve the CLI pin.
+- It never mints or binds an owner identity without an explicit user yes.
+- It is distinct from `legate` — sending/spawning/dispatching to a peer is `legate`'s job, not this
+  skill's.
+- It is distinct from `manage-inbox` — reading or acking owner mail once bound is `manage-inbox`'s
+  job, not this skill's.
+- An unrelated `init` intent (a git repo, an npm package, commit discipline) is out of scope — defer
+  to the matching unrelated skill or decline.

package/skills/init-cyberlegion/scripts/cyberlegion.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+// Runs the cyberlegion CLI this plugin ships, so the skill beside it never fetches a copy through npx.
+// The package root is three levels up from this file (skills/<skill>/scripts/), resolved from the
+// file's own location: the working directory is the repository the agent is working on, not the plugin.
+// Arguments, output, and the exit code pass straight through the package's bin.
+//
+// A skill folder installed on its own has no package around it. Then this runs the published CLI of
+// the version that shipped the skill instead, so the skill still works, only slower. The version sync
+// run at release keeps FALLBACK at the package version.
+import { spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+const FALLBACK = 'npx -y cyberlegion@0.5.0'
+const bin = new URL('../../../bin/cyberlegion.mjs', import.meta.url)
+
+if (existsSync(fileURLToPath(bin))) {
+	await import(bin.href)
+} else {
+	process.stderr.write(`cyberlegion: no plugin package around this skill; running ${FALLBACK}\n`)
+	const [command, ...args] = FALLBACK.split(' ')
+	const res = spawnSync(command, [...args, ...process.argv.slice(2)], {
+		stdio: 'inherit',
+		shell: process.platform === 'win32',
+	})
+	if (res.error) {
+		process.stderr.write(`cyberlegion: could not run ${FALLBACK}: ${res.error.message}\n`)
+		process.exit(1)
+	}
+	process.exit(res.status ?? 1)
+}

package/skills/legate/README.md

@@ -0,0 +1,22 @@
+# legate (gateway)
+
+The Legate's front door to the Legion — a thin classifier skill that routes an agent-to-agent
+messaging or dispatch request to the matching `cyberlegion` CLI call, or to `dispatch-governance`
+when the request needs routing judgment.
+
+## When to use
+
+- You need to send or check mail with another agent session.
+- You need to spawn, close, or nudge a peer session.
+- You need to wait for a threaded reply.
+- You need work done to fulfill a role and a verdict back — but do not yet know whether that should
+  be a warm peer, a cold subagent, or done inline.
+
+## What it does
+
+- Classifies the request against a fixed intent → CLI-call table (mail, session, identity, admin).
+- Hands any dispatch intent to `dispatch-governance` rather than guessing a strategy.
+- Spawns the `headless-legate` agent when there is no user channel to relay through.
+- Loads no other governance and writes no state — a front door only.
+
+Every mechanic is a `cyberlegion` CLI call — harness-agnostic, MCP-free.

package/skills/legate/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: legate
+description: "Use this skill when you need to reach another agent session — send a message to a named peer or \"the pane on the right\", check your inbox, wait for a reply, spawn or close a peer session, or dispatch work to fulfill a role and get a verdict back."
+---
+
+# legate
+
+The Legate — gateway skill for the Legion, the front door to agent session spawning, messaging, and dispatch.
+It **classifies** the request and either runs the matching `cyberlegion` CLI call directly or hands
+routing judgment to `dispatch-governance`. It is a **thin classifier**: it holds no production
+logic, loads no other governance, and writes no state of its own.
+
+> **Running the CLI.** Every `node scripts/cyberlegion.mjs …` command below runs the `cyberlegion` CLI
+> this plugin ships. The path is relative to this skill's own directory, not the working directory.
+> If you cannot resolve it, run the published CLI of the version that shipped this skill instead,
+> with the same arguments: `npx -y cyberlegion@0.5.0`.
+
+## Doorbell vs mailbox
+
+Two different primitives, never confused: a **nudge** (`unit nudge <ref>`) is a dumb doorbell —
+it rings a peer's pane and carries no content. The **payload always lives in the mailbox**
+(`mail send`, or the brief file `unit spawn` drops for a new unit) — a peer that receives a nudge
+reads its mail to learn *why* it was rung. Never encode meaning in a nudge itself; never skip the
+mailbox because a nudge already fired.
+
+## Classification map
+
+| User intent | Handling |
+|---|---|
+| Send a message to a named peer, "the pane on the right", a claude/cursor peer | `node scripts/cyberlegion.mjs mail send --to <handle>` (or `unit nudge <ref>` first if the peer needs waking, then `mail send`) |
+| Check inbox / read unread mail | `node scripts/cyberlegion.mjs mail inbox` — `mail read <msg-id>` to peek, `mail ack <msg-id>` once handled |
+| Spawn a new peer session | `node scripts/cyberlegion.mjs unit spawn --agent <name> ...` — cyberlegion owns worktree creation; pass `--cwd <dir>` only when the caller already has a directory to spawn into (e.g. reusing an existing worktree) |
+| Close / tear down a peer session | `node scripts/cyberlegion.mjs unit close <id>` |
+| Wait for a threaded reply | `node scripts/cyberlegion.mjs mail await --thread <id>` |
+| Watch mail as it streams in (observer, never acks) | `node scripts/cyberlegion.mjs mail watch` |
+| List addressable peers | `node scripts/cyberlegion.mjs unit who` |
+| Sweep dead peers | `node scripts/cyberlegion.mjs unit prune` |
+| Onboard / set up cyberlegion (register the surfacing hook, bind the main owner pane, first-run setup) | **invoke the `init-cyberlegion` skill** — the interactive onboarding front door over `cyberlegion init` / `unit register --standing` / `attach` |
+| Diagnose the environment (harness, multiplexer, pane, hub root) | `node scripts/cyberlegion.mjs mux doctor` |
+| Register the surfacing hook by hand (low-level, explicit harness) | `node scripts/cyberlegion.mjs init --agent <harness>` — the `init-cyberlegion` skill wraps this; use directly only when scripting a known harness |
+| Dispatch work to fulfill a role with a brief and expect a verdict back (routing judgment needed — which strategy, which agent def, warm vs cold) | **hand off to `dispatch-governance`** — do not compose `unit spawn`/`mail await`/the Task tool yourself |
+| No user channel at all (unattended trigger, multi-unit fan-out) | **spawn the `headless-legate` agent** by name — it realizes this same gateway + `dispatch-governance` flow headless |
+
+## Load the handling skill in-session
+
+For an attended session (a user or peer session holds this gateway), classify and act directly —
+spawn nothing. The one exception is a **dispatch** intent: routing which strategy to use (warm
+channel, cold subagent, or run-inline) is judgment this gateway does not carry — load
+`dispatch-governance` in-session and let it decide.
+
+**Headless (no user channel): spawn `headless-legate`.** When this gateway is reached with no live
+user or peer channel to relay through — an unattended scheduler, a multi-unit fan-out — spawn the
+`headless-legate` agent by name. It is not a separate role: it is this same classify-then-route flow,
+realized headless, batching `needs-input` instead of asking live.
+
+## Boundaries
+
+This skill never talks to the filesystem or another session directly — every mechanic is a
+`cyberlegion` CLI call. It never chooses a dispatch strategy itself (that is
+`dispatch-governance`'s one job) and never invokes a harness's Task/subagent tool (that is the
+caller's own tool, used only inside `dispatch-governance`'s subagent path via
+`subagent-backend-governance`).

package/skills/legate/scripts/cyberlegion.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+// Runs the cyberlegion CLI this plugin ships, so the skill beside it never fetches a copy through npx.
+// The package root is three levels up from this file (skills/<skill>/scripts/), resolved from the
+// file's own location: the working directory is the repository the agent is working on, not the plugin.
+// Arguments, output, and the exit code pass straight through the package's bin.
+//
+// A skill folder installed on its own has no package around it. Then this runs the published CLI of
+// the version that shipped the skill instead, so the skill still works, only slower. The version sync
+// run at release keeps FALLBACK at the package version.
+import { spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+const FALLBACK = 'npx -y cyberlegion@0.5.0'
+const bin = new URL('../../../bin/cyberlegion.mjs', import.meta.url)
+
+if (existsSync(fileURLToPath(bin))) {
+	await import(bin.href)
+} else {
+	process.stderr.write(`cyberlegion: no plugin package around this skill; running ${FALLBACK}\n`)
+	const [command, ...args] = FALLBACK.split(' ')
+	const res = spawnSync(command, [...args, ...process.argv.slice(2)], {
+		stdio: 'inherit',
+		shell: process.platform === 'win32',
+	})
+	if (res.error) {
+		process.stderr.write(`cyberlegion: could not run ${FALLBACK}: ${res.error.message}\n`)
+		process.exit(1)
+	}
+	process.exit(res.status ?? 1)
+}

package/skills/manage-inbox/README.md

@@ -0,0 +1,12 @@
+# manage-inbox
+
+The human's surface for the **owner mailbox** — the durable, session-independent inbox where
+frameless (cron-started, no-parent-frame) agents push their reports via `relay-governance`.
+
+User-facing. Triggers on "check my inbox", "any reports for me", "read that report", "ack that",
+"clear my owner inbox", or when a surfaced owner-mail doorbell needs acting on. Wraps the
+`cyberlegion` CLI's owner-scoped mail commands (`mail inbox/read/ack --owner <handle>`) so a human
+roaming across sessions manages the one owner mailbox from anywhere.
+
+Read is a deliberate `mail ack --owner` — surfacing shows a report inline but is never a read
+receipt. See `SKILL.md` for the full flow (resolve owner → list → read → ack → reply).