pi-subagents 0.63.0 → 0.64.0

package/src/runs/foreground/subagent-executor.ts

@@ -27,6 +27,7 @@ import { normalizePublicSubagentExecution, validateWorkflowCapacityOverrides } f
 import { runSync } from "./execution.ts";
 import { handleWatchdogToolAction, WATCHDOG_TOOL_ACTIONS } from "../../watchdog/tool-actions.ts";
 import type { MainWatchdogRuntime } from "../../watchdog/runtime.ts";
+import { applyWatchdogLaunchRules } from "../../watchdog/rules.ts";
 import { buildModelCandidates, normalizeParentModel, resolveEffectiveSubagentModel, resolveModelOrigin, type ModelOrigin, type ParentModel } from "../shared/model-fallback.ts";
 import { formatRetainedChildren, listRetainedChildren } from "../background/retained-children.ts";
 import { resolveModelScopesForAgent, type ModelScopeConfig } from "../shared/model-scope.ts";
@@ -2069,7 +2070,7 @@ async function resumeAsyncRun(input: {
 		// place rather than allocating a second provider worktree around it.
 		worktree: input.params.worktree === true && !("managedWorktree" in target && target.managedWorktree === true),
 		lane: input.params.lane ?? recoveryDescriptor?.lane,
-		controlConfig: recoveryDescriptor?.controlConfig ?? resolveControlConfig(input.deps.config.control, input.params.control),
+		controlConfig: resolveRevivalControlConfig({ globalConfig: input.deps.config.control, requestedControl: input.params.control, recoveryControlConfig: recoveryDescriptor?.controlConfig }),
 		intercomBridge: input.params.intercomBridge ?? recoveryDescriptor?.intercomBridge,
 		controlIntercomTarget: intercomBridge.active ? intercomBridge.orchestratorTarget : undefined,
 		childIntercomTarget: intercomBridge.active ? (agent, index) => resolveSubagentIntercomTarget(runId, agent, index) : undefined,
@@ -3229,6 +3230,8 @@ async function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): Pro
 				source: modelOrigin === "explicit" ? "explicit" : "inherited",
 			});
 		const modelOverrideFromParent = modelOrigin === "inherited";
