@gajae-code/coding-agent 0.13.2 → 0.14.0

package/src/task/executor.ts

@@ -24,6 +24,7 @@ import {
 	type ServiceTier,
 } from "@gajae-code/ai/core";
 import { type JsonSchemaValidationIssue, validateJsonSchemaValue } from "@gajae-code/ai/utils/schema";
+import * as canonicalSdk from "@gajae-code/coding-agent/sdk";
 import { logger, prompt, untilAborted } from "@gajae-code/utils";
 import { AsyncJobManager } from "../async";
 import { ModelRegistry } from "../config/model-registry";
@@ -42,7 +43,7 @@ import subagentSystemPromptTemplate from "../prompts/system/subagent-system-prom
 import subagentUserPromptTemplate from "../prompts/system/subagent-user-prompt.md" with { type: "text" };
 import submitReminderTemplate from "../prompts/system/subagent-yield-reminder.md" with { type: "text" };
 import { AgentRegistry } from "../registry/agent-registry";
-import { createAgentSession, discoverAuthStorage } from "../sdk";
+import { discoverAuthStorage } from "../sdk";
 import type { AgentSession, AgentSessionEvent, ForkContextSeed } from "../session/agent-session";
 import type { ArtifactManager } from "../session/artifacts";
 import type { AuthStorage } from "../session/auth-storage";
