cyberlegion 1.3.0 → 1.4.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "cyberlegion",
-	"version": "1.3.0",
+	"version": "1.4.1",
 	"description": "Agent session spawning, messaging, and dispatch — the Legion and its Legate.",
 	"author": {
 		"name": "unional"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "cyberlegion",
-	"version": "1.3.0",
+	"version": "1.4.1",
 	"description": "Agent session spawning, messaging, and dispatch — the Legion and its Legate.",
 	"author": {
 		"name": "unional"

package/.plugin/pins.json

@@ -1,3 +1,3 @@
 {
-	"cyberlegion": "1.3.0"
+	"cyberlegion": "1.4.1"
 }

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");
@@ -6371,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;
@@ -6378,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
@@ -6448,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);
@@ -6473,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;
@@ -6486,38 +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,
-			ownText: (text) => isRingText(text)
-		});
-		return {
-			rung: true,
-			pane
-		};
-	} catch (err) {
-		return {
-			rung: false,
-			pane,
-			warning: err instanceof Error ? err.message : String(err)
-		};
 	}
 }
 /**
@@ -6531,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.
@@ -6540,7 +6603,10 @@ async function wakeSpawn(getAdapter, exec, input, nudgeOpts = SPAWN_NUDGE_OPTS,
 	try {
 		const adapter = getAdapter();
 		const doorbell = (input.resumed ? resumeDoorbell : spawnDoorbell)(input.briefPath);
-		await withDraftGuard(adapter, exec, input.target, () => ringTurn(adapter, exec, input.target, doorbell, nudgeOpts), {
+		await withDraftGuard(adapter, exec, input.target, () => ringTurn(adapter, exec, input.target, doorbell, {
+			...nudgeOpts,
+			requirePosted: true
+		}), {
 			...guardOpts,
 			harness: input.harness,
 			ownText: (text) => isRingText(text)
@@ -6886,6 +6952,16 @@ function primaryRootOfRepo(exec, repo) {
 		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
@@ -6911,7 +6987,7 @@ function spawn(ctx, 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 || input.repo)) throw new Error("--cwd cannot combine with the worktree-creating flags --branch/--worktree-path/--repo");
 	const id = randomId();
-	const primaryRoot = input.repo ? primaryRootOfRepo(exec, input.repo) : 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);
@@ -6921,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, {
@@ -6932,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));
@@ -7024,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 },
@@ -7041,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 } : {}
 	};
 }
@@ -7052,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 {
@@ -7064,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);
 }
 /**
@@ -7998,6 +8098,102 @@ function addPermissionRule(file) {
 	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
@@ -8480,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
@@ -8642,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
@@ -8845,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
@@ -9232,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), {
@@ -9259,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, {
@@ -9586,7 +9854,7 @@ withGlobals(unit.command("focus")).description("move input focus to a peer's ses
 		}
 	});
 });
-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) => {
+withGlobals(unit.command("nudge")).description("deliver text as a turn in a peer's session — by default a doorbell telling them to check their mail; --message relays any text (e.g. a decision) instead").argument("<ref>", "unit id, handle, or worktree branch/CR ref").option("--message <text>", "text delivered as a turn in the peer session", DELIVERY_DOORBELL).action(async (ref, opts) => {
 	const ctx = ctxOf(opts);
 	touch(ctx);
 	const { pane, message, resubmits } = await nudgeUnit(ctx, ref, { message: opts.message });
@@ -9851,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), {
@@ -9859,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 } : {}
 			}
 		});
 	});

package/dist/index.d.mts

@@ -83,7 +83,22 @@ interface AgentRecord {
    * no presence bound, same as if none were ever claimed — nothing self-heals a stale pointer, it
    * stays inert until re-claimed. Independent of the hub's `mainPane` (the human's read-pane). */
   presence?: string;
