@iowarp/clio-coder 0.4.3 → 0.4.5

package/src/domains/evidence/store.ts

@@ -2,6 +2,7 @@ import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { assertSafeId } from "../../core/safe-id.js";
 import { type GateDecisionArtifact, verifyGateDecisionArtifact } from "../dispatch/index.js";
+import { isDecisionRecord } from "../session/entries.js";
 import { compareCodepoints as compareStrings } from "./ordering.js";
 import { hasRunProvenance, type RunProvenanceView, runProvenanceFromUnknown } from "./provenance.js";
 import { normalizeTrustStatus } from "./trust-status.js";
@@ -230,6 +231,7 @@ function parseOverview(value: unknown, source: string): EvidenceOverview {
 		tags,
 		files,
 		...(redactionCount === undefined ? {} : { redactionCount }),
+		...(value.decisions === undefined ? {} : { decisions: readDecisions(value.decisions, `${source}.decisions`) }),
 	};
 }
 
@@ -335,3 +337,17 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 export function findingsFile(evidenceId: string, findings: EvidenceFinding[]): EvidenceFindingsFile {
 	return { version: 1, evidenceId, findings };
 }
+
+function readDecisions(value: unknown, source: string): NonNullable<EvidenceOverview["decisions"]> {
+	if (!Array.isArray(value)) throw new Error(`${source}: expected array`);
+	return value.map((entry: unknown, index) => {
+		const path = `${source}[${index}]`;
+		if (!isRecord(entry) || !isDecisionRecord(entry.record)) throw new Error(`${path}: expected recorded decision`);
+		return {
+			runId: readString(entry, path, "runId"),
+			sessionId: readString(entry, path, "sessionId"),
+			ref: readString(entry, path, "ref"),
+			record: entry.record,
+		};
+	});
+}

package/src/domains/evidence/types.ts

@@ -2,6 +2,7 @@ import type { GateDecisionArtifact, RunEnvelope, RunReceipt, ToolCallStat } from
 import type { RunPersonaOverride, RunPipelineProvenance, RunReceiptAutonomyEnforcement } from "../dispatch/types.js";
 import type { EvalCommandPhase, EvalFailureClass, EvalRunRecord } from "../eval/index.js";
 import type { ProtectedArtifact } from "../safety/protected-artifacts.js";
+import type { DecisionRecord } from "../session/entries.js";
 import type { RunEscalationCounts } from "./provenance.js";
 import type { CanonicalTrustStatus } from "./trust-status.js";
 
@@ -81,7 +82,16 @@ export interface EvidenceTotals {
 	wallTimeMs: number;
 }
 
