cyberlegion 1.10.0 → 2.0.0

package/dist/index.mjs

@@ -6,7 +6,7 @@ import { acquire, gitWorktreeCreator, primaryRoot, release } from "cyber-agentki
 import { createHash, randomBytes } from "node:crypto";
 import { execFileSync } from "node:child_process";
 import { homedir } from "node:os";
-//#region src/mux-env.ts
+// src/mux-env.ts
 /**
 * Transitional env-normalization seam (mux.feature: "a pane carrying only the legacy fast-path vars
 * is still honored"). cyber-mux's own fast-path reads `$CYBER_MUX`/`$CYBER_MUX_PANE` — its
@@ -35,8 +35,7 @@ function normalizeMuxEnv(env) {
 		CYBER_MUX_PANE: env.CYBERLEGION_MUX_PANE
 	};
 }
-//#endregion
-//#region src/paths.ts
+// src/paths.ts
 /** The tracked marker file that makes a hub root initialized (see ensureMarker). */
 const MARKER_FILE = "config.json";
 /** Where `spawn` stamps that marker inside a worktree it creates, relative to the worktree root. */
@@ -166,8 +165,7 @@ const paths = {
 function sanitizePane(pane) {
 	return pane.replace(/[^A-Za-z0-9_-]/g, "_");
 }
-//#endregion
-//#region src/identity.ts
+// src/identity.ts
 const realExec = nodeExec;
 /** `currentPane`, narrowed to a backend the registry can actually store a locator under. A caller
 * inside a pane-carrying-but-unstorable multiplexer (wezterm/zellij) is simply unpaned here — it can
@@ -180,6 +178,128 @@ function storablePane(env) {
 		pane: cur.pane
 	} : void 0;
 }
+/**
+* This session's own pane as the multiplexer sees it now. The env names the pane the shell was
+* launched in, and for herdr that goes stale: herdr gives a pane a new id when it moves to another
+* tab or workspace, while the shell keeps its launch-time `$HERDR_PANE_ID`, and herdr ids recur on a
+* hub, so the stale id can be another unit's pane (#154). herdr's `pane current` resolves the
+* calling pane itself, so its answer wins on a herdr that answers it truly (0.8.2 on). When herdr
+* gives no answer, or an older herdr disagrees with the env, the env id stands. tmux pane
+* ids last as long as the pane, so tmux needs no second opinion.
+*/
+function selfPane(cur, exec) {
+	if (cur?.mux !== "herdr") return cur;
+	const live = herdrCallingPane(exec);
+	if (!live) return cur;
+	if (live.pane === cur.pane) return {
+		...cur,
+		...live.terminal ? { terminal: live.terminal } : {}
+	};
+	if (!herdrReportsCallingPane(exec)) return cur;
+	return {
+		...cur,
+		pane: live.pane,
+		...live.terminal ? { terminal: live.terminal } : {}
+	};
+}
+/** herdr 0.8.2 fixed `pane current` to answer the calling pane; before it, the command answered
+* another client's focused pane (herdr #2297), which would misattribute exactly as a stale env id
+* does. A version that cannot be read is treated as too old. */
+function herdrReportsCallingPane(exec) {
+	const m = exec("herdr", ["--version"])?.match(/(\d+)\.(\d+)\.(\d+)/);
+	if (!m) return false;
+	const [major, minor, patch] = m.slice(1).map(Number);
+	return major > 0 || minor > 8 || minor === 8 && patch >= 2;
+}
+function herdrCallingPane(exec) {
+	return herdrPaneAnswer(exec("herdr", ["pane", "current"]));
+}
+/** Parse a herdr `pane current` / `pane get` answer into its pane id and terminal id. */
+function herdrPaneAnswer(out) {
+	if (!out) return void 0;
+	try {
+		const pane = JSON.parse(out)?.result?.pane;
+		const id = pane?.pane_id;
+		if (typeof id !== "string" || !id) return void 0;
+		const terminal = pane.terminal_id;
+		return {
+			pane: id,
+			...typeof terminal === "string" && terminal ? { terminal } : {}
+		};
+	} catch {
+		return;
+	}
+}
+/**
+* The herdr terminal id behind a pane id — what a unit's herdr pane record keys on besides the pane
+* id. herdr gives a pane a new id when it moves to another workspace and keeps its terminal id
+* (#272; herdr 0.9.5: `pane move wRD:p2 --tab wRE:t1` answered `wRE:p2` on the same `terminal_id`).
+* Undefined when herdr does not answer or reports no terminal id.
+*/
+function herdrTerminalOf(exec, paneId) {
+	return herdrPaneAnswer(exec("herdr", [
+		"pane",
+		"get",
+		paneId
+	]))?.terminal;
+}
+/** The pane locator for a pane a spawn or restart just opened: tagged with its multiplexer so the
+* unit's own `prune` runs the right liveness check, and for herdr carrying the terminal id a move
+* keeps. `null` for a backend a record cannot carry. */
+function openedPaneLocator(exec, mux, id) {
+	if (mux === "tmux") return {
+		mux,
+		id
+	};
+	if (mux !== "herdr") return null;
+	const terminal = herdrTerminalOf(exec, id);
+	return {
+		mux,
+		id,
+		...terminal ? { terminal } : {}
+	};
+}
+/** herdr's live panes keyed by terminal id → current pane id. Empty when herdr gives no list, which
+* says nothing about any pane. */
+function herdrTerminals(exec) {
+	const map = /* @__PURE__ */ new Map();
+	const out = exec("herdr", ["pane", "list"]);
+	if (!out) return map;
+	try {
+		const panes = JSON.parse(out)?.result?.panes;
+		if (!Array.isArray(panes)) return map;
+		for (const p of panes) if (typeof p?.terminal_id === "string" && typeof p?.pane_id === "string") map.set(p.terminal_id, p.pane_id);
+	} catch {
+		return map;
+	}
+	return map;
+}
+/**
+* Where a herdr record that carries its terminal id lives now: the pane id herdr lists for that
+* terminal (`{ id }`), `'gone'` when herdr answered with a list that lacks the terminal, or
+* `undefined` when herdr gave no list. Not called for a record without a terminal id, which keeps
+* being judged by its pane id.
+*/
+function locateTerminal(exec, terminal, cache = {}) {
+	cache.terminals ??= herdrTerminals(exec);
+	if (cache.terminals.size === 0) return void 0;
+	const id = cache.terminals.get(terminal);
+	return id ? { id } : "gone";
+}
+/** Point a record whose herdr pane moved at the pane id it has now, moving its pane pointer with it.
+* The old pointer is dropped only while it still names this record, since herdr hands old ids out
+* again. */
+function followMove(ctx, rec, id) {
+	const pane = rec.pane;
+	if (!pane || pane.id === id) return;
+	if (ctx.store.resolvePaneId(pane.id) === rec.id) ctx.store.removePaneIndex(pane.id);
+	rec.pane = {
+		...pane,
+		id
+	};
+	saveAgent(ctx.store, rec);
+	ctx.store.putPaneIndex(id, rec.id);
+}
 const nowIso = (ctx) => new Date(ctx.now?.() ?? Date.now()).toISOString();
 function randomId() {
 	return randomBytes(8).toString("hex");
@@ -225,10 +345,33 @@ function detectHarness(explicit, ctx) {
 * explicit via the env var.
 */
 function resolveSelfId(ctx) {
+	return resolveSelf(ctx).id;
+}
+function resolveSelf(ctx) {
 	const env = ctx.env ?? process.env;
-	const cur = currentPane(normalizeMuxEnv(env));
-	if (cur) return ctx.store.resolvePaneId(cur.pane);
-	return env.CYBERLEGION_AGENT_ID || void 0;
+	const cur = selfPane(currentPane(normalizeMuxEnv(env)), ctx.exec ?? realExec);
+	if (cur) return {
+		id: selfIdAt(ctx.store, cur),
+		cur
+	};
+	return {
+		id: env.CYBERLEGION_AGENT_ID || void 0,
+		cur
+	};
+}
+/**
+* The unit a pane belongs to. The pane pointer answers first. When herdr named the calling pane's
+* terminal, a pointer whose record carries a different terminal is stale (the id was handed to
+* this pane after the unit's own pane moved away), and a missing pointer may mean this pane moved:
+* either way the record bearing this terminal is the caller (#272). A record without a terminal id
+* is trusted by its pointer as before.
+*/
+function selfIdAt(store, cur) {
+	const indexed = store.resolvePaneId(cur.pane);
+	if (!cur.terminal) return indexed;
+	const terminal = indexed ? loadAgent(store, indexed)?.pane?.terminal : void 0;
+	if (indexed && (!terminal || terminal === cur.terminal)) return indexed;
+	return listAgents(store).find((a) => a.pane?.mux === "herdr" && a.pane.terminal === cur.terminal)?.id;
 }
 /** Register (or idempotently refresh) this session's identity. */
 function register(ctx, input) {
@@ -240,8 +383,8 @@ function register(ctx, input) {
 	const existing = existingId ? loadAgent(ctx.store, existingId) : void 0;
 	const id = existing?.id ?? existingId ?? randomId();
 	const ts = nowIso(ctx);
-	const cur = storablePane(env);
 	const exec = ctx.exec ?? realExec;
+	const cur = selfPane(storablePane(env), exec);
 	const rec = {
 		id,
 		handle: input.handle ?? existing?.handle ?? id.slice(0, 6),
@@ -276,7 +419,8 @@ function paneLocator(cur, exec, env) {
 	};
 	return {
 		mux: cur.mux,
-		id: cur.pane
+		id: cur.pane,
+		...cur.terminal ? { terminal: cur.terminal } : {}
 	};
 }
 /** The checkout `dir` (else the cwd) sits in: its root, its branch, and the repository's primary
@@ -424,10 +568,26 @@ function bumpLastSeen(ctx, id) {
 	rec.lastSeen = nowIso(ctx);
 	saveAgent(ctx.store, rec);
 }
-/** Refresh this session's own last-seen if it is registered — best-effort, never throws. */
+/**
+* Refresh this session's own last-seen if it is registered — best-effort, never throws. In a herdr
+* pane whose calling pane herdr reported, it also heals the record's pane to the id and terminal
+* herdr gave, so a unit whose pane moved fixes its own record on its next turn (#272).
+*/
 function touch(ctx) {
-	const id = resolveSelfId(ctx);
-	if (id) bumpLastSeen(ctx, id);
+	const { id, cur } = resolveSelf(ctx);
+	if (!id) return;
+	bumpLastSeen(ctx, id);
+	if (cur?.mux !== "herdr" || !cur.terminal) return;
+	const rec = loadAgent(ctx.store, id);
+	if (rec?.pane?.mux !== "herdr") return;
+	if (rec.pane.terminal !== cur.terminal) {
+		rec.pane = {
+			...rec.pane,
+			terminal: cur.terminal
+		};
+		saveAgent(ctx.store, rec);
+	}
+	followMove(ctx, rec, cur.pane);
 }
 const STALE_MS = 9e5;
 /** Standing and service records have no session of their own, so nothing about a pane or a timer
@@ -454,7 +614,9 @@ function isPrunable(rec) {
 function sessionLive(ctx, rec) {
 	if (rec.status === "exited" || rec.status === "stopped") return false;
 	if (!rec.pane) return true;
-	const panes = PANE_ADAPTERS[rec.pane.mux].listPanes(ctx.exec ?? realExec);
+	const exec = ctx.exec ?? realExec;
+	if (rec.pane.mux === "herdr" && rec.pane.terminal) return locateTerminal(exec, rec.pane.terminal) !== "gone";
+	const panes = PANE_ADAPTERS[rec.pane.mux].listPanes(exec);
 	if (panes.length === 0) return true;
 	const id = rec.pane.id;
 	return panes.some((p) => p.id === id);
@@ -529,11 +691,12 @@ function reconcile(ctx, opts) {
 	if (panes.length === 0) return [];
 	const live = new Set(panes.map((p) => p.id));
 	const changed = [];
+	const cache = {};
 	for (const rec of listAgents(ctx.store)) {
 		if (!isPrunable(rec)) continue;
 		if (!rec.pane) continue;
 		if (rec.pane.mux !== cur.mux) continue;
-		if (!live.has(rec.pane.id)) {
+		if (rec.pane.mux === "herdr" && rec.pane.terminal ? terminalGone(ctx, rec, rec.pane.terminal, cache) : !live.has(rec.pane.id)) {
 			rec.status = "exited";
 			saveAgent(ctx.store, rec);
 			changed.push(rec);
@@ -558,27 +721,93 @@ function paneGone(exec, pane, lists) {
 	}
 	return panes.length > 0 && !panes.some((p) => p.id === pane.id);
 }
-/** Mark agents whose session is gone as exited. Reconcile-culls against the current mux's live set
-* first, then judges each remaining record (covers the other mux and sessions outside any
-* multiplexer pane): a pane-bound record by its pane alone — a live or unprobeable pane keeps it
-* whatever its last-seen — and a pane-less record by the staleness timer, its only signal. */
+/**
+* Whether a herdr record that carries its terminal id is positively gone: herdr listed its panes and
+* that terminal is not among them. A live terminal under a new pane id is a moved pane, so the record
+* follows it instead (#272). A pane id that herdr now gives another terminal does not keep the record
+* alive, since herdr ids recur. No list at all decides nothing.
+*/
+function terminalGone(ctx, rec, terminal, cache) {
+	const at = locateTerminal(ctx.exec ?? realExec, terminal, cache);
+	if (at === "gone") return true;
+	if (at) followMove(ctx, rec, at.id);
+	return false;
+}
+/**
+* Mark agents whose session is gone as exited, then delete every exited unit with nothing left to
+* work from. Reconcile-culls against the current mux's live set first, then judges each remaining
+* record (covers the other mux and sessions outside any multiplexer pane): a pane-bound record by its
+* pane alone — a live or unprobeable pane keeps it whatever its last-seen — and a pane-less record by
+* the staleness timer, its only signal. An exited unit whose worktree is still on disk is kept, since
+* `unit close` owns removing that worktree; every other exited unit is deleted with `deleteExited`.
+*/
 function prune(ctx) {
 	const exec = ctx.exec ?? realExec;
 	const now = ctx.now?.() ?? Date.now();
-	const changed = reconcile(ctx);
+	const marked = reconcile(ctx);
 	const lists = /* @__PURE__ */ new Map();
+	const cache = {};
 	for (const rec of listAgents(ctx.store)) {
 		if (!isPrunable(rec)) continue;
-		if (rec.pane ? paneGone(exec, rec.pane, lists) : now - new Date(rec.lastSeen).getTime() > STALE_MS) {
+		if (!rec.pane ? now - new Date(rec.lastSeen).getTime() > STALE_MS : rec.pane.mux === "herdr" && rec.pane.terminal ? terminalGone(ctx, rec, rec.pane.terminal, cache) : paneGone(exec, rec.pane, lists)) {
 			rec.status = "exited";
 			saveAgent(ctx.store, rec);
-			changed.push(rec);
+			marked.push(rec);
 		}
 	}
-	return changed;
+	const deleted = deleteExited(ctx);
+	const gone = new Set(deleted.map((r) => r.id));
+	return [...marked.filter((r) => !gone.has(r.id)).map((r) => ({
+		...r,
+		pruned: "exited"
+	})), ...deleted.map((r) => ({
+		...r,
+		pruned: "deleted"
+	}))];
+}
+/** Whether an exited record still has a worktree on disk — the one thing it leaves behind that
+* `unit close` must deal with. A record that never had a worktree has nothing on disk. */
+function worktreeOnDisk(rec) {
+	if (rec.worktree?.root == null || !existsSync(rec.worktree.root)) return false;
+	return !isPrimaryCheckout(rec.worktree.root, rec.worktree.primaryRoot);
+}
+/** Whether a worktree root is its repository's primary checkout — the one test `unit close` and
+* `unit prune` share for "a seat on the main checkout, which nothing removes". */
+function isPrimaryCheckout(worktreeRoot, primaryRoot) {
+	return worktreeRoot != null && primaryRoot != null && resolve(worktreeRoot) === resolve(primaryRoot);
+}
+/**
+* Delete every exited unit with no worktree left to close (none on disk, or only the primary checkout): its record, brief, mailbox, and the pane
+* pointer that still names it. Nothing revives an exited unit (`unit restart` takes only a running or
+* stopped one), so these records are read by nobody. A pane pointer is dropped only when it still
+* resolves to the deleted unit, since a multiplexer may have handed the pane id to another unit
+* since. A worktree that is gone from disk may still be registered with git, and the record is the
+* last place that names its repository, so that registration is cleared first, best-effort, as
+* `unit close` does. No pane is torn down: an exited unit's pane is already gone or belongs to
+* someone else.
+*/
+function deleteExited(ctx) {
+	const exec = ctx.exec ?? realExec;
+	const deleted = [];
+	for (const rec of listAgents(ctx.store)) {
+		if (rec.status !== "exited" || isSessionIndependent(rec) || worktreeOnDisk(rec)) continue;
+		const primaryRoot = rec.worktree?.primaryRoot;
+		if (primaryRoot && existsSync(primaryRoot)) exec("git", [
+			"-C",
+			primaryRoot,
+			"worktree",
+			"prune"
+		]);
+		const pane = rec.pane?.id ?? ctx.store.findPaneByAgentId(rec.id);
+		if (pane && ctx.store.resolvePaneId(pane) === rec.id) ctx.store.removePaneIndex(pane);
+		ctx.store.removeAgent(rec.id);
+		ctx.store.removeAgentData(rec.id);
+		ctx.store.removeMailbox(rec.id);
+		deleted.push(rec);
+	}
+	return deleted;
 }
-//#endregion
-//#region src/console/prompt-guard.ts
+// src/console/prompt-guard.ts
 const CODEX_PLACEHOLDERS = /* @__PURE__ */ new Set([
 	"Ask Codex to do anything",
 	"Explain this codebase",
@@ -736,8 +965,7 @@ async function clearLine(adapter, exec, target, sleep) {
 	adapter.sendText(exec, target, KILL_LINE);
 	await sleep(KEY_SETTLE_MS);
 }
-//#endregion
-//#region src/console/ring.ts
+// src/console/ring.ts
 const DEFAULT_ATTEMPTS = 10;
 const DEFAULT_SETTLE_MS = 400;
 /** cyber-mux's `isStaged` matches on the same prefix length. */
@@ -934,8 +1162,7 @@ async function wakeSpawn(getAdapter, exec, input, nudgeOpts = SPAWN_NUDGE_OPTS,
 		};
 	}
 }
-//#endregion
-//#region src/console/trust.ts
+// src/console/trust.ts
 /**
 * Each harness's folder-trust prompt, as it draws it, and the keys that accept it. Read from Claude
 * Code 2.1.286, Codex 0.153.4 (and its newer "Trust this folder?" wording), and cursor-agent
@@ -1045,8 +1272,7 @@ function stuck(where) {
 		message: `${where}, and the prompt is still showing after spawn sent the keys that accept it. A person must answer it.`
 	};
 }
-//#endregion
-//#region src/mux-select.ts
+// src/mux-select.ts
 /**
 * Backend selection via cyber-mux's two-mode mux probe, normalized through the transitional
 * `$CYBERLEGION_MUX*` → `$CYBER_MUX*` env seam (`mux-env.ts`) — tmux/herdr map to their existing
@@ -1066,8 +1292,7 @@ function selectSessionAdapter(env, exec = realExec) {
 	if (probe.mux === "wezterm" || probe.mux === "zellij") throw new Error(`spawn detected ${probe.mux}, a backend unit/registry cannot store a pane locator under (only tmux and herdr) — refusing before opening anything`);
 	throw new Error("spawn requires a session backend — run inside tmux ($TMUX) or herdr ($HERDR_ENV=1)");
 }
-//#endregion
-//#region src/workspace-label.ts
+// src/workspace-label.ts
 /** Leading actions that tear down or revert — the `A2-` class, checked first. */
 const TEARDOWN_ACTIONS = /* @__PURE__ */ new Set([
 	"clean",
@@ -1210,8 +1435,7 @@ function fitWords(words, budget) {
 	}
 	return out;
 }
-//#endregion
-//#region src/worktree-lease.ts
+// src/worktree-lease.ts
 /**
 * The two worktree-library calls a unit's lifetime makes: `unit spawn` acquires a worktree, `unit
 * close` releases it. Gathered here so a test can stand in for them and drive spawn's routing without
@@ -1235,8 +1459,7 @@ function leaseHolder(id) {
 * cyberlegion's own file, not the unit's work, and counting it would keep every slot from reuse in a
 * project that does not track it. */
 const LEASE_IGNORE = [WORKTREE_MARKER];
-//#endregion
-//#region src/session.ts
+// src/session.ts
 /** How each harness's own CLI is launched in the new pane. */
 const LAUNCH_MAP = {
 	claude: "claude",
@@ -1430,10 +1653,7 @@ async function spawn(ctx, input) {
 		cwd,
 		worktree,
 		...sharedWorktree ? { sharedWorktree } : {},
-		pane: muxName === "tmux" || muxName === "herdr" ? {
-			mux: muxName,
-			id: target.id
-		} : null,
+		pane: openedPaneLocator(exec, muxName, target.id),
 		status: "active",
 		createdAt: ts,
 		lastSeen: ts,
@@ -1628,8 +1848,7 @@ function resolveBrief(input, readStdin = () => readFileSync(0, "utf8")) {
 	if (input.task != null && input.task !== "") return input.task;
 	return null;
 }
-//#endregion
-//#region src/agentdef/resolve.ts
+// src/agentdef/resolve.ts
 function parseAgentDefFile(text) {
 	const m = /^---\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n)?([\s\S]*)$/.exec(text);
 	if (!m) return {
@@ -1749,8 +1968,7 @@ function listAgentDefs(input = {}) {
 	}
 	return defs;
 }
-//#endregion
-//#region src/agentdef/realize.ts
+// src/agentdef/realize.ts
 const DEFAULT_HARNESS = "claude";
 /** POSIX single-quote a value for safe inclusion in a shell command line. */
 function shellQuote(value) {
@@ -1835,8 +2053,7 @@ function realizeLaunch(def, opts = {}) {
 		...briefInstructions ? { briefInstructions } : {}
 	};
 }
-//#endregion
-//#region src/message.ts
+// src/message.ts
 /** Write one message into the recipient's inbox. Collision-free by <epochMs>-<hex>. */
 function send(ctx, input) {
 	const toId = resolveRecipient(ctx.store, input.to);
@@ -1897,8 +2114,7 @@ function deleteMessage(ctx, meId, msgId) {
 function deleteMailbox(store, id) {
 	store.removeMailbox(id);
 }
-//#endregion
-//#region src/decommission.ts
+// src/decommission.ts
 /**
 * Tear a unit down and reap its registry record — the deterministic inverse of `spawn`. Refuses a
 * dirty worktree unless `--force`. Teardown always precedes reap: an already-gone worktree or pane
@@ -1934,7 +2150,7 @@ async function decommission(ctx, input) {
 	const worktreeExists = worktreeRoot != null && existsSync(worktreeRoot);
 	const primaryRoot = worktreeExists ? await primaryRootOf(exec, worktreeRoot) : rec.worktree?.primaryRoot;
 	const held = rec.worktree?.lease;
-	const onPrimary = worktreeRoot != null && primaryRoot != null && resolve(worktreeRoot) === resolve(primaryRoot);
+	const onPrimary = isPrimaryCheckout(worktreeRoot, primaryRoot);
 	if (onPrimary && input.force) throw new Error(`refusing to close "${input.id}" with --force — its worktree is the primary checkout, which close never alters; close it without --force to end its session and reap its record`);
 	const removesWorktree = worktreeExists && !input.keepWorktree && !held && !onPrimary;
 	if (removesWorktree && !input.force && isDirty(exec, worktreeRoot)) throw new Error(`unit "${input.id}" has uncommitted changes in its worktree — pass --force to discard them`);
@@ -2000,10 +2216,9 @@ function isDirty(exec, worktreeRoot) {
 		"--porcelain",
 		"--untracked-files=all"
 	]);
-	return !!status && status.split("\n").some((line) => line && line !== `?? ${WORKTREE_MARKER}`);
+	return !!status && status.split("\n").some((line) => line && line !== `?? .agents/cyberlegion/config.json`);
 }
-//#endregion
-//#region src/install.ts
+// src/install.ts
 const PIN_TOKEN = /^[0-9A-Za-z][0-9A-Za-z._+-]*$/;
 function validatePin(pin) {
 	if (!PIN_TOKEN.test(pin)) throw new Error(`invalid --pin "${pin}" — expected a version or dist-tag token like 0.2.0 or latest (no spaces, ranges, or shell metacharacters)`);
@@ -2156,8 +2371,7 @@ function removeCursor(settings, event, canonical) {
 	else delete hooks[event];
 	return true;
 }
-//#endregion
-//#region src/output.ts
+// src/output.ts
 function stringifyCell(v) {
 	if (v == null) return "";
 	const s = String(v);
@@ -2190,8 +2404,7 @@ function fail(msg) {
 	console.error(JSON.stringify({ error: msg }));
 	process.exit(1);
 }
-//#endregion
-//#region src/project.ts
+// src/project.ts
 /**
 * The canonical git common dir for `dir`, or undefined outside a repository. The common dir is the
 * one path every checkout of a repository shares — the default checkout and each linked worktree
@@ -2310,8 +2523,7 @@ function byPath(ctx, dir) {
 	if (!commonDir) throw new Error(`"${dir}" is not inside a git repository`);
 	return ctx.store.getProject(projectIdOf(commonDir)) ?? registerProject(ctx, { dir });
 }
-//#endregion
-//#region src/runtime/inject-inbox.ts
+// src/runtime/inject-inbox.ts
 const EVENTS = ["SessionStart"];
 /**
 * Resolve the calling agent, gather its unread mail (and a standing owner's, when this session is
@@ -2366,8 +2578,7 @@ function injectInbox(ctx, event) {
 		additionalContext: parts.join("\n\n")
 	} };
 }
-//#endregion
-//#region src/service.ts
+// src/service.ts
 /** A refused ownership transition. `stale` means the caller's generation, token, or holder claim is
 * not the current one — the caller is not (or no longer) the authority it claims to be. */
 var ServiceOwnershipError = class extends Error {
@@ -2684,8 +2895,7 @@ async function startService(ctx, projectRef, name, input) {
 		throw err;
 	}
 }
-//#endregion
-//#region src/store/errors.ts
+// 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
 * error so a caller can report exactly what's broken and where, rather than "Unexpected token" with
@@ -2698,8 +2908,7 @@ var CorruptRecordError = class extends Error {
 		this.name = "CorruptRecordError";
 	}
 };
-//#endregion
-//#region src/store/process-liveness.ts
+// src/store/process-liveness.ts
 /**
 * Probe whether `pid` is alive using `process.kill(pid, 0)` — the POSIX "does this process exist"
 * idiom; it sends no signal, it only tests deliverability. `ESRCH` (no such process) is the only
@@ -2719,8 +2928,7 @@ function probeProcess(pid) {
 		return err.code === "ESRCH" ? "dead" : "unknown";
 	}
 }
-//#endregion
-//#region src/store/lock.ts
+// src/store/lock.ts
 var LockTimeoutError = class extends Error {
 	name;
 	constructor(name) {
@@ -2857,8 +3065,7 @@ async function withLockAsync(root, name, fn, opts) {
 		handle.release();
 	}
 }
-//#endregion
-//#region src/store/file-store.ts
+// src/store/file-store.ts
 /** Parse a record file's content, wrapping a `JSON.parse` failure in a typed, file-named
 * `CorruptRecordError` instead of letting a bare `SyntaxError` bubble up from deep inside
 * `listInbox`/`listAgents`/`getAgent` with no indication of WHICH file broke. A file that doesn't
@@ -3068,8 +3275,7 @@ var FileStore = class {
 		return withLockAsync(this.root, name, fn);
 	}
 };
-//#endregion
-//#region src/wake/await.ts
+// src/wake/await.ts
 /** Internal poll interval — not user-facing (the round-trip cost of one `mail await` cycle). */
 const POLL_MS$1 = 1e3;
 const DEFAULT_TIMEOUT_MS = 6e5;
@@ -3114,8 +3320,7 @@ async function awaitReply(ctx, input) {
 		await sleep(POLL_MS$1);
 	}
 }
-//#endregion
-//#region src/wake/watch.ts
+// src/wake/watch.ts
 const POLL_MS = 1e3;
 /**
 * A continuous foreground observer: prints each NEW matching message as it arrives, polling on a
@@ -3147,5 +3352,4 @@ async function watchMail(ctx, input, onMessage, opts = {}) {
 		await sleep(POLL_MS);
 	}
 }
-//#endregion
 export { DEFAULT_RESERVATION_TTL_MS, FileStore, ServiceOwnershipError, ack, acquireService, assertDistinctFromPrimary, awaitReply, bindService, bumpLastSeen, decommission, deleteMessage, detectHarness, emit, ensureMarker, fail, gitWorktreeAdapter, handoffService, inbox, injectInbox, install, listAgentDefs, listAgents, listProjects, loadAgent, nextStep, paths, peek, probeMultiplexer, projectRoot, prune, realExec, realizeLaunch, register, registerProject, releaseService, resolveAgent, resolveAgentDef, resolveBody, resolvePrimaryRoot, resolveProject, resolveProjectLocalRoot, resolveRecipient, resolveRoot, resolveSelfId, resolveService, selectSessionAdapter, send, serviceEndpointId, spawn, spawnAndWake, startService, toonList, toonObject, touch, verifyOwnership, watchMail, withOwnership };

package/package.json

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

package/plugin.json

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

package/readme.md

@@ -30,7 +30,7 @@ npx cyberlegion unit register --handle scout        # register/refresh this sess
 npx cyberlegion unit register --standing --handle homa  # mint a standing, session-independent owner inbox
 npx cyberlegion unit whoami                          # print your own identity
 npx cyberlegion unit who                             # list addressable peers / live peer sessions
-npx cyberlegion unit prune                           # mark dead agents exited and sweep
+npx cyberlegion unit prune                           # mark dead agents exited; delete exited ones with no worktree
 npx cyberlegion unit spawn --agent reviewer          # launch a peer in its own git worktree (tmux/herdr)
 npx cyberlegion unit focus <ref>                     # move input focus to a peer's session
 npx cyberlegion unit nudge <ref>                     # ring a peer's session (doorbell)

package/skills/dispatch-governance/SKILL.md

@@ -12,12 +12,13 @@ place that judgment lives, loaded in-session by the `legate` gateway on a dispat
 realized headless by the `headless-legate` agent. Both loads run the exact same procedure below.
 
 **Input:** an intent to fulfill role `R` with brief `B`, optionally expecting a result that
-satisfies verdict schema `V`.
+satisfies verdict schema `V`, and optionally the path `P` of an agent definition file. When the
+caller supplies `P`, it is the definition to use; the by-name lookup is skipped.
 
 > **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.10.0`.
+> with the same arguments: `npx -y cyberlegion@2.0.0`.
 
 ## 1. Resolve the agent definition
 
@@ -25,6 +26,18 @@ satisfies verdict schema `V`.
 node scripts/cyberlegion.mjs agent resolve <R> --format json
 ```
 
+When the intent carries a definition path `P`, resolve that file instead and do not look `<R>` up by
+name (a definition a plugin ships is not under the project's `.agents/agents/`, so by name it is not
+found):
+
+```bash
+node scripts/cyberlegion.mjs agent resolve --file <P> --format json
+```
+
+Everything below reads the same resolved def either way. Wherever a step passes `--agent <R>` to
+`unit spawn`, pass `--agent-file <P>` instead when `P` was given, and the subagent path builds its
+instruction from the def resolved from `P`.
+
 Read `model`, `effort`, `harness`, `warm`, `interactive` off the resolved def. `warm` marks a role
 that should run as a live peer session (not a fire-and-forget unit); `interactive` marks a role that
 may need to grill the caller or converse over multiple rounds, not just return one result.
@@ -53,7 +66,7 @@ to open a pane in; its absence rules that strategy out regardless of what the ag
   mint a thread id, weave it (and an instruction to reply on it) into brief `B`, then:
 
   ```bash
-  node scripts/cyberlegion.mjs unit spawn --agent <R> --brief-file <B> --at <placement>
+  node scripts/cyberlegion.mjs unit spawn --agent <R> --brief-file <B> --at <placement>   # or --agent-file <P> when given
   node scripts/cyberlegion.mjs mail await --thread <the-minted-thread-id> [--timeout <ms>] [--max-wait <s>]
   ```