pi-subagents 0.58.0 → 0.59.0

package/src/runs/shared/completion-evidence.ts

@@ -0,0 +1,89 @@
+import type {
+	FileMutationEffect,
+	SettlementDiagnostic,
+	TrackedMutationEvidence,
+} from "../../shared/types.ts";
+import type { CompletionMutationGuardResult } from "./completion-guard.ts";
+
+export const MISSING_IMPLEMENTATION_MUTATION_MESSAGE = "Subagent completed without making edits for an implementation task.";
+export const MISSING_IMPLEMENTATION_MUTATION_ERROR = `${MISSING_IMPLEMENTATION_MUTATION_MESSAGE}\nIt appears to have returned planning or scratchpad output instead of applying changes.`;
+
+export interface CompletionEvidencePlan {
+	guardTriggered: boolean;
+	guardBlocked: boolean;
+	mutationExpected: boolean;
+	mutationAttempted: boolean;
+	fileMutation?: FileMutationEffect;
+	legacyFailureError?: string;
+}
+
+export function planCompletionEvidence(input: {
+	guard?: CompletionMutationGuardResult;
+	guardTriggered?: boolean;
+	completionGuardEnabled: boolean;
+	mutationCapable: boolean;
+	implementationMutationExpected: boolean;
+	mutationAttemptObserved: boolean;
+	mutationEvidence?: TrackedMutationEvidence;
+	arbiterRescued?: boolean;
+	agentContractV1: boolean;
+}): CompletionEvidencePlan {
+	const guardBlocked = input.guard?.blocked === true;
+	const guardTriggered = input.guardTriggered
+		?? (input.guard?.triggered === true && !input.mutationAttemptObserved);
+	const mutationExpected = input.guard?.expectedMutation
+		?? (input.completionGuardEnabled && input.mutationCapable && input.implementationMutationExpected);
+	const mutationAttempted = input.guard?.attemptedMutation === true || input.mutationAttemptObserved;
+	const fileMutation = input.guard
+		? {
+			status: guardBlocked
+				? "blocked" as const
+				: input.guard.expectedMutation
+					? guardTriggered
+						? "missing" as const
+						: input.arbiterRescued
+							? "not-applicable" as const
+							: "observed" as const
+					: "not-applicable" as const,
+			expected: input.guard.expectedMutation,
+			attempted: guardBlocked ? false : mutationAttempted,
+			...(input.mutationEvidence ? { evidence: input.mutationEvidence } : {}),
+			...(guardBlocked && input.guard.message ? { message: input.guard.message } : {}),
+			...(guardTriggered ? { message: MISSING_IMPLEMENTATION_MUTATION_MESSAGE } : {}),
+			...(input.arbiterRescued ? { resolvedBy: "llm-intent-arbiter" as const } : {}),
+		}
+		: undefined;
+	return {
+		guardTriggered,
+		guardBlocked,
+		mutationExpected,
+		mutationAttempted,
+		fileMutation,
+		legacyFailureError: guardTriggered && !input.agentContractV1
+			? MISSING_IMPLEMENTATION_MUTATION_ERROR
+			: undefined,
+	};
+}
+
+export function projectSettlementDiagnostic(
+	plan: Pick<CompletionEvidencePlan, "guardTriggered" | "guardBlocked" | "mutationExpected" | "mutationAttempted">,
+	input: {
+		terminalFailed: boolean;
+		finalTextPresent: boolean;
+		mutationObserved: boolean;
+		requiredOutput?: SettlementDiagnostic["requiredOutput"];
+		afterCompactionSettlement?: boolean;
+	},
+): SettlementDiagnostic | undefined {
+	if (!input.terminalFailed && !plan.guardTriggered && !plan.guardBlocked) return undefined;
+	return {
+		finalTextPresent: input.finalTextPresent,
+		mutation: {
+			expected: plan.mutationExpected,
+			attempted: plan.mutationAttempted,
+			observed: input.mutationObserved,
+		},
+		...(input.requiredOutput ? { requiredOutput: input.requiredOutput } : {}),
+		afterCompactionSettlement: input.afterCompactionSettlement === true,
+	};
+}

