pi-crew 0.9.68 → 0.10.1

package/src/runtime/goal-workflow/adaptive-plan.ts

@@ -14,11 +14,15 @@
 //
 // `__test__parseAdaptivePlan` and `__test__repairAdaptivePlan` are re-exported
 // from team-runner.ts so existing test imports keep working.
+
+import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
+import { getCrewEnv } from "../../config/env-vars.ts";
 import { appendEventAsync, appendEventFireAndForget } from "../../state/event-log/event-log.ts";
 import { writeArtifact } from "../../state/stores/artifact-store.ts";
-import { saveRunManifestAsync } from "../../state/stores/state-store.ts";
-import type { TeamRunManifest, TeamTaskState } from "../../state/types.ts";
+import { appendPlanRevision, getCurrentPlanRecord } from "../../state/stores/plan-store.ts";
+import { saveRunManifestAsync, saveRunTasksAsync } from "../../state/stores/state-store.ts";
+import type { PlanRecord, TeamRunManifest, TeamTaskState } from "../../state/types.ts";
 import type { TeamConfig } from "../../teams/team-config.ts";
 import type { WorkflowConfig, WorkflowStep } from "../../workflows/workflow-config.ts";
 import { refreshTaskGraphQueues } from "../scheduling/task-graph-scheduler.ts";
@@ -39,7 +43,15 @@ export interface AdaptivePlan {
 	phases: AdaptivePlanPhase[];
 }
 