@@ -269,6 +270,15 @@ export interface ExecutorOptions {
 	 */
 	parentArtifactManager?: ArtifactManager;
 	managedPersistence?: ManagedTaskPersistence;
+	/**
+	 * The parent session's ENDPOINT-owned AsyncJobManager (resolved by the
+	 * TaskTool via forEndpoint(sessionId) ?? instance()). Model metadata and
+	 * live-handle state for THIS subagent are recorded in the SAME manager the
+	 * task job runs in — with concurrent top-level sessions the process-global
+	 * instance belongs to a different session and would surface this subagent
+	 * under the wrong session's record (review thread P1).
+	 */
+	asyncJobManager?: AsyncJobManager;
 	parentHindsightSessionState?: HindsightSessionState;
 	/**
 	 * Parent agent's OpenTelemetry configuration. When defined, the subagent's
@@ -1560,7 +1570,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 			// Record which model the subagent actually runs on (and any auth fallback,
 			// see #985) so the subagent panel can surface it to the user.
 			if (model) {
-				AsyncJobManager.instance()?.updateSubagentModel?.(options.subagentId ?? id, {
+				(options.asyncJobManager ?? AsyncJobManager.instance())?.updateSubagentModel?.(options.subagentId ?? id, {
 					requestedModel: modelSubstitutionWarning?.requested ?? resolvedModelString,
 					effectiveModel: resolvedModelString,
 					modelFellBack: authFallbackUsed === true,
@@ -1676,7 +1686,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 			}
 
 			const { session } = await awaitAbortable(
-				createAgentSession({
+				canonicalSdk.createAgentSession({
 					cwd: worktree ?? cwd,
 					authStorage,
 					modelRegistry,
@@ -1738,6 +1748,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 					},
 					parentHindsightSessionState: options.parentHindsightSessionState,
 					parentTaskPrefix: id,
+					inheritedAsyncJobManager: options.asyncJobManager,
 					inheritedMcpManager: options.parentMcpManager,
 					agentId: id,
 					agentDisplayName: agent.name,
@@ -1761,7 +1772,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 				session.seedDefaultFallbackResolution(activeIndex ?? 0, skips);
 			}
 			const liveSubagentId = options.subagentId ?? id;
-			const manager = AsyncJobManager.instance();
+			const manager = options.asyncJobManager ?? AsyncJobManager.instance();
 			if (manager) {
 				manager.registerLiveHandle(liveSubagentId, {
 					requestPause: () => {
@@ -1964,12 +1975,20 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 				if (event.type === "model_fallback_switched") {
 					activeProviderModelString = event.to;
 					progress.fastMode = isFastForModel(session.model);
-					AsyncJobManager.instance()?.updateSubagentModel?.(options.subagentId ?? id, {
-						requestedModel: modelSubstitutionWarning?.requested ?? resolvedModelString,
-						effectiveModel: event.to,
-						modelFellBack: true,
-						fastMode: progress.fastMode,
-					});
+					// Keep the fallback metadata on the SAME manager the initial
+					// update used: another session may have become the
+					// process-global instance, and writing to it would leave this
+					// session's subagent metadata stale or overwrite an unrelated
+					// same-ID record (review thread P2).
+					(options.asyncJobManager ?? AsyncJobManager.instance())?.updateSubagentModel?.(
+						options.subagentId ?? id,
+						{
+							requestedModel: modelSubstitutionWarning?.requested ?? resolvedModelString,
+							effectiveModel: event.to,
+							modelFellBack: true,
+							fastMode: progress.fastMode,
+						},
+					);
 					scheduleProgress(true);
 					forwardSubagentEvent(event);
 					return;
@@ -2108,7 +2127,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 				if (exitCode === 0) exitCode = 1;
 			}
 			sessionAbortController.abort();
-			AsyncJobManager.instance()?.removeLiveHandle(options.subagentId ?? id);
+			(options.asyncJobManager ?? AsyncJobManager.instance())?.removeLiveHandle(options.subagentId ?? id);
 			if (unsubscribe) {
 				try {
 					unsubscribe();

package/src/task/index.ts

@@ -18,9 +18,14 @@ import * as os from "node:os";
 import path from "node:path";
 import type { AgentTool, AgentToolResult, AgentToolUpdateCallback } from "@gajae-code/agent-core";
 import type { Model, Usage } from "@gajae-code/ai/core";
+import {
+	AsyncJobManager,
+	OwnerSubagentShutdownError,
+	type ResumeRunner,
+	type SubagentRunOutcome,
+} from "@gajae-code/coding-agent/async";
 import { $pickenv, prompt, Snowflake } from "@gajae-code/utils";
 import type { ToolSession } from "..";
-import { AsyncJobManager, OwnerSubagentShutdownError, type ResumeRunner, type SubagentRunOutcome } from "../async";
 import { resolveProfileBindings } from "../config/model-profiles";
 import { resolveAgentModelPatterns } from "../config/model-resolver";
 import type { Theme } from "../modes/theme/theme";
@@ -56,8 +61,10 @@ import {
 } from "../gjc-runtime/repository-binding";
 import { initializeLocalRoot, type LocalProtocolOptions, resolveLocalUrlToPath } from "../internal-urls";
 import { ArtifactManager } from "../session/artifacts";
+import { registerOwnedIfLineaged } from "../session/terminal-abort";
 import { generateCommitMessage } from "../utils/commit-message-generator";
 import * as git from "../utils/git";
+import { loadBundledAgents } from "./agents";
 import { discoverAgents, filterVisibleAgents, getAgent } from "./discovery";
 import { createManagedTaskPersistence, renderSubagentUserPrompt, runSubprocess } from "./executor";
 import { adviseForkContextMode } from "./fork-context-advisory";
@@ -66,7 +73,6 @@ import { getTaskIdValidationError, validateAllocatedTaskId } from "./id";
 import { AgentOutputManager } from "./output-manager";
 import { mapWithConcurrencyLimit, Semaphore } from "./parallel";
 import { assertNoRawTaskFields, buildTaskReceipt, buildTaskRoiSummary, type TaskResultReceipt } from "./receipt";
-
 import { renderResult, renderCall as renderTaskCall } from "./render";
 import { reconcileSpawnRoi } from "./roi-reconciliation";
 import { getTaskSimpleModeCapabilities, type TaskSimpleMode } from "./simple-mode";
@@ -796,6 +802,30 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 		return new TaskTool(session, agents, publicRepositoryBinding(sessionRepositoryBinding));
 	}
 
+	/** Create catalog metadata from bundled agents only, without ambient filesystem discovery. */
+	static async createForToolCatalog(session: ToolSession): Promise<TaskTool> {
+		const sessionRepositoryBinding = await captureRepositoryBinding(session.cwd, { displayPath: session.cwd });
+		await assertExecutionRootMatchesRepositoryBinding(session.cwd, sessionRepositoryBinding);
+		return new TaskTool(session, loadBundledAgents(), publicRepositoryBinding(sessionRepositoryBinding));
+	}
+
+	/**
+	 * The session's ENDPOINT-owned AsyncJobManager, falling back to the
+	 * process-global instance. Concurrent top-level sessions each register
+	 * their manager under their endpoint (sdk/session.ts), so a task job
+	 * created by THIS session must be registered, resumed, and reported
+	 * through THIS session's manager — otherwise a scope:"owned" abort
+	 * consults the endpoint manager and cannot cancel or prove the task, and
+	 * its completion is delivered by the wrong session's callback (review
+	 * thread P1).
+	 */
+	#resolveOwnedJobManager(): AsyncJobManager | undefined {
+		const endpointId = this.session.getSessionId?.() ?? undefined;
+		return (
+			this.session.getAsyncJobManager?.() ?? AsyncJobManager.forEndpoint(endpointId) ?? AsyncJobManager.instance()
+		);
+	}
+
 	async execute(
 		_toolCallId: string,
 		rawParams: unknown,
@@ -886,7 +916,14 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 			};
 		}
 
