cyberlegion 1.0.0 → 1.2.0

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { callerPane, currentPane, herdrMuxAdapter, nodeExec, nudge, probeMultiplexer, probeMultiplexer as probeMultiplexer$1, tmuxMuxAdapter } from "cyber-mux";
+import { callerPane, currentPane, herdrMuxAdapter, isStaged, nodeExec, 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";
@@ -38,6 +38,8 @@ function normalizeMuxEnv(env) {
 //#region src/paths.ts
 /** The tracked marker file that makes a hub root initialized (see ensureMarker). */
 const MARKER_FILE = "config.json";
+/** Where `spawn` stamps that marker inside a worktree it creates, relative to the worktree root. */
+const WORKTREE_MARKER = `.agents/cyberlegion/${MARKER_FILE}`;
 /** Walk up from `cwd` to the nearest git repo root; fall back to `cwd`. */
 function projectRoot(cwd = process.cwd()) {
 	let dir = resolve(cwd);
@@ -460,6 +462,7 @@ function reconcile(ctx, opts) {
 	const cur = storablePane(ctx.env ?? process.env);
 	if (!cur) return [];
 	const panes = PANE_ADAPTERS[cur.mux].listPanes(exec);
+	if (panes.length === 0) return [];
 	const live = new Set(panes.map((p) => p.id));
 	const changed = [];
 	for (const rec of listAgents(ctx.store)) {
@@ -475,18 +478,34 @@ function reconcile(ctx, opts) {
 	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). */
+/**
+* Whether a record's pane is positively gone: its existence probe fails AND its mux answers with a
+* pane list that does not hold it. `paneExists` alone collapses "unreachable" into "gone", so a mux
+* that answers no list at all (server down, a failed query) leaves the pane undecided — never gone.
+* The list is read at most once per mux per call.
+*/
+function paneGone(exec, pane, lists) {
+	const adapter = PANE_ADAPTERS[pane.mux];
+	if (adapter.paneExists(exec, { id: pane.id })) return false;
+	let panes = lists.get(pane.mux);
+	if (!panes) {
+		panes = adapter.listPanes(exec);
+		lists.set(pane.mux, panes);
+	}
+	return panes.length > 0 && !panes.some((p) => p.id === pane.id);
+}
+/** Mark agents whose session is gone as exited. Reconcile-culls against the current mux's live set
+* first, then judges each remaining record (covers the other mux and sessions outside any
+* multiplexer pane): a pane-bound record by its pane alone — a live or unprobeable pane keeps it
+* whatever its last-seen — and a pane-less record by the staleness timer, its only signal. */
 function prune(ctx) {
 	const exec = ctx.exec ?? realExec;
 	const now = ctx.now?.() ?? Date.now();
 	const changed = reconcile(ctx);
+	const lists = /* @__PURE__ */ new Map();
 	for (const rec of listAgents(ctx.store)) {
 		if (!isPrunable(rec)) 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) {
+		if (rec.pane ? paneGone(exec, rec.pane, lists) : now - new Date(rec.lastSeen).getTime() > STALE_MS) {
 			rec.status = "exited";
 			saveAgent(ctx.store, rec);
 			changed.push(rec);
@@ -639,6 +658,59 @@ async function withDraftGuard(adapter, exec, target, send, options = {}) {
 	}
 }
 //#endregion
+//#region src/console/ring.ts
+const DEFAULT_ATTEMPTS = 10;
+const DEFAULT_SETTLE_MS = 400;
+/** cyber-mux's `isStaged` matches on the same prefix length. */
+const NEEDLE_LEN = 40;
+/** How many screen rows carry `message` — the transcript, a queued follow-up, the input box. */
+function copiesOn(screen, message) {
+	if (!screen) return 0;
+	const needle = message.replace(/\s+/g, " ").trim().slice(0, NEEDLE_LEN);
+	if (needle === "") return 0;
+	return screen.split("\n").filter((row) => row.replace(/\s+/g, " ").includes(needle)).length;
+}
+/**
+* Submit `message` to `target` as a taken turn: cyber-mux's `nudge`, with one more way to see that the
+* turn was taken.
+*
+* `nudge` judges the turn by whether the text still sits at the bottom of the screen, and flushes
+* with a bare Enter while it does. Some harness screens put a taken turn back in the input box —
+* cursor-agent with a rejected login posts the ring to its transcript (or queues it as a follow-up)
+* and restores the same text into the box — so `nudge` flushes, and each flush rings again.
+*
+* So the screen is counted before the ring and after each submit. A swallowed Enter adds one copy of
+* the text, the one in the input box. Two or more new copies mean the harness also posted it above
+* the box, so the turn was taken and nothing is flushed. Text still at the bottom with only one new
+* copy is the swallowed Enter, and is flushed as before.
+*/
+async function ringTurn(adapter, exec, target, message, opts = {}) {
+	const attempts = opts.attempts ?? DEFAULT_ATTEMPTS;
+	const settleMs = opts.settleMs ?? DEFAULT_SETTLE_MS;
+	const sleep = opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+	if (!adapter.paneExists(exec, target)) throw new Error(`nudge failed: pane ${target.id} no longer exists — the peer's session is gone, not busy.`);
+	const before = copiesOn(adapter.read(exec, target).text, message);
+	const taken = () => {
+		const screen = adapter.read(exec, target).text;
+		return !isStaged(screen, message) || copiesOn(screen, message) >= before + 2;
+	};
+	adapter.submit(exec, target, message);
+	await sleep(settleMs);
+	if (taken()) return {
+		taken: true,
+		resubmits: 0
+	};
+	for (let attempt = 1; attempt <= attempts; attempt++) {
+		adapter.submit(exec, target);
+		await sleep(settleMs);
+		if (taken()) return {
+			taken: true,
+			resubmits: attempt
+		};
+	}
+	throw new Error(`nudge failed: peer at pane ${target.id} never took the turn — input still staged after ${attempts} re-submit attempts`);
+}
+//#endregion
 //#region src/console/doorbell.ts
 /**
 * The first-turn doorbell `unit spawn` delivers to a freshly-opened paned peer — the instruction
@@ -683,7 +755,7 @@ async function wakeSpawn(getAdapter, exec, input, nudgeOpts = SPAWN_NUDGE_OPTS,
 	if (input.noWake) return { rung: false };
 	try {
 		const adapter = getAdapter();
-		await withDraftGuard(adapter, exec, input.target, () => nudge(adapter, exec, input.target, spawnDoorbell(input.briefPath), nudgeOpts), {
+		await withDraftGuard(adapter, exec, input.target, () => ringTurn(adapter, exec, input.target, spawnDoorbell(input.briefPath), nudgeOpts), {
 			...guardOpts,
 			harness: input.harness
 		});
@@ -700,6 +772,117 @@ async function wakeSpawn(getAdapter, exec, input, nudgeOpts = SPAWN_NUDGE_OPTS,
 	}
 }
 //#endregion
+//#region src/console/trust.ts
+/**
+* Each harness's folder-trust prompt, as it draws it, and the keys that accept it. Read from Claude
+* Code 2.1.286, Codex 0.153.4 (and its newer "Trust this folder?" wording), and cursor-agent
+* 2026.09.26, each opened in a real tmux pane on a folder it did not trust.
+*
+* Claude Code lists "No, exit" first and focuses it, so a bare Enter quits the harness. Its accept is
+* therefore Down, a check that the screen shows "Yes, I trust this folder" selected, and only then
+* Enter. Codex highlights its first option on `1` and confirms on Enter. cursor-agent takes `a`
+* directly.
+*/
+const TRUST_PROMPTS = {
+	claude: {
+		markers: [["Quick safety check", "Yes, I trust this folder"]],
+		accept: [{
+			keys: ["Down"],
+			until: /❯\s*Yes, I trust this folder/
+		}, { keys: ["Enter"] }]
+	},
+	codex: {
+		markers: [["Do you trust the contents of this directory?", "Yes, continue"], ["Trust this folder?", "Trust and continue"]],
+		accept: [{
+			text: "1",
+			until: /›\s*1\.\s*(?:Yes, continue|Trust and continue)/
+		}, { keys: ["Enter"] }]
+	},
+	cursor: {
+		markers: [["Workspace Trust Required", "Trust this workspace"]],
+		accept: [{ text: "a" }]
+	}
+};
+const collapse = (s) => s.replace(/\s+/g, " ");
+/** Whether `screen` shows `harness`'s folder-trust prompt. */
+function showsTrustPrompt(harness, screen) {
+	const flat = collapse(screen);
+	return TRUST_PROMPTS[harness].markers.some((set) => set.every((phrase) => flat.includes(collapse(phrase))));
+}
+/**
+* Watch a freshly-opened pane until its harness either shows its folder-trust prompt or settles on a
+* screen without one, and answer the prompt by `input.policy`.
+*
+* "Settled" means the screen has changed from its first read (the shell, still showing the launch
+* line while the harness loads) and then read the same `stableReads` times in a row. A harness that
+* never draws within the timeout, or a screen that stays blank for `blankReads` reads, is
+* `unsettled`: no evidence of a prompt, so the caller rings as it would have before. Only the screen is read; no harness config file is consulted, so what counts is
+* what the harness itself decided to show.
+*/
+async function answerTrustPrompt(adapter, exec, target, input, opts = {}) {
+	const pollMs = opts.pollMs ?? 500;
+	const timeoutMs = opts.timeoutMs ?? 2e4;
+	const stableReads = opts.stableReads ?? 3;
+	const blankReads = opts.blankReads ?? 6;
+	const keyDelayMs = opts.keyDelayMs ?? 1e3;
+	const attempts = opts.attempts ?? 5;
+	const sleep = opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+	const read = () => {
+		try {
+			return adapter.read(exec, target).text ?? "";
+		} catch {
+			return "";
+		}
+	};
+	const shown = (screen) => showsTrustPrompt(input.harness, screen);
+	const first = read();
+	let seen = shown(first);
+	let previous = first;
+	let changed = false;
+	let same = 1;
+	for (let waited = 0; !seen && waited < timeoutMs; waited += pollMs) {
+		await sleep(pollMs);
+		const screen = read();
+		if (shown(screen)) {
+			seen = true;
+			break;
+		}
+		if (screen !== first) changed = true;
+		same = screen === previous ? same + 1 : 1;
+		previous = screen;
+		if (changed && same >= stableReads) return { state: "none" };
+		if (!changed && first.trim() === "" && same >= blankReads) return { state: "unsettled" };
+	}
+	if (!seen) return { state: "unsettled" };
+	const where = `${input.harness} in pane ${input.pane} is asking whether to trust ${input.folder}`;
+	if (input.policy === "ask") return {
+		state: "needs-human",
+		message: `${where}. unit spawn does not trust a folder it did not create, so a person must answer that prompt. The unit is registered and its brief written; once the prompt is answered, nudge the unit to its brief.`
+	};
+	await sleep(keyDelayMs);
+	for (const move of TRUST_PROMPTS[input.harness].accept) {
+		let done = move.until ? move.until.test(read()) : false;
+		for (let attempt = 0; !done && attempt < attempts; attempt++) {
+			if (move.keys) adapter.sendKeys(exec, target, move.keys);
+			if (move.text) adapter.sendText(exec, target, move.text);
+			await sleep(pollMs);
+			done = move.until ? move.until.test(read()) : true;
+		}
+		if (!done) return stuck(where);
+	}
+	for (let attempt = 0; attempt < attempts; attempt++) {
+		if (!shown(read())) return { state: "accepted" };
+		await sleep(pollMs);
+	}
+	return stuck(where);
+}
+function stuck(where) {
+	return {
+		state: "stuck",
+		message: `${where}, and the prompt is still showing after spawn sent the keys that accept it. A person must answer it.`
+	};
+}
+//#endregion
 //#region src/mux-select.ts
 /**
 * Backend selection via cyber-mux's two-mode mux probe, normalized through the transitional
@@ -933,7 +1116,10 @@ function spawn(ctx, input) {
 			assertDistinctFromPrimary$1(opened.worktree.root, primaryRoot);
 			ensureMarker(join(opened.worktree.root, ".agents", "cyberlegion"));
 			cwd = opened.worktree.root;
-			worktree = opened.worktree;
+			worktree = {
+				...opened.worktree,
+				primaryRoot
+			};
 			target = opened.target;
 		} else {
 			const added = gitWorktreeAdapter$1.add(exec, {
@@ -944,7 +1130,10 @@ function spawn(ctx, input) {
 			assertDistinctFromPrimary$1(added.root, primaryRoot);
 			ensureMarker(join(added.root, ".agents", "cyberlegion"));
 			cwd = added.root;
-			worktree = added;
+			worktree = {
+				...added,
+				primaryRoot
+			};
 			target = sessionAdapter.open(exec, {
 				cwd,
 				launch: launchLine(),
@@ -994,11 +1183,25 @@ function spawn(ctx, input) {
 * 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.
+*
+* Before the ring, the harness's folder-trust prompt is answered (`answerTrustPrompt`), with or
+* without `--no-wake`: a unit stuck at that prompt never reads its brief, and the doorbell typed into
+* it would answer it wrongly (Claude Code's focused option is "No, exit"). A worktree spawn made the
+* folder from the caller's own repository, so its prompt is accepted. A `--cwd` folder was not made
+* here, so its prompt is left for a person. A prompt left showing either way rings nothing and is
+* reported as `trustBlocked`, a failure the caller must surface, not a best-effort warning.
 */
 async function spawnAndWake(ctx, input, options = {}) {
 	const res = spawn(ctx, input);
 	const env = ctx.env ?? process.env;
 	const exec = ctx.exec ?? realExec;
+	const trust = await settleTrust(ctx, res, options.trustOpts);
+	if (trust.state === "needs-human" || trust.state === "stuck") return {
+		...res,
+		rung: false,
+		trust: trust.state,
+		trustBlocked: trust.message
+	};
 	const briefPath = res.agent.brief;
 	const wake = await wakeSpawn(() => selectSessionAdapter(env, exec), exec, {
 		target: { id: res.pane },
@@ -1009,10 +1212,31 @@ async function spawnAndWake(ctx, input, options = {}) {
 	return {
 		...res,
 		rung: wake.rung,
+		trust: trust.state,
 		...wake.warning ? { warning: wake.warning } : {}
 	};
 }
 /**
+* Answer the new pane's folder-trust prompt, if its harness shows one. A backend that cannot be
+* resolved leaves nothing to read, which is no evidence of a prompt: the ring's own containment
+* reports that backend.
+*/
+async function settleTrust(ctx, res, opts) {
+	const exec = ctx.exec ?? realExec;
+	let adapter;
+	try {
+		adapter = selectSessionAdapter(ctx.env ?? process.env, exec);
+	} catch {
+		return { state: "unsettled" };
+	}
+	return answerTrustPrompt(adapter, exec, { id: res.pane }, {
+		harness: res.agent.harness,
+		folder: res.agent.cwd,
+		pane: res.pane,
+		policy: res.agent.worktree ? "accept" : "ask"
+	}, opts);
+}
+/**
 * 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
@@ -1213,25 +1437,38 @@ const DEFAULT_HARNESS = "claude";
 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 a named model. Cursor refuses
-* an effort on its default (`auto[effort=high]` is not a model it accepts), so a cursor effort with
-* no model is left off and `realizeLaunch` reports it as not applied. */
+/** Cursor's model + effort, as the model id to launch and whether the effort rode along. Cursor has
+* no effort flag, and refuses the `<model>[effort=<level>]` bracket form its `--help` documents
+* (#72); `cursor-agent models` lists effort baked into flat ids (`claude-opus-5-high`) instead. So
+* the effort travels as the listed `<model>-<level>` id, or the model itself when it already is
+* one; with no such id listed, the model launches without the effort. Cursor also refuses an
+* effort on its default (`auto[effort=high]`), so with no model there is nothing to launch it on. */
+function cursorModel(model, effort, listCursorModels = () => []) {
+	if (!model || !effort) return {
+		model,
+		effortApplied: !effort
+	};
+	const listed = listCursorModels();
+	const suffix = `-${effort}`;
+	if (model.endsWith(suffix) && listed.includes(model)) return {
+		model,
+		effortApplied: true
+	};
+	const flat = `${model}${suffix}`;
+	if (listed.includes(flat)) return {
+		model: flat,
+		effortApplied: true
+	};
+	return {
+		model,
+		effortApplied: false
+	};
+}
+/** The model + effort arguments for claude or codex, which spell effort differently: claude has
+* `--effort`, codex only a config override. Cursor's effort rides on its model (`cursorModel`). */
 function modelAndEffortArgs(harness, model, effort) {
-	if (harness === "cursor") {
-		if (!model) return [];
-		return ["--model", shellQuote(effort ? withCursorEffort(model, effort) : model)];
-	}
 	const args = model ? ["--model", shellQuote(model)] : [];
-	if (!effort) return args;
+	if (!effort || harness === "cursor") return args;
 	if (harness === "codex") return [
 		...args,
 		"-c",
@@ -1257,18 +1494,20 @@ function instructionArgs(harness, 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`). */
+* through the harness's own control (see `cursorModel`, `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 asked = opts.model ?? def.model;
+	const cursor = harness === "cursor" ? cursorModel(asked, effort, opts.listCursorModels) : void 0;
+	const model = cursor ? cursor.model : asked;
 	const parts = [
 		LAUNCH_MAP[harness],
 		...modelAndEffortArgs(harness, model, effort),
 		...instructionArgs(harness, def.instructions)
 	];
 	const briefInstructions = harness === "cursor" && def.instructions ? def.instructions : void 0;
-	const notApplied = harness === "cursor" && effort && !model ? effort : void 0;
+	const notApplied = cursor && !cursor.effortApplied ? effort : void 0;
 	return {
 		harness,
 		command: parts.join(" "),
@@ -1361,12 +1600,18 @@ function decommission(ctx, input) {
 	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 primaryRoot = worktreeExists ? primaryRootOf(exec, worktreeRoot) : rec.worktree?.primaryRoot;
+	if (worktreeRoot && primaryRoot && 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 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 (worktreeRoot && !worktreeExists && primaryRoot && existsSync(primaryRoot)) exec("git", [
+		"-C",
+		primaryRoot,
+		"worktree",
+		"prune"
+	]);
 	if (removesWorktree) try {
 		gitWorktreeAdapter$1.remove(exec, worktreeRoot, { primaryRoot });
 	} catch (err) {
@@ -1386,13 +1631,38 @@ function decommission(ctx, input) {
 		pane
 	};
 }
+/**
+* The primary checkout of the repository `worktreeRoot` belongs to — `--git-common-dir` asked of the
+* worktree itself, so the answer does not depend on where the caller runs. Throws for a directory git
+* does not know: there is no repository to remove it from.
+*/
+function primaryRootOf(exec, worktreeRoot) {
+	const commonDir = exec("git", [
+		"-C",
+		worktreeRoot,
+		"rev-parse",
+		"--path-format=absolute",
+		"--git-common-dir"
+	]);
+	if (!commonDir) throw new Error(`cannot resolve the repository of worktree ${worktreeRoot} — git does not know it`);
+	return dirname(commonDir);
+}
+/**
+* Whether the worktree holds work a removal would discard. The marker `spawn` stamps into every
+* worktree it creates is cyberlegion's own file, not the unit's work: in a project that does not
+* track it, it shows as untracked in every spawned worktree, and counting it would make a plain close
+* of a finished unit always demand `--force`. Only that exact untracked path is set aside — listed
+* per file, so anything else the unit left under `.agents/` still counts.
+*/
 function isDirty(exec, worktreeRoot) {
-	return !!exec("git", [
+	const status = exec("git", [
 		"-C",
 		worktreeRoot,
 		"status",
-		"--porcelain"
+		"--porcelain",
+		"--untracked-files=all"
 	]);
+	return !!status && status.split("\n").some((line) => line && line !== `?? ${WORKTREE_MARKER}`);
 }
 //#endregion
 //#region src/install.ts
@@ -1400,33 +1670,35 @@ 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}`;
+const hookCommand = (event, pin) => `if command -v cyberlegion >/dev/null 2>&1; then cyberlegion mail hook --event ${event}; else npx -y cyberlegion${pin ? `@${pin}` : ""} mail hook --event ${event}; fi`;
+const HOOK_GENERATIONS = [/^(?:npx (?:-y )?cyberlegion(?:@\S+)?|cyberlegion) mail hook --event (\w+)$/, /^if command -v cyberlegion >\/dev\/null 2>&1; then cyberlegion mail hook --event (\w+); else npx -y cyberlegion(?:@\S+)? mail hook --event \1; fi$/];
 function hookTarget(command) {
-	return command.match(/^(?:npx cyberlegion(?:@[^\s]+)?|cyberlegion) (mail hook --event \S+)$/)?.[1];
+	for (const generation of HOOK_GENERATIONS) {
+		const event = command.match(generation)?.[1];
+		if (event) return event;
+	}
 }
 const VENDORS = {
 	claude: {
 		file: ".claude/settings.json",
 		shape: "claude",
-		events: {
-			SessionStart: "SessionStart",
-			PostToolUse: "PostToolUse"
-		}
+		events: { SessionStart: "SessionStart" },
+		pluginHook: true
 	},
 	cursor: {
 		file: ".cursor/hooks.json",
 		shape: "cursor",
-		events: { SessionStart: "sessionStart" }
+		events: { SessionStart: "sessionStart" },
+		pluginHook: false
 	},
 	codex: {
 		file: ".codex/hooks.json",
 		shape: "cursor",
-		events: {
-			SessionStart: "SessionStart",
-			PostToolUse: "PostToolUse"
-		}
+		events: { SessionStart: "SessionStart" },
+		pluginHook: true
 	}
 };
+const RETIRED_EVENTS = ["PostToolUse"];
 function readJson(file) {
 	if (!existsSync(file)) return {};
 	try {
@@ -1439,7 +1711,10 @@ 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. */
+/**
+* Make sure the surfacing hook fires for one harness, idempotently: leave it to the plugin where the
+* plugin ships it (removing an earlier project copy), otherwise register the PATH-first project hook.
+*/
 function install(harness, projectDir = process.cwd(), pin) {
 	const spec = VENDORS[harness];
 	if (!spec) throw new Error(`unknown harness "${harness}" (expected claude | cursor | codex)`);
@@ -1447,9 +1722,18 @@ function install(harness, projectDir = process.cwd(), pin) {
 	const file = join(projectDir, spec.file);
 	const settings = readJson(file);
 	const results = [];
+	let changed = false;
 	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);
+		let status;
+		if (spec.pluginHook) {
+			const removed = spec.shape === "claude" ? removeClaude(settings, vendorEvent, canonical) : removeCursor(settings, vendorEvent, canonical);
+			status = removed ? "removed project hook" : "provided by plugin";
+			changed ||= removed;
+		} else {
+			const command = hookCommand(canonical, pin);
+			status = spec.shape === "claude" ? upsertClaude(settings, vendorEvent, command) : upsertCursor(settings, vendorEvent, command);
+			changed = true;
+		}
 		results.push({
 			harness,
 			event: canonical,
@@ -1458,7 +1742,18 @@ function install(harness, projectDir = process.cwd(), pin) {
 			status
 		});
 	}
-	writeJson$1(file, settings);
+	if (spec.pluginHook) for (const event of RETIRED_EVENTS) {
+		if (!(spec.shape === "claude" ? removeClaude(settings, event, event) : removeCursor(settings, event, event))) continue;
+		changed = true;
+		results.push({
+			harness,
+			event,
+			vendorEvent: event,
+			file,
+			status: "removed project hook"
+		});
+	}
+	if (changed) writeJson$1(file, settings);
 	return results;
 }
 function upsertClaude(settings, event, command) {
@@ -1472,12 +1767,10 @@ function upsertClaude(settings, event, command) {
 			return "already present";
 		}
 	}
-	const group = { hooks: [{
+	groups.push({ hooks: [{
 		type: "command",
 		command
-	}] };
-	if (event === "PostToolUse") group.matcher = "Write|Edit";
-	groups.push(group);
+	}] });
 	return "registered";
 }
 function upsertCursor(settings, event, command) {
@@ -1495,6 +1788,36 @@ function upsertCursor(settings, event, command) {
 	list.push({ command });
 	return "registered";
 }
+const isOurs = (command, event) => command !== void 0 && hookTarget(command) === event;
+function removeClaude(settings, event, canonical) {
+	const hooks = settings.hooks;
+	const groups = hooks?.[event];
+	if (!hooks || !groups) return false;
+	let removed = false;
+	const kept = [];
+	for (const g of groups) {
+		const entries = (g.hooks ?? []).filter((h) => !isOurs(h.command, canonical));
+		if (entries.length !== (g.hooks ?? []).length) removed = true;
+		if (entries.length > 0) kept.push({
+			...g,
+			hooks: entries
+		});
+	}
+	if (!removed) return false;
+	if (kept.length > 0) hooks[event] = kept;
+	else delete hooks[event];
+	return true;
+}
+function removeCursor(settings, event, canonical) {
+	const hooks = settings.hooks;
+	const list = hooks?.[event];
+	if (!hooks || !list) return false;
+	const kept = list.filter((h) => !isOurs(h.command, canonical));
+	if (kept.length === list.length) return false;
+	if (kept.length > 0) hooks[event] = kept;
+	else delete hooks[event];
+	return true;
+}
 //#endregion
 //#region src/output.ts
 function stringifyCell(v) {
@@ -1651,7 +1974,7 @@ function byPath(ctx, dir) {
 }
 //#endregion
 //#region src/runtime/inject-inbox.ts
-const EVENTS = ["SessionStart", "PostToolUse"];
+const EVENTS = ["SessionStart"];
 /**
 * 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
@@ -1699,9 +2022,6 @@ function injectInbox(ctx, event) {
 			}
 		}
 	} 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,

package/hooks/hooks.json

@@ -0,0 +1,14 @@
+{
+	"hooks": {
+		"SessionStart": [
+			{
+				"hooks": [
+					{
+						"type": "command",
+						"command": "node \"${CLAUDE_PLUGIN_ROOT}/bin/cyberlegion.mjs\" mail hook --event SessionStart"
+					}
+				]
+			}
+		]
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cyberlegion",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Harness-agnostic agent session spawning and messaging over the filesystem",
   "keywords": [
     "agent",
@@ -36,6 +36,7 @@
     ".codex-plugin",
     ".plugin",
     "skills",
+    "hooks",
     "agents"
   ],
   "dependencies": {