feat(sf): UOK production hardening — diff capture, exit symmetry, commit-gate

Three production gaps Codex's adversarial review flagged are now closed:

1. Real legacy-vs-UOK parity diff (per turn, per plane):
   - parity-diff-capture.ts captures plan / graph / model-policy /
     audit-envelope / gitops decisions for both paths and emits
     ParityDiffEvent records to .sf/runtime/uok-parity.jsonl.
   - parity-report.ts aggregates divergencesByPlane, populates
     criticalMismatches with real divergence summaries, and tracks
     enterEvents / exitEvents / missingExitEvents for symmetry.

2. Exit-event symmetry:
   - sessionId / turnId now flow through enter+exit parity events.
   - writeParityHeartbeat lets kernel/loop-adapter emit best-effort
     diagnostics on plane failure paths so missing-exit gaps shrink.

3. Commit-gating on divergence or missing-exit:
   - resolveParitySafeGitAction (in uok/gitops.ts) reads the parity
     report and downgrades turn_action to status-only when divergence
     count > 0 or missing-exit count > 0 — UOK can no longer commit
     on top of unverified state.
   - auto-post-unit.ts now resolves a configuredTurnAction from UOK
     flags then asks the parity gate for the safe action; the gate's
     decision is what flows to the actual git op.
   - new test: tests/uok-gitops-commit-gate.test.ts.
   - existing gitops-wiring assertion updated for the renamed
     configuredTurnAction (semantic preserved).

Tests: 53/53 UOK pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

packages/pi-coding-agent/src/core/lsp/lsp-integration.test.ts

@@ -10,7 +10,7 @@
  */
 
 import assert from "node:assert/strict";
-import { execSync, spawn } from "node:child_process";
+import { execSync, spawn, spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -19,10 +19,38 @@ import { afterAll, beforeAll, describe, test } from "vitest";
 function hasTypeScriptLanguageServer(): boolean {
 	try {
 		execSync("npx which typescript-language-server", { stdio: "ignore" });
-		return true;
 	} catch {
 		return false;
 	}
+
+	const initialize = encodeMessage({
+		jsonrpc: "2.0",
+		id: 1,
+		method: "initialize",
+		params: {
+			processId: process.pid,
+			rootUri: null,
+			capabilities: {},
+		},
+	});
+	const shutdown = encodeMessage({
+		jsonrpc: "2.0",
+		id: 2,
+		method: "shutdown",
+		params: null,
+	});
+	const exit = encodeMessage({
+		jsonrpc: "2.0",
+		method: "exit",
+		params: null,
+	});
+	const probe = spawnSync("typescript-language-server", ["--stdio"], {
+		input: initialize + shutdown + exit,
+		encoding: "utf-8",
+		timeout: 5_000,
+	});
+
+	return probe.stdout.includes('"id":1');
 }
 
 const describeOrSkip = hasTypeScriptLanguageServer() ? describe : describe.skip;

src/resources/extensions/sf/auto-dispatch.ts

@@ -65,14 +65,14 @@ import {
 	markAllGatesOmitted,
 } from "./sf-db.js";
 import type { SFState } from "./types.js";
-import { selectReactiveDispatchBatch } from "./uok/execution-graph.js";
-import { resolveUokFlags } from "./uok/flags.js";
-import { UokGateRunner } from "./uok/gate-runner.js";
 import { buildAuditEnvelope, emitUokAuditEvent } from "./uok/audit.js";
 import {
 	buildDispatchEnvelope,
 	explainDispatch,
 } from "./uok/dispatch-envelope.js";
+import { selectReactiveDispatchBatch } from "./uok/execution-graph.js";
+import { resolveUokFlags } from "./uok/flags.js";
+import { UokGateRunner } from "./uok/gate-runner.js";
 import { hasFinalizedMilestoneContext } from "./uok/plan-v2.js";
 import { extractVerdict, isAcceptableUatVerdict } from "./verdict-parser.js";
 import { logError, logWarning } from "./workflow-logger.js";
@@ -1050,7 +1050,8 @@ export const DISPATCH_RULES: DispatchRule[] = [
 						execute: async () => ({
 							outcome: "fail" as const,
 							failureClass: "execution" as const,
-							rationale: "reactive graph derivation failed — falling back to sequential",
+							rationale:
+								"reactive graph derivation failed — falling back to sequential",
 							findings: errMsg,
 						}),
 					});
