cyberlegion 1.2.0 → 1.4.0

package/dist/index.d.mts

@@ -62,6 +62,10 @@ interface AgentRecord {
    * mux env prefix not) — what `unit restart` relaunches the unit with. Absent on a record that
    * predates it or that `spawn` did not write; restart then falls back to the harness default. */
   launch?: string;
+  /** The harness's own conversation (session) id, as its SessionStart hook last reported it from this
+   * unit's pane (`mail hook`) — what `unit restart` resumes. Absent until the hook has fired, and on a
+   * harness whose hook never runs; restart then rebriefs a fresh session. */
+  conversation?: string;
   spawnedBy?: string;
   /** Absent ⇒ session (backward compat, no migration). 'standing' = a session-independent,
    * prune-exempt owner inbox minted by `unit register --standing`. 'service' = a project service's
@@ -79,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 {
@@ -180,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
@@ -719,8 +740,17 @@ interface SpawnInput {
   /** Spawn into this existing directory instead — creates no worktree. Mutually exclusive with
    * `branch`/`worktreePath` (those create a worktree; this reuses one). */
   cwd?: string;
+  /** Create the worktree from the repository containing this path rather than the caller's cwd —
+   * so a caller spawns for another repository without a `cd` chained in front of the command.
+   * Mutually exclusive with `cwd` (that one creates no worktree to place). */
+  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;
@@ -765,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):
@@ -803,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");
@@ -615,6 +620,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.
 */
@@ -631,10 +639,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();
@@ -642,12 +651,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 {
@@ -657,6 +667,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;
@@ -683,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;
@@ -690,28 +713,37 @@ 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
 /**
 * The first-turn doorbell `unit spawn` delivers to a freshly-opened paned peer — the instruction
 * itself, not a notification that context is already populated. It names the brief's **file path**
@@ -725,6 +757,28 @@ async function ringTurn(adapter, exec, target, message, opts = {}) {
 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
@@ -747,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.
@@ -755,9 +814,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,
@@ -1055,6 +1119,30 @@ const LAUNCH_MAP = {
 	cursor: "cursor-agent",
 	codex: "codex"
 };
+/** 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$1((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
@@ -1078,9 +1166,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$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);
@@ -1090,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, {
@@ -1101,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));
@@ -1193,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 },
@@ -1210,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 } : {}
 	};
 }
@@ -1221,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 {
@@ -1233,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);
 }
 /**
@@ -1260,10 +1372,25 @@ 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}` : ""}`;
+}
+/**
+* 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
@@ -1279,7 +1406,7 @@ function muxEnvPrefix(muxName) {
 }
 /**
 * 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.
 */
@@ -1289,7 +1416,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) {
@@ -2509,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
@@ -2712,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/hooks/hooks.json

@@ -5,7 +5,7 @@
 				"hooks": [
 					{
 						"type": "command",
-						"command": "node \"${CLAUDE_PLUGIN_ROOT}/bin/cyberlegion.mjs\" mail hook --event SessionStart"
+						"command": "if [ -x \"$CYBERLEGION_CLI\" ]; then \"$CYBERLEGION_CLI\" mail hook --event SessionStart; else node \"${CLAUDE_PLUGIN_ROOT}/bin/cyberlegion.mjs\" mail hook --event SessionStart; fi"
 					}
 				]
 			}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cyberlegion",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "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.2.0",
+	"version": "1.4.0",
 	"description": "Agent session spawning, messaging, and dispatch — the Legion and its Legate.",
 	"author": {
 		"name": "unional"

package/readme.md

@@ -161,6 +161,11 @@ launcher cannot be resolved, a skill names one fallback pinned to the version th
 `npx -y cyberlegion@<version>`. `pnpm version` rewrites those pins and `.plugin/pins.json` at every
 release, and the test suite fails on a stale one.
 
+Claude Code puts the plugin's `bin/` on the Bash tool's PATH, and `bin/cyberlegion` forwards to
+`bin/cyberlegion.mjs`, so a bare `cyberlegion …` runs the shipped CLI in any Claude Code session with
+no global install. claude.ai and Cowork, including plugins distributed through claude.ai organization
+settings, refuse a plugin with a top-level `bin/`, so the plugin does not install there.
+
 ## License
 
 MIT

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.2.0`.
+> with the same arguments: `npx -y cyberlegion@1.4.0`.
 
 ## 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.2.0'
+const FALLBACK = 'npx -y cyberlegion@1.4.0'
 const bin = new URL('../../../bin/cyberlegion.mjs', import.meta.url)
 
 if (existsSync(fileURLToPath(bin))) {

package/skills/init-cyberlegion/README.md

@@ -2,13 +2,15 @@
 
 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) bind this pane as the durable `legate` owner inbox.
+explicit yes) allow the `cyberlegion` CLI in Claude Code's permissions and bind this pane as the
+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` / `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 → register hook → detect root vs spawned →
-consent-gated bind).
+bound). See `SKILL.md` for the full flow (probe → consent-gated permission rule + register hook →
+detect root vs spawned → consent-gated bind, with a home offered at the mint or to an existing owner).