cyberlegion 0.1.0 → 0.2.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 loadAgent, B as resolveSelfId, C as spawn, D as clearPresence, E as claimPresence, F as register, H as touch, I as registerStanding, J as normalizeMuxEnv, L as resolveAgent, M as prune, N as realExec, O as detectHarness, P as reconcile, R as resolvePresence, S as clearUnit, T as bumpLastSeen, V as resolveStandingOwner, _ as install, a as emit, b as resolveAgentDef, c as toonList, d as deleteMessage, f as inbox, g as send, h as resolveBody, i as injectInbox, j as presenceOf, k as listAgents, l as toonObject, m as readAck, n as awaitReply, o as fail, p as peek, q as resolveRoot, r as FileStore, s as nextStep, t as watchMail, u as ack, v as decommission, w as selectSessionAdapter, x as realizeLaunch, y as listAgentDefs } from "./watch-nkm6F1_f.mjs";
 import { resolve } from "node:path";
 import { Command, Option } from "commander";
+import { currentPane, nudge, 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,119 @@ function migrateStore(from, to) {
 	};
 }
 //#endregion
+//#region src/console/doorbell.ts
+/** The doorbell text delivered to a woken recipient; also the standalone `unit nudge` default. */
+const DELIVERY_DOORBELL = "You have unread mail — check your inbox.";
+/**
+* The first-turn doorbell `unit spawn` delivers to a freshly-opened paned peer. The peer's brief is
+* already injected into its context by its own SessionStart hook (never re-typed here — the ring
+* only makes the peer take a turn); this text points it at that loaded brief so it starts on its own
+* without a human nudge.
+*/
+const SPAWN_DOORBELL = "Your brief is loaded in context — read it and begin work.";
+/**
+* A freshly-launched harness cold-boots slower than an already-running peer, so the spawn first-turn
+* ring gets a wider retry budget than a plain `mail send` doorbell (nudge's own 10 × 400ms): flush the
+* staged buffer for up to ~8s (20 × 400ms) before giving up. The common case still returns after one
+* settle cycle once the peer takes the turn — the budget only bounds a slow or stuck boot. Still
+* bounded — a harness that never reaches its prompt resolves to a best-effort warning, never a hang.
+*/
+const SPAWN_NUDGE_OPTS = {
+	attempts: 20,
+	settleMs: 400
+};
+/** Resolve an agent's live session pane: its recorded pane, else a pane pointer keyed by its id. */
+function paneOf(store, id) {
+	return loadAgent(store, id)?.pane?.id ?? store.findPaneByAgentId(id);
+}
+/**
+* Best-effort wake the recipient of a just-delivered message so it checks its inbox. A peer's live
+* session pane, a standing owner's bound presence (`unit claim` — the live unit standing in for it,
+* an exited one falling back below), or — with neither — the hub's bound main pane, is rung via the
+* nudge submit-verify path (a taken turn, not fire-and-forget). Durable delivery already happened;
+* the ring is opportunistic on top, so a legitimate no-op (`--no-nudge`, a headless/absent recipient
+* with no live pane, a standing-owner send with no presence and no main pane bound, or a
+* self-addressed send) rings nothing, and a ring that never completes within nudge's retry cap is
+* swallowed into a warning. This never throws — it can never fail the send.
+*
+* The adapter is resolved lazily via `getAdapter`, invoked only once a pane to ring is confirmed and
+* inside the same swallowing try — so a session with no mux backend (where `selectSessionAdapter`
+* throws) is just a no-op wake, never a failed send.
+*/
+async function wakeRecipient(store, getAdapter, exec, input, nudgeOpts) {
+	if (input.noNudge) return { rung: false };
+	const recipient = loadAgent(store, input.toId);
+	if (!recipient) return { rung: false };
+	let pane;
+	let focusGated = false;
+	if (recipient.kind === "standing") {
+		const presenceUnit = presenceOf(store, recipient);
+		if (presenceUnit) pane = paneOf(store, presenceUnit.id);
+		else {
+			pane = store.getMainPane();
+			focusGated = true;
+		}
+	} else pane = paneOf(store, recipient.id);
+	if (!pane) return { rung: false };
+	if (pane === paneOf(store, input.fromId)) return { rung: false };
+	if (focusGated) {
+		let focused;
+		try {
+			focused = getAdapter().isPaneFocused(exec, { id: pane });
+		} catch {
+			focused = void 0;
+		}
+		if (focused === false) return {
+			rung: false,
+			pane
+		};
+	}
+	try {
+		await nudge(getAdapter(), exec, { id: pane }, DELIVERY_DOORBELL, nudgeOpts);
+		return {
+			rung: true,
+			pane
+		};
+	} catch (err) {
+		return {
+			rung: false,
+			pane,
+			warning: err instanceof Error ? err.message : String(err)
+		};
+	}
+}
+/**
+* Best-effort deliver a freshly-spawned paned peer's first turn so it acts on its already-loaded
+* brief with no human nudge. 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` rings the `SPAWN_DOORBELL` over the
+* boot-race-aware `nudge` submit-verify path (a taken turn, never re-typing the brief), the same
+* best-effort ring `wakeRecipient` gives `mail send`: the spawn (worktree, session, registry record)
+* is the guaranteed effect and the ring is opportunistic on top, so `--no-wake` rings nothing and a
+* ring that never completes within the retry budget is swallowed into a warning. This never throws —
+* it can never fail the spawn.
+*
+* The adapter is resolved lazily via `getAdapter` inside the same swallowing try, so even a session
+* whose backend has since gone away (where `selectSessionAdapter` would throw) degrades to a warned
+* no-op rather than a failed spawn.
+*/
+async function wakeSpawn(getAdapter, exec, input, nudgeOpts = SPAWN_NUDGE_OPTS) {
+	if (input.noWake) return { rung: false };
+	try {
+		await nudge(getAdapter(), exec, input.target, SPAWN_DOORBELL, nudgeOpts);
+		return {
+			rung: true,
+			pane: input.target.id
+		};
+	} catch (err) {
+		return {
+			rung: false,
+			pane: input.target.id,
+			warning: err instanceof Error ? err.message : String(err)
+		};
+	}
+}
+//#endregion
 //#region src/cli.ts
 const VERSION = "0.0.0";
 function ctxOf(opts) {
@@ -50,13 +164,13 @@ 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);
+	const pane = agent.pane?.id ?? ctx.store.findPaneByAgentId(agent.id);
 	if (!pane) fail(`unit "${ref}" has no known session pane`);
 	return { id: pane };
 }