package/src/runs/shared/completion-guard.ts

@@ -52,7 +52,7 @@ interface CompletionMutationGuardInput {
 	mutationEvidence?: TrackedMutationEvidence;
 }
 
-interface CompletionMutationGuardResult {
+export interface CompletionMutationGuardResult {
 	expectedMutation: boolean;
 	attemptedMutation: boolean;
 	triggered: boolean;

package/src/runs/shared/dynamic-fanout.ts

@@ -49,8 +49,8 @@ const DYNAMIC_EXPAND_FROM_KEYS = new Set(["output", "path"]);
 const DYNAMIC_PARALLEL_KEYS = new Set(["agent", "task", "phase", "label", "outputSchema", "cwd", "output", "outputMode", "reads", "progress", "skill", "model", "fast", "toolBudget", "acceptance", "agentContract", "gateOn"]);
 const RUNNER_DYNAMIC_PARALLEL_KEYS = new Set([
 	...DYNAMIC_PARALLEL_KEYS,
-	"outputName", "structured", "inheritProjectContext", "inheritGlobalContext", "inheritSkills", "skills", "outputPath", "namespaceOutputPath", "maxSubagentDepth", "timeoutMs", "waitToolEnabled",
-	"structuredOutput", "structuredOutputSchema", "tools", "extensions", "subagentOnlyExtensions", "mcpDirectTools", "mutationTools", "capabilityCeiling", "completionGuard", "systemPrompt",
+	"outputName", "structured", "inheritProjectContext", "inheritGlobalContext", "inheritSkills", "skills", "outputPath", "namespaceOutputPath", "maxSubagentDepth", "timeoutMs", "waitToolEnabled", "waitToolDefaultTimeoutMs",
+	"structuredOutput", "structuredOutputSchema", "tools", "allowNestedSubagents", "extensions", "subagentOnlyExtensions", "mcpDirectTools", "mutationTools", "capabilityCeiling", "completionGuard", "systemPrompt",
 	"systemPromptMode", "thinking", "modelCandidates", "sessionFile", "effectiveAcceptance", "acceptanceInput", "acceptanceRole", "parentSessionId", "launchResolvedExtensions", "requestedCwd",
 ]);
 const DYNAMIC_COLLECT_KEYS = new Set(["as", "outputSchema"]);

package/src/runs/shared/host-step-status.ts

@@ -0,0 +1,230 @@
+import type {
+	AsyncStatus,
+	HostStepNodeV1,
+	HostStepState,
+	HostStepVerdict,
+	WorkflowGraphNode,
+	WorkflowGraphSnapshot,
+	WorkflowNodeStatus,
+} from "../../shared/types.ts";
+
+export const HOST_STEP_MAX_ID_CHARS = 128;
+export const HOST_STEP_MAX_LABEL_CHARS = 80;
+export const HOST_STEP_MAX_ROLE_CHARS = 32;
+export const HOST_STEP_MAX_PROVIDER_CHARS = 64;
+export const HOST_STEP_MAX_REASON_CHARS = 64;
+export const HOST_STEP_MAX_DETAIL_CHARS = 200;
+export const HOST_STEP_MAX_TARGET_CHARS = 128;
+export const HOST_STEP_MAX_REF_CHARS = 128;
+export const HOST_STEP_MAX_REPORT_PATH_CHARS = 240;
+export const HOST_STEP_MAX_COUNT = 32;
+
+const HOST_STEP_FIELDS = new Set([
+	"version",
+	"kind",
+	"monitorKind",
+	"id",
+	"label",
+	"role",
+	"provider",
+	"state",
+	"verdict",
+	"reasonCode",
+	"detail",
+	"target",
+	"freshness",
+	"reportPath",
+	"exitCode",
+	"updatedAt",
+	"deadlineAt",
+]);
+
+const FRESHNESS_FIELDS = new Set(["expectedRef", "observedRef", "stale"]);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function assertBoundedString(value: unknown, field: string, maxChars: number, source: string, required = false): asserts value is string {
+	if (value === undefined && !required) return;
+	if (typeof value !== "string" || !value.trim()) throw new Error(`Invalid host step '${source}': ${field} must be a non-empty string.`);
+	if (value.length > maxChars) throw new Error(`Invalid host step '${source}': ${field} exceeds ${maxChars} characters.`);
+	if (/\r|\n/.test(value)) throw new Error(`Invalid host step '${source}': ${field} must be single-line.`);
+}
+
+function assertTimestamp(value: unknown, field: string, source: string, required = false): asserts value is number {
+	if (value === undefined && !required) return;
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) throw new Error(`Invalid host step '${source}': ${field} must be a non-negative safe integer.`);
+}
+
+function assertFreshness(value: unknown, source: string): asserts value is HostStepNodeV1["freshness"] {
+	if (!isRecord(value)) throw new Error(`Invalid host step '${source}': freshness must be an object.`);
+	const unknownFields = Object.keys(value).filter((field) => !FRESHNESS_FIELDS.has(field));
+	if (unknownFields.length > 0) throw new Error(`Invalid host step '${source}': freshness has unsupported fields: ${unknownFields.join(", ")}.`);
+	assertBoundedString(value.expectedRef, "freshness.expectedRef", HOST_STEP_MAX_REF_CHARS, source, true);
+	assertBoundedString(value.observedRef, "freshness.observedRef", HOST_STEP_MAX_REF_CHARS, source);
+	if (value.stale !== undefined && typeof value.stale !== "boolean") throw new Error(`Invalid host step '${source}': freshness.stale must be a boolean.`);
+}
+
+/**
+ * Validate the persisted host-step contract. This deliberately rejects unknown
+ * fields and unbounded values so status and receipt loaders fail closed.
+ */
+export function assertHostStepNode(value: unknown, source = "status"): asserts value is HostStepNodeV1 {
+	if (!isRecord(value)) throw new Error(`Invalid host step '${source}': expected an object.`);
+	const unknownFields = Object.keys(value).filter((field) => !HOST_STEP_FIELDS.has(field));
+	if (unknownFields.length > 0) throw new Error(`Invalid host step '${source}': unsupported fields: ${unknownFields.join(", ")}.`);
+	if (value.version !== 1) throw new Error(`Invalid host step '${source}': version must be 1.`);
+	if (value.kind !== "host-step") throw new Error(`Invalid host step '${source}': kind must be 'host-step'.`);
+	if (value.monitorKind !== "command" && value.monitorKind !== "ci" && value.monitorKind !== "gate") throw new Error(`Invalid host step '${source}': monitorKind must be 'command', 'ci', or 'gate'.`);
+	assertBoundedString(value.id, "id", HOST_STEP_MAX_ID_CHARS, source, true);
+	assertBoundedString(value.label, "label", HOST_STEP_MAX_LABEL_CHARS, source, true);
+	assertBoundedString(value.role, "role", HOST_STEP_MAX_ROLE_CHARS, source);
+	assertBoundedString(value.provider, "provider", HOST_STEP_MAX_PROVIDER_CHARS, source);
+	if (value.state !== "pending" && value.state !== "running" && value.state !== "done" && value.state !== "cancelled" && value.state !== "error") {
+		throw new Error(`Invalid host step '${source}': state is invalid.`);
+	}
+	if (value.verdict !== undefined && value.verdict !== "pass" && value.verdict !== "fail" && value.verdict !== "inconclusive") {
+		throw new Error(`Invalid host step '${source}': verdict is invalid.`);
+	}
+	if (value.state !== "done" && value.verdict !== undefined) throw new Error(`Invalid host step '${source}': verdict is only valid for done state.`);
+	assertBoundedString(value.reasonCode, "reasonCode", HOST_STEP_MAX_REASON_CHARS, source);
+	assertBoundedString(value.detail, "detail", HOST_STEP_MAX_DETAIL_CHARS, source);
+	assertBoundedString(value.target, "target", HOST_STEP_MAX_TARGET_CHARS, source);
+	if (value.freshness !== undefined) assertFreshness(value.freshness, source);
+	if (value.freshness && value.freshness.stale === true && (value.state !== "done" || value.verdict !== "inconclusive")) {
+		throw new Error(`Invalid host step '${source}': stale freshness requires done/inconclusive state.`);
+	}
+	assertBoundedString(value.reportPath, "reportPath", HOST_STEP_MAX_REPORT_PATH_CHARS, source);
+	const reportName = hostStepReportName(value.reportPath);
+	if (value.reportPath !== undefined && (!reportName || reportName === "." || reportName === "..")) throw new Error(`Invalid host step '${source}': reportPath must name a report.`);
+	if (value.exitCode !== undefined && value.exitCode !== null && (typeof value.exitCode !== "number" || !Number.isSafeInteger(value.exitCode) || value.exitCode < 0)) throw new Error(`Invalid host step '${source}': exitCode must be a non-negative safe integer or null.`);
+	if (value.monitorKind !== "command" && value.exitCode !== undefined) throw new Error(`Invalid host step '${source}': exitCode is only valid for command steps.`);
+	if ((value.state === "pending" || value.state === "running") && value.exitCode !== undefined) throw new Error(`Invalid host step '${source}': exitCode is only valid after command settlement.`);
+	assertTimestamp(value.updatedAt, "updatedAt", source, true);
+	assertTimestamp(value.deadlineAt, "deadlineAt", source);
+}
+
+export function parseHostStepNode(value: unknown, source = "status"): HostStepNodeV1 {
+	assertHostStepNode(value, source);
+	return {
+		...value,
+		...(value.freshness ? { freshness: { ...value.freshness } } : {}),
+	};
+}
+
+export function assertUniqueHostStepIds(hostSteps: readonly HostStepNodeV1[], source = "status"): void {
+	const ids = new Set<string>();
+	for (const hostStep of hostSteps) {
+		if (ids.has(hostStep.id)) throw new Error(`Invalid host step '${source}': duplicate host step id '${hostStep.id}'.`);
+		ids.add(hostStep.id);
+	}
+}
+
+/** Return only valid host nodes so an untrusted in-memory projection fails closed. */
+export function validHostStepNodes(graph: WorkflowGraphSnapshot | undefined): HostStepNodeV1[] {
+	const nodes = graph?.nodes ?? [];
+	const nodeIdCounts = new Map<string, number>();
+	for (const node of nodes) nodeIdCounts.set(node.id, (nodeIdCounts.get(node.id) ?? 0) + 1);
+	const hostSteps: HostStepNodeV1[] = [];
+	for (const [index, node] of nodes.entries()) {
+		if (node.kind !== "host-step") continue;
+		try {
+			const hostStep = parseHostStepNode(node.hostStep, `workflowGraph.nodes[${index}].hostStep`);
+			if (node.id !== hostStep.id || node.label !== hostStep.label) continue;
+			if (nodeIdCounts.get(hostStep.id) !== 1) continue;
+			hostSteps.push(hostStep);
+		} catch {
+			// Renderers must not turn malformed host data into a fake child row.
+		}
+	}
+	return hostSteps.slice(0, HOST_STEP_MAX_COUNT);
+}
+
+export function assertWorkflowGraphHostSteps(graph: WorkflowGraphSnapshot | undefined, source = "status", expectedRunId?: string): void {
+	if (!graph) return;
+	if (expectedRunId !== undefined && graph.runId !== expectedRunId) throw new Error(`Invalid host step '${source}': workflowGraph.runId does not match the status run id.`);
+	const hostStepCount = graph.nodes.filter((node) => node.kind === "host-step").length;
+	if (hostStepCount > HOST_STEP_MAX_COUNT) throw new Error(`Invalid host step '${source}': workflowGraph contains more than ${HOST_STEP_MAX_COUNT} host steps.`);
+	const hostSteps: HostStepNodeV1[] = [];
+	for (const [index, node] of graph.nodes.entries()) {
+		if (node.kind !== "host-step") continue;
+		const hostStep = parseHostStepNode(node.hostStep, `${source}.workflowGraph.nodes[${index}].hostStep`);
+		if (node.id !== hostStep.id) throw new Error(`Invalid host step '${source}': workflowGraph.nodes[${index}].id does not match hostStep.id.`);
+		if (node.label !== hostStep.label) throw new Error(`Invalid host step '${source}': workflowGraph.nodes[${index}].label does not match hostStep.label.`);
+		hostSteps.push(hostStep);
+	}
+	assertUniqueHostStepIds(hostSteps, source);
+	for (const hostStep of hostSteps) {
+		if (graph.nodes.filter((node) => node.id === hostStep.id).length !== 1) throw new Error(`Invalid host step '${source}': workflowGraph id '${hostStep.id}' is not unique.`);
+	}
+}
+
+export function hostStepWorkflowNode(hostStep: HostStepNodeV1): WorkflowGraphNode {
+	assertHostStepNode(hostStep, hostStep.id);
+	return {
+		id: hostStep.id,
+		kind: "host-step",
+		label: hostStep.label,
+		status: workflowNodeStatus(hostStep),
+		hostStep: { ...hostStep, ...(hostStep.freshness ? { freshness: { ...hostStep.freshness } } : {}) },
+	};
+}
+
+function workflowNodeStatus(hostStep: HostStepNodeV1): WorkflowNodeStatus {
+	if (hostStep.state === "pending") return "pending";
+	if (hostStep.state === "running") return "running";
+	if (hostStep.state === "cancelled") return "stopped";
+	if (hostStep.state === "error") return "failed";
+	if (hostStep.verdict === undefined || hostStep.verdict === "inconclusive") return "partial";
+	return hostStep.verdict === "fail" ? "failed" : "completed";
+}
+
+/**
+ * Host-only registration/update boundary. The caller supplies the existing
+ * status writer; monitor providers never receive a path or write status.json.
+ */
+export function upsertHostStep(input: {
+	status: AsyncStatus;
+	hostStep: HostStepNodeV1;
+	persist: (status: AsyncStatus) => void;
+}): AsyncStatus {
+	const hostStep = parseHostStepNode(input.hostStep, input.hostStep.id);
+	assertWorkflowGraphHostSteps(input.status.workflowGraph, "host-step", input.status.runId);
+	const graph: WorkflowGraphSnapshot = input.status.workflowGraph
+		? {
+			...input.status.workflowGraph,
+			nodes: [...input.status.workflowGraph.nodes],
+		}
+		: {
+			runId: input.status.runId,
+			mode: input.status.mode,
+			phases: [],
+			nodes: [],
+		};
+	const existingIndex = graph.nodes.findIndex((node) => node.id === hostStep.id);
+	const existing = existingIndex >= 0 ? graph.nodes[existingIndex] : undefined;
+	if (existing && existing.kind !== "host-step") throw new Error(`Host step '${hostStep.id}' conflicts with an existing workflow node.`);
+	if (existingIndex < 0 && graph.nodes.filter((candidate) => candidate.kind === "host-step").length >= HOST_STEP_MAX_COUNT) {
+		throw new Error(`Host step limit of ${HOST_STEP_MAX_COUNT} has been reached.`);
+	}
+	const node = hostStepWorkflowNode(hostStep);
+	if (existingIndex >= 0) graph.nodes[existingIndex] = node;
+	else graph.nodes.push(node);
+	const nextStatus: AsyncStatus = {
+		...input.status,
+		workflowGraph: graph,
+		lastUpdate: Math.max(input.status.lastUpdate ?? 0, hostStep.updatedAt),
+	};
+	input.persist(nextStatus);
+	return nextStatus;
+}
+
+export function hostStepVerdictLabel(state: HostStepState, verdict: HostStepVerdict | undefined): string {
+	return state === "done" ? verdict ?? "inconclusive" : state;
+}
+
+export function hostStepReportName(reportPath: string | undefined): string | undefined {
+	if (!reportPath) return undefined;
+	return reportPath.split(/[\\/]/).filter(Boolean).at(-1);
+}

package/src/runs/shared/lane-metadata.ts

@@ -0,0 +1,105 @@
+import type { AsyncStatus, WorkflowLaneMetadata, WorkflowLaneMode } from "../../shared/types.ts";
+
+export const WORKFLOW_LANE_KEY_MAX_BYTES = 128;
+export const WORKFLOW_LANE_SOURCE_REF_MAX_BYTES = 128;
+export const WORKFLOW_LANE_CLAIM_MAX_BYTES = 160;
+export const WORKFLOW_LANE_CLAIMS_MAX = 20;
+export const WORKFLOW_LANE_OUTPUT_PATH_MAX_BYTES = 256;
+export const WORKFLOW_LANE_OUTPUT_PATHS_MAX = 10;
+export const WORKTREE_STATUS_PATH_MAX_BYTES = 4096;
+export const WORKTREE_STATUS_BRANCH_MAX_BYTES = 256;
+
+const WORKFLOW_LANE_KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const WORKFLOW_LANE_MODES = new Set<WorkflowLaneMode>(["mutation", "review", "scout", "gate"]);
+
+function byteLength(value: string): number {
+	return Buffer.byteLength(value, "utf8");
+}
+
+function boundedNonEmptyString(value: unknown, label: string, maxBytes: number): string {
+	if (typeof value !== "string" || !value.trim()) throw new Error(`${label} must be a non-empty string.`);
+	const normalized = value.trim();
+	if (byteLength(normalized) > maxBytes) throw new Error(`${label} exceeds ${maxBytes} UTF-8 bytes.`);
+	if ([...normalized].some((character) => character === "\n" || character === "\r" || character === "\u0000")) throw new Error(`${label} must not contain newlines or NUL bytes.`);
+	return normalized;
+}
+
+function assertPlainObject(value: unknown, label: string): asserts value is Record<string, unknown> {
+	if (!value || typeof value !== "object" || Array.isArray(value) || (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)) {
+		throw new Error(`${label} must be a plain JSON object.`);
+	}
+}
+
+function assertKnownFields(value: Record<string, unknown>, fields: readonly string[], label: string): void {
+	const unknown = Object.keys(value).filter((field) => !fields.includes(field));
+	if (unknown.length > 0) throw new Error(`${label} has unsupported fields: ${unknown.join(", ")}.`);
+}
+
+function boundedStringArray(value: unknown, label: string, maxItems: number, maxBytes: number): string[] {
+	if (!Array.isArray(value)) throw new Error(`${label} must be an array.`);
+	if (value.length > maxItems) throw new Error(`${label} supports at most ${maxItems} entries.`);
+	return value.map((entry, index) => {
+		if (!Object.hasOwn(value, index)) throw new Error(`${label} must not contain sparse entries.`);
+		return boundedNonEmptyString(entry, `${label}[${index}]`, maxBytes);
+	});
+}
+
+/** Normalize and validate launch-declared lane metadata. */
+export function normalizeWorkflowLaneMetadata(value: unknown, label = "lane"): WorkflowLaneMetadata | undefined {
+	if (value === undefined) return undefined;
+	assertPlainObject(value, label);
+	assertKnownFields(value, ["version", "key", "mode", "sourceRef", "claims", "outputPaths"], label);
+	if (value.version !== 1) throw new Error(`${label}.version must be 1.`);
+	const key = boundedNonEmptyString(value.key, `${label}.key`, WORKFLOW_LANE_KEY_MAX_BYTES);
+	if (!WORKFLOW_LANE_KEY_PATTERN.test(key)) throw new Error(`${label}.key is invalid.`);
+	const mode = value.mode;
+	if (mode !== undefined && (typeof mode !== "string" || !WORKFLOW_LANE_MODES.has(mode as WorkflowLaneMode))) throw new Error(`${label}.mode is invalid.`);
+	const sourceRef = value.sourceRef === undefined ? undefined : boundedNonEmptyString(value.sourceRef, `${label}.sourceRef`, WORKFLOW_LANE_SOURCE_REF_MAX_BYTES);
+	const claims = value.claims === undefined ? undefined : boundedStringArray(value.claims, `${label}.claims`, WORKFLOW_LANE_CLAIMS_MAX, WORKFLOW_LANE_CLAIM_MAX_BYTES);
+	const outputPaths = value.outputPaths === undefined ? undefined : boundedStringArray(value.outputPaths, `${label}.outputPaths`, WORKFLOW_LANE_OUTPUT_PATHS_MAX, WORKFLOW_LANE_OUTPUT_PATH_MAX_BYTES);
+	return {
+		version: 1,
+		key,
+		...(mode !== undefined ? { mode: mode as WorkflowLaneMode } : {}),
+		...(sourceRef !== undefined ? { sourceRef } : {}),
+		...(claims !== undefined ? { claims } : {}),
+		...(outputPaths !== undefined ? { outputPaths } : {}),
+	};
+}
+
+export function assertWorkflowLaneKey(lane: WorkflowLaneMetadata | undefined, workflowKey: string | undefined, label = "lane"): void {
+	if (!lane || workflowKey === undefined) return;
+	if (lane.key !== workflowKey) throw new Error(`${label}.key '${lane.key}' does not match workflow key '${workflowKey}'.`);
+}
+
+export interface WorktreeStatusReference {
+	worktreePath: string;
+	branch: string;
+}
+
+/** Validate the display-only worktree fields copied into status.json. */
+export function normalizeWorktreeStatusReference(value: unknown, label = "worktree status reference"): WorktreeStatusReference | undefined {
+	if (value === undefined) return undefined;
+	assertPlainObject(value, label);
+	assertKnownFields(value, ["worktreePath", "branch"], label);
+	return {
+		worktreePath: boundedNonEmptyString(value.worktreePath, `${label}.worktreePath`, WORKTREE_STATUS_PATH_MAX_BYTES),
+		branch: boundedNonEmptyString(value.branch, `${label}.branch`, WORKTREE_STATUS_BRANCH_MAX_BYTES),
+	};
+}
+
+/** Validate only the additive lane/worktree fields of a persisted async status. */
+export function validateAsyncStatusLaneMetadata(status: Pick<AsyncStatus, "runId" | "workflowKey" | "lane" | "steps">, label = "async status"): void {
+	const lane = normalizeWorkflowLaneMetadata(status.lane, `${label}.lane`);
+	assertWorkflowLaneKey(lane, status.workflowKey, `${label}.lane`);
+	if (lane) status.lane = lane;
+	for (const [index, step] of (status.steps ?? []).entries()) {
+		const stepLane = normalizeWorkflowLaneMetadata(step.lane, `${label}.steps[${index}].lane`);
+		assertWorkflowLaneKey(stepLane, step.workflowKey, `${label}.steps[${index}].lane`);
+		if (stepLane) step.lane = stepLane;
+		const hasPath = step.worktreePath !== undefined;
+		const hasBranch = step.branch !== undefined;
+		if (hasPath !== hasBranch) throw new Error(`${label}.steps[${index}] must include both worktreePath and branch.`);
+		if (hasPath) normalizeWorktreeStatusReference({ worktreePath: step.worktreePath, branch: step.branch }, `${label}.steps[${index}]`);
+	}
+}

package/src/runs/shared/mcp-config-sources.ts

@@ -39,6 +39,44 @@ export interface McpServerDefinition {
 	literalEnv?: boolean;
 }
 
+export function isMcpServerDefinition(value: unknown): value is McpServerDefinition {
+	if (!isRecord(value)) return false;
+	for (const field of ["command", "socket", "cwd", "url", "bearerToken", "bearerTokenEnv", "protocolVersion", "httpTransport", "pluginDataDir"] as const) {
+		if (value[field] !== undefined && typeof value[field] !== "string") return false;
+	}
+	for (const field of ["args", "includeTools", "excludeTools"] as const) {
+		if (value[field] !== undefined && !isStringArray(value[field])) return false;
+	}
+	for (const field of ["env", "headers"] as const) {
+		if (value[field] !== undefined && !isStringRecord(value[field])) return false;
+	}
+	for (const field of ["exposeResources", "literalEnv"] as const) {
+		if (value[field] !== undefined && typeof value[field] !== "boolean") return false;
+	}
+	if (value.requestHeadersCommand !== undefined && !isRequestHeadersCommand(value.requestHeadersCommand)) return false;
+	if (value.auth !== undefined && value.auth !== "oauth" && value.auth !== "bearer" && value.auth !== false) return false;
+	return value.directTools === undefined || typeof value.directTools === "boolean" || isStringArray(value.directTools);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function isStringArray(value: unknown): value is string[] {
+	return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+
+function isStringRecord(value: unknown): value is Record<string, string> {
+	return isRecord(value) && Object.values(value).every((entry) => typeof entry === "string");
+}
+
+function isRequestHeadersCommand(value: unknown): value is NonNullable<McpServerDefinition["requestHeadersCommand"]> {
+	if (!isRecord(value) || typeof value.command !== "string") return false;
+	if (value.args !== undefined && !isStringArray(value.args)) return false;
+	if (value.env !== undefined && !isStringRecord(value.env)) return false;
+	return value.timeoutMs === undefined || (typeof value.timeoutMs === "number" && Number.isFinite(value.timeoutMs));
+}
+
 export function loadPackageMcpServers(cwd: string): Record<string, McpServerDefinition> {
 	const servers: Record<string, McpServerDefinition> = {};
 	const seen = new Set<string>();
@@ -64,11 +102,11 @@ export function loadPackageMcpServers(cwd: string): Record<string, McpServerDefi
 			const rawServers = (config as { mcpServers?: unknown }).mcpServers;
 			if (!rawServers || typeof rawServers !== "object" || Array.isArray(rawServers)) continue;
 			for (const [serverName, definition] of Object.entries(rawServers)) {
-				if (!definition || typeof definition !== "object" || Array.isArray(definition)) continue;
+				if (!isMcpServerDefinition(definition)) continue;
 				const normalizedName = `${packagePrefix}__${formatName(serverName, "server")}`;
 				if (seen.has(normalizedName)) continue;
 				seen.add(normalizedName);
-				servers[normalizedName] = definition as McpServerDefinition;
+				servers[normalizedName] = definition;
 			}
 		}
 	}
@@ -90,7 +128,7 @@ export function loadAgentPluginMcpServers(paths: unknown, cwd: string): Record<s
 		const rawServers = (config as { mcpServers: Record<string, unknown> }).mcpServers;
 
 		for (const [serverName, rawDefinition] of Object.entries(rawServers)) {
-			const definition = translatePluginServer(manifest.name, pluginRoot, serverName, rawDefinition);
+			const definition = translatePluginServer(manifest.name, pluginRoot, rawDefinition);
 			if (!definition) continue;
 			const normalizedName = `${formatName(manifest.name, "plugin")}__${formatName(serverName, "server")}`;
 			if (Object.hasOwn(servers, normalizedName)) continue;
@@ -254,12 +292,11 @@ function isValidPluginConfig(value: unknown): value is { mcpServers: Record<stri
 function translatePluginServer(
 	pluginName: string,
 	pluginRoot: string,
-	serverName: string,
 	value: unknown,
 ): McpServerDefinition | undefined {
 	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
 	const raw = value as Record<string, unknown>;
-	if (raw.type === "stdio") return translatePluginStdioServer(pluginName, pluginRoot, serverName, raw);
+	if (raw.type === "stdio") return translatePluginStdioServer(pluginName, pluginRoot, raw);
 	if (raw.type === "streamable-http" || raw.type === "sse") return translatePluginHttpServer(raw);
 	return undefined;
 }
@@ -267,7 +304,6 @@ function translatePluginServer(
 function translatePluginStdioServer(
 	pluginName: string,
 	pluginRoot: string,
-	serverName: string,
 	raw: Record<string, unknown>,
 ): McpServerDefinition | undefined {
 	if ([...Object.keys(raw)].some((key) => !PLUGIN_STDIO_FIELDS.has(key))) return undefined;