+export interface EvidenceDecision {
+	runId: string;
+	sessionId: string;
+	ref: string;
+	record: DecisionRecord;
+}
+
 export interface EvidenceOverview {
+	/** Recorded arguments resolved from authenticated receipts on the linked active session path. */
+	decisions?: EvidenceDecision[];
 	version: 1;
 	evidenceId: string;
 	source: EvidenceSource;
@@ -137,6 +147,8 @@ export interface EvidenceBuildResult {
 	overview: EvidenceOverview;
 	findings: EvidenceFinding[];
 	trustStatus: EvidenceTrustStatusFile;
+	/** Total claims without matching commands, from integrity-verified receipts only. */
+	ungroundedClaims: number;
 }
 
 export interface EvidenceInspectable {

package/src/domains/extensions/resources.ts

@@ -22,6 +22,13 @@ export function extensionSnapshotFor(cwd = process.cwd()): ExtensionSnapshot {
 	return buildExtensionSnapshot({ cwd, generation: 0 });
 }
 
+/**
+ * The canonical accessor for the enabled roots of one extension resource
+ * kind. The agent registry, fleet contract, skill and common resource
+ * loaders, and the extensions contract all read through it, so each of them
+ * sees the committed snapshot for the booted cwd or the ephemeral
+ * generation-0 build otherwise. Returns a fresh array the caller may mutate.
+ */
 export function enabledExtensionResourceRoots(
 	kind: ExtensionResourceKind,
 	cwd = process.cwd(),

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/marketplace-offer.ts

@@ -53,6 +53,8 @@ export interface MarketplaceOfferInstallResult {
 }
 
 export interface MarketplaceOfferDeps {
+	/** Whether the session can render ask_user. Defaults to interactive offers. */
+	interactive?: boolean;
 	/** Installed skill names the matcher must exclude. */
 	listInstalledSkillNames(): ReadonlyArray<string>;
 	/** The local marketplace lookup (catalog + index); already local-only. */
@@ -80,10 +82,18 @@ export function offerBindingTag(offerTag: string): string {
 	return `[clio-install:${offerTag}]`;
 }
 
+function boundedDescription(text: string): string {
+	return text
+		.replace(/\[[^[\]]*\]/gu, " ")
+		.replace(/\s+/gu, " ")
+		.trim()
+		.slice(0, 200);
+}
+
 export function marketplaceOfferReminder(entry: MarketplaceSkill, offerTag: string): string {
 	return (
 		`[Marketplace] This request may need expertise no installed skill covers. The local marketplace has ` +
-		`"${entry.name}" (not installed): ${entry.description} ` +
+		`"${entry.name}" (not installed): ${boundedDescription(entry.description)} ` +
 		`First check the installed side with context(scope="skills"); if ${entry.name} is genuinely the right fit ` +
 		`and nothing installed serves, ask the operator with ask_user (mode=single_question, header "Install skill") ` +
 		`whether to install ${entry.name}, offering exactly these options in this order: ` +
@@ -299,6 +309,15 @@ export function createMarketplaceOfferRegistration(deps: MarketplaceOfferDeps):
 			const match = bestMatch(input.text ?? "");
 			if (!match) return NO_EFFECTS;
 			offeredNames.add(match.entry.name);
+			if (deps.interactive === false) {
+				return [
+					{
+						kind: "inject_reminder",
+						severity: "info",
+						message: `[Marketplace] Skill "${match.entry.name}" matches this request; install with clio-coder skills install ${match.entry.name}.`,
+					},
+				];
+			}
 			const tag = newOfferTag();
 			pendingOffer = { entry: match.entry, tag };
 			return [{ kind: "inject_reminder", severity: "info", message: marketplaceOfferReminder(match.entry, tag) }];

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/runtime.ts

@@ -110,9 +110,13 @@ export type MiddlewareDiagnostic =
 export type MiddlewareDiagnosticSink = (diagnostic: MiddlewareDiagnostic) => void;
 
 /**
- * Default diagnostic sink. stderr-only for now; once the typed bus lands a
- * `middleware.hookFailed` channel, the composition root supplies a sink that
- * also emits there.
+ * Default diagnostic sink, and the one the domain loader constructs the
+ * bundle with. It writes to stderr only. The composition root
+ * (src/entry/orchestrator.ts) replaces it through setDiagnosticSink with a
+ * sink that publishes every diagnostic on the typed bus as
+ * `middleware.hookFailed`, which the interactive warn notice consumes, and
+ * that still calls this writer for non-interactive runs, which have no
+ * notice subscriber.
  */
 export function writeMiddlewareDiagnosticToStderr(diagnostic: MiddlewareDiagnostic): void {
 	if (diagnostic.kind === "hook_failed") {

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/detect.ts

@@ -126,12 +126,9 @@ export async function detectMux(options: DetectMuxOptions = {}): Promise<MuxDete
 		return { detection: none("panes are turned off"), client: null };
 	}
 	if (enabled === "embedded") {
-		// Embedded mode (Clio owning the pane host) is not implemented yet. An
-		// operator who picked it wanted panes, so the rung degrades to guest
-		// detection instead of refusing everything; the notice below says which
-		// mode actually runs. When the guest ladder also fails, that failure is
-		// reported on its own terms.
-		log("info", "interface.panes.enabled=embedded is not implemented yet; detecting a guest pane host instead");
+		const reason = "embedded pane hosting is not implemented; use auto or guest";
+		log("warning", reason);
+		return { detection: none(reason, [], true), client: null };
 	}
 	if (env.HERDR_ENV !== "1") {
 		return { detection: none("HERDR_ENV is not 1, so Clio is not running inside a pane host"), client: null };

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/accountability.ts

@@ -27,6 +27,8 @@ export interface AccountabilitySummary {
 	totalRuns: number;
 	firstPassRuns: number;
 	firstPassRate: number;
+	unverifiedSuccesses: number;
+	ungroundedClaims: number;
 	failureCauses: ReadonlyArray<{ tag: EvidenceTag; count: number }>;
 }
 
@@ -38,9 +40,19 @@ export interface AccountabilitySummary {
 export function summarizeEvidenceIndex(rows: ReadonlyArray<EvidenceIndexRow>): AccountabilitySummary {
 	const totalRuns = rows.length;
 	let firstPassRuns = 0;
+	let unverifiedSuccesses = 0;
+	let ungroundedClaims = 0;
 	const counts = new Map<EvidenceTag, number>();
 	for (const row of rows) {
 		if (row.firstPassSuccess) firstPassRuns += 1;
+		if (
+			row.succeeded === true &&
+			(row.tags.includes("no-validation") ||
+				row.tags.includes("proxy-validation") ||
+				row.completionEvidenceWarning === true)
+		)
+			unverifiedSuccesses += 1;
+		ungroundedClaims += row.ungroundedClaims ?? 0;
 		for (const tag of row.tags) {
 			if (!FAILURE_CAUSE_TAGS.has(tag)) continue;
 			counts.set(tag, (counts.get(tag) ?? 0) + 1);
@@ -53,6 +65,8 @@ export function summarizeEvidenceIndex(rows: ReadonlyArray<EvidenceIndexRow>): A
 		totalRuns,
 		firstPassRuns,
 		firstPassRate: totalRuns === 0 ? 0 : firstPassRuns / totalRuns,
+		unverifiedSuccesses,
+		ungroundedClaims,
 		failureCauses,
 	};
 }
@@ -60,7 +74,7 @@ export function summarizeEvidenceIndex(rows: ReadonlyArray<EvidenceIndexRow>): A
 /**
  * Read the sidecar index from the state dir and summarize it. Tolerant by way of
  * `readEvidenceIndex`: a missing or corrupt index yields the empty summary
- * (`{ totalRuns: 0, firstPassRuns: 0, firstPassRate: 0, failureCauses: [] }`).
+ * with zero counters and an empty failure-cause histogram.
  */
 export function readAccountabilitySummary(stateDir: string): AccountabilitySummary {
 	return summarizeEvidenceIndex(readEvidenceIndex(stateDir));