@@ -64,41 +178,10 @@ 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 +202,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 +219,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 +322,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,15 +348,13 @@ 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;
@@ -207,7 +373,7 @@ function defineSpawn(cmd) {
 			harness = realized.harness;
 			command = realized.command;
 		}
-		if (!harness) fail("session spawn needs --harness, or --agent/--agent-file resolving one");
+		if (!harness) fail("unit spawn needs --harness, or --agent/--agent-file resolving one");
 		const res = spawn(ctx, {
 			harness,
 			command,
@@ -219,21 +385,30 @@ function defineSpawn(cmd) {
 			cwd: opts.cwd,
 			at: opts.at
 		});
+		const wake = await wakeSpawn(() => selectSessionAdapter(ctx.env ?? process.env), realExec, {
+			target: { id: res.pane },
+			noWake: opts.wake === false
+		});
+		if (wake.warning) console.error(`first-turn doorbell not confirmed (peer still spawned; nudge it manually): ${wake.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: wake.rung
 			}),
-			json: res
+			json: {
+				...res,
+				rung: wake.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,33 +425,7 @@ 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);
@@ -292,11 +441,12 @@ withGlobals(session.command("focus")).description("move input focus to a peer's
 		}
 	});
 });
-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 message = opts.message || "You have unread mail — check your inbox.";
+	const result = await nudge(selectSessionAdapter(ctx.env ?? process.env), realExec, target, message);
 	emit(formatOf(opts), {
 		toon: toonObject({
 			nudged: ref,
@@ -304,11 +454,13 @@ withGlobals(session.command("nudge")).description("ring a peer's session (a dumb
 		}),
 		json: {
 			ref,
-			pane: target.id
+			pane: target.id,
+			message,
+			resubmits: result.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);
@@ -320,9 +472,31 @@ withGlobals(session.command("read")).description("scrape a peer's session screen
 	}, null, 2));
 	else console.log(text);
 });
+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 +508,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 +561,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 +678,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 +769,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 +793,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 +843,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,7 +915,7 @@ 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) => {