cyberlegion 1.2.0 → 1.4.0

package/skills/init-cyberlegion/SKILL.md

@@ -1,13 +1,15 @@
 ---
 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."
+description: "Use this skill to set up or onboard cyberlegion in this session or repo — probe the environment, register the mail-surfacing hook, (in a root session, on your yes) allow the cyberlegion CLI in Claude Code's permissions, and 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.
+(only in a root session, only on an explicit yes) allow the `cyberlegion` CLI in Claude Code's
+permissions and bind this pane as the durable `legate` owner inbox, offering that owner a **home** to
+wake in when nobody is standing in for it.
 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*.
@@ -37,21 +39,54 @@ node scripts/cyberlegion.mjs mux doctor
 ```
 
 Run this **before** touching the hook or any identity. It reports `harness`, `mux`, `pane`,
-`hubRoot`, and `selfId` — read it to learn the environment (is there a multiplexer? a pane?) and to
-detect root vs spawned (see step 3). Narrate a short, grounded summary of what it found — do not
-invent facts the probe did not report.
+`hubRoot`, `selfId`, and `permissionRule` — read it to learn the environment (is there a
+multiplexer? a pane? does Claude Code allow the CLI?) and to detect root vs spawned (see step 3).
+Narrate a short, grounded summary of what it found, including the permission rule (e.g. "permission
+rule: missing") — do not invent facts the probe did not report.
 
-### 2. Register the surfacing hook
+`permissionRule` is whether Claude Code's user settings carry a `permissions.allow` rule covering
+`cyberlegion`: `present`, `missing`, `unreadable`, or `n/a` (not Claude Code). Without it, Claude
+Code's auto-mode classifier can deny a unit's `cyberlegion mail send` as *External System Writes*,
+so a unit that finished its work cannot report back. Step 2 handles it.
+
+### 2. Register the surfacing hook (and, on a yes, allow the CLI)
 
 ```bash
 node scripts/cyberlegion.mjs init --pin <version>
 ```
 
+**The permission rule — ask first, never silent.** When the probe reported `permissionRule: missing`
+in a **root** session with a broader onboarding intent (see step 3 for how root is derived), ask
+before running `init`, e.g.:
+
+> "Claude Code has no permission rule for `cyberlegion`, so its auto-mode classifier can block a
+> unit's `cyberlegion mail send` and the unit's report never reaches you. Add
+> `Bash(cyberlegion *)` to `permissions.allow` in your Claude Code user settings
+> (`~/.claude/settings.json`)? It is merged into your existing list."
+
+On an explicit yes, add `--allow-cli` to the `init` call — the CLI merges the rule into the existing
+array, never replaces it, and refuses to rewrite a settings file it cannot parse:
+
+```bash
+node scripts/cyberlegion.mjs init --pin <version> --allow-cli
+```
+
+On a decline, run `init` without `--allow-cli` and say the rule stays missing. Never edit the
+settings file by hand. Do not ask, and do not pass `--allow-cli`, when:
+
+- the rule is `present` or `n/a` — nothing to do;
+- the rule is `unreadable` — tell the user the settings file could not be parsed and must be fixed
+  by hand; `--allow-cli` would refuse it;
+- this is a **spawned** unit — it never changes the user's global settings; report the rule as
+  missing in its result so the human can run this skill from a root session;
+- the request is hook-only — report the rule's state and stop (see step 3).
+
 Pass `--pin <version>` with the version resolved above so a project hook's npx fallback fetches the
 shipped version; **omit `--pin`** when the map yielded no version.
 
 Auto-detect is the default — no `--agent` flag. Pass `--agent <name>` **only** when `mux doctor` could
-not auto-detect the harness, or the user named one explicitly (it composes with `--pin`):
+not auto-detect the harness, or the user named one explicitly (it composes with `--pin` and
+`--allow-cli`):
 
 ```bash
 node scripts/cyberlegion.mjs init --pin <version> --agent <name>
@@ -60,7 +95,9 @@ node scripts/cyberlegion.mjs init --pin <version> --agent <name>
 This step is **idempotent**: if the hook is already registered, `init` reports `already present` —
 that is a clean no-op, never a duplicate registration and never an error. On Claude Code and Codex the
 plugin ships the hook itself, so `init` reports `provided by plugin` (or `removed project hook` when it
-cleared one an earlier `init` wrote); both mean the hook is set up.
+cleared one an earlier `init` wrote); both mean the hook is set up. On Claude Code its summary also
+reports `permission rule <state>` — `added` after `--allow-cli`, `present` when a covering rule was
+already there.
 
 ### 3. Detect root vs spawned — derived, never asked
 
@@ -72,7 +109,18 @@ has it set. Derive this from the probe — never ask the user to declare it.
 - **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.
+- **Root session where a `legate` owner is already bound** — do not re-ask the bind and do not mint a
+  second owner; go to step 6 to offer a home. A bind request ("make this pane my main legion inbox")
+  made when the owner already exists lands here too.
+
+To tell whether the owner exists, list the standing owners:
+
+```bash
+node scripts/cyberlegion.mjs unit register --standing --format json
+```
+
+A record with `"handle": "legate"` is the owner. Its `home` field says where its presence is
+spawned (`dir` plus `harness` or `agent`); no `home` field means it has none.
 
 ### 4. Ask before binding — never silent
 
