cyberlegion 1.6.0 → 1.7.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "cyberlegion",
-	"version": "1.6.0",
+	"version": "1.7.0",
 	"description": "Agent session spawning, messaging, and dispatch — the Legion and its Legate.",
 	"author": {
 		"name": "unional"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "cyberlegion",
-	"version": "1.6.0",
+	"version": "1.7.0",
 	"description": "Agent session spawning, messaging, and dispatch — the Legion and its Legate.",
 	"author": {
 		"name": "unional"

package/.plugin/pins.json

@@ -1,3 +1,3 @@
 {
-	"cyberlegion": "1.6.0"
+	"cyberlegion": "1.7.0"
 }

package/CHANGELOG.md

@@ -0,0 +1,459 @@
+# cyberlegion
+
+## 1.7.0
+
+### Minor Changes
+
+- 7f4858a: Update cyber-mux to 0.11.0. `unit focus` now records each focus in cyber-mux's jump history, so `cyber-mux focus --back` in the focused pane returns to the pane the focus came from.
+- 81b0c81: Add `--repo <name>` and `--branch <name>` to `unit focus`, so a caller can focus a unit by its worktree instead of its handle. One live match is focused; several fail listing the candidates; none fails naming the selector.
+
+### Patch Changes
+
+- 27d08e4: `unit register` now records the repository's primary checkout (`worktree.primaryRoot`) alongside the worktree root and branch, as `unit spawn` does, so `unit focus --repo` finds a registered unit in a linked worktree by the repository's name. Re-registering fills in the primary root on an older record that lacks one.
+- 067b85c: Update runtime dependencies.
+
+## 1.6.1
+
+### Patch Changes
+
+- 815a927: Depend on `cyber-agentkit` 2.x. Only the `cyber-agentkit/worktrees` entry is used, and it is unchanged.
+- 89c4f2c: Describe `unit clear`'s current injection in the session-adapter conformance ledger: one `submit` behind the draft guard, still with no read-back.
+- ad2f96d: Move `commander` to `devDependencies`. Only the bundled CLI uses it, and the CLI carries its own inlined copy, so installing `cyberlegion` no longer pulls in `commander`.
+- 89c4f2c: Tighten wording in `dispatch-governance` and `subagent-backend-governance`: say plainly that this CLI has no verdict-schema check, drop an ADR number this repo does not carry, and make the no-mid-flight-switch rule unambiguous.
+- 89c4f2c: Say in the `legate` skill that it loads `dispatch-governance` on a dispatch intent, instead of claiming it loads no other governance.
+- 89c4f2c: Align the `legate` skill's doorbell rule with `relay-governance`: a nudge never carries a message's payload, but `unit nudge --message` may carry a relayed decision.
+- 89c4f2c: List `unit clear` in the `legate` skill's classification map, for resetting a warm peer's context while keeping its pane.
+- 014c464: Update runtime dependencies.
+- 014c464: Update runtime dependencies.
+- c517d8e: Include `CHANGELOG.md` in the published package.
+
+## 1.6.0
+
+### Minor Changes
+
+- 85417a3: Move the worktree library dependency from `@cyberuni/agent-harness` to `cyber-agentkit` 1.0.0. The worktree lease marker is now `cyber-agentkit`; 1.x still recognises leases written with the old marker. Release together with cyber-mux.
+- 5ecfa33: Update runtime dependencies.
+- 5ecfa33: Update runtime dependencies.
+
+### Patch Changes
+
+- 6fd551f: Each skill's `scripts/cyberlegion.mjs` is now a self-contained script that `plugin build` compiles from `src/skill-script.ts`, instead of a launcher that reached up three levels to `bin/cyberlegion.mjs` and fell back to `npx`. A skill linked or copied on its own, including one linked out of `node_modules` by pnpm, runs the CLI it shipped with and needs no package, no `node_modules`, and no TypeScript at runtime. cynapse stays an optional peer: the compiled script loads it at runtime when it resolves and runs without it otherwise.
+
+## 1.5.0
+
+### Minor Changes
+
+- eb9140e: When [cynapse](https://github.com/cyberuni/cynapse) is installed beside it, cyberlegion registers its units as cynapse participants (stage 1 of #153). Each unit is `live` while it exists and `retired` once it is exited or closed, a new handle renames it, and every sync reconciles the whole hub, so a crash is corrected by the next run. `project register` and `project show` resolve the repository's GitHub node id, pass it to cynapse, and report the channel cynapse keys by it. cynapse is an optional peer dependency: without it, nothing changes and nothing extra runs. Mail still goes through the hub.
+- 4ab794a: Update runtime dependencies.
+- 4d8fa38: `unit spawn` now leases its worktree from the worktree library (`@cyberuni/agent-harness/worktrees`) instead of making a fresh checkout per unit. An idle worktree a closed unit released is recycled onto the new unit's branch, and a new one is created only when none is idle, at the library's slot path `<parent>/<repo>.worktrees/<repo>-<n>` (it was `legion-<id6>`). The lease is git's own lock on the worktree, and the spawn output reports whether the worktree was `reused`.
+  
+  `unit close` releases a leased worktree instead of removing it, so the next spawn can recycle it. Release removes nothing, so it does not refuse uncommitted changes, and a dirty worktree is not recycled. A lease someone took away is reported as `lost`, and the close still completes. The output gains a `lease` field.
+  
+  A spawn with `--worktree-path` bypasses the library: it holds no lease, and `close` removes its worktree as before. So does a unit spawned by an earlier version.
+- ebd47ce: `unit spawn` (and `service start`) now cut a new worktree's branch from freshly fetched `origin/HEAD` instead of the caller's local HEAD, so a unit no longer starts behind its upstream. `--base <ref>` names the start point instead. When there is no origin, the fetch fails, or `origin/HEAD` is not recorded, spawn falls back to local HEAD and says why on stderr. The spawn output reports the `base` it used.
+
+### Patch Changes
+
+- 7b7efd2: Governance skills no longer carry incident IDs, unshipped source paths or a migration-relative bullet, and `relay-governance` no longer claims to be the single home of the relayed-decision rule.
+
+## 1.4.1
+
+### Patch Changes
+
+- b95ccc7: `unit nudge --help` now says `--message` text is delivered as a turn in the peer's session, with the mail doorbell as the default.
+
+## 1.4.0
+
+### Minor Changes
+
+- 09f5cf6: `init-cyberlegion` now offers the `legate` owner a home when it mints it. It first explains the presence: `unit claim legate` makes a live session the one that gets the owner's mail, until another session claims it, `--clear` unbinds it, or that session exits. A home is the fallback when nobody holds the presence, and once set it is used instead of ringing the attached pane. Naming a folder registers it with `--home` and one launch (`--harness` or `--agent`); naming none mints the owner bare, as before. An owner that already exists is offered to add a home or drop it with `--clear-home`, without the bind being asked again. With no multiplexer, no home is offered.
+- f426a19: A standing owner can now have a home: `unit register --standing --handle <name> --home <dir> (--agent <def> | --harness <h>)`. When mail reaches a standing owner with no live presence, `mail send` spawns a session in the home in its own workspace and binds it as the presence. It accepts the folder's trust prompt and wakes the session to read the owner's inbox. A home outranks the bound main pane. `--clear-home` drops it. A home is validated when it is registered: it must exist, name exactly one launch, and not be a primary checkout. A spawn that cannot happen at delivery is a warning that falls back to the main pane. That includes a sender outside any multiplexer pane, and the warning names `CYBER_MUX` as the way to reach a running one. A re-register of a standing owner now keeps its bound presence instead of dropping it.
+
+### Patch Changes
+
+- d97003f: `mail send --to <handle>` and the verbs that take a unit ref now fail loud, naming the ids, when a handle names two or more live records — such as the service endpoints of two same-named repositories. They used to take the first match silently, so mail could land in the wrong endpoint. A standing record still wins a handle it shares; address any other ambiguous unit by id.
+- da3bea1: `unit spawn` and `unit restart` now report `rung: true` only once the new session's harness has posted the first-turn doorbell, not merely once the text left the input box. A doorbell typed before a booting harness drew its input box used to vanish and still count as rung, so the session sat idle with its brief unread. The doorbell is now typed again when that happens, and reported as `rung: false` with a warning if it never lands.
+
+## 1.3.0
+
+### Minor Changes
+
+- 595d3af: `cyberlegion init --allow-cli` adds `Bash(cyberlegion *)` to Claude Code's user `permissions.allow` (`~/.claude/settings.json`, or `$CLAUDE_CONFIG_DIR/settings.json`). It appends the rule to the existing list, writes nothing when a covering rule is already there, and refuses to rewrite a settings file it cannot parse. Without the rule, Claude Code's auto-mode classifier can deny a unit's `cyberlegion mail send` as an external write, so the unit cannot report back. `mux doctor` and `init` on Claude Code now report the rule as `present`, `missing`, or `unreadable`, and suggest `init --allow-cli` when it is missing.
+- 2463909: `unit restart` resumes a claude or codex unit's last conversation instead of always starting an empty session. The SessionStart hook (`mail hook`) now records the harness's session id on the unit each time a session starts in its pane, and restart relaunches with `claude --resume <id>` or `codex resume <id>`, ringing the session to continue its work. If the harness rejects the id, the plain launch runs instead. Cursor units, units with no recorded session, units launched through a wrapper command, and `unit restart --fresh` still get an empty session and a rebrief. The restart result gains a `resumed` field.
+- 2118659: `unit spawn` takes `-C, --repo <path>` to create the unit's worktree from another repository without `cd`-ing there first, so the call stays one bare `cyberlegion` command a `Bash(cyberlegion *)` allow rule covers.
+
+### Patch Changes
+
+- 17880fd: The plugin now ships `bin/cyberlegion`, an extensionless twin of `bin/cyberlegion.mjs`. Claude Code puts a plugin's `bin/` on the Bash tool's PATH, so a bare `cyberlegion …` now runs the shipped CLI in any Claude Code session instead of failing with `command not found` when there is no global install.
+- 7019060: A spawned unit's SessionStart mail hook now runs the CLI that spawned it, not the installed plugin's copy. `unit spawn` sets `CYBERLEGION_CLI` to the unit's CLI shim, and the plugin hook runs it when it names an executable, falling back to the plugin's own CLI otherwise — never to whatever `cyberlegion` is on PATH.
+- 7c4ddaa: `unit restart` no longer leaves a running session unbound when it dies between opening the new pane and binding the unit to it. The new pane's launch line now runs `unit rebind <id>` through the unit's CLI shim before the harness starts, so the session binds itself to the unit. The unit comes back `active` in the new pane, with no rerun and no second pane.
+- 9bbd63f: Stop treating a doorbell that a harness put back in its input box as a human's unsent draft. cursor-agent with a rejected login restores the ring's text after taking it, and the next ring then waited 20 seconds on it, or refused when it wrapped onto two rows. The draft guard now recognizes the CLI's own ring text, clears it at once, and types nothing back.
+
+## 1.2.0
+
+### Minor Changes
+
+- 9523925: Drop the PostToolUse mail hook. The plugin's `hooks/hooks.json` now fires on SessionStart only, and `mail hook` rejects `--event PostToolUse`. The hook re-injected every unread message on every Write/Edit, which cost more than the mid-turn latency it saved: the `mail send` doorbell already rings a busy unit's pane. `cyberlegion init` removes a PostToolUse project hook an earlier `init` wrote for Claude Code or Codex, so re-run it if your project config still has one.
+
+### Patch Changes
+
+- 8747331: `unit close` now removes a unit's worktree whatever directory it is run from. It found the repository from the caller's directory, so a close run from another repository asked the wrong repository to remove the worktree and aborted. The repository now comes from the worktree itself, and `unit spawn` records it on the unit, so a close whose worktree directory is already gone runs `git worktree prune` there and clears the registration git kept.
+- 12aa36d: `mail hook` no longer appends a `## Legion setup` nudge to a root session's payload. It fired in every root session on a hub whose owner is a claimed presence rather than a bound main pane, and it named `cyberlegion init` for a pane binding `init` does not do. The payload now carries only the caller's own unread mail and the standing owners' unread mail; onboarding stays with the `init-cyberlegion` skill.
+- 69b3475: `unit prune` no longer exits a unit whose pane is still live just because its last-seen is more than 15 minutes old — a unit working without calling the CLI, or idle at its prompt, keeps its handle. The staleness timer now applies only to records with no pane. When a pane's multiplexer cannot be queried, `prune` (and `who --reconcile`) leaves the record alone rather than reaping a possibly live unit.
+
+## 1.1.0
+
+### Minor Changes
+
+- a95c547: The mail-surfacing hook now runs the CLI the session was installed with, never one `npx` resolves from the registry when the hook fires (#69). The plugin ships its own `hooks/hooks.json` for Claude Code and Codex, running `node "${CLAUDE_PLUGIN_ROOT}/bin/cyberlegion.mjs" mail hook`, so the hook runs offline at the enabled version. On those harnesses `cyberlegion init` writes no project hook, removes one an earlier `init` wrote, and reports `provided by plugin` or `removed project hook`. On Cursor, `init` registers a hook that runs a `cyberlegion` on `PATH` first and falls back to `npx -y cyberlegion[@<pin>]` only when there is none.
+- afc0c3d: `relay-governance`: a decision relayed down the ownership chain now reaches a unit in the user-channel holder's own words, and the unit reads its scope from the decision request those words answer. The relayer adds no envelope (no where-said, relayer, or scope labels) and no next steps, and records that provenance on the work item's mail thread instead. A turn that answers no outstanding request is the owner's order, not a decision. The scope is the action, target, and revision the request named, narrowed by the words, so a decision no longer survives its target moving past that revision. This replaces the four parts a relayed decision used to carry, and with them the open question of whether the scope had two parts or three.
+
+### Patch Changes
+
+- 4571072: `unit close` no longer demands `--force` for a finished unit whose only change is the `.agents/cyberlegion/config.json` marker spawn stamped into its worktree, and `unit close --force` now has a real-git test proving it removes a worktree holding untracked and modified files.
+- 2467ba7: `unit spawn` (and `service start`) on cursor with both a model and an effort no longer launches `--model '<model>[effort=<level>]'`, which current `cursor-agent` refuses with "Cannot use this model". It now runs `cursor-agent models` and launches the flat `<model>-<level>` id when that id is listed. When no such id is listed, or the listing fails, it launches the model without the effort, warns on stderr, and reports the effort as `<level> (not applied)`.
+- a310dd7: Ring a peer once per nudge when its harness takes the turn but puts the text back in its input box. cursor-agent with a rejected login did this, and `unit nudge` (and the mail and spawn doorbells) read the restored text as unsent and flushed it again, queuing the ring twice or more.
+- f909cf4: `unit spawn` no longer hangs silently at a harness's folder-trust prompt. A spawn that creates a worktree accepts the prompt (Claude Code: Down, then Enter, checked against the screen so Enter never lands on "No, exit"; Codex: `1`, then Enter; cursor-agent: `a`). A `--cwd` spawn leaves the prompt for a person. A prompt left showing either way rings nothing, names the folder, harness, and pane on stderr, and exits non-zero. The first-turn doorbell now waits until the prompt is answered: typed into the prompt, its Enter quit Claude Code and an `a` in its text answered cursor-agent's prompt.
+
+## 1.0.0
+
+### Major Changes
+
+- 77fbb66: Update runtime dependencies.
+
+### Minor Changes
+
+- 06e4650: Ringing a peer no longer types over a human's unsent draft. The `mail send` doorbell, the spawn first-turn doorbell, `unit nudge`, and `unit clear` first read the peer's input box (Claude Code, Codex, cursor-agent). A draft being edited is waited out; a draft left unchanged for 20 seconds is cleared, the ring is sent, and the draft is typed back unsent. A draft that keeps changing for 60 seconds, or an idle draft spanning several rows, is left alone and the ring is skipped: the doorbell reports a warning, and `unit nudge`/`unit clear` fail.
+- 441d2e3: You can now end or replace a unit's session without destroying the unit. `unit close` is still the only command that removes a unit.
+  
+  - `unit stop <ref>` tears down the unit's pane, confirms the backend no longer lists it, and marks the unit `stopped`. The unit keeps its id, handle, inbox, brief, and worktree. A stopped unit is never pruned and stays addressable by handle, so mail sent to it while it has no session still lands in its inbox.
+  - `unit restart <ref> [--no-wake]` opens a fresh session at the unit's cwd with the launch command it was spawned with, and rings the session to read its brief. If a session is still running, restart stops it first. If the new session fails to open, the unit is left stopped, and running restart again recovers it.
+  - `unit rebind <ref>`, run inside a pane where you started the harness by hand, makes that session the unit.
+  - `unit show <ref>` reports where a unit's runtime is, whether the backend lists it right now (`live`, `gone`, `unknown`, `stopped`, `exited`), and which controls work on it. It writes nothing.
+  
+  `unit close` now also deletes the unit's mailbox. Before this change, the mailbox was left behind on disk. `unit spawn` now records its launch command on the unit's record so that `restart` can reuse it.
+
+### Patch Changes
+
+- 731731f: A cursor spawn with an effort but no model no longer fails. `cursor-agent` accepts no effort on its default model, so the spawn launches at cursor's default without the effort, warns on stderr, and reports the effort as `<level> (not applied)`.
+- 179bd81: Update cyber-mux to 0.8.0.
+
+## 0.5.0
+
+### Minor Changes
+
+- afa7fb2: The plugin's skills now run the CLI they ship with. Each skill that calls `cyberlegion` carries a `scripts/cyberlegion.mjs` launcher that runs this package's own CLI, so a skill no longer pays for an `npx` fetch on every call or races other agents on the npx cache. Where the launcher cannot be resolved, a skill names one fallback pinned to the version that shipped it, and `pnpm version` now rewrites those pins and `.plugin/pins.json` at every release.
+- 9b25902: `unit spawn` accepts `--model <name>` and `--effort <level>`, which set the model and effort for one launch. The precedence is flag > agent def > harness default, and a flag never writes back to the def. The flags work with `--agent`/`--agent-file` and with a bare `--harness`. The spawn output now includes `model` and `effort`, reporting what the session launched with, or `(harness default)` when no source set one.
+
+### Patch Changes
+
+- 46d67c6: `bin/cyberlegion.mjs` now fails with a clear message when `dist/cli.mjs` is missing, naming the file and the same-version `npx -y cyberlegion@<version>` fallback, instead of a raw `ERR_MODULE_NOT_FOUND`.
+- 64195cc: `unit spawn --agent` now passes a def's instructions in a form each harness accepts. Claude still gets `--append-system-prompt`. Codex now gets its `developer_instructions` config override (`-c developer_instructions="…"`), because codex has no `--append-system-prompt` flag. Cursor has no way to take instructions from the command line, so spawn now writes them in front of the task in the peer's brief file, under an `## Agent instructions` heading.
+- 725ee89: The `manage-inbox` skill no longer guesses which owner mailbox to use. If `CYBERLEGION_OWNER` is unset and more than one standing owner exists, it stops without running any mail command, lists every standing handle, and asks you to set `CYBERLEGION_OWNER`. If `CYBERLEGION_OWNER` names a handle that is not a standing owner, it reports the error instead of switching to another owner.
+- 19a9a68: `unit spawn --agent` now launches with the agent def's `effort`. Before this fix the value was parsed and then silently dropped. Each harness receives it through its own control: `--effort <level>` for claude, `-c model_reasoning_effort="<level>"` for codex, and a bracket parameter on the model (`<model>[effort=<level>]`) for cursor. Cursor has no effort control apart from the model, so a cursor def that sets `effort` without a `model` now fails with an error instead of launching at the default effort.
+- 53901c9: `unit spawn` now puts a `cyberlegion` command on the spawned session's PATH. It is a shim in the unit's data dir that re-runs the exact CLI that spawned the unit, so a brief's `cyberlegion mail send` works as written and reports through the spawning version, not one fetched from the registry.
+- 6a1ec6c: An agent def whose `harness` tag is not `claude`, `cursor`, or `codex` now fails to resolve, with an error naming the value and the valid harnesses. Before this fix a typo such as `harness: claud` resolved, and `unit spawn --agent` built a launch command starting with `undefined`. `agent list` fails the same way when any def it finds carries an unknown harness.
+
+## 0.4.0
+
+### Minor Changes
+
+- 72a0511: `unit close --keep-worktree` reaps a unit's record, mailbox, pane and brief while leaving its
+  worktree on disk, and reports the retained path (`retained` in TOON, `retainedWorktree` in JSON) so
+  a pool can detach the checkout and spawn the next unit into it with `--cwd`.
+  
+  Because nothing is deleted, the flag skips the dirty-worktree refusal — that check only ever
+  protected uncommitted work from `git worktree remove`. The primary-checkout refusal is unchanged:
+  neither `--force` nor `--keep-worktree` overrides it.
+- 33a64da: Add project references and project services with fenced, resolve-or-start ownership.
+  
+  - `project register|list|show` give a repository one stable id shared by its default checkout and every linked worktree, resolvable by id, path, or unique name from anywhere.
+  - `service resolve|acquire|bind|release|handoff|verify|start` give each named project service exactly one authoritative owner. Concurrent starts converge on one reservation; failed starts are retryable; a healthy owner is only displaced by an explicit, generation-checked force; handoff and recovery bump a fencing generation that `service verify` checks.
+  - A service endpoint is a durable mailbox independent of its owners (`mail inbox --owner <endpoint>`), exempt from prune and refused by `unit close`, so pending mail survives owner replacement. A pane-less owner reports that its session control is not recoverable.
+
+### Patch Changes
+
+- 9f2fe15: Ship the agent plugin inside the npm package, and bundle the CLI's dependencies into `dist/cli.mjs`.
+  
+  `plugin.json`, the generated `.claude-plugin/` and `.codex-plugin/` manifests, `.plugin/pins.json`,
+  `skills/`, and `agents/` now live in the package and are published with it.
+  
+  An installed agent plugin is a copy of a source checkout, not an npm install, so its directory has
+  no reliable `node_modules`. `dist/cli.mjs` now inlines `commander` and `cyber-mux` and runs with no
+  `node_modules` present. The library entry keeps both external, so a consumer that also uses
+  cyber-mux shares one copy.
+
+## 0.3.2
+
+### Patch Changes
+
+- 7cb6aaa: Take `cyber-mux` 0.5.0, whose `read` answers with `{ text, truncated? }` instead of a bare
+  string. `readUnit` still returns the trailing screen as a string, so nothing in this package's
+  own surface changes — only the shipped code behind it.
+- d28a531: Hardened `FileStore` against the concurrency and corruption risks a filesystem-only,
+  daemonless, multi-process mailbox is actually exposed to (surveyed from `agmsg` and
+  `firstmate`, two comparable tools, in `.research/messaging-robustness/evidence.md`):
+  
+  - Every store mutation (`putMessage`, `putAgent`, `putPaneIndex`, `writeBrief`,
+    `setMainPane`) now writes atomically — a sibling temp file, then `renameSync` into place —
+    instead of `writeFileSync` on the final path directly. A process crash mid-write, or a
+    reader racing a writer, can no longer hand `JSON.parse` a truncated file.
+  - Added an advisory, mkdir-based lock (`store/lock.ts`, `Store#withLock`) for genuine
+    read-modify-write operations such as `setMainPane`'s rebind. It reclaims a lock abandoned
+    by a confirmed-dead process but never steals one a live process still holds.
+  - A corrupt record file now throws a typed, file-named `CorruptRecordError` instead of a
+    bare `SyntaxError`; missing and corrupt records stay distinguishable.
+  - An agent or message id that would traverse outside its intended path segment (`../`, an
+    absolute path, an embedded path separator) is now rejected with a typed `InvalidIdError`
+    on write, rather than being joined into a filename unchanged.
+- 6d242f9: Restored the license file in the published tarball. Up to 0.3.1 this package was
+  published from a monorepo whose root license file was picked up automatically at publish
+  time. After the move to its own repository the root file is named in lower case, which
+  that mechanism no longer matched, so the tarball would have shipped with no license text
+  at all — only the `license: MIT` field in the manifest. The package now carries its own
+  copy, so the license travels with the code regardless of what the repository root is
+  called.
+- 1536191: `unit claim`/`unit claim --clear` (`identity.ts`'s `claimPresence`/`clearPresence`) now serialize
+  their load-mutate-save of a standing owner's presence pointer behind the store's advisory lock,
+  matching `setMainPane`. Two concurrent claims (or a claim racing a clear) against the same standing
+  owner previously read-modified-wrote the record unguarded; the last-claim-wins semantics are
+  unchanged, but the transition itself is now atomic rather than racing two processes' independent
+  reads against each other.
+- f551433: Removed the package's `prepack` script. It ran `pnpm build`, and the build tool writes
+  ANSI-colored progress lines to stdout — which corrupted the JSON that `npm pack --json`
+  emits, so any tool inspecting the package that way got a parse error instead of a file
+  list. Nothing is lost by dropping it: every path that packs or publishes this package
+  already builds first.
+- 19e95be: `--version` now reports the version from the package manifest instead of a hardcoded
+  `0.0.0`. Every release since 0.0.1 shipped a CLI that reported `0.0.0` regardless of the
+  version actually installed, which made `npx cyberlegion@<pin> --version` useless for
+  confirming which build was running. The test that covered `--version` asserted the literal
+  `0.0.0`, so it pinned the defect rather than catching it; it now asserts against the
+  manifest and fails loud on a placeholder.
+
+## 0.3.1
+
+### Patch Changes
+
+- e75f4a0: Fix stale `npx` version pins in the readmes.
+
+  The documented pin-to-an-exact-version examples cited versions that were never
+  published — `cyberplace@0.7.0` and `cyberfleet@0.1.0` return E404 — so anyone
+  copying them got a hard failure. `cyberlegion@0.1.0` resolved but was two minors
+  behind. Each now cites the current published version.
+
+## 0.3.0
+
+### Minor Changes
+
+- 82b3c24: **BREAKING** — the spawn wake now carries the brief instruction, and the SessionStart hook no longer
+  injects a brief.
+
+  `unit spawn`'s first-turn doorbell used to be content-free (`"Your brief is loaded in context — read
+it and begin work."`) because the peer's brief was injected into its context by the peer's own
+  `mail hook` SessionStart branch. That made brief pickup depend on a hook firing in the child — in the
+  child's harness, with the hub's hook correctly installed — none of which the spawning side can
+  observe. When the chain broke, the peer was woken and told to read a brief that was not there.
+
+  The doorbell is now the instruction itself, naming the brief's **file path**: _read your brief at
+  `<path>`, then begin work_. The brief is still written to its file and still never typed into the
+  pane, so the wake stays one bounded line however large the brief is.
+
+  What changes for consumers:
+  - `spawnAndWake` is the composed operation to reach for — it spawns the peer AND delivers its first
+    turn, deriving the doorbell's brief path from the record it just wrote. `spawn` alone still opens a
+    peer that sits idle, brief unread.
+  - `mail hook` never emits a `## Your brief` section, on the first call or any later one.
+  - The `spawning` agent status is retired — `unit spawn` registers a peer `active` outright, since
+    nothing flips it any more. A record migrated from an older hub may still carry `spawning`; reads
+    preserve it verbatim and never coerce or normalize it. (`unit register` still asserts `active`, as
+    it always has — that is an explicit re-registration, not a read normalizing a value.)
+  - `--no-wake` changed meaning without changing its flag: previously _no turn, brief auto-loaded_; now
+    _no turn and brief unread on disk_. A caller driving the first turn itself must convey the path.
+
+  Supersedes ADR-0027; see ADR-0032.
+
+  Note for readers of the 0.2.0 entry: it describes the first-turn doorbell as waking a peer
+  whose "brief is injected into context by its own SessionStart hook". That was accurate when it
+  shipped and is what this release retires — the hook injects no brief, and the wake names the file.
+
+## 0.2.0
+
+### Minor Changes
+
+- 211de72: **BREAKING** — `unit spawn --at` now defaults to `tab` instead of `pane:right`, and the redundant
+  `window` placement value is removed.
+  - **Default placement is `tab`.** A spawned peer opens as a new tab in the caller's current window,
+    opened without stealing focus (herdr `tab create --no-focus`, tmux `new-window -d`), so it no
+    longer shrinks the caller's pane by splitting it side-by-side. Pass `--at pane:right` explicitly
+    for the old behavior.
+  - **herdr now honors `tab`.** The herdr adapter previously mis-routed `tab` to a right-split pane;
+    it now opens a real herdr tab via `tab create`. tmux already mapped `tab` → `new-window`.
+  - **`window` is removed** from `--at`. It was tmux's local name for the Tab concept, redundant with
+    `tab`; the allowed set is now `pane:right | pane:down | tab | workspace`. `--at window` is
+    rejected. Placement vocabulary is aligned to the canonical Session › Workspace › Tab › Pane
+    concepts (documented in the mux node README and the website architecture page).
+
+- ddb1458: **BREAKING** — realign the CLI to its real architecture (ADR-0024). Command groups now mirror the
+  mux/legion layering instead of the retired `surfacing`/`wake` concept axis:
+  - `identity <verb>` and `session <verb>` collapse into one **`unit`** group: `unit register`,
+    `unit whoami`, `unit who` (now carries a `pane` field and a `"N units"` aggregate — the old
+    `session list` folded in), `unit prune`, `unit spawn`, `unit close`, `unit focus`, `unit nudge`,
+    `unit read`.
+  - `identity owner` → **`unit register --standing`** (bare, no `--handle`, lists the standing records).
+  - `identity bind-main` / `identity main` → **`attach`** (bare binds; `--clear` unbinds; `--show`
+    reads the bound pane).
+  - `admin doctor` / `admin mode` → **`mux doctor`** / **`mux mode`**.
+  - `admin install` folds into **`init`** (which owns hook installation directly); `admin` now carries
+    only `migrate`.
+
+  Hot-path top-level aliases (`who`, `send`, `inbox`, `spawn`) and the bare-status default action are
+  unchanged. `mail`, `agent`, and `dispatch` are unchanged.
+
+- b863089: **BREAKING** — dissolve the CLI's `dispatch` command group, `Store` result-slot
+  (`resultPath`/`writeResult`/`readResult`), and `realizeSubagentInstruction`/`selectWakePath` library
+  exports. A cold subagent now returns via the caller's own Task-result (its final returned message)
+  instead of a `dispatch prep`/collect result file, and a warm peer returns via `mail await` on a
+  thread instead of `dispatch channel`. Routing (warm-peer vs subagent vs run-inline) and the
+  wake-matrix decision move out of the CLI into the Legate plugin's governance
+  (`dispatch-governance`/`subagent-backend-governance`), which now composes `unit spawn` + `mail
+await` + `agent resolve` directly. Verdict-schema validation is dropped for now, to return later as
+  a dedicated `mail --verdict-schema` capability.
+- 59b4154: **BREAKING** — the multiplexer fast-path environment variables are renamed, and the multiplexer
+  layer is now the `cyber-mux` package rather than a copy of it carried here.
+  - **`$CYBERLEGION_MUX` / `$CYBERLEGION_MUX_PANE` become `$CYBER_MUX` / `$CYBER_MUX_PANE`.**
+    `mux doctor` now prints `export CYBER_MUX=<m> CYBER_MUX_PANE=<p>`, and `unit spawn` injects the
+    new names into the pane it opens. **The old pair is still read**, but only when the new pair is
+    absent, so a session that was already running when you upgrade keeps its identity instead of
+    falling back to a process-tree walk that answers for a different pane. That fallback is
+    transitional and will be removed — re-pin anything that sets these names by hand.
+  - **`cyber-mux` is now a dependency** (pinned exact). `packages/cyberlegion/src/console/` had been a
+    fork of that package's source since the extraction, and the two had drifted with the package
+    moving and the copy standing still. Every improvement landed upstream since was invisible here.
+  - **A detected multiplexer that a unit record cannot name is now refused, by name, before anything
+    opens.** `cyber-mux` drives four backends; a unit's pane pointer can only be stored for tmux and
+    herdr. Previously such an environment reported that no multiplexer was running, which was a lie
+    when you were plainly inside one; opening there would have stranded a live session that `unit
+prune` could never reap and no caller could reach.
+  - **A `--at pane:right` / `pane:down` spawn now splits the calling pane.** Both backends default to
+    splitting the pane a _human_ is looking at, which matches the caller's only by coincidence and
+    diverges exactly when a program is driving — which `unit spawn` always is.
+
+  Library consumers: the re-exported multiplexer types are now `cyber-mux`'s (`MuxAdapter`,
+  `MuxTarget`, `MuxPlacement`), and `send` is `sendText`. Note that `sendText` types text **without**
+  submitting it; `submit(target, text)` is the equivalent of the old `send`.
+
+- 7ed73d0: Owner-mail doorbell rings the bound main pane only when it is focused.
+  - **New focus probe.** `SessionAdapter.isPaneFocused` reports whether the attached client is currently viewing a pane — tri-state `focused | not-focused | unknown`. tmux reads `pane_active` + `window_active` + `session_attached`; herdr reads the pane record's own `focused` flag (`pane get`). A backend that cannot report focus, or a query that errors, answers `unknown`.
+  - **Doorbell focus gate.** When a standing-owner message is delivered, the doorbell now skips ringing the bound main pane if that pane is **positively not focused** — the human has roamed off it, so ringing would wake a session nobody is watching. The report stays queued in the durable owner inbox and surfaces on the pane's next SessionStart pull; nothing is lost. When the pane is focused, or focus is `unknown`, the ring proceeds as before (fail-open, no regression). A peer recipient's ring is never focus-gated, and a focus probe that errors never fails the send.
+
+- da6935a: Add `cyberlegion mail read <id> --ack` — read and acknowledge a message in one atomic step. It
+  prints the message body (as `read` does) and acks it in the same call, so "receive and consume" is
+  one round-trip instead of read-then-separately-ack. It is idempotent: it always prints the body and
+  acks only when the message is still unread, so running it on an already-acked message prints the
+  body and succeeds (`acked: false`) rather than erroring like a bare `mail ack`. An unknown message
+  id still errors, and it composes with `--owner` for the standing owner mailbox. Bare `mail read`
+  (no `--ack`) is unchanged — it stays the non-consuming peek.
+- 7598bf5: `unit who --reconcile` (and top-level `who --reconcile`) now also adopts live-but-unregistered panes: any live pane in the current multiplexer running a detectable harness (`claude | cursor | codex`) with no matching record gets a minted record — pane bound to a new id, handle derived from the pane's cwd basename (`id.slice(0, 6)` when no cwd is reported), status `active`, `lastSeen` now — so a manually-opened or hook-failed pane becomes listable, mailable, and dispatchable. Panes with no detectable harness are never adopted (herdr reports the running agent; tmux does not, so tmux adoption is deferred), a bound pane — exited included — is never re-adopted or resurrected, and `unit prune` stays cull-only.
+- 0988b81: Add `unit who --reconcile` (and top-level `who --reconcile`, mirroring `--all`) to live-probe the current multiplexer and mark any dead-pane record `exited` before listing. `unit prune` now reconcile-culls the same way in addition to its existing per-record liveness and staleness checks.
+- 38756f9: `unit spawn` now delivers the spawned peer's **first turn** on a fresh paned session, so a spawned
+  pod acts on its brief with no human nudge (issue #188).
+
+  A paned agent boots to an idle prompt: its brief is injected into context by its own SessionStart
+  hook, but the model takes no turn on its own (unlike a subagent, where the caller's Task call _is_
+  the turn). So `unit spawn` now rings a best-effort **first-turn doorbell** over the same boot-race-
+  aware submit-verify path `unit nudge` uses, exactly mirroring `mail send`'s delivery ring: the
+  worktree/session/registry record is the guaranteed effect and the ring is opportunistic on top.
+  - **Best-effort, never fails the spawn.** A ring that never completes within the retry budget (the
+    harness never reaches its prompt) is surfaced as a stderr warning; the peer is still spawned. The
+    spawn result carries a `rung` field.
+  - **`--no-wake` opts out** (mirroring `mail send --no-nudge`) for a caller that will drive the first
+    turn itself.
+
+  This is mechanism, not routing — it completes the spawn, it does not select a backend — so it stays
+  within the CLI's dumb-hands charter and fixes every paned caller at once (Operator, Pod, and the
+  Legate's `channel` dispatch strategy) with no persona change.
+
+- 59c951c: `unit spawn --at workspace` now opens the unit's own space under a short, human-identifiable name
+  instead of the backend's default, so a session is findable by eye rather than by reading every
+  workspace.
+
+  The name is `<code>-<subject>`, capped at 30 characters including the code.
+  - **Code** — a NieR YoRHa unit class read off the brief's leading action word in one fixed order:
+    `A2-` when the action tears down or reverts, else `9S-` when it is read-only recon (investigate,
+    audit, review, diagnose and kin), else `2B-`, the build-and-change class and the default when the
+    leading word matches no action at all. The same brief always yields the same code.
+  - **Subject** — `--handle` when given, otherwise the brief's first non-empty line: lowercased, a
+    recognized action word and any leading article dropped, non-alphanumerics collapsed to `-`, then
+    whole words taken while they fit, so the name ends on a complete word. A brief that yields nothing
+    usable falls back to the unit's own 6-character short id.
+
+  Only a `workspace` placement is named. A `pane:*` or `tab` placement opens into a space the caller is
+  already in, so it carries no name and never renames that space.
+
+  Examples: `--task "add a retry budget to the mail poller"` → `2B-retry-budget-to-the-mail`;
+  `--task "prune the stale pane index"` → `A2-stale-pane-index`; `--task "diagnose the boot race"
+--handle scribe` → `9S-scribe`.
+
+- 9955e97: Bind a standing owner's **presence** — the live unit standing in for it — and ring it on delivery.
+
+  A standing owner record (`unit register --standing`) is durable but has no session of its own, so it
+  cannot take a turn. It now carries a presence pointer:
+  - **`unit claim <handle>`** binds the caller's unit as that standing owner's presence — a
+    per-record singleton, last-claim-wins, so the pointer moves as the principal moves between units.
+    `--clear` unbinds, `--show` reads. An unknown handle fails loud and never auto-mints: `--clear` is
+    forgiving about _nothing being bound_, never about _the owner not existing_, so a typo'd handle
+    can't report a clear it never performed.
+  - **The claim is gated on spawn capability** — it probes the multiplexer and throws when there is
+    none (no panes ⇒ no dispatch ⇒ no presence), leaving the pointer untouched. The gate is a
+    checkable precondition, never an introspective carve-out about what kind of agent is asking: a
+    caller in a real pane can spawn and may hold the presence; a pane-less one cannot, however it was
+    realized.
+  - **A presence resolves live-only** — a presence whose unit has exited reads as no presence bound,
+    so the pointer can never name a reader that isn't there.
+  - **`mail send` rings a bound live presence unconditionally**, falling back to the focus-gated bound
+    main pane when none is bound. A presence is an agent expected to take the turn, not a human whose
+    attention is the scarce resource, so it inherits the existing peer rule rather than the
+    human-attention focus gate — which matters precisely because a presence exists to act on a
+    delivery while the human is away.
+
+  Additive: with no presence bound, the standing-owner ring and its focus gate behave exactly as
+  before.
+
+### Patch Changes
+
+- 9df2bf4: Address live units only, and fail fast on a dead pane.
+
+  A handle is reusable, so over time the dead units holding a name outnumber the live one.
+  `resolveRecipient`/`resolveAgent` matched on handle without filtering status, so a name could
+  resolve to an exited unit — `mail send` then reported "delivered" for an inbox with no reader.
+  Handles (and worktree-branch refs) now resolve to live units only, and a name matching only exited
+  units throws and lists them. An explicit id still addresses an exited unit.
+
+  `nudge` now probes `paneExists` before sending: a gone pane and a booting one both read back empty,
+  so a dead peer was being retried ten times and reported as "never took the turn" — the boot-race
+  shape — instead of the real cause.
+
+## 0.1.0
+
+### Minor Changes
+
+- 667163c: Add a `workspace` value to `session spawn --at` (and `dispatch channel --at`) that opens a genuinely new workspace/session instead of a pane inside the caller's current one. Under herdr this also creates the new worktree via `herdr worktree create`, so it lands properly nested under its source workspace instead of just adding to the caller's own pane count; under tmux it opens a new detached session.
+- 2758ea9: Add the owner mailbox read path. `mail hook` now surfaces every standing owner's unread mail
+  (with bodies) into a root session's injected context under a distinct `## Owner mail — <handle>
+(<N>)` heading — read-only, so a message keeps re-surfacing until explicitly acked; a session
+  that was legion-spawned (has `spawnedBy`) never gets an owner section. `mail inbox`, `mail read`,
+  and `mail ack` take a new `--owner <handle>` selector that targets a standing owner's mailbox
+  instead of the caller's own; `--owner` on a handle that is not a standing record errors rather
+  than falling back to reading a session's inbox as an owner mailbox.
+- 9e24386: Add `identity owner --handle <name>` to mint a standing, session-independent owner inbox — a durable recipient identity with no live session, tmux pane, or harness. Standing records are exempt from `prune` staleness checks, are listed by `who`, and take precedence over a live session when a handle is shared. Bare `identity owner` lists existing standing records.
+
+### Patch Changes
+
+- 667163c: Fix `session spawn`'s default worktree checkout location: it now lives as a sibling of the primary checkout (`<repo>.worktrees/legion-<id>`) instead of nested inside `<primary>/.agents/cyberlegion/worktrees/`, which polluted `git status` in the primary checkout and confused tooling that walks the tree recursively. The directory name uses the same 6-character id slice the peer's `handle` already defaults to.
+
+## 0.0.1
+
+### Patch Changes
+
+- 7c92d8e: Mark the CLI bin shim as executable so it runs directly after install.