one-code-extension 0.3.1 → 0.4.0

package/extensions/background/index.ts

@@ -6,18 +6,19 @@
  * long-running work over TASK_REGISTER_CHANNEL at runtime, so task_output and
  * task_stop address every background task in the session regardless of which
  * extension started it. Events and completions are delivered as steered
- * system notifications (lib/notifications.ts), never as user input.
+ * task notifications (lib/notifications.ts), never as user input; a fired
+ * wakeup or loop tick re-invokes the session with its prompt verbatim.
  */
 
-import { spawn } from "node:child_process";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { whenAborted } from "../lib/abort.ts";
 import { DEFER_CHANNEL } from "../lib/deferred.ts";
 import { persistIfLarge, sessionResultsDir } from "../lib/persisted-output.ts";
-import { detachedSpawnOptions, KILL_GRACE_MS, stopProcessTree } from "../lib/process-tree.ts";
+import { detachedSpawnOptions, KILL_GRACE_MS, stopProcessTree, waitForChildExit } from "../lib/process-tree.ts";
 import { sessionAlive } from "../lib/session-lifecycle.ts";
-import { ccToolRenderers, customMessageText, liveUiCtx, notificationComponent } from "../lib/tui-render.ts";
+import { bashSpawn, spawnShellCommand } from "../lib/shell-spawn.ts";
+import { ccToolRenderers, customMessageText, liveUiCtx, notificationComponent, scheduledTaskComponent } from "../lib/tui-render.ts";
 import {
 	type BackgroundTask,
 	BackgroundRegistry,
@@ -35,16 +36,28 @@ import {
 	MIN_DELAY_SECONDS,
 	parseLoopArgs,
 } from "./wakeup.ts";
-import { createTaskNotifier, oneShotNote, sessionOutlivesTurn, systemNotification } from "../lib/notifications.ts";
+import {
+	createTaskNotifier,
+	monitorEndedSummary,
+	monitorEventSummary,
+	oneShotNote,
+	sessionOutlivesTurn,
+	TASK_OUTPUT_DELIVERED_CHANNEL,
+	type TaskOutputDelivered,
+	taskNotification,
+	taskStatusOf,
+} from "../lib/notifications.ts";
 import {
 	batchSize,
 	emptyBatch,
-	formatMonitorBatch,
+	formatMonitorEvents,
 	MONITOR_BATCH_BUSY_MS,
+	MONITOR_BATCH_MAX_CHARS,
 	MONITOR_BATCH_IDLE_MS,
 	type MonitorBatch,
 	pushEvent,
 } from "./monitor-batch.ts";
+import { registerLocalCommand } from "../lib/local-command.ts";
 
 const OUTPUT_CAP = 30_000;
 const STORED_OUTPUT_CAP = 200_000;
@@ -103,16 +116,26 @@ export default function backgroundExtension(pi: ExtensionAPI) {
 		live.ui.setWidget("cc-background", running > 0 ? [` background tasks: ${running} running`] : undefined);
 	};
 
-	// Harness-injected notifications carry anti-confabulation framing for the
-	// model; the transcript shows a compact headline instead (ctrl+o expands).
-	// One registration covers every emitter of the type (bash uses it too).
-	for (const customType of ["task-notification", "wakeup", "loop"]) {
+	// The wire frames are model-facing; the transcript shows a compact headline
+	// instead (ctrl+o expands). One registration covers every emitter of
+	// `task-notification` (bash uses it too). A fired wakeup or loop tick is the
+	// prompt verbatim, shown behind Claude Code's "Running scheduled task" line.
+	pi.registerMessageRenderer("task-notification", (message, { expanded }, theme) =>
+		notificationComponent(theme, customMessageText(message.content), expanded),
+	);
+	for (const customType of ["wakeup", "loop"]) {
 		pi.registerMessageRenderer(customType, (message, { expanded }, theme) =>
-			notificationComponent(theme, customMessageText(message.content), expanded),
+			scheduledTaskComponent(theme, customMessageText(message.content), (message as { timestamp?: number }).timestamp ?? Date.now(), expanded),
 		);
 	}
+	// The dynamic /loop's opening turn is the user's command, not a fired task.
+	pi.registerMessageRenderer("loop-start", (message, { expanded }, theme) =>
+		notificationComponent(theme, customMessageText(message.content), expanded),
+	);
 
-	const notify = createTaskNotifier(pi);
+	// A monitor's end the model already read through task_output is withdrawn
+	// like a shell's (lib/notifications.ts).
+	const notify = createTaskNotifier(pi, { withdrawOnDelivery: true });
 
 	pi.registerTool({
 		name: "monitor",
@@ -137,7 +160,7 @@ export default function backgroundExtension(pi: ExtensionAPI) {
 				),
 			),
 		}),
-		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+		async execute(toolCallId, params, signal, _onUpdate, ctx) {
 			lastCtx = ctx;
 			if (Boolean(params.command) === Boolean(params.ws)) {
 				return {
@@ -170,10 +193,12 @@ export default function backgroundExtension(pi: ExtensionAPI) {
 				if (batchSize(pending) === 0) return;
 				const batch = pending;
 				pending = emptyBatch();
-				notify("task-notification", systemNotification(formatMonitorBatch(id, params.description, batch)), {
-					taskId: id,
-					events: batchSize(batch),
-				});
+				// CC's mid-run monitor batch: no status, the lines in `<event>`.
+				notify(
+					"task-notification",
+					taskNotification({ kind: "monitor", taskId: id, summary: monitorEventSummary(params.description), result: formatMonitorEvents(id, batch) }),
+					{ taskId: id, events: batchSize(batch) },
+				);
 			};
 
 			const onEvent = (line: string) => {
@@ -200,9 +225,19 @@ export default function backgroundExtension(pi: ExtensionAPI) {
 				if (!alive() || oneShot) return;
 				flush();
 				updateWidget();
+				// CC's monitor end: the recent tail rides `<event>` under the ended summary.
+				const ccStatus = taskStatusOf(finalStatus);
+				const recent = tail(stored, MONITOR_BATCH_MAX_CHARS).trim();
 				notify(
 					"task-notification",
-					systemNotification(`Monitor ${id} (${params.description}) ${finalStatus}${note ? ` — ${note}` : ""} after ${eventCount} event(s).`),
+					taskNotification({
+						kind: "monitor",
+						taskId: id,
+						toolUseId: toolCallId,
+						status: ccStatus,
+						summary: monitorEndedSummary(params.description, ccStatus, eventCount > 0, note),
+						result: recent || undefined,
+					}),
 					{ taskId: id, status: finalStatus },
 				);
 			};
@@ -214,13 +249,22 @@ export default function backgroundExtension(pi: ExtensionAPI) {
 				// leader — with zsh a `cmd; echo` or a pipeline otherwise lives on as an
 				// orphan holding the stdout pipe, so the task never finishes and, in a
 				// one-shot run, the process cannot exit (LIFECYCLE-REVIEW M2, measured).
-				const child = spawn(process.env.SHELL || "/bin/sh", ["-c", params.command], {
+				// The session's bash (Git Bash on Windows) — lib/shell-spawn.ts.
+				const bash = bashSpawn();
+				if (!bash.spawn) {
+					return {
+						content: [{ type: "text", text: `Cannot start the monitor: ${bash.error ?? "no bash shell was found"}` }],
+						details: {},
+						isError: true,
+					};
+				}
+				const child = spawnShellCommand(bash.spawn, params.command, {
 					cwd: ctx.cwd,
 					...detachedSpawnOptions(),
 					stdio: ["ignore", "pipe", "pipe"],
 				});
 				let buffer = "";
-				child.stdout.on("data", (chunk: Buffer) => {
+				child.stdout?.on("data", (chunk: Buffer) => {
 					buffer += chunk.toString();
 					let idx: number;
 					while ((idx = buffer.indexOf("\n")) !== -1) {
@@ -229,15 +273,17 @@ export default function backgroundExtension(pi: ExtensionAPI) {
 						if (line) onEvent(line);
 					}
 				});
-				child.stderr.on("data", (chunk: Buffer) => {
+				child.stderr?.on("data", (chunk: Buffer) => {
 					stored = tail(`${stored}${chunk.toString()}`, STORED_OUTPUT_CAP);
 				});
-				child.on("error", (error) => end("failed", error.message));
-				child.on("close", (code) =>
-					end(
-						stopRequested ? "stopped" : code === 0 ? "completed" : "failed",
-						code !== null && code !== 0 ? `exit code ${code}` : undefined,
-					),
+				// Exit plus a short stdio grace, not `close` (lib/process-tree.ts).
+				waitForChildExit(child).then(
+					({ code }) =>
+						end(
+							stopRequested ? "stopped" : code === 0 ? "completed" : "failed",
+							code !== null && code !== 0 ? `exit code ${code}` : undefined,
+						),
+					(error: Error) => end("failed", error.message),
 				);
 				stop = () => {
 					stopRequested = true;
@@ -328,7 +374,7 @@ export default function backgroundExtension(pi: ExtensionAPI) {
 				content: [
 					{
 						type: "text",
-						text: `Monitor ${id} started (${params.description}). Events arrive as system notifications; stop with task_stop, inspect with task_output.`,
+						text: `Monitor ${id} started (${params.description}). Events arrive as task notifications; stop with task_stop, inspect with task_output.`,
 					},
 				],
 				details: { taskId: id },
@@ -341,7 +387,7 @@ export default function backgroundExtension(pi: ExtensionAPI) {
 		label: "Task Output",
 		...ccToolRenderers("Task Output"),
 		description:
-			"Retrieve output from a running or finished background task (monitor, background subagent, or background bash) by task id. block=true (default) waits up to `timeout` ms for completion; block=false returns the current status immediately. You never need this just to learn that a task finished — completion arrives as a system notification with the status and the last 2 KB of output; call this for the rest of the output, when your next step needs the result now, or for a mid-run peek.",
+			"Retrieve output from a running or finished background task (monitor, background subagent, or background bash) by task id. block=true (default) waits up to `timeout` ms for completion; block=false returns the current status immediately. You never need this just to learn that a task finished — completion arrives as a task notification naming the output file; call this for the output itself, when your next step needs the result now, or for a mid-run peek.",
 		parameters: Type.Object({
 			task_id: Type.String({ description: "The task id to get output from" }),
 			block: Type.Optional(Type.Boolean({ description: "Wait for completion (default true)" })),
@@ -377,6 +423,9 @@ export default function backgroundExtension(pi: ExtensionAPI) {
 			updateWidget();
 			const header = formatTaskLine(task);
 			const body = tail(task.output(), OUTPUT_CAP) || "(no output yet)";
+			// The model now holds a finished task's output: a completion notification
+			// still waiting to go out for it is redundant (lib/notifications.ts).
+			if (task.status !== "running") pi.events.emit(TASK_OUTPUT_DELIVERED_CHANNEL, { taskId: task.id } satisfies TaskOutputDelivered);
 			return {
 				content: [{ type: "text", text: `${header}\n\n${body}` }],
 				details: { taskId: task.id, status: task.status, logPath: task.logPath },
@@ -430,7 +479,7 @@ export default function backgroundExtension(pi: ExtensionAPI) {
 			title: (a) => (a?.stop ? "stop" : a?.delaySeconds !== undefined ? `${a.delaySeconds}s` : undefined),
 		}),
 		description:
-			"Schedule when to resume work on a self-paced recurring task — the dynamic mode of the /loop command. After `delaySeconds` (clamped to [60, 3600]) the given prompt is delivered as a system notification and a new turn starts. One wakeup is pending at a time — scheduling again replaces it; {stop: true} ends the loop and cancels any pending wakeup.\n\nPass the same task back via `prompt` each turn so the next firing repeats it. Set `noop: true` when nothing changed this tick (you checked and there's nothing to report); `noop: false` when something happened worth keeping. Pick `delaySeconds` from what you're actually waiting for: poll external state (a CI run, a deploy) at the rate it changes; for a quiet idle heartbeat prefer a long delay (1200s+). Do NOT schedule a short wakeup just to poll background work you started here — its completion already notifies you.",
+			"Schedule when to resume work on a self-paced recurring task — the dynamic mode of the /loop command. After `delaySeconds` (clamped to [60, 3600]) the harness re-invokes you with the given prompt, verbatim, as the next turn's input. One wakeup is pending at a time — scheduling again replaces it; {stop: true} ends the loop and cancels any pending wakeup.\n\nPass the same task back via `prompt` each turn so the next firing repeats it. Set `noop: true` when nothing changed this tick (you checked and there's nothing to report); `noop: false` when something happened worth keeping. Pick `delaySeconds` from what you're actually waiting for: poll external state (a CI run, a deploy) at the rate it changes; for a quiet idle heartbeat prefer a long delay (1200s+). Do NOT schedule a short wakeup just to poll background work you started here — its completion already notifies you.",
 		parameters: Type.Object({
 			delaySeconds: Type.Optional(Type.Number({ description: "Seconds from now to wake up, clamped to [60, 3600]. Required unless stop is true" })),
 			prompt: Type.Optional(Type.String({ description: "The task to continue when the wakeup fires. Required unless stop is true" })),
@@ -488,9 +537,9 @@ export default function backgroundExtension(pi: ExtensionAPI) {
 		pi.events.emit(DEFER_CHANNEL, { name, keywords });
 	}
 
-	pi.registerCommand("background", {
+	registerLocalCommand(pi, "background", {
 		description: "List background tasks (monitors, background subagents)",
-		handler: async (_args, ctx) => {
+		handler: async (args, ctx) => {
 			const tasks = registry.list();
 			ctx.ui.notify(tasks.length ? tasks.map(formatTaskLine).join("\n") : "No background tasks.", "info");
 		},
@@ -509,7 +558,7 @@ export default function backgroundExtension(pi: ExtensionAPI) {
 		}
 	};
 
-	pi.registerCommand("loop", {
+	registerLocalCommand(pi, "loop", {
 		description: "Repeat a task on a loop: `/loop 5m <task>` (fixed interval) or `/loop <task>` (self-paced). `/loop stop` ends it.",
 		handler: async (args, ctx) => {
 			lastCtx = ctx;
@@ -580,7 +629,7 @@ export default function backgroundExtension(pi: ExtensionAPI) {
 				activatedWakeupTool = true;
 			}
 			ctx.ui.notify(`Self-paced loop started: ${parsed.task}. Stop with /loop stop.`, "info");
-			notify("loop", buildDynamicLoopPrompt(parsed.task), {});
+			notify("loop-start", buildDynamicLoopPrompt(parsed.task), {});
 		},
 	});
 

package/extensions/background/monitor-batch.ts

@@ -37,9 +37,12 @@ export function batchSize(batch: MonitorBatch): number {
 	return batch.shown.length + batch.overflow;
 }
 
-/** The notification body for one flushed batch. */
-export function formatMonitorBatch(id: string, description: string, batch: MonitorBatch): string {
-	const total = batchSize(batch);
+/**
+ * The `<event>` body for one flushed batch: the lines, then how many more
+ * arrived (the full stream stays behind `task_output`). The monitor's
+ * description rides the notification's `<summary>`, not this text.
+ */
+export function formatMonitorEvents(id: string, batch: MonitorBatch): string {
 	const lines: string[] = [];
 	let chars = 0;
 	let hidden = batch.overflow;
@@ -52,7 +55,6 @@ export function formatMonitorBatch(id: string, description: string, batch: Monit
 		lines.push(shown);
 		chars += shown.length + 1;
 	}
-	const head = `Monitor ${id} (${description}) emitted ${total} event(s):`;
 	const more = hidden > 0 ? `\n… +${hidden} more line(s) not shown — task_output ${id} has the full stream` : "";
-	return `${head}\n${lines.join("\n")}${more}`;
+	return `${lines.join("\n")}${more}`;
 }

package/extensions/background/wakeup.ts

@@ -1,9 +1,13 @@
 /**
  * schedule_wakeup helpers (pure) — Claude Code's self-paced /loop timer.
+ *
+ * A fired wakeup or loop tick is a RE-INVOCATION, not a notification: Claude
+ * Code enqueues the scheduled prompt verbatim as the next turn's input, behind
+ * a dim "Running scheduled task" line in the TUI (findings §21), so the model
+ * reads its own task back exactly as it wrote it. These builders therefore
+ * return the prompt as-is; the TUI shows the line (`scheduledTaskComponent`).
  */
 
-import { systemNotification } from "../lib/notifications.ts";
-
 export const MIN_DELAY_SECONDS = 60;
 export const MAX_DELAY_SECONDS = 3600;
 
@@ -42,37 +46,27 @@ export function parseLoopArgs(raw: string): ParsedLoop {
 	return { task: raw.trim() };
 }
 
-/** A loop follow-up: an instruction line, a blank, then the task — system-framed. */
-function framedLoop(lead: string, task: string): string {
-	return systemNotification([lead, "", task].join("\n"));
-}
-
-/** The follow-up a fixed-interval `/loop` tick delivers. */
+/** The turn input a fixed-interval `/loop` tick delivers: the task, verbatim (CC's cron fire). */
 export function buildLoopMessage(task: string): string {
-	return framedLoop(
-		"Loop tick — run the task below now. This repeats automatically on the interval and keeps firing until the user runs `/loop stop`.",
-		task,
-	);
+	return task;
 }
 
-/** The opening message for a dynamic (self-paced) `/loop` — instructs the model to drive schedule_wakeup. */
+/**
+ * The opening turn of a dynamic (self-paced) `/loop`: the user's command, so it
+ * reads as their instruction — drive schedule_wakeup, pass the task back each
+ * time. Unframed: it is the user's `/loop`, not a harness event.
+ */
 export function buildDynamicLoopPrompt(task: string): string {
-	return framedLoop(
+	return [
 		"Self-paced loop started. Work the task below now. When this iteration is done, call schedule_wakeup to schedule the next one — choose delaySeconds by what you're waiting for, and pass the same task back as `prompt`. End the loop with schedule_wakeup {stop: true} when the task is complete or the user says to stop.",
+		"",
 		task,
-	);
+	].join("\n");
 }
 
-/** The follow-up message a fired wakeup delivers. Framed so it never reads as user input. */
+/** The turn input a fired wakeup delivers: the scheduled prompt, verbatim (CC re-invokes with it). */
 export function buildWakeupMessage(request: WakeupRequest): string {
-	return systemNotification(
-		[
-			`Scheduled wake-up fired (reason given when scheduled: ${request.reason}).`,
-			"Continue the task below; when done, either schedule the next wake-up with schedule_wakeup or end the loop with schedule_wakeup {stop: true}.",
-			"",
-			request.prompt,
-		].join("\n"),
-	);
+	return request.prompt;
 }
 
 export function describeSchedule(request: WakeupRequest): string {

package/extensions/bash/background.ts

@@ -12,11 +12,11 @@
  * notification and task_output can never disagree.
  */
 
-import { spawn } from "node:child_process";
 import { createWriteStream } from "node:fs";
 import type { BackgroundTask } from "../background/registry.ts";
 import { whenAborted } from "../lib/abort.ts";
-import { detachedSpawnOptions, KILL_GRACE_MS, stopProcessTree } from "../lib/process-tree.ts";
+import { detachedSpawnOptions, KILL_GRACE_MS, stopProcessTree, waitForChildExit } from "../lib/process-tree.ts";
+import { bashSpawnOrThrow, type ShellSpawn, spawnShellCommand } from "../lib/shell-spawn.ts";
 
 export const STORED_OUTPUT_CAP = 200_000;
 
@@ -45,12 +45,18 @@ export interface StartBackgroundBashOptions {
 	/** Kill the process tree after this many seconds. */
 	timeoutSeconds?: number;
 	logPath?: string;
+	/**
+	 * The interpreter to run `command` under. Default: the session's bash
+	 * (lib/shell-spawn.ts — Git Bash on Windows, `CLAUDE_CODE_GIT_BASH_PATH`
+	 * honoured); the powershell extension passes its own spec.
+	 */
+	shell?: ShellSpawn;
 	onFinished(task: BackgroundTask, summary: BashFinishSummary): void;
 }
 
 export function startBackgroundBash(options: StartBackgroundBashOptions): BackgroundTask {
 	// Own process group, so stop/timeout can signal the whole tree (lib/process-tree.ts).
-	const child = spawn(process.env.SHELL || "/bin/sh", ["-c", options.command], {
+	const child = spawnShellCommand(options.shell ?? bashSpawnOrThrow(), options.command, {
 		cwd: options.cwd,
 		...detachedSpawnOptions(),
 		stdio: ["ignore", "pipe", "pipe"],
@@ -80,6 +86,7 @@ export function startBackgroundBash(options: StartBackgroundBashOptions): Backgr
 
 	const task: BackgroundTask = {
 		id: options.id,
+		// "bash" for a PowerShell run too: the kind is what the shell panel lists.
 		kind: "bash",
 		description: options.description,
 		command: options.command,
@@ -124,13 +131,15 @@ export function startBackgroundBash(options: StartBackgroundBashOptions): Backgr
 		else complete();
 	};
 
-	child.on("error", (error) => {
-		stored = stored ? `${stored}\n${error.message}` : error.message;
-		end("failed", null, null);
-	});
-	child.on("close", (code, signal) => {
-		end(stopRequested ? "stopped" : timedOut || code !== 0 ? "failed" : "completed", code, signal);
-	});
+	// Exit plus a short stdio grace, not `close`: a descendant the stop missed
+	// must not keep the task "running" for its whole life (lib/process-tree.ts).
+	waitForChildExit(child).then(
+		({ code, signal }) => end(stopRequested ? "stopped" : timedOut || code !== 0 ? "failed" : "completed", code, signal),
+		(error: Error) => {
+			stored = stored ? `${stored}\n${error.message}` : error.message;
+			end("failed", null, null);
+		},
+	);
 
 	return task;
 }

package/extensions/bash/guards.ts

@@ -34,7 +34,7 @@ import {
 	type Token,
 } from "../auto-mode/shell-analysis.ts";
 
-const clip = (text: string, max = 200): string => (text.length > max ? `${text.slice(0, max)}…` : text);
+export const clip = (text: string, max = 200): string => (text.length > max ? `${text.slice(0, max)}…` : text);
 
 export function bashGuardReason(command: string, opts: { background: boolean }): string | undefined {
 	// A heredoc/here-string body is data, but parseCommand tokenizes it as live
@@ -72,34 +72,54 @@ function sleepSeconds(args: Token[]): number | undefined {
 // A segment's raw slice can keep half of the operator that ended the previous
 // one (`a && b` → second raw is `& b`) — strip it for a clean echo.
 
-function waitReason(segments: Segment[]): string | undefined {
-	// Measure the run of LEADING sleep segments: `sleep 1 && sleep 1 && …` is
-	// one wait spelled as a chain, so the pacing exemption applies only to a
-	// single provably-short sleep. Unprovable durations (`sleep "$DELAY"`)
-	// count as long — the model controls the literal.
+/**
+ * The wait guard's grammar-independent half, shared with the PowerShell
+ * guards: measure the run of LEADING sleep statements — `sleep 1 && sleep 1 &&
+ * …` is one wait spelled as a chain, so the pacing exemption applies only to a
+ * single provably-short sleep. Unprovable durations (`sleep "$DELAY"`) count
+ * as long: the model controls the literal. `sleepSeconds` returns undefined
+ * for a non-sleep statement.
+ */
+export function leadingSleepReason<T>(
+	statements: T[],
+	sleepSeconds: (statement: T) => number | undefined | null,
+	raw: (statement: T) => string,
+	opts: { sleepName: string; joiner: string; untilExample: string },
+): string | undefined {
 	let leadSleeps = 0;
 	let total: number | undefined = 0;
-	for (const seg of segments) {
-		const { command: cmd, args } = resolvePayload(leadTokens(seg));
-		if (cmd !== "sleep") break;
+	for (const statement of statements) {
+		const seconds = sleepSeconds(statement);
+		if (seconds === null) break; // not a sleep
 		leadSleeps++;
-		const seconds = sleepSeconds(args);
 		total = total === undefined || seconds === undefined ? undefined : total + seconds;
 	}
 	if (leadSleeps === 0) return undefined;
 	if (leadSleeps === 1 && total !== undefined && total < 2) return undefined;
-	const rest = segments.slice(leadSleeps).map((seg) => seg.raw).filter(Boolean).join("; ");
-	const shown = segments.slice(0, leadSleeps).map((seg) => seg.raw).join(" && ");
+	const rest = statements.slice(leadSleeps).map(raw).filter(Boolean).join("; ");
+	const shown = statements.slice(0, leadSleeps).map(raw).join(opts.joiner);
 	const echo = rest ? `\`${shown}\` followed by: ${clip(rest)}` : `standalone \`${shown}\``;
 	return (
-		`Blocked: ${echo}. A foreground sleep stalls the whole session while it runs. ` +
-		"To wait for a command you started, run it with run_in_background: true — its completion arrives as a system notification on its own, so you never need to poll. " +
-		"To wait for a condition, use the monitor tool with an until-loop (e.g. `until <check>; do sleep 2; done`) — monitor is deferred, load it with tool_search select:monitor. " +
+		`Blocked: ${echo}. A foreground ${opts.sleepName} stalls the whole session while it runs. ` +
+		"To wait for a command you started, run it with run_in_background: true — its completion arrives as a task notification on its own, so you never need to poll. " +
+		`To wait for a condition, use the monitor tool with an until-loop (e.g. \`${opts.untilExample}\`) — monitor is deferred, load it with tool_search select:monitor. ` +
 		"If you genuinely need a delay (rate limiting, deliberate pacing), keep it under 2 seconds. " +
 		"Do not chain shorter sleeps to work around this block."
 	);
 }
 
+function waitReason(segments: Segment[]): string | undefined {
+	return leadingSleepReason(
+		segments,
+		(seg) => {
+			const { command: cmd, args } = resolvePayload(leadTokens(seg));
+			return cmd === "sleep" ? sleepSeconds(args) : null;
+		},
+		(seg) => seg.raw,
+		{ sleepName: "sleep", joiner: " && ", untilExample: "until <check>; do sleep 2; done" },
+	);
+}
+
 // ---------------------------------------------------------------------------
 // Poll-loop guard
 
@@ -173,7 +193,7 @@ export function hasBackgroundAmp(command: string): boolean {
 function orphanReason(command: string, segments: Segment[]): string | undefined {
 	const message = (via: string) =>
 		`Blocked: this command detaches a process with ${via}, leaving an orphan this session cannot manage — its output and exit status would be lost. ` +
-		"Run it with run_in_background: true instead: it returns a task id immediately, completion arrives as a system notification, output stays readable with task_output, and it can be stopped with task_stop. " +
+		"Run it with run_in_background: true instead: it returns a task id immediately, completion arrives as a task notification, output stays readable with task_output, and it can be stopped with task_stop. " +
 		"If you need shell-level parallelism inside one command, end it with `wait` so the children are reaped.";
 
 	for (const seg of segments) {