pi-subagents 0.63.0 → 0.64.0

package/src/watchdog/settings.ts

@@ -3,39 +3,31 @@ import * as path from "node:path";
 import { THINKING_LEVELS, type ThinkingLevel } from "../shared/model-info.ts";
 import { getAgentDir, getProjectConfigDir } from "../shared/utils.ts";
 import {
-	WATCHDOG_DELIVERY_MODES,
-	WATCHDOG_LATE_WARNING_POLICIES,
 	WATCHDOG_WARNING_SEVERITIES,
 	type ResolvedWatchdogConfig,
-	type WatchdogAsyncCompletionConfig,
-	type WatchdogAutoFollowConfig,
 	type WatchdogChildOverrideConfig,
 	type WatchdogChildrenConfig,
-	type WatchdogDeliveryMode,
 	type WatchdogEndpointConfig,
 	type WatchdogCadenceConfig,
 	type WatchdogGuidanceConfig,
-	type WatchdogLateWarningPolicy,
 	type WatchdogScopeConfig,
 	type WatchdogLspConfig,
+	type WatchdogRoleModelRule,
+	type WatchdogRulesConfig,
 	type WatchdogSettingsError,
 	type WatchdogSettingsResult,
 	type WatchdogSettingsSource,
 	type WatchdogSeverity,
-	type WatchdogSyncBacklog,
 } from "./types.ts";
 
-type WatchdogAutoFollowPatch = Partial<WatchdogAutoFollowConfig>;
 type WatchdogGuidancePatch = Partial<WatchdogGuidanceConfig>;
 type WatchdogScopePatch = Partial<WatchdogScopeConfig>;
 type WatchdogCadencePatch = Partial<WatchdogCadenceConfig>;
 type WatchdogEndpointPatch = Partial<WatchdogEndpointConfig>;
 type WatchdogChildOverridePatch = Partial<WatchdogChildOverrideConfig>;
