pi-crew 0.9.68 → 0.10.2

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
 		? {
@@ -360,6 +368,11 @@ export interface InjectAdaptivePlanInput {
 	tasks: TeamTaskState[];
 	workflow: WorkflowConfig;
 	team: TeamConfig;
+	/** False for scaffold (dry-run) runs: the planner never executes, so there
+	 *  is no plan to inject — and no plan to be missing. Reports neutral
+	 *  (neither injected nor missing) so the preview completes instead of
+	 *  blocking on a plan a dry-run can never produce. */
+	executeWorkers?: boolean;
 }
 
 export interface InjectAdaptivePlanResult {
@@ -369,8 +382,18 @@ export interface InjectAdaptivePlanResult {
 	missingPlan: boolean;
 }
 
+/**
+ * True for workflows whose `assess` step emits a plan the runtime injects as
+ * concrete tasks. The `implementation` workflow is adaptive by name (historic
+ * hard-code, kept for backward compat); any other workflow opts in via
+ * frontmatter `adaptive: true`.
+ */
+export function isAdaptiveWorkflow(workflow: WorkflowConfig): boolean {
+	return workflow.adaptive === true || workflow.name === "implementation";
+}
+
 export async function injectAdaptivePlanIfReady(input: InjectAdaptivePlanInput): Promise<InjectAdaptivePlanResult> {
-	if (input.workflow.name !== "implementation")
+	if (!isAdaptiveWorkflow(input.workflow) || input.executeWorkers === false)
 		return {
 			tasks: input.tasks,
 			workflow: input.workflow,
@@ -409,6 +432,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 +457,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 +468,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 +505,41 @@ 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)}`;
+			// Same display contract as static workflow steps: the planner's
+			// title (or the task text's first line) names the task; the full
+			// task text is the description for detail surfaces. Never the bare
+			// stepId — the task list is the plan, not an id roster.
+			const firstLine =
+				planned.task
+					.split("\n")
+					.map((line) => line.trim())
+					.filter(Boolean)
+					.find((line) => !line.startsWith("#")) ?? "";
+			const title = (planned.title ?? firstLine ?? stepId).slice(0, 120);
+			phaseItemIds.push(itemId);
+			planItems.push({
+				id: itemId,
+				ref: stepId,
+				title,
+				taskIds: [],
+				specIds: [],
+				acceptance: [],
+				status: "pending",
+			});
 			steps.push({
 				id: stepId,
 				role: planned.role,
@@ -499,11 +553,13 @@ export async function injectAdaptivePlanIfReady(input: InjectAdaptivePlanInput):
 				stepId,
 				role: planned.role,
 				agent: input.team.roles.find((role) => role.name === planned.role)?.agent ?? planned.role,
-				title: planned.title ?? stepId,
+				title,
+				description: planned.task !== title ? planned.task : undefined,
 				status: "queued",
 				dependsOn: previousStepIds,
 				cwd: input.manifest.cwd,
 				adaptive: { phase: phase.name, task: planned.task },
+				planItem: itemId,
 				graph: {
 					taskId,
 					dependencies: previousStepIds,
@@ -513,6 +569,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 +593,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,11 +20,13 @@
 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";
 import { logInternalError } from "../../utils/internal-error.ts";
 import { packageRoot, projectCrewRoot, userPiRoot } from "../../utils/paths.ts";
+import { safeAbort } from "../../utils/safe-abort.ts";
 import { resolveRealContainedPath } from "../../utils/safe-paths.ts";
 import type { DynamicWorkflowConfig } from "../../workflows/workflow-config.ts";
 import { assertDeterministicScript, isDeterminismCheckEnabled } from "../deterministic-ast.ts";
@@ -151,7 +153,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,14 +225,17 @@ 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(() => {
 				// ERR-1: abort the timeout controller so the abort propagates to
 				// runChildPi (via the combined signal passed to makeWorkflowCtx),
 				// which kills spawned children instead of letting them run.
-				timeoutController.abort();
+				// safeAbort: the combined signal may feed a signal-spawned child
+				// (abortChildProcess AbortError would otherwise reach the
+				// uncaughtException handler from this timer callback).
+				safeAbort(timeoutController, "dwf-script-timeout");
 				reject(
 					new Error(
 						`Dynamic workflow script timed out after ${SCRIPT_TIMEOUT_MS}ms. The script may have spawned a child process that did not exit. Check for spawn/exec calls without proper stdio handling.`,

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;
@@ -175,15 +181,31 @@ export function mergeTaskUpdatesPreservingTerminal(base: TeamTaskState[], result
 			const current = indexById.get(updated.id);
 			if (!current) continue;
 			if (!shouldMergeTaskUpdate(current, updated)) {
-				// Log skipped merges for visibility into rejected parallel updates.
-				// In distributed systems with parallel workers, rejected merges may
-				// indicate bugs (wrong status, timestamp corruption) if they accumulate.
-				console.debug("[merge-gate] Skipping stale merge for task", updated.id, {
-					currentStatus: current.status,
-					updatedStatus: updated.status,
-					currentFinishedAt: current.finishedAt,
-					updatedFinishedAt: updated.finishedAt,
-				});
+				// Routine no-op skips (an unchanged queued/running snapshot
+				// arriving from a parallel worker) are NORMAL parallel-merge
+				// behaviour and must stay silent — pi renders extension
+				// console output inline in the session transcript, so logging
+				// every skip floods whatever session is open (main or an
+				// agent view). Only a REAL rejected change (status transition,
+				// completion time, or result) is surfaced, as a warning: in
+				// distributed systems, rejected transitions may indicate bugs
+				// (wrong status, timestamp corruption) if they accumulate.
+				const meaningfulDiff =
+					updated.status !== current.status ||
+					updated.finishedAt !== current.finishedAt ||
+					updated.startedAt !== current.startedAt ||
+					Boolean(updated.resultArtifact) !== Boolean(current.resultArtifact) ||
+					Boolean(updated.error) ||
+					Boolean(updated.modelAttempts?.length) ||
+					Boolean(updated.usage);
+				if (meaningfulDiff) {
+					console.warn("[merge-gate] Rejected update for task", updated.id, {
+						currentStatus: current.status,
+						updatedStatus: updated.status,
+						currentFinishedAt: current.finishedAt,
+						updatedFinishedAt: updated.finishedAt,
+					});
+				}
 				skipped += 1;
 				continue;
 			}