@gajae-code/coding-agent 0.11.7 → 0.11.9

package/src/edit/modes/patch.ts

@@ -44,6 +44,7 @@ import {
 	restoreLineEndings,
 	stripBom,
 } from "../normalize";
+import { withEditPathMutation } from "../path-mutation-lock";
 import { readEditFileText, serializeEditFileText } from "../read-file";
 import type { EditToolDetails, LspBatchRequest } from "../renderer";
 import {
@@ -93,6 +94,15 @@ export interface ApplyPatchOptions {
 	fuzzyThreshold?: number;
 	allowFuzzy?: boolean;
 	fs?: FileSystem;
+	/**
+	 * When false, skip durable cross-process file locks (in-process path mutex
+	 * still serializes). Defaults to true only for the real `defaultFileSystem`
+	 * (or when `fs` is omitted). Disk-backed adapters that are not
+	 * `defaultFileSystem` (notably production `LspFileSystem` via
+	 * `executePatchSingle`) MUST pass `crossProcessLock: true` explicitly —
+	 * object identity is not a durable-lock capability probe.
+	 */
+	crossProcessLock?: boolean;
 }
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -1409,13 +1419,29 @@ function applyHunksToContent(
 
 /**
  * Apply a patch operation to the filesystem.
+ *
+ * Concurrent mutations of the same absolute path are serialized (in-process always;
+ * cross-process file lock when using the real filesystem) so disjoint concurrent
+ * edits cannot silently overwrite each other (#2900).
  */
 export async function applyPatch(input: PatchInput, options: ApplyPatchOptions): Promise<ApplyPatchResult> {
-	return applyNormalizedPatch(input, options);
+	const resolvePath = (p: string): string => resolveToCwd(p, options.cwd);
+	const absolutePath = resolvePath(input.path);
+	const mutationPaths = [absolutePath];
+	if (input.rename) {
+		const destPath = resolvePath(input.rename);
+		if (destPath !== absolutePath) mutationPaths.push(destPath);
+	}
+	const usingDefaultFs = options.fs === undefined || options.fs === defaultFileSystem;
+	// dryRun/preview must stay read-only: never create durable `<path>.lock` dirs
+	// (would fail on read-only parents and mutate the FS during preview) (#2900 review).
+	const crossProcess = options.dryRun === true ? false : (options.crossProcessLock ?? usingDefaultFs);
+	return withEditPathMutation(mutationPaths, () => applyNormalizedPatch(input, options), { crossProcess });
 }
 
 /**
  * Apply a normalized patch operation to the filesystem.
+ * Caller must already hold path mutation rights when concurrent writers exist.
  * @internal
  */
 async function applyNormalizedPatch(input: PatchInput, options: ApplyPatchOptions): Promise<ApplyPatchResult> {
@@ -1514,6 +1540,12 @@ async function applyNormalizedPatch(input: PatchInput, options: ApplyPatchOption
 	const isMove = Boolean(input.rename) && destPath !== absolutePath;
 
 	if (!dryRun) {
+		// Commit-time CAS: reject if another writer mutated the file after our
+		// authoritative read (e.g. a process that did not take the path lock).
+		const commitContent = await readExistingPatchFile(fs, absolutePath, input.path);
+		if (commitContent !== originalContent) {
+			throw new ApplyPatchError(`concurrent edit conflict: file changed since read: ${input.path}`);
+		}
 		if (isMove) {
 			const parentDir = path.dirname(destPath);
 			if (parentDir && parentDir !== ".") {
@@ -1735,11 +1767,16 @@ export async function executePatchSingle(
 
 	const input: PatchInput = { path: resolvedPath, op, rename: resolvedRename, diff };
 	const patchFileSystem = new LspFileSystem(writethrough, signal, batchRequest, beginDeferredDiagnosticsForPath);
+	// Production edit path uses LspFileSystem (disk-backed writethrough), which is
+	// not `defaultFileSystem` by object identity. Force durable cross-process
+	// locking so multi-process agents cannot silently race past the path mutex
+	// (#2900 review: do not infer lock capability from FileSystem identity).
 	const result = await applyPatch(input, {
 		cwd: session.cwd,
 		fs: patchFileSystem,
 		fuzzyThreshold,
 		allowFuzzy,
+		crossProcessLock: true,
 	});
 
 	// Post-write verification: only meaningful for in-place updates where the

package/src/edit/modes/replace.ts

@@ -55,6 +55,7 @@ void import("@gajae-code/natives")
 		// Native unavailable; fuzzy matching uses the TS fallback.
 	});
 
+import { withEditPathMutation } from "../path-mutation-lock";
 import { readEditFileText, serializeEditFileText } from "../read-file";
 import type { EditToolDetails, LspBatchRequest } from "../renderer";
 
@@ -1087,6 +1088,47 @@ export async function executeReplaceSingle(
 	}
 
 	const absolutePath = resolvePlanPath(session, path);
+	return withEditPathMutation([absolutePath], () =>
+		executeReplaceSingleUnderLock({
+			session,
+			path,
+			params,
+			signal,
+			batchRequest,
+			allowFuzzy,
+			fuzzyThreshold,
+			writethrough,
+			beginDeferredDiagnosticsForPath,
+			absolutePath,
+			old_text,
+			new_text,
+			all,
+		}),
+	);
+}
+
+async function executeReplaceSingleUnderLock(
+	options: ExecuteReplaceSingleOptions & {
+		absolutePath: string;
+		old_text: string;
+		new_text: string;
+		all: boolean | undefined;
+	},
+): Promise<AgentToolResult<EditToolDetails, typeof replaceEditEntrySchema>> {
+	const {
+		path,
+		signal,
+		batchRequest,
+		allowFuzzy,
+		fuzzyThreshold,
+		writethrough,
+		beginDeferredDiagnosticsForPath,
+		absolutePath,
+		old_text,
+		new_text,
+		all,
+	} = options;
+
 	const rawContent = await readEditFileText(absolutePath, path);
 	const { bom, text: content } = stripBom(rawContent);
 	const originalEnding = detectLineEnding(content);

package/src/edit/path-mutation-lock.ts

@@ -0,0 +1,112 @@
+/**
+ * Path-scoped mutation coordinator for edit tools.
+ *
+ * Serializes concurrent read→compute→write windows against the same absolute
+ * path so independent sessions cannot silently overwrite each other's successful
+ * disjoint edits (https://github.com/Yeachan-Heo/gajae-code/issues/2900).
+ *
+ * - Always: in-process async mutex keyed by resolved absolute path.
+ * - Optionally: durable cross-process `<path>.lock` via `withFileLock` for real
+ *   filesystem mutations (subagents / separate processes).
+ *
+ * Nested acquisition of the same path is not supported; callers that already
+ * hold the lock must not re-enter.
+ */
+import * as path from "node:path";
+import { type FileLockOptions, withFileLock } from "../config/file-lock";
+
+type AsyncMutex = {
+	acquire(): Promise<() => void>;
+};
+
+const pathMutexes = new Map<string, AsyncMutex>();
+
+function createAsyncMutex(): AsyncMutex {
+	let locked = false;
+	const waiters: Array<() => void> = [];
+	return {
+		async acquire(): Promise<() => void> {
+			if (!locked) {
+				locked = true;
+				return () => release();
+			}
+			const { promise, resolve } = Promise.withResolvers<void>();
+			waiters.push(resolve);
+			await promise;
+			return () => release();
+		},
+	};
+
+	function release(): void {
+		const next = waiters.shift();
+		if (next) {
+			next();
+			return;
+		}
+		locked = false;
+	}
+}
+
+function mutexFor(absolutePath: string): AsyncMutex {
+	const key = path.resolve(absolutePath);
+	let mutex = pathMutexes.get(key);
+	if (!mutex) {
+		mutex = createAsyncMutex();
+		pathMutexes.set(key, mutex);
+	}
+	return mutex;
+}
+
+async function withInProcessPathLock<T>(absolutePath: string, fn: () => Promise<T>): Promise<T> {
+	const release = await mutexFor(absolutePath).acquire();
+	try {
+		return await fn();
+	} finally {
+		release();
+	}
+}
+
+/** Default lock budget: long enough for large writes + formatter writeback. */
+const DEFAULT_CROSS_PROCESS_LOCK: FileLockOptions = {
+	staleMs: 60_000,
+	retries: 600,
+	retryDelayMs: 50,
+};
+
+export type EditPathMutationOptions = {
+	/**
+	 * When true (default), also acquire a durable cross-process file lock.
+	 * Disable for injectible/in-memory filesystem tests that do not touch disk.
+	 */
+	crossProcess?: boolean;
+	fileLock?: FileLockOptions;
+};
+
+/**
+ * Run `fn` while holding exclusive mutation rights for every absolute path.
+ * Paths are locked in lexicographic order to avoid deadlocks on multi-path ops
+ * (e.g. rename source + destination).
+ */
+export async function withEditPathMutation<T>(
+	absolutePaths: readonly string[],
+	fn: () => Promise<T>,
+	options: EditPathMutationOptions = {},
+): Promise<T> {
+	const unique = [...new Set(absolutePaths.map(entry => path.resolve(entry)))].sort();
+	if (unique.length === 0) return fn();
+
+	const crossProcess = options.crossProcess !== false;
+	const fileLock = { ...DEFAULT_CROSS_PROCESS_LOCK, ...options.fileLock };
+
+	const runAt = async (index: number): Promise<T> => {
+		if (index >= unique.length) return fn();
+		const target = unique[index];
+		const next = () => runAt(index + 1);
+		return withInProcessPathLock(target, async () => {
+			if (!crossProcess) return next();
+			return withFileLock(target, next, fileLock);
+		});
+	};
+
+	return runAt(0);
+}

package/src/eval/py/executor.ts

@@ -61,7 +61,7 @@ export interface PythonExecutorOptions {
 	/** @internal Bridge session id, set by `executePython` before delegating. */
 	bridgeSessionId?: string;
 	/** @internal Bridge endpoint info, set by `executePython` before delegating. */
-	bridge?: { url: string; token: string };
+	bridge?: { url: string; capability: string };
 }
 
 export interface PythonKernelExecutor {
@@ -106,6 +106,7 @@ export interface PythonResult {
 interface PythonSession {
 	sessionId: string;
 	kernel: PythonKernel;
+	bridgeCapability?: string;
 	ownerIds: Set<string>;
 	hasFallbackOwner: boolean;
 	queue: Promise<void>;
@@ -261,14 +262,14 @@ function buildKernelEnv(options: {
 	sessionFile?: string;
 	artifactsDir?: string;
 	bridgeSessionId?: string;
-	bridge?: { url: string; token: string };
+	bridge?: { url: string; capability: string };
 }): Record<string, string> | undefined {
 	const env: Record<string, string> = {};
 	if (options.sessionFile) env.PI_SESSION_FILE = options.sessionFile;
 	if (options.artifactsDir) env.PI_ARTIFACTS_DIR = options.artifactsDir;
 	if (options.bridge && options.bridgeSessionId) {
 		env.PI_TOOL_BRIDGE_URL = options.bridge.url;
-		env.PI_TOOL_BRIDGE_TOKEN = options.bridge.token;
+		env.PI_TOOL_BRIDGE_CAPABILITY = options.bridge.capability;
 		env.PI_TOOL_BRIDGE_SESSION = options.bridgeSessionId;
 	}
 	return Object.keys(env).length > 0 ? env : undefined;
@@ -328,6 +329,7 @@ async function acquireSession(sessionId: string, cwd: string, options: PythonExe
 			const session: PythonSession = {
 				sessionId,
 				kernel,
+				bridgeCapability: options.bridge?.capability,
 				ownerIds: new Set(),
 				hasFallbackOwner: false,
 				queue: Promise.resolve(),
@@ -361,12 +363,25 @@ async function replaceSessionKernel(
 		throw new PythonExecutionCancelledError(false);
 	}
 	requireRemainingTimeoutMs(options.deadlineMs);
-	const next = await startKernel(cwd, options);
-	if (sessions.get(session.sessionId) !== session) {
-		await next.shutdown().catch(() => undefined);
-		throw new PythonExecutionCancelledError(false);
+	const bridge = options.bridge;
+	const previousCapability = bridge?.capability;
+	const nextCapability = bridge ? crypto.randomUUID() : undefined;
+	if (bridge && nextCapability) bridge.capability = nextCapability;
+	let next: PythonKernel | undefined;
+	try {
+		next = await startKernel(cwd, options);
+		if (sessions.get(session.sessionId) !== session) {
+			throw new PythonExecutionCancelledError(false);
+		}
+		session.kernel = next;
+		session.bridgeCapability = nextCapability;
+	} catch (err) {
+		await next?.shutdown().catch(() => undefined);
+		if (bridge && previousCapability && bridge.capability === nextCapability) {
+			bridge.capability = previousCapability;
+		}
+		throw err;
 	}
-	session.kernel = next;
 }
 
 async function resetSession(sessionId: string): Promise<void> {
@@ -481,8 +496,8 @@ async function executeWithKernel(
 			displayOutputs.push({ type: "status", event });
 		});
 	const unregisterBridge =
-		options?.toolSession && options?.bridgeSessionId
-			? registerPyToolBridge(options.bridgeSessionId, {
+		options?.toolSession && options?.bridgeSessionId && options.bridge
+			? registerPyToolBridge(options.bridgeSessionId, options.bridge.capability, {
 					toolSession: options.toolSession,
 					signal: options.signal,
 					emitStatus,
@@ -578,7 +593,8 @@ async function ensureKernelAvailable(cwd: string, options: PythonExecutorOptions
 async function ensureToolBridge(options: PythonExecutorOptions): Promise<void> {
 	if (!options.toolSession || options.bridge) return;
 	try {
-		options.bridge = await ensurePyToolBridge();
+		const bridge = await ensurePyToolBridge();
+		options.bridge = { ...bridge, capability: crypto.randomUUID() };
 	} catch (err) {
 		logger.warn("Failed to start Python tool bridge", {
 			error: err instanceof Error ? err.message : String(err),
@@ -607,6 +623,9 @@ async function executeOnSession(code: string, cwd: string, options: PythonExecut
 		await resetSession(sessionId);
 	}
 	const session = await acquireSession(sessionId, cwd, options);
+	if (options.bridge && session.bridgeCapability) {
+		options.bridge.capability = session.bridgeCapability;
+	}
 	return await runQueued(session, options, async () => {
 		if (options.signal?.aborted) {
 			throw new PythonExecutionCancelledError(isTimedOutCancellation(options.signal.reason, options.signal));

package/src/eval/py/prelude.py

@@ -453,10 +453,10 @@ if "__gjc_prelude_loaded__" not in globals():
 
     if all(
         _k in os.environ
-        for _k in ("PI_TOOL_BRIDGE_URL", "PI_TOOL_BRIDGE_TOKEN", "PI_TOOL_BRIDGE_SESSION")
+        for _k in ("PI_TOOL_BRIDGE_URL", "PI_TOOL_BRIDGE_CAPABILITY", "PI_TOOL_BRIDGE_SESSION")
     ):
         tool = _ToolProxy(
             os.environ["PI_TOOL_BRIDGE_URL"],
-            os.environ["PI_TOOL_BRIDGE_TOKEN"],
+            os.environ["PI_TOOL_BRIDGE_CAPABILITY"],
             os.environ["PI_TOOL_BRIDGE_SESSION"],
         )

package/src/eval/py/tool-bridge.ts

@@ -19,7 +19,10 @@ export interface PyToolBridgeEntry {
 
 export interface PyToolBridgeInfo {
 	url: string;
-	token: string;
+}
+
+interface PyToolBridgeRegistration extends PyToolBridgeEntry {
+	sessionId: string;
 }
 
 interface BridgeServer {
@@ -27,11 +30,20 @@ interface BridgeServer {
 	stop: () => Promise<void>;
 }
 
-const registrations = new Map<string, PyToolBridgeEntry>();
+const registrations = new Map<string, PyToolBridgeRegistration>();
 let serverPromise: Promise<BridgeServer> | null = null;
 
+function isCanonicalCapability(capability: string): boolean {
+	return capability.length > 0 && !/\s/.test(capability);
+}
+
+function parseBearerCapability(authorization: string | null): string | null {
+	if (!authorization?.startsWith("Bearer ")) return null;
+	const capability = authorization.slice("Bearer ".length);
+	return isCanonicalCapability(capability) ? capability : null;
+}
+
 async function startServer(): Promise<BridgeServer> {
-	const token = crypto.randomUUID();
 	const server = Bun.serve({
 		hostname: "127.0.0.1",
 		port: 0,
@@ -40,7 +52,12 @@ async function startServer(): Promise<BridgeServer> {
 			if (req.method !== "POST" || url.pathname !== "/v1/tool") {
 				return new Response("Not Found", { status: 404 });
 			}
-			if (req.headers.get("authorization") !== `Bearer ${token}`) {
+			const capability = parseBearerCapability(req.headers.get("authorization"));
+			if (!capability) {
+				return new Response("Forbidden", { status: 403 });
+			}
+			const registration = registrations.get(capability);
+			if (!registration) {
 				return new Response("Forbidden", { status: 403 });
 			}
 
@@ -55,19 +72,15 @@ async function startServer(): Promise<BridgeServer> {
 			if (!sessionId || !name) {
 				return Response.json({ ok: false, error: "Missing session/name" }, { status: 400 });
 			}
-			const entry = registrations.get(sessionId);
-			if (!entry) {
-				return Response.json(
-					{ ok: false, error: `No active Python tool bridge session: ${sessionId}` },
-					{ status: 200 },
-				);
+			if (sessionId !== registration.sessionId) {
+				return new Response("Forbidden", { status: 403 });
 			}
 
 			try {
 				const value = await callSessionTool(name, body.args, {
-					session: entry.toolSession,
-					signal: entry.signal,
-					emitStatus: entry.emitStatus,
+					session: registration.toolSession,
+					signal: registration.signal,
+					emitStatus: registration.emitStatus,
 				});
 				return Response.json({ ok: true, value });
 			} catch (err) {
@@ -81,7 +94,6 @@ async function startServer(): Promise<BridgeServer> {
 
 	const info: PyToolBridgeInfo = {
 		url: `http://${server.hostname}:${server.port}`,
-		token,
 	};
 	logger.debug("Python tool bridge listening", { url: info.url });
 
@@ -111,11 +123,15 @@ export async function ensurePyToolBridge(): Promise<PyToolBridgeInfo> {
  * Register a tool session for the duration of one execution. The returned
  * function MUST be called to remove the entry once execution finishes.
  */
-export function registerPyToolBridge(sessionId: string, entry: PyToolBridgeEntry): () => void {
-	registrations.set(sessionId, entry);
+export function registerPyToolBridge(sessionId: string, capability: string, entry: PyToolBridgeEntry): () => void {
+	if (!isCanonicalCapability(capability)) {
+		throw new Error("Python tool bridge capability must be a non-empty canonical bearer token");
+	}
+	const registration = { ...entry, sessionId };
+	registrations.set(capability, registration);
 	return () => {
-		if (registrations.get(sessionId) === entry) {
-			registrations.delete(sessionId);
+		if (registrations.get(capability) === registration) {
+			registrations.delete(capability);
 		}
 	};
 }

package/src/extensibility/gjc-plugins/runtime-adapters.ts

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
+import { bindPluginMcpToPublicNetwork } from "../../runtime-mcp/plugin-network-boundary";
 import { loadCustomTools } from "../custom-tools/loader";
 import type { CustomTool } from "../custom-tools/types";
 import { loadEffectiveGjcPluginRegistry, registryPathForScope } from "./registry";
@@ -330,7 +331,7 @@ export async function buildPluginMcpConfigs(input: { cwd: string }): Promise<{
 					// resolution path expands ${env:...}/shell templates, which would let
 					// a third-party bundle exfiltrate host secrets. Plugin-bundle MCP
 					// servers connect without bundle-declared headers.
-					configs[m.name] = { type: cfg.transport, url: cfg.url };
+					configs[m.name] = bindPluginMcpToPublicNetwork({ type: cfg.transport, url: url.toString() });
 				}
 			} catch (error) {
 				quarantine.push({

package/src/gjc-runtime/deep-interview-ambiguity.ts

@@ -25,14 +25,6 @@ import {
  * (no filesystem, no state-writer, no CLI runtime) so every writer can apply it.
  */
 
-// =============================================================================
-// Weights (mirrors the Ouroboros deterministic_floor coefficients)
-// =============================================================================
-
-const DISPUTED_FACT_WEIGHT = 0.1;
-const UNSCORED_COMPONENT_WEIGHT = 0.05;
-const AUTO_ANSWER_DILUTION_WEIGHT = 0.05;
-
 const CORE_CLARITY_DIMENSIONS = ["goal", "constraints", "criteria"] as const;
 
 export interface AmbiguityFloorBreakdown {
@@ -59,64 +51,57 @@ function asArray(value: unknown): unknown[] {
 	return Array.isArray(value) ? value : [];
 }
 
-function round2(value: number): number {
-	return Math.round(value * 100) / 100;
-}
-
-/** A disputed fact contributes pressure until it is resolved via `superseded_by` or re-confirmation. */
+/** A disputed fact contributes pressure until it is resolved or superseded. */
 function isUnresolvedDisputedFact(value: unknown): boolean {
 	if (!isPlainObject(value)) return false;
-	const fact = value as Partial<DeepInterviewEstablishedFact>;
-	if (fact.disputed !== true) return false;
+	const fact = value as Partial<DeepInterviewEstablishedFact> & { status?: unknown };
+	if (fact.disputed !== true && fact.status !== "disputed") return false;
 	return typeof fact.superseded_by !== "string" || fact.superseded_by.trim() === "";
 }
 
 /**
  * An active component is unscored while any core clarity dimension lacks a finite
- * numeric score. Deferred components are excluded (they are outside ambiguity math),
- * and the gate only arms once the topology was explicitly confirmed in Round 0.
+ * numeric score. Deferred and inactive components are outside ambiguity math.
  */
 function countUnscoredActiveComponents(topology: unknown): number {
 	if (!isPlainObject(topology) || topology.status !== "confirmed") return 0;
 	let unscored = 0;
 	for (const component of asArray(topology.components)) {
-		if (!isPlainObject(component) || component.status === "deferred") continue;
-		const clarity = isPlainObject(component.clarity_scores) ? component.clarity_scores : {};
-		const incomplete = CORE_CLARITY_DIMENSIONS.some(dimension => {
-			const score = clarity[dimension];
-			return typeof score !== "number" || !Number.isFinite(score);
-		});
-		if (incomplete) unscored += 1;
+		if (!isPlainObject(component) || component.status === "deferred" || component.active === false) continue;
+		const scores = isPlainObject(component.scores)
+			? component.scores
+			: isPlainObject(component.clarity_scores)
+				? component.clarity_scores
+				: {};
+		if (
+			CORE_CLARITY_DIMENSIONS.some(dimension => {
+				const score = scores[dimension];
+				return typeof score !== "number" || !Number.isFinite(score);
+			})
+		) {
+			unscored += 1;
+		}
 	}
 	return unscored;
 }
 
-function autoAnswerRatio(inner: Record<string, unknown>): number {
-	const autoAnswered = asArray(inner.auto_answered_rounds).length;
-	if (autoAnswered === 0) return 0;
-	const scored = asArray(inner.rounds).filter(round => isPlainObject(round) && round.lifecycle === "scored").length;
-	return Math.min(1, autoAnswered / Math.max(scored, 1));
-}
-
-// =============================================================================
-// Floor computation + clamping
-// =============================================================================
-
-/** Compute the deterministic floor from the inner deep-interview `state` object. */
+/** Compute the deterministic floor from integer units of persisted evidence. */
 export function computeAmbiguityFloor(inner: unknown): AmbiguityFloorBreakdown {
 	const state = isPlainObject(inner) ? inner : {};
 	const disputedFactCount = asArray(state.established_facts).filter(isUnresolvedDisputedFact).length;
 	const unscoredActiveComponentCount = countUnscoredActiveComponents(state.topology);
-	const ratio = autoAnswerRatio(state);
-	const floor =
-		DISPUTED_FACT_WEIGHT * disputedFactCount +
-		UNSCORED_COMPONENT_WEIGHT * unscoredActiveComponentCount +
-		AUTO_ANSWER_DILUTION_WEIGHT * ratio;
+	const scored = asArray(state.rounds).filter(round => isPlainObject(round) && round.lifecycle === "scored").length;
+	const autoAnswered = new Set(asArray(state.auto_answered_rounds).map(value => JSON.stringify(value))).size;
+	const ratioUnits = scored === 0 ? 0 : Math.min(10_000, Math.floor((autoAnswered * 10_000) / scored));
+	const floorUnits = Math.min(
+		10_000,
+		disputedFactCount * 1_000 + unscoredActiveComponentCount * 500 + Math.floor(ratioUnits / 20),
+	);
 	return {
-		floor: round2(Math.min(1, Math.max(0, floor))),
+		floor: floorUnits / 10_000,
 		disputed_fact_count: disputedFactCount,
 		unscored_active_component_count: unscoredActiveComponentCount,
-		auto_answer_ratio: round2(ratio),
+		auto_answer_ratio: ratioUnits / 10_000,
 	};
 }
 
@@ -128,10 +113,8 @@ export function clampReportedAmbiguity(reported: number, floor: number): Ambigui
 }
 
 /**
- * Mark every established fact recorded in `retractedRound` as disputed. This is the
- * mechanical contradiction signal for answer retraction: when the user replaces an
- * already-scored answer (A -> B pivot), the facts that answer established can no
- * longer be trusted, so they raise the floor until re-confirmed or superseded.
+ * Legacy pure utility for migrations and explicit repair flows. The recorder does
+ * not dispute facts when an answer is retracted: scored evidence is immutable.
  * Returns new arrays/objects; never mutates the input.
  */
 export function disputeFactsFromRetractedRound(
@@ -204,3 +187,41 @@ export function applyAmbiguityFloorToEnvelope(value: unknown): AppliedAmbiguityF
 	inner.ambiguity_floor = breakdown;
 	return { envelope: { ...envelope, state: inner }, breakdown, clamped };
 }
+export type DeepInterviewAmbiguityMilestone = "initial" | "progress" | "refined" | "ready";
+
+export function deriveAmbiguityMilestone(
+	effectiveUnits: number,
+	thresholdUnits: number,
+): DeepInterviewAmbiguityMilestone {
+	if (!Number.isSafeInteger(effectiveUnits) || effectiveUnits < 0 || effectiveUnits > 10_000) {
+		throw new RangeError("effective ambiguity units must be an integer from 0 to 10000");
+	}
+	if (!Number.isSafeInteger(thresholdUnits) || thresholdUnits < 1 || thresholdUnits > 10_000) {
+		throw new RangeError("threshold units must be an integer from 1 to 10000");
+	}
+	if (effectiveUnits <= thresholdUnits) return "ready";
+	if (effectiveUnits > 6_000) return "initial";
+	if (effectiveUnits > 3_000) return "progress";
+	return "refined";
+}
+
+export function scoreToUnits(score: number): number {
+	if (!Number.isFinite(score) || score < 0 || score > 1) throw new RangeError("score must be finite in [0, 1]");
+	const units = score * 10_000;
+	if (!Number.isSafeInteger(units)) throw new RangeError("score must be expressed in integral 1e-4 units");
+	return units;
+}
+
+export function weightedAmbiguityUnits(
+	scores: { goal: number; constraints: number; criteria: number; context?: number },
+	type: "greenfield" | "brownfield",
+): number {
+	const goal = scoreToUnits(scores.goal);
+	const constraints = scoreToUnits(scores.constraints);
+	const criteria = scoreToUnits(scores.criteria);
+	const numerator =
+		type === "brownfield"
+			? 35 * goal + 25 * constraints + 25 * criteria + 15 * scoreToUnits(scores.context ?? Number.NaN)
+			: 40 * goal + 30 * constraints + 30 * criteria;
+	return 10_000 - Math.floor(numerator / 100 + 0.5);
+}