cyberlegion 0.1.0 → 0.3.0

package/dist/cli.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
-import { A as detectHarness, B as resolveStandingOwner, C as resolveAgentDef, D as selectSessionAdapter, E as spawn, F as register, I as registerStanding, K as resolveRoot, L as resolveAgent, M as loadAgent, N as prune, O as probeMultiplexer, P as realExec, S as listAgentDefs, V as touch, _ as inbox, a as fail, b as send, c as toonObject, d as DispatchWaitingError, f as channel, g as deleteMessage, h as ack, i as emit, j as listAgents, k as bumpLastSeen, l as install, m as awaitReply, n as FileStore, o as nextStep, p as prep, r as injectInbox, s as toonList, t as watchMail, u as collect, v as peek, w as realizeLaunch, x as decommission, y as resolveBody, z as resolveSelfId } from "./watch-BuYsdwhx.mjs";
+import { A as bumpLastSeen, B as registerStanding, C as nudgeUnit, D as selectSessionAdapter, E as spawnAndWake, F as loadAgent, G as resolveStandingOwner, H as resolvePresence, I as prune, J as listAgentDefs, K as touch, L as realExec, M as clearPresence, N as detectHarness, O as DELIVERY_DOORBELL, P as listAgents, R as reconcile, S as focusUnit, V as resolveAgent, W as resolveSelfId, Y as resolveAgentDef, _ as install, a as emit, b as resolveSpawnLaunch, c as toonList, d as deleteMessage, et as resolveRoot, f as inbox, g as send, h as resolveBody, i as injectInbox, j as claimPresence, k as wakeRecipient, l as toonObject, m as readAck, n as awaitReply, o as fail, p as peek, q as normalizeMuxEnv, r as FileStore, s as nextStep, t as watchMail, u as ack, v as decommission, w as readUnit, x as clearUnit, z as register } from "./watch-BZmEAqUo.mjs";
 import { resolve } from "node:path";
 import { Command, Option } from "commander";
+import { currentPane, probeMultiplexer } from "cyber-mux";
 //#region src/admin.ts
 /**
 * Merge one store's registry + mailboxes + briefs into another (skip agent ids already present at
@@ -37,6 +38,41 @@ function migrateStore(from, to) {
 	};
 }
 //#endregion
+//#region src/cli-input.ts
+/**
+* Translate `unit spawn`'s options into the spawn input and its wake decision — resolving an
+* `--agent`/`--agent-file` def into the harness and composed launch command, with an explicit
+* `--harness` overriding the def's own.
+*
+* Throws when no harness can be resolved, so the CLI's own `fail()` still renders it.
+*/
+function spawnCommandInput(opts) {
+	const { harness, command } = resolveSpawnLaunch({
+		agent: opts.agent,
+		agentFile: opts.agentFile,
+		harness: opts.harness
+	});
+	if (!harness) throw new Error("unit spawn needs --harness, or --agent/--agent-file resolving one");
+	return {
+		input: {
+			harness,
+			command,
+			task: opts.task,
+			briefFile: opts.briefFile,
+			handle: opts.handle,
+			branch: opts.branch,
+			worktreePath: opts.worktreePath,
+			cwd: opts.cwd,
+			at: opts.at
+		},
+		noWake: opts.wake === false
+	};
+}
+/** What `unit read` prints: the raw scrape, or the JSON envelope under `--format json`. */
+function readCommandOutput(format, result) {
+	return format === "json" ? JSON.stringify(result, null, 2) : result.output;
+}
+//#endregion
 //#region src/cli.ts
 const VERSION = "0.0.0";
 function ctxOf(opts) {
@@ -50,55 +86,18 @@ function formatOf(opts) {
 }
 function requireSelf(ctx) {
 	const id = resolveSelfId(ctx);
-	if (!id) fail("no identity in this session — run `cyberlegion identity register` first");
+	if (!id) fail("no identity in this session — run `cyberlegion unit register` first");
 	bumpLastSeen(ctx, id);
 	return id;
 }
-function resolveTarget(ctx, ref) {
-	const agent = resolveAgent(ctx.store, ref);
-	const pane = agent.tmux?.pane ?? ctx.store.findPaneByAgentId(agent.id);
-	if (!pane) fail(`unit "${ref}" has no known session pane`);
-	return { id: pane };
-}
 function withGlobals(cmd) {
 	return cmd.option("--space <path>", "isolate the hub root (overrides the global hub / $CYBERLEGION_ROOT)").addOption(new Option("--format <format>", "output format").choices(["toon", "json"]).default("toon"));
 }
 const program = new Command();
-program.name("cyberlegion").description("Harness-agnostic agent session spawning, messaging, and dispatch over the filesystem").version(VERSION).enablePositionalOptions();
-const identity = program.command("identity").description("self-identify and discover peers");
-withGlobals(identity.command("register")).description("register or refresh this session identity").option("--handle <name>", "human handle for this agent").option("--harness <h>", "claude | cursor | codex (else auto-detected)").action((opts) => {
-	const rec = register(ctxOf(opts), {
-		handle: opts.handle,
-		harness: opts.harness
-	});
-	emit(formatOf(opts), {
-		toon: toonObject({
-			id: rec.id,
-			handle: rec.handle,
-			harness: rec.harness ?? "-",
-			status: rec.status
-		}),
-		json: rec
-	});
-});
-withGlobals(identity.command("whoami")).description("print this session own identity").action((opts) => {
-	const ctx = ctxOf(opts);
-	const id = resolveSelfId(ctx);
-	if (!id) fail("no identity in this session — run `cyberlegion identity register` first");
-	const rec = loadAgent(ctx.store, id);
-	if (!rec) fail(`registered self id "${id}" has no agent record`);
-	emit(formatOf(opts), {
-		toon: toonObject({
-			id: rec.id,
-			handle: rec.handle,
-			harness: rec.harness ?? "-",
-			status: rec.status
-		}),
-		json: rec
-	});
-});
-withGlobals(identity.command("owner")).description("mint (or refresh) a standing, session-independent owner inbox").option("--handle <name>", "the owner handle to claim").action((opts) => {
-	const ctx = ctxOf(opts);
+program.name("cyberlegion").description("Harness-agnostic agent session spawning and messaging over the filesystem").version(VERSION).enablePositionalOptions();
+const unit = program.command("unit").description("legion units — register, discover, spawn, and reap");
+/** The standing-owner branch of `unit register --standing` (folds the old `identity owner`). */
+function runStanding(ctx, opts) {
 	if (!opts.handle) {
 		const standing = listAgents(ctx.store).filter((a) => a.kind === "standing");
 		emit(formatOf(opts), {
@@ -119,7 +118,7 @@ withGlobals(identity.command("owner")).description("mint (or refresh) a standing
 					key: "status",
 					get: (a) => a.status
 				}
-			], `${standing.length} agents`),
+			], `${standing.length} standing`),
 			json: standing
 		});
 		return;
@@ -136,13 +135,94 @@ withGlobals(identity.command("owner")).description("mint (or refresh) a standing
 		}),
 		json: rec
 	});