-type WatchdogChildrenPatch = Partial<Omit<WatchdogChildrenConfig, "autoFollow" | "overrides">> & {
-	autoFollow?: WatchdogAutoFollowPatch;
+type WatchdogChildrenPatch = Partial<Omit<WatchdogChildrenConfig, "overrides">> & {
 	overrides?: Record<string, WatchdogChildOverridePatch>;
 };
-type WatchdogAsyncCompletionPatch = Partial<WatchdogAsyncCompletionConfig>;
 type WatchdogLspPatch = Partial<WatchdogLspConfig>;
 
 export type WatchdogSettingsWriteScope = "user" | "project";
@@ -52,14 +44,13 @@ export interface WatchdogModelSettingsWrite {
 	thinking?: ThinkingLevel | false | null;
 }
 
-type WatchdogConfigPatch = Partial<Omit<ResolvedWatchdogConfig, "guidance" | "autoFollow" | "scope" | "cadence" | "main" | "children" | "asyncCompletion" | "lsp">> & {
+type WatchdogConfigPatch = Partial<Omit<ResolvedWatchdogConfig, "guidance" | "scope" | "cadence" | "main" | "children" | "lsp" | "rules">> & {
+	rules?: WatchdogRulesConfig;
 	guidance?: WatchdogGuidancePatch;
-	autoFollow?: WatchdogAutoFollowPatch;
 	scope?: WatchdogScopePatch;
 	cadence?: WatchdogCadencePatch;
 	main?: WatchdogEndpointPatch;
 	children?: WatchdogChildrenPatch;
-	asyncCompletion?: WatchdogAsyncCompletionPatch;
 	lsp?: WatchdogLspPatch;
 };
 
@@ -70,22 +61,13 @@ interface ParseMeta {
 
 export const DEFAULT_WATCHDOG_CONFIG: ResolvedWatchdogConfig = {
 	enabled: false,
-	delivery: "held",
-	showDuringRun: false,
-	syncBacklog: "off",
 	agentEndTimeoutMs: 30_000,
-	lateWarningPolicy: "show-stale-no-autofollow",
 	severityThreshold: "concern",
 	maxWarnings: null,
 	guidance: {
 		watchdogMd: true,
-		systemPromptPath: null,
-	},
-	autoFollow: {
-		blockers: true,
-		maxAttempts: 3,
-		stalemateRepeats: 3,
 	},
+	stalemateRepeats: 3,
 	scope: {
 		enabled: true,
 	},
@@ -98,73 +80,51 @@ export const DEFAULT_WATCHDOG_CONFIG: ResolvedWatchdogConfig = {
 	children: {
 		enabled: false,
 		watchdogTailTimeoutMs: 120_000,
-		autoFollow: {
-			blockers: true,
-			maxAttempts: 3,
-			stalemateRepeats: 3,
-		},
 		overrides: {},
 	},
-	asyncCompletion: {
-		enabled: false,
-		autoFollowBlockers: false,
-	},
 	lsp: {
 		enabled: true,
 		timeoutMs: 3_000,
 		maxFiles: 20,
 		maxDiagnostics: 50,
 	},
-	compactAtPercent: 80,
-	reviewRetryDelayMs: 1_000,
-	maxReviewFailures: 3,
 };
 
 const WATCHDOG_FIELDS = new Set([
 	"enabled",
-	"delivery",
-	"showDuringRun",
-	"syncBacklog",
 	"agentEndTimeoutMs",
-	"lateWarningPolicy",
 	"severityThreshold",
 	"maxWarnings",
 	"guidance",
-	"autoFollow",
+	"stalemateRepeats",
 	"scope",
 	"cadence",
 	"main",
 	"children",
-	"asyncCompletion",
 	"lsp",
-	"compactAtPercent",
-	"reviewRetryDelayMs",
-	"maxReviewFailures",
+	"rules",
 ]);
-const GUIDANCE_FIELDS = new Set(["watchdogMd", "systemPromptPath"]);
-const AUTO_FOLLOW_FIELDS = new Set(["blockers", "maxAttempts", "stalemateRepeats"]);
+const RULES_FIELDS = new Set(["action", "roleModels"]);
+const ROLE_MODEL_RULE_FIELDS = new Set(["allow", "deny", "note"]);
+const GUIDANCE_FIELDS = new Set(["watchdogMd"]);
 const SCOPE_FIELDS = new Set(["enabled"]);
 const CADENCE_FIELDS = new Set(["everyNTools"]);
 const ENDPOINT_FIELDS = new Set(["enabled", "model", "thinking"]);
-const CHILDREN_FIELDS = new Set(["enabled", "model", "thinking", "watchdogTailTimeoutMs", "autoFollow", "overrides"]);
-const CHILD_OVERRIDE_FIELDS = new Set(["enabled", "model", "thinking"]);
-const ASYNC_COMPLETION_FIELDS = new Set(["enabled", "autoFollowBlockers"]);
+const CHILDREN_FIELDS = new Set(["enabled", "model", "thinking", "watchdogTailTimeoutMs", "cadence", "overrides"]);
+const CHILD_OVERRIDE_FIELDS = new Set(["enabled", "model", "thinking", "cadence"]);
 const LSP_FIELDS = new Set(["enabled", "timeoutMs", "maxFiles", "maxDiagnostics"]);
 
 function cloneDefaultConfig(): ResolvedWatchdogConfig {
 	return {
 		...DEFAULT_WATCHDOG_CONFIG,
 		guidance: { ...DEFAULT_WATCHDOG_CONFIG.guidance },
-		autoFollow: { ...DEFAULT_WATCHDOG_CONFIG.autoFollow },
 		scope: { ...DEFAULT_WATCHDOG_CONFIG.scope },
 		cadence: { ...DEFAULT_WATCHDOG_CONFIG.cadence },
 		main: { ...DEFAULT_WATCHDOG_CONFIG.main },
 		children: {
 			...DEFAULT_WATCHDOG_CONFIG.children,
-			autoFollow: { ...DEFAULT_WATCHDOG_CONFIG.children.autoFollow },
 			overrides: {},
 		},
-		asyncCompletion: { ...DEFAULT_WATCHDOG_CONFIG.asyncCompletion },
 		lsp: { ...DEFAULT_WATCHDOG_CONFIG.lsp },
 	};
 }
@@ -227,35 +187,11 @@ function parseEnum<T extends string>(value: unknown, field: string, meta: ParseM
 	throw invalid(meta, field, values.map((item) => `'${item}'`).join(" or "));
 }
 
-function parseSyncBacklog(value: unknown, field: string, meta: ParseMeta): WatchdogSyncBacklog {
-	if (value === "off") return "off";
-	return parseInteger(value, field, meta, "'off' or a positive integer", (candidate) => candidate >= 1);
-}
-
 function parseGuidancePatch(value: unknown, field: string, meta: ParseMeta): WatchdogGuidancePatch {
 	const input = parseObject(value, field, meta);
 	assertKnownFields(input, GUIDANCE_FIELDS, field, meta);
 	const patch: WatchdogGuidancePatch = {};
 	if ("watchdogMd" in input) patch.watchdogMd = parseBoolean(input.watchdogMd, `${field}.watchdogMd`, meta);
-	if ("systemPromptPath" in input) {
-		patch.systemPromptPath = input.systemPromptPath === null
-			? null
-			: parseNonEmptyString(input.systemPromptPath, `${field}.systemPromptPath`, meta);
-	}
-	return patch;
-}
-
-function parseAutoFollowPatch(value: unknown, field: string, meta: ParseMeta): WatchdogAutoFollowPatch {
-	const input = parseObject(value, field, meta);
-	assertKnownFields(input, AUTO_FOLLOW_FIELDS, field, meta);
-	const patch: WatchdogAutoFollowPatch = {};
-	if ("blockers" in input) patch.blockers = parseBoolean(input.blockers, `${field}.blockers`, meta);
-	if ("maxAttempts" in input) {
-		patch.maxAttempts = parseNullableInteger(input.maxAttempts, `${field}.maxAttempts`, meta, "null or a positive integer", (candidate) => candidate >= 1);
-	}
-	if ("stalemateRepeats" in input) {
-		patch.stalemateRepeats = parseInteger(input.stalemateRepeats, `${field}.stalemateRepeats`, meta, "a positive integer", (candidate) => candidate >= 1);
-	}
 	return patch;
 }
 
@@ -296,6 +232,7 @@ function parseChildOverridePatch(value: unknown, field: string, meta: ParseMeta)
 	if ("enabled" in input) patch.enabled = parseBoolean(input.enabled, `${field}.enabled`, meta);
 	if ("model" in input) patch.model = parseNonEmptyString(input.model, `${field}.model`, meta);
 	if ("thinking" in input) patch.thinking = parseThinking(input.thinking, `${field}.thinking`, meta);
+	if ("cadence" in input) patch.cadence = parseCadencePatch(input.cadence, `${field}.cadence`, meta);
 	return patch;
 }
 
@@ -309,7 +246,7 @@ function parseChildrenPatch(value: unknown, field: string, meta: ParseMeta): Wat
 	if ("watchdogTailTimeoutMs" in input) {
 		patch.watchdogTailTimeoutMs = parseInteger(input.watchdogTailTimeoutMs, `${field}.watchdogTailTimeoutMs`, meta, "a positive integer", (candidate) => candidate >= 1);
 	}
-	if ("autoFollow" in input) patch.autoFollow = parseAutoFollowPatch(input.autoFollow, `${field}.autoFollow`, meta);
+	if ("cadence" in input) patch.cadence = parseCadencePatch(input.cadence, `${field}.cadence`, meta);
 	if ("overrides" in input) {
 		const overrides = parseObject(input.overrides, `${field}.overrides`, meta);
 		patch.overrides = {};
@@ -321,15 +258,6 @@ function parseChildrenPatch(value: unknown, field: string, meta: ParseMeta): Wat
 	return patch;
 }
 
-function parseAsyncCompletionPatch(value: unknown, field: string, meta: ParseMeta): WatchdogAsyncCompletionPatch {
-	const input = parseObject(value, field, meta);
-	assertKnownFields(input, ASYNC_COMPLETION_FIELDS, field, meta);
-	const patch: WatchdogAsyncCompletionPatch = {};
-	if ("enabled" in input) patch.enabled = parseBoolean(input.enabled, `${field}.enabled`, meta);
-	if ("autoFollowBlockers" in input) patch.autoFollowBlockers = parseBoolean(input.autoFollowBlockers, `${field}.autoFollowBlockers`, meta);
-	return patch;
-}
-
 function parseLspPatch(value: unknown, field: string, meta: ParseMeta): WatchdogLspPatch {
 	const input = parseObject(value, field, meta);
 	assertKnownFields(input, LSP_FIELDS, field, meta);
@@ -341,20 +269,43 @@ function parseLspPatch(value: unknown, field: string, meta: ParseMeta): Watchdog
 	return patch;
 }
 
+function parseStringList(value: unknown, field: string, meta: ParseMeta): string[] {
+	if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string" || !entry.trim())) throw invalid(meta, field, "an array of non-empty strings");
+	return value.map((entry: string) => entry.trim());
+}
+
+function parseRoleModelRule(value: unknown, field: string, meta: ParseMeta): WatchdogRoleModelRule {
+	const input = parseObject(value, field, meta);
+	assertKnownFields(input, ROLE_MODEL_RULE_FIELDS, field, meta);
+	const rule: WatchdogRoleModelRule = {};
+	if ("allow" in input) rule.allow = parseStringList(input.allow, `${field}.allow`, meta);
+	if ("deny" in input) rule.deny = parseStringList(input.deny, `${field}.deny`, meta);
+	if ("note" in input) rule.note = parseNonEmptyString(input.note, `${field}.note`, meta);
+	return rule;
+}
+
+function parseRules(value: unknown, field: string, meta: ParseMeta): WatchdogRulesConfig {
+	const input = parseObject(value, field, meta);
+	assertKnownFields(input, RULES_FIELDS, field, meta);
+	const rules: WatchdogRulesConfig = { action: "warn", roleModels: {} };
+	if ("action" in input) rules.action = parseEnum(input.action, `${field}.action`, meta, ["warn", "block"] as const);
+	if ("roleModels" in input) {
+		for (const [agent, rule] of Object.entries(parseObject(input.roleModels, `${field}.roleModels`, meta))) {
+			if (!agent.trim()) throw invalid(meta, `${field}.roleModels`, "agent names to be non-empty");
+			rules.roleModels[agent] = parseRoleModelRule(rule, `${field}.roleModels.${agent}`, meta);
+		}
+	}
+	return rules;
+}
+
 function parseWatchdogPatch(value: unknown, field: string, meta: ParseMeta): WatchdogConfigPatch {
 	const input = parseObject(value, field, meta);
 	assertKnownFields(input, WATCHDOG_FIELDS, field, meta);
 	const patch: WatchdogConfigPatch = {};
 	if ("enabled" in input) patch.enabled = parseBoolean(input.enabled, `${field}.enabled`, meta);
-	if ("delivery" in input) patch.delivery = parseEnum<WatchdogDeliveryMode>(input.delivery, `${field}.delivery`, meta, WATCHDOG_DELIVERY_MODES);
-	if ("showDuringRun" in input) patch.showDuringRun = parseBoolean(input.showDuringRun, `${field}.showDuringRun`, meta);
-	if ("syncBacklog" in input) patch.syncBacklog = parseSyncBacklog(input.syncBacklog, `${field}.syncBacklog`, meta);
 	if ("agentEndTimeoutMs" in input) {
 		patch.agentEndTimeoutMs = parseInteger(input.agentEndTimeoutMs, `${field}.agentEndTimeoutMs`, meta, "a positive integer", (candidate) => candidate >= 1);
 	}
-	if ("lateWarningPolicy" in input) {
-		patch.lateWarningPolicy = parseEnum<WatchdogLateWarningPolicy>(input.lateWarningPolicy, `${field}.lateWarningPolicy`, meta, WATCHDOG_LATE_WARNING_POLICIES);
-	}
 	if ("severityThreshold" in input) {
 		patch.severityThreshold = parseEnum<WatchdogSeverity>(input.severityThreshold, `${field}.severityThreshold`, meta, WATCHDOG_WARNING_SEVERITIES);
 	}
@@ -362,22 +313,15 @@ function parseWatchdogPatch(value: unknown, field: string, meta: ParseMeta): Wat
 		patch.maxWarnings = parseNullableInteger(input.maxWarnings, `${field}.maxWarnings`, meta, "null or a non-negative integer", (candidate) => candidate >= 0);
 	}
 	if ("guidance" in input) patch.guidance = parseGuidancePatch(input.guidance, `${field}.guidance`, meta);
-	if ("autoFollow" in input) patch.autoFollow = parseAutoFollowPatch(input.autoFollow, `${field}.autoFollow`, meta);
+	if ("stalemateRepeats" in input) {
+		patch.stalemateRepeats = parseInteger(input.stalemateRepeats, `${field}.stalemateRepeats`, meta, "a positive integer", (candidate) => candidate >= 1);
+	}
 	if ("scope" in input) patch.scope = parseScopePatch(input.scope, `${field}.scope`, meta);
 	if ("cadence" in input) patch.cadence = parseCadencePatch(input.cadence, `${field}.cadence`, meta);
 	if ("main" in input) patch.main = parseEndpointPatch(input.main, `${field}.main`, meta);
 	if ("children" in input) patch.children = parseChildrenPatch(input.children, `${field}.children`, meta);
-	if ("asyncCompletion" in input) patch.asyncCompletion = parseAsyncCompletionPatch(input.asyncCompletion, `${field}.asyncCompletion`, meta);
 	if ("lsp" in input) patch.lsp = parseLspPatch(input.lsp, `${field}.lsp`, meta);
-	if ("compactAtPercent" in input) {
-		patch.compactAtPercent = parseInteger(input.compactAtPercent, `${field}.compactAtPercent`, meta, "an integer from 50 through 95", (candidate) => candidate >= 50 && candidate <= 95);
-	}
-	if ("reviewRetryDelayMs" in input) {
-		patch.reviewRetryDelayMs = parseInteger(input.reviewRetryDelayMs, `${field}.reviewRetryDelayMs`, meta, "a positive integer", (candidate) => candidate >= 1);
-	}
-	if ("maxReviewFailures" in input) {
-		patch.maxReviewFailures = parseInteger(input.maxReviewFailures, `${field}.maxReviewFailures`, meta, "a positive integer", (candidate) => candidate >= 1);
-	}
+	if ("rules" in input) patch.rules = parseRules(input.rules, `${field}.rules`, meta);
 	return patch;
 }
 

package/src/watchdog/types.ts

@@ -18,7 +18,7 @@ export type WatchdogCategory = typeof WATCHDOG_WARNING_CATEGORIES[number];
 export const WATCHDOG_WARNING_CONFIDENCES = ["medium", "high"] as const;
 export type WatchdogConfidence = typeof WATCHDOG_WARNING_CONFIDENCES[number];
 
-export const WATCHDOG_WARNING_SOURCES = ["main", "child", "async-completion", "lsp"] as const;
+export const WATCHDOG_WARNING_SOURCES = ["main", "child", "lsp"] as const;
 export type WatchdogWarningSource = typeof WATCHDOG_WARNING_SOURCES[number];
 
 export const WATCHDOG_LSP_DIAGNOSTIC_SEVERITIES = ["error", "warning", "info", "hint"] as const;
@@ -42,14 +42,6 @@ export const WATCHDOG_WARNING_STATES = [
 ] as const;
 export type WatchdogWarningState = typeof WATCHDOG_WARNING_STATES[number];
 
-export const WATCHDOG_LATE_WARNING_POLICIES = ["show-stale-no-autofollow"] as const;
-export type WatchdogLateWarningPolicy = typeof WATCHDOG_LATE_WARNING_POLICIES[number];
-
-export const WATCHDOG_DELIVERY_MODES = ["held"] as const;
-export type WatchdogDeliveryMode = typeof WATCHDOG_DELIVERY_MODES[number];
-
-export type WatchdogSyncBacklog = "off" | number;
-
 export interface WatchdogWarning {
 	severity: WatchdogSeverity;
 	summary: string;
@@ -61,7 +53,6 @@ export interface WatchdogWarning {
 	agent?: string;
 	runId?: string;
 	stale?: boolean;
-	autoFollowAttempt?: number;
 	state?: WatchdogWarningState;
 }
 
@@ -81,15 +72,8 @@ export interface WatchdogWarningMessage {
 	details: WatchdogWarningDetails;
 }
 
-export interface WatchdogAutoFollowConfig {
-	blockers: boolean;
-	maxAttempts: number | null;
-	stalemateRepeats: number;
-}
-
 export interface WatchdogGuidanceConfig {
 	watchdogMd: boolean;
-	systemPromptPath: string | null;
 }
 
 export interface WatchdogScopeConfig {
@@ -110,19 +94,16 @@ export interface WatchdogChildOverrideConfig {
 	enabled?: boolean;
 	model?: string;
 	thinking?: string | false;
+	cadence?: Partial<WatchdogCadenceConfig>;
 }
 
 export interface WatchdogChildrenConfig extends WatchdogEndpointConfig {
 	watchdogTailTimeoutMs: number;
-	autoFollow: WatchdogAutoFollowConfig;
+	/** Mid-run cadence for child watchdogs; defaults to the top-level cadence. */
+	cadence?: Partial<WatchdogCadenceConfig>;
 	overrides: Record<string, WatchdogChildOverrideConfig>;
 }
 
-export interface WatchdogAsyncCompletionConfig {
-	enabled: boolean;
-	autoFollowBlockers: boolean;
-}
-
 export interface WatchdogLspConfig {
 	enabled: boolean;
 	timeoutMs: number;
@@ -156,26 +137,31 @@ export interface WatchdogLspRuntimeSnapshot extends WatchdogLspResult {
 	updatedAt?: string;
 }
 
+export interface WatchdogRoleModelRule {
+	allow?: string[];
+	deny?: string[];
+	note?: string;
+}
+
+export interface WatchdogRulesConfig {
+	action: "warn" | "block";
+	roleModels: Record<string, WatchdogRoleModelRule>;
+}
+
 export interface ResolvedWatchdogConfig {
 	enabled: boolean;
-	delivery: WatchdogDeliveryMode;
-	showDuringRun: boolean;
-	syncBacklog: WatchdogSyncBacklog;
 	agentEndTimeoutMs: number;
-	lateWarningPolicy: WatchdogLateWarningPolicy;
 	severityThreshold: WatchdogSeverity;
 	maxWarnings: number | null;
 	guidance: WatchdogGuidanceConfig;
-	autoFollow: WatchdogAutoFollowConfig;
+	/** Consecutive identical boundary warnings before the watchdog stops continuing the run. */
+	stalemateRepeats: number;
 	scope: WatchdogScopeConfig;
 	cadence: WatchdogCadenceConfig;
 	main: WatchdogEndpointConfig;
 	children: WatchdogChildrenConfig;
-	asyncCompletion: WatchdogAsyncCompletionConfig;
 	lsp: WatchdogLspConfig;
-	compactAtPercent: number;
-	reviewRetryDelayMs: number;
-	maxReviewFailures: number;
+	rules?: WatchdogRulesConfig;
 }
 
 export interface WatchdogSettingsError {

package/src/watchdog/warning-format.ts

@@ -44,7 +44,6 @@ export function formatWatchdogWarningContent(warning: WatchdogWarning): string {
 		tag("run_id", details.runId),
 		tag("state", details.state),
 		tag("stale", details.stale),
-		tag("auto_follow_attempt", details.autoFollowAttempt),
 	];
 	return [
 		`<subagent_watchdog ${attrs.join(" ")}>`,

package/src/workflows/chat-progress.ts

@@ -2,6 +2,7 @@ import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { Details, WorkflowPreflightLaneV1, WorkflowPreflightV1 } from "../shared/types.ts";
+import { workflowPreflightLaneForRuntimeKey } from "./workflow-preflight.ts";
 
 export const WORKFLOW_CHAT_PROGRESS_MODES = ["auto", "off", "live-card"] as const;
 export type WorkflowChatProgressMode = typeof WORKFLOW_CHAT_PROGRESS_MODES[number];
@@ -111,7 +112,6 @@ function cleanLabel(value: unknown): string | undefined {
 
 export function buildWorkflowChatProgressRows(trace: NonNullable<Details["workflow"]>["trace"], preflight?: WorkflowPreflightV1): WorkflowChatProgressRow[] {
 	const rows = new Map<string, WorkflowChatProgressRow>();
-	for (const lane of preflight?.lanes ?? []) rows.set(lane.key, { key: lane.key, state: "planned", preflight: lane });
 	for (const entry of trace) {
 		if (entry.operation !== "run") continue;
 		const existing = rows.get(entry.key);
@@ -124,8 +124,9 @@ export function buildWorkflowChatProgressRows(trace: NonNullable<Details["workfl
 			}
 			continue;
 		}
+		const lane = workflowPreflightLaneForRuntimeKey(preflight, entry.key, [entry.generatedLaneKey]);
 		const next: WorkflowChatProgressRow = existing ?? { key: entry.key, state: "running" };
-		if (existing?.preflight) next.preflight = existing.preflight;
+		if (lane && !next.preflight) next.preflight = lane;
 		next.state = entry.state === "completed"
 			? "complete"
 			: entry.state === "failed"

package/src/workflows/workflow-checklist.ts

@@ -1,5 +1,6 @@
 import type { AsyncJobStep, HostStepNodeV1, WorkflowGraphNode, WorkflowGraphSnapshot, WorkflowPreflightLaneV1, WorkflowPreflightV1 } from "../shared/types.ts";
 import { sanitizeDisplayText } from "../shared/display-text.ts";
+import { workflowPreflightLaneForRuntimeKey } from "./workflow-preflight.ts";
 
 export type WorkflowChecklistState = "complete" | "running" | "queued" | "blocked" | "failed" | "paused" | "stopped";
 
@@ -189,8 +190,8 @@ function duration(step: Pick<WorkflowChecklistStep, "durationMs" | "startedAt" |
 	return end === undefined ? undefined : Math.max(0, end - startedAt);
 }
 
-function laneFor(key: string, phase: string, lanes: ReadonlyMap<string, WorkflowPreflightLaneV1>): WorkflowPreflightLaneV1 | undefined {
-	return lanes.get(key) ?? lanes.get(phase) ?? [...lanes.values()].find((lane) => key.startsWith(`${lane.key}.`));
+function laneFor(preflight: WorkflowPreflightV1 | undefined, key: string, preferredKeys: readonly (string | undefined)[] = []): WorkflowPreflightLaneV1 | undefined {
+	return workflowPreflightLaneForRuntimeKey(preflight, key, preferredKeys);
 }
 
 function stepKey(step: WorkflowChecklistStep): string | undefined {
@@ -264,7 +265,7 @@ function traceSources(trace: readonly WorkflowChecklistTraceEntry[] | undefined)
 }
 
 function traceItem(entry: WorkflowChecklistTraceEntry, index: number, preflight: WorkflowPreflightLaneV1 | undefined): WorkflowChecklistItem {
-	const phase = keyText(entry.generatedLaneKey ?? entry.phase ?? preflight?.key, "Workflow");
+	const phase = keyText(preflight?.key ?? entry.generatedLaneKey ?? entry.phase, "Workflow");
 	const item = stepItem({ key: entry.key, label: entry.label, phase, agent: entry.agent, status: entry.state === "started" ? "running" : entry.state, durationMs: entry.durationMs, error: entry.error }, index, phase, entry.key, entry.label ?? entry.key, preflight);
 	if (entry.operation === "host") item.kind = "host";
 	return item;
@@ -317,16 +318,13 @@ function finalize(phase: WorkflowChecklistPhase): void {
 
 export function projectWorkflowChecklist(input: WorkflowChecklistInput): WorkflowChecklistProjection {
 	const phases = new Map<string, WorkflowChecklistPhase>();
-	const lanes = new Map((input.preflight?.lanes ?? []).map((lane) => [lane.key, lane]));
 	const steps = (input.steps ?? []) as readonly WorkflowChecklistStep[];
 	const nodes = graphNodes(input.graph);
 	const trace = traceSources(input.trace);
 	const traceByKey = new Map(trace.map((entry) => [entry.key, entry]));
 	const phaseByNode = new Map<string, string>();
-	const graphPhaseLabels = new Set<string>();
 	for (const phase of input.graph?.phases ?? []) {
 		const title = keyText(phase.title, "Workflow");
-		graphPhaseLabels.add(title);
 		phaseFor(phases, title);
 		for (const nodeId of phase.nodeIds) if (!phaseByNode.has(nodeId)) phaseByNode.set(nodeId, title);
 	}
@@ -356,28 +354,28 @@ export function projectWorkflowChecklist(input: WorkflowChecklistInput): Workflo
 		if (matches.length) {
 			for (const match of matches) {
 				usedSteps.add(match.index);
-				add(phases, phase, applyNow(mergeNodeStep(node, match.step, phase, traceByKey.get(stepKey(match.step) ?? node.id), laneFor(node.id, phase, lanes)), input.now));
+				add(phases, phase, applyNow(mergeNodeStep(node, match.step, phase, traceByKey.get(stepKey(match.step) ?? node.id), laneFor(input.preflight, node.id, [phase])), input.now));
 			}
 			continue;
 		}
-		add(phases, phase, applyNow(mergeNodeStep(node, { key: node.id, label: node.label, phase, agent: node.agent, status: node.status, outputName: node.outputName, error: node.error, acceptance: node.acceptanceStatus ? { status: node.acceptanceStatus } : undefined }, phase, traceByKey.get(node.id), laneFor(node.id, phase, lanes)), input.now));
+		add(phases, phase, applyNow(mergeNodeStep(node, { key: node.id, label: node.label, phase, agent: node.agent, status: node.status, outputName: node.outputName, error: node.error, acceptance: node.acceptanceStatus ? { status: node.acceptanceStatus } : undefined }, phase, traceByKey.get(node.id), laneFor(input.preflight, node.id, [phase])), input.now));
 	}
 
 	for (const [index, step] of steps.entries()) {
 		if (usedSteps.has(index)) continue;
 		const key = keyText(stepKey(step), `step-${index + 1}`);
 		const traceEntry = traceByKey.get(key);
-		const phase = keyText(step.phase ?? laneFor(key, "", lanes)?.key ?? traceEntry?.generatedLaneKey ?? traceEntry?.phase, "Workflow");
-		add(phases, phase, applyNow(stepItem(step, index, phase, key, step.label ?? step.key ?? step.agent, laneFor(key, phase, lanes)), input.now));
+		const lane = laneFor(input.preflight, key, [step.phase, traceEntry?.generatedLaneKey, traceEntry?.phase]);
+		const phase = keyText(lane?.key ?? step.phase ?? traceEntry?.generatedLaneKey ?? traceEntry?.phase, "Workflow");
+		add(phases, phase, applyNow(stepItem(step, index, phase, key, step.label ?? step.key ?? step.agent, lane), input.now));
 	}
 
 	for (const host of hostById.values()) add(phases, keyText(host.label, "Host"), hostItem(host, keyText(host.label, "Host")));
 	for (const entry of trace) {
 		if (graphKeys.has(entry.key) || stepKeys.has(entry.key) || hostKeys.has(entry.key)) continue;
-		const item = traceItem(entry, phases.size, laneFor(entry.key, entry.generatedLaneKey ?? entry.phase ?? "", lanes));
+		const item = traceItem(entry, phases.size, laneFor(input.preflight, entry.key, [entry.generatedLaneKey, entry.phase]));
 		add(phases, item.phase, item);
 	}
-	for (const lane of input.preflight?.lanes ?? []) if (!graphKeys.has(lane.key) && !graphPhaseLabels.has(lane.key) && !phases.get(lane.key)?.items.length) add(phases, lane.key, { key: lane.key, label: lane.key, phase: lane.key, state: "queued", preflight: lane });
 
 	const finalized = [...phases.values()].filter((phase) => phase.items.length > 0);
 	for (const phase of finalized) {

package/src/workflows/workflow-preflight.ts

@@ -146,8 +146,35 @@ function declaredKeys(preflight: WorkflowPreflightV1): Set<string> {
  * Treat declared lane keys as plan roots: `lane` is the lane itself and
  * `lane.stage` is a stage by convention, even without generated provenance.
  */
+export function workflowKeyMatchesPreflightLane(key: string, laneKey: string, generatedLaneKey?: string): boolean {
+	return generatedLaneKey === laneKey || key === laneKey || key.startsWith(`${laneKey}.`);
+}
+
+/** Select the most specific advisory lane without allowing declaration order to override an exact runtime key. */
+export function workflowPreflightLaneForRuntimeKey(
+	preflight: WorkflowPreflightV1 | undefined,
+	key: string,
+	preferredKeys: readonly (string | undefined)[] = [],
+): WorkflowPreflightLaneV1 | undefined {
+	const lanes = preflight?.lanes;
+	if (!lanes) return undefined;
+	const exact = lanes.find((lane) => lane.key === key);
+	if (exact) return exact;
+	let closestRoot: WorkflowPreflightLaneV1 | undefined;
+	for (const lane of lanes) {
+		if (key.startsWith(`${lane.key}.`) && (!closestRoot || lane.key.length > closestRoot.key.length)) closestRoot = lane;
+	}
+	if (closestRoot) return closestRoot;
+	for (const preferredKey of preferredKeys) {
+		if (!preferredKey) continue;
+		const preferred = lanes.find((lane) => lane.key === preferredKey);
+		if (preferred) return preferred;
+	}
+	return undefined;
+}
+
 function declaredLaneCoversWorkflowKey(entry: WorkflowTraceLike, laneKey: string): boolean {
-	return entry.key === laneKey || entry.key.startsWith(`${laneKey}.`);
+	return workflowKeyMatchesPreflightLane(entry.key, laneKey, entry.generatedLaneKey);
 }
 
 function keyCoveredByDeclaredLane(entry: WorkflowTraceLike, declared: ReadonlySet<string>): boolean {