+		const launchRuleError = applyWatchdogLaunchRules({ cwd: effectiveCwd, agent: a.name, model: modelOverride ?? (parentModel && `${parentModel.provider}/${parentModel.id}`), warn: (violation) => deps.watchdog?.displayRuleWarning(violation) });
+		if (launchRuleError) return toExecutionErrorResult(params, new Error(launchRuleError), data.contextPolicy.contextSummary);
 		const asyncResult = executeAsyncSingle(id, compactOptional<Parameters<typeof executeAsyncSingle>[1]>({
 			agent: params.agent!,
 			task: shouldForkAgent(contextPolicy, params.agent!) ? wrapForkTask(params.task ?? "") : (params.task ?? ""),
@@ -3664,6 +3667,8 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 		},
 	);
 	const modelOverrideFromParent = modelOrigin === "inherited";
+	const launchRuleError = applyWatchdogLaunchRules({ cwd: effectiveCwd, agent: agentConfig.name, model: modelOverride ?? (parentModel && `${parentModel.provider}/${parentModel.id}`), warn: (violation) => deps.watchdog?.displayRuleWarning(violation) });
+	if (launchRuleError) return toExecutionErrorResult(params, new Error(launchRuleError), data.contextPolicy.contextSummary);
 	let skillOverride: string[] | false | undefined = normalizeSkillInput(params.skill);
 	let readsOverride: string[] | false | undefined = params.reads;
 	const rawOutput = params.output !== undefined ? params.output : agentConfig.output;
@@ -4438,6 +4443,7 @@ export function prepareWorkflowLaunchParams(
 		if (output !== undefined && typeof output !== "string" && typeof output !== "boolean") throw new Error("output must be a path string or boolean.");
 		const outputMode = Object.hasOwn(childParams, "outputMode") ? childParams.outputMode : workflowDefaults.outputMode;
 		if (outputMode !== undefined && outputMode !== "inline" && outputMode !== "file-only") throw new Error("outputMode must be 'inline' or 'file-only'.");
+		const control = mergeWorkflowControlOverrides(workflowDefaults.control, childParams.control as ControlConfig | undefined);
 		return {
 			action: "resume",
 			id: childParams.resume.trim(),
@@ -4456,14 +4462,17 @@ export function prepareWorkflowLaunchParams(
 			...(options.missionDetached ? { mission: false } : {}),
 			...(timeoutMs !== undefined ? { timeoutMs: timeoutMs as number } : {}),
 			...(toolBudget !== undefined ? { toolBudget: toolBudget as ToolBudgetConfig } : {}),
+			...(control !== undefined ? { control } : {}),
 			...(intercomBridge !== undefined ? { intercomBridge: intercomBridge as IntercomBridgeConfig } : {}),
 			...(capabilityCeiling ? { capabilityCeiling } : {}),
 		};
 	}
+	const control = mergeWorkflowControlOverrides(workflowDefaults.control, childParams.control as ControlConfig | undefined);
 	const launchParams = {
 		...workflowDefaults,
 		async: options.externalAsyncRequired === true && childParams.async === undefined && workflowDefaults.async === undefined ? true : false,
 		...childParams,
+		...(control !== undefined ? { control } : {}),
 		...(options.externalAsyncRequired === true && childParams.async === undefined && workflowDefaults.async === undefined ? { workflowAwaitAsync: true } : {}),
 		...(options.missionDetached ? { mission: false } : {}),
 		workflowParentRunId: parentWorkflowRunId,
@@ -4482,6 +4491,17 @@ export function prepareWorkflowLaunchParams(
 	return normalizedGate.params;
 }
 
+function mergeWorkflowControlOverrides(workflowControl: ControlConfig | undefined, childControl: ControlConfig | undefined): ControlConfig | undefined {
+	if (childControl === undefined) return workflowControl;
+	if (workflowControl === undefined) return childControl;
+	return { ...workflowControl, ...childControl };
+}
+
+export function resolveRevivalControlConfig(input: { globalConfig?: ControlConfig; requestedControl?: ControlConfig; recoveryControlConfig?: ResolvedControlConfig }): ResolvedControlConfig {
+	if (input.requestedControl === undefined) return input.recoveryControlConfig ?? resolveControlConfig(input.globalConfig, undefined);
+	return resolveControlConfig(input.recoveryControlConfig ?? input.globalConfig, input.requestedControl);
+}
+
 type GateParamsNormalizationResult =
 	| { ok: true; params: SubagentParamsLike }
 	| { ok: false; error: string };

package/src/runs/shared/acceptance.ts

@@ -21,7 +21,9 @@ import type {
 	ResolvedAcceptanceGate,
 	SingleResult,
 	SubagentRunMode,
+	ChildWatchdogProgress,
 } from "../../shared/types.ts";
+import { unresolvedChildWatchdogBlockers } from "../../watchdog/child-status.ts";
 import { isAgentContractV1 } from "./agent-contract.ts";
 import { classifyTaskMutationIntent, stripSeverityCompounds, taskMayMutate } from "./task-intent.ts";
 
@@ -1360,6 +1362,7 @@ export async function evaluateAcceptance(input: {
 	reportOptional?: boolean;
 	artifactsDir?: string;
 	runId?: string;
+	watchdog?: ChildWatchdogProgress;
 }): Promise<AcceptanceLedger> {
 	const acceptance = input.acceptance;
 	const initialStatus = acceptance.level === "none" ? "not-required" : "claimed";
@@ -1375,6 +1378,13 @@ export async function evaluateAcceptance(input: {
 	};
 	if (acceptance.level === "none") return ledger;
 
+	if (input.watchdog) {
+		const unresolved = unresolvedChildWatchdogBlockers(input.watchdog);
+		ledger.runtimeChecks.push(unresolved.length
+			? { id: "watchdog-blocker", status: "failed", message: `Unresolved watchdog blocker: ${unresolved[0]!.summary}` }
+			: { id: "watchdog-blocker", status: "passed", message: "No unresolved watchdog blockers." });
+	}
+
 	const parsed: AcceptanceReportParseResult = input.reportError
 		? { error: input.reportError }
 		: input.report !== undefined

package/src/runs/shared/async-status-projection.ts

@@ -2,6 +2,7 @@ import { sanitizeDisplayText, truncateDisplayText } from "../../shared/display-t
 import { formatModelThinking } from "../../shared/formatters.ts";
 import type { AsyncJobState, AsyncJobStep, HostStepFreshnessV1, HostStepMonitorKind, HostStepNodeV1, HostStepState, HostStepVerdict, NestedRunSummary, NestedStepSummary, SubagentRunMode, WorkflowGraphSnapshot, WorkflowPreflightLaneV1, WorkflowPreflightV1 } from "../../shared/types.ts";
 import { HOST_STEP_MAX_COUNT, HOST_STEP_MAX_DETAIL_CHARS, HOST_STEP_MAX_LABEL_CHARS, HOST_STEP_MAX_PROVIDER_CHARS, HOST_STEP_MAX_REASON_CHARS, HOST_STEP_MAX_REF_CHARS, HOST_STEP_MAX_ROLE_CHARS, HOST_STEP_MAX_TARGET_CHARS, hostStepReportName, parseHostStepNode, validHostStepNodes } from "./host-step-status.ts";
+import { workflowPreflightLaneForRuntimeKey } from "../../workflows/workflow-preflight.ts";
 import { workflowGraphStageNodes } from "./workflow-graph.ts";
 
 export const ASYNC_STATUS_SNAPSHOT_KIND = "pi-subagents.async-status-snapshot";
@@ -472,7 +473,7 @@ function projectWorkflowGraphRow(node: WorkflowGraphSnapshot["nodes"][number], p
 	};
 }
 
-/** Project loaded workflow child facts plus stored preflight hints into compact rows. */
+/** Project authoritative workflow facts into compact rows, annotated by preflight hints. */
 export function projectAsyncWorkflowRows(
 	steps: readonly AsyncJobStep[] | undefined,
 	hostStepsOrPreflight?: readonly HostStepNodeV1[] | WorkflowGraphSnapshot | WorkflowPreflightV1,
@@ -482,7 +483,8 @@ export function projectAsyncWorkflowRows(
 	const graph = isWorkflowGraph(hostStepsOrPreflight) ? hostStepsOrPreflight : undefined;
 	const hostSteps = isWorkflowPreflight(hostStepsOrPreflight) || graph ? undefined : hostStepsOrPreflight;
 	const loaded = steps ?? [];
-	const declared = new Map<string, WorkflowPreflightLaneV1>();
+	const preflightForKey = (key: string, groupKeys: readonly (string | undefined)[] = []): WorkflowPreflightLaneV1 | undefined =>
+		workflowPreflightLaneForRuntimeKey(preflight, key, groupKeys);
 	if (graph) {
 		const loadedIndexesByKey = new Map<string, number[]>();
 		for (const [index, step] of loaded.entries()) {
@@ -493,7 +495,6 @@ export function projectAsyncWorkflowRows(
 		}
 		const consumed = new Set<number>();
 		const childRows: AsyncStatusWorkflowRow[] = [];
-		for (const lane of preflight?.lanes ?? []) declared.set(lane.key, lane);
 		const graphStages = workflowGraphStageNodes(graph);
 		const graphKeys = new Set(graphStages.map((node) => node.id));
 		const graphPhaseByNodeId = new Map<string, string>();
@@ -502,60 +503,27 @@ export function projectAsyncWorkflowRows(
 				if (graphKeys.has(nodeId) && !graphPhaseByNodeId.has(nodeId)) graphPhaseByNodeId.set(nodeId, phase.title);
 			}
 		}
-		const graphLaneKeys = new Set(graphPhaseByNodeId.values());
-		const preflightForNode = (node: WorkflowGraphSnapshot["nodes"][number]): WorkflowPreflightLaneV1 | undefined => {
-			const phaseTitle = graphPhaseByNodeId.get(node.id);
-			return declared.get(node.id) ?? (node.phase ? declared.get(node.phase) : undefined) ?? (phaseTitle ? declared.get(phaseTitle) : undefined);
-		};
 		for (const node of graphStages) {
+			const lane = preflightForKey(node.id, [node.phase, graphPhaseByNodeId.get(node.id)]);
 			const indexes = (loadedIndexesByKey.get(node.id) ?? []).filter((index) => !consumed.has(index));
-			if (indexes.length > 0) {
-				for (const index of indexes) {
-					consumed.add(index);
-					childRows.push(projectLoadedWorkflowRow(loaded[index]!, index, preflightForNode(node)));
-				}
-			} else {
-				childRows.push(projectWorkflowGraphRow(node, preflightForNode(node)));
-			}
-		}
-		for (const lane of preflight?.lanes ?? []) {
-			if (graphKeys.has(lane.key) || graphLaneKeys.has(lane.key)) continue;
-			const indexes = (loadedIndexesByKey.get(lane.key) ?? []).filter((index) => !consumed.has(index));
 			if (indexes.length > 0) {
 				for (const index of indexes) {
 					consumed.add(index);
 					childRows.push(projectLoadedWorkflowRow(loaded[index]!, index, lane));
 				}
 			} else {
-				childRows.push({ name: lane.key, state: "planned", preflight: lane });
+				childRows.push(projectWorkflowGraphRow(node, lane));
 			}
 		}
 		for (const [index, step] of loaded.entries()) {
-			if (!consumed.has(index)) childRows.push(projectLoadedWorkflowRow(step, index, step.workflowKey ? declared.get(step.workflowKey) : undefined));
+			if (!consumed.has(index)) childRows.push(projectLoadedWorkflowRow(step, index, step.workflowKey ? preflightForKey(step.workflowKey, [step.phase]) : undefined));
 		}
 		return [...childRows, ...validHostStepList(graph).map(hostStepRow)];
 	}
-	const loadedIndexByKey = new Map<string, number>();
-	for (const [index, step] of loaded.entries()) {
-		if (step.workflowKey !== undefined && !loadedIndexByKey.has(step.workflowKey)) loadedIndexByKey.set(step.workflowKey, index);
-	}
-	const consumed = new Set<number>();
-	const childRows: AsyncStatusWorkflowRow[] = [];
-	for (const lane of preflight?.lanes ?? []) {
-		declared.set(lane.key, lane);
-		const index = loadedIndexByKey.get(lane.key);
-		if (index === undefined) {
-			childRows.push({ name: lane.key, state: "planned", preflight: lane });
-			continue;
-		}
-		consumed.add(index);
-		childRows.push(projectLoadedWorkflowRow(loaded[index]!, index, lane));
-	}
-	for (const [index, step] of loaded.entries()) {
-		if (consumed.has(index)) continue;
-		childRows.push(projectLoadedWorkflowRow(step, index, step.workflowKey ? declared.get(step.workflowKey) : undefined));
-	}
-	return [...childRows, ...validHostStepList(hostSteps).map(hostStepRow)];
+	return [
+		...loaded.map((step, index) => projectLoadedWorkflowRow(step, index, step.workflowKey ? preflightForKey(step.workflowKey, [step.phase]) : undefined)),
+		...validHostStepList(hostSteps).map(hostStepRow),
+	];
 }
 
 function projectLoadedWorkflowRow(step: AsyncJobStep, index: number, preflight?: WorkflowPreflightLaneV1): AsyncStatusWorkflowRow {

package/src/runs/shared/pi-args.ts

@@ -47,7 +47,6 @@ import {
 } from "./tool-availability.ts";
 import {
 	CHILD_WATCHDOG_CONFIG_ENV,
-	encodeChildWatchdogConfig,
 	type ChildWatchdogConfig,
 } from "../../watchdog/child-status.ts";
 import { WAIT_TOOL_DEFAULT_TIMEOUT_MS_ENV, WAIT_TOOL_ENABLED_ENV } from "../background/wait-config.ts";
@@ -1031,9 +1030,7 @@ export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
 	const encodedToolBudget = encodeToolBudgetEnv(input.toolBudget);
 	if (encodedToolBudget) env[TOOL_BUDGET_ENV] = encodedToolBudget;
 	env[TOOL_BUDGET_ZERO_AUTH_ENV] = input.allowZeroToolBudget ? "1" : undefined;
-	const encodedChildWatchdog = encodeChildWatchdogConfig(input.childWatchdog);
-	if (encodedChildWatchdog)
-		env[CHILD_WATCHDOG_CONFIG_ENV] = encodedChildWatchdog;
+	if (input.childWatchdog) env[CHILD_WATCHDOG_CONFIG_ENV] = JSON.stringify(input.childWatchdog);
 
 	env[SUBAGENT_PARENT_SESSION_ENV] =
 		input.parentSessionId ?? process.env[SUBAGENT_PARENT_SESSION_ENV] ?? "";

package/src/runs/shared/subagent-control.ts

@@ -45,11 +45,12 @@ export function resolveControlConfig(
 	const enabled = override?.enabled ?? globalConfig?.enabled ?? DEFAULT_CONTROL_CONFIG.enabled;
 	const overrideNeedsAttentionAfterMs = parsePositiveInt(override?.needsAttentionAfterMs);
 	const globalNeedsAttentionAfterMs = parsePositiveInt(globalConfig?.needsAttentionAfterMs);
+	const globalNeedsAttentionAfterMsIsExplicit = (globalConfig as Partial<ResolvedControlConfig> | undefined)?.needsAttentionAfterMsIsExplicit ?? globalNeedsAttentionAfterMs !== undefined;
 	const needsAttentionAfterMs = overrideNeedsAttentionAfterMs
 		?? globalNeedsAttentionAfterMs
 		?? DEFAULT_CONTROL_CONFIG.needsAttentionAfterMs;
 	const needsAttentionAfterMsIsExplicit = overrideNeedsAttentionAfterMs !== undefined
-		|| globalNeedsAttentionAfterMs !== undefined;
+		|| globalNeedsAttentionAfterMsIsExplicit;
 	const activeNoticeAfterMs = parsePositiveInt(override?.activeNoticeAfterMs)
 		?? parsePositiveInt(globalConfig?.activeNoticeAfterMs)
 		?? DEFAULT_CONTROL_CONFIG.activeNoticeAfterMs;
@@ -98,11 +99,12 @@ export function deriveActivityState(input: {
 	config: ResolvedControlConfig;
 	startedAt: number;
 	lastActivityAt?: number;
+	turnCount?: number;
 	currentTool?: string;
 	thinking?: string | false;
 	now?: number;
 }): ActivityState | undefined {
-	if (!input.config.enabled || input.currentTool) return undefined;
+	if (!input.config.enabled || input.currentTool || (input.turnCount ?? 0) === 0) return undefined;
 	const now = input.now ?? Date.now();
 	const lastActivity = input.lastActivityAt ?? input.startedAt;
 	const ageMs = Math.max(0, now - lastActivity);

package/src/shared/types.ts

@@ -15,6 +15,7 @@ import type { ThinkingLevel } from "./model-info.ts";
 import type { GlobalMissionIndexRecord, MissionRecord, MissionStoreConfig } from "../missions/types.ts";
 import type { ExtensionBindings } from "../runs/shared/extension-bindings.ts";
 import type { WorkflowChildPermitContext } from "./workflow-child-permit.ts";
+import type { WatchdogWarningDetails } from "../watchdog/types.ts";
 
 // ============================================================================
 // Basic Types
@@ -894,13 +895,19 @@ export interface SubagentResultIntercomPayload {
 // Progress Tracking
 // ============================================================================
 
+export interface ChildWatchdogWarningSummary extends Pick<WatchdogWarningDetails, "severity" | "category" | "summary" | "evidence" | "recommendedAction" | "displayedAt"> {
+	/** True when a later assistant turn in the child followed the warning. */
+	addressed: boolean;
+	stalemate: boolean;
+}
+
 export interface ChildWatchdogProgress {
-	phase: "idle" | "reviewing" | "autofollow" | "settling" | "stale" | "failed";
+	phase: "idle" | "reviewing" | "stale" | "failed";
 	seq: number;
 	lastUpdate: number;
-	followUpPending: boolean;
 	reason?: string;
 	timedOut?: boolean;
+	warnings?: ChildWatchdogWarningSummary[];
 }
 
 export interface AgentProgress {

package/src/tui/render.ts

@@ -7,6 +7,7 @@ import { createHash } from "node:crypto";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import { getMarkdownTheme, keyText, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Container, Markdown, Spacer, Text, visibleWidth, type Component } from "@earendil-works/pi-tui";
+import { unresolvedChildWatchdogBlockers } from "../watchdog/child-status.ts";
 import {
 	type AgentProgress,
 	type AsyncJobState,
@@ -360,6 +361,7 @@ function workflowStepPriority(step: AsyncJobStep, currentNodeId?: string): numbe
 		|| step.turnBudgetExceeded === true
 		|| step.activityState === "needs_attention"
 		|| step.watchdog?.phase === "stale"
+		|| unresolvedChildWatchdogBlockers(step.watchdog).length > 0
 		|| gate !== undefined
 	) return 1;
 	if (step.status === "pending") return 2;
@@ -505,6 +507,7 @@ function laneGate(step: AsyncJobStep | undefined): string | undefined {
 }
 
 function laneNextAction(state: AsyncLaneProjection["state"], step: AsyncJobStep | undefined, output: string | undefined, gate: string | undefined): string | undefined {
+	if (unresolvedChildWatchdogBlockers(step?.watchdog).length > 0) return "resolve watchdog blockers";
 	if (step?.watchdog?.phase === "stale") return "inspect stale state";
 	if (step?.toolBudgetBlocked === true || step?.turnBudgetExceeded === true) return "inspect blocked state";
 	if (gate === "review blockers") return "resolve review blockers";
@@ -543,6 +546,7 @@ export function projectAsyncLane(job: AsyncJobState, ...args: [selectedStep?: As
 		selectedStep?.activityState === "active_long_running" ? "long-running" : undefined,
 		selectedStep?.activityState === "needs_attention" ? "attention" : undefined,
 		selectedStep?.watchdog?.phase === "stale" ? "stale" : undefined,
+		unresolvedChildWatchdogBlockers(selectedStep?.watchdog).length > 0 ? `wd:${unresolvedChildWatchdogBlockers(selectedStep?.watchdog).length}` : undefined,
 		selectedStep?.toolBudgetBlocked === true || selectedStep?.turnBudgetExceeded === true ? "blocked" : undefined,
 	].filter((chip): chip is string => Boolean(chip));
 	const state = isTerminalLaneState(job.status) ? job.status : selectedStep?.status ?? job.status;
@@ -1001,6 +1005,7 @@ function widgetStepRenderKey(step: AsyncJobStep, index: number, expanded = false
 		step.execution?.stopped,
 		step.execution?.detached,
 		step.watchdog?.phase,
+		unresolvedChildWatchdogBlockers(step.watchdog).length,
 		step.error,
 		expanded ? expandedStepActivityRenderKey(step) : undefined,
 		nestedRenderKey(step.children, expanded),

package/src/watchdog/child-status.ts

@@ -1,13 +1,15 @@
-import type { ResolvedWatchdogConfig, WatchdogLspConfig } from "./types.ts";
+import type { ChildWatchdogProgress, ChildWatchdogWarningSummary } from "../shared/types.ts";
+import { SUBAGENT_WATCHDOG_WARNING_TYPE, type ResolvedWatchdogConfig, type WatchdogCadenceConfig, type WatchdogCategory, type WatchdogLspConfig } from "./types.ts";
+
+export const CHILD_WATCHDOG_WARNING_LIMIT = 20;
 
 export const CHILD_WATCHDOG_CONFIG_ENV = "PI_SUBAGENT_WATCHDOG_CHILD_CONFIG";
 export const CHILD_WATCHDOG_STATUS_EVENT = "subagent.watchdog.status";
 
-export const CHILD_WATCHDOG_PHASES = ["idle", "reviewing", "autofollow", "settling", "stale", "failed"] as const;
+export const CHILD_WATCHDOG_PHASES = ["idle", "reviewing", "stale", "failed"] as const;
 export type ChildWatchdogPhase = typeof CHILD_WATCHDOG_PHASES[number];
 
 export interface ChildWatchdogConfig {
-	enabled: boolean;
 	runId?: string;
 	agent?: string;
 	childIndex?: number;
@@ -17,9 +19,9 @@ export interface ChildWatchdogConfig {
 	model?: string;
 	thinking?: string | false;
 	lsp: WatchdogLspConfig;
-	autoFollowBlockers: boolean;
-	autoFollowMaxAttempts: number | null;
 	stalemateRepeats: number;
+	/** Mid-run review cadence; everyNTools null means boundary reviews only. */
+	cadence: WatchdogCadenceConfig;
 }
 
 export interface ChildWatchdogStatusEvent {
@@ -31,18 +33,10 @@ export interface ChildWatchdogStatusEvent {
 	seq: number;
 	phase: ChildWatchdogPhase;
 	ts: number;
-	followUpPending: boolean;
 	reason?: string;
 }
 
-export interface ChildWatchdogStateSnapshot {
-	phase: ChildWatchdogPhase;
-	seq: number;
-	lastUpdate: number;
-	followUpPending: boolean;
-	reason?: string;
-	timedOut?: boolean;
-}
+export type ChildWatchdogStateSnapshot = ChildWatchdogProgress;
 
 export function resolveChildWatchdogConfig(input: {
 	config: ResolvedWatchdogConfig;
@@ -55,8 +49,8 @@ export function resolveChildWatchdogConfig(input: {
 	if (!enabled) return undefined;
 	const model = override?.model ?? input.config.children.model;
 	const thinking = override?.thinking ?? input.config.children.thinking;
+	const cadence = override?.cadence ?? input.config.children.cadence ?? input.config.cadence;
 	return {
-		enabled: true,
 		...(input.runId ? { runId: input.runId } : {}),
 		...(input.agent ? { agent: input.agent } : {}),
 		...(input.childIndex !== undefined ? { childIndex: input.childIndex } : {}),
@@ -66,16 +60,11 @@ export function resolveChildWatchdogConfig(input: {
 		...(model ? { model } : {}),
 		...(thinking !== undefined ? { thinking } : {}),
 		lsp: { ...input.config.lsp },
-		autoFollowBlockers: input.config.children.autoFollow.blockers,
-		autoFollowMaxAttempts: input.config.children.autoFollow.maxAttempts,
-		stalemateRepeats: input.config.children.autoFollow.stalemateRepeats,
+		stalemateRepeats: input.config.stalemateRepeats,
+		cadence: { everyNTools: cadence.everyNTools ?? null },
 	};
 }
 
-export function encodeChildWatchdogConfig(config: ChildWatchdogConfig | undefined): string | undefined {
-	return config ? JSON.stringify(config) : undefined;
-}
-
 function childConfigObject(value: unknown, field: string): Record<string, unknown> {
 	if (value && typeof value === "object" && !Array.isArray(value)) return value as Record<string, unknown>;
 	throw new Error(`Invalid child watchdog config: ${field} must be an object.`);
@@ -108,10 +97,12 @@ function childConfigNullableNonNegativeInteger(input: Record<string, unknown>, f
 	throw new Error(`Invalid child watchdog config: ${field} must be null or a non-negative integer.`);
 }
 
-function childConfigBoolean(input: Record<string, unknown>, field: string): boolean {
-	const value = input[field];
-	if (typeof value === "boolean") return value;
-	throw new Error(`Invalid child watchdog config: ${field} must be a boolean.`);
+function childConfigCadence(value: unknown): WatchdogCadenceConfig {
+	const input = childConfigObject(value, "cadence");
+	const everyNTools = input.everyNTools;
+	if (everyNTools === null) return { everyNTools: null };
+	if (typeof everyNTools === "number" && Number.isInteger(everyNTools) && everyNTools >= 5) return { everyNTools };
+	throw new Error("Invalid child watchdog config: cadence.everyNTools must be null or an integer >= 5.");
 }
 
 function childConfigLsp(value: unknown): WatchdogLspConfig {
@@ -138,7 +129,7 @@ export function decodeChildWatchdogConfig(raw: string | undefined): ChildWatchdo
 	if (!raw) return undefined;
 	const parsed = childConfigObject(JSON.parse(raw), "root");
 	if (parsed.enabled === false) return undefined;
-	if (parsed.enabled !== true) throw new Error("Invalid child watchdog config: enabled must be true or false.");
+	if ("enabled" in parsed && parsed.enabled !== true) throw new Error("Invalid child watchdog config: enabled must be true or false.");
 	const thinking = parsed.thinking;
 	if (thinking !== undefined && typeof thinking !== "string" && thinking !== false) {
 		throw new Error("Invalid child watchdog config: thinking must be a string or false.");
@@ -148,7 +139,6 @@ export function decodeChildWatchdogConfig(raw: string | undefined): ChildWatchdo
 	const childIndex = childConfigOptionalIndex(parsed, "childIndex");
 	const model = childConfigOptionalString(parsed, "model");
 	return {
-		enabled: true,
 		...(runId ? { runId } : {}),
 		...(agent ? { agent } : {}),
 		...(childIndex !== undefined ? { childIndex } : {}),
@@ -158,9 +148,8 @@ export function decodeChildWatchdogConfig(raw: string | undefined): ChildWatchdo
 		...(model ? { model } : {}),
 		...(thinking !== undefined ? { thinking: thinking as string | false } : {}),
 		lsp: childConfigLsp(parsed.lsp),
-		autoFollowBlockers: childConfigBoolean(parsed, "autoFollowBlockers"),
-		autoFollowMaxAttempts: childConfigNullableNonNegativeInteger(parsed, "autoFollowMaxAttempts"),
 		stalemateRepeats: childConfigPositiveInteger(parsed, "stalemateRepeats"),
+		cadence: childConfigCadence(parsed.cadence),
 	};
 }
 
@@ -173,14 +162,13 @@ export function isChildWatchdogStatusEvent(value: unknown): value is ChildWatchd
 		&& event.seq >= 0
 		&& typeof event.ts === "number"
 		&& Number.isFinite(event.ts)
-		&& typeof event.followUpPending === "boolean"
 		&& typeof event.phase === "string"
 		&& (CHILD_WATCHDOG_PHASES as readonly string[]).includes(event.phase);
 }
 
 export function childWatchdogIsActive(snapshot: ChildWatchdogStateSnapshot | undefined): boolean {
 	if (!snapshot) return false;
-	return snapshot.followUpPending || snapshot.phase === "reviewing" || snapshot.phase === "autofollow" || snapshot.phase === "settling";
+	return snapshot.phase === "reviewing";
 }
 
 export function acceptChildWatchdogEvent(input: {
@@ -199,7 +187,40 @@ export function acceptChildWatchdogEvent(input: {
 		phase: input.event.phase,
 		seq: input.event.seq,
 		lastUpdate: input.event.ts,
-		followUpPending: input.event.followUpPending,
 		...(input.event.reason ? { reason: input.event.reason } : {}),
+		...(input.current?.warnings?.length ? { warnings: input.current.warnings } : {}),
 	};
 }
+
+function childWatchdogWarningFromMessage(message: unknown): ChildWatchdogWarningSummary | undefined {
+	const candidate = message as { role?: unknown; customType?: unknown; details?: Record<string, unknown> } | undefined;
+	if (candidate?.role !== "custom" || candidate.customType !== SUBAGENT_WATCHDOG_WARNING_TYPE) return undefined;
+	const details = candidate.details ?? {};
+	if (details.severity !== "concern" && details.severity !== "blocker") return undefined;
+	if (typeof details.summary !== "string" || typeof details.evidence !== "string" || typeof details.recommendedAction !== "string") return undefined;
+	return {
+		severity: details.severity,
+		category: details.category as WatchdogCategory,
+		summary: details.summary,
+		evidence: details.evidence,
+		recommendedAction: details.recommendedAction,
+		...(typeof details.displayedAt === "string" ? { displayedAt: details.displayedAt } : {}),
+		addressed: false,
+		stalemate: details.state === "stalemate",
+	};
+}
+
+/** A watchdog warning message is appended; an assistant turn marks earlier warnings addressed. Undefined when unchanged. */
+export function applyChildWatchdogMessage(current: ChildWatchdogStateSnapshot | undefined, message: unknown, now = Date.now()): ChildWatchdogStateSnapshot | undefined {
+	const warning = childWatchdogWarningFromMessage(message);
+	if (warning) {
+		const warnings = [...(current?.warnings ?? []), warning].slice(-CHILD_WATCHDOG_WARNING_LIMIT);
+		return current ? { ...current, warnings } : { phase: "idle", seq: 0, lastUpdate: now, warnings };
+	}
+	if ((message as { role?: unknown } | undefined)?.role !== "assistant" || !current?.warnings?.some((entry) => !entry.addressed)) return undefined;
+	return { ...current, warnings: current.warnings.map((entry) => entry.addressed ? entry : { ...entry, addressed: true }) };
+}
+
+export function unresolvedChildWatchdogBlockers(progress: Pick<ChildWatchdogProgress, "warnings"> | undefined): ChildWatchdogWarningSummary[] {
+	return (progress?.warnings ?? []).filter((warning) => warning.severity === "blocker" && (!warning.addressed || warning.stalemate));
+}

package/src/watchdog/diff-tool.ts

@@ -0,0 +1,77 @@
+import { spawnSync } from "node:child_process";
+import * as path from "node:path";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { Type, type Static } from "typebox";
+
+export const WATCHDOG_DIFF_TOOL_NAME = "watchdog_diff";
+export const WATCHDOG_DIFF_MAX_CHARS = 24_000;
+const MAX_UNTRACKED_FILES = 50;
+
+export interface WatchdogDiffBaseline {
+	root: string;
+	ref: string;
+}
+
+const WatchdogDiffParams = Type.Object({
+	path: Type.Optional(Type.String({ description: "Restrict the diff to one file or directory, relative to the repo root." })),
+	stat: Type.Optional(Type.Boolean({ description: "Return per-file change counts instead of the full diff." })),
+}, { additionalProperties: false });
+
+type WatchdogDiffParams = Static<typeof WatchdogDiffParams>;
+
+function runGit(root: string, args: string[]): { ok: boolean; stdout: string; stderr: string } {
+	const result = spawnSync("git", ["-C", root, ...args], { encoding: "utf-8", maxBuffer: 16 * 1024 * 1024, windowsHide: true });
+	return { ok: result.status === 0, stdout: result.stdout ?? "", stderr: (result.stderr ?? "").trim() };
+}
+
+/** HEAD at session start, so later child commits still show in the diff. */
+export function captureWatchdogDiffBaseline(cwd: string): WatchdogDiffBaseline | undefined {
+	const toplevel = runGit(cwd, ["rev-parse", "--show-toplevel"]);
+	if (!toplevel.ok) return undefined;
+	const head = runGit(cwd, ["rev-parse", "HEAD"]);
+	if (!head.ok) return undefined;
+	const root = toplevel.stdout.trim();
+	const ref = head.stdout.trim();
+	return root && ref ? { root, ref } : undefined;
+}
+
+function validatePath(value: string | undefined): string | undefined {
+	const trimmed = value?.trim();
+	if (!trimmed) return undefined;
+	if (trimmed.startsWith("-")) throw new Error("watchdog_diff path must not start with '-'.");
+	if (path.isAbsolute(trimmed)) throw new Error("watchdog_diff path must be relative to the repo root.");
+	if (trimmed.split(/[\\/]/).includes("..")) throw new Error("watchdog_diff path must not contain '..'.");
+	return trimmed;
+}
+
+function bound(text: string): string {
+	if (text.length <= WATCHDOG_DIFF_MAX_CHARS) return text;
+	const marker = `\n\n[... ${text.length - WATCHDOG_DIFF_MAX_CHARS} characters omitted; call again with a narrower path ...]`;
+	return `${text.slice(0, WATCHDOG_DIFF_MAX_CHARS - marker.length)}${marker}`;
+}
+
+/** In a shared cwd, changes already pending when the session started also appear. */
+export function createWatchdogDiffTool(baseline: WatchdogDiffBaseline): AgentTool<typeof WatchdogDiffParams, { chars: number }> {
+	return {
+		name: WATCHDOG_DIFF_TOOL_NAME,
+		label: "Watchdog diff",
+		description: "Show the repository diff since the review baseline, plus untracked file paths. Optional path narrows it; stat:true returns per-file counts only.",
+		parameters: WatchdogDiffParams,
+		executionMode: "sequential",
+		async execute(_toolCallId, params: WatchdogDiffParams) {
+			const pathFilter = validatePath(params.path);
+			const diff = runGit(baseline.root, ["diff", "--no-color", "--no-ext-diff", ...(params.stat === true ? ["--stat"] : []), baseline.ref, "--", ...(pathFilter ? [pathFilter] : [])]);
+			if (!diff.ok) throw new Error(`git diff failed: ${diff.stderr || "unknown error"}`);
+			const untrackedResult = runGit(baseline.root, ["ls-files", "--others", "--exclude-standard", "-z", "--", ...(pathFilter ? [pathFilter] : [])]);
+			const untracked = untrackedResult.ok ? untrackedResult.stdout.split("\0").filter(Boolean) : [];
+			const sections = [diff.stdout.trimEnd()];
+			if (untracked.length) {
+				const shown = untracked.slice(0, MAX_UNTRACKED_FILES);
+				sections.push(["Untracked files (use read to inspect):", ...shown.map((file) => ` ${file}`)].join("\n"));
+				if (untracked.length > shown.length) sections.push(`... ${untracked.length - shown.length} more untracked files`);
+			}
+			const text = bound(sections.filter(Boolean).join("\n\n")) || `No changes since baseline ${baseline.ref.slice(0, 12)}.`;
+			return { content: [{ type: "text", text }], details: { chars: text.length } };
+		},
+	};
+}

package/src/watchdog/emission-guard.ts

@@ -88,7 +88,8 @@ export class WatchdogEmissionGuard {
 		this.startModelUpdate();
 	}
 
-	evaluate(warning: WatchdogWarning): WatchdogEmissionDecision {
+	/** `allowRepeatOf`: one already-accepted identity that may repeat (boundary re-findings before stalemate). */
+	evaluate(warning: WatchdogWarning, options: { allowRepeatOf?: string } = {}): WatchdogEmissionDecision {
 		if (isContentFree(warning.summary) || isContentFree(warning.evidence) || isContentFree(warning.recommendedAction)) {
 			return { accepted: false, reason: "content-free" };
 		}
@@ -102,8 +103,9 @@ export class WatchdogEmissionGuard {
 				&& warning.severity === "blocker";
 			if (!updateEscalation) return { accepted: false, reason: "update-budget", identity, underlyingIdentity };
 		}
-		if (priorSeverity !== undefined && !escalation) return { accepted: false, reason: "duplicate", identity, underlyingIdentity };
-		if (this.maxWarnings !== null && this.acceptedCount >= this.maxWarnings && !escalation) {
+		const repeat = priorSeverity !== undefined && options.allowRepeatOf === identity;
+		if (priorSeverity !== undefined && !escalation && !repeat) return { accepted: false, reason: "duplicate", identity, underlyingIdentity };
+		if (this.maxWarnings !== null && this.acceptedCount >= this.maxWarnings && !escalation && !repeat) {
 			return { accepted: false, reason: "max-warnings", identity, underlyingIdentity };
 		}
 

package/src/watchdog/guidance.ts

@@ -0,0 +1,20 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAgentDir, getProjectConfigDir } from "../shared/utils.ts";
+
+export const WATCHDOG_GUIDANCE_MAX_CHARS = 8_000;
+
+function readOptional(filePath: string): string {
+	try {
+		return fs.readFileSync(filePath, "utf-8").trim();
+	} catch {
+		return "";
+	}
+}
+
+/** Read fresh on every review; project file first, then user file. */
+export function loadWatchdogGuidance(cwd: string, enabled: boolean): string {
+	if (!enabled) return "";
+	const sections = [getProjectConfigDir(cwd), getAgentDir()].map((dir) => readOptional(path.join(dir, "WATCHDOG.md"))).filter(Boolean);
+	return sections.join("\n\n").slice(0, WATCHDOG_GUIDANCE_MAX_CHARS);
+}