@iowarp/clio-coder 0.4.4 → 0.4.5

package/src/domains/eval/verifiers/integrity.ts

@@ -0,0 +1,39 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+
+export class EvalGraderIntegrityError extends Error {}
+
+/** Explicit dependencies avoid guessing executable paths from arbitrary shell commands. */
+export async function protectGraderFiles(cwd: string, files: readonly string[]): Promise<() => Promise<void>> {
+	const paths = files.map((file) => {
+		const path = resolve(cwd, file);
+		const rel = relative(cwd, path);
+		if (isAbsolute(file) || rel === ".." || rel.startsWith(`..${sep}`))
+			throw new EvalGraderIntegrityError(`grader dependency escapes workspace: ${file}`);
+		return path;
+	});
+	const fingerprint = async (path: string) => {
+		// Do not follow a replacement symlink to content chosen outside the fixture.
+		let current = path;
+		while (current !== resolve(cwd)) {
+			if ((await lstat(current)).isSymbolicLink())
+				throw new EvalGraderIntegrityError(`grader dependency is a symlink: ${path}`);
+			current = resolve(current, "..");
+		}
+		return createHash("sha256")
+			.update(await readFile(path))
+			.digest("hex");
+	};
+	const hashes = await Promise.all(paths.map(fingerprint));
+	return async () => {
+		for (const [index, path] of paths.entries()) {
+			try {
+				if ((await fingerprint(path)) === hashes[index]) continue;
+			} catch {
+				/* Missing, unreadable, and replaced dependencies all invalidate grading. */
+			}
+			throw new EvalGraderIntegrityError(`grader dependency changed during trial: ${relative(cwd, path)}`);
+		}
+	};
+}

package/src/domains/eval/verifiers/patch.ts

