@iowarp/clio-coder 0.4.9 → 0.5.0

package/src/cli/uninstall.ts

@@ -6,10 +6,10 @@ import { delimiter, dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { resolvePackageRoot } from "../core/package-root.js";
 import { resetXdgCache, resolveClioDirs } from "../core/xdg.js";
 import { detectInstallMethod } from "../domains/lifecycle/install-method.js";
+import { GUI_UNINSTALL_ADVICE, prepareGuiUninstall } from "./gui.js";
 import { createLifecyclePresenter, type LifecycleItem, measurePath, shortenPath } from "./lifecycle-presenter.js";
 import { type RemovalFailure, removePath, reportRemovalFailures } from "./removal.js";
 import { printError } from "./shared.js";
-import { prepareWebUninstall } from "./web.js";
 
 const HELP = `clio-coder uninstall [--remove-binary] [--keep-config] [--keep-data] [--dry-run] [--force] [--json]
 
@@ -19,7 +19,7 @@ Per-project \`.clio-coder/\` directories sit outside those roots and are never
 removed here. Every project Clio has run in is recorded in the session metadata,
 so the real run and --dry-run both list them and name the command that clears one.
 Shell startup files are reported, never edited.
-Owned web background services are stopped and disabled before their state is
+Owned graphical background services are stopped and disabled before their state is
 removed; their desktop launchers are removed using the app's ownership manifests.
 
 Flags:
@@ -334,13 +334,13 @@ export async function runUninstallCommand(argv: ReadonlyArray<string>): Promise<
 	const linkSize = measurePath(linkPath);
 	const launcher = classifyLauncher(linkPath);
 	const shellEdits = detectShellRcEdits();
-	let web: Awaited<ReturnType<typeof prepareWebUninstall>>;
+	let web: Awaited<ReturnType<typeof prepareGuiUninstall>>;
 	try {
 		const desktopPrefix =
 			process.env.XDG_DATA_HOME && isAbsolute(process.env.XDG_DATA_HOME)
 				? process.env.XDG_DATA_HOME
 				: join(homedir(), ".local/share");
-		web = await prepareWebUninstall({ stateDir: dirs.state, desktopPrefix });
+		web = await prepareGuiUninstall({ stateDir: dirs.state, desktopPrefix });
 	} catch (error) {
 		presenter.fail(error instanceof Error ? error.message : "Web installation ownership could not be checked.");
 		presenter.finish();
@@ -388,6 +388,15 @@ export async function runUninstallCommand(argv: ReadonlyArray<string>): Promise<
 		},
 	];
 	for (const item of web.items) items.push({ ...item, status: "remove", detail: "verified app ownership" });
+	for (const item of web.unmanaged)
+		items.push({ ...item, status: "skip", detail: "this build has no graphical application to remove it with" });
+	// The background service reads its configuration from state/gui. Deleting that would strand the
+	// service with nothing left to uninstall it by, so state/gui stays whenever anything is unmanaged.
+	const keepGuiState = web.unmanaged.length > 0 && existsSync(join(dirs.state, "gui"));
+	if (keepGuiState) {
+		const state = items.find((item) => item.label === "State");
+		if (state) state.detail = "sessions, audit, receipts; gui is kept";
+	}
 
 	// A login file is reported, never edited; see detectShellRcEdits.
 	for (const file of shellEdits) {
@@ -395,6 +404,12 @@ export async function runUninstallCommand(argv: ReadonlyArray<string>): Promise<
 	}
 
 	presenter.listItems("The following will be removed", items);
+	if (web.unmanaged.length > 0) {
+		presenter.warn(
+			`Graphical application files stay in place${keepGuiState ? `, with ${shortenPath(join(dirs.state, "gui"))}` : ""}`,
+		);
+		presenter.commandAdvice(GUI_UNINSTALL_ADVICE.lead, GUI_UNINSTALL_ADVICE.command);
+	}
 
 	const projectInv = projectContextInventory(dirs.state);
 	if (projectInv.dirs.length > 0) {
@@ -434,7 +449,7 @@ export async function runUninstallCommand(argv: ReadonlyArray<string>): Promise<
 		for (const item of web.items) presenter.completedStep(`Removed ${item.label}`);
 	} catch (error) {
 		presenter.fail(
-			error instanceof Error ? error.message : "Could not stop the web installation; Clio state was preserved.",
+			error instanceof Error ? error.message : "Could not stop the graphical installation; Clio state was preserved.",
 		);
 		presenter.finish();
 		return 1;
@@ -459,9 +474,14 @@ export async function runUninstallCommand(argv: ReadonlyArray<string>): Promise<
 	}
 
 	if (stateSize.exists) {
-		const failure = removePath("state", dirs.state, false);
-		if (failure) failures.push(failure);
-		else presenter.completedStep("Removed State");
+		const targets = keepGuiState
+			? readdirSync(dirs.state)
+					.filter((name) => name !== "gui")
+					.map((name) => join(dirs.state, name))
+			: [dirs.state];
+		const failed = targets.flatMap((path) => removePath("state", path, false) ?? []);
+		failures.push(...failed);
+		if (!failed.length) presenter.completedStep(keepGuiState ? "Removed State, except gui" : "Removed State");
 	}
 
 	// Only a symlink into this installation is ever unlinked. Reporting the

package/src/cli/usage.ts

@@ -746,7 +746,7 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 		process.stdout.write(
 			indent(
 				formatColumns([
-					["session", "uncached prefill", "hot/partial/cold/small"],
+					["session", "uncached prefill", "hot/partial/cold/small/unknown"],
 					...cacheSessions.map((session) => [
 						session.sessionId,
 						session.promptCache.uncachedPrefillTokens === null ? "n/a" : String(session.promptCache.uncachedPrefillTokens),
@@ -755,6 +755,7 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 							session.promptCache.verdictCounts.partial,
 							session.promptCache.verdictCounts.cold,
 							session.promptCache.verdictCounts.small,
+							session.promptCache.verdictCounts.unknown,
 						].join("/"),
 					]),
 				]),

package/src/cli/workspace-check.ts

@@ -0,0 +1,71 @@
+import { realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { sanitizeCallTargetText } from "../domains/safety/call-target.js";
+import { canSelect, promptSelect } from "./select.js";
+
+export type WorkspaceConcern = "home" | "system" | null;
+
+/** Inputs are canonical paths so a symlink cannot hide a broad workspace. */
+export function workspaceConcern(cwd: string, home: string): WorkspaceConcern {
+	if (cwd === home || ["/home", "/Users"].includes(path.dirname(cwd)) || cwd === "/root") return "home";
+	const under = (root: string) => cwd === root || cwd.startsWith(`${root}${path.sep}`);
+	if ([path.parse(cwd).root, "/home", "/Users", "/tmp", "/var/tmp", "/opt", "/srv", "/mnt", "/media"].includes(cwd))
+		return "system";
+	if (["/var/tmp", "/var/folders", "/usr/local/src"].some(under)) return null;
+	return [
+		"/etc",
+		"/usr",
+		"/bin",
+		"/sbin",
+		"/lib",
+		"/lib64",
+		"/boot",
+		"/dev",
+		"/proc",
+		"/sys",
+		"/run",
+		"/var",
+		"/System",
+		"/Library",
+	].some(under)
+		? "system"
+		: null;
+}
+
+/** Runs before project configuration, hooks, or the interactive shell load. */
+export async function confirmStartupWorkspace(cwd = process.cwd()): Promise<boolean> {
+	const canonical = realpathSync(cwd);
+	const concern = workspaceConcern(canonical, realpathSync(homedir()));
+	if (concern === null) return true;
+	const heading = [
+		"",
+		"Open this workspace?",
+		"",
+		`  ${sanitizeCallTargetText(canonical)}`,
+		"",
+		concern === "home"
+			? "This is your home folder. It includes personal files and application settings."
+			: "This is a system or shared folder. Changes here can affect more than one project.",
+		"Clio can read files and, depending on permissions, edit files and run commands.",
+		"Open a project folder instead if you did not intend this scope.",
+		"",
+	];
+	if (!canSelect()) {
+		process.stderr.write(
+			`${heading.join("\n")}\nStart from a project folder or use a terminal to confirm this workspace.\n`,
+		);
+		return false;
+	}
+	const result = await promptSelect({
+		heading,
+		choices: [
+			{ value: false, label: "No, exit" },
+			{ value: true, label: "Yes, open this folder" },
+		],
+		initialIndex: 0,
+		backLabel: "cancel",
+		clearOnExit: true,
+	});
+	return result.kind === "selected" && result.value;
+}

package/src/core/bash-exec.ts

@@ -202,6 +202,9 @@ function buildToolEnv(source: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEn
 	for (const key of Object.keys(env))
 		if (isSecretArgKey(key) || key.startsWith("BASH_FUNC_")) Reflect.deleteProperty(env, key);
 	env.AI_AGENT = AI_AGENT_NAME;
+	// An inherited CDPATH sends a relative cd somewhere the command does not
+	// name, and bash admission resolves cds from the command's text alone.
+	Reflect.deleteProperty(env, "CDPATH");
 	for (const key of CLIO_CONTROL_ENV_KEYS) {
 		Reflect.deleteProperty(env, key);
 	}
@@ -212,7 +215,7 @@ function buildToolEnv(source: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEn
 // re-reads /etc/profile and the user's profile chain on EVERY call (~10ms on
 // a lean profile, hundreds of ms with nvm/conda in it). The profile exists to
 // shape the environment, so capture that environment once per process and
-// spawn every subsequent command as a plain `bash -c` with the snapshot. Each
+// spawn every subsequent command as `bash -o pipefail -c` with the snapshot. Each
 // call still gets a fresh shell — only the env composition is cached, so
 // there is no state bleed and cancellation semantics are untouched. When the
 // capture fails (profile error, timeout, no PATH), every call falls back to
@@ -298,7 +301,10 @@ export async function runBashCommand(command: string, options: RunBashCommandOpt
 		let pendingClose: (() => void) | null = null;
 		const output = createBashOutputProgressController(options.onUpdate);
 
-		const child = spawn("/bin/bash", [plan.mode, command], {
+		// Preserve an upstream failure through output filters such as tail, so
+		// verification receipts cannot report success merely because the filter
+		// succeeded. A caller can explicitly opt out with `set +o pipefail`.
+		const child = spawn("/bin/bash", ["-o", "pipefail", plan.mode, command], {
 			...(options.cwd === undefined ? {} : { cwd: options.cwd }),
 			env: attribution.env,
 			detached: process.platform !== "win32",

package/src/core/bus-events.ts

@@ -83,8 +83,24 @@ export const BusChannels = {
 
 export type BusChannel = (typeof BusChannels)[keyof typeof BusChannels];
 
+/**
+ * Every collision, capacity, or stress category a {@link RuntimeNoticePayload}
+ * can carry. Each member must have a declared producer (see
+ * declareRuntimeNoticeProducer in src/engine/apis/residency.ts), which a
+ * contract test enforces so no kind outlives the code that emits it.
+ */
+export const RUNTIME_NOTICE_KINDS = [
+	"will-not-fit",
+	"about-to-evict",
+	"swap",
+	"co-resident",
+	"stress",
+	"degraded",
+	"route-fallback",
+] as const;
+
 /** Collision, capacity, or stress category for a {@link RuntimeNoticePayload}. */
-export type RuntimeNoticeKind = "will-not-fit" | "about-to-evict" | "swap" | "co-resident" | "stress" | "degraded";
+export type RuntimeNoticeKind = (typeof RUNTIME_NOTICE_KINDS)[number];
 
 /**
  * Model-residency notice published on {@link BusChannels.RuntimeNotice} by the
@@ -96,7 +112,9 @@ export type RuntimeNoticeKind = "will-not-fit" | "about-to-evict" | "swap" | "co
  * carrying the same content the turn fails with, instead of a bare SDK error.
  * `degraded` reports a live turn whose token rate collapsed (see
  * src/engine/apis/degraded-inference.ts), which is how a silent spill to CPU
- * becomes visible while it is happening.
+ * becomes visible while it is happening. `route-fallback` reports a background
+ * step, such as a memory step, served by the chat target because its own
+ * route was unavailable.
  */
 export interface RuntimeNoticePayload {
 	kind: RuntimeNoticeKind;
@@ -108,6 +126,17 @@ export interface RuntimeNoticePayload {
 	detail?: Record<string, number | string | boolean>;
 }
 
+declare const declaredRuntimeNotice: unique symbol;
+
+/**
+ * A {@link RuntimeNoticePayload} minted by an emitter from
+ * declareRuntimeNoticeProducer (src/engine/apis/residency.ts). The brand exists
+ * only in the type system and is the payload type of
+ * {@link BusChannels.RuntimeNotice}, so a raw notice emitted on the bus outside
+ * a declared producer fails to typecheck.
+ */
+export type DeclaredRuntimeNotice = RuntimeNoticePayload & { readonly [declaredRuntimeNotice]: true };
+
 /**
  * One completed proactive-memory model step, published on
  * {@link BusChannels.MemoryStepCompleted}. It carries the endpoint the step
@@ -849,7 +878,7 @@ export type BusPayloadMap = {
 	[BusChannels.LoopBlocked]: LoopBlockedPayload;
 	[BusChannels.ToolBudgetExceeded]: ToolBudgetExceededPayload;
 	[BusChannels.ProviderHealth]: ProviderHealthPayload;
-	[BusChannels.RuntimeNotice]: RuntimeNoticePayload;
+	[BusChannels.RuntimeNotice]: DeclaredRuntimeNotice;
 	[BusChannels.ResidencyMutation]: ResidencyMutationPayload;
 	[BusChannels.DispatchScopeNotice]: DispatchScopeNoticePayload;
 	[BusChannels.DispatchEnqueued]: DispatchEnqueuedPayload;

package/src/core/cache-telemetry.ts

@@ -1,5 +1,5 @@
 /** Cache classification for one backend completion call. */
-export type BackendCacheVerdict = "hot" | "partial" | "cold" | "small";
+export type BackendCacheVerdict = "hot" | "partial" | "cold" | "small" | "unknown";
 
 /** Backend timing source that directly reports local prefill work. */
 export type BackendTimingsSource = "llamacpp-timings" | "lmstudio-timings";
@@ -20,10 +20,11 @@ export interface CacheVerdictCounts {
 	partial: number;
 	cold: number;
 	small: number;
+	unknown: number;
 }
 
 export function emptyCacheVerdictCounts(): CacheVerdictCounts {
-	return { hot: 0, partial: 0, cold: 0, small: 0 };
+	return { hot: 0, partial: 0, cold: 0, small: 0, unknown: 0 };
 }
 
 /** Return newly evaluated prefill tokens when the backend reports cache reads. */

package/src/core/compile-cache.ts

@@ -36,7 +36,7 @@
  */
 
 import { existsSync } from "node:fs";
-import { enableCompileCache } from "node:module";
+import { enableCompileCache, flushCompileCache } from "node:module";
 import { join } from "node:path";
 import { resolveClioDirs } from "./xdg.js";
 
@@ -157,3 +157,13 @@ export function deleteInjectedCompileCacheFrom(env: NodeJS.ProcessEnv): void {
 	}
 	Reflect.deleteProperty(env, INJECTED_COMPILE_CACHE_ENV);
 }
+
+/** Publish compiled modules while the parent is alive, before a worker needs them. */
+export function publishClioCompileCache(): void {
+	if (processCompileCache.directory() === null) return;
+	try {
+		flushCompileCache();
+	} catch {
+		// Bytecode reuse is optional; never change dispatch or shutdown behavior.
+	}
+}

package/src/core/config.ts

@@ -13,7 +13,7 @@
  */
 
 import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { isAbsolute, join } from "node:path";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
 import {
 	ACTIVE_AGENT_AUTOMATION_ROLES,
@@ -596,6 +596,7 @@ function validateTarget(issues: Issues, path: string, value: unknown): ClioSetti
 		"cache",
 		"lmstudio",
 		"litellm",
+		"ollama",
 		"maxConcurrentRequests",
 	]);
 	const id = "id" in value ? expectString(issues, `${path}.id`, value.id) : undefined;
@@ -662,8 +663,13 @@ function validateTarget(issues: Issues, path: string, value: unknown): ClioSetti
 				if (!isPlainObject(binding)) issues.add(bindingPath, "expected a map");
 				else {
 					issues.unknownKeys(bindingPath, binding, ["backend", "controlUrl", "model", "build", "gatewayDeploymentId"]);
-					const backend = expectEnum(issues, `${bindingPath}.backend`, binding.backend, ["llamacpp", "vllm"] as const);
+					const backend = expectEnum(issues, `${bindingPath}.backend`, binding.backend, [
+						"llamacpp",
+						"vllm",
+						"lmstudio",
+					] as const);
 					for (const key of ["controlUrl", "model", "build"] as const) {
+						if (key === "build" && backend === "lmstudio" && binding[key] === undefined) continue;
 						if (typeof binding[key] !== "string" || !binding[key].trim())
 							issues.add(`${bindingPath}.${key}`, "expected a nonempty string");
 					}
@@ -685,13 +691,13 @@ function validateTarget(issues: Issues, path: string, value: unknown): ClioSetti
 						backend &&
 						typeof binding.controlUrl === "string" &&
 						typeof binding.model === "string" &&
-						typeof binding.build === "string"
+						(typeof binding.build === "string" || backend === "lmstudio")
 					) {
 						target.cache.deployment = {
 							backend,
 							controlUrl: binding.controlUrl,
 							model: binding.model,
-							build: binding.build,
+							...(typeof binding.build === "string" ? { build: binding.build } : {}),
 							...(typeof binding.gatewayDeploymentId === "string" ? { gatewayDeploymentId: binding.gatewayDeploymentId } : {}),
 						};
 					}
@@ -700,8 +706,17 @@ function validateTarget(issues: Issues, path: string, value: unknown): ClioSetti
 			if ("warm" in value.cache) {
 				if (!isPlainObject(value.cache.warm)) issues.add(`${path}.cache.warm`, "expected a map");
 				else {
-					issues.unknownKeys(`${path}.cache.warm`, value.cache.warm, ["maxInputTokens", "maxDurationMs", "cooldownMs"]);
+					issues.unknownKeys(`${path}.cache.warm`, value.cache.warm, [
+						"startup",
+						"maxInputTokens",
+						"maxDurationMs",
+						"cooldownMs",
+					]);
 					target.cache.warm = {};
+					if ("startup" in value.cache.warm) {
+						const startup = expectBoolean(issues, `${path}.cache.warm.startup`, value.cache.warm.startup);
+						if (startup !== undefined) target.cache.warm.startup = startup;
+					}
 					for (const key of ["maxInputTokens", "maxDurationMs", "cooldownMs"] as const) {
 						const bound = value.cache.warm[key];
 						if (bound === undefined) continue;
@@ -721,6 +736,19 @@ function validateTarget(issues: Issues, path: string, value: unknown): ClioSetti
 		const v = validateLiteLLMSettings(issues, `${path}.litellm`, value.litellm);
 		if (v !== undefined) target.litellm = v;
 	}
+	if ("ollama" in value) {
+		if (!isPlainObject(value.ollama)) {
+			issues.add(`${path}.ollama`, `expected a map, got ${describe(value.ollama)}`);
+		} else {
+			issues.unknownKeys(`${path}.ollama`, value.ollama, ["numCtx"]);
+			const ollama: NonNullable<ClioSettings["targets"][number]["ollama"]> = {};
+			if ("numCtx" in value.ollama) {
+				const parsed = expectInteger(issues, `${path}.ollama.numCtx`, value.ollama.numCtx, { min: 1 });
+				if (parsed !== undefined) ollama.numCtx = parsed;
+			}
+			if (Object.keys(ollama).length > 0) target.ollama = ollama;
+		}
+	}
 	if ("maxConcurrentRequests" in value) {
 		const v = expectInteger(issues, `${path}.maxConcurrentRequests`, value.maxConcurrentRequests, { min: 1 });
 		if (v !== undefined) target.maxConcurrentRequests = v;
@@ -1339,6 +1367,7 @@ export function validateSettings(raw: unknown): SettingsValidationResult {
 				"nodes",
 				"permissions",
 				"concurrency",
+				"worktrees",
 				"retry",
 				"limits",
 				"history",
@@ -1576,12 +1605,35 @@ export function validateSettings(raw: unknown): SettingsValidationResult {
 				if (parsed !== undefined) settings.fleet.concurrency = parsed;
 			}
 		}
+		if ("worktrees" in rawFleet) {
+			const rawWorktrees = rawFleet.worktrees;
+			if (!isPlainObject(rawWorktrees)) {
+				issues.add("fleet.worktrees", `expected a mapping, got ${describe(rawWorktrees)}`);
+			} else {
+				issues.unknownKeys("fleet.worktrees", rawWorktrees, ["root"]);
+				if ("root" in rawWorktrees) {
+					const root = rawWorktrees.root;
+					if (
+						typeof root === "string" &&
+						(root === "auto" || root === "tmpfs" || root === "disk" || (isAbsolute(root) && !root.includes("\0")))
+					) {
+						settings.fleet.worktrees.root = root;
+					} else {
+						issues.add(
+							"fleet.worktrees.root",
+							`expected auto, tmpfs, disk, or an absolute path, got ${describe(rawWorktrees.root)}`,
+						);
+					}
+				}
+			}
+		}
 		for (const [blockName, fields] of [
 			[
 				"retry",
 				[
 					["maxRetries", 0],
 					["routeCooldownMs", 0],
+					["breakerThreshold", 1],
 				],
 			],
 			[
@@ -1804,6 +1856,7 @@ export function validateSettings(raw: unknown): SettingsValidationResult {
 		else {
 			const ui = raw.interface;
 			issues.unknownKeys("interface", ui, [
+				"demo",
 				"outputDetail",
 				"smoothStreaming",
 				"mode",
@@ -1813,7 +1866,7 @@ export function validateSettings(raw: unknown): SettingsValidationResult {
 				"panes",
 				"keybindings",
 			]);
-			for (const key of ["terminalProgress", "desktopNotifications"] as const) {
+			for (const key of ["terminalProgress", "desktopNotifications", "demo"] as const) {
 				if (!(key in ui)) continue;
 				const parsed = expectBoolean(issues, `interface.${key}`, ui[key]);
 				if (parsed !== undefined) (settings.interface as unknown as Record<string, unknown>)[key] = parsed;

package/src/core/defaults.ts

@@ -88,6 +88,8 @@ export interface FleetPermissionsSettings {
 export interface FleetRetrySettings {
 	maxRetries: number;
 	routeCooldownMs: number;
+	/** Consecutive target failures that open a route's breaker; 1 trips on the first. */
+	breakerThreshold: number;
 }
 
 export interface FleetLimitsSettings {
@@ -150,8 +152,8 @@ export type DurableCompactionSettings = Omit<CompactionSettings, "excludeLastTur
  *   - policy: candidate selection rule set.
  *   - target: used/window ratio an applied event batches down to.
  *   - protectLastTurns: recent user turns whose observations are never evicted.
- *   - minEvictableTokens: results below this estimate are never evicted; the
- *     marker would cost more than it saves.
+ *   - minEvictableTokens: protect smaller results from low-yield eviction.
+ *     The engine separately rejects replacements that save no tokens.
  */
 export type WorkingSetPolicyId = "age-horizon" | "structural-v1";
 
@@ -254,6 +256,8 @@ export type FullscreenScrollbar = "hidden" | "auto" | "always";
 export type SmoothStreaming = "off" | "auto" | "on";
 
 export interface InterfaceSettings {
+	/** Interactive project-work guidance and contextual footer tips. */
+	demo: boolean;
 	terminalProgress: boolean;
 	/** Output style: Compact, Standard, or Detailed bounded previews. */
 	outputDetail: OutputStyle;
@@ -299,6 +303,7 @@ export interface ModelSelectorSettings {
 }
 
 export interface ProjectResourcesSettings {
+	/** Admit explicitly imported foreign skills/prompts at either scope; loose compatibility roots stay inactive. */
 	trustProjectImports: boolean;
 }
 
@@ -388,11 +393,21 @@ export interface FleetNodeSettings {
 	residency?: FleetNodeResidency;
 }
 
+export interface FleetWorktreesSettings {
+	/**
+	 * Where a `worktree: true` task's working tree is created, for local
+	 * placement: `disk` (under the project root), `tmpfs`, `auto` (tmpfs when
+	 * one exists and has room), or an absolute path.
+	 */
+	root: string;
+}
+
 export interface FleetSettings extends FleetRouteSettings {
 	nodes: FleetNodeSettings[];
 	adaptiveRouting: AdaptiveRoutingSettings;
 	permissions: FleetPermissionsSettings;
 	concurrency: "auto" | number;
+	worktrees: FleetWorktreesSettings;
 	retry: FleetRetrySettings;
 	limits: FleetLimitsSettings;
 	history: FleetHistorySettings;
@@ -514,8 +529,9 @@ export const DEFAULT_SETTINGS = {
 			mode: "deny" as WorkerPermissionMode,
 			escalation: { timeoutMs: 120000, fallback: "deny" } as WorkerEscalationSettings,
 		},
-		concurrency: 1 as "auto" | number,
-		retry: { maxRetries: 2, routeCooldownMs: 15000 },
+		concurrency: "auto" as "auto" | number,
+		worktrees: { root: "disk" },
+		retry: { maxRetries: 2, routeCooldownMs: 15000, breakerThreshold: 1 },
 		limits: {
 			toolCallsPerRun: GUARDRAIL_DEFAULTS.workerToolCallCap,
 			internalRunTimeoutMs: GUARDRAIL_DEFAULTS.internalDispatchTimeoutMs,
@@ -550,6 +566,7 @@ export const DEFAULT_SETTINGS = {
 		review: { enabled: false } as ReviewSettings,
 	} as SafetySettings,
 	interface: {
+		demo: true,
 		terminalProgress: false,
 		outputDetail: "standard",
 		mode: "regular",
@@ -648,10 +665,13 @@ fleet:
     escalation:
       timeoutMs: 120000
       fallback: deny
-  concurrency: 1
+  concurrency: auto
+  worktrees:
+    root: disk
   retry:
     maxRetries: 2
     routeCooldownMs: 15000
+    breakerThreshold: 1
   limits:
     toolCallsPerRun: 150
     internalRunTimeoutMs: 900000
@@ -690,6 +710,8 @@ safety:
     enabled: false
 
 interface:
+  # Capability guidance during project work; disable for a quiet experience.
+  demo: true
   outputDetail: standard
   smoothStreaming: auto
   mode: regular

package/src/core/diagnostics.ts

@@ -0,0 +1,25 @@
+type DiagnosticSink = (text: string, level: "warning" | "error") => void;
+
+const sinks = new Set<DiagnosticSink>();
+
+export function hasDiagnosticSink(): boolean {
+	return sinks.size > 0;
+}
+
+/** The active terminal owner supplies a renderer; headless processes keep stderr. */
+export function installDiagnosticSink(sink: DiagnosticSink): () => void {
+	sinks.add(sink);
+	return () => {
+		sinks.delete(sink);
+	};
+}
+
+export function writeDiagnostic(text: string, level: "warning" | "error" = "warning"): void {
+	try {
+		const sink = [...sinks].at(-1);
+		if (sink) sink(text, level);
+		else process.stderr.write(text.endsWith("\n") ? text : `${text}\n`);
+	} catch {
+		// Never turn a reporting failure into another diagnostic or a raw TUI write.
+	}
+}

package/src/core/event-bus.ts

@@ -1,4 +1,5 @@
 import type { BusChannel, BusPayloadMap } from "./bus-events.js";
+import { writeDiagnostic } from "./diagnostics.js";
 
 /**
  * Listener invoked by {@link SafeEventBus.emit}.
@@ -40,7 +41,7 @@ type StoredListener = (payload: never) => void | Promise<void>;
 
 function reportListenerError(channel: string, error: unknown): void {
 	const message = error instanceof Error ? (error.stack ?? error.message) : String(error);
-	console.error(`[clio-coder:event-bus] Listener crashed on ${channel}: ${message}`);
+	writeDiagnostic(`[clio-coder:event-bus] Listener crashed on ${channel}: ${message}`, "error");
 }
 
 export function createSafeEventBus(): SafeEventBus {

package/src/core/gateway-routing.ts

@@ -24,22 +24,29 @@ export type GatewayRoutingObservation = LiteLLMGatewayRoutingObservation;
 
 /**
  * Preserve the provider's diagnostic while making Clio's failure policy
- * explicit and actionable. LiteLLM targets deliberately do not enter Clio's
- * transient retry ladder: a named route is an operator choice, not permission
- * to substitute another model behind their back.
+ * explicit and actionable. A dropped client connection before any output can
+ * use the visible retry ladder on the same route. Gateway/backend errors stay
+ * terminal: a named route never authorizes substitution of another model.
  */
 export function liteLLMRouteFailureMessage(
 	errorMessage: string | null | undefined,
 	targetId: string,
 	modelId: string,
+	hasPartialResponse = false,
 ): string {
 	const providerMessage = errorMessage?.trim() || "LiteLLM request failed.";
+	if (!hasPartialResponse && isLiteLLMConnectionFailure(providerMessage)) return providerMessage;
 	const advice =
 		`LiteLLM route '${modelId}' on target '${targetId}' failed. ` +
 		"Clio did not retry or substitute another model; select a different route with /model, then resend.";
 	return providerMessage.includes(advice) ? providerMessage : `${providerMessage}\n\n${advice}`;
 }
 
+/** OpenAI SDK transport failure, distinct from an HTTP gateway/backend error. */
+export function isLiteLLMConnectionFailure(message: string | null | undefined): boolean {
+	return message?.trim() === "Connection error.";
+}
+
 interface HeaderReader {
 	get(name: string): string | null;
 }

package/src/core/git-commit-attribution.ts

@@ -18,6 +18,7 @@ import {
 	type CommitAttributionEvidence,
 	decisionTrailerRefs,
 } from "./commit-attribution.js";
+import { writeDiagnostic } from "./diagnostics.js";
 import { clioStateDir } from "./xdg.js";
 
 /** Effective `attribution.gitCommits` for child-process seams. Internal state, not an operator override. */
@@ -96,7 +97,7 @@ export interface ManagedCommitAttributionEnvironment {
 export function reportCommitAttributionDiagnostic(diagnostic: string | null): void {
 	if (diagnostic === null || reportedDiagnostics.has(diagnostic)) return;
 	reportedDiagnostics.add(diagnostic);
-	process.stderr.write(`[clio-coder:attribution] ${diagnostic}\n`);
+	writeDiagnostic(`[clio-coder:attribution] ${diagnostic}\n`);
 }
 
 export function setGitCommitAttributionEnabled(enabled: boolean): void {