@@ -85,27 +133,105 @@ Only a root session with no `legate` owner bound is offered the bind. Ask plainl
 - **User agrees explicitly** — proceed to step 5.
 - **Already bound** — never reach this ask (see step 3).
 
-### 5. On an explicit yes — mint and bind
+### 5. On an explicit yes — offer a home, then mint and bind
+
+**No multiplexer or pane in the probe** → skip the home: mint bare and continue (see *Non-mux parity*
+below). `unit claim` refuses a caller with no multiplexer, and a home is spawned the same way
+`unit spawn` opens a session.
+
+Otherwise, before minting, explain the presence and ask for a home. Mail to the `legate` owner
+reaches whoever stands in for it, in this order:
+
+1. **A live presence** — a session that ran `unit claim legate`. The claim holds until another
+   session claims the owner, until `unit claim legate --clear` unbinds it, or until that session
+   exits.
+2. **The home** — when nobody holds the presence, a session is started in the home folder, bound as
+   the presence, and woken to read the owner's inbox. A home **outranks this pane**: with a home set,
+   a delivery with no live presence starts a session there instead of ringing the pane `attach` binds.
+   Say this in the question: setting a home means unclaimed mail no longer rings this pane.
+3. **This pane** (`attach`) — rung only when focused, when there is neither a presence nor a home.
+
+Ask plainly, e.g.:
+
+> "Should the legate owner have a home — a folder where a session is started to act for it when
+> mail arrives and nobody is live? While you're here, `cyberlegion unit claim legate` makes this
+> session the one that gets the mail, until another session claims it, you run
+> `unit claim legate --clear`, or this one exits; the home is only used when nobody holds it — and
+> once it is set, mail nobody holds starts a session there instead of ringing this pane.
+> A session started there has the folder's trust prompt accepted for it, since you named the
+> folder. Name a folder, or say none."
+
+**A folder** → mint with the home and **exactly one** launch:
+
+```bash
+node scripts/cyberlegion.mjs unit register --standing --handle legate --home <dir> --harness <harness>
+node scripts/cyberlegion.mjs attach
+```
+
+`<harness>` is the `harness` the probe reported, or the one the user names instead — one of
+`claude`, `cursor`, or `codex`. When the user
+names an agent definition to launch there, pass `--agent <definition>` and **no** `--harness`. This
+`--agent` is `unit register`'s — an agent definition resolved from the home — not `init --agent`.
+If the probe reported `harness: unknown` and the user named no agent definition, ask for one — never
+run `--home` without a launch, and never pass `--harness unknown`. Pass `<dir>` as an absolute path.
+
+**None** → mint bare, as before:
 
 ```bash
 node scripts/cyberlegion.mjs unit register --standing --handle legate
 node scripts/cyberlegion.mjs attach
 ```
 
-Run these **in this order** and only after the explicit yes: mint the durable, session-independent
-`legate` owner inbox first, then bind the current pane as that owner's live presence.
+Run the mint and `attach` **in this order** and only after the explicit yes: mint the durable,
+session-independent `legate` owner inbox first, then bind the current pane as the owner's main pane.
+
+**The CLI refuses a home** (the folder does not exist, it is a repository's primary checkout, the
+agent definition does not resolve from it) — it writes nothing. Tell the user its reason and ask for
+another folder or none; do not pick a folder yourself and do not fall back to a bare mint unasked.
+If it rejects `--home` as an unknown option, the CLI is older than homes: say so, and mint bare only
+if the user agrees. On a decline, mint nothing and skip `attach`; the hook stays.
 
 **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.
 
+### 6. An owner already minted — add or drop a home
+
+Reached only from step 3, in a root session with a broader onboarding intent, when `legate` is
+already minted. Never re-ask the bind and never run `attach` here. Re-registering a standing owner
+refreshes the same record — the same id, its bound presence kept — so it is not a second mint.
+
+With no multiplexer or pane in the probe, offer nothing here — neither adding nor dropping a home.
+
+- **No home** — explain the presence and the trust-prompt acceptance as in step 5 and offer to give the owner one. On a folder, run
+  `unit register --standing --handle legate --home <dir>` with exactly one of `--harness` /
+  `--agent`, exactly as in step 5; a refusal is handled the same way.
+  If the CLI rejects `--home` (or `--clear-home`) as an unknown option, say it predates homes and
+  change nothing.
+- **A home** — name its folder and offer to drop it. On a yes:
+
+  ```bash
+  node scripts/cyberlegion.mjs unit register --standing --handle legate --clear-home
+  ```
+
+- **A decline** — run nothing.
+
+## Troubleshooting
+
+**A unit's `cyberlegion mail send` was denied by the auto-mode classifier** (*Permission for this
+action was denied by the Claude Code auto mode classifier. Reason: [External System Writes]*) — the
+`Bash(cyberlegion *)` permission rule is missing. Run this skill from a root session and say yes to
+the permission ask, or run `cyberlegion init --allow-cli` there.
+
 ## 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`
