@iowarp/clio-coder 0.4.5 → 0.4.7

package/src/core/defaults.ts

@@ -219,15 +219,37 @@ export interface RetrySettings {
 	streamStallMs: number;
 }
 
-export type OutputVerbosity = "minimal" | "default" | "verbose";
+export const OUTPUT_STYLES = ["compact", "standard", "detailed"] as const;
+export type OutputStyle = (typeof OUTPUT_STYLES)[number];
+
+/** Read older preferences without rewriting a user's settings on startup. */
+export function normalizeOutputStyle(value: unknown): OutputStyle | undefined {
+	switch (value) {
+		case "minimal":
+		case "compact":
+			return "compact";
+		case "default":
+		case "standard":
+			return "standard";
+		case "verbose":
+		case "detailed":
+			return "detailed";
+		default:
+			return undefined;
+	}
+}
+
+export function nextOutputStyle(style: OutputStyle): OutputStyle {
+	return OUTPUT_STYLES[(OUTPUT_STYLES.indexOf(style) + 1) % OUTPUT_STYLES.length] ?? "standard";
+}
 export type TuiMode = "regular" | "fullscreen";
 export type FullscreenScrollbar = "hidden" | "auto" | "always";
 export type SmoothStreaming = "off" | "auto" | "on";
 
 export interface InterfaceSettings {
 	terminalProgress: boolean;
-	/** Transcript detail: collapsed, balanced, or fully transparent. */
-	outputDetail: OutputVerbosity;
+	/** Output style: Compact, Standard, or Detailed bounded previews. */
+	outputDetail: OutputStyle;
 	/** Regular scrollback-preserving renderer or alternate-screen sticky layout. */
 	mode: TuiMode;
 	/** Fullscreen transcript scrollbar visibility. */
@@ -261,7 +283,7 @@ export interface ReviewSettings {
 }
 
 export interface ModelSelectorSettings {
-	/** Exact target/model refs cycled by Alt+J/Alt+K. */
+	/** Exact target/model refs used by the scoped model cycle actions. */
 	cycleSet: string[];
 	/** Exact target/model refs shown in the focused model picker. */
 	favorites: string[];
@@ -456,7 +478,7 @@ export const DEFAULT_SETTINGS = {
 			recentLimit: 12,
 		} as ModelSelectorSettings,
 		maxOutputTokens: 0,
-		prewarm: true,
+		prewarm: false,
 		retry: {
 			enabled: true,
 			maxRetries: 3,
@@ -484,7 +506,7 @@ export const DEFAULT_SETTINGS = {
 			mode: "deny" as WorkerPermissionMode,
 			escalation: { timeoutMs: 120000, fallback: "deny" } as WorkerEscalationSettings,
 		},
-		concurrency: "auto" as "auto" | number,
+		concurrency: 1 as "auto" | number,
 		retry: { maxRetries: 2, routeCooldownMs: 15000 },
 		limits: {
 			toolCallsPerRun: GUARDRAIL_DEFAULTS.workerToolCallCap,
@@ -521,10 +543,10 @@ export const DEFAULT_SETTINGS = {
 	} as SafetySettings,
 	interface: {
 		terminalProgress: false,
-		outputDetail: "default",
+		outputDetail: "standard",
 		mode: "regular",
 		fullscreenScrollbar: "auto",
-		smoothStreaming: "off",
+		smoothStreaming: "auto",
 		desktopNotifications: false,
 		panes: {
 			enabled: "off",
@@ -591,7 +613,7 @@ chat:
     favorites: []
     recentLimit: 12
   maxOutputTokens: 0
-  prewarm: true
+  prewarm: false
   retry:
     enabled: true
     maxRetries: 3
@@ -617,7 +639,7 @@ fleet:
     escalation:
       timeoutMs: 120000
       fallback: deny
-  concurrency: auto
+  concurrency: 1
   retry:
     maxRetries: 2
     routeCooldownMs: 15000
@@ -659,8 +681,8 @@ safety:
     enabled: false
 
 interface:
-  outputDetail: default
-  smoothStreaming: off
+  outputDetail: standard
+  smoothStreaming: auto
   mode: regular
   fullscreenScrollbar: auto
   terminalProgress: false

package/src/{interactive → core}/external-editor.ts

@@ -3,7 +3,7 @@ import { randomUUID } from "node:crypto";
 import { readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { shellQuote } from "../core/shell-quote.js";
+import { shellQuote } from "./shell-quote.js";
 
 export type ExternalEditorProbe = (candidates: ReadonlyArray<string>) => string | null;
 
@@ -48,11 +48,11 @@ export function resolveExternalEditor(
 	return probe(["nano", "vi"]);
 }
 
-export function editTextExternally(initialText: string, command: string | null): ExternalEditResult {
+export function editTextExternally(initialText: string, command: string | null, extension = ".md"): ExternalEditResult {
 	if (!command) return { ok: false, error: "no external editor configured; set VISUAL or EDITOR" };
-	const tmpFile = join(tmpdir(), `clio-coder-editor-${process.pid}-${randomUUID()}.md`);
+	const tmpFile = join(tmpdir(), `clio-coder-editor-${process.pid}-${randomUUID()}${extension}`);
 	try {
-		writeFileSync(tmpFile, initialText, "utf8");
+		writeFileSync(tmpFile, initialText, { encoding: "utf8", mode: 0o600, flag: "wx" });
 		const result = runEditor(command, tmpFile);
 		if (result.error) return { ok: false, error: result.error.message };
 		if (result.status !== 0) return { ok: false, error: `external editor exited with code ${result.status ?? "?"}` };

package/src/core/recent-models.ts

@@ -3,7 +3,7 @@
  *
  * Recents are runtime state, not user configuration, so they live in the state
  * dir (recent-models.json) and never in settings.yaml. Keeping them out
- * of the settings file means an Alt+L model pick does not rewrite settings.yaml
+ * of the settings file means an Alt+M model pick does not rewrite settings.yaml
  * just to bump a recency list, which would fire the config watcher in every
  * other running session. Favorites (modelSelector.favorites) remain in
  * settings.yaml because they are deliberate user configuration.
@@ -72,7 +72,7 @@ export function rememberRecentModel(ref: string, limit: number): string[] {
 	const next = [ref, ...base.filter((entry) => entry !== ref)].slice(0, max);
 	cache = next;
 	cachePath = path;
-	// An Alt+L model pick in a session outliving `clio-coder uninstall` must not
+	// An Alt+M model pick in a session outliving `clio-coder uninstall` must not
 	// rebuild the state root around recent-models.json. The in-memory list still
 	// updates so the picker behaves for the rest of the run; see stateRootRemoved().
 	if (stateRootRemoved()) return next;

package/src/core/session-routing.ts

@@ -3,7 +3,7 @@
  *
  * Saved settings (settings.yaml) are defaults shared by every Clio process.
  * Live routing for a running session — active orchestrator target/model/
- * thinking, the fleet default used by /run, and the Alt+J / Alt+K scope list —
+ * thinking, the fleet default used by /run, and the configured model-cycle scope list —
  * is owned by the process that is running the session. Each process seeds its
  * routing from saved settings at boot and afterwards reads everything through
  * an effective view: the shared snapshot (targets, theme, safety, retry, …)
@@ -279,7 +279,7 @@ const ROUTING_FIELD_LABELS: ReadonlyArray<{
 	},
 	{
 		field: "chat.modelPicker.cycleSet",
-		label: "Alt+J/Alt+K cycle set",
+		label: "Scoped model cycle set",
 		read: (s) => s.chat.modelPicker.cycleSet.join(","),
 	},
 ];
@@ -317,7 +317,7 @@ export interface RoutingChangeNotice {
  * moves settings.yaml underneath it. One helper feeds every surface — the TUI
  * notification center and the ACP session ledger — so the wording cannot
  * drift. `commandHints` appends the interactive remedies (/settings, /model,
- * Alt+L), which only make sense where a user can type slash commands.
+ * Alt+M), which only make sense where a user can type slash commands.
  */
 export function routingChangeNotices(
 	changedPaths: ReadonlyArray<string>,

package/src/core/state-file-lock.ts

@@ -118,7 +118,7 @@ function tryAcquire(lockPath: string): boolean {
 
 function timeoutError(lockPath: string, timeoutMs: number): Error {
 	return new Error(
-		`timed out after ${timeoutMs}ms waiting for ${lockPath} (owner pid=${readLockOwner(lockPath)?.pid ?? "?"}); delete it if no other clio process is running`,
+		`timed out after ${timeoutMs}ms waiting for ${lockPath} (owner pid=${readLockOwner(lockPath)?.pid ?? "?"}); delete it if no other clio-coder process is running`,
 	);
 }
 

package/src/core/tool-names.ts

@@ -67,3 +67,8 @@ export const ALL_TOOL_NAMES: ReadonlyArray<BuiltinToolName> = Object.values(Tool
 export function isBuiltinToolName(name: ToolName): name is BuiltinToolName {
 	return (ALL_TOOL_NAMES as ReadonlyArray<string>).includes(name);
 }
+
+/** Reserved command-capability namespace. Syntax conveys execution class, never availability. */
+export function isHarnessExtensionToolName(name: string): name is DynamicToolName {
+	return name.length <= 64 && /^extension_[a-z0-9][a-z0-9_-]*__[a-z][a-z0-9_]*$/.test(name);
+}

package/src/domains/agents/extension.ts

@@ -12,34 +12,70 @@ export function createAgentsBundle(_context: DomainContext): DomainBundle<Agents
 	let specs: ReadonlyArray<AgentSpec> = [];
 	let diagnostics: ReadonlyArray<AgentRecipeDiagnostic> = [];
 	let revision = 0;
+	let rediscoveryPending = false;
+	let attemptedRecipes: ReadonlyArray<AgentRecipe> | null = null;
 
 	function discover(): void {
+		attemptedRecipes = null;
 		const nextDiagnostics: AgentRecipeDiagnostic[] = [];
 		const merged = discoverAgentRecipes(process.cwd(), nextDiagnostics);
+		attemptedRecipes = merged;
 		const config = _context.getContract<ConfigContract>("config");
 		assertAgentIdNamespace(merged, config?.get()?.integrations.externalAgents?.entries ?? []);
 		recipes = merged;
 		specs = recipes.map(normalizeAgentSpec);
 		diagnostics = nextDiagnostics;
 		revision += 1;
+		rediscoveryPending = false;
 	}
 
 	let unsubscribeExtensionsReload: (() => void) | null = null;
 	const extension: DomainExtension = {
 		async start() {
 			discover();
-			// Recipes are cached at start; extension agent roots come from the
-			// committed extension generation, so a changed generation rediscovers.
-			unsubscribeExtensionsReload = _context.bus.on(BusChannels.ExtensionsReloaded, (payload: unknown) => {
-				if ((payload as { changed?: unknown } | undefined)?.changed !== true) return;
+			// Recipes are cached at start; plugin agent roots come from the
+			// committed plugin generation, so a changed generation rediscovers.
+			const onResourceReload = (payload: unknown) => {
+				if (!rediscoveryPending && (payload as { changed?: unknown } | undefined)?.changed !== true) return;
 				try {
 					discover();
 				} catch (error) {
+					// Snapshot admission may already have revoked packages. Never retain
+					// their cached authority when namespace or filesystem discovery fails.
+					rediscoveryPending = true;
+					recipes = attemptedRecipes ?? recipes.filter((recipe) => recipe.source === "builtin");
+					let conflictingIds = new Set<string>();
+					try {
+						const config = _context.getContract<ConfigContract>("config");
+						conflictingIds = new Set((config?.get()?.integrations.externalAgents?.entries ?? []).map((agent) => agent.id));
+					} catch {
+						// If even current operator configuration is unreadable, no custom
+						// cached recipe has a trustworthy namespace admission decision.
+						recipes = recipes.filter((recipe) => recipe.source === "builtin");
+					}
+					recipes = recipes.filter((recipe) => recipe.source !== "plugin" && !conflictingIds.has(recipe.id));
+					specs = recipes.map(normalizeAgentSpec);
+					diagnostics = [
+						...diagnostics,
+						{
+							source: "project" as const,
+							filepath: process.cwd(),
+							message: `recipe reload failed; package recipes withdrawn until retry: ${error instanceof Error ? error.message : String(error)}`,
+						},
+					].slice(-100);
+					revision += 1;
 					process.stderr.write(
-						`[clio-coder:agents] rediscovery after extension reload failed: ${error instanceof Error ? error.message : String(error)}\n`,
+						`[clio-coder:agents] rediscovery after resource reload failed: ${error instanceof Error ? error.message : String(error)}\n`,
 					);
 				}
-			});
+			};
+			const unsubscribe = [
+				_context.bus.on(BusChannels.ExtensionsReloaded, onResourceReload),
+				_context.bus.on(BusChannels.PluginsReloaded, onResourceReload),
+			];
+			unsubscribeExtensionsReload = () => {
+				for (const stop of unsubscribe) stop();
+			};
 		},
 		async stop() {
 			unsubscribeExtensionsReload?.();

package/src/domains/agents/fleet-commands.ts

@@ -38,7 +38,14 @@ export const FLEET_COMMAND_DEFAULT_TIMEOUT_MS = 600_000;
  */
 export const FLEET_COMMAND_BASE_ENV: ReadonlyArray<string> = ["PATH", "HOME", "LANG", "LC_ALL", "TZ", "TMPDIR"];
 
+export interface FleetCommandArgumentSlot {
+	name: string;
+	maxLength: number;
+}
+
 export interface FleetCommand {
+	/** Operator-owned required positional data slots; omission forbids appended args. */
+	argumentSlots?: ReadonlyArray<FleetCommandArgumentSlot>;
 	id: string;
 	/** argv list, never a shell string: no quoting bugs and no shell injection. */
 	argv: ReadonlyArray<string>;
@@ -59,6 +66,18 @@ export interface FleetCommandRegistry {
 const CommandSchema = Type.Object(
 	{
 		argv: Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }),
+		argumentSlots: Type.Optional(
+			Type.Array(
+				Type.Object(
+					{
+						name: Type.String({ pattern: "^[A-Za-z][A-Za-z0-9_-]{0,63}$" }),
+						maxLength: Type.Integer({ minimum: 1, maximum: 8192 }),
+					},
+					{ additionalProperties: false },
+				),
+				{ minItems: 1, maxItems: 64 },
+			),
+		),
 		cwd: Type.Optional(Type.String({ minLength: 1 })),
 		timeoutMs: Type.Optional(
 			Type.Integer({ minimum: FLEET_COMMAND_MIN_TIMEOUT_MS, maximum: FLEET_COMMAND_MAX_TIMEOUT_MS }),
@@ -114,7 +133,17 @@ export function parseFleetCommands(raw: string, sourcePath: string): FleetComman
 	if (schemaError !== null) throw new Error(`fleet commands ${sourcePath}: ${schemaError}`);
 	const registry = parsed as {
 		version: 1;
-		commands: Record<string, { argv: string[]; cwd?: string; timeoutMs?: number; env?: string[]; description?: string }>;
+		commands: Record<
+			string,
+			{
+				argv: string[];
+				argumentSlots?: FleetCommandArgumentSlot[];
+				cwd?: string;
+				timeoutMs?: number;
+				env?: string[];
+				description?: string;
+			}
+		>;
 	};
 	const commands = new Map<string, FleetCommand>();
 	for (const [id, entry] of Object.entries(registry.commands)) {
@@ -130,9 +159,16 @@ export function parseFleetCommands(raw: string, sourcePath: string): FleetComman
 				throw new Error(`fleet commands ${sourcePath}: command '${id}' env name '${name}' is not a variable name`);
 			}
 		}
+		if (entry.argumentSlots)
+			validateFleetCommandArgs(
+				{ id, argv: entry.argv, cwd: "", timeoutMs: 1000, env: [], description: "", argumentSlots: entry.argumentSlots },
+				entry.argumentSlots.map(() => "{{slot}}"),
+				{ allowTemplates: true },
+			);
 		commands.set(id, {
 			id,
 			argv: [...entry.argv],
+			...(entry.argumentSlots ? { argumentSlots: entry.argumentSlots.map((slot) => ({ ...slot })) } : {}),
 			cwd: entry.cwd === undefined ? "" : checkCwd(id, entry.cwd, sourcePath),
 			timeoutMs: entry.timeoutMs ?? FLEET_COMMAND_DEFAULT_TIMEOUT_MS,
 			env: [...(entry.env ?? [])],
@@ -152,3 +188,58 @@ export function loadFleetCommands(cwd: string): FleetCommandRegistry | null {
 	if (!existsSync(path)) return null;
 	return parseFleetCommands(readFileSync(path, "utf8"), path);
 }
+
+/** Bind authored code-step arguments before plan admission; each stays one argv token. */
+export function resolveFleetCommandArgs(
+	args: ReadonlyArray<string>,
+	vars: Readonly<Record<string, string>> = {},
+): string[] {
+	if (args.length > 64) throw new Error("fleet code args: at most 64 arguments are allowed");
+	return args.map((token) => {
+		const match = /^\{\{\s*([A-Za-z_][A-Za-z0-9_-]*)\s*\}\}$/u.exec(token);
+		if (!match && token.includes("{{")) throw new Error("fleet code args: placeholders must occupy a whole argument");
+		const value = match ? vars[match[1] ?? ""] : token;
+		if (value === undefined) throw new Error(`fleet code args: missing variable ${match?.[1]} (pass --var name=value)`);
+		if (value.includes("\0") || value.length > 8192)
+			throw new Error("fleet code args: invalid NUL or oversized argument");
+		return value;
+	});
+}
+
+/** Enforce operator-declared data slots; contracts cannot append flags or executable code. */
+export function validateFleetCommandArgs(
+	command: FleetCommand,
+	args: ReadonlyArray<string>,
+	options: { allowTemplates?: boolean } = {},
+): void {
+	const slots = command.argumentSlots ?? [];
+	if (
+		slots.length > 64 ||
+		new Set(slots.map((slot) => slot.name)).size !== slots.length ||
+		slots.some(
+			(slot) =>
+				!/^[A-Za-z][A-Za-z0-9_-]{0,63}$/u.test(slot.name) ||
+				!Number.isInteger(slot.maxLength) ||
+				slot.maxLength < 1 ||
+				slot.maxLength > 8192,
+		)
+	) {
+		throw new Error(`fleet command '${command.id}': invalid argumentSlots declaration`);
+	}
+	if (args.length !== slots.length) {
+		throw new Error(
+			`fleet command '${command.id}': expected ${slots.length} declared argument slots, got ${args.length}; the operator must declare argumentSlots in commands.yaml`,
+		);
+	}
+	for (let index = 0; index < slots.length; index++) {
+		const slot = slots[index];
+		const value = args[index];
+		if (!slot || typeof value !== "string") throw new Error(`fleet command '${command.id}': invalid argument`);
+		if (options.allowTemplates && /^\{\{\s*([A-Za-z_][A-Za-z0-9_-]*)\s*\}\}$/u.test(value)) continue;
+		if (value.length === 0 || value.length > slot.maxLength || value.includes("\0") || value.startsWith("-")) {
+			throw new Error(
+				`fleet command '${command.id}': argument '${slot.name}' must be nonempty data of at most ${slot.maxLength} characters, without NUL or a leading dash; fixed flags belong in argv`,
+			);
+		}
+	}
+}

package/src/domains/agents/fleet-contract.ts

@@ -1,3 +1,5 @@
+import { enabledPluginResourceRoots } from "../plugins/index.js";
+import { resolvePackagePathReference, resolvePackageReferences } from "../resources/package-references.js";
 /**
  * Repo-owned fleet contracts (Symphony P5: work policy lives in the repo,
  * versioned and strictly validated).
@@ -16,8 +18,12 @@ import { Type } from "typebox";
 import { Value } from "typebox/value";
 import { resolvePackageRoot } from "../../core/package-root.js";
 import { clioConfigDir } from "../../core/xdg.js";
-import { enabledExtensionResourceRoots } from "../extensions/index.js";
-import { type FleetCommandRegistry, loadFleetCommands } from "./fleet-commands.js";
+import {
+	type FleetCommandRegistry,
+	loadFleetCommands,
+	resolveFleetCommandArgs,
+	validateFleetCommandArgs,
+} from "./fleet-commands.js";
 import { parseFrontmatter } from "./frontmatter.js";
 import { normalizeWriteBoundary, WRITE_BOUNDARY_MAX_ENTRIES } from "./write-boundary.js";
 
@@ -111,6 +117,7 @@ export interface FleetContractCodeStep {
 	kind: "code";
 	id: string;
 	command: string;
+	args?: ReadonlyArray<string>;
 	scope: FleetStepScope;
 	dependencies: ReadonlyArray<string>;
 	commitFrom?: ReadonlyArray<string>;
@@ -119,7 +126,13 @@ export interface FleetContractCodeStep {
 
 /** The verification half of a loop: the question that decides continuation. */
 export type FleetContractLoopCheck =
-	| { kind: "code"; command: string; scope: FleetStepScope; writes?: ReadonlyArray<string> }
+	| {
+			kind: "code";
+			command: string;
+			args?: ReadonlyArray<string>;
+			scope: FleetStepScope;
+			writes?: ReadonlyArray<string>;
+	  }
 	| {
 			kind: "agent";
 			agent: string;
@@ -199,7 +212,7 @@ export interface FleetContract {
 	path: string;
 }
 
-export type FleetContractSource = "builtin" | "extension" | "user" | "project";
+export type FleetContractSource = "builtin" | "plugin" | "user" | "project";
 
 export interface FleetContractListing {
 	name: string;
@@ -291,6 +304,7 @@ function codeStepSchema(version: FleetContractVersion) {
 			kind: Type.Literal("code"),
 			id: Type.String({ minLength: 1 }),
 			command: Type.String({ minLength: 1 }),
+			args: Type.Optional(Type.Array(Type.String({ maxLength: 8192, pattern: "^[^\\u0000]*$" }), { maxItems: 64 })),
 			scope: FleetScopeSchema,
 			dependencies: Type.Array(Type.String({ minLength: 1 })),
 			...(version >= 3 ? { commitFrom: Type.Optional(Type.Array(Type.String({ minLength: 1 }), { minItems: 1 })) } : {}),
@@ -313,6 +327,7 @@ function loopStepSchema(version: FleetContractVersion) {
 					{
 						kind: Type.Literal("code"),
 						command: Type.String({ minLength: 1 }),
+						args: Type.Optional(Type.Array(Type.String({ maxLength: 8192, pattern: "^[^\\u0000]*$" }), { maxItems: 64 })),
 						scope: FleetScopeSchema,
 						...writesSchema(version),
 					},
@@ -412,12 +427,14 @@ type RawStep = {
 	id: string;
 	agent?: string;
 	command?: string;
+	args?: string[];
 	commitFrom?: string[];
 	writes?: string[];
 	maxAttempts?: number;
 	check?: {
 		kind: "code" | "agent" | "gate";
 		command?: string;
+		args?: string[];
 		agent?: string;
 		gate?: string;
 		scope: FleetStepScope;
@@ -488,7 +505,13 @@ function normalizeStep(step: RawStep): FleetContractStep {
 			dependencies: [...step.dependencies],
 			check:
 				check.kind === "code"
-					? { kind: "code", command: check.command ?? "", scope: check.scope, ...normalizedWrites(check.writes) }
+					? {
+							kind: "code",
+							command: check.command ?? "",
+							...(check.args ? { args: [...check.args] } : {}),
+							scope: check.scope,
+							...normalizedWrites(check.writes),
+						}
 					: check.kind === "gate"
 						? { kind: "gate", gate: check.gate ?? "" }
 						: {
@@ -512,6 +535,7 @@ function normalizeStep(step: RawStep): FleetContractStep {
 			kind: "code",
 			id: step.id,
 			command: step.command ?? "",
+			...(step.args ? { args: [...step.args] } : {}),
 			scope: step.scope,
 			dependencies: [...step.dependencies],
 			...(step.commitFrom !== undefined ? { commitFrom: [...step.commitFrom] } : {}),
@@ -901,13 +925,20 @@ export function fleetLoopSteps(contract: FleetContract): FleetContractLoopStep[]
  * check is a code step in every way that matters to the registry, so it is
  * bound to a real command by the same validation.
  */
-export function fleetCodeSteps(contract: FleetContract): Array<{ id: string; command: string }> {
-	const steps: Array<{ id: string; command: string }> = [];
+export function fleetCodeSteps(
+	contract: FleetContract,
+): Array<{ id: string; command: string; args?: ReadonlyArray<string> }> {
+	const steps: Array<{ id: string; command: string; args?: ReadonlyArray<string> }> = [];
 	for (const step of contract.steps) {
-		if (step.kind === "code") steps.push({ id: step.id, command: step.command });
+		if (step.kind === "code")
+			steps.push({ id: step.id, command: step.command, ...(step.args ? { args: step.args } : {}) });
 		else if (step.kind === "gate") steps.push({ id: step.id, command: step.run });
 		else if (step.kind === "loop" && step.check.kind === "code") {
-			steps.push({ id: fleetLoopCheckStepId(step.id, 1), command: step.check.command });
+			steps.push({
+				id: fleetLoopCheckStepId(step.id, 1),
+				command: step.check.command,
+				...(step.check.args ? { args: step.check.args } : {}),
+			});
 		}
 	}
 	return steps;
@@ -945,19 +976,26 @@ export class FleetCommandRegistryMissingError extends Error {
  * failure mode this whole mechanism exists to prevent: a green test phase that
  * never ran a test.
  */
-export function validateFleetCommands(contract: FleetContract, registry: FleetCommandRegistry | null): void {
+export function validateFleetCommands(
+	contract: FleetContract,
+	registry: FleetCommandRegistry | null,
+	vars?: Readonly<Record<string, string>>,
+): void {
 	const codeSteps = fleetCodeSteps(contract);
 	if (codeSteps.length === 0) return;
 	if (registry === null) {
 		throw new FleetCommandRegistryMissingError(contract.path, [...new Set(codeSteps.map((step) => step.command))].sort());
 	}
 	for (const step of codeSteps) {
-		if (!registry.commands.has(step.command)) {
+		const command = registry.commands.get(step.command);
+		if (!command) {
 			const known = [...registry.commands.keys()].sort().join(", ");
 			throw new Error(
 				`fleet contract ${contract.path}: step '${step.id}' names unknown command '${step.command}' (registered: ${known || "none"})`,
 			);
 		}
+		const args = vars === undefined ? (step.args ?? []) : resolveFleetCommandArgs(step.args ?? [], vars);
+		validateFleetCommandArgs(command, args, { allowTemplates: vars === undefined });
 	}
 }
 
@@ -971,21 +1009,48 @@ function builtinFleetsDir(): string {
 	return join(resolvePackageRoot(), "src", "domains", "agents", "fleets");
 }
 
-function fleetSources(cwd: string): ReadonlyArray<{ dir: string; source: FleetContractSource }> {
+export function resolveFleetReferences(
+	contract: FleetContract,
+	source: { source: FleetContractSource; rootPath?: string },
+): FleetContract {
+	if (!source.rootPath) return contract;
+	const context = { rootPath: source.rootPath, plugin: source.source === "plugin" };
+	// Authored text is resolved after schema parsing; paths cannot inject YAML keys.
+	return {
+		...contract,
+		body: resolvePackageReferences(contract.body, context),
+		steps: contract.steps.map((step) => {
+			if (step.kind === "code" && step.args)
+				return { ...step, args: step.args.map((arg) => resolvePackagePathReference(arg, context)) };
+			if (step.kind === "loop" && step.check.kind === "code" && step.check.args)
+				return {
+					...step,
+					check: { ...step.check, args: step.check.args.map((arg) => resolvePackagePathReference(arg, context)) },
+				};
+			return step;
+		}),
+	};
+}
+
+function fleetSources(cwd: string): ReadonlyArray<{ dir: string; source: FleetContractSource; rootPath?: string }> {
 	return [
 		{ dir: builtinFleetsDir(), source: "builtin" },
-		...enabledExtensionResourceRoots("fleets", cwd)
+		...enabledPluginResourceRoots("fleets", cwd)
 			.sort((left, right) => left.source.localeCompare(right.source))
-			.map((root) => ({ dir: root.path, source: "extension" as const })),
+			.map((root) => ({ dir: root.path, rootPath: root.rootPath, source: "plugin" as const })),
 		{ dir: join(clioConfigDir(), "fleets"), source: "user" },
 		{ dir: fleetsDir(cwd), source: "project" },
 	];
 }
 
-function fleetContractPath(cwd: string, name: string): { path: string; source: FleetContractSource } | null {
+function fleetContractPath(
+	cwd: string,
+	name: string,
+): { path: string; source: FleetContractSource; rootPath?: string } | null {
 	for (const source of [...fleetSources(cwd)].reverse()) {
 		const candidate = join(source.dir, `${name}.md`);
-		if (existsSync(candidate)) return { path: candidate, source: source.source };
+		if (existsSync(candidate))
+			return { path: candidate, source: source.source, ...(source.rootPath ? { rootPath: source.rootPath } : {}) };
 	}
 	return null;
 }
@@ -995,7 +1060,7 @@ export function loadFleetContract(cwd: string, name: string): FleetContract {
 	if (located === null) {
 		throw new Error(`fleet contract not found: ${join(fleetsDir(cwd), `${name}.md`)} (and no builtin named '${name}')`);
 	}
-	const contract = parseFleetContract(readFileSync(located.path, "utf8"), located.path);
+	const contract = resolveFleetReferences(parseFleetContract(readFileSync(located.path, "utf8"), located.path), located);
 	validateFleetCommands(contract, loadFleetCommands(cwd));
 	return contract;
 }
@@ -1027,12 +1092,15 @@ export function listFleetContracts(cwd: string): FleetContractListing[] {
 	}
 	const listings = new Map<string, FleetContractListing>();
 	const sources = fleetSources(cwd);
-	for (const { dir, source } of sources) {
+	for (const { dir, source, rootPath } of sources) {
 		for (const file of listDirectory(dir)) {
 			const path = join(dir, file);
 			const name = basename(file, ".md");
 			try {
-				const contract = parseFleetContract(readFileSync(path, "utf8"), path);
+				const contract = resolveFleetReferences(parseFleetContract(readFileSync(path, "utf8"), path), {
+					source,
+					...(rootPath ? { rootPath } : {}),
+				});
 				if (registryError !== null && fleetCodeSteps(contract).length > 0) throw new Error(registryError);
 				validateFleetCommands(contract, registry);
 				listings.set(name, { name, path, source, contract, error: null, needsCommands: null });

package/src/domains/agents/recipe.ts

@@ -131,20 +131,21 @@ export interface AgentRecipe {
 	resultContract: ResultContract;
 	product?: AgentProduct;
 	tags: ReadonlyArray<string>;
-	source: "builtin" | "extension" | "user" | "project";
+	source: "builtin" | "plugin" | "user" | "project";
 	filepath: string;
 	/** Persona prompt body. */
 	body: string;
 }
 
 export interface RecipeSource {
+	rootPath?: string;
 	dir: string;
 	source: AgentRecipe["source"];
-	/** Project root whose extension and skill resources are being discovered. */
+	/** Project root whose package and skill resources are being discovered. */
 	cwd?: string;
-	/** Stable provenance used to correlate resources from one extension. */
+	/** Stable provenance used to correlate resources from one package. */
 	origin?: string;
-	/** The declaring extension's skill root; extension agents may bind only here. */
+	/** The declaring package's skill root; package agents may bind only here. */
 	skillRoot?: string;
 }