pi-crew 0.9.67 → 0.10.1

package/src/runtime/model/model-budget-summary.ts

@@ -0,0 +1,53 @@
+/**
+ * model-budget-summary.ts — R8 model-routing transparency (WP-8, T5).
+ *
+ * One pre-run summary line: the resolved fallback chain + the WORST-CASE
+ * spawn budget per task (`attemptModels × (maxAttempts + 1)` — the RT-6
+ * formula; always ≥ 1 full attempt above the theoretical max). Cost
+ * surprises in multi-model fallback runs were invisible until workers
+ * started burning through attempts; this makes the ceiling loud UP FRONT.
+ */
+
+import { loadConfig } from "../../config/config.ts";
+import { DEFAULT_RETRY_POLICY } from "../recovery/retry-executor.ts";
+import { computeSpawnBudgetMax } from "../task-runner/child-executor.ts";
+import { buildConfiguredModelRouting } from "./model-fallback.ts";
+
+export interface ModelBudgetSummary {
+	/** Deduped resolved chain (requested first, then fallbacks). */
+	chain: string[];
+	/** Worst-case child spawns per task: chain.length × (maxAttempts + 1). */
+	worstCaseSpawnsPerTask: number;
+	/** Configured maxAttempts (or the default when unset/unreadable). */
+	maxAttempts: number;
+	/** Rendered single-line summary for console output. */
+	line: string;
+}
+
+/** Compute the pre-run model budget summary. Never throws — degrades to an
+ *  empty chain + default attempts on any config/catalog read failure. */
+export function summarizeModelBudget(cwd: string): ModelBudgetSummary {
+	let maxAttempts = DEFAULT_RETRY_POLICY.maxAttempts;
+	let chain: string[] = [];
+	try {
+		const { config } = loadConfig(cwd);
+		// The same routing pipeline tasks use (config catalog + auto tail policy):
+		// the summary must describe what would ACTUALLY spawn, not a parallel
+		// reconstruction of it.
+		const routing = buildConfiguredModelRouting({ cwd, policy: config.runtime?.modelFallback });
+		chain = routing.candidates;
+		if (config.reliability?.retryPolicy?.maxAttempts !== undefined) {
+			maxAttempts = config.reliability.retryPolicy.maxAttempts;
+		}
+	} catch {
+		/* degrade: defaults below */
+	}
+	const worst = computeSpawnBudgetMax(Math.max(1, chain.length), maxAttempts);
+	const chainText = chain.length ? chain.join(" → ") : "(default pi model)";
+	return {
+		chain,
+		worstCaseSpawnsPerTask: worst,
+		maxAttempts,
+		line: `[team-tool.run] model routing: ${chainText} · worst-case ${worst} spawns/task (chain=${Math.max(1, chain.length)} × maxAttempts+1=${maxAttempts + 1})`,
+	};
+}

package/src/runtime/model/model-fallback.ts

@@ -273,14 +273,43 @@ export function splitThinkingSuffix(model: string): {
 	};
 }
 