+}
+withGlobals(unit.command("register")).description("register or refresh this session identity (or --standing: a session-independent owner inbox)").option("--handle <name>", "human handle for this agent").option("--harness <h>", "claude | cursor | codex (else auto-detected)").option("--standing", "mint a standing, session-independent owner inbox (bare, with no --handle: list them)").action((opts) => {
+	const ctx = ctxOf(opts);
+	if (opts.standing) {
+		runStanding(ctx, opts);
+		return;
+	}
+	const rec = register(ctx, {
+		handle: opts.handle,
+		harness: opts.harness
+	});
+	emit(formatOf(opts), {
+		toon: toonObject({
+			id: rec.id,
+			handle: rec.handle,
+			harness: rec.harness ?? "-",
+			status: rec.status
+		}),
+		json: rec
+	});
+});
+withGlobals(unit.command("claim")).description("bind the caller's unit as a standing owner's presence; --show reads it, --clear unbinds").argument("<handle>", "standing owner handle").option("--clear", "unbind the presence (a no-op when nothing is bound)").option("--show", "print the bound presence instead of claiming").action((handle, opts) => {
+	const ctx = ctxOf(opts);
+	if (opts.show) {
+		let presence;
+		try {
+			presence = resolvePresence(ctx.store, handle);
+		} catch (err) {
+			fail(err instanceof Error ? err.message : String(err));
+		}
+		emit(formatOf(opts), {
+			toon: toonObject({ presence: presence?.id ?? "none" }),
+			json: { presence: presence?.id ?? null }
+		});
+		return;
+	}
+	if (opts.clear) {
+		try {
+			clearPresence(ctx, handle);
+		} catch (err) {
+			fail(err instanceof Error ? err.message : String(err));
+		}
+		emit(formatOf(opts), {
+			toon: toonObject({ presence: "none" }),
+			json: { presence: null }
+		});
+		return;
+	}
+	let rec;
+	try {
+		rec = claimPresence(ctx, handle);
+	} catch (err) {
+		fail(err instanceof Error ? err.message : String(err));
+	}
+	emit(formatOf(opts), {
+		toon: toonObject({
+			owner: rec.handle,
+			presence: rec.presence
+		}),
+		json: {
+			owner: rec.handle,
+			presence: rec.presence
+		}
+	});
+});
+withGlobals(unit.command("whoami")).description("print this session own identity").action((opts) => {
+	const ctx = ctxOf(opts);
+	const id = resolveSelfId(ctx);
+	if (!id) fail("no identity in this session — run `cyberlegion unit register` first");
+	const rec = loadAgent(ctx.store, id);
+	if (!rec) fail(`registered self id "${id}" has no agent record`);
+	emit(formatOf(opts), {
+		toon: toonObject({
+			id: rec.id,
+			handle: rec.handle,
+			harness: rec.harness ?? "-",
+			status: rec.status
+		}),
+		json: rec
+	});
 });
 function runWho(opts) {
 	const ctx = ctxOf(opts);
 	touch(ctx);
+	if (opts.reconcile) reconcile(ctx, { adopt: true });
 	const agents = listAgents(ctx.store).filter((a) => opts.all || a.status !== "exited");
 	emit(formatOf(opts), {
-		toon: toonList("agents", agents, [
+		toon: toonList("units", agents, [
 			{
 				key: "id",
 				get: (a) => a.id
@@ -158,14 +238,18 @@ function runWho(opts) {
 			{
 				key: "status",
 				get: (a) => a.status
+			},
+			{
+				key: "pane",
+				get: (a) => a.pane?.id ?? "-"
 			}
-		], `${agents.length} agents`),
+		], `${agents.length} units`),
 		json: agents
 	});
-	if (agents.length === 0) nextStep("cyberlegion identity register to join");
+	if (agents.length === 0) nextStep("cyberlegion unit register to join");
 }
-withGlobals(identity.command("who")).description("list the addressable peers").option("--all", "include exited agents").action(runWho);
-withGlobals(identity.command("prune")).description("mark dead agents exited and sweep").action((opts) => {
+withGlobals(unit.command("who")).description("list the addressable units").option("--all", "include exited units").option("--reconcile", "live-probe the current mux: cull dead-pane records and adopt unbound harness-bearing panes before listing").action(runWho);
+withGlobals(unit.command("prune")).description("mark dead units exited and sweep").action((opts) => {
 	const ctx = ctxOf(opts);
 	touch(ctx);
 	const changed = prune(ctx);
@@ -180,60 +264,44 @@ withGlobals(identity.command("prune")).description("mark dead agents exited and
 		json: changed
 	});
 });
-const session = program.command("session").description("warm peer session lifecycle over a multiplexer");
 function defineSpawn(cmd) {
-	return withGlobals(cmd).description("launch a new peer session in its own git worktree (tmux or herdr)").option("--harness <h>", "claude | cursor | codex (required unless --agent/--agent-file resolves one)").option("--agent <name>", "resolve an agent def (.agents/agents/<name>.md) for harness/model/instructions").option("--agent-file <path>", "read an exact agent def file instead of resolving by name").option("--task <text>", "brief text, or - for stdin").option("--brief-file <path>", "read the brief from a file").option("--handle <name>", "handle for the new peer").option("--branch <name>", "branch for the new worktree (default cyberlegion/unit-<id>)").option("--worktree-path <path>", "where to check out the new worktree").option("--cwd <path>", "spawn the session in an existing directory; create no worktree (mutually exclusive with --branch/--worktree-path)").addOption(new Option("--at <placement>", "where to open the new session").choices([
+	return withGlobals(cmd).description("launch a new peer session in its own git worktree (tmux or herdr)").option("--harness <h>", "claude | cursor | codex (required unless --agent/--agent-file resolves one)").option("--agent <name>", "resolve an agent def (.agents/agents/<name>.md) for harness/model/instructions").option("--agent-file <path>", "read an exact agent def file instead of resolving by name").option("--task <text>", "brief text, or - for stdin").option("--brief-file <path>", "read the brief from a file").option("--handle <name>", "handle for the new peer").option("--branch <name>", "branch for the new worktree (default cyberlegion/unit-<id>)").option("--worktree-path <path>", "where to check out the new worktree").option("--cwd <path>", "spawn the session in an existing directory; create no worktree (mutually exclusive with --branch/--worktree-path)").addOption(new Option("--at <placement>", "where to open the new session (default: new-worktree → workspace, --cwd → tab)").choices([
 		"pane:right",
 		"pane:down",
 		"tab",
-		"window",
 		"workspace"
-	]).default("pane:right")).action((opts) => {
+	])).option("--no-wake", "suppress the first-turn doorbell (spawn idle; the caller drives the first turn itself)").action(async (opts) => {
 		const ctx = ctxOf(opts);
 		touch(ctx);
-		let harness = opts.harness;
-		let command;
-		if (opts.agent || opts.agentFile) {
-			let def;
-			try {
-				def = resolveAgentDef({
-					name: opts.agent,
-					file: opts.agentFile
-				});
-			} catch (err) {
-				fail(err instanceof Error ? err.message : String(err));
-			}
-			const realized = realizeLaunch(def, { harness: opts.harness });
-			harness = realized.harness;
-			command = realized.command;
+		let spawnInput;
+		try {
+			spawnInput = spawnCommandInput(opts);
+		} catch (err) {
+			fail(err instanceof Error ? err.message : String(err));
 		}
-		if (!harness) fail("session spawn needs --harness, or --agent/--agent-file resolving one");
-		const res = spawn(ctx, {
-			harness,
-			command,
-			task: opts.task,
-			briefFile: opts.briefFile,
-			handle: opts.handle,
-			branch: opts.branch,
-			worktreePath: opts.worktreePath,
-			cwd: opts.cwd,
-			at: opts.at
-		});
+		const res = await spawnAndWake(ctx, spawnInput.input, { noWake: spawnInput.noWake });
+		if (res.warning) console.error(`first-turn doorbell not confirmed (peer still spawned; nudge it manually): ${res.warning}`);
 		emit(formatOf(opts), {
 			toon: toonObject({
 				spawned: res.agent.id,
 				handle: res.agent.handle,
 				harness: res.agent.harness,
 				worktree: res.agent.worktree?.root,
-				pane: res.pane
+				pane: res.pane,
+				rung: res.rung
 			}),
-			json: res
+			json: {
+				agent: res.agent,
+				pane: res.pane,
+				launch: res.launch,
+				rung: res.rung
+			}
 		});
-		nextStep(`cyberlegion session read ${res.agent.id}`);
+		nextStep(`cyberlegion unit read ${res.agent.id}`);
 	});
 }
-defineSpawn(session.command("spawn"));
-withGlobals(session.command("close")).description("tear down a unit's worktree + session and reap its state (the inverse of spawn)").argument("<id>", "unit id, handle, or worktree branch/CR ref").option("--force", "discard uncommitted changes in the worktree (never overrides refusing the primary checkout)").action((ref, opts) => {
+defineSpawn(unit.command("spawn"));
+withGlobals(unit.command("close")).description("tear down a unit's worktree + session and reap its state (the inverse of spawn)").argument("<id>", "unit id, handle, or worktree branch/CR ref").option("--force", "discard uncommitted changes in the worktree (never overrides refusing the primary checkout)").action((ref, opts) => {
 	const ctx = ctxOf(opts);
 	touch(ctx);
 	const agent = resolveAgent(ctx.store, ref);
@@ -250,79 +318,73 @@ withGlobals(session.command("close")).description("tear down a unit's worktree +
 		json: res
 	});
 });
-withGlobals(session.command("list")).description("list live peer sessions").action((opts) => {
-	const ctx = ctxOf(opts);
-	touch(ctx);
-	const agents = listAgents(ctx.store).filter((a) => a.status !== "exited");
-	emit(formatOf(opts), {
-		toon: toonList("sessions", agents, [
-			{
-				key: "id",
-				get: (a) => a.id
-			},
-			{
-				key: "handle",
-				get: (a) => a.handle
-			},
-			{
-				key: "status",
-				get: (a) => a.status
-			},
-			{
-				key: "pane",
-				get: (a) => a.tmux?.pane ?? "-"
-			}
-		], `${agents.length} sessions`),
-		json: agents
-	});
-});
-withGlobals(session.command("focus")).description("move input focus to a peer's session").argument("<ref>", "unit id, handle, or worktree branch/CR ref").action((ref, opts) => {
+withGlobals(unit.command("focus")).description("move input focus to a peer's session").argument("<ref>", "unit id, handle, or worktree branch/CR ref").action((ref, opts) => {
 	const ctx = ctxOf(opts);
 	touch(ctx);
-	const target = resolveTarget(ctx, ref);
-	selectSessionAdapter(ctx.env ?? process.env).focus(realExec, target);
+	const { pane } = focusUnit(ctx, ref);
 	emit(formatOf(opts), {
 		toon: toonObject({
 			focused: ref,
-			pane: target.id
+			pane
 		}),
 		json: {
 			ref,
-			pane: target.id
+			pane
 		}
 	});
 });
-withGlobals(session.command("nudge")).description("ring a peer's session (a dumb doorbell — the mail is the payload)").argument("<ref>", "unit id, handle, or worktree branch/CR ref").action((ref, opts) => {
+withGlobals(unit.command("nudge")).description("ring a peer's session (a doorbell that tells them to check their mail)").argument("<ref>", "unit id, handle, or worktree branch/CR ref").option("--message <text>", "the doorbell text delivered to the peer session", DELIVERY_DOORBELL).action(async (ref, opts) => {
 	const ctx = ctxOf(opts);
 	touch(ctx);
-	const target = resolveTarget(ctx, ref);
-	selectSessionAdapter(ctx.env ?? process.env).send(realExec, target, "");
+	const { pane, message, resubmits } = await nudgeUnit(ctx, ref, { message: opts.message });
 	emit(formatOf(opts), {
 		toon: toonObject({
 			nudged: ref,
-			pane: target.id
+			pane
 		}),
 		json: {
 			ref,
-			pane: target.id
+			pane,
+			message,
+			resubmits
 		}
 	});
 });
-withGlobals(session.command("read")).description("scrape a peer's session screen").argument("<ref>", "unit id, handle, or worktree branch/CR ref").option("--lines <n>", "trailing lines to capture", (v) => Number.parseInt(v, 10)).action((ref, opts) => {
+withGlobals(unit.command("read")).description("scrape a peer's session screen").argument("<ref>", "unit id, handle, or worktree branch/CR ref").option("--lines <n>", "trailing lines to capture", (v) => Number.parseInt(v, 10)).action((ref, opts) => {
 	const ctx = ctxOf(opts);
 	touch(ctx);
-	const target = resolveTarget(ctx, ref);
-	const text = selectSessionAdapter(ctx.env ?? process.env).read(realExec, target, { lines: opts.lines });
-	if (formatOf(opts) === "json") console.log(JSON.stringify({
+	const { pane, output } = readUnit(ctx, ref, { lines: opts.lines });
+	console.log(readCommandOutput(formatOf(opts), {
 		ref,
-		pane: target.id,
-		output: text
-	}, null, 2));
-	else console.log(text);
+		pane,
+		output
+	}));
+});
+withGlobals(unit.command("clear")).description("reset a warm peer's context to cold by injecting its own harness fresh-context command — keeps the pane/session warm; tears down nothing").argument("<ref>", "unit id, handle, or worktree branch/CR ref").action((ref, opts) => {
+	const ctx = ctxOf(opts);
+	touch(ctx);
+	let res;
+	try {
+		res = clearUnit(ctx, ref);
+	} catch (err) {
+		fail(err instanceof Error ? err.message : String(err));
+	}
+	emit(formatOf(opts), {
+		toon: toonObject({
+			cleared: ref,
+			pane: res.pane,
+			command: res.command
+		}),
+		json: {
+			cleared: ref,
+			pane: res.pane,
+			command: res.command
+		}
+	});
 });
 const mail = program.command("mail").description("durable inter-agent messaging");
 function defineSend(cmd) {
-	return withGlobals(cmd).description("send a message to a peer (by handle or id)").requiredOption("--to <peer>", "recipient handle or id").option("--from <id>", "sender id (else this session own identity)").option("--subject <s>", "subject").option("--body <text>", "message body").option("--body-file <path>", "read body from a file, or - for stdin").option("--thread <id>", "thread id").option("--reply-to <msg>", "message id this replies to").action((opts) => {
+	return withGlobals(cmd).description("send a message to a peer (by handle or id)").requiredOption("--to <peer>", "recipient handle or id").option("--from <id>", "sender id (else this session own identity)").option("--subject <s>", "subject").option("--body <text>", "message body").option("--body-file <path>", "read body from a file, or - for stdin").option("--thread <id>", "thread id").option("--reply-to <msg>", "message id this replies to").option("--no-nudge", "suppress the delivery doorbell (do not wake the recipient's pane)").action(async (opts) => {
 		const ctx = ctxOf(opts);
 		const fromId = opts.from ?? requireSelf(ctx);
 		const body = resolveBody(opts.body, opts.bodyFile);
@@ -334,21 +396,30 @@ function defineSend(cmd) {
 			thread: opts.thread,
 			replyTo: opts.replyTo
 		});
+		const wake = await wakeRecipient(ctx.store, () => selectSessionAdapter(ctx.env ?? process.env), realExec, {
+			toId: msg.to,
+			fromId,
+			noNudge: opts.nudge === false
+		});
+		if (wake.warning) console.error(`delivery doorbell not confirmed (message still delivered): ${wake.warning}`);
 		emit(formatOf(opts), {
 			toon: toonObject({
 				sent: msg.id,
 				to: opts.to,
-				subject: msg.subject
+				subject: msg.subject,
+				rung: wake.rung
 			}),
-			json: msg
+			json: {
+				...msg,
+				rung: wake.rung
+			}
 		});
 	});
 }
 defineSend(mail.command("send"));
-function runInbox(opts) {
-	const ctx = ctxOf(opts);
-	touch(ctx);
-	const meId = opts.owner ? resolveStandingOwner(ctx.store, opts.owner) : requireSelf(ctx);
+/** List a resolved inbox (the caller's own or an --owner mailbox) as TOON with an aggregate;
+* `readCmd` is the follow-up read command prefix surfaced as the next step. */
+function emitInbox(ctx, opts, meId, readCmd) {
 	const items = inbox({ store: ctx.store }, {
 		meId,
 		unread: opts.unread,
@@ -378,12 +449,34 @@ function runInbox(opts) {
 		json: items
 	});
 	const firstUnread = items.find((m) => !m.read);
-	if (firstUnread) nextStep(`cyberlegion mail read ${firstUnread.id}`);
+	if (firstUnread) nextStep(`${readCmd} ${firstUnread.id}`);
+}
+function runInbox(opts) {
+	const ctx = ctxOf(opts);
+	touch(ctx);
+	emitInbox(ctx, opts, opts.owner ? resolveStandingOwner(ctx.store, opts.owner) : requireSelf(ctx), "cyberlegion mail read");
 }
 withGlobals(mail.command("inbox")).description("list your mail").option("--unread", "only un-acked mail").option("--from <id>", "filter by sender").option("--thread <id>", "filter to messages carrying this thread id").option("--owner <handle>", "target a standing owner's mailbox instead of this session's own").action(runInbox);
-withGlobals(mail.command("read")).description("peek at a message without acknowledging it").argument("<msg-id>", "message id").option("--owner <handle>", "peek a standing owner's mailbox instead of this session's own").action((msgId, opts) => {
+withGlobals(mail.command("read")).description("read a message; --ack consumes it in the same step, otherwise it only peeks").argument("<msg-id>", "message id").option("--ack", "acknowledge the message in the same step (idempotent — no error if already acked)").option("--owner <handle>", "read a standing owner's mailbox instead of this session's own").action((msgId, opts) => {
 	const ctx = ctxOf(opts);
 	const meId = opts.owner ? resolveStandingOwner(ctx.store, opts.owner) : requireSelf(ctx);
+	if (opts.ack) {
+		const { msg, acked } = readAck({ store: ctx.store }, meId, msgId);
+		emit(formatOf(opts), {
+			toon: toonObject({
+				id: msg.id,
+				from: msg.fromHandle,
+				subject: msg.subject,
+				body: msg.body,
+				acked
+			}),
+			json: {
+				...msg,
+				acked
+			}
+		});
+		return;
+	}
 	const msg = peek({ store: ctx.store }, meId, msgId);
 	if (!msg) fail(`"${msgId}" is not a message in this inbox`);
 	emit(formatOf(opts), {
@@ -473,96 +566,6 @@ withGlobals(mail.command("hook")).description("emit the harness hook injection p
 	const payload = injectInbox(ctx, opts.event);
 	if (payload) console.log(JSON.stringify(payload));
 });
-const dispatch = program.command("dispatch").description("delegate work and await a result (result-slot primitives)");
-function definePrepOptions(cmd) {
-	return withGlobals(cmd).option("--agent <name>", "resolve an agent def to build the instruction/launch from").option("--agent-file <path>", "read an exact agent def file instead of resolving by name").option("--role <name>", "role label folded into the generic instruction when no agent def is given").option("--brief-text <text>", "brief body text").option("--brief-file <path>", "read the brief from a file, or - for stdin").option("--verdict-schema <path>", "JSON schema file (required keys + primitive types) the result must satisfy").option("--thread <id>", "thread id (defaults to the minted dispatch id)");
-}
-function dispatchResultFields(r) {
-	return {
-		id: r.id,
-		verdict: r.verdict != null ? JSON.stringify(r.verdict) : void 0,
-		body: r.body,
-		ts: r.ts
-	};
-}
-definePrepOptions(dispatch.command("prep")).description("allocate an id + brief + result slot and return the envelope — spawns nothing, never invokes Task").action((opts) => {
-	const ctx = ctxOf(opts);
-	let envelope;
-	try {
-		envelope = prep({ store: ctx.store }, {
-			agent: opts.agent,
-			agentFile: opts.agentFile,
-			role: opts.role,
-			briefText: opts.briefText,
-			briefFile: opts.briefFile,
-			thread: opts.thread
-		});
-	} catch (err) {
-		fail(err instanceof Error ? err.message : String(err));
-	}
-	emit(formatOf(opts), {
-		toon: toonObject({ ...envelope }),
-		json: envelope
-	});
-	nextStep(`spawn a subagent with the instruction, then \`cyberlegion dispatch collect ${envelope.id}\` — or on the channel path, \`cyberlegion mail await --thread ${envelope.thread}\``);
-});
-definePrepOptions(dispatch.command("channel")).description("prep + spawn a peer session + (--wait) await the mail-thread reply — the one CLI-driven convenience (needs --agent or --agent-file to realize the peer launch)").addOption(new Option("--at <placement>", "where to open the new session").choices([
-	"pane:right",
-	"pane:down",
-	"tab",
-	"window",
-	"workspace"
-]).default("pane:right")).option("--wait", "block for the mail-thread reply and print the validated result").option("--timeout <ms>", "give up after this many ms with no reply (0 = wait forever)", (v) => Number.parseInt(v, 10), 6e5).option("--max-wait <s>", "self-cap for one internal poll cycle, in seconds (re-arm by re-running with --wait)", (v) => Number.parseInt(v, 10), 240).action(async (opts) => {
-	const ctx = ctxOf(opts);
-	touch(ctx);
-	let result;
-	try {
-		result = await channel(ctx, {
-			agent: opts.agent,
-			agentFile: opts.agentFile,
-			role: opts.role,
-			briefText: opts.briefText,
-			briefFile: opts.briefFile,
-			verdictSchema: opts.verdictSchema,
-			thread: opts.thread,
-			at: opts.at,
-			wait: opts.wait,
-			timeoutMs: opts.timeout,
-			maxWaitS: opts.maxWait
-		});
-	} catch (err) {
-		if (err instanceof DispatchWaitingError) {
-			console.error(err.message);
-			return;
-		}
-		fail(err instanceof Error ? err.message : String(err));
-	}
-	if ("ts" in result) {
-		emit(formatOf(opts), {
-			toon: toonObject(dispatchResultFields(result)),
-			json: result
-		});
-		return;
-	}
-	emit(formatOf(opts), {
-		toon: toonObject({ ...result }),
-		json: result
-	});
-	nextStep(`cyberlegion mail await --thread ${result.thread} to collect the reply later`);
-});
-withGlobals(dispatch.command("collect")).description("read + validate a subagent's result file (the subagent path's counterpart to mail await)").argument("<id>", "dispatch id").option("--verdict-schema <path>", "JSON schema file the result must satisfy").action((id, opts) => {
-	const ctx = ctxOf(opts);
-	let result;
-	try {
-		result = collect({ store: ctx.store }, id, opts.verdictSchema);
-	} catch (err) {
-		fail(err instanceof Error ? err.message : String(err));
-	}
-	emit(formatOf(opts), {
-		toon: toonObject(dispatchResultFields(result)),
-		json: result
-	});
-});
 const agent = program.command("agent").description("resolve reusable agent definitions");
 const INSTRUCTIONS_PREVIEW_LEN = 200;
 function truncated(text, full) {
@@ -654,31 +657,11 @@ withGlobals(agent.command("path")).description("print the resolved def file path
 		json: { path: def.path }
 	});
 });
-const admin = program.command("admin").description("setup and diagnostics");
-withGlobals(admin.command("install")).description("wire the mail-surfacing hook into a harness config").requiredOption("--agent <harness>", "claude | cursor | codex").option("--dir <path>", "project dir to write config into", process.cwd()).action((opts) => {
-	const results = install(opts.agent, opts.dir);
-	emit(formatOf(opts), {
-		toon: toonList("hooks", results, [
-			{
-				key: "event",
-				get: (r) => r.event
-			},
-			{
-				key: "status",
-				get: (r) => r.status
-			},
-			{
-				key: "file",
-				get: (r) => r.file
-			}
-		], `${results.length} hooks`),
-		json: results
-	});
-});
-withGlobals(admin.command("doctor")).description("probe harness, multiplexer (ancestry-discovered), hub root, and self-id").action((opts) => {
+const mux = program.command("mux").description("the unit-agnostic pane layer — multiplexer detection and diagnostics");
+withGlobals(mux.command("doctor")).description("probe harness, multiplexer (ancestry-discovered), hub root, and self-id").action((opts) => {
 	const ctx = ctxOf(opts);
 	const harness = detectHarness(void 0, ctx) ?? "unknown";
-	const probe = probeMultiplexer(ctx.exec ?? realExec, ctx.env ?? process.env);
+	const probe = probeMultiplexer(ctx.exec ?? realExec, normalizeMuxEnv(ctx.env ?? process.env));
 	const selfId = resolveSelfId(ctx) ?? "-";
 	emit(formatOf(opts), {
 		toon: toonObject({
@@ -698,19 +681,46 @@ withGlobals(admin.command("doctor")).description("probe harness, multiplexer (an
 			selfId
 		}
 	});
-	if (probe.mux !== "none") nextStep(`export CYBERLEGION_MUX=${probe.mux}${probe.pane ? ` CYBERLEGION_MUX_PANE=${probe.pane}` : ""} — pin the fast-path, skip ancestry discovery on later calls`);
+	if (probe.mux !== "none") nextStep(`export CYBER_MUX=${probe.mux}${probe.pane ? ` CYBER_MUX_PANE=${probe.pane}` : ""} — pin the fast-path, skip ancestry discovery on later calls`);
 });
-withGlobals(admin.command("mode")).description("report the detected session-backend mode").action((opts) => {
-	let mux = "none";
+withGlobals(mux.command("mode")).description("report the detected session-backend mode").action((opts) => {
+	const ctx = ctxOf(opts);
+	let mode = "none";
 	try {
-		mux = selectSessionAdapter(process.env).name;
+		mode = selectSessionAdapter(ctx.env ?? process.env).name;
 	} catch {}
 	emit(formatOf(opts), {
-		toon: toonObject({ mode: mux }),
-		json: { mode: mux }
+		toon: toonObject({ mode }),
+		json: { mode }
 	});
 });
-withGlobals(admin.command("migrate")).description("merge one hub root state into another (e.g. an old project-local root into the global hub)").requiredOption("--from <path>", "source hub root").requiredOption("--to <path>", "destination hub root").action((opts) => {
+withGlobals(program.command("attach")).description("bind this pane as the hub's main pane (the owner's live presence); --show reads it, --clear unbinds").option("--clear", "unbind the main pane (a no-op when nothing is bound)").option("--show", "print the bound main pane instead of binding").action((opts) => {
+	const ctx = ctxOf(opts);
+	if (opts.show) {
+		const pane = ctx.store.getMainPane();
+		emit(formatOf(opts), {
+			toon: toonObject({ mainPane: pane ?? "none" }),
+			json: { mainPane: pane ?? null }
+		});
+		return;
+	}
+	if (opts.clear) {
+		ctx.store.setMainPane(null);
+		emit(formatOf(opts), {
+			toon: toonObject({ mainPane: "none" }),
+			json: { mainPane: null }
+		});
+		return;
+	}
+	const cur = currentPane(normalizeMuxEnv(ctx.env ?? process.env));
+	if (!cur) fail("no multiplexer pane to bind — run this from inside a tmux or herdr pane");
+	ctx.store.setMainPane(cur.pane);
+	emit(formatOf(opts), {
+		toon: toonObject({ mainPane: cur.pane }),
+		json: { mainPane: cur.pane }
+	});
+});
+withGlobals(program.command("admin").description("hub-state maintenance").command("migrate")).description("merge one hub root state into another (e.g. an old project-local root into the global hub)").requiredOption("--from <path>", "source hub root").requiredOption("--to <path>", "destination hub root").action((opts) => {
 	const res = migrateStore(new FileStore(resolve(opts.from)), new FileStore(resolve(opts.to)));
 	emit(formatOf(opts), {
 		toon: toonObject({
@@ -721,10 +731,51 @@ withGlobals(admin.command("migrate")).description("merge one hub root state into
 		json: res
 	});
 });
+withGlobals(program.command("init")).description("resolve this session harness, register the Legion surfacing hook, and advise owner binding").option("--agent <h>", "claude | cursor | codex (else auto-detected)").option("--dir <path>", "project dir to write config into", process.cwd()).option("--pin <version>", "version to pin the registered npx hook command to (e.g. the bundled plugin version)").action((opts) => {
+	const ctx = ctxOf(opts);
+	let harness;
+	try {
+		const detected = detectHarness(opts.agent, ctx);
+		if (!detected) fail("could not detect harness — pass --agent claude|cursor|codex");
+		harness = detected;
+	} catch (err) {
+		fail(err instanceof Error ? err.message : String(err));
+	}
+	let results;
+	try {
+		results = install(harness, opts.dir, opts.pin);
+	} catch (err) {
+		fail(err instanceof Error ? err.message : String(err));
+	}
+	emit(formatOf(opts), {
+		toon: toonList("hooks", results, [
+			{
+				key: "event",
+				get: (r) => r.event
+			},
+			{
+				key: "status",
+				get: (r) => r.status
+			},
+			{
+				key: "file",
+				get: (r) => r.file
+			}
+		], `harness ${harness}, ${results.length} hooks`),
+		json: {
+			harness,
+			hooks: results
+		}
+	});
+	if (!listAgents(ctx.store).some((a) => a.kind === "standing")) {
+		nextStep("cyberlegion unit register --standing --handle <name> to mint the durable owner inbox");
+		nextStep("cyberlegion attach to bind this pane as the owner live presence");
+	}
+});
 defineSpawn(program.command("spawn"));
 defineSend(program.command("send"));
 withGlobals(program.command("inbox")).description("list your mail (alias of `mail inbox`)").option("--unread", "only un-acked mail").option("--from <id>", "filter by sender").option("--thread <id>", "filter to messages carrying this thread id").action(runInbox);
-withGlobals(program.command("who")).description("list the addressable peers (alias of `identity who`)").option("--all", "include exited agents").action(runWho);
+withGlobals(program.command("who")).description("list the addressable units (alias of `unit who`)").option("--all", "include exited units").option("--reconcile", "live-probe the current mux: cull dead-pane records and adopt unbound harness-bearing panes before listing").action(runWho);
 withGlobals(program).action((opts) => {
 	const ctx = ctxOf(opts);
 	touch(ctx);
@@ -752,12 +803,24 @@ withGlobals(program).action((opts) => {
 			units
 		}
 	});
-	if (!id) nextStep("cyberlegion identity register to join");
+	if (!id) nextStep("cyberlegion unit register to join");
 	else if (unread > 0) nextStep("cyberlegion mail inbox --unread");
 });
-program.parseAsync(process.argv).catch((err) => {
-	console.error(JSON.stringify({ error: err instanceof Error ? err.message : String(err) }));
-	process.exit(1);
-});
+/**
+* Run the CLI. Exported rather than executed at module scope so the command bodies are reachable
+* from a test: with a bare `program.parseAsync(process.argv)` here, importing this module ran the
+* whole CLI, so every `.action()` body — and every option wire inside it — was unreachable, and a
+* flag that stopped being forwarded changed real behavior with the suite green.
+*
+* `bin/cyberlegion.mjs` calls this; nothing else should.
+*/
+async function runCli(argv = process.argv) {
+	try {
+		await program.parseAsync(argv);
+	} catch (err) {
+		console.error(JSON.stringify({ error: err instanceof Error ? err.message : String(err) }));
+		process.exit(1);
+	}
+}
 //#endregion
-export {};
+export { runCli };