-}
+  /** Only meaningful on a `kind: 'standing'` record — where a presence is spawned when mail arrives
+   * and none is live (`mail/doorbell`), set by `unit register --standing --home`. Its own field,
+   * never `cwd`: `cwd` is wherever the registering process ran and is rewritten on every refresh. */
+  home?: StandingHome;
+}
+/** A standing owner's home: an absolute folder, plus exactly one way to launch a session in it — an
+ * agent definition resolved from that folder, or a bare harness. */
+type StandingHome = {
+  dir: string;
+} & ({
+  agent: string;
+  harness?: never;
+} | {
+  harness: Harness;
+  agent?: never;
+});
 /** A registered project: one git repository, shared by its default checkout and every linked
  * worktree of it. Keyed by its git common dir, never by a pane or a display name. */
 interface ProjectRecord {
@@ -184,6 +199,8 @@ interface Store extends MailboxStore {
    * store (e.g. a standing record's presence rebind) should hold the SAME named lock around that
    * whole sequence, not just around the final write. */
   withLock<T>(name: string, fn: () => T): T;
+  /** `withLock` held across an async `fn` until its promise settles (`store/lock.ts`). */
+  withLockAsync<T>(name: string, fn: () => Promise<T>): Promise<T>;
 }
 //#endregion
 //#region src/identity.d.ts
@@ -729,6 +746,11 @@ interface SpawnInput {
   repo?: string;
   /** Placement relative to the caller; defaults to 'tab'. */
   at?: MuxPlacement;
+  /** With `cwd`: keep the unit out of the primary checkout of the repository **containing `cwd`**,
+   * not the caller's, and allow a `cwd` in no repository at all. For a spawn whose caller may run
+   * anywhere — the delivery doorbell's spawn into a standing owner's home, sent from a cron job in
+   * no repository. */
+  cwdOwnRepo?: boolean;
 }
 interface SpawnResult {
   agent: AgentRecord;
@@ -773,12 +795,14 @@ export declare function spawnAndWake(ctx: IdContext, input: SpawnInput, options?
   noWake?: boolean;
   nudgeOpts?: NudgeOptions;
   trustOpts?: TrustOptions;
-}): Promise<SpawnResult & {
+}): Promise<SpawnResult & FirstTurn>;
+/** What happened after a spawn landed: whether its first turn was rung, and how its trust prompt went. */
+interface FirstTurn {
   rung: boolean;
   warning?: string;
   trust: TrustOutcome['state'];
   trustBlocked?: string;
-}>;
+}
 //#endregion
 //#region src/store/file-store.d.ts
 /** The on-disk `Store` implementation — current per-writer sharded `.json` layout (ADR-0020):
@@ -811,6 +835,7 @@ export declare class FileStore implements Store {
   setMainPane(pane: string | null): void;
   getMainPane(): string | undefined;
   withLock<T>(name: string, fn: () => T): T;
+  withLockAsync<T>(name: string, fn: () => Promise<T>): Promise<T>;
 }
 //#endregion
 //#region src/wake/await.d.ts

package/dist/index.mjs

@@ -303,10 +303,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
@@ -333,7 +338,7 @@ function unaddressable(ref, exited, tried) {
 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;
 }
@@ -347,7 +352,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");
@@ -694,6 +699,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;
@@ -701,25 +713,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}`);
 }
 /**
 * The first-turn doorbell `unit spawn` delivers to a freshly-opened paned peer — the instruction
@@ -778,6 +801,11 @@ const SPAWN_NUDGE_OPTS = {
 * 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.
@@ -787,7 +815,10 @@ async function wakeSpawn(getAdapter, exec, input, nudgeOpts = SPAWN_NUDGE_OPTS,
 	try {
 		const adapter = getAdapter();
 		const doorbell = (input.resumed ? resumeDoorbell : spawnDoorbell)(input.briefPath);
-		await withDraftGuard(adapter, exec, input.target, () => ringTurn(adapter, exec, input.target, doorbell, nudgeOpts), {
+		await withDraftGuard(adapter, exec, input.target, () => ringTurn(adapter, exec, input.target, doorbell, {
+			...nudgeOpts,
+			requirePosted: true
+		}), {
 			...guardOpts,
 			harness: input.harness,
 			ownText: (text) => isRingText(text)
@@ -1102,6 +1133,16 @@ function primaryRootOfRepo(exec, repo) {
 		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
@@ -1127,7 +1168,7 @@ function spawn(ctx, 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 || input.repo)) throw new Error("--cwd cannot combine with the worktree-creating flags --branch/--worktree-path/--repo");
 	const id = randomId();
-	const primaryRoot = input.repo ? primaryRootOfRepo(exec, input.repo) : resolvePrimaryRoot$1(exec);
+	const primaryRoot = input.cwd !== void 0 && input.cwdOwnRepo === true ? primaryRootOf$1(exec, input.cwd) : input.repo ? primaryRootOfRepo(exec, input.repo) : resolvePrimaryRoot$1(exec);
 	const launch = input.command ?? LAUNCH_MAP[harness];
 	const launchLine = () => composeLaunchLine(ctx, sessionAdapter.name, id, launch);
 	const from = callerPane(sessionAdapter, normalizedEnv);
@@ -1137,7 +1178,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$1(cwd, primaryRoot);
+		if (primaryRoot !== void 0) assertDistinctFromPrimary$1(cwd, primaryRoot);
 		worktree = null;
 		const at = input.at ?? "tab";
 		target = sessionAdapter.open(exec, {
@@ -1148,6 +1189,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));
@@ -1240,15 +1282,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 },
@@ -1257,9 +1323,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 } : {}
 	};
 }
@@ -1268,7 +1333,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 {
@@ -1280,7 +1345,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);
 }
 /**
@@ -2571,6 +2636,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
@@ -2774,6 +2849,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/wake/await.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cyberlegion",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "description": "Harness-agnostic agent session spawning and messaging over the filesystem",
   "keywords": [
     "agent",
@@ -49,7 +49,7 @@
     "tsdown": "^0.23.0",
     "tsx": "^4.22.3",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.7"
+    "vitest": "^5.0.0"
   },
   "engines": {
     "node": ">=22"

package/plugin.json

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

package/skills/dispatch-governance/SKILL.md

@@ -17,7 +17,7 @@ satisfies verdict schema `V`.
 > **Running the CLI.** Every `node scripts/cyberlegion.mjs …` command below runs the `cyberlegion` CLI
 > this plugin ships. The path is relative to this skill's own directory, not the working directory.
 > If you cannot resolve it, run the published CLI of the version that shipped this skill instead,
-> with the same arguments: `npx -y cyberlegion@1.3.0`.
+> with the same arguments: `npx -y cyberlegion@1.4.1`.
 
 ## 1. Resolve the agent definition
 

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

@@ -11,7 +11,7 @@ import { spawnSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 
-const FALLBACK = 'npx -y cyberlegion@1.3.0'
+const FALLBACK = 'npx -y cyberlegion@1.4.1'
 const bin = new URL('../../../bin/cyberlegion.mjs', import.meta.url)
 
 if (existsSync(fileURLToPath(bin))) {

package/skills/init-cyberlegion/README.md

@@ -3,13 +3,14 @@
 The onboarding front door to the Legion — walks a session through getting `cyberlegion` working in
 this repo: probe the environment, register the surfacing hook, and (root session only, only on an
 explicit yes) allow the `cyberlegion` CLI in Claude Code's permissions and bind this pane as the
-durable `legate` owner inbox.
+durable `legate` owner inbox, offering that owner a home folder where a session is started when mail
+arrives and nobody holds its presence.
 
 User-facing. Triggers on "set up cyberlegion", "onboard the legion", "register the cyberlegion
 surfacing hook", "make this pane my main legion inbox", "get cyberlegion working in this repo". Wraps
-`cyberlegion mux doctor` / `init [--allow-cli]` / `unit register --standing` / `attach` — every mechanic is a
+`cyberlegion mux doctor` / `init [--allow-cli]` / `unit register --standing [--home | --clear-home]` / `attach` — every mechanic is a
 CLI call, no filesystem or hub state touched directly.
 
 Distinct from `legate` (spawn/mail/dispatch a peer) and `manage-inbox` (read/ack owner mail once
 bound). See `SKILL.md` for the full flow (probe → consent-gated permission rule + register hook →
-detect root vs spawned → consent-gated bind).
+detect root vs spawned → consent-gated bind, with a home offered at the mint or to an existing owner).

package/skills/init-cyberlegion/SKILL.md

@@ -8,7 +8,8 @@ description: "Use this skill to set up or onboard cyberlegion in this session or
 The onboarding front door to the Legion — a thin, user-invocable wrapper that walks a session through
 getting `cyberlegion` working in this repo: probe the environment, register the surfacing hook, and
 (only in a root session, only on an explicit yes) allow the `cyberlegion` CLI in Claude Code's
-permissions and bind this pane as the durable `legate` owner inbox.
+permissions and bind this pane as the durable `legate` owner inbox, offering that owner a **home** to
+wake in when nobody is standing in for it.
 It is a **thin wrapper**: every mechanic is a `cyberlegion` CLI call. The skill holds the *conversation
 and the judgment* — is this a root session? should we ask to bind? what does the environment look
 like? — the CLI holds all the *mechanism*.
@@ -108,7 +109,18 @@ has it set. Derive this from the probe — never ask the user to declare it.
 - **A hook-only request in a root session** ("just register the surfacing hook") — also stop here.
   Registering the hook satisfies the ask; do not proceed to the bind offer unasked.
 - **Root session, broader onboarding intent, no `legate` owner bound yet** — continue to step 4.
-- **Root session where a `legate` owner is already bound** — stop; do not re-ask, do not re-mint.
+- **Root session where a `legate` owner is already bound** — do not re-ask the bind and do not mint a
+  second owner; go to step 6 to offer a home. A bind request ("make this pane my main legion inbox")
+  made when the owner already exists lands here too.
+
+To tell whether the owner exists, list the standing owners:
+
+```bash
+node scripts/cyberlegion.mjs unit register --standing --format json
+```
+
+A record with `"handle": "legate"` is the owner. Its `home` field says where its presence is
+spawned (`dir` plus `harness` or `agent`); no `home` field means it has none.
 
 ### 4. Ask before binding — never silent
 
@@ -121,21 +133,90 @@ Only a root session with no `legate` owner bound is offered the bind. Ask plainl
 - **User agrees explicitly** — proceed to step 5.
 - **Already bound** — never reach this ask (see step 3).
 
-### 5. On an explicit yes — mint and bind
+### 5. On an explicit yes — offer a home, then mint and bind
+
+**No multiplexer or pane in the probe** → skip the home: mint bare and continue (see *Non-mux parity*
+below). `unit claim` refuses a caller with no multiplexer, and a home is spawned the same way
+`unit spawn` opens a session.
+
+Otherwise, before minting, explain the presence and ask for a home. Mail to the `legate` owner
+reaches whoever stands in for it, in this order:
+
+1. **A live presence** — a session that ran `unit claim legate`. The claim holds until another
+   session claims the owner, until `unit claim legate --clear` unbinds it, or until that session
+   exits.
+2. **The home** — when nobody holds the presence, a session is started in the home folder, bound as
+   the presence, and woken to read the owner's inbox. A home **outranks this pane**: with a home set,
+   a delivery with no live presence starts a session there instead of ringing the pane `attach` binds.
+   Say this in the question: setting a home means unclaimed mail no longer rings this pane.
+3. **This pane** (`attach`) — rung only when focused, when there is neither a presence nor a home.
+
+Ask plainly, e.g.:
+
+> "Should the legate owner have a home — a folder where a session is started to act for it when
+> mail arrives and nobody is live? While you're here, `cyberlegion unit claim legate` makes this
+> session the one that gets the mail, until another session claims it, you run
+> `unit claim legate --clear`, or this one exits; the home is only used when nobody holds it — and
+> once it is set, mail nobody holds starts a session there instead of ringing this pane.
+> A session started there has the folder's trust prompt accepted for it, since you named the
+> folder. Name a folder, or say none."
+
+**A folder** → mint with the home and **exactly one** launch:
+
+```bash
+node scripts/cyberlegion.mjs unit register --standing --handle legate --home <dir> --harness <harness>
+node scripts/cyberlegion.mjs attach
+```
+
+`<harness>` is the `harness` the probe reported, or the one the user names instead — one of
+`claude`, `cursor`, or `codex`. When the user
+names an agent definition to launch there, pass `--agent <definition>` and **no** `--harness`. This
+`--agent` is `unit register`'s — an agent definition resolved from the home — not `init --agent`.
+If the probe reported `harness: unknown` and the user named no agent definition, ask for one — never
+run `--home` without a launch, and never pass `--harness unknown`. Pass `<dir>` as an absolute path.
+
+**None** → mint bare, as before:
 
 ```bash
 node scripts/cyberlegion.mjs unit register --standing --handle legate
 node scripts/cyberlegion.mjs attach
 ```
 
-Run these **in this order** and only after the explicit yes: mint the durable, session-independent
-`legate` owner inbox first, then bind the current pane as that owner's live presence.
+Run the mint and `attach` **in this order** and only after the explicit yes: mint the durable,
+session-independent `legate` owner inbox first, then bind the current pane as the owner's main pane.
+
+**The CLI refuses a home** (the folder does not exist, it is a repository's primary checkout, the
+agent definition does not resolve from it) — it writes nothing. Tell the user its reason and ask for
+another folder or none; do not pick a folder yourself and do not fall back to a bare mint unasked.
+If it rejects `--home` as an unknown option, the CLI is older than homes: say so, and mint bare only
+if the user agrees. On a decline, mint nothing and skip `attach`; the hook stays.
 
 **Non-mux parity.** If the probe reported no multiplexer or pane, `attach` is a no-op —
 that is expected, not a failure. Still run `unit register --standing --handle legate` on yes, and complete
 **without erroring**. The root session surfaces owner mail via the `!spawnedBy` fallback instead of a
 bound pane.
 
+### 6. An owner already minted — add or drop a home
+
+Reached only from step 3, in a root session with a broader onboarding intent, when `legate` is
+already minted. Never re-ask the bind and never run `attach` here. Re-registering a standing owner
+refreshes the same record — the same id, its bound presence kept — so it is not a second mint.
+
+With no multiplexer or pane in the probe, offer nothing here — neither adding nor dropping a home.
+
+- **No home** — explain the presence and the trust-prompt acceptance as in step 5 and offer to give the owner one. On a folder, run
+  `unit register --standing --handle legate --home <dir>` with exactly one of `--harness` /
+  `--agent`, exactly as in step 5; a refusal is handled the same way.
+  If the CLI rejects `--home` (or `--clear-home`) as an unknown option, say it predates homes and
+  change nothing.
+- **A home** — name its folder and offer to drop it. On a yes:
+
+  ```bash
+  node scripts/cyberlegion.mjs unit register --standing --handle legate --clear-home
+  ```
+
+- **A decline** — run nothing.
+
 ## Troubleshooting
 
 **A unit's `cyberlegion mail send` was denied by the auto-mode classifier** (*Permission for this
@@ -149,7 +230,8 @@ the permission ask, or run `cyberlegion init --allow-cli` there.
   config format, and never edits Claude Code's settings by hand (the permission rule goes in only
   through `init --allow-cli`, only on an explicit yes in a root session). Its only filesystem read is the plugin's own bundled `${CLAUDE_PLUGIN_ROOT}/.plugin/pins.json`
   version map, to resolve the CLI pin.
-- It never mints or binds an owner identity without an explicit user yes.
+- It never mints or binds an owner identity without an explicit user yes, and never sets or drops
+  an owner's home except on a folder or a drop the user named.
 - It is distinct from `legate` — sending/spawning/dispatching to a peer is `legate`'s job, not this
   skill's.
 - It is distinct from `manage-inbox` — reading or acking owner mail once bound is `manage-inbox`'s

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

@@ -11,7 +11,7 @@ import { spawnSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 
-const FALLBACK = 'npx -y cyberlegion@1.3.0'
+const FALLBACK = 'npx -y cyberlegion@1.4.1'
 const bin = new URL('../../../bin/cyberlegion.mjs', import.meta.url)
 
 if (existsSync(fileURLToPath(bin))) {

package/skills/legate/SKILL.md

@@ -13,7 +13,7 @@ logic, loads no other governance, and writes no state of its own.
 > **Running the CLI.** Every `node scripts/cyberlegion.mjs …` command below runs the `cyberlegion` CLI
 > this plugin ships. The path is relative to this skill's own directory, not the working directory.
 > If you cannot resolve it, run the published CLI of the version that shipped this skill instead,
-> with the same arguments: `npx -y cyberlegion@1.3.0`.
+> with the same arguments: `npx -y cyberlegion@1.4.1`.
 
 ## Doorbell vs mailbox
 

package/skills/legate/scripts/cyberlegion.mjs

@@ -11,7 +11,7 @@ import { spawnSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 
-const FALLBACK = 'npx -y cyberlegion@1.3.0'
+const FALLBACK = 'npx -y cyberlegion@1.4.1'
 const bin = new URL('../../../bin/cyberlegion.mjs', import.meta.url)
 
 if (existsSync(fileURLToPath(bin))) {

package/skills/manage-inbox/SKILL.md

@@ -13,7 +13,7 @@ the one owner mailbox from wherever they are.
 > **Running the CLI.** Every `node scripts/cyberlegion.mjs …` command below runs the `cyberlegion` CLI
 > this plugin ships. The path is relative to this skill's own directory, not the working directory.
 > If you cannot resolve it, run the published CLI of the version that shipped this skill instead,
-> with the same arguments: `npx -y cyberlegion@1.3.0`.
+> with the same arguments: `npx -y cyberlegion@1.4.1`.
 
 ## Resolve the owner handle
 

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

@@ -11,7 +11,7 @@ import { spawnSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 
-const FALLBACK = 'npx -y cyberlegion@1.3.0'
+const FALLBACK = 'npx -y cyberlegion@1.4.1'
 const bin = new URL('../../../bin/cyberlegion.mjs', import.meta.url)
 
 if (existsSync(fileURLToPath(bin))) {

package/skills/relay-governance/SKILL.md

@@ -15,7 +15,7 @@ agent (`headless-legate`, `sdd-automaton`, the cold judges) to know how *it* rep
 > **Running the CLI.** Every `node scripts/cyberlegion.mjs …` command below runs the `cyberlegion` CLI
 > this plugin ships. The path is relative to this skill's own directory, not the working directory.
 > If you cannot resolve it, run the published CLI of the version that shipped this skill instead,
-> with the same arguments: `npx -y cyberlegion@1.3.0`.
+> with the same arguments: `npx -y cyberlegion@1.4.1`.
 
 ## The one probe: who, if anyone, collects my return?
 

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

@@ -11,7 +11,7 @@ import { spawnSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 
-const FALLBACK = 'npx -y cyberlegion@1.3.0'
+const FALLBACK = 'npx -y cyberlegion@1.4.1'
 const bin = new URL('../../../bin/cyberlegion.mjs', import.meta.url)
 
 if (existsSync(fileURLToPath(bin))) {

package/skills/subagent-backend-governance/SKILL.md

@@ -14,7 +14,7 @@ the unit's **role** — see *Mid-turn messaging is scoped by role*, below.
 > **Running the CLI.** Every `node scripts/cyberlegion.mjs …` command below runs the `cyberlegion` CLI
 > this plugin ships. The path is relative to this skill's own directory, not the working directory.
 > If you cannot resolve it, run the published CLI of the version that shipped this skill instead,
-> with the same arguments: `npx -y cyberlegion@1.3.0`.
+> with the same arguments: `npx -y cyberlegion@1.4.1`.
 
 ## 1. Resolve the agent def
 

package/skills/subagent-backend-governance/scripts/cyberlegion.mjs

@@ -11,7 +11,7 @@ import { spawnSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 
-const FALLBACK = 'npx -y cyberlegion@1.3.0'
+const FALLBACK = 'npx -y cyberlegion@1.4.1'
 const bin = new URL('../../../bin/cyberlegion.mjs', import.meta.url)
 
 if (existsSync(fileURLToPath(bin))) {