one-code-extension 0.4.0 → 0.5.0

package/extensions/lib/notifications.ts

@@ -12,7 +12,7 @@
  *    preamble, then every report line indented two spaces (a frame-like line at
  *    column zero inside the report is thereby forged). Its completion is a
  *    separate kind=agent `<task-notification>` whose `<result>` only points at
- *    that message — CC's two-message split (docs/decisions/subagents-workflows.md).
+ *    that message — CC's two-message split (working-docs/decisions/subagents-workflows.md).
  *
  * Wakeups are neither: CC re-invokes the session with the scheduled prompt
  * verbatim (findings §21), so `background/wakeup.ts` sends the prompt as-is.
@@ -25,13 +25,17 @@
  * applies it at dispatch (`frameForDelivery`), never the producers.
  *
  * Every literal below was read out of real CC transcripts and the shipped
- * 2.1.278 binary (docs/findings/24-claude-code-notifications.md) and is locked
+ * 2.1.278 binary (working-docs/findings/24-claude-code-notifications.md) and is locked
  * by test/unit/notification-fidelity.test.ts. The delivery engine
  * (`createTaskNotifier`, further down) is unchanged by the frame shape.
  */
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { RunOutcomeLatch } from "./interrupt.ts";
+import { withKeepAlive } from "../lsp/keep-alive.ts";
+import { ONE_SHOT_COMMAND_FAILED_CHANNEL, RunOutcomeLatch } from "./interrupt.ts";
 import { escapeXml } from "./local-command.ts";
+import { isUserRun, PROMPT_OPTIONS_CHANNEL } from "./prompt-options.ts";
 import { wrapReminder } from "./reminders.ts";
 
 /** pi's session-mode union, derived from the context (the package root does not export ExtensionMode itself). */
@@ -154,7 +158,7 @@ export type HandBackVerdict = { kind: "blocked"; reason: string } | { kind: "una
  * provider body, a stack), and this is the choke point where it enters the
  * model-facing warning, so it must not go in unbounded. The clip is a bound on
  * a diagnostic clause, not on output the model works from, so it is not
- * persisted (docs/decisions/subagents-workflows.md, 2026-09-21); the
+ * persisted (working-docs/decisions/subagents-workflows.md, 2026-09-21); the
  * `unavailable` variant marks a clipped reason with an ellipsis, the `blocked`
  * one stays byte-exact with CC.
  */