@@ -1,4 +1,43 @@
 import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { readdirSync, readFileSync, readlinkSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+type FileBaseline = Map<string, { hash: string; bytes: number }>;
+const baselines = new Map<string, FileBaseline>();
+
+/** Held by the harness process so a runner cannot rewrite its own baseline. */
+export function recordPatchBaseline(cwd: string): void {
+	baselines.set(resolve(cwd), snapshotFiles(cwd));
+}
+
+export function forgetPatchBaseline(cwd: string): void {
+	baselines.delete(resolve(cwd));
+}
+
+function snapshotFiles(cwd: string): FileBaseline {
+	const files: FileBaseline = new Map();
+	function walk(dir: string, prefix: string): void {
+		for (const entry of readdirSync(dir, { withFileTypes: true })) {
+			if (entry.name === ".git") continue;
+			const path = join(dir, entry.name);
+			const relative = prefix + entry.name;
+			if (entry.isDirectory()) walk(path, `${relative}/`);
+			else if (entry.isFile() || entry.isSymbolicLink()) {
+				const bytes = entry.isSymbolicLink() ? Buffer.from(readlinkSync(path)) : readFileSync(path);
+				files.set(relative, {
+					hash: createHash("sha256")
+						.update(entry.isSymbolicLink() ? "link:" : "file:")
+						.update(bytes)
+						.digest("hex"),
+					bytes: bytes.length,
+				});
+			}
+		}
+	}
+	walk(cwd, "");
+	return files;
+}
 
 export interface PatchMetrics {
 	bytes: number;
@@ -6,9 +45,26 @@ export interface PatchMetrics {
 	testFilesModified: number;
 }
 
-export function collectPatchMetrics(cwd: string): PatchMetrics {
+export function collectPatchMetrics(cwd: string): PatchMetrics | null {
+	const baseline = baselines.get(resolve(cwd));
+	if (baseline !== undefined) {
+		const current = snapshotFiles(cwd);
+		const changed = [...new Set([...baseline.keys(), ...current.keys()])].filter(
+			(path) => baseline.get(path)?.hash !== current.get(path)?.hash,
+		);
+		return {
+			// For hash baselines this is changed file content bytes, including deleted
+			// content, rather than a textual Git diff (which cannot represent all files).
+			bytes: changed.reduce((sum, path) => sum + (current.get(path)?.bytes ?? baseline.get(path)?.bytes ?? 0), 0),
+			filesChanged: changed.length,
+			testFilesModified: changed.filter((file) => /(^|\/)(test|tests|spec|__tests__)(\/|$)|\.(test|spec)\./.test(file))
+				.length,
+		};
+	}
+
 	const diff = spawnSync("git", ["diff", "--", "."], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
-	const text = diff.status === 0 && typeof diff.stdout === "string" ? diff.stdout : "";
+	if (diff.status !== 0 || typeof diff.stdout !== "string") return null;
+	const text = diff.stdout;
 	const files = text
 		.split(/\r?\n/)
 		.filter((line) => line.startsWith("diff --git "))

package/src/domains/eval/workspaces/temp-copy.ts

@@ -4,6 +4,7 @@ import { tmpdir } from "node:os";
 import { relative, resolve } from "node:path";
 import { promisify } from "node:util";
 import type { EvalWorkspaceV2 } from "../schema/suite.js";
+import { forgetPatchBaseline, recordPatchBaseline } from "../verifiers/patch.js";
 import type { PreparedEvalWorkspace } from "./local.js";
 
 const execFileAsync = promisify(execFile);
@@ -42,9 +43,11 @@ export async function prepareTempCopyWorkspace(
 			recursive: true,
 			filter: (path) => shouldCopy(relative(source, path), excludes, selection),
 		});
+		recordPatchBaseline(dest);
 		return {
 			dir: dest,
 			cleanup: async () => {
+				forgetPatchBaseline(dest);
 				await rm(dest, { recursive: true, force: true });
 			},
 		};

package/src/domains/evidence/build.ts

@@ -1473,11 +1473,13 @@ function renderSessionTranscriptEntry(linked: LinkedSessionEntry): string[] {
 				const label = decision.label === undefined ? "" : ` label=${previewUnknown(decision.label)}`;
 				const sourceQuestion =
 					decision.source_question === undefined ? "" : ` sourceQuestion=${previewUnknown(decision.source_question)}`;
-				const revision = decision.revisedAt === undefined ? "" : ` revisedAt=${decision.revisedAt} revisionSource=operator`;
+				const revisionSource = decision.revisionSource ?? "unknown";
+				const revision =
+					decision.revisedAt === undefined ? "" : ` revisedAt=${decision.revisedAt} revisionSource=${revisionSource}`;
 				const correction =
 					decision.correction === undefined
 						? ""
-						: ` correctionSource=operator correction=${previewUnknown(decision.correction)}`;
+						: ` correctionSource=${revisionSource} correction=${previewUnknown(decision.correction)}`;
 				return `  decision key=${decision.key} status=${decision.status} decidedAt=${decision.decidedAt}${revision}${label}${sourceQuestion} value=${previewUnknown(decision.value)}${correction}`;
 			}),
 		];

package/src/domains/interop/registry.ts

@@ -19,7 +19,7 @@ export const INTEROP_AGENT_KINDS: ReadonlyArray<InteropAgentKind> = [
 		instructionFiles: ["CLAUDE.md", ".claude/CLAUDE.md"],
 		acp: {
 			command: "npx",
-			args: ["-y", "@zed-industries/claude-code-acp"],
+			args: ["-y", "@zed-industries/claude-code-acp@0.16.2"],
 			npmPackage: "@zed-industries/claude-code-acp",
 			npmPackageBin: "claude-code-acp",
 		},
@@ -39,7 +39,7 @@ export const INTEROP_AGENT_KINDS: ReadonlyArray<InteropAgentKind> = [
 		instructionFiles: ["AGENTS.md", "CODEX.md", ".codex/AGENTS.md"],
 		acp: {
 			command: "npx",
-			args: ["-y", "@agentclientprotocol/codex-acp"],
+			args: ["-y", "@agentclientprotocol/codex-acp@1.10.0"],
 			npmPackage: "@agentclientprotocol/codex-acp",
 			npmPackageBin: "codex-acp",
 		},

package/src/domains/middleware/hooks-io.ts

@@ -19,13 +19,18 @@
  */
 
 import { spawnSync } from "node:child_process";
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
 import { parse as parseYaml } from "yaml";
 import {
+	gitCommitAttributionEnabled,
 	reportCommitAttributionDiagnostic,
 	withManagedGitCommitAttributionEnvironment,
 } from "../../core/git-commit-attribution.js";
+import { buildSafeToolEnv } from "../../core/safe-exec.js";
+import {
+	captureProjectSurface,
+	type ProjectSurfaceSnapshot,
+	projectSurfaceTrustNotice,
+} from "../../core/workspace-trust.js";
 import {
 	type HookReceiptSink,
 	loadUserHooks,
@@ -49,6 +54,7 @@ export interface HookFileIssue {
 export interface ReadHookSourcesResult {
 	batches: UserHookDeclarationBatch[];
 	fileIssues: HookFileIssue[];
+	projectSurface: ProjectSurfaceSnapshot;
 }
 
 /** One package's hook declarations, captured by the supplier from verified bytes. */
@@ -77,15 +83,9 @@ export interface ReadHookSourcesOptions {
 function readBatch(
 	source: UserHookSource,
 	filePath: string,
+	text: string,
 	fileIssues: HookFileIssue[],
 ): UserHookDeclarationBatch | null {
-	let text: string;
-	try {
-		text = readFileSync(filePath, "utf8");
-	} catch {
-		// Missing file: not an error, the source is simply absent.
-		return null;
-	}
 	try {
 		const parsed = parseYaml(text) as unknown;
 		return { source, declarations: parsed ?? [] };
@@ -125,21 +125,22 @@ export function readHookSources(options: ReadHookSourcesOptions): ReadHookSource
 		batches.push({ source, declarations: entry.declarations });
 	}
 
-	const projectBatch = readBatch(
-		{ origin: "project", sourcePath: ".clio-coder/hooks.yaml" },
-		join(options.cwd, ".clio-coder", "hooks.yaml"),
-		fileIssues,
-	);
-	if (projectBatch) batches.push(projectBatch);
-
-	const localBatch = readBatch(
-		{ origin: "project.local", sourcePath: ".clio-coder/hooks.local.yaml" },
-		join(options.cwd, ".clio-coder", "hooks.local.yaml"),
-		fileIssues,
-	);
-	if (localBatch) batches.push(localBatch);
-
-	return { batches, fileIssues };
+	const projectSurface = captureProjectSurface(options.cwd, "hooks");
+	for (const [index, file] of projectSurface.files.entries()) {
+		const source: UserHookSource = {
+			origin: index === 0 ? "project" : "project.local",
+			sourcePath: index === 0 ? ".clio-coder/hooks.yaml" : ".clio-coder/hooks.local.yaml",
+		};
+		if (file.error !== undefined) fileIssues.push({ source, message: file.error });
+		if (file.text === null) continue;
+		if (projectSurface.verdict !== "trusted") {
+			fileIssues.push({ source, message: projectSurfaceTrustNotice(projectSurface, file.path) });
+			continue;
+		}
+		const batch = readBatch(source, file.path, file.text, fileIssues);
+		if (batch) batches.push(batch);
+	}
+	return { batches, fileIssues, projectSurface };
 }
 
 export interface BuildUserHookRegistrationsOptions {
@@ -151,6 +152,8 @@ export interface BuildUserHookRegistrationsOptions {
 	/** Injected for tests; defaults to the spawnSync runner. */
 	runCommand?: UserHookCommandRunner;
 	now?: () => number;
+	/** Operator notice when an already published project's trust changes. */
+	report?: (line: string) => void;
 }
 
 export interface BuildUserHookRegistrationsResult extends UserHookLoadResult {
@@ -173,13 +176,28 @@ export function buildUserHookRegistrations(
 	const workspaceRoot = options.workspaceRoot ?? options.cwd;
 	const readOptions: ReadHookSourcesOptions = { cwd: options.cwd };
 	if (options.capturedSources !== undefined) readOptions.capturedSources = options.capturedSources;
-	const { batches, fileIssues } = readHookSources(readOptions);
+	const { batches, fileIssues, projectSurface } = readHookSources(readOptions);
 	const loaded = loadUserHooks(batches, { workspaceRoot });
 	const runCommand = options.runCommand ?? spawnSyncCommandRunner();
+	let reportedUntrusted = false;
+	const projectStillTrusted = (): boolean => {
+		const current = captureProjectSurface(options.cwd, "hooks");
+		if (current.verdict === "trusted" && current.contentHash === projectSurface.contentHash) return true;
+		if (!reportedUntrusted) {
+			reportedUntrusted = true;
+			options.report?.(
+				`[clio-coder:hooks] project hooks changed or trust was revoked; hooks skipped. Review with clio-coder config trust hooks, then reload extensions.`,
+			);
+		}
+		return false;
+	};
 	const registrations = loaded.hooks.map((hook) =>
 		userHookToRegistration(hook, {
 			recordReceipt: options.recordReceipt,
 			runCommand,
+			...(hook.source.origin === "project" || hook.source.origin === "project.local"
+				? { isTrusted: projectStillTrusted }
+				: {}),
 			...(options.now !== undefined ? { now: options.now } : {}),
 		}),
 	);
@@ -195,8 +213,9 @@ export function spawnSyncCommandRunner(): UserHookCommandRunner {
 		const [command, ...args] = argv;
 		// A user hook is operator automation, not Clio work: the environment is
 		// normalized so a nested seam sees consistent state, but no role is claimed.
-		const attribution = withManagedGitCommitAttributionEnvironment(process.env, {
+		const attribution = withManagedGitCommitAttributionEnvironment(buildSafeToolEnv(), {
 			cwd: options.cwd ?? process.cwd(),
+			enabled: gitCommitAttributionEnabled(process.env),
 			evidence: {},
 		});
 		reportCommitAttributionDiagnostic(attribution.diagnostic);

package/src/domains/middleware/hooks.ts

@@ -397,6 +397,8 @@ export interface UserHookRegistrationDeps {
 	/** Synchronous command runner. Injected so tests need no real subprocess. */
 	runCommand: UserHookCommandRunner;
 	now?: () => number;
+	/** Published project hooks stop executing after their approved surface changes or is revoked. */
+	isTrusted?: () => boolean;
 }
 
 function reminderEffect(message: string, severity: MiddlewareReminderSeverity): MiddlewareEffect {
@@ -441,6 +443,10 @@ export function userHookToRegistration(
 		evaluate: (input) => {
 			if (!hook.enabled) return [];
 			try {
+				if (deps.isTrusted?.() === false) {
+					deps.recordReceipt({ ...baseReceipt(input), outcome: "skipped" });
+					return [];
+				}
 				return evaluateHook(hook, deps, baseReceipt(input));
 			} catch {
 				// A hook must never throw into a turn; report a skipped receipt.

package/src/domains/middleware/injection-screen.ts

@@ -0,0 +1,23 @@
+import { INSTRUCTION_SHAPED_WARNING } from "../../core/untrusted-content.js";
+import type { MiddlewareRuleDefinition } from "./runtime.js";
+
+/** Raw-body marker detection is supplied by the registry before result shaping. */
+export const INJECTION_SCREEN_RULE: MiddlewareRuleDefinition = {
+	rule: {
+		id: "safety.untrusted-instructions",
+		source: "builtin",
+		description: "Warn when external tool data contains instruction-shaped markers",
+		enabled: true,
+		hooks: ["after_tool"],
+		effectKinds: ["annotate_tool_result"],
+	},
+	toolNames: ["web_fetch", "read", "bash", "dispatch", "monitor"],
+	predicate: (input) => input.metadata?.untrustedInstructionMarkers === true,
+	effects: [
+		{
+			kind: "annotate_tool_result",
+			severity: "warn",
+			message: INSTRUCTION_SHAPED_WARNING,
+		},
+	],
+};

package/src/domains/middleware/rules.ts

@@ -1,3 +1,4 @@
+import { INJECTION_SCREEN_RULE } from "./injection-screen.js";
 import type { MiddlewareRuleDefinition } from "./runtime.js";
 import { STALLED_TURN_RULE_DEFINITION } from "./stalled-turn.js";
 import type { MiddlewareRule } from "./types.js";
@@ -8,7 +9,10 @@ import type { MiddlewareRule } from "./types.js";
  * channel delivers the declarative half to workers, which resolve payloads
  * from this table by rule id.
  */
-const BUILTIN_MIDDLEWARE_RULE_DEFINITIONS: ReadonlyArray<MiddlewareRuleDefinition> = [STALLED_TURN_RULE_DEFINITION];
+const BUILTIN_MIDDLEWARE_RULE_DEFINITIONS: ReadonlyArray<MiddlewareRuleDefinition> = [
+	STALLED_TURN_RULE_DEFINITION,
+	INJECTION_SCREEN_RULE,
+];
 
 export const BUILTIN_MIDDLEWARE_RULE_IDS = BUILTIN_MIDDLEWARE_RULE_DEFINITIONS.map((definition) => definition.rule.id);
 

package/src/domains/middleware/stalled-turn.ts

@@ -9,7 +9,7 @@ export const STALLED_TURN_REQUEST_CONTINUATION_MESSAGE =
 	"You ended your turn after announcing an action without executing it: no tools were called. Continue now and perform the announced action, or state plainly that you are finished and waiting for the user.";
 
 export const SKILL_SUGGESTION_WAIT_CONTINUATION_MESSAGE =
-	"You ended your turn on a skill suggestion without doing the task. The suggestion line has already made the offer and only the operator loads a skill, so nothing is needed from them before you proceed. Continue the task now without the skill.";
+	"You ended your turn on a skill suggestion without doing the task. The suggestion line has already made the offer and only the operator loads a skill, so the skill choice needs nothing from them before you proceed. Continue the already-authorized task now without the skill. This continuation is not an operator answer to any other question: if the remaining work is a proposal awaiting an explicit operator go-ahead, park it on the task board and say so instead of implementing.";
 
 const INTENT_PATTERN = /\b(let me|i['’]ll|i will|i am going to|i['’]m going to|now i|next i|let's|let us)\b/i;
 
@@ -110,12 +110,25 @@ const ACTION_OBJECT_CONNECTOR_PATTERN = /^(?:at|for|in|into|on|through|to)\s+/i;
 const ACTION_OBJECT_DETERMINER_PATTERN = /^(?:a|an|my|our|that|the|their|these|this|those|your)\s+/i;
 const ACTION_OBJECT_PATTERN = /^(?!(?:again|everyone|later|next|now|soon|then|you)\b)[`"'./~]*[\p{L}\p{N}_-]/iu;
 const CONDITIONAL_LEAD_IN_PATTERN = /\b(?:if|once|unless|until|when|whenever)\b/i;
-const CONDITIONAL_INVITATION_PATTERN = /\b(?:ask|give|point|say|send|share|tell)\b[\s\S]*\b(?:and|then)\s*$/i;
+// "say go and", "confirm and", "reply yes and": the sentence hands the operator
+// the decision and promises work only after it.
+const CONDITIONAL_INVITATION_PATTERN =
+	/\b(?:answer|approve|ask|confirm|give|point|reply|respond|say|send|share|tell|type)\b[\s\S]*\b(?:and|then)\s*$/i;
 // "if needed", and any conditional whose condition is about the user: "if you
 // want", "if that is what you need". Conditions about the work ("if the config
 // is valid") stay announcements.
+// Any condition that waits on the operator ("after you approve", "once you
+// confirm", "until you say", "upon your go-ahead") is a proposal awaiting a
+// decision, not an announcement: the operator's answer is the missing input,
+// and an automatic continuation would stand in for it (issue #365).
 const CONDITIONAL_OFFER_SUFFIX_PATTERN =
-	/\b(?:if\s+(?:needed|necessary|requested)\b|if\b[^.!?]*\byou\b|when(?:ever)?\s+you\b)/i;
+	/\b(?:if\s+(?:needed|necessary|requested|approved|confirmed)\b|(?:if|after|once|until|unless|when(?:ever)?|as\s+soon\s+as|provided|assuming)\b[^.!?]*\byou\b|(?:upon|on|after|with|pending|awaiting|following)\s+(?:your\s+|the\s+operator(?:'s)?\s+)?(?:approval|go-?ahead|confirmation|sign-?off|decision|word|green\s+light|okay|ok)\b)/i;
+// A lead-in that is itself a wait ("Awaiting your go-ahead; I'll then write
+// the test") defers whatever the intent clause goes on to name.
+const OPERATOR_WAIT_LEAD_PATTERN = /\b(?:await(?:ing)?|pending|waiting\s+(?:for|on))\b/i;
+// "I will not edit files" announces a refusal, and "next I would create
+// clamp.py" describes a hypothetical; neither promises an action now.
+const NEGATED_OR_HYPOTHETICAL_CLAUSE_PATTERN = /^\s*(?:not|never|would|could|might|may)\b/i;
 const LET_ME_KNOW_PATTERN = /\blet me know\b/i;
 // "I'll wait for your go-ahead before I touch src/cli/index.ts" names a path
 // and promises nothing now. A clause that opens by deferring is a wait
@@ -199,12 +212,14 @@ function announcesConcreteAction(sentence: string): boolean {
 		if (
 			CONDITIONAL_LEAD_IN_PATTERN.test(leadIn) ||
 			CONDITIONAL_INVITATION_PATTERN.test(leadIn) ||
+			OPERATOR_WAIT_LEAD_PATTERN.test(leadIn) ||
 			CONDITIONAL_OFFER_SUFFIX_PATTERN.test(sentence)
 		) {
 			return false;
 		}
 		const clause = sentence.slice(intent.index + intent[0].length);
 		if (DEFERRAL_LEAD_PATTERN.test(clause)) return false;
+		if (NEGATED_OR_HYPOTHETICAL_CLAUSE_PATTERN.test(clause)) return false;
 		if (hasActionWithObject(clause)) return true;
 		// A path or command is evidence of an immediate action only when the
 		// announcement itself is unconditional; "once package.json is updated"

package/src/domains/middleware/task-board-reminder.ts

@@ -17,8 +17,10 @@ export const TASK_BOARD_REMINDER_REGISTRATION_ID = "observer.task-board-reminder
 export function taskBoardReminderMessage(steps: number): string {
 	return (
 		`[Tasks] This request enumerates ${steps} steps. Before the first edit, declare the task board: ` +
-		'tasks action="plan" with a title and one task per step, then work them one at a time ' +
-		'("start", then "done" with an evidence note).'
+		'tasks action="plan" with a title and one task per authorized step, then work them one at a time ' +
+		'("start", then "done" with an evidence note). A plan does not authorize implementation: ' +
+		'for proposed work awaiting an operator go-ahead, use action="block" with a note naming the pending operator decision, ' +
+		'or action="drop", and wait.'
 	);
 }
 

package/src/domains/middleware/task-nudge.ts

@@ -36,7 +36,10 @@ export function buildOpenTasksMessage(board: TaskBoardSnapshot): string {
 	return (
 		`[Clio Coder] task board "${board.title}" still has ${open.length} of ${counts.total} task(s) open:\n` +
 		`${rows.join("\n")}\n` +
-		`Continue working them, or record the honest state on the board: ` +
+		`Continue only work already authorized by the operator. This reminder and a self-created plan are not authorization ` +
+		`to implement a proposal. If implementation awaits an operator decision, use tasks action="block" with a note ` +
+		`naming that pending operator decision, or action="drop"; then wait for an explicit operator go-ahead. ` +
+		`A skill-install choice does not authorize implementation. Otherwise record the honest state on the board: ` +
 		`tasks action="done" with an evidence note, action="block" with a reason, or action="drop". ` +
 		`Do not end the turn with a stale board.`
 	);

package/src/domains/mux/contract.ts

@@ -61,7 +61,13 @@ const TOKEN_VALUE_MAX = 80;
 /** How long `available()` stays false after a transport failure before probing again. */
 const DEGRADE_COOLDOWN_MS = 5_000;
 
+export type MuxPaneOpenFailure =
+	| { source: "mux"; kind: MuxError["kind"]; wireCode: string | null; method: string | null; message: string }
+	| { source: "local"; message: string };
+
 export interface MuxOpenUtilityPaneRequest {
+	/** Request-scoped diagnostics; the pane-or-null best-effort result is unchanged. */
+	onFailure?: (failure: MuxPaneOpenFailure) => void;
 	argv: ReadonlyArray<string>;
 	cwd: string;
 	label: string;
@@ -230,7 +236,12 @@ export function createMuxRuntime(options: MuxRuntimeOptions): MuxRuntime {
 	 * is what the caller sees when the pane layer is not there, which is the same
 	 * value it sees in `none` mode.
 	 */
-	const attempt = async <T>(what: string, run: (live: MuxClient) => Promise<T>, fallback: T): Promise<T> => {
+	const attempt = async <T>(
+		what: string,
+		run: (live: MuxClient) => Promise<T>,
+		fallback: T,
+		onError?: (error: unknown) => void,
+	): Promise<T> => {
 		if (!usable() || client === null) return fallback;
 		try {
 			const value = await run(client);
@@ -238,6 +249,7 @@ export function createMuxRuntime(options: MuxRuntimeOptions): MuxRuntime {
 			return value;
 		} catch (error) {
 			degrade(what, error);
+			onError?.(error);
 			return fallback;
 		}
 	};
@@ -301,6 +313,13 @@ export function createMuxRuntime(options: MuxRuntimeOptions): MuxRuntime {
 		},
 
 		async openUtilityPane(request: MuxOpenUtilityPaneRequest): Promise<MuxPaneRef | null> {
+			const report = (failure: MuxPaneOpenFailure): void => {
+				try {
+					request.onFailure?.(failure);
+				} catch {
+					// Diagnostics must not break the best-effort contract.
+				}
+			};
 			// Idempotence for docks: a slot that already has a pane answers with it.
 			const dockSlot = request.dock?.slot;
 			if (dockSlot && docks) {
@@ -314,6 +333,7 @@ export function createMuxRuntime(options: MuxRuntimeOptions): MuxRuntime {
 					let ref: MuxPaneRef;
 					if (request.dock && docks) {
 						const placed = await docks.open(request.dock.slot, {
+							onRefused: (message) => report({ source: "local", message }),
 							...(request.dock.share === undefined ? {} : { share: request.dock.share }),
 							cwd: request.cwd,
 							...(request.env ? { env: request.env } : {}),
@@ -356,6 +376,19 @@ export function createMuxRuntime(options: MuxRuntimeOptions): MuxRuntime {
 					return ref;
 				},
 				null,
+				(error) => {
+					if (error instanceof MuxError) {
+						report({
+							source: "mux",
+							kind: error.kind,
+							wireCode: error.wireCode,
+							method: error.method,
+							message: error.message,
+						});
+					} else {
+						report({ source: "local", message: error instanceof Error ? error.message : String(error) });
+					}
+				},
 			);
 		},
 

package/src/domains/mux/dock-controller.ts

@@ -198,7 +198,12 @@ export interface DockController {
 	 */
 	open(
 		slot: DockSlot,
-		options?: { share?: number; cwd?: string; env?: Readonly<Record<string, string>> },
+		options?: {
+			share?: number;
+			cwd?: string;
+			env?: Readonly<Record<string, string>>;
+			onRefused?: (reason: string) => void;
+		},
 	): Promise<MuxPaneRef | null>;
 	/** Record an adopted pane (crash recovery) as this slot's dock. */
 	adopt(slot: DockSlot, ref: MuxPaneRef): void;
@@ -265,11 +270,13 @@ export function createDockController(options: DockControllerOptions): DockContro
 			const geometry = await client.paneLayout(anchorPaneId);
 			const anchorRect = geometry.panes.find((pane) => pane.paneId === anchorPaneId)?.rect;
 			if (!anchorRect) {
+				openOptions.onRefused?.(`no anchor geometry for ${anchorPaneId}; check the pane host layout before trying again`);
 				log("debug", `mux ${slot} dock open found no anchor rect for ${anchorPaneId}`);
 				return null;
 			}
 			const plan = planDockOpen(anchorRect, spec, openOptions.share);
 			if ("refused" in plan) {
+				openOptions.onRefused?.(`${plan.refused}; enlarge the anchor pane before trying again`);
 				log("info", `mux ${slot} dock refused: ${plan.refused}`);
 				return null;
 			}

package/src/domains/mux/index.ts

@@ -21,6 +21,7 @@ export type {
 	MuxContract,
 	MuxNotifyRequest,
 	MuxOpenUtilityPaneRequest,
+	MuxPaneOpenFailure,
 	MuxRuntime,
 	MuxRuntimeOptions,
 } from "./contract.js";

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

@@ -645,9 +645,19 @@ export function createMuxClient(options: MuxClientOptions): MuxClient {
 						// so an empty-id error line on this connection is still ours.
 						if (responseId !== id && !(responseId === "" && error)) return;
 						if (error) {
-							const code = typeof error.code === "string" ? error.code : "unknown";
-							const message = typeof error.message === "string" ? error.message : code;
-							finish(() => reject(new MuxError(muxErrorKind(code), message, { wireCode: code, method })));
+							const code = typeof error.code === "string" ? error.code : undefined;
+							// Absence is different from a host literally saying "unknown".
+							// Keep supplied text verbatim and make missing text explicit here.
+							const message =
+								typeof error.message === "string" ? error.message : "no failure message was supplied by the pane host";
+							finish(() =>
+								reject(
+									new MuxError(muxErrorKind(code ?? "unknown"), message, {
+										...(code === undefined ? {} : { wireCode: code }),
+										method,
+									}),
+								),
+							);
 							return;
 						}
 						finish(() => resolve(line.result));

package/src/domains/observability/contract.ts

@@ -47,7 +47,7 @@ export interface ObservabilityNotice {
 }
 
 /**
- * Compact lifecycle summary for a recent dispatch run. Projected from the
+ * Compact lifecycle summary for an active or recently settled dispatch run. Projected from the
  * dispatch bus channels; raw tool arguments and reasoning are absent. Worker
  * progress is a bounded, redacted presentation of the live stream. `evidence`
  * is populated asynchronously once the forensic bundle for the run finalizes.
@@ -205,7 +205,7 @@ export interface ObservabilityContract extends ObservabilityRunProjection {
 	recordSessionTurn(trace: SessionTurnTrace): void;
 	/**
 	 * Current product-facing projection. Cheap to call: it folds in-memory state
-	 * (bounded run/notice rings, session cost/tokens, aggregated metrics, and the
+	 * (active runs, bounded terminal history/notices, session cost/tokens, aggregated metrics, and the
 	 * cached accountability summary) into a fresh immutable snapshot.
 	 */
 	snapshot(): ObservabilitySnapshot;