cyberlegion 0.3.2 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cyberlegion",
-  "version": "0.3.2",
+  "version": "0.4.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",

package/plugin.json

@@ -0,0 +1,24 @@
+{
+	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+	"name": "cyberlegion",
+	"version": "0.4.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,66 @@ 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
+carries the version it was built against in `.plugin/pins.json`, and its skills read that pin to invoke `npx cyberlegion@<version> …` rather than inventing a version. In a
+workspace checkout with no bundled pin, they fall back to the unpinned `npx cyberlegion …` form or
+the local bin (`packages/cyberlegion/bin/cyberlegion.mjs`).
+
 ## 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,138 @@
+---
+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`.
+
+## 1. Resolve the agent definition
+
+```bash
+npx cyberlegion@0.3.1 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
+npx cyberlegion@0.3.1 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
+  npx cyberlegion@0.3.1 unit spawn --agent <R> --brief-file <B> --at <placement>
+  npx cyberlegion@0.3.1 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/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,110 @@
+---
+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*.
+
+> **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
+> `universal-plugin bundle` step emits at release time. Look up the `cyberlegion` key:
+>
+> - **A version is found** → use it for every `npx cyberlegion@0.3.1 ...` call below, **and** 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.
+> - **No `pins.json`, no `cyberlegion` key, or a malformed map** (an unbundled workspace checkout) →
+>   fall back to the unpinned `npx cyberlegion ...` form and pass **no** `--pin`. **Never invent a
+>   version number.**
+>
+> Do not scrape the version from prose. (`legion-publish` — actually publishing `cyberlegion` to npm —
+> is a later extraction CR; until then the npx pin is dormant and the local workspace bin serves.)
+
+## Flow
+
+### 1. Probe the environment
+
+```bash
+npx cyberlegion@0.3.1 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
+npx cyberlegion@0.3.1 init --pin <version>
+```
+
+Pass `--pin <version>` with the version resolved above so the installed hook is pinned to the shipped
+version; **omit `--pin`** (and use the unpinned `npx cyberlegion init`) 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
+npx cyberlegion@0.3.1 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
+npx cyberlegion@0.3.1 unit register --standing --handle legate
+npx cyberlegion@0.3.1 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/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.
+
+> **Version pin.** Every invocation below reads `npx cyberlegion@0.3.1 ...` — a placeholder.
+> The package is not yet published to npm (`legion-publish` is a later CR in the extraction); until
+> then, resolve the CLI from a workspace checkout (`packages/cyberlegion/bin/cyberlegion.mjs`) or
+> whatever pinned version the project has declared. Never invent a version number.
+
+## 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 | `npx cyberlegion@0.3.1 mail send --to <handle>` (or `unit nudge <ref>` first if the peer needs waking, then `mail send`) |
+| Check inbox / read unread mail | `npx cyberlegion@0.3.1 mail inbox` — `mail read <msg-id>` to peek, `mail ack <msg-id>` once handled |
+| Spawn a new peer session | `npx cyberlegion@0.3.1 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 | `npx cyberlegion@0.3.1 unit close <id>` |
+| Wait for a threaded reply | `npx cyberlegion@0.3.1 mail await --thread <id>` |
+| Watch mail as it streams in (observer, never acks) | `npx cyberlegion@0.3.1 mail watch` |
+| List addressable peers | `npx cyberlegion@0.3.1 unit who` |
+| Sweep dead peers | `npx cyberlegion@0.3.1 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) | `npx cyberlegion@0.3.1 mux doctor` |
+| Register the surfacing hook by hand (low-level, explicit harness) | `npx cyberlegion@0.3.1 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/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).

package/skills/manage-inbox/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: manage-inbox
+description: "Use this skill when the user wants to check, read, or clear the owner mailbox — the durable inbox where headless and cron-started agents send their reports. Triggers: 'check my inbox', 'any reports for me', 'what did the agents send', 'read that report', 'ack that', 'mark it read', 'clear my owner inbox', or acting on a surfaced owner-mail doorbell."
+---
+
+# manage-inbox
+
+The human's surface for the **owner mailbox** — the hub-level, session-independent inbox a standing
+owner identity holds, where frameless agents (cron-started, no parent frame) push their reports. It
+wraps the `cyberlegion` CLI's owner-scoped mail commands so a human roaming across sessions manages
+the one owner mailbox from wherever they are.
+
+> **Version pin.** Invocations read `npx cyberlegion@0.3.1 …` as a placeholder. Until the package
+> is published, resolve the CLI from the workspace checkout (`packages/cyberlegion/bin/cyberlegion.mjs`)
+> or the project's pinned version. Never invent a version number.
+
+## Resolve the owner handle
+
+The owner mailbox is a **standing** identity. Find it first:
+
+```bash
+npx cyberlegion@0.3.1 unit register --standing            # lists the standing owner record(s)
+```
+
+Use `$CYBERLEGION_OWNER` if set, else the single standing handle listed. If **no** standing owner
+exists, there is no owner mailbox yet — create one with `unit register --standing --handle <name>` (that is a
+deliberate act; do not auto-create it while just checking mail).
+
+## List — what is waiting
+
+```bash
+npx cyberlegion@0.3.1 mail inbox --owner <handle>            # all owner mail, oldest-first
+npx cyberlegion@0.3.1 mail inbox --owner <handle> --unread   # only what is new
+```
+
+The aggregate line reports `<N> messages (<U> unread)`. This is a **pull** from any session — the
+same unread also **surfaces** into a root session automatically (the doorbell), so you may already
+have seen it inline; listing is how you review deliberately.
+
+## Read — peek without consuming
+
+```bash
+npx cyberlegion@0.3.1 mail read <msg-id> --owner <handle>
+```
+
+Prints the report body (sender, subject, id). **Read does not ack** — the message stays unread and
+keeps surfacing until you explicitly clear it. Peeking is safe; it changes nothing.
+
+## Ack — the only thing that clears it
+
+```bash
+npx cyberlegion@0.3.1 mail ack <msg-id> --owner <handle>
+```
+
+Ack is the sole read-state change and the sole signal that a report is handled — a surfaced message
+that was merely printed into a session is **not** read until you ack it. Ack once you have actually
+acted on (or consciously dismissed) the report; acking an already-acked or unknown id errors rather
+than silently succeeding. Two concurrent acks of the same message resolve to exactly one success —
+nothing is double-consumed.
+
+## Reply — answer a frameless agent's question
+
+A report may be a **question** a frameless agent could not ask live. Reply on its thread so a later
+tick (or the agent's next run) picks up the answer:
+
+```bash
+npx cyberlegion@0.3.1 mail send --to <agent-or-thread-origin> --thread <t> --body "<answer>"
+```
+
+The thread carries the state across the agent's stateless re-runs.
+
+## Boundaries
+
+- This skill only manages the **owner** mailbox (`--owner`). A session's own inbox is the plain
+  `mail inbox`/`read`/`ack` (no `--owner`) and is not this skill's concern.
+- It is a thin CLI wrapper — it decides *nothing* about routing or dispatch (that is the Legate /
+  `dispatch-governance`), and writes no state beyond the ack/reply the human directs.

package/skills/relay-governance/README.md

@@ -0,0 +1,36 @@
+# relay-governance
+
+Internal cyberlegion governance. The Legion's **report/ask contract**: how a headless agent (no live
+user channel) returns a result or surfaces a question it cannot answer, keyed on its own lifecycle —
+plus the **receive side**: how an agent triages a relayed steer by authority level.
+
+- **Subagent** (Task-spawned, a caller frame awaits) → return `needsInput` in the `DispatchResult`.
+- **Spawned peer / channel** (spawner awaits) → return the packet or reply on the mail thread.
+- **Bare top-level / cron** (no frame) → push `mail send` to the standing owner and exit; a later
+  tick or the owner's reply resumes, state carried on the thread.
+
+Loaded by `dispatch-governance` (to relay a callee's `needsInput`) and by any headless agent
+(`headless-legate`, `sdd-automaton`, cold judges). Not user-invocable — see `SKILL.md`.
+
+**Receiving a steer:** decompose by authority level, never bundle-adopt or bundle-reject. An
+in-scope refinement (testable against the receiver's own frozen spec / CR acceptance / leash) adopts
+in-band, no provenance needed; cross-cutting / out-of-leash doctrine escalates up the relay for
+ratification. Provenance over peer mail cannot be established, so a receiver acts only on what it
+can verify against its own loaded contract — a ratification it fetched from a peer is invalid.
+
+**The ownership chain:** keyed on relationship, not on transport alone. A decision relayed by the
+receiver's **own owner** **and** arriving on a **turn** in its own session — carrying the Council's
+verbatim words, where they were said, the relaying unit, and its scope (one action on one target) —
+is adoptable within that named scope and nothing adjacent, spent once acted on, attenuating at every
+hop. Either half alone leaves it a peer steer. The four parts are a **well-formedness** requirement:
+presence is checkable on its face, so a missing part gates adoption, and truth is not, so the parts
+buy **audit** after the fact, never verification in the moment. Not forgery-proof: `unit nudge
+--message` records no caller identity, so position is a structural fact, not a proof.
+
+This is the **single home** of that rule. `subagent-backend-governance` references it for the
+owner's mid-turn channel rather than restating it, and the revision part of the scope is a named
+**open cross-repo seam** — a sibling corpus states a three-part scope; this one states two.
+
+The frameless→owner branch composes the `cyberlegion` CLI's standing owner identity (`identity
+owner`), owner mail (`mail send` / `mail --owner`), and owner-mail surfacing (the `surfacing` hook).
+Read is a deliberate `mail ack --owner`; surfacing shows a message but is never a read receipt.