cyberlegion

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 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.