+- Every mechanic here is a `cyberlegion` CLI call — this skill writes no hub state, invents no
+  config format, and never edits Claude Code's settings by hand (the permission rule goes in only
+  through `init --allow-cli`, only on an explicit yes in a root session). 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 never mints or binds an owner identity without an explicit user yes, and never sets or drops
+  an owner's home except on a folder or a drop the user named.
 - 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

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

@@ -11,7 +11,7 @@ import { spawnSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 
-const FALLBACK = 'npx -y cyberlegion@1.2.0'
+const FALLBACK = 'npx -y cyberlegion@1.4.0'
 const bin = new URL('../../../bin/cyberlegion.mjs', import.meta.url)
 
 if (existsSync(fileURLToPath(bin))) {

package/skills/legate/SKILL.md

@@ -13,7 +13,7 @@ logic, loads no other governance, and writes no state of its own.
 > **Running the CLI.** Every `node scripts/cyberlegion.mjs …` command below runs the `cyberlegion` CLI
 > this plugin ships. The path is relative to this skill's own directory, not the working directory.
 > If you cannot resolve it, run the published CLI of the version that shipped this skill instead,
-> with the same arguments: `npx -y cyberlegion@1.2.0`.
+> with the same arguments: `npx -y cyberlegion@1.4.0`.
 
 ## Doorbell vs mailbox
 

package/skills/legate/scripts/cyberlegion.mjs

@@ -11,7 +11,7 @@ import { spawnSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 
-const FALLBACK = 'npx -y cyberlegion@1.2.0'
+const FALLBACK = 'npx -y cyberlegion@1.4.0'
 const bin = new URL('../../../bin/cyberlegion.mjs', import.meta.url)
 
 if (existsSync(fileURLToPath(bin))) {

package/skills/manage-inbox/SKILL.md

@@ -13,7 +13,7 @@ the one owner mailbox from wherever they are.
 > **Running the CLI.** Every `node scripts/cyberlegion.mjs …` command below runs the `cyberlegion` CLI
 > this plugin ships. The path is relative to this skill's own directory, not the working directory.
 > If you cannot resolve it, run the published CLI of the version that shipped this skill instead,
-> with the same arguments: `npx -y cyberlegion@1.2.0`.
+> with the same arguments: `npx -y cyberlegion@1.4.0`.
 
 ## Resolve the owner handle
 

package/skills/manage-inbox/scripts/cyberlegion.mjs

@@ -11,7 +11,7 @@ import { spawnSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 
-const FALLBACK = 'npx -y cyberlegion@1.2.0'
+const FALLBACK = 'npx -y cyberlegion@1.4.0'
 const bin = new URL('../../../bin/cyberlegion.mjs', import.meta.url)
 
 if (existsSync(fileURLToPath(bin))) {

package/skills/relay-governance/SKILL.md

@@ -15,7 +15,7 @@ agent (`headless-legate`, `sdd-automaton`, the cold judges) to know how *it* rep
 > **Running the CLI.** Every `node scripts/cyberlegion.mjs …` command below runs the `cyberlegion` CLI
 > this plugin ships. The path is relative to this skill's own directory, not the working directory.
 > If you cannot resolve it, run the published CLI of the version that shipped this skill instead,
-> with the same arguments: `npx -y cyberlegion@1.2.0`.
+> with the same arguments: `npx -y cyberlegion@1.4.0`.
 
 ## The one probe: who, if anyone, collects my return?
 

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

@@ -11,7 +11,7 @@ import { spawnSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 
-const FALLBACK = 'npx -y cyberlegion@1.2.0'
+const FALLBACK = 'npx -y cyberlegion@1.4.0'
 const bin = new URL('../../../bin/cyberlegion.mjs', import.meta.url)
 
 if (existsSync(fileURLToPath(bin))) {

package/skills/subagent-backend-governance/SKILL.md

@@ -14,7 +14,7 @@ the unit's **role** — see *Mid-turn messaging is scoped by role*, below.
 > **Running the CLI.** Every `node scripts/cyberlegion.mjs …` command below runs the `cyberlegion` CLI
 > this plugin ships. The path is relative to this skill's own directory, not the working directory.
 > If you cannot resolve it, run the published CLI of the version that shipped this skill instead,
-> with the same arguments: `npx -y cyberlegion@1.2.0`.
+> with the same arguments: `npx -y cyberlegion@1.4.0`.
 
 ## 1. Resolve the agent def
 

package/skills/subagent-backend-governance/scripts/cyberlegion.mjs

@@ -11,7 +11,7 @@ import { spawnSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 
-const FALLBACK = 'npx -y cyberlegion@1.2.0'
+const FALLBACK = 'npx -y cyberlegion@1.4.0'
 const bin = new URL('../../../bin/cyberlegion.mjs', import.meta.url)
 
 if (existsSync(fileURLToPath(bin))) {