+// WP-8 (R8): loud passthrough warnings — deduped per model so a chain of
+// tasks resolving the same unvalidated model warns once per process. The
+// delegate surface (spawn-policy admission) validates models against the
+// catalog itself (WP-5) and never routes through resolveModelCandidate.
+const passthroughWarned = new Set<string>();
+function warnUnvalidatedPassthrough(model: string, reason: string): void {
+	const key = `${model}|${reason}`;
+	if (passthroughWarned.has(key)) return;
+	passthroughWarned.add(key);
+	console.warn(
+		`[model-routing] unvalidated passthrough: '${model}' (${reason}) — not confirmed against the configured model catalog; spawn may fail at the provider.`,
+	);
+}
+
+/** Test seam: the dedup set is module-global (one warn per model+reason per
+ *  process); tests reset it for deterministic counting. */
+export function resetPassthroughWarnings(): void {
+	passthroughWarned.clear();
+}
+
 export function resolveModelCandidate(
 	model: string | undefined,
 	availableModels: AvailableModelInfo[] | undefined,
 	preferredProvider?: string,
 ): string | undefined {
 	if (!model) return undefined;
-	if (model.includes("/")) return model;
-	if (!availableModels || availableModels.length === 0) return model;
+	// Provider-qualified refs ("provider/model") pass through UNVALIDATED —
+	// the caller asserted a full id; there is nothing to resolve. Loud (R8):
+	// this is the documented trust path, not a silent one.
+	if (model.includes("/")) {
+		warnUnvalidatedPassthrough(model, "provider-qualified ref, no catalog check");
+		return model;
+	}
+	if (!availableModels || availableModels.length === 0) {
+		warnUnvalidatedPassthrough(model, "no model catalog available");
+		return model;
+	}
 
 	const { baseModel, thinkingSuffix } = splitThinkingSuffix(model);
 	const matches = availableModels.filter((entry) => entry.id === baseModel);
@@ -294,6 +323,7 @@ export function resolveModelCandidate(
 		// Fuzzy fallback: try to resolve via partial name matching
 		const fuzzy = fuzzyResolveModelId(baseModel, availableModels);
 		if (fuzzy) return `${fuzzy}${thinkingSuffix}`;
+		warnUnvalidatedPassthrough(model, "no exact or fuzzy catalog match");
 		return model;
 	}
 	return `${matches[0]!.fullId}${thinkingSuffix}`;

package/src/runtime/model/pi-args.ts

@@ -328,6 +328,16 @@ export function buildPiWorkerArgs(input: BuildPiWorkerArgsInput): BuildPiWorkerA
 		) {
 			allowed = allowed.filter((ext) => path.resolve(ext) === path.resolve(PROMPT_RUNTIME_EXTENSION_PATH));
 		}
+		// ADR-5 §8 (governed nesting, T3/WP-5 step 8): every spawn this builder
+		// produces runs at depth > 0 (workers are depth 1, delegate grandchildren
+		// are 2+; currentCrewDepth(base)+1 is ALWAYS >= 1) — the extension list
+		// is an unconditional ALLOWLIST: only the trusted
+		// PROMPT_RUNTIME_EXTENSION_PATH passes, REGARDLESS OF SOURCE. User-sourced
+		// agent declarations can no longer inject extensions into sub-agents
+		// (SEC-1's project-only strip left user/builtin declarations unfiltered —
+		// the audit's untested hole). The denylist + SEC-1 strip above remain as
+		// defense-in-depth; the allowlist is authoritative.
+		allowed = [];
 		for (const extension of [PROMPT_RUNTIME_EXTENSION_PATH, ...allowed]) args.push("--extension", extension);
 	} else {
 		args.push("--extension", PROMPT_RUNTIME_EXTENSION_PATH);

package/src/runtime/model/provider-extensions.ts

@@ -44,6 +44,12 @@ export interface DiscoveredProviderExtension {
  */
 const cache = new Map<string, { mtimeMs: number; result: DiscoveredProviderExtension[] }>();
 
+// R5-L3 (Round 5 LOW-3): FIFO cap at insertion (mirrors knowledgeCache in
+// knowledge-injection.ts). Entries are only removed when a re-access sees a
+// changed mtime, so distinct settings paths (e.g. per-test temp roots) would
+// otherwise accumulate for the process lifetime.
+const MAX_PROVIDER_EXTENSION_CACHE = 64;
+
 function cachedResult(settingsPath: string): { mtimeMs: number; result: DiscoveredProviderExtension[] } | undefined {
 	const entry = cache.get(settingsPath);
 	if (!entry) return undefined;
@@ -157,6 +163,10 @@ export function discoverProviderExtensions(settingsPath?: string): DiscoveredPro
 	// Cache the resolved result keyed on the settings.json path + mtime.
 	try {
 		cache.set(settingsFile, { mtimeMs: fs.statSync(settingsFile).mtimeMs, result: out });
+		if (cache.size > MAX_PROVIDER_EXTENSION_CACHE) {
+			const oldest = cache.keys().next().value;
+			if (oldest !== undefined) cache.delete(oldest);
+		}
 	} catch {
 		cache.delete(settingsFile);
 	}

package/src/runtime/orphan-worker-registry.ts

@@ -201,7 +201,7 @@ function readRegistry(): OrphanWorkerEntry[] {
 		}
 		// Silent failure is deliberate for robustness (registry read failures
 		// shouldn't crash the process), but log at warning level to aid troubleshooting.
-		console.warn(`[orphan-worker-registry] readRegistry failed: ${error}`);
+		logInternalError("orphan-worker-registry", new Error(`readRegistry failed: ${error}`), undefined, "warn");
 		return [];
 	}
 }

package/src/runtime/output/output-validator.ts

@@ -115,6 +115,51 @@ export function validateWorkerOutput(role: string, output: string): OutputValida
 	};
 }
 
