@iowarp/clio-coder 0.4.6 → 0.4.8

package/src/cli/uninstall.ts

@@ -9,6 +9,7 @@ import { detectInstallMethod } from "../domains/lifecycle/install-method.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]
 
@@ -18,6 +19,8 @@ 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
+removed; their desktop launchers are removed using the app's ownership manifests.
 
 Flags:
   --keep-config    preserve the configuration root (settings.yaml, credentials)
@@ -331,6 +334,18 @@ 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>>;
+	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 });
+	} catch (error) {
+		presenter.fail(error instanceof Error ? error.message : "Web installation ownership could not be checked.");
+		presenter.finish();
+		return 1;
+	}
 
 	// The state root's own children (audit, sessions) are inside the State row
 	// and go with it; listing them again as separate removals double-counted the
@@ -372,6 +387,7 @@ export async function runUninstallCommand(argv: ReadonlyArray<string>): Promise<
 			detail: launcherItemDetail(launcher, args.removeBinary),
 		},
 	];
+	for (const item of web.items) items.push({ ...item, status: "remove", detail: "verified app ownership" });
 
 	// A login file is reported, never edited; see detectShellRcEdits.
 	for (const file of shellEdits) {
@@ -413,6 +429,16 @@ export async function runUninstallCommand(argv: ReadonlyArray<string>): Promise<
 	}
 
 	const failures: RemovalFailure[] = [];
