pi-subagents 0.63.0 → 0.65.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/scripted-workflow.ts

@@ -9,7 +9,14 @@ import type { AcceptanceRecoveryMetadata, HostStepNodeV1, SingleResult } from ".
 import { normalizeWorkflowHostCommandParams, type WorkflowHostCommandParams, type WorkflowHostCommandResult } from "./host-command.ts";
 
 const KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+function validGitRef(ref: unknown): ref is string {
+	if (typeof ref !== "string" || !ref || ref === "@" || Buffer.byteLength(ref, "utf-8") > 1024 || ref.startsWith("/") || ref.endsWith("/") || ref.includes("//") || ref.includes("..") || ref.includes("@{")) return false;
+	if (/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/iu.test(ref)) return false;
+	if (/[[\]\\~^:?*\u0000-\u0020\u007f]/u.test(ref) || ref.endsWith(".") || ref.endsWith(".lock")) return false;
+	return ref.split("/").every((component) => component.length > 0 && component !== "." && component !== ".." && !component.startsWith(".") && !component.endsWith(".") && !component.endsWith(".lock"));
+}
 const requireFromPackage = createRequire(import.meta.url);
+const WORKFLOW_ASSEMBLY_FLUSH_TIMEOUT_MS = 5_000;
 
 export interface WorkflowScriptValidationError {
 	message: string;
@@ -49,6 +56,12 @@ let suppressNativePromiseConsumption = 0;
 const activeNativePromises = [];
 const pending = new Map();
 const runKeyPattern = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+function validGitRef(ref) {
+  if (typeof ref !== "string" || !ref || ref === "@" || new TextEncoder().encode(ref).length > 1024 || ref.startsWith("/") || ref.endsWith("/") || ref.includes("//") || ref.includes("..") || ref.includes("@{")) return false;
+  if (/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/iu.test(ref)) return false;
+  if (/[[\]\\~^:?*\u0000-\u0020\u007f]/u.test(ref) || ref.endsWith(".") || ref.endsWith(".lock")) return false;
+  return ref.split("/").every((component) => component.length > 0 && component !== "." && component !== ".." && !component.startsWith(".") && !component.endsWith(".") && !component.endsWith(".lock"));
+}
 const trackedPromiseTrackers = new WeakMap();
 const trackedPromiseTargets = new WeakMap();
 let nativePromiseTrackers = new WeakMap();
@@ -611,6 +624,7 @@ function validateRunCall(key, params, label, fingerprints) {
   }
   if (Object.prototype.hasOwnProperty.call(params, "clarify")) throw new Error(label + " does not support clarify UI.");
   if (params.worktree !== undefined && typeof params.worktree !== "boolean") throw new Error(label + " worktree must be true or false.");
+  if (params.baseRef !== undefined && (typeof params.baseRef !== "string" || !validGitRef(params.baseRef))) throw new Error(label + " baseRef must be a valid Git ref.");
   validateLaneMetadata(params.lane, label + " lane", key);
   if (params.gate !== undefined && (typeof params.gate !== "string" || !params.gate.trim())) throw new Error(label + " gate must be a non-empty command string.");
   if (params.gate !== undefined && params.acceptance !== undefined) throw new Error(label + " gate cannot be combined with acceptance; use one gate command or acceptance.verify.");
@@ -1070,6 +1084,8 @@ export interface RunWorkflowScriptOptions {
 	oneUsePermit?: { claim: (key: string) => string | undefined };
 	timeoutMs?: number;
 	signal?: AbortSignal;
+	/** Let an async workflow flush pure result assembly after reload once every child is terminal. */
+	continueAfterAbortWhenChildrenSettled?: (abortError: Error) => boolean;
 	/** Maximum children executing concurrently within this workflow. Defaults to 20. */
 	globalConcurrencyLimit?: number;
 	admit?: (calls: Array<{ key: string; params: Record<string, unknown> }>) => void | Promise<void>;
@@ -1614,7 +1630,7 @@ function resolveWorkflowParserEntry(): string {
 	}
 }
 
-const AUTO_RESUME_PARAM_KEYS = ["acceptance", "agentContract", "index", "intercomBridge", "label", "lane", "maxRuntimeMs", "output", "outputMode", "outputSchema", "phase", "skill", "skills", "task", "timeoutMs", "toolBudget", "worktree"] as const;
+const AUTO_RESUME_PARAM_KEYS = ["acceptance", "agentContract", "baseRef", "index", "intercomBridge", "label", "lane", "maxRuntimeMs", "output", "outputMode", "outputSchema", "phase", "skill", "skills", "task", "timeoutMs", "toolBudget", "worktree"] as const;
 
 function isZeroUsage(usage: unknown): boolean {
 	if (!isRecord(usage)) return false;
@@ -1682,6 +1698,9 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 	let acceptanceRecoveryBarrier: { key: string } | undefined;
 	let settled = false;
 	let finishing = false;
+	let assemblyAbortRequested = false;
+	let assemblyFlushTimer: ReturnType<typeof setTimeout> | undefined;
+	let abortError: Error | undefined;
 
 	const partial = (): Omit<WorkflowScriptResult, "value"> => ({ emits, console: consoleEntries, trace, children: childOrder.flatMap((key) => {
 		const child = children.get(key);
@@ -1750,6 +1769,10 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 		const finish = (outcome: { value: unknown } | { error: Error & { workflowErrorKind?: unknown } }) => {
 			if (settled || finishing) return;
 			finishing = true;
+			if (assemblyFlushTimer !== undefined) {
+				clearTimeout(assemblyFlushTimer);
+				assemblyFlushTimer = undefined;
+			}
 			childController.abort("error" in outcome ? outcome.error : new Error("Workflow script completed."));
 			void Promise.allSettled([...steers.values(), ...hostCalls.values()].map(({ promise }) => promise)).then(() => {
 				if (settled) return;
@@ -1781,6 +1804,26 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 				: typeof signalReason === "string"
 					? new Error(signalReason)
 					: new Error("Workflow script aborted.");
+			if (finishing) return;
+			abortError = error;
+			const allChildrenSettled = launches.size > 0
+				&& [...launches.keys()].every((key) => children.has(key));
+			let mayFlushAssembly = false;
+			try {
+				mayFlushAssembly = options.continueAfterAbortWhenChildrenSettled?.(error) === true;
+			} catch (callbackError) {
+				const callbackMessage = callbackError instanceof Error ? callbackError.message : String(callbackError);
+				return finish({ error: new Error(`Workflow assembly flush eligibility failed: ${callbackMessage}`) });
+			}
+			if (mayFlushAssembly && allChildrenSettled) {
+				// A reloaded async workflow may already be past its last child launch.
+				// Keep the worker alive for pure result assembly, but abort the child
+				// signal so any later launch or side effect cannot use stale context.
+				assemblyAbortRequested = true;
+				childController.abort(error);
+				assemblyFlushTimer = setTimeout(() => finish({ error }), WORKFLOW_ASSEMBLY_FLUSH_TIMEOUT_MS);
+				return;
+			}
 			for (const key of launches.keys()) {
 				if (children.has(key)) continue;
 				stoppedLaunches.add(key);
@@ -1873,6 +1916,7 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 				return;
 			}
 			if (message.type !== "call" || typeof message.callId !== "number" || typeof message.method !== "string" || !isRecord(message.args)) return;
+			if (assemblyAbortRequested) return finish({ error: abortError ?? new Error("Workflow context was replaced or reloaded.") });
 
 			const respond = (promise: Promise<unknown>, responsePath?: string, onBoundaryError?: (error: unknown) => void) => {
 				void promise.then(
@@ -2059,6 +2103,9 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 			if (params.worktree !== undefined && typeof params.worktree !== "boolean") {
 				return respond(Promise.reject(new Error(`runs.run('${key}') worktree must be true or false.`)));
 			}
+			if (params.baseRef !== undefined && (typeof params.baseRef !== "string" || !validGitRef(params.baseRef))) {
+				return respond(Promise.reject(new Error(`runs.run('${key}') baseRef must be a valid Git ref.`)));
+			}
 			if (params.gate !== undefined && (typeof params.gate !== "string" || !params.gate.trim())) {
 				return respond(Promise.reject(new Error(`runs.run('${key}') gate must be a non-empty command string.`)));
 			}

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) {