@selesai/code 0.13.40 → 0.14.3

package/dist/extensions/pi-subagents/src/watchdog/runtime.ts

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import type { ExtensionContext } from "@selesai/code";
+import type { ExtensionContext, InputEvent } from "@selesai/code";
 import { computeWatchdogRepoChangeSignature, eventIndicatesRepoEdit, type WatchdogRepoChangeSignature } from "./change-signature.ts";
 import { WatchdogEmissionGuard } from "./emission-guard.ts";
 import {
@@ -12,8 +12,9 @@ import {
 import { ruleViolationWarning, type WatchdogRuleViolation } from "./rules.ts";
 import { WatchdogScopeArtifact } from "./scope.ts";
 import { resolveWatchdogConfig } from "./settings.ts";
-import { formatWatchdogTurnDelta } from "./turn-delta.ts";
+import { formatWatchdogOrchestrationActivity, formatWatchdogTurnDelta } from "./turn-delta.ts";
 import {
+	WATCHDOG_WARNING_IMPORTANCES,
 	type ResolvedWatchdogConfig,
 	type WatchdogEndpointConfig,
 	type WatchdogLspRuntimeSnapshot,
@@ -31,6 +32,9 @@ type ReviewStopReason = "stop" | "error" | "aborted" | "length";
 export interface WatchdogReviewResult {
 	warnings?: WatchdogWarning[];
 	stopReason?: ReviewStopReason;
+	/** Provider error text for a failed review, surfaced in status `Last error`. */
+	errorMessage?: string;
+	clarification?: { question: string; evidence: string };
 }
 
 export interface WatchdogReviewRequest {
@@ -40,6 +44,7 @@ export interface WatchdogReviewRequest {
 	reviewId: number;
 	config: ResolvedWatchdogConfig;
 	emitWarning(warning: WatchdogWarning): boolean;
+	allowClarification?: boolean;
 	signal?: AbortSignal;
 }
 
@@ -81,6 +86,9 @@ interface MainWatchdogRuntimeOptions {
 	review?: WatchdogReviewFunction;
 	reviewDescription?: string;
 	displayWarning?: (warning: WatchdogWarningDetails, options?: WatchdogWarningSendOptions) => void;
+	displayUserWarning?: (warning: WatchdogWarningDetails) => void;
+	/** Supplying this main-session delivery capability gates clarification (children omit it). */
+	displayClarification?: (content: string) => void;
 	reviewChangesOnly?: boolean;
 	lspDiagnostics?: WatchdogLspDiagnosticsFunction;
 	repoChangeSignature?: typeof computeWatchdogRepoChangeSignature;
@@ -88,8 +96,8 @@ interface MainWatchdogRuntimeOptions {
 
 export type WatchdogWarningSendOptions = { deliverAs: "steer" } | { triggerTurn: false };
 
-type ContextLike = Pick<ExtensionContext, "cwd">;
-type ReviewDeltaOutcome = "completed" | "timeout" | "stale";
+type ContextLike = Pick<ExtensionContext, "cwd"> & { signal?: AbortSignal };
+type ReviewDeltaOutcome = "completed" | "timeout" | "stale" | NonNullable<WatchdogReviewResult["clarification"]>;
 
 const DEFAULT_REVIEW: WatchdogReviewFunction = () => ({ warnings: [] });
 const MAX_REVIEW_INPUT_CHARS = 24_000;
@@ -126,6 +134,7 @@ export class MainWatchdogRuntime {
 	private readonly reviewConnected: boolean;
 	private readonly reviewDescription: string;
 	private readonly displayWarning: ((warning: WatchdogWarningDetails, options?: WatchdogWarningSendOptions) => void) | undefined;
+	private readonly displayUserWarning: ((warning: WatchdogWarningDetails) => void) | undefined;
 	private readonly reviewChangesOnly: boolean;
 	private readonly lspDiagnostics: WatchdogLspDiagnosticsFunction;
 	private readonly repoChangeSignature: typeof computeWatchdogRepoChangeSignature;
@@ -170,6 +179,11 @@ export class MainWatchdogRuntime {
 	private activeReviewAbortController: AbortController | undefined;
 	private failedReviews = 0;
 	private staleReviews = 0;
+	private readonly displayClarification: MainWatchdogRuntimeOptions["displayClarification"];
+	private askedThisPrompt = false;
+	private activityTail = "";
+	private activityPending = false;
+	private activityReviewUsed = false;
 
 	constructor(options: MainWatchdogRuntimeOptions = {}) {
 		this.cwd = options.cwd ?? process.cwd();
@@ -178,6 +192,8 @@ export class MainWatchdogRuntime {
 		this.reviewConnected = Boolean(options.review);
 		this.reviewDescription = options.reviewDescription ?? (options.review ? "injected seam" : "not wired");
 		this.displayWarning = options.displayWarning;
+		this.displayUserWarning = options.displayUserWarning;
+		this.displayClarification = options.displayClarification;
 		this.reviewChangesOnly = options.reviewChangesOnly === true;
 		this.lspDiagnostics = options.lspDiagnostics ?? collectWatchdogLspDiagnostics;
 		this.repoChangeSignature = options.repoChangeSignature ?? computeWatchdogRepoChangeSignature;
@@ -200,6 +216,8 @@ export class MainWatchdogRuntime {
 	refreshConfig(cwd = this.cwd): WatchdogSettingsResult {
 		this.cwd = cwd;
 		const wasEnabled = this.isEnabled();
+		const hadClarification = this.configResult.config.clarification;
+		const previousMain = this.configResult.config.main;
 		const session = this.sessionOverrideEnabled === undefined && this.sessionModelOverride === undefined
 			? undefined
 			: {
@@ -215,6 +233,10 @@ export class MainWatchdogRuntime {
 			this.guard = new WatchdogEmissionGuard({ maxWarnings: this.guardMaxWarnings });
 		}
 		if (wasEnabled && !this.isEnabled()) this.invalidateActiveReview("watchdog disabled");
+		if (!this.isEnabled() || !this.configResult.config.clarification) this.clearActivity();
+		if (this.displayClarification && (hadClarification || this.configResult.config.clarification) && (this.reviewing || this.waitingAtAgentEnd)) {
+			if (!this.configResult.config.clarification || previousMain.model !== this.configResult.config.main.model || previousMain.thinking !== this.configResult.config.main.thinking) this.invalidateActiveReview("clarification configuration changed");
+		}
 		return this.configResult;
 	}
 
@@ -252,7 +274,8 @@ export class MainWatchdogRuntime {
 		return this.getSnapshot();
 	}
 
-	reset(_reason = "reset", options: { clearReviewInputSignature?: boolean; resetChangeSignature?: boolean; clearLspLedger?: boolean; clearScope?: boolean } = {}): void {
+	reset(_reason = "reset", options: { clearReviewInputSignature?: boolean; resetChangeSignature?: boolean; clearLspLedger?: boolean; clearScope?: boolean; clearActivity?: boolean } = {}): void {
+		this.activeReviewAbortController?.abort();
 		this.abortActiveAgentEnd();
 		this.epoch++;
 		this.status = "idle";
@@ -274,6 +297,7 @@ export class MainWatchdogRuntime {
 			this.lastLspSnapshot = undefined;
 		}
 		if (options.clearScope) this.scope.reset();
+		if (options.clearScope || options.clearActivity) this.clearActivity();
 		if (options.clearReviewInputSignature) this.lastReviewInputSignature = undefined;
 		if (options.resetChangeSignature) this.resetRepoChangeBaseline({ reviewed: true });
 		this.guard.reset();
@@ -281,6 +305,8 @@ export class MainWatchdogRuntime {
 	}
 
 	dispose(): void {
+		this.clearActivity();
+		this.activeReviewAbortController?.abort();
 		this.disposed = true;
 		this.abortActiveAgentEnd();
 		this.epoch++;
@@ -305,6 +331,8 @@ export class MainWatchdogRuntime {
 		if (this.disposed) return;
 		const incomingPrompt = promptFromBeforeAgentStart(event);
 		this.reset("before_agent_start");
+		this.askedThisPrompt = false;
+		this.activityReviewUsed = false;
 		this.resetBoundaryRepeats();
 		this.refreshConfig(ctx.cwd);
 		this.userPrompt = incomingPrompt;
@@ -317,16 +345,24 @@ export class MainWatchdogRuntime {
 		this.resetRepoChangeBaseline();
 	}
 
-	handleTurnEnd(event: unknown, ctx: ContextLike): void {
+	handleTurnEnd(event: unknown, ctx: ContextLike, structuredTerminal = false): void {
 		if (this.disposed) return;
 		this.refreshConfig(ctx.cwd);
 		if (!this.isEnabled()) return;
 		try {
+			if (this.displayClarification && this.configResult.config.clarification && this.boundaryRepeats === 0) {
+				const activity = formatWatchdogOrchestrationActivity(event);
+				if (activity) {
+					this.activityTail = [this.activityTail, boundWatchdogReviewText(activity, 3_000)].filter(Boolean).join(REVIEW_DELTA_SEPARATOR).slice(-6_000);
+					this.activityPending = true;
+				}
+			}
 			this.observedRepoEditThisTurn ||= eventIndicatesRepoEdit(event);
 			const delta = formatWatchdogTurnDelta({
 				includeUserPrompt: this.includeUserPromptInNextDelta,
 				userPrompt: this.userPrompt,
 				events: [event],
+				structuredTerminal,
 			});
 			this.includeUserPromptInNextDelta = false;
 			this.enqueueDelta(delta);
@@ -359,20 +395,19 @@ export class MainWatchdogRuntime {
 		if (this.disposed) return;
 		this.refreshConfig(ctx.cwd);
 		if (!this.isEnabled()) return;
-		const changeSignature = this.resolveReviewChangeSignature(ctx.cwd);
-		if (this.reviewChangesOnly && !changeSignature) {
-			this.clearPendingDeltas();
-			if (this.status === "queued") this.status = "idle";
-			this.resolveWaiters(true);
-			return;
-		}
-		if (changeSignature && changeSignature.key === this.lastReviewedChangeSignature) {
+		if (ctx.signal?.aborted) return;
+		const changeSignature = this.resolveReviewChangeSignature(this.currentRepoChangeSignature(ctx.cwd), ctx.cwd);
+		const activityReview = Boolean(this.displayClarification && this.configResult.config.clarification && !this.activityReviewUsed && this.boundaryRepeats === 0 && this.activityPending);
+		const knownEvidence = changeSignature && changeSignature.key === this.lastReviewedChangeSignature;
+		if (!activityReview && (knownEvidence || (this.reviewChangesOnly && !changeSignature))) {
 			this.clearPendingDeltas();
-			this.status = "idle";
+			if (knownEvidence || this.status === "queued") this.status = "idle";
 			this.resolveWaiters(true);
 			return;
 		}
 		this.cancelMidRunReview();
+		if (activityReview && (!changeSignature || knownEvidence)) this.activityReviewUsed = true;
+		this.activityPending = false;
 		this.waitingAtAgentEnd = true;
 		const agentEndEpoch = this.epoch;
 		const agentEndId = ++this.agentEndIdCounter;
@@ -403,7 +438,8 @@ export class MainWatchdogRuntime {
 				this.resolveWaiters(true);
 				return;
 			}
-			const outcome = await this.reviewDelta(delta, this.configResult.config.agentEndTimeoutMs);
+			const outcome = await this.reviewDelta(delta, this.configResult.config.agentEndTimeoutMs, { allowClarification: true });
+			if (!this.isAgentEndCurrent(agentEndEpoch, agentEndId)) return;
 			this.waitingAtAgentEnd = false;
 			if (outcome === "timeout") {
 				this.staleReviews++;
@@ -413,11 +449,16 @@ export class MainWatchdogRuntime {
 				this.resolveWaiters(true);
 				return;
 			}
-			if (outcome === "completed" && this.status !== "failed" && this.status !== "stale") {
+			if ((outcome === "completed" || typeof outcome === "object") && this.status !== "failed" && this.status !== "stale") {
+				// A question consumes this evidence just like a completed review, not a pending exchange.
 				this.lastReviewInputSignature = signature;
 				if (changeSignature) this.lastReviewedChangeSignature = changeSignature.key;
 				this.currentChangedPaths = changeSignature?.changedPaths;
 				this.status = "idle";
+				if (typeof outcome === "object" && !ctx.signal?.aborted) this.displayClarification?.([
+					"Main watchdog clarification:", outcome.question, `Evidence: ${outcome.evidence}`,
+					"Consider this missing context as you continue the task. This is not approval, permission, or a warning. The reviewer has yielded; no reply or follow-up review is required.",
+				].join("\n"));
 			}
 			this.resolveWaiters(true);
 		} finally {
@@ -431,13 +472,13 @@ export class MainWatchdogRuntime {
 		this.ruleWarningsThisRun.add(violation.summary);
 		const details = normalizeWatchdogWarningDetails(ruleViolationWarning(violation), { state: "displayed", displayedAt: new Date().toISOString() });
 		this.lastWarning = details;
-		this.displayWarning?.(details, { deliverAs: "steer" });
+		this.routeWarning(details, { deliverAs: "steer" });
 	}
 
-	recordDisplayedWarning(warning: WatchdogWarning): WatchdogWarningDetails {
+	displayRecordedWarning(warning: WatchdogWarning): void {
 		const details = normalizeWatchdogWarningDetails(warning, { state: "displayed", source: warning.source ?? "main" });
 		this.lastWarning = details;
-		return details;
+		this.routeWarning(details);
 	}
 
 	getSnapshot(cwd?: string): WatchdogRuntimeSnapshot {
@@ -468,6 +509,17 @@ export class MainWatchdogRuntime {
 		};
 	}
 
+	/** A real user input sent while the agent streams reaches the loop without before_agent_start, so record it in scope here. */
+	handleUserInput(event: Pick<InputEvent, "text" | "source" | "streamingBehavior">): void {
+		if (this.disposed || event.source === "extension") return;
+		if (this.displayClarification && this.configResult.config.clarification && (this.reviewing || this.waitingAtAgentEnd)) this.reset("new user input");
+		if (event.streamingBehavior) this.scope.addPrompt(event.text);
+	}
+
+	handleModelChange(): void {
+		if (this.displayClarification && this.configResult.config.clarification && (this.reviewing || this.waitingAtAgentEnd)) this.reset("model changed");
+	}
+
 	async waitForIdle(timeoutMs = 1_000): Promise<boolean> {
 		return this.waitForSettled(timeoutMs);
 	}
@@ -491,7 +543,13 @@ export class MainWatchdogRuntime {
 	}
 
 	private warningMeetsThreshold(warning: WatchdogWarning): boolean {
-		return this.configResult.config.severityThreshold === "concern" || warning.severity === "blocker";
+		return (WATCHDOG_WARNING_IMPORTANCES as readonly string[]).includes(warning.importance)
+			&& (this.configResult.config.severityThreshold === "concern" || warning.severity === "blocker");
+	}
+
+	private routeWarning(details: WatchdogWarningDetails, options?: WatchdogWarningSendOptions): void {
+		if (details.importance === "high") this.displayWarning?.(details, options);
+		else this.displayUserWarning?.(details);
 	}
 
 	private acceptWarning(epoch: number, reviewId: number, warning: WatchdogWarning): boolean {
@@ -523,6 +581,7 @@ export class MainWatchdogRuntime {
 	}
 
 	private invalidateActiveReview(_reason: string): void {
+		this.activeReviewAbortController?.abort();
 		this.abortActiveAgentEnd();
 		this.epoch++;
 		this.status = "idle";
@@ -567,7 +626,7 @@ export class MainWatchdogRuntime {
 		this.activeReviewWarning = undefined;
 	}
 
-	private async reviewDelta(delta: string, timeoutMs: number, options: { correction?: boolean } = {}): Promise<ReviewDeltaOutcome> {
+	private async reviewDelta(delta: string, timeoutMs: number, options: { correction?: boolean; allowClarification?: boolean } = {}): Promise<ReviewDeltaOutcome> {
 		if (this.reviewing || this.disposed) return "stale";
 		this.reviewing = true;
 		const reviewEpoch = this.epoch;
@@ -578,6 +637,7 @@ export class MainWatchdogRuntime {
 		let timeout: ReturnType<typeof setTimeout> | undefined;
 		const abortController = new AbortController();
 		this.activeReviewAbortController = abortController;
+		const allowClarification = Boolean(options.allowClarification && this.displayClarification && this.configResult.config.clarification && !this.askedThisPrompt && !this.stalemate);
 		const reviewPromise = Promise.resolve().then(() => this.review({
 			delta,
 			epoch: reviewEpoch,
@@ -586,6 +646,7 @@ export class MainWatchdogRuntime {
 			hasScope: this.scopeBlock().trim().length > 0,
 			signal: abortController.signal,
 			emitWarning: (warning) => this.acceptWarning(reviewEpoch, reviewId, warning),
+			...(allowClarification ? { allowClarification: true } : {}),
 		}));
 		try {
 			const result = await Promise.race([
@@ -600,9 +661,18 @@ export class MainWatchdogRuntime {
 			}
 			if (!this.isCurrent(reviewEpoch, reviewId)) return "stale";
 			if (!result) return "stale";
+			if (allowClarification && this.configResult.config.clarification && result.clarification && (!result.stopReason || result.stopReason === "stop") && !this.activeReviewWarning && !result.warnings?.length && !abortController.signal.aborted) {
+				const question = result.clarification.question.trim();
+				const evidence = result.clarification.evidence.trim();
+				if (question && evidence) {
+					this.askedThisPrompt = true;
+					return { question: boundWatchdogReviewText(question, 1_000), evidence: boundWatchdogReviewText(evidence, 2_000) };
+				}
+			}
 			for (const warning of result.warnings ?? []) this.acceptWarning(reviewEpoch, reviewId, warning);
 			if (result.stopReason && result.stopReason !== "stop") {
-				this.fail(`Watchdog review ended with stop reason '${result.stopReason}'.`);
+				const detail = result.errorMessage?.trim() ? ` ${boundWatchdogReviewText(result.errorMessage.trim(), 600)}` : "";
+				this.fail(`Watchdog review ended with stop reason '${result.stopReason}'.${detail}`);
 				return "completed";
 			}
 			this.displayAcceptedReviewWarning(options.correction);
@@ -634,7 +704,7 @@ export class MainWatchdogRuntime {
 		};
 		if (correction) {
 			this.lastWarning = details;
-			this.displayWarning?.(details, { deliverAs: "steer" });
+			this.routeWarning(details, { deliverAs: "steer" });
 			return;
 		}
 		this.deliverBoundaryWarning(details);
@@ -655,7 +725,7 @@ export class MainWatchdogRuntime {
 			: details;
 		this.stalemate = stalemate;
 		this.lastWarning = delivered;
-		this.displayWarning?.(delivered, stalemate ? { triggerTurn: false } : undefined);
+		this.routeWarning(delivered, stalemate ? { triggerTurn: false } : undefined);
 	}
 
 	// The previous boundary finding is a repeat to count, not a duplicate, until stalemate.
@@ -681,9 +751,8 @@ export class MainWatchdogRuntime {
 		this.observedRepoEditThisTurn = false;
 	}
 
-	private resolveReviewChangeSignature(cwd = this.cwd): WatchdogRepoChangeSignature | undefined {
+	private resolveReviewChangeSignature(current: WatchdogRepoChangeSignature | undefined, cwd: string): WatchdogRepoChangeSignature | undefined {
 		if (!this.reviewChangesOnly) return undefined;
-		const current = this.currentRepoChangeSignature(cwd);
 		if (current) {
 			this.currentChangedPaths = current.changedPaths;
 			if (current.key === this.turnStartChangeSignature?.key) return undefined;
@@ -783,15 +852,16 @@ export class MainWatchdogRuntime {
 		const input = this.pendingDeltas.join(REVIEW_DELTA_SEPARATOR);
 		const scopeBlock = this.scopeBlock();
 		const changes = changeSignature?.changedPaths.length
-			? ["Changed repo paths:", ...changeSignature.changedPaths.slice(0, 200).map((file) => `- ${file}`)].join("\n")
+			? ["Changed repo paths: every dirty path in the working tree. Authorship is not verified; a path may predate this session or come from another session.", ...changeSignature.changedPaths.slice(0, 200).map((file) => `- ${file}`)].join("\n")
 			: "";
-		const contextPieces = [scopeBlock, changes, lspBlock].filter(Boolean);
+		const activity = this.activityTail ? `Recent delivered orchestration activity (oldest first; bounded observations, not a task board; waits/holds are not evidence of neglect):\n${this.activityTail}` : "";
+		const contextPieces = [scopeBlock, changes, lspBlock, activity].filter(Boolean);
 		if (!contextPieces.length) return boundWatchdogReviewText(input);
 
 		const maxContextLength = Math.floor(MAX_REVIEW_INPUT_CHARS / 2);
 		const maxPieceLength = Math.max(1_000, Math.floor(maxContextLength / contextPieces.length));
 		const boundedContext = contextPieces.map((piece) => piece.length > maxPieceLength
-			? `${piece.slice(0, maxPieceLength - 6)}\n- ...`
+			? piece === activity ? boundWatchdogReviewText(piece, maxPieceLength) : `${piece.slice(0, maxPieceLength - 6)}\n- ...`
 			: piece).join(REVIEW_DELTA_SEPARATOR);
 		const separatorLength = input ? REVIEW_DELTA_SEPARATOR.length : 0;
 		const inputBudget = MAX_REVIEW_INPUT_CHARS - boundedContext.length - separatorLength;
@@ -808,6 +878,12 @@ export class MainWatchdogRuntime {
 		this.pendingDeltaChars = 0;
 	}
 
+	private clearActivity(): void {
+		if (!this.activityTail) return;
+		this.activityTail = "";
+		this.activityPending = false;
+	}
+
 	private fail(message: string): void {
 		this.failedReviews++;
 		this.lastError = message;
@@ -848,4 +924,4 @@ export class MainWatchdogRuntime {
 			waiter.resolve(settled);
 		}
 	}
-}
+}

package/dist/extensions/pi-subagents/src/watchdog/scope.ts

@@ -34,7 +34,7 @@ export class WatchdogScopeArtifact {
 		if (!this.entries.length) return "";
 		return [
 			"Current scope:",
-			"The following real user prompts are the current scope record, newest last. Newer prompts supersede and mutate older prompts: they may add, modify, or remove requirements. Flag work that serves no current scope item as category 'scope-drift'.",
+			"The following real user prompts are the current scope record, newest last. Side questions are additive, not scope drift or cancellation of older objectives; only explicit changes supersede requirements. Use watchdog_warn for evidence-backed reminders of forgotten authorized work, not dependencies still pending or explicit holds. The orchestrator owns task tracking. Flag unauthorized work as category 'scope-drift'.",
 			...this.entries.map((entry, index) => [
 				`Scope prompt ${index + 1} (${entry.createdAt}):`,
 				entry.prompt,

package/dist/extensions/pi-subagents/src/watchdog/settings.ts

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { THINKING_LEVELS, type ThinkingLevel } from "../shared/model-info.ts";
 import { getAgentDir, getProjectConfigDir } from "../shared/utils.ts";
+import { withSettingsFileLease } from "../shared/settings-file-lease.ts";
 import {
 	WATCHDOG_WARNING_SEVERITIES,
 	type ResolvedWatchdogConfig,
@@ -61,6 +62,7 @@ interface ParseMeta {
 
 export const DEFAULT_WATCHDOG_CONFIG: ResolvedWatchdogConfig = {
 	enabled: false,
+	clarification: false,
 	agentEndTimeoutMs: 30_000,
 	severityThreshold: "concern",
 	maxWarnings: null,
@@ -92,6 +94,7 @@ export const DEFAULT_WATCHDOG_CONFIG: ResolvedWatchdogConfig = {
 
 const WATCHDOG_FIELDS = new Set([
 	"enabled",
+	"clarification",
 	"agentEndTimeoutMs",
 	"severityThreshold",
 	"maxWarnings",
@@ -303,6 +306,7 @@ function parseWatchdogPatch(value: unknown, field: string, meta: ParseMeta): Wat
 	assertKnownFields(input, WATCHDOG_FIELDS, field, meta);
 	const patch: WatchdogConfigPatch = {};
 	if ("enabled" in input) patch.enabled = parseBoolean(input.enabled, `${field}.enabled`, meta);
+	if ("clarification" in input) patch.clarification = parseBoolean(input.clarification, `${field}.clarification`, meta);
 	if ("agentEndTimeoutMs" in input) {
 		patch.agentEndTimeoutMs = parseInteger(input.agentEndTimeoutMs, `${field}.agentEndTimeoutMs`, meta, "a positive integer", (candidate) => candidate >= 1);
 	}
@@ -458,24 +462,28 @@ function writeSettingsFile(settingsPath: string, settings: Record<string, unknow
 export function writeUserWatchdogEnabled(enabled: boolean): string {
 	const settingsPath = getUserSettingsPath();
 	const meta: ParseMeta = { scope: "user", path: settingsPath };
-	const settings = readSettingsFileStrict(settingsPath);
-	const watchdog = ensureWatchdogSettings(settings, meta);
-	watchdog.enabled = enabled;
-	targetSettingsObject(watchdog, { kind: "main" }, meta).enabled = enabled;
-	return writeSettingsFile(settingsPath, settings);
+	return withSettingsFileLease(settingsPath, () => {
+		const settings = readSettingsFileStrict(settingsPath);
+		const watchdog = ensureWatchdogSettings(settings, meta);
+		watchdog.enabled = enabled;
+		targetSettingsObject(watchdog, { kind: "main" }, meta).enabled = enabled;
+		return writeSettingsFile(settingsPath, settings);
+	});
 }
 
 export function writeWatchdogModelSettings(input: WatchdogModelSettingsWrite): string {
 	const settingsPath = settingsPathForWrite(input.scope, input.cwd);
 	const meta: ParseMeta = { scope: input.scope, path: settingsPath };
-	const settings = readSettingsFileStrict(settingsPath);
-	const watchdog = ensureWatchdogSettings(settings, meta);
-	const target = targetSettingsObject(watchdog, input.target, meta);
-	if (input.model === null) delete target.model;
-	else if (input.model !== undefined) target.model = input.model;
-	if (input.thinking === null) delete target.thinking;
-	else if (input.thinking !== undefined) target.thinking = input.thinking;
-	return writeSettingsFile(settingsPath, settings);
+	return withSettingsFileLease(settingsPath, () => {
+		const settings = readSettingsFileStrict(settingsPath);
+		const watchdog = ensureWatchdogSettings(settings, meta);
+		const target = targetSettingsObject(watchdog, input.target, meta);
+		if (input.model === null) delete target.model;
+		else if (input.model !== undefined) target.model = input.model;
+		if (input.thinking === null) delete target.thinking;
+		else if (input.thinking !== undefined) target.thinking = input.thinking;
+		return writeSettingsFile(settingsPath, settings);
+	});
 }
 
 export function resolveWatchdogConfig(cwd: string, options: { session?: Record<string, unknown> } = {}): WatchdogSettingsResult {
@@ -509,4 +517,4 @@ export function resolveWatchdogConfig(cwd: string, options: { session?: Record<s
 		errors,
 		sources,
 	};
-}
+}

package/dist/extensions/pi-subagents/src/watchdog/tool-actions.ts

@@ -4,8 +4,8 @@ import { THINKING_LEVELS, type ThinkingLevel } from "../shared/model-info.ts";
 import type { Details } from "../shared/types.ts";
 import { buildWatchdogStatus } from "./register-main.ts";
 import type { MainWatchdogRuntime } from "./runtime.ts";
-import { parseWatchdogThinkingInput, recommendStrongWatchdogModel, resolveWatchdogModelInput } from "./model-selection.ts";
-import { writeWatchdogModelSettings, type WatchdogModelSettingsTarget, type WatchdogSettingsWriteScope } from "./settings.ts";
+import { formatWatchdogRecommendation, parseWatchdogThinkingInput, recommendStrongWatchdogModel, recommendWatchdogModel, resolveWatchdogModelInput } from "./model-selection.ts";
+import { resolveWatchdogConfig, writeWatchdogModelSettings, type WatchdogModelSettingsTarget, type WatchdogSettingsWriteScope } from "./settings.ts";
 
 interface WatchdogToolParams {
 	action?: string;
@@ -52,7 +52,7 @@ function parseThinking(raw: string | false | undefined): ThinkingLevel | false |
 	return parseWatchdogThinkingInput(raw, "watchdog.configure thinking") ?? undefined;
 }
 
-function resolveConfiguredValue(ctx: ExtensionContext, params: WatchdogToolParams): { model?: string | null; thinking?: ThinkingLevel | false | null; description: string } {
+function resolveConfiguredValue(ctx: ExtensionContext, params: WatchdogToolParams, runtime?: MainWatchdogRuntime): { model?: string | null; thinking?: ThinkingLevel | false | null; description: string } {
 	const thinking = parseThinking(params.thinking);
 	const rawModel = params.model?.trim();
 	if (!rawModel) {
@@ -61,7 +61,9 @@ function resolveConfiguredValue(ctx: ExtensionContext, params: WatchdogToolParam
 	}
 	if (rawModel === "inherit") return { model: null, thinking: thinking ?? null, description: "inherit" };
 	if (rawModel === "recommended") {
-		const recommendation = recommendStrongWatchdogModel(ctx);
+		const recommendation = (params.target ?? "main") === "main"
+			? recommendWatchdogModel(ctx, (runtime?.getSnapshot(ctx.cwd).config ?? resolveWatchdogConfig(ctx.cwd).config).main)
+			: recommendStrongWatchdogModel(ctx);
 		return {
 			model: recommendation.model,
 			thinking: recommendation.thinking,
@@ -76,11 +78,11 @@ function resolveConfiguredValue(ctx: ExtensionContext, params: WatchdogToolParam
 	};
 }
 
-function buildRecommendationText(ctx: ExtensionContext): string {
-	const recommendation = recommendStrongWatchdogModel(ctx);
+function buildRecommendationText(ctx: ExtensionContext, runtime?: MainWatchdogRuntime): string {
+	const recommendation = recommendWatchdogModel(ctx, (runtime?.getSnapshot(ctx.cwd).config ?? resolveWatchdogConfig(ctx.cwd).config).main);
 	return [
 		"Subagent watchdog recommended model",
-		`Recommended: ${recommendation.model}:${recommendation.thinking}`,
+		recommendation.source === "configured" ? formatWatchdogRecommendation(recommendation) : `Recommended: ${recommendation.model}:${recommendation.thinking}`,
 		`Reason: ${recommendation.reason}`,
 		"Apply temporarily with subagent({ action: \"watchdog.configure\", scope: \"session\", model: \"recommended\" }).",
 		"Persist with scope: \"project\" or scope: \"user\" only when the user asks for that scope.",
@@ -100,10 +102,9 @@ function buildCheckText(runtime: MainWatchdogRuntime | undefined, ctx: Extension
 	}
 	lines.push(`LSP diagnostics: ${snapshot.lsp.enabled ? "on" : "off"} · ${snapshot.lsp.status}`);
 	try {
-		const recommendation = recommendStrongWatchdogModel(ctx);
-		lines.push(`Recommended strong watchdog: ${recommendation.model}:${recommendation.thinking}`);
+		lines.push(formatWatchdogRecommendation(recommendWatchdogModel(ctx, snapshot.config.main)));
 	} catch (error) {
-		lines.push(`Recommended strong watchdog unavailable: ${messageFromError(error)}`);
+		lines.push(`Watchdog recommendation unavailable: ${messageFromError(error)}`);
 	}
 	return lines.join("\n");
 }
@@ -114,13 +115,13 @@ export function handleWatchdogToolAction(action: string, params: WatchdogToolPar
 			if (!runtime) return result("Subagent watchdog runtime is unavailable.", true);
 			return result(buildWatchdogStatus(runtime.getSnapshot(ctx.cwd), ctx));
 		}
-		if (action === "watchdog.recommend-model") return result(buildRecommendationText(ctx));
+		if (action === "watchdog.recommend-model") return result(buildRecommendationText(ctx, runtime));
 		if (action === "watchdog.check") return result(buildCheckText(runtime, ctx));
 		if (action !== "watchdog.configure") return result(`Unknown watchdog action: ${action}`, true);
 
 		const scope = parseScope(params.scope);
 		const target = parseTarget(params);
-		const value = resolveConfiguredValue(ctx, params);
+		const value = resolveConfiguredValue(ctx, params, runtime);
 		if (scope === "session") {
 			if (!runtime) return result("Subagent watchdog runtime is unavailable.", true);
 			if (target.kind !== "main") return result("Session-scoped watchdog.configure currently supports target='main' only.", true);
@@ -152,4 +153,4 @@ export function handleWatchdogToolAction(action: string, params: WatchdogToolPar
 }
 
 export const WATCHDOG_TOOL_ACTIONS = ["watchdog.status", "watchdog.check", "watchdog.configure", "watchdog.recommend-model"] as const;
-export const WATCHDOG_THINKING_VALUES = ["inherit", ...THINKING_LEVELS] as const;
+export const WATCHDOG_THINKING_VALUES = ["inherit", ...THINKING_LEVELS] as const;

package/dist/extensions/pi-subagents/src/watchdog/turn-delta.ts

@@ -21,6 +21,8 @@ export interface WatchdogTurnDeltaInput {
 	messages?: unknown[];
 	events?: unknown[];
 	finalAssistantStop?: boolean;
+	/** A validated structured output is the authoritative terminal response. */
+	structuredTerminal?: boolean;
 }
 
 function textFromContent(content: unknown): string {
@@ -122,13 +124,15 @@ function messagesFromEvent(event: unknown): unknown[] {
 	return [];
 }
 
-export function formatWatchdogReviewMessage(message: unknown): string | undefined {
+export function formatWatchdogReviewMessage(message: unknown, options: { structuredTerminal?: boolean } = {}): string | undefined {
 	if (!message || typeof message !== "object") return undefined;
 	const input = message as MessageLike;
 	if (input.role === "custom" && input.customType === SUBAGENT_WATCHDOG_WARNING_TYPE) return undefined;
 	if (input.role === "assistant") {
 		const text = textFromContent(input.content);
-		const lines = text ? ["Assistant:", text] : ["Assistant: (no text)"];
+		const lines = text
+			? ["Assistant:", text]
+			: [options.structuredTerminal ? "Assistant: (validated structured output is the terminal response; no prose is required)" : "Assistant: (no text)"];
 		if (input.stopReason === "stop") lines.push("Assistant stop: stop");
 		return lines.join("\n");
 	}
@@ -147,15 +151,40 @@ export function formatWatchdogTurnDelta(input: WatchdogTurnDeltaInput): string {
 	const sections: string[] = [];
 	if (input.includeUserPrompt && input.userPrompt?.trim()) sections.push(["User prompt:", input.userPrompt].join("\n"));
 	for (const message of input.messages ?? []) {
-		const section = formatWatchdogReviewMessage(message);
+		const section = formatWatchdogReviewMessage(message, { structuredTerminal: input.structuredTerminal });
 		if (section) sections.push(section);
 	}
 	for (const event of input.events ?? []) {
 		for (const message of messagesFromEvent(event)) {
-			const section = formatWatchdogReviewMessage(message);
+			const section = formatWatchdogReviewMessage(message, { structuredTerminal: input.structuredTerminal });
 			if (section) sections.push(section);
 		}
 	}
-	if (input.finalAssistantStop) sections.push("Final assistant stop: stop without tool call");
+	if (input.finalAssistantStop) sections.push(input.structuredTerminal
+		? "Final assistant stop: validated structured output completed the response"
+		: "Final assistant stop: stop without tool call");
 	return sections.join("\n\n---\n\n");
-}
+}
+
+/** Only completed, exactly paired native orchestration calls are activity evidence. */
+export function formatWatchdogOrchestrationActivity(event: unknown): string {
+	const turn = event as { type?: string; message?: { content?: unknown }; toolResults?: unknown[] } | undefined;
+	if (turn?.type !== "turn_end" || !Array.isArray(turn.message?.content) || !Array.isArray(turn.toolResults)) return "";
+	const sections: string[] = [];
+	for (const call of turn.message.content) {
+		if (call?.type !== "toolCall" || typeof call.id !== "string") continue;
+		const args = call.arguments;
+		if (!args || typeof args !== "object") continue;
+		const eligible = call.name === "bg_wait"
+			|| (call.name === "subagent_supervisor" && ["pending", "list", "reply"].includes(args.action))
+			|| (call.name === "subagent" && (["status", "resume", "interrupt", "steer", "stop"].includes(args.action)
+				|| (args.action === undefined && (typeof args.agent === "string" || args.workflow !== undefined))));
+		if (!eligible) continue;
+		const result = turn.toolResults.find((value) => {
+			const result = value as { role?: string; toolCallId?: string; toolName?: string };
+			return result?.role === "toolResult" && result.toolCallId === call.id && result.toolName === call.name;
+		});
+		if (result) sections.push(formatToolCall(call.name, args), formatWatchdogReviewMessage(result) ?? "");
+	}
+	return sections.join("\n\n");
+}