cyberlegion 0.3.2 → 0.5.0

package/dist/index.mjs

@@ -1,4 +1,2298 @@
-import { $ as resolveProjectLocalRoot, A as bumpLastSeen, D as selectSessionAdapter, E as spawnAndWake, F as loadAgent, I as prune, J as listAgentDefs, K as touch, L as realExec, N as detectHarness, P as listAgents, Q as projectRoot, T as spawn, U as resolveRecipient, V as resolveAgent, W as resolveSelfId, X as ensureMarker, Y as resolveAgentDef, Z as paths, _ as install, a as emit, c as toonList, d as deleteMessage, et as resolveRoot, f as inbox, g as send, h as resolveBody, i as injectInbox, l as toonObject, n as awaitReply, o as fail, p as peek, r as FileStore, s as nextStep, t as watchMail, u as ack, v as decommission, y as realizeLaunch, z as register } from "./watch-D33fQcUI.mjs";
-import { probeMultiplexer } from "cyber-mux";
-import { assertDistinctFromPrimary, gitWorktreeAdapter, resolvePrimaryRoot } from "cyber-mux/worktree";
-export { FileStore, ack, assertDistinctFromPrimary, awaitReply, bumpLastSeen, decommission, deleteMessage, detectHarness, emit, ensureMarker, fail, gitWorktreeAdapter, inbox, injectInbox, install, listAgentDefs, listAgents, loadAgent, nextStep, paths, peek, probeMultiplexer, projectRoot, prune, realExec, realizeLaunch, register, resolveAgent, resolveAgentDef, resolveBody, resolvePrimaryRoot, resolveProjectLocalRoot, resolveRecipient, resolveRoot, resolveSelfId, selectSessionAdapter, send, spawn, spawnAndWake, toonList, toonObject, touch, watchMail };
+import { callerPane, currentPane, herdrMuxAdapter, nodeExec, nudge, probeMultiplexer, probeMultiplexer as probeMultiplexer$1, tmuxMuxAdapter } from "cyber-mux";
+import { assertDistinctFromPrimary, assertDistinctFromPrimary as assertDistinctFromPrimary$1, gitWorktreeAdapter, gitWorktreeAdapter as gitWorktreeAdapter$1, resolvePrimaryRoot, resolvePrimaryRoot as resolvePrimaryRoot$1 } from "cyber-mux/worktree";
+import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { createHash, randomBytes } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { homedir } from "node:os";
+//#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/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$1(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"),
+	projectsDir: (root) => join(root, "projects"),
+	serviceLeaseFile: (root, project, service) => join(root, "services", assertSafeId(project, "project id"), `${assertSafeId(service, "service name")}.json`),
+	projectFile: (root, id) => join(root, "projects", `${assertSafeId(id, "project id")}.json`),
+	/** 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/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
+	};
+}
+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 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;
+/** Standing and service records have no session of their own, so nothing about a pane or a timer
+* can declare them dead. */
+function isSessionIndependent(rec) {
+	return rec.kind === "standing" || rec.kind === "service";
+}
+/**
+* Whether a unit's session is still there, as far as its backend can tell. "Cannot rule out alive"
+* must never become grounds to replace an owner — the same fail-closed policy `store/lock.ts` takes
+* on an ambiguous holder — so a session reads as gone only on positive evidence: its multiplexer
+* answered with a pane list and the pane is not in it. A record with no pane cannot be probed, and a
+* backend the caller cannot reach (a different server, no client, a failed query) answers with
+* nothing; both read as live. `paneExists` is not used here because it collapses "unreachable" into
+* "gone". An exited record is never live.
+*/
+function sessionLive(ctx, rec) {
+	if (rec.status === "exited") return false;
+	if (!rec.pane) return true;
+	const panes = PANE_ADAPTERS[rec.pane.mux].listPanes(ctx.exec ?? realExec);
+	if (panes.length === 0) return true;
+	const id = rec.pane.id;
+	return panes.some((p) => p.id === id);
+}
+/** 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 (isSessionIndependent(rec)) 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 (isSessionIndependent(rec)) 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 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
+};
+/**
+* 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$1(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"
+};
+/**
+* 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$1(exec);
+	const launch = input.command ?? LAUNCH_MAP[harness];
+	const launchLine = () => {
+		const shimDir = ctx.self ? writeSelfShim(paths.dataDir(ctx.store.root, id), ctx.self) : void 0;
+		return `${shimDir ? `PATH=${shellQuote$1(shimDir)}:"$PATH" ` : ""}${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$1(cwd, primaryRoot);
+		worktree = null;
+		const at = input.at ?? "tab";
+		target = sessionAdapter.open(exec, {
+			cwd,
+			launch: launchLine(),
+			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$1(resolve(worktreePath), primaryRoot);
+		if (at === "workspace" && sessionAdapter.worktree) {
+			const opened = sessionAdapter.worktree.createInWorkspace(exec, {
+				primaryRoot,
+				branch,
+				path: worktreePath,
+				launch: launchLine(),
+				...labelFor(at, input, brief, id)
+			});
+			assertDistinctFromPrimary$1(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$1.add(exec, {
+				primaryRoot,
+				path: worktreePath,
+				branch
+			});
+			assertDistinctFromPrimary$1(added.root, primaryRoot);
+			ensureMarker(join(added.root, ".agents", "cyberlegion"));
+			cwd = added.root;
+			worktree = added;
+			target = sessionAdapter.open(exec, {
+				cwd,
+				launch: launchLine(),
+				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, composeBrief(brief, input.briefInstructions));
+	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 "";
+}
+/**
+* Write `<dataDir>/bin/cyberlegion`, a POSIX shim that execs `self` with the caller's arguments,
+* and return its directory. A spawned session gets that directory first on its PATH, so the
+* `cyberlegion` a brief tells it to run is the install that spawned it: nothing is resolved from
+* the registry or the session's own PATH at report time.
+*/
+function writeSelfShim(dataDir, self) {
+	const dir = join(dataDir, "bin");
+	mkdirSync(dir, { recursive: true });
+	const shim = join(dir, "cyberlegion");
+	writeFileSync(shim, `#!/bin/sh\nexec ${self.map(shellQuote$1).join(" ")} "$@"\n`);
+	chmodSync(shim, 493);
+	return dir;
+}
+/** Single-quote `s` for a POSIX shell, so any path survives word splitting and expansion. */
+function shellQuote$1(s) {
+	return `'${s.replaceAll("'", "'\\''")}'`;
+}
+/** The brief file's text: the task alone, or — when the harness took no instructions on its command
+* line — the def's instructions under their own heading ahead of it, so the peer can see they reach
+* it as a user turn rather than a system prompt. */
+function composeBrief(brief, instructions) {
+	if (!instructions) return brief;
+	return `## Agent instructions\n\n${instructions}\n\n## Brief\n\n${brief}`;
+}
+/** 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/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;
+}
+/** The known harnesses are exactly those with a launch binary — one home for the set. */
+const HARNESSES = Object.keys(LAUNCH_MAP);
+/** A `harness` tag outside the known set has no launch binary, so a typo fails here, loudly, rather
+* than surfacing later as an unlaunchable command. */
+function toHarness(value, path) {
+	if (value === void 0 || HARNESSES.includes(value)) return value;
+	throw new Error(`agent def "${path}" has unknown harness "${value}" — expected one of ${HARNESSES.join(", ")}`);
+}
+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: toHarness(fm.harness, path),
+		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/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, `'\\''`)}'`;
+}
+/** Cursor carries effort as a bracket parameter on the model (`<model>[effort=<level>]`): merge it into
+* any bracket list the model already has, replacing an `effort=` already there. */
+function withCursorEffort(model, effort) {
+	const open = model.lastIndexOf("[");
+	if (open === -1 || !model.endsWith("]")) return `${model}[effort=${effort}]`;
+	const params = model.slice(open + 1, -1).split(",").filter((p) => p !== "" && !p.startsWith("effort="));
+	return `${model.slice(0, open)}[${[...params, `effort=${effort}`].join(",")}]`;
+}
+/** The model + effort arguments for one harness. No two harnesses spell effort alike: claude has
+* `--effort`, codex only a config override, cursor only a parameter on the model — so a cursor
+* effort with no model has nowhere to go and throws rather than launching at the default effort. */
+function modelAndEffortArgs(harness, model, effort) {
+	if (harness === "cursor") {
+		if (effort && !model) throw new Error(`cursor carries effort only as a parameter on the model; set a model to launch with effort "${effort}"`);
+		if (!model) return [];
+		return ["--model", shellQuote(effort ? withCursorEffort(model, effort) : model)];
+	}
+	const args = model ? ["--model", shellQuote(model)] : [];
+	if (!effort) return args;
+	if (harness === "codex") return [
+		...args,
+		"-c",
+		shellQuote(`model_reasoning_effort="${effort}"`)
+	];
+	return [
+		...args,
+		"--effort",
+		shellQuote(effort)
+	];
+}
+/** A TOML basic string: JSON's escapes are all legal TOML escapes, and TOML also forbids a raw DEL. */
+function tomlBasicString(value) {
+	return JSON.stringify(value).replace(/\x7f/g, "\\u007f");
+}
+/** The instruction arguments for one harness. Only claude has an append-to-system-prompt flag;
+* codex takes a `developer_instructions` config override, added on top of its own base
+* instructions. Cursor has no channel at all — its instructions go to the brief instead. */
+function instructionArgs(harness, instructions) {
+	if (!instructions || harness === "cursor") return [];
+	if (harness === "claude") return ["--append-system-prompt", shellQuote(instructions)];
+	return ["-c", shellQuote(`developer_instructions=${tomlBasicString(instructions)}`)];
+}
+/** Build the harness launch invocation for a def — explicit `model`/`effort`/`harness` win over the
+* def's own tags, which win over the harness default. The def's effort and instructions each go
+* through the harness's own control (see `modelAndEffortArgs`, `instructionArgs`). */
+function realizeLaunch(def, opts = {}) {
+	const harness = opts.harness ?? def.harness ?? DEFAULT_HARNESS;
+	const model = opts.model ?? def.model;
+	const effort = opts.effort ?? def.effort;
+	const parts = [
+		LAUNCH_MAP[harness],
+		...modelAndEffortArgs(harness, model, effort),
+		...instructionArgs(harness, def.instructions)
+	];
+	const briefInstructions = harness === "cursor" && def.instructions ? def.instructions : void 0;
+	return {
+		harness,
+		command: parts.join(" "),
+		model,
+		effort,
+		...briefInstructions ? { briefInstructions } : {}
+	};
+}
+//#endregion
+//#region src/decommission.ts
+/**
+* Tear a unit down and reap its registry record — the deterministic inverse of `spawn`. Refuses
+* the primary checkout (absolute — neither `--force` nor `--keep-worktree` 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.
+*
+* `keepWorktree` reaps everything else — pane, record, pane pointer, brief — and leaves the
+* checkout on disk, reporting it as `retainedWorktree`.
+*/
+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`);
+	if (rec.kind === "service") throw new Error(`refusing to decommission "${input.id}" — it is a service endpoint, not a unit`);
+	const exec = ctx.exec ?? realExec;
+	const env = ctx.env ?? process.env;
+	const worktreeRoot = rec.worktree?.root;
+	const primaryRoot = worktreeRoot ? resolvePrimaryRoot$1(exec) : void 0;
+	if (worktreeRoot && resolve(worktreeRoot) === resolve(primaryRoot)) throw new Error(`refusing to decommission "${input.id}" — its worktree is the primary checkout; neither --force nor --keep-worktree overrides this`);
+	const worktreeExists = worktreeRoot != null && existsSync(worktreeRoot);
+	const removesWorktree = worktreeExists && !input.keepWorktree;
+	if (removesWorktree && !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 (removesWorktree) try {
+		gitWorktreeAdapter$1.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,
+		retainedWorktree: worktreeExists && input.keepWorktree ? worktreeRoot : void 0,
+		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);
+}
+/** 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/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
+* all report the same `.git` — so it is what makes "same project from two worktrees" one reference.
+* Realpath'd so a symlinked path to the same repository cannot mint a second id.
+*/
+function commonDirOf(exec, dir) {
+	const out = exec("git", [
+		"-C",
+		dir,
+		"rev-parse",
+		"--path-format=absolute",
+		"--git-common-dir"
+	]);
+	if (!out) return void 0;
+	return realOrResolved(out);
+}
+/**
+* Derive a project's stable reference from its canonical common dir. Deterministic rather than
+* minted, so two worktrees registering the same project at the same instant converge on one id with
+* no lock, and two unrelated repositories that merely share a directory name never collide.
+*/
+function projectIdOf(commonDir) {
+	return `prj-${createHash("sha256").update(commonDir).digest("hex").slice(0, 16)}`;
+}
+function realOrResolved(path) {
+	try {
+		return realpathSync(path);
+	} catch {
+		return resolve(path);
+	}
+}
+/**
+* The default checkout's root, and whether that answer is authoritative. Asked from the default
+* checkout itself (its git dir IS the common dir), `--show-toplevel` is exact wherever the git dir
+* lives. Asked from a linked worktree, git has no pointer back to the default checkout when its git
+* dir was separated (`git init --separate-git-dir`) — even `git worktree list` then reports the git
+* dir — so the common dir's parent is only a guess.
+*/
+function defaultCheckoutOf(exec, dir, commonDir) {
+	const gitDir = exec("git", [
+		"-C",
+		dir,
+		"rev-parse",
+		"--path-format=absolute",
+		"--git-dir"
+	]);
+	const top = exec("git", [
+		"-C",
+		dir,
+		"rev-parse",
+		"--show-toplevel"
+	]);
+	if (gitDir && top && realOrResolved(gitDir) === commonDir) return {
+		root: realOrResolved(top),
+		exact: true
+	};
+	return {
+		root: dirname(commonDir),
+		exact: false
+	};
+}
+/**
+* Register (or idempotently refresh) the project containing `dir` — any checkout of it, default or
+* linked. Keeps the first `registeredAt`, so re-registering from a worktree is a no-op in effect.
+*/
+function registerProject(ctx, input = {}) {
+	const exec = ctx.exec ?? realExec;
+	const dir = resolve(input.dir ?? process.cwd());
+	const commonDir = commonDirOf(exec, dir);
+	if (!commonDir) throw new Error(`cannot register a project at "${dir}" — not inside a git repository`);
+	ctx.store.ensureMarker();
+	const id = projectIdOf(commonDir);
+	const existing = ctx.store.getProject(id);
+	const checkout = defaultCheckoutOf(exec, dir, commonDir);
+	const root = checkout.exact || !existing ? checkout.root : existing.root;
+	const rec = {
+		id,
+		name: basename(root),
+		root,
+		commonDir,
+		registeredAt: existing?.registeredAt ?? new Date(ctx.now?.() ?? Date.now()).toISOString()
+	};
+	ctx.store.putProject(rec);
+	return rec;
+}
+function listProjects(store) {
+	return store.listProjects();
+}
+function looksLikePath(ref) {
+	return isAbsolute(ref) || ref.startsWith(".") || ref.includes(sep) || ref.includes("/");
+}
+function isDirectory(path) {
+	return existsSync(path) && statSync(path).isDirectory();
+}
+/**
+* Resolve a project from anywhere — by id, by a path inside any of its checkouts, or by name when
+* exactly one registered project carries it. A path registers its project on first use: git has
+* already confirmed it is a repository, and registering is idempotent, so there is nothing a typo
+* could mint. A name never registers — nothing can be found by a name no checkout has reported —
+* and an ambiguous name names its candidates rather than picking one.
+*/
+function resolveProject(ctx, ref) {
+	const byId = ctx.store.getProject(ref);
+	if (byId) return byId;
+	const asPath = resolve(ref);
+	if (looksLikePath(ref) && isDirectory(asPath)) return byPath(ctx, asPath);
+	const named = ctx.store.listProjects().filter((p) => p.name === ref);
+	if (named.length === 1) return named[0];
+	if (named.length > 1) throw new Error(`project name "${ref}" is ambiguous — ${named.map((p) => `${p.id} (${p.root})`).join(", ")}; pass an id or a path`);
+	if (isDirectory(asPath)) return byPath(ctx, asPath);
+	throw new Error(`no registered project "${ref}" (tried id, path, and name) — pass a path inside the repository to register it`);
+}
+function byPath(ctx, dir) {
+	const commonDir = commonDirOf(ctx.exec ?? realExec, 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
+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/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 {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+		this.name = "ServiceOwnershipError";
+	}
+};
+/** How long a reservation holds before another caller may take over a start that never bound. */
+const DEFAULT_RESERVATION_TTL_MS = 3e5;
+const SERVICE_NAME = /^[a-z0-9][a-z0-9_-]{0,62}$/;
+function assertServiceName(name) {
+	if (!SERVICE_NAME.test(name)) throw new Error(`invalid service name "${name}" — use lowercase letters, digits, "-" or "_" (max 63)`);
+}
+function serviceEndpointId(projectId, name) {
+	return `svc-${projectId}-${name}`;
+}
+const nowMs = (ctx) => ctx.now?.() ?? Date.now();
+const iso = (ms) => new Date(ms).toISOString();
+function lockName(projectId, name) {
+	return `service-${projectId}-${name}`;
+}
+function isLive(ctx, unit) {
+	if (unit.status === "exited") return false;
+	return ctx.isLive ? ctx.isLive(unit) : sessionLive(ctx, unit);
+}
+function ensureEndpoint(ctx, project, name) {
+	const id = serviceEndpointId(project.id, name);
+	const existing = loadAgent(ctx.store, id);
+	if (existing) return existing;
+	ctx.store.ensureMarker();
+	const ts = iso(nowMs(ctx));
+	const rec = {
+		id,
+		handle: `${name}@${project.name}`,
+		kind: "service",
+		service: {
+			project: project.id,
+			name
+		},
+		cwd: project.root,
+		pane: null,
+		status: "active",
+		createdAt: ts,
+		lastSeen: ts
+	};
+	saveAgent(ctx.store, rec);
+	return rec;
+}
+function view(ctx, project, endpoint, lease) {
+	const base = {
+		project,
+		endpoint,
+		lease
+	};
+	if (lease.state === "vacant") return {
+		...base,
+		health: "vacant",
+		control: "none"
+	};
+	if (lease.state === "reserved") {
+		const expired = nowMs(ctx) > Date.parse(lease.reservation?.expiresAt ?? "");
+		return {
+			...base,
+			health: expired ? "expired" : "starting",
+			control: "none",
+			...expired ? { note: "the reservation expired without a bound owner; the next acquire takes over" } : {}
+		};
+	}
+	const owner = lease.holder ? loadAgent(ctx.store, lease.holder) : void 0;
+	if (!owner) return {
+		...base,
+		health: "unhealthy",
+		control: "none",
+		note: "the owner has no unit record"
+	};
+	const control = owner.pane || ctx.store.findPaneByAgentId(owner.id) ? "pane" : "none";
+	const controlNote = control === "none" ? "the owner resolves, but its session control is not recoverable from here (no multiplexer pane — e.g. a native subagent only its parent can drive)" : void 0;
+	if (!isLive(ctx, owner)) return {
+		...base,
+		owner,
+		health: "unhealthy",
+		control,
+		note: "the owner session is gone"
+	};
+	return {
+		...base,
+		owner,
+		health: "healthy",
+		control,
+		...controlNote ? { note: controlNote } : {}
+	};
+}
+function vacantLease(ctx, projectId, name) {
+	return {
+		project: projectId,
+		service: name,
+		endpoint: serviceEndpointId(projectId, name),
+		generation: 0,
+		state: "vacant",
+		updatedAt: iso(nowMs(ctx))
+	};
+}
+/** Load the project, service endpoint, and lease — creating the endpoint and a vacant lease when
+* `create` is set, else throwing for a service that was never started. */
+function load(ctx, projectRef, name, create) {
+	assertServiceName(name);
+	const project = resolveProject(ctx, projectRef);
+	const lease = ctx.store.getServiceLease(project.id, name);
+	const endpoint = loadAgent(ctx.store, serviceEndpointId(project.id, name));
+	if (lease && endpoint) return {
+		project,
+		endpoint,
+		lease
+	};
+	if (!create) throw new Error(`no service "${name}" in project ${project.name} (${project.id})`);
+	return {
+		project,
+		endpoint: ensureEndpoint(ctx, project, name),
+		lease: lease ?? vacantLease(ctx, project.id, name)
+	};
+}
+/** Run `fn` on the service's current state under its lock — every ownership transition goes here. */
+function transition(ctx, projectRef, name, create, fn) {
+	assertServiceName(name);
+	const project = resolveProject(ctx, projectRef);
+	return ctx.store.withLock(lockName(project.id, name), () => fn(load(ctx, project.id, name, create)));
+}
+function write(ctx, lease) {
+	const next = {
+		...lease,
+		updatedAt: iso(nowMs(ctx))
+	};
+	ctx.store.putServiceLease(next);
+	return next;
+}
+function stale(message) {
+	return new ServiceOwnershipError("stale", message);
+}
+/** Read a service's ownership without changing anything. Throws for a service never started. */
+function resolveService(ctx, projectRef, name) {
+	const { project, endpoint, lease } = load(ctx, projectRef, name, false);
+	return view(ctx, project, endpoint, lease);
+}
+/**
+* Contact-or-start: resolve the service's healthy owner, or reserve the right to start one. Exactly
+* one of any number of concurrent callers gets `reserved`; the rest see `starting` (a start is in
+* progress) or `resolved`. A vacant service, an unhealthy owner, and an expired reservation are all
+* reservable, each under a new generation that fences out whatever held the old one.
+*/
+function acquireService(ctx, projectRef, name, input = {}) {
+	return transition(ctx, projectRef, name, true, ({ project, endpoint, lease }) => {
+		const current = view(ctx, project, endpoint, lease);
+		if (input.force) {
+			if (input.force.generation !== lease.generation) throw stale(`cannot force: generation ${input.force.generation} is not the current ${lease.generation}`);
+		} else if (current.health === "healthy") return {
+			outcome: "resolved",
+			lease,
+			view: current
+		};
+		else if (current.health === "starting") return {
+			outcome: "starting",
+			lease,
+			view: current
+		};
+		const now = nowMs(ctx);
+		const token = randomBytes(8).toString("hex");
+		const next = write(ctx, {
+			project: project.id,
+			service: name,
+			endpoint: endpoint.id,
+			generation: lease.generation + 1,
+			state: "reserved",
+			reservation: {
+				token,
+				...input.by ? { by: input.by } : {},
+				at: iso(now),
+				expiresAt: iso(now + (input.ttlMs ?? 3e5)),
+				...input.force ? { forced: true } : {}
+			},
+			updatedAt: iso(now)
+		});
+		return {
+			outcome: "reserved",
+			lease: next,
+			view: view(ctx, project, endpoint, next),
+			token
+		};
+	});
+}
+function liveUnit(ctx, id) {
+	const unit = loadAgent(ctx.store, id);
+	if (!unit) throw new ServiceOwnershipError("unknown-unit", `no unit "${id}"`);
+	if (!isLive(ctx, unit)) throw new ServiceOwnershipError("unit-not-live", `unit "${id}" has no live session`);
+	return unit;
+}
+/**
+* Complete a reservation: make `unit` the owner at the reserved generation. Refused when the
+* reservation is no longer the current one (it expired and someone else re-reserved, or it was
+* released) — the starter then holds a runtime that is not the authority and must stop it. A
+* reservation that expired with nobody taking over is still bindable: nothing replaced it.
+*/
+function bindService(ctx, projectRef, name, input) {
+	return transition(ctx, projectRef, name, false, ({ project, endpoint, lease }) => {
+		if (lease.state !== "reserved" || lease.generation !== input.generation || lease.reservation?.token !== input.token) throw stale(`reservation for generation ${input.generation} is no longer current (now ${lease.state} at ${lease.generation})`);
+		liveUnit(ctx, input.unit);
+		return view(ctx, project, endpoint, write(ctx, {
+			project: lease.project,
+			service: lease.service,
+			endpoint: lease.endpoint,
+			generation: lease.generation,
+			state: "active",
+			holder: input.unit,
+			updatedAt: lease.updatedAt
+		}));
+	});
+}
+/**
+* Give the service up: abandon a reservation (a failed start — pass its `token`) or step down as
+* owner (pass the holder `unit`). Either must match the current generation. The generation is kept;
+* the next acquire bumps it.
+*/
+function releaseService(ctx, projectRef, name, input) {
+	return transition(ctx, projectRef, name, false, ({ project, endpoint, lease }) => {
+		if (!(lease.generation === input.generation && (lease.state === "reserved" && input.token !== void 0 && lease.reservation?.token === input.token || lease.state === "active" && input.unit !== void 0 && lease.holder === input.unit))) throw stale(`nothing to release at generation ${input.generation} (now ${lease.state} at ${lease.generation})`);
+		return view(ctx, project, endpoint, write(ctx, {
+			project: lease.project,
+			service: lease.service,
+			endpoint: lease.endpoint,
+			generation: lease.generation,
+			state: "vacant",
+			updatedAt: lease.updatedAt
+		}));
+	});
+}
+/**
+* Transfer ownership from the current holder to another live unit, under a new generation. Only the
+* holder at the current generation can hand off, and afterwards it is stale.
+*/
+function handoffService(ctx, projectRef, name, input) {
+	return transition(ctx, projectRef, name, false, ({ project, endpoint, lease }) => {
+		if (lease.state !== "active" || lease.generation !== input.generation || lease.holder !== input.from) throw stale(`"${input.from}" is not the owner at generation ${input.generation}`);
+		liveUnit(ctx, input.to);
+		return view(ctx, project, endpoint, write(ctx, {
+			...lease,
+			generation: lease.generation + 1,
+			holder: input.to
+		}));
+	});
+}
+/**
+* The fencing check: succeed only when `unit` owns the service at exactly `generation`. A runtime
+* calls this before acting as the service's authority; a stale runtime — replaced, handed off, or
+* recovered past — is refused.
+*/
+function verifyOwnership(ctx, projectRef, name, input) {
+	const { project, endpoint, lease } = load(ctx, projectRef, name, false);
+	if (lease.state !== "active" || lease.holder !== input.unit || lease.generation !== input.generation) throw stale(`"${input.unit}" at generation ${input.generation} is not the owner (now ${lease.state}${lease.holder ? ` by ${lease.holder}` : ""} at ${lease.generation})`);
+	return view(ctx, project, endpoint, lease);
+}
+/**
+* Run `fn` as the verified owner, holding the service lock so no transition can interleave between
+* the check and the act. For short critical sections only — the lock is bounded-wait for everyone
+* else — and never reentrant: `fn` must not call another service transition on the same service.
+*/
+function withOwnership(ctx, projectRef, name, input, fn) {
+	assertServiceName(name);
+	const project = resolveProject(ctx, projectRef);
+	return ctx.store.withLock(lockName(project.id, name), () => fn(verifyOwnership(ctx, project.id, name, input)));
+}
+/**
+* Resolve-or-start end to end: acquire, and only when this caller wins the reservation, launch a
+* runtime and bind it. A launch that throws releases the reservation (best-effort — an expiry covers
+* a release that itself fails) so the start is retryable at once. A launch that finishes after its
+* reservation was superseded is refused at bind: the launched unit is not the owner, and the error
+* names it so the caller can stop it.
+*/
+async function startService(ctx, projectRef, name, input) {
+	const acquired = acquireService(ctx, projectRef, name, input);
+	if (acquired.outcome !== "reserved") return {
+		outcome: acquired.outcome,
+		view: acquired.view
+	};
+	const { generation, endpoint } = acquired.lease;
+	let launched;
+	try {
+		launched = await input.launch({
+			generation,
+			endpoint
+		});
+	} catch (err) {
+		try {
+			releaseService(ctx, projectRef, name, {
+				generation,
+				token: acquired.token
+			});
+		} catch {}
+		throw err;
+	}
+	try {
+		return {
+			outcome: "started",
+			view: bindService(ctx, projectRef, name, {
+				generation,
+				token: acquired.token,
+				unit: launched.unit
+			}),
+			launched
+		};
+	} catch (err) {
+		if (err instanceof ServiceOwnershipError) throw new ServiceOwnershipError(err.code, `launched unit "${launched.unit}" could not become the owner — ${err.message}; stop it`);
+		throw err;
+	}
+}
+//#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
+		});
+	}
+	putProject(rec) {
+		writeJson(paths.projectFile(this.root, rec.id), rec);
+	}
+	getProject(id) {
+		const file = readPathOrUndefined(() => paths.projectFile(this.root, id));
+		if (!file || !existsSync(file)) return void 0;
+		return readJsonRecord(file);
+	}
+	listProjects() {
+		const dir = paths.projectsDir(this.root);
+		if (!existsSync(dir)) return [];
+		return readdirSync(dir).filter((f) => f.endsWith(".json")).map((f) => readJsonRecord(join(dir, f))).sort((a, b) => a.registeredAt.localeCompare(b.registeredAt));
+	}
+	putServiceLease(lease) {
+		writeJson(paths.serviceLeaseFile(this.root, lease.project, lease.service), lease);
+	}
+	getServiceLease(project, service) {
+		const file = readPathOrUndefined(() => paths.serviceLeaseFile(this.root, project, service));
+		if (!file || !existsSync(file)) return void 0;
+		return readJsonRecord(file);
+	}
+	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 { 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 };