@iowarp/clio-coder 0.3.8 → 0.4.0

package/docs/troubleshooting.md

@@ -1,6 +1,6 @@
 # Troubleshooting & Error Remediation
 
-This guide provides concrete, actionable remediation procedures for operational errors, permission denials, target connection failures, and system diagnostics in Clio Coder `v0.3.7`.
+This guide provides concrete, actionable remediation procedures for operational errors, permission denials, target connection failures, and system diagnostics in Clio Coder `v0.4.0`.
 
 ---
 
@@ -26,6 +26,93 @@ This guide provides concrete, actionable remediation procedures for operational
 
 ---
 
+## Reading a cold cache
+
+On a local server prefill is most of what a turn costs, so a cold prefix cache is the difference between a first token in under a second and one in fifty. This is how to find out why a turn went cold, starting from what the TUI shows.
+
+**1. Read the `/context` cache lines.** Two lines answer different questions. The prompt-cache line says what the provider reported and whether the compiled prompt shell was reused. The prefill line says what the server itself did:
+
+```text
+prefill: 34,951 uncached · 0 cached · 48,617 ms
+```
+
+Those are the server's own numbers, not Clio's estimate. `server does not report cache reads` in place of the cached figure means the backend gave no `cache_n` at all, which is LM Studio 2.29.0's OpenAI-compatible port today; on that target the verdict comes from the provider's `cached_tokens` instead and the prefill line reports only total prompt work and milliseconds.
+
+**2. Look for the expected-cold line.** When the last settled run came back `cold` and Clio had recorded a cause, `/context` names it rather than warning:
+
+```text
+last cold turn: working-set eviction (expected)
+```
+
+The eight causes and what stamps each one are in [context-engine.md](context-engine.md#cache-divergence-honesty). `background_memory` renders in prose as `last cold turn: background memory step (expected)`.
+
+**3. Confirm it in the ledger.** The reasons are durable, so a finished session answers the same question without the TUI. Open `current.jsonl` under the session directory `clio-coder paths` reports and read the run's first assistant entry:
+
+```json
+{
+  "timing": { "ttftMs": 53194, "apiMs": 56770 },
+  "promptCache": {
+    "input": 34951, "cacheRead": 0, "cacheWrite": 0,
+    "backendVerdict": "cold",
+    "expectedColdReasons": ["dispatch", "residency"],
+    "backend": {
+      "promptTokens": 34951, "cachedTokens": 0, "predictedTokens": 24,
+      "promptMs": 48617, "predictedMs": 373, "source": "llamacpp-timings"
+    }
+  }
+}
+```
+
+`expectedColdReasons` is stamped once per run, on its first persisted call, so a turn with several model calls carries it on the first one only. `clio-coder doctor` folds the latest session for you and prints the verdict counts plus the most frequent reason, and `clio-coder usage report` gives per-session uncached prefill and verdict counts across the window.
+
+**4. When there is no reason, the warning is the finding.** A cold backend with a reused prompt shell and no recorded reason is a real disagreement: Clio kept the bytes stable and the server re-prefilled anyway. `/context` leaves the warning in place for exactly that case. Four causes are worth checking in order, and none of them is a Clio bug:
+
+- **The server slept.** A llama.cpp router started with `--sleep-idle-seconds N` drops the slot's prefix cache when it sleeps, and `--cache-ram` does not reliably restore a large state. A gap longer than that setting between two turns explains a cold turn completely. Raise the flag, or accept that a session left idle pays for its first turn back.
+- **Something else used the endpoint.** A worker, a second Clio session, or another client on the same server evicts the slot. Clio stamps `dispatch`, `residency`, and `background_memory` only for work it can attribute to itself on that endpoint; a foreign process leaves no stamp. `clio-coder targets --probe` reports the endpoint's slot count, and `/fleet` settings show active slots per endpoint.
+- **The model was swapped.** A router serving one model at a time reloads on a residency change, and everything the previous model had cached is gone. This normally does stamp `residency`, but only when the mutation went through Clio.
+- **The prompt moved for a reason Clio did not classify.** Compare the run's `promptHash` and `toolSignature` in `context-snapshots.jsonl` against the previous run's. Equal hashes with a cold backend point at the server; different hashes with no `prompt_recompiled` or `tool_surface_change` stamp is worth an issue.
+
+One case is expected on hybrid architectures and looks like a bug. Qwen3.8 keeps recurrent state that llama.cpp cannot roll back to an arbitrary token, so a change anywhere inside a cached prefix re-prefills from the last context checkpoint rather than from the changed byte. A small edit to old history can therefore cost thousands of tokens of prefill with the prompt hash otherwise stable. The server's checkpoint count and its `--checkpoint-min-step` are the levers; see the `qwen3.8-27b` family's `serving` and `measuredUnder` notes in `src/domains/providers/models/local-models/clio-local-coding-targets.yaml` for the measured figures and the exact argv they were taken under.
+
+---
+
+## A TUI that stops answering the keyboard
+
+When an interactive session stops responding to typing, the question worth
+answering before anything else is which half of the input pipeline stopped: the
+stdin reader that hands bytes to the application, or the renderer that turns
+them into a frame on stdout. Clio keeps that evidence without being asked. Every
+interactive process holds a bounded in-memory ring of the last 256 input-ingress
+records and the last 256 committed frames, and writes it out when the process
+receives `SIGTERM`, which is the signal a `kill` of the stuck pane sends.
+
+The dump lands in the state directory `clio-coder paths` reports:
+
+```text
+<stateDir>/input-wedge/<ISO timestamp>-<pid>.json
+```
+
+The five newest dumps are kept and older ones are removed as new ones land.
+Read `classification` first:
+
+| `classification` | What it means |
+| :--- | :--- |
+| `input-not-committed` | Bytes reached the application and no frame carrying them ever reached stdout. The renderer is the stuck half. |
+| `no-input-recorded` | Nothing was delivered at all. If the operator was typing, the stdin reader is the stuck half. |
+| `input-committed` | Both halves were moving. Whatever the session was doing, it was not this pipeline. |
+
+`msSinceLastInputIngress` and `msSinceLastCommittedFrame` say how long each half
+had been quiet when the signal arrived, and the `inputIngress` and `frames`
+arrays carry the records themselves. Frames are kept only when they reached
+stdout, so an empty `frames` array is itself a finding.
+
+For a full session trace rather than the tail, set `CLIO_CODER_RENDER_TRACE` to
+a file path before starting the session. That writes every record, including
+provider deltas and terminal writes, as JSONL. The ring is the always-on subset
+of the same records, for the case where nobody armed the trace first.
+
+---
+
 ## Diagnostic Commands
 
 When encountering unexpected system behavior:

package/docs/tui-design.md

@@ -1,7 +1,7 @@
 # Clio TUI Design System
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive color/glyph token laboratory and terminal transcript preview renderer is located at [docs/html/tui_design_blueprint.html](html/tui_design_blueprint.html) (Version: 0.3.8).
+> **Interactive Spec Available:** An interactive color/glyph token laboratory and terminal transcript preview renderer is located at [docs/html/tui_design_blueprint.html](html/tui_design_blueprint.html) (Version: 0.4.0).
 
 This document is the reference specification for the Clio Coder TUI visual layout, styling, and behavior. It describes color semantics, the glyph vocabulary, structural recipes, and state choreography for all surfaces under [src/interactive/](../src/interactive/).
 

package/docs/worker-dispatch-mechanics.md

@@ -1,7 +1,7 @@
 # Worker Dispatch Mechanics
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive NDJSON protocol timeline stream and heartbeat watchdog simulator is located at [docs/html/worker_dispatch_blueprint.html](html/worker_dispatch_blueprint.html) (Version: 0.3.8).
+> **Interactive Spec Available:** An interactive NDJSON protocol timeline stream and heartbeat watchdog simulator is located at [docs/html/worker_dispatch_blueprint.html](html/worker_dispatch_blueprint.html) (Version: 0.4.0).
 
 This document describes the design and lifecycle of Clio Coder dispatched workers, focusing on the spawning sequence, execution isolation, the standard input/output NDJSON communication loop, and permission escalation routing.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@iowarp/clio-coder",
-	"version": "0.3.8",
+	"version": "0.4.0",
 	"description": "Coding agent for HPC and scientific-software developers, part of IOWarp's CLIO ecosystem of agentic science.",
 	"keywords": [
 		"ai",
@@ -92,11 +92,14 @@
 		"//": "below here: a real model target, chosen with --target <id>; costs money and/or GPU time, never run in CI",
 		"live:smoke": "node --import tsx benchmarks/internal/live-smoke.ts",
 		"live:fleet-dispatch": "node --import tsx benchmarks/internal/live-fleet-dispatch.ts",
+		"live:release-residue": "node --import tsx tests/live/release-residue.ts",
 		"live:tui": "node --import tsx benchmarks/internal/pty-drive.ts",
 		"live:home": "node --import tsx benchmarks/internal/live-home.ts"
 	},
+	"optionalDependencies": {
+		"@anthropic-ai/claude-agent-sdk": "0.3.186"
+	},
 	"dependencies": {
-		"@anthropic-ai/claude-agent-sdk": "0.3.186",
 		"@earendil-works/pi-agent-core": "0.84.0",
 		"@earendil-works/pi-ai": "0.84.0",
 		"@earendil-works/pi-tui": "0.84.0",

package/src/cli/acp.ts

@@ -66,11 +66,15 @@ export async function runAcpCommand(
 	args: ReadonlyArray<string>,
 	options: { apiKey?: string; noContextFiles?: boolean; noSkills?: boolean; skillPaths?: ReadonlyArray<string> } = {},
 ): Promise<number> {
-	if (args.includes("--help") || args.includes("-h")) {
+	// The top-level argv parser normally rewrites --acp to the `acp` command
+	// sentinel. Keep the command boundary tolerant too, so another dispatcher
+	// can pass the flag spelling through without changing ACP option semantics.
+	const normalizedArgs = args[0] === "--acp" ? args.slice(1) : args;
+	if (normalizedArgs.includes("--help") || normalizedArgs.includes("-h")) {
 		process.stdout.write(HELP);
 		return 0;
 	}
-	const flags = parseAcpFlags(args);
+	const flags = parseAcpFlags(normalizedArgs);
 	if (typeof flags === "string") {
 		printError(flags);
 		process.stderr.write(HELP);

package/src/cli/agents.ts

@@ -9,7 +9,7 @@ import { printError } from "./shared.js";
 
 const HELP = `clio-coder agents [--json] [--all]
 
-List user-facing agent specs from built-in, user, and project recipes.
+List user-facing agent specs from built-in, extension, user, and project recipes.
 
 Flags:
   --json   emit specs as JSON instead of the formatted table

package/src/cli/argv.ts

@@ -70,6 +70,11 @@ export interface GlobalCliFlags {
 	noContextFiles: boolean;
 	noSkills: boolean;
 	skillPaths: string[];
+	/**
+	 * Panes activation from the command line. `--with-panes` and `--no-panes`
+	 * both beat the `panes.enabled` setting; absent means the setting decides.
+	 */
+	panes?: "with" | "without";
 	rest: string[];
 	error?: string;
 }
@@ -85,6 +90,8 @@ const GLOBAL_ONLY_FLAGS: ReadonlyMap<string, string> = new Map([
 	["--api-key", "--api-key <key>"],
 	["--no-context-files", "--no-context-files"],
 	["-nc", "-nc"],
+	["--with-panes", "--with-panes"],
+	["--no-panes", "--no-panes"],
 ]);
 
 /**
@@ -128,6 +135,7 @@ export function extractGlobalFlags(
 	let apiKey: string | undefined;
 	let noContextFiles = false;
 	let noSkills = false;
+	let panes: "with" | "without" | undefined;
 	const skillPaths: string[] = [];
 	for (let i = 0; i < argv.length; i++) {
 		const arg = argv[i];
@@ -140,6 +148,14 @@ export function extractGlobalFlags(
 			rest.push(...argv.slice(i));
 			break;
 		}
+		if (arg === "--acp") {
+			// Treat the global spelling as a command boundary. Rewriting only the
+			// sentinel keeps every trailing ACP option on the exact same dispatcher
+			// and parser path as `clio-coder acp`, without importing that command into
+			// the dependency-light startup graph.
+			rest.push("acp", ...argv.slice(i + 1));
+			break;
+		}
 		if (ROOT_FLAG_TOKENS.has(arg)) {
 			rest.push(arg);
 			continue;
@@ -152,6 +168,12 @@ export function extractGlobalFlags(
 			noSkills = true;
 			continue;
 		}
+		if (arg === "--with-panes" || arg === "--no-panes") {
+			// Last occurrence wins, so a wrapper script's baked-in choice can be
+			// overridden by appending the opposite flag.
+			panes = arg === "--with-panes" ? "with" : "without";
+			continue;
+		}
 		if (arg === "--api-key" || arg === "--skill") {
 			const value = argv[i + 1];
 			if (value === undefined || value.startsWith("-") || isSubcommand(value)) {
@@ -162,6 +184,7 @@ export function extractGlobalFlags(
 					rest,
 					error: `${arg} requires a value`,
 					...(apiKey === undefined ? {} : { apiKey }),
+					...(panes === undefined ? {} : { panes }),
 				};
 			}
 			if (arg === "--api-key") apiKey = value;
@@ -176,6 +199,7 @@ export function extractGlobalFlags(
 			rest,
 			error: unknownGlobalOptionError(arg),
 			...(apiKey === undefined ? {} : { apiKey }),
+			...(panes === undefined ? {} : { panes }),
 		};
 	}
 	return {
@@ -184,5 +208,6 @@ export function extractGlobalFlags(
 		skillPaths,
 		rest,
 		...(apiKey === undefined ? {} : { apiKey }),
+		...(panes === undefined ? {} : { panes }),
 	};
 }

package/src/cli/config-inspect.ts

@@ -1,7 +1,7 @@
 /**
  * The effective-customization graph behind `clio-coder config inspect`. This is the
  * "why is Clio behaving this way" surface: it answers what settings, context
- * files, rules, skills, prompts, agents, extensions, safety, memory, hooks, and
+ * files, rules, skills, prompts, agents, fleets, extensions, safety, memory, hooks, and
  * the operator profile loaded, from where, with what precedence, and what each
  * costs in context.
  *
@@ -12,8 +12,9 @@
  */
 
 import { existsSync, readFileSync } from "node:fs";
-import { basename } from "node:path";
+import { basename, join } from "node:path";
 import type { ClioSettings } from "../core/config.js";
+import { resolvePackageRoot } from "../core/package-root.js";
 import { readLayeredSettings, type SettingsOrigin, settingsSourceFor } from "../core/settings-layers.js";
 import { clioDataDir } from "../core/xdg.js";
 import {
@@ -39,7 +40,8 @@ export type CustomizationCategory =
 	| "extension"
 	| "skill-root"
 	| "prompt-root"
-	| "agents"
+	| "agent-root"
+	| "fleet-root"
 	| "safety"
 	| "memory";
 
@@ -265,18 +267,43 @@ function inspectResourceRoots(cwd: string, graph: CustomizationGraph): void {
 	for (const [kind, category] of [
 		["skills", "skill-root"],
 		["prompts", "prompt-root"],
+		["agents", "agent-root"],
+		["fleets", "fleet-root"],
 	] as const) {
 		try {
+			if (kind === "agents" || kind === "fleets") {
+				const builtinPath = join(
+					resolvePackageRoot(),
+					"src",
+					"domains",
+					"agents",
+					kind === "agents" ? "builtins" : "fleets",
+				);
+				graph.entries.push({
+					category,
+					id: `${kind}:builtin`,
+					scope: "builtin",
+					sourcePath: builtinPath,
+					trust: "trusted",
+					precedence: "layer",
+					reloadClass: "next-turn",
+					detail: { present: existsSync(builtinPath), source: "builtin", resourcePrecedence: 0 },
+				});
+			}
 			for (const root of defaultScopedResourceRoots(kind, cwd)) {
 				graph.entries.push({
 					category,
 					id: `${kind}:${root.scope}`,
-					scope: root.scope,
+					scope: root.scope === "package" ? "extension" : root.scope,
 					sourcePath: root.path,
 					trust: root.scope === "package" ? "untrusted" : "trusted",
-					precedence: "single",
+					precedence: "layer",
 					reloadClass: "next-turn",
-					detail: { present: existsSync(root.path), source: root.source },
+					detail: {
+						present: existsSync(root.path),
+						source: root.source,
+						...(root.precedence === undefined ? {} : { resourcePrecedence: root.precedence }),
+					},
 				});
 			}
 		} catch (err) {

package/src/cli/config.ts

@@ -4,7 +4,7 @@ import { printError } from "./shared.js";
 const HELP = `clio-coder config inspect [--json]
 
 Print the effective-customization graph: what settings, context files, rules,
-skills, prompts, agents, extensions, safety, memory, hooks, and the operator
+skills, prompts, agents, fleets, extensions, safety, memory, hooks, and the operator
 profile loaded, from where, with what precedence, trust, reload class, and
 context cost. Read-only; nothing is created.
 

package/src/cli/configure.ts

@@ -19,6 +19,8 @@ import {
 	listKnownModelsForRuntime,
 	listProviderSupportEntries,
 	type ProviderSupportEntry,
+	readTargetModelSnapshot,
+	recordTargetModelSnapshot,
 	resolveRuntimeAuthTarget,
 	supportGroupLabel,
 } from "../domains/providers/index.js";
@@ -103,6 +105,7 @@ const DEFAULT_PORTS: Record<string, number> = {
 	lemonade: 8000,
 	"anthropic-compat": 8000,
 	"openai-compat": 8000,
+	litellm: 4000,
 };
 
 interface ParsedArgs {
@@ -317,7 +320,9 @@ function printRuntimeList(includeHidden: boolean): void {
 				: runtime?.auth === "api-key"
 					? status?.available
 						? "credential"
-						: "needs-key"
+						: targetRequiresAuth({ id: entry.runtimeId, runtime: entry.runtimeId }, runtime)
+							? "needs-key"
+							: "key-optional"
 					: (runtime?.auth ?? "none");
 		rows.push({
 			group: supportGroupLabel(entry.group),
@@ -387,8 +392,8 @@ function catalogContextWindowFor(runtime: RuntimeDescriptor, modelId: string): n
 /**
  * Check the resolved model against the catalog where there is one and against
  * the target's own list where there is not. A runtime with no catalog used to
- * pass any string here while the same command wrote the live list that ruled
- * it out into `wireModels`, so the target saved as `ok` and failed on its first
+ * pass any string here while the same command had a live list that ruled it
+ * out, so the target saved as `ok` and failed on its first
  * turn. Without a catalog or a live list there is nothing to check against, and
  * the note says so rather than implying the id was verified.
  */
@@ -617,7 +622,6 @@ function buildDescriptor(
 	parts: {
 		url?: string;
 		model?: string;
-		wireModels?: string[];
 		apiKeyEnv?: string;
 		apiKeyRef?: string;
 		oauthProfile?: string;
@@ -631,19 +635,12 @@ function buildDescriptor(
 ): TargetDescriptor {
 	const descriptor: TargetDescriptor = { id, runtime: runtime.id };
 	if (parts.url) descriptor.url = parts.url;
-	const wireModels =
-		parts.wireModels?.filter((value, index, all) => value.trim().length > 0 && all.indexOf(value) === index) ?? [];
 	if (parts.model) descriptor.defaultModel = parts.model;
-	else {
-		const firstWireModel = wireModels[0];
-		if (firstWireModel) descriptor.defaultModel = firstWireModel;
-	}
 	const auth: NonNullable<TargetDescriptor["auth"]> = {};
 	if (parts.apiKeyEnv) auth.apiKeyEnvVar = parts.apiKeyEnv;
 	if (parts.apiKeyRef) auth.apiKeyRef = parts.apiKeyRef;
 	if (parts.oauthProfile) auth.oauthProfile = parts.oauthProfile;
 	if (Object.keys(auth).length > 0) descriptor.auth = auth;
-	if (wireModels.length > 0) descriptor.wireModels = wireModels;
 	if (parts.gateway) descriptor.gateway = true;
 	if (parts.lifecycle) descriptor.lifecycle = parts.lifecycle;
 	const caps: NonNullable<TargetDescriptor["capabilities"]> = {};
@@ -714,7 +711,7 @@ async function loginOAuthRuntime(rl: ReturnType<typeof createInterface>, runtime
  */
 interface WireModelInventory {
 	models: string[];
-	source: "catalog" | "probe" | "existing" | "none";
+	source: "catalog" | "probe" | "cache" | "legacy" | "none";
 	/** Per-model load state when the probe reported it. */
 	modelStates?: Readonly<Record<string, ProbeModelStatus>> | undefined;
 }
@@ -761,13 +758,21 @@ async function resolveSupportedWireModels(
 		// lists models only through probeModels still gets its ids checked.
 		const probe = await runtimeProbe(runtime, target, authToken);
 		if (probe?.ok && probe.models && probe.models.length > 0) {
+			recordTargetModelSnapshot(target, probe.models);
 			return { models: [...probe.models], source: "probe", modelStates: probe.modelStates };
 		}
 		const discovered = await runtimeProbeModels(runtime, target, authToken);
-		if (discovered.length > 0) return { models: discovered, source: "probe" };
+		if (discovered.length > 0) {
+			recordTargetModelSnapshot(target, discovered);
+			return { models: discovered, source: "probe" };
+		}
+	}
+	const cached = readTargetModelSnapshot(target);
+	if (cached && cached.models.length > 0) return { models: [...cached.models], source: "cache" };
+	if (existing?.wireModels && existing.wireModels.length > 0) {
+		recordTargetModelSnapshot(target, existing.wireModels);
+		return { models: [...existing.wireModels], source: "legacy" };
 	}
-	if (existing?.wireModels && existing.wireModels.length > 0)
-		return { models: [...existing.wireModels], source: "existing" };
 	return { models: [], source: "none" };
 }
 
@@ -905,7 +910,6 @@ async function runNonInteractive(runtime: RuntimeDescriptor, args: ParsedArgs):
 	const descriptor = buildDescriptor(runtime, args.id, {
 		...(url !== undefined ? { url } : {}),
 		...(model ? { model } : {}),
-		...(wireModels.length > 0 ? { wireModels } : {}),
 		...(apiKeyEnv !== undefined ? { apiKeyEnv } : {}),
 		...(apiKeyRef !== undefined ? { apiKeyRef } : {}),
 		...(oauthProfile !== undefined ? { oauthProfile } : {}),
@@ -966,6 +970,7 @@ async function runNonInteractive(runtime: RuntimeDescriptor, args: ParsedArgs):
 	applyConfiguration(settings);
 	updateSettings(applyConfiguration);
 	const probe = await runtimeProbe(runtime, descriptor);
+	if (probe?.ok && probe.models) recordTargetModelSnapshot(descriptor, probe.models);
 	printSummary(settings, descriptor, probe);
 	if (
 		runtime.auth === "oauth" &&
@@ -1272,10 +1277,7 @@ async function runInteractive(
 	}
 
 	let model: string | undefined = defaults.model;
-	let inventory: WireModelInventory =
-		existing?.wireModels && existing.wireModels.length > 0
-			? { models: [...existing.wireModels], source: "existing" }
-			: { models: [], source: "none" };
+	let inventory: WireModelInventory = { models: [], source: "none" };
 	const tentative = buildDescriptor(runtime, targetId, {
 		...(url !== undefined ? { url } : {}),
 		...(apiKeyEnv !== undefined ? { apiKeyEnv } : {}),
@@ -1367,7 +1369,6 @@ async function runInteractive(
 		...(apiKeyEnv !== undefined ? { apiKeyEnv } : {}),
 		...(apiKeyRef !== undefined ? { apiKeyRef } : {}),
 		...(oauthProfile !== undefined ? { oauthProfile } : {}),
-		...(wireModels.length > 0 ? { wireModels } : {}),
 		gateway: gatewayAnswer,
 		...(defaults.lifecycle !== undefined
 			? { lifecycle: defaults.lifecycle }
@@ -1395,6 +1396,7 @@ async function runInteractive(
 	}
 
 	const probe = await runtimeProbe(runtime, descriptor);
+	if (probe?.ok && probe.models) recordTargetModelSnapshot(descriptor, probe.models);
 	if (probe) {
 		process.stdout.write("\n");
 		for (const line of probeLines(descriptor, probe)) process.stdout.write(`${line}\n`);

package/src/cli/doctor-panes.ts

@@ -0,0 +1,124 @@
+import { accessSync, constants, mkdirSync } from "node:fs";
+import { readSettings } from "../core/config.js";
+import { runEventJournalRoot } from "../domains/dispatch/run-event-journal.js";
+import type { DoctorFinding } from "../domains/lifecycle/doctor.js";
+import { detectMux, MUX_METHOD_MIN_PROTOCOL, resolveSocketCandidates } from "../domains/mux/index.js";
+import { describeResolution, findPinnedTool, toolStatus } from "../domains/toolchain/index.js";
+
+/**
+ * The panes section of `clio-coder doctor`.
+ *
+ * Five rows, in the order an operator debugs them: what mode the pane layer
+ * resolved to, whether the socket answered, whether the server is new enough
+ * for the methods phase 3 uses, where the pane host binary resolves, and
+ * whether the journal directory the viewer reads is writable.
+ *
+ * No row is an error. Panes are optional: an operator who never wanted them has
+ * a healthy install without them, and doctor's exit code answers "is this
+ * install healthy". The rows that would be errors elsewhere are warnings that
+ * name the next step instead.
+ */
+
+const PANE_HOST_TOOL_ID = "herdr";
+
+/** Highest protocol any method Clio drives requires, for the version row. */
+const REQUIRED_PROTOCOL = Math.max(...Object.values(MUX_METHOD_MIN_PROTOCOL));
+
+function journalWritabilityFinding(root = runEventJournalRoot()): DoctorFinding {
+	try {
+		// The viewer reads this tree and the journal writes it, so the useful
+		// question is whether it can exist and be written, not whether it does.
+		mkdirSync(root, { recursive: true });
+		accessSync(root, constants.W_OK);
+		return { ok: true, name: "panes journal dir", detail: `${root} is writable` };
+	} catch (error) {
+		return {
+			ok: true,
+			level: "warn",
+			name: "panes journal dir",
+			detail: `${root} is not writable (${error instanceof Error ? error.message : String(error)}); \`clio-coder fleet view\` will have no transcript to follow`,
+		};
+	}
+}
+
+export async function panesFindings(env: NodeJS.ProcessEnv = process.env): Promise<DoctorFinding[]> {
+	let enabled: "auto" | "embedded" | "off" = "off";
+	try {
+		enabled = readSettings().panes.enabled;
+	} catch {
+		// An unreadable settings file is already reported by the settings row;
+		// this section answers on the shipped default (off) rather than throwing.
+	}
+
+	// Inactive by choice is a different answer from unavailable. With the
+	// setting off, detection is skipped the same way the boot skips it, and the
+	// row names the two ways to turn the extension on instead of warning about
+	// a socket nobody asked for.
+	if (enabled === "off") {
+		return [
+			{
+				ok: true,
+				name: "panes mode",
+				detail:
+					"off by choice (panes.enabled=off); start `clio-coder --with-panes` for one session, or set panes.enabled=auto",
+			},
+			journalWritabilityFinding(),
+		];
+	}
+
+	// Detection is the same ladder the interactive boot runs, so this row is the
+	// answer that boot would get. It opens a socket and nothing else: no file is
+	// created and no pane is touched.
+	const { detection, client } = await detectMux({ enabled, env });
+	await client?.close().catch(() => undefined);
+
+	const candidates = detection.candidates.length > 0 ? detection.candidates : resolveSocketCandidates(env);
+	const findings: DoctorFinding[] = [
+		{
+			ok: true,
+			level: detection.mode === "none" ? "warn" : "ok",
+			name: "panes mode",
+			detail: `${detection.mode} (panes.enabled=${enabled}); ${detection.reason}`,
+		},
+		{
+			ok: true,
+			level: detection.socketPath === null ? "warn" : "ok",
+			name: "panes socket",
+			detail:
+				detection.socketPath === null
+					? `no socket answered; tried ${candidates.length > 0 ? candidates.join(", ") : "no candidates"}`
+					: `${detection.socketPath} answered a ping`,
+		},
+	];
+
+	const server = detection.server;
+	findings.push({
+		ok: true,
+		level: server === null || server.protocol < REQUIRED_PROTOCOL ? "warn" : "ok",
+		name: "panes protocol",
+		detail:
+			server === null
+				? `unknown; Clio's optional methods need protocol ${REQUIRED_PROTOCOL} or newer`
+				: `server ${server.version}, protocol ${server.protocol}; Clio's optional methods need ${REQUIRED_PROTOCOL} (${server.protocol >= REQUIRED_PROTOCOL ? "satisfied" : "toasts and agent focus fall back"})`,
+	});
+
+	const entry = findPinnedTool(PANE_HOST_TOOL_ID);
+	findings.push(
+		entry === null
+			? {
+					ok: true,
+					level: "warn",
+					name: "panes binary",
+					detail: `${PANE_HOST_TOOL_ID} is not in the pinned tool registry`,
+				}
+			: {
+					ok: true,
+					level: toolStatus(entry).resolution.source === "none" ? "warn" : "ok",
+					name: "panes binary",
+					detail: describeResolution(toolStatus(entry)),
+				},
+	);
+
+	findings.push(journalWritabilityFinding());
+	return findings;
+}