cyberlegion 1.2.0 → 1.4.0

package/dist/cli.mjs

@@ -5861,6 +5861,9 @@ function standingId(handle) {
 function registerStanding(ctx, input) {
 	ctx.store.ensureMarker();
 	const id = standingId(input.handle);
+	return ctx.store.withLock(`presence:${id}`, () => writeStanding(ctx, id, input));
+}
+function writeStanding(ctx, id, input) {
 	const existing = loadAgent(ctx.store, id);
 	const ts = nowIso(ctx);
 	const rec = {
@@ -5874,6 +5877,9 @@ function registerStanding(ctx, input) {
 		createdAt: existing?.createdAt ?? ts,
 		lastSeen: ts
 	};
+	if (existing?.presence !== void 0) rec.presence = existing.presence;
+	const home = input.home === void 0 ? existing?.home : input.home ?? void 0;
+	if (home) rec.home = home;
 	saveAgent(ctx.store, rec);
 	return rec;
 }
@@ -5889,10 +5895,15 @@ function gitWorktree(exec) {
 		]) ?? void 0
 	};
 }
-/** Prefer a standing record over a plain session record when both match a handle — an owner
-* report must land in the durable standing inbox, not a dying session's. */
-function preferStanding(matches) {
-	return matches.find((a) => a.kind === "standing") ?? matches[0];
+/** Pick the one live record a handle names. A standing record wins over the rest — an owner report
+* must land in the durable standing inbox, not a dying session's. Otherwise two or more matches are
+* ambiguous (two same-named repos give their service endpoints the same handle), and silently taking
+* the first could deliver to the wrong one, so fail loud naming the ids, as `resolveOwnerMailbox` does. */
+function pickLive(ref, live) {
+	const standing = live.find((a) => a.kind === "standing");
+	if (standing) return standing;
+	if (live.length > 1) throw new Error(`"${ref}" names ${live.length} units — pass an id (${live.map((a) => a.id).join(", ")})`);
+	return live[0];
 }
 /** Split a handle's matches into live and exited. An exited unit's pane is gone and its inbox has
 * no reader, so a *name* must never resolve to one — a handle is reusable across units, and the
@@ -6010,7 +6021,7 @@ function resolvePresence(store, handle) {
 function resolveRecipient(store, to) {
 	if (loadAgent(store, to)) return to;
 	const { live, exited } = matchHandle(listAgents(store), to);
-	const match = preferStanding(live);
+	const match = pickLive(to, live);
 	if (!match) throw unaddressable(to, exited, "id and handle");
 	return match.id;
 }
@@ -6024,7 +6035,7 @@ function resolveAgent(store, ref) {
 	if (byId) return byId;
 	const agents = listAgents(store);
 	const { live, exited } = matchHandle(agents, ref);
-	const byHandle = preferStanding(live);
+	const byHandle = pickLive(ref, live);
 	if (byHandle) return byHandle;
 	const byBranchAll = agents.filter((a) => a.worktree?.branch === ref);
 	const byBranch = byBranchAll.find((a) => a.status !== "exited");
@@ -6292,6 +6303,9 @@ const KILL_LINE = "";
 *   throws without sending. A multi-row draft cannot be typed back exactly: a scrape cannot tell a
 *   wrapped row from a newline, and a newline typed back would submit it.
 *
+* Text `ownText` recognizes is the caller's own, not a draft: it is cleared at once, whatever rows it
+* wraps onto, `send` runs, and nothing is typed back.
+*
 * Text the clear leaves in place was never a draft — an idle placeholder this reader does not know —
 * so `send` runs and nothing is typed back.
 */
@@ -6308,10 +6322,11 @@ async function withDraftGuard(adapter, exec, target, send, options = {}) {
 			return { kind: "unknown" };
 		}
 	};
+	const isOwn = (s) => s.kind === "draft" && options.ownText?.(s.text) === true;
 	let state = read();
 	const start = now();
 	let changedAt = start;