+/**
+ * bug-026 sub-issue A: strict log-noise line shapes observed in the corrupted
+ * `02_explore-core.txt` result artifact (run team_20260815144514) — extension/
+ * MCP session-log stderr that the child-executor result fallback chain leaked
+ * into the result artifact when the worker payload was corrupted/empty.
+ *
+ * A trimmed non-empty line counts as log noise ONLY if it matches one of:
+ *  1. a bracket-tag extension log line: `[oc-go] ...`, `[pi-qwen-mm] ...`,
+ *     `[pi-qwen-mm] [core] [stderr] ...` — the leading tag is a lowercase
+ *     identifier (deliberately excludes capitalized bracketed prose like
+ *     `[Note] ...`), optionally followed by known sub-tags
+ *     (core/mcp/stderr/stdout/warn/info/error/debug);
+ *  2. a Python `warnings.warn(` line (deprecation-warning continuation);
+ *  3. a timestamped logging line: `2026-08-15 21:49:02,986 WARNING ...`.
+ *
+ * Anything else — prose, markdown, file:line results, `OK done.` — is NOT
+ * noise, so a single such line marks the artifact as usable content.
+ *
+ * NOTE: a `true` return is NOT by itself failure evidence; the caller
+ * (post-execution.ts) applies the two-gate rule (authoritative output
+ * sources empty AND artifact log-noise-only) before failing a task.
+ */
+const BRACKET_TAG_LOG_LINE = /^\[[a-z0-9][a-z0-9_.-]*\](?:\s*\[(?:core|mcp|stderr|stdout|warn|info|error|debug)\])*(?:\s.*)?$/;
+const PYTHON_WARNING_LINE = /(?:^|\s)warnings\.warn\(/;
+const TIMESTAMPED_LOG_LINE = /^\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}:\d{2}(?:[.,]\d{1,6})?(?:Z|[+-]\d{2}:?\d{2})?\s+[A-Za-z]+\b/;
+
+/**
+ * Detect a "stderr-only" result artifact: every non-empty trimmed line is
+ * strict log noise (see the pattern docs above). Empty/whitespace-only input
+ * returns false — emptiness is the caller's separate, explicit check.
+ * Conservative by design: any prose/markdown line makes it return false.
+ */
+export function isStderrOnlyResult(text: string): boolean {
+	if (!text?.trim()) return false;
+	let noiseLines = 0;
+	for (const line of text.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		const isNoise = BRACKET_TAG_LOG_LINE.test(trimmed) || PYTHON_WARNING_LINE.test(trimmed) || TIMESTAMPED_LOG_LINE.test(trimmed);
+		if (!isNoise) return false;
+		noiseLines++;
+	}
+	return noiseLines > 0;
+}
+
 /**
  * Extract structured findings from reviewer output.
  * Returns array of { file, line, severity, message } objects.

package/src/runtime/parent-guard.ts

@@ -1,3 +1,5 @@
+import { getCrewEnv } from "../config/env-vars.ts";
+
 /**
  * Parent liveness guard for pi-crew background-runner process.
  *
@@ -70,7 +72,7 @@
  * polling approach for near-instantaneous parent-death detection on Unix
  * systems, avoiding the polling overhead entirely.
  */
