cyberlegion 0.3.2 → 0.4.0

package/dist/watch-D33fQcUI.mjs

@@ -1,2044 +0,0 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { basename, dirname, join, resolve } from "node:path";
-import { callerPane, currentPane, herdrMuxAdapter, nodeExec, nudge, probeMultiplexer, tmuxMuxAdapter } from "cyber-mux";
-import { execFileSync } from "node:child_process";
-import { homedir } from "node:os";
-import { assertDistinctFromPrimary, gitWorktreeAdapter, resolvePrimaryRoot } from "cyber-mux/worktree";
-import { randomBytes } from "node:crypto";
-//#region src/paths.ts
-/** The tracked marker file that makes a hub root initialized (see ensureMarker). */
-const MARKER_FILE = "config.json";
-/** Walk up from `cwd` to the nearest git repo root; fall back to `cwd`. */
-function projectRoot(cwd = process.cwd()) {
-	let dir = resolve(cwd);
-	for (;;) {
-		if (existsSync(join(dir, ".git"))) return dir;
-		const parent = dirname(dir);
-		if (parent === dir) return resolve(cwd);
-		dir = parent;
-	}
-}
-function makeDefaultExec(cwd) {
-	return (cmd, args) => {
-		try {
-			return execFileSync(cmd, args, {
-				encoding: "utf8",
-				stdio: [
-					"ignore",
-					"pipe",
-					"ignore"
-				],
-				cwd
-			}).trim();
-		} catch {
-			return null;
-		}
-	};
-}
-/**
-* Resolve the cyberlegion hub root. Precedence: explicit --root/--space, then `$CYBERLEGION_ROOT`,
-* then the GLOBAL hub `~/.agents/cyberlegion` (addressable across every project and worktree
-* boundary — identity/mail/registry state lives here by default; `--space` isolates it), falling
-* back to a project-local `.agents/cyberlegion` only when no home directory is resolvable.
-*/
-function resolveRoot(opts = {}) {
-	const env = opts.env ?? process.env;
-	const explicit = opts.root ?? opts.space ?? env.CYBERLEGION_ROOT;
-	if (explicit) return resolve(explicit);
-	const home = homedir();
-	if (home) return join(home, ".agents", "cyberlegion");
-	return join(projectRoot(opts.cwd), ".agents", "cyberlegion");
-}
-/**
-* Resolve the primary checkout's project-local cyberlegion dir — the tracked marker for a
-* legion-enabled project (never the global hub, and never where spawned unit worktrees themselves
-* are checked out — see `resolveUnitWorktreePath`), keyed off `git worktree`'s common-dir so it
-* resolves the same from the primary checkout or from any of its linked worktrees.
-*/
-function resolveProjectLocalRoot(opts = {}) {
-	const exec = opts.exec ?? makeDefaultExec(opts.cwd);
-	let primary;
-	try {
-		primary = resolvePrimaryRoot(exec);
-	} catch {
-		primary = void 0;
-	}
-	return join(primary ?? projectRoot(opts.cwd), ".agents", "cyberlegion");
-}
-/**
-* Create the tracked `config.json` marker at `root` (a hub root) if it does not already exist.
-* Callers pass the root under which the marker should be created/ensured; this mkdir's it as
-* needed. Idempotent — never overwrites an existing marker.
-*/
-function ensureMarker(root) {
-	mkdirSync(root, { recursive: true });
-	const marker = join(root, MARKER_FILE);
-	if (!existsSync(marker)) writeFileSync(marker, `${JSON.stringify({ version: 1 }, null, 2)}\n`);
-}
-/**
-* Thrown when an agent/message id destined to become a filename PATH SEGMENT fails
-* `assertSafeId` — see that function's doc for why this rejects rather than encodes.
-*/
-var InvalidIdError = class extends Error {
-	kind;
-	value;
-	constructor(kind, value) {
-		super(`invalid ${kind} ${JSON.stringify(value)} — must not be empty, ".", "..", or contain a path separator`);
-		this.kind = kind;
-		this.value = value;
-		this.name = "InvalidIdError";
-	}
-};
-const UNSAFE_ID = /[\\/\0]/;
-/**
-* Filename-safety guard for any id that becomes a bare PATH SEGMENT under the hub root — agent ids
-* (`agentFile`/`inboxDir`/`dataDir`/`briefFile`) and message ids (`messageFile`). Both are
-* effectively user/peer-controlled: an agent id round-trips a caller-supplied `--handle`-adjacent
-* value in some flows, and nothing upstream of the store validates it before it reaches a `join()`.
-*
-* REJECT, don't encode: unlike `sanitizePane` (which deliberately encodes, because a tmux/herdr pane
-* locator is an opaque, internally-produced token that only needs to survive as a *lookup key*, not
-* round-trip as an identity), an agent/message id is a PRIMARY KEY — `getAgent(id)` must return
-* exactly what `putAgent` stored under that same `id`. Silently encoding two different malformed ids
-* onto the same sanitized filename would let one caller's write silently clobber or read another's
-* record — a worse failure than a loud, immediate refusal. So: empty, `.`, `..`, and any embedded
-* path separator (POSIX `/`, Windows `\`) or NUL byte are rejected outright, which also rejects an
-* absolute path outright (an absolute path always contains a separator).
-*/
-function assertSafeId(id, kind) {
-	if (!id || id === "." || id === ".." || UNSAFE_ID.test(id)) throw new InvalidIdError(kind, id);
-	return id;
-}
-const paths = {
-	agentsDir: (root) => join(root, "agents"),
-	agentFile: (root, id) => join(root, "agents", `${assertSafeId(id, "agent id")}.json`),
-	panesDir: (root) => join(root, "panes"),
-	paneFile: (root, pane) => join(root, "panes", `${sanitizePane(pane)}.id`),
-	inboxDir: (root, id) => join(root, "inbox", assertSafeId(id, "agent id")),
-	inboxReadDir: (root, id) => join(root, "inbox", assertSafeId(id, "agent id"), "read"),
-	dataDir: (root, id) => join(root, "data", assertSafeId(id, "agent id")),
-	briefFile: (root, id) => join(root, "data", assertSafeId(id, "agent id"), "brief.md"),
-	mainPaneFile: (root) => join(root, "main-pane.id"),
-	/** A message's file path within `toId`'s unread/read inbox dir, keyed by its own collision-free
-	* id — validated the same as an agent id (it's the same class of risk: a peer- or CLI-controlled
-	* string becoming a filename). */
-	messageFile: (root, toId, msgId) => join(paths.inboxDir(root, toId), `${assertSafeId(msgId, "message id")}.json`),
-	messageReadFile: (root, toId, msgId) => join(paths.inboxReadDir(root, toId), `${assertSafeId(msgId, "message id")}.json`)
-};
-/**
-* Where a spawned unit's own git worktree is checked out by default — a sibling of the primary
-* checkout (`<parent>/<repo>.worktrees/legion-<id>`), never nested inside the primary's own working
-* tree. A linked worktree living inside the primary's tree is untracked-but-present: it pollutes
-* `git status` in the primary checkout, confuses tooling that walks the tree recursively (test
-* runners, watchers, `find`/`rm -rf`), and risks a tree-wide op in the primary crossing into the
-* nested worktree's own checkout. `<repo>.worktrees/` matches the sibling convention already in use
-* for other tools' worktrees in this environment (herdr's `worktree-<word>-<word>-<hash>`, cursor's
-* `<proj><count>`); the `legion-` prefix self-identifies this tool's own units the same way, without
-* needing a subfolder.
-*/
-function resolveUnitWorktreePath(primaryRoot, id) {
-	return join(dirname(primaryRoot), `${basename(primaryRoot)}.worktrees`, `legion-${id}`);
-}
-/** tmux pane ids look like "%3"; make them filesystem-safe. */
-function sanitizePane(pane) {
-	return pane.replace(/[^A-Za-z0-9_-]/g, "_");
-}
-//#endregion
-//#region src/agentdef/resolve.ts
-function parseAgentDefFile(text) {
-	const m = /^---\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n)?([\s\S]*)$/.exec(text);
-	if (!m) return {
-		fm: {},
-		instructions: text.trim()
-	};
-	const [, block, rest] = m;
-	const fm = {};
-	const lines = block.split("\n");
-	let i = 0;
-	while (i < lines.length) {
-		const line = lines[i].replace(/\r$/, "");
-		if (line.trim() === "" || line.trim().startsWith("#")) {
-			i++;
-			continue;
-		}
-		if (line.length - line.trimStart().length > 0) {
-			i++;
-			continue;
-		}
-		const idx = line.indexOf(":");
-		if (idx === -1) {
-			i++;
-			continue;
-		}
-		const key = line.slice(0, idx).trim();
-		let value = line.slice(idx + 1).trim();
-		i++;
-		if (value === ">" || value === ">-" || value === "|" || value === "|-") {
-			const parts = [];
-			while (i < lines.length) {
-				const l = lines[i].replace(/\r$/, "");
-				if (l.trim() === "") {
-					i++;
-					continue;
-				}
-				if (l.length - l.trimStart().length === 0) break;
-				parts.push(l.trim());
-				i++;
-			}
-			value = parts.join(value.startsWith("|") ? "\n" : " ");
-		}
-		fm[key] = unquote(value);
-	}
-	return {
-		fm,
-		instructions: rest.trim()
-	};
-}
-function unquote(v) {
-	if (v.length >= 2 && (v.startsWith("\"") && v.endsWith("\"") || v.startsWith("'") && v.endsWith("'"))) return v.slice(1, -1);
-	return v;
-}
-function toBool(v) {
-	if (v === void 0) return void 0;
-	if (v === "true") return true;
-	if (v === "false") return false;
-}
-function toAgentDef(path, text, fallbackName) {
-	const { fm, instructions } = parseAgentDefFile(text);
-	return {
-		name: fm.name ?? fallbackName,
-		description: fm.description,
-		model: fm.model,
-		effort: fm.effort,
-		harness: fm.harness,
-		warm: toBool(fm.warm),
-		interactive: toBool(fm.interactive),
-		instructions,
-		path
-	};
-}
-/** The project's own `.agents/agents/` dir — the convention `agent list`/name-search scans. */
-function projectAgentsDir(cwd) {
-	return join(projectRoot(cwd), ".agents", "agents");
-}
-/** Resolve one agent definition, by explicit file or by name search. Throws a clear error when
-* neither locates a def — never returns a partial/empty result. */
-function resolveAgentDef(input) {
-	if (input.file) {
-		const path = resolve(input.file);
-		if (!existsSync(path)) throw new Error(`agent def file "${input.file}" does not exist`);
-		return toAgentDef(path, readFileSync(path, "utf8"), basename(path).replace(/\.md$/, ""));
-	}
-	if (!input.name) throw new Error("resolveAgentDef needs a --agent <name> or --agent-file <path>");
-	const roots = [...input.searchRoots ?? [], projectAgentsDir(input.cwd)];
-	for (const root of roots) {
-		const candidate = join(root, `${input.name}.md`);
-		if (existsSync(candidate)) return toAgentDef(candidate, readFileSync(candidate, "utf8"), input.name);
-	}
-	throw new Error(`no agent definition named "${input.name}" found under .agents/agents/`);
-}
-/** List every resolvable agent def under `.agents/agents/` (+ any extra search roots). Definitive
-* empty array when the dir is absent or empty — never throws for "none found" here (unlike a
-* named resolve, listing is inherently zero-or-more). */
-function listAgentDefs(input = {}) {
-	const roots = [...input.searchRoots ?? [], projectAgentsDir(input.cwd)];
-	const seen = /* @__PURE__ */ new Set();
-	const defs = [];
-	for (const root of roots) {
-		if (!existsSync(root)) continue;
-		for (const file of readdirSync(root)) {
-			if (!file.endsWith(".md")) continue;
-			const path = join(root, file);
-			if (seen.has(path)) continue;
-			seen.add(path);
-			defs.push(toAgentDef(path, readFileSync(path, "utf8"), file.replace(/\.md$/, "")));
-		}
-	}
-	return defs;
-}
-//#endregion
-//#region src/mux-env.ts
-/**
-* Transitional env-normalization seam (mux.feature: "a pane carrying only the legacy fast-path vars
-* is still honored"). cyber-mux's own fast-path reads `$CYBER_MUX`/`$CYBER_MUX_PANE` — its
-* `currentPane` hardcodes those names (no `envPrefix` override), and `probeMultiplexer`'s `envPrefix`
-* option renames the WHOLE pair together, so neither can be steered to fall back onto a
-* differently-named legacy pair. Every call into cyber-mux that reads the fast-path
-* (`probeMultiplexer`, `currentPane`, `callerPane`, `resolveMuxAdapter`) must be handed this seam's
-* output instead of the raw env.
-*
-* When `$CYBER_MUX`/`$CYBER_MUX_PANE` are both absent and either legacy `$CYBERLEGION_MUX`/
-* `$CYBERLEGION_MUX_PANE` var is present, copies the legacy pair onto the current names. Never
-* overwrites an already-set current var — the current pair always wins outright the moment either
-* half of it is set, exactly matching the frozen precedence chain (mux.feature: "the current
-* fast-path vars win over the legacy pair when both are set").
-*
-* Transitional — deleted once no pre-migration pane (one that only ever exported the legacy pair) is
-* still alive.
-*/
-function normalizeMuxEnv(env) {
-	const hasCurrent = env.CYBER_MUX !== void 0 || env.CYBER_MUX_PANE !== void 0;
-	const hasLegacy = env.CYBERLEGION_MUX !== void 0 || env.CYBERLEGION_MUX_PANE !== void 0;
-	if (hasCurrent || !hasLegacy) return env;
-	return {
-		...env,
-		CYBER_MUX: env.CYBERLEGION_MUX,
-		CYBER_MUX_PANE: env.CYBERLEGION_MUX_PANE
-	};
-}
-//#endregion
-//#region src/identity.ts
-const realExec = nodeExec;
-/** `currentPane`, narrowed to a backend the registry can actually store a locator under. A caller
-* inside a pane-carrying-but-unstorable multiplexer (wezterm/zellij) is simply unpaned here — it can
-* still resolve an identity via the `$CYBERLEGION_AGENT_ID` env fallback, it just cannot bind a pane
-* locator to it. */
-function storablePane(env) {
-	const cur = currentPane(normalizeMuxEnv(env));
-	return cur && (cur.mux === "tmux" || cur.mux === "herdr") ? {
-		mux: cur.mux,
-		pane: cur.pane
-	} : void 0;
-}
-const nowIso = (ctx) => new Date(ctx.now?.() ?? Date.now()).toISOString();
-function randomId() {
-	return randomBytes(8).toString("hex");
-}
-function loadAgent(store, id) {
-	return store.getAgent(id);
-}
-function saveAgent(store, rec) {
-	store.putAgent(rec);
-}
-function listAgents(store) {
-	return store.listAgents();
-}
-/** Detect the harness: explicit wins, then env probes, then the tmux pane command. */
-function detectHarness(explicit, ctx) {
-	if (explicit) {
-		if (explicit === "claude" || explicit === "cursor" || explicit === "codex") return explicit;
-		throw new Error(`unknown --harness "${explicit}" (expected claude | cursor | codex)`);
-	}
-	const env = ctx.env ?? process.env;
-	if (env.CLAUDECODE || env.CLAUDE_CODE_ENTRYPOINT) return "claude";
-	if (Object.keys(env).some((k) => k.startsWith("CURSOR"))) return "cursor";
-	if (Object.keys(env).some((k) => k.startsWith("CODEX"))) return "codex";
-	const pane = env.TMUX_PANE;
-	if (pane) {
-		const cmd = (ctx.exec ?? realExec)("tmux", [
-			"display-message",
-			"-p",
-			"-t",
-			pane,
-			"#{pane_current_command}"
-		]);
-		if (cmd?.includes("cursor")) return "cursor";
-		if (cmd?.includes("codex")) return "codex";
-		if (cmd?.includes("claude")) return "claude";
-	}
-}
-/**
-* Recover the calling agent's own id, mux-agnostically. Inside any multiplexer pane (tmux or herdr)
-* the pane index is authoritative — a pane with no pane entry is simply unregistered and must NOT
-* adopt `$CYBERLEGION_AGENT_ID` (that env fallback applies ONLY when the session is in no
-* multiplexer pane at all). There is no shared bare "self" file — self-id is always pane-keyed or
-* explicit via the env var.
-*/
-function resolveSelfId(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;
-}
-/** Register (or idempotently refresh) this session's identity. */
-function register(ctx, input) {
-	ctx.store.ensureMarker();
-	const env = ctx.env ?? process.env;
-	const harness = detectHarness(input.harness, ctx);
-	if (!harness) throw new Error("could not detect harness — pass --harness claude|cursor|codex");
-	const existingId = resolveSelfId(ctx);
-	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 rec = {
-		id,
-		handle: input.handle ?? existing?.handle ?? id.slice(0, 6),
-		harness,
-		cwd: process.cwd(),
-		worktree: existing?.worktree ?? gitWorktree(exec),
-		pane: cur ? paneLocator(cur, exec, env) : null,
-		status: "active",
-		createdAt: existing?.createdAt ?? ts,
-		lastSeen: ts,
-		...existing?.brief ? { brief: existing.brief } : {},
-		...existing?.spawnedBy ? { spawnedBy: existing.spawnedBy } : {}
-	};
-	saveAgent(ctx.store, rec);
-	if (cur) ctx.store.putPaneIndex(cur.pane, id);
-	return rec;
-}
-/** Build the record's pane locator. `window`/`session` are tmux-only (herdr's pane id is
-* self-contained and its CLI needs nothing more to address a pane). */
-function paneLocator(cur, exec, env) {
-	if (cur.mux === "tmux") return {
-		mux: "tmux",
-		id: cur.pane,
-		window: exec("tmux", [
-			"display-message",
-			"-p",
-			"-t",
-			cur.pane,
-			"#{window_id}"
-		]) ?? void 0,
-		session: env.TMUX?.split(",")[0]
-	};
-	return {
-		mux: cur.mux,
-		id: cur.pane
-	};
-}
-/** Derive a standing record's stable id from its handle — same slug rule as `sanitizePane`, prefixed
-* so it reads distinct from a random 16-hex session id or a pane pointer. */
-function standingId(handle) {
-	return `standing-${sanitizePane(handle)}`;
-}
-/**
-* Mint (or idempotently refresh) a standing identity: a session-independent, prune-exempt owner
-* inbox keyed by handle, with no pane/tmux/harness. A SIBLING of `register`, not an overload — it
-* skips all pane/tmux machinery and harness auto-detection entirely.
-*/
-function registerStanding(ctx, input) {
-	ctx.store.ensureMarker();
-	const id = standingId(input.handle);
-	const existing = loadAgent(ctx.store, id);
-	const ts = nowIso(ctx);
-	const rec = {
-		id,
-		handle: input.handle,
-		kind: "standing",
-		pane: null,
-		harness: void 0,
-		cwd: process.cwd(),
-		status: "active",
-		createdAt: existing?.createdAt ?? ts,
-		lastSeen: ts
-	};
-	saveAgent(ctx.store, rec);
-	return rec;
-}
-function gitWorktree(exec) {
-	const root = exec("git", ["rev-parse", "--show-toplevel"]);
-	if (!root) return null;
-	return {
-		root,
-		branch: exec("git", [
-			"rev-parse",
-			"--abbrev-ref",
-			"HEAD"
-		]) ?? 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];
-}
-/** 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
-* dead holders of it outnumber the live one over time. Standing records never exit. An explicit id
-* still resolves either way: naming a unit outright is a deliberate choice, unlike reaching for a
-* handle and silently landing on a corpse. */
-function matchHandle(agents, handle) {
-	const matched = agents.filter((a) => a.handle === handle);
-	return {
-		live: matched.filter((a) => a.status !== "exited"),
-		exited: matched.filter((a) => a.status === "exited")
-	};
-}
-/** Fail loudly when a handle names only the dead — never fall through to a corpse. */
-function unaddressable(ref, exited, tried) {
-	if (exited.length > 0) {
-		const dead = exited.map((a) => `${a.id.slice(0, 6)}${a.pane ? ` (${a.pane.id})` : ""}`).join(", ");
-		return /* @__PURE__ */ new Error(`"${ref}" matches only exited unit(s) — ${dead} — which have no reader. Address a live unit ('cyberlegion unit who'), or run 'cyberlegion unit register --standing --handle ${ref}' for a durable inbox.`);
-	}
-	return /* @__PURE__ */ new Error(`no agent addressable as "${ref}" (tried ${tried})`);
-}
-/** Resolve a handle to its standing owner record's id — never falls back to a live session agent
-* sharing that handle, so `--owner` can never be pointed at a session's inbox by mistake. */
-function resolveStandingOwner(store, handle) {
-	const match = listAgents(store).find((a) => a.handle === handle && a.kind === "standing");
-	if (!match) throw new Error(`no standing owner "${handle}" — run 'cyberlegion unit register --standing --handle ${handle}'`);
-	return match.id;
-}
-/**
-* Bind the caller's own unit as a standing owner's presence — the live unit standing in for a
-* durable record that has no session of its own. Order matters: resolve the standing record first
-* (an unknown handle throws via `resolveStandingOwner` — fail-loud, never auto-mints), THEN gate on
-* spawn capability, THEN resolve the caller's own id — so an unknown handle or a caller with no
-* multiplexer never touches the pointer. Last claim wins: a plain overwrite, no merge.
-*/
-function claimPresence(ctx, handle) {
-	const standingId = resolveStandingOwner(ctx.store, handle);
-	if (!loadAgent(ctx.store, standingId)) throw new Error(`no standing owner "${handle}" — run 'cyberlegion unit register --standing --handle ${handle}'`);
-	if (probeMultiplexer(ctx.exec ?? realExec, normalizeMuxEnv(ctx.env ?? process.env)).mux === "none") throw new Error("claiming a presence needs a multiplexer to open panes");
-	const selfId = resolveSelfId(ctx);
-	if (!selfId) throw new Error("no identity in this session — run `cyberlegion unit register` first");
-	return ctx.store.withLock(`presence:${standingId}`, () => {
-		const rec = loadAgent(ctx.store, standingId);
-		if (!rec) throw new Error(`no standing owner "${handle}" — run 'cyberlegion unit register --standing --handle ${handle}'`);
-		rec.presence = selfId;
-		saveAgent(ctx.store, rec);
-		return rec;
-	});
-}
-/**
-* Unbind a standing owner's presence. The unknown-handle throw (via `resolveStandingOwner`) wins
-* over this call's own tolerance: `--clear` is forgiving about *nothing being bound* (a no-op, never
-* an error), never about *the owner not existing* — a typo'd handle fails loudly instead of silently
-* reporting a clear it never performed.
-*/
-function clearPresence(ctx, handle) {
-	const standingId = resolveStandingOwner(ctx.store, handle);
-	if (!loadAgent(ctx.store, standingId)) throw new Error(`no standing owner "${handle}" — run 'cyberlegion unit register --standing --handle ${handle}'`);
-	return ctx.store.withLock(`presence:${standingId}`, () => {
-		const rec = loadAgent(ctx.store, standingId);
-		if (!rec) throw new Error(`no standing owner "${handle}" — run 'cyberlegion unit register --standing --handle ${handle}'`);
-		if (rec.presence !== void 0) {
-			rec.presence = void 0;
-			saveAgent(ctx.store, rec);
-		}
-		return rec;
-	});
-}
-/**
-* The live-only presence rule, keyed off a standing record the caller ALREADY HOLDS — the pointer
-* records a unit id, and that unit can exit while the standing record it stands in for never does,
-* so a presence whose unit is missing or `status: exited` reads as no presence bound, exactly as if
-* none were ever claimed. Nothing here self-heals the stale pointer; it stays inert until re-claimed
-* via `claimPresence`.
-*
-* Separate from `resolvePresence` because this one is INCAPABLE of throwing: the delivery doorbell
-* must never fail a send that already landed durably, so it cannot resolve the presence through a
-* handle-resolving path that throws when the standing record races away underneath it (a concurrent
-* `unit close`/`decommission` between loading the recipient and reading its presence). It is also
-* strictly cheaper — no O(n) registry scan to re-find a record the caller is holding.
-*/
-function presenceOf(store, rec) {
-	if (!rec.presence) return void 0;
-	const presenceUnit = loadAgent(store, rec.presence);
-	if (!presenceUnit || presenceUnit.status === "exited") return void 0;
-	return presenceUnit;
-}
-/**
-* Resolve a standing owner's presence by handle, live-only (`presenceOf`). The handle-keyed front
-* door for the CLI read path: it keeps the fail-loud unknown-handle throw (via `resolveStandingOwner`)
-* so `unit claim <handle> --show` on a typo'd handle errors rather than reporting a definitive `none`
-* for an owner that does not exist.
-*/
-function resolvePresence(store, handle) {
-	const rec = loadAgent(store, resolveStandingOwner(store, handle));
-	if (!rec) return void 0;
-	return presenceOf(store, rec);
-}
-/** Resolve a recipient argument (id or handle) to an agent id. A handle resolves to live units
-* only — mail addressed to an exited unit lands in an inbox nobody reads. */
-function resolveRecipient(store, to) {
-	if (loadAgent(store, to)) return to;
-	const { live, exited } = matchHandle(listAgents(store), to);
-	const match = preferStanding(live);
-	if (!match) throw unaddressable(to, exited, "id and handle");
-	return match.id;
-}
-/**
-* Resolve a unit reference by id, handle, or its worktree branch (the unit↔CR join key: an
-* `AgentRecord.worktree.branch` equals the SDD `<cr-ref>` it maps to, when spawned for one). Used
-* by verbs that address "the unit working on CR X" as well as "the unit named X".
-*/
-function resolveAgent(store, ref) {
-	const byId = loadAgent(store, ref);
-	if (byId) return byId;
-	const agents = listAgents(store);
-	const { live, exited } = matchHandle(agents, ref);
-	const byHandle = preferStanding(live);
-	if (byHandle) return byHandle;
-	const byBranchAll = agents.filter((a) => a.worktree?.branch === ref);
-	const byBranch = byBranchAll.find((a) => a.status !== "exited");
-	if (byBranch) return byBranch;
-	throw unaddressable(ref, [...exited, ...byBranchAll.filter((a) => a.status === "exited")].filter((a, i, all) => all.findIndex((b) => b.id === a.id) === i), "id, handle, and worktree branch/CR");
-}
-function bumpLastSeen(ctx, id) {
-	const rec = loadAgent(ctx.store, id);
-	if (!rec) return;
-	rec.lastSeen = nowIso(ctx);
-	saveAgent(ctx.store, rec);
-}
-/** Refresh this session's own last-seen if it is registered — best-effort, never throws. */
-function touch(ctx) {
-	const id = resolveSelfId(ctx);
-	if (id) bumpLastSeen(ctx, id);
-}
-const STALE_MS = 9e5;
-/** The per-mux session adapters `prune` consults for pane liveness — each answers with its own
-* backend primitive so a herdr pane is never probed with a tmux query, and vice versa. */
-const PANE_ADAPTERS = {
-	tmux: tmuxMuxAdapter,
-	herdr: herdrMuxAdapter
-};
-/** Map a backend-reported agent string to a known harness — substring-matched like the tmux
-* pane-command probe in `detectHarness`; anything else is unclassifiable. */
-function harnessFromAgent(agent) {
-	if (!agent) return void 0;
-	if (agent.includes("cursor")) return "cursor";
-	if (agent.includes("codex")) return "codex";
-	if (agent.includes("claude")) return "claude";
-}
-/**
-* Adopt half of reconcile-against-mux: mint a record for each live pane with a detectable harness
-* and no matching record — bind pane→id, handle from the pane's reported cwd basename (sanitized;
-* `id.slice(0, 6)` when the backend reports no cwd), status active, lastSeen now. A pane is bound —
-* and never adopted — when its pane index resolves to an existing record or any record (any status,
-* exited included) bears it; resurrecting an exited record is the in-pane session's own `register`
-* via the pane pointer, never reconcile's. tmux panes carry no harness signal, so only herdr panes
-* are adoptable today.
-*/
-function adopt(ctx, panes) {
-	const agents = listAgents(ctx.store);
-	const adopted = [];
-	for (const pane of panes) {
-		if (pane.mux !== "tmux" && pane.mux !== "herdr") continue;
-		const harness = harnessFromAgent(pane.harness);
-		if (!harness) continue;
-		const boundId = ctx.store.resolvePaneId(pane.id);
-		if (boundId && loadAgent(ctx.store, boundId)) continue;
-		if (agents.some((a) => a.pane?.mux === pane.mux && a.pane.id === pane.id)) continue;
-		const id = randomId();
-		const ts = nowIso(ctx);
-		const rec = {
-			id,
-			handle: pane.cwd ? sanitizePane(basename(pane.cwd)) : id.slice(0, 6),
-			harness,
-			cwd: pane.cwd ?? "",
-			pane: {
-				mux: pane.mux,
-				id: pane.id
-			},
-			status: "active",
-			createdAt: ts,
-			lastSeen: ts
-		};
-		saveAgent(ctx.store, rec);
-		ctx.store.putPaneIndex(pane.id, id);
-		adopted.push(rec);
-	}
-	return adopted;
-}
-/**
-* Cull dead records against the current mux's live pane set (the mux the caller is actually inside,
-* per `currentPane`) — mux-scoped: it never declares the *other* mux's records dead, since it can't
-* enumerate them. Standing records are exempt; a `pane: null` record can't be pane-culled by
-* enumeration (left to `prune`'s staleness timer). Outside any multiplexer pane there is nothing to
-* enumerate, so it culls nothing. With `adopt` set (the `who --reconcile` path — `prune` stays
-* cull-only), the same live set also feeds adoption of unbound harness-bearing panes.
-*/
-function reconcile(ctx, opts) {
-	const exec = ctx.exec ?? realExec;
-	const cur = storablePane(ctx.env ?? process.env);
-	if (!cur) return [];
-	const panes = PANE_ADAPTERS[cur.mux].listPanes(exec);
-	const live = new Set(panes.map((p) => p.id));
-	const changed = [];
-	for (const rec of listAgents(ctx.store)) {
-		if (rec.kind === "standing") continue;
-		if (rec.status === "exited") continue;
-		if (!rec.pane) continue;
-		if (rec.pane.mux !== cur.mux) continue;
-		if (!live.has(rec.pane.id)) {
-			rec.status = "exited";
-			saveAgent(ctx.store, rec);
-			changed.push(rec);
-		}
-	}
-	if (opts?.adopt) changed.push(...adopt(ctx, panes));
-	return changed;
-}
-/** Mark agents whose pane is gone or whose last-seen is stale as exited. Reconcile-culls against the
-* current mux's live set first, then falls through to the per-record paneExists + staleness check
-* (covers the other mux and sessions outside any multiplexer pane). */
-function prune(ctx) {
-	const exec = ctx.exec ?? realExec;
-	const now = ctx.now?.() ?? Date.now();
-	const changed = reconcile(ctx);
-	for (const rec of listAgents(ctx.store)) {
-		if (rec.kind === "standing") continue;
-		if (rec.status === "exited") continue;
-		const paneGone = rec.pane ? !PANE_ADAPTERS[rec.pane.mux].paneExists(exec, { id: rec.pane.id }) : false;
-		const stale = now - new Date(rec.lastSeen).getTime() > STALE_MS;
-		if (paneGone || stale) {
-			rec.status = "exited";
-			saveAgent(ctx.store, rec);
-			changed.push(rec);
-		}
-	}
-	return changed;
-}
-//#endregion
-//#region src/console/doorbell.ts
-/** The doorbell text delivered to a woken recipient; also the standalone `unit nudge` default. */
-const DELIVERY_DOORBELL = "You have unread mail — check your inbox.";
-/**
-* The first-turn doorbell `unit spawn` delivers to a freshly-opened paned peer — the instruction
-* itself, not a notification that context is already populated. It names the brief's **file path**
-* and tells the peer to read it and begin, so pickup does not depend on a SessionStart hook firing
-* in the child (superseding ADR-0027, which split payload-delivery from turn-delivery).
-*
-* The path is named, never the brief's body: the brief is still written to its file and still never
-* typed into the pane, so a long brief costs one line here however large it is, and a re-submit on
-* the boot race re-types this instruction rather than the payload.
-*/
-function spawnDoorbell(briefPath) {
-	return `Read your brief at ${briefPath}, then begin work.`;
-}
-/**
-* A freshly-launched harness cold-boots slower than an already-running peer, so the spawn first-turn
-* ring gets a wider retry budget than a plain `mail send` doorbell (nudge's own 10 × 400ms): flush the
-* staged buffer for up to ~8s (20 × 400ms) before giving up. The common case still returns after one
-* settle cycle once the peer takes the turn — the budget only bounds a slow or stuck boot. Still
-* bounded — a harness that never reaches its prompt resolves to a best-effort warning, never a hang.
-*/
-const SPAWN_NUDGE_OPTS = {
-	attempts: 20,
-	settleMs: 400
-};
-/** Resolve an agent's live session pane: its recorded pane, else a pane pointer keyed by its id. */
-function paneOf(store, id) {
-	return loadAgent(store, id)?.pane?.id ?? store.findPaneByAgentId(id);
-}
-/**
-* Best-effort wake the recipient of a just-delivered message so it checks its inbox. A peer's live
-* session pane, a standing owner's bound presence (`unit claim` — the live unit standing in for it,
-* an exited one falling back below), or — with neither — the hub's bound main pane, is rung via the
-* nudge submit-verify path (a taken turn, not fire-and-forget). Durable delivery already happened;
-* the ring is opportunistic on top, so a legitimate no-op (`--no-nudge`, a headless/absent recipient
-* with no live pane, a standing-owner send with no presence and no main pane bound, or a
-* self-addressed send) rings nothing, and a ring that never completes within nudge's retry cap is
-* swallowed into a warning. This never throws — it can never fail the send.
-*
-* The adapter is resolved lazily via `getAdapter`, invoked only once a pane to ring is confirmed and
-* inside the same swallowing try — so a session with no mux backend (where `selectSessionAdapter`
-* throws) is just a no-op wake, never a failed send.
-*/
-async function wakeRecipient(store, getAdapter, exec, input, nudgeOpts) {
-	if (input.noNudge) return { rung: false };
-	const recipient = loadAgent(store, input.toId);
-	if (!recipient) return { rung: false };
-	let pane;
-	let focusGated = false;
-	if (recipient.kind === "standing") {
-		const presenceUnit = presenceOf(store, recipient);
-		if (presenceUnit) pane = paneOf(store, presenceUnit.id);
-		else {
-			pane = store.getMainPane();
-			focusGated = true;
-		}
-	} else pane = paneOf(store, recipient.id);
-	if (!pane) return { rung: false };
-	if (pane === paneOf(store, input.fromId)) return { rung: false };
-	if (focusGated) {
-		let focused;
-		try {
-			focused = getAdapter().isPaneFocused(exec, { id: pane });
-		} catch {
-			focused = void 0;
-		}
-		if (focused === false) return {
-			rung: false,
-			pane
-		};
-	}
-	try {
-		await nudge(getAdapter(), exec, { id: pane }, DELIVERY_DOORBELL, nudgeOpts);
-		return {
-			rung: true,
-			pane
-		};
-	} catch (err) {
-		return {
-			rung: false,
-			pane,
-			warning: err instanceof Error ? err.message : String(err)
-		};
-	}
-}
-/**
-* Best-effort deliver a freshly-spawned paned peer's first turn so it acts on its brief with no
-* human nudge. A paned agent boots to an idle prompt — the brief sits unread on disk and the model
-* takes no turn on its own, unlike a subagent (where the caller's Task call IS the turn). So `unit
-* spawn` rings the instruction (`spawnDoorbell`, naming the brief's file path) over the
-* boot-race-aware `nudge` submit-verify path (a taken turn, never typing the brief itself), the same
-* best-effort ring `wakeRecipient` gives `mail send`: the spawn (worktree, session, registry record)
-* is the guaranteed effect and the ring is opportunistic on top, so `--no-wake` rings nothing and a
-* ring that never completes within the retry budget is swallowed into a warning. This never throws —
-* it can never fail the spawn.
-*
-* The adapter is resolved lazily via `getAdapter` inside the same swallowing try, so even a session
-* whose backend has since gone away (where `selectSessionAdapter` would throw) degrades to a warned
-* no-op rather than a failed spawn.
-*/
-async function wakeSpawn(getAdapter, exec, input, nudgeOpts = SPAWN_NUDGE_OPTS) {
-	if (input.noWake) return { rung: false };
-	try {
-		await nudge(getAdapter(), exec, input.target, spawnDoorbell(input.briefPath), nudgeOpts);
-		return {
-			rung: true,
-			pane: input.target.id
-		};
-	} catch (err) {
-		return {
-			rung: false,
-			pane: input.target.id,
-			warning: err instanceof Error ? err.message : String(err)
-		};
-	}
-}
-//#endregion
-//#region src/mux-select.ts
-/**
-* Backend selection via cyber-mux's two-mode mux probe, normalized through the transitional
-* `$CYBERLEGION_MUX*` → `$CYBER_MUX*` env seam (`mux-env.ts`) — tmux/herdr map to their existing
-* cyber-mux adapters.
-*
-* cyber-mux detects MORE backends than `unit/registry`'s `AgentRecord.pane` can carry a locator
-* under (`'tmux' | 'herdr'` only). A DETECTED wezterm/zellij is refused HERE, before anything opens,
-* naming the backend it found (mux.feature: "a detected backend a unit record cannot carry is
-* refused before opening anything") — driving it would open a real pane no record could name,
-* stranding a live session `prune` can never reap and no caller can nudge. Anything else (`none`,
-* `screen`) falls through to the plain "no backend" refusal, unchanged from before the migration.
-*/
-function selectSessionAdapter(env, exec = realExec) {
-	const probe = probeMultiplexer(exec, normalizeMuxEnv(env));
-	if (probe.mux === "tmux") return tmuxMuxAdapter;
-	if (probe.mux === "herdr") return herdrMuxAdapter;
-	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
-/** Leading actions that tear down or revert — the `A2-` class, checked first. */
-const TEARDOWN_ACTIONS = /* @__PURE__ */ new Set([
-	"clean",
-	"cleanup",
-	"decommission",
-	"delete",
-	"deprecate",
-	"disable",
-	"drop",
-	"prune",
-	"purge",
-	"remove",
-	"retire",
-	"revert",
-	"revoke",
-	"rollback",
-	"teardown",
-	"undo",
-	"uninstall",
-	"unregister"
-]);
-/** Leading actions that only look and report — the `9S-` class, checked after teardown. */
-const RECON_ACTIONS = /* @__PURE__ */ new Set([
-	"analyze",
-	"assess",
-	"audit",
-	"check",
-	"compare",
-	"debug",
-	"diagnose",
-	"evaluate",
-	"examine",
-	"explain",
-	"explore",
-	"find",
-	"identify",
-	"inspect",
-	"investigate",
-	"locate",
-	"measure",
-	"profile",
-	"read",
-	"reproduce",
-	"research",
-	"review",
-	"scan",
-	"survey",
-	"trace",
-	"triage",
-	"verify"
-]);
-/**
-* Leading actions that build or change — the `2B-` class. `2B-` is also the code for a brief whose
-* lead matches nothing at all, but the two cases differ in the SUBJECT: a recognized action is
-* dropped from it (the code already says "build"), an unrecognized leading word is kept (it is the
-* subject's own first noun, and dropping it would strip real signal).
-*/
-const BUILD_ACTIONS = /* @__PURE__ */ new Set([
-	"add",
-	"backfill",
-	"build",
-	"create",
-	"document",
-	"enable",
-	"extend",
-	"fix",
-	"generalize",
-	"harden",
-	"implement",
-	"introduce",
-	"make",
-	"migrate",
-	"move",
-	"port",
-	"refactor",
-	"rename",
-	"replace",
-	"rework",
-	"ship",
-	"split",
-	"support",
-	"swap",
-	"update",
-	"wire",
-	"write"
-]);
-/** Dropped when it leads the subject — an article carries no identifying signal. */
-const LEADING_ARTICLES = /* @__PURE__ */ new Set([
-	"a",
-	"an",
-	"the"
-]);
-/**
-* Resolve the label a `workspace` placement opens under. Total width never exceeds `LABEL_CAP`, and
-* the result always carries a code — a brief that yields no usable subject falls back to the unit's
-* own short id rather than to a bare code.
-*/
-function deriveWorkspaceLabel(input) {
-	const briefWords = tokenize(firstNonEmptyLine(input.brief));
-	const lead = briefWords[0];
-	let code = "2B-";
-	let leadIsAction = false;
-	if (lead && TEARDOWN_ACTIONS.has(lead)) {
-		code = "A2-";
-		leadIsAction = true;
-	} else if (lead && RECON_ACTIONS.has(lead)) {
-		code = "9S-";
-		leadIsAction = true;
-	} else if (lead && BUILD_ACTIONS.has(lead)) leadIsAction = true;
-	let subjectWords;
-	if (input.handle) subjectWords = tokenize(input.handle);
-	else {
-		subjectWords = leadIsAction ? briefWords.slice(1) : briefWords.slice();
-		if (subjectWords[0] && LEADING_ARTICLES.has(subjectWords[0])) subjectWords.shift();
-	}
-	const subject = fitWords(subjectWords, 27) || input.id.slice(0, 6);
-	return `${code}${subject}`;
-}
-/** The brief's first line with any content — a leading blank line is not the subject. */
-function firstNonEmptyLine(brief) {
-	for (const line of brief.split("\n")) if (line.trim() !== "") return line;
-	return "";
-}
-/** Lowercase alphanumeric runs; every other character is a separator, never part of a word. */
-function tokenize(text) {
-	return text.toLowerCase().split(/[^a-z0-9]+/).filter((w) => w !== "");
-}
-/**
-* Join whole words with `-` while they fit `budget`, so the label ends on a complete word rather
-* than mid-word. A single first word wider than the whole budget is hard-truncated — that is the
-* only case where a label can end mid-word, and the alternative is no subject at all.
-*/
-function fitWords(words, budget) {
-	if (words.length === 0) return "";
-	let out = words[0].slice(0, budget);
-	for (const word of words.slice(1)) {
-		const next = `${out}-${word}`;
-		if (next.length > budget) break;
-		out = next;
-	}
-	return out;
-}
-//#endregion
-//#region src/session.ts
-/** How each harness's own CLI is launched in the new pane. */
-const LAUNCH_MAP = {
-	claude: "claude",
-	cursor: "cursor-agent",
-	codex: "codex"
-};
-/**
-* Per-harness fresh-context ("reset") command `clear` injects into a warm peer's pane to return
-* its conversation to a cold context without tearing the pane/session down — keyed on genuine
-* fresh-context semantics, never on the literal word "clear".
-*/
-const RESET_MAP = {
-	claude: "/clear",
-	codex: "/clear",
-	copilot: "/clear",
-	cursor: "/new-chat"
-};
-/**
-* Harnesses whose apparent "clear" command does NOT truly empty the model context — e.g. gemini's
-* `/clear` wipes only the terminal screen, leaving the model's own context stale. There is no
-* honest fresh-context command for these, so they are refused explicitly rather than lumped in
-* with a harness that is merely unmapped.
-*/
-const FALSE_FRIEND_HARNESSES = /* @__PURE__ */ new Set(["gemini"]);
-/**
-* Resolve `harness`'s own fresh-context command from the reset map. String-keyed (not `Harness`)
-* so it also guards a harness present in `LAUNCH_MAP`/`identity.ts`'s `Harness` union but not yet
-* given an honest reset mapping here. Throws rather than guessing:
-* - a known false-friend harness (its "clear" only clears the screen, not the context)
-* - any harness absent from the map entirely
-*/
-function resetCommandFor(harness) {
-	const mapped = RESET_MAP[harness];
-	if (mapped) return mapped;
-	if (FALSE_FRIEND_HARNESSES.has(harness)) throw new Error(`"${harness}" has no honest fresh-context command — its own "/clear" clears only the terminal screen, not the model context, so unit clear refuses to send a false-friend reset that would leave stale context behind`);
-	throw new Error(`"${harness}" is not in the reset map (${Object.keys(RESET_MAP).join(" | ")}) — unit clear refuses to guess a command`);
-}
-/**
-* Launch a new peer session as a genuine sibling unit: create a real git worktree distinct from
-* the primary checkout (refuse the primary checkout), open a session backend (tmux or herdr) with
-* its cwd set to that worktree, pre-register the peer, and drop its brief as a file — never typed
-* into its prompt. Nothing loads that file for the peer: it is the spawn wake that tells the peer to
-* go read it, naming its path (`spawnAndWake` below, and ADR-0032). `spawn` alone therefore leaves a
-* peer sitting idle with its brief unread, which is why callers want `spawnAndWake`.
-*
-* Spawned unit worktrees live sibling to the primary checkout (`<parent>/<repo>.worktrees/legion-<id6>`),
-* never nested inside it, even though the registry/mailbox itself lives in the global hub — the hub
-* addresses units across project and worktree boundaries, but a unit's checkout is necessarily
-* scoped to this one project's git remote.
-*/
-function spawn(ctx, input) {
-	ctx.store.ensureMarker();
-	const env = ctx.env ?? process.env;
-	const exec = ctx.exec ?? realExec;
-	const sessionAdapter = selectSessionAdapter(env, exec);
-	const normalizedEnv = normalizeMuxEnv(env);
-	const harness = input.harness;
-	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");
-	const id = randomId();
-	const primaryRoot = resolvePrimaryRoot(exec);
-	const launch = input.command ?? LAUNCH_MAP[harness];
-	const fullLaunch = `${muxEnvPrefix(sessionAdapter.name)}${launch}`;
-	const from = callerPane(sessionAdapter, normalizedEnv);
-	let cwd;
-	let worktree;
-	let target;
-	if (input.cwd) {
-		if (!existsSync(input.cwd)) throw new Error(`--cwd directory must already exist: ${input.cwd}`);
-		cwd = resolve(input.cwd);
-		assertDistinctFromPrimary(cwd, primaryRoot);
-		worktree = null;
-		const at = input.at ?? "tab";
-		target = sessionAdapter.open(exec, {
-			cwd,
-			launch: fullLaunch,
-			at,
-			from,
-			...labelFor(at, input, brief, id)
-		});
-	} else {
-		const branch = input.branch ?? `cyberlegion/unit-${id}`;
-		const at = input.at ?? "workspace";
-		const worktreePath = input.worktreePath ?? resolveUnitWorktreePath(primaryRoot, id.slice(0, 6));
-		assertDistinctFromPrimary(resolve(worktreePath), primaryRoot);
-		if (at === "workspace" && sessionAdapter.worktree) {
-			const opened = sessionAdapter.worktree.createInWorkspace(exec, {
-				primaryRoot,
-				branch,
-				path: worktreePath,
-				launch: fullLaunch,
-				...labelFor(at, input, brief, id)
-			});
-			assertDistinctFromPrimary(opened.worktree.root, primaryRoot);
-			ensureMarker(join(opened.worktree.root, ".agents", "cyberlegion"));
-			cwd = opened.worktree.root;
-			worktree = opened.worktree;
-			target = opened.target;
-		} else {
-			const added = gitWorktreeAdapter.add(exec, {
-				primaryRoot,
-				path: worktreePath,
-				branch
-			});
-			assertDistinctFromPrimary(added.root, primaryRoot);
-			ensureMarker(join(added.root, ".agents", "cyberlegion"));
-			cwd = added.root;
-			worktree = added;
-			target = sessionAdapter.open(exec, {
-				cwd,
-				launch: fullLaunch,
-				at,
-				from,
-				...labelFor(at, input, brief, id)
-			});
-		}
-	}
-	const ts = new Date(ctx.now?.() ?? Date.now()).toISOString();
-	const muxName = sessionAdapter.name;
-	const rec = {
-		id,
-		handle: input.handle ?? id.slice(0, 6),
-		harness,
-		cwd,
-		worktree,
-		pane: muxName === "tmux" || muxName === "herdr" ? {
-			mux: muxName,
-			id: target.id
-		} : null,
-		status: "active",
-		createdAt: ts,
-		lastSeen: ts,
-		brief: paths.briefFile(ctx.store.root, id),
-		...resolveSelfId(ctx) ? { spawnedBy: resolveSelfId(ctx) } : {}
-	};
-	saveAgent(ctx.store, rec);
-	ctx.store.putPaneIndex(target.id, id);
-	ctx.store.writeBrief(id, brief);
-	return {
-		agent: rec,
-		pane: target.id,
-		launch
-	};
-}
-/**
-* `unit spawn` end to end: open the peer, then deliver its first turn.
-*
-* The two acts live together here rather than at the CLI call site so the **brief path the doorbell
-* names is derived from the record `spawn` just wrote**, not handed in by a caller. That is the
-* point of the seam: a caller cannot ring with the wrong path because it supplies no path — an
-* empty string, a stale path, or the brief's whole body are all unrepresentable here, rather than
-* merely untested.
-*
-* The ring is best-effort on top of the guaranteed spawn effect (worktree + session + registry
-* record): `--no-wake` rings nothing, and a ring that never completes is reported as a warning on
-* the result rather than thrown, so it can never fail a spawn that already landed.
-*/
-async function spawnAndWake(ctx, input, options = {}) {
-	const res = spawn(ctx, input);
-	const env = ctx.env ?? process.env;
-	const exec = ctx.exec ?? realExec;
-	const briefPath = res.agent.brief;
-	const wake = await wakeSpawn(() => selectSessionAdapter(env, exec), exec, {
-		target: { id: res.pane },
-		briefPath: briefPath ?? "",
-		noWake: options.noWake || !briefPath
-	}, options.nudgeOpts);
-	return {
-		...res,
-		rung: wake.rung,
-		...wake.warning ? { warning: wake.warning } : {}
-	};
-}
-/**
-* The label a `workspace` placement opens under — the short human-scannable name that makes a unit's
-* own visible space findable by eye (`console/workspace-label.ts` owns the naming rule). Only the
-* `workspace` placement carries one: a pane or tab lives inside a space the caller is already
-* looking at, so it has nothing of its own to name. Spread into the adapter options, so a
-* non-workspace placement passes no `label` key at all rather than an explicit `undefined`.
-*
-* The gate is load-bearing, not defensive: cyber-mux names whatever tier `at` opens — a workspace,
-* a tab, or a pane — so passing a label on a `tab` placement would rename the caller's own tab.
-* Exported so that gate is tested directly rather than only through a backend's arguments.
-*/
-function labelFor(at, input, brief, id) {
-	if (at !== "workspace") return {};
-	return { label: deriveWorkspaceLabel({
-		brief,
-		handle: input.handle,
-		id
-	}) };
-}
-/**
-* The env prefix typed ahead of the launch command so the spawned peer inherits the caller's
-* multiplexer fast-path and never has to run its own ancestry discovery (`$CYBER_MUX` /
-* `$CYBER_MUX_PANE`). `VAR=val cmd` scopes the vars to that one process (and its children)
-* without needing `export`. tmux natively sets `$TMUX_PANE` for a pane's own processes, so the
-* pane var is expanded by the child's own shell rather than baked in here.
-*/
-function muxEnvPrefix(muxName) {
-	if (muxName === "tmux") return "CYBER_MUX=tmux CYBER_MUX_PANE=$TMUX_PANE ";
-	if (muxName === "herdr") return "CYBER_MUX=herdr ";
-	return "";
-}
-/**
-* Resolve a unit's live session pane from a ref, or throw naming the ref. The one place
-* focus/nudge/read agree on what "addressable" means — a record's own pane, else a pane pointer
-* keyed by its id (a herdr peer stores its pane only in that index).
-*/
-function paneTargetOf(ctx, ref) {
-	const agent = resolveAgent(ctx.store, ref);
-	const pane = agent.pane?.id ?? ctx.store.findPaneByAgentId(agent.id);
-	if (!pane) throw new Error(`unit "${ref}" has no known session pane`);
-	return {
-		agent,
-		target: { id: pane }
-	};
-}
-/**
-* Move input focus to a peer's session. The adapter beams the attached view all the way there —
-* across workspace and tab — rather than no-opping when the peer sits outside the caller's current
-* workspace, and surfaces a backend failure instead of reporting a false success.
-*
-* Lives here rather than inline in the CLI for the same reason `spawnAndWake` does: composed at the
-* call site it took a hardcoded `realExec`, so the operation could not be driven with an injected
-* exec and its success path was unreachable from a test.
-*/
-function focusUnit(ctx, ref) {
-	const { agent, target } = paneTargetOf(ctx, ref);
-	const exec = ctx.exec ?? realExec;
-	selectSessionAdapter(ctx.env ?? process.env, exec).focus(exec, target);
-	return {
-		agent,
-		pane: target.id
-	};
-}
-/**
-* Ring a peer's session as a **taken turn**, not fire-and-forget: `nudge` submits, reads the pane
-* back to confirm the text is no longer staged, and flushes the staged buffer (never re-typing) up
-* to a bounded cap — then throws if the peer never took the turn. A doorbell must carry text; an
-* empty ring is a no-op, so the default points the peer at its inbox.
-*/
-async function nudgeUnit(ctx, ref, options = {}) {
-	const { agent, target } = paneTargetOf(ctx, ref);
-	const exec = ctx.exec ?? realExec;
-	const message = options.message || "You have unread mail — check your inbox.";
-	const result = await nudge(selectSessionAdapter(ctx.env ?? process.env, exec), exec, target, message, options.nudgeOpts);
-	return {
-		agent,
-		pane: target.id,
-		message,
-		resubmits: result.resubmits
-	};
-}
-/** Scrape the trailing output of a peer's session screen. */
-function readUnit(ctx, ref, options = {}) {
-	const { agent, target } = paneTargetOf(ctx, ref);
-	const exec = ctx.exec ?? realExec;
-	const output = selectSessionAdapter(ctx.env ?? process.env, exec).read(exec, target, { lines: options.lines }).text;
-	return {
-		agent,
-		pane: target.id,
-		output
-	};
-}
-/**
-* Reset a warm peer's context to cold WITHOUT tearing anything down — injects the peer's own
-* harness fresh-context command (`resetCommandFor`) into its pane through the session adapter.
-* Warmth is the unit (pane/process stays warm — no cold-start), coldness is the context. The
-* command is resolved (and any false-friend/unmapped harness throws) BEFORE anything is sent, so
-* a fail-loud harness never has anything typed into its pane. Touches neither the registry record
-* nor the worktree — `close` (`decommission`) owns teardown.
-*/
-function clearUnit(ctx, ref) {
-	const { agent, target } = paneTargetOf(ctx, ref);
-	const pane = target.id;
-	if (!agent.harness) throw new Error(`unit "${ref}" has no harness on record — cannot resolve its reset command`);
-	const command = resetCommandFor(agent.harness);
-	const env = ctx.env ?? process.env;
-	const exec = ctx.exec ?? realExec;
-	selectSessionAdapter(env, exec).submit(exec, { id: pane }, command);
-	return {
-		agent,
-		pane,
-		command
-	};
-}
-/** Resolve a spawn brief from --brief-file, --task -, or --task <text>; null if no source given. */
-function resolveBrief(input, readStdin = () => readFileSync(0, "utf8")) {
-	if (input.briefFile) return readFileSync(input.briefFile, "utf8");
-	if (input.task === "-") return readStdin();
-	if (input.task != null && input.task !== "") return input.task;
-	return null;
-}
-//#endregion
-//#region src/agentdef/realize.ts
-const DEFAULT_HARNESS = "claude";
-/** POSIX single-quote a value for safe inclusion in a shell command line. */
-function shellQuote(value) {
-	return `'${value.replace(/'/g, `'\\''`)}'`;
-}
-/** Build the harness launch invocation for a def — explicit `model`/`harness` win over the def's
-* own tags, which win over the harness default. Every harness gets the same shape (bin,
-* `--model` when known, `--append-system-prompt` carrying the def's instructions body) since the
-* exact per-harness flag surface is realized later by the launching caller, not by cyberlegion. */
-function realizeLaunch(def, opts = {}) {
-	const harness = opts.harness ?? def.harness ?? DEFAULT_HARNESS;
-	const model = opts.model ?? def.model;
-	const parts = [LAUNCH_MAP[harness]];
-	if (model) parts.push("--model", shellQuote(model));
-	if (def.instructions) parts.push("--append-system-prompt", shellQuote(def.instructions));
-	return {
-		harness,
-		command: parts.join(" ")
-	};
-}
-/**
-* Resolve what `unit spawn` should launch, from either an explicit `--harness` or an agent def
-* (`--agent` / `--agent-file`) whose harness, model and instructions compose the launch command.
-* An explicit `--harness` overrides the def's own.
-*
-* Extracted from the CLI action so the def→launch wiring is reachable from a test: composed inline
-* it sat between two well-covered halves (`resolveAgentDef`, `realizeLaunch`) with nothing
-* exercising the join between them.
-*/
-function resolveSpawnLaunch(input) {
-	if (!input.agent && !input.agentFile) return { harness: input.harness };
-	const realized = realizeLaunch(resolveAgentDef({
-		name: input.agent,
-		file: input.agentFile,
-		...input.cwd ? { cwd: input.cwd } : {},
-		...input.searchRoots ? { searchRoots: input.searchRoots } : {}
-	}), { harness: input.harness });
-	return {
-		harness: realized.harness,
-		command: realized.command
-	};
-}
-//#endregion
-//#region src/decommission.ts
-/**
-* Tear a unit down and reap its registry record — the deterministic inverse of `spawn`. Refuses
-* the primary checkout (absolute — `--force` never overrides it) and a dirty worktree unless
-* `--force`. Teardown always precedes reap: an already-gone worktree or pane is tolerated, but a
-* genuine worktree-removal failure aborts and leaves the record intact so the operation is
-* retryable.
-*/
-function decommission(ctx, input) {
-	const rec = loadAgent(ctx.store, input.id);
-	if (!rec) throw new Error(`no unit registered as agents/${input.id}.json — nothing to decommission`);
-	const exec = ctx.exec ?? realExec;
-	const env = ctx.env ?? process.env;
-	const worktreeRoot = rec.worktree?.root;
-	const primaryRoot = worktreeRoot ? resolvePrimaryRoot(exec) : void 0;
-	if (worktreeRoot && resolve(worktreeRoot) === resolve(primaryRoot)) throw new Error(`refusing to decommission "${input.id}" — its worktree is the primary checkout; --force does not override this`);
-	const worktreeExists = worktreeRoot != null && existsSync(worktreeRoot);
-	if (worktreeExists && !input.force && isDirty(exec, worktreeRoot)) throw new Error(`unit "${input.id}" has uncommitted changes in its worktree — pass --force to discard them`);
-	const pane = rec.pane?.id ?? ctx.store.findPaneByAgentId(input.id);
-	if (worktreeExists) try {
-		gitWorktreeAdapter.remove(exec, worktreeRoot, { primaryRoot });
-	} catch (err) {
-		throw new Error(`decommission "${input.id}" aborted — worktree removal failed, record left intact for retry: ${err instanceof Error ? err.message : String(err)}`);
-	}
-	if (pane) try {
-		selectSessionAdapter(env, exec).teardown(exec, { id: pane });
-	} catch {}
-	ctx.store.removeAgent(input.id);
-	if (pane) ctx.store.removePaneIndex(pane);
-	ctx.store.removeAgentData(input.id);
-	return {
-		agent: rec,
-		worktreeRoot,
-		pane
-	};
-}
-function isDirty(exec, worktreeRoot) {
-	return !!exec("git", [
-		"-C",
-		worktreeRoot,
-		"status",
-		"--porcelain"
-	]);
-}
-//#endregion
-//#region 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)`);
-}
-const hookCommand = (event, pin) => pin ? `npx cyberlegion@${pin} mail hook --event ${event}` : `npx cyberlegion mail hook --event ${event}`;
-function hookTarget(command) {
-	return command.match(/^(?:npx cyberlegion(?:@[^\s]+)?|cyberlegion) (mail hook --event \S+)$/)?.[1];
-}
-const VENDORS = {
-	claude: {
-		file: ".claude/settings.json",
-		shape: "claude",
-		events: {
-			SessionStart: "SessionStart",
-			PostToolUse: "PostToolUse"
-		}
-	},
-	cursor: {
-		file: ".cursor/hooks.json",
-		shape: "cursor",
-		events: { SessionStart: "sessionStart" }
-	},
-	codex: {
-		file: ".codex/hooks.json",
-		shape: "cursor",
-		events: {
-			SessionStart: "SessionStart",
-			PostToolUse: "PostToolUse"
-		}
-	}
-};
-function readJson(file) {
-	if (!existsSync(file)) return {};
-	try {
-		return JSON.parse(readFileSync(file, "utf8"));
-	} catch {
-		return {};
-	}
-}
-function writeJson$1(file, data) {
-	mkdirSync(dirname(file), { recursive: true });
-	writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`);
-}
-/** Register the surfacing hook into one harness's config, idempotently. */
-function install(harness, projectDir = process.cwd(), pin) {
-	const spec = VENDORS[harness];
-	if (!spec) throw new Error(`unknown harness "${harness}" (expected claude | cursor | codex)`);
-	if (pin !== void 0) validatePin(pin);
-	const file = join(projectDir, spec.file);
-	const settings = readJson(file);
-	const results = [];
-	for (const [canonical, vendorEvent] of Object.entries(spec.events)) {
-		const command = hookCommand(canonical, pin);
-		const status = spec.shape === "claude" ? upsertClaude(settings, vendorEvent, command) : upsertCursor(settings, vendorEvent, command);
-		results.push({
-			harness,
-			event: canonical,
-			vendorEvent,
-			file,
-			status
-		});
-	}
-	writeJson$1(file, settings);
-	return results;
-}
-function upsertClaude(settings, event, command) {
-	const hooks = settings.hooks ??= {};
-	const groups = hooks[event] ??= [];
-	const target = hookTarget(command);
-	for (const g of groups) for (const h of g.hooks ?? []) {
-		if (h.command === command) return "already present";
-		if (target && hookTarget(h.command) === target) {
-			h.command = command;
-			return "already present";
-		}
-	}
-	const group = { hooks: [{
-		type: "command",
-		command
-	}] };
-	if (event === "PostToolUse") group.matcher = "Write|Edit";
-	groups.push(group);
-	return "registered";
-}
-function upsertCursor(settings, event, command) {
-	if (settings.version == null) settings.version = 1;
-	const hooks = settings.hooks ??= {};
-	const list = hooks[event] ??= [];
-	const target = hookTarget(command);
-	for (const h of list) {
-		if (h.command === command) return "already present";
-		if (target && hookTarget(h.command) === target) {
-			h.command = command;
-			return "already present";
-		}
-	}
-	list.push({ command });
-	return "registered";
-}
-//#endregion
-//#region 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);
-	const from = loadAgent(ctx.store, input.fromId);
-	const ts = ctx.now?.() ?? Date.now();
-	const msg = {
-		id: `${ts}-${randomBytes(3).toString("hex")}`,
-		from: input.fromId,
-		fromHandle: from?.handle ?? input.fromId,
-		to: toId,
-		...input.subject ? { subject: input.subject } : {},
-		body: input.body,
-		...input.thread ? { thread: input.thread } : {},
-		...input.replyTo ? { replyTo: input.replyTo } : {},
-		ts,
-		sentAt: new Date(ts).toISOString()
-	};
-	ctx.store.putMessage(toId, msg);
-	return msg;
-}
-/** Resolve a message body from the --body flag, a --body-file path, or stdin (--body-file -). */
-function resolveBody(body, bodyFile, readStdin = () => readFileSync(0, "utf8")) {
-	if (body != null) return body;
-	if (bodyFile) return bodyFile === "-" ? readStdin() : readFileSync(bodyFile, "utf8");
-	throw new Error("provide --body <text> or --body-file <path|->");
-}
-/** List the caller's mail, chronological (lexical id sort == time order). */
-function inbox(ctx, q) {
-	const snap = ctx.store.listInbox(q.meId);
-	const unread = snap.unread.map((m) => ({
-		...m,
-		read: false
-	}));
-	const acked = q.unread ? [] : snap.read.map((m) => ({
-		...m,
-		read: true
-	}));
-	let items = [...unread, ...acked];
-	if (q.from) items = items.filter((m) => m.from === q.from || m.fromHandle === q.from);
-	if (q.thread) items = items.filter((m) => m.thread === q.thread);
-	return items.sort((a, b) => a.id.localeCompare(b.id));
-}
-/** Peek at a message (unread or already-acked) without changing its state. */
-function peek(ctx, meId, msgId) {
-	const snap = ctx.store.listInbox(meId);
-	return [...snap.unread, ...snap.read].find((m) => m.id === msgId);
-}
-/** Acknowledge a message by moving it out of the unread set. Errors if not currently unread. */
-function ack(ctx, meId, msgId) {
-	return ctx.store.ackMessage(meId, msgId);
-}
-/** Read and consume a message in one atomic step: returns the body and acks it if still unread.
-* Idempotent — an already-acked message is returned with `acked: false` rather than erroring (unlike
-* bare `ack`); an unknown message id throws. Backs `mail read --ack`. */
-function readAck(ctx, meId, msgId) {
-	const snap = ctx.store.listInbox(meId);
-	if (snap.unread.some((m) => m.id === msgId)) return {
-		msg: ctx.store.ackMessage(meId, msgId),
-		acked: true
-	};
-	const already = snap.read.find((m) => m.id === msgId);
-	if (already) return {
-		msg: already,
-		acked: false
-	};
-	throw new Error(`"${msgId}" is not a message in this inbox`);
-}
-/** Permanently remove a message (unread or already-acked) from the caller's inbox. */
-function deleteMessage(ctx, meId, msgId) {
-	ctx.store.removeMessage(meId, msgId);
-}
-//#endregion
-//#region src/output.ts
-function stringifyCell(v) {
-	if (v == null) return "";
-	const s = String(v);
-	return /[,\n"]/.test(s) ? `"${s.replace(/"/g, "\"\"")}"` : s;
-}
-/** One TOON-encoded object: `key: value` lines, blank/undefined fields dropped. */
-function toonObject(fields) {
-	return Object.entries(fields).filter(([, v]) => v != null).map(([k, v]) => `${k}: ${v}`).join("\n");
-}
-/** One TOON-encoded list: a `name[N]{field,...}:` header plus one row per item, then an aggregate
-* summary line. Definitive on empty — still emits `name[0]{...}:` plus the summary line. */
-function toonList(name, items, fields, summary) {
-	return [
-		`${name}[${items.length}]{${fields.map((f) => f.key).join(",")}}:`,
-		...items.map((item) => fields.map((f) => stringifyCell(f.get(item))).join(",")).map((r) => `  ${r}`),
-		summary
-	].join("\n");
-}
-/** Print a command's result to stdout in the requested format. */
-function emit(format, payload) {
-	if (format === "json") console.log(JSON.stringify(payload.json, null, 2));
-	else console.log(payload.toon);
-}
-/** A stderr-only next-step suggestion — never part of the machine-readable stdout result. */
-function nextStep(msg) {
-	console.error(`→ ${msg}`);
-}
-/** A structured, fail-loud error: stderr + exit 1. Never prompts, never partially writes. */
-function fail(msg) {
-	console.error(JSON.stringify({ error: msg }));
-	process.exit(1);
-}
-//#endregion
-//#region src/runtime/inject-inbox.ts
-const EVENTS = ["SessionStart", "PostToolUse"];
-/**
-* Resolve the calling agent, gather its unread mail (and a standing owner's, when this session is
-* the hub's main pane), and return the SessionStart-style injection payload — or null when there is
-* nothing to inject (an unregistered caller or an empty inbox never fails the harness hook).
-*
-* This never injects a brief. Brief delivery is the spawn wake's job: the first-turn doorbell
-* carries the instruction and names the brief's file path, so pickup does not depend on this hook
-* firing in the child (`unit/lifecycle`, superseding ADR-0027).
-*/
-function injectInbox(ctx, event) {
-	if (!EVENTS.includes(event)) throw new Error(`unsupported --event "${event}" (expected ${EVENTS.join(" | ")})`);
-	let meId = resolveSelfId(ctx);
-	if (!meId) {
-		if (currentPane(normalizeMuxEnv(ctx.env ?? process.env))) try {
-			register(ctx, {});
-			meId = resolveSelfId(ctx);
-		} catch {
-			return null;
-		}
-		if (!meId) return null;
-	}
-	const parts = [];
-	const rec = loadAgent(ctx.store, meId);
-	const unread = inbox({ store: ctx.store }, {
-		meId,
-		unread: true
-	});
-	if (unread.length > 0) {
-		const lines = unread.map((m) => `- **${m.fromHandle}**${m.subject ? ` — ${m.subject}` : ""}: ${m.body} \`(${m.id})\``);
-		parts.push(`## Unread mail (${unread.length})\n\n${lines.join("\n")}`);
-	}
-	const cur = currentPane(normalizeMuxEnv(ctx.env ?? process.env));
-	if (rec && !rec.spawnedBy) try {
-		const bound = ctx.store.getMainPane();
-		if (!bound || cur?.pane === bound) {
-			const standing = listAgents(ctx.store).filter((a) => a.kind === "standing");
-			for (const owner of standing) {
-				const ownerUnread = inbox({ store: ctx.store }, {
-					meId: owner.id,
-					unread: true
-				});
-				if (ownerUnread.length === 0) continue;
-				const lines = ownerUnread.map((m) => `- **${m.fromHandle}**${m.subject ? ` — ${m.subject}` : ""}: ${m.body} \`(${m.id})\``);
-				parts.push(`## Owner mail — ${owner.handle} (${ownerUnread.length})\n\n${lines.join("\n")}`);
-			}
-		}
-	} catch {}
-	if (rec && !rec.spawnedBy) try {
-		if (cur ? !ctx.store.getMainPane() : !listAgents(ctx.store).some((a) => a.kind === "standing")) parts.push("## Legion setup\n\nThis pane has no owner inbox bound yet — run `cyberlegion init` to register the surfacing hook and bind this pane as the owner live presence.");
-	} catch {}
-	if (parts.length === 0) return null;
-	return { hookSpecificOutput: {
-		hookEventName: event,
-		additionalContext: parts.join("\n\n")
-	} };
-}
-//#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
-* error so a caller can report exactly what's broken and where, rather than "Unexpected token" with
-* no location. */
-var CorruptRecordError = class extends Error {
-	file;
-	constructor(file, cause) {
-		super(`corrupt record at "${file}": ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
-		this.file = file;
-		this.name = "CorruptRecordError";
-	}
-};
-//#endregion
-//#region 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
-* errno that means "definitely dead". Every other errno — `EPERM` above all, common under sandboxes
-* and containers where a genuinely live process can be unsignalable by this one, or any process
-* owned by a different uid — reads as `'unknown'`, never `'dead'`: collapsing `EPERM` into "dead" is
-* exactly the defect this three-state return exists to make structurally impossible to reintroduce
-* at a new call site. Same-pid is trivially `'alive'` (a process checking its own prior identity,
-* e.g. after a crash-and-restart that reused nothing).
-*/
-function probeProcess(pid) {
-	if (pid === process.pid) return "alive";
-	try {
-		process.kill(pid, 0);
-		return "alive";
-	} catch (err) {
-		return err.code === "ESRCH" ? "dead" : "unknown";
-	}
-}
-//#endregion
-//#region src/store/lock.ts
-var LockTimeoutError = class extends Error {
-	name;
-	constructor(name) {
-		super(`timed out waiting for lock "${name}"`);
-		this.name = name;
-		this.name = "LockTimeoutError";
-	}
-};
-function locksDir(root) {
-	return join(root, "locks");
-}
-function lockDirFor(root, name) {
-	return join(locksDir(root), `${name}.lock`);
-}
-/** Read a lock dir's recorded holder. Absent/corrupt/mid-acquire (holder.json not written yet) all
-* read as "unknown" — never grounds to steal. An ambiguous read must never look like a green light. */
-function readHolder(dir) {
-	try {
-		return JSON.parse(readFileSync(join(dir, "holder.json"), "utf8"));
-	} catch {
-		return;
-	}
-}
-/** Locking's policy on `probeProcess`'s `'unknown'` state: treat it exactly like `'alive'` — i.e.
-* NOT `'dead'`. The one invariant that must never break here is stealing a lock a live holder still
-* holds, and `'unknown'` means "cannot rule out alive", so it can only ever be safe to fold it into
-* the "do not steal" side. This is a local policy decision, not `probeProcess`'s — a different call
-* site (a staleness reaper, say) folding `'unknown'` into "not provably alive" instead would be
-* reading the SAME three states toward the opposite default, which is exactly the bug class this
-* three-state type exists to force each call site to decide explicitly (see process-liveness.ts). */
-function heldByLiveOrUnknownPid(pid) {
-	return probeProcess(pid) !== "dead";
-}
-function sleepSync(ms) {
-	if (ms <= 0) return;
-	Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-}
-/**
-* Attempt to reclaim an abandoned lock dir without ever discarding a LIVE one out from under its
-* holder — the exact defect agmsg/firstmate's lock suites exist to catch (evidence.md items 3-4).
-*
-* `mkdirSync` on the lock path itself already arbitrates ordinary contention (EEXIST = someone else
-* got there first); the harder race is a STEAL: two processes independently deciding the same lock
-* looks dead. `renameSync` gives the same exclusivity `mkdirSync` gives for a fresh path, but for an
-* EXISTING one — of any number of processes racing to rename the SAME source path away, exactly one
-* succeeds and the rest get ENOENT. So the rename-away is the sole arbiter of "who gets to attempt
-* the steal", not the earlier staleness read.
-*
-* That still leaves one race: the content we read as stale might not be the content we actually
-* capture, if the true holder released and a NEW, live holder re-acquired at this same path between
-* our staleness read and our rename. So after winning the rename, re-check the pid we ACTUALLY
-* captured (not the one from the earlier read) — if it's alive, this was a live lock we grabbed by
-* accident; put it back immediately (best-effort — if a third party has since re-mkdir'd the path,
-* the invariant we're protecting already holds, so just drop our capture) and refuse to finalize.
-*/
-function tryReclaimStale(dir) {
-	const grave = `${dir}.stale-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
-	try {
-		renameSync(dir, grave);
-	} catch (err) {
-		if (err.code === "ENOENT") return false;
-		throw err;
-	}
-	const captured = readHolder(grave);
-	if (captured && heldByLiveOrUnknownPid(captured.pid)) {
-		try {
-			renameSync(grave, dir);
-		} catch {
-			rmSync(grave, {
-				recursive: true,
-				force: true
-			});
-		}
-		return false;
-	}
-	rmSync(grave, {
-		recursive: true,
-		force: true
-	});
-	return true;
-}
-/**
-* Acquire an advisory, mkdir-based lock at `root/locks/<name>.lock`. mkdir (not O_EXCL on a file) is
-* the primitive here because a lock also needs to carry its holder metadata (pid + timestamp) for
-* staleness detection, and a directory gives that a natural home (`holder.json` inside it) without a
-* second file to keep in sync; `mkdirSync` on a non-existent path is exactly as atomic as an
-* exclusive file create on every filesystem this tool targets (POSIX; NTFS via Node's Win32 mkdir).
-*
-* Blocks (busy-retries) until acquired or `timeoutMs` elapses, reclaiming a dead holder's lock along
-* the way (see `tryReclaimStale`) but NEVER a live one — contention with a live holder always waits
-* it out or times out, never steals.
-*/
-function acquireLock(root, name, opts = {}) {
-	const retryDelayMs = opts.retryDelayMs ?? 20;
-	const timeoutMs = opts.timeoutMs ?? 5e3;
-	const dir = lockDirFor(root, name);
-	mkdirSync(locksDir(root), { recursive: true });
-	const deadline = Date.now() + timeoutMs;
-	for (;;) try {
-		mkdirSync(dir);
-		writeFileSync(join(dir, "holder.json"), JSON.stringify({
-			pid: process.pid,
-			acquiredAt: Date.now()
-		}));
-		return { release: () => rmSync(dir, {
-			recursive: true,
-			force: true
-		}) };
-	} catch (err) {
-		if (err.code !== "EEXIST") throw err;
-		const holder = readHolder(dir);
-		if (holder && !heldByLiveOrUnknownPid(holder.pid) && tryReclaimStale(dir)) continue;
-		if (Date.now() > deadline) throw new LockTimeoutError(name);
-		sleepSync(retryDelayMs);
-	}
-}
-/** Acquire `name`, run `fn`, and always release — the shape every genuine read-modify-write in the
-* store should use (`setMainPane`, `identity.ts`'s `claimPresence`/`clearPresence` today). */
-function withLock(root, name, fn, opts) {
-	const handle = acquireLock(root, name, opts);
-	try {
-		return 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
-* `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
-* exist is a caller error — callers check existence first, so this only ever sees files known to
-* be present but possibly torn (a crash mid-write predating the atomic-write fix, or on-disk
-* tampering) — see evidence.md item 5, "no silent success on a broken store". */
-function readJsonRecord(file) {
-	const raw = readFileSync(file, "utf8");
-	try {
-		return JSON.parse(raw);
-	} catch (err) {
-		throw new CorruptRecordError(file, err);
-	}
-}
-function readMessages(dir) {
-	if (!existsSync(dir)) return [];
-	return readdirSync(dir).filter((f) => f.endsWith(".json")).map((f) => readJsonRecord(join(dir, f)));
-}
-/** Write `data` to `file` crash-safely: write to a sibling temp file first, then `renameSync` into
-* place. `rename` is atomic within a filesystem (POSIX guarantees this; Node's Win32 rename is too
-* for same-volume paths, which every path here is — always under the same store root), so any
-* reader either sees the OLD complete content or the NEW complete content, never a truncated
-* in-between. Before this fix, `putMessage`/`putAgent`/`putPaneIndex`/`setMainPane` called
-* `writeFileSync` directly on the final path — only `ackMessage`'s move (a rename of an already-
-* complete file) was atomic. A process crashing mid-`writeFileSync`, or a reader racing a writer on
-* a large record, could hand `JSON.parse` a truncated file and throw an uncaught `SyntaxError` deep
-* inside `listInbox`/`listAgents`/`getAgent`.
-*
-* Deliberately no `fsync` before the rename: this tool defends against a process CRASHING mid-write
-* (the actual, observed risk in a daemonless multi-process CLI), where the page cache alone is
-* sufficient, not against a power-loss/OS-crash losing unflushed pages, which cyberlegion doesn't
-* claim to survive today (no writer here holds data the user can't just re-send). Add fsync if that
-* durability bar ever changes.
-*
-* The temp name embeds pid + a counter so two writers to the SAME final path never collide on their
-* own temp files mid-write (each writer's temp file is unique to it). */
-let tmpCounter = 0;
-function writeFileAtomic(file, data) {
-	mkdirSync(dirname(file), { recursive: true });
-	const tmp = `${file}.${process.pid}.${tmpCounter++}.tmp`;
-	writeFileSync(tmp, data);
-	renameSync(tmp, file);
-}
-function writeJson(file, data) {
-	writeFileAtomic(file, `${JSON.stringify(data, null, 2)}\n`);
-}
-function writeText(file, text) {
-	writeFileAtomic(file, text);
-}
-/** Build a path via `build()` for a READ-only lookup, treating a syntactically-invalid id
-* (`InvalidIdError`) the same as "not found" rather than throwing. Reads are the wrong place to
-* enforce id-shape: `resolveAgent`/`resolveRecipient` (identity.ts) speculatively probe an arbitrary
-* ref — which may legitimately be a worktree BRANCH NAME containing `/` — as a candidate id before
-* falling back to handle/branch lookup, so `getAgent('cyberlegion/unit-abc')` must fail soft, not
-* throw, or that fallback chain breaks. The traversal risk this guards against (an id escaping the
-* store root) only bites on a WRITE — nothing is ever created or overwritten by a probe that finds
-* nothing — so a hard reject stays reserved for the write paths below (`putAgent`, `putMessage`,
-* `putPaneIndex`, `writeBrief`), where a malformed id would otherwise put a stray file wherever it
-* pointed. */
-function readPathOrUndefined(build) {
-	try {
-		return build();
-	} catch (err) {
-		if (err instanceof InvalidIdError) return void 0;
-		throw err;
-	}
-}
-/** The on-disk `Store` implementation — current per-writer sharded `.json` layout (ADR-0020):
-* one file per message/agent, collision-free filenames, ack = atomic rename into `read/`. */
-var FileStore = class {
-	root;
-	constructor(root) {
-		this.root = root;
-	}
-	ensureMarker() {
-		ensureMarker(this.root);
-	}
-	putMessage(toId, msg) {
-		writeFileAtomic(paths.messageFile(this.root, toId, msg.id), `${JSON.stringify(msg, null, 2)}\n`);
-	}
-	listInbox(id) {
-		const inbox = readPathOrUndefined(() => paths.inboxDir(this.root, id));
-		const read = readPathOrUndefined(() => paths.inboxReadDir(this.root, id));
-		return {
-			unread: inbox ? readMessages(inbox) : [],
-			read: read ? readMessages(read) : []
-		};
-	}
-	ackMessage(id, msgId) {
-		const src = readPathOrUndefined(() => paths.messageFile(this.root, id, msgId));
-		if (!src || !existsSync(src)) throw new Error(`"${msgId}" is not an unread message in this inbox`);
-		const msg = readJsonRecord(src);
-		const dest = paths.messageReadFile(this.root, id, msgId);
-		mkdirSync(dirname(dest), { recursive: true });
-		renameSync(src, dest);
-		return msg;
-	}
-	removeMessage(id, msgId) {
-		const unreadFile = readPathOrUndefined(() => paths.messageFile(this.root, id, msgId));
-		if (unreadFile && existsSync(unreadFile)) {
-			rmSync(unreadFile);
-			return;
-		}
-		const readFile = readPathOrUndefined(() => paths.messageReadFile(this.root, id, msgId));
-		if (readFile && existsSync(readFile)) {
-			rmSync(readFile);
-			return;
-		}
-		throw new Error(`"${msgId}" is not a message in this inbox`);
-	}
-	putAgent(rec) {
-		writeJson(paths.agentFile(this.root, rec.id), rec);
-	}
-	getAgent(id) {
-		const file = readPathOrUndefined(() => paths.agentFile(this.root, id));
-		if (!file || !existsSync(file)) return void 0;
-		return readJsonRecord(file);
-	}
-	listAgents() {
-		const dir = paths.agentsDir(this.root);
-		if (!existsSync(dir)) return [];
-		return readdirSync(dir).filter((f) => f.endsWith(".json")).map((f) => readJsonRecord(join(dir, f))).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
-	}
-	removeAgent(id) {
-		rmSync(paths.agentFile(this.root, id), { force: true });
-	}
-	removeAgentData(id) {
-		rmSync(paths.dataDir(this.root, id), {
-			recursive: true,
-			force: true
-		});
-	}
-	putPaneIndex(pane, agentId) {
-		writeText(paths.paneFile(this.root, pane), agentId);
-	}
-	resolvePaneId(pane) {
-		const file = paths.paneFile(this.root, pane);
-		return existsSync(file) ? readFileSync(file, "utf8").trim() : void 0;
-	}
-	findPaneByAgentId(agentId) {
-		const dir = paths.panesDir(this.root);
-		if (!existsSync(dir)) return void 0;
-		for (const f of readdirSync(dir)) {
-			if (!f.endsWith(".id")) continue;
-			if (readFileSync(join(dir, f), "utf8").trim() === agentId) return f.slice(0, -3);
-		}
-	}
-	removePaneIndex(pane) {
-		rmSync(paths.paneFile(this.root, pane), { force: true });
-	}
-	writeBrief(agentId, text) {
-		writeText(paths.briefFile(this.root, agentId), text);
-	}
-	readBrief(agentId) {
-		const file = readPathOrUndefined(() => paths.briefFile(this.root, agentId));
-		return file && existsSync(file) ? readFileSync(file, "utf8") : void 0;
-	}
-	setMainPane(pane) {
-		withLock(this.root, "main-pane", () => {
-			const file = paths.mainPaneFile(this.root);
-			if (pane) {
-				writeText(file, pane);
-				return;
-			}
-			rmSync(file, { force: true });
-		});
-	}
-	getMainPane() {
-		const file = paths.mainPaneFile(this.root);
-		return existsSync(file) ? readFileSync(file, "utf8").trim() : void 0;
-	}
-	withLock(name, fn) {
-		return withLock(this.root, name, fn);
-	}
-};
-//#endregion
-//#region 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;
-const DEFAULT_MAX_WAIT_S = 240;
-/**
-* Block on the caller's UNREAD inbox until a message matching `thread` (and optional `from`)
-* arrives, polling on a fixed ~1s internal interval. Three unambiguous outcomes:
-*
-* - `matched` — a message arrived; it is printed by the caller AND acked here (moved to read/), so
-*   it leaves the unread set. Block-then-read: each await consumes exactly its round.
-* - `waiting` — this call's internal poll cycle hit its `maxWaitS` cap (default 240s, always well
-*   under a harness tool-timeout SIGKILL) with no match yet. A clean, non-error return the caller
-*   re-arms on (calls `awaitReply` again) — NOT the same as giving up.
-* - `timed-out` — the caller's overall `timeoutMs` (default 600_000ms / 600s; `0` = wait forever)
-*   elapsed across re-arms with no match. The caller should exit non-zero.
-*/
-async function awaitReply(ctx, input) {
-	const timeoutMs = input.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-	const maxWaitMs = (input.maxWaitS ?? DEFAULT_MAX_WAIT_S) * 1e3;
-	const now = input.now ?? (() => Date.now());
-	const sleep = input.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
-	const start = now();
-	const cycleDeadline = start + maxWaitMs;
-	for (;;) {
-		const items = inbox(ctx, {
-			meId: input.meId,
-			unread: true,
-			thread: input.thread,
-			from: input.from
-		});
-		if (items.length > 0) {
-			const message = items[0];
-			ack(ctx, input.meId, message.id);
-			return {
-				kind: "matched",
-				message
-			};
-		}
-		const elapsed = now() - start;
-		if (timeoutMs !== 0 && elapsed >= timeoutMs) return { kind: "timed-out" };
-		if (now() >= cycleDeadline) return { kind: "waiting" };
-		await sleep(POLL_MS$1);
-	}
-}
-//#endregion
-//#region src/wake/watch.ts
-const POLL_MS = 1e3;
-/**
-* A continuous foreground observer: prints each NEW matching message as it arrives, polling on a
-* fixed ~1s interval, until interrupted (or `maxIterations` in tests). Never acks — a message
-* `watch` prints stays unread and still surfaces later in `mail inbox`/`mail await`.
-*/
-async function watchMail(ctx, input, onMessage, opts = {}) {
-	const sleep = opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
-	const seen = /* @__PURE__ */ new Set();
-	for (const m of inbox(ctx, {
-		meId: input.meId,
-		thread: input.thread,
-		from: input.from
-	})) seen.add(m.id);
-	let iterations = 0;
-	for (;;) {
-		const items = inbox(ctx, {
-			meId: input.meId,
-			thread: input.thread,
-			from: input.from
-		});
-		for (const m of items) {
-			if (seen.has(m.id)) continue;
-			seen.add(m.id);
-			onMessage(m);
-		}
-		iterations++;
-		if (opts.maxIterations != null && iterations >= opts.maxIterations) return;
-		await sleep(POLL_MS);
-	}
-}
-//#endregion
-export { resolveProjectLocalRoot as $, bumpLastSeen as A, registerStanding as B, nudgeUnit as C, selectSessionAdapter as D, spawnAndWake as E, loadAgent as F, resolveStandingOwner as G, resolvePresence as H, prune as I, listAgentDefs as J, touch as K, realExec as L, clearPresence as M, detectHarness as N, DELIVERY_DOORBELL as O, listAgents as P, projectRoot as Q, reconcile as R, focusUnit as S, spawn as T, resolveRecipient as U, resolveAgent as V, resolveSelfId as W, ensureMarker as X, resolveAgentDef as Y, paths as Z, install as _, emit as a, resolveSpawnLaunch as b, toonList as c, deleteMessage as d, resolveRoot as et, inbox as f, send as g, resolveBody as h, injectInbox as i, claimPresence as j, wakeRecipient as k, toonObject as l, readAck as m, awaitReply as n, fail as o, peek as p, normalizeMuxEnv as q, FileStore as r, nextStep as s, watchMail as t, ack as u, decommission as v, readUnit as w, clearUnit as x, realizeLaunch as y, register as z };