cyberfleet 0.0.0 → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 unional
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/cli.mjs

@@ -1,499 +1,8 @@
 #!/usr/bin/env node
-import { execFileSync } from "node:child_process";
-import { Command } from "commander";
-import { randomBytes } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-//#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);
-}
-/**
-* The flagship rule: refuse when a ship's resolved worktree root would be the primary checkout
-* itself. Mirrors firstmate's "refuse unless the path is a real worktree root distinct from the
-* project primary checkout" — a mission is never run in the primary checkout.
-*/
-function assertDistinctFromPrimary(worktreeRoot, primaryRoot) {
-	if (resolve(worktreeRoot) === resolve(primaryRoot)) throw new Error("refusing to run a mission in the primary checkout — spawn a worktree-ship distinct from the flagship");
-}
-//#endregion
-//#region src/paths.ts
-/** The tracked marker file inside `.cyberfleet/` that makes a project root a ship (see detectMode). */
-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 shared `.cyberfleet` transport root. Precedence: explicit --root/--space, then
-* CYBERFLEET_ROOT, then the PRIMARY checkout's `.cyberfleet` (ADR-0022 decision 10 — the primary
-* and every worktree are both ships, but runtime state — agents/inbox/panes — stays pinned to the
-* primary so it is shared fleet-wide instead of forking per worktree), falling back to the
-* caller's own project root when not inside a git repository.
-*/
-function resolveRoot(opts = {}) {
-	const env = opts.env ?? process.env;
-	const explicit = opts.root ?? opts.space ?? env.CYBERFLEET_ROOT;
-	if (explicit) return resolve(explicit);
-	const exec = opts.exec ?? makeDefaultExec(opts.cwd);
-	let primary;
-	try {
-		primary = resolvePrimaryRoot(exec);
-	} catch {
-		primary = void 0;
-	}
-	return join(primary ?? projectRoot(opts.cwd), ".cyberfleet");
-}
-/**
-* Detect ship vs. command-center by the tracked `.cyberfleet/config.json` marker's presence alone
-* at this project root — no check against `.agents/specs` or any other SDD state. The marker is
-* tracked (`.gitignore` excludes the rest of `.cyberfleet/`), so it travels to every worktree: the
-* primary checkout AND every worktree it spawns are both ships once the marker exists. Checking
-* the marker file rather than just the directory avoids a false positive from a stray empty
-* `.cyberfleet/` dir (e.g. one left behind after a partial teardown).
-*/
-function detectMode(opts = {}) {
-	const cwdRoot = projectRoot(opts.cwd);
-	return {
-		mode: existsSync(join(cwdRoot, ".cyberfleet", MARKER_FILE)) ? "ship" : "command-center",
-		cwdRoot,
-		fleetRoot: resolveRoot(opts)
-	};
-}
-/**
-* Create the tracked `.cyberfleet/config.json` marker at `root` (a fleet root, i.e. a
-* `.cyberfleet/` dir path) if it does not already exist, making that project root a ship. Callers
-* pass the root under which `.cyberfleet/` should be created/ensured; this mkdir's it as needed.
-* Idempotent — never overwrites an existing marker.
-*/
-function ensureFleetMarker(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`),
-	selfFile: (root) => join(root, "self"),
-	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"),
-	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/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 writeJson$1(file, data) {
-	mkdirSync(dirname(file), { recursive: true });
-	writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`);
-}
-/** 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 file is authoritative — a pane with no
-* pane file is simply unregistered and must NOT adopt the non-tmux self identity (per the frozen
-* scenario, the env/self-file fallback applies only when there is no $TMUX_PANE).
-*/
-function resolveSelfId(ctx) {
-	const env = ctx.env ?? process.env;
-	const pane = env.TMUX_PANE;
-	if (pane) {
-		const file = paths.paneFile(ctx.root, pane);
-		return existsSync(file) ? readFileSync(file, "utf8").trim() : void 0;
-	}
-	if (env.CYBERFLEET_AGENT_ID) return env.CYBERFLEET_AGENT_ID;
-	const self = paths.selfFile(ctx.root);
-	if (existsSync(self)) return readFileSync(self, "utf8").trim();
-}
-function loadAgent(root, id) {
-	const file = paths.agentFile(root, id);
-	if (!existsSync(file)) return void 0;
-	return JSON.parse(readFileSync(file, "utf8"));
-}
-function saveAgent(root, rec) {
-	writeJson$1(paths.agentFile(root, rec.id), rec);
-}
-function listAgents(root) {
-	const dir = paths.agentsDir(root);
-	if (!existsSync(dir)) return [];
-	return readdirSync(dir).filter((f) => f.endsWith(".json")).map((f) => JSON.parse(readFileSync(`${dir}/${f}`, "utf8"))).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
-}
-/** Register (or idempotently refresh) this session's identity. */
-function register(ctx, input) {
-	ensureFleetMarker(ctx.root);
-	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.root, 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.root, rec);
-	if (pane) writeFileText(paths.paneFile(ctx.root, pane), id);
-	else writeFileText(paths.selfFile(ctx.root), 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
-	};
-}
-function writeFileText(file, text) {
-	mkdirSync(dirname(file), { recursive: true });
-	writeFileSync(file, text);
-}
-/** Resolve a recipient argument (id or handle) to an agent id. */
-function resolveRecipient(root, to) {
-	if (loadAgent(root, to)) return to;
-	const match = listAgents(root).find((a) => a.handle === to);
-	if (!match) throw new Error(`no agent addressable as "${to}"`);
-	return match.id;
-}
-/**
-* Resolve a ship reference by id, handle, or its worktree branch (the ship↔CR join key, ADR-0022
-* decision 8 + the `add-fleet-comms` CR's convention: an `AgentRecord.worktree.branch` equals the
-* SDD `<cr-ref>` it maps to). Used by verbs that address "the ship working on CR X" as well as
-* "the ship named X".
-*/
-function resolveShip(root, ref) {
-	const byId = loadAgent(root, ref);
-	if (byId) return byId;
-	const agents = listAgents(root);
-	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 ship addressable as "${ref}" (tried id, handle, and worktree branch/CR)`);
-}
-/**
-* Pause a ship's mission — a cyberfleet-level marker on its `AgentRecord.status` only. This is
-* NOT a bridge to SDD's `pause-mission` checkpoint (which rewrites the plan brief's todos/NEXT
-* anchor) — that gap is flagged, not silently papered over: a caller who wants the actual mission
-* checkpoint must run `sdd:pause-mission` in-session.
-*/
-function pauseAgent(root, id) {
-	const rec = loadAgent(root, id);
-	if (!rec) throw new Error(`no agent "${id}"`);
-	rec.status = "paused";
-	saveAgent(root, rec);
-	return rec;
-}
-function bumpLastSeen(ctx, id) {
-	const rec = loadAgent(ctx.root, id);
-	if (!rec) return;
-	rec.lastSeen = nowIso(ctx);
-	saveAgent(ctx.root, 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.root)) {
-		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.root, rec);
-			changed.push(rec);
-		}
-	}
-	return changed;
-}
-//#endregion
-//#region src/install.ts
-const hookCommand = (event) => `cyberfleet inbox --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(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(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/message.ts
-/** Write one message file into the recipient's inbox. Collision-free by <epochMs>-<hex>. */
-function send(ctx, input) {
-	const toId = resolveRecipient(ctx.root, input.to);
-	const from = loadAgent(ctx.root, input.fromId);
-	const ts = ctx.now?.() ?? Date.now();
-	const id = `${ts}-${randomBytes(3).toString("hex")}`;
-	const msg = {
-		id,
-		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()
-	};
-	const dir = paths.inboxDir(ctx.root, toId);
-	mkdirSync(dir, { recursive: true });
-	writeFileSync(join(dir, `${id}.json`), `${JSON.stringify(msg, null, 2)}\n`);
-	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|->");
-}
-function readDir(dir) {
-	if (!existsSync(dir)) return [];
-	return readdirSync(dir).filter((f) => f.endsWith(".json")).map((f) => JSON.parse(readFileSync(join(dir, f), "utf8")));
-}
-/** List the caller's mail, chronological (lexical filename sort == time order). */
-function inbox(ctx, q) {
-	const unread = readDir(paths.inboxDir(ctx.root, q.meId)).map((m) => ({
-		...m,
-		read: false
-	}));
-	const acked = q.unread ? [] : readDir(paths.inboxReadDir(ctx.root, q.meId)).map((m) => ({
-		...m,
-		read: true
-	}));
-	let items = [...unread, ...acked];
-	if (q.from) items = items.filter((m) => m.from === q.from || m.fromHandle === q.from);
-	return items.sort((a, b) => a.id.localeCompare(b.id));
-}
-/** Print + ack a message by moving it out of the unread set. Errors if not unread. */
-function read(ctx, meId, msgId) {
-	const src = join(paths.inboxDir(ctx.root, meId), `${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 readDirPath = paths.inboxReadDir(ctx.root, meId);
-	mkdirSync(readDirPath, { recursive: true });
-	renameSync(src, join(readDirPath, `${msgId}.json`));
-	return msg;
-}
-//#endregion
+import { Command, Option } from "commander";
+import { FileStore, emit, listAgents, projectRoot, realExec, resolveAgent, resolvePrimaryRoot, resolveRoot, selectSessionAdapter, toonList, toonObject, touch } from "cyberlegion";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
 //#region src/sdd/hal.ts
 /**
 * Infer whether a CR's persisted gate lines show a self-assertion the run-level leash did not
@@ -832,300 +341,149 @@ function buildMissions(agentsRoot, agents) {
 	return agents.map((a) => buildMissionRow(agentsRoot, a));
 }
 //#endregion
-//#region src/output.ts
-function printFields(fields) {
-	const entries = Object.entries(fields).filter(([, v]) => v != null);
-	if (entries.length === 0) return;
-	const width = Math.max(...entries.map(([k]) => k.length));
-	for (const [key, val] of entries) console.log(`${key.padEnd(width)}  ${val}`);
-}
-function printTable(items, cols) {
-	if (items.length === 0) {
-		console.log("(none)");
-		return;
-	}
-	const widths = cols.map((c) => Math.max(c.label.length, ...items.map((i) => c.get(i).length)));
-	console.log(cols.map((c, i) => c.label.toUpperCase().padEnd(widths[i])).join("  "));
-	console.log(widths.map((w) => "-".repeat(w)).join("  "));
-	for (const item of items) console.log(cols.map((c, i) => c.get(item).padEnd(widths[i])).join("  "));
-}
-//#endregion
-//#region src/runtime/inject-inbox.ts
-const EVENTS = ["SessionStart", "PostToolUse"];
+//#region src/mode.ts
+/** The tracked marker file that makes a cyberlegion root initialized (mirrors cyberlegion's own
+* `ensureMarker` — kept in sync by hand since it is not itself exported). */
+const MARKER_FILE = "config.json";
 /**
-* 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).
+* Detect ship vs. command-center by the tracked `.agents/cyberlegion/config.json` marker's
+* presence alone at this project root — no check against `.agents/specs` or any other SDD state.
+* A spawned unit worktree is stamped with its own marker at spawn time (see cyberlegion's
+* `session.ts`), so this simply asks: is this cwd's project root one of those stamped worktrees?
 */
-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.root, meId);
-	if (rec?.status === "spawning") {
-		const briefFile = paths.briefFile(ctx.root, meId);
-		if (existsSync(briefFile)) parts.push(`## Your brief\n\n${readFileSync(briefFile, "utf8").trim()}`);
-		rec.status = "active";
-		saveAgent(ctx.root, rec);
-	}
-	const unread = inbox({ root: ctx.root }, {
-		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 fleet mail (${unread.length})\n\n${lines.join("\n")}`);
-	}
-	if (parts.length === 0) return null;
-	return { hookSpecificOutput: {
-		hookEventName: event,
-		additionalContext: parts.join("\n\n")
-	} };
+function detectMode(opts = {}) {
+	const cwdRoot = projectRoot(opts.cwd);
+	return {
+		mode: existsSync(join(cwdRoot, ".agents", "cyberlegion", MARKER_FILE)) ? "ship" : "command-center",
+		cwdRoot,
+		fleetRoot: resolveRoot(opts)
+	};
 }
 //#endregion
 //#region src/cli.ts
 function ctxOf(opts) {
 	return {
-		root: resolveRoot({
+		store: new FileStore(resolveRoot({
 			root: opts.root,
 			space: opts.space
-		}),
+		})),
 		env: process.env
 	};
 }
-function requireSelf(ctx) {
-	const id = resolveSelfId(ctx);
-	if (!id) throw new Error("no fleet identity in this session — run `cyberfleet register` first");
-	bumpLastSeen(ctx, id);
-	return id;
+function formatOf(opts) {
+	return opts.format === "json" ? "json" : "toon";
+}
+/**
+* Pause a unit's mission — a cyberfleet-level marker on its `AgentRecord.status` only. Not
+* exported by cyberlegion (fleet-specific concept), so it stays here — a thin write through the
+* shared `Store` seam. This is NOT a bridge to SDD's `pause-mission` checkpoint (which rewrites the
+* plan brief's todos/## NEXT anchor) — that gap is flagged, not silently papered over: a caller who
+* wants the actual mission checkpoint must run `sdd:pause-mission` in-session.
+*/
+function pauseAgent(ctx, id) {
+	const rec = ctx.store.getAgent(id);
+	if (!rec) throw new Error(`no agent "${id}"`);
+	rec.status = "paused";
+	ctx.store.putAgent(rec);
+	return rec;
 }
-const rootOpts = (cmd) => cmd.option("--root <path>", "transport root (.cyberfleet dir)").option("--space <path>", "alias for --root");
+const rootOpts = (cmd) => cmd.option("--root <path>", "cyberlegion hub root (overrides the global hub / $CYBERLEGION_ROOT)").option("--space <path>", "alias for --root").addOption(new Option("--format <format>", "output format").choices(["toon", "json"]).default("toon"));
 const program = new Command();
-program.name("cyberfleet").description("Harness-agnostic, MCP-free inter-agent sessions and messaging").version("0.0.0");
-rootOpts(program.command("register")).description("register or refresh this session identity").option("--handle <name>", "human handle for this agent").option("--harness <h>", "claude | cursor | codex (else auto-detected)").action((opts) => {
-	const rec = register(ctxOf(opts), {
-		handle: opts.handle,
-		harness: opts.harness
-	});
-	printFields({
-		id: rec.id,
-		handle: rec.handle,
-		harness: rec.harness,
-		status: rec.status
-	});
-});
-rootOpts(program.command("who")).description("list the addressable fleet").option("--all", "include exited agents").action((opts) => {
-	const ctx = ctxOf(opts);
-	touch(ctx);
-	printTable(listAgents(ctx.root).filter((a) => opts.all || a.status !== "exited"), [
-		{
-			label: "handle",
-			get: (a) => a.handle
-		},
-		{
-			label: "harness",
-			get: (a) => a.harness
-		},
-		{
-			label: "cwd",
-			get: (a) => a.cwd
-		},
-		{
-			label: "status",
-			get: (a) => a.status
-		},
-		{
-			label: "pane",
-			get: (a) => a.tmux?.pane ?? "-"
-		},
-		{
-			label: "last-seen",
-			get: (a) => a.lastSeen
-		},
-		{
-			label: "id",
-			get: (a) => a.id
-		}
-	]);
-});
-rootOpts(program.command("mode")).description("report ship (a .cyberfleet/ dir here) vs command-center, and the shared fleet root").action((opts) => {
+program.name("cyberfleet").description("Fleet layer over cyberlegion — ships, missions, and the Council view").version("0.0.0");
+rootOpts(program.command("mode")).description("report ship (a spawned unit worktree) vs command-center, and the shared fleet root").action((opts) => {
 	const info = detectMode({
 		root: opts.root,
 		space: opts.space
 	});
-	printFields({
-		mode: info.mode,
-		cwdRoot: info.cwdRoot,
-		fleetRoot: info.fleetRoot
-	});
-});
-rootOpts(program.command("send")).description("send a message to a peer (by handle or id)").requiredOption("--to <peer>", "recipient handle or id").option("--subject <s>", "subject").option("--body <text>", "message body").option("--body-file <path>", "read body from a file, or - for stdin").option("--thread <id>", "thread id").option("--reply-to <msg>", "message id this replies to").action((opts) => {
-	const ctx = ctxOf(opts);
-	const fromId = requireSelf(ctx);
-	const body = resolveBody(opts.body, opts.bodyFile);
-	const msg = send({ root: ctx.root }, {
-		fromId,
-		to: opts.to,
-		subject: opts.subject,
-		body,
-		thread: opts.thread,
-		replyTo: opts.replyTo
-	});
-	printFields({
-		sent: msg.id,
-		to: opts.to,
-		subject: msg.subject
-	});
-});
-rootOpts(program.command("inbox")).description("list your mail, or emit the SessionStart hook payload").option("--unread", "only un-acked mail").option("--from <id>", "filter by sender").option("--hook", "emit the harness hook injection payload instead").option("--event <event>", "SessionStart | PostToolUse (with --hook)", "SessionStart").action((opts) => {
-	const ctx = ctxOf(opts);
-	if (opts.hook) {
-		touch(ctx);
-		const payload = injectInbox(ctx, opts.event);
-		if (payload) console.log(JSON.stringify(payload));
-		return;
-	}
-	const meId = requireSelf(ctx);
-	const items = inbox({ root: ctx.root }, {
-		meId,
-		unread: opts.unread,
-		from: opts.from
-	});
-	if (items.length === 0) {
-		console.log(opts.unread ? "(no unread mail)" : "(inbox empty)");
-		return;
-	}
-	for (const m of items) console.log(`${m.read ? " " : "*"} ${m.id}  ${m.fromHandle}${m.subject ? ` — ${m.subject}` : ""}: ${m.body}`);
-});
-rootOpts(program.command("read")).description("print a message and acknowledge it").argument("<msg-id>", "message id").action((msgId, opts) => {
-	const ctx = ctxOf(opts);
-	const meId = requireSelf(ctx);
-	const msg = read({ root: ctx.root }, meId, msgId);
-	printFields({
-		from: msg.fromHandle,
-		subject: msg.subject,
-		id: msg.id
+	emit(formatOf(opts), {
+		toon: toonObject({
+			mode: info.mode,
+			cwdRoot: info.cwdRoot,
+			fleetRoot: info.fleetRoot
+		}),
+		json: info
 	});
-	console.log(`\n${msg.body}`);
 });
-rootOpts(program.command("spawn")).description("launch a new peer session in its own git worktree (tmux or herdr)").requiredOption("--harness <h>", "claude | cursor | codex").option("--task <text>", "brief text, or - for stdin").option("--brief-file <path>", "read the brief from a file").option("--handle <name>", "handle for the new peer").option("--branch <name>", "branch for the new ship worktree (default cyberfleet/ship-<id>)").option("--worktree-path <path>", "where to check out the new ship worktree").action(async (opts) => {
-	const { spawn } = await import("./spawn-C036T1Ob.mjs");
+rootOpts(program.command("missions")).description("who needs the Council's hands — ships × mission × gate × leash, derived from SDD state").option("--agents-root <path>", "override the root under which .agents/ is resolved (default: the primary checkout)").action((opts) => {
 	const ctx = ctxOf(opts);
 	touch(ctx);
-	const res = spawn(ctx, {
-		harness: opts.harness,
-		task: opts.task,
-		briefFile: opts.briefFile,
-		handle: opts.handle,
-		branch: opts.branch,
-		worktreePath: opts.worktreePath
-	});
-	printFields({
-		spawned: res.agent.id,
-		handle: res.agent.handle,
-		harness: res.agent.harness,
-		worktree: res.agent.worktree?.root,
-		pane: res.pane,
-		launch: res.launch
+	const rows = buildMissions(opts.agentsRoot ?? resolveAgentsRoot(realExec), listAgents(ctx.store).filter((a) => a.status !== "exited"));
+	emit(formatOf(opts), {
+		toon: toonList("missions", rows, [
+			{
+				key: "handle",
+				get: (r) => r.handle
+			},
+			{
+				key: "branch",
+				get: (r) => r.branch ?? "-"
+			},
+			{
+				key: "status",
+				get: (r) => r.status
+			},
+			{
+				key: "mission",
+				get: (r) => r.mission ? `${r.mission.status} ${r.mission.completed}/${r.mission.total}` : "-"
+			},
+			{
+				key: "spec",
+				get: (r) => r.spec?.status ?? "-"
+			},
+			{
+				key: "gate:spec",
+				get: (r) => r.gate.spec ? `${r.gate.spec.verdict}(${r.gate.spec.by})` : "-"
+			},
+			{
+				key: "gate:impl",
+				get: (r) => r.gate.impl ? `${r.gate.impl.verdict}(${r.gate.impl.by})` : "-"
+			},
+			{
+				key: "leash",
+				get: (r) => r.leash ?? "-"
+			},
+			{
+				key: "council",
+				get: (r) => r.needsCouncil ? "yes" : "-"
+			},
+			{
+				key: "hal",
+				get: (r) => r.hal ? "!" : ""
+			}
+		], `${rows.length} ships`),
+		json: rows
 	});
 });
-rootOpts(program.command("prune")).description("mark dead agents exited and sweep").action((opts) => {
-	const ctx = ctxOf(opts);
-	touch(ctx);
-	const changed = prune(ctx);
-	console.log(changed.length ? `pruned ${changed.length} agent(s)` : "nothing to prune");
-});
-program.command("install").description("wire the fleet surfacing hook into a harness config").requiredOption("--agent <harness>", "claude | cursor | codex").option("--dir <path>", "project dir to write config into", process.cwd()).action((opts) => {
-	const results = install(opts.agent, opts.dir);
-	for (const r of results) console.log(`${r.status}: ${r.harness} ${r.vendorEvent} → ${r.file}`);
-});
-rootOpts(program.command("missions")).description("who needs the Council's hands — ships × mission × gate × leash, derived from SDD state").option("--json", "emit the full structured array instead of the table").option("--agents-root <path>", "override the root under which .agents/ is resolved (default: the primary checkout)").action((opts) => {
-	const ctx = ctxOf(opts);
-	touch(ctx);
-	const rows = buildMissions(opts.agentsRoot ?? resolveAgentsRoot(realExec), listAgents(ctx.root).filter((a) => a.status !== "exited"));
-	if (opts.json) {
-		console.log(JSON.stringify(rows, null, 2));
-		return;
-	}
-	printTable(rows, [
-		{
-			label: "handle",
-			get: (r) => r.handle
-		},
-		{
-			label: "branch/cr",
-			get: (r) => r.branch ?? "-"
-		},
-		{
-			label: "status",
-			get: (r) => r.status
-		},
-		{
-			label: "mission",
-			get: (r) => r.mission ? `${r.mission.status} ${r.mission.completed}/${r.mission.total}` : "-"
-		},
-		{
-			label: "spec",
-			get: (r) => r.spec?.status ?? "-"
-		},
-		{
-			label: "gate:spec",
-			get: (r) => r.gate.spec ? `${r.gate.spec.verdict}(${r.gate.spec.by})` : "-"
-		},
-		{
-			label: "gate:impl",
-			get: (r) => r.gate.impl ? `${r.gate.impl.verdict}(${r.gate.impl.by})` : "-"
-		},
-		{
-			label: "leash",
-			get: (r) => r.leash ?? "-"
-		},
-		{
-			label: "council",
-			get: (r) => r.needsCouncil ? "yes" : "-"
-		},
-		{
-			label: "HAL",
-			get: (r) => r.hal ? "!" : ""
-		}
-	]);
-});
 rootOpts(program.command("jump")).description("select/focus a ship's session (tmux pane), or print its worktree path to cd into").argument("<peer>", "handle, id, or worktree branch/CR ref").action((peer, opts) => {
 	const ctx = ctxOf(opts);
 	touch(ctx);
-	const agent = resolveShip(ctx.root, peer);
-	if (agent.tmux?.pane) try {
-		execFileSync("tmux", [
-			"select-pane",
-			"-t",
-			agent.tmux.pane
-		], { stdio: "ignore" });
-		printFields({
-			jumped: agent.handle,
-			pane: agent.tmux.pane
+	const agent = resolveAgent(ctx.store, peer);
+	const pane = agent.tmux?.pane ?? ctx.store.findPaneByAgentId(agent.id);
+	if (pane) try {
+		selectSessionAdapter(ctx.env ?? process.env).focus(realExec, { id: pane });
+		emit(formatOf(opts), {
+			toon: toonObject({
+				jumped: agent.handle,
+				pane
+			}),
+			json: {
+				jumped: agent.handle,
+				pane
+			}
 		});
 		return;
 	} catch {}
 	console.log(agent.worktree?.root ?? agent.cwd);
 });
-rootOpts(program.command("ack")).description("acknowledge a message (thin alias of `read` — both print + move it to acked)").argument("<msg-id>", "message id").action((msgId, opts) => {
-	const ctx = ctxOf(opts);
-	const meId = requireSelf(ctx);
-	const msg = read({ root: ctx.root }, meId, msgId);
-	printFields({
-		acked: msg.id,
-		from: msg.fromHandle,
-		subject: msg.subject
-	});
-});
 rootOpts(program.command("pause")).description("pause a ship's mission — a cyberfleet-level status marker only (see note)").argument("<peer>", "handle, id, or worktree branch/CR ref").action((peer, opts) => {
 	const ctx = ctxOf(opts);
-	const agent = resolveShip(ctx.root, peer);
-	const rec = pauseAgent(ctx.root, agent.id);
-	printFields({
-		paused: rec.handle,
-		status: rec.status
+	const rec = pauseAgent(ctx, resolveAgent(ctx.store, peer).id);
+	emit(formatOf(opts), {
+		toon: toonObject({
+			paused: rec.handle,
+			status: rec.status
+		}),
+		json: rec
 	});
 	process.stderr.write("note: this only flips the cyberfleet ship record to status:paused — it is NOT a bridge to SDD's pause-mission checkpoint (which rewrites the plan brief's todos/## NEXT anchor). Run `sdd:pause-mission` in-session for the actual mission checkpoint (flagged gap).\n");
 });
@@ -1152,4 +510,4 @@ program.parseAsync(process.argv).catch((err) => {
 	process.exit(1);
 });
 //#endregion
-export { ensureFleetMarker as a, gitWorktreeAdapter as c, saveAgent as i, resolvePrimaryRoot as l, realExec as n, paths as o, resolveSelfId as r, assertDistinctFromPrimary as s, randomId as t };
+export {};

package/package.json

@@ -1,56 +1,56 @@
 {
-	"name": "cyberfleet",
-	"version": "0.0.0",
-	"description": "Harness-agnostic, MCP-free inter-agent sessions and messaging over the filesystem",
-	"keywords": [
-		"agent",
-		"claude-code",
-		"cursor",
-		"codex",
-		"inter-agent",
-		"tmux"
-	],
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/cyberuni/cyberplace.git",
-		"directory": "packages/cyberfleet"
-	},
-	"license": "MIT",
-	"author": "unional <homawong@gmail.com>",
-	"type": "module",
-	"bin": {
-		"cyberfleet": "bin/cyberfleet.mjs"
-	},
-	"exports": {
-		"./package.json": "./package.json"
-	},
-	"files": [
-		"bin",
-		"dist"
-	],
-	"scripts": {
-		"build": "tsdown",
-		"dev": "tsx src/cli.ts",
-		"prepack": "pnpm build",
-		"test": "pnpm build && vitest run src",
-		"test:watch": "vitest",
-		"typecheck": "tsc --noEmit"
-	},
-	"dependencies": {
-		"commander": "^14.0.3"
-	},
-	"devDependencies": {
-		"@types/node": "^24.10.1",
-		"tsdown": "^0.22.0",
-		"tsx": "^4.22.3",
-		"typescript": "^6.0.0",
-		"vitest": "^4.1.7"
-	},
-	"engines": {
-		"node": ">=22"
-	},
-	"publishConfig": {
-		"access": "public",
-		"provenance": true
-	}
-}
+  "name": "cyberfleet",
+  "version": "0.0.1",
+  "description": "Harness-agnostic, MCP-free inter-agent sessions and messaging over the filesystem",
+  "keywords": [
+    "agent",
+    "claude-code",
+    "cursor",
+    "codex",
+    "inter-agent",
+    "tmux"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cyberuni/cyberplace.git",
+    "directory": "packages/cyberfleet"
+  },
+  "license": "MIT",
+  "author": "unional <homawong@gmail.com>",
+  "type": "module",
+  "bin": {
+    "cyberfleet": "bin/cyberfleet.mjs"
+  },
+  "exports": {
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "dist"
+  ],
+  "dependencies": {
+    "commander": "^14.0.3",
+    "cyberlegion": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "tsdown": "^0.22.0",
+    "tsx": "^4.22.3",
+    "typescript": "^6.0.0",
+    "vitest": "^4.1.7"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsx src/cli.ts",
+    "test": "pnpm build && vitest run src",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/readme.md

@@ -0,0 +1,59 @@
+# cyberfleet
+
+[![npm version](https://img.shields.io/npm/v/cyberfleet.svg)](https://www.npmjs.com/package/cyberfleet)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+The fleet layer on top of [cyberlegion](../cyberlegion). It carries only fleet-specific logic — ships, missions, and the Council view — derived from SDD state. The mechanism verbs (register, send, inbox, spawn, prune, …) are **not** re-exposed here; run those directly through the `cyberlegion` CLI it depends upon.
+
+## Usage
+
+No install required — run with `npx`:
+
+```sh
+npx cyberfleet <command>
+```
+
+Or pin to an exact version:
+
+```sh
+npx cyberfleet@0.1.0 <command>
+```
+
+## Commands
+
+```sh
+# Report ship (a spawned unit worktree) vs command-center, and the shared fleet root
+npx cyberfleet mode
+
+# Who needs the Council's hands — ships × mission × gate × leash, derived from SDD state
+npx cyberfleet missions
+npx cyberfleet missions --agents-root <path>
+
+# Select/focus a ship's session (tmux pane), or print its worktree path to cd into
+npx cyberfleet jump <peer>
+
+# Pause a ship's mission — a cyberfleet-level status marker only (NOT the SDD pause-mission checkpoint)
+npx cyberfleet pause <peer>
+
+# SDD gate operations
+npx cyberfleet gate approve <cr> <gateName>   # Council ratification — STUBBED, not safely relayable via CLI
+```
+
+`<peer>` accepts a handle, id, or worktree branch / CR ref.
+
+## Global options
+
+| Option              | Description                                                        |
+|---------------------|-------------------------------------------------------------------|
+| `--root <path>`     | cyberlegion hub root (overrides the global hub / `$CYBERLEGION_ROOT`) |
+| `--space <path>`    | Alias for `--root`                                                 |
+| `--format <format>` | Output format: `toon` (default) or `json`                         |
+
+## Notes
+
+- **`pause` is not a mission checkpoint.** It only flips a ship's `AgentRecord.status`. To checkpoint an actual mission (rewrite the plan brief's todos / `## NEXT` anchor), run `sdd:pause-mission` in-session.
+- **`gate approve` is stubbed.** Human-attributed Council ratification cannot be safely relayed through this CLI.
+
+## License
+
+MIT

package/dist/spawn-C036T1Ob.mjs

@@ -1,193 +0,0 @@
-import { a as ensureFleetMarker, c as gitWorktreeAdapter, i as saveAgent, l as resolvePrimaryRoot, n as realExec, o as paths, r as resolveSelfId, s as assertDistinctFromPrimary, t as randomId } from "./cli.mjs";
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-//#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) but is unverified against a live binary.
-*/
-const herdrSessionAdapter = {
-	name: "herdr",
-	open(exec, opts) {
-		const id = exec("herdr", [
-			"pane",
-			"split",
-			"--current",
-			"--direction",
-			"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) ?? "";
-	},
-	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", [
-			"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) ?? "";
-	},
-	teardown(exec, target) {
-		exec("tmux", [
-			"kill-pane",
-			"-t",
-			target.id
-		]);
-	}
-};
-//#endregion
-//#region src/console/index.ts
-/** Backend selection: `$TMUX` → tmux, `$HERDR_ENV` → herdr, else a clear error. */
-function selectSessionAdapter(env) {
-	if (env.TMUX) return tmuxSessionAdapter;
-	if (env.HERDR_ENV) return herdrSessionAdapter;
-	throw new Error("spawn requires a session backend — run inside tmux ($TMUX) or herdr ($HERDR_ENV=1)");
-}
-//#endregion
-//#region src/spawn.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 ship (ADR-0022 decision 8): create a real git
-* worktree distinct from the primary checkout (the flagship rule), open a session backend (tmux
-* or herdr — decision 9) 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.
-*/
-function spawn(ctx, input) {
-	ensureFleetMarker(ctx.root);
-	const env = ctx.env ?? process.env;
-	const exec = ctx.exec ?? realExec;
-	const sessionAdapter = selectSessionAdapter(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>");
-	const id = randomId();
-	const primaryRoot = resolvePrimaryRoot(exec);
-	const branch = input.branch ?? `cyberfleet/ship-${id}`;
-	const worktreePath = input.worktreePath ?? paths.worktreeDir(ctx.root, id);
-	const worktree = gitWorktreeAdapter.add(exec, {
-		primaryRoot,
-		path: worktreePath,
-		branch
-	});
-	assertDistinctFromPrimary(worktree.root, primaryRoot);
-	ensureFleetMarker(join(worktree.root, ".cyberfleet"));
-	const launch = LAUNCH_MAP[harness];
-	const target = sessionAdapter.open(exec, {
-		cwd: worktree.root,
-		launch
-	});
-	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.root, id),
-		...resolveSelfId(ctx) ? { spawnedBy: resolveSelfId(ctx) } : {}
-	};
-	saveAgent(ctx.root, rec);
-	writeText(paths.paneFile(ctx.root, target.id), id);
-	writeText(paths.briefFile(ctx.root, id), brief);
-	return {
-		agent: rec,
-		pane: target.id,
-		launch
-	};
-}
-/** 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;
-}
-function writeText(file, text) {
-	mkdirSync(dirname(file), { recursive: true });
-	writeFileSync(file, text);
-}
-//#endregion
-export { spawn };