cyberlegion 0.2.0 → 0.3.0

package/bin/cyberlegion.mjs

@@ -3,4 +3,5 @@ import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 const dir = dirname(fileURLToPath(import.meta.url))
-await import(join(dir, '..', 'dist', 'cli.mjs'))
+const { runCli } = await import(join(dir, '..', 'dist', 'cli.mjs'))
+await runCli()

package/dist/cli.d.mts

@@ -1 +1,12 @@
-export { };
+//#region src/cli.d.ts
+/**
+ * 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.
+ */
+declare function runCli(argv?: string[]): Promise<void>;
+//#endregion
+export { runCli };

package/dist/cli.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-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 { 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, nudge, probeMultiplexer } from "cyber-mux";
+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
@@ -38,117 +38,39 @@ 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.";
+//#region src/cli-input.ts
 /**
-* 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.
+* 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.
 *
-* 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.
+* Throws when no harness can be resolved, so the CLI's own `fail()` still renders it.
 */
-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)
-		};
-	}
+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
+	};
 }
-/**
-* 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)
-		};
-	}
+/** 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
@@ -168,12 +90,6 @@ function requireSelf(ctx) {
 	bumpLastSeen(ctx, id);
 	return id;
 }
-function resolveTarget(ctx, ref) {
-	const agent = resolveAgent(ctx.store, ref);
-	const pane = agent.pane?.id ?? 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"));
 }
@@ -357,39 +273,14 @@ function defineSpawn(cmd) {
 	])).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("unit 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 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}`);
+		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,
@@ -397,11 +288,13 @@ function defineSpawn(cmd) {
 				harness: res.agent.harness,
 				worktree: res.agent.worktree?.root,
 				pane: res.pane,
-				rung: wake.rung
+				rung: res.rung
 			}),
 			json: {
-				...res,
-				rung: wake.rung
+				agent: res.agent,
+				pane: res.pane,
+				launch: res.launch,
+				rung: res.rung
 			}
 		});
 		nextStep(`cyberlegion unit read ${res.agent.id}`);
@@ -428,49 +321,44 @@ withGlobals(unit.command("close")).description("tear down a unit's worktree + se
 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(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);
-	const message = opts.message || "You have unread mail — check your inbox.";
-	const result = await nudge(selectSessionAdapter(ctx.env ?? process.env), realExec, target, message);
+	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: result.resubmits
+			resubmits
 		}
 	});
 });
 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);
@@ -918,9 +806,21 @@ withGlobals(program).action((opts) => {
 	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 };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { Exec, Exec as Exec$1, MuxAdapter, MuxPlacement, MuxProbe, probeMultiplexer } from "cyber-mux";
+import { Exec, Exec as Exec$1, MuxAdapter, MuxPlacement, MuxProbe, NudgeOptions, probeMultiplexer } from "cyber-mux";
 import { assertDistinctFromPrimary, gitWorktreeAdapter, resolvePrimaryRoot } from "cyber-mux/worktree";
 
 //#region src/store/store.d.ts
@@ -15,7 +15,10 @@ interface Message {
   sentAt: string;
 }
 type Harness = 'claude' | 'cursor' | 'codex';
-type AgentStatus = 'spawning' | 'active' | 'idle' | 'stale' | 'exited' | 'paused';
+/** The statuses this version writes. `spawning` is retired: spawn registers a peer `active`
+ * outright, since nothing flips it any more (the SessionStart hook injects no brief and mutates no
+ * status — see `mail/surface`). */
+type AgentStatus = 'active' | 'idle' | 'stale' | 'exited' | 'paused';
 interface AgentRecord {
   id: string;
   handle: string;
@@ -35,7 +38,19 @@ interface AgentRecord {
     session?: string;
   } | null;
   pid?: number;
-  status: AgentStatus;
+  /** A record migrated from an older hub (`admin migrate`) may carry a status this version no
+   * longer writes — the retired `spawning` is the known case. **Reads preserve it verbatim**: no
+   * read path validates, coerces, or normalizes a status, and none may start doing so
+   * (`mail/surface` freezes that a legacy `spawning` record keeps the status it was migrated with).
+   * A write that merely round-trips a record preserves it too.
+   *
+   * The exceptions are deliberate lifecycle writes, not normalizations: `register` asserts a session
+   * is live *now* and so writes `active`, while `prune`/`reconcile` write `exited` over whatever a
+   * record carried (`identity.ts`). A legacy record therefore does move off `spawning` — by an
+   * explicit lifecycle act, never by being read.
+   *
+   * The open member keeps the guarantee typed rather than accidental. */
+  status: AgentStatus | (string & {});
   createdAt: string;
   lastSeen: string;
   brief?: string;
@@ -211,9 +226,13 @@ interface InjectPayload {
   };
 }
 /**
- * Resolve the calling agent, gather its pending brief + unread mail, and return the
- * SessionStart-style injection payload — or null when there is nothing to inject (an
- * unregistered caller or an empty inbox never fails the harness hook).
+ * Resolve the calling agent, gather its unread mail (and a standing owner's, when this session is
+ * the hub's main pane), and return the SessionStart-style injection payload — or null when there is
+ * nothing to inject (an unregistered caller or an empty inbox never fails the harness hook).
+ *
+ * This never injects a brief. Brief delivery is the spawn wake's job: the first-turn doorbell
+ * carries the instruction and names the brief's file path, so pickup does not depend on this hook
+ * firing in the child (`unit/lifecycle`, superseding ADR-0027).
  */
 declare function injectInbox(ctx: IdContext, event: string): InjectPayload | null;
 //#endregion