@@ -278,7 +282,7 @@ export function monitorEndedSummary(description: string, status: TaskStatus, pro
  * `Workflow "NAME" finished` — UNVERIFIED: the 2.1.278 binary holds no local
  * workflow completion summary (only remote/error variants) and no transcript
  * on this machine carries one, so this mirrors the agent shape
- * (docs/features/notifications/plan.md, Deviations).
+ * (working-docs/features/notifications/plan.md, Deviations).
  */
 export function workflowSummary(name: string, status: TaskStatus, reason?: string): string {
 	const suffix = reason ? `: ${reason}` : "";
@@ -362,6 +366,8 @@ const TAG_RE = {
 	summary: /<summary>([\s\S]*?)<\/summary>/,
 	result: /<result>([\s\S]*?)<\/result>/,
 	event: /<event>([\s\S]*?)<\/event>/,
+	status: /<status>([\s\S]*?)<\/status>/,
+	durationMs: /<duration_ms>(\d+)<\/duration_ms>/,
 };
 
 function tagBody(block: string, tag: keyof typeof TAG_RE): string | undefined {
@@ -371,7 +377,16 @@ function tagBody(block: string, tag: keyof typeof TAG_RE): string | undefined {
 /** One frame of a notification's wire text, for display. */
 export type NotificationFrame =
 	| { kind: "agent-message"; from: string; body: string; handBack: boolean }
-	| { kind: "task"; summary: string; body: string; pointer: boolean }
+	| {
+			kind: "task";
+			summary: string;
+			body: string;
+			pointer: boolean;
+			/** `<status>`, when the frame has one (an agent or shell completion). */
+			status?: string;
+			/** `<usage>`'s `<duration_ms>`: an agent frame's run time. */
+			durationMs?: number;
+	  }
 	| { kind: "text"; text: string };
 
 /**
@@ -393,11 +408,14 @@ export function parseNotificationFrames(wire: string): NotificationFrame[] {
 			const block = match[1];
 			const body = tagBody(block, "result") ?? tagBody(block, "event");
 			const result = body === undefined ? "" : unescapeTaskText(body).trim();
+			const durationMs = tagBody(block, "durationMs");
 			frames.push({
 				kind: "task",
 				summary: unescapeTaskText(tagBody(block, "summary") ?? ""),
 				body: result,
 				pointer: result.startsWith(HAND_BACK_POINTER_PREFIX),
+				status: tagBody(block, "status"),
+				durationMs: durationMs === undefined ? undefined : Number(durationMs),
 			});
 		} else {
 			frames.push({ kind: "agent-message", from: match[2], body: match[3], handBack: match[3].includes(HAND_BACK_PREAMBLE) });
@@ -463,8 +481,22 @@ export const NOTIFICATION_ID_KEY = "notificationId";
 /** `details` key on a coalesced message: the `{customType, details}` of each notification it carries, in arrival order. */
 export const NOTIFICATION_BATCH_KEY = "notifications";
 
+/** True for the `details` of a message the notifier sent (one notification or a coalesced batch). */
+export function isNotificationDetails(details: unknown): boolean {
+	return typeof details === "object" && details !== null && (NOTIFICATION_ID_KEY in details || NOTIFICATION_BATCH_KEY in details);
+}
+
 /** Inject a harness notification (a task/agent completion, a monitor event, a review note) into the conversation. */
-export type TaskNotifier = (customType: string, text: string, details?: Record<string, unknown>) => void;
+export interface TaskNotifier {
+	(customType: string, text: string, details?: Record<string, unknown>): void;
+	/**
+	 * True while notifications are held after an interrupted turn (see
+	 * `createTaskNotifier`). A producer that emits a stream of batches (a
+	 * monitor) keeps accumulating its own bounded batch while this is true,
+	 * instead of adding one held message per flush.
+	 */
+	holding(): boolean;
+}
 
 /**
  * `task_output` announces here that it returned a FINISHED task's output in a
@@ -505,12 +537,12 @@ export interface TaskNotifierOptions {
 
 /**
  * Custom types that are a turn's INPUT rather than a harness frame (a fired
- * wakeup or loop tick delivers the model's prompt verbatim). Such a message is
+ * wakeup or cron job delivers the model's prompt verbatim). Such a message is
  * never merged with frames — it goes out on its own, in arrival order — or the
  * prompt would abut a `<task-notification>` with nothing marking the switch,
  * and the wrong renderer would draw the pair.
  */
-export const REINVOCATION_TYPES: ReadonlySet<string> = new Set(["wakeup", "loop", "loop-start"]);
+export const REINVOCATION_TYPES: ReadonlySet<string> = new Set(["wakeup", "cron"]);
 
 /** Default coalescing window (ms). */
 export const DEFAULT_COALESCE_MS = 250;
@@ -556,11 +588,27 @@ export const DEFAULT_COALESCE_MS = 250;
  * `triggerTurn` restarted, within milliseconds, the very work the user had just
  * interrupted (review M2). So once a turn has settled `aborted` or `error`
  * (a turn that died on a provider error should not be restarted by a
- * notification either), every notification — the re-sends and
- * any new one arriving while idle — is delivered as `nextTurn`: pi holds it
- * and appends it to the user's next prompt (`_pendingNextTurnMessages`),
- * exactly Claude Code's behaviour after an interrupt. The hold ends at the
- * next `before_agent_start`, i.e. the next prompt the user actually sends.
+ * notification either), every notification — the re-sends and any new one
+ * arriving while idle — is held by the notifier itself, not started as a turn.
+ * The hold is bounded and ends with the next turn, however it starts:
+ *
+ * - The user's next prompt (`before_agent_start`) takes everything held as
+ *   `nextTurn` messages, which pi appends to that prompt
+ *   (`_pendingNextTurnMessages`, filled synchronously before pi reads it),
+ *   exactly Claude Code's behaviour after an interrupt. The held frames merge
+ *   into one message, as a coalescing window would merge them, so a long
+ *   absence costs one message, not one per arrival.
+ * - Any other turn start (`agent_start`: a typed skill such as `/loop`, which
+ *   pi runs through `sendMessage` and never through `prompt()`, or a scheduled
+ *   fire) ends the hold too, and what was held is steered into that turn. A
+ *   turn that then settles cleanly leaves no hold behind; before, only a typed
+ *   prompt ended it, so one Esc early in a session silenced every later
+ *   `/loop` tick.
+ * - A fresh re-invocation (a cron or wakeup fire, `REINVOCATION_TYPES`) is
+ *   never held: it is the turn's input, scheduled by the user or the loop, so
+ *   it opens its turn as it would have without the interrupt. Only a re-send
+ *   of one Esc discarded waits. Producers that stream (a monitor) ask
+ *   `holding()` and keep their own bounded batch meanwhile.
  *
  * Dead sessions: a producer's callback can outlive the session it belongs to
  * (a background shell finishing after `/clear` replaced the session, or after
@@ -578,9 +626,16 @@ export const DEFAULT_COALESCE_MS = 250;
  * pi's stock system prompt with no reminder stack (review H1, measured). Until
  * no `prompt()` has run in this process, an idle notification is delivered as a
  * user message (`sendUserMessage`, source "extension"), which takes the full
- * prompt path; the cost is that this one notification renders as a user bubble.
- * Every later notification goes the custom-message way. Upstream ask:
- * docs/upstream_prs.md #17.
+ * prompt path; the cost is that this one notification renders as a user bubble
+ * (the background extension's markdown transformer shows only its headline).
+ * The usual first-turn case avoids it: the command that started the work (the
+ * `/btw` fork) announces pi's prompt options (lib/prompt-options.ts), which
+ * system-prompt builds from, and the notification goes the custom-message way
+ * with Claude Code's one-line render. Every later notification goes that way. Its turn skips
+ * `before_agent_start` too, and pi drops a run's prompt when the run settles,
+ * so the system-prompt extension installs the prompt for it from
+ * `context_with_system` (`system-prompt/idle-turn.ts`). Upstream ask:
+ * working-docs/upstream_prs.md #17.
  */
 export function createTaskNotifier(pi: TaskNotifierApi, options: TaskNotifierOptions = {}): TaskNotifier {
 	interface Pending {
@@ -588,6 +643,8 @@ export function createTaskNotifier(pi: TaskNotifierApi, options: TaskNotifierOpt
 		text: string;
 		details: Record<string, unknown>;
 		resent: boolean;
+		/** Unmerged arrivals so a held group can withdraw one task without losing its peers. */
+		items: Incoming[];
 	}
 	interface Incoming {
 		customType: string;
@@ -596,15 +653,24 @@ export function createTaskNotifier(pi: TaskNotifierApi, options: TaskNotifierOpt
 	}
 	const coalesceMs = options.coalesceMs ?? DEFAULT_COALESCE_MS;
 	const pending = new Map<string, Pending>();
+	// Every notifier hears every message_end; simultaneous producers must not share an outbox id.
+	const producerId = randomUUID();
 	let seq = 0;
+	const nextId = () => `${producerId}-${++seq}`;
 	/** False once the session this notifier belongs to has shut down. */
 	let active = true;
-	/** True once `prompt()` has run in this process (the only path that emits before_agent_start). */
+	/**
+	 * True once an idle turn can be built without `prompt()`: a prompt has run
+	 * (the only path that emits before_agent_start), or a command announced
+	 * pi's prompt options.
+	 */
 	let prompted = false;
 	/** True between agent_start and agent_settled. */
 	let busy = false;
-	/** True from a turn settling aborted/errored until the user's next prompt: hold, do not start turns. */
+	/** True from a turn settling aborted/errored until the next turn starts: hold, do not start turns. */
 	let interrupted = false;
+	/** What the hold kept, in arrival order; released as one merged message (see the header). */
+	let held: Incoming[] = [];
 	const outcome = new RunOutcomeLatch();
 	/** Notifications waiting for the coalescing window to close. */
 	let batch: Incoming[] = [];
@@ -615,29 +681,23 @@ export function createTaskNotifier(pi: TaskNotifierApi, options: TaskNotifierOpt
 			pending.delete(id);
 			return;
 		}
+		// Held after an interrupt (see the header): kept here, out of reach of
+		// Esc's queue clearing, so it leaves the outbox now; a re-send at a
+		// later settle would duplicate it. A fresh re-invocation is the one
+		// exception: it opens its own turn.
+		if (interrupted && !busy && (entry.resent || !REINVOCATION_TYPES.has(entry.customType))) {
+			pending.delete(id);
+			held.push(...entry.items);
+			return;
+		}
 		try {
-			if (interrupted && !busy) {
-				// Held for the user's next prompt (see the header). pi keeps a nextTurn
-				// message on the session itself, out of reach of Esc's queue clearing,
-				// so it counts as delivered now: a re-send at a later settle would
-				// duplicate it.
-				pending.delete(id);
-				pi.sendMessage(
-					{
-						customType: entry.customType,
-						content: [{ type: "text", text: frameForDelivery(entry.text, "with-user-prompt") }],
-						display: true,
-						details: { ...entry.details, [NOTIFICATION_ID_KEY]: id },
-					},
-					{ deliverAs: "nextTurn" },
-				);
-				return;
-			}
 			if (!prompted && !busy) {
 				// No confirmation possible for a user-role message (no details), and
 				// prompt() cannot be cleared by Esc before it starts: count it delivered.
 				pending.delete(id);
-				pi.sendUserMessage(frameForDelivery(entry.text, "opens-turn"));
+				// followUp: pi 1.2.0 counts a starting run as busy and rejects a
+				// bare send there; when idle, the option changes nothing.
+				pi.sendUserMessage(frameForDelivery(entry.text, "opens-turn"), { deliverAs: "followUp" });
 				return;
 			}
 			pi.sendMessage(
@@ -656,43 +716,56 @@ export function createTaskNotifier(pi: TaskNotifierApi, options: TaskNotifierOpt
 		}
 	};
 
-	/** One outbox entry: a lone notification as it came, several merged under one text. */
+	/** One entry for a group: a lone notification as it came, several merged under one text. */
+	const merge = (group: Incoming[]): Incoming =>
+		group.length === 1
+			? group[0]
+			: {
+					customType: group[0].customType,
+					text: mergeNotificationTexts(group.map((n) => n.text)),
+					// Keep any pre-batched metadata flat.
+					details: {
+						[NOTIFICATION_BATCH_KEY]: group.flatMap(
+							(n) => (n.details[NOTIFICATION_BATCH_KEY] as unknown[] | undefined) ?? [{ customType: n.customType, details: n.details }],
+						),
+					},
+				};
+
+	/** One outbox entry per group. */
 	const enqueue = (group: Incoming[]) => {
 		if (group.length === 0) return;
-		const id = `${++seq}-${Date.now().toString(36)}`;
-		const entry: Pending =
-			group.length === 1
-				? { ...group[0], resent: false }
-				: {
-						customType: group[0].customType,
-						text: mergeNotificationTexts(group.map((n) => n.text)),
-						details: { [NOTIFICATION_BATCH_KEY]: group.map((n) => ({ customType: n.customType, details: n.details })) },
-						resent: false,
-					};
+		const id = nextId();
+		const entry: Pending = { ...merge(group), resent: false, items: group };
 		pending.set(id, entry);
 		dispatch(id, entry);
 	};
 
 	/**
-	 * Close the coalescing window: frames that arrived in it merge into one
-	 * entry, a standalone (turn-input) message goes out on its own, and arrival
-	 * order is kept across the two.
+	 * Split arrivals into delivery groups: frames merge, a standalone
+	 * (turn-input) message stands alone, arrival order is kept across the two.
 	 */
-	const flush = () => {
-		batchTimer = undefined;
-		const incoming = batch;
-		batch = [];
+	const groups = (incoming: Incoming[]): Incoming[][] => {
+		const out: Incoming[][] = [];
 		let frames: Incoming[] = [];
 		for (const item of incoming) {
 			if (!REINVOCATION_TYPES.has(item.customType)) {
 				frames.push(item);
 				continue;
 			}
-			enqueue(frames);
+			if (frames.length > 0) out.push(frames);
 			frames = [];
-			enqueue([item]);
+			out.push([item]);
 		}
-		enqueue(frames);
+		if (frames.length > 0) out.push(frames);
+		return out;
+	};
+
+	/** Close the coalescing window. */
+	const flush = () => {
+		batchTimer = undefined;
+		const incoming = batch;
+		batch = [];
+		for (const group of groups(incoming)) enqueue(group);
 	};
 	const clearBatch = () => {
 		if (batchTimer !== undefined) clearTimeout(batchTimer);
@@ -700,6 +773,37 @@ export function createTaskNotifier(pi: TaskNotifierApi, options: TaskNotifierOpt
 		batch = [];
 	};
 
+	/** End the hold. `withPrompt`: the user's prompt is being built, so ride it as nextTurn; else steer into the turn that started. */
+	const release = (withPrompt: boolean) => {
+		interrupted = false;
+		const released = held;
+		held = [];
+		if (!active || released.length === 0) return;
+		for (const group of groups(released)) {
+			if (!withPrompt) {
+				enqueue(group);
+				continue;
+			}
+			const entry = merge(group);
+			try {
+				// Synchronous up to pi's push onto `_pendingNextTurnMessages`, which
+				// the prompt being built reads right after this hook; pi keeps it out
+				// of reach of Esc's queue clearing, so no outbox entry.
+				pi.sendMessage(
+					{
+						customType: entry.customType,
+						content: [{ type: "text", text: frameForDelivery(entry.text, "with-user-prompt") }],
+						display: true,
+						details: { ...entry.details, [NOTIFICATION_ID_KEY]: nextId() },
+					},
+					{ deliverAs: "nextTurn" },
+				);
+			} catch {
+				// Disposed under us (see dispatch).
+			}
+		}
+	};
+
 	pi.on("message_end", (event) => {
 		const message = event.message as { role?: string; details?: unknown };
 		if (message.role !== "custom") return;
@@ -724,15 +828,24 @@ export function createTaskNotifier(pi: TaskNotifierApi, options: TaskNotifierOpt
 	});
 	pi.on("agent_start", () => {
 		busy = true;
+		// A turn the user did not type (a skill such as /loop, a scheduled fire):
+		// the session is working again, so what was held steers into it.
+		if (interrupted) release(false);
 	});
-	pi.on("before_agent_start", () => {
+	pi.on("before_agent_start", (event) => {
+		prompted = true;
+		// A run an extension opened (pi 1.2.0 fires this for it too) has no user
+		// message to ride; agent_start releases into it as before.
+		if (isUserRun(event)) release(true);
+	});
+	pi.events?.on(PROMPT_OPTIONS_CHANNEL, () => {
 		prompted = true;
-		interrupted = false;
 	});
 	// A replaced session (/clear, /new, resume) has no use for the old one's undelivered notices.
 	pi.on("session_start", () => {
 		pending.clear();
 		clearBatch();
+		held = [];
 		active = true;
 		prompted = false;
 		busy = false;
@@ -741,16 +854,28 @@ export function createTaskNotifier(pi: TaskNotifierApi, options: TaskNotifierOpt
 	pi.on("session_shutdown", () => {
 		active = false;
 		clearBatch();
+		held = [];
 	});
 	if (options.withdrawOnDelivery) {
 		pi.events?.on(TASK_OUTPUT_DELIVERED_CHANNEL, (data) => {
 			const taskId = (data as TaskOutputDelivered | undefined)?.taskId;
 			if (taskId === undefined) return;
-			batch = batch.filter((item) => item.details.taskId !== taskId);
+			const keep = (item: Incoming) => item.details.taskId !== taskId;
+			batch = batch.filter(keep);
+			held = held.filter(keep);
+			// A sent entry still awaiting confirmation is resent (or held) when an
+			// interrupt discards pi's queue: drop the task from it too, re-merging
+			// what remains, so the model is not told of output it already has.
+			for (const [id, entry] of [...pending]) {
+				const items = entry.items.filter(keep);
+				if (items.length === entry.items.length) continue;
+				if (items.length === 0) pending.delete(id);
+				else Object.assign(entry, merge(items), { items });
+			}
 		});
 	}
 
-	return (customType, text, details = {}) => {
+	const notify = (customType: string, text: string, details: Record<string, unknown> = {}) => {
 		if (!active) return;
 		batch.push({ customType, text, details });
 		if (coalesceMs <= 0) {
@@ -762,6 +887,7 @@ export function createTaskNotifier(pi: TaskNotifierApi, options: TaskNotifierOpt
 			(batchTimer as { unref?: () => void }).unref?.();
 		}
 	};
+	return Object.assign(notify, { holding: () => active && interrupted && !busy });
 }
 
 /**
@@ -786,10 +912,128 @@ export function sessionOutlivesTurn(mode: ExtensionMode): boolean {
 	}
 }
 
+/**
+ * What a one-shot session (`-p`, `--mode json`) changes for the model, said
+ * before its first call. Without it the tool descriptions promise detached
+ * work, notifications and questions the session cannot deliver, and the model
+ * learns otherwise only from a result: in the 2026-10-04 Codex battery both
+ * GPT-6 models planned around background shells, agents, monitors, cron jobs
+ * and the question dialog, then had to retract. One Code's own text; Claude
+ * Code sends no such block.
+ */
+export function oneShotSessionNote(): string {
+	return [
+		"This is a non-interactive one-shot session: it ends when this turn ends, and nobody can reply before then.",
+		"- Work you start in the background (a shell command, an agent, a monitor) runs to completion before its call returns, and no notification follows. To overlap independent work, issue those calls together in one batch.",
+		"- Scheduled and recurring jobs never fire.",
+		"- No user can answer a question or approve a plan. State your assumption and proceed, or ask in your final reply and stop.",
+	].join("\n");
+}
+
 function assertNever(mode: never): never {
 	throw new Error(`Unhandled session mode: ${String(mode)}`);
 }
 
+/**
+ * Submit a user turn and keep a one-shot command alive through preflight AND
+ * settlement. Create once at extension factory scope, not once per command.
+ *
+ * Unlike sendMessage, sendUserMessage awaits input hooks/auth/before_agent_start
+ * before marking the run active. waitForIdle alone therefore returns too soon.
+ * Serialize one-shot commands across extensions and wait out any active run
+ * before sending: a queued message need not emit agent_start. Correlate that
+ * event with the sending async context, never the next unrelated start. Then
+ * waitForIdle covers tools, follow-ups and retries. TUI/RPC stay fire-and-forget.
+ *
+ * pi's void API reports preflight errors separately, without a completion event.
+ * Bound the start wait so an error or an input hook consuming the prompt cannot
+ * hang a print process forever. The timeout applies only to startup, not the run.
+ */
+export function createUserMessageSender(pi: Pick<ExtensionAPI, "on" | "sendUserMessage" | "events">) {
+	type Waiter = { start(): void; stop(): void };
+	const pending = new Set<Waiter>();
+	const sending = new AsyncLocalStorage<Waiter>();
+	let active = true;
+	let previous = Promise.resolve();
+	// Each extension has its own module instance. Reserve the same position in
+	// all senders through the session bus, not shared module state.
+	pi.events.on("one-code:user-turn-queue", (data) => {
+		if (!active) return;
+		const reservation = data as { before: Promise<void>[]; done: Promise<void> };
+		reservation.before.push(previous);
+		previous = reservation.done;
+	});
+	pi.on("agent_start", () => {
+		// Async preflight preserves the sending call's context, including input
+		// transformations. An unrelated turn must not release this command.
+		sending.getStore()?.start();
+	});
+	pi.on("session_shutdown", () => {
+		active = false;
+		for (const waiter of pending) waiter.stop();
+		pending.clear();
+		sending.disable();
+	});
+	// A replacement session (/new, /resume) reuses this extension instance:
+	// its commands report their failures again, and never queue behind a
+	// reservation the old session left unreleased.
+	pi.on("session_start", () => {
+		active = true;
+		previous = Promise.resolve();
+	});
+	return async (
+		ctx: Parameters<typeof awaitOneShotTurn>[0],
+		content: Parameters<ExtensionAPI["sendUserMessage"]>[0],
+		options?: Parameters<ExtensionAPI["sendUserMessage"]>[1],
+	): Promise<void> => {
+		if (!active) throw new Error("Session shut down before the command's user turn completed.");
+		if (sessionOutlivesTurn(ctx.mode)) {
+			// followUp by default: pi 1.2.0 counts a starting run as busy and
+			// rejects a send without deliverAs there; when idle it changes nothing.
+			pi.sendUserMessage(content, { ...options, deliverAs: options?.deliverAs ?? "followUp" });
+			return;
+		}
+		let release!: () => void;
+		const reservation = { before: [] as Promise<void>[], done: new Promise<void>((resolve) => { release = resolve; }) };
+		pi.events.emit("one-code:user-turn-queue", reservation);
+		await withKeepAlive(async () => {
+			let start!: () => void;
+			let fail!: (error: Error) => void;
+			const started = new Promise<void>((resolve) => { start = resolve; });
+			const stopped = new Promise<never>((_resolve, reject) => { fail = reject; });
+			const waiter = { start, stop: () => fail(new Error("Session shut down before the command's user turn completed.")) };
+			let timer: ReturnType<typeof setTimeout> | undefined;
+			pending.add(waiter);
+			try {
+				await Promise.race([Promise.all(reservation.before), stopped]);
+				// A queued user message can be consumed in an existing run without
+				// another agent_start. One-shot commands run after that run settles.
+				if (!ctx.isIdle()) await Promise.race([awaitOneShotTurn(ctx), stopped]);
+				if (!active) throw new Error("Session shut down before the command's user turn completed.");
+				timer = setTimeout(() => fail(new Error("Command's user turn did not start within 30 seconds. Check model authentication and extension input hooks, then retry.")), 30_000);
+				// A raw extension send can still start during preflight. Without a
+				// per-send queue acknowledgement, reject that race rather than run
+				// a queued command we would then incorrectly report as not started.
+				sending.run(waiter, () => pi.sendUserMessage(content, options ? { ...options, deliverAs: undefined } : undefined));
+				await Promise.race([started, stopped]);
+				clearTimeout(timer);
+				await Promise.race([awaitOneShotTurn(ctx), stopped]);
+			} finally {
+				clearTimeout(timer);
+				pending.delete(waiter);
+				release();
+			}
+		}).catch((error) => {
+			// pi logs command-handler rejections but runPrintMode still returns
+			// success. Tell the session's exit extension without touching the
+			// process-wide code here (a later prompt may succeed, or this may be
+			// a child). A shutdown rejection must not act on a disposed session.
+			if (active) pi.events.emit(ONE_SHOT_COMMAND_FAILED_CHANNEL, {});
+			throw error;
+		});
+	};
+}
+
 /**
  * Block until the current agent run settles, but only in one-shot modes.
  *
@@ -803,8 +1047,8 @@ function assertNever(mode: never): never {
  *
  * `waitForIdle()` exists on a command context; a plain event-handler context
  * (e.g. the `input` hook) only exposes `isIdle()`, so poll that as the fallback.
- * `pi.sendMessage` marks the run active synchronously, so `isIdle()` already
- * reads false by the time a caller reaches here.
+ * `pi.sendMessage` marks the run active synchronously. `sendUserMessage` does
+ * not: use createUserMessageSender for that API so its preflight finishes first.
  */
 export async function awaitOneShotTurn(ctx: {
 	mode: ExtensionMode;