-	while (state.kind === "draft" && now() - changedAt < idleMs) {
+	while (state.kind === "draft" && !isOwn(state) && now() - changedAt < idleMs) {
 		if (now() - start + pollMs > maxWaitMs) throw new Error(`pane ${target.id} holds a draft the user is still editing — gave up after ${maxWaitMs / 1e3}s without typing`);
 		await sleep(pollMs);
 		const next = read();
@@ -6319,12 +6334,13 @@ async function withDraftGuard(adapter, exec, target, send, options = {}) {
 		state = next;
 	}
 	if (state.kind !== "draft") return send();
+	if (isOwn(state)) {
+		await clearLine(adapter, exec, target, sleep);
+		return send();
+	}
 	if (state.rows > 1) throw new Error(`pane ${target.id} holds an idle draft spanning ${state.rows} rows, which cannot be typed back exactly — left it untouched`);
 	const draft = state.text;
-	adapter.sendText(exec, target, END_OF_LINE);
-	await sleep(KEY_SETTLE_MS);
-	adapter.sendText(exec, target, KILL_LINE);
-	await sleep(KEY_SETTLE_MS);
+	await clearLine(adapter, exec, target, sleep);
 	const after = read();
 	if (after.kind === "draft" && after.text === draft) return send();
 	try {
@@ -6334,6 +6350,12 @@ async function withDraftGuard(adapter, exec, target, send, options = {}) {
 		adapter.sendText(exec, target, draft);
 	}
 }
+async function clearLine(adapter, exec, target, sleep) {
+	adapter.sendText(exec, target, END_OF_LINE);
+	await sleep(KEY_SETTLE_MS);
+	adapter.sendText(exec, target, KILL_LINE);
+	await sleep(KEY_SETTLE_MS);
+}
 //#endregion
 //#region src/console/ring.ts
 const DEFAULT_ATTEMPTS = 10;
@@ -6360,6 +6382,13 @@ function copiesOn(screen, message) {
 * the text, the one in the input box. Two or more new copies mean the harness also posted it above
 * the box, so the turn was taken and nothing is flushed. Text still at the bottom with only one new
 * copy is the swallowed Enter, and is flushed as before.
+*
+* With `requirePosted`, text gone from the box is not enough on its own: text typed before the harness
+* drew its input box, or wiped by a redraw, is gone too, and no turn was taken. The turn then counts
+* as taken only when a new copy of the text is on screen — the harness posted it to its transcript or
+* queue. Text that is neither staged nor posted is lost: after one more settle for a slow redraw, it
+* is typed again. It is opt-in because it needs the posted copy to stay on screen: a busy peer's
+* output can scroll earlier copies away, so a ring to it could read as lost and be typed twice.
 */
 async function ringTurn(adapter, exec, target, message, opts = {}) {
 	const attempts = opts.attempts ?? DEFAULT_ATTEMPTS;
@@ -6367,25 +6396,36 @@ async function ringTurn(adapter, exec, target, message, opts = {}) {
 	const sleep = opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
 	if (!adapter.paneExists(exec, target)) throw new Error(`nudge failed: pane ${target.id} no longer exists — the peer's session is gone, not busy.`);
 	const before = copiesOn(adapter.read(exec, target).text, message);
-	const taken = () => {
+	const check = () => {
 		const screen = adapter.read(exec, target).text;
-		return !isStaged(screen, message) || copiesOn(screen, message) >= before + 2;
+		const copies = copiesOn(screen, message);
+		if (isStaged(screen, message)) return copies >= before + 2 ? "taken" : "staged";
+		return copies > before || !opts.requirePosted ? "taken" : "lost";
 	};
 	adapter.submit(exec, target, message);
 	await sleep(settleMs);
-	if (taken()) return {
+	let state = check();
+	if (state === "taken") return {
 		taken: true,
 		resubmits: 0
 	};
+	let lostReads = state === "lost" ? 1 : 0;
 	for (let attempt = 1; attempt <= attempts; attempt++) {
-		adapter.submit(exec, target);
+		if (state === "staged") adapter.submit(exec, target);
+		else if (lostReads >= 2) {
+			adapter.submit(exec, target, message);
+			lostReads = 0;
+		}
 		await sleep(settleMs);
-		if (taken()) return {
+		state = check();
+		if (state === "taken") return {
 			taken: true,
 			resubmits: attempt
 		};
+		lostReads = state === "lost" ? lostReads + 1 : 0;
 	}
-	throw new Error(`nudge failed: peer at pane ${target.id} never took the turn — input still staged after ${attempts} re-submit attempts`);
+	const why = state === "lost" ? "the text vanished without the harness posting it" : `input still staged after ${attempts} re-submit attempts`;
+	throw new Error(`nudge failed: peer at pane ${target.id} never took the turn — ${why}`);
 }
 //#endregion
 //#region src/console/doorbell.ts
@@ -6404,6 +6444,28 @@ const DELIVERY_DOORBELL = "You have unread mail — check your inbox.";
 function spawnDoorbell(briefPath) {
 	return `Read your brief at ${briefPath}, then begin work.`;
 }
+const SPAWN_DOORBELL = /^Readyourbriefat.+,thenbeginwork\.$/;
+const RESUME_DOORBELL = /^Yoursessionwasrestartedwithitsconversationresumed—continueyourwork\.Ifyouhavenoearlierconversation,readyourbriefat.+,thenbeginwork\.$/;
+/**
+* Whether `text`, read out of a peer's input box, is a ring cyberlegion typed — the delivery doorbell,
+* a spawn or resume doorbell, or `message`, the one about to be rung — rather than a human's draft. A harness
+* can take a ring and put its text back in the box (cursor-agent with a rejected login). Whitespace is
+* ignored, since the box wraps the text onto rows wherever it likes.
+*/
+function isRingText(text, message) {
+	const squeeze = (s) => s.replace(/\s+/g, "");
+	const box = squeeze(text);
+	if (box === "") return false;
+	return box === squeeze("You have unread mail — check your inbox.") || SPAWN_DOORBELL.test(box) || RESUME_DOORBELL.test(box) || message !== void 0 && box === squeeze(message);
+}
+/**
+* The first-turn instruction for a restarted session that resumed its conversation. The resume can
+* fall back to a fresh session (the harness no longer has the conversation), and the ring cannot tell
+* which one took the turn, so it names the brief for a session that finds no earlier conversation.
+*/
+function resumeDoorbell(briefPath) {
+	return `Your session was restarted with its conversation resumed — continue your work. If you have no earlier conversation, 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
@@ -6415,6 +6477,11 @@ const SPAWN_NUDGE_OPTS = {
 	attempts: 20,
 	settleMs: 400
 };
+/** What a sender reads when a standing owner's home could not give it a presence. */
+function homeSpawnWarning(handle, err) {
+	const reason = err instanceof Error ? err.message : String(err);
+	return `standing owner "${handle}" has a home, but no presence could be spawned: ${reason}${/session backend/.test(reason) ? " — a sender outside any multiplexer pane can reach a running one by setting CYBER_MUX=herdr or CYBER_MUX=tmux" : ""}`;
+}
 /** 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);
@@ -6440,8 +6507,24 @@ async function wakeRecipient(store, getAdapter, exec, input, nudgeOpts, guardOpt
 	let pane;
 	let harness;
 	let focusGated = false;
+	let spawnWarning;
 	if (recipient.kind === "standing") {
-		const presenceUnit = presenceOf(store, recipient);
+		let presenceUnit = presenceOf(store, recipient);
+		if (!presenceUnit && recipient.home && input.spawnHome) try {
+			const outcome = await input.spawnHome(recipient);
+			if (outcome.kind === "existing") presenceUnit = outcome.presence;
+			else {
+				const warning = outcome.trustBlocked ?? outcome.warning;
+				return {
+					rung: outcome.rung,
+					pane: outcome.pane,
+					spawned: outcome.presence.id,
+					...warning ? { warning } : {}
+				};
+			}
+		} catch (err) {
+			spawnWarning = homeSpawnWarning(recipient.handle, err);
+		}
 		if (presenceUnit) {
 			pane = paneOf(store, presenceUnit.id);
 			harness = presenceUnit.harness;
@@ -6453,37 +6536,46 @@ async function wakeRecipient(store, getAdapter, exec, input, nudgeOpts, guardOpt
 		pane = paneOf(store, recipient.id);
 		harness = recipient.harness;
 	}
-	if (!pane) return { rung: false };
-	if (pane === paneOf(store, input.fromId)) return { rung: false };
-	if (focusGated) {
-		let focused;
+	const result = await ringResolved();
+	if (!spawnWarning) return result;
+	return {
+		...result,
+		warning: result.warning ? `${spawnWarning}; ${result.warning}` : spawnWarning
+	};
+	async function ringResolved() {
+		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 {
-			focused = getAdapter().isPaneFocused(exec, { id: pane });
-		} catch {
-			focused = void 0;
+			const adapter = getAdapter();
+			const target = { id: pane };
+			await withDraftGuard(adapter, exec, target, () => ringTurn(adapter, exec, target, DELIVERY_DOORBELL, nudgeOpts), {
+				...guardOpts,
+				harness,
+				ownText: (text) => isRingText(text)
+			});
+			return {
+				rung: true,
+				pane
+			};
+		} catch (err) {
+			return {
+				rung: false,
+				pane,
+				warning: err instanceof Error ? err.message : String(err)
+			};
 		}
-		if (focused === false) return {
-			rung: false,
-			pane
-		};
-	}
-	try {
-		const adapter = getAdapter();
-		const target = { id: pane };
-		await withDraftGuard(adapter, exec, target, () => ringTurn(adapter, exec, target, DELIVERY_DOORBELL, nudgeOpts), {
-			...guardOpts,
-			harness
-		});
-		return {
-			rung: true,
-			pane
-		};
-	} catch (err) {
-		return {
-			rung: false,
-			pane,
-			warning: err instanceof Error ? err.message : String(err)
-		};
 	}
 }
 /**
@@ -6497,6 +6589,11 @@ async function wakeRecipient(store, getAdapter, exec, input, nudgeOpts, guardOpt
 * ring that never completes within the retry budget is swallowed into a warning. This never throws —
 * it can never fail the spawn.
 *
+* The ring counts only once the harness posts the doorbell (`requirePosted`), not merely once it
+* leaves the input box: a doorbell typed before a booting harness drew its box vanishes the same way,
+* and nothing else will tell the peer its brief exists. A fresh session has no earlier copy to
+* scroll away, so the posted copy is a reliable sign here.
+*
 * 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.
@@ -6505,9 +6602,14 @@ async function wakeSpawn(getAdapter, exec, input, nudgeOpts = SPAWN_NUDGE_OPTS,
 	if (input.noWake) return { rung: false };
 	try {
 		const adapter = getAdapter();
-		await withDraftGuard(adapter, exec, input.target, () => ringTurn(adapter, exec, input.target, spawnDoorbell(input.briefPath), nudgeOpts), {
+		const doorbell = (input.resumed ? resumeDoorbell : spawnDoorbell)(input.briefPath);
+		await withDraftGuard(adapter, exec, input.target, () => ringTurn(adapter, exec, input.target, doorbell, {
+			...nudgeOpts,
+			requirePosted: true
+		}), {
 			...guardOpts,
-			harness: input.harness
+			harness: input.harness,
+			ownText: (text) => isRingText(text)
 		});
 		return {
 			rung: true,
@@ -6836,6 +6938,30 @@ function resetCommandFor(harness) {
 	if (FALSE_FRIEND_HARNESSES.has(harness)) throw new Error(`"${harness}" has no honest fresh-context command — its own "/clear" clears only the terminal screen, not the model context, so unit clear refuses to send a false-friend reset that would leave stale context behind`);
 	throw new Error(`"${harness}" is not in the reset map (${Object.keys(RESET_MAP).join(" | ")}) — unit clear refuses to guess a command`);
 }
+/** The primary checkout of the repository containing `repo`, asked of git from inside it (`git -C`)
+* rather than from the process cwd. */
+function primaryRootOfRepo(exec, repo) {
+	const dir = resolve(repo);
+	try {
+		return resolvePrimaryRoot((cmd, args) => exec(cmd, cmd === "git" ? [
+			"-C",
+			dir,
+			...args
+		] : args));
+	} catch {
+		throw new Error(`--repo ${repo} is not inside a git repository`);
+	}
+}
+/** The primary checkout of the repository containing `dir`, or `undefined` when `dir` is in no git
+* repository — for a folder that may sit outside any repository, where there is no primary checkout
+* to keep a unit out of. */
+function primaryRootOf$1(exec, dir) {
+	try {
+		return primaryRootOfRepo(exec, dir);
+	} catch {
+		return;
+	}
+}
 /**
 * 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
@@ -6859,9 +6985,9 @@ function spawn(ctx, input) {
 	if (!harness || !(harness in LAUNCH_MAP)) throw new Error(`spawn needs a --harness in the launch map (${Object.keys(LAUNCH_MAP).join(" | ")})`);
 	const brief = resolveBrief(input);
 	if (brief == null) throw new Error("spawn needs a brief — pass --task <text>, --task - (stdin), or --brief-file <path>");
-	if (input.cwd && (input.branch || input.worktreePath)) throw new Error("--cwd cannot combine with the worktree-creating flags --branch/--worktree-path");
+	if (input.cwd && (input.branch || input.worktreePath || input.repo)) throw new Error("--cwd cannot combine with the worktree-creating flags --branch/--worktree-path/--repo");
 	const id = randomId();
-	const primaryRoot = resolvePrimaryRoot(exec);
+	const primaryRoot = input.cwd !== void 0 && input.cwdOwnRepo === true ? primaryRootOf$1(exec, input.cwd) : input.repo ? primaryRootOfRepo(exec, input.repo) : resolvePrimaryRoot(exec);
 	const launch = input.command ?? LAUNCH_MAP[harness];
 	const launchLine = () => composeLaunchLine(ctx, sessionAdapter.name, id, launch);
 	const from = callerPane(sessionAdapter, normalizedEnv);
@@ -6871,7 +6997,7 @@ function spawn(ctx, input) {
 	if (input.cwd) {
 		if (!existsSync(input.cwd)) throw new Error(`--cwd directory must already exist: ${input.cwd}`);
 		cwd = resolve(input.cwd);
-		assertDistinctFromPrimary(cwd, primaryRoot);
+		if (primaryRoot !== void 0) assertDistinctFromPrimary(cwd, primaryRoot);
 		worktree = null;
 		const at = input.at ?? "tab";
 		target = sessionAdapter.open(exec, {
@@ -6882,6 +7008,7 @@ function spawn(ctx, input) {
 			...labelFor(at, input, brief, id)
 		});
 	} else {
+		if (primaryRoot === void 0) throw new Error("a worktree spawn needs a primary checkout");
 		const branch = input.branch ?? `cyberlegion/unit-${id}`;
 		const at = input.at ?? "workspace";
 		const worktreePath = input.worktreePath ?? resolveUnitWorktreePath(primaryRoot, id.slice(0, 6));
@@ -6974,15 +7101,39 @@ function spawn(ctx, input) {
 */
 async function spawnAndWake(ctx, input, options = {}) {
 	const res = spawn(ctx, input);
-	const env = ctx.env ?? process.env;
-	const exec = ctx.exec ?? realExec;
-	const trust = await settleTrust(ctx, res, options.trustOpts);
-	if (trust.state === "needs-human" || trust.state === "stuck") return {
+	const trust = await settleSpawnTrust(ctx, res, options);
+	if (trust.trustBlocked) return {
+		...res,
+		...trust
+	};
+	return {
 		...res,
+		...await ringSpawnFirstTurn(ctx, res, trust, options)
+	};
+}
+/**
+* Settle a just-spawned unit's folder-trust prompt — the first half of `spawnAndWake` after the spawn
+* itself. Split from the ring so `spawnPresence` (`presence-spawn.ts`) can hold the presence lock
+* across this step and release it before the ring. `trustFolder` says a person already vouched for
+* this folder (a standing owner's registered home), so its prompt is accepted as a worktree spawn's is.
+*/
+async function settleSpawnTrust(ctx, res, options) {
+	const trust = await settleTrust(ctx, res, options.trustOpts, options.trustFolder);
+	if (trust.state === "needs-human" || trust.state === "stuck") return {
 		rung: false,
 		trust: trust.state,
 		trustBlocked: trust.message
 	};
+	return {
+		rung: false,
+		trust: trust.state
+	};
+}
+/** Ring a just-spawned unit's first turn once its trust prompt has settled — the second half of
+* `spawnAndWake`. */
+async function ringSpawnFirstTurn(ctx, res, trust, options) {
+	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 },
@@ -6991,9 +7142,8 @@ async function spawnAndWake(ctx, input, options = {}) {
 		harness: res.agent.harness
 	}, options.nudgeOpts);
 	return {
-		...res,
 		rung: wake.rung,
-		trust: trust.state,
+		trust: trust.trust,
 		...wake.warning ? { warning: wake.warning } : {}
 	};
 }
@@ -7002,7 +7152,7 @@ async function spawnAndWake(ctx, input, options = {}) {
 * resolved leaves nothing to read, which is no evidence of a prompt: the ring's own containment
 * reports that backend.
 */
-async function settleTrust(ctx, res, opts) {
+async function settleTrust(ctx, res, opts, trustFolder = false) {
 	const exec = ctx.exec ?? realExec;
 	let adapter;
 	try {
@@ -7014,7 +7164,7 @@ async function settleTrust(ctx, res, opts) {
 		harness: res.agent.harness,
 		folder: res.agent.cwd,
 		pane: res.pane,
-		policy: res.agent.worktree ? "accept" : "ask"
+		policy: res.agent.worktree || trustFolder ? "accept" : "ask"
 	}, opts);
 }
 /**
@@ -7041,10 +7191,43 @@ function labelFor(at, input, brief, id) {
 * supplied `ctx.self`), the multiplexer env prefix, then the harness launch command. Writes the shim
 * as a side effect, so call it only past every refusal, right before the session opens. Shared by
 * `spawn` and `unit restart` so a restarted unit boots exactly as a spawned one does.
+*
+* `bindSelf` has the new pane run `unit rebind <id>` through the shim before the harness starts, so
+* the session binds itself to the unit even when the caller dies before its own bind write. It needs
+* the shim, so a context with no recorded invocation gets no bind step.
+*/
+function composeLaunchLine(ctx, muxName, id, launch, options = {}) {
+	const shim = ctx.self ? writeSelfShim(paths.dataDir(ctx.store.root, id), ctx.self) : void 0;
+	const bind = shim && options.bindSelf ? `${shellQuote$1(shim)} unit rebind ${shellQuote$1(id)} --space ${shellQuote$1(ctx.store.root)} >/dev/null 2>&1; ` : "";
+	const prefix = `${shim ? shimEnvPrefix(shim) : ""}${muxEnvPrefix(muxName)}`;
+	return `${bind}${prefix}${launch}${options.fallback ? ` || ${prefix}${options.fallback}` : ""}`;
+}
+/**
+* How each harness resumes a conversation by id, appended to the unit's own launch command. Cursor is
+* absent: its hook's id is not confirmed to be the chat id `cursor-agent --resume` takes, so a cursor
+* unit restarts fresh and is rebriefed.
+*/
+const RESUME_MAP = {
+	claude: (id) => `--resume ${shellQuote$1(id)}`,
+	codex: (id) => `resume ${shellQuote$1(id)}`
+};
+/**
+* The launch that resumes `conversation`, or undefined when this harness has no resume here or the
+* launch is not the harness's own command — a wrapper script may not take the harness's flags.
+*/
+function resumeLaunch(harness, launch, conversation) {
+	const resume = RESUME_MAP[harness];
+	if (!resume || launch.split(/\s+/)[0] !== LAUNCH_MAP[harness]) return void 0;
+	return `${launch} ${resume(conversation)}`;
+}
+/**
+* Put the shim's directory first on PATH, so a brief's bare `cyberlegion` runs it, and name the shim
+* itself in `$CYBERLEGION_CLI`. The plugin's hook runs outside that PATH lookup (and a PATH lookup
+* cannot tell this shim from a stale global install), so it reads the variable instead: set only
+* here, it marks a spawned session and names the CLI that spawned it.
 */
-function composeLaunchLine(ctx, muxName, id, launch) {
-	const shimDir = ctx.self ? writeSelfShim(paths.dataDir(ctx.store.root, id), ctx.self) : void 0;
-	return `${shimDir ? `PATH=${shellQuote$1(shimDir)}:"$PATH" ` : ""}${muxEnvPrefix(muxName)}${launch}`;
+function shimEnvPrefix(shim) {
+	return `PATH=${shellQuote$1(dirname(shim))}:"$PATH" CYBERLEGION_CLI=${shellQuote$1(shim)} `;
 }
 /**
 * The env prefix typed ahead of the launch command so the spawned peer inherits the caller's
@@ -7073,7 +7256,7 @@ function selfInvocation() {
 }
 /**
 * Write `<dataDir>/bin/cyberlegion`, a POSIX shim that execs `self` with the caller's arguments,
-* and return its directory. A spawned session gets that directory first on its PATH, so the
+* and return its path. A spawned session gets that directory first on its PATH, so the
 * `cyberlegion` a brief tells it to run is the install that spawned it: nothing is resolved from
 * the registry or the session's own PATH at report time.
 */
@@ -7083,7 +7266,7 @@ function writeSelfShim(dataDir, self) {
 	const shim = join(dir, "cyberlegion");
 	writeFileSync(shim, `#!/bin/sh\nexec ${self.map(shellQuote$1).join(" ")} "$@"\n`);
 	chmodSync(shim, 493);
-	return dir;
+	return shim;
 }
 /** Single-quote `s` for a POSIX shell, so any path survives word splitting and expansion. */
 function shellQuote$1(s) {
@@ -7135,7 +7318,8 @@ async function nudgeUnit(ctx, ref, options = {}) {
 	const adapter = selectSessionAdapter(ctx.env ?? process.env, exec);
 	const result = await withDraftGuard(adapter, exec, target, () => ringTurn(adapter, exec, target, message, options.nudgeOpts), {
 		...options.guardOpts,
-		harness: agent.harness
+		harness: agent.harness,
+		ownText: (text) => isRingText(text, message)
 	});
 	return {
 		agent,
@@ -7174,7 +7358,8 @@ async function clearUnit(ctx, ref, options = {}) {
 	const adapter = selectSessionAdapter(env, exec);
 	await withDraftGuard(adapter, exec, target, async () => adapter.submit(exec, target, command), {
 		...options.guardOpts,
-		harness: agent.harness
+		harness: agent.harness,
+		ownText: (text) => isRingText(text)
 	});
 	return {
 		agent,
@@ -7469,6 +7654,7 @@ function spawnCommandInput(opts, listCursorModels) {
 			branch: opts.branch,
 			worktreePath: opts.worktreePath,
 			cwd: opts.cwd,
+			repo: opts.repo,
 			at: opts.at
 		},
 		noWake: opts.wake === false,
@@ -7860,6 +8046,154 @@ function fail(msg) {
 	process.exit(1);
 }
 //#endregion
+//#region src/permission.ts
+const CLI_RULE = "Bash(cyberlegion *)";
+const COVERING = /^Bash(?:\((?:\*|cyberlegion(?: \*|:\*|\*))\))?$/;
+/** Claude Code's user settings file: `$CLAUDE_CONFIG_DIR/settings.json`, else `~/.claude/settings.json`. */
+function claudeUserSettingsFile(env = process.env) {
+	return join(env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude"), "settings.json");
+}
+function readSettings(file) {
+	if (!existsSync(file)) return {
+		settings: {},
+		allow: []
+	};
+	let settings;
+	try {
+		settings = JSON.parse(readFileSync(file, "utf8"));
+	} catch {
+		throw new Error(`cannot parse Claude Code settings ${file} — fix it by hand, then re-run`);
+	}
+	if (typeof settings !== "object" || settings === null || Array.isArray(settings)) throw new Error(`Claude Code settings ${file} is not a JSON object — fix it by hand, then re-run`);
+	const { permissions } = settings;
+	const allow = permissions?.allow ?? [];
+	if (permissions !== void 0 && (typeof permissions !== "object" || permissions === null) || !Array.isArray(allow)) throw new Error(`Claude Code settings ${file} has a malformed permissions.allow — fix it by hand, then re-run`);
+	return {
+		settings,
+		allow
+	};
+}
+const covers = (allow) => allow.some((rule) => typeof rule === "string" && COVERING.test(rule));
+/** Whether the settings file's allow list already lets `cyberlegion` subcommands run. */
+function permissionRuleState(file) {
+	try {
+		return covers(readSettings(file).allow) ? "present" : "missing";
+	} catch {
+		return "unreadable";
+	}
+}
+/**
+* Add the CLI rule to the settings file's allow list, merged in after every existing entry. A
+* covering rule already there is a no-op; a file that cannot be read as settings is never rewritten.
+*/
+function addPermissionRule(file) {
+	const { settings, allow } = readSettings(file);
+	if (covers(allow)) return "present";
+	settings.permissions = {
+		...settings.permissions ?? {},
+		allow: [...allow, CLI_RULE]
+	};
+	mkdirSync(dirname(file), { recursive: true });
+	writeFileSync(file, `${JSON.stringify(settings, null, 2)}\n`);
+	return "added";
+}
+//#endregion
+//#region src/presence-spawn.ts
+/** The brief a presence spawned into a standing owner's home starts from: whom it stands in for, and
+* where that owner's mail is. What to *do* with the mail is the home's agent definition's business. */
+function presenceBrief(handle) {
+	return [
+		`You stand in for the standing owner "${handle}": you are its presence, spawned because mail was delivered to it and no unit was standing in.`,
+		"",
+		`Read its mail: cyberlegion mail inbox --owner ${handle}, then cyberlegion mail read --owner ${handle} <id>.`,
+		`Ack what you have handled: cyberlegion mail ack --owner ${handle} <id>.`
+	].join("\n");
+}
+/**
+* Give a standing owner with a home a presence: spawn a unit in the home and bind it, unless a live
+* presence already exists — the delivery doorbell's step when mail arrives and nobody is standing in.
+*
+* Under the presence lock (the one `unit claim` takes) it re-reads the owner and decides there, so
+* two near-simultaneous deliveries spawn one unit: the second finds the first's presence live and
+* gets it back as `existing`, to ring like any presence. The lock covers the re-read, the spawn (open
+* the pane, write the record and brief), the bind, and the trust step, so no other delivery can ring
+* the new presence while its trust prompt may be showing. Only the first-turn ring runs after it is
+* released. A delivery that waits past the lock's bound takes the doorbell's lock-timeout warning;
+* its message is already in the inbox the new presence is about to read.
+*
+* The spawn opens its own workspace — never a tab or split of the sender's space, since the sender is
+* not its parent and may be in no pane — launched from the home's agent definition (resolved from the
+* home) or its harness. The home's trust prompt is accepted: a person named the folder at
+* `unit register --standing --home`. A prompt left showing anyway means the unit cannot read its
+* brief, so it is unbound again (if still the presence, before the lock is released) rather than left
+* for later deliveries to ring — a ring typed into a trust prompt answers it wrongly.
+*
+* Throws when the spawn cannot happen (no multiplexer, a missing home, an unresolvable definition, a
+* lock timeout). The doorbell turns that into a warning.
+*/
+async function spawnPresence(ctx, owner, options = {}) {
+	const home = owner.home;
+	if (!home) throw new Error(`standing owner "${owner.handle}" has no home`);
+	const outcome = await ctx.store.withLockAsync(`presence:${owner.id}`, async () => {
+		const current = loadAgent(ctx.store, owner.id);
+		if (!current) throw new Error(`standing owner "${owner.handle}" is gone`);
+		const live = presenceOf(ctx.store, current);
+		if (live) return { existing: live };
+		const launched = resolveSpawnLaunch({
+			agent: home.agent,
+			harness: home.harness,
+			cwd: home.dir
+		});
+		const res = spawn(ctx, {
+			harness: launched.harness,
+			command: launched.command,
+			briefInstructions: launched.briefInstructions,
+			task: presenceBrief(owner.handle),
+			cwd: home.dir,
+			cwdOwnRepo: true,
+			at: "workspace"
+		});
+		current.presence = res.agent.id;
+		saveAgent(ctx.store, current);
+		const unbind = () => {
+			const latest = loadAgent(ctx.store, owner.id);
+			if (latest?.presence !== res.agent.id) return false;
+			latest.presence = void 0;
+			saveAgent(ctx.store, latest);
+			return true;
+		};
+		let trust;
+		try {
+			trust = await settleSpawnTrust(ctx, res, {
+				...options,
+				trustFolder: true
+			});
+		} catch (err) {
+			unbind();
+			throw err;
+		}
+		const unbound = trust.trustBlocked ? unbind() : false;
+		return {
+			spawned: res,
+			trust,
+			unbound
+		};
+	});
+	if (outcome.existing) return {
+		kind: "existing",
+		presence: outcome.existing
+	};
+	const { spawned: res, trust, unbound } = outcome;
+	const turn = trust.trustBlocked ? trust : await ringSpawnFirstTurn(ctx, res, trust, options);
+	return {
+		kind: "spawned",
+		presence: res.agent,
+		pane: res.pane,
+		unbound,
+		...turn
+	};
+}
+//#endregion
 //#region src/project.ts
 /**
 * The canonical git common dir for `dir`, or undefined outside a repository. The common dir is the
@@ -8342,6 +8676,54 @@ async function startService(ctx, projectRef, name, input) {
 	}
 }
 //#endregion
+//#region src/standing-home.ts
+/**
+* Decide what a registration does to a standing owner's home: `undefined` keeps whatever the record
+* already has, `null` drops it, and a `StandingHome` replaces it. Every way a home can be wrong is
+* refused here, before anything is written — a failure found at delivery time could only be a warning
+* on someone else's send.
+*
+* The checks run in a fixed order so that a combination matching two refusals gets the first:
+* a home flag outside a named standing registration, then `--home` with `--clear-home`, then a launch
+* with no `--home`, then the folder, the launch, and the primary checkout.
+*
+* `--harness` is a home flag only on a standing registration; a plain `unit register` takes it for
+* the session itself.
+*/
+function resolveHomeFlags(exec, flags) {
+	if ((flags.home !== void 0 || flags.clearHome === true || flags.agent !== void 0) && !(flags.standing && flags.handle)) throw new Error("a home belongs only to a named standing owner — pass --standing --handle <name>");
+	if (!flags.standing) return void 0;
+	if (flags.home !== void 0 && flags.clearHome) throw new Error("--home and --clear-home contradict — pass one");
+	if (flags.home === void 0 && (flags.agent !== void 0 || flags.harness !== void 0)) throw new Error("a launch needs --home: --agent and --harness name how to start a session in it");
+	if (flags.clearHome) return null;
+	if (flags.home === void 0) return void 0;
+	const dir = resolve(flags.home);
+	if (!existsSync(dir) || !statSync(dir).isDirectory()) throw new Error(`the home must already exist: ${flags.home}`);
+	if (flags.agent === void 0 === (flags.harness === void 0)) throw new Error("a home needs exactly one of --agent or --harness");
+	let launch;
+	if (flags.harness !== void 0) {
+		if (!(flags.harness in LAUNCH_MAP)) throw new Error(`unrecognized --harness "${flags.harness}" (${Object.keys(LAUNCH_MAP).join(" | ")})`);
+		launch = { harness: flags.harness };
+	} else {
+		const agent = flags.agent;
+		try {
+			resolveAgentDef({
+				name: agent,
+				cwd: dir
+			});
+		} catch {
+			throw new Error(`the agent definition "${agent}" does not resolve from the home ${dir}`);
+		}
+		launch = { agent };
+	}
+	const primary = primaryRootOf$1(exec, dir);
+	if (primary !== void 0 && realpathSync(primary) === realpathSync(dir)) throw new Error(`the home refuses the primary checkout ${dir} — a spawned unit never works there`);
+	return {
+		dir,
+		...launch
+	};
+}
+//#endregion
 //#region src/store/errors.ts
 /** A record file exists but its content didn't parse as JSON — a torn write (crash mid-`writeFileSync`,
 * pre-atomic-write code path) or on-disk tampering. Carries the file path and the original parse
@@ -8504,6 +8886,16 @@ function withLock(root, name, fn, opts) {
 		handle.release();
 	}
 }
+/** `withLock` for an async read-decide-write: the lock is held until `fn`'s promise settles, not
+* merely until it returns one. The wait to acquire is the same bounded, synchronous one. */
+async function withLockAsync(root, name, fn, opts) {
+	const handle = acquireLock(root, name, opts);
+	try {
+		return await fn();
+	} finally {
+		handle.release();
+	}
+}
 //#endregion
 //#region src/store/file-store.ts
 /** Parse a record file's content, wrapping a `JSON.parse` failure in a typed, file-named
@@ -8707,6 +9099,9 @@ var FileStore = class {
 	withLock(name, fn) {
 		return withLock(this.root, name, fn);
 	}
+	withLockAsync(name, fn) {
+		return withLockAsync(this.root, name, fn);
+	}
 };
 //#endregion
 //#region src/unit-runtime.ts
@@ -8794,8 +9189,11 @@ function stopUnit(ctx, ref) {
 /**
 * Give a unit a fresh runtime and keep the unit: stop a still-running session (the same verified stop
 * as `stopUnit`), open a new session at the unit's cwd with the launch it was spawned with, bind the
-* record to the new pane, and ring it to read its brief — a rebrief, since a new session starts with
-* an empty context. Every refusal runs before anything is torn down.
+* record to the new pane, and ring it. When the record carries the harness's conversation id and the
+* harness can resume by id, the session resumes that conversation and is rung to continue, with the
+* plain launch as a shell fallback should the harness reject the id; otherwise (or with `fresh`) it
+* starts empty and is rung to read its brief — a rebrief. Every refusal runs before anything is torn
+* down.
 *
 * The unit is recorded `stopped` before the open, so a restart interrupted between the two leaves an
 * ordinary stopped unit and a rerun recovers it; nothing needs a separate repair path.
@@ -8817,6 +9215,7 @@ async function restartUnit(ctx, ref, options = {}) {
 	const env = ctx.env ?? process.env;
 	const exec = ctx.exec ?? realExec;
 	const launch = stopped.launch ?? LAUNCH_MAP[harness];
+	const resume = stopped.conversation && !options.fresh ? resumeLaunch(harness, launch, stopped.conversation) : void 0;
 	const at = stopped.worktree ? "workspace" : "tab";
 	let target;
 	let adapter;
@@ -8829,7 +9228,10 @@ async function restartUnit(ctx, ref, options = {}) {
 		}) } : {};
 		target = adapter.open(exec, {
 			cwd: stopped.cwd,
-			launch: composeLaunchLine(ctx, adapter.name, rec.id, launch),
+			launch: resume ? composeLaunchLine(ctx, adapter.name, rec.id, resume, {
+				bindSelf: true,
+				fallback: launch
+			}) : composeLaunchLine(ctx, adapter.name, rec.id, launch, { bindSelf: true }),
 			at,
 			from: callerPane(adapter, normalizeMuxEnv(env)),
 			...label
@@ -8853,13 +9255,15 @@ async function restartUnit(ctx, ref, options = {}) {
 	const wake = await wakeSpawn(() => adapter, exec, {
 		target,
 		briefPath: briefPath ?? "",
-		noWake: options.noWake || !briefPath
+		noWake: options.noWake || !briefPath,
+		resumed: !!resume
 	}, options.nudgeOpts);
 	return {
 		agent: bound,
 		...previousPane ? { previousPane } : {},
 		pane: target.id,
 		launch,
+		resumed: !!resume,
 		rung: wake.rung,
 		...wake.warning ? { warning: wake.warning } : {}
 	};
@@ -8957,6 +9361,29 @@ function showUnit(ctx, ref) {
 		controls: controlsFor(ctx, rec, liveness)
 	};
 }
+/**
+* Record the harness's conversation id on the calling unit, from the JSON its SessionStart hook hands
+* `mail hook` on stdin (`session_id`, which Claude Code and Codex both send). The hook fires on every
+* session start in the pane — a fresh start, a resume, a `/clear` — so the record follows the
+* conversation the pane is in now. Best-effort and silent: an unparseable input, no id, or a caller
+* that is not a unit records nothing and never fails the harness hook.
+*/
+function recordConversation(ctx, hookInput) {
+	let id;
+	try {
+		id = JSON.parse(hookInput)?.session_id;
+	} catch {
+		return;
+	}
+	if (typeof id !== "string" || id === "") return;
+	const meId = resolveSelfId(ctx);
+	const rec = meId ? loadAgent(ctx.store, meId) : void 0;
+	if (!rec || rec.kind === "standing" || rec.kind === "service" || rec.conversation === id) return;
+	saveAgent(ctx.store, {
+		...rec,
+		conversation: id
+	});
+}
 //#endregion
 //#region src/wake/await.ts
 /** Internal poll interval — not user-facing (the round-trip cost of one `mail await` cycle). */
@@ -9062,7 +9489,7 @@ const program = new Command();
 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) {
+function runStanding(ctx, opts, home) {
 	if (!opts.handle) {
 		const standing = listAgents(ctx.store).filter((a) => a.kind === "standing");
 		emit(formatOf(opts), {
@@ -9089,22 +9516,33 @@ function runStanding(ctx, opts) {
 		return;
 	}
 	const liveClaim = listAgents(ctx.store).find((a) => a.handle === opts.handle && a.kind !== "standing" && a.status !== "exited");
-	const rec = registerStanding(ctx, { handle: opts.handle });
+	const rec = registerStanding(ctx, {
+		handle: opts.handle,
+		home
+	});
 	if (liveClaim) console.error(`a live session already claims handle "${opts.handle}"`);
 	emit(formatOf(opts), {
 		toon: toonObject({
 			id: rec.id,
 			handle: rec.handle,
 			kind: rec.kind,
-			status: rec.status
+			status: rec.status,
+			home: rec.home?.dir ?? "none",
+			...rec.home ? { launch: rec.home.agent ? `agent ${rec.home.agent}` : `harness ${rec.home.harness}` } : {}
 		}),
 		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) => {
+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)").option("--home <dir>", "with --standing: the existing folder a presence is spawned in when mail arrives and none is live").option("--agent <name>", "with --home: launch that agent definition, resolved from the home").option("--clear-home", "with --standing: drop the owner's home").action((opts) => {
 	const ctx = ctxOf(opts);
+	let home;
+	try {
+		home = resolveHomeFlags(ctx.exec ?? realExec, opts);
+	} catch (err) {
+		fail(err instanceof Error ? err.message : String(err));
+	}
 	if (opts.standing) {
-		runStanding(ctx, opts);
+		runStanding(ctx, opts, home);
 		return;
 	}
 	const rec = register(ctx, {
@@ -9249,7 +9687,7 @@ function warnEffortNotApplied(spawnInput) {
 }
 /** The launch options `unit spawn` and `service start` share. */
 function withSpawnOptions(cmd) {
-	return withGlobals(cmd).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/effort/instructions").option("--agent-file <path>", "read an exact agent def file instead of resolving by name").option("--model <name>", "model for this launch only (flag > agent def > harness default)").option("--effort <level>", "effort for this launch only (flag > agent def > harness default)").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([
+	return withGlobals(cmd).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/effort/instructions").option("--agent-file <path>", "read an exact agent def file instead of resolving by name").option("--model <name>", "model for this launch only (flag > agent def > harness default)").option("--effort <level>", "effort for this launch only (flag > agent def > harness default)").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("-C, --repo <path>", "create the worktree from the git repository containing <path>, not the current directory's").option("--cwd <path>", "spawn the session in an existing directory; create no worktree (mutually exclusive with --branch/--worktree-path/--repo)").addOption(new Option("--at <placement>", "where to open the new session (default: new-worktree → workspace, --cwd → tab)").choices([
 		"pane:right",
 		"pane:down",
 		"tab",
@@ -9349,15 +9787,19 @@ withGlobals(unit.command("stop")).description("end a unit's session and keep the
 	});
 	if (!res.alreadyStopped) nextStep(`cyberlegion unit restart ${res.agent.handle}`);
 });
-withGlobals(unit.command("restart")).description("give a unit a fresh session and keep the unit — stops a running session, relaunches it, and rebriefs it").argument("<ref>", "unit id, handle, or worktree branch/CR ref").option("--no-wake", "do not ring the new session to read its brief (the caller briefs it by mail)").action(async (ref, opts) => {
+withGlobals(unit.command("restart")).description("give a unit a new session and keep the unit — stops a running session, relaunches it resuming the harness's recorded conversation where it can, and otherwise rebriefs it").argument("<ref>", "unit id, handle, or worktree branch/CR ref").option("--no-wake", "do not ring the new session to read its brief (the caller briefs it by mail)").option("--fresh", "start an empty session and rebrief it, even when the unit's conversation could be resumed").action(async (ref, opts) => {
 	const ctx = ctxOf(opts);
 	touch(ctx);
-	const res = await restartUnit(ctx, ref, { noWake: opts.wake === false });
+	const res = await restartUnit(ctx, ref, {
+		noWake: opts.wake === false,
+		fresh: opts.fresh === true
+	});
 	emit(formatOf(opts), {
 		toon: toonObject({
 			restarted: res.agent.id,
 			previous: res.previousPane ?? "-",
 			pane: res.pane,
+			resumed: res.resumed,
 			rung: res.rung
 		}),
 		json: res
@@ -9677,7 +10119,8 @@ function defineSend(cmd) {
 		const wake = await wakeRecipient(ctx.store, () => selectSessionAdapter(ctx.env ?? process.env), realExec, {
 			toId: msg.to,
 			fromId,
-			noNudge: opts.nudge === false
+			noNudge: opts.nudge === false,
+			spawnHome: (owner) => spawnPresence(ctx, owner)
 		});
 		if (wake.warning) console.error(`delivery doorbell not confirmed (message still delivered): ${wake.warning}`);
 		emit(formatOf(opts), {
@@ -9685,11 +10128,13 @@ function defineSend(cmd) {
 				sent: msg.id,
 				to: opts.to,
 				subject: msg.subject,
-				rung: wake.rung
+				rung: wake.rung,
+				...wake.spawned ? { spawned: wake.spawned } : {}
 			}),
 			json: {
 				...msg,
-				rung: wake.rung
+				rung: wake.rung,
+				...wake.spawned ? { spawned: wake.spawned } : {}
 			}
 		});
 	});
@@ -9841,6 +10286,9 @@ withGlobals(mail.command("watch")).description("stream new matching mail as it a
 withGlobals(mail.command("hook")).description("emit the harness hook injection payload (raw JSON on stdout, not TOON)").option("--event <event>", "SessionStart", "SessionStart").action((opts) => {
 	const ctx = ctxOf(opts);
 	touch(ctx);
+	if (!process.stdin.isTTY) try {
+		recordConversation(ctx, readFileSync(0, "utf8"));
+	} catch {}
 	const payload = injectInbox(ctx, opts.event);
 	if (payload) console.log(JSON.stringify(payload));
 });
@@ -9935,30 +10383,33 @@ withGlobals(agent.command("path")).description("print the resolved def file path
 		json: { path: def.path }
 	});
 });
+const ALLOW_CLI_HINT = `cyberlegion init --allow-cli to add ${CLI_RULE} to Claude Code's permissions.allow, so units can mail their results back`;
 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, normalizeMuxEnv(ctx.env ?? process.env));
 	const selfId = resolveSelfId(ctx) ?? "-";
+	const permissionRule = harness === "claude" ? permissionRuleState(claudeUserSettingsFile(ctx.env ?? process.env)) : "n/a";
+	const report = {
+		harness,
+		mux: probe.mux,
+		pane: probe.pane,
+		via: probe.via,
+		hubRoot: ctx.store.root,
+		selfId
+	};
 	emit(formatOf(opts), {
 		toon: toonObject({
-			harness,
-			mux: probe.mux,
-			pane: probe.pane,
-			via: probe.via,
-			hubRoot: ctx.store.root,
-			selfId
+			...report,
+			permissionRule
 		}),
 		json: {
-			harness,
-			mux: probe.mux,
-			pane: probe.pane,
-			via: probe.via,
-			hubRoot: ctx.store.root,
-			selfId
+			...report,
+			permissionRule
 		}
 	});
+	if (permissionRule === "missing") nextStep(ALLOW_CLI_HINT);
 	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(mux.command("mode")).description("report the detected session-backend mode").action((opts) => {
@@ -10009,7 +10460,7 @@ withGlobals(program.command("admin").description("hub-state maintenance").comman
 		json: res
 	});
 });
-withGlobals(program.command("init")).description("resolve this session harness, set up 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 the npx fallback of the cursor hook fetches (e.g. the bundled plugin version)").action((opts) => {
+withGlobals(program.command("init")).description("resolve this session harness, set up 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 the npx fallback of the cursor hook fetches (e.g. the bundled plugin version)").option("--allow-cli", `add ${CLI_RULE} to Claude Code's user permissions.allow (claude only)`).action((opts) => {
 	const ctx = ctxOf(opts);
 	let harness;
 	try {
@@ -10019,6 +10470,16 @@ withGlobals(program.command("init")).description("resolve this session harness,
 	} catch (err) {
 		fail(err instanceof Error ? err.message : String(err));
 	}
+	if (opts.allowCli && harness !== "claude") fail(`--allow-cli applies to claude only, not ${harness}`);
+	let permissionRule;
+	if (harness === "claude") {
+		const settingsFile = claudeUserSettingsFile(ctx.env ?? process.env);
+		try {
+			permissionRule = opts.allowCli ? addPermissionRule(settingsFile) : permissionRuleState(settingsFile);
+		} catch (err) {
+			fail(err instanceof Error ? err.message : String(err));
+		}
+	}
 	let results;
 	try {
 		results = install(harness, opts.dir, opts.pin);
@@ -10039,12 +10500,14 @@ withGlobals(program.command("init")).description("resolve this session harness,
 				key: "file",
 				get: (r) => r.file
 			}
-		], `harness ${harness}, ${results.length} hooks`),
+		], `harness ${harness}, ${results.length} hooks${permissionRule ? `, permission rule ${permissionRule}` : ""}`),
 		json: {
 			harness,
-			hooks: results
+			hooks: results,
+			...permissionRule && { permissionRule }
 		}
 	});
+	if (permissionRule === "missing") nextStep(ALLOW_CLI_HINT);
 	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");