-const POLL_INTERVAL_MS = Number(process.env.PI_CREW_PARENT_GUARD_INTERVAL_MS) || 500;
+const POLL_INTERVAL_MS = Number(getCrewEnv("PI_CREW_PARENT_GUARD_INTERVAL_MS")) || 500;
 
 const guardIntervals = new Map<number, ReturnType<typeof setInterval>>();
 

package/src/runtime/peer-dep.ts

@@ -38,6 +38,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { getCrewEnv } from "../config/env-vars.ts";
 import { resolveNpmGlobalRoot } from "./pi-spawn.ts";
 
 /**
@@ -78,7 +79,7 @@ export function peerDepResolutionBases(): string[] {
 	const bases: string[] = [];
 
 	// 0. Parent-provided hint (fastest — no probe). Set by async-runner.
-	const envHint = process.env[PEER_DEP_DIR_ENV]?.trim();
+	const envHint = getCrewEnv(PEER_DEP_DIR_ENV)?.trim();
 	if (envHint) bases.push(path.resolve(envHint));
 
 	// 1. This file's location — works when pi-crew and pi-coding-agent share a

package/src/runtime/per-write-validator.ts

@@ -87,11 +87,6 @@ function rememberSeen(path: string, content: string): void {
 	}
 }
 
-/** Test seam: reset the dedup cache between tests. */
-export function resetPerWriteValidatorCache(): void {
-	seenContent.clear();
-}
-
 /**
  * Replace the validator registry (test seam). Production uses
  * DEFAULT_VALIDATORS; tests inject a custom map to exercise specific extensions.

package/src/runtime/pi-spawn.ts

@@ -3,6 +3,8 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
+import { getCrewEnv } from "../config/env-vars.ts";
+import { logInternalError } from "../utils/internal-error.ts";
 
 export interface PiSpawnCommand {
 	command: string;
@@ -30,8 +32,11 @@ function isWithinAllowedPrefixes(resolvedPath: string): boolean {
 		const execDir = path.dirname(fs.realpathSync.native(process.execPath));
 		allowedPrefixes.push(execDir.toLowerCase());
 		allowedPrefixes.push(path.join(path.dirname(execDir), "lib", "node_modules").toLowerCase());
-	} catch {
-		/* ignore */
+	} catch (error) {
+		// R17-B3 (LOW): execPath realpath failure is genuinely unexpected (the
+		// running binary vanished / permission issue) — surface it so the
+		// "cannot find pi" fallback is diagnosable.
+		logInternalError("pi-spawn.allowlist-prefixes", error, "execPath realpath failed", "warn");
 	}
 
 	// npm global bin via APPDATA