-const MAX_ADAPTIVE_TASKS = 12;
+/**
+ * T2/R4 (ADR-4 §5): the cap is PER-PHASE, not global. Pre-v2 this was a
+ * global flatten cap (MAX_ADAPTIVE_TASKS = 12) applied across the whole plan —
+ * a 3-phase plan may now schedule up to 3 x this across its life, bounded and
+ * visible per phase in the persisted PlanRecord. Deliberately a module
+ * constant, NOT a config key (the `adaptive` config section belongs to
+ * T3/WP-5 — review finding F3 of the ADR round).
+ */
+const ADAPTIVE_MAX_TASKS_PER_PHASE = 12;
 
 export function slug(value: string): string {
 	return (
@@ -124,7 +136,6 @@ export function parseAdaptivePlan(text: string, allowedRoles: string[]): Adaptiv
 	if (!phasesRaw) return undefined;
 	const allowed = new Set(allowedRoles);
 	const phases: AdaptivePlanPhase[] = [];
-	let total = 0;
 	for (const [phaseIndex, phaseRaw] of phasesRaw.entries()) {
 		if (!phaseRaw || typeof phaseRaw !== "object" || Array.isArray(phaseRaw)) return undefined;
 		const phaseObj = phaseRaw as { name?: unknown; tasks?: unknown };
@@ -139,13 +150,12 @@ export function parseAdaptivePlan(text: string, allowedRoles: string[]): Adaptiv
 			};
 			if (typeof taskObj.role !== "string" || !allowed.has(taskObj.role)) return undefined;
 			if (typeof taskObj.task !== "string" || !taskObj.task.trim()) return undefined;
-			if (total >= MAX_ADAPTIVE_TASKS) return undefined;
+			if (tasks.length >= ADAPTIVE_MAX_TASKS_PER_PHASE) return undefined; // per-phase (ADR-4 §5)
 			tasks.push({
 				role: taskObj.role,
 				title: typeof taskObj.title === "string" ? taskObj.title : undefined,
 				task: taskObj.task.trim(),
 			});
-			total++;
 		}
 		phases.push({
 			name: typeof phaseObj.name === "string" && phaseObj.name.trim() ? phaseObj.name.trim() : `phase-${phaseIndex + 1}`,
@@ -289,7 +299,6 @@ export function repairAdaptivePlan(text: string, allowedRoles: string[]): { plan
 	if (!phasesRaw) return { repaired: false, reason: "missing-phases" };
 	const allowed = new Set(allowedRoles);
 	const phases: AdaptivePlanPhase[] = [];
-	let total = 0;
 	let repaired = salvageUsed || raw !== closeResult.text;
 	for (const [phaseIndex, phaseRaw] of phasesRaw.entries()) {
 		if (!phaseRaw || typeof phaseRaw !== "object" || Array.isArray(phaseRaw)) continue;
@@ -297,7 +306,8 @@ export function repairAdaptivePlan(text: string, allowedRoles: string[]): { plan
 		if (!Array.isArray(phaseObj.tasks)) continue;
 		const tasks: AdaptivePlanTask[] = [];
 		for (const taskRaw of phaseObj.tasks) {
-			if (total >= MAX_ADAPTIVE_TASKS) {
+			if (tasks.length >= ADAPTIVE_MAX_TASKS_PER_PHASE) {
+				// Per-phase cap (ADR-4 §5): truncate THIS phase, keep later phases.
 				repaired = true;
 				break;
 			}
@@ -321,14 +331,12 @@ export function repairAdaptivePlan(text: string, allowedRoles: string[]): { plan
 				title: typeof taskObj.title === "string" ? taskObj.title : undefined,
 				task: taskText,
 			});
-			total++;
 		}
 		if (tasks.length)
 			phases.push({
 				name: typeof phaseObj.name === "string" && phaseObj.name.trim() ? phaseObj.name.trim() : `phase-${phaseIndex + 1}`,
 				tasks,
 			});
-		if (total >= MAX_ADAPTIVE_TASKS) break;
 	}
 	return phases.length
 		? {
@@ -409,6 +417,9 @@ export async function injectAdaptivePlanIfReady(input: InjectAdaptivePlanInput):
 		};
 	}
 	const assessTask = completedAssess;
+	// Review R5: manifest variant tracked through the repair path — the plan
+	// save below must not clobber the repair artifact descriptor.
+	let manifestBase = input.manifest;
 	const resultPath = completedAssess.resultArtifact.path;
 	let text = "";
 	try {
@@ -431,7 +442,7 @@ export async function injectAdaptivePlanIfReady(input: InjectAdaptivePlanInput):
 	let plan = parseAdaptivePlan(text, allowedRoles);
 	if (!plan) {
 		const repair =
-			process.env.PI_CREW_ADAPTIVE_REPAIR === "0" || process.env.PI_TEAMS_ADAPTIVE_REPAIR === "0"
+			getCrewEnv("PI_CREW_ADAPTIVE_REPAIR") === "0" || getCrewEnv("PI_TEAMS_ADAPTIVE_REPAIR") === "0"
 				? { repaired: false, reason: "disabled" }
 				: repairAdaptivePlan(text, allowedRoles);
 		if (repair.plan) {
@@ -442,11 +453,12 @@ export async function injectAdaptivePlanIfReady(input: InjectAdaptivePlanInput):
 				producer: assessTask.id,
 				content: `${JSON.stringify({ reason: repair.reason, phases: repair.plan.phases.map((phase) => ({ name: phase.name, count: phase.tasks.length, roles: phase.tasks.map((task) => task.role) })) }, null, 2)}\n`,
 			});
-			await saveRunManifestAsync({
+			manifestBase = {
 				...input.manifest,
 				updatedAt: new Date().toISOString(),
 				artifacts: [...input.manifest.artifacts, repairArtifact],
-			});
+			};
+			await saveRunManifestAsync(manifestBase);
 			appendEventFireAndForget(input.manifest.eventsPath, {
 				type: "adaptive.plan_repaired",
 				runId: input.manifest.runId,
@@ -478,14 +490,30 @@ export async function injectAdaptivePlanIfReady(input: InjectAdaptivePlanInput):
 	}
 	const steps: WorkflowStep[] = [];
 	const tasks: TeamTaskState[] = [];
+	// T2/R4 (ADR-4 §6 producer 2): item ids are stable across revisions —
+	// phase/task POSITION based, independent of role renames.
+	const planPhases: PlanRecord["phases"] = [];
+	const planItems: PlanRecord["items"] = [];
 	let previousStepIds = ["assess"];
 	let counter = 0;
 	for (const [phaseIndex, phase] of plan.phases.entries()) {
 		const currentStepIds: string[] = [];
+		const phaseItemIds: string[] = [];
 		for (const [taskIndex, planned] of phase.tasks.entries()) {
 			counter++;
+			const itemId = `adaptive-p${phaseIndex + 1}-t${taskIndex + 1}`;
 			const stepId = `adaptive-${phaseIndex + 1}-${taskIndex + 1}-${slug(planned.role)}`;
 			const taskId = `adaptive-${String(counter).padStart(2, "0")}-${slug(planned.role)}`;
+			phaseItemIds.push(itemId);
+			planItems.push({
+				id: itemId,
+				ref: stepId,
+				title: planned.title ?? planned.task.slice(0, 80),
+				taskIds: [],
+				specIds: [],
+				acceptance: [],
+				status: "pending",
+			});
 			steps.push({
 				id: stepId,
 				role: planned.role,
@@ -504,6 +532,7 @@ export async function injectAdaptivePlanIfReady(input: InjectAdaptivePlanInput):
 				dependsOn: previousStepIds,
 				cwd: input.manifest.cwd,
 				adaptive: { phase: phase.name, task: planned.task },
+				planItem: itemId,
 				graph: {
 					taskId,
 					dependencies: previousStepIds,
@@ -513,6 +542,12 @@ export async function injectAdaptivePlanIfReady(input: InjectAdaptivePlanInput):
 			});
 			currentStepIds.push(stepId);
 		}
+		planPhases.push({
+			id: `adaptive-phase-${phaseIndex + 1}`,
+			title: phase.name,
+			itemIds: phaseItemIds,
+			status: "pending",
+		});
 		previousStepIds = currentStepIds;
 	}
 	const dependencyTaskIdByStep = new Map<string, string>([
@@ -531,6 +566,45 @@ export async function injectAdaptivePlanIfReady(input: InjectAdaptivePlanInput):
 			: task.graph,
 	}));
 	const allTasks = refreshTaskGraphQueues([...input.tasks, ...withGraph]);
+	// T2/R4 (ADR-4 §2/§6): persist the PlanRecord + manifest pointer (dual-write;
+	// crash between the two is benign — getCurrentPlanRecord falls back to the
+	// highest version). Producers never set taskIds (single-writer rule §3).
+	const planRecord: PlanRecord = {
+		id: randomUUID(),
+		runId: input.manifest.runId,
+		version: 1,
+		title: `Adaptive plan (${plan.phases.length} phase(s))`,
+		phases: planPhases,
+		items: planItems,
+		createdAt: new Date().toISOString(),
+		authorTaskId: assessTask.id,
+	};
+	// Review R1 (P1, crash-window): if a record ALREADY exists (the append
+	// survived a kill between the plans.json write and the tasks save below),
+	// REUSE it instead of re-appending — the fresh randomUUID would throw
+	// lineage-break on resume and permanently brick the run. Task/item ids are
+	// position-deterministic from the SAME parsed artifact, so the rebuilt
+	// linkage matches the surviving record exactly.
+	const existingRecord = getCurrentPlanRecord(input.manifest);
+	if (!existingRecord) appendPlanRevision(input.manifest, planRecord);
+	// Review round-2 N1: on the crash-window reuse path the pointer MUST name
+	// the SURVIVING record — the fresh planRecord was never persisted, so its
+	// randomUUID would dangle (masked today by the highest-version fallback,
+	// but it violates ADR-4 §2's pointer invariant).
+	const planPointer = existingRecord
+		? { id: existingRecord.id, version: existingRecord.version }
+		: { id: planRecord.id, version: planRecord.version };
+	await saveRunManifestAsync({
+		...manifestBase,
+		updatedAt: new Date().toISOString(),
+		plan: planPointer,
+	});
+	// FIX (T2/B2 case e, pre-existing): the injected tasks MUST be persisted at
+	// injection time. mergeUnitResult reloads tasks.json as the merge base and
+	// mergeTaskUpdatesPreservingTerminal DROPS updates for ids absent from the
+	// base — an injection that only lived in memory had its completed adaptive
+	// tasks silently erased from disk at the first merge.
+	await saveRunTasksAsync(manifestBase, allTasks);
 	await appendEventAsync(input.manifest.eventsPath, {
 		type: "adaptive.plan_injected",
 		runId: input.manifest.runId,

package/src/runtime/goal-workflow/dynamic-workflow-runner.ts

@@ -20,6 +20,7 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { transformSync } from "esbuild";
+import { getCrewEnv } from "../../config/env-vars.ts";
 import { appendEvent } from "../../state/event-log/event-log.ts";
 import { writeArtifact } from "../../state/stores/artifact-store.ts";
 import type { TeamRunManifest, TeamTaskState } from "../../state/types.ts";
@@ -151,7 +152,7 @@ export async function runDynamicWorkflow(input: RunDynamicWorkflowInput): Promis
 	// require, fs, child_process). Cloning a hostile repo and running its workflow = arbitrary
 	// code execution. Default-deny project workflows unless the user explicitly opts in via
 	// PI_CREW_TRUST_PROJECT_DWF=1. Builtin and user workflows proceed without restriction.
-	if (workflow.source === "project" && process.env.PI_CREW_TRUST_PROJECT_DWF !== "1") {
+	if (workflow.source === "project" && getCrewEnv("PI_CREW_TRUST_PROJECT_DWF") !== "1") {
 		appendEvent(eventsPath, {
 			type: "dwf.trust_denied",
 			runId: manifest.runId,
@@ -223,7 +224,7 @@ export async function runDynamicWorkflow(input: RunDynamicWorkflowInput): Promis
 		// it does NOT kill the script. Promise.race with a hard timeout at least returns an
 		// error so the runner doesn't hang. The spawned child process is leaked, but the
 		// dynamic-workflow returns failure promptly. (v1.5: use Worker threads to actually kill.)
-		const SCRIPT_TIMEOUT_MS = Number.parseInt(process.env.PI_CREW_DWF_SCRIPT_TIMEOUT_MS ?? "", 10) || 1_800_000; // 30 min default (was 10 min; raised for distill-dwf + similar long pipelines)
+		const SCRIPT_TIMEOUT_MS = Number.parseInt(getCrewEnv("PI_CREW_DWF_SCRIPT_TIMEOUT_MS") ?? "", 10) || 1_800_000; // 30 min default (was 10 min; raised for distill-dwf + similar long pipelines)
 		let timeoutHandle: NodeJS.Timeout | undefined;
 		const timeoutPromise = new Promise<never>((_, reject) => {
 			timeoutHandle = setTimeout(() => {

package/src/runtime/goal-workflow/goal-state-store.ts

@@ -6,7 +6,7 @@
  * goal loop owns OUTER state) + §0c C10 (hardening: assertSafePathId + UUID goalId).
  *
  * Stores GoalLoopState as atomic JSON at <crewRoot>/state/goals/<goalId>.json.
- * Modeled on ScheduleStore (state/coordination/schedule.ts:86) but with atomicWriteJson +
+ * Modeled on the (removed in Phase 1.7) ScheduleStore coordination pattern but with atomicWriteJson +
  * path-traversal defense (assertSafePathId on every public method).
  *
  * Per §0c C2: budget lives here (budgetUsed accumulates collectRunMetrics across turns);

package/src/runtime/group-join.ts

@@ -3,7 +3,7 @@ import { appendMailboxMessage, findMailboxMessageByRequestId, readDeliveryState
 import { appendEvent } from "../state/event-log/event-log.ts";
 import { writeArtifact } from "../state/stores/artifact-store.ts";
 import type { ArtifactDescriptor, TeamRunManifest, TeamTaskState } from "../state/types.ts";
-import { aggregateTaskOutputs } from "./task-output-context.ts";
+import { aggregateTaskOutputs, type ResultArtifactReadCache } from "./task-output-context.ts";
 
 export type CrewGroupJoinMode = "off" | "group" | "smart";
 
@@ -51,6 +51,11 @@ export function deliverGroupJoin(input: {
 	batch: TeamTaskState[];
 	allTasks: TeamTaskState[];
 	partial?: boolean;
+	/** R10-1: optional per-run result-artifact read cache. The closeout
+	 *  aggregates the same settled batch for the batch-summary artifact
+	 *  immediately before this call — passing that cache here turns the
+	 *  group-join aggregation into cache hits (byte-identical output). */
+	cache?: ResultArtifactReadCache;
 }): CrewGroupJoinDelivery | undefined {
 	if (!shouldGroupJoin(input.mode, input.batch)) return undefined;
 	const taskIds = input.batch.map((task) => task.id);
@@ -63,7 +68,7 @@ export function deliverGroupJoin(input: {
 	const remaining = latest.filter((task) => task.status === "queued" || task.status === "running").map((task) => task.id);
 	const partial = input.partial ?? remaining.length > 0;
 	const batchId = batchIdFor(input.manifest.runId, taskIds);
-	const summary = aggregateTaskOutputs(latest, input.manifest);
+	const summary = aggregateTaskOutputs(latest, input.manifest, input.cache);
 	const requestId = requestIdFor(input.manifest.runId, batchId, partial);
 	const existingMailbox = findMailboxMessageByRequestId(input.manifest, requestId);
 	const existingStatus = existingMailbox
@@ -141,127 +146,8 @@ export function deliverGroupJoin(input: {
 	return { ...delivery, artifact, messageId: mailbox.id };
 }
 
-import type { CrewAgentRecord } from "./crew-agent-runtime.ts";
-
+/**
+ * Persisted settings vocabulary for join mode (imported by settings-store.ts
+ * for `defaultJoinMode` validation and config application).
+ */
 export type JoinMode = "async" | "group" | "smart";
-export type DeliveryCallback = (records: CrewAgentRecord[], partial: boolean) => void;
-
-interface AgentGroup {
-	groupId: string;
-	agentIds: Set<string>;
-	completedRecords: Map<string, CrewAgentRecord>;
-	timeoutHandle?: ReturnType<typeof setTimeout>;
-	delivered: boolean;
-	isStraggler: boolean;
-}
-
-const DEFAULT_TIMEOUT = 30_000;
-const STRAGGLER_TIMEOUT = 15_000;
-
-export class GroupJoinManager {
-	private groups = new Map<string, AgentGroup>();
-	private agentToGroup = new Map<string, string>();
-
-	private deliverCb: DeliveryCallback;
-	private groupTimeout: number;
-
-	constructor(deliverCb: DeliveryCallback, groupTimeout = DEFAULT_TIMEOUT) {
-		this.deliverCb = deliverCb;
-		this.groupTimeout = groupTimeout;
-	}
-
-	registerGroup(groupId: string, agentIds: string[]): void {
-		const group: AgentGroup = {
-			groupId,
-			agentIds: new Set(agentIds),
-			completedRecords: new Map(),
-			delivered: false,
-			isStraggler: false,
-		};
-		this.groups.set(groupId, group);
-		for (const id of agentIds) {
-			this.agentToGroup.set(id, groupId);
-		}
-	}
-
-	onAgentComplete(record: CrewAgentRecord): "delivered" | "held" | "pass" {
-		const groupId = this.agentToGroup.get(record.taskId);
-		if (!groupId) return "pass";
-
-		const group = this.groups.get(groupId);
-		if (!group || group.delivered) return "pass";
-
-		group.completedRecords.set(record.taskId, record);
-
-		if (group.completedRecords.size >= group.agentIds.size) {
-			this.deliver(group, false);
-			return "delivered";
-		}
-
-		if (!group.timeoutHandle) {
-			const timeout = group.isStraggler ? STRAGGLER_TIMEOUT : this.groupTimeout;
-			group.timeoutHandle = setTimeout(() => {
-				this.onTimeout(group);
-			}, timeout);
-		}
-
-		return "held";
-	}
-
-	private onTimeout(group: AgentGroup): void {
-		if (group.delivered) return;
-		group.timeoutHandle = undefined;
-
-		const remaining = new Set<string>();
-		for (const id of group.agentIds) {
-			if (!group.completedRecords.has(id)) remaining.add(id);
-		}
-
-		for (const id of group.completedRecords.keys()) {
-			this.agentToGroup.delete(id);
-		}
-
-		this.deliverCb([...group.completedRecords.values()], true);
-
-		group.completedRecords.clear();
-		group.agentIds = remaining;
-		group.isStraggler = true;
-
-		// Re-arm timer for remaining stragglers so they aren't silently abandoned
-		if (remaining.size > 0) {
-			group.timeoutHandle = setTimeout(() => this.onTimeout(group), STRAGGLER_TIMEOUT);
-			group.timeoutHandle.unref();
-		}
-	}
-
-	private deliver(group: AgentGroup, partial: boolean): void {
-		if (group.timeoutHandle) {
-			clearTimeout(group.timeoutHandle);
-			group.timeoutHandle = undefined;
-		}
-		group.delivered = true;
-		this.deliverCb([...group.completedRecords.values()], partial);
-		this.cleanupGroup(group.groupId);
-	}
-
-	private cleanupGroup(groupId: string): void {
-		const group = this.groups.get(groupId);
-		if (!group) return;
-		for (const id of group.agentIds) {
-			this.agentToGroup.delete(id);
-		}
-		this.groups.delete(groupId);
-	}
-
-	isGrouped(agentId: string): boolean {
-		return this.agentToGroup.has(agentId);
-	}
-
-	dispose(): void {
-		for (const group of this.groups.values()) {
-			if (group.timeoutHandle) clearTimeout(group.timeoutHandle);
-		}
-		this.groups.clear();
-		this.agentToGroup.clear();
-	}
-}

package/src/runtime/live-session/live-session-runtime.ts

@@ -5,6 +5,7 @@ import { resolveToolPolicy } from "../../agents/agent-config.ts";
 import type { CrewRuntimeConfig } from "../../config/config.ts";
 import { loadConfig } from "../../config/config.ts";
 import { DEFAULT_LIVE_SESSION } from "../../config/defaults.ts";
+import { getCrewEnv } from "../../config/env-vars.ts";
 import { appendEvent, appendEventFireAndForget } from "../../state/event-log/event-log.ts";
 import type { TeamRunManifest, TeamTaskState, UsageState } from "../../state/types.ts";
 import { logInternalError } from "../../utils/internal-error.ts";
@@ -81,6 +82,13 @@ import { collectLiveSessionHealth, formatLiveSessionDiagnostics } from "./live-s
  * explorer subagents launched together; 3 of 4 crashed.)
  */
 let liveSessionModulePromise: Promise<LiveSessionModule> | undefined;
+
+/**
+ * Phase 4 (ADR 2026-08-15-runtime-convergence, decision (a) — freeze):
+ * warn-once flag so the experimental-path notice fires at most once per
+ * process, not per task.
+ */
+let experimentalWarned = false;
 function loadLiveSessionModule(): Promise<LiveSessionModule> {
 	if (!liveSessionModulePromise) {
 		liveSessionModulePromise = import("@earendil-works/pi-coding-agent") as unknown as Promise<LiveSessionModule>;
@@ -549,13 +557,30 @@ export async function runLiveSessionTask(input: LiveSessionSpawnInput): Promise<
 	// any module. Under tsx, concurrent first-imports race module-record
 	// instantiation; awaiting the registration-time warmup eliminates the window.
 	await awaitRuntimeWarmup();
+
+	// Phase 4 (ADR 2026-08-15-runtime-convergence, decision (a) — freeze):
+	// the live-session path is permanently EXPERIMENTAL and intentionally
+	// diverges from the supported child-process path (no worker-cap semaphore,
+	// no depth guard, permissive SDK tool surface, single-model-fallback
+	// report). Warn once per process so operators see the notice without
+	// per-task spam.
+	if (!experimentalWarned) {
+		experimentalWarned = true;
+		logInternalError(
+			"live-session.experimental",
+			new Error("experimental path"),
+			"runtime.mode=live-session is EXPERIMENTAL and frozen (decision (a)); it diverges from child-process semantics (no worker-cap/depth guard, permissive tools) — see docs/decisions/2026-08-15-runtime-convergence.md",
+			"warn",
+		);
+	}
+
 	const isCurrent = input.isCurrent ?? (() => true);
 	let streamOut: StreamingOutputHandle | undefined;
 
 	// G1: Capture yield result from custom tool callback
 	let customToolYieldResult: YieldResult | undefined;
 	let customToolYieldResolved = false;
-	if (process.env.PI_CREW_MOCK_LIVE_SESSION === "success") {
+	if (getCrewEnv("PI_CREW_MOCK_LIVE_SESSION") === "success") {
 		const agentId = `${input.manifest.runId}:${input.task.id}`;
 		const inherited =
 			input.runtimeConfig?.inheritContext === true && input.parentContext ? ` with inherited context: ${input.parentContext}` : "";

package/src/runtime/merge-gate.ts

@@ -13,6 +13,7 @@
  */
 import { TEAM_TASK_STATUSES, TEAM_TERMINAL_TASK_STATUSES, type TeamTaskStatus } from "../state/contracts.ts";
 import type { TeamTaskState } from "../state/types.ts";
+import { logInternalError } from "../utils/internal-error.ts";
 import { refreshTaskGraphQueues } from "./scheduling/task-graph-scheduler.ts";
 
 export function isNonTerminalTaskStatus(status: TeamTaskState["status"]): boolean {
@@ -123,7 +124,12 @@ export function shouldMergeTaskUpdate(current: TeamTaskState, updated: TeamTaskS
 		// Malformed finishedAt (NaN) is treated as Infinity — invalid state should be
 		// replaced rather than persisting corruption. Log warning for visibility.
 		if (!Number.isFinite(currentTime)) {
-			console.warn(`[merge-gate] Task ${current.id} has malformed finishedAt: ${current.finishedAt}`);
+			logInternalError(
+				"merge-gate",
+				new Error(`Task ${current.id} has malformed finishedAt: ${current.finishedAt}`),
+				undefined,
+				"warn",
+			);
 		}
 		if (isMalformedFinishedAtReplacement(currentTime, updatedTime)) {
 			return true;

package/src/runtime/merge-loop.ts

@@ -0,0 +1,130 @@
+/**
+ * Merge of settled dispatch units into the run state for the team-run
+ * scheduler loop.
+ *
+ * Extracted from team-runner.ts (2026-08, Phase 2.6 maintainability split —
+ * CORE-4 extraction 5). Pure code motion: isRunTerminalPreserved +
+ * mergeUnitResult moved verbatim, including the RT-12 / NEW-D1 / R15-2 /
+ * CANCEL-1 comments.
+ *
+ * `isRunTerminalPreserved` lives here (not in finalize-run.ts) because it is
+ * shared by mergeUnitResult, finalizeRun (finalize-run.ts imports it from
+ * here) and the core loop in team-runner.ts (which imports it from here) —
+ * keeping it here avoids a merge-loop ↔ finalize-run import cycle.
+ */
+import { flushPendingAtomicWrites } from "../state/atomic-write.ts";
+import { withRunLock } from "../state/coordination/locks.ts";
+import { loadRunManifestById, saveRunManifestAsync, saveRunTasksAsync, updateRunStatus } from "../state/stores/state-store.ts";
+import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
+import { classifyFatalFsError } from "../utils/fs-errno.ts";
+import { cancelNonTerminalTasks } from "./dispatch-batch.ts";
+import { mergeTaskUpdatesPreservingTerminal } from "./merge-gate.ts";
+import type { SchedulerContext, SchedulerDecision } from "./scheduler-context.ts";
+import { mergeArtifacts } from "./team-runner-artifacts.ts";
+
+/**
+ * CORE-4 extraction 5: wait for one in-flight dispatch unit to settle and
+ * merge its result into the run state.
+ *
+ * Awaits Promise.race on ctx.pendingUnits; the first settled unit is merged
+ * into ctx.manifest/tasks under the run lock (flushPendingAtomicWrites +
+ * loadRunManifestById + mergeTaskUpdatesPreservingTerminal + save). The settled
+ * unit is then deleted from ctx.pendingUnits, and the merge outcome (taskIds
+ * + result object) is recorded on ctx.settledMerge for the post-merge inline
+ * logic (cancel-during-exec check + batch summary).
+ *
+ * Returns null to continue to the phase/budget check. A `{ kind: "return" }`
+ * decision is reserved for future run-complete/failure detection during merge.
+ *
+ * Reads ctx.pendingUnits/manifest/tasks. Mutates ctx.pendingUnits (delete),
+ * ctx.manifest/tasks, ctx.settledMerge.
+ *
+ * @param ctx  The scheduler context.
+ */
+/** R15-2/R15-1: run statuses that must never be overwritten by an in-memory
+ * derived status (mergeUnitResult force-"running", finalizeRun "completed").
+ * "blocked" is deliberately EXCLUDED — a blocked run can be unblocked and the
+ * finalize chain may legitimately derive blocked from in-memory state. */
+export function isRunTerminalPreserved(status: TeamRunManifest["status"]): boolean {
+	return status === "cancelled" || status === "failed" || status === "completed";
+}
+
+export async function mergeUnitResult(ctx: SchedulerContext): Promise<SchedulerDecision | null> {
+	// RT-12: race on pre-created wrapper promises (created once at dispatch
+	// time) instead of rebuilding a wrapper-promise array with new async
+	// closures every iteration. This reduces allocation from O(C×T) wrapper
+	// promises to O(C) total (one per unit, created once at dispatch).
+	const settled = await Promise.race([...ctx.pendingUnits.values()].map((u) => u.wrapped));
+	const completedUnit = ctx.pendingUnits.get(settled.unitKey)!;
+	ctx.pendingUnits.delete(settled.unitKey);
+
+	// Build the single result to merge. On rejection, synthesize a failed
+	// result so the run continues (mirrors the old validResults guard).
+	// bug-026 sub-issue B: a rejected unit means runTeamTask itself threw —
+	// typically an atomicWriteFile/persistSingleTaskUpdate ENOSPC mid-run.
+	// Classify the errno and stamp failureCause on the synthesized failed
+	// tasks so the operator sees "failed (disk full)", not a generic write
+	// error string.
+	const thrownFailureCause = settled.result ? undefined : classifyFatalFsError(settled.error);
+	const resultToMerge: { manifest: TeamRunManifest; tasks: TeamTaskState[] } = settled.result ?? {
+		manifest: ctx.manifest,
+		tasks: cancelNonTerminalTasks(ctx.tasks, "failed", settled.error!.message, (t) => completedUnit.taskIds.includes(t.id)).map((t) =>
+			thrownFailureCause && t.status === "failed" ? { ...t, failureCause: thrownFailureCause } : t,
+		),
+	};
+	const validResults = [resultToMerge];
+	// Reconstruct manifest from the last worker's snapshot. The .artifacts field
+	// is re-merged from both the team-runner's in-memory state and all workers'
+	// snapshots, so artifact writes by task-runner (which individually save manifest
+	// after writing artifacts) are safely persisted. The in-memory manifest is only
+	// used for the next batch iteration's orchestration — actual persistence is safe.
+	// Use updateRunStatus to recompute manifest status from merged tasks rather than
+	// relying on the last result's manifest (which is arbitrary due to mapConcurrent
+	// returning results in arbitrary order).
+	// Use the in-memory manifest as base (not the last-completing worker's snapshot).
+	// Recompute status from merged tasks so the manifest reflects actual task state,
+	// not the arbitrary order in which mapConcurrent returned results.
+	// Read committed manifest from disk inside the lock so artifact merge is based
+	// on committed state, not in-memory state that may differ from disk.
+	const mergeResult = await withRunLock(ctx.manifest, async () => {
+		// NEW-D1: flush any pending coalesced atomic writes before reading from
+		// disk. Without this, a worker's async manifest save (coalesced by
+		// atomic-write) may not be committed yet, causing a lost-update on the
+		// merge read. flushPendingAtomicWrites forces all queued writes to disk.
+		flushPendingAtomicWrites();
+		const disk = loadRunManifestById(ctx.manifest.cwd, ctx.manifest.runId);
+		const diskManifest = disk?.manifest ?? ctx.manifest;
+		const diskArtifacts = diskManifest.artifacts;
+		const reconciledArtifacts = mergeArtifacts([...diskArtifacts, ...validResults.map((item) => item.manifest.artifacts)].flat());
+		// R15-2: only force "running" when the disk manifest is NON-terminal
+		// (queued/planning/running/blocked). If the disk status is already terminal
+		// (cancelled/failed/completed — an external cancel or reconciler write
+		// landing during the batch), PRESERVE that terminal status: forcing
+		// "running" would legally erase it (contracts.ts allows cancelled/failed/
+		// completed → running) and the loop would never observe the disk-terminal
+		// (CANCEL-1/CANCEL-2 only catch worker-reported cancel or signal abort).
+		const mergedBase = { ...diskManifest, artifacts: reconciledArtifacts };
+		const resultManifest = isRunTerminalPreserved(diskManifest.status)
+			? mergedBase
+			: updateRunStatus(mergedBase, "running", "Merged task updates from parallel batch.");
+		// CANCEL-1: use the freshly-loaded disk tasks as the merge base instead
+		// of the in-memory `tasks` closure variable. The in-memory tasks reflect
+		// only team-runner's view; an external cancel (handleCancel, background
+		// race with SIGTERM arriving after cancel wrote but before merge ran)
+		// writes 'cancelled' to disk.tasks — using disk.tasks as base preserves
+		// that cancellation through the merge instead of overwriting it with the
+		// stale in-memory view. disk was loaded inside this lock, so it reflects
+		// the freshest committed state.
+		const resultTasks = mergeTaskUpdatesPreservingTerminal(disk?.tasks ?? ctx.tasks, validResults);
+		await saveRunManifestAsync(resultManifest);
+		await saveRunTasksAsync(resultManifest, resultTasks);
+		return { resultManifest, resultTasks };
+	});
+	ctx.manifest = mergeResult.resultManifest;
+	ctx.tasks = mergeResult.resultTasks;
+	ctx.settledMerge = { taskIds: completedUnit.taskIds, result: resultToMerge };
+	return null;
+}
+
+/** @internal 1.9(b) test export — exercise mergeUnitResult directly. */
+export const __test__mergeUnitResult = mergeUnitResult;