@sayknow-cli/coding-agent 0.3.12 → 0.3.13

package/src/slash-commands/builtin-registry.ts

@@ -3,7 +3,7 @@ import * as path from "node:path";
 import { ThinkingLevel } from "@sayknow-cli/agent-core";
 import { type Model, modelsAreEqual } from "@sayknow-cli/ai";
 import { getOAuthProviders } from "@sayknow-cli/ai/utils/oauth";
-import { Spacer, Text } from "@sayknow-cli/tui";
+import { isPetMode, PET_MODE_IDS, PET_SKIN_IDS, PET_SKINS, Spacer, Text } from "@sayknow-cli/tui";
 import { setProjectDir } from "@sayknow-cli/utils";
 import { jobElapsedMs } from "../async";
 import { materializeActiveModelProfileAssignments } from "../config/model-profile-activation";
@@ -23,8 +23,20 @@ import { clearPluginRootsAndCaches, resolveActiveProjectRegistryPath } from "../
 import { td } from "../i18n";
 import { resolveMemoryBackend } from "../memory-backend";
 import { DynamicBorder } from "../modes/components/dynamic-border";
+import { SayknowPetWidget } from "../modes/components/sayknow-pet-widget";
 import { theme } from "../modes/theme/theme";
 import type { InteractiveModeContext } from "../modes/types";
