cyberfleet 0.0.0

package/bin/cyberfleet.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const dir = dirname(fileURLToPath(import.meta.url))
+await import(join(dir, '..', 'dist', 'cli.mjs'))

package/dist/cli.mjs

@@ -0,0 +1,1155 @@
+#!/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
+//#region src/sdd/hal.ts
+/**
+* Infer whether a CR's persisted gate lines show a self-assertion the run-level leash did not
+* cover.
+*
+* Truth table (leash × any self-asserted `by: "agent"` gate):
+*
+* | leash        | spec gate by:agent | impl gate by:agent | aboveLeash |
+* |--------------|---------------------|----------------------|------------|
+* | auto-none    | —                   | —                    | false      |
+* | auto-none    | yes                 | —                    | **true**   |
+* | auto-none    | —                   | yes                  | **true**   |
+* | auto-spec    | yes                 | —                    | false      |
+* | auto-spec    | —                   | yes                  | **true**   |
+* | auto-all     | yes                 | yes                  | false      |
+* | (no leash line recorded) | —/yes    | —/yes                | false (cannot infer) |
+*
+* `auto-none` covers no gate, so ANY self-assert is above leash. `auto-spec` covers only the spec
+* gate, so a self-asserted impl gate is above leash (a spec-gate self-assert is within). `auto-all`
+* covers both, so self-assertion is never above leash. With no leash line at all there is nothing
+* to compare against — this returns false rather than guessing (an unearned HAL flash would be
+* worse than a missed one, per the ADR's "rare, earned signal" framing).
+*/
+function inferHal(ledger) {
+	if (!ledger.leash) return false;
+	const specSelfAsserted = ledger.gates.spec?.by === "agent";
+	const implSelfAsserted = ledger.gates.impl?.by === "agent";
+	switch (ledger.leash.leash) {
+		case "auto-none": return specSelfAsserted || implSelfAsserted;
+		case "auto-spec": return implSelfAsserted;
+		case "auto-all": return false;
+		default: return false;
+	}
+}
+/**
+* "Who needs the Council's hands" (ADR-0022 decision 10) — true when any of:
+*   - a gate line's verdict is `"pause"` (the conductor stopped and is waiting), or
+*   - the CR's combat log has a `halt` line (a mid-flight stop, not at a gate), or
+*   - any gate line is still self-asserted (`by: "agent"`) — provisional, awaiting a human's
+*     ratification into the ledger (the relayed-ratification seam — see `gate approve`).
+*/
+function computeNeedsCouncil(ledger, hasHaltLine) {
+	if (hasHaltLine) return true;
+	for (const gate of [ledger.gates.spec, ledger.gates.impl]) {
+		if (!gate) continue;
+		if (gate.verdict === "pause") return true;
+		if (gate.by === "agent") return true;
+	}
+	return false;
+}
+//#endregion
+//#region src/sdd/read.ts
+/**
+* Locate every project's ledger sibling dir under the three SDD spec conventions this reader
+* supports: `.agents/specs/<project>/` (multi-project) and `.agents/spec/` (single-project, named
+* `"repo"`). Never throws; an absent `.agents/specs` or `.agents/spec` simply contributes nothing.
+*/
+function discoverProjectLedgerLocations(agentsRoot) {
+	const out = [];
+	const specsDir = join(agentsRoot, ".agents", "specs");
+	if (existsSync(specsDir)) try {
+		for (const e of readdirSync(specsDir, { withFileTypes: true })) if (e.isDirectory()) out.push({
+			project: e.name,
+			dir: join(specsDir, e.name)
+		});
+	} catch {}
+	const singleDir = join(agentsRoot, ".agents", "spec");
+	if (existsSync(singleDir)) out.push({
+		project: "repo",
+		dir: singleDir
+	});
+	return out;
+}
+function parseJsonlFile(file, project) {
+	let text;
+	try {
+		text = readFileSync(file, "utf8");
+	} catch {
+		return [];
+	}
+	const lines = [];
+	for (const raw of text.split("\n")) {
+		const s = raw.trim();
+		if (!s) continue;
+		try {
+			lines.push({
+				project,
+				...JSON.parse(s)
+			});
+		} catch {}
+	}
+	return lines;
+}
+/**
+* Glob every ledger line across every discovered project: `<project>/ledger/*.jsonl` (ADR-0020
+* shards, sorted for stable but not authoritative-across-shards order) plus each project's
+* legacy single-file `<project>/ledger.jsonl` (pre-shard corpora, ADR-0020's tolerated legacy
+* form). Never throws.
+*/
+function readAllLedgerLines(agentsRoot) {
+	const out = [];
+	for (const { project, dir } of discoverProjectLedgerLocations(agentsRoot)) {
+		const legacy = join(dir, "ledger.jsonl");
+		if (existsSync(legacy)) out.push(...parseJsonlFile(legacy, project));
+		const shardsDir = join(dir, "ledger");
+		if (!existsSync(shardsDir)) continue;
+		let files = [];
+		try {
+			files = readdirSync(shardsDir).filter((f) => f.endsWith(".jsonl"));
+		} catch {
+			files = [];
+		}
+		for (const f of files.sort()) out.push(...parseJsonlFile(join(shardsDir, f), project));
+	}
+	return out;
+}
+/** Read the latest `gate`/`leash` ledger lines for one CR ref across every discovered project. */
+function readLedgerState(agentsRoot, cr) {
+	const lines = readAllLedgerLines(agentsRoot).filter((l) => l.cr === cr);
+	const gates = {
+		spec: null,
+		impl: null
+	};
+	let leash = null;
+	let project = null;
+	for (const l of lines) {
+		project ??= l.project;
+		if (l.kind === "gate" && (l.gate === "spec" || l.gate === "impl") && l.verdict && l.by) gates[l.gate] = {
+			gate: l.gate,
+			verdict: l.verdict,
+			by: l.by
+		};
+		else if (l.kind === "leash" && l.leash && l.by) leash = {
+			leash: l.leash,
+			by: l.by
+		};
+	}
+	return {
+		project,
+		gates,
+		leash
+	};
+}
+/**
+* True when the CR's combat log (`.agents/plans/<cr>.log.jsonl`, sibling to its plan brief) has
+* any `halt` line — a mid-flight stop not at a gate (see combat-log-governance). The combat log
+* may be absent even for a real mission (not every mission writes one); absence is not an error.
+*/
+function hasHalt(agentsRoot, cr) {
+	const file = join(agentsRoot, ".agents", "plans", `${cr}.log.jsonl`);
+	if (!existsSync(file)) return false;
+	let text;
+	try {
+		text = readFileSync(file, "utf8");
+	} catch {
+		return false;
+	}
+	for (const raw of text.split("\n")) {
+		const s = raw.trim();
+		if (!s) continue;
+		try {
+			if (JSON.parse(s).kind === "halt") return true;
+		} catch {}
+	}
+	return false;
+}
+/** The first content line of the `## NEXT` resume anchor, or '' when there is none. */
+function nextLead(text) {
+	const lines = text.split("\n");
+	const i = lines.findIndex((l) => /^##\s+NEXT\b/i.test(l.trim()));
+	if (i === -1) return "";
+	for (let j = i + 1; j < lines.length; j++) {
+		const l = lines[j].replace(/\r$/, "").trim();
+		if (l === "") continue;
+		if (l.startsWith("#")) return "";
+		return l.replace(/^[-*]\s+/, "").replace(/\*\*/g, "").trim();
+	}
+	return "";
+}
+function unquote(v) {
+	return v.replace(/^["']|["']$/g, "");
+}
+/**
+* Parse `.agents/plans/<cr>.plan.md`'s frontmatter (dispatch `status` + the `todos:` tally) plus
+* its `## NEXT` lead line. Returns null when the plan brief is absent or has no frontmatter block
+* (mirrors discover-plans.mts: a `*.plan.md` with no frontmatter is a stray, not a brief).
+*/
+function readPlanBrief(agentsRoot, cr) {
+	const file = join(agentsRoot, ".agents", "plans", `${cr}.plan.md`);
+	if (!existsSync(file)) return null;
+	let text;
+	try {
+		text = readFileSync(file, "utf8");
+	} catch {
+		return null;
+	}
+	const m = /^---\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)/.exec(text);
+	if (!m) return null;
+	let status = "active";
+	let total = 0;
+	let completed = 0;
+	let inTodos = false;
+	for (const raw of m[1].split("\n")) {
+		const line = raw.replace(/\r$/, "");
+		if (line.trim() === "" || line.trim().startsWith("#")) continue;
+		const indent = line.length - line.trimStart().length;
+		const trimmed = line.trim();
+		if (indent === 0) {
+			inTodos = false;
+			const [key, ...rest] = trimmed.split(":");
+			const value = unquote(rest.join(":").trim());
+			if (key === "status" && value !== "") status = value;
+			else if (key === "todos") inTodos = true;
+			continue;
+		}
+		if (inTodos) {
+			const sm = /^(?:-\s+)?status:\s*(.+)$/.exec(trimmed);
+			if (sm) {
+				total++;
+				if (unquote(sm[1].trim()) === "completed") completed++;
+			}
+		}
+	}
+	return {
+		status,
+		total,
+		completed,
+		next: nextLead(text)
+	};
+}
+/**
+* Parse one project's `spec.md` frontmatter `status` only (never the body). Tries the multi-
+* project convention (`.agents/specs/<project>/spec.md`) first, falling back to the single-
+* project convention (`.agents/spec/spec.md`, used when `project` is `"repo"` or unresolved).
+* Returns null when neither exists or the frontmatter has no `status`.
+*/
+function readSpecStatus(agentsRoot, project) {
+	const candidates = project === "repo" ? [join(agentsRoot, ".agents", "spec", "spec.md")] : [join(agentsRoot, ".agents", "specs", project, "spec.md")];
+	for (const file of candidates) {
+		if (!existsSync(file)) continue;
+		let text;
+		try {
+			text = readFileSync(file, "utf8");
+		} catch {
+			continue;
+		}
+		const m = /^---\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)/.exec(text);
+		if (!m) continue;
+		for (const raw of m[1].split("\n")) {
+			const line = raw.replace(/\r$/, "");
+			if (line.length - line.trimStart().length !== 0) continue;
+			const [key, ...rest] = line.trim().split(":");
+			if (key === "status") {
+				const value = unquote(rest.join(":").trim());
+				return value === "" ? null : value;
+			}
+		}
+	}
+	return null;
+}
+//#endregion
+//#region src/missions.ts
+/**
+* Resolve the root under which `.agents/` lives — the primary checkout (so `missions` sees the
+* whole fleet's SDD state regardless of which ship's worktree it is invoked from), falling back to
+* this project root when not inside a git repository at all.
+*/
+function resolveAgentsRoot(exec, cwd) {
+	try {
+		return resolvePrimaryRoot(exec);
+	} catch {
+		return projectRoot(cwd);
+	}
+}
+/**
+* Derive one ship's mission row. The ship↔CR join key is `AgentRecord.worktree.branch` — this
+* repo's convention is that a ship's worktree branch equals the `<cr-ref>` its plan brief and
+* ledger shards are filed under (e.g. branch `add-fleet-comms` ↔ `add-fleet-comms.plan.md` ↔
+* ledger shard prefix `add-fleet-comms.*`). A ship with no worktree/branch (not yet spawned into
+* one, or standalone) joins to nothing — every SDD-derived field is null, never thrown.
+*/
+function buildMissionRow(agentsRoot, agent) {
+	const branch = agent.worktree?.branch ?? null;
+	const base = {
+		handle: agent.handle,
+		id: agent.id,
+		worktreeRoot: agent.worktree?.root ?? null,
+		branch,
+		status: agent.status
+	};
+	if (!branch) return {
+		...base,
+		cr: null,
+		mission: null,
+		spec: null,
+		gate: {
+			spec: null,
+			impl: null
+		},
+		leash: null,
+		needsCouncil: false,
+		hal: false
+	};
+	const cr = branch;
+	const ledger = readLedgerState(agentsRoot, cr);
+	const plan = readPlanBrief(agentsRoot, cr);
+	const specStatus = ledger.project ? readSpecStatus(agentsRoot, ledger.project) : null;
+	const halt = hasHalt(agentsRoot, cr);
+	return {
+		...base,
+		cr,
+		mission: plan ? {
+			status: plan.status,
+			completed: plan.completed,
+			total: plan.total,
+			next: plan.next
+		} : null,
+		spec: specStatus ? { status: specStatus } : null,
+		gate: {
+			spec: ledger.gates.spec ? {
+				verdict: ledger.gates.spec.verdict,
+				by: ledger.gates.spec.by
+			} : null,
+			impl: ledger.gates.impl ? {
+				verdict: ledger.gates.impl.verdict,
+				by: ledger.gates.impl.by
+			} : null
+		},
+		leash: ledger.leash?.leash ?? null,
+		needsCouncil: computeNeedsCouncil(ledger, halt),
+		hal: inferHal(ledger)
+	};
+}
+/** Derive the mission row set for every ship in the fleet registry. */
+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"];
+/**
+* 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.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")
+	} };
+}
+//#endregion
+//#region src/cli.ts
+function ctxOf(opts) {
+	return {
+		root: 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;
+}
+const rootOpts = (cmd) => cmd.option("--root <path>", "transport root (.cyberfleet dir)").option("--space <path>", "alias for --root");
+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) => {
+	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
+	});
+	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");
+	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
+	});
+});
+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
+		});
+		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
+	});
+	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");
+});
+rootOpts(program.command("gate").description("SDD gate operations").command("approve")).description("Council ratification of a gate — STUBBED, not safely relayable through this CLI (see note)").argument("<cr>", "CR ref").argument("<gateName>", "spec | impl").action((cr, gateName, _opts) => {
+	if (gateName !== "spec" && gateName !== "impl") throw new Error("<gateName> must be spec | impl");
+	const wouldWrite = {
+		kind: "gate",
+		cr,
+		gate: gateName,
+		verdict: "approve",
+		by: process.env.SDD_HANDLE ?? realExec("git", ["config", "user.name"]) ?? realExec("git", [
+			"log",
+			"-1",
+			"--format=%an"
+		]) ?? "<unknown>"
+	};
+	process.stderr.write(`cyberfleet gate approve is NOT implemented — a human ratification into the SDD ledger cannot be safely relayed through this CLI without running in-session with the SDD schema in force (the relayed-ratification seam). It would have written:
+  ${JSON.stringify(wouldWrite)}\nRatify this gate via the SDD spec-gate skill, in-session, instead. Flagging for the Council.
+`);
+	process.exitCode = 1;
+});
+program.parseAsync(process.argv).catch((err) => {
+	process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+	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 };

package/dist/spawn-C036T1Ob.mjs

@@ -0,0 +1,193 @@
+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 };

package/package.json

@@ -0,0 +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
+	}
+}