@@ -49,24 +54,46 @@ function isWithinAllowedPrefixes(resolvedPath: string): boolean {
 	try {
 		const projectBin = path.resolve("node_modules", ".bin");
 		allowedPrefixes.push(projectBin.toLowerCase());
-	} catch {
-		/* ignore */
+	} catch (error) {
+		// R17-B3: probe failure → prefix simply not allowed; keep the cause
+		// visible under PI_TEAMS_DEBUG.
+		logInternalError("pi-spawn.allowlist-prefixes.project-bin", error, undefined, "debug");
 	}
 
 	// User home npm-global
 	try {
 		const homeNpm = path.join(os.homedir(), ".npm-global", "bin");
 		allowedPrefixes.push(homeNpm.toLowerCase());
-	} catch {
-		/* ignore */
+	} catch (error) {
+		// R17-B3: probe failure → prefix simply not allowed; keep the cause
+		// visible under PI_TEAMS_DEBUG.
+		logInternalError("pi-spawn.allowlist-prefixes.npm-global", error, undefined, "debug");
 	}
 
 	// User home .local/bin
 	try {
 		const homeLocal = path.join(os.homedir(), ".local", "bin");
 		allowedPrefixes.push(homeLocal.toLowerCase());
-	} catch {
-		/* ignore */
+	} catch (error) {
+		// R17-B3: probe failure → prefix simply not allowed; keep the cause
+		// visible under PI_TEAMS_DEBUG.
+		logInternalError("pi-spawn.allowlist-prefixes.local-bin", error, undefined, "debug");
+	}
+
+	// Canonicalize prefixes (macOS: /var/folders/... realpath → /private/var/folders/...).
+	// validateExplicitBin() compares fs.realpathSync(resolved) against this list —
+	// without the canonical forms, any prefix reached through a symlink (macOS
+	// tmpdir, ~/.npm-global as symlink) rejects its own realpath'd target
+	// (CI incident: run-worker-cap.test.ts on macos-latest). Additive: original
+	// forms stay, so Windows \\?\-prefixed realpaths simply never match.
+	for (let i = 0; i < allowedPrefixes.length; i++) {
+		try {
+			const real = fs.realpathSync.native(allowedPrefixes[i]!).toLowerCase();
+			if (real !== allowedPrefixes[i] && !allowedPrefixes.includes(real)) allowedPrefixes.push(real);
+		} catch {
+			// Prefix path doesn't exist (env var points nowhere) — the original form
+			// stays; nothing to canonicalize.
+		}
 	}
 
 	return allowedPrefixes.some((prefix) => normalized.startsWith(prefix));
@@ -81,12 +108,20 @@ function resolvePiPackageRoot(): string | undefined {
 			try {
 				const pkg = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf-8")) as { name?: string };
 				if (pkg.name && PI_PACKAGE_NAMES.includes(pkg.name)) return dir;
-			} catch {
+			} catch (error) {
+				// R17-B3: the upward walk EXPECTS ENOENT probes (most dirs have no
+				// readable package.json) — debug-gated so the walk stays silent
+				// unless PI_TEAMS_DEBUG is set, but EACCES-style causes are visible.
+				logInternalError("pi-spawn.resolve-pi-package-root.probe", error, `dir=${dir}`, "debug");
 				// Continue walking upward.
 			}
 			dir = path.dirname(dir);
 		}
-	} catch {
+	} catch (error) {
+		// R17-B3: realpath failure on argv[1] is unexpected (not the normal
+		// missing-entry case, which is handled by the !entry guard above) —
+		// debug-gated visibility for the "cannot find pi" diagnosis.
+		logInternalError("pi-spawn.resolve-pi-package-root", error, `argv1=${process.argv[1] ?? ""}`, "debug");
 		return undefined;
 	}
 	return undefined;
@@ -101,7 +136,10 @@ function packageBinScript(packageJsonPath: string): string | undefined {
 		if (!binPath) return undefined;
 		const candidate = path.resolve(path.dirname(packageJsonPath), binPath);
 		return isRunnableNodeScript(candidate) ? candidate : undefined;
-	} catch {
+	} catch (error) {
+		// R17-B3 (LOW): a package.json that EXISTS but fails to parse is corrupt —
+		// not the expected ENOENT of the upward-walk probes.
+		logInternalError("pi-spawn.package-bin-script", error, `packageJsonPath=${packageJsonPath}`, "warn");
 		return undefined;
 	}
 }
@@ -115,7 +153,10 @@ function findPiPackageJsonFrom(startDir: string): string | undefined {
 				name?: string;
 			};
 			if (pkg.name && PI_PACKAGE_NAMES.includes(pkg.name)) return direct;
-		} catch {
+		} catch (error) {
+			// R17-B3: same EXPECTED-ENOENT upward-walk probe as
+			// resolvePiPackageRoot — debug-gated, keeps walking either way.
+			logInternalError("pi-spawn.find-pi-package-json.probe", error, `dir=${dir}`, "debug");
 			// Continue searching upward and in node_modules.
 		}
 		for (const pkgName of PI_PACKAGE_NAMES) {
@@ -163,7 +204,12 @@ export function resolveNpmGlobalRoot(): string | undefined {
 			windowsHide: true,
 		}).trim();
 		resolved = out.length > 0 ? out : undefined;
