@iowarp/clio-coder 0.4.7 → 0.4.9

package/src/domains/gateway/mcp/protocol.ts

@@ -0,0 +1,273 @@
+/**
+ * JSON-RPC 2.0 framing for the MCP stdio transport.
+ *
+ * The transport carries one JSON message per line: UTF-8 text, newline
+ * terminated, with no embedded newline. Everything here is pure: the framer
+ * accepts byte chunks and yields typed messages or one typed protocol error,
+ * and the client decides what to do with either. Invalid UTF-8 is a protocol
+ * error rather than a U+FFFD substitution, because a tool result that reached
+ * the model with silently replaced bytes would misreport what the server said.
+ */
+
+export const MCP_PROTOCOL_VERSION = "2025-06-18";
+export const DEFAULT_MAX_LINE_BYTES = 4 * 1024 * 1024;
+export const JSON_RPC_METHOD_NOT_FOUND = -32601;
+
+export type McpErrorCode = "timeout" | "closed" | "protocol" | "server" | "spawn" | "aborted" | "overload";
+
+/**
+ * Every failure the client reports carries one of the codes above. `overload`
+ * names an outbound line the client refused to queue: on its own because it
+ * exceeds the cap, or fatally because the server stopped reading its stdin.
+ */
+export class McpError extends Error {
+	override readonly name = "McpError";
+	readonly code: McpErrorCode;
+	readonly data: unknown;
+
+	constructor(code: McpErrorCode, message: string, data?: unknown) {
+		super(message);
+		this.code = code;
+		this.data = data;
+	}
+}
+
+export type JsonRpcId = number | string;
+
+export interface JsonRpcRequest {
+	jsonrpc: "2.0";
+	id: JsonRpcId;
+	method: string;
+	params?: unknown;
+}
+
+export interface JsonRpcNotification {
+	jsonrpc: "2.0";
+	method: string;
+	params?: unknown;
+}
+
+export interface JsonRpcErrorObject {
+	code: number;
+	message: string;
+	data?: unknown;
+}
+
+export interface JsonRpcResponse {
+	jsonrpc: "2.0";
+	id: JsonRpcId | null;
+	result?: unknown;
+	error?: JsonRpcErrorObject;
+}
+
+export type JsonRpcMessage =
+	| { kind: "request"; message: JsonRpcRequest }
+	| { kind: "notification"; message: JsonRpcNotification }
+	| { kind: "response"; message: JsonRpcResponse };
+
+export type ProtocolFrame = { kind: "message"; message: JsonRpcMessage } | { kind: "error"; error: McpError };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function isJsonRpcId(value: unknown): value is JsonRpcId {
+	return typeof value === "string" || (typeof value === "number" && Number.isFinite(value));
+}
+
+// Transport-only metadata cannot be supplied by a server field. The result
+// object remains the key until its pending request reaches the tool decoder.
+const structuredJson = new WeakMap<object, string>();
+
+export function structuredContentJson(result: object): string | undefined {
+	return structuredJson.get(result);
+}
+
+/** Classify one decoded JSON value as a request, notification, or response, or name why it is none of them. */
+export function classifyJsonRpcMessage(value: unknown): JsonRpcMessage | McpError {
+	if (!isRecord(value)) return new McpError("protocol", "message is not a JSON object");
+	if (value.jsonrpc !== "2.0") return new McpError("protocol", 'message lacks jsonrpc: "2.0"');
+	if (typeof value.method === "string") {
+		if (value.id === undefined || value.id === null) {
+			const notification: JsonRpcNotification = { jsonrpc: "2.0", method: value.method };
+			if (value.params !== undefined) notification.params = value.params;
+			return { kind: "notification", message: notification };
+		}
+		if (!isJsonRpcId(value.id)) return new McpError("protocol", "request id must be a string or a finite number");
+		const request: JsonRpcRequest = { jsonrpc: "2.0", id: value.id, method: value.method };
+		if (value.params !== undefined) request.params = value.params;
+		return { kind: "request", message: request };
+	}
+	const hasResult = Object.hasOwn(value, "result");
+	const hasError = Object.hasOwn(value, "error");
+	if (!hasResult && !hasError) return new McpError("protocol", "message has neither method, result, nor error");
+	if (hasResult && hasError) return new McpError("protocol", "response carries both result and error");
+	if (value.id !== null && !isJsonRpcId(value.id)) {
+		return new McpError("protocol", "response id must be a string, a finite number, or null");
+	}
+	const response: JsonRpcResponse = {
+		jsonrpc: "2.0",
+		id: value.id === undefined ? null : (value.id as JsonRpcId | null),
+	};
+	if (hasResult) response.result = value.result;
+	if (hasError) {
+		const error = value.error;
+		if (!isRecord(error) || typeof error.code !== "number" || typeof error.message !== "string") {
+			return new McpError("protocol", "response error must carry a numeric code and a message");
+		}
+		const errorObject: JsonRpcErrorObject = { code: error.code, message: error.message };
+		if (error.data !== undefined) errorObject.data = error.data;
+		response.error = errorObject;
+	}
+	return { kind: "response", message: response };
+}
+
+/** Decode one complete line (without its terminator) into a message or a protocol error. */
+export function parseJsonRpcLine(line: Buffer): JsonRpcMessage | McpError {
+	let text: string;
+	try {
+		text = new TextDecoder("utf-8", { fatal: true }).decode(line);
+	} catch {
+		return new McpError("protocol", "message line is not valid UTF-8");
+	}
+	let parsed: unknown;
+	try {
+		// Node >=22.19 supports source-aware revivers and rawJSON. Keep numeric
+		// source tokens without changing protocol IDs, schemas, or other fields.
+		const sources = new WeakMap<object, Map<string, string>>();
+		parsed = JSON.parse(text, function (this: object, key: string, value: unknown, context?: { source: string }) {
+			if (typeof value === "number") {
+				if (context?.source === undefined) throw new Error("JSON numeric source tokens are unavailable");
+				let entries = sources.get(this);
+				if (entries === undefined) {
+					entries = new Map();
+					sources.set(this, entries);
+				}
+				entries.set(key, context.source);
+			}
+			return value;
+		}) as unknown;
+		if (isRecord(parsed) && isRecord(parsed.result) && isRecord(parsed.result.structuredContent)) {
+			const content = parsed.result.structuredContent;
+			// ES2022 typings predate this supported Node runtime API. No custom
+			// tokenizer is needed, and the existing incoming-line cap bounds it.
+			const rawJSON = (JSON as JSON & { rawJSON(source: string): unknown }).rawJSON;
+			const exact = JSON.stringify(content, function (this: object, key: string, value: unknown) {
+				const source = sources.get(this)?.get(key);
+				return source === undefined ? value : rawJSON(source);
+			});
+			// Plain JSON evidence must survive cloning and serialization as well.
+			// Tag tokens that Number cannot round-trip instead of retaining rounded
+			// numbers, Infinity (which serializes to null), or a signless zero.
+			parsed.result.structuredContent = JSON.parse(
+				JSON.stringify(content, function (this: object, key: string, value: unknown) {
+					const source = sources.get(this)?.get(key);
+					return source !== undefined && JSON.stringify(value) !== source ? { $literal: source } : value;
+				}),
+			) as unknown;
+			structuredJson.set(parsed.result, exact);
+		}
+	} catch (error) {
+		return new McpError(
+			"protocol",
+			`message line is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
+	return classifyJsonRpcMessage(parsed);
+}
+
+/** Serialize one outbound message as a newline-terminated line. JSON.stringify escapes every newline inside strings. */
+export function encodeJsonRpcMessage(message: JsonRpcRequest | JsonRpcNotification | JsonRpcResponse): Buffer {
+	return Buffer.from(`${JSON.stringify(message)}\n`, "utf8");
+}
+
+export interface LineFramer {
+	/** Accept one chunk and return every frame it completed. After an error frame the framer yields nothing more. */
+	push(chunk: Buffer): ProtocolFrame[];
+	/** Flush a final unterminated line at end of stream. */
+	flush(): ProtocolFrame[];
+	/** Bytes held for the line still being assembled. */
+	readonly pendingBytes: number;
+	/** True once an error frame has been produced. */
+	readonly failed: boolean;
+}
+
+/**
+ * Split a byte stream into newline-delimited messages. A line longer than the
+ * cap is refused as soon as its bytes exceed it, before any newline arrives,
+ * so an unterminated flood cannot grow the buffer without bound. Blank lines
+ * are skipped; a trailing carriage return is tolerated.
+ */
+export function createLineFramer(maxLineBytes: number = DEFAULT_MAX_LINE_BYTES): LineFramer {
+	const pending: Buffer[] = [];
+	let pendingBytes = 0;
+	let failed = false;
+
+	const fail = (message: string): ProtocolFrame[] => {
+		failed = true;
+		pending.length = 0;
+		pendingBytes = 0;
+		return [{ kind: "error", error: new McpError("protocol", message) }];
+	};
+
+	const frameLine = (line: Buffer): ProtocolFrame | null => {
+		const trimmed = line.length > 0 && line[line.length - 1] === 0x0d ? line.subarray(0, line.length - 1) : line;
+		if (trimmed.length === 0) return null;
+		const decoded = parseJsonRpcLine(trimmed);
+		if (decoded instanceof McpError) return { kind: "error", error: decoded };
+		return { kind: "message", message: decoded };
+	};
+
+	return {
+		get pendingBytes() {
+			return pendingBytes;
+		},
+		get failed() {
+			return failed;
+		},
+		push(chunk) {
+			if (failed) return [];
+			const frames: ProtocolFrame[] = [];
+			let start = 0;
+			for (;;) {
+				const newline = chunk.indexOf(0x0a, start);
+				if (newline === -1) break;
+				const tail = chunk.subarray(start, newline);
+				const lineBytes = pendingBytes + tail.length;
+				if (lineBytes > maxLineBytes) return fail(`message line exceeds ${maxLineBytes} bytes`);
+				const line = pending.length === 0 ? tail : Buffer.concat([...pending, tail], lineBytes);
+				pending.length = 0;
+				pendingBytes = 0;
+				const frame = frameLine(line);
+				if (frame !== null) {
+					frames.push(frame);
+					if (frame.kind === "error") {
+						failed = true;
+						return frames;
+					}
+				}
+				start = newline + 1;
+			}
+			if (start < chunk.length) {
+				const rest = chunk.subarray(start);
+				if (pendingBytes + rest.length > maxLineBytes) {
+					frames.push(...fail(`message line exceeds ${maxLineBytes} bytes`));
+					return frames;
+				}
+				pending.push(Buffer.from(rest));
+				pendingBytes += rest.length;
+			}
+			return frames;
+		},
+		flush() {
+			if (failed || pendingBytes === 0) return [];
+			const line = Buffer.concat(pending, pendingBytes);
+			pending.length = 0;
+			pendingBytes = 0;
+			const frame = frameLine(line);
+			if (frame === null) return [];
+			if (frame.kind === "error") failed = true;
+			return [frame];
+		},
+	};
+}

package/src/domains/gateway/mcp/trust.ts

@@ -0,0 +1,263 @@
+/**
+ * Explicit trust for project-declared MCP servers. A repository can ship
+ * `.clio-coder/mcp.yaml`, and cloning a repository must not launch anything,
+ * so a project server runs only once the operator records a trust decision
+ * for that exact declaration. The record binds the project root, the server
+ * id, and the declaration digest: change the command, arguments, environment,
+ * cwd, or timeout and the record is stale until the operator re-trusts it.
+ * User-scope declarations are trusted by authorship; they carry no record.
+ */
+
+import { realpathSync } from "node:fs";
+import path from "node:path";
+import { safeResourceWrite } from "../../../core/safe-resource-write.js";
+import { clioConfigDir } from "../../../core/xdg.js";
+import {
+	loadMcpServerConfig,
+	type McpConfigDiagnostic,
+	type McpServerDeclaration,
+	readBoundedFileText,
+} from "./config.js";
+
+export const MCP_TRUST_FILENAME = "mcp-trust.json";
+export const MCP_TRUST_VERSION = 1;
+
+/** Bounds on the trust file, read on every resolve; a file past either is unusable until repaired. */
+export const MCP_TRUST_CAPS = Object.freeze({
+	fileBytes: 1024 * 1024,
+	records: 256,
+});
+
+export type McpTrustActionClass = "read" | "execute" | "unknown";
+export const MCP_TRUST_ACTION_CLASSES: ReadonlyArray<McpTrustActionClass> = ["read", "execute", "unknown"];
+
+export interface McpTrustRecord {
+	/** Canonical (realpath) project root the record applies to. */
+	projectRoot: string;
+	id: string;
+	digest: string;
+	/** The action class the gateway gives this server's tools. */
+	actionClass: McpTrustActionClass;
+	trustedAt: string;
+}
+
+export interface McpTrustState {
+	version: typeof MCP_TRUST_VERSION;
+	records: McpTrustRecord[];
+}
+
+export type McpTrustStatus =
+	| { status: "trusted"; actionClass: McpTrustActionClass }
+	| { status: "untrusted"; actionClass: "unknown"; reason: string }
+	| { status: "stale"; actionClass: "unknown"; reason: string };
+
+export interface ResolvedMcpServer extends McpServerDeclaration {
+	trust: McpTrustStatus;
+}
+
+export interface McpTrustOptions {
+	cwd: string;
+	/** Override for the user config directory; defaults to clioConfigDir(). */
+	configDir?: string;
+}
+
+export interface McpTrustReadResult {
+	state: McpTrustState;
+	/** Non-empty when the file exists but could not be used; the state is then empty. */
+	diagnostics: string[];
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function isActionClass(value: unknown): value is McpTrustActionClass {
+	return typeof value === "string" && (MCP_TRUST_ACTION_CLASSES as ReadonlyArray<string>).includes(value);
+}
+
+export function mcpTrustPath(configDir?: string): string {
+	return path.join(configDir ?? clioConfigDir(), MCP_TRUST_FILENAME);
+}
+
+function canonicalProjectRoot(cwd: string): string {
+	const resolved = path.resolve(cwd);
+	try {
+		return realpathSync(resolved);
+	} catch {
+		return resolved;
+	}
+}
+
+function parseTrustState(text: string): McpTrustState | Error {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(text) as unknown;
+	} catch (error) {
+		return new Error(`invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	if (!isRecord(parsed) || parsed.version !== MCP_TRUST_VERSION) {
+		return new Error(`trust state must be a version ${MCP_TRUST_VERSION} object`);
+	}
+	if (!Array.isArray(parsed.records)) return new Error("trust state records must be an array");
+	if (parsed.records.length > MCP_TRUST_CAPS.records) {
+		return new Error(`trust state exceeds the ${MCP_TRUST_CAPS.records}-record cap`);
+	}
+	const records: McpTrustRecord[] = [];
+	for (const [index, raw] of parsed.records.entries()) {
+		if (!isRecord(raw)) return new Error(`records[${index}] must be an object`);
+		for (const field of ["projectRoot", "id", "digest", "trustedAt"] as const) {
+			if (typeof raw[field] !== "string" || raw[field].length === 0) {
+				return new Error(`records[${index}].${field} must be a non-empty string`);
+			}
+		}
+		if (!isActionClass(raw.actionClass)) {
+			return new Error(`records[${index}].actionClass must be one of ${MCP_TRUST_ACTION_CLASSES.join(", ")}`);
+		}
+		records.push({
+			projectRoot: raw.projectRoot as string,
+			id: raw.id as string,
+			digest: raw.digest as string,
+			actionClass: raw.actionClass,
+			trustedAt: raw.trustedAt as string,
+		});
+	}
+	return { version: MCP_TRUST_VERSION, records };
+}
+
+/**
+ * Read the trust file through a bounded read. A missing file is an empty
+ * state; an oversized, over-populated, or corrupt one is empty with a
+ * diagnostic, and nothing here ever rewrites it.
+ */
+export function readMcpTrustState(configDir?: string): McpTrustReadResult {
+	const filePath = mcpTrustPath(configDir);
+	const empty: McpTrustState = { version: MCP_TRUST_VERSION, records: [] };
+	const read = readBoundedFileText(filePath, MCP_TRUST_CAPS.fileBytes);
+	if (!read.ok) {
+		if (read.reason === "missing") return { state: empty, diagnostics: [] };
+		return { state: empty, diagnostics: [`${filePath}: ${read.message}`] };
+	}
+	const parsed = parseTrustState(read.text);
+	if (parsed instanceof Error) return { state: empty, diagnostics: [`${filePath}: ${parsed.message}`] };
+	return { state: parsed, diagnostics: [] };
+}
+
+/** Persist the state, or name why it would not be readable again under the caps. */
+function writeTrustState(records: ReadonlyArray<McpTrustRecord>, configDir?: string): string | null {
+	if (records.length > MCP_TRUST_CAPS.records) {
+		return `trust state would exceed the ${MCP_TRUST_CAPS.records}-record cap; untrust servers you no longer use first`;
+	}
+	const sorted = [...records].sort(
+		(left, right) => left.projectRoot.localeCompare(right.projectRoot) || left.id.localeCompare(right.id),
+	);
+	const text = `${JSON.stringify({ version: MCP_TRUST_VERSION, records: sorted }, null, 2)}\n`;
+	if (Buffer.byteLength(text, "utf8") > MCP_TRUST_CAPS.fileBytes) {
+		return `trust state would exceed the ${MCP_TRUST_CAPS.fileBytes}-byte cap; untrust servers you no longer use first`;
+	}
+	safeResourceWrite(mcpTrustPath(configDir), text, { mode: 0o600 });
+	return null;
+}
+
+function trustStatusFor(server: McpServerDeclaration, projectRoot: string, state: McpTrustState): McpTrustStatus {
+	if (server.scope === "user") return { status: "trusted", actionClass: "unknown" };
+	const record = state.records.find((entry) => entry.projectRoot === projectRoot && entry.id === server.id);
+	if (record === undefined) {
+		return {
+			status: "untrusted",
+			actionClass: "unknown",
+			reason: `project-scope server '${server.id}' requires explicit trust: clio-coder mcp trust ${server.id}`,
+		};
+	}
+	if (record.digest !== server.digest) {
+		return {
+			status: "stale",
+			actionClass: "unknown",
+			reason: `declaration of '${server.id}' changed (command, args, env, cwd, or timeout) since it was trusted; review it and run clio-coder mcp trust ${server.id} again`,
+		};
+	}
+	return { status: "trusted", actionClass: record.actionClass };
+}
+
+export interface ResolvedMcpServers {
+	servers: ResolvedMcpServer[];
+	diagnostics: McpConfigDiagnostic[];
+	/** Trust-file problems, separate from config diagnostics. */
+	trustDiagnostics: string[];
+}
+
+/** Every declared server with its trust status; the gateway launches only `trusted` entries. */
+export function resolveMcpServers(options: McpTrustOptions): ResolvedMcpServers {
+	const loaded = loadMcpServerConfig(options);
+	const trust = readMcpTrustState(options.configDir);
+	const projectRoot = canonicalProjectRoot(options.cwd);
+	return {
+		servers: loaded.servers.map((server) => ({ ...server, trust: trustStatusFor(server, projectRoot, trust.state) })),
+		diagnostics: loaded.diagnostics,
+		trustDiagnostics: trust.diagnostics,
+	};
+}
+
+export interface TrustMcpServerOptions extends McpTrustOptions {
+	id: string;
+	actionClass?: McpTrustActionClass;
+	now?: () => Date;
+}
+
+export type TrustMcpServerResult = { ok: true; record: McpTrustRecord } | { ok: false; message: string };
+
+/** Record trust for one project-declared server at its current digest. */
+export function trustMcpServer(options: TrustMcpServerOptions): TrustMcpServerResult {
+	const actionClass = options.actionClass ?? "unknown";
+	if (!isActionClass(actionClass)) {
+		return { ok: false, message: `actionClass must be one of ${MCP_TRUST_ACTION_CLASSES.join(", ")}` };
+	}
+	const loaded = loadMcpServerConfig(options);
+	const server = loaded.servers.find((entry) => entry.id === options.id);
+	if (server === undefined) {
+		const problems = loaded.diagnostics.map((entry) => `${entry.path}: ${entry.message}`);
+		return {
+			ok: false,
+			message:
+				`no declared MCP server with id '${options.id}'` +
+				(problems.length > 0 ? `; config diagnostics: ${problems.join("; ")}` : ""),
+		};
+	}
+	if (server.scope !== "project") {
+		return { ok: false, message: `server '${options.id}' is a user-scope declaration; it is trusted by authorship` };
+	}
+	const trust = readMcpTrustState(options.configDir);
+	if (trust.diagnostics.length > 0) {
+		return { ok: false, message: `trust state is unusable; repair or remove it first: ${trust.diagnostics.join("; ")}` };
+	}
+	const projectRoot = canonicalProjectRoot(options.cwd);
+	const record: McpTrustRecord = {
+		projectRoot,
+		id: server.id,
+		digest: server.digest,
+		actionClass,
+		trustedAt: (options.now?.() ?? new Date()).toISOString(),
+	};
+	const records = trust.state.records.filter((entry) => !(entry.projectRoot === projectRoot && entry.id === server.id));
+	records.push(record);
+	const refused = writeTrustState(records, options.configDir);
+	if (refused !== null) return { ok: false, message: refused };
+	return { ok: true, record };
+}
+
+export type UntrustMcpServerResult = { ok: true; removed: boolean } | { ok: false; message: string };
+
+/** Remove the trust record for one server in this project, whether or not it is still declared. */
+export function untrustMcpServer(options: McpTrustOptions & { id: string }): UntrustMcpServerResult {
+	const trust = readMcpTrustState(options.configDir);
+	if (trust.diagnostics.length > 0) {
+		return { ok: false, message: `trust state is unusable; repair or remove it first: ${trust.diagnostics.join("; ")}` };
+	}
+	const projectRoot = canonicalProjectRoot(options.cwd);
+	const records = trust.state.records.filter((entry) => !(entry.projectRoot === projectRoot && entry.id === options.id));
+	const removed = records.length !== trust.state.records.length;
+	if (removed) {
+		const refused = writeTrustState(records, options.configDir);
+		if (refused !== null) return { ok: false, message: refused };
+	}
+	return { ok: true, removed };
+}

package/src/domains/lifecycle/doctor.ts

@@ -482,7 +482,10 @@ export function formatDoctorReport(findings: DoctorFinding[]): string {
  * to the durable preflight store that dispatch placement consults. A failing
  * node is a WARN (ineligible for placement), never fatal.
  */
-export async function runDoctorFleetChecks(projectRoot: string = process.cwd()): Promise<DoctorFinding[]> {
+export async function runDoctorFleetChecks(
+	projectRoot: string = process.cwd(),
+	options: { fix?: boolean } = {},
+): Promise<DoctorFinding[]> {
 	let settings: ReturnType<typeof readSettings>;
 	try {
 		settings = readSettings();
@@ -491,7 +494,7 @@ export async function runDoctorFleetChecks(projectRoot: string = process.cwd()):
 	}
 	const nodes = settings.fleet?.nodes ?? [];
 	if (nodes.length === 0) return [];
-	const { runFleetNodePreflight } = await import("../dispatch/fleet-preflight.js");
+	const { recordFleetPreflight, runFleetNodePreflight } = await import("../dispatch/fleet-preflight.js");
 	// Endpoint facts are per node. Every configured target is probed from every
 	// node, because a `localhost` URL names a different machine on each one and
 	// an orchestrator-side probe would describe none of them.
@@ -502,12 +505,23 @@ export async function runDoctorFleetChecks(projectRoot: string = process.cwd()):
 		...(target.defaultModel !== undefined ? { wireModelId: target.defaultModel } : {}),
 	}));
 	const records = await Promise.all(nodes.map((node) => runFleetNodePreflight(node, projectRoot, { targets })));
+	// Placement admits a node only from a stored record. Plain doctor observes;
+	// --fix is the run that may write state, so it is the one that records.
+	let recorded = options.fix === true;
+	if (recorded) {
+		try {
+			recordFleetPreflight(records);
+		} catch {
+			recorded = false;
+		}
+	}
+	const admission = recorded ? "recorded for dispatch" : "not recorded, run doctor --fix to admit this node";
 	return records.map((record) => ({
 		ok: true,
 		level: record.ok ? "ok" : "warn",
 		name: `fleet node ${record.nodeId}`,
 		detail: record.ok
-			? `eligible: ${record.host} clio ${record.remoteVersion ?? "(custom entry)"}, path parity for ${record.projectRoot}, ${
+			? `eligible (${admission}): ${record.host} clio ${record.remoteVersion ?? "(custom entry)"}, path parity for ${record.projectRoot}, ${
 					record.targets.filter((fact) => fact.reachable === "true").length
 				}/${record.targets.length} targets reachable from the node`
 			: `ineligible: ${record.detail ?? "preflight failed"}`,

package/src/domains/middleware/hooks.ts

@@ -10,8 +10,8 @@
  *
  * There is no arbitrary script execution: `command` takes an argv array and is
  * run without a shell, so there is no string to inject into. Hooks never
- * replace the safety policy. They register after the guard hooks and can only
- * add effects (including requesting `block_tool`); the durable safety contract
+ * replace the safety policy. They can only add effects (including requesting
+ * `block_tool`); the durable safety contract
  * still classifies every tool call independently and a hook cannot grant a
  * permission safety would deny.
  *

package/src/domains/mux/contract.ts

@@ -11,16 +11,12 @@
  * created, tracked in `pane-registry.ts` and tagged with the `clio_coder_owner`
  * metadata token so `clio-coder doctor` can find orphans. The one documented
  * exception is Clio's own hosting pane in guest mode, which `reportSelf`
- * writes to under SA-3 of the v0.4.0 cycle plan.
+ * writes to without requiring Clio ownership.
  *
- * What is deliberately absent: per-run viewer panes. The v0.4.0 phase 3/4
- * integration opened a pane per dispatched run in a hidden Fleet tab, with a
- * focus ladder, run-state reporting, and resume adoption keyed on run ids. All
- * of that projected fleet state the native surfaces already show onto panes
- * nobody had asked for. The one run-viewing surface is now the workers-view
- * watch pane (src/interactive/watch-pane.ts): a single utility pane following
- * a selection file, opened on operator demand and retargeted by file writes
- * that never touch this socket.
+ * Runs are viewed through the workers-view watch pane
+ * (src/interactive/watch-pane.ts). This single utility pane follows a selection
+ * file, opens on operator demand, and is retargeted by file writes that never
+ * touch this socket. Dispatch does not create per-run viewer panes.
  */
 
 import type { DomainContract } from "../../core/domain-loader.js";

package/src/domains/mux/detect.ts

@@ -8,7 +8,7 @@
  * contract test pins that by making `net.connect` throw for the duration of the
  * call.
  *
- * Embedded mode resolves to `none` until Phase 5 lands the session bootstrap.
+ * Embedded pane hosting is not implemented, so it resolves to `none`.
  * Asking for it is not an error, but it is a refusal rather than a quiet
  * degrade: the detection carries `refused: true`, the boot prints the reason on
  * stderr, and doctor's mode row warns. A session that asked for panes and got

package/src/domains/mux/extension.ts

@@ -14,7 +14,7 @@ import { detectMux, type MuxEnablement } from "./detect.js";
 import type { MuxLog } from "./types.js";
 
 export interface MuxDomainOptions {
-	/** `off` skips detection entirely; `embedded` degrades to `none` until phase 5. */
+	/** `off` skips detection; unsupported `embedded` hosting is refused as `none`. */
 	enabled?: MuxEnablement;
 	env?: NodeJS.ProcessEnv;
 	log?: MuxLog;

package/src/domains/mux/protocol.ts

@@ -1,12 +1,10 @@
 /**
  * Protocol floors for the wire methods that are not universal.
  *
- * Phase 1 recorded `protocol` and `version` from the `ping` handshake and gated
- * nothing on them, because every method phase 1 used exists across the whole
- * protocol range Clio cares about. Phase 3 adds two that do not, and Phase 4
- * adds the worktree family: a herdr old
- * enough to predate them answers `invalid_request`, and the honest response is
- * to take the documented fallback rather than to log a failure per call.
+ * The `ping` handshake records the server protocol and version. Notification,
+ * pane-control, layout, and worktree methods require the protocol floors below.
+ * Older servers answer `invalid_request`, so callers check support and take
+ * the documented fallback before making those calls.
  *
  * The floors are protocol introductions checked against herdr's changelog and
  * then re-verified with `herdr api schema --json` on the released artifacts
@@ -24,7 +22,7 @@
 
 import type { MuxServerInfo } from "./types.js";
 
-/** Wire methods this file gates. Phase 1 methods are unconditional and absent here. */
+/** Wire methods with explicit protocol floors. Basic discovery methods are unconditional. */
 export type MuxGatedMethod =
 	| "notification.show"
 	| "pane.rename"

package/src/domains/mux/socket-client.ts

@@ -175,9 +175,9 @@ export interface MuxWorktreeRemovedResult {
 }
 
 /**
- * The domain-facing surface. Phase 1 covers exactly the wire methods spec 4.3
- * lists for this phase, plus `pane.send_text`, `pane.report_agent`,
- * `pane.report_metadata` (see the notes on those methods below).
+ * The domain-facing wire surface covers discovery, workspace and pane control,
+ * notifications, layouts, worktrees, and agent metadata. Individual methods
+ * document their protocol requirements and behavior below.
  */
 export interface MuxClient {
 	readonly socketPath: string;