pi-crew 0.11.18 → 0.11.19

package/src/runtime/task-runner.ts

@@ -160,92 +160,147 @@ export async function runTeamTask(input: TaskRunnerInput): Promise<{ manifest: T
 		//     to its prompt (it diagnoses; it does not re-derive exit codes).
 		// Disabled by PI_CREW_VERIFY_GATE=0; scaffold runtime never gates.
 		if (ctx.task.role === "verifier" && ctx.runtimeKind !== "scaffold" && resolveVerifyGateEnabled()) {
-			const preGate = await runVerifierGatePreGate({
-				cwd: ctx.task.cwd,
-				signal: input.signal,
-				classifier: {
-					enabled: resolveClassifierEnabled(input.runtimeConfig?.classifierEnabled),
-					modelRegistry: input.modelRegistry,
-					classifierModel: resolveClassifierModel(input.runtimeConfig?.classifierModel),
-					eventsPath: manifest.eventsPath,
+			// PHASE 4 (U13-ADJ): the verify-gate itself must NEVER fail a task —
+			// any unexpected error in the pre-gate block (engine bug, FS failure
+			// on an artifact write) degrades to the ungated verifier spawn
+			// (exactly the pre-U13 behavior) instead of throwing out of runTeamTask.
+			// FIX (review round): the SKIP-path finalizer call is deliberately NOT
+			// inside this try — it is hoisted below. When `return await
+			// finalizeTaskResult(...)` lived in the try, a finalizer throw was
+			// swallowed by the belt catch and execution FELL THROUGH to the
+			// verifier spawn AFTER the skip event was emitted and diagnostics
+			// mutated (double-finalize / divergent task state). A finalizer error
+			// must propagate out of runTeamTask, exactly like the normal path's
+			// finalizer (pre-belt semantics).
+			let skipFinalize: TaskExecutionResult | undefined;
+			try {
+				const preGate = await runVerifierGatePreGate({
+					cwd: ctx.task.cwd,
+					signal: input.signal,
+					classifier: {
+						enabled: resolveClassifierEnabled(input.runtimeConfig?.classifierEnabled),
+						modelRegistry: input.modelRegistry,
+						classifierModel: resolveClassifierModel(input.runtimeConfig?.classifierModel),
+						eventsPath: manifest.eventsPath,
+						runId: manifest.runId,
+						taskId: ctx.task.id,
+					},
+					metricRegistry: input.metricRegistry,
+				});
+				// Diagnostic event (task.verifier_pre_gate — U6B's event type; the
+				// TEAM_EVENT_TYPES registry entry stays report-only pending a
+				// src/state/** lane, same as classifier-pre-gate's own appends).
+				appendEventFireAndForget(manifest.eventsPath, {
+					type: "task.verifier_pre_gate",
 					runId: manifest.runId,
 					taskId: ctx.task.id,
-				},
-				metricRegistry: input.metricRegistry,
-			});
-			// Diagnostic event (task.verifier_pre_gate — U6B's event type; the
-			// TEAM_EVENT_TYPES registry entry stays report-only pending a
-			// src/state/** lane, same as classifier-pre-gate's own appends).
-			appendEventFireAndForget(manifest.eventsPath, {
-				type: "task.verifier_pre_gate",
-				runId: manifest.runId,
-				taskId: ctx.task.id,
-				message: preGate.decision.skipVerifier
-					? `Deterministic verify_gate ${preGate.outcome.verdict} — LLM verifier spawn SKIPPED (${preGate.decision.reason})`
-					: `Deterministic verify_gate ${preGate.outcome.verdict} — LLM verifier spawns with gate context (${preGate.decision.reason})`,
-				data: {
-					verdict: preGate.outcome.verdict,
-					decision: preGate.decision,
-					evidenceLines: preGate.outcome.evidenceLines,
-					...(preGate.preGate ? { classifierAction: preGate.preGate.action } : {}),
-				},
-			});
-			if (preGate.decision.skipVerifier) {
-				// Terminalize WITHOUT spawning: synthesize the branch result (gate
-				// summary as the task result artifact + stdout) and reuse the full
-				// finalizer — events, hooks, persistence, verification evidence.
-				const summary = renderVerifyGateSummary(preGate.outcome, preGate.decision.reason);
-				const resultArtifact = writeArtifact(manifest.artifactsRoot, {
-					kind: "result",
-					relativePath: `results/${ctx.task.id}.txt`,
-					content: `${summary}\n`,
-					producer: ctx.task.id,
-				});
-				ctx.task = {
-					...ctx.task,
-					// Provenance: this verdict came from the deterministic gate, not a
-					// model attempt (U6B mount note: evaluator/model provenance marker).
-					diagnostics: {
-						...(ctx.task.diagnostics ?? {}),
-						verifyGate: {
-							verdict: preGate.outcome.verdict,
-							reason: preGate.decision.reason,
-							evidenceLines: preGate.outcome.evidenceLines,
-						},
+					message: preGate.decision.skipVerifier
+						? `Deterministic verify_gate ${preGate.outcome.verdict} — LLM verifier spawn SKIPPED (${preGate.decision.reason})`
+						: `Deterministic verify_gate ${preGate.outcome.verdict} — LLM verifier spawns with gate context (${preGate.decision.reason})`,
+					data: {
+						verdict: preGate.outcome.verdict,
+						decision: preGate.decision,
+						evidenceLines: preGate.outcome.evidenceLines,
+						...(preGate.outcome.determinismNote ? { determinismNote: preGate.outcome.determinismNote } : {}),
+						...(preGate.preGate ? { classifierAction: preGate.preGate.action } : {}),
 					},
-				};
-				return await finalizeTaskResult(ctx, {
-					resultArtifact,
-					logArtifact: undefined,
-					transcriptArtifact: undefined,
-					exitCode: 0,
-					error: undefined,
-					modelAttempts: [],
-					parsedOutput: undefined,
-					finalStdout: summary,
-					transcriptPath: undefined,
-					terminalEvidence: [],
-					startupEvidence: ctx.startupEvidence,
 				});
-			}
-			if (preGate.promptContext) {
-				// Spawn proceeds — attach the gate results to the verifier prompt
-				// (both channels: full prompt + the user-message half). The prompt
-				// artifact was written in pre-execution with the PRE-gate prompt;
-				// rewrite it so the persisted artifact matches what the worker saw.
-				ctx.prompt = `${ctx.prompt}\n\n${preGate.promptContext}`;
-				if (ctx.userPrompt !== undefined) ctx.userPrompt = `${ctx.userPrompt}\n\n${preGate.promptContext}`;
-				if (ctx.promptArtifact) {
-					ctx.promptArtifact = writeArtifact(manifest.artifactsRoot, {
-						kind: "prompt",
-						// Same relative-path convention pre-execution used
-						// (prompts/<taskId>.md) — ArtifactDescriptor carries only the
-						// absolute path, so the rewrite re-derives the relative path.
-						relativePath: `prompts/${ctx.task.id}.md`,
-						content: `${ctx.prompt}\n`,
-						producer: ctx.task.id,
-					});
+				if (preGate.decision.skipVerifier) {
+					// Terminalize WITHOUT spawning: synthesize the branch result (gate
+					// summary as the task result artifact + stdout) and reuse the full
+					// finalizer — events, hooks, persistence, verification evidence.
+					const summary = renderVerifyGateSummary(preGate.outcome, preGate.decision.reason);
+					// PHASE 4 gap 1 (U13-ADJ): the skip-path artifact write must NEVER
+					// fail the task — an FS error here (ENOSPC / EACCES / ENOTDIR)
+					// degrades to "no result artifact" (the finalizer treats it as
+					// optional) instead of throwing out of runTeamTask.
+					let resultArtifact: ArtifactDescriptor | undefined;
+					try {
+						resultArtifact = writeArtifact(manifest.artifactsRoot, {
+							kind: "result",
+							relativePath: `results/${ctx.task.id}.txt`,
+							content: `${summary}\n`,
+							producer: ctx.task.id,
+						});
+					} catch (error) {
+						console.error(
+							`[task-runner] verify-gate skip-path writeArtifact failed — degrading (task continues without a result artifact): ${
+								error instanceof Error ? error.message : String(error)
+							}`,
+						);
+					}
+					ctx.task = {
+						...ctx.task,
+						// Provenance: this verdict came from the deterministic gate, not a
+						// model attempt (U6B mount note: evaluator/model provenance marker).
+						diagnostics: {
+							...(ctx.task.diagnostics ?? {}),
+							verifyGate: {
+								verdict: preGate.outcome.verdict,
+								reason: preGate.decision.reason,
+								evidenceLines: preGate.outcome.evidenceLines,
+							},
+						},
+					};
+					// FIX (review round): prepare the finalizer args here but DO NOT
+					// call finalizeTaskResult inside the belt try — see the hoisted
+					// call right after the catch below.
+					skipFinalize = {
+						resultArtifact,
+						logArtifact: undefined,
+						transcriptArtifact: undefined,
+						exitCode: 0,
+						error: undefined,
+						modelAttempts: [],
+						parsedOutput: undefined,
+						finalStdout: summary,
+						transcriptPath: undefined,
+						terminalEvidence: [],
+						startupEvidence: ctx.startupEvidence,
+					};
+				}
+				if (preGate.promptContext) {
+					// Spawn proceeds — attach the gate results to the verifier prompt
+					// (both channels: full prompt + the user-message half). The prompt
+					// artifact was written in pre-execution with the PRE-gate prompt;
+					// rewrite it so the persisted artifact matches what the worker saw.
+					ctx.prompt = `${ctx.prompt}\n\n${preGate.promptContext}`;
+					if (ctx.userPrompt !== undefined) ctx.userPrompt = `${ctx.userPrompt}\n\n${preGate.promptContext}`;
+					if (ctx.promptArtifact) {
+						// PHASE 4 gap 1 (cont.): same never-fail-a-task degrade for the
+						// prompt-artifact rewrite — on FS failure keep the pre-gate
+						// artifact on disk (the worker still gets the extended prompt).
+						try {
+							ctx.promptArtifact = writeArtifact(manifest.artifactsRoot, {
+								kind: "prompt",
+								// Same relative-path convention pre-execution used
+								// (prompts/<taskId>.md) — ArtifactDescriptor carries only the
+								// absolute path, so the rewrite re-derives the relative path.
+								relativePath: `prompts/${ctx.task.id}.md`,
+								content: `${ctx.prompt}\n`,
+								producer: ctx.task.id,
+							});
+						} catch (error) {
+							console.error(
+								`[task-runner] verify-gate prompt-artifact rewrite failed — degrading (persisted prompt keeps the pre-gate content): ${
+									error instanceof Error ? error.message : String(error)
+								}`,
+							);
+						}
+					}
 				}
+			} catch (error) {
+				console.error(
+					`[task-runner] verify-gate pre-gate error — degrading to the ungated verifier spawn: ${
+						error instanceof Error ? error.message : String(error)
+					}`,
+				);
+			}
+			// FIX (review round): skip-path finalizer — OUTSIDE the belt try so a
+			// finalizer throw propagates out of runTeamTask (pre-belt semantics)
+			// instead of being swallowed and falling through to the verifier spawn.
+			if (skipFinalize !== undefined) {
+				return await finalizeTaskResult(ctx, skipFinalize);
 			}
 		}
 		// Destructure mutable fields for branch closures + sync-back

package/src/runtime/verification/verify-gate.ts

@@ -32,6 +32,13 @@
  *     outcome escalates. A FAILED gate never reaches the classifier — a cheap
  *     classifier may never rubber-stamp a failure (U6B escalation policy),
  *     so consulting it there would only burn a call.
+ *   - Layer 3 (PHASE 4, U13-ADJ determinism, DEFAULT OFF): when
+ *     PI_CREW_VERIFY_DETERMINISM=1 and the default checks are all green, the
+ *     most critical check (test-critical in the default preset) is RERUN
+ *     once; a disagreement (flaky) or a rerun executor failure downgrades
+ *     the verdict to INCONCLUSIVE — never FAILED, never a task failure. It
+ *     never changes the FAILED↔spawn logic; flag off keeps the gate
+ *     bit-for-bit identical to pre-U13-ADJ.
  *
  * SAFETY: a gate that cannot run (disabled by env, no checks resolved,
  * executor failure) degrades to "spawn the LLM verifier as today" — the
@@ -86,6 +93,10 @@ export interface VerifyGateOutcome {
 	evidenceLines: string[];
 	allPassed: boolean;
 	totalDurationMs: number;
+	/** PHASE 4 (U13-ADJ): set ONLY by the layer-3 determinism rerun when it
+	 *  detected flakiness or a rerun executor failure — the note is also
+	 *  appended to evidenceLines and shapes the rendered context trailer. */
+	determinismNote?: string;
 }
 
 /** Injected command executor. The TOOL path wraps ctx.executeTool("bash");
@@ -125,6 +136,16 @@ export function resolveVerifyGateTimeoutMs(explicit?: number): number {
 	return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_VERIFY_GATE_TIMEOUT_MS;
 }
 
+/** PHASE 4 (U13-ADJ, upgrade 2026-10-13) layer-3 toggle:
+ *  PI_CREW_VERIFY_DETERMINISM beats the explicit arg; default OFF (unset →
+ *  explicit ?? false). Flag off ⇒ the gate runs exactly as pre-U13-ADJ
+ *  (no third check, no rerun, no verdict downgrade — bit-for-bit). */
+export function resolveVerifyDeterminismEnabled(explicit?: boolean): boolean {
+	const env = getCrewEnvBool("PI_CREW_VERIFY_DETERMINISM");
+	if (env !== undefined) return env;
+	return explicit ?? false;
+}
+
 /**
  * Default check preset — the spec's "check cấu hình" set, resolved from the
  * target repo's package.json scripts so the gate adapts instead of failing:
@@ -242,6 +263,106 @@ export function createSubprocessVerifyGateExecutor(): VerifyGateExecutor {
 	};
 }
 
+/** PHASE 4 (U13-ADJ) layer-3 result — one entry per pre-gate execution. */
+export interface DeterminismLayerResult {
+	/** false → the layer did not run (budget rule / no eligible target). */
+	ran: boolean;
+	/** Metric label: "deterministic" | "flaky" | "rerun_error" when ran;
+	 *  the skip reason ("verdict_failed" | "verdict_inconclusive" |
+	 *  "no_critical_pass") otherwise. */
+	result: string;
+	/** The gate outcome AFTER the layer (the layer-1 outcome when !ran). */
+	outcome: VerifyGateOutcome;
+	/** Non-empty iff the rerun disagreed (flaky) or its executor failed. */
+	note: string;
+}
+
+/** Pick the layer-3 rerun target: the MOST critical check — the LAST check
+ *  with critical !== false that ran and PASSED (default preset order puts
+ *  test-critical last: tests are the strongest determinism signal). Checks
+ *  that failed are never rerun (pointless — a failure already escalates). */
+function pickDeterminismRerunTarget(
+	checks: VerifyGateCheck[],
+	results: VerifyGateCheckResult[],
+): { check: VerifyGateCheck; result: VerifyGateCheckResult } | undefined {
+	let target: { check: VerifyGateCheck; result: VerifyGateCheckResult } | undefined;
+	for (let i = 0; i < checks.length; i++) {
+		const check = checks[i];
+		const result = results[i];
+		if (!check || !result || result.skipped || !result.passed) continue;
+		if (check.critical === false) continue; // critical undefined = critical
+		target = { check, result };
+	}
+	return target;
+}
+
+/** PHASE 4 (U13-ADJ) layer 3 — the determinism rerun. Runs ONLY when the
+ *  layer-1 verdict is PASS (budget rule: never rerun an already-FAILED gate)
+ *  AND at least one critical check passed. Semantics:
+ *  - rerun exit 0 (agrees with run 1) → verdict stays PASS, the rerun is
+ *    recorded as a passing `determinism:<name>` check for evidence;
+ *  - rerun exit ≠ 0 (DISAGREES — flaky) → verdict INCONCLUSIVE (never
+ *    FAILED) + note "deterministic-check: flaky <name>";
+ *  - rerun executor failure (exitCode null) → INCONCLUSIVE (soft-degrade,
+ *    never FAILED) + note "deterministic-check: rerun executor error".
+ *  The layer can ONLY downgrade its own rerun check to INCONCLUSIVE — it
+ *  never changes the FAILED↔spawn decision logic. NEVER rejects. */
+export async function applyVerifyGateDeterminismLayer(
+	checks: VerifyGateCheck[],
+	outcome: VerifyGateOutcome,
+	exec: VerifyGateExecutor,
+	opts: { cwd: string; signal?: AbortSignal; timeoutMs?: number },
+): Promise<DeterminismLayerResult> {
+	// Budget rule: no pointless rerun when the gate already failed / resolved
+	// nothing — layer 3 only re-tests a GREEN gate for hidden nondeterminism.
+	if (outcome.verdict !== "PASS") {
+		return { ran: false, result: `verdict_${outcome.verdict.toLowerCase()}`, outcome, note: "" };
+	}
+	const target = pickDeterminismRerunTarget(checks, outcome.checks);
+	if (!target) {
+		return { ran: false, result: "no_critical_pass", outcome, note: "" };
+	}
+	const timeoutMs = resolveVerifyGateTimeoutMs(opts.timeoutMs);
+	const start = Date.now();
+	let rerun: VerifyGateExecutorResult;
+	try {
+		rerun = await exec(target.check.command, { cwd: opts.cwd, timeoutMs, signal: opts.signal });
+	} catch (error) {
+		// Executor contract says never-reject; defend anyway (soft-degrade).
+		rerun = { exitCode: null, output: "", error: error instanceof Error ? error.message : String(error) };
+	}
+	const rerunCheck: VerifyGateCheckResult = {
+		name: `determinism:${target.check.name}`,
+		command: target.check.command,
+		exitCode: rerun.exitCode,
+		passed: rerun.exitCode === 0,
+		durationMs: Date.now() - start,
+		outputTail: tailOutput(rerun.output ?? ""),
+		...(rerun.error ? { error: rerun.error } : {}),
+	};
+	const base = evaluateVerifyGateResults([...outcome.checks, rerunCheck]);
+	if (rerun.exitCode === 0) {
+		return { ran: true, result: "deterministic", outcome: base, note: "" };
+	}
+	const note =
+		rerun.exitCode === null
+			? `deterministic-check: rerun executor error (${target.check.name})`
+			: `deterministic-check: flaky ${target.check.name}`;
+	return {
+		ran: true,
+		result: rerun.exitCode === null ? "rerun_error" : "flaky",
+		// The rerun check's failure would otherwise read as gate FAILED — the
+		// ONLY thing layer 3 may do is downgrade ITS OWN rerun to INCONCLUSIVE.
+		outcome: {
+			...base,
+			verdict: "INCONCLUSIVE",
+			evidenceLines: [...base.evidenceLines, note],
+			determinismNote: note,
+		},
+		note,
+	};
+}
+
 export interface VerifierSpawnDecision {
 	/** true → do NOT spawn the LLM verifier; the gate verdict stands. */
 	skipVerifier: boolean;
@@ -286,10 +407,19 @@ export function renderVerifyGateContext(outcome: VerifyGateOutcome): string {
 			lines.push(`### ${check.name} output tail`, "```", tail, "```");
 		}
 	}
-	lines.push(
-		"",
-		"The deterministic gate already ran these commands — do NOT re-run them; verify the WORK (diff, files, acceptance), using these results as ground truth for build/test state.",
-	);
+	// PHASE 4 gap 2 (U13-ADJ): distinguish "executor died" (exit=err — spawn /
+	// timer failure, NO exit code) from a real exit≠0. An executor death is
+	// NOT evidence the build is broken — asserting it as ground truth would
+	// bias the LLM verifier against a possibly-fine build. Real exit≠0 keeps
+	// the original wording bit-for-bit; a flaky rerun (layer 3) gets its own
+	// trailer because "do NOT re-run / ground truth" would be provably wrong.
+	const executorDeath = outcome.checks.some((c) => !c.skipped && c.exitCode === null);
+	const trailer = executorDeath
+		? "A verification command could not run (executor error — exit=err). Treat the build/test state as UNKNOWN; run the build/tests yourself before concluding."
+		: outcome.determinismNote
+			? "The gate rerun detected NONDETERMINISM (a check passed once and failed on rerun). These gate results are NOT reliable — re-run the affected command yourself and treat the build/test state as UNKNOWN."
+			: "The deterministic gate already ran these commands — do NOT re-run them; verify the WORK (diff, files, acceptance), using these results as ground truth for build/test state.";
+	lines.push("", trailer);
 	return lines.join("\n");
 }
 
@@ -314,6 +444,9 @@ export interface VerifierGatePreGateInput {
 		taskId?: string;
 	};
 	metricRegistry?: MetricRegistry;
+	/** PHASE 4 (U13-ADJ): explicit layer-3 determinism toggle — env
+	 *  PI_CREW_VERIFY_DETERMINISM beats this; both default OFF. */
+	determinism?: boolean;
 }
 
 export interface VerifierGatePreGateResult {
@@ -333,18 +466,41 @@ function incMetric(registry: MetricRegistry | undefined, name: string, help: str
 }
 
 /**
- * Spawn-site orchestration: run the deterministic gate, consult the U6B
+ * Spawn-site orchestration: run the deterministic gate, optionally the U13-ADJ
+ * layer-3 determinism rerun (flag-gated, default OFF), consult the U6B
  * classifier layer when inconclusive, resolve the two-layer spawn decision,
  * and emit the acceptance metrics. NEVER rejects — executor failures degrade
  * to INCONCLUSIVE checks, which escalate to the LLM verifier.
  */
 export async function runVerifierGatePreGate(input: VerifierGatePreGateInput): Promise<VerifierGatePreGateResult> {
 	const checks = input.checks ?? defaultVerifyGateChecks(input.cwd);
-	const outcome = await runVerifyGate(checks, createSubprocessVerifyGateExecutor(), {
+	const exec = createSubprocessVerifyGateExecutor();
+	let outcome = await runVerifyGate(checks, exec, {
 		cwd: input.cwd,
 		signal: input.signal,
 		timeoutMs: input.timeoutMs,
 	});
+	// ── PHASE 4 (U13-ADJ) layer 3: determinism rerun (DEFAULT OFF) ──────────
+	// Only re-tests a GREEN gate: a flaky critical check or a rerun executor
+	// failure downgrades PASS→INCONCLUSIVE (never FAILED), so a nondeterministic
+	// green gate can no longer skip the LLM verifier. Flag off ⇒ skipped
+	// entirely (bit-for-bit pre-U13-ADJ behavior).
+	let determinismNote = "";
+	if (resolveVerifyDeterminismEnabled(input.determinism)) {
+		const layer = await applyVerifyGateDeterminismLayer(checks, outcome, exec, {
+			cwd: input.cwd,
+			signal: input.signal,
+			timeoutMs: input.timeoutMs,
+		});
+		outcome = layer.outcome;
+		determinismNote = layer.note;
+		incMetric(
+			input.metricRegistry,
+			"crew.verification.verify_gate_determinism_runs_total",
+			"Layer-3 determinism reruns (U13-ADJ) by result",
+			{ result: layer.result },
+		);
+	}
 	let preGate: VerifierPreGateResult | undefined;
 	if (outcome.verdict === "INCONCLUSIVE" && input.classifier?.enabled) {
 		try {
@@ -389,6 +545,7 @@ export async function runVerifierGatePreGate(input: VerifierGatePreGateInput): P
 		outcome,
 		decision,
 		...(preGate ? { preGate } : {}),
-		promptContext: decision.attachGateContext ? renderVerifyGateContext(outcome) : "",
+		promptContext:
+			decision.attachGateContext || (determinismNote !== "" && !decision.skipVerifier) ? renderVerifyGateContext(outcome) : "",
 	};
 }

package/src/state/atomic-write.ts

@@ -828,16 +828,23 @@ export function atomicWriteFile(filePath: string, content: string, options?: Ato
 export async function atomicWriteFileAsync(filePath: string, content: string, options?: AtomicWriteOptions): Promise<void> {
 	cancelPendingCoalescedWrite(filePath);
 	const { durability, mode } = normalizeOptions(options);
+	// PHASE 0 P3 (U22 bước-0): run the symlink guard BEFORE dispatching to the
+	// worker. Previously the worker branch sat ABOVE this guard, so an unsafe
+	// target was written by the worker without the main-side check, and the
+	// normalized options were dropped entirely (worker hardcoded 0o600).
+	if (!isSymlinkSafeDirCached(filePath))
+		throw new Error(`Refusing to write: target is a symlink or inside untrusted directory: ${filePath}`);
 	// Phase 1.5 (RFC 15): when the worker-thread atomic writer is enabled
 	// (PI_CREW_WORKER_ATOMIC_WRITER=1), dispatch to a dedicated worker thread
 	// that performs SYNC fs ops with no internal yields. Mitigates the
 	// non-deterministic V8/libuv crash during event-loop yields in multi-step
 	// goal-wrapped workflows.
 	if (isWorkerAtomicWriterEnabled()) {
-		return atomicWriteFileViaWorker(filePath, content);
+		// PHASE 0 P3: forward `mode` through the message protocol. Durability is
+		// not forwarded — the worker now ALWAYS fsyncs data + parent dir (defect
+		// (b) in worker-atomic-writer.ts), i.e. durability:"full" semantics.
+		return atomicWriteFileViaWorker(filePath, content, mode);
 	}
-	if (!isSymlinkSafeDirCached(filePath))
-		throw new Error(`Refusing to write: target is a symlink or inside untrusted directory: ${filePath}`);
 	// PERF (2026-08-24): shared dir memo — a sync mkdir on an existing dir is one
 	// cheap syscall; replacing `await fs.promises.mkdir` is fine because the
 	// memoized hit does not throw and does not yield the event loop.

package/src/state/coordination/locks.ts

@@ -3,10 +3,12 @@ import { randomUUID, timingSafeEqual } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { DEFAULT_LOCKS } from "../../config/defaults.ts";
+import { getCrewEnvBool } from "../../config/env-vars.ts";
 import { logInternalError } from "../../utils/internal-error.ts";
 import { sleepSync } from "../../utils/sleep.ts";
 import { ensureDirSync, isSymlinkSafeDirCached, isSymlinkSafePath } from "../atomic-write.ts";
 import type { TeamRunManifest } from "../types.ts";
+import { acquireProcessLock, isProcessLockHeldError, type ProcessLockHandle } from "./process-lock.ts";
 
 export interface RunLockOptions {
 	staleMs?: number;
@@ -305,6 +307,13 @@ function timingSafeTokenMatch(a: string, b: string): boolean {
  * never swept, no matter how old.
  *
  * Returns the lock files it removed. Idempotent: a second sweep finds nothing.
+ *
+ * @deprecated-after-window U21 (2026-10-13): async run-lock holders now also
+ * own a kernel process socket (locks.ts `withRunLock`) which needs NO sweep —
+ * it dies with its process. This file-lock sweep still covers the SYNC path
+ * (`withRunLockSync`, file-only by design) and legacy/foreign holders during
+ * the migration window; remove it after the file-lock migration window
+ * closes.
  */
 export function sweepStaleLocks(lockFiles: readonly string[], options: RunLockOptions = {}): { removed: string[] } {
 	const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
@@ -327,6 +336,10 @@ export function sweepStaleLocks(lockFiles: readonly string[], options: RunLockOp
 /**
  * US-002: discover every `run.lock` under a runs root
  * (`<runsRoot>/<runId>/run.lock`), bounded, for sweepStaleLocks. Missing → empty.
+ *
+ * @deprecated-after-window U21: alongside `sweepStaleLocks` — socket-guarded
+ * async holders need no sweep; remove after the file-lock migration window
+ * closes (sync path + legacy holders keep needing it until then).
  */
 export function discoverRunLockFiles(runsRoot: string, maxDirs = 500): string[] {
 	try {
@@ -550,6 +563,79 @@ async function acquireLockWithRetryAsync(filePath: string, staleMs: number, kind
 	}
 }
 
+/**
+ * U21 (2026-10-13): process-socket supplement toggle for the ASYNC run-lock
+ * path. Default ON; `'0'`/`'false'`/`'no'` restores the pre-U21 file-lock-only
+ * behaviour bit-for-bit (dual-holder migration window escape hatch). Read via
+ * the crew env registry — this is a HOST-process read, never passed to children
+ * (the lock name is derived from the run dir path; nothing is inherited).
+ */
+function runLockSocketSupplementEnabled(): boolean {
+	return getCrewEnvBool("PI_CREW_RUN_LOCK_SOCKET") ?? true;
+}
+
+/**
+ * U21: the kernel-socket lock name for a run-lock file path. Derived from the
+ * ABSOLUTE run dir path so every process agrees on the name for the same run
+ * regardless of cwd/relative-path spelling.
+ */
+export function runLockSocketName(filePath: string): string {
+	return `run:${path.resolve(filePath)}`;
+}
+
+/**
+ * U21 dual-guard acquire for the async run-lock: file lock FIRST (existing
+ * WAIT/backoff admission of D1 / RR-011 completely unchanged), THEN the kernel
+ * process socket (process-lock.ts, vendored from chord).
+ *
+ * If the socket is held (`reason: "locked"`) we treat it exactly like file
+ * contention: drop OUR file token (token-guarded releaseOwnLock) and keep
+ * WAITing — same `staleMs * 2` deadline budget the file-acquire loop uses —
+ * then retry the whole file+socket acquisition. When BOTH are held the caller
+ * owns the run. Non-contention socket failures propagate AFTER the file token
+ * is dropped (we never keep the file without the guard that promised it).
+ *
+ * The socket exists to harden async holders against dual-process entry where
+ * O_EXCL file locks are weak (NFS and similar); it intentionally does NOT
+ * touch the six file-lock semantics (re-entrance, token release, live WAIT,
+ * stale-steal + WARN, EPERM, ENOENT) — those all live in the file tier.
+ */
+async function acquireRunLockGuarded(filePath: string, staleMs: number): Promise<{ token: string; socket: ProcessLockHandle | undefined }> {
+	if (!runLockSocketSupplementEnabled()) {
+		// Supplement OFF (PI_CREW_RUN_LOCK_SOCKET=0): pre-U21 behaviour, bit-for-bit.
+		return { token: await acquireLockWithRetryAsync(filePath, staleMs, "run"), socket: undefined };
+	}
+	const deadline = Date.now() + staleMs * 2; // same budget as the file-acquire loop
+	let attempt = 0;
+	for (;;) {
+		const token = await acquireLockWithRetryAsync(filePath, staleMs, "run");
+		// RR-011 (F02) extended to the dual-guard window: the token must be
+		// visible as a LIVE in-process hold from the moment the file tier is
+		// ours — the socket listen below is a macrotask and can be delayed by
+		// event-loop pressure, which would otherwise make concurrent
+		// same-process acquirers misread our fresh token as a stealable corpse.
+		runLockHeldTokens.add(token);
+		try {
+			const socket = await acquireProcessLock(runLockSocketName(filePath));
+			return { token, socket };
+		} catch (error) {
+			// Never keep the file token without the socket guard that follows it.
+			runLockHeldTokens.delete(token);
+			releaseOwnLock(filePath, token);
+			if (!isProcessLockHeldError(error)) throw error;
+			// Socket contention — WAIT (timer-based, never sleepSync: the live
+			// socket holder may be another async context of THIS process, and
+			// blocking the event loop would starve it — the v0.9.26 deadlock
+			// class) and retry within the same staleMs*2 deadline.
+			if (Date.now() > deadline) {
+				throw new Error(`Run '${path.basename(filePath)}' is locked by another operation.`);
+			}
+			await sleep(Math.min(250, 25 * 2 ** attempt));
+			attempt++;
+		}
+	}
+}
+
 /**
  * General-purpose file lock for arbitrary file paths.
  * Uses the same O_EXCL atomic create strategy as run locks.
@@ -762,6 +848,13 @@ export async function withFileLockAsync<T>(filePath: string, fn: () => Promise<T
 	}
 }
 
+/**
+ * SYNC run-lock — FILE-LOCK-ONLY by design (U21): a socket listen cannot be
+ * awaited from a synchronous path, so the process-socket supplement of
+ * `withRunLock` does not apply here. Mutual exclusion between sync and async
+ * holders is still guaranteed by the SHARED file lock (an async holder always
+ * takes the file lock first, before its socket supplement).
+ */
 export function withRunLockSync<T>(manifest: TeamRunManifest, fn: () => T, options: RunLockOptions = {}): T {
 	const filePath = lockPath(manifest);
 	const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
@@ -798,6 +891,19 @@ export function withRunLockSync<T>(manifest: TeamRunManifest, fn: () => T, optio
 	});
 }
 
+/**
+ * ASYNC run-lock — U21 (2026-10-13) DUAL GUARD: the existing file lock
+ * (acquired FIRST — WAIT/backoff admission of D1 / RR-011 unchanged) is
+ * SUPPLEMENTED by a kernel process socket owned for the holder's process
+ * lifetime (see `acquireRunLockGuarded`). The supplement guards against
+ * dual-process entry where O_EXCL file locks are weak (NFS etc.); it is
+ * toggled by PI_CREW_RUN_LOCK_SOCKET (default ON, `'0'` = pre-U21 behaviour
+ * bit-for-bit). All six file-lock semantics (re-entrance, token release,
+ * live-in-process WAIT, stale-steal + WARN, EPERM, ENOENT) are unchanged and
+ * live in the file tier; the re-entrance bypass below returns BEFORE any
+ * socket acquisition, so nested same-context calls never self-deadlock on
+ * the kernel socket. Release order: socket FIRST, file token LAST.
+ */
 export async function withRunLock<T>(manifest: TeamRunManifest, fn: () => Promise<T>, options: RunLockOptions = {}): Promise<T> {
 	const filePath = lockPath(manifest);
 	const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
@@ -806,7 +912,7 @@ export async function withRunLock<T>(manifest: TeamRunManifest, fn: () => Promis
 		return await fn();
 	}
 	fs.mkdirSync(path.dirname(filePath), { recursive: true });
-	const token = await acquireLockWithRetryAsync(filePath, staleMs, "run");
+	const { token, socket } = await acquireRunLockGuarded(filePath, staleMs);
 	// RR-011 (F02): register the hold IMMEDIATELY (no await between the acquire
 	// returning and this add — otherwise a concurrent contender could observe the
 	// fresh on-disk token as a stealable corpse). Deleted in the finally below.
@@ -824,7 +930,17 @@ export async function withRunLock<T>(manifest: TeamRunManifest, fn: () => Promis
 			// RR-011 (F02): see withRunLockSync above — unregister the live token
 			// BEFORE the token-guarded releaseOwnLock (runLockHeldTokens invariant).
 			runLockHeldTokens.delete(token);
-			releaseOwnLock(filePath, token);
+			// U21: release the socket BEFORE the file token — a contender whose
+			// file-acquire already succeeded on the weak-file tier then sees the
+			// socket free only after BOTH guards of the previous holder are gone;
+			// the file stays held (by us) until the socket is fully released.
+			// FIX (review round): if socket.release() rejects, releaseOwnLock must
+			// still run — otherwise our own file token leaks on disk as a live lock.
+			try {
+				if (socket) await socket.release();
+			} finally {
+				releaseOwnLock(filePath, token);
+			}
 		}
 	});
 }