@@ -378,8 +397,10 @@ interface SpawnResult {
 /**
  * Launch a new peer session as a genuine sibling unit: create a real git worktree distinct from
  * the primary checkout (refuse the primary checkout), open a session backend (tmux or herdr) with
- * its cwd set to that worktree, pre-register the peer, and drop its brief as a file the peer's own
- * SessionStart hook reads — never typed into its prompt.
+ * its cwd set to that worktree, pre-register the peer, and drop its brief as a file — never typed
+ * into its prompt. Nothing loads that file for the peer: it is the spawn wake that tells the peer to
+ * go read it, naming its path (`spawnAndWake` below, and ADR-0032). `spawn` alone therefore leaves a
+ * peer sitting idle with its brief unread, which is why callers want `spawnAndWake`.
  *
  * Spawned unit worktrees live sibling to the primary checkout (`<parent>/<repo>.worktrees/legion-<id6>`),
  * never nested inside it, even though the registry/mailbox itself lives in the global hub — the hub
@@ -387,6 +408,26 @@ interface SpawnResult {
  * scoped to this one project's git remote.
  */
 declare function spawn(ctx: IdContext, input: SpawnInput): SpawnResult;
+/**
+ * `unit spawn` end to end: open the peer, then deliver its first turn.
+ *
+ * The two acts live together here rather than at the CLI call site so the **brief path the doorbell
+ * names is derived from the record `spawn` just wrote**, not handed in by a caller. That is the
+ * point of the seam: a caller cannot ring with the wrong path because it supplies no path — an
+ * empty string, a stale path, or the brief's whole body are all unrepresentable here, rather than
+ * merely untested.
+ *
+ * The ring is best-effort on top of the guaranteed spawn effect (worktree + session + registry
+ * record): `--no-wake` rings nothing, and a ring that never completes is reported as a warning on
+ * the result rather than thrown, so it can never fail a spawn that already landed.
+ */
+declare function spawnAndWake(ctx: IdContext, input: SpawnInput, options?: {
+  noWake?: boolean;
+  nudgeOpts?: NudgeOptions;
+}): Promise<SpawnResult & {
+  rung: boolean;
+  warning?: string;
+}>;
 //#endregion
 //#region src/store/file-store.d.ts
 /** The on-disk `Store` implementation — current per-writer sharded `.json` layout (ADR-0020):
@@ -466,4 +507,4 @@ interface WatchOptions {
  */
 declare function watchMail(ctx: MsgContext, input: WatchInput, onMessage: (msg: InboxItem) => void, opts?: WatchOptions): Promise<void>;
 //#endregion
-export { type AgentDef, type AgentRecord, type AwaitInput, type AwaitOutcome, type DecommissionInput, type DecommissionResult, type Exec, FileStore, type Format, type Harness, type HookEvent, type IdContext, type InboxItem, type InboxQuery, type InboxSnapshot, type Message, type MuxProbe, type RegisterInput, type RootOptions, type SendInput, type SpawnInput, type SpawnResult, type Store, ack, assertDistinctFromPrimary, awaitReply, bumpLastSeen, decommission, deleteMessage, detectHarness, emit, ensureMarker, fail, gitWorktreeAdapter, inbox, injectInbox, install, listAgentDefs, listAgents, loadAgent, nextStep, paths, peek, probeMultiplexer, projectRoot, prune, realExec, realizeLaunch, register, resolveAgent, resolveAgentDef, resolveBody, resolvePrimaryRoot, resolveProjectLocalRoot, resolveRecipient, resolveRoot, resolveSelfId, selectSessionAdapter, send, spawn, toonList, toonObject, touch, watchMail };
+export { type AgentDef, type AgentRecord, type AwaitInput, type AwaitOutcome, type DecommissionInput, type DecommissionResult, type Exec, FileStore, type Format, type Harness, type HookEvent, type IdContext, type InboxItem, type InboxQuery, type InboxSnapshot, type Message, type MuxProbe, type RegisterInput, type RootOptions, type SendInput, type SpawnInput, type SpawnResult, type Store, ack, assertDistinctFromPrimary, awaitReply, bumpLastSeen, decommission, deleteMessage, detectHarness, emit, ensureMarker, fail, gitWorktreeAdapter, inbox, injectInbox, install, listAgentDefs, listAgents, loadAgent, nextStep, paths, peek, probeMultiplexer, projectRoot, prune, realExec, realizeLaunch, register, resolveAgent, resolveAgentDef, resolveBody, resolvePrimaryRoot, resolveProjectLocalRoot, resolveRecipient, resolveRoot, resolveSelfId, selectSessionAdapter, send, spawn, spawnAndWake, toonList, toonObject, touch, watchMail };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { A as loadAgent, B as resolveSelfId, C as spawn, F as register, G as projectRoot, H as touch, K as resolveProjectLocalRoot, L as resolveAgent, M as prune, N as realExec, O as detectHarness, T as bumpLastSeen, U as ensureMarker, W as paths, _ 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, k as listAgents, l as toonObject, 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, z as resolveRecipient } from "./watch-nkm6F1_f.mjs";
+import { $ as resolveProjectLocalRoot, A as bumpLastSeen, D as selectSessionAdapter, E as spawnAndWake, F as loadAgent, I as prune, J as listAgentDefs, K as touch, L as realExec, N as detectHarness, P as listAgents, Q as projectRoot, T as spawn, U as resolveRecipient, V as resolveAgent, W as resolveSelfId, X as ensureMarker, Y as resolveAgentDef, Z as paths, _ as install, a as emit, c as toonList, d as deleteMessage, et as resolveRoot, f as inbox, g as send, h as resolveBody, i as injectInbox, l as toonObject, n as awaitReply, o as fail, p as peek, r as FileStore, s as nextStep, t as watchMail, u as ack, v as decommission, y as realizeLaunch, z as register } from "./watch-BZmEAqUo.mjs";
 import { probeMultiplexer } from "cyber-mux";
 import { assertDistinctFromPrimary, gitWorktreeAdapter, resolvePrimaryRoot } from "cyber-mux/worktree";
-export { FileStore, ack, assertDistinctFromPrimary, awaitReply, bumpLastSeen, decommission, deleteMessage, detectHarness, emit, ensureMarker, fail, gitWorktreeAdapter, inbox, injectInbox, install, listAgentDefs, listAgents, loadAgent, nextStep, paths, peek, probeMultiplexer, projectRoot, prune, realExec, realizeLaunch, register, resolveAgent, resolveAgentDef, resolveBody, resolvePrimaryRoot, resolveProjectLocalRoot, resolveRecipient, resolveRoot, resolveSelfId, selectSessionAdapter, send, spawn, toonList, toonObject, touch, watchMail };
+export { FileStore, ack, assertDistinctFromPrimary, awaitReply, bumpLastSeen, decommission, deleteMessage, detectHarness, emit, ensureMarker, fail, gitWorktreeAdapter, inbox, injectInbox, install, listAgentDefs, listAgents, loadAgent, nextStep, paths, peek, probeMultiplexer, projectRoot, prune, realExec, realizeLaunch, register, resolveAgent, resolveAgentDef, resolveBody, resolvePrimaryRoot, resolveProjectLocalRoot, resolveRecipient, resolveRoot, resolveSelfId, selectSessionAdapter, send, spawn, spawnAndWake, toonList, toonObject, touch, watchMail };

package/dist/{watch-nkm6F1_f.mjs → watch-BZmEAqUo.mjs}

@@ -1,40 +1,10 @@
 import { basename, dirname, join, resolve } from "node:path";
-import { callerPane, currentPane, herdrMuxAdapter, nodeExec, probeMultiplexer, tmuxMuxAdapter } from "cyber-mux";
+import { callerPane, currentPane, herdrMuxAdapter, nodeExec, nudge, probeMultiplexer, tmuxMuxAdapter } from "cyber-mux";
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { assertDistinctFromPrimary, gitWorktreeAdapter, resolvePrimaryRoot } from "cyber-mux/worktree";
-import { randomBytes } from "node:crypto";
 import { execFileSync } from "node:child_process";
 import { homedir } from "node:os";
-//#region src/mux-env.ts
-/**
-* Transitional env-normalization seam (mux.feature: "a pane carrying only the legacy fast-path vars
-* is still honored"). cyber-mux's own fast-path reads `$CYBER_MUX`/`$CYBER_MUX_PANE` — its
-* `currentPane` hardcodes those names (no `envPrefix` override), and `probeMultiplexer`'s `envPrefix`
-* option renames the WHOLE pair together, so neither can be steered to fall back onto a
-* differently-named legacy pair. Every call into cyber-mux that reads the fast-path
-* (`probeMultiplexer`, `currentPane`, `callerPane`, `resolveMuxAdapter`) must be handed this seam's
-* output instead of the raw env.
-*
-* When `$CYBER_MUX`/`$CYBER_MUX_PANE` are both absent and either legacy `$CYBERLEGION_MUX`/
-* `$CYBERLEGION_MUX_PANE` var is present, copies the legacy pair onto the current names. Never
-* overwrites an already-set current var — the current pair always wins outright the moment either
-* half of it is set, exactly matching the frozen precedence chain (mux.feature: "the current
-* fast-path vars win over the legacy pair when both are set").
-*
-* Transitional — deleted once no pre-migration pane (one that only ever exported the legacy pair) is
-* still alive.
-*/
-function normalizeMuxEnv(env) {
-	const hasCurrent = env.CYBER_MUX !== void 0 || env.CYBER_MUX_PANE !== void 0;
-	const hasLegacy = env.CYBERLEGION_MUX !== void 0 || env.CYBERLEGION_MUX_PANE !== void 0;
-	if (hasCurrent || !hasLegacy) return env;
-	return {
-		...env,
-		CYBER_MUX: env.CYBERLEGION_MUX,
-		CYBER_MUX_PANE: env.CYBERLEGION_MUX_PANE
-	};
-}
-//#endregion
+import { assertDistinctFromPrimary, gitWorktreeAdapter, resolvePrimaryRoot } from "cyber-mux/worktree";
+import { randomBytes } from "node:crypto";
 //#region src/paths.ts
 /** The tracked marker file that makes a hub root initialized (see ensureMarker). */
 const MARKER_FILE = "config.json";
@@ -135,6 +105,149 @@ function sanitizePane(pane) {
 	return pane.replace(/[^A-Za-z0-9_-]/g, "_");
 }
 //#endregion
+//#region src/agentdef/resolve.ts
+function parseAgentDefFile(text) {
+	const m = /^---\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n)?([\s\S]*)$/.exec(text);
+	if (!m) return {
+		fm: {},
+		instructions: text.trim()
+	};
+	const [, block, rest] = m;
+	const fm = {};
+	const lines = block.split("\n");
+	let i = 0;
+	while (i < lines.length) {
+		const line = lines[i].replace(/\r$/, "");
+		if (line.trim() === "" || line.trim().startsWith("#")) {
+			i++;
+			continue;
+		}
+		if (line.length - line.trimStart().length > 0) {
+			i++;
+			continue;
+		}
+		const idx = line.indexOf(":");
+		if (idx === -1) {
+			i++;
+			continue;
+		}
+		const key = line.slice(0, idx).trim();
+		let value = line.slice(idx + 1).trim();
+		i++;
+		if (value === ">" || value === ">-" || value === "|" || value === "|-") {
+			const parts = [];
+			while (i < lines.length) {
+				const l = lines[i].replace(/\r$/, "");
+				if (l.trim() === "") {
+					i++;
+					continue;
+				}
+				if (l.length - l.trimStart().length === 0) break;
+				parts.push(l.trim());
+				i++;
+			}
+			value = parts.join(value.startsWith("|") ? "\n" : " ");
+		}
+		fm[key] = unquote(value);
+	}
+	return {
+		fm,
+		instructions: rest.trim()
+	};
+}
+function unquote(v) {
+	if (v.length >= 2 && (v.startsWith("\"") && v.endsWith("\"") || v.startsWith("'") && v.endsWith("'"))) return v.slice(1, -1);
+	return v;
+}
+function toBool(v) {
+	if (v === void 0) return void 0;
+	if (v === "true") return true;
+	if (v === "false") return false;
+}
+function toAgentDef(path, text, fallbackName) {
+	const { fm, instructions } = parseAgentDefFile(text);
+	return {
+		name: fm.name ?? fallbackName,
+		description: fm.description,
+		model: fm.model,
+		effort: fm.effort,
+		harness: fm.harness,
+		warm: toBool(fm.warm),
+		interactive: toBool(fm.interactive),
+		instructions,
+		path
+	};
+}
+/** The project's own `.agents/agents/` dir — the convention `agent list`/name-search scans. */
+function projectAgentsDir(cwd) {
+	return join(projectRoot(cwd), ".agents", "agents");
+}
+/** Resolve one agent definition, by explicit file or by name search. Throws a clear error when
+* neither locates a def — never returns a partial/empty result. */
+function resolveAgentDef(input) {
+	if (input.file) {
+		const path = resolve(input.file);
+		if (!existsSync(path)) throw new Error(`agent def file "${input.file}" does not exist`);
+		return toAgentDef(path, readFileSync(path, "utf8"), basename(path).replace(/\.md$/, ""));
+	}
+	if (!input.name) throw new Error("resolveAgentDef needs a --agent <name> or --agent-file <path>");
+	const roots = [...input.searchRoots ?? [], projectAgentsDir(input.cwd)];
+	for (const root of roots) {
+		const candidate = join(root, `${input.name}.md`);
+		if (existsSync(candidate)) return toAgentDef(candidate, readFileSync(candidate, "utf8"), input.name);
+	}
+	throw new Error(`no agent definition named "${input.name}" found under .agents/agents/`);
+}
+/** List every resolvable agent def under `.agents/agents/` (+ any extra search roots). Definitive
+* empty array when the dir is absent or empty — never throws for "none found" here (unlike a
+* named resolve, listing is inherently zero-or-more). */
+function listAgentDefs(input = {}) {
+	const roots = [...input.searchRoots ?? [], projectAgentsDir(input.cwd)];
+	const seen = /* @__PURE__ */ new Set();
+	const defs = [];
+	for (const root of roots) {
+		if (!existsSync(root)) continue;
+		for (const file of readdirSync(root)) {
+			if (!file.endsWith(".md")) continue;
+			const path = join(root, file);
+			if (seen.has(path)) continue;
+			seen.add(path);
+			defs.push(toAgentDef(path, readFileSync(path, "utf8"), file.replace(/\.md$/, "")));
+		}
+	}
+	return defs;
+}
+//#endregion
+//#region src/mux-env.ts
+/**
+* Transitional env-normalization seam (mux.feature: "a pane carrying only the legacy fast-path vars
+* is still honored"). cyber-mux's own fast-path reads `$CYBER_MUX`/`$CYBER_MUX_PANE` — its
+* `currentPane` hardcodes those names (no `envPrefix` override), and `probeMultiplexer`'s `envPrefix`
+* option renames the WHOLE pair together, so neither can be steered to fall back onto a
+* differently-named legacy pair. Every call into cyber-mux that reads the fast-path
+* (`probeMultiplexer`, `currentPane`, `callerPane`, `resolveMuxAdapter`) must be handed this seam's
+* output instead of the raw env.
+*
+* When `$CYBER_MUX`/`$CYBER_MUX_PANE` are both absent and either legacy `$CYBERLEGION_MUX`/
+* `$CYBERLEGION_MUX_PANE` var is present, copies the legacy pair onto the current names. Never
+* overwrites an already-set current var — the current pair always wins outright the moment either
+* half of it is set, exactly matching the frozen precedence chain (mux.feature: "the current
+* fast-path vars win over the legacy pair when both are set").
+*
+* Transitional — deleted once no pre-migration pane (one that only ever exported the legacy pair) is
+* still alive.
+*/
+function normalizeMuxEnv(env) {
+	const hasCurrent = env.CYBER_MUX !== void 0 || env.CYBER_MUX_PANE !== void 0;
+	const hasLegacy = env.CYBERLEGION_MUX !== void 0 || env.CYBERLEGION_MUX_PANE !== void 0;
+	if (hasCurrent || !hasLegacy) return env;
+	return {
+		...env,
+		CYBER_MUX: env.CYBERLEGION_MUX,
+		CYBER_MUX_PANE: env.CYBERLEGION_MUX_PANE
+	};
+}
+//#endregion
 //#region src/identity.ts
 const realExec = nodeExec;
 /** `currentPane`, narrowed to a backend the registry can actually store a locator under. A caller
@@ -524,6 +637,125 @@ function prune(ctx) {
 	return changed;
 }
 //#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 instruction
+* itself, not a notification that context is already populated. It names the brief's **file path**
+* and tells the peer to read it and begin, so pickup does not depend on a SessionStart hook firing
+* in the child (superseding ADR-0027, which split payload-delivery from turn-delivery).
+*
+* The path is named, never the brief's body: the brief is still written to its file and still never
+* typed into the pane, so a long brief costs one line here however large it is, and a re-submit on
+* the boot race re-types this instruction rather than the payload.
+*/
+function spawnDoorbell(briefPath) {
+	return `Read your brief at ${briefPath}, then 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 brief with no
+* human nudge. A paned agent boots to an idle prompt — the brief sits unread on disk and 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 instruction (`spawnDoorbell`, naming the brief's file path) over the
+* boot-race-aware `nudge` submit-verify path (a taken turn, never typing the brief itself), 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, spawnDoorbell(input.briefPath), 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/mux-select.ts
 /**
 * Backend selection via cyber-mux's two-mode mux probe, normalized through the transitional
@@ -747,8 +979,10 @@ function resetCommandFor(harness) {
 /**
 * Launch a new peer session as a genuine sibling unit: create a real git worktree distinct from
 * the primary checkout (refuse the primary checkout), open a session backend (tmux or herdr) with
-* its cwd set to that worktree, pre-register the peer, and drop its brief as a file the peer's own
-* SessionStart hook reads — never typed into its prompt.
+* its cwd set to that worktree, pre-register the peer, and drop its brief as a file — never typed
+* into its prompt. Nothing loads that file for the peer: it is the spawn wake that tells the peer to
+* go read it, naming its path (`spawnAndWake` below, and ADR-0032). `spawn` alone therefore leaves a
+* peer sitting idle with its brief unread, which is why callers want `spawnAndWake`.
 *
 * Spawned unit worktrees live sibling to the primary checkout (`<parent>/<repo>.worktrees/legion-<id6>`),
 * never nested inside it, even though the registry/mailbox itself lives in the global hub — the hub
@@ -791,6 +1025,7 @@ function spawn(ctx, input) {
 		const branch = input.branch ?? `cyberlegion/unit-${id}`;
 		const at = input.at ?? "workspace";
 		const worktreePath = input.worktreePath ?? resolveUnitWorktreePath(primaryRoot, id.slice(0, 6));
+		assertDistinctFromPrimary(resolve(worktreePath), primaryRoot);
 		if (at === "workspace" && sessionAdapter.worktree) {
 			const opened = sessionAdapter.worktree.createInWorkspace(exec, {
 				primaryRoot,
@@ -835,7 +1070,7 @@ function spawn(ctx, input) {
 			mux: muxName,
 			id: target.id
 		} : null,
-		status: "spawning",
+		status: "active",
 		createdAt: ts,
 		lastSeen: ts,
 		brief: paths.briefFile(ctx.store.root, id),
@@ -851,6 +1086,35 @@ function spawn(ctx, input) {
 	};
 }
 /**
+* `unit spawn` end to end: open the peer, then deliver its first turn.
+*
+* The two acts live together here rather than at the CLI call site so the **brief path the doorbell
+* names is derived from the record `spawn` just wrote**, not handed in by a caller. That is the
+* point of the seam: a caller cannot ring with the wrong path because it supplies no path — an
+* empty string, a stale path, or the brief's whole body are all unrepresentable here, rather than
+* merely untested.
+*
+* The ring is best-effort on top of the guaranteed spawn effect (worktree + session + registry
+* record): `--no-wake` rings nothing, and a ring that never completes is reported as a warning on
+* the result rather than thrown, so it can never fail a spawn that already landed.
+*/
+async function spawnAndWake(ctx, input, options = {}) {
+	const res = spawn(ctx, input);
+	const env = ctx.env ?? process.env;
+	const exec = ctx.exec ?? realExec;
+	const briefPath = res.agent.brief;
+	const wake = await wakeSpawn(() => selectSessionAdapter(env, exec), exec, {
+		target: { id: res.pane },
+		briefPath: briefPath ?? "",
+		noWake: options.noWake || !briefPath
+	}, options.nudgeOpts);
+	return {
+		...res,
+		rung: wake.rung,
+		...wake.warning ? { warning: wake.warning } : {}
+	};
+}
+/**
 * The label a `workspace` placement opens under — the short human-scannable name that makes a unit's
 * own visible space findable by eye (`console/workspace-label.ts` owns the naming rule). Only the
 * `workspace` placement carries one: a pane or tab lives inside a space the caller is already
@@ -882,6 +1146,67 @@ function muxEnvPrefix(muxName) {
 	return "";
 }
 /**
+* Resolve a unit's live session pane from a ref, or throw naming the ref. The one place
+* focus/nudge/read agree on what "addressable" means — a record's own pane, else a pane pointer
+* keyed by its id (a herdr peer stores its pane only in that index).
+*/
+function paneTargetOf(ctx, ref) {
+	const agent = resolveAgent(ctx.store, ref);
+	const pane = agent.pane?.id ?? ctx.store.findPaneByAgentId(agent.id);
+	if (!pane) throw new Error(`unit "${ref}" has no known session pane`);
+	return {
+		agent,
+		target: { id: pane }
+	};
+}
+/**
+* Move input focus to a peer's session. The adapter beams the attached view all the way there —
+* across workspace and tab — rather than no-opping when the peer sits outside the caller's current
+* workspace, and surfaces a backend failure instead of reporting a false success.
+*
+* Lives here rather than inline in the CLI for the same reason `spawnAndWake` does: composed at the
+* call site it took a hardcoded `realExec`, so the operation could not be driven with an injected
+* exec and its success path was unreachable from a test.
+*/
+function focusUnit(ctx, ref) {
+	const { agent, target } = paneTargetOf(ctx, ref);
+	const exec = ctx.exec ?? realExec;
+	selectSessionAdapter(ctx.env ?? process.env, exec).focus(exec, target);
+	return {
+		agent,
+		pane: target.id
+	};
+}
+/**
+* Ring a peer's session as a **taken turn**, not fire-and-forget: `nudge` submits, reads the pane
+* back to confirm the text is no longer staged, and flushes the staged buffer (never re-typing) up
+* to a bounded cap — then throws if the peer never took the turn. A doorbell must carry text; an
+* empty ring is a no-op, so the default points the peer at its inbox.
+*/
+async function nudgeUnit(ctx, ref, options = {}) {
+	const { agent, target } = paneTargetOf(ctx, ref);
+	const exec = ctx.exec ?? realExec;
+	const message = options.message || "You have unread mail — check your inbox.";
+	const result = await nudge(selectSessionAdapter(ctx.env ?? process.env, exec), exec, target, message, options.nudgeOpts);
+	return {
+		agent,
+		pane: target.id,
+		message,
+		resubmits: result.resubmits
+	};
+}
+/** Scrape the trailing output of a peer's session screen. */
+function readUnit(ctx, ref, options = {}) {
+	const { agent, target } = paneTargetOf(ctx, ref);
+	const exec = ctx.exec ?? realExec;
+	const output = selectSessionAdapter(ctx.env ?? process.env, exec).read(exec, target, { lines: options.lines });
+	return {
+		agent,
+		pane: target.id,
+		output
+	};
+}
+/**
 * Reset a warm peer's context to cold WITHOUT tearing anything down — injects the peer's own
 * harness fresh-context command (`resetCommandFor`) into its pane through the session adapter.
 * Warmth is the unit (pane/process stays warm — no cold-start), coldness is the context. The
@@ -890,9 +1215,8 @@ function muxEnvPrefix(muxName) {
 * nor the worktree — `close` (`decommission`) owns teardown.
 */
 function clearUnit(ctx, ref) {
-	const agent = resolveAgent(ctx.store, ref);
-	const pane = agent.pane?.id ?? ctx.store.findPaneByAgentId(agent.id);
-	if (!pane) throw new Error(`unit "${ref}" has no known session pane`);
+	const { agent, target } = paneTargetOf(ctx, ref);
+	const pane = target.id;
 	if (!agent.harness) throw new Error(`unit "${ref}" has no harness on record — cannot resolve its reset command`);
 	const command = resetCommandFor(agent.harness);
 	const env = ctx.env ?? process.env;
@@ -933,119 +1257,28 @@ function realizeLaunch(def, opts = {}) {
 		command: parts.join(" ")
 	};
 }
-//#endregion
-//#region src/agentdef/resolve.ts
-function parseAgentDefFile(text) {
-	const m = /^---\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n)?([\s\S]*)$/.exec(text);
-	if (!m) return {
-		fm: {},
-		instructions: text.trim()
-	};
-	const [, block, rest] = m;
-	const fm = {};
-	const lines = block.split("\n");
-	let i = 0;
-	while (i < lines.length) {
-		const line = lines[i].replace(/\r$/, "");
-		if (line.trim() === "" || line.trim().startsWith("#")) {
-			i++;
-			continue;
-		}
-		if (line.length - line.trimStart().length > 0) {
-			i++;
-			continue;
-		}
-		const idx = line.indexOf(":");
-		if (idx === -1) {
-			i++;
-			continue;
-		}
-		const key = line.slice(0, idx).trim();
-		let value = line.slice(idx + 1).trim();
-		i++;
-		if (value === ">" || value === ">-" || value === "|" || value === "|-") {
-			const parts = [];
-			while (i < lines.length) {
-				const l = lines[i].replace(/\r$/, "");
-				if (l.trim() === "") {
-					i++;
-					continue;
-				}
-				if (l.length - l.trimStart().length === 0) break;
-				parts.push(l.trim());
-				i++;
-			}
-			value = parts.join(value.startsWith("|") ? "\n" : " ");
-		}
-		fm[key] = unquote(value);
-	}
+/**
+* Resolve what `unit spawn` should launch, from either an explicit `--harness` or an agent def
+* (`--agent` / `--agent-file`) whose harness, model and instructions compose the launch command.
+* An explicit `--harness` overrides the def's own.
+*
+* Extracted from the CLI action so the def→launch wiring is reachable from a test: composed inline
+* it sat between two well-covered halves (`resolveAgentDef`, `realizeLaunch`) with nothing
+* exercising the join between them.
+*/
+function resolveSpawnLaunch(input) {
+	if (!input.agent && !input.agentFile) return { harness: input.harness };
+	const realized = realizeLaunch(resolveAgentDef({
+		name: input.agent,
+		file: input.agentFile,
+		...input.cwd ? { cwd: input.cwd } : {},
+		...input.searchRoots ? { searchRoots: input.searchRoots } : {}
+	}), { harness: input.harness });
 	return {
-		fm,
-		instructions: rest.trim()
+		harness: realized.harness,
+		command: realized.command
 	};
 }
-function unquote(v) {
-	if (v.length >= 2 && (v.startsWith("\"") && v.endsWith("\"") || v.startsWith("'") && v.endsWith("'"))) return v.slice(1, -1);
-	return v;
-}
-function toBool(v) {
-	if (v === void 0) return void 0;
-	if (v === "true") return true;
-	if (v === "false") return false;
-}
-function toAgentDef(path, text, fallbackName) {
-	const { fm, instructions } = parseAgentDefFile(text);
-	return {
-		name: fm.name ?? fallbackName,
-		description: fm.description,
-		model: fm.model,
-		effort: fm.effort,
-		harness: fm.harness,
-		warm: toBool(fm.warm),
-		interactive: toBool(fm.interactive),
-		instructions,
-		path
-	};
-}
-/** The project's own `.agents/agents/` dir — the convention `agent list`/name-search scans. */
-function projectAgentsDir(cwd) {
-	return join(projectRoot(cwd), ".agents", "agents");
-}
-/** Resolve one agent definition, by explicit file or by name search. Throws a clear error when
-* neither locates a def — never returns a partial/empty result. */
-function resolveAgentDef(input) {
-	if (input.file) {
-		const path = resolve(input.file);
-		if (!existsSync(path)) throw new Error(`agent def file "${input.file}" does not exist`);
-		return toAgentDef(path, readFileSync(path, "utf8"), basename(path).replace(/\.md$/, ""));
-	}
-	if (!input.name) throw new Error("resolveAgentDef needs a --agent <name> or --agent-file <path>");
-	const roots = [...input.searchRoots ?? [], projectAgentsDir(input.cwd)];
-	for (const root of roots) {
-		const candidate = join(root, `${input.name}.md`);
-		if (existsSync(candidate)) return toAgentDef(candidate, readFileSync(candidate, "utf8"), input.name);
-	}
-	throw new Error(`no agent definition named "${input.name}" found under .agents/agents/`);
-}
-/** List every resolvable agent def under `.agents/agents/` (+ any extra search roots). Definitive
-* empty array when the dir is absent or empty — never throws for "none found" here (unlike a
-* named resolve, listing is inherently zero-or-more). */
-function listAgentDefs(input = {}) {
-	const roots = [...input.searchRoots ?? [], projectAgentsDir(input.cwd)];
-	const seen = /* @__PURE__ */ new Set();
-	const defs = [];
-	for (const root of roots) {
-		if (!existsSync(root)) continue;
-		for (const file of readdirSync(root)) {
-			if (!file.endsWith(".md")) continue;
-			const path = join(root, file);
-			if (seen.has(path)) continue;
-			seen.add(path);
-			defs.push(toAgentDef(path, readFileSync(path, "utf8"), file.replace(/\.md$/, "")));
-		}
-	}
-	return defs;
-}
 //#endregion
 //#region src/decommission.ts
 /**
@@ -1303,9 +1536,13 @@ function fail(msg) {
 //#region src/runtime/inject-inbox.ts
 const EVENTS = ["SessionStart", "PostToolUse"];
 /**
-* Resolve the calling agent, gather its pending brief + unread mail, and return the
-* SessionStart-style injection payload — or null when there is nothing to inject (an
-* unregistered caller or an empty inbox never fails the harness hook).
+* Resolve the calling agent, gather its unread mail (and a standing owner's, when this session is
+* the hub's main pane), and return the SessionStart-style injection payload — or null when there is
+* nothing to inject (an unregistered caller or an empty inbox never fails the harness hook).
+*
+* This never injects a brief. Brief delivery is the spawn wake's job: the first-turn doorbell
+* carries the instruction and names the brief's file path, so pickup does not depend on this hook
+* firing in the child (`unit/lifecycle`, superseding ADR-0027).
 */
 function injectInbox(ctx, event) {
 	if (!EVENTS.includes(event)) throw new Error(`unsupported --event "${event}" (expected ${EVENTS.join(" | ")})`);
@@ -1321,12 +1558,6 @@ function injectInbox(ctx, event) {
 	}
 	const parts = [];
 	const rec = loadAgent(ctx.store, meId);
-	if (rec?.status === "spawning") {
-		const brief = ctx.store.readBrief(meId);
-		if (brief) parts.push(`## Your brief\n\n${brief.trim()}`);
-		rec.status = "active";
-		saveAgent(ctx.store, rec);
-	}
 	const unread = inbox({ store: ctx.store }, {
 		meId,
 		unread: true
@@ -1557,4 +1788,4 @@ async function watchMail(ctx, input, onMessage, opts = {}) {
 	}
 }
 //#endregion
-export { loadAgent as A, resolveSelfId as B, spawn as C, clearPresence as D, claimPresence as E, register as F, projectRoot as G, touch as H, registerStanding as I, normalizeMuxEnv as J, resolveProjectLocalRoot as K, resolveAgent as L, prune as M, realExec as N, detectHarness as O, reconcile as P, resolvePresence as R, clearUnit as S, bumpLastSeen as T, ensureMarker as U, resolveStandingOwner as V, paths as W, install as _, emit as a, resolveAgentDef as b, toonList as c, deleteMessage as d, inbox as f, send as g, resolveBody as h, injectInbox as i, presenceOf as j, listAgents as k, toonObject as l, readAck as m, awaitReply as n, fail as o, peek as p, resolveRoot as q, FileStore as r, nextStep as s, watchMail as t, ack as u, decommission as v, selectSessionAdapter as w, realizeLaunch as x, listAgentDefs as y, resolveRecipient as z };
+export { resolveProjectLocalRoot as $, bumpLastSeen as A, registerStanding as B, nudgeUnit as C, selectSessionAdapter as D, spawnAndWake as E, loadAgent as F, resolveStandingOwner as G, resolvePresence as H, prune as I, listAgentDefs as J, touch as K, realExec as L, clearPresence as M, detectHarness as N, DELIVERY_DOORBELL as O, listAgents as P, projectRoot as Q, reconcile as R, focusUnit as S, spawn as T, resolveRecipient as U, resolveAgent as V, resolveSelfId as W, ensureMarker as X, resolveAgentDef as Y, paths as Z, install as _, emit as a, resolveSpawnLaunch as b, toonList as c, deleteMessage as d, resolveRoot as et, inbox as f, send as g, resolveBody as h, injectInbox as i, claimPresence as j, wakeRecipient as k, toonObject as l, readAck as m, awaitReply as n, fail as o, peek as p, normalizeMuxEnv as q, FileStore as r, nextStep as s, watchMail as t, ack as u, decommission as v, readUnit as w, clearUnit as x, realizeLaunch as y, register as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cyberlegion",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Harness-agnostic agent session spawning and messaging over the filesystem",
   "keywords": [
     "agent",