@iowarp/clio-coder 0.4.9 → 0.5.0

package/src/domains/providers/runtimes/protocol/litellm.ts

@@ -186,6 +186,8 @@ export function aggregateLiteLLMCapabilities(rows: ReadonlyArray<Partial<Capabil
 }
 
 interface LiteLLMCatalog {
+	/** Whether the authenticated inference listing returned a valid catalog. */
+	listed: boolean;
 	models: string[];
 	modelCapabilities: Record<string, Partial<CapabilityFlags>>;
 	modelStates: Record<string, ProbeModelStatus>;
@@ -193,9 +195,11 @@ interface LiteLLMCatalog {
 	deployments: Record<string, Array<{ model: string; apiBase?: string }>>;
 	/** Whether the empty catalog is specifically because the gateway rejected the key. */
 	authFailed: boolean;
+	notes?: string[];
 }
 
 const EMPTY_CATALOG: LiteLLMCatalog = {
+	listed: false,
 	models: [],
 	modelCapabilities: {},
 	modelStates: {},
@@ -209,65 +213,68 @@ function isAuthError(leg: { ok: boolean; error?: string }): boolean {
 }
 
 /**
- * Read the catalog from `/v1/model/info`, falling back to `/v1/models`.
- *
- * The detail endpoint is the only one that carries capabilities, but it can be
- * refused for a virtual key with narrower permissions than the master key. A
- * gateway that answers the plain listing and refuses the detail is still usable;
- * it just cannot tell Clio anything beyond which aliases exist, so the target
- * falls back to its declared capabilities exactly as `openai-compat` would.
+ * The inference listing controls alias availability; detail only enriches exact
+ * aliases. Detail access may be restricted independently of inference access.
  */
 async function fetchCatalog(base: string, ctx: ProbeContext, headers: Record<string, string>): Promise<LiteLLMCatalog> {
-	const detailOpts = { url: `${base}/v1/model/info`, timeoutMs: ctx.httpTimeoutMs, headers } as const;
-	const detail = await (ctx.signal
-		? probeJson<LiteLLMModelInfoResponse>({ ...detailOpts, signal: ctx.signal })
-		: probeJson<LiteLLMModelInfoResponse>(detailOpts));
+	const options = { timeoutMs: ctx.httpTimeoutMs, headers, ...(ctx.signal ? { signal: ctx.signal } : {}) };
+	const list = await probeJson<LiteLLMModelsResponse>({ ...options, url: `${base}/v1/models` });
+	if (isAuthError(list)) return { ...EMPTY_CATALOG, authFailed: true };
+	const listed = list.ok && Array.isArray(list.data?.data);
+	const models = listed
+		? [...new Set(list.data?.data?.flatMap((row) => (typeof row?.id === "string" && row.id.length > 0 ? [row.id] : [])))]
+		: [];
+	// An explicitly empty inference listing must not be broadened by admin metadata.
+	if (listed && models.length === 0) return { ...EMPTY_CATALOG, listed: true };
 
-	if (detail.ok && Array.isArray(detail.data?.data)) {
-		const catalog: LiteLLMCatalog = {
-			models: [],
-			modelCapabilities: {},
-			modelStates: {},
-			deployments: {},
-			authFailed: false,
-		};
-		const capabilityRows: Record<string, Array<Partial<CapabilityFlags>>> = {};
-		for (const row of detail.data.data) {
-			if (typeof row?.model_name !== "string" || row.model_name.length === 0) continue;
-			const alias = row.model_name;
-			if (catalog.deployments[alias] === undefined) {
-				catalog.models.push(alias);
-				catalog.deployments[alias] = [];
-				capabilityRows[alias] = [];
-			}
-			const caps = row.model_info ? capabilitiesFromLiteLLMModelInfo(row.model_info) : {};
-			capabilityRows[alias]?.push(caps);
-			const upstream = row.litellm_params?.model;
-			const apiBase = row.litellm_params?.api_base;
-			catalog.deployments[alias]?.push({
-				model: typeof upstream === "string" ? upstream : alias,
-				...(typeof apiBase === "string" ? { apiBase } : {}),
-			});
-		}
-		for (const alias of catalog.models) {
-			const caps = aggregateLiteLLMCapabilities(capabilityRows[alias] ?? []);
-			if (Object.keys(caps).length > 0) catalog.modelCapabilities[alias] = caps;
+	let detail = await probeJson<LiteLLMModelInfoResponse>({ ...options, url: `${base}/v1/model/info` });
+	if (
+		(!detail.ok && /^HTTP (404|405|501)\b/u.test(detail.error ?? "")) ||
+		(detail.ok && !Array.isArray(detail.data?.data))
+	) {
+		detail = await probeJson<LiteLLMModelInfoResponse>({ ...options, url: `${base}/model/info` });
+	}
+	const catalog: LiteLLMCatalog = {
+		listed,
+		models,
+		modelCapabilities: {},
+		modelStates: {},
+		deployments: {},
+		authFailed: false,
+	};
+	if (!detail.ok || !Array.isArray(detail.data?.data)) {
+		catalog.notes = ["Gateway detail metadata is unavailable; route capabilities are unknown."];
+		return catalog;
+	}
+	if (!listed) {
+		catalog.notes = [
+			"Inference model listing is unavailable; aliases come from gateway detail metadata and availability is unverified.",
+		];
+	}
+	const available = new Set(models);
+	const capabilityRows: Record<string, Array<Partial<CapabilityFlags>>> = {};
+	for (const row of detail.data.data) {
+		if (typeof row?.model_name !== "string" || row.model_name.length === 0) continue;
+		const alias = row.model_name;
+		if (listed && !available.has(alias)) continue;
+		if (catalog.deployments[alias] === undefined) {
+			if (!listed) catalog.models.push(alias);
+			catalog.deployments[alias] = [];
+			capabilityRows[alias] = [];
 		}
-		if (catalog.models.length > 0) return catalog;
+		capabilityRows[alias]?.push(row.model_info ? capabilitiesFromLiteLLMModelInfo(row.model_info) : {});
+		const upstream = row.litellm_params?.model;
+		const apiBase = row.litellm_params?.api_base;
+		catalog.deployments[alias]?.push({
+			model: typeof upstream === "string" ? upstream : alias,
+			...(typeof apiBase === "string" ? { apiBase } : {}),
+		});
 	}
-	const detailAuthFailed = isAuthError(detail);
-
-	const listOpts = { url: `${base}/v1/models`, timeoutMs: ctx.httpTimeoutMs, headers } as const;
-	const list = await (ctx.signal
-		? probeJson<LiteLLMModelsResponse>({ ...listOpts, signal: ctx.signal })
-		: probeJson<LiteLLMModelsResponse>(listOpts));
-	if (!list.ok || !Array.isArray(list.data?.data)) {
-		return { ...EMPTY_CATALOG, authFailed: detailAuthFailed || isAuthError(list) };
+	for (const alias of catalog.models) {
+		const caps = aggregateLiteLLMCapabilities(capabilityRows[alias] ?? []);
+		if (Object.keys(caps).length > 0) catalog.modelCapabilities[alias] = caps;
 	}
-	const models = list.data.data
-		.map((row) => (typeof row?.id === "string" ? row.id : null))
-		.filter((id): id is string => id !== null && id.length > 0);
-	return { models, modelCapabilities: {}, modelStates: {}, deployments: {}, authFailed: false };
+	return catalog;
 }
 
 const litellmRuntime: RuntimeDescriptor = {
@@ -284,25 +291,27 @@ const litellmRuntime: RuntimeDescriptor = {
 		if (!base) return { ok: false, error: "target has no url" };
 		const headers = bearerHeaders(target, ctx);
 
-		// Liveness first, and deliberately on the unauthenticated endpoint. A
-		// gateway with authentication enforced answers 401 to `/v1/models` when
-		// credentials are missing or wrong, which is indistinguishable from an
-		// unreachable host if that is the only thing probed. `/health/liveliness`
-		// separates "the gateway is down" from "this key is not valid", and the
-		// two have completely different remedies.
+		// Liveness is supplementary: a reverse proxy may restrict this public
+		// endpoint while the authenticated inference listing remains usable.
 		const liveOpts = { url: `${base}/health/liveliness`, timeoutMs: ctx.httpTimeoutMs } as const;
 		const live = await (ctx.signal
 			? probeJson<unknown>({ ...liveOpts, signal: ctx.signal })
 			: probeJson<unknown>(liveOpts));
-		if (!live.ok) return { ok: false, error: live.error ?? "gateway is not reachable" };
 
 		const catalog = await fetchCatalog(base, ctx, headers);
-		if (catalog.models.length === 0) {
+		if (!catalog.listed || catalog.models.length === 0) {
 			const result: ProbeResult = {
 				ok: false,
 				error: catalog.authFailed
-					? "gateway rejected the key"
-					: "gateway is live but served no model catalog; check the target's API key",
+					? "gateway rejected model-list access"
+					: "gateway inference model catalog is unavailable or empty",
+				failureKind: catalog.authFailed
+					? "authentication"
+					: live.ok || catalog.listed || catalog.models.length > 0
+						? "catalog-unavailable"
+						: "generic",
+				...(catalog.models.length > 0 ? { models: catalog.models } : {}),
+				...(catalog.notes ? { notes: catalog.notes } : {}),
 			};
 			if (catalog.authFailed) result.authFailed = true;
 			if (live.latencyMs !== undefined) result.latencyMs = live.latencyMs;
@@ -320,7 +329,8 @@ const litellmRuntime: RuntimeDescriptor = {
 				result.capabilityModelId = selected;
 			}
 		}
-		const notes: string[] = [];
+		const notes: string[] = [...(catalog.notes ?? [])];
+		if (!live.ok) notes.push("Unauthenticated liveness check failed; authenticated model listing succeeded.");
 		const configured = target.defaultModel?.trim();
 		if (configured && !catalog.models.includes(configured)) {
 			notes.push(`configured model '${configured}' is not in the gateway catalog`);
@@ -351,7 +361,9 @@ const litellmRuntime: RuntimeDescriptor = {
 	async probeModels(target: TargetDescriptor, ctx: ProbeContext): Promise<string[]> {
 		const base = rootUrl(target);
 		if (!base) return [];
-		return (await fetchCatalog(base, ctx, bearerHeaders(target, ctx))).models;
+		const catalog = await fetchCatalog(base, ctx, bearerHeaders(target, ctx));
+		// This legacy string-array surface cannot distinguish hints from live IDs.
+		return catalog.listed ? catalog.models : [];
 	},
 
 	synthesizeModel(target: TargetDescriptor, wireModelId: string, kb: KnowledgeBaseHit | null): Model<Api> {

package/src/domains/providers/support.ts

@@ -55,7 +55,7 @@ const SUMMARY_BY_RUNTIME_ID: Readonly<Record<string, string>> = {
 	openai: "OpenAI Platform API",
 	"openai-codex": "ChatGPT Plus/Pro via Codex OAuth",
 	openrouter: "OpenRouter API",
-	"ollama-native": "Ollama native API",
+	ollama: "Ollama native API",
 	lmstudio: "LM Studio chat over OpenAI-compatible REST with native REST model management",
 	llamacpp: "llama.cpp server (auto-detect surface)",
 	"anthropic-compat": "Generic Anthropic-compatible REST",

package/src/domains/providers/types/local-model-quirks.ts

@@ -7,9 +7,8 @@
  *
  * Field naming follows the Hugging Face / model-card terminology so the YAML
  * can be authored against the source-of-truth card. The OpenAI adapter
- * translates these into pi-ai sampling parameters at consumption:
- *   - OpenAI-compatible surfaces accept `top_p`, `top_k`, `min_p`,
- *     `repeat_penalty`.
+ * maps these to endpoint-specific parameters; OpenAI compatibility alone
+ * does not establish support for extensions such as top_k or repetition penalties.
  */
 
 import type { ThinkingBudgetByLevel, ThinkingEffortByLevel } from "../thinking-control-policy.js";

package/src/domains/providers/types/runtime-descriptor.ts

@@ -115,6 +115,12 @@ export interface ProbeResult {
 	 * weights (single-model server, so there is no eviction recourse).
 	 */
 	notes?: ReadonlyArray<string>;
+	/**
+	 * Server settings the probe could see that defeat prefix-cache reuse, each
+	 * naming the setting that fixes it. Every entry is also one of `notes`;
+	 * `clio-coder doctor` reports these without surfacing the other notes.
+	 */
+	cacheAdvisories?: ReadonlyArray<string>;
 	/**
 	 * Composite descriptors set this to the api family they will use for chat.
 	 * `synthesizeModel` reads it back out of the cached probe state to choose
@@ -126,7 +132,8 @@ export interface ProbeResult {
 }
 
 export interface ReasoningProbeResult {
-	reasoning: boolean;
+	/** Only true establishes observed support; false/null are inconclusive. */
+	reasoning: boolean | null;
 	latencyMs: number;
 	error?: string;
 }
@@ -183,6 +190,19 @@ export interface RuntimeDescriptor {
 	 */
 	hidden?: boolean;
 	probe?(target: TargetDescriptor, ctx: ProbeContext): Promise<ProbeResult>;
+	/**
+	 * Window this target asks the server to open the model at on every request,
+	 * when the runtime sends one (Ollama `num_ctx`). The server reloads the
+	 * model at that size, so it outranks whatever window is loaded now.
+	 */
+	requestedContextWindow?(target: TargetDescriptor): number | undefined;
+	/**
+	 * Largest window to plan a model at while it is not resident, when the
+	 * runtime opens a cold model at a server-chosen size no API reports before
+	 * load (Ollama's `OLLAMA_CONTEXT_LENGTH`). A model maximum above it is what
+	 * the weights allow, not what the next load will serve.
+	 */
+	coldContextWindowCap?: number;
 	probeModels?(target: TargetDescriptor, ctx: ProbeContext): Promise<string[]>;
 	/**
 	 * Optional per-model reasoning capability probe. Protocol-compatible local
@@ -190,8 +210,8 @@ export interface RuntimeDescriptor {
 	 * Anthropic wire surface regardless of whether the loaded model supports
 	 * thinking. Implementations here send a one-shot priming request and look at
 	 * `reasoning_content` / `reasoning` / `reasoning_text` in the response.
-	 * Result is cached per (target, model) by the providers domain so
-	 * /thinking can surface the correct level set.
+	 * Only positive observations are cached per (target, model). This generates
+	 * tokens and must be explicitly requested, never part of routine discovery.
 	 */
 	probeReasoning?(target: TargetDescriptor, modelId: string, ctx: ProbeContext): Promise<ReasoningProbeResult>;
 	synthesizeModel(target: TargetDescriptor, wireModelId: string, kb: KnowledgeBaseHit | null): Model<Api>;

package/src/domains/providers/types/target-descriptor.ts

@@ -19,15 +19,16 @@ export interface TargetCacheSettings {
 	retention?: "none" | "short" | "long";
 	/** Explicit read-only deployment binding; never grants administrative authority. */
 	deployment?: {
-		backend: "llamacpp" | "vllm";
+		backend: "llamacpp" | "vllm" | "lmstudio";
 		controlUrl: string;
 		model: string;
-		build: string;
+		/** Required for build-pinned llama.cpp/vLLM deployments. */
+		build?: string;
 		/** Required for a gateway binding; compared with its current route inventory. */
 		gatewayDeploymentId?: string;
 	};
 	/** Local warm bounds. Paid routes remain ineligible. */
-	warm?: { maxInputTokens?: number; maxDurationMs?: number; cooldownMs?: number };
+	warm?: { startup?: boolean; maxInputTokens?: number; maxDurationMs?: number; cooldownMs?: number };
 }
 
 // Canonical persisted lifecycle name. Readers temporarily normalize the
@@ -73,6 +74,16 @@ export interface LiteLLMTargetSettings {
 	request?: LiteLLMRequestSettings;
 }
 
+/** Ollama request options Clio sends only when the operator sets them. */
+export interface OllamaTargetSettings {
+	/**
+	 * Context window requested as `options.num_ctx` on every chat request, and
+	 * the window Clio plans against. Ollama reloads a model whose `num_ctx`
+	 * changes, so on a server other clients share this evicts their load.
+	 */
+	numCtx?: number;
+}
+
 /**
  * Persisted target specification from settings.yaml (`targets:`). It binds a
  * user-facing target id to a RuntimeDescriptor id, target URL/auth metadata,
@@ -93,6 +104,7 @@ export interface TargetDescriptor {
 	cache?: TargetCacheSettings;
 	lmstudio?: LmStudioTargetSettings;
 	litellm?: LiteLLMTargetSettings;
+	ollama?: OllamaTargetSettings;
 	/** Explicit request-slot limit for this inference endpoint. It overrides live discovery. */
 	maxConcurrentRequests?: number;
 }

package/src/domains/resources/collision.ts

@@ -55,7 +55,10 @@ function compareCandidates<T>(a: ResourceCandidate<T>, b: ResourceCandidate<T>):
 	return a.source.path.localeCompare(b.source.path);
 }
 
-export function resolveResourceCollisions<T>(candidates: ReadonlyArray<ResourceCandidate<T>>): CollisionResolution<T> {
+export function resolveResourceCollisions<T>(
+	candidates: ReadonlyArray<ResourceCandidate<T>>,
+	priority?: (value: T) => number,
+): CollisionResolution<T> {
 	const byName = new Map<string, ResourceCandidate<T>[]>();
 	for (const candidate of candidates) {
 		const key = candidate.name.trim();
@@ -68,7 +71,9 @@ export function resolveResourceCollisions<T>(candidates: ReadonlyArray<ResourceC
 	const winners: T[] = [];
 	const diagnostics: ResourceDiagnostic[] = [];
 	for (const [name, entries] of byName.entries()) {
-		const sorted = [...entries].sort(compareCandidates);
+		const sorted = [...entries].sort(
+			(a, b) => (priority ? priority(a.value) - priority(b.value) : 0) || compareCandidates(a, b),
+		);
 		const winner = sorted[sorted.length - 1];
 		if (!winner) continue;
 		winners.push(winner.value);

package/src/domains/resources/index.ts

@@ -114,6 +114,7 @@ export {
 	promptTemplateDisplayText,
 } from "./prompts/loader.js";
 export { parseCommandArgs, substituteArgs } from "./prompts/substitute.js";
+export { installedSkillNames, installedSkillPackages } from "./skills/availability.js";
 export { parseSkillEvals, type SkillEvalParseResult, type SkillEvalScenario } from "./skills/evals.js";
 export {
 	type InstallSkillInput,

package/src/domains/resources/library-actions.ts

@@ -440,9 +440,11 @@ export function planLibraryLifecycle(request: LibraryLifecycleRequest): LibraryL
 				(ref) => !entries.some((item) => item.loadable && `${item.kind ?? "plugin"}:${item.id}` === ref),
 			);
 			if (request.operation === "enable") {
-				if (!copy.valid || !copy.compatible)
+				if (!copy.valid || !copy.compatible) {
 					refusal = `${identity.ref} cannot be enabled: ${copy.diagnostics.map((d) => d.message).join("; ")}`;
-				else if (missing.length)
+					if (libraryCopyState(copy) === "damaged")
+						refusal += `. Inspect local changes first; to replace from the recorded source and preserve changed files in a recovery backup, run clio-coder library update ${identity.ref} --${copy.scope} --force`;
+				} else if (missing.length)
 					refusal = `library_requirement_missing: ${missing.join(", ")}; install or enable those first`;
 				const winner = entries.find((item) => item.id === identity.name && item.effective);
 				effectiveAfter = winner

package/src/domains/resources/library-inventory.ts

@@ -507,7 +507,9 @@ function fromSkill(skill: Skill, index: OwnerIndex): LibraryResource {
 	const reason = hard
 		? skill.diagnostics.find((item) => item.type === "error" || item.type === "collision")?.message
 		: !skill.trusted
-			? "root is not trusted; enable integrations.projectResources.trustProjectImports or install the package"
+			? skill.source === "plugin"
+				? "imported package is untrusted; review it and enable integrations.projectResources.trustProjectImports"
+				: "discovered only; explicitly import into Clio with interop adopt or library import"
 			: undefined;
 	const scope = skill.scope === "cli" ? "user" : skill.scope;
 	return {
@@ -541,7 +543,9 @@ function fromPrompt(template: PromptTemplate, index: OwnerIndex): LibraryResourc
 	const reason = template.unavailable
 		? template.unavailable
 		: !template.trusted
-			? "root is not trusted; enable integrations.projectResources.trustProjectImports or install the package"
+			? scope === "package"
+				? "imported package is untrusted; review it and enable integrations.projectResources.trustProjectImports"
+				: "discovered only; explicitly import into Clio with interop adopt or library import"
 			: undefined;
 	return {
 		key: libraryResourceKey(

package/src/domains/resources/prompts/loader.ts

@@ -26,7 +26,7 @@ export interface PromptTemplate {
 	content: string;
 	filePath: string;
 	sourceInfo: ResourceSourceInfo;
-	/** False for a project compatibility root until the operator opts in; such a template refuses to expand. */
+	/** False for loose compatibility roots and untrusted imported packages; expansion is refused. */
 	trusted: boolean;
 	/**
 	 * Why this template cannot be expanded, when a load-time failure left it
@@ -104,8 +104,8 @@ export type PromptTemplateExpansion =
 /**
  * Clio's own prompt roots plus the command and prompt directories the other
  * agents on the machine own. A foreign prompt is text substituted into a
- * message the operator typed, so a project-scope one stays untrusted behind the
- * same opt-in a project-scope foreign skill needs.
+ * message the operator typed. Loose foreign roots remain discovery-only;
+ * explicitly imported foreign packages share the skills trust gate.
  */
 function defaultPromptTemplateRoots(input: LoadPromptTemplatesInput = {}): PromptTemplateRoot[] {
 	const cwd = input.cwd ?? process.cwd();
@@ -119,7 +119,7 @@ function defaultPromptTemplateRoots(input: LoadPromptTemplatesInput = {}): Promp
 				scope: "user",
 				source: `${kind.id}-user`,
 				precedence: COMPAT_RESOURCE_PRECEDENCE.userCompat,
-				trusted: true,
+				trusted: false,
 			});
 		}
 		if (kind.projectPromptRoot !== undefined) {
@@ -128,7 +128,7 @@ function defaultPromptTemplateRoots(input: LoadPromptTemplatesInput = {}): Promp
 				scope: "project",
 				source: `${kind.id}-project`,
 				precedence: COMPAT_RESOURCE_PRECEDENCE.projectCompat,
-				trusted: trustProject,
+				trusted: false,
 			});
 		}
 	}
@@ -365,7 +365,17 @@ export function loadPromptTemplates(input: LoadPromptTemplatesInput = {}): Promp
 	const roots = input.roots ?? defaultPromptTemplateRoots(input);
 	const diagnostics: ResourceDiagnostic[] = [];
 	const candidates = roots.flatMap((root) => loadPromptRoot(root, diagnostics));
-	const resolved = resolveResourceCollisions(candidates);
+	// Discovery-only foreign files cannot shadow an admitted Clio prompt.
+	const resolved = resolveResourceCollisions(
+		candidates,
+		(template) =>
+			Number(template.trusted) * 2 +
+			Number(
+				template.sourceInfo.scope === "package" ||
+					template.sourceInfo.source === "config" ||
+					template.sourceInfo.source === "project",
+			),
+	);
 	const items: PromptTemplate[] = [];
 	for (const template of resolved.winners) {
 		if (input.reservedNames?.has(template.name) === true) {
@@ -418,7 +428,10 @@ export function expandPromptTemplateInput(input: string, templates: PromptTempla
 		};
 	}
 	if (!template.trusted) {
-		const message = `prompt template ${template.name} comes from an untrusted project root; set integrations.projectResources.trustProjectImports to use it`;
+		const message =
+			template.sourceInfo.scope === "package"
+				? `prompt template ${template.name} is imported but untrusted; review it and enable integrations.projectResources.trustProjectImports to use it`
+				: `prompt template ${template.name} is discovered from another agent; explicitly import it into Clio with interop adopt or library import before use. The trust setting does not import loose files`;
 		return {
 			expanded: false,
 			text: input,

package/src/domains/resources/skills/availability.ts

@@ -0,0 +1,56 @@
+import path from "node:path";
+import { listInstalledPlugins, pluginSnapshotFor, readPluginInstallRecord } from "../../plugins/index.js";
+import type { Skill } from "./loader.js";
+
+/** Disk installation state, separate from the running session's resource snapshot. */
+export function installedSkillPackages(skills: ReadonlyArray<Skill>, cwd: string, trustImports = false) {
+	const snapshot = pluginSnapshotFor(cwd);
+	return listInstalledPlugins(cwd, { all: true })
+		.filter((pkg) => pkg.kind === "skill" || pkg.resources.skills)
+		.map((pkg) => {
+			const members = pkg.manifest?.clio.components.filter((item) => item.kind === "skill").map((item) => item.id) ?? [];
+			const names = [...new Set([...(pkg.kind === "skill" ? [pkg.id] : []), ...members])];
+			const active = skills.some((skill) => {
+				const relative = path.relative(pkg.rootPath, skill.filePath);
+				return (
+					skill.source === "plugin" &&
+					relative !== ".." &&
+					!relative.startsWith(`..${path.sep}`) &&
+					!path.isAbsolute(relative)
+				);
+			});
+			const admitted = snapshot.resourceRoots.skills.some(
+				(root) =>
+					root.provenance.canonicalRoot === pkg.provenance?.canonicalRoot &&
+					root.provenance.contentDigest === pkg.provenance?.contentDigest,
+			);
+			const state = !pkg.valid
+				? "invalid"
+				: !pkg.compatible
+					? "incompatible"
+					: !pkg.enabled
+						? "disabled"
+						: !pkg.effective
+							? "shadowed"
+							: !pkg.loadable
+								? "damaged"
+								: pkg.trust === "foreign" && !trustImports
+									? "requires trust"
+									: active
+										? "ready"
+										: admitted
+											? "no ready skills; inspect /library"
+											: "pending reload; run /library reload";
+			const record = readPluginInstallRecord(pkg.id, { cwd, scope: pkg.scope });
+			const origin = typeof record?.origin === "object" ? record.origin.kind : (record?.origin ?? "local");
+			return { name: pkg.id, names, scope: pkg.scope, state, origin, path: pkg.rootPath };
+		});
+}
+
+/** Loose compatibility discoveries must never suppress a marketplace install offer. */
+export function installedSkillNames(skills: ReadonlyArray<Skill>, cwd: string): Set<string> {
+	return new Set([
+		...skills.filter((skill) => skill.source === "clio-coder" || skill.source === "plugin").map((skill) => skill.name),
+		...installedSkillPackages(skills, cwd).flatMap((pkg) => pkg.names),
+	]);
+}

package/src/domains/resources/skills/loader.ts

@@ -11,6 +11,7 @@ import { enabledPluginResourceRoots, pluginBaseDir } from "../../plugins/index.j
 import type { ResourceDiagnostic, ResourceScope, ResourceSourceInfo } from "../collision.js";
 import { readRootEntries, splitYamlFrontmatter, stringField } from "../common-loader.js";
 import { resolvePackageReferences } from "../package-references.js";
+import { installedSkillNames } from "./availability.js";
 import { normalizedSkillHash } from "./content-hash.js";
 import { getMarketplaceSkills } from "./marketplace.js";
 
@@ -163,7 +164,7 @@ export interface LoadSkillsInput {
 	home?: string;
 	/** Override the Clio config dir used for the user skill root (testing). */
 	configDir?: string;
-	/** Opt in to model-visible project compatibility roots (.agents/.codex). */
+	/** Trust explicitly imported foreign packages; never activates loose compatibility roots. */
 	trustProjectCompatRoots?: boolean;
 	/** Disable normal root discovery. Explicit skill paths still load. */
 	disableDiscovery?: boolean;
@@ -215,9 +216,8 @@ function defaultPrecedenceForScope(scope: ResourceScope): number {
 }
 
 /**
- * Whether project-scope compatibility roots are model-visible. Prompts share
- * this gate with skills: both substitute another agent's project file into
- * Clio's context, so one opt-in covers both.
+ * Whether explicitly imported foreign packages may provide skills/prompts.
+ * Loose compatibility roots remain discovery-only, at every scope.
  */
 export function projectCompatTrusted(explicit?: boolean): boolean {
 	return explicit === true;
@@ -226,9 +226,9 @@ export function projectCompatTrusted(explicit?: boolean): boolean {
 /**
  * Discovery roots, lowest to highest precedence:
  *  1. plugin skills
- *  2. shared user compat roots, one per interop agent kind that owns a skills directory
+ *  2. discovery-only user compat roots, one per interop agent kind
  *  3. Clio user root (<config>/skills)
- *  4. the same agents' project roots, trusted only on opt-in
+ *  4. the same agents' project roots, also discovery-only
  *  5. Clio project root (.clio-coder/skills)
  *
  * The compatibility roots come from the interop registry rather than a list
@@ -264,7 +264,7 @@ export function defaultSkillRoots(input: LoadSkillsInput = {}): SkillRoot[] {
 			source: kind.skillSource,
 			origin: `${kind.skillSource}-user`,
 			precedence: SKILL_PRECEDENCE.userCompat,
-			trusted: true,
+			trusted: false,
 			containment: home,
 		});
 	}
@@ -289,7 +289,7 @@ export function defaultSkillRoots(input: LoadSkillsInput = {}): SkillRoot[] {
 			source: kind.skillSource,
 			origin: `${kind.skillSource}-project`,
 			precedence: SKILL_PRECEDENCE.projectCompat,
-			trusted: trustProject,
+			trusted: false,
 			containment: cwd,
 		});
 	}
@@ -845,6 +845,11 @@ function loadExplicitSkillPath(
 function compareSkillCandidates(a: Skill, b: Skill): number {
 	const trust = Number(a.trusted) - Number(b.trusted);
 	if (trust !== 0) return trust;
+	// An imported copy awaiting trust still owns its name over a loose discovery.
+	const owned = (skill: Skill) =>
+		skill.source === "plugin" || skill.source === "clio-coder" || skill.source === "cli" || skill.source === "path";
+	const ownership = Number(owned(a)) - Number(owned(b));
+	if (ownership !== 0) return ownership;
 	const precedence = a.precedence - b.precedence;
 	if (precedence !== 0) return precedence;
 	const rank = interopSourceRank(b.source) - interopSourceRank(a.source);
@@ -1051,7 +1056,9 @@ export function parsePendingSkillRequests(
 	if (command) {
 		const name = command.name;
 		const args = command.args;
-		const installedSkill = skills.items.find((entry) => entry.name === name);
+		const installedSkill = skills.items.find(
+			(entry) => entry.name === name && (entry.trusted || entry.source === "plugin" || entry.source === "clio-coder"),
+		);
 		if (installedSkill) {
 			return {
 				text: args,
@@ -1066,6 +1073,10 @@ export function parsePendingSkillRequests(
 				],
 			};
 		}
+		// A package installed by another process can still await session reload.
+		if (installedSkillNames(skills.items, options.cwd ?? process.cwd()).has(name)) {
+			return { text: args, pendingSkillRequests: [{ name, args, source: "slash-command", installed: true }] };
+		}
 		// Check the local marketplace/discovery contract. Empty means unavailable/offline.
 		const marketplaceSkill = getMarketplaceSkills(options.cwd ? { cwd: options.cwd } : {}).find((s) => s.name === name);
 		if (marketplaceSkill) {