pi-orchestrator-config 4.3.10 → 4.3.12

package/README.md

@@ -104,6 +104,17 @@ Two systems for Pi agents to communicate with each other, activated on-demand vi
 | `*_send`  | Send a prompt to a peer agent                                   |
 | `*_get`   | Non-blocking poll for a response                                |
 | `*_await` | Block until response arrives                                    |
+| `coms_queue_inspect` | Preview owned queued P2P messages before recovery             |
+| `coms_queue_clear` | Irreversibly clear only an inspect preview                     |
+
+Queue recovery is explicit. Run `coms_queue_inspect` first and review its
+body-free preview. Then pass its `preview_id` to `coms_queue_clear`.
+Reconnects and timeouts never clear queues. This recovers the local P2P coms
+queue. Pi RPC hosts may separately offer `clear_queue` for their steering and
+follow-up queue. It is a distinct queue and must also be previewed and cleared
+explicitly. RPC preview tokens expire after five minutes, retain at most 20
+entries per provider, and require a host-side atomic snapshot comparison before
+clearing.
 
 Forked from [disler/pi-vs-claude-code](https://github.com/disler/pi-vs-claude-code) coms extensions. We own these files — FIFO message queue, structured task delegation via coms protocol.
 
@@ -562,7 +573,7 @@ Pidash is a web-based dashboard that runs alongside the TUI, accessible from any
 - Event buffering for message replay on refresh
 - Browser push notifications for background events (configurable per event type)
 - Async agent live streaming (real-time tool calls and output inline in chat)
-- Sidebar session working indicator (pulsing green dot when AI is active)
+- Session activity state distinguishes working, waiting for input, and idle. Prompt wait is not counted or styled as active work; streaming and queued browser prompts remain separate.
 - `[HH:MM]` timestamps on all messages
 
 **Access:**
@@ -831,7 +842,7 @@ See [DEVELOPMENT.md](DEVELOPMENT.md) for tips on testing extensions locally, run
 
 ## Prerequisites
 
-- [pi](https://github.com/badlogic/pi-mono) (minimum version: **0.84.0**)
+- [pi](https://github.com/badlogic/pi-mono) (minimum version: **0.84.4**). Pidash uses Pi's `ui_prompt_start` and `ui_prompt_end` events to show prompt wait separately from agent work.
 - `gh` CLI (for GitHub operations)
 - `uv` (for Python execution)
 - `myk-pi-tools` (optional, for `/pr-review` and `/release`)

package/extensions/coms/coms-p2p.ts

@@ -32,10 +32,13 @@ import { createLogger } from "../shared/logger.js";
 import { setLogFilePrefix } from "../shared/file-logger.js";
 import { probeStaleSocket } from "./probe-socket.js";
 import { isUserMessageDuringInbound, computeMixedTurn } from "./mixed-turn.js";
+import { buildQueuePreview, clearLocalQueue, type QueueRecoveryItem, type QueueRecoveryPreview } from "./queue-recovery.js";
 
 // ━━ Constants ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 const log = createLogger("coms");
+const RECOVERY_PREVIEW_TTL_MS = 5 * 60 * 1000;
+const MAX_RECOVERY_PREVIEWS_PER_SESSION = 20;
 let COMS_DIR = path.join(os.homedir(), ".pi", "coms");
 let MAX_HOPS = 5;
 
@@ -89,9 +92,10 @@ interface TaskUpdateEnvelope extends Envelope {
 
 interface QueueManageEnvelope extends Envelope {
 	type: "queue_manage";
-	action: "delete" | "edit" | "clear" | "prioritize";
+	action: "inspect" | "delete" | "edit" | "clear" | "prioritize";
 	target_msg_id?: string;
 	new_content?: string;
+	preview_id?: string;
 	sender_name: string;
 }
 
@@ -157,6 +161,8 @@ interface PendingReply {
 	result?: { response?: any; error?: string | null; queued_msg_ids?: string[] };
 	target_name?: string;
 	created_at: string;
+	/** Creation time drives body-free recovery previews. */
+	queued_at?: string;
 }
 
 interface InboundContext {
@@ -169,6 +175,7 @@ interface InboundContext {
 	prompt: string;
 	tasks?: Array<{ subject: string; description: string }> | null;
 	response_schema?: object | null;
+	queued_at: string;
 	fulfilled: boolean;
 	/** How many times this inbound was re-injected due to mixed-turn conflict */
 	mixedTurnRetries?: number;
@@ -613,6 +620,27 @@ export default function (pi: ExtensionAPI) {
 	/** Track pending (unresponded) outbound msg_ids per target name. */
 	const pendingOutbound: Map<string, Set<string>> = new Map();
 	const inboundQueue: Map<string, InboundContext> = new Map();
+	/** Destructive recovery is valid only after an explicit, short-lived inspect preview. */
+	const queueRecoveryPreviews = new Map<string, { targetSession: string; itemIds: string[]; expiresAt: number }>();
+
+	function pruneQueueRecoveryPreviews(now = Date.now()): void {
+		let removed = 0;
+		for (const [previewId, preview] of queueRecoveryPreviews) {
+			if (preview.expiresAt <= now) {
+				queueRecoveryPreviews.delete(previewId);
+				removed++;
+			}
+		}
+		if (removed) log.debug("recovery_previews_pruned", { removed, remaining: queueRecoveryPreviews.size });
+	}
+
+	function retainQueueRecoveryPreview(previewId: string, targetSession: string, itemIds: string[]): void {
+		pruneQueueRecoveryPreviews();
+		const sessionPreviews = [...queueRecoveryPreviews.entries()].filter(([, preview]) => preview.targetSession === targetSession);
+		for (const [expiredId] of sessionPreviews.slice(0, Math.max(0, sessionPreviews.length - MAX_RECOVERY_PREVIEWS_PER_SESSION + 1))) queueRecoveryPreviews.delete(expiredId);
+		queueRecoveryPreviews.set(previewId, { targetSession, itemIds, expiresAt: Date.now() + RECOVERY_PREVIEW_TTL_MS });
+		log.debug("recovery_preview_retained", { session: targetSession, count: itemIds.length, active: queueRecoveryPreviews.size });
+	}
 	let server: net.Server | null = null;
 	let fsWatcher: fs.FSWatcher | null = null;
 	let pingWorker: Worker | null = null;
@@ -700,9 +728,11 @@ export default function (pi: ExtensionAPI) {
 			prompt: env.prompt,
 			tasks: Array.isArray(env.tasks) ? env.tasks : null,
 			response_schema: env.response_schema ?? null,
+			queued_at: nowIso(),
 			fulfilled: false,
 		};
 		inboundQueue.set(env.msg_id, inbound);
+		log.debug("recovery_inbound_enqueued", { msgId: env.msg_id, sender: env.sender_name, state: "queued" });
 		maybeRefreshWidget();
 
 		// 3. If already processing another inbound, just queue — agent_end will drain FIFO.
@@ -954,6 +984,7 @@ export default function (pi: ExtensionAPI) {
 	// ━━ queue_manage handler ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 	// Only the message OWNER (sender_session match) can manage their messages.
 	function handleQueueManage(socket: net.Socket, env: QueueManageEnvelope): void {
+		pruneQueueRecoveryPreviews();
 		const action = env.action;
 		let affected = 0;
 		let error: string | null = null;
@@ -980,19 +1011,54 @@ export default function (pi: ExtensionAPI) {
 		};
 
 		if (action === "delete" && env.target_msg_id) {
+			const preview = env.preview_id ? queueRecoveryPreviews.get(env.preview_id) : undefined;
 			const ib = inboundQueue.get(env.target_msg_id);
-			if (!ib) { error = "not_found"; }
+			if (!env.preview_id) { error = "preview_required"; }
+			else if (!preview || preview.targetSession !== env.sender_session || !preview.itemIds.includes(env.target_msg_id)) { error = "invalid_preview"; }
+			else if (!ib) { error = "not_found"; }
 			else if (!isOwned(ib)) { error = "not_owned"; }
-			else { dropInbound(ib); affected++; }
+			else { dropInbound(ib); queueRecoveryPreviews.delete(env.preview_id); affected++; }
 		} else if (action === "edit" && env.target_msg_id && typeof env.new_content === "string") {
 			const ib = inboundQueue.get(env.target_msg_id);
 			if (!ib) { error = "not_found"; }
 			else if (!isOwned(ib)) { error = "not_owned"; }
 			else { ib.prompt = env.new_content; affected++; }
 		} else if (action === "clear") {
-			for (const ib of [...inboundQueue.values()]) {
-				if (isOwned(ib)) { dropInbound(ib); affected++; }
+			if (!env.preview_id) {
+				error = "preview_required";
+			} else {
+				const storedPreview = queueRecoveryPreviews.get(env.preview_id);
+				if (!storedPreview || storedPreview.targetSession !== env.sender_session) {
+					error = "invalid_preview";
+					try { socket.write(JSON.stringify({ type: "ack", msg_id: env.msg_id, affected, error }) + "\n"); } catch {}
+					log.warn("recovery_clear_denied", { sender: env.sender_name, reason: error });
+					return;
+				}
+				const items = [...inboundQueue.values()].filter(isOwned).map((ib, index): QueueRecoveryItem => ({
+					id: ib.msg_id, sender: ib.sender_name, target: identity?.name ?? "local", queuedAt: ib.queued_at,
+					position: index + 1, deliveryState: "queued",
+				}));
+				const outcome = clearLocalQueue(items, storedPreview.itemIds);
+				if (outcome.outcome === "partial") {
+					error = "preview_stale";
+				} else {
+					for (const item of outcome.cleared) {
+						const inbound = inboundQueue.get(item.id);
+						if (inbound && isOwned(inbound)) { dropInbound(inbound); affected++; }
+					}
+				}
+				queueRecoveryPreviews.delete(env.preview_id);
 			}
+		} else if (action === "inspect") {
+			const items = [...inboundQueue.values()].filter(isOwned).map((ib, index): QueueRecoveryItem => ({
+				id: ib.msg_id, sender: ib.sender_name, target: identity?.name ?? "local", queuedAt: ib.queued_at,
+				position: index + 1, deliveryState: "queued",
+			}));
+			const preview = buildQueuePreview("local", items, Date.now(), ulid());
+			retainQueueRecoveryPreview(preview.previewId, env.sender_session, preview.items.map(item => item.id));
+			try { socket.write(JSON.stringify({ type: "ack", msg_id: env.msg_id, affected: 0, error: null, preview }) + "\n"); } catch {}
+			log.info("recovery_preview", { provider: "local", sender: env.sender_name, count: preview.items.length });
+			return;
 		} else if (action === "prioritize" && env.target_msg_id) {
 			const ib = inboundQueue.get(env.target_msg_id);
 			if (!ib) { error = "not_found"; }
@@ -1015,7 +1081,8 @@ export default function (pi: ExtensionAPI) {
 		} catch { /* ignore */ }
 
 		maybeRefreshWidget();
-		log.debug("queue_manage", action, "target", env.target_msg_id, "affected", affected, "error", error);
+		const recoveryLog = error === "preview_required" || error === "invalid_preview" || error === "preview_stale" ? log.warn : error ? log.error : log.info;
+		recoveryLog("recovery_local_result", { action, affected, outcome: error ? "failure" : "success", error });
 	}
 
 	// ━━ task_manage handler — remote task operations from peers ━━━━━━━━━━━
@@ -1344,7 +1411,9 @@ export default function (pi: ExtensionAPI) {
 - coms_list — see connected peers
 - coms_send — send a message to a peer
 - coms_get — check status of a sent message
-- coms_queue_delete / coms_queue_edit / coms_queue_clear / coms_queue_prioritize — manage queued messages
+- coms_queue_inspect — preview owned inbound queue items before recovery (no message bodies)
+- coms_queue_clear — irreversibly clear only a prior inspect preview; never clears automatically
+- coms_queue_delete / coms_queue_edit / coms_queue_prioritize — manage queued messages
 - coms_tasks_create — create tasks on a peer's task list with auto-report and auto-message
 - coms_task_delete — delete a task you created on a peer's task list
 - coms_task_list — list tasks on a peer's task list without sending a message
@@ -1886,7 +1955,7 @@ Do not respond to this message.`;
 				subject: Type.String({ description: "Brief task title" }),
 				description: Type.String({ description: "Detailed task description" }),
 			}), { description: "Optional structured tasks to create in the peer's task list." })),
-			clearPrevious: Type.Optional(Type.Boolean({ description: "If true, clear all your prior pending messages on the receiver before delivering this one." })),
+			clearPrevious: Type.Optional(Type.Boolean({ description: "Deprecated and rejected: inspect with coms_queue_inspect, then explicitly clear using preview_id." })),
 		}),
 		async execute(_callId, params) {
 			if (!identity) {
@@ -1906,7 +1975,7 @@ Do not respond to this message.`;
 			}
 			// Clear sender's prior pending messages on the receiver before delivering
 			if (params.clearPrevious) {
-				try { await sendQueueManage(target, "clear"); } catch { /* best-effort */ }
+				throw new Error("coms_send clearPrevious is no longer allowed. Inspect with coms_queue_inspect, then explicitly clear with its preview_id.");
 			}
 			const hops = currentInbound ? currentInbound.hops + 1 : 0;
 			if (hops >= MAX_HOPS) {
@@ -2091,7 +2160,7 @@ Do not respond to this message.`;
 	// ━━ coms queue management tools ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 	/** Send a queue_manage envelope to a peer. Only affects messages owned by this session. */
-	async function sendQueueManage(target: { name: string; endpoint: string }, action: string, targetMsgId?: string, newContent?: string): Promise<{ affected?: number; error?: string | null }> {
+	async function sendQueueManage(target: { name: string; endpoint: string }, action: string, targetMsgId?: string, newContent?: string, previewId?: string): Promise<{ affected?: number; error?: string | null; preview?: unknown }> {
 		if (!identity) throw new Error("coms not initialised");
 		const ack = await sendEnvelope(target.endpoint, {
 			type: "queue_manage",
@@ -2103,23 +2172,60 @@ Do not respond to this message.`;
 			action,
 			target_msg_id: targetMsgId,
 			new_content: newContent,
+			preview_id: previewId,
 			sender_name: identity.name,
 		});
-		return { affected: ack?.affected, error: ack?.error };
+		return { affected: ack?.affected, error: ack?.error, preview: ack?.preview };
 	}
 
+	pi.registerTool({
+		name: "coms_queue_inspect",
+		label: "Coms Queue Inspect",
+		description: "Preview your queued inbound messages on a peer before any irreversible recovery. Returns IDs, sender, target, age, FIFO position, and delivery state, never full message bodies. Pass preview_id to coms_queue_clear.",
+		parameters: Type.Object({
+			target: Type.String({ description: "Peer name or session_id." }),
+		}),
+		async execute(_callId, params) {
+			const target = await resolveTarget(params.target);
+			if (!target) throw new Error(`coms: no live agent matching "${params.target}"`);
+			const result = await sendQueueManage(target, "inspect");
+			const preview = result.preview as QueueRecoveryPreview | undefined;
+			if (result.error || !preview || preview.outcome !== "supported" || !preview.previewId || !Array.isArray(preview.items)) {
+				throw new Error(`coms_queue_inspect failed: ${result.error ?? "malformed preview"}`);
+			}
+			log.info("recovery_inspect_requested", { target: target.name, previewId: preview.previewId, count: preview.items.length });
+			const itemLines = preview.items.map(item =>
+				`- id: ${item.id} | sender: ${item.sender} | target: ${item.target} | age_ms: ${item.ageMs} | position: ${item.position} | delivery_state: ${item.deliveryState}`,
+			);
+			return {
+				content: [{
+					type: "text" as const,
+					text: [
+						`coms_queue_inspect → ${target.name}`,
+						"Review this preview before clearing. No message bodies are shown.",
+						`preview_id: ${preview.previewId}`,
+						`items: ${preview.items.length}`,
+						...itemLines,
+					].join("\n"),
+				}],
+				details: preview,
+			};
+		},
+	});
+
 	pi.registerTool({
 		name: "coms_queue_delete",
 		label: "Coms Queue Delete",
-		description: "Delete your message from a peer's queue. Only works on your own pending messages.",
+		description: "Irreversibly delete one of your messages shown by coms_queue_inspect. Only the owner may delete it.",
 		parameters: Type.Object({
 			target: Type.String({ description: "Peer name or session_id." }),
-			msg_id: Type.String({ description: "The msg_id to delete from the peer's queue." }),
+			msg_id: Type.String({ description: "The inspected msg_id to delete from the peer's queue." }),
+			preview_id: Type.String({ description: "previewId returned by coms_queue_inspect for this peer." }),
 		}),
 		async execute(_callId, params) {
 			const target = await resolveTarget(params.target);
 			if (!target) throw new Error(`coms: no live agent matching "${params.target}"`);
-			const result = await sendQueueManage(target, "delete", params.msg_id);
+			const result = await sendQueueManage(target, "delete", params.msg_id, undefined, params.preview_id);
 			if (result.error) throw new Error(`coms_queue_delete failed: ${result.error}`);
 			return { content: [{ type: "text" as const, text: `coms_queue_delete → ${target.name}\nmsg_id: ${params.msg_id}` }] };
 		},
@@ -2146,15 +2252,18 @@ Do not respond to this message.`;
 	pi.registerTool({
 		name: "coms_queue_clear",
 		label: "Coms Queue Clear",
-		description: "Delete ALL your pending messages from a peer's queue. Only affects your own messages.",
+		description: "Irreversibly clear only the messages shown by a preceding coms_queue_inspect preview. Ownership is enforced by the peer; untouched messages retain FIFO order.",
 		parameters: Type.Object({
 			target: Type.String({ description: "Peer name or session_id." }),
+			preview_id: Type.String({ description: "previewId returned by coms_queue_inspect for this peer." }),
 		}),
 		async execute(_callId, params) {
 			const target = await resolveTarget(params.target);
 			if (!target) throw new Error(`coms: no live agent matching "${params.target}"`);
-			await sendQueueManage(target, "clear");
-			return { content: [{ type: "text" as const, text: `coms_queue_clear → ${target.name}` }] };
+			const result = await sendQueueManage(target, "clear", undefined, undefined, params.preview_id);
+			if (result.error) throw new Error(`coms_queue_clear failed: ${result.error}`);
+			log.info("recovery_clear_requested", { target: target.name, affected: result.affected ?? 0 });
+			return { content: [{ type: "text" as const, text: `coms_queue_clear → ${target.name}\ncleared: ${result.affected ?? 0}` }], details: { affected: result.affected ?? 0, preview_id: params.preview_id } };
 		},
 	});
 
@@ -3163,6 +3272,8 @@ Do not respond to this message.`;
 			try { removeRegistryEntry(ident.project, ident.coms_session_id); } catch { /* ignore */ }
 			log.info("shutdown", ident.coms_session_id);
 		}
+		queueRecoveryPreviews.clear();
+		log.debug("recovery_previews_cleared", { reason: "shutdown" });
 		if (currentCtx?.hasUI) {
 			try { currentCtx.ui.setWidget("coms-pool", undefined); } catch { /* ignore */ }
 			try { currentCtx.ui.setStatus("coms", undefined); } catch { /* ignore */ }

package/extensions/coms/queue-recovery.ts

@@ -0,0 +1,196 @@
+/**
+ * Queue recovery contracts shared by the P2P queue tools and optional RPC hosts.
+ * Recovery is intentionally two-step: callers must retain a previewId from inspect
+ * and pass it to a destructive operation. Message text never belongs in a preview.
+ */
+import { createHash } from "node:crypto";
+import { createLogger } from "../shared/logger.js";
+
+const log = createLogger("coms");
+export const RPC_RECOVERY_PREVIEW_TTL_MS = 5 * 60 * 1000;
+export const MAX_RPC_RECOVERY_PREVIEWS_PER_PROVIDER = 20;
+
+interface RpcPreviewRecord {
+  snapshot: string;
+  items: QueueRecoveryItem[];
+  expiresAt: number;
+}
+
+const rpcPreviews = new WeakMap<RpcQueueRecoveryProvider, Map<string, RpcPreviewRecord>>();
+let rpcPreviewSequence = 0;
+
+export type QueueRecoveryOutcome = "supported" | "unavailable" | "malformed" | "partial" | "failure" | "success" | "invalid_preview" | "stale_preview" | "indeterminate";
+export type QueueDeliveryState = "queued" | "processing" | "pending_reply" | "timed_out";
+
+export interface QueueRecoveryItem {
+  id: string;
+  sender: string;
+  target: string;
+  /** `null` when the queue source does not expose an enqueue timestamp. */
+  queuedAt: string | null;
+  position: number;
+  deliveryState: QueueDeliveryState;
+}
+
+export interface QueuePreviewItem extends QueueRecoveryItem {
+  /** `null` when `queuedAt` is unknown. */
+  ageMs: number | null;
+}
+
+export interface QueueRecoveryPreview {
+  outcome: "supported" | "unavailable" | "malformed";
+  provider: "local" | "rpc";
+  previewId: string;
+  items: QueuePreviewItem[];
+  reason?: string;
+}
+
+/** Body-free audit record returned when a host may have cleared before returning malformed data. */
+export interface QueueRecoveryAttempt {
+  snapshot: string;
+  items: QueueRecoveryItem[];
+}
+
+export interface QueueRecoveryResult {
+  outcome: Exclude<QueueRecoveryOutcome, "supported">;
+  cleared: QueueRecoveryItem[];
+  untouched: QueueRecoveryItem[];
+  attempted?: QueueRecoveryAttempt;
+  reason?: string;
+}
+
+export function clearLocalQueue(items: QueueRecoveryItem[], ids: readonly string[]): QueueRecoveryResult {
+  const selected = new Set(ids);
+  const cleared = items.filter(item => selected.has(item.id));
+  const untouched = items.filter(item => !selected.has(item.id));
+  const outcome = cleared.length === ids.length ? "success" : "partial";
+  log.debug("recovery_local_classified", { requested: ids.length, cleared: cleared.length, outcome });
+  return {
+    outcome,
+    cleared,
+    untouched,
+    ...(outcome === "success" ? {} : { reason: "Some previewed queue items no longer exist" }),
+  };
+}
+
+export interface RpcQueueRecoveryProvider {
+  /** Read-only host adapter. Pi RPC hosts may expose this alongside conditional clearing. */
+  previewQueue?(): Promise<unknown>;
+  /**
+   * Atomically compare the supplied body-free snapshot with the host queue and clear only on a match.
+   * Return `{ outcome: "stale_preview" }` on mismatch; otherwise return the cleared queue response.
+   */
+  clearQueueIfSnapshot(expectedSnapshot: string): Promise<unknown>;
+}
+
+function validRpcQueue(response: unknown): response is { steering: string[]; followUp: string[] } {
+  return !!response && typeof response === "object" && Array.isArray((response as any).steering) && Array.isArray((response as any).followUp)
+    && (response as any).steering.every((item: unknown) => typeof item === "string")
+    && (response as any).followUp.every((item: unknown) => typeof item === "string");
+}
+
+function writeFrame(hash: ReturnType<typeof createHash>, value: string | number): void {
+  const bytes = Buffer.from(typeof value === "number" ? String(value) : value, "utf8");
+  const length = Buffer.allocUnsafe(4);
+  length.writeUInt32BE(bytes.length);
+  hash.update(length).update(bytes);
+}
+
+/** Returns a SHA-256 digest of explicit UTF-8 length-framed queue fields, never message text. */
+export function rpcQueueSnapshot(response: unknown): string | undefined {
+  if (!validRpcQueue(response)) {
+    log.warn("recovery_rpc_malformed", { operation: "snapshot" });
+    return undefined;
+  }
+  const hash = createHash("sha256");
+  writeFrame(hash, "pi-config.rpc-queue.v1");
+  for (const [kind, messages] of [["steering", response.steering], ["follow_up", response.followUp]] as const) {
+    writeFrame(hash, kind);
+    writeFrame(hash, messages.length);
+    for (const message of messages) writeFrame(hash, message);
+  }
+  const snapshot = `sha256:${hash.digest("hex")}`;
+  log.debug("recovery_rpc_snapshot", { steering: response.steering.length, followUp: response.followUp.length });
+  return snapshot;
+}
+
+function pruneRpcPreviews(previews: Map<string, RpcPreviewRecord>, now: number): void {
+  for (const [previewId, preview] of previews) if (preview.expiresAt <= now) previews.delete(previewId);
+}
+
+function retainRpcPreview(provider: RpcQueueRecoveryProvider, previewId: string, snapshot: string, items: QueueRecoveryItem[], now: number): void {
+  const previews = rpcPreviews.get(provider) ?? new Map<string, RpcPreviewRecord>();
+  pruneRpcPreviews(previews, now);
+  while (previews.size >= MAX_RPC_RECOVERY_PREVIEWS_PER_PROVIDER) previews.delete(previews.keys().next().value!);
+  previews.set(previewId, { snapshot, items, expiresAt: now + RPC_RECOVERY_PREVIEW_TTL_MS });
+  rpcPreviews.set(provider, previews);
+  log.debug("recovery_rpc_preview_retained", { active: previews.size, count: items.length });
+}
+
+/** Classifies a host-supplied, read-only RPC queue preview without retaining text in its result. */
+export async function previewRpcQueue(provider: RpcQueueRecoveryProvider | undefined, now = Date.now()): Promise<QueueRecoveryPreview> {
+  if (!provider?.previewQueue) {
+    log.warn("recovery_rpc_preview_unavailable", { operation: "preview" });
+    return { outcome: "unavailable", provider: "rpc", previewId: "", items: [], reason: "RPC queue preview is unavailable" };
+  }
+  try {
+    const response = await provider.previewQueue();
+    const snapshot = rpcQueueSnapshot(response);
+    if (!snapshot || !validRpcQueue(response)) return { outcome: "malformed", provider: "rpc", previewId: "", items: [], reason: "Malformed RPC queue preview" };
+    const queueItems = [...rpcItems("steering", response.steering), ...rpcItems("follow_up", response.followUp)];
+    const preview = buildQueuePreview("rpc", queueItems, now, `rpc-queue-preview-${now}-${++rpcPreviewSequence}`);
+    retainRpcPreview(provider, preview.previewId, snapshot, queueItems, now);
+    log.info("recovery_rpc_preview", { operation: "preview", count: preview.items.length });
+    return preview;
+  } catch (error) {
+    log.error("recovery_rpc_preview_failed", { operation: "preview", reason: error instanceof Error ? error.message : String(error) });
+    return { outcome: "unavailable", provider: "rpc", previewId: "", items: [], reason: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+export function buildQueuePreview(provider: "local" | "rpc", items: QueueRecoveryItem[], now = Date.now(), previewId = `queue-preview-${now}`): QueueRecoveryPreview {
+  log.debug("recovery_preview_built", { provider, count: items.length });
+  return {
+    outcome: "supported",
+    provider,
+    previewId,
+    items: items.map(item => ({ ...item, ageMs: item.queuedAt === null ? null : Math.max(0, now - Date.parse(item.queuedAt)) })),
+  };
+}
+
+function rpcItems(kind: "steering" | "follow_up", messages: string[]): QueueRecoveryItem[] {
+  log.debug("recovery_rpc_items", { kind, count: messages.length, queuedAt: "unknown" });
+  return messages.map((_message, index) => ({ id: `${kind}-${index + 1}`, sender: "pi-rpc", target: "local", queuedAt: null, position: index + 1, deliveryState: "queued" }));
+}
+
+/** Clears only the exact RPC queue snapshot represented by a live preview token. */
+export async function clearRpcQueue(provider: RpcQueueRecoveryProvider | undefined, previewId: string, now = Date.now()): Promise<QueueRecoveryResult> {
+  if (!provider) {
+    log.warn("recovery_rpc_clear_unavailable", { operation: "clear" });
+    return { outcome: "unavailable", cleared: [], untouched: [], reason: "RPC queue recovery is unavailable" };
+  }
+  const previews = rpcPreviews.get(provider);
+  if (previews) pruneRpcPreviews(previews, now);
+  const preview = previewId ? previews?.get(previewId) : undefined;
+  if (!preview) {
+    log.warn("recovery_rpc_clear_denied", { operation: "clear", reason: "invalid_preview" });
+    return { outcome: "invalid_preview", cleared: [], untouched: [], reason: "A valid RPC queue preview is required" };
+  }
+  previews?.delete(previewId);
+  try {
+    const response = await provider.clearQueueIfSnapshot(preview.snapshot);
+    if (response && typeof response === "object" && (response as any).outcome === "stale_preview") {
+      log.warn("recovery_rpc_clear_denied", { operation: "clear", reason: "stale_preview" });
+      return { outcome: "stale_preview", cleared: [], untouched: preview.items, reason: "RPC queue changed after preview" };
+    }
+    if (!validRpcQueue(response)) {
+      log.warn("recovery_rpc_clear_indeterminate", { operation: "clear", attempted: preview.items.length });
+      return { outcome: "indeterminate", cleared: [], untouched: [], attempted: { snapshot: preview.snapshot, items: preview.items }, reason: "Host clear response was malformed after an attempted clear" };
+    }
+    log.info("recovery_rpc_clear", { operation: "clear", outcome: "success", cleared: preview.items.length });
+    return { outcome: "success", cleared: preview.items, untouched: [] };
+  } catch (error) {
+    log.error("recovery_rpc_clear_failed", { operation: "clear", reason: error instanceof Error ? error.message : String(error) });
+    return { outcome: "failure", cleared: [], untouched: [], reason: error instanceof Error ? error.message : String(error) };
+  }
+}