@iowarp/clio-coder 0.4.0 → 0.4.2

package/src/cli/docs.ts

@@ -1,13 +1,13 @@
 import { spawn } from "node:child_process";
-import { createReadStream, readdirSync, statSync } from "node:fs";
+import { createReadStream, readdirSync, realpathSync, statSync } from "node:fs";
 import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
 import type { AddressInfo } from "node:net";
 import { relative, resolve } from "node:path";
 import chalk from "chalk";
 import { resolvePackageRoot } from "../core/package-root.js";
-import { printError, printHeader } from "./shared.js";
+import { printError, printHeader } from "./argv.js";
 
-// Human-facing viewer over the bundled HTML blueprints. It binds an ephemeral
+// Human-facing viewer over the source-checkout HTML blueprints. It binds an ephemeral
 // static file server to 127.0.0.1 only, serves docs/html/index.html as the
 // menu plus the blueprint pages, prints the URL, and runs until SIGINT. It
 // uses only Node's built-in http and fs: zero new dependencies, no daemon, no
@@ -21,7 +21,8 @@ const HELP = `clio-coder docs [topic] [--no-open]
 
 Serve Clio Coder's interactive HTML documentation locally and open it in a
 browser. The blueprints live in docs/html of a source checkout; the npm package
-ships the Markdown guides in docs/ only. The server binds an ephemeral port on
+ships the categorized Markdown reference tree under docs/ and excludes HTML.
+The server binds an ephemeral port on
 127.0.0.1, keeps no state, runs no daemon, and reaches no external network.
 Press Ctrl+C to stop it.
 
@@ -64,13 +65,13 @@ export interface DocsMenuEntry {
 	label: string;
 }
 
-/** Resolve docs/html from the package root; present in a source checkout, absent from the npm package. */
-export function resolveDocsHtmlDir(): string {
+/** Resolve the source-checkout HTML root. The npm package deliberately excludes it. */
+function resolveDocsHtmlDir(): string {
 	return resolve(resolvePackageRoot(), "docs", "html");
 }
 
 /** Content-type for a file path by extension. Pure. Defaults to octet-stream. */
-export function contentTypeFor(filePath: string): string {
+function contentTypeFor(filePath: string): string {
 	const dot = filePath.lastIndexOf(".");
 	if (dot === -1) return "application/octet-stream";
 	return CONTENT_TYPES[filePath.slice(dot).toLowerCase()] ?? "application/octet-stream";
@@ -82,7 +83,7 @@ export function contentTypeFor(filePath: string): string {
  * to `index.html`, and rejects any traversal segment so a request can never
  * escape the served directory.
  */
-export function resolveRequestPath(rawUrl: string): { ok: true; relative: string } | { ok: false; reason: string } {
+function resolveRequestPath(rawUrl: string): { ok: true; relative: string } | { ok: false; reason: string } {
 	const pathPart = (rawUrl.split(/[?#]/, 1)[0] ?? "").trim();
 	let decoded: string;
 	try {
@@ -112,7 +113,7 @@ function titleize(topic: string): string {
  * the file-name list, not the directory. `index.html` is the menu itself and is
  * excluded; a trailing `_blueprint` is stripped from the topic key.
  */
-export function synthesizeMenu(fileNames: ReadonlyArray<string>): DocsMenuEntry[] {
+function synthesizeMenu(fileNames: ReadonlyArray<string>): DocsMenuEntry[] {
 	const entries: DocsMenuEntry[] = [];
 	for (const name of fileNames) {
 		if (!name.toLowerCase().endsWith(".html")) continue;
@@ -129,7 +130,7 @@ export function synthesizeMenu(fileNames: ReadonlyArray<string>): DocsMenuEntry[
  * topic (`safety`), the blueprint file stem (`safety_blueprint`), or a full
  * `.html` name, case-insensitively. Returns null when nothing matches.
  */
-export function topicToFile(topic: string, fileNames: ReadonlyArray<string>): string | null {
+function topicToFile(topic: string, fileNames: ReadonlyArray<string>): string | null {
 	const wanted = topic
 		.trim()
 		.toLowerCase()
@@ -159,8 +160,8 @@ function listHtmlFiles(htmlDir: string): string[] {
 }
 
 /** Build the static request handler for one html root. */
-function createDocsRequestHandler(htmlDir: string): (req: IncomingMessage, res: ServerResponse) => void {
-	const root = resolve(htmlDir);
+export function createDocsRequestHandler(htmlDir: string): (req: IncomingMessage, res: ServerResponse) => void {
+	const root = realpathSync(resolve(htmlDir));
 	return (req, res) => {
 		if (req.method !== "GET" && req.method !== "HEAD") {
 			res.writeHead(405, { "content-type": "text/plain; charset=utf-8", allow: "GET, HEAD" });
@@ -174,20 +175,27 @@ function createDocsRequestHandler(htmlDir: string): (req: IncomingMessage, res:
 			res.end(resolved.reason);
 			return;
 		}
-		const target = resolve(root, resolved.relative);
-		if (!isWithin(target, root)) {
+		const requestedTarget = resolve(root, resolved.relative);
+		if (!isWithin(requestedTarget, root)) {
 			res.writeHead(403, { "content-type": "text/plain; charset=utf-8" });
 			res.end("forbidden");
 			return;
 		}
 		let size: number | null = null;
+		let target: string | null = null;
 		try {
+			target = realpathSync(requestedTarget);
+			if (!isWithin(target, root)) {
+				res.writeHead(403, { "content-type": "text/plain; charset=utf-8" });
+				res.end("forbidden");
+				return;
+			}
 			const stat = statSync(target);
 			if (stat.isFile()) size = stat.size;
 		} catch {
 			size = null;
 		}
-		if (size === null) {
+		if (size === null || target === null) {
 			res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
 			res.end("not found");
 			return;
@@ -227,7 +235,7 @@ export interface StartDocsServerOptions {
 }
 
 /** Start the viewer bound to 127.0.0.1 on an ephemeral port. */
-export async function startDocsServer(options: StartDocsServerOptions): Promise<DocsServerHandle> {
+async function startDocsServer(options: StartDocsServerOptions): Promise<DocsServerHandle> {
 	const host = options.host ?? HOST;
 	const server = createServer(createDocsRequestHandler(options.htmlDir));
 	await new Promise<void>((resolveListen, rejectListen) => {
@@ -263,7 +271,7 @@ function openBrowser(url: string): void {
 	}
 }
 
-function waitForShutdown(): Promise<void> {
+export function waitForShutdown(): Promise<void> {
 	return new Promise((resolveShutdown) => {
 		const onSignal = (): void => {
 			process.removeListener("SIGINT", onSignal);
@@ -304,14 +312,14 @@ export async function runDocsCommand(args: ReadonlyArray<string> = []): Promise<
 	try {
 		htmlDir = resolveDocsHtmlDir();
 	} catch (err) {
-		printError(`could not resolve bundled docs: ${err instanceof Error ? err.message : String(err)}`);
+		printError(`could not resolve the docs HTML root: ${err instanceof Error ? err.message : String(err)}`);
 		return 1;
 	}
 	const files = listHtmlFiles(htmlDir);
 	if (files.length === 0) {
 		printError(`no HTML docs at ${htmlDir}`);
 		process.stdout.write(
-			`  the npm package ships the Markdown guides only: ${resolve(resolvePackageRoot(), "docs")}\n` +
+			`  the npm package ships only the categorized Markdown reference tree: ${resolve(resolvePackageRoot(), "docs")}\n` +
 				"  the interactive blueprints are in a source checkout and at https://github.com/iowarp/clio-coder/tree/main/docs/html\n",
 		);
 		return 1;
@@ -333,7 +341,7 @@ export async function runDocsCommand(args: ReadonlyArray<string> = []): Promise<
 	const handle = await startDocsServer({ htmlDir });
 	const landingUrl = landing === "index.html" ? handle.url : `${handle.url}${landing}`;
 	printHeader("Clio docs viewer");
-	process.stdout.write(`  serving ${htmlDir}\n`);
+	process.stdout.write(`  serving HTML root ${htmlDir}\n`);
 	process.stdout.write(`  open ${chalk.cyan(landingUrl)}\n`);
 	process.stdout.write("  bound to 127.0.0.1 only: no external network, no daemon, no state.\n");
 	process.stdout.write("  press Ctrl+C to stop.\n");

package/src/cli/doctor-naming.ts

@@ -0,0 +1,323 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { parse as parseYaml } from "yaml";
+import { withSettingsLock } from "../core/config.js";
+import { resolveClioDirs } from "../core/xdg.js";
+import type { DoctorFinding } from "../domains/lifecycle/doctor.js";
+import {
+	migrateNamingSettingsFile,
+	transformNamingSettingsDocument,
+} from "../domains/lifecycle/migrations/2026-09-01-clio-coder-naming.js";
+import { inspectNamingHistory } from "../domains/lifecycle/naming-history.js";
+import {
+	inspectInstalledNamingResources,
+	inspectModelOverlayNaming,
+	inspectSkillMetadataNaming,
+} from "../domains/lifecycle/naming-resources.js";
+import { inspectToolMarkerNaming } from "../domains/lifecycle/naming-tool-markers.js";
+import { inspectYaziNaming, regenerateYaziNamingProfile } from "../domains/lifecycle/naming-yazi.js";
+
+export interface NamingDoctorOptions {
+	fix?: boolean;
+	cwd?: string;
+	yaziEnabled?: boolean;
+}
+
+interface SettingsNamingInspection {
+	path: string;
+	legacy: number;
+	conflicts: number;
+	error: string | null;
+}
+
+const LEGACY_ENVIRONMENT_NAMES = [
+	["CLIO_EVAL_RUNNER_STDOUT_FILE", "CLIO_CODER_EVAL_RUNNER_STDOUT_FILE"],
+	["CLIO_YAZI_PICK_TOKEN", "CLIO_CODER_YAZI_PICK_TOKEN"],
+] as const;
+
+function namingEnvironmentFindings(
+	yaziEnabled: boolean,
+	environment: NodeJS.ProcessEnv = process.env,
+): DoctorFinding[] {
+	const present = LEGACY_ENVIRONMENT_NAMES.filter(
+		([legacy]) => (yaziEnabled || legacy !== "CLIO_YAZI_PICK_TOKEN") && Boolean(environment[legacy]?.trim()),
+	);
+	if (present.length === 0) {
+		return [{ ok: true, name: "naming environment", detail: "no legacy Clio Coder environment variables are set" }];
+	}
+	return present.map(([legacy, canonical]) => ({
+		ok: true,
+		level: "warn",
+		name: "naming environment",
+		detail: `${legacy} is deprecated; use ${canonical} (compatibility ends in v0.7.0)`,
+	}));
+}
+
+function namingResourceFindings(options: NamingDoctorOptions): DoctorFinding[] {
+	try {
+		const resourceOptions = {
+			...(options.cwd ? { cwd: options.cwd } : {}),
+			...(options.fix !== undefined ? { fix: options.fix } : {}),
+		};
+		const resources = inspectInstalledNamingResources(resourceOptions);
+		const legacyResources = resources.filter((entry) => entry.status !== "absent");
+		const rootOptions = options.cwd ? { cwd: options.cwd } : {};
+		const skillMetadata = inspectSkillMetadataNaming(rootOptions).filter((entry) => entry.legacyMetadataKey);
+		const overlays = inspectModelOverlayNaming(rootOptions).filter(
+			(entry) => entry.legacyFile || entry.legacyMetadataKeys > 0,
+		);
+		if (legacyResources.length === 0 && skillMetadata.length === 0 && overlays.length === 0) {
+			return [{ ok: true, name: "naming resources", detail: "installed skills and model overlays use canonical names" }];
+		}
+		const renamed = legacyResources.filter((entry) => entry.status === "renamed").length;
+		const renamable = legacyResources.filter((entry) => entry.status === "renamable").length;
+		const conflicts = legacyResources.filter(
+			(entry) => entry.status === "modified" || entry.status === "canonical-present",
+		).length;
+		return [
+			{
+				ok: true,
+				level:
+					renamed > 0 && renamable === 0 && conflicts === 0 && skillMetadata.length === 0 && overlays.length === 0
+						? "ok"
+						: "warn",
+				name: "naming resources",
+				detail: [
+					`${renamed} proven skills renamed`,
+					`${renamable} proven skills await doctor --fix`,
+					`${conflicts} modified/conflicting skills left untouched`,
+					`${skillMetadata.length} legacy skill metadata keys${skillMetadata.length > 0 ? ` (rename \`clio:\` to \`clio-coder:\` in ${skillMetadata.map((entry) => entry.path).join(", ")})` : ""}`,
+					`${overlays.length} legacy model overlay files/metadata (manual migration required)`,
+				].join("; "),
+			},
+		];
+	} catch (error) {
+		return [
+			{
+				ok: false,
+				name: "naming resources",
+				detail: `resource naming inspection failed: ${error instanceof Error ? error.message : String(error)}`,
+			},
+		];
+	}
+}
+
+function inspectSettingsNaming(path: string): SettingsNamingInspection {
+	if (!existsSync(path)) return { path, legacy: 0, conflicts: 0, error: null };
+	try {
+		const transformed = transformNamingSettingsDocument(parseYaml(readFileSync(path, "utf8")));
+		return {
+			path,
+			legacy: transformed.replacements.length,
+			conflicts: transformed.conflicts.length,
+			error: null,
+		};
+	} catch (error) {
+		return { path, legacy: 0, conflicts: 0, error: error instanceof Error ? error.message : String(error) };
+	}
+}
+
+function settingsFinding(label: string, inspection: SettingsNamingInspection, fixed: boolean): DoctorFinding {
+	if (inspection.error !== null) {
+		return {
+			ok: false,
+			name: `naming ${label}`,
+			detail: `${inspection.path} could not be inspected: ${inspection.error}`,
+		};
+	}
+	const count = inspection.legacy + inspection.conflicts;
+	if (count === 0) {
+		return { ok: true, name: `naming ${label}`, detail: `${inspection.path} has canonical settings identifiers` };
+	}
+	return {
+		ok: fixed,
+		level: fixed ? "ok" : "warn",
+		name: `naming ${label}`,
+		detail: fixed
+			? `${inspection.path}: migrated ${inspection.legacy} aliases and resolved ${inspection.conflicts} canonical collisions; backup written beside the file`
+			: `${inspection.path}: ${inspection.legacy} legacy aliases and ${inspection.conflicts} canonical collisions (run \`clio-coder doctor --fix\`)`,
+	};
+}
+
+function yaziNamingFinding(fix: boolean, enabled: boolean): DoctorFinding {
+	if (!enabled) {
+		return {
+			ok: true,
+			name: "naming files profile",
+			detail: "disabled by settings",
+		};
+	}
+	const inspection = inspectYaziNaming();
+	const legacy = inspection.legacyEvents + inspection.legacyEnvironmentNames;
+	if (legacy === 0) {
+		return {
+			ok: true,
+			name: "naming files profile",
+			detail: inspection.present
+				? `${inspection.profileDir} uses canonical event and environment identifiers`
+				: `${inspection.profileDir} is absent; the next managed open will generate canonical identifiers`,
+		};
+	}
+	if (!fix) {
+		return {
+			ok: true,
+			level: "warn",
+			name: "naming files profile",
+			detail: `${inspection.profileDir}: ${inspection.legacyEvents} legacy events and ${inspection.legacyEnvironmentNames} legacy environment names (run \`clio-coder doctor --fix\`)`,
+		};
+	}
+	const report = regenerateYaziNamingProfile();
+	return {
+		ok: report.status !== "regeneration-failed",
+		...(report.status === "regeneration-failed" ? {} : { level: "ok" as const }),
+		name: "naming files profile",
+		detail: report.detail,
+	};
+}
+
+function toolMarkerNamingFinding(fix: boolean): DoctorFinding {
+	try {
+		const reports = inspectToolMarkerNaming({ fix });
+		if (reports.length === 0) {
+			return { ok: true, name: "naming tool markers", detail: "known tool versions use canonical install markers" };
+		}
+		const fixed = reports.filter((entry) => entry.status === "renamed" || entry.status === "duplicate-removed").length;
+		const fixable = reports.filter(
+			(entry) => entry.status === "renamable" || entry.status === "agreeing-duplicate",
+		).length;
+		const manual = reports.length - fixed - fixable;
+		return {
+			ok: true,
+			level: fixed > 0 && fixable === 0 && manual === 0 ? "ok" : "warn",
+			name: "naming tool markers",
+			detail: `${fixed} validated markers fixed; ${fixable} await doctor --fix; ${manual} invalid/conflicting markers left untouched`,
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			name: "naming tool markers",
+			detail: `tool marker inspection failed: ${error instanceof Error ? error.message : String(error)}`,
+		};
+	}
+}
+
+function immutableHistoryNamingFinding(): DoctorFinding {
+	const dirs = resolveClioDirs();
+	const counts = inspectNamingHistory({ stateDir: dirs.state, dataDir: dirs.data });
+	const errors = counts.filter((entry) => entry.error !== null);
+	if (errors.length > 0) {
+		return {
+			ok: false,
+			name: "naming immutable history",
+			detail: errors.map((entry) => `${entry.area}: ${entry.error}`).join("; "),
+		};
+	}
+	const legacy = counts.reduce((sum, entry) => sum + entry.legacyIdentifiers, 0);
+	return {
+		ok: true,
+		...(legacy > 0 ? { level: "warn" as const } : {}),
+		name: "naming immutable history",
+		detail: `${counts.map((entry) => `${entry.area}=${entry.legacyIdentifiers}`).join("; ")} legacy identifiers; read-only retention, no rewrite`,
+	};
+}
+
+function legacyGitRefsFinding(cwd: string): DoctorFinding {
+	let refs: string[];
+	try {
+		refs = execFileSync(
+			"git",
+			["-C", cwd, "for-each-ref", "--format=%(refname:short)", "refs/heads/clio/task", "refs/heads/clio/compete"],
+			{ encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5_000 },
+		)
+			.split("\n")
+			.map((entry) => entry.trim())
+			.filter((entry) => /^clio\/(?:task|compete)\//u.test(entry))
+			.sort();
+	} catch {
+		refs = [];
+	}
+	if (refs.length === 0) {
+		return { ok: true, name: "naming git refs", detail: "no legacy Clio Coder task or compete refs found" };
+	}
+	const shown = refs.slice(0, 20);
+	return {
+		ok: true,
+		level: "warn",
+		name: "naming git refs",
+		detail: `${refs.length} legacy refs retained (never auto-renamed): ${shown.join(", ")}${refs.length > shown.length ? ", …" : ""}`,
+	};
+}
+
+function legacyWorktreeMarkerFinding(cwd: string): DoctorFinding {
+	const root = join(cwd, ".clio-coder", "worktrees");
+	let legacy = 0;
+	try {
+		for (const entry of readdirSync(root, { withFileTypes: true })) {
+			const candidates = entry.isFile()
+				? entry.name.endsWith(".task-owner.json")
+					? [join(root, entry.name)]
+					: []
+				: entry.isDirectory()
+					? [join(root, entry.name, ".clio-coder-compete-owner.json")]
+					: [];
+			for (const path of candidates) {
+				if (!existsSync(path)) continue;
+				const parsed = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
+				if (parsed.kind === "clio-task-worktree" || parsed.kind === "clio-compete-group") legacy += 1;
+			}
+		}
+	} catch {
+		// An absent or partially unreadable project-local worktree root is not a
+		// repair target. Proven markers remain the lifecycle readers' authority.
+	}
+	return {
+		ok: true,
+		...(legacy > 0 ? { level: "warn" as const } : {}),
+		name: "naming worktree markers",
+		detail:
+			legacy === 0
+				? "active worktree markers use canonical identifiers"
+				: `${legacy} active legacy worktree markers retained for cleanup compatibility; no automatic rewrite`,
+	};
+}
+
+/** Read-only naming-footprint settings sweep plus the sanctioned deterministic fixes. */
+export function namingFootprintFindings(options: NamingDoctorOptions = {}): DoctorFinding[] {
+	const cwd = options.cwd ?? process.cwd();
+	const userSettingsPath = join(resolveClioDirs().config, "settings.yaml");
+	const candidates = [
+		{ label: "settings user", path: userSettingsPath, lock: true },
+		{ label: "settings project", path: join(cwd, ".clio-coder", "settings.yaml"), lock: false },
+		{ label: "settings local", path: join(cwd, ".clio-coder", "settings.local.yaml"), lock: false },
+	] as const;
+	const findings: DoctorFinding[] = [];
+	for (const candidate of candidates) {
+		const before = inspectSettingsNaming(candidate.path);
+		let fixed = false;
+		if (options.fix && before.error === null && before.legacy + before.conflicts > 0) {
+			try {
+				if (candidate.lock) withSettingsLock(() => migrateNamingSettingsFile(candidate.path));
+				else migrateNamingSettingsFile(candidate.path);
+				fixed = true;
+			} catch (error) {
+				findings.push({
+					ok: false,
+					name: `naming ${candidate.label}`,
+					detail: `--fix could not migrate ${candidate.path}: ${error instanceof Error ? error.message : String(error)}`,
+				});
+				continue;
+			}
+		}
+		findings.push(settingsFinding(candidate.label, before, fixed));
+	}
+	findings.push(...namingEnvironmentFindings(options.yaziEnabled ?? true));
+	findings.push(...namingResourceFindings({ ...options, cwd }));
+	findings.push(yaziNamingFinding(Boolean(options.fix), options.yaziEnabled ?? true));
+	findings.push(toolMarkerNamingFinding(Boolean(options.fix)));
+	findings.push(immutableHistoryNamingFinding());
+	findings.push(legacyGitRefsFinding(cwd));
+	findings.push(legacyWorktreeMarkerFinding(cwd));
+	return findings;
+}

package/src/cli/doctor-panes.ts

@@ -1,6 +1,7 @@
-import { accessSync, constants, mkdirSync } from "node:fs";
+import { accessSync, constants } from "node:fs";
+import { join } from "node:path";
 import { readSettings } from "../core/config.js";
-import { runEventJournalRoot } from "../domains/dispatch/run-event-journal.js";
+import { resolveClioDirs } from "../core/xdg.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";
@@ -8,10 +9,11 @@ import { describeResolution, findPinnedTool, toolStatus } from "../domains/toolc
 /**
  * The panes section of `clio-coder doctor`.
  *
- * Five rows, in the order an operator debugs them: what mode the pane layer
+ * Six 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.
+ * for the methods phase 3 uses, where the pane host binary resolves, what the
+ * boot layout composes, 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
@@ -24,11 +26,8 @@ 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 {
+function journalWritabilityFinding(root = join(resolveClioDirs().state, "runs")): 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) {
@@ -36,15 +35,28 @@ function journalWritabilityFinding(root = runEventJournalRoot()): DoctorFinding
 			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`,
+			detail: `${root} is absent or 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";
+	let layoutRow: DoctorFinding = {
+		ok: true,
+		name: "panes layout",
+		detail: "off",
+	};
 	try {
-		enabled = readSettings().panes.enabled;
+		const panes = readSettings().interface.panes;
+		enabled = panes.enabled;
+		if (panes.layout !== "off") {
+			layoutRow = {
+				ok: true,
+				name: "panes layout",
+				detail: `${panes.layout} at boot (workers dock ${(panes.workers.ratio * 100).toFixed(0)}%, files dock ${(panes.files.ratio * 100).toFixed(0)}%)`,
+			};
+		}
 	} catch {
 		// An unreadable settings file is already reported by the settings row;
 		// this section answers on the shipped default (off) rather than throwing.
@@ -59,10 +71,9 @@ export async function panesFindings(env: NodeJS.ProcessEnv = process.env): Promi
 			{
 				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",
+				detail: "off by choice",
 			},
-			journalWritabilityFinding(),
+			layoutRow,
 		];
 	}
 
@@ -70,6 +81,7 @@ export async function panesFindings(env: NodeJS.ProcessEnv = process.env): Promi
 	// 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 });
+	const snapshot = client ? await client.snapshot().catch(() => null) : null;
 	await client?.close().catch(() => undefined);
 
 	const candidates = detection.candidates.length > 0 ? detection.candidates : resolveSocketCandidates(env);
@@ -119,6 +131,26 @@ export async function panesFindings(env: NodeJS.ProcessEnv = process.env): Promi
 				},
 	);
 
+	findings.push(layoutRow);
+	const legacyOwnedPanes =
+		snapshot?.panes.filter(
+			(pane) => pane.tokens.clio_owner === "clio:mux" && pane.tokens.clio_coder_owner !== "clio-coder:mux",
+		).length ?? 0;
+	const staleWatchTitles =
+		snapshot?.panes.filter(
+			(pane) =>
+				(pane.title === "clio watch" || pane.label === "clio watch") &&
+				(pane.tokens.clio_coder_owner === "clio-coder:mux" || pane.tokens.clio_owner === "clio:mux"),
+		).length ?? 0;
+	findings.push({
+		ok: true,
+		level: legacyOwnedPanes > 0 || staleWatchTitles > 0 ? "warn" : "ok",
+		name: "naming panes",
+		detail:
+			legacyOwnedPanes > 0 || staleWatchTitles > 0
+				? `${legacyOwnedPanes} panes carry only the legacy clio_owner=clio:mux token; ${staleWatchTitles} owned panes retain the stale 'clio watch' title; quit/cleanup recognizes both token schemes`
+				: "no legacy Clio Coder pane ownership tokens or watch titles found",
+	});
 	findings.push(journalWritabilityFinding());
 	return findings;
 }

package/src/cli/doctor-toolchain.ts

@@ -7,19 +7,31 @@ import {
 } from "../domains/mux/index.js";
 import { describeResolution, toolStatuses } from "../domains/toolchain/index.js";
 
-function yaziProfileFinding(): DoctorFinding {
+export interface ToolchainFindingOptions {
+	panesEnabled?: boolean;
+	filesEnabled?: boolean;
+}
+
+function yaziProfileFinding(enabled: boolean): DoctorFinding {
+	if (!enabled) {
+		return {
+			ok: true,
+			name: "files pane profile",
+			detail: "disabled by settings",
+		};
+	}
 	try {
 		const profile = inspectCurrentYaziProfile();
 		return {
 			ok: true,
-			name: "yazi managed profile",
+			name: "files pane profile",
 			detail: describeYaziProfile(profile),
 			level: profile.state === "current" ? "ok" : "warn",
 		};
 	} catch (error) {
 		return {
 			ok: true,
-			name: "yazi managed profile",
+			name: "files pane profile",
 			level: "warn",
 			detail: `${yaziProfileDir()} could not be inspected (${error instanceof Error ? error.message : String(error)}); user config ${userYaziConfigDir()} is separate and untouched`,
 		};
@@ -43,15 +55,24 @@ function yaziProfileFinding(): DoctorFinding {
  * being used, and a row that only said "not found" would send them looking for
  * a binary that is right there on their PATH.
  */
-export function toolchainFindings(): DoctorFinding[] {
+export function toolchainFindings(options: ToolchainFindingOptions = {}): DoctorFinding[] {
+	const panesEnabled = options.panesEnabled ?? true;
+	const filesEnabled = options.filesEnabled ?? true;
 	const tools = toolStatuses().map((status) => ({
 		ok: true,
 		name: `external tool ${status.id}`,
-		// The rejection and the remedy both live inside the shared resolution
-		// sentence, so this row and `clio-coder tools status` cannot describe the
-		// same machine differently.
-		detail: describeResolution(status),
-		level: status.resolution.source === "none" ? ("warn" as const) : ("ok" as const),
+		// Active integrations share the tools-status resolution sentence. Disabled
+		// experimental integrations stay neutral and do not advertise setup work.
+		detail:
+			(status.id === "herdr" && !panesEnabled) || (status.id === "yazi" && !filesEnabled)
+				? "experimental integration disabled by settings"
+				: describeResolution(status),
+		level:
+			(status.id === "herdr" && !panesEnabled) || (status.id === "yazi" && !filesEnabled)
+				? ("ok" as const)
+				: status.resolution.source === "none"
+					? ("warn" as const)
+					: ("ok" as const),
 	}));
-	return [...tools, yaziProfileFinding()];
+	return [...tools, yaziProfileFinding(filesEnabled)];
 }