-		const manager = AsyncJobManager.instance();
+		// The session's ENDPOINT-owned manager first: with concurrent top-level
+		// sessions the process-global instance may belong to a different
+		// session, and an endpoint-qualified owned registration recorded here
+		// must live in the SAME manager the job actually runs in — otherwise a
+		// scope:"owned" abort consults the endpoint manager, cannot cancel or
+		// prove the task, and returns uncertainty while the task continues
+		// (review thread P1).
+		const manager = this.#resolveOwnedJobManager();
 		if (!manager) {
 			return {
 				content: [{ type: "text", text: "Subagent background execution is unavailable in this session." }],
@@ -1015,7 +1052,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 		};
 		let resumeRunner: ResumeRunner | undefined;
 		if (typeof manager.setResumeRunner === "function") {
-			resumeRunner = (_subagentId, message, resumeDescriptor) => {
+			resumeRunner = (_subagentId, message, resumeDescriptor, resumeToolCallId) => {
 				const descriptor = isTaskResumeDescriptor(resumeDescriptor?.data) ? resumeDescriptor.data : undefined;
 				if (!descriptor) return undefined;
 				const admission = (() => {
@@ -1066,7 +1103,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 					repositoryBinding: descriptor.repositoryBinding,
 					duplicate_policy: descriptor.duplicatePolicy,
 				};
-				return manager.register(
+				const resumeJobId = manager.register(
 					"task",
 					descriptor.task.id,
 					async ({ signal: runSignal }) => {
@@ -1128,6 +1165,21 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 						},
 					},
 				);
+				// Bind the resumed job to the CURRENT resume request's tool call
+				// (the original launch id would attribute it to the OLD turn, so a
+				// scope:"owned" abort of the resuming turn could miss it — review
+				// thread P1).
+				// The registration is ENDPOINT-qualified: concurrent sessions can
+				// receive the same provider-local tool-call id, and an
+				// endpoint-less resolve would take the FIRST matching binding —
+				// registering B's task under A's endpoint/lineage (review P1).
+				registerOwnedIfLineaged(
+					manager,
+					resumeToolCallId ?? descriptor.toolCallId,
+					resumeJobId,
+					this.session.getSessionId?.() ?? undefined,
+				);
+				return resumeJobId;
 			};
 			manager.setResumeRunner(resumeRunner);
 		}
@@ -1357,6 +1409,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 						},
 					},
 				);
+				registerOwnedIfLineaged(manager, _toolCallId, jobId, this.session.getSessionId?.() ?? undefined);
 				startedJobs.push({ jobId, taskId: taskItem.id });
 				if (typeof manager.registerResumeDescriptor === "function") {
 					manager.registerResumeDescriptor(
@@ -1960,6 +2013,10 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 				},
 			) => {
 				const forkContextSeed = prebuiltForkContextSeeds?.get(task.id) ?? (await buildForkContextSeed(task));
+				// The session's ENDPOINT-owned manager (resolved once per task so
+				// model metadata and live handles land in the SAME manager the
+				// job runs in — review thread P1).
+				const manager = this.#resolveOwnedJobManager();
 				const forkContext = requestsForkContext(task)
 					? { mode: task.inheritContext, clonedTokens: forkContextSeed?.metadata.approximateTokens ?? 0 }
 					: undefined;
@@ -2000,6 +2057,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 						runMode: overrides?.runMode ?? executionOverrides?.runMode,
 						resumeMessage: overrides?.resumeMessage ?? executionOverrides?.resumeMessage,
 						subagentId: task.id,
+						asyncJobManager: manager,
 						taskDepth,
 						modelOverride,
 						parentActiveModelPattern,
@@ -2022,7 +2080,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 							progressMap.set(index, {
 								...structuredClone(progress),
 							});
-							AsyncJobManager.instance()?.recordSubagentProgress(task.id, progress);
+							this.#resolveOwnedJobManager()?.recordSubagentProgress(task.id, progress);
 							emitProgress();
 						},
 						authStorage: this.session.authStorage,