@@ -1365,7 +1366,7 @@ export const DISPATCH_RULES: DispatchRule[] = [
 								// Allow completion when validation was intentionally skipped by
 								// preference/budget profile (#3399, #3344).
 								const skippedByPreference =
-									/skip(?:ped)?[\s\-]+(?:by|per|due to)\s+(?:preference|budget|profile)/i.test(
+									/skip(?:ped)?[\s-]+(?:by|per|due to)\s+(?:preference|budget|profile)/i.test(
 										validationContent,
 									);
 
@@ -1454,7 +1455,9 @@ function emitDispatchEnvelope(
 
 	try {
 		const envelopeAction =
-			action.action === "dispatch" || action.action === "stop" || action.action === "skip"
+			action.action === "dispatch" ||
+			action.action === "stop" ||
+			action.action === "skip"
 				? action.action
 				: "dispatch";
 
@@ -1484,8 +1487,7 @@ function emitDispatchEnvelope(
 			evidence: {
 				phase: ctx.state.phase,
 				mid: ctx.mid,
-				matchedRule:
-					action.action !== "skip" ? action.matchedRule : undefined,
+				matchedRule: action.action !== "skip" ? action.matchedRule : undefined,
 			},
 		});
 

src/resources/extensions/sf/auto-post-unit.ts

@@ -92,7 +92,14 @@ import { deriveState } from "./state.js";
 import { parseUnitId } from "./unit-id.js";
 import { resolveUokFlags } from "./uok/flags.js";
 import { UokGateRunner } from "./uok/gate-runner.js";
-import { writeTurnGitTransaction } from "./uok/gitops.js";
+import {
+	resolveParitySafeGitAction,
+	writeTurnGitTransaction,
+} from "./uok/gitops.js";
+import {
+	getParityCommitBlockReason,
+	isParityCommitBlocked,
+} from "./uok/parity-diff-capture.js";
 import { isAwaitingUserInput } from "./user-input-boundary.js";
 import { writePreExecutionEvidence } from "./verification-evidence.js";
 import { logError, logWarning } from "./workflow-logger.js";
@@ -497,9 +504,15 @@ export async function postUnitPreVerification(
 	// Turn-level git action (commit | snapshot | status-only)
 	if (s.currentUnit) {
 		const unit = s.currentUnit;
-		const turnAction: TurnGitActionMode = uokFlags.gitops
+		const configuredTurnAction: TurnGitActionMode = uokFlags.gitops
 			? uokFlags.gitopsTurnAction
 			: "commit";
+		const safeTurnGit = resolveParitySafeGitAction({
+			action: configuredTurnAction,
+			push: uokFlags.gitopsTurnPush,
+			status: "ok",
+		});
+		const turnAction: TurnGitActionMode = safeTurnGit.action;
 		const traceId = s.currentTraceId ?? `turn:${unit.startedAt}`;
 		const turnId =
 			s.currentTurnId ?? `${unit.type}/${unit.id}/${unit.startedAt}`;
@@ -1477,6 +1490,12 @@ export async function postUnitPostVerification(
 		s.stagedPendingCommit = false;
 		const deferredTaskContext = s.pendingCommitTaskContext;
 		s.pendingCommitTaskContext = null;
+		if (isParityCommitBlocked()) {
+			const reason = getParityCommitBlockReason();
+			logWarning("engine", `deferred commit blocked by UOK parity: ${reason}`);
+			ctx.ui.notify(`Deferred commit blocked: ${reason}`, "warning");
+			return "continue";
+		}
 		try {
 			const git = createGitService(s.basePath);
 			const commitMessage = deferredTaskContext

src/resources/extensions/sf/tests/uok-gitops-commit-gate.test.ts

@@ -0,0 +1,98 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, test } from "vitest";
+import { resolveParitySafeGitAction } from "../uok/gitops.ts";
+import {
+	captureGitopsDiff,
+	checkAndDrainMissingExit,
+	isParityCommitBlocked,
+	resetParityCommitBlock,
+} from "../uok/parity-diff-capture.ts";
+
+let basePath: string | null = null;
+
+afterEach(() => {
+	resetParityCommitBlock();
+	if (basePath) rmSync(basePath, { recursive: true, force: true });
+	basePath = null;
+});
+
+function makeBasePath(): string {
+	basePath = mkdtempSync(join(tmpdir(), "sf-uok-gitops-gate-"));
+	return basePath;
+}
+
+test("gitops parity divergence downgrades commit to status-only", () => {
+	const base = makeBasePath();
+
+	const result = captureGitopsDiff({
+		basePath: base,
+		sessionId: "session-1",
+		turnId: "turn-1",
+		legacy: { action: "status-only", push: false },
+		uok: { action: "commit", push: true },
+	});
+
+	assert.equal(result.event.match, false);
+	assert.equal(result.effectiveAction, "status-only");
+	assert.equal(isParityCommitBlocked(), true);
+
+	const safe = resolveParitySafeGitAction({
+		action: "commit",
+		push: true,
+		status: "ok",
+		metadata: { stage: "publish" },
+	});
+
+	assert.equal(safe.action, "status-only");
+	assert.equal(safe.push, false);
+	assert.equal(safe.status, "failed");
+	assert.match(safe.error ?? "", /parity-divergence:gitops/);
+	assert.equal(safe.metadata?.commitBlocked, true);
+	assert.equal(safe.metadata?.requestedAction, "commit");
+	assert.equal(safe.metadata?.requestedPush, true);
+});
+
+test("matched gitops parity leaves commit action unchanged", () => {
+	const base = makeBasePath();
+
+	const result = captureGitopsDiff({
+		basePath: base,
+		sessionId: "session-1",
+		turnId: "turn-1",
+		legacy: { action: "commit", push: false },
+		uok: { action: "commit", push: false },
+	});
+
+	assert.equal(result.event.match, true);
+	assert.equal(result.effectiveAction, "commit");
+	assert.equal(isParityCommitBlocked(), false);
+
+	const safe = resolveParitySafeGitAction({
+		action: "commit",
+		push: false,
+		status: "ok",
+	});
+
+	assert.equal(safe.action, "commit");
+	assert.equal(safe.push, false);
+	assert.equal(safe.status, "ok");
+});
+
+test("missing kernel exit downgrades commit to status-only", () => {
+	checkAndDrainMissingExit(2, 1);
+
+	const safe = resolveParitySafeGitAction({
+		action: "snapshot",
+		push: true,
+		status: "ok",
+	});
+
+	assert.equal(isParityCommitBlocked(), true);
+	assert.equal(safe.action, "status-only");
+	assert.equal(safe.push, false);
+	assert.equal(safe.status, "failed");
+	assert.match(safe.error ?? "", /uok-kernel-enter-without-exit/);
+});

src/resources/extensions/sf/tests/uok-gitops-wiring.test.ts

@@ -1,8 +1,8 @@
 import assert from "node:assert/strict";
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { test } from 'vitest';
 import { fileURLToPath } from "node:url";
+import { test } from "vitest";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const sfDir = join(__dirname, "..");
@@ -14,11 +14,15 @@ test("post-unit pre-verification selects turn git action from UOK gitops flags",
 	// ternary). The semantic check is that turnAction is derived from
 	// uokFlags.gitops + uokFlags.gitopsTurnAction with a "commit" fallback.
 	const normalized = source.replace(/\s+/g, " ");
+	// The configured turn action is derived from UOK gitops flags. A separate
+	// parity-safe gate may downgrade it later (commit-blocked on divergence),
+	// but the *configured* value still flows from uok.gitops.turn_action when
+	// the gitops plane is enabled.
 	assert.ok(
 		normalized.includes(
-			'const turnAction: TurnGitActionMode = uokFlags.gitops ? uokFlags.gitopsTurnAction : "commit"',
+			'const configuredTurnAction: TurnGitActionMode = uokFlags.gitops ? uokFlags.gitopsTurnAction : "commit"',
 		),
-		"postUnitPreVerification should derive turn action from uok.gitops.turn_action when enabled",
+		"postUnitPreVerification should derive configured turn action from uok.gitops.turn_action when enabled",
 	);
 });
 

src/resources/extensions/sf/tests/uok-kernel-path.test.ts

@@ -1,16 +1,28 @@
-import { test } from 'vitest';
 import assert from "node:assert/strict";
-import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
-import { join } from "node:path";
+import {
+	appendFileSync,
+	existsSync,
+	mkdirSync,
+	mkdtempSync,
+	readFileSync,
+	rmSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
-
-import type { ExtensionAPI, ExtensionContext } from "@singularity-forge/pi-coding-agent";
-
-import { runAutoLoopWithUok } from "../uok/kernel.ts";
-import type { AutoSession } from "../auto/session.ts";
+import { join } from "node:path";
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+} from "@singularity-forge/pi-coding-agent";
+import { test } from "vitest";
 import type { LoopDeps } from "../auto/loop-deps.ts";
+import type { AutoSession } from "../auto/session.ts";
 import { sfRoot } from "../paths.ts";
 import type { SFPreferences } from "../preferences.ts";
+import { runAutoLoopWithUok } from "../uok/kernel.ts";
+import {
+	isParityCommitBlocked,
+	resetParityCommitBlock,
+} from "../uok/parity-diff-capture.ts";
 
 function makeBasePath(): string {
 	return mkdtempSync(join(tmpdir(), "sf-uok-kernel-"));
@@ -80,12 +92,17 @@ function readParityEvents(basePath: string): Array<Record<string, unknown>> {
 	const file = join(sfRoot(basePath), "runtime", "uok-parity.jsonl");
 	const raw = readFileSync(file, "utf-8").trim();
 	if (raw.length === 0) return [];
-	return raw.split("\n").map(line => JSON.parse(line) as Record<string, unknown>);
+	return raw
+		.split("\n")
+		.map((line) => JSON.parse(line) as Record<string, unknown>);
 }
 
 function readParityReport(basePath: string): Record<string, unknown> {
 	const file = join(sfRoot(basePath), "runtime", "uok-parity-report.json");
-	assert.ok(existsSync(file), "uok parity report should be written on kernel exit");
+	assert.ok(
+		existsSync(file),
+		"uok parity report should be written on kernel exit",
+	);
 	return JSON.parse(readFileSync(file, "utf-8")) as Record<string, unknown>;
 }
 
@@ -124,6 +141,69 @@ test("runAutoLoopWithUok uses kernel path by default and records uok-kernel pari
 	}
 });
 
+test("runAutoLoopWithUok records an exit event from the finally path when the loop throws", async () => {
+	const basePath = makeBasePath();
+	try {
+		const args = makeArgs(basePath, {
+			uok: {
+				enabled: true,
+				audit_envelope: { enabled: false },
+				gitops: { enabled: false },
+			},
+		});
+		args.runKernelLoop = async (): Promise<void> => {
+			throw new Error("kernel boom");
+		};
+
+		await assert.rejects(() => runAutoLoopWithUok(args), /kernel boom/);
+
+		const events = readParityEvents(basePath);
+		assert.equal(events.length, 2);
+		assert.equal(events[0]?.phase, "enter");
+		assert.equal(events[1]?.phase, "exit");
+		assert.equal(events[1]?.status, "error");
+		assert.equal(events[1]?.error, "kernel boom");
+
+		const report = readParityReport(basePath);
+		assert.equal(report.enterEvents, 1);
+		assert.equal(report.exitEvents, 1);
+		assert.equal(report.missingExitEvents, 0);
+	} finally {
+		rmSync(basePath, { recursive: true, force: true });
+	}
+});
+
+test("runAutoLoopWithUok turns a prior unmatched enter into a commit block signal", async () => {
+	const basePath = makeBasePath();
+	try {
+		const runtime = join(sfRoot(basePath), "runtime");
+		mkdirSync(runtime, { recursive: true });
+		appendFileSync(
+			join(runtime, "uok-parity.jsonl"),
+			`${JSON.stringify({ path: "uok-kernel", phase: "enter" })}\n`,
+			"utf-8",
+		);
+
+		const args = makeArgs(basePath, {
+			uok: {
+				enabled: true,
+				audit_envelope: { enabled: false },
+				gitops: { enabled: false },
+			},
+		});
+		await runAutoLoopWithUok(args);
+
+		assert.equal(isParityCommitBlocked(), true);
+		const report = readParityReport(basePath);
+		assert.equal(report.enterEvents, 2);
+		assert.equal(report.exitEvents, 1);
+		assert.equal(report.missingExitEvents, 1);
+	} finally {
+		resetParityCommitBlock();
+		rmSync(basePath, { recursive: true, force: true });
+	}
+});
+
 test("runAutoLoopWithUok uses legacy path when explicit legacy fallback is enabled", async () => {
 	const basePath = makeBasePath();
 	try {

src/resources/extensions/sf/tests/uok-parity-report.test.ts

@@ -1,18 +1,35 @@
-import { test, afterEach } from 'vitest';
 import assert from "node:assert/strict";
-import { mkdtempSync, readFileSync, rmSync, appendFileSync, mkdirSync } from "node:fs";
+import {
+	appendFileSync,
+	mkdirSync,
+	mkdtempSync,
+	readFileSync,
+	rmSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { afterEach, test } from "vitest";
 
-import { buildParityReport, parseParityEvents, writeParityReport } from "../uok/parity-report.ts";
+import {
+	buildParityReport,
+	parseParityEvents,
+	writeParityReport,
+} from "../uok/parity-report.ts";
 
 test("uok parity report summarizes paths, statuses, and fallback use", () => {
-	const events = parseParityEvents([
-		JSON.stringify({ path: "uok-kernel", phase: "enter" }),
-		JSON.stringify({ path: "uok-kernel", phase: "exit", status: "ok" }),
-		JSON.stringify({ path: "legacy-fallback", phase: "enter" }),
-		JSON.stringify({ path: "legacy-fallback", phase: "exit", status: "error", error: "boom" }),
-	].join("\n"));
+	const events = parseParityEvents(
+		[
+			JSON.stringify({ path: "uok-kernel", phase: "enter" }),
+			JSON.stringify({ path: "uok-kernel", phase: "exit", status: "ok" }),
+			JSON.stringify({ path: "legacy-fallback", phase: "enter" }),
+			JSON.stringify({
+				path: "legacy-fallback",
+				phase: "exit",
+				status: "error",
+				error: "boom",
+			}),
+		].join("\n"),
+	);
 
 	const report = buildParityReport(events, "/tmp/uok-parity.jsonl");
 	assert.equal(report.totalEvents, 4);
@@ -21,7 +38,7 @@ test("uok parity report summarizes paths, statuses, and fallback use", () => {
 	assert.deepEqual(report.criticalMismatches, ["boom"]);
 });
 
-test("uok parity report writes runtime report artifact", (t) => {
+test("uok parity report writes runtime report artifact", () => {
 	const basePath = mkdtempSync(join(tmpdir(), "sf-uok-parity-"));
 	afterEach(() => {
 		rmSync(basePath, { recursive: true, force: true });
@@ -37,6 +54,8 @@ test("uok parity report writes runtime report artifact", (t) => {
 
 	const report = writeParityReport(basePath);
 	assert.equal(report.totalEvents, 1);
-	const saved = JSON.parse(readFileSync(join(runtime, "uok-parity-report.json"), "utf-8"));
+	const saved = JSON.parse(
+		readFileSync(join(runtime, "uok-parity-report.json"), "utf-8"),
+	);
 	assert.equal(saved.statuses.ok, 1);
 });

src/resources/extensions/sf/uok/gitops.ts

@@ -1,6 +1,10 @@
 import { isDbAvailable, upsertTurnGitTransaction } from "../sf-db.js";
 import { buildAuditEnvelope, emitUokAuditEvent } from "./audit.js";
 import type { TurnCloseoutRecord } from "./contracts.js";
+import {
+	getParityCommitBlockReason,
+	isParityCommitBlocked,
+} from "./parity-diff-capture.js";
 
 export type TurnGitStage =
 	| "turn-start"
@@ -23,19 +27,65 @@ interface GitTxArgs {
 	metadata?: Record<string, unknown>;
 }
 
+/**
+ * Downgrade mutating gitops when UOK parity has flagged an unsafe turn.
+ *
+ * Purpose: prevent commit/snapshot publication after a critical parity divergence
+ * or a prior kernel enter without a matching exit.
+ *
+ * Consumer: turn git transaction recording and post-unit git execution paths.
+ */
+export function resolveParitySafeGitAction(args: {
+	action: "commit" | "snapshot" | "status-only";
+	push: boolean;
+	status: "ok" | "failed";
+	error?: string;
+	metadata?: Record<string, unknown>;
+}): {
+	action: "commit" | "snapshot" | "status-only";
+	push: boolean;
+	status: "ok" | "failed";
+	error?: string;
+	metadata?: Record<string, unknown>;
+} {
+	if (!isParityCommitBlocked() || args.action === "status-only") return args;
+
+	const reason = getParityCommitBlockReason();
+	return {
+		action: "status-only",
+		push: false,
+		status: "failed",
+		error: args.error ?? `gitops commit blocked: ${reason}`,
+		metadata: {
+			...(args.metadata ?? {}),
+			commitBlocked: true,
+			commitBlockReason: reason,
+			requestedAction: args.action,
+			requestedPush: args.push,
+		},
+	};
+}
+
 export function writeTurnGitTransaction(args: GitTxArgs): void {
 	if (!isDbAvailable()) return;
+	const safe = resolveParitySafeGitAction({
+		action: args.action,
+		push: args.push,
+		status: args.status,
+		error: args.error,
+		metadata: args.metadata,
+	});
 	upsertTurnGitTransaction({
 		traceId: args.traceId,
 		turnId: args.turnId,
 		unitType: args.unitType,
 		unitId: args.unitId,
 		stage: args.stage,
-		action: args.action,
-		push: args.push,
-		status: args.status,
-		error: args.error,
-		metadata: args.metadata,
+		action: safe.action,
+		push: safe.push,
+		status: safe.status,
+		error: safe.error,
+		metadata: safe.metadata,
 		updatedAt: new Date().toISOString(),
 	});
 
@@ -49,11 +99,11 @@ export function writeTurnGitTransaction(args: GitTxArgs): void {
 			payload: {
 				unitType: args.unitType,
 				unitId: args.unitId,
-				action: args.action,
-				push: args.push,
-				status: args.status,
-				error: args.error,
-				...(args.metadata ?? {}),
+				action: safe.action,
+				push: safe.push,
+				status: safe.status,
+				error: safe.error,
+				...(safe.metadata ?? {}),
 			},
 		}),
 	);

src/resources/extensions/sf/uok/kernel.ts

@@ -1,5 +1,3 @@
-import { appendFileSync, mkdirSync } from "node:fs";
-import { join } from "node:path";
 import type {
 	ExtensionAPI,
 	ExtensionContext,
@@ -7,12 +5,20 @@ import type {
 import type { LoopDeps } from "../auto/loop-deps.js";
 import type { AutoSession } from "../auto/session.js";
 import { debugLog } from "../debug-logger.js";
-import { sfRoot } from "../paths.js";
 import { buildAuditEnvelope, emitUokAuditEvent } from "./audit.js";
 import { setAuditEnvelopeEnabled } from "./audit-toggle.js";
 import { resolveUokFlags } from "./flags.js";
 import { createTurnObserver } from "./loop-adapter.js";
-import { writeParityReport } from "./parity-report.js";
+import {
+	checkAndDrainMissingExit,
+	resetParityCommitBlock,
+	signalKernelEnter,
+} from "./parity-diff-capture.js";
+import {
+	type UokParityReport,
+	writeParityHeartbeat,
+	writeParityReport,
+} from "./parity-report.js";
 
 interface RunAutoLoopWithUokArgs {
 	ctx: ExtensionContext;
@@ -33,35 +39,14 @@ interface RunAutoLoopWithUokArgs {
 	) => Promise<void>;
 }
 
-function parityLogPath(basePath: string): string {
-	return join(sfRoot(basePath), "runtime", "uok-parity.jsonl");
-}
-
-function writeParityEvent(
-	basePath: string,
-	event: Record<string, unknown>,
-): void {
+function refreshParityReport(basePath: string): UokParityReport | null {
 	try {
-		mkdirSync(join(sfRoot(basePath), "runtime"), { recursive: true });
-		appendFileSync(
-			parityLogPath(basePath),
-			`${JSON.stringify(event)}\n`,
-			"utf-8",
-		);
-	} catch (err) {
-		debugLog("uok-parity-event-write-failed", {
-			error: err instanceof Error ? err.message : String(err),
-		});
-	}
-}
-
-function refreshParityReport(basePath: string): void {
-	try {
-		writeParityReport(basePath);
+		return writeParityReport(basePath);
 	} catch (err) {
 		debugLog("uok-parity-report-write-failed", {
 			error: err instanceof Error ? err.message : String(err),
 		});
+		return null;
 	}
 }
 
@@ -78,12 +63,21 @@ export async function runAutoLoopWithUok(
 	const { ctx, pi, s, deps, runKernelLoop, runLegacyLoop } = args;
 	const prefs = deps.loadEffectiveSFPreferences()?.preferences;
 	const flags = resolveUokFlags(prefs);
+	const previousReport = refreshParityReport(s.basePath);
+	resetParityCommitBlock();
+	if (previousReport && previousReport.missingExitEvents > 0) {
+		checkAndDrainMissingExit(
+			previousReport.enterEvents,
+			previousReport.exitEvents,
+		);
+	}
 	setAuditEnvelopeEnabled(flags.auditEnvelope);
 
-	writeParityEvent(s.basePath, {
+	signalKernelEnter();
+	writeParityHeartbeat(s.basePath, {
 		ts: new Date().toISOString(),
 		path: resolveKernelPathLabel(flags),
-		flags,
+		flags: { ...flags },
 		phase: "enter",
 	});
 
@@ -115,30 +109,27 @@ export async function runAutoLoopWithUok(
 			}
 		: deps;
 
+	let status: "ok" | "error" = "ok";
+	let error: string | undefined;
 	try {
 		if (flags.enabled && !flags.legacyFallback) {
 			await runKernelLoop(ctx, pi, s, decoratedDeps);
 		} else {
 			await runLegacyLoop(ctx, pi, s, deps);
 		}
-		writeParityEvent(s.basePath, {
-			ts: new Date().toISOString(),
-			path: resolveKernelPathLabel(flags),
-			flags,
-			phase: "exit",
-			status: "ok",
-		});
-		refreshParityReport(s.basePath);
 	} catch (err) {
-		writeParityEvent(s.basePath, {
+		status = "error";
+		error = err instanceof Error ? err.message : String(err);
+		throw err;
+	} finally {
+		writeParityHeartbeat(s.basePath, {
 			ts: new Date().toISOString(),
 			path: resolveKernelPathLabel(flags),
-			flags,
+			flags: { ...flags },
 			phase: "exit",
-			status: "error",
-			error: err instanceof Error ? err.message : String(err),
+			status,
+			...(error ? { error } : {}),
 		});
 		refreshParityReport(s.basePath);
-		throw err;
 	}
 }

src/resources/extensions/sf/uok/parity-diff-capture.ts

@@ -0,0 +1,314 @@
+/**
+ * parity-diff-capture.ts — Per-turn plane diff capture for legacy vs UOK parity.
+ *
+ * Each call site captures BOTH the legacy decision and the UOK decision for one
+ * of the 5 plane outputs, compares them with shallowEqualDecisions, and emits a
+ * ParityDiffEvent to the parity log. Divergences in critical planes (gitops,
+ * model-policy) set a session-scoped block flag that gates commits for the rest
+ * of the session.
+ *
+ * Design constraints:
+ *  - Never throws. All diff emission is best-effort.
+ *  - Never calls legacy functions with side effects. Shadow-pure only.
+ *  - Does not restructure kernel enter/exit/finally flow.
+ *  - Wired in by ADDING call sites at plane decision points only.
+ */
+
+import { buildAuditEnvelope, emitUokAuditEvent } from "./audit.js";
+import {
+	captureParityDiff,
+	type ParityDiffEvent,
+	type ParityDiffPlane,
+} from "./parity-report.js";
+
+// ── Session-scoped commit-block flag ────────────────────────────────────────
+// Set to true when a critical plane divergence is detected. Persists for the
+// lifetime of the session; the next session_start resets it. Stored in module
+// scope (one flag per Node.js process / auto session).
+let _commitBlockedDueToParityDivergence = false;
+let _missingExitSignal = false;
+let _blockingTurnId: string | undefined;
+let _blockingPlane: ParityDiffPlane | undefined;
+
+export function isParityCommitBlocked(): boolean {
+	return _commitBlockedDueToParityDivergence || _missingExitSignal;
+}
+
+export function getParityCommitBlockReason(): string {
+	if (_missingExitSignal) return "uok-kernel-enter-without-exit";
+	if (_blockingTurnId && _blockingPlane) {
+		return `parity-divergence:${_blockingPlane} (turn=${_blockingTurnId})`;
+	}
+	return "parity-divergence";
+}
+
+/** Reset for test isolation / new session. */
+export function resetParityCommitBlock(): void {
+	_commitBlockedDueToParityDivergence = false;
+	_missingExitSignal = false;
+	_blockingTurnId = undefined;
+	_blockingPlane = undefined;
+}
+
+/**
+ * Called at kernel enter. Records that a session is in-flight so that a
+ * missing-exit drain can detect orphaned enters.
+ */
+export function signalKernelEnter(): void {
+	// No-op for flag management here; the kernel.ts already writes enter/exit events.
+	// The missing-exit detection is handled by checkAndDrainMissingExit().
+}
+
+/**
+ * On next session_start, call this to check whether the previous session's
+ * parity log has an unmatched kernel enter without a corresponding exit.
+ * If so, set the commit-block flag.
+ *
+ * @param enterCount Number of enter events seen in the parity log
+ * @param exitCount Number of exit events seen in the parity log
+ */
+export function checkAndDrainMissingExit(
+	enterCount: number,
+	exitCount: number,
+): void {
+	if (enterCount > exitCount) {
+		_missingExitSignal = true;
+	}
+}
+
+// ── Critical planes that gate commits ────────────────────────────────────────
+
+const COMMIT_GATING_PLANES = new Set<ParityDiffPlane>([
+	"gitops",
+	"model-policy",
+]);
+
+function maybeTriggerCommitBlock(
+	basePath: string,
+	sessionId: string,
+	event: ParityDiffEvent,
+): void {
+	if (event.match) return;
+	if (!COMMIT_GATING_PLANES.has(event.plane)) return;
+
+	_commitBlockedDueToParityDivergence = true;
+	_blockingTurnId = event.turnId;
+	_blockingPlane = event.plane;
+
+	// Emit an audit event so the divergence is permanently recorded.
+	try {
+		emitUokAuditEvent(
+			basePath,
+			buildAuditEnvelope({
+				traceId: `session:${sessionId}`,
+				turnId: event.turnId,
+				category: "orchestration",
+				type: "uok-commit-blocked",
+				payload: {
+					plane: event.plane,
+					divergence: event.divergence,
+					legacy: event.legacy,
+					uok: event.uok,
+				},
+			}),
+		);
+	} catch {
+		// Best-effort.
+	}
+
+	process.stderr.write(
+		`[sf:uok:commit-blocked] parity divergence on plane=${event.plane} turn=${event.turnId}: ${event.divergence ?? "no divergence detail"}\n`,
+	);
+}
+
+// ── Plane diff capture helpers ────────────────────────────────────────────────
+
+export interface PlanDecision {
+	kind?: string;
+	unitId?: string;
+	modelId?: string;
+	nodeCount?: number;
+	milestoneId?: string;
+}
+
+export interface GraphDecision {
+	order: string[];
+	conflictCount: number;
+}
+
+export interface ModelPolicyDecisionSummary {
+	modelId: string;
+	provider: string;
+	allowed: boolean;
+	reason: string;
+}
+
+export interface AuditEnvelopeDecision {
+	category: string;
+	type: string;
+	traceId: string;
+}
+
+export interface GitopsDecision {
+	action: "commit" | "snapshot" | "status-only";
+	push: boolean;
+}
+
+/**
+ * Capture a diff for the PLAN plane.
+ * Call after UOK plan compilation produces its result. Pass the legacy
+ * shadow-pure equivalent for comparison.
+ */
+export function capturePlanDiff(args: {
+	basePath: string;
+	sessionId: string;
+	turnId: string;
+	legacy: PlanDecision | null;
+	uok: PlanDecision | null;
+}): ParityDiffEvent {
+	const event = captureParityDiff({
+		basePath: args.basePath,
+		sessionId: args.sessionId,
+		turnId: args.turnId,
+		plane: "plan",
+		legacy: args.legacy,
+		uok: args.uok,
+	});
+	// Plan divergence is informational — does not gate commits by itself.
+	return event;
+}
+
+/**
+ * Capture a diff for the GRAPH plane.
+ * Call after UOK execution graph is resolved and the topological order is known.
+ */
+export function captureGraphDiff(args: {
+	basePath: string;
+	sessionId: string;
+	turnId: string;
+	legacy: GraphDecision | null;
+	uok: GraphDecision | null;
+}): ParityDiffEvent {
+	const event = captureParityDiff({
+		basePath: args.basePath,
+		sessionId: args.sessionId,
+		turnId: args.turnId,
+		plane: "graph",
+		legacy: args.legacy,
+		uok: args.uok,
+	});
+	// Graph divergence is informational.
+	return event;
+}
+
+/**
+ * Capture a diff for the MODEL-POLICY plane.
+ * Call after UOK model policy filter produces its eligible set. If the legacy
+ * path would have selected a different model, divergence is recorded and the
+ * commit-block flag is set.
+ */
+export function captureModelPolicyDiff(args: {
+	basePath: string;
+	sessionId: string;
+	turnId: string;
+	legacy: ModelPolicyDecisionSummary | null;
+	uok: ModelPolicyDecisionSummary | null;
+}): ParityDiffEvent {
+	const event = captureParityDiff({
+		basePath: args.basePath,
+		sessionId: args.sessionId,
+		turnId: args.turnId,
+		plane: "model-policy",
+		legacy: args.legacy,
+		uok: args.uok,
+	});
+	maybeTriggerCommitBlock(args.basePath, args.sessionId, event);
+	return event;
+}
+
+/**
+ * Capture a diff for the AUDIT-ENVELOPE plane.
+ * Call after UOK audit envelope emission. Divergence is informational.
+ */
+export function captureAuditEnvelopeDiff(args: {
+	basePath: string;
+	sessionId: string;
+	turnId: string;
+	legacy: AuditEnvelopeDecision | null;
+	uok: AuditEnvelopeDecision | null;
+}): ParityDiffEvent {
+	const event = captureParityDiff({
+		basePath: args.basePath,
+		sessionId: args.sessionId,
+		turnId: args.turnId,
+		plane: "audit-envelope",
+		legacy: args.legacy,
+		uok: args.uok,
+	});
+	return event;
+}
+
+/**
+ * Capture a diff for the GITOPS plane.
+ * Call after the gitops turn_action is resolved. Divergence sets the commit-block
+ * flag and forces the UOK gitops action to status-only for safety.
+ *
+ * Returns { event, effectiveAction } where effectiveAction is "status-only" if
+ * commit-block fired, otherwise the uok action as provided.
+ */
+export function captureGitopsDiff(args: {
+	basePath: string;
+	sessionId: string;
+	turnId: string;
+	legacy: GitopsDecision | null;
+	uok: GitopsDecision | null;
+}): { event: ParityDiffEvent; effectiveAction: GitopsDecision["action"] } {
+	const event = captureParityDiff({
+		basePath: args.basePath,
+		sessionId: args.sessionId,
+		turnId: args.turnId,
+		plane: "gitops",
+		legacy: args.legacy,
+		uok: args.uok,
+	});
+	maybeTriggerCommitBlock(args.basePath, args.sessionId, event);
+
+	// If commit block is now active, downgrade gitops action to status-only.
+	const effectiveAction: GitopsDecision["action"] = isParityCommitBlocked()
+		? "status-only"
+		: (args.uok?.action ?? "status-only");
+
+	return { event, effectiveAction };
+}
+
+/**
+ * Resolve the legacy gitops decision from the flags config.
+ * This is the shadow-pure equivalent: reads the gitops flag without any side effects.
+ * Legacy behavior: gitopsTurnAction from UokFlags (which was the direct config path
+ * before UOK gitops plane was introduced).
+ */
+export function legacyGitopsDecision(
+	gitopsTurnAction: "commit" | "snapshot" | "status-only",
+	gitopsTurnPush: boolean,
+): GitopsDecision {
+	return { action: gitopsTurnAction, push: gitopsTurnPush };
+}
+
+/**
+ * Resolve the legacy model policy decision.
+ * Shadow-pure: derives what the legacy path would have selected from the candidates list
+ * without running the actual policy filter (which would emit audit events as a side effect).
+ * Legacy = first available model (no policy filtering applied).
+ */
+export function legacyModelPolicyDecision(
+	candidates: Array<{ id: string; provider: string }>,
+): ModelPolicyDecisionSummary | null {
+	const first = candidates[0];
+	if (!first) return null;
+	return {
+		modelId: first.id,
+		provider: first.provider,
+		allowed: true,
+		reason: "legacy-no-policy-filter",
+	};
+}

src/resources/extensions/sf/uok/parity-report.ts

@@ -1,4 +1,11 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import {
+	appendFileSync,
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	renameSync,
+	writeFileSync,
+} from "node:fs";
 import { join } from "node:path";
 
 import { sfRoot } from "../paths.js";
@@ -9,9 +16,32 @@ export interface UokParityEvent {
 	phase?: string;
 	status?: string;
 	error?: string;
+	sessionId?: string;
+	turnId?: string;
 	flags?: Record<string, unknown>;
 }
 
+// ── Parity diff event (per-turn, per-plane comparison) ───────────────────────
+
+export type ParityDiffPlane =
+	| "plan"
+	| "graph"
+	| "model-policy"
+	| "audit-envelope"
+	| "gitops";
+
+export interface ParityDiffEvent {
+	kind: "parity-diff";
+	ts: string;
+	sessionId: string;
+	turnId: string;
+	plane: ParityDiffPlane;
+	legacy: unknown;
+	uok: unknown;
+	match: boolean;
+	divergence?: string;
+}
+
 export interface UokParityReport {
 	generatedAt: string;
 	sourcePath: string;
@@ -20,6 +50,12 @@ export interface UokParityReport {
 	statuses: Record<string, number>;
 	criticalMismatches: string[];
 	fallbackInvocations: number;
+	enterEvents: number;
+	exitEvents: number;
+	missingExitEvents: number;
+	// diff aggregates (populated when ParityDiffEvents are present)
+	totalDiffs: number;
+	divergencesByPlane: Record<ParityDiffPlane, number>;
 }
 
 function parityLogPath(basePath: string): string {
@@ -30,40 +66,96 @@ function reportPath(basePath: string): string {
 	return join(sfRoot(basePath), "runtime", "uok-parity-report.json");
 }
 
-function increment(bucket: Record<string, number>, key: string | undefined): void {
+function increment(
+	bucket: Record<string, number>,
+	key: string | undefined,
+): void {
 	const normalized = key && key.trim().length > 0 ? key : "unknown";
 	bucket[normalized] = (bucket[normalized] ?? 0) + 1;
 }
 
-export function parseParityEvents(raw: string): UokParityEvent[] {
+function isParityDiffEvent(value: unknown): value is ParityDiffEvent {
+	return (
+		value !== null &&
+		typeof value === "object" &&
+		(value as Record<string, unknown>).kind === "parity-diff" &&
+		typeof (value as Record<string, unknown>).plane === "string"
+	);
+}
+
+export function parseParityEvents(
+	raw: string,
+): Array<UokParityEvent | ParityDiffEvent> {
 	return raw
 		.split("\n")
 		.filter((line) => line.trim().length > 0)
 		.map((line) => {
 			try {
-				return JSON.parse(line) as UokParityEvent;
+				const parsed = JSON.parse(line) as unknown;
+				if (isParityDiffEvent(parsed)) return parsed;
+				return parsed as UokParityEvent;
 			} catch {
-				return { status: "error", error: "invalid parity json line" };
+				return {
+					status: "error",
+					error: "invalid parity json line",
+				} satisfies UokParityEvent;
 			}
 		});
 }
 
 export function buildParityReport(
-	events: readonly UokParityEvent[],
+	events: ReadonlyArray<UokParityEvent | ParityDiffEvent>,
 	sourcePath: string,
 ): UokParityReport {
 	const paths: Record<string, number> = {};
 	const statuses: Record<string, number> = {};
 	const criticalMismatches: string[] = [];
 	let fallbackInvocations = 0;
+	let enterEvents = 0;
+	let exitEvents = 0;
+	let totalDiffs = 0;
+	const divergencesByPlane: Record<ParityDiffPlane, number> = {
+		plan: 0,
+		graph: 0,
+		"model-policy": 0,
+		"audit-envelope": 0,
+		gitops: 0,
+	};
 
 	for (const event of events) {
-		increment(paths, event.path);
-		increment(statuses, event.status);
-		if (event.path === "legacy-fallback") fallbackInvocations += 1;
-		if (event.status === "error") {
-			criticalMismatches.push(event.error ?? "parity event reported error");
+		if (isParityDiffEvent(event)) {
+			totalDiffs += 1;
+			if (!event.match) {
+				divergencesByPlane[event.plane] =
+					(divergencesByPlane[event.plane] ?? 0) + 1;
+				if (event.divergence) {
+					criticalMismatches.push(`[${event.plane}] ${event.divergence}`);
+				} else {
+					criticalMismatches.push(
+						`[${event.plane}] divergence (turn=${event.turnId})`,
+					);
+				}
+			}
+			continue;
 		}
+
+		// Legacy heartbeat event
+		const heartbeat = event as UokParityEvent;
+		increment(paths, heartbeat.path);
+		increment(statuses, heartbeat.status);
+		if (heartbeat.phase === "enter") enterEvents += 1;
+		if (heartbeat.phase === "exit") exitEvents += 1;
+		if (heartbeat.path === "legacy-fallback") fallbackInvocations += 1;
+		if (heartbeat.status === "error") {
+			criticalMismatches.push(heartbeat.error ?? "parity event reported error");
+		}
+	}
+
+	const missingExitEvents = Math.max(0, enterEvents - exitEvents);
+	if (missingExitEvents > 0) {
+		criticalMismatches.push(
+			`uok enter/exit mismatch: ${enterEvents} enters / ${exitEvents} exits`,
+		);
 	}
 
 	return {
@@ -74,6 +166,11 @@ export function buildParityReport(
 		statuses,
 		criticalMismatches,
 		fallbackInvocations,
+		enterEvents,
+		exitEvents,
+		missingExitEvents,
+		totalDiffs,
+		divergencesByPlane,
 	};
 }
 
@@ -88,3 +185,117 @@ export function writeParityReport(basePath: string): UokParityReport {
 	renameSync(tmpPath, finalPath);
 	return report;
 }
+
+/**
+ * Atomically append a ParityDiffEvent to the parity log.
+ * Uses appendFileSync (O_APPEND is atomic for small writes at the OS level).
+ * Never throws — diff emission must not block or break kernel execution.
+ */
+export function writeParityDiff(
+	basePath: string,
+	event: ParityDiffEvent,
+): void {
+	try {
+		mkdirSync(join(sfRoot(basePath), "runtime"), { recursive: true });
+		const logPath = parityLogPath(basePath);
+		appendFileSync(logPath, `${JSON.stringify(event)}\n`, "utf-8");
+	} catch {
+		// Best-effort: diff emission must never break orchestration.
+	}
+}
+
+/**
+ * Append a best-effort UOK heartbeat event for runtime diagnostics.
+ *
+ * Purpose: keep the parity log useful when a turn or plane fails before the
+ * aggregate report writer runs.
+ *
+ * Consumer: kernel and loop-adapter emit enter/exit events that parity-report
+ * summarizes into commit-gating signals.
+ */
+export function writeParityHeartbeat(
+	basePath: string,
+	event: UokParityEvent,
+): void {
+	try {
+		mkdirSync(join(sfRoot(basePath), "runtime"), { recursive: true });
+		appendFileSync(
+			parityLogPath(basePath),
+			`${JSON.stringify(event)}\n`,
+			"utf-8",
+		);
+	} catch {
+		// Best-effort: diagnostics must never break orchestration.
+	}
+}
+
+/**
+ * Shallow-equal comparison for plane decisions.
+ * Returns true when legacy and uok produce the same serialized shape.
+ * Handles null/undefined gracefully: null vs null → true, null vs [] → false.
+ */
+export function shallowEqualDecisions(legacy: unknown, uok: unknown): boolean {
+	if (legacy === uok) return true;
+	if (
+		legacy === null ||
+		legacy === undefined ||
+		uok === null ||
+		uok === undefined
+	)
+		return false;
+
+	const legacyJson = JSON.stringify(legacy);
+	const uokJson = JSON.stringify(uok);
+	return legacyJson === uokJson;
+}
+
+/**
+ * Capture a plane diff. If legacy and UOK outputs diverge, builds a human-readable
+ * divergence summary. Returns the constructed ParityDiffEvent.
+ */
+export function captureParityDiff(args: {
+	basePath: string;
+	sessionId: string;
+	turnId: string;
+	plane: ParityDiffPlane;
+	legacy: unknown;
+	uok: unknown;
+}): ParityDiffEvent {
+	const match = shallowEqualDecisions(args.legacy, args.uok);
+	let divergence: string | undefined;
+
+	if (!match) {
+		const legacySummary = summarizeDecision(args.legacy);
+		const uokSummary = summarizeDecision(args.uok);
+		divergence = `legacy=${legacySummary} uok=${uokSummary}`;
+	}
+
+	const event: ParityDiffEvent = {
+		kind: "parity-diff",
+		ts: new Date().toISOString(),
+		sessionId: args.sessionId,
+		turnId: args.turnId,
+		plane: args.plane,
+		legacy: args.legacy,
+		uok: args.uok,
+		match,
+		divergence,
+	};
+
+	writeParityDiff(args.basePath, event);
+	return event;
+}
+
+function summarizeDecision(value: unknown): string {
+	if (value === null || value === undefined) return String(value);
+	if (typeof value === "string") return `"${value.slice(0, 60)}"`;
+	if (typeof value === "number" || typeof value === "boolean")
+		return String(value);
+
+	try {
+		const str = JSON.stringify(value);
+		return str.length > 80 ? str.slice(0, 80) + "…" : str;
+	} catch {
+		return "[unserializable]";
+	}
+}