cyberlegion 0.0.0

package/dist/watch-DA8I44dv.mjs

@@ -0,0 +1,1403 @@
+import { basename, dirname, join, resolve } from "node:path";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { homedir } from "node:os";
+//#region src/identity.ts
+const realExec = (cmd, args) => {
+	try {
+		return execFileSync(cmd, args, {
+			encoding: "utf8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).trim();
+	} catch {
+		return null;
+	}
+};
+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. In tmux 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 there is no `$TMUX_PANE`). 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 pane = env.TMUX_PANE;
+	if (pane) return ctx.store.resolvePaneId(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 pane = env.TMUX_PANE;
+	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),
+		tmux: pane ? {
+			pane,
+			window: exec("tmux", [
+				"display-message",
+				"-p",
+				"-t",
+				pane,
+				"#{window_id}"
+			]) ?? void 0,
+			session: env.TMUX?.split(",")[0]
+		} : null,
+		status: "active",
+		createdAt: existing?.createdAt ?? ts,
+		lastSeen: ts,
+		...existing?.brief ? { brief: existing.brief } : {},
+		...existing?.spawnedBy ? { spawnedBy: existing.spawnedBy } : {}
+	};
+	saveAgent(ctx.store, rec);
+	if (pane) ctx.store.putPaneIndex(pane, id);
+	return rec;
+}
+function gitWorktree(exec) {
+	const root = exec("git", ["rev-parse", "--show-toplevel"]);
+	if (!root) return null;
+	return {
+		root,
+		branch: exec("git", [
+			"rev-parse",
+			"--abbrev-ref",
+			"HEAD"
+		]) ?? void 0
+	};
+}
+/** Resolve a recipient argument (id or handle) to an agent id. */
+function resolveRecipient(store, to) {
+	if (loadAgent(store, to)) return to;
+	const match = listAgents(store).find((a) => a.handle === to);
+	if (!match) throw new Error(`no agent addressable as "${to}"`);
+	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 byHandle = agents.find((a) => a.handle === ref);
+	if (byHandle) return byHandle;
+	const byBranch = agents.find((a) => a.worktree?.branch === ref);
+	if (byBranch) return byBranch;
+	throw new Error(`no agent addressable as "${ref}" (tried 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 = 900 * 1e3;
+/** Mark agents whose pane is gone or whose last-seen is stale as exited. */
+function prune(ctx) {
+	const exec = ctx.exec ?? realExec;
+	const now = ctx.now?.() ?? Date.now();
+	const changed = [];
+	for (const rec of listAgents(ctx.store)) {
+		if (rec.status === "exited") continue;
+		const paneGone = rec.tmux?.pane ? exec("tmux", [
+			"has-session",
+			"-t",
+			rec.tmux.pane
+		]) === null && !(exec("tmux", [
+			"list-panes",
+			"-a",
+			"-F",
+			"#{pane_id}"
+		]) ?? "").split("\n").includes(rec.tmux.pane) : 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/mux-probe.ts
+const KNOWN_MUX = [
+	"tmux",
+	"herdr",
+	"screen",
+	"none"
+];
+function isKnownMux(v) {
+	return v != null && KNOWN_MUX.includes(v);
+}
+/**
+* Two-mode multiplexer detection.
+*
+* Fast-path: `$CYBERLEGION_MUX` (tmux | herdr | screen | none) is trusted outright — this also
+* serves as an OVERRIDE (`=none` forces no-mux even inside a real multiplexer). `$CYBERLEGION_MUX_PANE`
+* carries the pane id alongside it.
+*
+* Discovery (else): walk the process ancestry from `$$` via `ps -o ppid=,comm= -p <pid>`, since the
+* tool's own shell may not be the human's pane. `$TMUX`/`$HERDR_ENV` are NOT trusted alone — they
+* are used only as a fast-positive hint the ancestry walk falls back to when the walk itself is
+* inconclusive (e.g. `ps` unavailable), never as a substitute for it.
+*/
+function probeMultiplexer(exec, env, opts = {}) {
+	if (isKnownMux(env.CYBERLEGION_MUX)) return {
+		mux: env.CYBERLEGION_MUX,
+		...env.CYBERLEGION_MUX_PANE ? { pane: env.CYBERLEGION_MUX_PANE } : {},
+		via: "env"
+	};
+	if (opts.discover === false) return {
+		mux: "none",
+		via: "ancestry"
+	};
+	return discoverByAncestry(exec, env);
+}
+const MUX_COMM = [
+	{
+		re: /^tmux(:|$)/,
+		mux: "tmux",
+		pane: (env) => env.TMUX_PANE
+	},
+	{
+		re: /^herdr(:|$)/,
+		mux: "herdr",
+		pane: (env) => env.HERDR_PANE
+	},
+	{
+		re: /^screen(:|$)/,
+		mux: "screen",
+		pane: () => void 0
+	}
+];
+const MAX_ANCESTORS = 32;
+function walkAncestry(exec, env) {
+	let pid = process.pid;
+	const seen = /* @__PURE__ */ new Set();
+	for (let i = 0; i < MAX_ANCESTORS; i++) {
+		if (seen.has(pid)) break;
+		seen.add(pid);
+		const line = exec("ps", [
+			"-o",
+			"ppid=,comm=",
+			"-p",
+			String(pid)
+		]);
+		if (!line) break;
+		const trimmed = line.trim();
+		const spaceIdx = trimmed.indexOf(" ");
+		const ppidStr = spaceIdx === -1 ? trimmed : trimmed.slice(0, spaceIdx);
+		const comm = spaceIdx === -1 ? "" : trimmed.slice(spaceIdx + 1).trim();
+		const ppid = Number.parseInt(ppidStr, 10);
+		for (const entry of MUX_COMM) if (entry.re.test(comm)) return {
+			mux: entry.mux,
+			pane: entry.pane(env),
+			via: "ancestry"
+		};
+		if (!Number.isFinite(ppid) || ppid <= 1) break;
+		pid = ppid;
+	}
+}
+function discoverByAncestry(exec, env) {
+	const found = walkAncestry(exec, env);
+	if (found) return found;
+	if (env.TMUX) return {
+		mux: "tmux",
+		pane: env.TMUX_PANE,
+		via: "ancestry"
+	};
+	if (env.HERDR_ENV) return {
+		mux: "herdr",
+		pane: env.HERDR_PANE,
+		via: "ancestry"
+	};
+	return {
+		mux: "none",
+		via: "ancestry"
+	};
+}
+//#endregion
+//#region src/console/session.herdr.ts
+/**
+* herdr backend — detected via `$HERDR_ENV`. herdr (https://herdr.dev) is an agent-aware terminal
+* multiplexer that also reports real busy-state (working / idle / blocked / done); this adapter
+* only drives its pane lifecycle, not the state feed. Talks to herdr's own CLI (`herdr pane ...`)
+* rather than its Unix-socket API, so it composes with this codebase's synchronous `Exec`
+* convention exactly like the tmux adapter — no new client/transport needed.
+*
+* herdr is optional/experimental and is not installed in this environment; this follows herdr's
+* documented CLI reference (split/run/read/close/focus) but is unverified against a live binary.
+*/
+const herdrSessionAdapter = {
+	name: "herdr",
+	open(exec, opts) {
+		const id = exec("herdr", [
+			"pane",
+			"split",
+			"--current",
+			"--direction",
+			opts.at === "pane:down" ? "down" : "right",
+			"--cwd",
+			opts.cwd
+		]);
+		if (!id) throw new Error("herdr pane split failed");
+		const target = { id };
+		exec("herdr", [
+			"pane",
+			"run",
+			id,
+			opts.launch
+		]);
+		return target;
+	},
+	send(exec, target, text) {
+		exec("herdr", [
+			"pane",
+			"run",
+			target.id,
+			text
+		]);
+	},
+	read(exec, target, opts) {
+		const args = [
+			"pane",
+			"read",
+			target.id,
+			"--source",
+			"visible"
+		];
+		if (opts?.lines != null) args.push("--lines", String(opts.lines));
+		return exec("herdr", args) ?? "";
+	},
+	focus(exec, target) {
+		exec("herdr", [
+			"pane",
+			"focus",
+			target.id
+		]);
+	},
+	teardown(exec, target) {
+		exec("herdr", [
+			"pane",
+			"close",
+			target.id
+		]);
+	}
+};
+//#endregion
+//#region src/console/session.tmux.ts
+/** tmux backend — detected via `$TMUX`. */
+const tmuxSessionAdapter = {
+	name: "tmux",
+	open(exec, opts) {
+		const pane = exec("tmux", opts.at === "pane:down" ? [
+			"split-window",
+			"-v",
+			"-c",
+			opts.cwd,
+			"-P",
+			"-F",
+			"#{pane_id}"
+		] : opts.at === "tab" || opts.at === "window" ? [
+			"new-window",
+			"-c",
+			opts.cwd,
+			"-P",
+			"-F",
+			"#{pane_id}"
+		] : [
+			"split-window",
+			"-h",
+			"-c",
+			opts.cwd,
+			"-P",
+			"-F",
+			"#{pane_id}"
+		]);
+		if (!pane) throw new Error("tmux split-window failed");
+		const target = { id: pane };
+		tmuxSessionAdapter.send(exec, target, opts.launch);
+		return target;
+	},
+	send(exec, target, text) {
+		exec("tmux", [
+			"send-keys",
+			"-t",
+			target.id,
+			text,
+			"Enter"
+		]);
+	},
+	read(exec, target, opts) {
+		const args = [
+			"capture-pane",
+			"-p",
+			"-t",
+			target.id
+		];
+		if (opts?.lines != null) args.push("-S", `-${opts.lines}`);
+		return exec("tmux", args) ?? "";
+	},
+	focus(exec, target) {
+		exec("tmux", [
+			"select-pane",
+			"-t",
+			target.id
+		]);
+	},
+	teardown(exec, target) {
+		exec("tmux", [
+			"kill-pane",
+			"-t",
+			target.id
+		]);
+	}
+};
+//#endregion
+//#region src/console/index.ts
+/**
+* Backend selection via the two-mode mux probe (`$CYBERLEGION_MUX` fast-path/override, else
+* ancestry discovery from `$$` falling back to the `$TMUX`/`$HERDR_ENV` hint when the walk is
+* inconclusive) — tmux/herdr map to their existing adapters; anything else is a clear error.
+*/
+function selectSessionAdapter(env, exec = realExec) {
+	const probe = probeMultiplexer(exec, env);
+	if (probe.mux === "tmux") return tmuxSessionAdapter;
+	if (probe.mux === "herdr") return herdrSessionAdapter;
+	throw new Error("spawn requires a session backend — run inside tmux ($TMUX) or herdr ($HERDR_ENV=1)");
+}
+//#endregion
+//#region src/console/worktree.ts
+/** The only worktree backend at MVP — plain `git worktree`. */
+const gitWorktreeAdapter = {
+	add(exec, opts) {
+		if (exec("git", [
+			"-C",
+			opts.primaryRoot,
+			"worktree",
+			"add",
+			"-b",
+			opts.branch,
+			opts.path
+		]) === null) throw new Error(`git worktree add failed for ${opts.path}`);
+		return {
+			root: resolve(opts.path),
+			branch: opts.branch
+		};
+	},
+	remove(exec, path, opts) {
+		if (exec("git", [
+			"-C",
+			opts.primaryRoot,
+			"worktree",
+			"remove",
+			path,
+			"--force"
+		]) === null) throw new Error(`git worktree remove failed for ${path}`);
+	}
+};
+/**
+* Resolve the primary checkout's root regardless of whether the caller's cwd is the primary
+* checkout or a linked worktree — `--git-common-dir` always points at the main repo's `.git`.
+*/
+function resolvePrimaryRoot(exec) {
+	const commonDir = exec("git", [
+		"rev-parse",
+		"--path-format=absolute",
+		"--git-common-dir"
+	]);
+	if (!commonDir) throw new Error("cannot resolve the primary checkout — not inside a git repository");
+	return dirname(commonDir);
+}
+/**
+* Refuse the primary checkout: a spawned unit's resolved worktree root must never be the primary
+* checkout itself. A unit is never run in the primary checkout.
+*/
+function assertDistinctFromPrimary(worktreeRoot, primaryRoot) {
+	if (resolve(worktreeRoot) === resolve(primaryRoot)) throw new Error("refusing to run a unit in the primary checkout — spawn a worktree distinct from the primary checkout");
+}
+//#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 — where spawned unit worktrees
+* live (never the global hub), keyed off `git worktree`'s common-dir so it resolves the same from
+* the primary checkout or from any of its linked worktrees.
+*/
+function resolveProjectLocalRoot(opts = {}) {
+	const exec = opts.exec ?? makeDefaultExec(opts.cwd);
+	let primary;
+	try {
+		primary = resolvePrimaryRoot(exec);
+	} catch {
+		primary = void 0;
+	}
+	return join(primary ?? projectRoot(opts.cwd), ".agents", "cyberlegion");
+}
+/**
+* Create the tracked `config.json` marker at `root` (a hub root) if it does not already exist.
+* Callers pass the root under which the marker should be created/ensured; this mkdir's it as
+* needed. Idempotent — never overwrites an existing marker.
+*/
+function ensureMarker(root) {
+	mkdirSync(root, { recursive: true });
+	const marker = join(root, MARKER_FILE);
+	if (!existsSync(marker)) writeFileSync(marker, `${JSON.stringify({ version: 1 }, null, 2)}\n`);
+}
+const paths = {
+	agentsDir: (root) => join(root, "agents"),
+	agentFile: (root, id) => join(root, "agents", `${id}.json`),
+	panesDir: (root) => join(root, "panes"),
+	paneFile: (root, pane) => join(root, "panes", `${sanitizePane(pane)}.id`),
+	inboxDir: (root, id) => join(root, "inbox", id),
+	inboxReadDir: (root, id) => join(root, "inbox", id, "read"),
+	dataDir: (root, id) => join(root, "data", id),
+	briefFile: (root, id) => join(root, "data", id, "brief.md"),
+	resultFile: (root, id) => join(root, "data", id, "result.json"),
+	worktreeDir: (root, id) => join(root, "worktrees", 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/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 the peer's own
+* SessionStart hook reads — never typed into its prompt.
+*
+* Spawned unit worktrees live project-local (`<primary>/.agents/cyberlegion/worktrees/<id>`), 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 project-local.
+*/
+function spawn(ctx, input) {
+	ctx.store.ensureMarker();
+	const env = ctx.env ?? process.env;
+	const exec = ctx.exec ?? realExec;
+	const sessionAdapter = selectSessionAdapter(env, exec);
+	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>");
+	const id = randomId();
+	const primaryRoot = resolvePrimaryRoot(exec);
+	const branch = input.branch ?? `cyberlegion/unit-${id}`;
+	const worktreePath = input.worktreePath ?? paths.worktreeDir(join(primaryRoot, ".agents", "cyberlegion"), id);
+	const worktree = gitWorktreeAdapter.add(exec, {
+		primaryRoot,
+		path: worktreePath,
+		branch
+	});
+	assertDistinctFromPrimary(worktree.root, primaryRoot);
+	ensureMarker(join(worktree.root, ".agents", "cyberlegion"));
+	const launch = input.command ?? LAUNCH_MAP[harness];
+	const target = sessionAdapter.open(exec, {
+		cwd: worktree.root,
+		launch: `${muxEnvPrefix(sessionAdapter.name)}${launch}`,
+		at: input.at
+	});
+	const ts = new Date(ctx.now?.() ?? Date.now()).toISOString();
+	const rec = {
+		id,
+		handle: input.handle ?? id.slice(0, 6),
+		harness,
+		cwd: worktree.root,
+		worktree,
+		tmux: sessionAdapter.name === "tmux" ? { pane: target.id } : null,
+		status: "spawning",
+		createdAt: ts,
+		lastSeen: ts,
+		brief: paths.briefFile(ctx.store.root, id),
+		...resolveSelfId(ctx) ? { spawnedBy: resolveSelfId(ctx) } : {}
+	};
+	saveAgent(ctx.store, rec);
+	ctx.store.putPaneIndex(target.id, id);
+	ctx.store.writeBrief(id, brief);
+	return {
+		agent: rec,
+		pane: target.id,
+		launch
+	};
+}
+/**
+* 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 (`$CYBERLEGION_MUX` /
+* `$CYBERLEGION_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 "CYBERLEGION_MUX=tmux CYBERLEGION_MUX_PANE=$TMUX_PANE ";
+	if (muxName === "herdr") return "CYBERLEGION_MUX=herdr ";
+	return "";
+}
+/** Resolve a spawn brief from --brief-file, --task -, or --task <text>; null if no source given. */
+function resolveBrief(input, readStdin = () => readFileSync(0, "utf8")) {
+	if (input.briefFile) return readFileSync(input.briefFile, "utf8");
+	if (input.task === "-") return readStdin();
+	if (input.task != null && input.task !== "") return input.task;
+	return null;
+}
+//#endregion
+//#region src/agentdef/realize.ts
+const DEFAULT_HARNESS = "claude";
+/** POSIX single-quote a value for safe inclusion in a shell command line. */
+function shellQuote(value) {
+	return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/** Build the harness launch invocation for a def — explicit `model`/`harness` win over the def's
+* own tags, which win over the harness default. Every harness gets the same shape (bin,
+* `--model` when known, `--append-system-prompt` carrying the def's instructions body) since the
+* exact per-harness flag surface is realized later by the launching caller, not by cyberlegion. */
+function realizeLaunch(def, opts = {}) {
+	const harness = opts.harness ?? def.harness ?? DEFAULT_HARNESS;
+	const model = opts.model ?? def.model;
+	const parts = [LAUNCH_MAP[harness]];
+	if (model) parts.push("--model", shellQuote(model));
+	if (def.instructions) parts.push("--append-system-prompt", shellQuote(def.instructions));
+	return {
+		harness,
+		command: parts.join(" ")
+	};
+}
+/** Build the instruction string a parent model uses to spawn its OWN harness Task subagent for
+* `def` — cyberlegion never invokes the Task tool itself. Names `subagent_type: <def.name>` for a
+* harness that recognizes it, but always inlines the model + full instructions too so the same
+* instruction string is correct even when the harness has no such named subagent type. */
+function realizeSubagentInstruction(def, opts) {
+	const lines = [`Spawn a subagent (subagent_type: ${def.name} if your harness recognizes that name, else a generic one).`];
+	if (def.model) lines.push(`Model: ${def.model}.`);
+	if (def.effort) lines.push(`Effort: ${def.effort}.`);
+	lines.push(`Read the brief at ${opts.briefFile} and write its result JSON to ${opts.resultFile}.`);
+	if (def.instructions) lines.push("", "Instructions:", def.instructions);
+	return lines.join("\n");
+}
+//#endregion
+//#region src/agentdef/resolve.ts
+function parseAgentDefFile(text) {
+	const m = /^---\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n)?([\s\S]*)$/.exec(text);
+	if (!m) return {
+		fm: {},
+		instructions: text.trim()
+	};
+	const [, block, rest] = m;
+	const fm = {};
+	const lines = block.split("\n");
+	let i = 0;
+	while (i < lines.length) {
+		const line = lines[i].replace(/\r$/, "");
+		if (line.trim() === "" || line.trim().startsWith("#")) {
+			i++;
+			continue;
+		}
+		if (line.length - line.trimStart().length > 0) {
+			i++;
+			continue;
+		}
+		const idx = line.indexOf(":");
+		if (idx === -1) {
+			i++;
+			continue;
+		}
+		const key = line.slice(0, idx).trim();
+		let value = line.slice(idx + 1).trim();
+		i++;
+		if (value === ">" || value === ">-" || value === "|" || value === "|-") {
+			const parts = [];
+			while (i < lines.length) {
+				const l = lines[i].replace(/\r$/, "");
+				if (l.trim() === "") {
+					i++;
+					continue;
+				}
+				if (l.length - l.trimStart().length === 0) break;
+				parts.push(l.trim());
+				i++;
+			}
+			value = parts.join(value.startsWith("|") ? "\n" : " ");
+		}
+		fm[key] = unquote(value);
+	}
+	return {
+		fm,
+		instructions: rest.trim()
+	};
+}
+function unquote(v) {
+	if (v.length >= 2 && (v.startsWith("\"") && v.endsWith("\"") || v.startsWith("'") && v.endsWith("'"))) return v.slice(1, -1);
+	return v;
+}
+function toBool(v) {
+	if (v === void 0) return void 0;
+	if (v === "true") return true;
+	if (v === "false") return false;
+}
+function toAgentDef(path, text, fallbackName) {
+	const { fm, instructions } = parseAgentDefFile(text);
+	return {
+		name: fm.name ?? fallbackName,
+		description: fm.description,
+		model: fm.model,
+		effort: fm.effort,
+		harness: fm.harness,
+		warm: toBool(fm.warm),
+		interactive: toBool(fm.interactive),
+		instructions,
+		path
+	};
+}
+/** The project's own `.agents/agents/` dir — the convention `agent list`/name-search scans. */
+function projectAgentsDir(cwd) {
+	return join(projectRoot(cwd), ".agents", "agents");
+}
+/** Resolve one agent definition, by explicit file or by name search. Throws a clear error when
+* neither locates a def — never returns a partial/empty result. */
+function resolveAgentDef(input) {
+	if (input.file) {
+		const path = resolve(input.file);
+		if (!existsSync(path)) throw new Error(`agent def file "${input.file}" does not exist`);
+		return toAgentDef(path, readFileSync(path, "utf8"), basename(path).replace(/\.md$/, ""));
+	}
+	if (!input.name) throw new Error("resolveAgentDef needs a --agent <name> or --agent-file <path>");
+	const roots = [...input.searchRoots ?? [], projectAgentsDir(input.cwd)];
+	for (const root of roots) {
+		const candidate = join(root, `${input.name}.md`);
+		if (existsSync(candidate)) return toAgentDef(candidate, readFileSync(candidate, "utf8"), input.name);
+	}
+	throw new Error(`no agent definition named "${input.name}" found under .agents/agents/`);
+}
+/** List every resolvable agent def under `.agents/agents/` (+ any extra search roots). Definitive
+* empty array when the dir is absent or empty — never throws for "none found" here (unlike a
+* named resolve, listing is inherently zero-or-more). */
+function listAgentDefs(input = {}) {
+	const roots = [...input.searchRoots ?? [], projectAgentsDir(input.cwd)];
+	const seen = /* @__PURE__ */ new Set();
+	const defs = [];
+	for (const root of roots) {
+		if (!existsSync(root)) continue;
+		for (const file of readdirSync(root)) {
+			if (!file.endsWith(".md")) continue;
+			const path = join(root, file);
+			if (seen.has(path)) continue;
+			seen.add(path);
+			defs.push(toAgentDef(path, readFileSync(path, "utf8"), file.replace(/\.md$/, "")));
+		}
+	}
+	return defs;
+}
+//#endregion
+//#region src/decommission.ts
+/**
+* Tear a unit down and reap its registry record — the deterministic inverse of `spawn`. Refuses
+* the primary checkout (absolute — `--force` never overrides it) and a dirty worktree unless
+* `--force`. Teardown always precedes reap: an already-gone worktree or pane is tolerated, but a
+* genuine worktree-removal failure aborts and leaves the record intact so the operation is
+* retryable.
+*/
+function decommission(ctx, input) {
+	const rec = loadAgent(ctx.store, input.id);
+	if (!rec) throw new Error(`no unit registered as agents/${input.id}.json — nothing to decommission`);
+	const exec = ctx.exec ?? realExec;
+	const env = ctx.env ?? process.env;
+	const worktreeRoot = rec.worktree?.root;
+	const primaryRoot = worktreeRoot ? resolvePrimaryRoot(exec) : void 0;
+	if (worktreeRoot && resolve(worktreeRoot) === resolve(primaryRoot)) throw new Error(`refusing to decommission "${input.id}" — its worktree is the primary checkout; --force does not override this`);
+	const worktreeExists = worktreeRoot != null && existsSync(worktreeRoot);
+	if (worktreeExists && !input.force && isDirty(exec, worktreeRoot)) throw new Error(`unit "${input.id}" has uncommitted changes in its worktree — pass --force to discard them`);
+	const pane = rec.tmux?.pane ?? ctx.store.findPaneByAgentId(input.id);
+	if (worktreeExists) try {
+		gitWorktreeAdapter.remove(exec, worktreeRoot, { primaryRoot });
+	} catch (err) {
+		throw new Error(`decommission "${input.id}" aborted — worktree removal failed, record left intact for retry: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	if (pane) try {
+		selectSessionAdapter(env, exec).teardown(exec, { id: pane });
+	} catch {}
+	ctx.store.removeAgent(input.id);
+	if (pane) ctx.store.removePaneIndex(pane);
+	ctx.store.removeAgentData(input.id);
+	return {
+		agent: rec,
+		worktreeRoot,
+		pane
+	};
+}
+function isDirty(exec, worktreeRoot) {
+	return !!exec("git", [
+		"-C",
+		worktreeRoot,
+		"status",
+		"--porcelain"
+	]);
+}
+//#endregion
+//#region src/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/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/dispatch/prep.ts
+/** The instruction a caller uses when no agent def is given — still names both slot paths so a
+* generic Task-tool spawn (or a human) can carry out the same contract. */
+function genericInstruction(role, briefFile, resultFile) {
+	const lines = [`Spawn a subagent${role ? ` (role: ${role})` : ""}.`];
+	lines.push(`Read the brief at ${briefFile} and write its result JSON to ${resultFile}.`);
+	return lines.join("\n");
+}
+/**
+* Allocate a dispatch: mint an id (thread defaults to it), write the brief into the Store, compute
+* the result-slot path, and build the instruction from a resolved agent def (or a generic one).
+* Spawns nothing — the envelope is handed to whatever spawns next (a Task tool, `channel()`, a
+* human).
+*/
+function prep(ctx, input, readStdin) {
+	const id = randomId();
+	const thread = input.thread ?? id;
+	const briefText = resolveBody(input.briefText, input.briefFile, readStdin);
+	ctx.store.writeBrief(id, briefText);
+	const briefFile = paths.briefFile(ctx.store.root, id);
+	const resultFile = ctx.store.resultPath(id);
+	let def;
+	if (input.agent || input.agentFile) def = resolveAgentDef({
+		name: input.agent,
+		file: input.agentFile
+	});
+	return {
+		id,
+		thread,
+		briefFile,
+		resultFile,
+		instruction: def ? realizeSubagentInstruction(def, {
+			briefFile,
+			resultFile
+		}) : genericInstruction(input.role, briefFile, resultFile)
+	};
+}
+//#endregion
+//#region src/dispatch/verdict.ts
+function primitiveTypeOf(v) {
+	if (Array.isArray(v)) return "array";
+	return typeof v;
+}
+/**
+* Parse `body` as JSON and, when `schemaFile` is given, structurally check it against a minimal
+* required/type schema. Any failure — invalid JSON, an unreadable/invalid schema file, a missing
+* required key, or a type mismatch — is `{ ok: false }`, never a pass.
+*/
+function validateVerdict(body, schemaFile) {
+	let value;
+	try {
+		value = JSON.parse(body);
+	} catch (err) {
+		return {
+			ok: false,
+			error: `verdict body is not valid JSON: ${err instanceof Error ? err.message : String(err)}`
+		};
+	}
+	if (!schemaFile) return {
+		ok: true,
+		value
+	};
+	let schema;
+	try {
+		schema = JSON.parse(readFileSync(schemaFile, "utf8"));
+	} catch (err) {
+		return {
+			ok: false,
+			error: `verdict schema "${schemaFile}" is not readable/valid JSON: ${err instanceof Error ? err.message : String(err)}`
+		};
+	}
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return {
+		ok: false,
+		error: "verdict body must be a JSON object to validate against a schema"
+	};
+	const obj = value;
+	for (const key of schema.required ?? []) if (!(key in obj)) return {
+		ok: false,
+		error: `verdict is missing required key "${key}"`
+	};
+	for (const [key, expected] of Object.entries(schema.properties ?? {})) {
+		if (!(key in obj)) continue;
+		const actual = primitiveTypeOf(obj[key]);
+		if (actual !== expected) return {
+			ok: false,
+			error: `verdict key "${key}" expected type "${expected}" but got "${actual}"`
+		};
+	}
+	return {
+		ok: true,
+		value
+	};
+}
+//#endregion
+//#region src/dispatch/channel.ts
+/** Thrown by a `--wait` channel call when its internal poll-cycle cap is hit with no reply yet — a
+* clean, re-armable sentinel (mirrors `mail await`'s "waiting" outcome), never a failure. */
+var DispatchWaitingError = class extends Error {
+	thread;
+	constructor(thread) {
+		super(`waiting — no reply on thread "${thread}" yet; re-run to keep waiting`);
+		this.thread = thread;
+	}
+};
+/**
+* `prep()` + spawn a peer session realized from the same agent def + (optionally) `awaitReply` on
+* the thread. Requires `--agent`/`--agent-file` (a channel peer needs a real launch to realize).
+*/
+async function channel(ctx, input, readStdin) {
+	if (!input.agent && !input.agentFile) throw new Error("dispatch channel needs --agent <name> or --agent-file <path> to realize the peer launch");
+	const envelope = prep(ctx, input, readStdin);
+	const realized = realizeLaunch(resolveAgentDef({
+		name: input.agent,
+		file: input.agentFile
+	}));
+	spawn(ctx, {
+		harness: realized.harness,
+		command: realized.command,
+		briefFile: envelope.briefFile,
+		at: input.at
+	});
+	if (!input.wait) return envelope;
+	const meId = resolveSelfId(ctx);
+	if (!meId) throw new Error("dispatch channel --wait needs an identity — run `cyberlegion identity register` first");
+	const outcome = await awaitReply({
+		store: ctx.store,
+		now: ctx.now
+	}, {
+		meId,
+		thread: envelope.thread,
+		timeoutMs: input.timeoutMs,
+		maxWaitS: input.maxWaitS
+	});
+	if (outcome.kind === "waiting") throw new DispatchWaitingError(envelope.thread);
+	if (outcome.kind === "timed-out") throw new Error(`no reply on thread "${envelope.thread}" within timeout`);
+	const validated = validateVerdict(outcome.message.body, input.verdictSchema);
+	if (!validated.ok) throw new Error(validated.error);
+	return {
+		id: envelope.id,
+		verdict: validated.value,
+		body: outcome.message.body,
+		ts: outcome.message.ts
+	};
+}
+//#endregion
+//#region src/dispatch/collect.ts
+/** Read + validate a dispatch's result file. Throws (fail-loud) when the file is not yet written,
+* or when it fails the optional verdict schema. */
+function collect(ctx, id, verdictSchema) {
+	const body = ctx.store.readResult(id);
+	if (body === void 0) throw new Error(`no result written yet for dispatch "${id}" — the subagent has not written its result file`);
+	const validated = validateVerdict(body, verdictSchema);
+	if (!validated.ok) throw new Error(validated.error);
+	return {
+		id,
+		verdict: validated.value,
+		body,
+		ts: ctx.now?.() ?? Date.now()
+	};
+}
+//#endregion
+//#region src/install.ts
+const hookCommand = (event) => `cyberlegion mail hook --event ${event}`;
+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()) {
+	const spec = VENDORS[harness];
+	if (!spec) throw new Error(`unknown harness "${harness}" (expected claude | cursor | codex)`);
+	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);
+		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] ??= [];
+	if (groups.some((g) => g.hooks?.some((h) => 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] ??= [];
+	if (list.some((h) => h.command === command)) return "already present";
+	list.push({ command });
+	return "registered";
+}
+//#endregion
+//#region src/output.ts
+function stringifyCell(v) {
+	if (v == null) return "";
+	const s = String(v);
+	return /[,\n"]/.test(s) ? `"${s.replace(/"/g, "\"\"")}"` : s;
+}
+/** One TOON-encoded object: `key: value` lines, blank/undefined fields dropped. */
+function toonObject(fields) {
+	return Object.entries(fields).filter(([, v]) => v != null).map(([k, v]) => `${k}: ${v}`).join("\n");
+}
+/** One TOON-encoded list: a `name[N]{field,...}:` header plus one row per item, then an aggregate
+* summary line. Definitive on empty — still emits `name[0]{...}:` plus the summary line. */
+function toonList(name, items, fields, summary) {
+	return [
+		`${name}[${items.length}]{${fields.map((f) => f.key).join(",")}}:`,
+		...items.map((item) => fields.map((f) => stringifyCell(f.get(item))).join(",")).map((r) => `  ${r}`),
+		summary
+	].join("\n");
+}
+/** Print a command's result to stdout in the requested format. */
+function emit(format, payload) {
+	if (format === "json") console.log(JSON.stringify(payload.json, null, 2));
+	else console.log(payload.toon);
+}
+/** A stderr-only next-step suggestion — never part of the machine-readable stdout result. */
+function nextStep(msg) {
+	console.error(`→ ${msg}`);
+}
+/** A structured, fail-loud error: stderr + exit 1. Never prompts, never partially writes. */
+function fail(msg) {
+	console.error(JSON.stringify({ error: msg }));
+	process.exit(1);
+}
+//#endregion
+//#region src/runtime/inject-inbox.ts
+const EVENTS = ["SessionStart", "PostToolUse"];
+/**
+* Resolve the calling agent, gather its pending brief + unread mail, 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).
+*/
+function injectInbox(ctx, event) {
+	if (!EVENTS.includes(event)) throw new Error(`unsupported --event "${event}" (expected ${EVENTS.join(" | ")})`);
+	const meId = resolveSelfId(ctx);
+	if (!meId) return null;
+	const parts = [];
+	const rec = loadAgent(ctx.store, meId);
+	if (rec?.status === "spawning") {
+		const brief = ctx.store.readBrief(meId);
+		if (brief) parts.push(`## Your brief\n\n${brief.trim()}`);
+		rec.status = "active";
+		saveAgent(ctx.store, rec);
+	}
+	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")}`);
+	}
+	if (parts.length === 0) return null;
+	return { hookSpecificOutput: {
+		hookEventName: event,
+		additionalContext: parts.join("\n\n")
+	} };
+}
+//#endregion
+//#region src/store/file-store.ts
+function readMessages(dir) {
+	if (!existsSync(dir)) return [];
+	return readdirSync(dir).filter((f) => f.endsWith(".json")).map((f) => JSON.parse(readFileSync(join(dir, f), "utf8")));
+}
+function writeJson(file, data) {
+	mkdirSync(dirname(file), { recursive: true });
+	writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`);
+}
+function writeText(file, text) {
+	mkdirSync(dirname(file), { recursive: true });
+	writeFileSync(file, text);
+}
+/** 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) {
+		const dir = paths.inboxDir(this.root, toId);
+		mkdirSync(dir, { recursive: true });
+		writeFileSync(join(dir, `${msg.id}.json`), `${JSON.stringify(msg, null, 2)}\n`);
+	}
+	listInbox(id) {
+		return {
+			unread: readMessages(paths.inboxDir(this.root, id)),
+			read: readMessages(paths.inboxReadDir(this.root, id))
+		};
+	}
+	ackMessage(id, msgId) {
+		const src = join(paths.inboxDir(this.root, id), `${msgId}.json`);
+		if (!existsSync(src)) throw new Error(`"${msgId}" is not an unread message in this inbox`);
+		const msg = JSON.parse(readFileSync(src, "utf8"));
+		const dir = paths.inboxReadDir(this.root, id);
+		mkdirSync(dir, { recursive: true });
+		renameSync(src, join(dir, `${msgId}.json`));
+		return msg;
+	}
+	removeMessage(id, msgId) {
+		const unreadFile = join(paths.inboxDir(this.root, id), `${msgId}.json`);
+		if (existsSync(unreadFile)) {
+			rmSync(unreadFile);
+			return;
+		}
+		const readFile = join(paths.inboxReadDir(this.root, id), `${msgId}.json`);
+		if (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 = paths.agentFile(this.root, id);
+		if (!existsSync(file)) return void 0;
+		return JSON.parse(readFileSync(file, "utf8"));
+	}
+	listAgents() {
+		const dir = paths.agentsDir(this.root);
+		if (!existsSync(dir)) return [];
+		return readdirSync(dir).filter((f) => f.endsWith(".json")).map((f) => JSON.parse(readFileSync(join(dir, f), "utf8"))).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+	}
+	removeAgent(id) {
+		rmSync(paths.agentFile(this.root, id), { force: true });
+	}
+	removeAgentData(id) {
+		rmSync(paths.dataDir(this.root, id), {
+			recursive: true,
+			force: true
+		});
+	}
+	putPaneIndex(pane, agentId) {
+		writeText(paths.paneFile(this.root, pane), agentId);
+	}
+	resolvePaneId(pane) {
+		const file = paths.paneFile(this.root, pane);
+		return existsSync(file) ? readFileSync(file, "utf8").trim() : void 0;
+	}
+	findPaneByAgentId(agentId) {
+		const dir = paths.panesDir(this.root);
+		if (!existsSync(dir)) return void 0;
+		for (const f of readdirSync(dir)) {
+			if (!f.endsWith(".id")) continue;
+			if (readFileSync(join(dir, f), "utf8").trim() === agentId) return f.slice(0, -3);
+		}
+	}
+	removePaneIndex(pane) {
+		rmSync(paths.paneFile(this.root, pane), { force: true });
+	}
+	writeBrief(agentId, text) {
+		writeText(paths.briefFile(this.root, agentId), text);
+	}
+	readBrief(agentId) {
+		const file = paths.briefFile(this.root, agentId);
+		return existsSync(file) ? readFileSync(file, "utf8") : void 0;
+	}
+	resultPath(id) {
+		return paths.resultFile(this.root, id);
+	}
+	writeResult(id, value) {
+		writeJson(paths.resultFile(this.root, id), value);
+	}
+	readResult(id) {
+		const file = paths.resultFile(this.root, id);
+		return existsSync(file) ? readFileSync(file, "utf8") : void 0;
+	}
+};
+//#endregion
+//#region src/wake/watch.ts
+const POLL_MS = 1e3;
+/**
+* A continuous foreground observer: prints each NEW matching message as it arrives, polling on a
+* fixed ~1s interval, until interrupted (or `maxIterations` in tests). Never acks — a message
+* `watch` prints stays unread and still surfaces later in `mail inbox`/`mail await`.
+*/
+async function watchMail(ctx, input, onMessage, opts = {}) {
+	const sleep = opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+	const seen = /* @__PURE__ */ new Set();
+	for (const m of inbox(ctx, {
+		meId: input.meId,
+		thread: input.thread,
+		from: input.from
+	})) seen.add(m.id);
+	let iterations = 0;
+	for (;;) {
+		const items = inbox(ctx, {
+			meId: input.meId,
+			thread: input.thread,
+			from: input.from
+		});
+		for (const m of items) {
+			if (seen.has(m.id)) continue;
+			seen.add(m.id);
+			onMessage(m);
+		}
+		iterations++;
+		if (opts.maxIterations != null && iterations >= opts.maxIterations) return;
+		await sleep(POLL_MS);
+	}
+}
+//#endregion
+export { resolveProjectLocalRoot as A, loadAgent as B, resolveAgentDef as C, ensureMarker as D, spawn as E, selectSessionAdapter as F, resolveRecipient as G, realExec as H, probeMultiplexer as I, resolveSelfId as K, bumpLastSeen as L, assertDistinctFromPrimary as M, gitWorktreeAdapter as N, paths as O, resolvePrimaryRoot as P, detectHarness as R, listAgentDefs as S, realizeSubagentInstruction as T, register as U, prune as V, resolveAgent as W, inbox as _, fail as a, send as b, toonObject as c, DispatchWaitingError as d, channel as f, deleteMessage as g, ack as h, emit as i, resolveRoot as j, projectRoot as k, install as l, awaitReply as m, FileStore as n, nextStep as o, prep as p, touch as q, injectInbox as r, toonList as s, watchMail as t, collect as u, peek as v, realizeLaunch as w, decommission as x, resolveBody as y, listAgents as z };