cyberlegion 0.4.0 → 0.5.0

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { callerPane, currentPane, herdrMuxAdapter, nodeExec, nudge, probeMultiplexer, probeMultiplexer as probeMultiplexer$1, tmuxMuxAdapter } from "cyber-mux";
 import { assertDistinctFromPrimary, assertDistinctFromPrimary as assertDistinctFromPrimary$1, gitWorktreeAdapter, gitWorktreeAdapter as gitWorktreeAdapter$1, resolvePrimaryRoot, resolvePrimaryRoot as resolvePrimaryRoot$1 } from "cyber-mux/worktree";
-import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { createHash, randomBytes } from "node:crypto";
 import { execFileSync } from "node:child_process";
@@ -746,7 +746,10 @@ function spawn(ctx, input) {
 	const id = randomId();
 	const primaryRoot = resolvePrimaryRoot$1(exec);
 	const launch = input.command ?? LAUNCH_MAP[harness];
-	const fullLaunch = `${muxEnvPrefix(sessionAdapter.name)}${launch}`;
+	const launchLine = () => {
+		const shimDir = ctx.self ? writeSelfShim(paths.dataDir(ctx.store.root, id), ctx.self) : void 0;
+		return `${shimDir ? `PATH=${shellQuote$1(shimDir)}:"$PATH" ` : ""}${muxEnvPrefix(sessionAdapter.name)}${launch}`;
+	};
 	const from = callerPane(sessionAdapter, normalizedEnv);
 	let cwd;
 	let worktree;
@@ -759,7 +762,7 @@ function spawn(ctx, input) {
 		const at = input.at ?? "tab";
 		target = sessionAdapter.open(exec, {
 			cwd,
-			launch: fullLaunch,
+			launch: launchLine(),
 			at,
 			from,
 			...labelFor(at, input, brief, id)
@@ -774,7 +777,7 @@ function spawn(ctx, input) {
 				primaryRoot,
 				branch,
 				path: worktreePath,
-				launch: fullLaunch,
+				launch: launchLine(),
 				...labelFor(at, input, brief, id)
 			});
 			assertDistinctFromPrimary$1(opened.worktree.root, primaryRoot);
@@ -794,7 +797,7 @@ function spawn(ctx, input) {
 			worktree = added;
 			target = sessionAdapter.open(exec, {
 				cwd,
-				launch: fullLaunch,
+				launch: launchLine(),
 				at,
 				from,
 				...labelFor(at, input, brief, id)
@@ -821,7 +824,7 @@ function spawn(ctx, input) {
 	};
 	saveAgent(ctx.store, rec);
 	ctx.store.putPaneIndex(target.id, id);
-	ctx.store.writeBrief(id, brief);
+	ctx.store.writeBrief(id, composeBrief(brief, input.briefInstructions));
 	return {
 		agent: rec,
 		pane: target.id,
@@ -888,6 +891,31 @@ function muxEnvPrefix(muxName) {
 	if (muxName === "herdr") return "CYBER_MUX=herdr ";
 	return "";
 }
+/**
+* Write `<dataDir>/bin/cyberlegion`, a POSIX shim that execs `self` with the caller's arguments,
+* and return its directory. A spawned session gets that directory first on its PATH, so the
+* `cyberlegion` a brief tells it to run is the install that spawned it: nothing is resolved from
+* the registry or the session's own PATH at report time.
+*/
+function writeSelfShim(dataDir, self) {
+	const dir = join(dataDir, "bin");
+	mkdirSync(dir, { recursive: true });
+	const shim = join(dir, "cyberlegion");
+	writeFileSync(shim, `#!/bin/sh\nexec ${self.map(shellQuote$1).join(" ")} "$@"\n`);
+	chmodSync(shim, 493);
+	return dir;
+}
+/** Single-quote `s` for a POSIX shell, so any path survives word splitting and expansion. */
+function shellQuote$1(s) {
+	return `'${s.replaceAll("'", "'\\''")}'`;
+}
+/** The brief file's text: the task alone, or — when the harness took no instructions on its command
+* line — the def's instructions under their own heading ahead of it, so the peer can see they reach
+* it as a user turn rather than a system prompt. */
+function composeBrief(brief, instructions) {
+	if (!instructions) return brief;
+	return `## Agent instructions\n\n${instructions}\n\n## Brief\n\n${brief}`;
+}
 /** Resolve a spawn brief from --brief-file, --task -, or --task <text>; null if no source given. */
 function resolveBrief(input, readStdin = () => readFileSync(0, "utf8")) {
 	if (input.briefFile) return readFileSync(input.briefFile, "utf8");
@@ -955,6 +983,14 @@ function toBool(v) {
 	if (v === "true") return true;
 	if (v === "false") return false;
 }
+/** The known harnesses are exactly those with a launch binary — one home for the set. */
+const HARNESSES = Object.keys(LAUNCH_MAP);
+/** A `harness` tag outside the known set has no launch binary, so a typo fails here, loudly, rather
+* than surfacing later as an unlaunchable command. */
+function toHarness(value, path) {
+	if (value === void 0 || HARNESSES.includes(value)) return value;
+	throw new Error(`agent def "${path}" has unknown harness "${value}" — expected one of ${HARNESSES.join(", ")}`);
+}
 function toAgentDef(path, text, fallbackName) {
 	const { fm, instructions } = parseAgentDefFile(text);
 	return {
@@ -962,7 +998,7 @@ function toAgentDef(path, text, fallbackName) {
 		description: fm.description,
 		model: fm.model,
 		effort: fm.effort,
-		harness: fm.harness,
+		harness: toHarness(fm.harness, path),
 		warm: toBool(fm.warm),
 		interactive: toBool(fm.interactive),
 		instructions,
@@ -1015,19 +1051,67 @@ const DEFAULT_HARNESS = "claude";
 function shellQuote(value) {
 	return `'${value.replace(/'/g, `'\\''`)}'`;
 }
-/** Build the harness launch invocation for a def — explicit `model`/`harness` win over the def's
-* own tags, which win over the harness default. Every harness gets the same shape (bin,
-* `--model` when known, `--append-system-prompt` carrying the def's instructions body) since the
-* exact per-harness flag surface is realized later by the launching caller, not by cyberlegion. */
+/** Cursor carries effort as a bracket parameter on the model (`<model>[effort=<level>]`): merge it into
+* any bracket list the model already has, replacing an `effort=` already there. */
+function withCursorEffort(model, effort) {
+	const open = model.lastIndexOf("[");
+	if (open === -1 || !model.endsWith("]")) return `${model}[effort=${effort}]`;
+	const params = model.slice(open + 1, -1).split(",").filter((p) => p !== "" && !p.startsWith("effort="));
+	return `${model.slice(0, open)}[${[...params, `effort=${effort}`].join(",")}]`;
+}
+/** The model + effort arguments for one harness. No two harnesses spell effort alike: claude has
+* `--effort`, codex only a config override, cursor only a parameter on the model — so a cursor
+* effort with no model has nowhere to go and throws rather than launching at the default effort. */
+function modelAndEffortArgs(harness, model, effort) {
+	if (harness === "cursor") {
+		if (effort && !model) throw new Error(`cursor carries effort only as a parameter on the model; set a model to launch with effort "${effort}"`);
+		if (!model) return [];
+		return ["--model", shellQuote(effort ? withCursorEffort(model, effort) : model)];
+	}
+	const args = model ? ["--model", shellQuote(model)] : [];
+	if (!effort) return args;
+	if (harness === "codex") return [
+		...args,
+		"-c",
+		shellQuote(`model_reasoning_effort="${effort}"`)
+	];
+	return [
+		...args,
+		"--effort",
+		shellQuote(effort)
+	];
+}
+/** A TOML basic string: JSON's escapes are all legal TOML escapes, and TOML also forbids a raw DEL. */
+function tomlBasicString(value) {
+	return JSON.stringify(value).replace(/\x7f/g, "\\u007f");
+}
+/** The instruction arguments for one harness. Only claude has an append-to-system-prompt flag;
+* codex takes a `developer_instructions` config override, added on top of its own base
+* instructions. Cursor has no channel at all — its instructions go to the brief instead. */
+function instructionArgs(harness, instructions) {
+	if (!instructions || harness === "cursor") return [];
+	if (harness === "claude") return ["--append-system-prompt", shellQuote(instructions)];
+	return ["-c", shellQuote(`developer_instructions=${tomlBasicString(instructions)}`)];
+}
+/** Build the harness launch invocation for a def — explicit `model`/`effort`/`harness` win over the
+* def's own tags, which win over the harness default. The def's effort and instructions each go
+* through the harness's own control (see `modelAndEffortArgs`, `instructionArgs`). */
 function realizeLaunch(def, opts = {}) {
 	const harness = opts.harness ?? def.harness ?? DEFAULT_HARNESS;
 	const model = opts.model ?? def.model;
-	const parts = [LAUNCH_MAP[harness]];
-	if (model) parts.push("--model", shellQuote(model));
-	if (def.instructions) parts.push("--append-system-prompt", shellQuote(def.instructions));
+	const effort = opts.effort ?? def.effort;
+	const parts = [
+		LAUNCH_MAP[harness],
+		...modelAndEffortArgs(harness, model, effort),
+		...instructionArgs(harness, def.instructions)
+	];
+	const briefInstructions = harness === "cursor" && def.instructions ? def.instructions : void 0;
 	return {
 		harness,
-		command: parts.join(" ")
+		command: parts.join(" "),
+		model,
+		effort,
+		...briefInstructions ? { briefInstructions } : {}
 	};
 }
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cyberlegion",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Harness-agnostic agent session spawning and messaging over the filesystem",
   "keywords": [
     "agent",
@@ -44,6 +44,7 @@
   },
   "devDependencies": {
     "@types/node": "^24.10.1",
+    "smol-toml": "^1.8.0",
     "tsdown": "^0.22.0",
     "tsx": "^4.22.3",
     "typescript": "^7.0.2",
@@ -59,7 +60,7 @@
   "scripts": {
     "build": "tsdown",
     "check:metaphor-free": "tsx src/check-metaphor-free.ts",
-    "dev": "tsx src/cli.ts",
+    "dev": "tsx src/dev.ts",
     "test": "vitest run src",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit"

package/plugin.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
 	"name": "cyberlegion",
-	"version": "0.4.0",
+	"version": "0.5.0",
 	"description": "Agent session spawning, messaging, and dispatch — the Legion and its Legate.",
 	"author": {
 		"name": "unional"

package/readme.md

@@ -154,9 +154,12 @@ npx skills add cyberuni/cyberplace --plugin cyberlegion --global
 
 This package doubles as the plugin root: `plugin.json`, the generated `.claude-plugin/` and
 `.codex-plugin/` manifests, `skills/`, and `agents/` all ship in the npm tarball. The bundle
-carries the version it was built against in `.plugin/pins.json`, and its skills read that pin to invoke `npx cyberlegion@<version> …` rather than inventing a version. In a
-workspace checkout with no bundled pin, they fall back to the unpinned `npx cyberlegion …` form or
-the local bin (`packages/cyberlegion/bin/cyberlegion.mjs`).
+Each skill that runs the CLI carries a launcher, `scripts/cyberlegion.mjs`, that runs the CLI
+shipped in this same package (`bin/cyberlegion.mjs` over the committed `dist/cli.mjs`), so a skill
+never fetches a copy through npx and always runs the version its own text describes. Where the
+launcher cannot be resolved, a skill names one fallback pinned to the version that shipped it,
+`npx -y cyberlegion@<version>`. `pnpm version` rewrites those pins and `.plugin/pins.json` at every
+release, and the test suite fails on a stale one.
 
 ## License
 

package/skills/dispatch-governance/SKILL.md

@@ -14,10 +14,15 @@ realized headless by the `headless-legate` agent. Both loads run the exact same
 **Input:** an intent to fulfill role `R` with brief `B`, optionally expecting a result that
 satisfies verdict schema `V`.
 
+> **Running the CLI.** Every `node scripts/cyberlegion.mjs …` command below runs the `cyberlegion` CLI
+> this plugin ships. The path is relative to this skill's own directory, not the working directory.
+> If you cannot resolve it, run the published CLI of the version that shipped this skill instead,
+> with the same arguments: `npx -y cyberlegion@0.5.0`.
+
 ## 1. Resolve the agent definition
 
 ```bash
-npx cyberlegion@0.3.1 agent resolve <R> --format json
+node scripts/cyberlegion.mjs agent resolve <R> --format json
 ```
 
 Read `model`, `effort`, `harness`, `warm`, `interactive` off the resolved def. `warm` marks a role
@@ -27,7 +32,7 @@ may need to grill the caller or converse over multiple rounds, not just return o
 ## 2. Probe the environment
 
 ```bash
-npx cyberlegion@0.3.1 mux doctor --format json
+node scripts/cyberlegion.mjs mux doctor --format json
 ```
 
 Read whether a multiplexer was ancestry-discovered (tmux/herdr) — a **channel** strategy needs one
@@ -48,8 +53,8 @@ to open a pane in; its absence rules that strategy out regardless of what the ag
   mint a thread id, weave it (and an instruction to reply on it) into brief `B`, then:
 
   ```bash
-  npx cyberlegion@0.3.1 unit spawn --agent <R> --brief-file <B> --at <placement>
-  npx cyberlegion@0.3.1 mail await --thread <the-minted-thread-id> [--timeout <ms>] [--max-wait <s>]
+  node scripts/cyberlegion.mjs unit spawn --agent <R> --brief-file <B> --at <placement>
+  node scripts/cyberlegion.mjs mail await --thread <the-minted-thread-id> [--timeout <ms>] [--max-wait <s>]
   ```
 
   `unit spawn` launches the peer (its brief tells it what thread to reply on); `mail await` then

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

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

package/skills/init-cyberlegion/SKILL.md

@@ -12,26 +12,28 @@ It is a **thin wrapper**: every mechanic is a `cyberlegion` CLI call. The skill
 and the judgment* — is this a root session? should we ask to bind? what does the environment look
 like? — the CLI holds all the *mechanism*.
 
+> **Running the CLI.** Every `node scripts/cyberlegion.mjs …` command below runs the `cyberlegion` CLI
+> this plugin ships. The path is relative to this skill's own directory, not the working directory.
+>
 > **Version pin.** Resolve the CLI version **once, before the flow**, by reading the plugin's bundled
 > map at `${CLAUDE_PLUGIN_ROOT}/.plugin/pins.json` — a flat `{ "<package>": "<version>" }` map the
-> `universal-plugin bundle` step emits at release time. Look up the `cyberlegion` key:
+> release version flow keeps equal to the shipped package version. Look up the `cyberlegion` key:
 >
-> - **A version is found** → use it for every `npx cyberlegion@0.3.1 ...` call below, **and** pass
->   it to the hook registration in step 2 as `init --pin <version>` so the installed surfacing hook is
->   pinned to the same shipped version.
+> - **A version is found** → pass it to the hook registration in step 2 as `init --pin <version>`
+>   so the installed surfacing hook is pinned to the same shipped version. If you cannot resolve
+>   `scripts/cyberlegion.mjs`, run `npx -y cyberlegion@<version>` in its place, with the same arguments.
 > - **No `pins.json`, no `cyberlegion` key, or a malformed map** (an unbundled workspace checkout) →
->   fall back to the unpinned `npx cyberlegion ...` form and pass **no** `--pin`. **Never invent a
->   version number.**
+>   pass **no** `--pin`; if you cannot resolve `scripts/cyberlegion.mjs`, fall back to the unpinned
+>   `npx -y cyberlegion` form. **Never invent a version number.**
 >
-> Do not scrape the version from prose. (`legion-publish` — actually publishing `cyberlegion` to npm —
-> is a later extraction CR; until then the npx pin is dormant and the local workspace bin serves.)
+> Do not scrape the version from prose.
 
 ## Flow
 
 ### 1. Probe the environment
 
 ```bash
-npx cyberlegion@0.3.1 mux doctor
+node scripts/cyberlegion.mjs mux doctor
 ```
 
 Run this **before** touching the hook or any identity. It reports `harness`, `mux`, `pane`,
@@ -42,17 +44,17 @@ invent facts the probe did not report.
 ### 2. Register the surfacing hook
 
 ```bash
-npx cyberlegion@0.3.1 init --pin <version>
+node scripts/cyberlegion.mjs init --pin <version>
 ```
 
 Pass `--pin <version>` with the version resolved above so the installed hook is pinned to the shipped
-version; **omit `--pin`** (and use the unpinned `npx cyberlegion init`) when the map yielded no version.
+version; **omit `--pin`** when the map yielded no version.
 
 Auto-detect is the default — no `--agent` flag. Pass `--agent <name>` **only** when `mux doctor` could
 not auto-detect the harness, or the user named one explicitly (it composes with `--pin`):
 
 ```bash
-npx cyberlegion@0.3.1 init --pin <version> --agent <name>
+node scripts/cyberlegion.mjs init --pin <version> --agent <name>
 ```
 
 This step is **idempotent**: if the hook is already registered, `init` reports `already present` —
@@ -84,8 +86,8 @@ Only a root session with no `legate` owner bound is offered the bind. Ask plainl
 ### 5. On an explicit yes — mint and bind
 
 ```bash
-npx cyberlegion@0.3.1 unit register --standing --handle legate
-npx cyberlegion@0.3.1 attach
+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

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

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

package/skills/legate/SKILL.md

@@ -10,10 +10,10 @@ It **classifies** the request and either runs the matching `cyberlegion` CLI cal
 routing judgment to `dispatch-governance`. It is a **thin classifier**: it holds no production
 logic, loads no other governance, and writes no state of its own.
 
-> **Version pin.** Every invocation below reads `npx cyberlegion@0.3.1 ...` — a placeholder.
-> The package is not yet published to npm (`legion-publish` is a later CR in the extraction); until
-> then, resolve the CLI from a workspace checkout (`packages/cyberlegion/bin/cyberlegion.mjs`) or
-> whatever pinned version the project has declared. Never invent a version number.
+> **Running the CLI.** Every `node scripts/cyberlegion.mjs …` command below runs the `cyberlegion` CLI
+> this plugin ships. The path is relative to this skill's own directory, not the working directory.
+> If you cannot resolve it, run the published CLI of the version that shipped this skill instead,
+> with the same arguments: `npx -y cyberlegion@0.5.0`.
 
 ## Doorbell vs mailbox
 
@@ -27,17 +27,17 @@ mailbox because a nudge already fired.
 
 | User intent | Handling |
 |---|---|
-| Send a message to a named peer, "the pane on the right", a claude/cursor peer | `npx cyberlegion@0.3.1 mail send --to <handle>` (or `unit nudge <ref>` first if the peer needs waking, then `mail send`) |
-| Check inbox / read unread mail | `npx cyberlegion@0.3.1 mail inbox` — `mail read <msg-id>` to peek, `mail ack <msg-id>` once handled |
-| Spawn a new peer session | `npx cyberlegion@0.3.1 unit spawn --agent <name> ...` — cyberlegion owns worktree creation; pass `--cwd <dir>` only when the caller already has a directory to spawn into (e.g. reusing an existing worktree) |
-| Close / tear down a peer session | `npx cyberlegion@0.3.1 unit close <id>` |
-| Wait for a threaded reply | `npx cyberlegion@0.3.1 mail await --thread <id>` |
-| Watch mail as it streams in (observer, never acks) | `npx cyberlegion@0.3.1 mail watch` |
-| List addressable peers | `npx cyberlegion@0.3.1 unit who` |
-| Sweep dead peers | `npx cyberlegion@0.3.1 unit prune` |
+| Send a message to a named peer, "the pane on the right", a claude/cursor peer | `node scripts/cyberlegion.mjs mail send --to <handle>` (or `unit nudge <ref>` first if the peer needs waking, then `mail send`) |
+| Check inbox / read unread mail | `node scripts/cyberlegion.mjs mail inbox` — `mail read <msg-id>` to peek, `mail ack <msg-id>` once handled |
+| Spawn a new peer session | `node scripts/cyberlegion.mjs unit spawn --agent <name> ...` — cyberlegion owns worktree creation; pass `--cwd <dir>` only when the caller already has a directory to spawn into (e.g. reusing an existing worktree) |
+| Close / tear down a peer session | `node scripts/cyberlegion.mjs unit close <id>` |
+| Wait for a threaded reply | `node scripts/cyberlegion.mjs mail await --thread <id>` |
+| Watch mail as it streams in (observer, never acks) | `node scripts/cyberlegion.mjs mail watch` |
+| List addressable peers | `node scripts/cyberlegion.mjs unit who` |
+| Sweep dead peers | `node scripts/cyberlegion.mjs unit prune` |
 | Onboard / set up cyberlegion (register the surfacing hook, bind the main owner pane, first-run setup) | **invoke the `init-cyberlegion` skill** — the interactive onboarding front door over `cyberlegion init` / `unit register --standing` / `attach` |
-| Diagnose the environment (harness, multiplexer, pane, hub root) | `npx cyberlegion@0.3.1 mux doctor` |
-| Register the surfacing hook by hand (low-level, explicit harness) | `npx cyberlegion@0.3.1 init --agent <harness>` — the `init-cyberlegion` skill wraps this; use directly only when scripting a known harness |
+| Diagnose the environment (harness, multiplexer, pane, hub root) | `node scripts/cyberlegion.mjs mux doctor` |
+| Register the surfacing hook by hand (low-level, explicit harness) | `node scripts/cyberlegion.mjs init --agent <harness>` — the `init-cyberlegion` skill wraps this; use directly only when scripting a known harness |
 | Dispatch work to fulfill a role with a brief and expect a verdict back (routing judgment needed — which strategy, which agent def, warm vs cold) | **hand off to `dispatch-governance`** — do not compose `unit spawn`/`mail await`/the Task tool yourself |
 | No user channel at all (unattended trigger, multi-unit fan-out) | **spawn the `headless-legate` agent** by name — it realizes this same gateway + `dispatch-governance` flow headless |
 

package/skills/legate/scripts/cyberlegion.mjs

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

package/skills/manage-inbox/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: manage-inbox
-description: "Use this skill when the user wants to check, read, or clear the owner mailbox — the durable inbox where headless and cron-started agents send their reports. Triggers: 'check my inbox', 'any reports for me', 'what did the agents send', 'read that report', 'ack that', 'mark it read', 'clear my owner inbox', or acting on a surfaced owner-mail doorbell."
+description: "Use this skill when the user wants to check, read, or clear the owner mailbox — the durable inbox where headless and cron-started agents send their reports. Triggers: 'check my inbox', 'any reports for me', 'what did the agents send', 'read that report', 'ack that', 'mark it read', 'clear my owner inbox', answering a question an agent left in a report, or acting on a surfaced owner-mail doorbell. Not for creating or binding the owner identity (init-cyberlegion) or a session's own mail (legate)."
 ---
 
 # manage-inbox
@@ -10,27 +10,37 @@ owner identity holds, where frameless agents (cron-started, no parent frame) pus
 wraps the `cyberlegion` CLI's owner-scoped mail commands so a human roaming across sessions manages
 the one owner mailbox from wherever they are.
 
-> **Version pin.** Invocations read `npx cyberlegion@0.3.1 …` as a placeholder. Until the package
-> is published, resolve the CLI from the workspace checkout (`packages/cyberlegion/bin/cyberlegion.mjs`)
-> or the project's pinned version. Never invent a version number.
+> **Running the CLI.** Every `node scripts/cyberlegion.mjs …` command below runs the `cyberlegion` CLI
+> this plugin ships. The path is relative to this skill's own directory, not the working directory.
+> If you cannot resolve it, run the published CLI of the version that shipped this skill instead,
+> with the same arguments: `npx -y cyberlegion@0.5.0`.
 
 ## Resolve the owner handle
 
 The owner mailbox is a **standing** identity. Find it first:
 
 ```bash
-npx cyberlegion@0.3.1 unit register --standing            # lists the standing owner record(s)
+node scripts/cyberlegion.mjs unit register --standing            # lists the standing owner record(s)
 ```
 
-Use `$CYBERLEGION_OWNER` if set, else the single standing handle listed. If **no** standing owner
-exists, there is no owner mailbox yet — create one with `unit register --standing --handle <name>` (that is a
-deliberate act; do not auto-create it while just checking mail).
+Pick the handle in this order, and scope every mail command below to it with `--owner <handle>`:
+
+1. **`$CYBERLEGION_OWNER` is set** — use it as given; do not consult the standing list. If the CLI
+   answers that it is not a standing owner, report that error to the user and stop. Never retry with
+   a handle from the standing list: the variable named one owner, and a substitute is a guess.
+2. **Unset, exactly one standing owner** — use that handle without asking.
+3. **Unset, no standing owner** — tell the user there is no owner mailbox yet and stop. Do not run
+   `unit register --standing --handle` yourself: creating the owner identity is a deliberate act
+   that belongs to `init-cyberlegion`.
+4. **Unset, more than one standing owner** — stop. Run no mail command with `--owner`. List every
+   standing handle, and tell the user to set `CYBERLEGION_OWNER` to the one whose mailbox they mean.
+   Never pick one: a wrong pick shows, or acks, another owner's mail.
 
 ## List — what is waiting
 
 ```bash
-npx cyberlegion@0.3.1 mail inbox --owner <handle>            # all owner mail, oldest-first
-npx cyberlegion@0.3.1 mail inbox --owner <handle> --unread   # only what is new
+node scripts/cyberlegion.mjs mail inbox --owner <handle>            # all owner mail, oldest-first
+node scripts/cyberlegion.mjs mail inbox --owner <handle> --unread   # only what is new
 ```
 
 The aggregate line reports `<N> messages (<U> unread)`. This is a **pull** from any session — the
@@ -40,16 +50,16 @@ have seen it inline; listing is how you review deliberately.
 ## Read — peek without consuming
 
 ```bash
-npx cyberlegion@0.3.1 mail read <msg-id> --owner <handle>
+node scripts/cyberlegion.mjs mail read <msg-id> --owner <handle>
 ```
 
-Prints the report body (sender, subject, id). **Read does not ack** — the message stays unread and
+Prints the report body (sender, subject, id). Do not add `--ack`. **Read does not ack** — the message stays unread and
 keeps surfacing until you explicitly clear it. Peeking is safe; it changes nothing.
 
 ## Ack — the only thing that clears it
 
 ```bash
-npx cyberlegion@0.3.1 mail ack <msg-id> --owner <handle>
+node scripts/cyberlegion.mjs mail ack <msg-id> --owner <handle>
 ```
 
 Ack is the sole read-state change and the sole signal that a report is handled — a surfaced message
@@ -58,13 +68,15 @@ acted on (or consciously dismissed) the report; acking an already-acked or unkno
 than silently succeeding. Two concurrent acks of the same message resolve to exactly one success —
 nothing is double-consumed.
 
+If the ack exits nonzero, tell the user it failed and why; never report the message as cleared.
+
 ## Reply — answer a frameless agent's question
 
 A report may be a **question** a frameless agent could not ask live. Reply on its thread so a later
 tick (or the agent's next run) picks up the answer:
 
 ```bash
-npx cyberlegion@0.3.1 mail send --to <agent-or-thread-origin> --thread <t> --body "<answer>"
+node scripts/cyberlegion.mjs mail send --to <agent-or-thread-origin> --thread <t> --body "<answer>"
 ```
 
 The thread carries the state across the agent's stateless re-runs.
@@ -73,5 +85,6 @@ The thread carries the state across the agent's stateless re-runs.
 
 - This skill only manages the **owner** mailbox (`--owner`). A session's own inbox is the plain
   `mail inbox`/`read`/`ack` (no `--owner`) and is not this skill's concern.
+- Creating or binding the owner identity is `init-cyberlegion`'s job; hand those requests to it.
 - It is a thin CLI wrapper — it decides *nothing* about routing or dispatch (that is the Legate /
   `dispatch-governance`), and writes no state beyond the ack/reply the human directs.

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

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

package/skills/relay-governance/README.md

@@ -19,8 +19,8 @@ ratification. Provenance over peer mail cannot be established, so a receiver act
 can verify against its own loaded contract — a ratification it fetched from a peer is invalid.
 
 **The ownership chain:** keyed on relationship, not on transport alone. A decision relayed by the
-receiver's **own owner** **and** arriving on a **turn** in its own session — carrying the Council's
-verbatim words, where they were said, the relaying unit, and its scope (one action on one target) —
+receiver's **own owner** **and** arriving on a **turn** in its own session — carrying the user-channel
+holder's verbatim words, where they were said, the relaying unit, and its scope (one action on one target) —
 is adoptable within that named scope and nothing adjacent, spent once acted on, attenuating at every
 hop. Either half alone leaves it a peer steer. The four parts are a **well-formedness** requirement:
 presence is checkable on its face, so a missing part gates adoption, and truth is not, so the parts