+import {
+	buildNotificationStatusReport,
+	checkNotificationHealth,
+	formatNotificationHealthReport,
+	formatNotificationRecoveryReport,
+	formatNotificationStatusReport,
+	formatNotificationTestResult,
+	recoverNotifications,
+	sendNotificationTest,
+} from "../notifications/notification-service";
+import { computeCacheMissCostSummary, formatCacheMissSummaryLines } from "../session/cache-economics";
 import { formatModelOnboardingGuidance } from "../setup/model-onboarding-guidance";
 import {
 	addApiCompatibleProvider,
@@ -37,7 +49,7 @@ import { getDisplayChangelogEntries } from "../utils/changelog";
 import { buildContextReportText } from "./helpers/context-report";
 import { buildFastStatusReport } from "./helpers/fast-status-report";
 import { formatDuration } from "./helpers/format";
-import { commandConsumed, errorMessage, parseSlashCommand, usage } from "./helpers/parse";
+import { commandConsumed, errorMessage, parseSlashCommand, parseSubcommand, usage } from "./helpers/parse";
 import { handleSshAcp } from "./helpers/ssh";
 import { buildUsageReportText } from "./helpers/usage-report";
 import type {
@@ -471,6 +483,66 @@ const shutdownHandlerTui = (_command: ParsedSlashCommand, runtime: TuiSlashComma
 };
 
 const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
+	{
+		name: "notify",
+		priority: 30,
+		description: "Notification status, health, test, recovery, and session on/off",
+		acpDescription: "Notification status, health, test, recovery, and session on/off",
+		subcommands: [
+			{ name: "on", description: "Enable notifications for this session" },
+			{ name: "off", description: "Disable notifications for this session" },
+			{ name: "status", description: "Show notification configuration (no secrets)" },
+			{ name: "health", description: "Config, daemon-ownership and endpoint health" },
+			{ name: "test", description: "Send a test notification", usage: "[message]" },
+			{ name: "recovery", description: "Clear dead-owner locks and stale endpoint files" },
+			{ name: "setup", description: "How to pair a Telegram bot (run in a terminal)" },
+		],
+		inlineHint: "[on|off|status|health|test|recovery|setup]",
+		acpInputHint: "[on|off|status|health|test|recovery|setup]",
+		allowArgs: true,
+		handle: async (command, runtime) => {
+			const { verb, rest } = parseSubcommand(command.args);
+			const action = verb || "status";
+			// `on`/`off` are session-local runtime controls owned by the
+			// notifications extension command (`api.registerCommand("notify")`),
+			// which holds the live per-session server/disable state. Pass them
+			// through untouched — never consume them — so this builtin cannot
+			// shadow that control. Everything below is config/service diagnostics
+			// the extension does not implement, so the builtin owns them exclusively
+			// (and the extension therefore never consumes them).
+			if (action === "on" || action === "off") {
+				return { prompt: command.text };
+			}
+			const stateRoot = path.join(runtime.cwd, ".skc", "state");
+			switch (action) {
+				case "status":
+					await runtime.output(formatNotificationStatusReport(buildNotificationStatusReport(runtime.settings)));
+					return commandConsumed();
+				case "health": {
+					const report = await checkNotificationHealth({ settings: runtime.settings, stateRoot });
+					await runtime.output(formatNotificationHealthReport(report));
+					return commandConsumed();
+				}
+				case "test": {
+					const result = await sendNotificationTest({ settings: runtime.settings, text: rest || undefined });
+					await runtime.output(formatNotificationTestResult(result));
+					return commandConsumed();
+				}
+				case "recovery": {
+					const report = await recoverNotifications({ settings: runtime.settings, stateRoot });
+					await runtime.output(formatNotificationRecoveryReport(report));
+					return commandConsumed();
+				}
+				case "setup":
+					return usage(
+						"Run `skc notify setup` in a terminal to pair a Telegram bot token with a private chat (interactive; requires a TTY).",
+						runtime,
+					);
+				default:
+					return usage(`Usage: /notify [on|off|status|health|test|recovery|setup] (got "${action}")`, runtime);
+			}
+		},
+	},
 	{
 		name: "settings",
 		priority: 40,
@@ -488,6 +560,39 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 			runtime.ctx.editor.setText("");
 		},
 	},
+	{
+		name: "pet",
+		description: "Sayknow pet living beside the composer",
+		subcommands: [
+			{ name: "off", description: "Hide the pet" },
+			...PET_SKIN_IDS.map(id => ({ name: id, description: PET_SKINS[id].description })),
+		],
+		inlineHint: `[${PET_MODE_IDS.join("|")}]`,
+		allowArgs: true,
+		handleTui: (command, runtime) => {
+			const ctx = runtime.ctx;
+			const raw = command.args?.trim().toLowerCase() ?? "";
+			const arg = raw === "on" ? "red" : raw;
+			if (!arg) {
+				ctx.showPetSelector();
+				ctx.editor.setText("");
+				return;
+			}
+			if (arg !== "off" && !SayknowPetWidget.pixelProtocol()) {
+				ctx.showStatus(
+					"Sayknow pet needs a sixel/kitty-graphics terminal (Windows Terminal 1.22+, kitty, Ghostty, WezTerm)",
+					{ dim: true },
+				);
+			} else if (isPetMode(arg)) {
+				ctx.setPetMode(arg);
+				const name = arg === "off" ? "Sayknow pet hidden" : `${PET_SKINS[arg].label} is here`;
+				ctx.showStatus(name);
+			} else {
+				ctx.showStatus(`Usage: /pet [${PET_MODE_IDS.join("|")}]`, { dim: true });
+			}
+			ctx.editor.setText("");
+		},
+	},
 	{
 		name: "goal",
 		priority: 84,
@@ -821,13 +926,42 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 		allowArgs: true,
 		handle: async (command, runtime) => {
 			if (!command.args || command.args === "info") {
-				await runtime.output(
-					[
-						`Session: ${runtime.session.sessionId}`,
-						`Title: ${runtime.session.sessionName}`,
-						`CWD: ${runtime.cwd}`,
-					].join("\n"),
-				);
+				const stats = runtime.session.getSessionStats();
+				const lines = [
+					`Session: ${runtime.session.sessionId}`,
+					`Title: ${runtime.session.sessionName}`,
+					`CWD: ${runtime.cwd}`,
+					"",
+					"Tokens",
+					`Input: ${stats.tokens.input.toLocaleString()}`,
+					`Output: ${stats.tokens.output.toLocaleString()}`,
+				];
+				if (stats.tokens.cacheRead > 0) {
+					lines.push(`Cache Read: ${stats.tokens.cacheRead.toLocaleString()}`);
+				}
+				if (stats.tokens.cacheWrite > 0) {
+					lines.push(`Cache Write: ${stats.tokens.cacheWrite.toLocaleString()}`);
+				}
+				lines.push(`Total: ${stats.tokens.total.toLocaleString()}`);
+				if (stats.cost > 0 || stats.premiumRequests > 0) {
+					lines.push("", "Cost");
+					if (stats.cost > 0) {
+						lines.push(`Total: ${stats.cost.toFixed(4)}`);
+					}
+					if (stats.premiumRequests > 0) {
+						lines.push(`Premium Requests: ${stats.premiumRequests.toLocaleString()}`);
+					}
+				}
+				const cacheMissSummary = stats.costBreakdown
+					? computeCacheMissCostSummary(stats.tokens, {
+							kind: "persisted-aggregate",
+							costBreakdown: stats.costBreakdown,
+						})
+					: undefined;
+				if (cacheMissSummary) {
+					lines.push("", "Cache Miss Cost", ...formatCacheMissSummaryLines(cacheMissSummary));
+				}
+				await runtime.output(lines.join("\n"));
 				return commandConsumed();
 			}
 			if (command.args === "delete") {

package/src/task/executor.ts

@@ -47,6 +47,7 @@ import { persistTaskTokenLog, taskTokenLogFromUsage } from "./token-log";
 import {
 	type AgentDefinition,
 	type AgentProgress,
+	hasCompleteUsageCostBreakdown,
 	MAX_OUTPUT_BYTES,
 	MAX_OUTPUT_LINES,
 	type ModelSubstitutionWarning,
@@ -86,8 +87,8 @@ function normalizeModelPatterns(value: string | string[] | undefined): string[]
 		.filter(Boolean);
 }
 
-function renderIrcPeerRoster(selfId: string): string {
-	const peers = AgentRegistry.global()
+function renderIrcPeerRoster(agentRegistry: AgentRegistry, selfId: string): string {
+	const peers = agentRegistry
 		.list()
 		.filter(ref => ref.id !== selfId && (ref.status === "running" || ref.status === "idle"));
 	if (peers.length === 0) return "- (no other live agents)";
@@ -151,6 +152,8 @@ export interface ExecutorOptions {
 	authStorage?: AuthStorage;
 	modelRegistry?: ModelRegistry;
 	settings?: Settings;
+	/** Parent session's registry; shared by child sessions for IRC routing and roster visibility. */
+	agentRegistry?: AgentRegistry;
 	/**
 	 * Live service-tier intent of the parent session (`AgentSession.serviceTier`),
 	 * used as the inherited tier when `task.serviceTier === "inherit"`. Passing the
@@ -705,6 +708,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 				: agent.spawns.join(",");
 
 	const lspEnabled = enableLsp ?? true;
+	const agentRegistry = options.agentRegistry ?? AgentRegistry.global();
 	const ircEnabled = options.ircAvailable === true;
 	const contextFileForPrompt = ircEnabled ? undefined : options.contextFile;
 	const skipPythonPreflight = Array.isArray(toolNames) && !toolNames.includes("eval");
@@ -743,6 +747,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
 	};
 	let hasUsage = false;
+	let usageCostBreakdownComplete = true;
 
 	const requestAbort = (reason: AbortReason) => {
 		if (reason === "timeout") {
@@ -1109,6 +1114,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 						const usageRecord = messageUsage as Record<string, unknown>;
 						const costRecord = (messageUsage as { cost?: Record<string, unknown> }).cost;
 						hasUsage = true;
+						usageCostBreakdownComplete &&= hasCompleteUsageCostBreakdown(usageRecord);
 						accumulatedUsage.input += getNumberField(usageRecord, "input") ?? 0;
 						accumulatedUsage.output += getNumberField(usageRecord, "output") ?? 0;
 						accumulatedUsage.cacheRead += getNumberField(usageRecord, "cacheRead") ?? 0;
@@ -1382,7 +1388,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 							worktree: worktree ?? "",
 							outputSchema: normalizedOutputSchema,
 							contextFile: contextFileForPrompt,
-							ircPeers: ircEnabled ? renderIrcPeerRoster(id) : "",
+							ircPeers: ircEnabled ? renderIrcPeerRoster(agentRegistry, id) : "",
 							ircSelfId: ircEnabled ? id : "",
 							forkContext: forkContextNotice,
 						});
@@ -1411,6 +1417,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 					parentTaskPrefix: id,
 					agentId: id,
 					agentDisplayName: agent.name,
+					agentRosterLabel: options.description,
 					bashAllowedPrefixes: agent.bashAllowedPrefixes,
 					enableLsp: lspEnabled,
 					skipPythonPreflight,
@@ -1418,6 +1425,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 					localProtocolOptions: options.localProtocolOptions,
 					telemetry: subagentTelemetry,
 					forkContextSeed: options.forkContextSeed,
+					agentRegistry,
 					shouldPause: () => pauseRequested,
 				}),
 			);
@@ -1866,6 +1874,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 		abortReason: finalAbortReason,
 		paused,
 		usage: hasUsage ? accumulatedUsage : undefined,
+		usageCostBreakdownComplete: hasUsage && usageCostBreakdownComplete ? true : undefined,
 		outputPath,
 		extractedToolData: progress.extractedToolData,
 		retryFailure: progress.retryFailure,

package/src/task/index.ts

@@ -34,12 +34,14 @@ import {
 	type ForkContextMode,
 	type ForkContextPolicy,
 	getTaskSchema,
+	hasCompleteAggregateUsageCostBreakdown,
 	type SingleResult,
 	type TaskItem,
 	type TaskParams,
 	type TaskToolDetails,
 	type TaskToolSchemaInstance,
 } from "./types";
+
 // Import review tools for side effects (registers subagent tool handlers)
 import "../tools/review";
 import type { LocalProtocolOptions } from "../internal-urls";
@@ -53,6 +55,7 @@ import { getTaskIdValidationError, validateAllocatedTaskId } from "./id";
 import { AgentOutputManager } from "./output-manager";
 import { mapWithConcurrencyLimit, Semaphore } from "./parallel";
 import { assertNoRawTaskFields, buildTaskReceipt, buildTaskRoiSummary } from "./receipt";
+
 import { renderResult, renderCall as renderTaskCall } from "./render";
 import { reconcileSpawnRoi } from "./roi-reconciliation";
 import { getTaskSimpleModeCapabilities, type TaskSimpleMode } from "./simple-mode";
@@ -1316,6 +1319,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 						},
 						authStorage: this.session.authStorage,
 						modelRegistry: this.session.modelRegistry,
+						agentRegistry: this.session.agentRegistry,
 						settings: this.session.settings,
 						inheritedServiceTier: this.session.serviceTier,
 						contextFiles,
@@ -1379,6 +1383,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 						},
 						authStorage: this.session.authStorage,
 						modelRegistry: this.session.modelRegistry,
+						agentRegistry: this.session.agentRegistry,
 						settings: this.session.settings,
 						inheritedServiceTier: this.session.serviceTier,
 						contextFiles,
@@ -1529,6 +1534,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 			// Aggregate usage from executor results (already accumulated incrementally)
 			const aggregatedUsage = createUsageTotals();
 			let hasAggregatedUsage = false;
+
 			for (const result of results) {
 				if (result.usage) {
 					addUsageTotals(aggregatedUsage, result.usage);
@@ -1734,6 +1740,8 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 				results: receipts,
 				totalDurationMs: totalDuration,
 				usage: hasAggregatedUsage ? aggregatedUsage : undefined,
+				usageCostBreakdownComplete:
+					hasAggregatedUsage && hasCompleteAggregateUsageCostBreakdown(results) ? true : undefined,
 				forkContextClonedTokens: forkContextClonedTokens > 0 ? forkContextClonedTokens : undefined,
 				roiSummary,
 				roiReconciliation,

package/src/task/receipt.ts

@@ -1,5 +1,4 @@
-import type { SingleResult, TaskToolDetails } from "./types";
-
+import { hasCompleteUsageCostBreakdown, type SingleResult, type TaskToolDetails } from "./types";
 export interface TaskRoi {
 	tokens: number;
 	contextTokens?: number;
@@ -32,6 +31,7 @@ export interface TaskResultReceipt {
 	modelSubstitutionWarning?: SingleResult["modelSubstitutionWarning"];
 	usage?: SingleResult["usage"];
 	cost?: number;
+	usageCostBreakdownComplete?: true;
 	branchName?: string;
 	retryFailure?: { attempt: number; errorSummary: string };
 	errorSummary?: string;
@@ -246,6 +246,8 @@ export function buildTaskReceipt(raw: SingleResult): TaskResultReceipt {
 		modelSubstitutionWarning: raw.modelSubstitutionWarning,
 		usage: raw.usage,
 		cost: raw.usage?.cost.total,
+		usageCostBreakdownComplete:
+			raw.usageCostBreakdownComplete === true && hasCompleteUsageCostBreakdown(raw.usage) ? true : undefined,
 		branchName: raw.branchName,
 		retryFailure: raw.retryFailure
 			? { attempt: raw.retryFailure.attempt, errorSummary: "Retry failure recorded." }
@@ -274,6 +276,7 @@ export interface RawTaskToolDetails {
 	results: SingleResult[];
 	totalDurationMs: number;
 	usage?: TaskToolDetails["usage"];
+	usageCostBreakdownComplete?: TaskToolDetails["usageCostBreakdownComplete"];
 	async?: TaskToolDetails["async"];
 	forkContextClonedTokens?: number;
 	roiSummary?: TaskToolDetails["roiSummary"];
@@ -286,6 +289,8 @@ export function sanitizeTaskToolDetails(raw: RawTaskToolDetails): TaskToolDetail
 		results: raw.results.map(buildTaskReceipt),
 		totalDurationMs: raw.totalDurationMs,
 		usage: raw.usage,
+		usageCostBreakdownComplete:
+			raw.usageCostBreakdownComplete === true && hasCompleteUsageCostBreakdown(raw.usage) ? true : undefined,
 		forkContextClonedTokens: raw.forkContextClonedTokens,
 		roiSummary: raw.roiSummary ?? buildTaskRoiSummary(raw.results.map(buildTaskReceipt)),
 		async: raw.async,

package/src/task/types.ts

@@ -320,6 +320,8 @@ export interface SingleResult {
 	paused?: boolean;
 	/** Aggregated usage from the subprocess, accumulated incrementally from message_end events. */
 	usage?: Usage;
+	/** True only when every usage-contributing assistant supplied a complete, non-negative raw cost breakdown. */
+	usageCostBreakdownComplete?: true;
 	/** Output path for the task result */
 	outputPath?: string;
 	/** Patch path for isolated worktree output */
@@ -353,6 +355,28 @@ export interface SingleResult {
 	forkContextAdvisory?: { recommendedMode: ForkContextMode; reasons: string[] };
 }
 
+/** True only for complete, factual five-bucket cost accounting. */
+export function hasCompleteUsageCostBreakdown(usage: unknown): boolean {
+	if (!usage || typeof usage !== "object") return false;
+	const cost = (usage as { cost?: unknown }).cost;
+	if (!cost || typeof cost !== "object") return false;
+	return ["input", "output", "cacheRead", "cacheWrite", "total"].every(key => {
+		const value = (cost as Record<string, unknown>)[key];
+		return typeof value === "number" && Number.isFinite(value) && value >= 0;
+	});
+}
+
+/** True only when every usage-contributing result has explicit, complete cost provenance. */
+export function hasCompleteAggregateUsageCostBreakdown(
+	results: readonly Pick<SingleResult, "usage" | "usageCostBreakdownComplete">[],
+): boolean {
+	return results.every(
+		result =>
+			result.usage === undefined ||
+			(result.usageCostBreakdownComplete === true && hasCompleteUsageCostBreakdown(result.usage)),
+	);
+}
+
 /** Tool details for TUI rendering */
 export interface TaskToolDetails {
 	projectAgentsDir: string | null;
@@ -360,6 +384,8 @@ export interface TaskToolDetails {
 	totalDurationMs: number;
 	/** Aggregated usage across all subagents. */
 	usage?: Usage;
+	/** True only when every usage-contributing subagent supplied a complete raw cost breakdown. */
+	usageCostBreakdownComplete?: true;
 	/** Aggregate cloned tokens copied into fork-context seeds across subagents. */
 	forkContextClonedTokens?: number;
 	roiSummary?: {

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

@@ -7,9 +7,12 @@
  * source; registering returns a disposer.
  */
 
+import type { WorkflowGateEmitter } from "../modes/shared/agent-wire/unattended-session";
 import type { AskAnswerSource } from "./index";
 
 const sources = new Map<string, AskAnswerSource>();
+const workflowGateEmitters = new Map<string, WorkflowGateEmitter>();
+const workflowGateListeners = new Map<string, Set<(emitter: WorkflowGateEmitter | undefined) => void>>();
 
 /** Register `source` for `sessionId`. Returns a disposer that clears it. */
 export function registerAskAnswerSource(sessionId: string, source: AskAnswerSource): () => void {
@@ -23,3 +26,25 @@ export function registerAskAnswerSource(sessionId: string, source: AskAnswerSour
 export function getAskAnswerSource(sessionId: string): AskAnswerSource | undefined {
 	return sources.get(sessionId);
 }
+
+/** Publish a session's current workflow-gate emitter after mode initialization. */
+export function notifyWorkflowGateEmitterChanged(sessionId: string, emitter: WorkflowGateEmitter | undefined): void {
+	if (emitter) workflowGateEmitters.set(sessionId, emitter);
+	else workflowGateEmitters.delete(sessionId);
+	for (const listener of workflowGateListeners.get(sessionId) ?? []) listener(emitter);
+}
+
+/** Observe workflow-gate emitter installation even when it occurs after session_start. */
+export function registerWorkflowGateEmitterListener(
+	sessionId: string,
+	listener: (emitter: WorkflowGateEmitter | undefined) => void,
+): () => void {
+	const listeners = workflowGateListeners.get(sessionId) ?? new Set();
+	listeners.add(listener);
+	workflowGateListeners.set(sessionId, listeners);
+	listener(workflowGateEmitters.get(sessionId));
+	return () => {
+		listeners.delete(listener);
+		if (listeners.size === 0) workflowGateListeners.delete(sessionId);
+	};
+}

package/src/tools/browser/tab-supervisor.ts

@@ -89,11 +89,57 @@ export interface RunInTabOptions {
 
 export interface ReleaseTabOptions {
 	kill?: boolean;
+	/**
+	 * Absolute end-to-end deadline (`Date.now()`-based, ms) for the whole teardown chain.
+	 * Shared across a `releaseAllTabs` loop so close/close-all honors ONE aggregate budget.
+	 * Omitted (the GC/session-teardown callers) keeps the original unbounded behavior.
+	 */
+	deadlineAt?: number;
 }
 
 const tabs = new Map<string, TabSession>();
 const GRACE_MS = 750;
 
+/**
+ * Remaining time (ms) until an absolute teardown deadline, or +Infinity when no deadline
+ * is set (the GC / session-teardown callers). A non-positive result means the shared
+ * close budget is already spent.
+ */
+function remainingBudget(deadlineAt: number | undefined): number {
+	if (deadlineAt === undefined) return Number.POSITIVE_INFINITY;
+	return deadlineAt - Date.now();
+}
+
+/**
+ * Await `op` but never longer than `remainingMs` (#2027). On timeout — or when the budget
+ * is already exhausted — the operation is detached and kept alive best-effort with its
+ * rejection swallowed, so a dying CDP target cannot wedge the close teardown or leak an
+ * unhandled rejection. Returns true when `op` settled within budget, false when detached.
+ */
+async function awaitWithinBudget(op: Promise<unknown>, remainingMs: number, label: string): Promise<boolean> {
+	const settled = Promise.resolve(op).then(
+		() => true,
+		() => true,
+	);
+	if (remainingMs === Number.POSITIVE_INFINITY) return await settled;
+	if (remainingMs <= 0) {
+		void settled;
+		logger.debug("close teardown budget already spent; detaching step", { label });
+		return false;
+	}
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	const timedOut = new Promise<boolean>(resolve => {
+		timer = setTimeout(() => resolve(false), remainingMs);
+	});
+	try {
+		const ok = await Promise.race([settled, timedOut]);
+		if (!ok) logger.debug("close teardown step exceeded deadline; detached", { label });
+		return ok;
+	} finally {
+		if (timer) clearTimeout(timer);
+	}
+}
+
 export function getTab(name: string): TabSession | undefined {
 	return tabs.get(name);
 }
@@ -316,17 +362,24 @@ export async function releaseTab(name: string, opts: ReleaseTabOptions = {}): Pr
 	}
 	tab.pending.clear();
 	let forced = false;
+	const deadlineAt = opts.deadlineAt;
 	if (wasAlive) {
 		try {
 			tab.worker.send({ type: "close" });
-			await waitForClosed(tab);
+			await waitForClosed(tab, remainingBudget(deadlineAt));
 		} catch {
 			forced = true;
 		}
 	}
-	await tab.worker.terminate().catch(() => undefined);
-	if (forced && tab.kindTag === "headless") await closeOrphanTarget(tab);
-	await releaseBrowser(tab.browser, { kill: opts.kill ?? false });
+	await awaitWithinBudget(tab.worker.terminate(), remainingBudget(deadlineAt), "worker.terminate");
+	if (forced && tab.kindTag === "headless") {
+		await awaitWithinBudget(closeOrphanTarget(tab), remainingBudget(deadlineAt), "closeOrphanTarget");
+	}
+	await awaitWithinBudget(
+		releaseBrowser(tab.browser, { kill: opts.kill ?? false }),
+		remainingBudget(deadlineAt),
+		"releaseBrowser",
+	);
 	// Only delete if the map still holds THIS tab: a same-name reacquire during our async
 	// teardown may have installed a fresh tab that we must not evict.
 	if (tabs.get(name) === tab) tabs.delete(name);
@@ -495,13 +548,17 @@ async function closeOrphanTarget(tab: TabSession): Promise<void> {
 	}
 }
 
-async function waitForClosed(tab: TabSession): Promise<void> {
+async function waitForClosed(tab: TabSession, remainingMs: number = Number.POSITIVE_INFINITY): Promise<void> {
 	const { promise, resolve } = Promise.withResolvers<void>();
 	const unsubscribe = tab.worker.onMessage(msg => {
 		if (msg.type === "closed") resolve();
 	});
 	try {
-		await raceWithTimeout(promise, GRACE_MS, "Timed out closing browser tab worker");
+		await raceWithTimeout(
+			promise,
+			Math.max(0, Math.min(GRACE_MS, remainingMs)),
+			"Timed out closing browser tab worker",
+		);
 	} finally {
 		unsubscribe();
 	}

package/src/tools/browser.ts

@@ -187,7 +187,7 @@ export class BrowserTool implements AgentTool<typeof browserSchema, BrowserToolD
 				case "open":
 					return await this.#open(name, params, details, timeoutMs, signal);
 				case "close":
-					return await this.#close(name, params, details, signal);
+					return await this.#close(name, params, details, timeoutMs, signal);
 				case "run":
 					return await this.#run(name, params, details, timeoutMs, signal);
 				case "act":
@@ -274,15 +274,20 @@ export class BrowserTool implements AgentTool<typeof browserSchema, BrowserToolD
 		name: string,
 		params: BrowserParams,
 		details: BrowserToolDetails,
+		timeoutMs: number,
 		signal?: AbortSignal,
 	): Promise<AgentToolResult<BrowserToolDetails>> {
 		const kill = !!params.kill;
+		// One end-to-end budget across the whole close/close-all teardown chain (#2027):
+		// releaseAllTabs → waitForClosed → worker.terminate → releaseBrowser stay bounded so
+		// a CDP target dying mid-teardown cannot hang the tool call or the agent turn.
+		const deadlineAt = Date.now() + timeoutMs;
 		if (params.all) {
-			const count = await untilAborted(signal, () => releaseAllTabs({ kill }));
+			const count = await untilAborted(signal, () => releaseAllTabs({ kill, deadlineAt }));
 			details.result = `Closed ${count} tab(s)`;
 			return toolResult(details).text(details.result).done();
 		}
-		const closed = await untilAborted(signal, () => releaseTab(name, { kill }));
+		const closed = await untilAborted(signal, () => releaseTab(name, { kill, deadlineAt }));
 		details.result = closed ? `Closed tab ${JSON.stringify(name)}` : `No tab named ${JSON.stringify(name)}`;
 		return toolResult(details).text(details.result).done();
 	}