cyberlegion 0.4.0 → 0.5.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "cyberlegion",
-	"version": "0.4.0",
+	"version": "0.5.0",
 	"description": "Agent session spawning, messaging, and dispatch — the Legion and its Legate.",
 	"author": {
 		"name": "unional"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "cyberlegion",
-	"version": "0.4.0",
+	"version": "0.5.0",
 	"description": "Agent session spawning, messaging, and dispatch — the Legion and its Legate.",
 	"author": {
 		"name": "unional"

package/.plugin/pins.json

@@ -1,3 +1,3 @@
 {
-	"cyberlegion": "0.3.1"
+	"cyberlegion": "0.5.0"
 }

package/bin/cyberlegion.mjs

@@ -1,7 +1,24 @@
 #!/usr/bin/env node
+import { existsSync, readFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 const dir = dirname(fileURLToPath(import.meta.url))
-const { runCli } = await import(join(dir, '..', 'dist', 'cli.mjs'))
+const cli = join(dir, '..', 'dist', 'cli.mjs')
+
+// A plugin installed from a source checkout carries whatever the checkout carries, and no install
+// step runs after the copy. Without the built CLI, a bare import dies with ERR_MODULE_NOT_FOUND and
+// no way forward; say what is missing and name the exact published version that runs instead.
+if (!existsSync(cli)) {
+	const { version } = JSON.parse(readFileSync(join(dir, '..', 'package.json'), 'utf8'))
+	process.stderr.write(
+		`cyberlegion: the built CLI is missing: ${cli}\n` +
+			'This install has no dist/ — it is a source checkout that was never built.\n' +
+			`Run the published CLI of the same version instead: npx -y cyberlegion@${version}\n` +
+			`Or build it in place: pnpm install && pnpm build (in ${join(dir, '..')})\n`,
+	)
+	process.exit(1)
+}
+
+const { runCli } = await import(cli)
 await runCli()

package/dist/cli.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
-import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { execFileSync } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
@@ -3170,12 +3170,12 @@ function assertDistinctFromPrimary(worktreeRoot, primaryRoot) {
 * Without this a value carrying a space or a quote would split into extra words, or unbalance the
 * line outright.
 */
-function shellQuote$1(value) {
+function shellQuote$2(value) {
 	return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 /** `env K=V …` with a trailing space, ready to prepend to a command line. Values are shell-quoted. */
 function envPrefix(env) {
-	return `env ${Object.entries(env).map(([key, value]) => `${key}=${shellQuote$1(value)}`).join(" ")} `;
+	return `env ${Object.entries(env).map(([key, value]) => `${key}=${shellQuote$2(value)}`).join(" ")} `;
 }
 /**
 * Given the env a route could not carry and the command (if any) that would run in the opened pane,
@@ -5080,119 +5080,6 @@ function sanitizePane(pane) {
 	return pane.replace(/[^A-Za-z0-9_-]/g, "_");
 }
 //#endregion
-//#region src/agentdef/resolve.ts
-function parseAgentDefFile(text) {
-	const m = /^---\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n)?([\s\S]*)$/.exec(text);
-	if (!m) return {
-		fm: {},
-		instructions: text.trim()
-	};
-	const [, block, rest] = m;
-	const fm = {};
-	const lines = block.split("\n");
-	let i = 0;
-	while (i < lines.length) {
-		const line = lines[i].replace(/\r$/, "");
-		if (line.trim() === "" || line.trim().startsWith("#")) {
-			i++;
-			continue;
-		}
-		if (line.length - line.trimStart().length > 0) {
-			i++;
-			continue;
-		}
-		const idx = line.indexOf(":");
-		if (idx === -1) {
-			i++;
-			continue;
-		}
-		const key = line.slice(0, idx).trim();
-		let value = line.slice(idx + 1).trim();
-		i++;
-		if (value === ">" || value === ">-" || value === "|" || value === "|-") {
-			const parts = [];
-			while (i < lines.length) {
-				const l = lines[i].replace(/\r$/, "");
-				if (l.trim() === "") {
-					i++;
-					continue;
-				}
-				if (l.length - l.trimStart().length === 0) break;
-				parts.push(l.trim());
-				i++;
-			}
-			value = parts.join(value.startsWith("|") ? "\n" : " ");
-		}
-		fm[key] = unquote(value);
-	}
-	return {
-		fm,
-		instructions: rest.trim()
-	};
-}
-function unquote(v) {
-	if (v.length >= 2 && (v.startsWith("\"") && v.endsWith("\"") || v.startsWith("'") && v.endsWith("'"))) return v.slice(1, -1);
-	return v;
-}
-function toBool(v) {
-	if (v === void 0) return void 0;
-	if (v === "true") return true;
-	if (v === "false") return false;
-}
-function toAgentDef(path, text, fallbackName) {
-	const { fm, instructions } = parseAgentDefFile(text);
-	return {
-		name: fm.name ?? fallbackName,
-		description: fm.description,
-		model: fm.model,
-		effort: fm.effort,
-		harness: fm.harness,
-		warm: toBool(fm.warm),
-		interactive: toBool(fm.interactive),
-		instructions,
-		path
-	};
-}
-/** The project's own `.agents/agents/` dir — the convention `agent list`/name-search scans. */
-function projectAgentsDir(cwd) {
-	return join(projectRoot(cwd), ".agents", "agents");
-}
-/** Resolve one agent definition, by explicit file or by name search. Throws a clear error when
-* neither locates a def — never returns a partial/empty result. */
-function resolveAgentDef(input) {
-	if (input.file) {
-		const path = resolve(input.file);
-		if (!existsSync(path)) throw new Error(`agent def file "${input.file}" does not exist`);
-		return toAgentDef(path, readFileSync(path, "utf8"), basename(path).replace(/\.md$/, ""));
-	}
-	if (!input.name) throw new Error("resolveAgentDef needs a --agent <name> or --agent-file <path>");
-	const roots = [...input.searchRoots ?? [], projectAgentsDir(input.cwd)];
-	for (const root of roots) {
-		const candidate = join(root, `${input.name}.md`);
-		if (existsSync(candidate)) return toAgentDef(candidate, readFileSync(candidate, "utf8"), input.name);
-	}
-	throw new Error(`no agent definition named "${input.name}" found under .agents/agents/`);
-}
-/** List every resolvable agent def under `.agents/agents/` (+ any extra search roots). Definitive
-* empty array when the dir is absent or empty — never throws for "none found" here (unlike a
-* named resolve, listing is inherently zero-or-more). */
-function listAgentDefs(input = {}) {
-	const roots = [...input.searchRoots ?? [], projectAgentsDir(input.cwd)];
-	const seen = /* @__PURE__ */ new Set();
-	const defs = [];
-	for (const root of roots) {
-		if (!existsSync(root)) continue;
-		for (const file of readdirSync(root)) {
-			if (!file.endsWith(".md")) continue;
-			const path = join(root, file);
-			if (seen.has(path)) continue;
-			seen.add(path);
-			defs.push(toAgentDef(path, readFileSync(path, "utf8"), file.replace(/\.md$/, "")));
-		}
-	}
-	return defs;
-}
-//#endregion
 //#region src/mux-env.ts
 /**
 * Transitional env-normalization seam (mux.feature: "a pane carrying only the legacy fast-path vars
@@ -6005,7 +5892,10 @@ function spawn(ctx, input) {
 	const id = randomId();
 	const primaryRoot = resolvePrimaryRoot(exec);
 	const launch = input.command ?? LAUNCH_MAP[harness];
-	const fullLaunch = `${muxEnvPrefix(sessionAdapter.name)}${launch}`;
+	const launchLine = () => {
+		const shimDir = ctx.self ? writeSelfShim(paths.dataDir(ctx.store.root, id), ctx.self) : void 0;
+		return `${shimDir ? `PATH=${shellQuote$1(shimDir)}:"$PATH" ` : ""}${muxEnvPrefix(sessionAdapter.name)}${launch}`;
+	};
 	const from = callerPane(sessionAdapter, normalizedEnv);
 	let cwd;
 	let worktree;
@@ -6018,7 +5908,7 @@ function spawn(ctx, input) {
 		const at = input.at ?? "tab";
 		target = sessionAdapter.open(exec, {
 			cwd,
-			launch: fullLaunch,
+			launch: launchLine(),
 			at,
 			from,
 			...labelFor(at, input, brief, id)
@@ -6033,7 +5923,7 @@ function spawn(ctx, input) {
 				primaryRoot,
 				branch,
 				path: worktreePath,
-				launch: fullLaunch,
+				launch: launchLine(),
 				...labelFor(at, input, brief, id)
 			});
 			assertDistinctFromPrimary(opened.worktree.root, primaryRoot);
@@ -6053,7 +5943,7 @@ function spawn(ctx, input) {
 			worktree = added;
 			target = sessionAdapter.open(exec, {
 				cwd,
-				launch: fullLaunch,
+				launch: launchLine(),
 				at,
 				from,
 				...labelFor(at, input, brief, id)
@@ -6080,7 +5970,7 @@ function spawn(ctx, input) {
 	};
 	saveAgent(ctx.store, rec);
 	ctx.store.putPaneIndex(target.id, id);
-	ctx.store.writeBrief(id, brief);
+	ctx.store.writeBrief(id, composeBrief(brief, input.briefInstructions));
 	return {
 		agent: rec,
 		pane: target.id,
@@ -6148,6 +6038,37 @@ function muxEnvPrefix(muxName) {
 	return "";
 }
 /**
+* The argv that re-invokes the running CLI exactly: this node binary, its loader flags (tsx under
+* `pnpm cl dev`), and the entry script with symlinks resolved — so an `npx` or `.bin` link reaches
+* the same file it ran from, never whatever the name resolves to later.
+*/
+function selfInvocation() {
+	const entry = process.argv[1];
+	return [
+		process.execPath,
+		...process.execArgv,
+		...entry ? [realpathSync(entry)] : []
+	];
+}
+/**
+* Write `<dataDir>/bin/cyberlegion`, a POSIX shim that execs `self` with the caller's arguments,
+* and return its directory. A spawned session gets that directory first on its PATH, so the
+* `cyberlegion` a brief tells it to run is the install that spawned it: nothing is resolved from
+* the registry or the session's own PATH at report time.
+*/
+function writeSelfShim(dataDir, self) {
+	const dir = join(dataDir, "bin");
+	mkdirSync(dir, { recursive: true });
+	const shim = join(dir, "cyberlegion");
+	writeFileSync(shim, `#!/bin/sh\nexec ${self.map(shellQuote$1).join(" ")} "$@"\n`);
+	chmodSync(shim, 493);
+	return dir;
+}
+/** Single-quote `s` for a POSIX shell, so any path survives word splitting and expansion. */
+function shellQuote$1(s) {
+	return `'${s.replaceAll("'", "'\\''")}'`;
+}
+/**
 * Resolve a unit's live session pane from a ref, or throw naming the ref. The one place
 * focus/nudge/read agree on what "addressable" means — a record's own pane, else a pane pointer
 * keyed by its id (a herdr peer stores its pane only in that index).
@@ -6230,6 +6151,13 @@ function clearUnit(ctx, ref) {
 		command
 	};
 }
+/** The brief file's text: the task alone, or — when the harness took no instructions on its command
+* line — the def's instructions under their own heading ahead of it, so the peer can see they reach
+* it as a user turn rather than a system prompt. */
+function composeBrief(brief, instructions) {
+	if (!instructions) return brief;
+	return `## Agent instructions\n\n${instructions}\n\n## Brief\n\n${brief}`;
+}
 /** Resolve a spawn brief from --brief-file, --task -, or --task <text>; null if no source given. */
 function resolveBrief(input, readStdin = () => readFileSync(0, "utf8")) {
 	if (input.briefFile) return readFileSync(input.briefFile, "utf8");
@@ -6238,69 +6166,251 @@ function resolveBrief(input, readStdin = () => readFileSync(0, "utf8")) {
 	return null;
 }
 //#endregion
+//#region src/agentdef/resolve.ts
+function parseAgentDefFile(text) {
+	const m = /^---\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n)?([\s\S]*)$/.exec(text);
+	if (!m) return {
+		fm: {},
+		instructions: text.trim()
+	};
+	const [, block, rest] = m;
+	const fm = {};
+	const lines = block.split("\n");
+	let i = 0;
+	while (i < lines.length) {
+		const line = lines[i].replace(/\r$/, "");
+		if (line.trim() === "" || line.trim().startsWith("#")) {
+			i++;
+			continue;
+		}
+		if (line.length - line.trimStart().length > 0) {
+			i++;
+			continue;
+		}
+		const idx = line.indexOf(":");
+		if (idx === -1) {
+			i++;
+			continue;
+		}
+		const key = line.slice(0, idx).trim();
+		let value = line.slice(idx + 1).trim();
+		i++;
+		if (value === ">" || value === ">-" || value === "|" || value === "|-") {
+			const parts = [];
+			while (i < lines.length) {
+				const l = lines[i].replace(/\r$/, "");
+				if (l.trim() === "") {
+					i++;
+					continue;
+				}
+				if (l.length - l.trimStart().length === 0) break;
+				parts.push(l.trim());
+				i++;
+			}
+			value = parts.join(value.startsWith("|") ? "\n" : " ");
+		}
+		fm[key] = unquote(value);
+	}
+	return {
+		fm,
+		instructions: rest.trim()
+	};
+}
+function unquote(v) {
+	if (v.length >= 2 && (v.startsWith("\"") && v.endsWith("\"") || v.startsWith("'") && v.endsWith("'"))) return v.slice(1, -1);
+	return v;
+}
+function toBool(v) {
+	if (v === void 0) return void 0;
+	if (v === "true") return true;
+	if (v === "false") return false;
+}
+/** The known harnesses are exactly those with a launch binary — one home for the set. */
+const HARNESSES = Object.keys(LAUNCH_MAP);
+/** A `harness` tag outside the known set has no launch binary, so a typo fails here, loudly, rather
+* than surfacing later as an unlaunchable command. */
+function toHarness(value, path) {
+	if (value === void 0 || HARNESSES.includes(value)) return value;
+	throw new Error(`agent def "${path}" has unknown harness "${value}" — expected one of ${HARNESSES.join(", ")}`);
+}
+function toAgentDef(path, text, fallbackName) {
+	const { fm, instructions } = parseAgentDefFile(text);
+	return {
+		name: fm.name ?? fallbackName,
+		description: fm.description,
+		model: fm.model,
+		effort: fm.effort,
+		harness: toHarness(fm.harness, path),
+		warm: toBool(fm.warm),
+		interactive: toBool(fm.interactive),
+		instructions,
+		path
+	};
+}
+/** The project's own `.agents/agents/` dir — the convention `agent list`/name-search scans. */
+function projectAgentsDir(cwd) {
+	return join(projectRoot(cwd), ".agents", "agents");
+}
+/** Resolve one agent definition, by explicit file or by name search. Throws a clear error when
+* neither locates a def — never returns a partial/empty result. */
+function resolveAgentDef(input) {
+	if (input.file) {
+		const path = resolve(input.file);
+		if (!existsSync(path)) throw new Error(`agent def file "${input.file}" does not exist`);
+		return toAgentDef(path, readFileSync(path, "utf8"), basename(path).replace(/\.md$/, ""));
+	}
+	if (!input.name) throw new Error("resolveAgentDef needs a --agent <name> or --agent-file <path>");
+	const roots = [...input.searchRoots ?? [], projectAgentsDir(input.cwd)];
+	for (const root of roots) {
+		const candidate = join(root, `${input.name}.md`);
+		if (existsSync(candidate)) return toAgentDef(candidate, readFileSync(candidate, "utf8"), input.name);
+	}
+	throw new Error(`no agent definition named "${input.name}" found under .agents/agents/`);
+}
+/** List every resolvable agent def under `.agents/agents/` (+ any extra search roots). Definitive
+* empty array when the dir is absent or empty — never throws for "none found" here (unlike a
+* named resolve, listing is inherently zero-or-more). */
+function listAgentDefs(input = {}) {
+	const roots = [...input.searchRoots ?? [], projectAgentsDir(input.cwd)];
+	const seen = /* @__PURE__ */ new Set();
+	const defs = [];
+	for (const root of roots) {
+		if (!existsSync(root)) continue;
+		for (const file of readdirSync(root)) {
+			if (!file.endsWith(".md")) continue;
+			const path = join(root, file);
+			if (seen.has(path)) continue;
+			seen.add(path);
+			defs.push(toAgentDef(path, readFileSync(path, "utf8"), file.replace(/\.md$/, "")));
+		}
+	}
+	return defs;
+}
+//#endregion
 //#region src/agentdef/realize.ts
 const DEFAULT_HARNESS = "claude";
 /** POSIX single-quote a value for safe inclusion in a shell command line. */
 function shellQuote(value) {
 	return `'${value.replace(/'/g, `'\\''`)}'`;
 }
-/** Build the harness launch invocation for a def — explicit `model`/`harness` win over the def's
-* own tags, which win over the harness default. Every harness gets the same shape (bin,
-* `--model` when known, `--append-system-prompt` carrying the def's instructions body) since the
-* exact per-harness flag surface is realized later by the launching caller, not by cyberlegion. */
+/** Cursor carries effort as a bracket parameter on the model (`<model>[effort=<level>]`): merge it into
+* any bracket list the model already has, replacing an `effort=` already there. */
+function withCursorEffort(model, effort) {
+	const open = model.lastIndexOf("[");
+	if (open === -1 || !model.endsWith("]")) return `${model}[effort=${effort}]`;
+	const params = model.slice(open + 1, -1).split(",").filter((p) => p !== "" && !p.startsWith("effort="));
+	return `${model.slice(0, open)}[${[...params, `effort=${effort}`].join(",")}]`;
+}
+/** The model + effort arguments for one harness. No two harnesses spell effort alike: claude has
+* `--effort`, codex only a config override, cursor only a parameter on the model — so a cursor
+* effort with no model has nowhere to go and throws rather than launching at the default effort. */
+function modelAndEffortArgs(harness, model, effort) {
+	if (harness === "cursor") {
+		if (effort && !model) throw new Error(`cursor carries effort only as a parameter on the model; set a model to launch with effort "${effort}"`);
+		if (!model) return [];
+		return ["--model", shellQuote(effort ? withCursorEffort(model, effort) : model)];
+	}
+	const args = model ? ["--model", shellQuote(model)] : [];
+	if (!effort) return args;
+	if (harness === "codex") return [
+		...args,
+		"-c",
+		shellQuote(`model_reasoning_effort="${effort}"`)
+	];
+	return [
+		...args,
+		"--effort",
+		shellQuote(effort)
+	];
+}
+/** A TOML basic string: JSON's escapes are all legal TOML escapes, and TOML also forbids a raw DEL. */
+function tomlBasicString(value) {
+	return JSON.stringify(value).replace(/\x7f/g, "\\u007f");
+}
+/** The instruction arguments for one harness. Only claude has an append-to-system-prompt flag;
+* codex takes a `developer_instructions` config override, added on top of its own base
+* instructions. Cursor has no channel at all — its instructions go to the brief instead. */
+function instructionArgs(harness, instructions) {
+	if (!instructions || harness === "cursor") return [];
+	if (harness === "claude") return ["--append-system-prompt", shellQuote(instructions)];
+	return ["-c", shellQuote(`developer_instructions=${tomlBasicString(instructions)}`)];
+}
+/** Build the harness launch invocation for a def — explicit `model`/`effort`/`harness` win over the
+* def's own tags, which win over the harness default. The def's effort and instructions each go
+* through the harness's own control (see `modelAndEffortArgs`, `instructionArgs`). */
 function realizeLaunch(def, opts = {}) {
 	const harness = opts.harness ?? def.harness ?? DEFAULT_HARNESS;
 	const model = opts.model ?? def.model;
-	const parts = [LAUNCH_MAP[harness]];
-	if (model) parts.push("--model", shellQuote(model));
-	if (def.instructions) parts.push("--append-system-prompt", shellQuote(def.instructions));
+	const effort = opts.effort ?? def.effort;
+	const parts = [
+		LAUNCH_MAP[harness],
+		...modelAndEffortArgs(harness, model, effort),
+		...instructionArgs(harness, def.instructions)
+	];
+	const briefInstructions = harness === "cursor" && def.instructions ? def.instructions : void 0;
 	return {
 		harness,
-		command: parts.join(" ")
+		command: parts.join(" "),
+		model,
+		effort,
+		...briefInstructions ? { briefInstructions } : {}
 	};
 }
 /**
 * Resolve what `unit spawn` should launch, from either an explicit `--harness` or an agent def
-* (`--agent` / `--agent-file`) whose harness, model and instructions compose the launch command.
-* An explicit `--harness` overrides the def's own.
+* (`--agent` / `--agent-file`) whose harness, model, effort and instructions compose the launch
+* command. An explicit `--harness`/`--model`/`--effort` overrides the def's own, for this launch only.
+* With no def, a `--model`/`--effort` composes a launch from `--harness` alone; with neither, the
+* harness's own default command stands (no `command` returned).
 *
 * Extracted from the CLI action so the def→launch wiring is reachable from a test: composed inline
 * it sat between two well-covered halves (`resolveAgentDef`, `realizeLaunch`) with nothing
 * exercising the join between them.
 */
 function resolveSpawnLaunch(input) {
-	if (!input.agent && !input.agentFile) return { harness: input.harness };
-	const realized = realizeLaunch(resolveAgentDef({
+	const overrides = {
+		harness: input.harness,
+		model: input.model,
+		effort: input.effort
+	};
+	if (!input.agent && !input.agentFile) {
+		if (!input.harness || !input.model && !input.effort) return { harness: input.harness };
+		return realizeLaunch({
+			name: input.harness,
+			instructions: "",
+			path: ""
+		}, overrides);
+	}
+	return realizeLaunch(resolveAgentDef({
 		name: input.agent,
 		file: input.agentFile,
 		...input.cwd ? { cwd: input.cwd } : {},
 		...input.searchRoots ? { searchRoots: input.searchRoots } : {}
-	}), { harness: input.harness });
-	return {
-		harness: realized.harness,
-		command: realized.command
-	};
+	}), overrides);
 }
 //#endregion
 //#region src/cli-input.ts
 /**
 * Translate `unit spawn`'s options into the spawn input and its wake decision — resolving an
 * `--agent`/`--agent-file` def into the harness and composed launch command, with an explicit
-* `--harness` overriding the def's own.
+* `--harness`/`--model`/`--effort` overriding the def's own.
 *
 * Throws when no harness can be resolved, so the CLI's own `fail()` still renders it.
 */
 function spawnCommandInput(opts) {
-	const { harness, command } = resolveSpawnLaunch({
+	const { harness, command, model, effort, briefInstructions } = resolveSpawnLaunch({
 		agent: opts.agent,
 		agentFile: opts.agentFile,
-		harness: opts.harness
+		harness: opts.harness,
+		model: opts.model,
+		effort: opts.effort
 	});
 	if (!harness) throw new Error("unit spawn needs --harness, or --agent/--agent-file resolving one");
 	return {
 		input: {
 			harness,
 			command,
+			briefInstructions,
 			task: opts.task,
 			briefFile: opts.briefFile,
 			handle: opts.handle,
@@ -6309,7 +6419,11 @@ function spawnCommandInput(opts) {
 			cwd: opts.cwd,
 			at: opts.at
 		},
-		noWake: opts.wake === false
+		noWake: opts.wake === false,
+		launched: {
+			model,
+			effort
+		}
 	};
 }
 /** What `unit read` prints: the raw scrape, or the JSON envelope under `--format json`. */
@@ -7506,7 +7620,8 @@ const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.u
 function ctxOf(opts) {
 	return {
 		store: new FileStore(resolveRoot({ space: opts.space })),
-		env: process.env
+		env: process.env,
+		self: selfInvocation()
 	};
 }
 function formatOf(opts) {
@@ -7692,9 +7807,11 @@ withGlobals(unit.command("prune")).description("mark dead units exited and sweep
 		json: changed
 	});
 });
+/** What a model/effort/harness field reads when no source set it and the harness's own default applies. */
+const HARNESS_DEFAULT = "(harness default)";
 /** The launch options `unit spawn` and `service start` share. */
 function withSpawnOptions(cmd) {
-	return withGlobals(cmd).option("--harness <h>", "claude | cursor | codex (required unless --agent/--agent-file resolves one)").option("--agent <name>", "resolve an agent def (.agents/agents/<name>.md) for harness/model/instructions").option("--agent-file <path>", "read an exact agent def file instead of resolving by name").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 worktree (default cyberlegion/unit-<id>)").option("--worktree-path <path>", "where to check out the new worktree").option("--cwd <path>", "spawn the session in an existing directory; create no worktree (mutually exclusive with --branch/--worktree-path)").addOption(new Option("--at <placement>", "where to open the new session (default: new-worktree → workspace, --cwd → tab)").choices([
+	return withGlobals(cmd).option("--harness <h>", "claude | cursor | codex (required unless --agent/--agent-file resolves one)").option("--agent <name>", "resolve an agent def (.agents/agents/<name>.md) for harness/model/effort/instructions").option("--agent-file <path>", "read an exact agent def file instead of resolving by name").option("--model <name>", "model for this launch only (flag > agent def > harness default)").option("--effort <level>", "effort for this launch only (flag > agent def > harness default)").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 worktree (default cyberlegion/unit-<id>)").option("--worktree-path <path>", "where to check out the new worktree").option("--cwd <path>", "spawn the session in an existing directory; create no worktree (mutually exclusive with --branch/--worktree-path)").addOption(new Option("--at <placement>", "where to open the new session (default: new-worktree → workspace, --cwd → tab)").choices([
 		"pane:right",
 		"pane:down",
 		"tab",
@@ -7718,6 +7835,8 @@ function defineSpawn(cmd) {
 				spawned: res.agent.id,
 				handle: res.agent.handle,
 				harness: res.agent.harness,
+				model: spawnInput.launched.model ?? HARNESS_DEFAULT,
+				effort: spawnInput.launched.effort ?? HARNESS_DEFAULT,
 				worktree: res.agent.worktree?.root,
 				pane: res.pane,
 				rung: res.rung
@@ -7726,6 +7845,8 @@ function defineSpawn(cmd) {
 				agent: res.agent,
 				pane: res.pane,
 				launch: res.launch,
+				model: spawnInput.launched.model ?? HARNESS_DEFAULT,
+				effort: spawnInput.launched.effort ?? HARNESS_DEFAULT,
 				rung: res.rung
 			}
 		});
@@ -8207,9 +8328,9 @@ function agentDefFields(d) {
 	return {
 		name: d.name,
 		description: d.description,
-		model: d.model ?? "(harness default)",
+		model: d.model ?? HARNESS_DEFAULT,
 		effort: d.effort,
-		harness: d.harness ?? "(harness default)",
+		harness: d.harness ?? HARNESS_DEFAULT,
 		warm: d.warm ?? false,
 		interactive: d.interactive ?? false,
 		path: d.path

package/dist/index.d.mts

@@ -171,6 +171,10 @@ interface IdContext {
   env?: NodeJS.ProcessEnv;
   exec?: Exec$1;
   now?: () => number;
+  /** The argv that re-invokes this very CLI — node, its loader flags, and the entry script
+   * (`selfInvocation`). `unit spawn` puts a `cyberlegion` shim over it on the new session's PATH,
+   * so a unit reports through the install that spawned it. Absent, spawn writes no shim. */
+  self?: string[];
 }
 declare function loadAgent(store: Store, id: string): AgentRecord | undefined;
 declare function listAgents(store: Store): AgentRecord[];
@@ -243,17 +247,25 @@ declare function listAgentDefs(input?: {
 interface RealizeLaunchOptions {
   /** Overrides def.model when present. */
   model?: string;
+  /** Overrides def.effort when present. */
+  effort?: string;
   /** Overrides def.harness when present; falls back to 'claude' when neither is set. */
   harness?: Harness;
 }
 interface RealizedLaunch {
   harness: Harness;
   command: string;
+  /** The model and effort the command launches with, from whichever source won; absent when the
+   * harness default applies. */
+  model?: string;
+  effort?: string;
+  /** The def's instructions, for a harness whose CLI cannot take them (cursor): `unit spawn` writes
+   * them in front of the brief instead. Absent when the command carries them, or there are none. */
+  briefInstructions?: string;
 }
-/** Build the harness launch invocation for a def — explicit `model`/`harness` win over the def's
- * own tags, which win over the harness default. Every harness gets the same shape (bin,
- * `--model` when known, `--append-system-prompt` carrying the def's instructions body) since the
- * exact per-harness flag surface is realized later by the launching caller, not by cyberlegion. */
+/** Build the harness launch invocation for a def — explicit `model`/`effort`/`harness` win over the
+ * def's own tags, which win over the harness default. The def's effort and instructions each go
+ * through the harness's own control (see `modelAndEffortArgs`, `instructionArgs`). */
 declare function realizeLaunch(def: AgentDef, opts?: RealizeLaunchOptions): RealizedLaunch;
 //#endregion
 //#region src/decommission.d.ts
@@ -621,6 +633,9 @@ interface SpawnInput {
    * (avoids a session.ts ↔ agentdef/realize.ts import cycle, since `realizeLaunch` already reads
    * `LAUNCH_MAP` from here). */
   command?: string;
+  /** A def's instructions its harness cannot take on the command line (an agent-def's
+   * `realizeLaunch` output, for cursor): written in front of the brief under their own heading. */
+  briefInstructions?: string;
   /** Branch to create the unit's worktree on; defaults to `cyberlegion/unit-<id>`. */
   branch?: string;
   /** Where to check out the unit's worktree; defaults to a sibling of the primary checkout