@iowarp/clio-coder 0.4.9 → 0.5.0

package/src/cli/run.ts

@@ -1,8 +1,11 @@
+import { realpathSync } from "node:fs";
+import path from "node:path";
 import { type ClioSettings, readSettings } from "../core/config.js";
 import { loadDomains } from "../core/domain-loader.js";
 import { readFileArgsAsync } from "../core/file-references.js";
 import { withRunOverrides } from "../core/run-overrides.js";
 import { readStrictLayeredSettings } from "../core/settings-layers.js";
+import { getTerminationCoordinator } from "../core/termination.js";
 import { clioDataDir } from "../core/xdg.js";
 import type { AgentsContract } from "../domains/agents/contract.js";
 import { AgentsDomainModule } from "../domains/agents/index.js";
@@ -30,6 +33,7 @@ import { SafetyDomainModule } from "../domains/safety/index.js";
 import { SchedulingDomainModule } from "../domains/scheduling/index.js";
 import { SessionDomainModule } from "../domains/session/index.js";
 import type { ImageContent } from "../engine/types.js";
+import type { HeadlessRunDeadline } from "../entry/boot-options.js";
 import {
 	assistantTextFromEvent,
 	receiptGatewayRoutingLabel,
@@ -44,17 +48,21 @@ import { flushRawStdout, restoreStdout, takeOverStdout } from "./output-guard.js
 import { setupSteerChannel } from "./steer-channel.js";
 
 const USAGE =
-	'usage: clio-coder run [--target <id>] [--model <wireId>] [--thinking <level>] [--autonomy <level>] [--json] [--json-events full|terminal] [--session <id>|--continue] [--agent <recipe-id>] "<task>"\n';
+	'usage: clio-coder run [--cwd <dir>] [--target <id>] [--model <wireId>] [--thinking <level>] [--autonomy <level>] [--json] [--json-events full|terminal] [--session <id>|--continue] [--fail-on-noop] [--timeout <seconds>] [--agent <recipe-id>] "<task>"\n';
 
 const HELP = `clio-coder run [flags] "<task>"
 
 Run one headless main-agent turn. Fleet dispatch is explicit with --agent.
 
 Flags:
+  --cwd <dir>               run as if started in <dir>; applies to --agent too
   --target <id>             one-run main-agent or dispatch target override
   --model <wireId>          one-run model override
   --thinking <level>        one-run thinking level: off|minimal|low|medium|high|xhigh|max
   --autonomy <level>        one-run autonomy: read-only|suggest|auto-edit|full-auto
+  --turn-mode <mode>        main-agent workflow: answer|proposal|change; not an authorization grant
+  --allow-tools <names>     main-agent capability allowlist, comma-separated; none disables all tools
+  --no-delegate            forbid main-agent dispatch for this task and its continuations
   --temperature <N>         one-run sampler override for supported local/OpenAI-compatible runtimes
   --top-p <N>               one-run nucleus sampling override (0..1)
   --top-k <N>               one-run top-k override
@@ -62,12 +70,14 @@ Flags:
   --presence-penalty <N>    one-run presence penalty override
   --frequency-penalty <N>   one-run frequency penalty override
   --repeat-penalty <N>      one-run repeat penalty override
-  --max-context-tokens <N>  one-run context-window override for supported local runtimes
+  --max-context-tokens <N>  cap this run's context budget without enlarging the server window
   --json                    stream JSONL events for the main-agent path; dispatch streams events and receipt JSON
   --json-events <mode>      main-agent JSON stream mode: full|terminal; implies --json
   --steer-channel <path>    read live steering lines from a FIFO or appended regular file
   --session <id>            append this turn to an existing session
   --continue                append this turn to the most recent session for this cwd
+  --fail-on-noop            exit 1 when the main-agent run changed nothing (see below)
+  --timeout <seconds>       wall-clock limit for the whole main-agent run; exit 124 on expiry
   --agent <recipe-id>       dispatch a fleet agent instead of the main agent
   --agent-profile <name>    named fleet profile for dispatch
   --agent-runtime <id>      pick the first fleet profile whose target uses this runtime
@@ -76,6 +86,16 @@ Flags:
   --skill <path>            load one explicit skill for this run, repeatable
   --no-skills               disable skill discovery while still honoring --skill
 
+--cwd enters <dir> before anything reads the working directory: settings
+layers, context files, skills, @file references, the session ledger, and every
+tool path. A run started with --cwd <dir> behaves as if it had been started in
+<dir>, so relative paths in other arguments resolve there too. A directory the
+process cannot enter is a usage error (exit 2) and no model is called.
+CLIO_CODER_HOME, CLIO_CODER_CONFIG_DIR, CLIO_CODER_DATA_DIR,
+CLIO_CODER_STATE_DIR, and CLIO_CODER_CACHE_DIR are not resolved before the
+chdir, so a relative value lands under <dir>. Pass absolute paths in them
+when using --cwd.
+
 A headless turn starts a fresh session unless --session or --continue names one
 to append to. A named session that cannot be resumed fails the run: an answer
 written without the history the caller asked for is worse than no answer. The
@@ -85,12 +105,78 @@ There is no operator in a headless run: permission asks are denied, and the
 ask_user interview tool is not registered. Skills that interview fall back to
 their stated defaults; supply decisions in the task prompt instead.
 
+Every main-agent receipt records blocked calls under safety.blockedAttempts and
+a noop flag. A run is a no-op when a block remains unresolved and no write
+succeeded, or when it ran tools and none succeeded; a run that called no tool
+is not. Only the main agent's own write-class calls count as writes: an
+artifact report, bash, and dispatch work do not. A later successful read or
+command can recover a block of the same action class. Native observation does
+not certify that a blocked execution or write requirement was fulfilled.
+Bookkeeping and reports cannot recover blocks. An unresolved blocked run with no successful write exits 1 with outcome
+"failed" and outcomeDetail "noop".
+A successful limitation call also fails, with outcomeDetail "limitation".
+--fail-on-noop additionally fails runs whose tools all failed without a block.
+The flag applies to the main agent only.
+
+--timeout <seconds> bounds the whole run, boot included. On expiry the run
+starts the same coordinated shutdown a SIGTERM does: the turn is aborted, a
+running bash tool's process group is signalled, and the receipt is sealed with
+outcome "timed_out" before the process exits 124, the code timeout(1) uses. An
+external SIGTERM still seals "canceled" with exit 143. A timeout during boot,
+before the turn starts, exits 124 with no receipt. Main agent only.
+
 A turn that ends by writing an artifact (plan/review/report) has no assistant
 message after it, because writing the artifact is the answer. Text mode prints
 that tool's result line, naming what was written and where; --json carries the
 artifact content itself in the event stream.
 `;
 
+/**
+ * Enter the directory `--cwd` names, the way `acp --cwd` does. Everything a run
+ * resolves against the working directory reads `process.cwd()`: layered
+ * settings, context files, skill discovery, `@file` references, the session
+ * ledger, and every tool path (`src/tools/path-utils.ts`). So the chdir happens
+ * before any of that, and the path is canonicalized first so the receipt and
+ * every later comparison name the same physical directory. Returns null on
+ * success, or the resolved path that could not be entered.
+ */
+function enterRunCwd(value: string): string | null {
+	const resolved = path.resolve(value);
+	try {
+		process.chdir(realpathSync(resolved));
+		return null;
+	} catch {
+		return resolved;
+	}
+}
+
+/** timeout(1)'s status, and the one code-step and the eval runners already use for a timeout. */
+const RUN_TIMEOUT_EXIT_CODE = 124;
+
+/**
+ * Arm `--timeout`. On expiry the timer starts the process's coordinated
+ * shutdown, the path a SIGTERM takes, so the headless drain hook aborts the
+ * turn, bash-exec signals any running tool's process group, and the receipt is
+ * sealed before exit. A shutdown that is already under way (a signal, or the
+ * run settling on its own) owns the exit code, so the timer then does nothing.
+ * The timer is unref'd: it bounds the run and never keeps the process alive.
+ */
+function armRunTimeout(seconds: number): HeadlessRunDeadline {
+	const coordinator = getTerminationCoordinator();
+	let expired = false;
+	const timer = setTimeout(
+		() => {
+			if (coordinator.getPhase() !== "idle") return;
+			expired = true;
+			process.stderr.write(`clio-coder run: --timeout ${seconds}s elapsed; shutting down\n`);
+			void coordinator.shutdown(RUN_TIMEOUT_EXIT_CODE);
+		},
+		Math.ceil(seconds * 1000),
+	);
+	timer.unref();
+	return { seconds, expired: () => expired, settle: () => clearTimeout(timer) };
+}
+
 function hasDispatchOnlyOptions(parsed: RunCliArgs): boolean {
 	return (
 		parsed.agentProfile !== undefined ||
@@ -247,6 +333,12 @@ export async function runClioRun(
 				process.stderr.write(USAGE);
 				return 2;
 			}
+			if (parsed.constraints && parsed.agentId !== undefined) {
+				process.stderr.write(
+					"clio-coder run: --turn-mode, --allow-tools, and --no-delegate apply to the main-agent task\n",
+				);
+				return 2;
+			}
 			if (parsed.sessionId !== undefined && parsed.continueSession) {
 				process.stderr.write("clio-coder run: --session and --continue name different sessions; pass one\n");
 				process.stderr.write(USAGE);
@@ -259,85 +351,121 @@ export async function runClioRun(
 				process.stderr.write(USAGE);
 				return 2;
 			}
-
-			const noSkills = options.noSkills === true || parsed.noSkills === true;
-			const skillPaths = Array.from(new Set([...(options.skillPaths ?? []), ...parsed.skillPaths]));
-			// An explicit --skill path is a contract: a path that is missing or loads
-			// no valid skill fails the run before any model invocation instead of
-			// silently degrading to whatever skills discovery finds.
-			const skillPathErrors = explicitSkillPathErrors(skillPaths);
-			if (skillPathErrors.length > 0) {
-				for (const message of skillPathErrors) {
-					process.stderr.write(`clio-coder run: --skill ${message}\n`);
-				}
+			// A worker's receipt is sealed inside the dispatch domain, where a
+			// failed outcome also feeds retry policy, so the no-op verdict stays a
+			// main-agent contract rather than a flag --agent would silently ignore.
+			if (parsed.failOnNoop && parsed.agentId !== undefined) {
+				process.stderr.write("clio-coder run: --fail-on-noop applies to the main agent, not --agent dispatch\n");
+				process.stderr.write(USAGE);
 				return 2;
 			}
-
-			const assembled = await assemblePrompt(parsed);
-			if (!assembled) return 2;
-
-			if (parsed.agentId === undefined) {
-				// Reject unknown and unsupported interactive commands before boot;
-				// neither has a headless handler that could honor the request.
-				const preflight = await headlessSlashPreflight(assembled.prompt);
-				if (preflight !== null && "refusal" in preflight) {
-					process.stderr.write(`clio-coder run: ${preflight.refusal}\n`);
-					return 2;
-				}
-				if (preflight !== null) {
-					process.stdout.write(`${preflight.display}\n`);
-					return 0;
+			// A worker's receipt is sealed inside the dispatch domain, where a
+			// timeout abort seals "canceled" by design (DispatchContract.abort), so
+			// --timeout is a main-agent contract for now.
+			if (parsed.timeoutSeconds !== undefined && parsed.agentId !== undefined) {
+				process.stderr.write("clio-coder run: --timeout applies to the main agent, not --agent dispatch\n");
+				process.stderr.write(USAGE);
+				return 2;
+			}
+			// Armed before anything that can block (piped stdin, boot, the
+			// provider), so the limit covers the whole run. Every return below
+			// settles it: the CLI sets process.exitCode and lets the event loop
+			// drain, so a timer left armed behind a usage error and any lingering
+			// handle would fire shutdown(124) over that error's exit 2.
+			const deadline = parsed.timeoutSeconds === undefined ? undefined : armRunTimeout(parsed.timeoutSeconds);
+			try {
+				if (parsed.cwd !== undefined) {
+					const unusable = enterRunCwd(parsed.cwd);
+					if (unusable !== null) {
+						process.stderr.write(`clio-coder run: --cwd is not a directory this process can enter: ${unusable}\n`);
+						return 2;
+					}
 				}
-				// An explicit --target override is a one-run target; a missing id is an
-				// operator config error, not an assistant response. Reject it before the
-				// headless turn so the resolver diagnostic never streams to stdout as a
-				// message_end/agent_end assistant turn.
-				if (parsed.target !== undefined && explicitTargetMissing(parsed.target)) {
-					process.stderr.write(`clio-coder run: target '${parsed.target}' not found in settings.targets\n`);
+
+				const noSkills = options.noSkills === true || parsed.noSkills === true;
+				const skillPaths = Array.from(new Set([...(options.skillPaths ?? []), ...parsed.skillPaths]));
+				// An explicit --skill path is a contract: a path that is missing or loads
+				// no valid skill fails the run before any model invocation instead of
+				// silently degrading to whatever skills discovery finds.
+				const skillPathErrors = explicitSkillPathErrors(skillPaths);
+				if (skillPathErrors.length > 0) {
+					for (const message of skillPathErrors) {
+						process.stderr.write(`clio-coder run: --skill ${message}\n`);
+					}
 					return 2;
 				}
-				takeOverStdout();
-				try {
-					const code = await runClioCommand({
-						...(options.apiKey === undefined ? {} : { apiKey: options.apiKey }),
-						...(options.noContextFiles ? { noContextFiles: true } : {}),
-						...(noSkills ? { noSkills: true } : {}),
-						...(skillPaths.length > 0 ? { skillPaths } : {}),
-						headless: {
-							prompt: assembled.prompt,
-							mode: parsed.json ? "json" : "text",
-							jsonEvents: parsed.jsonEvents,
+
+				const assembled = await assemblePrompt(parsed);
+				if (!assembled) return 2;
+
+				if (parsed.agentId === undefined) {
+					// Reject unknown and unsupported interactive commands before boot;
+					// neither has a headless handler that could honor the request.
+					const preflight = await headlessSlashPreflight(assembled.prompt);
+					if (preflight !== null && "refusal" in preflight) {
+						process.stderr.write(`clio-coder run: ${preflight.refusal}\n`);
+						return 2;
+					}
+					if (preflight !== null) {
+						process.stdout.write(`${preflight.display}\n`);
+						return 0;
+					}
+					// An explicit --target override is a one-run target; a missing id is an
+					// operator config error, not an assistant response. Reject it before the
+					// headless turn so the resolver diagnostic never streams to stdout as a
+					// message_end/agent_end assistant turn.
+					if (parsed.target !== undefined && explicitTargetMissing(parsed.target)) {
+						process.stderr.write(`clio-coder run: target '${parsed.target}' not found in settings.targets\n`);
+						return 2;
+					}
+					takeOverStdout();
+					try {
+						const code = await runClioCommand({
+							...(options.apiKey === undefined ? {} : { apiKey: options.apiKey }),
+							...(options.noContextFiles ? { noContextFiles: true } : {}),
 							...(noSkills ? { noSkills: true } : {}),
 							...(skillPaths.length > 0 ? { skillPaths } : {}),
-							...(assembled.images && assembled.images.length > 0 ? { images: assembled.images } : {}),
-							...(assembled.workingContextPaths && assembled.workingContextPaths.length > 0
-								? { workingContextPaths: assembled.workingContextPaths }
-								: {}),
-							...(parsed.target !== undefined ? { target: parsed.target } : {}),
-							...(parsed.model !== undefined ? { model: parsed.model } : {}),
-							...(parsed.thinking !== undefined ? { thinking: parsed.thinking } : {}),
-							...(parsed.autonomy !== undefined ? { autonomy: parsed.autonomy } : {}),
-							...(parsed.sampling !== undefined ? { sampling: parsed.sampling } : {}),
-							...(parsed.steerChannel !== undefined ? { steerChannel: parsed.steerChannel } : {}),
-							...(parsed.sessionId !== undefined
-								? { resumeSession: { kind: "id" as const, id: parsed.sessionId } }
-								: parsed.continueSession
-									? { resumeSession: { kind: "latest" as const } }
+							headless: {
+								prompt: assembled.prompt,
+								...(parsed.constraints ? { constraints: parsed.constraints } : {}),
+								mode: parsed.json ? "json" : "text",
+								jsonEvents: parsed.jsonEvents,
+								...(noSkills ? { noSkills: true } : {}),
+								...(skillPaths.length > 0 ? { skillPaths } : {}),
+								...(assembled.images && assembled.images.length > 0 ? { images: assembled.images } : {}),
+								...(assembled.workingContextPaths && assembled.workingContextPaths.length > 0
+									? { workingContextPaths: assembled.workingContextPaths }
 									: {}),
-						},
-					});
-					await flushRawStdout();
-					return code;
-				} finally {
-					restoreStdout();
+								...(parsed.target !== undefined ? { target: parsed.target } : {}),
+								...(parsed.model !== undefined ? { model: parsed.model } : {}),
+								...(parsed.thinking !== undefined ? { thinking: parsed.thinking } : {}),
+								...(parsed.autonomy !== undefined ? { autonomy: parsed.autonomy } : {}),
+								...(parsed.sampling !== undefined ? { sampling: parsed.sampling } : {}),
+								...(parsed.steerChannel !== undefined ? { steerChannel: parsed.steerChannel } : {}),
+								...(parsed.failOnNoop ? { failOnNoop: true } : {}),
+								...(deadline !== undefined ? { deadline } : {}),
+								...(parsed.sessionId !== undefined
+									? { resumeSession: { kind: "id" as const, id: parsed.sessionId } }
+									: parsed.continueSession
+										? { resumeSession: { kind: "latest" as const } }
+										: {}),
+							},
+						});
+						await flushRawStdout();
+						return code;
+					} finally {
+						restoreStdout();
+					}
 				}
-			}
 
-			return await runDispatch(parsed as RunCliArgs & { agentId: string }, assembled.prompt, {
-				...options,
-				noSkills,
-				skillPaths,
-			});
+				return await runDispatch(parsed as RunCliArgs & { agentId: string }, assembled.prompt, {
+					...options,
+					noSkills,
+					skillPaths,
+				});
+			} finally {
+				deadline?.settle();
+			}
 		},
 	);
 }

package/src/cli/skills.ts

@@ -1,6 +1,6 @@
-import { resolve } from "node:path";
+import { isAbsolute, relative, resolve, sep } from "node:path";
 import { readSettings } from "../core/config.js";
-import { loadSkills, modelVisibleSkills, skillCatalogValidity } from "../domains/resources/index.js";
+import { defaultSkillRoots, loadSkills, modelVisibleSkills, skillCatalogValidity } from "../domains/resources/index.js";
 import { formatColumns } from "./shared.js";
 
 /** Runtime discovery is a read surface of the library; package mutations live in library.ts. */
@@ -21,12 +21,30 @@ export function runSkillsRead(args: ReadonlyArray<string>): number {
 			? { disableDiscovery: true, explicitSkillPaths: [resolve(positional[0])] }
 			: { cwd: process.cwd(), trustProjectCompatRoots: readSettings().integrations.projectResources.trustProjectImports },
 	);
+	// Compatibility files remain inspectable with --all, but their diagnostics
+	// do not describe the default inventory of usable Clio skills.
+	const discoveryRoots =
+		command === "validate" || args.includes("--all")
+			? []
+			: defaultSkillRoots()
+					.filter((root) => root.source !== "clio-coder" && root.source !== "plugin")
+					.map((root) => root.path);
+	const diagnostics = list.diagnostics.filter((diagnostic) => {
+		const diagnosticPath = diagnostic.path;
+		return (
+			!diagnosticPath ||
+			!discoveryRoots.some((root) => {
+				const rel = relative(root, diagnosticPath);
+				return rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+			})
+		);
+	});
 	const skills = command === "validate" || args.includes("--all") ? list.items : modelVisibleSkills(list.items);
 	const valid =
-		command === "validate" ? skillCatalogValidity(list).ok : !list.diagnostics.some((diag) => diag.type === "error");
+		command === "validate" ? skillCatalogValidity(list).ok : !diagnostics.some((diag) => diag.type === "error");
 	if (json)
 		process.stdout.write(
-			`${JSON.stringify({ ...(command === "validate" ? { ok: valid } : {}), skills, diagnostics: list.diagnostics }, null, 2)}\n`,
+			`${JSON.stringify({ ...(command === "validate" ? { ok: valid } : {}), skills, diagnostics }, null, 2)}\n`,
 		);
 	else {
 		process.stdout.write(
@@ -36,13 +54,13 @@ export function runSkillsRead(args: ReadonlyArray<string>): number {
 					skill.name,
 					skill.scope,
 					skill.source,
-					skill.trusted ? "trusted" : "untrusted",
-					skill.disableModelInvocation ? "manual" : "model",
+					skill.trusted ? "trusted" : skill.source === "plugin" ? "requires trust" : "import required",
+					!skill.trusted ? "inactive" : skill.disableModelInvocation ? "manual" : "model",
 					skill.description,
 				]),
 			]),
 		);
-		for (const diagnostic of list.diagnostics) process.stderr.write(`${diagnostic.type}: ${diagnostic.message}\n`);
+		for (const diagnostic of diagnostics) process.stderr.write(`${diagnostic.type}: ${diagnostic.message}\n`);
 	}
 	return valid ? 0 : 1;
 }

package/src/cli/targets.ts

@@ -12,6 +12,7 @@ import {
 } from "../core/config.js";
 import { THINKING_LEVELS, type ThinkingLevel } from "../core/defaults.js";
 import { loadDomains } from "../core/domain-loader.js";
+import { warnLegacyNaming } from "../core/naming-compat.js";
 import { ConfigDomainModule } from "../domains/config/index.js";
 import { ensureClioState } from "../domains/lifecycle/index.js";
 import type { ProvidersContract, TargetStatus } from "../domains/providers/contract.js";
@@ -21,7 +22,7 @@ import {
 	isOrchestratorEligibleRuntime,
 	ProvidersDomainModule,
 } from "../domains/providers/index.js";
-import { getRuntimeRegistry } from "../domains/providers/registry.js";
+import { closestRuntimeId, getRuntimeRegistry } from "../domains/providers/registry.js";
 import { registerBuiltinRuntimes } from "../domains/providers/runtimes/builtins.js";
 import type { CapabilityFlags } from "../domains/providers/types/capability-flags.js";
 import type { RuntimeTier } from "../domains/providers/types/runtime-descriptor.js";
@@ -36,9 +37,10 @@ type ProviderOutputTier = RuntimeTier | "unknown";
 const HELP = `clio-coder targets
 
 List and manage configured model targets.
+--reasoning and --tools opt into generating qualification and can load models.
 
 Usage:
-  clio-coder targets [--json] [--probe] [--target <id>]
+  clio-coder targets [--json] [--probe [--reasoning] [--tools [--tools-timeout <seconds>]]] [--target <id>]
   clio-coder targets add [configure flags]
   clio-coder targets use <id> [--model <id>] [--orchestrator-model <id>] [--background-model <id>]
                        [--fleet-target <id>] [--fleet-model <id>]
@@ -79,6 +81,9 @@ function printUsage(usage: string): number {
 interface ListArgs {
 	json: boolean;
 	probe: boolean;
+	reasoning: boolean;
+	tools: boolean;
+	toolsTimeoutMs?: number;
 	target?: string;
 	help: boolean;
 }
@@ -121,7 +126,7 @@ interface ProfileBindArgs {
 const PROFILE_SUBCOMMANDS = new Set(["list", "set", "remove", "rename", "bind", "unbind", "bindings"]);
 
 function parseListArgs(args: ReadonlyArray<string>): ListArgs {
-	const parsed: ListArgs = { json: false, probe: false, help: false };
+	const parsed: ListArgs = { json: false, probe: false, reasoning: false, tools: false, help: false };
 	for (let i = 0; i < args.length; i += 1) {
 		const arg = args[i];
 		if (arg === "--help" || arg === "-h") {
@@ -136,6 +141,23 @@ function parseListArgs(args: ReadonlyArray<string>): ListArgs {
 			parsed.probe = true;
 			continue;
 		}
+		if (arg === "--reasoning") {
+			parsed.reasoning = true;
+			continue;
+		}
+		if (arg === "--tools") {
+			parsed.tools = true;
+			continue;
+		}
+		if (arg === "--tools-timeout") {
+			const value = args[i + 1];
+			const seconds = value === undefined ? Number.NaN : Number(value);
+			if (!Number.isFinite(seconds) || seconds <= 0)
+				throw new Error("--tools-timeout requires a positive number of seconds");
+			parsed.toolsTimeoutMs = Math.round(seconds * 1000);
+			i += 1;
+			continue;
+		}
 		if (arg === "--target") {
 			const value = args[i + 1];
 			if (!value) throw new Error("--target requires a value");
@@ -146,6 +168,9 @@ function parseListArgs(args: ReadonlyArray<string>): ListArgs {
 		if (arg?.startsWith("-")) throw new Error(`unknown flag: ${arg}`);
 		throw new Error(`unknown targets argument: ${arg}`);
 	}
+	if (parsed.reasoning && !parsed.probe) throw new Error("--reasoning requires --probe");
+	if (parsed.tools && !parsed.probe) throw new Error("--tools requires --probe");
+	if (parsed.toolsTimeoutMs !== undefined && !parsed.tools) throw new Error("--tools-timeout requires --tools");
 	return parsed;
 }
 
@@ -186,7 +211,14 @@ export async function runTargetsCommand(args: ReadonlyArray<string>): Promise<nu
 	}
 	if (parsed.probe) {
 		try {
-			await providers.probeAllLive();
+			// Explicit generation is scoped to the named target when supplied.
+			const probeOptions = {
+				reasoning: parsed.reasoning,
+				tools: parsed.tools,
+				...(parsed.toolsTimeoutMs !== undefined ? { toolsTimeoutMs: parsed.toolsTimeoutMs } : {}),
+			};
+			if (parsed.target !== undefined) await providers.probeTarget(parsed.target, probeOptions);
+			else await providers.probeAllLive(probeOptions);
 		} catch (err) {
 			process.stderr.write(`targets: live probe failed: ${err instanceof Error ? err.message : String(err)}\n`);
 		}
@@ -816,9 +848,16 @@ function runConvert(args: ReadonlyArray<string>): number {
 	if (registry.list().length === 0) registerBuiltinRuntimes(registry);
 	const runtime = registry.get(runtimeId);
 	if (!runtime) {
-		printError(`unknown runtime id: ${runtimeId} (run \`clio-coder configure --list\` to see registered runtimes)`);
+		const suggestion = closestRuntimeId(registry, runtimeId);
+		printError(
+			`unknown runtime id: ${runtimeId}${suggestion ? ` (did you mean '${suggestion}'?)` : ""} (run \`clio-coder configure --list\` to see registered runtimes)`,
+		);
 		return 2;
 	}
+	if (runtimeId !== runtime.id) {
+		warnLegacyNaming(runtimeId, runtime.id);
+		runtimeId = runtime.id;
+	}
 	const settings = readSettings();
 	const target = settings.targets.find((entry) => entry.id === id);
 	if (!target) {
@@ -1099,15 +1138,41 @@ function residentModelsSummary(states: TargetStatus["discoveredModelStates"]): s
  */
 function formatContextWindow(
 	status: Pick<TargetStatus, "capabilities" | "contextWindowProvenance"> &
-		Partial<Pick<TargetStatus, "target" | "discoveredModelStates">>,
+		Partial<Pick<TargetStatus, "target" | "discoveredModelStates" | "runtime">>,
 ): string {
 	const window = status.capabilities.contextWindow;
+	const modelState = status.target?.defaultModel
+		? status.discoveredModelStates?.[status.target.defaultModel]
+		: undefined;
+	// A resident model's serving window bounds the session below whatever the
+	// model allows, so both are named: the operator sees which one a run is
+	// planned against and how far the model could be raised (issue #375).
+	const serving = modelState?.contextLength;
+	// A configured `num_ctx` is what every request asks for, so the server
+	// serves that window from the next turn on, capped by the model maximum.
+	const requested = status.target ? status.runtime?.requestedContextWindow?.(status.target) : undefined;
+	if (requested !== undefined) {
+		const known = status.contextWindowProvenance !== "runtime-default";
+		const planned = known ? Math.min(requested, window) : requested;
+		const bounds = ["num_ctx", ...(serving !== undefined && serving !== planned ? [`serving ${serving}`] : [])];
+		if (known && window !== planned) bounds.push(`model max ${window}`);
+		return `ctx ${planned} (${bounds.join("; ")})`;
+	}
+	if (serving !== undefined && serving > 0) {
+		if (status.contextWindowProvenance === "configured" && window < serving) return `ctx ${window} (serving ${serving})`;
+		if (status.contextWindowProvenance === "runtime-default" || window === serving) return `ctx ${serving} (serving)`;
+		return `ctx ${serving} (serving; model max ${window})`;
+	}
 	if (status.contextWindowProvenance === "runtime-default") return `ctx ${window} (unverified runtime default)`;
+	// A model that is not resident loads at a window the server picks, so the
+	// runtime's cold cap is planned against and the maximum is named beside it.
+	const cold = status.runtime?.coldContextWindowCap;
+	if (cold !== undefined && status.contextWindowProvenance !== "configured" && window > cold) {
+		return `ctx ${cold} (cold; model max ${window})`;
+	}
 	// A llama.cpp window that is one slot's share of `--ctx-size` names the
 	// split, so `ctx 196608` is not mistaken for the whole server (issue #187).
-	const slots = status.target?.defaultModel
-		? status.discoveredModelStates?.[status.target.defaultModel]?.contextSlots
-		: undefined;
+	const slots = modelState?.contextSlots;
 	return slots && Math.floor(slots.totalContextSize / slots.slots) === window
 		? `ctx ${window} (${slots.totalContextSize} / ${slots.slots} slots)`
 		: `ctx ${window}`;
@@ -1129,9 +1194,18 @@ function formatNotes(status: TargetStatus): string {
 	const residency = residentModelsSummary(status.discoveredModelStates);
 	if (residency) parts.push(residency);
 	if (status.probeNotes && status.probeNotes.length > 0) parts.push(`note: ${status.probeNotes.join("; ")}`);
+	const tools = formatToolProbe(status.toolProbe);
+	if (tools) parts.push(tools);
 	return parts.join(" ");
 }
 
+function formatToolProbe(probe: TargetStatus["toolProbe"]): string | null {
+	if (!probe) return null;
+	const model = probe.modelId ?? "no model";
+	if (probe.status === "verified") return `tools verified (${model}, ${probe.latencyMs}ms)`;
+	return `tools ${probe.status} (${model}): ${probe.error ?? "unknown error"}`;
+}
+
 function degradedHealthDiagnostic(status: TargetStatus): string | null {
 	return status.health.status === "degraded" && status.health.lastError ? status.health.lastError : null;
 }
@@ -1190,6 +1264,7 @@ interface SerializedStatus {
 	probeModelId?: TargetStatus["probeModelId"];
 	probeNotes?: TargetStatus["probeNotes"];
 	probeSurfaces?: TargetStatus["probeSurfaces"];
+	toolProbe?: TargetStatus["toolProbe"];
 	discoveredModels: TargetStatus["discoveredModels"];
 	discoveredModelLabels?: TargetStatus["discoveredModelLabels"];
 	discoveredModelsSource?: TargetStatus["discoveredModelsSource"];
@@ -1243,5 +1318,8 @@ function serializeStatus(
 	if (status.probeSurfaces !== undefined) {
 		out.probeSurfaces = status.probeSurfaces;
 	}
+	if (status.toolProbe !== undefined) {
+		out.toolProbe = status.toolProbe;
+	}
 	return out;
 }