@@ -2077,6 +2135,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 						runMode: overrides?.runMode ?? executionOverrides?.runMode,
 						resumeMessage: overrides?.resumeMessage ?? executionOverrides?.resumeMessage,
 						subagentId: task.id,
+						asyncJobManager: manager,
 						taskDepth,
 						modelOverride,
 						parentActiveModelPattern,
@@ -2099,7 +2158,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 							progressMap.set(index, {
 								...structuredClone(progress),
 							});
-							AsyncJobManager.instance()?.recordSubagentProgress(task.id, progress);
+							this.#resolveOwnedJobManager()?.recordSubagentProgress(task.id, progress);
 							emitProgress();
 						},
 						authStorage: this.session.authStorage,

package/src/task/render.ts

@@ -987,12 +987,17 @@ export function renderResult(
 
 			const lines: string[] = [];
 
+			// Tool details can be restored from a persisted session or arrive through
+			// a runtime update, so the declared receipt array is not sufficient at
+			// this rendering boundary.
+			const resultsUnavailable = !Array.isArray(details.results);
+			const results = resultsUnavailable ? [] : details.results;
 			const hasProgress = Boolean(details.progress && details.progress.length > 0);
-			const shouldRenderProgress = hasProgress && (isPartial || details.results.length === 0);
-			const hasResults = details.results.length > 0;
+			const shouldRenderProgress = hasProgress && (isPartial || results.length === 0);
+			const hasResults = results.length > 0;
 			if (hasResults) {
-				details.results.forEach((res, i) => {
-					const isLast = !shouldRenderProgress && i === details.results.length - 1;
+				results.forEach((res, i) => {
+					const isLast = !shouldRenderProgress && i === results.length - 1;
 					lines.push(...renderAgentResult(res, isLast, expanded, theme));
 				});
 			}
@@ -1004,10 +1009,10 @@ export function renderResult(
 				});
 			}
 			if (hasResults && !shouldRenderProgress) {
-				const abortedCount = details.results.filter(r => r.status === "aborted").length;
-				const mergeFailedCount = details.results.filter(r => r.status === "merge_failed").length;
-				const successCount = details.results.filter(r => r.status === "completed").length;
-				const failCount = details.results.length - successCount - mergeFailedCount - abortedCount;
+				const abortedCount = results.filter(r => r.status === "aborted").length;
+				const mergeFailedCount = results.filter(r => r.status === "merge_failed").length;
+				const successCount = results.filter(r => r.status === "completed").length;
+				const failCount = results.length - successCount - mergeFailedCount - abortedCount;
 				let summary = `${theme.fg("dim", "Total:")} `;
 				if (abortedCount > 0) {
 					summary += theme.fg("error", `${abortedCount} aborted`);
@@ -1027,9 +1032,18 @@ export function renderResult(
 				summary += `${theme.sep.dot}${theme.fg("dim", formatDuration(details.totalDurationMs))}`;
 				lines.push(summary);
 			}
+			if (resultsUnavailable && !isPartial) {
+				lines.push(theme.fg("dim", "Task result details unavailable"));
+			}
 
 			if (lines.length === 0) {
-				const text = fallbackText.trim() ? fallbackText : "No results";
+				const text = resultsUnavailable
+					? isPartial
+						? "Task results pending"
+						: "Task result details unavailable"
+					: fallbackText.trim()
+						? fallbackText
+						: "No results";
 				const result = [theme.fg("dim", truncateToWidth(text, width))];
 				if (!hasDynamicRetry) cached = { key, lines: result };
 				return result;

package/src/tools/ask-answer-registry.ts

@@ -3,8 +3,10 @@
  *
  * Decouples the `ask` tool (which reads the source via `AgentSession`) from the
  * notifications extension (which registers one), without threading a new method
- * through the extension/runner/controller wiring. A session has at most one
- * source; registering returns a disposer.
+ * through the extension/runner/controller wiring. A session may have multiple
+ * sources. A "protocol" source always takes precedence over an "interactive"
+ * source regardless of registration order; within the same kind, the most
+ * recently registered source wins. Registering returns a disposer.
  */
 
 /** Error code a remote ask source uses to signal that its own timeout fired. */
@@ -14,19 +16,31 @@ import { logger } from "@gajae-code/utils";
 import type { WorkflowGateEmitter } from "../modes/shared/agent-wire/workflow-gate-broker";
 import type { AskAnswerSource } from "./index";
 
-const sources = new Map<string, AskAnswerSource[]>();
+export type AskAnswerSourceKind = "protocol" | "interactive";
+
+interface RegisteredAskAnswerSource {
+	readonly source: AskAnswerSource;
+	readonly kind: AskAnswerSourceKind;
+}
+
+const sources = new Map<string, RegisteredAskAnswerSource[]>();
 const workflowGateEmitters = new Map<string, WorkflowGateEmitter>();
 const workflowGateListeners = new Map<string, Set<(emitter: WorkflowGateEmitter | undefined) => void>>();
 
 /** Register `source` for `sessionId`. Returns a disposer that restores the prior source. */
-export function registerAskAnswerSource(sessionId: string, source: AskAnswerSource): () => void {
+export function registerAskAnswerSource(
+	sessionId: string,
+	source: AskAnswerSource,
+	kind: AskAnswerSourceKind = "interactive",
+): () => void {
 	const stack = sources.get(sessionId) ?? [];
-	stack.push(source);
+	const entry: RegisteredAskAnswerSource = { source, kind };
+	stack.push(entry);
 	sources.set(sessionId, stack);
 	return () => {
 		const current = sources.get(sessionId);
 		if (!current) return;
-		const index = current.lastIndexOf(source);
+		const index = current.lastIndexOf(entry);
 		if (index >= 0) current.splice(index, 1);
 		if (current.length === 0) sources.delete(sessionId);
 	};
@@ -34,7 +48,9 @@ export function registerAskAnswerSource(sessionId: string, source: AskAnswerSour
 
 /** The highest-priority answer source for `sessionId`, if one is registered. */
 export function getAskAnswerSource(sessionId: string): AskAnswerSource | undefined {
-	return sources.get(sessionId)?.at(-1);
+	const entries = sources.get(sessionId);
+	const protocolEntry = entries?.findLast(entry => entry.kind === "protocol");
+	return protocolEntry?.source ?? entries?.at(-1)?.source;
 }
 
 /** Publish a session's current workflow-gate emitter after mode initialization. */

package/src/tools/ask.ts

@@ -803,10 +803,14 @@ export class AskTool implements AgentTool<AskParametersSchema, AskToolDetails> {
 		_onUpdate?: AgentToolUpdateCallback<AskToolDetails>,
 		context?: AgentToolContext,
 	): Promise<AgentToolResult<AskToolDetails>> {
-		await assertUltragoalAskAllowed(this.session.cwd, {
-			activeSkillState: this.session.getActiveSkillState?.(),
-			sessionId: this.session.getSessionId?.() ?? null,
-		});
+		await assertUltragoalAskAllowed(
+			this.session.cwd,
+			{
+				activeSkillState: this.session.getActiveSkillState?.(),
+				sessionId: this.session.getSessionId?.() ?? null,
+			},
+			this.session.getSessionAgentDir?.() ?? this.session.settings.getAgentDir(),
+		);
 		assertDeepInterviewStructuredResponseWithinLimit(params);
 		let activeRemoteReceipt: AskRemoteReceipt | undefined;
 		let activeRemoteRequest: AskAnswerRequest | undefined;

package/src/tools/bash-sleep-advisory.ts

@@ -0,0 +1,115 @@
+/**
+ * Advisory detection of long blocking `sleep` in bash commands (#4465).
+ *
+ * When the agent reaches for a long silent `sleep N` instead of using
+ * `subagent await` or `job poll` to wait for background work, the session emits
+ * nothing for the entire duration and looks indistinguishable from a hang to
+ * the operator. This module detects that pattern and returns a bounded advisory
+ * notice — it never blocks the command, adds no fake progress, and respects the
+ * authority boundary: only the tool result/guidance surfaces the warning, not a
+ * runtime refusal. Legitimate sleeps (daemons, test servers, rate-limit pacing)
+ * are not blocked; the notice is purely advisory.
+ *
+ * Detection is intentionally conservative: a standalone `sleep` with an explicit
+ * numeric duration at or above the threshold, or a `sleep` chained with `&&` to
+ * a single trailing command (the common "sleep then check" pattern from #4465).
+ * Compound commands where `sleep` is incidental to real work are not flagged.
+/**
+ * Minimum sleep duration (in seconds) that triggers the advisory notice.
+ */
+const LONG_SLEEP_THRESHOLD_SEC = 120;
+
+/**
+ * Matches a standalone `sleep` command with an explicit numeric duration.
+ * Supports `sleep N`, `sleep Ns`, `sleep Nm`, `sleep Nh`, `sleep 1d`, and
+ * multiple arguments (`sleep 5 3` — sleeps 5s per POSIX, but the intent is the
+ * same). The number is parsed as seconds for the threshold check.
+ *
+ * Examples that trigger:
+ *   `sleep 800`
+ *   `sleep 800; git log --oneline -1`
+ *   `sleep 300 && git log --oneline -1`
+ *   `sleep 5m`
+ *
+ * Examples that do NOT trigger:
+ *   `sleep 5`
+ *   `sleep 10; echo done`
+ *   `server --port 3000` (no sleep at all)
+ */
+const SLEEP_DURATION_RE = /(?:^|[\s;&|]+)sleep\s+([0-9]+(?:\.[0-9]+)?)([smhd]?)/;
+
+/** Parse a sleep duration token into seconds. */
+function parseSleepSeconds(rawNumber: string, unit: string): number {
+	const value = Number.parseFloat(rawNumber);
+	if (!Number.isFinite(value) || value <= 0) return 0;
+	const unitLower = unit.toLowerCase();
+	switch (unitLower) {
+		case "":
+		case "s":
+			return value;
+		case "m":
+			return value * 60;
+		case "h":
+			return value * 3600;
+		case "d":
+			return value * 86400;
+		default:
+			return value;
+	}
+}
+
+/** Round seconds to the nearest whole minute for human-readable display. */
+function roundToMinutes(seconds: number): number {
+	return Math.round(seconds / 60);
+}
+
+/**
+ * Format a duration in seconds as a short `Xm` / `Xs` string.
+ *
+ * `Xs` for anything under a minute (covers the zero case), otherwise `Xm`.
+ * Uses the same minute rounding as the notice body so the two stay consistent.
+ */
+function formatDuration(seconds: number): string {
+	return seconds < 60 ? `${Math.round(seconds)}s` : `${roundToMinutes(seconds)}m`;
+}
+
+/**
+ * Detect a long blocking sleep in a bash command and return an advisory notice,
+ * or `undefined` if the command does not contain a qualifying sleep. The notice
+ * is appended to the bash result output; it never blocks execution.
+ *
+ * `timeoutSec` is the effective (already-clamped) execution timeout the command
+ * will run under, when known. The bash tool kills the command at this timeout
+ * whether the sleep fits inside it or not. Passing it lets the notice report
+ * the bounded effective silent wait the operator will actually observe, instead
+ * of the requested duration (which may be much longer and is never reached).
+ * When `timeoutSec` is `undefined` (no timeout known at the construction
+ * boundary), the notice reports only the requested duration and stays useful.
+ */
+export function longSleepAdvisory(command: string, timeoutSec?: number): string | undefined {
+	const match = command.match(SLEEP_DURATION_RE);
+	if (!match) return undefined;
+	const requestedSeconds = parseSleepSeconds(match[1]!, match[2]!);
+	if (requestedSeconds < LONG_SLEEP_THRESHOLD_SEC) return undefined;
+
+	const parts = [
+		`Note: this command requests a sleep of ~${formatDuration(requestedSeconds)}, during which the session produces no output and is indistinguishable from a hang (#4465).`,
+	];
+
+	// When the effective timeout is known and is shorter than the requested
+	// sleep, the command is killed at the timeout — the operator never sees the
+	// full requested duration. Surface the bounded wait so the notice matches
+	// observable behavior. (For PTY/async the same timeout applies: the tool
+	// kills the command at timeoutSec regardless of mode.)
+	if (timeoutSec !== undefined && timeoutSec < requestedSeconds) {
+		parts.push(
+			`The execution timeout will kill this command after ~${formatDuration(timeoutSec)}, so the effective silent wait is bounded by the timeout, not the requested sleep.`,
+		);
+	}
+
+	parts.push(
+		"Long blocking sleeps are not how to wait for subagents or background jobs.",
+		"Prefer `subagent await` (which emits periodic liveness) or `job poll` to wait observably.",
+	);
+	return parts.join(" ");
+}