@overdeck/desktop 0.49.1 → 0.49.2

package/server/stuck-remediation-BDa_tXgB.js

@@ -0,0 +1,774 @@
+import { Li as getOverdeckHome, Ri as init_paths, Ui as sessionFilePath } from "./config-yaml-D9nfpEx1.js";
+import { A as listPaneValuesSync, C as init_tmux, D as killSessionSync, E as killSession, W as sessionExistsSync, i as capturePaneSync, l as detectTerminalApiErrorSync, z as sendEscapeKeyAsync } from "./tmux-DWEc4Ld9.js";
+import { _ as logDeaconEventSync, h as init_persistent_logger } from "./agents-jXgqpHca.js";
+import { $t as init_activity, C as markAgentTroubled, Ft as resumeAgent, Ut as messageAgent, W as getAgentRuntimeStateSync, en as resolveLatestSessionIdSync, q as init_agents, wt as init_agent_enrichment, yn as listRunningAgentsSync, yt as countPendingAskUserQuestionsForAgent } from "./agent-state-BJhGIJZe.js";
+import { c as init_control_settings, i as getFlywheelActiveRunId, p as isFlywheelGloballyPaused } from "./control-settings-BMoDHY1G.js";
+import { h as readWorkspacePlanSync, s as init_io } from "./io-DKrWd3gX.js";
+import { a as getDispatchableItems, c as init_dag } from "./dag-BPc74hwj.js";
+import { a as loadCloisterConfigSync, r as init_config, t as DEFAULT_CLOISTER_CONFIG } from "./config-Doq_tF-f.js";
+import { d as getReviewStatusSync, p as init_review_status } from "./review-status-yOGD2MuK.js";
+import { n as getAgentWorkActivityMs, r as isAgentIdleForNudge, t as getAgentEffectiveLastActivityMs } from "./agent-idle-ONBssBN_.js";
+import { i as recordRecoveryFailure, r as init_recovery_trip } from "./recovery-trip-BKLrL6NX.js";
+import { Effect } from "effect";
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "fs";
+import { join } from "path";
+//#region ../../lib/cloister/agent-death.ts
+init_persistent_logger();
+init_config();
+init_activity();
+init_agent_enrichment();
+init_agents();
+init_review_status();
+/**
+* Agent death diagnostics (PAN-2108).
+*
+* When an ohmypi/pi agent process dies, the launcher records its exit code +
+* timestamp to `<agentDir>/exit-status` (see buildOhmypiCommand in
+* launcher-generator.ts), and omp's stdout/stderr is captured to
+* `<agentDir>/output.log`. This module turns those into a one-line death reason
+* the deacon can log, replacing the opaque "session is dead" with an actual
+* cause — the gap that made the flywheel orchestrator's silent death
+* undiagnosable in RUN-30.
+*/
+init_paths();
+init_tmux();
+function agentDir(agentId) {
+	return join(getOverdeckHome(), "agents", agentId);
+}
+/** Read the launcher-recorded exit code + UTC timestamp, or null if absent. */
+function readAgentExitStatus(agentId) {
+	try {
+		const p = join(agentDir(agentId), "exit-status");
+		if (!existsSync(p)) return null;
+		const raw = readFileSync(p, "utf-8").trim();
+		if (!raw) return null;
+		const [code, at = ""] = raw.split(/\s+/);
+		return {
+			code: code ?? "?",
+			at
+		};
+	} catch {
+		return null;
+	}
+}
+/**
+* Best-effort one-line description of why an agent process died: the
+* launcher-recorded exit status (preferred), the tmux pane exit status (fallback
+* when the dead pane corpse still exists), and the tail of output.log.
+*/
+function describeAgentDeath(agentId) {
+	const parts = [];
+	const exit = readAgentExitStatus(agentId);
+	if (exit) parts.push(`exit=${exit.code}${exit.at ? ` at ${exit.at}` : ""}`);
+	else if (sessionExistsSync(agentId)) {
+		const paneExit = listPaneValuesSync(agentId, "#{pane_exit_status}").find((v) => v !== "");
+		if (paneExit) parts.push(`pane_exit=${paneExit}`);
+	}
+	try {
+		const logPath = join(agentDir(agentId), "output.log");
+		if (existsSync(logPath)) {
+			const tail = readFileSync(logPath, "utf-8").slice(-1500).trim().split("\n").slice(-6).join(" | ").trim();
+			if (tail) parts.push(`output.log tail: ${tail}`);
+		}
+	} catch {}
+	return parts.length ? parts.join("; ") : "no exit trace (exit-status + output.log empty)";
+}
+//#endregion
+//#region ../../lib/cloister/stuck-remediation-state.ts
+init_control_settings();
+init_paths();
+function agentStateDir(agentId) {
+	return join(getOverdeckHome(), "agents", agentId);
+}
+function statePath(agentId) {
+	return join(agentStateDir(agentId), "stuck-remediation.json");
+}
+function readStuckRemediationState(agentId) {
+	const filePath = statePath(agentId);
+	if (!existsSync(filePath)) return null;
+	try {
+		return JSON.parse(readFileSync(filePath, "utf-8"));
+	} catch (error) {
+		console.warn(`Failed to read stuck-remediation state for ${agentId}:`, error);
+		return null;
+	}
+}
+function writeStuckRemediationState(agentId, state) {
+	mkdirSync(agentStateDir(agentId), { recursive: true });
+	writeFileSync(statePath(agentId), `${JSON.stringify(state, null, 2)}\n`, "utf-8");
+}
+function clearStuckRemediationState(agentId) {
+	const filePath = statePath(agentId);
+	if (!existsSync(filePath)) return;
+	unlinkSync(filePath);
+}
+//#endregion
+//#region ../../lib/cloister/planning-wedge.ts
+init_io();
+init_dag();
+init_recovery_trip();
+/**
+* PAN-3677: positive transcript proof of the planning background-task wedge.
+*
+* The incident: planning sessions (planning-min-888 / planning-min-889) hung on
+* the provider call that followed their background Explore children reaching a
+* terminal state — one run with both children finished, one with a child dead
+* from the 262,144-token model limit while its sibling finished. The mirror
+* stayed 'active' (the Stop hook never fired), the pane kept repainting its
+* spinner, and queued `pan tell` messages were never processed.
+*
+* Stuck-remediation must NEVER interrupt a turn it cannot prove is wedged: a
+* healthy long reasoning turn is also mirror-'active' with no tool calls for
+* a while. This module supplies the positive signature from the authoritative
+* source — the session JSONL:
+*
+*   1. the parent launched at least one background child IN THE CURRENT TURN
+*      (Agent tool result: "Async agent launched successfully. … agentId: X");
+*   2. EVERY child launched since that boundary is proven terminal, via either
+*      - a task-notification queue-operation carrying a terminal
+*        `<status>` (completed / failed / cancelled / killed), or
+*      - a TaskOutput tool result for that task id with a terminal `<status>`.
+*
+* TURN SCOPING: at each genuine prompt boundary — a `user` entry with
+* string/text content (kickoff, recovery-resume seed) or a queue-operation
+* `remove` of a non-task-notification message (a consumed `pan tell`) —
+* children already proven TERMINAL are retired from the evidence; a closed
+* explorer batch from earlier in the session can never keep `wedged` true
+* through a later healthy turn (historical poisoning). Children NOT yet
+* terminal carry across the boundary, because real background tasks outlive
+* user turns: in the MIN-888 transcript the operator's `pan tell` was consumed
+* while the API explorer was still running, and the wedge formed only after
+* that child finished. `user` entries carrying tool_result parts are turn
+* machinery, never boundaries.
+*
+* If proof is missing — no background children since the boundary, or any
+* child without terminal proof — the answer is NOT wedged and the caller must
+* not interrupt. The detector is deliberately blind to everything else
+* (model, prompt, wall clock): those judgments live in the remediation
+* ladder.
+*
+* Known limitation: a task id can notify more than once (a finished child can
+* be resumed and run again within the same turn). Re-resume is rare in
+* planning flows and the ladder's one-stage-per-episode guard bounds the cost
+* of a stale read; if it ever false-fires, the interrupt is an Escape —
+* recoverable, transcript-safe.
+*/
+init_paths();
+/** Terminal background-task statuses recognized in notifications / TaskOutput results. */
+const TERMINAL_TASK_STATUSES = new Set([
+	"completed",
+	"failed",
+	"cancelled",
+	"killed",
+	"error"
+]);
+function extractText(content) {
+	if (typeof content === "string") return content;
+	if (Array.isArray(content)) return content.map((part) => {
+		if (part && typeof part === "object") {
+			const p = part;
+			if (p.type === "text" && typeof p.text === "string") return p.text;
+			if (p.type === "tool_result") return extractText(p.content);
+		}
+		return "";
+	}).join("\n");
+	return "";
+}
+function parseTaskNotification(content) {
+	if (!content.includes("<task-notification>")) return null;
+	const taskId = /<task-id>\s*([a-z0-9]+)\s*<\/task-id>/.exec(content)?.[1];
+	if (!taskId) return null;
+	return {
+		taskId,
+		status: /<status>\s*([a-z_-]+)\s*<\/status>/i.exec(content)?.[1]?.toLowerCase() ?? null
+	};
+}
+/**
+* True when a JSONL entry opens a new genuine user turn: a `user` entry with
+* string or text-only content (the kickoff prompt, a recovery-resume seed),
+* or a queue-operation `remove` of a NON-task-notification message (a
+* consumed operator `pan tell` — the harness folds it into context at that
+* point without writing a user entry). `user` entries made of tool_result
+* parts are turn machinery and NEVER boundaries; task-notification
+* queue-operations are the wedge evidence itself, also never boundaries.
+*/
+function isPromptBoundary(e) {
+	if (e.type === "queue-operation") {
+		const content = typeof e.content === "string" ? e.content : "";
+		return e.operation === "remove" && !content.includes("<task-notification>");
+	}
+	if (e.type !== "user") return false;
+	const content = e.message?.content;
+	if (typeof content === "string") return content.trim().length > 0;
+	if (Array.isArray(content)) {
+		const hasToolResult = content.some((p) => p && typeof p === "object" && p.type === "tool_result");
+		return content.some((p) => p && typeof p === "object" && p.type === "text") && !hasToolResult;
+	}
+	return false;
+}
+/**
+* Parse one session's JSONL entries (already-parsed JSON objects, in file
+* order) into the wedge evidence. At every genuine prompt boundary (see
+* isPromptBoundary), children already proven terminal are RETIRED — only
+* still-running children carry into the new turn, because real background
+* tasks outlive user turns. Unknown/malformed lines are ignored — a parser
+* miss always degrades to "not wedged", never to a false positive.
+*/
+function parseBackgroundTaskWedge(entries) {
+	let launched = [];
+	let terminal = /* @__PURE__ */ new Map();
+	let consumedNotifications = /* @__PURE__ */ new Set();
+	for (const entry of entries) {
+		if (!entry || typeof entry !== "object") continue;
+		const e = entry;
+		if (isPromptBoundary(e)) {
+			launched = launched.filter((id) => !terminal.has(id));
+			terminal = new Map([...terminal].filter(([id]) => launched.includes(id)));
+			consumedNotifications = new Set([...consumedNotifications].filter((id) => launched.includes(id)));
+			continue;
+		}
+		if (e.type === "queue-operation") {
+			const notification = parseTaskNotification(typeof e.content === "string" ? e.content : "");
+			if (!notification) continue;
+			if (e.operation === "remove") consumedNotifications.add(notification.taskId);
+			if (notification.status && TERMINAL_TASK_STATUSES.has(notification.status)) terminal.set(notification.taskId, notification.status);
+			continue;
+		}
+		const content = e.message?.content;
+		if (!Array.isArray(content)) continue;
+		for (const part of content) {
+			if (!part || typeof part !== "object") continue;
+			const p = part;
+			if (p.type !== "tool_result") continue;
+			const text = extractText(p.content);
+			if (text.includes("Async agent launched successfully")) {
+				const agentId = /agentId:\s*([a-z0-9]+)/.exec(text)?.[1];
+				if (agentId && !launched.includes(agentId)) launched.push(agentId);
+				continue;
+			}
+			if (text.includes("<retrieval_status>")) {
+				const taskId = /<task_id>\s*([a-z0-9]+)\s*<\/task_id>/.exec(text)?.[1];
+				const status = /<status>\s*([a-z_-]+)\s*<\/status>/i.exec(text)?.[1]?.toLowerCase();
+				if (taskId && status && TERMINAL_TASK_STATUSES.has(status)) {
+					terminal.set(taskId, status);
+					consumedNotifications.add(taskId);
+				}
+			}
+		}
+	}
+	const terminalTaskIds = launched.filter((id) => terminal.has(id));
+	const nonTerminalTaskIds = launched.filter((id) => !terminal.has(id));
+	const unconsumedTerminalTaskIds = terminalTaskIds.filter((id) => !consumedNotifications.has(id));
+	return {
+		launchedTaskIds: launched,
+		terminalTaskIds,
+		nonTerminalTaskIds,
+		unconsumedTerminalTaskIds,
+		wedged: launched.length > 0 && nonTerminalTaskIds.length === 0
+	};
+}
+/**
+* Read a session JSONL and return its wedge evidence, or null when the file
+* cannot be read/parsed — callers treat null as "not proven", never as wedged.
+*/
+function readBackgroundTaskWedgeEvidence(sessionPath) {
+	let raw;
+	try {
+		raw = readFileSync(sessionPath, "utf-8");
+	} catch {
+		return null;
+	}
+	const entries = [];
+	for (const line of raw.split("\n")) {
+		if (!line.trim()) continue;
+		try {
+			entries.push(JSON.parse(line));
+		} catch {}
+	}
+	return parseBackgroundTaskWedge(entries);
+}
+/**
+* Resolve an agent's CURRENT session through the production resolver
+* (resolveLatestSessionIdSync — the same door resumeAgent uses) and parse its
+* live JSONL. Returns null when there is no resumable session or no readable
+* transcript — always degrading to "not proven".
+*/
+function readAgentBackgroundTaskWedgeEvidence(agentId, workspace) {
+	const sessionId = resolveLatestSessionIdSync(agentId).sessionId;
+	if (!sessionId) return null;
+	return readBackgroundTaskWedgeEvidence(sessionFilePath(workspace, sessionId));
+}
+//#endregion
+//#region ../../lib/cloister/stuck-remediation.ts
+init_tmux();
+function issueIdForAgent(agent) {
+	return agent.issueId || agent.id.replace(/^agent-/, "").toUpperCase();
+}
+function shouldSkipReviewStatus(status) {
+	if (!status) return false;
+	if (status.stuck || status.deaconIgnored || status.mergeStatus === "merged" || status.readyForMerge) return true;
+	if (status.reviewStatus === "blocked" || status.reviewStatus === "failed") return true;
+	if (status.verificationStatus === "failed" || status.testStatus === "failed") return true;
+	if (status.reviewStatus === "reviewing" || status.reviewStatus === "passed") return true;
+	return status.reviewStatus === "pending" && !!status.reviewRequestedAt;
+}
+/**
+* PAN-2581 (FR-2, residual): phase gate for the health-check poke loop
+* (service.ts pokeAgent → pokeAgentWithEscalation → idle-alive pause), the
+* SECOND independent idleness consumer besides stuck-remediation. A warm-idle
+* work agent on a pipeline-owned issue — and a warm-idle review/test agent
+* after its verdict — must never be poked ("are you stuck?") or idle-alive
+* paused: the poke spends tokens re-explaining the wait, and the pause
+* manufactures the paused-delivery-target deadlock PAN-2461 exists to undo.
+* A genuinely stalled mid-review parent is covered by the PAN-2584 liveness
+* deadline, not pokes. Owed-rework agents (review blocked/failed, tests
+* failed) are ALSO skipped here by design: shouldSkipReviewStatus returns
+* true for those because the PAN-2519 wedged-rework path owns their
+* escalation — the health-check poke loop must not double-drive them.
+* Roles outside work/review/test (plan, strike, flywheel, sequencer) keep
+* their existing idleness semantics.
+*/
+function shouldSkipIdlePokeForAgent(agent, readStatus = getReviewStatusSync) {
+	if (!agent) return false;
+	if (agent.role !== "work" && agent.role !== "review" && agent.role !== "test") return false;
+	return shouldSkipReviewStatus(readStatus((agent.issueId || agent.id.replace(/^agent-/, "").replace(/-(review|test|ship)(-.*)?$/, "").replace(/-slot-\d+$/, "")).toUpperCase()));
+}
+function hasPendingRework(status) {
+	if (!status) return false;
+	if (status.stuck || status.deaconIgnored || status.mergeStatus === "merged" || status.readyForMerge) return false;
+	return status.reviewStatus === "blocked" || status.reviewStatus === "failed" || status.verificationStatus === "failed" || status.testStatus === "failed";
+}
+const STUCK_KILL_REQUEUE_CEILING = 25;
+async function evaluateWedgedReworkAgent(agent, config, now, actions) {
+	const agentId = agent.id;
+	if (agent.role !== "work" || !agent.workspace) return false;
+	const issueId = issueIdForAgent(agent);
+	const status = getReviewStatusSync(issueId);
+	if (!hasPendingRework(status)) return false;
+	const lastActivityMs = getAgentEffectiveLastActivityMs(agentId);
+	if (lastActivityMs === null || !Number.isFinite(lastActivityMs)) return false;
+	const stuckState = readStuckRemediationState(agentId);
+	if (stuckState) {
+		const firstStuckMs = new Date(stuckState.firstStuckAt).getTime();
+		if (Number.isFinite(firstStuckMs) && lastActivityMs > firstStuckMs) {
+			clearStuckRemediationState(agentId);
+			return false;
+		}
+	}
+	const idleMinutes = Math.floor((now - lastActivityMs) / 6e4);
+	const lastStage = stuckState?.lastStage ?? 0;
+	if (idleMinutes < config.stage3_minutes || lastStage >= 3) return false;
+	const firstStuck = firstStuckAt(new Date(lastActivityMs).toISOString(), stuckState);
+	if ((status?.autoRequeueCount ?? 0) >= STUCK_KILL_REQUEUE_CEILING) {
+		markAgentTroubled(agentId);
+		writeStuckRemediationState(agentId, stageState(3, now, firstStuck));
+		logAction(actions, transitionAction(3, issueId, idleMinutes, "rework-wedge-troubled"));
+		await surfaceStuckNeedsYou(agent, issueId, firstStuck, actions);
+		return true;
+	}
+	killSessionSync(agentId);
+	writeStuckRemediationState(agentId, stageState(3, now, firstStuck));
+	logAction(actions, transitionAction(3, issueId, idleMinutes, "killed-for-respawn"));
+	return true;
+}
+function shouldCheckReadyBeadsForAgent(agent, now) {
+	const agentId = agent.id;
+	if (!agentId) return false;
+	if (agent.status !== "running") return false;
+	if (agent.role !== "work") return false;
+	if (!agent.workspace) return false;
+	const completedAt = agent.completedAt;
+	if (agent.paused || agent.troubled || completedAt) return false;
+	if (!sessionExistsSync(agentId)) return false;
+	if (shouldSkipReviewStatus(getReviewStatusSync(issueIdForAgent(agent)))) return false;
+	return isAgentIdleForNudge(agentId, 300 * 1e3, now);
+}
+function firstStuckAt(runtimeLastActivity, stuckState) {
+	return stuckState?.firstStuckAt ?? runtimeLastActivity;
+}
+function stageState(stage, now, firstStuck, prev) {
+	return {
+		lastStage: stage,
+		lastStageAt: new Date(now).toISOString(),
+		firstStuckAt: firstStuck,
+		...prev?.respawnCount !== void 0 ? { respawnCount: prev.respawnCount } : {},
+		...prev?.lastRespawnAt !== void 0 ? { lastRespawnAt: prev.lastRespawnAt } : {}
+	};
+}
+function transitionAction(stage, issueId, idleMinutes, action) {
+	return `[deacon] stuck-remediation stage=${stage} issue=${issueId} idleMin=${idleMinutes} action=${action}`;
+}
+function logAction(actions, action) {
+	actions.push(action);
+	console.log(action);
+	logDeaconEventSync(action);
+}
+async function surfaceStuckNeedsYou(agent, issueId, generation, actions) {
+	if (!agent.workspace) return;
+	if ((await recordRecoveryFailure(agent.workspace, issueId, "stuck-remediation", generation, 1)).emitNeedsYou) logAction(actions, `[deacon] needs-you ${issueId}: stuck remediation exhausted`);
+}
+async function evaluateAgent(agent, config, now, actions) {
+	const agentId = agent.id;
+	if (!agentId) return;
+	if (agent.status !== "running") return;
+	const completedAt = agent.completedAt;
+	if (agent.paused || agent.troubled || completedAt) return;
+	if (agent.role === "flywheel") {
+		await evaluateFlywheelOrchestrator(agent, config, now, actions);
+		return;
+	}
+	if (!sessionExistsSync(agentId)) return;
+	if (agent.role === "plan") {
+		await evaluatePlanningAgent(agent, config, now, actions);
+		return;
+	}
+	if (await evaluateWedgedReworkAgent(agent, config, now, actions)) return;
+	if (!shouldCheckReadyBeadsForAgent(agent, now)) return;
+	if (!agent.workspace) return;
+	const issueId = issueIdForAgent(agent);
+	const plan = readWorkspacePlanSync(agent.workspace);
+	if (!plan) return;
+	if (getDispatchableItems(plan, /* @__PURE__ */ new Set()).length > 0) return;
+	const lastActivityMs = getAgentEffectiveLastActivityMs(agentId);
+	if (lastActivityMs === null) return;
+	if (!Number.isFinite(lastActivityMs)) return;
+	const lastActivity = new Date(lastActivityMs).toISOString();
+	const stuckState = readStuckRemediationState(agentId);
+	if (stuckState) {
+		const firstStuckMs = new Date(stuckState.firstStuckAt).getTime();
+		if (Number.isFinite(firstStuckMs) && lastActivityMs > firstStuckMs) {
+			clearStuckRemediationState(agentId);
+			return;
+		}
+	}
+	const idleMinutes = Math.floor((now - lastActivityMs) / 6e4);
+	const lastStage = stuckState?.lastStage ?? 0;
+	const firstStuck = firstStuckAt(lastActivity, stuckState);
+	const terminalProviderError = detectTerminalApiErrorSync(capturePaneSync(agentId, 80));
+	if (terminalProviderError) {
+		markAgentTroubled(agentId);
+		writeStuckRemediationState(agentId, stageState(3, now, firstStuck));
+		logAction(actions, `${agentId} provider-terminal: ${terminalProviderError.summary}`);
+		await surfaceStuckNeedsYou(agent, issueId, firstStuck, actions);
+		return;
+	}
+	if (idleMinutes >= config.stage3_minutes && lastStage < 3) {
+		markAgentTroubled(agentId);
+		writeStuckRemediationState(agentId, stageState(3, now, firstStuck));
+		logAction(actions, transitionAction(3, issueId, idleMinutes, "marked-troubled"));
+		await surfaceStuckNeedsYou(agent, issueId, firstStuck, actions);
+		return;
+	}
+	if (idleMinutes >= config.stage2_minutes && lastStage < 2) {
+		if ((await resumeAgent(agentId, `Resuming after auto-detected stall (${idleMinutes} min idle). Review your last work and decide whether to continue or signal done with \`pan done ${issueId}\`.`)).success) {
+			writeStuckRemediationState(agentId, stageState(2, now, firstStuck));
+			logAction(actions, transitionAction(2, issueId, idleMinutes, "resumed"));
+		} else {
+			const action = `${transitionAction(2, issueId, idleMinutes, "resume-failed")} — death: ${describeAgentDeath(agentId)}`;
+			console.warn(action);
+			logDeaconEventSync(action);
+		}
+		return;
+	}
+	if (idleMinutes >= config.stage1_minutes && lastStage < 1) {
+		await messageAgent(agentId, `You appear stuck — no tool calls for ${idleMinutes} min. If your implementation is complete, run \`pan done ${issueId}\`. Otherwise reply with a one-line summary of what you're waiting on, then continue.`);
+		writeStuckRemediationState(agentId, stageState(1, now, firstStuck));
+		logAction(actions, transitionAction(1, issueId, idleMinutes, "poked"));
+	}
+}
+function decidePlanningWedgeRemediation(opts) {
+	const { mirrorState, pendingQuestions, wedgeProven, workActivityMs, lastStage, now, config } = opts;
+	if (pendingQuestions > 0) return { kind: "none" };
+	if (mirrorState !== "active") return { kind: "none" };
+	if (!wedgeProven) return { kind: "none" };
+	if (workActivityMs === null || !Number.isFinite(workActivityMs)) return { kind: "none" };
+	const idleMinutes = Math.floor((now - workActivityMs) / 6e4);
+	if (idleMinutes >= config.stage3_minutes) {
+		if (lastStage >= 3) return { kind: "none" };
+		return {
+			kind: "troubled",
+			idleMinutes
+		};
+	}
+	if (idleMinutes >= config.stage2_minutes) {
+		if (lastStage >= 2) return { kind: "none" };
+		return {
+			kind: "kill-resume",
+			idleMinutes
+		};
+	}
+	if (idleMinutes >= config.stage1_minutes) {
+		if (lastStage >= 1) return { kind: "none" };
+		return {
+			kind: "interrupt-nudge",
+			idleMinutes
+		};
+	}
+	return { kind: "none" };
+}
+/**
+* Episode-clear rule for the planning wedge path, keyed on WORK activity only
+* (never pane repaints — the spinner would "clear" a still-wedged episode and
+* re-fire stage 1 every tick): work flowing after the episode opened means the
+* recovery worked.
+*/
+function shouldClearPlanningWedgeEpisode(stuckState, workActivityMs) {
+	if (!stuckState) return false;
+	const firstStuckMs = new Date(stuckState.firstStuckAt).getTime();
+	return Number.isFinite(firstStuckMs) && workActivityMs > firstStuckMs;
+}
+/**
+* Execute one wedge-ladder decision. Ordering is the contract: stage 1 sends
+* Escape BEFORE queueing its single nudge (the interrupt returns the prompt;
+* the nudge — and any queued operator messages — are processed after). Stage 2
+* kills the session and plain-resumes the SAME saved session id, so the
+* transcript (and every explorer's findings) survives — unlike the
+* compact-respawn path that lost conversation-only survey notes in the manual
+* MIN-889 recovery.
+*/
+async function executePlanningWedgeDecision(agentId, issueId, decision, firstStuck, now, deps) {
+	if (decision.kind === "interrupt-nudge") {
+		try {
+			await deps.sendEscape(agentId);
+		} catch (err) {
+			console.error(`[deacon] Failed to interrupt wedged planning session ${agentId}:`, err);
+			return;
+		}
+		const message = `Your previous turn stalled for ${decision.idleMinutes} min with no progress and was interrupted (a hung provider call). Process any queued operator messages first. Then collect background-task results NON-blocking (TaskOutput with block:false) — every child that reached a terminal state already has its result or error available; do NOT re-enter a blocking wait. Continue planning now: write the PRD/xBRIEF artifacts and proceed to your instructed stopping point.`;
+		let deliveryError = null;
+		try {
+			await deps.message(agentId, message);
+		} catch (err) {
+			deliveryError = err instanceof Error ? err.message : String(err);
+		}
+		deps.writeState(agentId, stageState(1, now, firstStuck));
+		deps.log(deliveryError ? `${transitionAction(1, issueId, decision.idleMinutes, "interrupted-wedged-turn")} — nudge delivery failed: ${deliveryError}` : transitionAction(1, issueId, decision.idleMinutes, "interrupted-wedged-turn"));
+		return;
+	}
+	if (decision.kind === "kill-resume") {
+		try {
+			await deps.killSession(agentId);
+		} catch {}
+		const message = `Resuming after an automated stall recovery (${decision.idleMinutes} min with no progress). Your transcript is intact — continue planning from where you left off. Collect background-task results NON-blocking (TaskOutput with block:false) and proceed.`;
+		const result = await deps.resume(agentId, message);
+		if (result.success) {
+			deps.writeState(agentId, stageState(2, now, firstStuck));
+			deps.log(transitionAction(2, issueId, decision.idleMinutes, "kill-resumed-wedged-planning"));
+		} else {
+			deps.markTroubled(agentId);
+			deps.writeState(agentId, stageState(3, now, firstStuck));
+			deps.log(`${transitionAction(3, issueId, decision.idleMinutes, "kill-resume-failed-troubled")} — ${result.error ?? "unknown"}`);
+			await deps.surfaceNeedsYou();
+		}
+		return;
+	}
+	deps.markTroubled(agentId);
+	deps.writeState(agentId, stageState(3, now, firstStuck));
+	deps.log(transitionAction(3, issueId, decision.idleMinutes, "wedged-planning-troubled"));
+	await deps.surfaceNeedsYou();
+}
+async function evaluatePlanningAgent(agent, config, now, actions) {
+	const agentId = agent.id;
+	const issueId = issueIdForAgent(agent);
+	const pendingQuestions = await Effect.runPromise(countPendingAskUserQuestionsForAgent(agentId));
+	if (pendingQuestions > 0) {
+		if (!isAgentIdleForNudge(agentId, 300 * 1e3, now)) return;
+		if (agent.auto !== true) return;
+		const lastActivityMs = getAgentEffectiveLastActivityMs(agentId);
+		if (lastActivityMs === null || !Number.isFinite(lastActivityMs)) return;
+		const lastActivity = new Date(lastActivityMs).toISOString();
+		const stuckState = readStuckRemediationState(agentId);
+		if (stuckState) {
+			const firstStuckMs = new Date(stuckState.firstStuckAt).getTime();
+			if (Number.isFinite(firstStuckMs) && lastActivityMs > firstStuckMs) {
+				clearStuckRemediationState(agentId);
+				return;
+			}
+		}
+		const idleMinutes = Math.floor((now - lastActivityMs) / 6e4);
+		const lastStage = stuckState?.lastStage ?? 0;
+		if (idleMinutes < config.stage1_minutes || lastStage >= 1) return;
+		await messageAgent(agentId, `This planning session was launched with \`pan plan ${issueId} --auto\`, so do not wait for operator input. Proceed with the most defensible default from the issue/PRD/comments, record the choice in \`plan.autoDecisions[]\` with rationale, and continue to \`pan plan finalize\`. Only halt for a genuine contradiction between authoritative inputs.`);
+		writeStuckRemediationState(agentId, stageState(1, now, firstStuckAt(lastActivity, stuckState)));
+		logAction(actions, transitionAction(1, issueId, idleMinutes, "auto-planning-default"));
+		return;
+	}
+	const workActivityMs = getAgentWorkActivityMs(agentId);
+	if (workActivityMs === null || !Number.isFinite(workActivityMs)) return;
+	const stuckState = readStuckRemediationState(agentId);
+	if (shouldClearPlanningWedgeEpisode(stuckState, workActivityMs)) {
+		clearStuckRemediationState(agentId);
+		return;
+	}
+	const mirrorState = getAgentRuntimeStateSync(agentId)?.state ?? null;
+	if (mirrorState !== "active") return;
+	if (Math.floor((now - workActivityMs) / 6e4) < config.stage1_minutes) return;
+	const decision = decidePlanningWedgeRemediation({
+		mirrorState,
+		pendingQuestions,
+		wedgeProven: agent.workspace ? readAgentBackgroundTaskWedgeEvidence(agentId, agent.workspace)?.wedged === true : false,
+		workActivityMs,
+		lastStage: stuckState?.lastStage ?? 0,
+		now,
+		config
+	});
+	if (decision.kind === "none") return;
+	await executePlanningWedgeDecision(agentId, issueId, decision, firstStuckAt(new Date(workActivityMs).toISOString(), stuckState), now, {
+		sendEscape: (id) => sendEscapeKeyAsync(id),
+		message: (id, msg) => messageAgent(id, msg),
+		killSession: (id) => Effect.runPromise(killSession(id)),
+		resume: (id, msg) => resumeAgent(id, msg),
+		markTroubled: (id) => markAgentTroubled(id),
+		writeState: (id, state) => writeStuckRemediationState(id, state),
+		surfaceNeedsYou: () => surfaceStuckNeedsYou(agent, issueId, firstStuckAt(new Date(workActivityMs).toISOString(), stuckState), actions),
+		log: (msg) => logAction(actions, msg)
+	});
+}
+const FLYWHEEL_RESPAWN_WINDOW_MS = 1800 * 1e3;
+const FLYWHEEL_MAX_RESPAWNS = 3;
+const FLYWHEEL_ORCHESTRATOR_AGENT_ID = "flywheel-orchestrator";
+/**
+* Pure decision for recovering a dead or wedged flywheel orchestrator (no I/O —
+* side effects live in remediateFlywheelOrchestrator). The respawn cap
+* (FLYWHEEL_MAX_RESPAWNS within FLYWHEEL_RESPAWN_WINDOW_MS) stops an infinite
+* relaunch loop: past the cap, escalate to paused+troubled. `hasActiveRun` false
+* ⇒ the operator stopped the flywheel deliberately ⇒ do not resurrect.
+*/
+function decideFlywheelRemediation(opts) {
+	if (!opts.hasActiveRun) return { kind: "noop" };
+	const lastRespawnMs = opts.prev?.lastRespawnAt ? new Date(opts.prev.lastRespawnAt).getTime() : 0;
+	const respawnCount = Number.isFinite(lastRespawnMs) && opts.now - lastRespawnMs < FLYWHEEL_RESPAWN_WINDOW_MS ? opts.prev?.respawnCount ?? 0 : 0;
+	if (respawnCount >= FLYWHEEL_MAX_RESPAWNS) return {
+		kind: "escalate",
+		respawnCount
+	};
+	return {
+		kind: "relaunch",
+		respawnCount: respawnCount + 1
+	};
+}
+/** True when the orchestrator's process is actually gone (session missing or dead pane). */
+function isFlywheelOrchestratorDead(agentId) {
+	if (!sessionExistsSync(agentId)) return true;
+	return listPaneValuesSync(agentId, "#{pane_dead}").some((v) => v === "1");
+}
+/**
+* Recover a dead or wedged flywheel orchestrator: relaunch (capped) or, past the
+* cap, pause+trouble. `reason` describes why recovery fired (death vs wedge) for
+* the deacon log. NO_RESUME is intentionally NOT consulted (see header comment) —
+* the operator gate is the active run (`pan flywheel stop`) / patrol freeze.
+*/
+async function remediateFlywheelOrchestrator(agentId, now, actions, reason) {
+	const decision = decideFlywheelRemediation({
+		hasActiveRun: Boolean(getFlywheelActiveRunId()),
+		prev: readStuckRemediationState(agentId),
+		now
+	});
+	if (decision.kind === "noop") return;
+	const { resumeFlywheel, pauseFlywheel } = await import("./flywheel-HJt7QdWP.js");
+	const prev = readStuckRemediationState(agentId);
+	const nowIso = new Date(now).toISOString();
+	if (decision.kind === "escalate") {
+		await pauseFlywheel();
+		markAgentTroubled(agentId);
+		writeStuckRemediationState(agentId, {
+			lastStage: 3,
+			lastStageAt: nowIso,
+			firstStuckAt: prev?.firstStuckAt ?? nowIso,
+			respawnCount: decision.respawnCount,
+			lastRespawnAt: prev?.lastRespawnAt
+		});
+		logAction(actions, `[deacon] FLYWHEEL orchestrator ${reason} and exceeded ${FLYWHEEL_MAX_RESPAWNS} relaunches in ${FLYWHEEL_RESPAWN_WINDOW_MS / 6e4}min — paused + troubled; operator needed`);
+		return;
+	}
+	try {
+		killSessionSync(agentId);
+	} catch {}
+	try {
+		await resumeFlywheel({ resumeCause: "system" });
+		writeStuckRemediationState(agentId, {
+			lastStage: 0,
+			lastStageAt: nowIso,
+			firstStuckAt: nowIso,
+			respawnCount: decision.respawnCount,
+			lastRespawnAt: nowIso
+		});
+		logAction(actions, `[deacon] FLYWHEEL orchestrator ${reason} — fresh-launched (relaunch ${decision.respawnCount}/${FLYWHEEL_MAX_RESPAWNS})`);
+	} catch (error) {
+		logAction(actions, `[deacon] FLYWHEEL orchestrator ${reason} — relaunch FAILED: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+async function evaluateFlywheelOrchestrator(agent, config, now, actions) {
+	const agentId = agent.id;
+	if (isFlywheelOrchestratorDead(agentId)) {
+		await remediateFlywheelOrchestrator(agentId, now, actions, `DIED (${describeAgentDeath(agentId)})`);
+		return;
+	}
+	if (!isAgentIdleForNudge(agentId, 300 * 1e3, now)) return;
+	const runtime = getAgentRuntimeStateSync(agentId);
+	if (!runtime?.lastActivity) return;
+	const lastActivityMs = new Date(runtime.lastActivity).getTime();
+	if (!Number.isFinite(lastActivityMs)) return;
+	const stuckState = readStuckRemediationState(agentId);
+	if (stuckState) {
+		const firstStuckMs = new Date(stuckState.firstStuckAt).getTime();
+		if (Number.isFinite(firstStuckMs) && lastActivityMs > firstStuckMs) {
+			clearStuckRemediationState(agentId);
+			return;
+		}
+	}
+	const idleMinutes = Math.floor((now - lastActivityMs) / 6e4);
+	const lastStage = stuckState?.lastStage ?? 0;
+	const firstStuck = firstStuckAt(runtime.lastActivity, stuckState);
+	if (idleMinutes >= config.flywheel_stage3_minutes && lastStage < 3) {
+		await remediateFlywheelOrchestrator(agentId, now, actions, `wedged (idle ${idleMinutes}min)`);
+		return;
+	}
+	if (idleMinutes >= config.flywheel_stage2_minutes && lastStage < 2) {
+		await messageAgent(agentId, `Stage 2: idle ${idleMinutes} min — run a FULL flywheel tick NOW: inventory -> diagnose -> suggest -> launch ready work -> \`pan flywheel emit-status\`. Then call ScheduleWakeup(delaySeconds:1000) to arm the next tick. Do NOT ask the operator a question, do NOT wait, and do NOT just emit a stale status or pause.`);
+		writeStuckRemediationState(agentId, stageState(2, now, firstStuck, stuckState));
+		logAction(actions, transitionAction(2, "FLYWHEEL", idleMinutes, "escalated-nudge"));
+		return;
+	}
+	if (idleMinutes >= config.flywheel_stage1_minutes && lastStage < 1) {
+		await messageAgent(agentId, `You appear stuck — ${idleMinutes} min since your last tick. Run a FULL flywheel tick NOW: inventory -> diagnose -> suggest -> launch ready work -> \`pan flywheel emit-status\`. Then call ScheduleWakeup(delaySeconds:1000) to arm the next tick. Do NOT ask the operator a question, do NOT wait, and do NOT just emit a stale status or pause.`);
+		writeStuckRemediationState(agentId, stageState(1, now, firstStuck, stuckState));
+		logAction(actions, transitionAction(1, "FLYWHEEL", idleMinutes, "poked"));
+	}
+}
+async function reconcileActiveFlywheelWithoutRunningAgent(now, actions) {
+	if (!getFlywheelActiveRunId()) return;
+	if (isFlywheelGloballyPaused()) return;
+	if (sessionExistsSync(FLYWHEEL_ORCHESTRATOR_AGENT_ID)) return;
+	await remediateFlywheelOrchestrator(FLYWHEEL_ORCHESTRATOR_AGENT_ID, now, actions, `DIED (${describeAgentDeath(FLYWHEEL_ORCHESTRATOR_AGENT_ID)})`);
+}
+async function checkStuckAgentRemediation(opts = {}) {
+	const config = loadCloisterConfigSync().stuck_remediation ?? DEFAULT_CLOISTER_CONFIG.stuck_remediation;
+	if (!config.enabled) return [];
+	const actions = [];
+	const now = opts.now ?? Date.now();
+	const runningAgents = listRunningAgentsSync();
+	let sawFlywheelOrchestrator = false;
+	for (const agent of runningAgents) {
+		if (agent.id === FLYWHEEL_ORCHESTRATOR_AGENT_ID || agent.role === "flywheel") sawFlywheelOrchestrator = true;
+		try {
+			await evaluateAgent(agent, config, now, actions);
+		} catch (error) {
+			const message = `[deacon] stuck-remediation agent=${agent.id || "(unknown)"} error=${error instanceof Error ? error.message : String(error)}`;
+			console.error(message, error);
+			logDeaconEventSync(message);
+		}
+	}
+	if (!sawFlywheelOrchestrator) try {
+		await reconcileActiveFlywheelWithoutRunningAgent(now, actions);
+	} catch (error) {
+		const message = `[deacon] stuck-remediation agent=${FLYWHEEL_ORCHESTRATOR_AGENT_ID} error=${error instanceof Error ? error.message : String(error)}`;
+		console.error(message, error);
+		logDeaconEventSync(message);
+	}
+	return actions;
+}
+//#endregion
+export { shouldClearPlanningWedgeEpisode as a, executePlanningWedgeDecision as i, decideFlywheelRemediation as n, shouldSkipIdlePokeForAgent as o, decidePlanningWedgeRemediation as r, shouldSkipReviewStatus as s, checkStuckAgentRemediation as t };
+
+//# sourceMappingURL=stuck-remediation-BDa_tXgB.js.map