-	} catch {
+	} catch (error) {
+		// R17-B3 (LOW): `npm root -g` failing (npm not on PATH / timeout) means
+		// Windows non-APPDATA installs fall back to the static roots and often
+		// fail with ENOENT downstream — surface the root cause here. Memoized,
+		// so at most one warn per process.
+		logInternalError("pi-spawn.npm-root-g", error, "npm root -g probe failed", "warn");
 		resolved = undefined;
 	}
 	cachedNpmGlobalRoot = resolved ?? null;
@@ -240,14 +286,14 @@ function validateExplicitBin(explicit: string): string | undefined {
 		}
 	} catch (e) {
 		if (e instanceof Error && e.message.includes("allowed prefixes")) throw e;
-		console.error("[pi-spawn] validateExplicitBin: unexpected realpathSync error:", e);
+		logInternalError("pi-spawn", e, "validateExplicitBin: unexpected realpathSync error", "error");
 		return undefined;
 	}
 	return resolved;
 }
 
 export function getPiSpawnCommand(args: string[]): PiSpawnCommand {
-	const explicit = process.env.PI_TEAMS_PI_BIN?.trim();
+	const explicit = getCrewEnv("PI_TEAMS_PI_BIN")?.trim();
 	if (explicit) {
 		const validated = validateExplicitBin(explicit);
 		if (validated) {

package/src/runtime/plan-approval.ts

@@ -0,0 +1,125 @@
+/**
+ * Plan-approval gate helpers.
+ *
+ * Extracted from team-runner.ts (2026-08, Phase 2.6 maintainability split —
+ * plan-approval family). Pure code motion: requiresPlanApproval /
+ * isPlanApprovalPending / isMutatingTask / ensurePlanApprovalRequested moved
+ * verbatim from team-runner.ts. cancelPlanTasks stays in team-runner.ts
+ * (RT-14 structural source-pin test requires it defined there).
+ */
+
+import * as fs from "node:fs";
+import type { CrewRuntimeConfig } from "../config/config.ts";
+import { parsePlannerPlanOutput } from "../extension/plan-orchestrate.ts";
+import { appendEvent } from "../state/event-log/event-log.ts";
+import { appendPlanRevision, getCurrentPlanRecord, setPlanApproval } from "../state/stores/plan-store.ts";
+import { saveRunManifestAsync } from "../state/stores/state-store.ts";
+import type { PlanRecord, TeamRunManifest, TeamTaskState } from "../state/types.ts";
+import type { WorkflowConfig } from "../workflows/workflow-config.ts";
+import { permissionForRole } from "./role-permission.ts";
+
+export function requiresPlanApproval(_workflow: WorkflowConfig, runtimeConfig: CrewRuntimeConfig | undefined): boolean {
+	// ROADMAP T1.2: plan-level HITL applies to ANY workflow when
+	// config.runtime.requirePlanApproval === true (not just 'implementation').
+	// The gate fires at the read-only → mutating (plan → execute) boundary.
+	return runtimeConfig?.requirePlanApproval === true;
+}
+
+/** State-level predicate shared by every render surface (widget badge,
+ *  progress banner, powerbar segment) so gating is byte-identical to the
+ *  action side: `required === true && status === "pending"`. A malformed
+ *  manifest (`pending` without `required`) must NOT light up surfaces while
+ *  keys/backends refuse — single source of truth (WP-3 review F2). */
+export function isPlanApprovalStatePending(approval: TeamRunManifest["planApproval"]): boolean {
+	return approval?.required === true && approval.status === "pending";
+}
+
+export function isPlanApprovalPending(manifest: TeamRunManifest): boolean {
+	return isPlanApprovalStatePending(manifest.planApproval);
+}
+
+/**
+ * T2/R4 (ADR-4 §2, reader migration): plan-record-first approval predicate
+ * with manifest fallback. The current revision's approval state, when present,
+ * is authoritative; otherwise the legacy manifest gate decides. Pre-v2 runs
+ * (no plans.json) take exactly the old path — pinned by the migration
+ * negative AC in plan-store.test.ts.
+ */
+export function isPlanApprovalPendingEffective(manifest: TeamRunManifest): boolean {
+	const current = getCurrentPlanRecord(manifest);
+	if (current?.approval) return current.approval.status === "pending";
+	return isPlanApprovalPending(manifest);
+}
+
+/**
+ * T2/R4 (ADR-4 §8 vocabulary mapping): a deny is `cancelled` on the manifest
+ * side and `rejected` on the record side — either means "decided negative"
+ * to the scheduler cancel paths (team-runner.ts readers).
+ */
+export function isPlanApprovalDenied(manifest: TeamRunManifest): boolean {
+	if (manifest.planApproval?.status === "cancelled") return true;
+	return getCurrentPlanRecord(manifest)?.approval?.status === "rejected";
+}
+
+export function isMutatingTask(task: TeamTaskState): boolean {
+	return permissionForRole(task.role) !== "read_only";
+}
+
+export async function ensurePlanApprovalRequested(manifest: TeamRunManifest, tasks: TeamTaskState[]): Promise<TeamRunManifest> {
+	if (manifest.planApproval) return manifest;
+	const assessTask = tasks.find((task) => task.stepId === "assess" && task.status === "completed");
+	// ROADMAP T1.2: for non-adaptive workflows, fall back to the most recent
+	// completed read-only (planning) task as the plan reference.
+	const planTask = assessTask ?? [...tasks].reverse().find((t) => t.status === "completed" && !isMutatingTask(t));
+	const now = new Date().toISOString();
+
+	// T2/R4 (ADR-4 §6 producer 3 + §8 dual-write): make sure a PlanRecord
+	// exists before the gate lights up, so approval names plan id+version.
+	// - Record already present (adaptive producer ran, or a re-request after
+	//   crash between the record append and the manifest save) → reuse it.
+	// - No record → try the planner-tagged `<plan>` contract on the plan
+	//   artifact; if that fails → manifest-only gate (pre-v2 behavior, the
+	//   dual-read fallback in plan-store keeps readers correct).
+	let record = getCurrentPlanRecord(manifest);
+	if (!record && planTask?.resultArtifact?.path) {
+		try {
+			const text = fs.readFileSync(planTask.resultArtifact.path, "utf-8");
+			const parsed: PlanRecord | undefined = parsePlannerPlanOutput(text, manifest.runId, planTask.id);
+			if (parsed) record = appendPlanRevision(manifest, parsed);
+		} catch {
+			// Unreadable/unparsable artifact → manifest-only gate (below); the
+			// gate must still light up — never a throw here.
+		}
+	}
+	if (record) {
+		setPlanApproval(manifest, { status: "pending", planVersion: record.version });
+	}
+
+	const updated: TeamRunManifest = {
+		...manifest,
+		updatedAt: now,
+		planApproval: {
+			required: true,
+			status: "pending",
+			requestedAt: now,
+			updatedAt: now,
+			planTaskId: planTask?.id,
+			planArtifactPath: planTask?.resultArtifact?.path,
+		},
+		plan: record ? { id: record.id, version: record.version } : manifest.plan,
+	};
+	await saveRunManifestAsync(updated);
+	appendEvent(updated.eventsPath, {
+		type: "plan.approval_required",
+		runId: updated.runId,
+		taskId: planTask?.id,
+		message: "Plan requires explicit approval before mutating tasks run. Use: team api op=approve-plan runId=...",
+		data: { planArtifactPath: planTask?.resultArtifact?.path, planId: record?.id, planVersion: record?.version },
+	});
+	return updated;
+}
+
+/** @internal 1.9(b) test export — exercise requiresPlanApproval directly. */
+export const __test__requiresPlanApproval = requiresPlanApproval;
+/** @internal 1.9(b) test export — exercise ensurePlanApprovalRequested directly. */
+export const __test__ensurePlanApprovalRequested = ensurePlanApprovalRequested;