@iowarp/clio-coder 0.3.8 → 0.4.0

package/src/interactive/overlay-permission-lifecycle.ts

@@ -11,6 +11,7 @@ import type { PermissionRequiredMeta, ToolRegistry } from "../tools/registry.js"
 import { approvalParkedNotice, autonomyDeniedNotice, workerEscalationNotice } from "./bus-notices.js";
 import type { ToolApprovalStateEvent } from "./chat-loop.js";
 import type { NoticeLevel } from "./command-output.js";
+import { createMutationInspector, type MutationInspector, mutationFacts } from "./mutation-preview.js";
 import type { OverlayState } from "./overlay-key-routing.js";
 import { type ApprovalRequestView, askAxis, describeCallTarget } from "./permission-overlay.js";
 
@@ -35,6 +36,7 @@ interface WorkerEscalationEntry {
 	axis: ApprovalRequestView["axis"];
 	reason: string;
 	target?: string;
+	fallback: "deny" | "fail";
 }
 
 export interface OverlayPermissionLifecycleDeps {
@@ -43,7 +45,12 @@ export interface OverlayPermissionLifecycleDeps {
 	dispatch: Pick<DispatchContract, "resolveWorkerPermission">;
 	getAutonomy(): string;
 	getOverlayState(): OverlayState;
-	openPermissionOverlay(view: ApprovalRequestView): boolean;
+	/**
+	 * Open the dialog for one parked call. `inspect` carries the complete
+	 * mutation text and is the only channel that does; it is process-local by
+	 * construction, so it is passed here rather than folded into the view.
+	 */
+	openPermissionOverlay(view: ApprovalRequestView, inspect?: MutationInspector): boolean;
 	closeOverlay(): void;
 	appendNotice(level: NoticeLevel, text: string): void;
 	applyApprovalState(event: ToolApprovalStateEvent): void;
@@ -131,6 +138,9 @@ function mainApprovalRequestView(
 			? { kind: "net" as const, ruleId: axisFromDecision.ruleId }
 			: { kind: "autonomy" as const, level: autonomy });
 	const target = describeCallTarget(call.tool, call.args);
+	// Facts only. The mutation text stays in the inspector the overlay opener
+	// gets; this object reaches the transcript row and the approval-state event.
+	const mutation = mutationFacts(call.tool, call.args);
 	return {
 		requestId: meta?.requestId ?? "permission-pending",
 		tool: call.tool,
@@ -144,10 +154,21 @@ function mainApprovalRequestView(
 			: {}),
 		...(call.tool === ToolNames.AskUser ? { exposure: askUserExposure(call.args) } : {}),
 		...(target.length > 0 ? { target } : {}),
+		...(mutation !== null ? { mutation } : {}),
 		...(queueDepth !== undefined && queueDepth > 1 ? { queueDepth } : {}),
 	};
 }
 
+/**
+ * The inspector for a main-agent ask, or undefined when there is nothing local
+ * to read. A worker escalation never gets one: its arguments stay in the
+ * worker, and the card says so rather than implying an inspection it cannot do.
+ */
+function mainMutationInspector(call: ClassifierCall, view: ApprovalRequestView): MutationInspector | undefined {
+	if (view.mutation === undefined) return undefined;
+	return createMutationInspector(call.tool, call.args, view.mutation);
+}
+
 function workerEscalationEntry(payload: PermissionRequestedPayload, autonomy: string): WorkerEscalationEntry | null {
 	if (!isLiveWorkerEscalationRequest(payload) || typeof payload.requestId !== "string") return null;
 	const origin = typeof payload.origin === "string" ? payload.origin : undefined;
@@ -170,6 +191,7 @@ function workerEscalationEntry(payload: PermissionRequestedPayload, autonomy: st
 		...(typeof payload.target === "string" && payload.target.length > 0
 			? { target: sanitizeCallTargetText(payload.target).slice(0, 200) }
 			: {}),
+		fallback: payload.fallback === "fail" ? "fail" : "deny",
 	};
 }
 
@@ -187,42 +209,87 @@ function workerApprovalRequestView(entry: WorkerEscalationEntry): ApprovalReques
 
 export function createOverlayPermissionLifecycle(deps: OverlayPermissionLifecycleDeps): OverlayPermissionLifecycle {
 	let pendingPermission: { call: ClassifierCall; decision: SafetyDecision; meta?: PermissionRequiredMeta } | null = null;
-	let pendingWorker: Pick<WorkerEscalationEntry, "agentId" | "requestId" | "runId"> | null = null;
+	let pendingWorker: WorkerEscalationEntry | null = null;
 	const workerQueue: WorkerEscalationEntry[] = [];
 	const announcedRequestIds = new Set<string>();
 	/** Worker escalations already surfaced, so one request parks the operator once. */
 	const announcedWorkerRequestIds = new Set<string>();
+	/** Expiry notices already printed, including a decision that lost the terminal-state race. */
+	const expiredWorkerRequestIds = new Set<string>();
 	let confirmed = false;
 	let stopping = false;
+	let withdrawingWorker = false;
 
-	const openWorker = (entry: WorkerEscalationEntry): void => {
-		if (deps.getOverlayState() !== "closed") return;
-		if (!deps.openPermissionOverlay(workerApprovalRequestView(entry))) return;
-		pendingWorker = { runId: entry.runId, requestId: entry.requestId, agentId: entry.agentId };
+	const openWorker = (entry: WorkerEscalationEntry): boolean => {
+		if (!deps.openPermissionOverlay(workerApprovalRequestView(entry))) return false;
+		pendingWorker = entry;
 		pendingPermission = null;
 		confirmed = false;
+		return true;
 	};
 	const maybeOpenWorker = (): void => {
-		if (deps.getOverlayState() !== "closed") return;
-		const next = workerQueue.shift();
-		if (next) openWorker(next);
+		const next = workerQueue[0];
+		if (next && openWorker(next)) workerQueue.shift();
 	};
 	const retryPending = (): void => {
 		maybeOpenWorker();
-		if (deps.getOverlayState() === "closed" && deps.toolRegistry?.hasParkedCalls()) {
+		if (deps.getOverlayState() !== "permission-confirm" && deps.toolRegistry?.hasParkedCalls()) {
 			deps.toolRegistry.renotifyHead();
 		}
 	};
+	const announceWorkerExpiry = (
+		entry: WorkerEscalationEntry,
+		fallback: "deny" | "fail",
+		cause: "timeout" | "terminal" | "late-answer",
+	): void => {
+		if (!markPermissionRequestSurfaced(expiredWorkerRequestIds, entry.requestId)) return;
+		const why =
+			cause === "timeout"
+				? "expired after its escalation timeout"
+				: cause === "terminal"
+					? "expired when its run ended"
+					: "expired before the operator decision arrived";
+		deps.appendNotice(
+			"warn",
+			`Worker approval request ${entry.requestId} for ${entry.agentId} (${entry.runId}) ${why}; fallback ${fallback} applied.`,
+		);
+	};
+	const removeQueuedWorkers = (matches: (entry: WorkerEscalationEntry) => boolean): WorkerEscalationEntry[] => {
+		const removed: WorkerEscalationEntry[] = [];
+		for (let index = workerQueue.length - 1; index >= 0; index -= 1) {
+			const entry = workerQueue[index];
+			if (entry === undefined || !matches(entry)) continue;
+			removed.unshift(entry);
+			workerQueue.splice(index, 1);
+		}
+		return removed;
+	};
+	const withdrawWorkers = (
+		matches: (entry: WorkerEscalationEntry) => boolean,
+		cause: "timeout" | "terminal",
+		fallback?: "deny" | "fail",
+	): void => {
+		const active = pendingWorker !== null && matches(pendingWorker) ? pendingWorker : null;
+		const expired = [...(active === null ? [] : [active]), ...removeQueuedWorkers(matches)];
+		if (expired.length === 0) return;
+		if (active !== null) {
+			pendingWorker = null;
+			confirmed = false;
+			withdrawingWorker = true;
+			deps.closeOverlay();
+		}
+		for (const entry of expired) announceWorkerExpiry(entry, fallback ?? entry.fallback, cause);
+		deps.requestRender();
+	};
 
 	const unsubscribePermission =
 		deps.toolRegistry?.onPermissionRequired((call, decision, meta) => {
 			const autonomy = deps.getAutonomy();
 			const view = mainApprovalRequestView(call, decision, meta, autonomy, deps.toolRegistry?.parkedCount());
-			// The dialog states the tool, the target, the action class, the axis
-			// that asked, and the keys that answer it. While it is on screen the
-			// notice repeats all of that one line above the transcript, so it is
-			// emitted only when no dialog could open (another overlay holds the
-			// screen), which is the case where it is the operator's only signal.
+			// The dialog states the tool, target, action class, asking axis, and
+			// decision keys. Another modal is interrupted so this prompt can take
+			// focus. The notice remains for a second queued approval or a frame that
+			// could not mount, when it is the operator's only additional signal.
 			const announceParked = (): void => {
 				if (!markPermissionRequestSurfaced(announcedRequestIds, meta.requestId)) return;
 				const notice = approvalParkedNotice(call.tool, decision, autonomy);
@@ -236,11 +303,7 @@ export function createOverlayPermissionLifecycle(deps: OverlayPermissionLifecycl
 					view,
 				});
 			}
-			if (deps.getOverlayState() !== "closed") {
-				announceParked();
-				return;
-			}
-			if (!deps.openPermissionOverlay(view)) {
+			if (!deps.openPermissionOverlay(view, mainMutationInspector(call, view))) {
 				announceParked();
 				return;
 			}
@@ -260,6 +323,18 @@ export function createOverlayPermissionLifecycle(deps: OverlayPermissionLifecycl
 		workerQueue.push(entry);
 		maybeOpenWorker();
 	});
+	const unsubscribeWorkerResolution = deps.bus.on(BusChannels.PermissionResolved, (payload) => {
+		if (typeof payload.requestId !== "string") return;
+		if (payload.decidedBy !== "timeout" && payload.status !== "expired") return;
+		const fallback = payload.fallback === "fail" ? "fail" : "deny";
+		withdrawWorkers((entry) => entry.requestId === payload.requestId, "timeout", fallback);
+	});
+	const withdrawTerminalRun = (payload: { runId?: unknown }): void => {
+		if (typeof payload.runId !== "string") return;
+		withdrawWorkers((entry) => entry.runId === payload.runId, "terminal");
+	};
+	const unsubscribeWorkerCompleted = deps.bus.on(BusChannels.DispatchCompleted, withdrawTerminalRun);
+	const unsubscribeWorkerFailed = deps.bus.on(BusChannels.DispatchFailed, withdrawTerminalRun);
 
 	const unsubscribeAutonomy =
 		deps.toolRegistry?.onAutonomyDenied((_call, decision, level) => {
@@ -269,6 +344,12 @@ export function createOverlayPermissionLifecycle(deps: OverlayPermissionLifecycl
 		}) ?? (() => {});
 
 	const onPermissionOverlayClosed = (): void => {
+		if (withdrawingWorker) {
+			withdrawingWorker = false;
+			confirmed = false;
+			retryPending();
+			return;
+		}
 		const permission = pendingPermission;
 		const worker = pendingWorker;
 		pendingPermission = null;
@@ -279,10 +360,14 @@ export function createOverlayPermissionLifecycle(deps: OverlayPermissionLifecycl
 			try {
 				deps.dispatch.resolveWorkerPermission?.(worker.runId, worker.requestId, wasConfirmed ? "approve" : "deny");
 			} catch (error) {
-				deps.appendNotice(
-					"warn",
-					`Could not deliver permission decision to run ${worker.runId}: ${error instanceof Error ? error.message : String(error)}`,
-				);
+				const message = error instanceof Error ? error.message : String(error);
+				if (
+					/run or assignment '.+' is not active|run '.+' is (?:aborting|terminating)|no longer accepts input/u.test(message)
+				) {
+					announceWorkerExpiry(worker, worker.fallback, "late-answer");
+				} else {
+					deps.appendNotice("warn", `Could not deliver permission decision to run ${worker.runId}: ${message}`);
+				}
 			}
 		} else if (wasConfirmed && permission) {
 			deps.bus.emit(BusChannels.PermissionResolved, {
@@ -364,6 +449,9 @@ export function createOverlayPermissionLifecycle(deps: OverlayPermissionLifecycl
 		dispose: () => {
 			unsubscribePermission();
 			unsubscribeWorker();
+			unsubscribeWorkerResolution();
+			unsubscribeWorkerCompleted();
+			unsubscribeWorkerFailed();
 			unsubscribeAutonomy();
 		},
 	};

package/src/interactive/overlay-session-lifecycle.ts

@@ -403,19 +403,83 @@ export function createOverlaySessionLifecycle(deps: OverlaySessionLifecycleDeps)
 		void runHandoffExtraction(session, fromSessionId, verdict.goal);
 	}
 
+	/** Characters of the second round's answer quoted in the terminal refusal. */
+	const HANDOFF_REFUSAL_QUOTE_CHARS = 200;
+
+	/**
+	 * A refusal that says what was asked for and what came back, not only that no
+	 * JSON object arrived. Both rounds are named, so an operator reading it knows
+	 * two model calls were spent and on what.
+	 */
+	function terminalHandoffRefusal(firstReason: string, secondReason: string, secondText: string): string {
+		const answered = secondText.replace(/\s+/g, " ").trim().slice(0, HANDOFF_REFUSAL_QUOTE_CHARS);
+		return [
+			"the extraction round could not produce a handoff record after one repair attempt.",
+			`Asked for: one JSON object with decisions, facts, files, commands, and openQuestions.`,
+			`Round 1: ${firstReason}.`,
+			`Round 2: ${secondReason}.`,
+			`Round 2 returned: ${answered.length > 0 ? answered : "(nothing)"}`,
+		].join(" ");
+	}
+
+	/**
+	 * Extract, then repair once.
+	 *
+	 * A local model that answers with prose around the object, or with nothing
+	 * parseable, used to end `/handoff` outright: every downstream behavior (the
+	 * dropped-path listing, the `e` editor, accept-mints-a-session) was
+	 * unreachable and the operator had paid for the round either way (issue
+	 * #223). Exactly one repair round follows, quoting what came back and what
+	 * the parser objected to, and both rounds bill through the same out-of-turn
+	 * usage store.
+	 */
+	async function extractWithOneRepair(
+		goal: string,
+	): Promise<
+		| { ok: true; parsed: Extract<ReturnType<typeof parseHandoffExtraction>, { ok: true }> }
+		| { ok: false; level: "error" | "warn"; reason: string }
+	> {
+		const first = await deps.chat.extractHandoff(goal);
+		if (first.status !== "answered") {
+			return {
+				ok: false,
+				level: first.status === "failed" ? "error" : "warn",
+				reason: first.status === "aborted" ? "the extraction round was cancelled" : first.reason,
+			};
+		}
+		const parsedFirst = parseHandoffExtraction(first.text);
+		if (parsedFirst.ok) return { ok: true, parsed: parsedFirst };
+
+		const second = await deps.chat.extractHandoff(goal, {
+			repair: { complaint: parsedFirst.reason, previous: first.text },
+		});
+		if (second.status !== "answered") {
+			return {
+				ok: false,
+				level: second.status === "failed" ? "error" : "warn",
+				reason:
+					second.status === "aborted"
+						? "the repair round was cancelled"
+						: `round 1 could not be read (${parsedFirst.reason}); the repair round then failed: ${second.reason}`,
+			};
+		}
+		const parsedSecond = parseHandoffExtraction(second.text);
+		if (parsedSecond.ok) return { ok: true, parsed: parsedSecond };
+		return {
+			ok: false,
+			level: "error",
+			reason: terminalHandoffRefusal(parsedFirst.reason, parsedSecond.reason, second.text),
+		};
+	}
+
 	async function runHandoffExtraction(session: SessionContract, fromSessionId: string, goal: string): Promise<void> {
 		const notice = deps.getSlashNotice();
-		const outcome = await deps.chat.extractHandoff(goal);
-		if (outcome.status !== "answered") {
-			const reason = outcome.status === "aborted" ? "the extraction round was cancelled" : outcome.reason;
-			emitCommandNotice(notice, outcome.status === "failed" ? "error" : "warn", "handoff", reason);
-			return;
-		}
-		const parsed = parseHandoffExtraction(outcome.text);
-		if (!parsed.ok) {
-			emitCommandNotice(notice, "error", "handoff", parsed.reason);
+		const extraction = await extractWithOneRepair(goal);
+		if (!extraction.ok) {
+			emitCommandNotice(notice, extraction.level, "handoff", extraction.reason);
 			return;
 		}
+		const parsed = extraction.parsed;
 		const meta = session.current();
 		const cwd = typeof meta?.cwd === "string" && meta.cwd.length > 0 ? meta.cwd : null;
 		const entries = deps.readStructuredEntries(fromSessionId);

package/src/interactive/overlay-transitions.ts

@@ -20,12 +20,15 @@ export interface OverlayTransitionsDeps {
 export interface OverlayTransitions {
 	state: OverlayState;
 	handle: OverlayHandle | null;
+	/** Raise a permission prompt while preserving the modal it interrupted. */
+	showPermission(handle: OverlayHandle): boolean;
 	close(): void;
 }
 
 export function createOverlayTransitions(deps: OverlayTransitionsDeps): OverlayTransitions {
 	let state: OverlayState = "closed";
 	let handle: OverlayHandle | null = null;
+	let interrupted: { state: OverlayState; handle: OverlayHandle | null } | null = null;
 
 	return {
 		get state() {
@@ -44,6 +47,13 @@ export function createOverlayTransitions(deps: OverlayTransitionsDeps): OverlayT
 		set handle(next) {
 			handle = next;
 		},
+		showPermission(nextHandle) {
+			if (state === "permission-confirm") return false;
+			interrupted = state === "closed" ? null : { state, handle };
+			state = "permission-confirm";
+			handle = nextHandle;
+			return true;
+		},
 		close,
 	};
 
@@ -55,12 +65,16 @@ export function createOverlayTransitions(deps: OverlayTransitionsDeps): OverlayT
 			return;
 		}
 		const leaving = state;
-		state = "closed";
-		deps.stopDispatchBoardTicker();
-		handle?.hide();
-		handle = null;
+		const leavingHandle = handle;
+		const restoring = leaving === "permission-confirm" ? interrupted : null;
+		interrupted = null;
+		state = restoring?.state ?? "closed";
+		handle = restoring?.handle ?? null;
+		if (restoring === null) deps.stopDispatchBoardTicker();
+		leavingHandle?.hide();
 		if (leaving === "permission-confirm") deps.onPermissionOverlayClosed();
 		else deps.onOverlayClosed?.();
+		restoring?.handle?.focus();
 		deps.renderContextIsland();
 		deps.renderTaskIsland();
 		deps.requestRender();

package/src/interactive/overlays/agents.ts

@@ -60,6 +60,7 @@ export function openAgentsOverlay(tui: TUI, ctx: SlashCommandContext, onClose: (
 	const items = [...fleetItems, ...delegationItems];
 
 	return openListOverlay(tui, {
+		markerId: "agents",
 		title: "Agents Reference",
 		items,
 		filterable: true,