+	try {
+		await web.remove();
+		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.",
+		);
+		presenter.finish();
+		return 1;
+	}
 
 	if (cacheSize.exists) {
 		const failure = removePath("cache", dirs.cache, false);

package/src/cli/usage.ts

@@ -85,6 +85,7 @@ interface UsageTotals {
 	output: number;
 	cacheRead: number;
 	cacheWrite: number;
+	cacheWrite1h?: number;
 	reasoningTokens: number;
 	totalTokens: number;
 	costUsd: number;
@@ -169,6 +170,7 @@ function outOfTurnUsageCall(row: OutOfTurnUsageRow): LedgerUsageCall {
 		output: row.usage.output ?? 0,
 		cacheRead: row.usage.cacheRead ?? 0,
 		cacheWrite: row.usage.cacheWrite ?? 0,
+		...(typeof row.usage.cacheWrite1h === "number" ? { cacheWrite1h: row.usage.cacheWrite1h } : {}),
 		reasoningTokens: row.usage.reasoning ?? 0,
 		totalTokens: row.usage.totalTokens ?? 0,
 		costUsd: row.usage.costUsd ?? 0,
@@ -197,6 +199,7 @@ function addUsageCall(totals: UsageTotals, call: LedgerUsageCall): void {
 	totals.output += call.output;
 	totals.cacheRead += call.cacheRead;
 	totals.cacheWrite += call.cacheWrite;
+	if (call.cacheWrite1h !== undefined) totals.cacheWrite1h = (totals.cacheWrite1h ?? 0) + call.cacheWrite1h;
 	totals.reasoningTokens += call.reasoningTokens;
 	totals.totalTokens += call.totalTokens;
 	totals.costUsd += call.costUsd;

package/src/cli/web.ts

@@ -0,0 +1,79 @@
+import { lstatSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { resolvePackageRoot } from "../core/package-root.js";
+import { printError } from "./argv.js";
+
+const HELP = `Clio Coder web application
+
+Usage:
+  clio-coder web [--open] [--port <0-65535>]
+  clio-coder web background install [--open] [--port <1-65535>]
+  clio-coder web background status|start|open|stop|uninstall
+  clio-coder web launcher install|status|uninstall
+
+The foreground server prints a private launch link. --open opens your default
+browser. Press Ctrl+C to stop. --no-open explicitly disables browser opening.
+Optional --idle-exit <milliseconds> stops an idle foreground server.
+Use --path </app/path> to open a particular page. --reuse-background uses this
+installation's background app when configured, or starts a foreground server.
+
+On Linux with a systemd user session, background install keeps the app available
+at login. Open its launch link once, then install it from your browser. Background
+stop stops it now; background uninstall also removes its login and desktop entries.
+Other platforms can run the foreground web app. Your CLI, terminal interface,
+headless runs, and web app use the same Clio runtime and configuration.
+`;
+
+export async function runWebCommand(args: string[]): Promise<number> {
+	if (args.includes("--help") || args.includes("-h")) {
+		process.stdout.write(HELP);
+		return 0;
+	}
+	try {
+		const root = resolvePackageRoot();
+		process.env.CLIO_CODER_PACKAGE_ROOT = root;
+		// A URL keeps this a separate entry; bundling it into the command chunk
+		// would change import.meta.url and the worker/client paths beside it.
+		const server = await import(pathToFileURL(join(root, "dist/web/server.js")).href);
+		await server.main(args);
+		return 0;
+	} catch (error) {
+		printError(error instanceof Error ? error.message : "Could not start the web application.");
+		return 1;
+	}
+}
+
+/** Separate packaged entry; inspection never starts a listener or opens a browser. */
+export async function prepareWebUninstall(options: { stateDir: string; desktopPrefix: string }): Promise<{
+	items: Array<{ label: string; path: string }>;
+	remove(): Promise<void>;
+}> {
+	// Most CLI-only installs have no web lifecycle files. Keep that path lazy,
+	// including checkouts whose optional web bundle has not been built yet.
+	const paths = [
+		join(options.stateDir, "web/background"),
+		join(options.desktopPrefix, "applications/io.iowarp.ClioCoder.desktop"),
+		join(options.desktopPrefix, "applications/io.iowarp.ClioCoder.desktop.owner.json"),
+	];
+	const present = paths.some((path) => {
+		try {
+			lstatSync(path);
+			return true;
+		} catch (error) {
+			if (["ENOENT", "ENOTDIR"].includes((error as NodeJS.ErrnoException).code ?? "")) return false;
+			throw error;
+		}
+	});
+	if (!present)
+		return {
+			items: [],
+			remove: async () => {
+				if ((await prepareWebUninstall(options)).items.length)
+					throw new Error("A web installation appeared during confirmation; run uninstall again.");
+			},
+		};
+	const packageRoot = resolvePackageRoot();
+	const server = await import(pathToFileURL(join(packageRoot, "dist/web/server.js")).href);
+	return server.prepareWebUninstall({ ...options, packageRoot });
+}

package/src/core/bus-events.ts

@@ -64,6 +64,7 @@ export const BusChannels = {
 	CompactionEnd: "compaction.end",
 	MiddlewareHookFailed: "middleware.hookFailed",
 	ExtensionsReloaded: "extensions.reloaded",
+	PluginsReloaded: "plugins.reloaded",
 	ExtensionsLoadIssue: "extensions.loadIssue",
 	ContextActivity: "context.activity",
 	ContextSourcesChanged: "context.sourcesChanged",
@@ -629,6 +630,7 @@ export interface DispatchTerminalStats {
 	outputTokenCount: number;
 	cacheReadTokenCount: number;
 	cacheWriteTokenCount: number;
+	cacheWrite1hTokenCount?: number;
 	reasoningTokenCount: number;
 	staticShellHash: string | null;
 	sessionShellHash: string | null;
@@ -713,10 +715,8 @@ export interface CompactionPayload {
 /**
  * Published on {@link BusChannels.ExtensionsReloaded} by the composition
  * root after a new extension generation and its user-hook registrations
- * have both been committed. Consumers that cache extension-sourced data
- * (prompt fragments, agent recipes, the session prompt) refresh on
- * `changed`; an unchanged generation carries the previous digest and needs
- * no work. Never published between the two commits.
+ * have both been committed. Never published between the two commits.
+ * Recipe and prompt consumers subscribe to PluginsReloaded instead.
  */
 export interface ExtensionsReloadedPayload {
 	generation: number;
@@ -726,6 +726,9 @@ export interface ExtensionsReloadedPayload {
 	digest: string;
 }
 
+/** Data-only plugin generation publication, independent of extension hook generations. */
+export type PluginsReloadedPayload = ExtensionsReloadedPayload;
+
 /** Operator diagnostics for skipped extension or project-hook configuration. */
 export interface ExtensionsLoadIssuePayload {
 	message: string;
@@ -859,6 +862,7 @@ export type BusPayloadMap = {
 	[BusChannels.CompactionEnd]: CompactionPayload;
 	[BusChannels.MiddlewareHookFailed]: MiddlewareHookFailedPayload;
 	[BusChannels.ExtensionsReloaded]: ExtensionsReloadedPayload;
+	[BusChannels.PluginsReloaded]: PluginsReloadedPayload;
 	[BusChannels.ExtensionsLoadIssue]: ExtensionsLoadIssuePayload;
 	[BusChannels.ContextActivity]: ContextActivityPayload;
 	[BusChannels.ContextSourcesChanged]: ContextSourcesChangedPayload;

package/src/core/config.ts

@@ -593,6 +593,7 @@ function validateTarget(issues: Issues, path: string, value: unknown): ClioSetti
 		"lifecycle",
 		"gateway",
 		"pricing",
+		"cache",
 		"lmstudio",
 		"litellm",
 		"maxConcurrentRequests",
@@ -642,6 +643,76 @@ function validateTarget(issues: Issues, path: string, value: unknown): ClioSetti
 		const v = validatePricing(issues, `${path}.pricing`, value.pricing);
 		if (v !== undefined) target.pricing = v;
 	}
+	if ("cache" in value) {
+		if (!isPlainObject(value.cache)) issues.add(`${path}.cache`, "expected a map");
+		else {
+			issues.unknownKeys(`${path}.cache`, value.cache, ["retention", "deployment", "warm"]);
+			target.cache = {};
+			if ("retention" in value.cache) {
+				const retention = expectEnum(issues, `${path}.cache.retention`, value.cache.retention, [
+					"none",
+					"short",
+					"long",
+				] as const);
+				if (retention !== undefined) target.cache.retention = retention;
+			}
+			if ("deployment" in value.cache) {
+				const binding = value.cache.deployment;
+				const bindingPath = `${path}.cache.deployment`;
+				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);
+					for (const key of ["controlUrl", "model", "build"] as const) {
+						if (typeof binding[key] !== "string" || !binding[key].trim())
+							issues.add(`${bindingPath}.${key}`, "expected a nonempty string");
+					}
+					if (typeof binding.controlUrl === "string") {
+						try {
+							const url = new URL(binding.controlUrl);
+							if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.search || url.hash)
+								throw new Error("invalid URL");
+						} catch {
+							issues.add(`${bindingPath}.controlUrl`, "expected an HTTP(S) URL without credentials, query, or fragment");
+						}
+					}
+					if (
+						binding.gatewayDeploymentId !== undefined &&
+						(typeof binding.gatewayDeploymentId !== "string" || !binding.gatewayDeploymentId.trim())
+					)
+						issues.add(`${bindingPath}.gatewayDeploymentId`, "expected a nonempty string");
+					if (
+						backend &&
+						typeof binding.controlUrl === "string" &&
+						typeof binding.model === "string" &&
+						typeof binding.build === "string"
+					) {
+						target.cache.deployment = {
+							backend,
+							controlUrl: binding.controlUrl,
+							model: binding.model,
+							build: binding.build,
+							...(typeof binding.gatewayDeploymentId === "string" ? { gatewayDeploymentId: binding.gatewayDeploymentId } : {}),
+						};
+					}
+				}
+			}
+			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"]);
+					target.cache.warm = {};
+					for (const key of ["maxInputTokens", "maxDurationMs", "cooldownMs"] as const) {
+						const bound = value.cache.warm[key];
+						if (bound === undefined) continue;
+						if (typeof bound !== "number" || !Number.isSafeInteger(bound) || bound < 1)
+							issues.add(`${path}.cache.warm.${key}`, "expected a positive safe integer");
+						else target.cache.warm[key] = bound;
+					}
+				}
+			}
+		}
+	}
 	if ("lmstudio" in value) {
 		const v = validateLmStudioSettings(issues, `${path}.lmstudio`, value.lmstudio);
 		if (v !== undefined) target.lmstudio = v;

package/src/core/defaults.ts

@@ -283,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[];

package/src/core/domain-loader.ts

@@ -78,35 +78,11 @@ export async function loadDomains(
 		},
 	};
 
-	for (const name of order) {
-		const mod = modules.find((m) => m.manifest.name === name);
-		if (!mod) continue;
-		try {
-			const bundle = await mod.createExtension(context);
-			await bundle.extension.start();
-			extensions.set(name, bundle.extension);
-			contracts.set(name, bundle.contract);
-			loaded.push(name);
-			bus.emit(BusChannels.DomainLoaded, { name });
-		} catch (error) {
-			failed.push({ name, error });
-			bus.emit(BusChannels.DomainFailed, { name, error });
-			// The throw below aborts boot; nothing downstream gets a chance to
-			// render the failure, so the structured line must land first.
-			const message = error instanceof Error ? error.message : String(error);
-			(options.diagnostic ?? ((text: string) => process.stderr.write(text)))(
-				`[clio-coder:domain] load failed: ${name}: ${message}\n`,
-			);
-			throw new DomainLoadError(name, error);
-		}
-	}
-
-	const stop = async (): Promise<void> => {
+	const stopAll = async (): Promise<void> => {
 		const debug = process.env.CLIO_CODER_DEBUG_SHUTDOWN === "1";
 		const budgetMs = resolveShutdownHookBudgetMs();
-		for (const name of [...loaded].reverse()) {
-			const ext = extensions.get(name);
-			if (!ext?.stop) continue;
+		for (const [name, ext] of [...extensions].reverse()) {
+			if (!ext.stop) continue;
 			const stopFn = ext.stop.bind(ext);
 			const t0 = debug ? process.hrtime.bigint() : 0n;
 			const completed = await runWithBudget(stopFn, budgetMs, (err) => {
@@ -124,7 +100,34 @@ export async function loadDomains(
 				);
 			}
 		}
+		extensions.clear();
+		contracts.clear();
 	};
+	let stopping: Promise<void> | undefined;
+	const stop = (): Promise<void> => (stopping ??= stopAll());
+
+	for (const name of order) {
+		const mod = modules.find((m) => m.manifest.name === name);
+		if (!mod) continue;
+		try {
+			const bundle = await mod.createExtension(context);
+			// A rejected start may already own listeners or other resources.
+			extensions.set(name, bundle.extension);
+			await bundle.extension.start();
+			contracts.set(name, bundle.contract);
+			loaded.push(name);
+			bus.emit(BusChannels.DomainLoaded, { name });
+		} catch (error) {
+			failed.push({ name, error });
+			bus.emit(BusChannels.DomainFailed, { name, error });
+			await stop();
+			const message = error instanceof Error ? error.message : String(error);
+			(options.diagnostic ?? ((text: string) => process.stderr.write(text)))(
+				`[clio-coder:domain] load failed: ${name}: ${message}\n`,
+			);
+			throw new DomainLoadError(name, error);
+		}
+	}
 
 	const getContract = <T extends DomainContract = DomainContract>(name: string): T | undefined => {
 		return contracts.get(name) as T | undefined;
@@ -134,7 +137,13 @@ export async function loadDomains(
 }
 
 function topoSort(modules: ReadonlyArray<DomainModule>): string[] {
-	const names = new Set(modules.map((m) => m.manifest.name));
+	const names = new Set<string>();
+	for (const { manifest } of modules) {
+		if (names.has(manifest.name)) {
+			throw new DomainLoadError("topo", new Error(`Duplicate domain: ${manifest.name}`));
+		}
+		names.add(manifest.name);
+	}
 	const unresolved: string[] = [];
 	for (const m of modules) {
 		for (const dep of m.manifest.dependsOn) {

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/termination.ts

@@ -29,6 +29,16 @@ interface RegisteredHook {
 	timeoutMs?: number;
 }
 
+function registeredHook(hook: Hook, options?: { timeoutMs: number }): RegisteredHook {
+	if (
+		options &&
+		(!Number.isSafeInteger(options.timeoutMs) || options.timeoutMs <= 0 || options.timeoutMs > 2 ** 31 - 1)
+	) {
+		throw new RangeError("shutdown hook timeout must be a positive 32-bit timer delay");
+	}
+	return { run: hook, ...options };
+}
+
 /** Wall-clock budget per hook and per domain.stop() call. */
 export const DEFAULT_SHUTDOWN_HOOK_MS = 500;
 
@@ -141,19 +151,13 @@ class TerminationCoordinator {
 	}
 
 	onDrain(hook: Hook, options?: { timeoutMs: number }): void {
-		if (
-			options &&
-			(!Number.isSafeInteger(options.timeoutMs) || options.timeoutMs <= 0 || options.timeoutMs > 2 ** 31 - 1)
-		) {
-			throw new RangeError("shutdown hook timeout must be a positive 32-bit timer delay");
-		}
-		this.drainHooks.push({ run: hook, ...options });
+		this.drainHooks.push(registeredHook(hook, options));
 	}
 	onTerminate(hook: Hook): void {
 		this.terminateHooks.push({ run: hook });
 	}
-	onPersist(hook: Hook): void {
-		this.persistHooks.push({ run: hook });
+	onPersist(hook: Hook, options?: { timeoutMs: number }): void {
+		this.persistHooks.push(registeredHook(hook, options));
 	}
 
 	async shutdown(code = 0): Promise<void> {

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/contract.ts

@@ -3,7 +3,7 @@ import type { AgentRecipeDiagnostic } from "./registry.js";
 import type { AgentSpec } from "./spec.js";
 
 export interface AgentsContract {
-	/** Monotonic catalog revision; changes after every successful discovery. */
+	/** Monotonic catalog revision; changes after discovery or external-agent settings updates. */
 	revision(): number;
 	/** Raw recipes as loaded from Markdown files. */
 	list(): ReadonlyArray<AgentRecipe>;

package/src/domains/agents/extension.ts

@@ -12,38 +12,82 @@ 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;
+	let unsubscribePluginsReload: (() => void) | null = null;
+	let unsubscribeConfigChange: (() => 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;
+			unsubscribeConfigChange =
+				_context.getContract<ConfigContract>("config")?.onChange("nextTurn", ({ diff }) => {
+					if (
+						diff.nextTurn.some(
+							(path) =>
+								path === "integrations.externalAgents.entries" || path.startsWith("integrations.externalAgents.entries."),
+						)
+					) {
+						revision += 1;
+					}
+				}) ?? null;
+			// 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`,
 					);
 				}
-			});
+			};
+			unsubscribePluginsReload = _context.bus.on(BusChannels.PluginsReloaded, onResourceReload);
 		},
 		async stop() {
-			unsubscribeExtensionsReload?.();
-			unsubscribeExtensionsReload = null;
+			unsubscribePluginsReload?.();
+			unsubscribePluginsReload = null;
+			unsubscribeConfigChange?.();
+			unsubscribeConfigChange = null;
 		},
 	};