@sayknow-cli/coding-agent 0.3.6 → 0.3.8

package/src/skc-runtime/session-state-sidecar.ts

@@ -1,13 +1,35 @@
+import * as fsSync from "node:fs";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import type { AssistantMessage } from "@sayknow-cli/ai";
-import { logger } from "@sayknow-cli/utils";
+import { logger, postmortem } from "@sayknow-cli/utils";
+import { sessionRuntimeDir } from "./session-layout";
 
 export const SKC_COORDINATOR_SESSION_STATE_FILE_ENV = "SKC_COORDINATOR_SESSION_STATE_FILE";
 export const SKC_COORDINATOR_SESSION_ID_ENV = "SKC_COORDINATOR_SESSION_ID";
+export const SKC_COORDINATOR_SESSION_BRANCH_ENV = "SKC_COORDINATOR_SESSION_BRANCH";
+const SKC_SESSION_PROMPT_ACCEPTED_JSON_ENV = "SKC_SESSION_PROMPT_ACCEPTED_JSON";
+const SKC_SESSION_WORKTREE_BASELINE_DIRTY_ENV = "SKC_SESSION_WORKTREE_BASELINE_DIRTY";
 
 export type RuntimeState = "ready_for_input" | "running" | "needs_user_input" | "completed" | "errored";
 
+type FinalResponseSource = "agent_end" | "launch_error";
+const MAX_PUBLIC_ERROR_MESSAGE_LENGTH = 2000;
+const HEARTBEAT_MS = 1000;
+
+type LastPayloadCacheEntry = { mtimeMs: number; size: number; payload: Record<string, unknown> };
+const lastPayloadByStateFile = new Map<string, LastPayloadCacheEntry>();
+
+/** Test-only counters for runtime sidecar hot-path assertions. */
+export const __sessionStateSidecarPerfCounters = {
+	persistFromEventCalls: 0,
+	reset(): void {
+		this.persistFromEventCalls = 0;
+	},
+};
+
+const lastWrittenPayloadByStateFile = new Map<string, Record<string, unknown>>();
+
 interface RuntimeStateEvent {
 	type: string;
 	messages?: unknown[];
@@ -17,6 +39,7 @@ interface RuntimeStateContext {
 	sessionId: string;
 	cwd: string;
 	sessionFile?: string | null;
+	branch?: string | null;
 }
 
 interface RuntimeStateSidecarPayload {
@@ -25,7 +48,9 @@ interface RuntimeStateSidecarPayload {
 	state?: unknown;
 	ready_for_input?: unknown;
 	cwd?: unknown;
+	workdir?: unknown;
 	session_file?: unknown;
+	final_response?: { source?: unknown };
 }
 
 export type TerminalRuntimeStateStatus =
@@ -45,6 +70,11 @@ function sameResolvedPath(left: string, right: string): boolean {
 	return path.resolve(left) === path.resolve(right);
 }
 
+function isCoordinatorOwnedStateFile(stateFile: string): boolean {
+	const coordinatorStateFile = process.env[SKC_COORDINATOR_SESSION_STATE_FILE_ENV]?.trim();
+	return !!coordinatorStateFile && sameResolvedPath(coordinatorStateFile, stateFile);
+}
+
 export async function readTerminalRuntimeStateMarker(input: {
 	stateFile?: string | null;
 	sessionId?: string | null;
@@ -103,7 +133,7 @@ function assistantText(assistant: AssistantMessage | undefined): string | null {
 function finalResponseForEvent(event: RuntimeStateEvent): {
 	text: string | null;
 	format: "markdown";
-	source: "agent_end";
+	source: FinalResponseSource;
 	artifact_path: null;
 	truncated: false;
 } | null {
@@ -117,7 +147,7 @@ function finalResponseForEvent(event: RuntimeStateEvent): {
 	};
 }
 
-function stateForEvent(event: RuntimeStateEvent): RuntimeState | null {
+export function stateForEvent(event: RuntimeStateEvent): RuntimeState | null {
 	if (event.type === "agent_start" || event.type === "turn_start") return "running";
 	if (event.type === "agent_end") {
 		const assistant = lastAssistant(event.messages);
@@ -127,51 +157,407 @@ function stateForEvent(event: RuntimeStateEvent): RuntimeState | null {
 	return null;
 }
 
+export function eventAffectsCoordinatorRuntimeState(event: RuntimeStateEvent): boolean {
+	return stateForEvent(event) !== null;
+}
+
+function readPreviousPayload(stateFile: string): Record<string, unknown> {
+	try {
+		return JSON.parse(fsSync.readFileSync(stateFile, "utf8")) as Record<string, unknown>;
+	} catch {
+		return {};
+	}
+}
+
+async function readPreviousPayloadForEvent(stateFile: string): Promise<Record<string, unknown>> {
+	if (!isCoordinatorOwnedStateFile(stateFile)) {
+		const cachedWritten = lastWrittenPayloadByStateFile.get(stateFile);
+		if (cachedWritten) return cachedWritten;
+	}
+	let stat: Awaited<ReturnType<typeof fs.stat>>;
+	try {
+		stat = await fs.stat(stateFile);
+	} catch {
+		lastPayloadByStateFile.delete(stateFile);
+		return {};
+	}
+	const cached = lastPayloadByStateFile.get(stateFile);
+	if (cached && cached.mtimeMs === stat.mtimeMs && cached.size === stat.size) return cached.payload;
+	try {
+		const payload = JSON.parse(await Bun.file(stateFile).text()) as Record<string, unknown>;
+		lastPayloadByStateFile.set(stateFile, { mtimeMs: stat.mtimeMs, size: stat.size, payload });
+		return payload;
+	} catch {
+		lastPayloadByStateFile.delete(stateFile);
+		return {};
+	}
+}
+
+function withoutUpdatedAt(payload: Record<string, unknown>): Record<string, unknown> {
+	const { updated_at: _updatedAt, ...rest } = payload;
+	return rest;
+}
+
+function shouldSkipRuntimeStateWrite(
+	previous: Record<string, unknown>,
+	payload: Record<string, unknown>,
+	nowMs: number,
+): boolean {
+	if (payload.state === "completed" || payload.state === "errored") return false;
+	if (previous.state !== payload.state) return false;
+	if (previous.state !== "running" || payload.state !== "running") return false;
+	if (JSON.stringify(withoutUpdatedAt(previous)) !== JSON.stringify(withoutUpdatedAt(payload))) return false;
+	const previousUpdatedAt = typeof previous.updated_at === "string" ? Date.parse(previous.updated_at) : NaN;
+	if (!Number.isFinite(previousUpdatedAt)) return false;
+	return nowMs - previousUpdatedAt < HEARTBEAT_MS;
+}
+
+function rememberWrittenPayload(stateFile: string, payload: Record<string, unknown>): void {
+	lastWrittenPayloadByStateFile.set(stateFile, payload);
+	try {
+		const stat = fsSync.statSync(stateFile);
+		lastPayloadByStateFile.set(stateFile, { mtimeMs: stat.mtimeMs, size: stat.size, payload });
+	} catch {
+		lastPayloadByStateFile.delete(stateFile);
+	}
+}
+function shouldPreserveTerminalPayload(
+	previous: RuntimeStateSidecarPayload,
+	input: { sessionId: string; cwd: string; sessionFile?: string | null },
+): boolean {
+	if (previous.state !== "completed" && previous.state !== "errored") return false;
+	const source = previous.final_response?.source;
+	if (source !== "agent_end" && source !== "launch_error") return false;
+	if (typeof previous.session_id === "string" && previous.session_id !== input.sessionId) return false;
+	if (typeof previous.cwd === "string" && !sameResolvedPath(previous.cwd, input.cwd)) return false;
+	if (typeof previous.workdir === "string" && !sameResolvedPath(previous.workdir, input.cwd)) return false;
+	if (
+		input.sessionFile &&
+		typeof previous.session_file === "string" &&
+		!sameResolvedPath(previous.session_file, input.sessionFile)
+	) {
+		return false;
+	}
+	return true;
+}
+
+function cachedTerminalPayload(
+	stateFile: string,
+	input: { sessionId: string; cwd: string; sessionFile?: string | null },
+): RuntimeStateSidecarPayload | null {
+	const cached = lastWrittenPayloadByStateFile.get(stateFile) as RuntimeStateSidecarPayload | undefined;
+	return cached && shouldPreserveTerminalPayload(cached, input) ? cached : null;
+}
+
+function runtimeStateFileForContext(context: RuntimeStateContext): string | null {
+	const explicit = process.env[SKC_COORDINATOR_SESSION_STATE_FILE_ENV]?.trim();
+	if (explicit) return explicit;
+	if (!context.sessionId.trim()) return null;
+	return path.join(sessionRuntimeDir(context.cwd, context.sessionId), "runtime-state.json");
+}
+function branchForContext(context: RuntimeStateContext): string | null {
+	return context.branch ?? (process.env[SKC_COORDINATOR_SESSION_BRANCH_ENV]?.trim() || null);
+}
+
+function basePayload(input: {
+	context: RuntimeStateContext;
+	previous: Record<string, unknown>;
+	state: RuntimeState;
+	now: string;
+	source: string;
+	event: string;
+	reason: string | null;
+	sessionId: string;
+}): Record<string, unknown> {
+	return {
+		schema_version: 1,
+		session_id: input.sessionId,
+		state: input.state,
+		ready_for_input: input.state === "completed" || input.state === "ready_for_input",
+		updated_at: input.now,
+		current_turn_id: typeof input.previous.current_turn_id === "string" ? input.previous.current_turn_id : null,
+		last_turn_id: typeof input.previous.last_turn_id === "string" ? input.previous.last_turn_id : null,
+		live: input.state === "running",
+		reason: input.reason,
+		source: input.source,
+		event: input.event,
+		cwd: input.context.cwd,
+		workdir: input.context.cwd,
+		branch: branchForContext(input.context),
+		session_file: input.context.sessionFile ?? null,
+	};
+}
+function booleanFromUnknown(value: unknown): boolean | null {
+	if (typeof value === "boolean") return value;
+	if (typeof value === "string") {
+		const normalized = value.trim().toLowerCase();
+		if (normalized === "true") return true;
+		if (normalized === "false") return false;
+	}
+	return null;
+}
+
+function promptAcceptedFromEnv(): boolean {
+	const promptAcceptedJson = process.env[SKC_SESSION_PROMPT_ACCEPTED_JSON_ENV]?.trim();
+	if (!promptAcceptedJson) return false;
+	try {
+		return fsSync.statSync(promptAcceptedJson).size > 0;
+	} catch {
+		return false;
+	}
+}
+
+function readJsonFileSync(file: string): Record<string, unknown> | null {
+	try {
+		return JSON.parse(fsSync.readFileSync(file, "utf8")) as Record<string, unknown>;
+	} catch {
+		return null;
+	}
+}
+
+function worktreeBaselineDirtyFromEnvOrMarker(): boolean | null {
+	const promptAcceptedJson = process.env[SKC_SESSION_PROMPT_ACCEPTED_JSON_ENV]?.trim();
+	if (promptAcceptedJson) {
+		const promptAccepted = readJsonFileSync(promptAcceptedJson);
+		const promptBaseline = booleanFromUnknown(promptAccepted?.worktreeBaselineDirty);
+		if (promptBaseline !== null) return promptBaseline;
+	}
+	const envValue = booleanFromUnknown(process.env[SKC_SESSION_WORKTREE_BASELINE_DIRTY_ENV]);
+	if (envValue !== null) return envValue;
+	return null;
+}
+
+function observedRecoverableWorktreeChanges(cwd: string): boolean {
+	if (!cwd.trim()) return false;
+	try {
+		const proc = Bun.spawnSync(["git", "status", "--porcelain"], { cwd, stdout: "pipe", stderr: "pipe" });
+		return proc.exitCode === 0 && proc.stdout.byteLength > 0;
+	} catch {
+		return false;
+	}
+}
+
+function publicSafeErrorMessage(message: string): string {
+	const normalized = message.replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, " ").trim();
+	if (normalized.length <= MAX_PUBLIC_ERROR_MESSAGE_LENGTH) return normalized;
+	return `${normalized.slice(0, MAX_PUBLIC_ERROR_MESSAGE_LENGTH)}…`;
+}
+
+function errorMessageForPostmortem(reason: postmortem.Reason): string {
+	return publicSafeErrorMessage(`SKC process cleanup ran for ${reason}`);
+}
+
+function numericProcessExitCode(defaultCode: number | null): number | null {
+	return typeof process.exitCode === "number" ? process.exitCode : defaultCode;
+}
+
+function postmortemExitDetails(
+	reason: postmortem.Reason,
+	previous: RuntimeStateSidecarPayload,
+	cwd: string,
+): {
+	state: RuntimeState;
+	reason: string;
+	exitKind: string;
+	exitCode: number | null;
+	signal: string | null;
+	error?: { code: string; message: string; recoverable: true };
+	recovery?: { action: string; reason: string };
+	promptAccepted: boolean;
+	observedRecoverableWorktreeChanges: boolean;
+	worktreeBaselineDirty: boolean | null;
+	worktreeChangedSinceBaseline: boolean;
+} {
+	const promptAccepted = promptAcceptedFromEnv();
+	const observedChanges = observedRecoverableWorktreeChanges(typeof previous.cwd === "string" ? previous.cwd : cwd);
+	const worktreeBaselineDirty = worktreeBaselineDirtyFromEnvOrMarker();
+	const worktreeChangedSinceBaseline = worktreeBaselineDirty === false && observedChanges;
+	if (reason === postmortem.Reason.EXIT || reason === postmortem.Reason.MANUAL) {
+		const exitCode = numericProcessExitCode(0) ?? 0;
+		const exitedBeforeTerminalState =
+			exitCode === 0 && reason === postmortem.Reason.EXIT && previous.state === "running";
+		const state: RuntimeState = exitCode === 0 && !exitedBeforeTerminalState ? "completed" : "errored";
+		const exitReason = exitedBeforeTerminalState
+			? "process_exit_before_terminal_state"
+			: reason === postmortem.Reason.EXIT
+				? "process_exit"
+				: "manual_cleanup";
+		let classifiedReason = exitReason;
+		if (exitedBeforeTerminalState) {
+			if (!promptAccepted) classifiedReason = "process_exit_before_prompt_acceptance";
+			else if (worktreeChangedSinceBaseline)
+				classifiedReason = "accepted_prompt_observed_recoverable_worktree_changes";
+			else if (observedChanges)
+				classifiedReason = "accepted_prompt_dirty_worktree_observed_without_new_change_proof";
+			else classifiedReason = "accepted_prompt_no_useful_output";
+		}
+		return {
+			state,
+			reason: classifiedReason,
+			exitKind: reason,
+			exitCode,
+			signal: null,
+			...(state === "errored"
+				? {
+						error: {
+							code: classifiedReason,
+							message: publicSafeErrorMessage(
+								exitedBeforeTerminalState
+									? "SKC process exited before emitting terminal agent state"
+									: `SKC process exited with code ${exitCode}`,
+							),
+							recoverable: true,
+						},
+						recovery: {
+							action: "recover_or_resume_session",
+							reason: exitedBeforeTerminalState
+								? "previous runtime state was non-terminal; preserve the worktree and inspect the session before retrying"
+								: "process exited with a non-zero status",
+						},
+					}
+				: {}),
+			promptAccepted,
+			observedRecoverableWorktreeChanges: observedChanges,
+			worktreeBaselineDirty,
+			worktreeChangedSinceBaseline,
+		};
+	}
+	const signalByReason: Partial<Record<postmortem.Reason, string>> = {
+		[postmortem.Reason.SIGINT]: "SIGINT",
+		[postmortem.Reason.SIGTERM]: "SIGTERM",
+		[postmortem.Reason.SIGHUP]: "SIGHUP",
+	};
+	return {
+		state: "errored",
+		reason,
+		exitKind: reason,
+		exitCode: numericProcessExitCode(null),
+		signal: signalByReason[reason] ?? null,
+		error: { code: reason, message: errorMessageForPostmortem(reason), recoverable: true },
+		recovery: { action: "recover_or_resume_session", reason: "process cleanup ran before terminal agent state" },
+		promptAccepted,
+		observedRecoverableWorktreeChanges: observedChanges,
+		worktreeBaselineDirty,
+		worktreeChangedSinceBaseline,
+	};
+}
+
+function writeStateFileSync(stateFile: string, payload: Record<string, unknown>): void {
+	fsSync.mkdirSync(path.dirname(stateFile), { recursive: true });
+	fsSync.writeFileSync(stateFile, `${JSON.stringify(payload)}\n`);
+	rememberWrittenPayload(stateFile, payload);
+}
+
+async function writeStateFile(stateFile: string, payload: Record<string, unknown>): Promise<void> {
+	await fs.mkdir(path.dirname(stateFile), { recursive: true });
+	await Bun.write(stateFile, `${JSON.stringify(payload)}\n`);
+	rememberWrittenPayload(stateFile, payload);
+}
+
 export async function persistCoordinatorRuntimeStateFromEvent(
 	event: RuntimeStateEvent,
 	context: RuntimeStateContext,
 ): Promise<void> {
-	const stateFile = process.env[SKC_COORDINATOR_SESSION_STATE_FILE_ENV]?.trim();
+	__sessionStateSidecarPerfCounters.persistFromEventCalls += 1;
+	const stateFile = runtimeStateFileForContext(context);
 	if (!stateFile) return;
 	const state = stateForEvent(event);
 	if (!state) return;
-	const now = new Date().toISOString();
-	let previous: Record<string, unknown> = {};
-	try {
-		previous = JSON.parse(await Bun.file(stateFile).text()) as Record<string, unknown>;
-	} catch {
-		previous = {};
-	}
+	const nowMs = Date.now();
+	const now = new Date(nowMs).toISOString();
+	const previous = await readPreviousPayloadForEvent(stateFile);
 	const finalResponse = finalResponseForEvent(event);
+	const sessionId = process.env[SKC_COORDINATOR_SESSION_STATE_FILE_ENV]?.trim()
+		? process.env[SKC_COORDINATOR_SESSION_ID_ENV]?.trim() || context.sessionId
+		: context.sessionId;
 	const payload = {
-		schema_version: 1,
-		session_id: process.env[SKC_COORDINATOR_SESSION_ID_ENV]?.trim() || context.sessionId,
-		state,
-		ready_for_input: state === "completed" || state === "ready_for_input",
-		updated_at: now,
-		current_turn_id: typeof previous.current_turn_id === "string" ? previous.current_turn_id : null,
-		last_turn_id: typeof previous.last_turn_id === "string" ? previous.last_turn_id : null,
-		live: typeof previous.live === "boolean" ? previous.live : null,
-		reason: null,
-		source: "agent_session_event",
-		event: event.type,
-		cwd: context.cwd,
-		session_file: context.sessionFile ?? null,
+		...basePayload({
+			context,
+			previous,
+			state,
+			now,
+			source: "agent_session_event",
+			event: event.type,
+			reason: null,
+			sessionId,
+		}),
+		...(state === "completed" || state === "errored" ? { ended_at: now } : {}),
 		...(finalResponse ? { final_response: finalResponse } : {}),
 		...(state === "errored"
 			? {
 					error: {
 						code: "agent_error",
-						message: lastAssistant(event.messages)?.errorMessage ?? "agent_error",
+						message: publicSafeErrorMessage(lastAssistant(event.messages)?.errorMessage ?? "agent_error"),
 						recoverable: true,
 					},
 				}
 			: {}),
 	};
+	if (state === "completed" || state === "errored") rememberWrittenPayload(stateFile, payload);
 	try {
-		await fs.mkdir(path.dirname(stateFile), { recursive: true });
-		await Bun.write(stateFile, `${JSON.stringify(payload, null, 2)}\n`);
+		if (shouldSkipRuntimeStateWrite(previous, payload, nowMs)) return;
+		await writeStateFile(stateFile, payload);
 	} catch (error) {
 		logger.warn("Failed to persist coordinator runtime state", { error: String(error), stateFile });
 	}
 }
+
+export function persistCoordinatorRuntimeStateFromPostmortem(
+	reason: postmortem.Reason,
+	context: RuntimeStateContext,
+): void {
+	const stateFile = runtimeStateFileForContext(context);
+	if (!stateFile) return;
+	const sessionId = process.env[SKC_COORDINATOR_SESSION_STATE_FILE_ENV]?.trim()
+		? process.env[SKC_COORDINATOR_SESSION_ID_ENV]?.trim() || context.sessionId
+		: context.sessionId;
+	const preserveInput = { sessionId, cwd: context.cwd, sessionFile: context.sessionFile };
+	const cachedTerminal = cachedTerminalPayload(stateFile, preserveInput);
+	const previous: Record<string, unknown> = cachedTerminal
+		? (cachedTerminal as unknown as Record<string, unknown>)
+		: readPreviousPayload(stateFile);
+	if (cachedTerminal || shouldPreserveTerminalPayload(previous as RuntimeStateSidecarPayload, preserveInput)) return;
+	const previousForDetails: RuntimeStateSidecarPayload =
+		(previous as RuntimeStateSidecarPayload).state === "completed" ||
+		(previous as RuntimeStateSidecarPayload).state === "errored"
+			? { ...(previous as RuntimeStateSidecarPayload), state: "running" }
+			: (previous as RuntimeStateSidecarPayload);
+	const now = new Date().toISOString();
+	const details = postmortemExitDetails(reason, previousForDetails, context.cwd);
+	const payload = {
+		...basePayload({
+			context,
+			previous,
+			state: details.state,
+			now,
+			source: "process_postmortem",
+			event: "process_exit",
+			reason: details.reason,
+			sessionId,
+		}),
+		ended_at: now,
+		detected_at: now,
+		exit_kind: details.exitKind,
+		exit_code: details.exitCode,
+		signal: details.signal,
+		...(details.error ? { error: details.error } : {}),
+		...(details.recovery ? { recovery: details.recovery } : {}),
+		previous_runtime_state: typeof previous.state === "string" ? previous.state : null,
+		prompt_accepted: details.promptAccepted,
+		observed_recoverable_worktree_changes: details.observedRecoverableWorktreeChanges,
+		worktree_baseline_dirty: details.worktreeBaselineDirty,
+		worktree_changed_since_baseline: details.worktreeChangedSinceBaseline,
+	};
+	try {
+		writeStateFileSync(stateFile, payload);
+	} catch (error) {
+		logger.warn("Failed to persist coordinator runtime state during postmortem", { error: String(error), stateFile });
+	}
+}
+
+export function registerCoordinatorRuntimeStateFinalizer(context: RuntimeStateContext): () => void {
+	if (!runtimeStateFileForContext(context)) return () => {};
+	return postmortem.register("coordinator-runtime-state", reason => {
+		persistCoordinatorRuntimeStateFromPostmortem(reason, context);
+	});
+}

package/src/skc-runtime/state-runtime.ts

@@ -26,6 +26,7 @@ import {
 	type WorkflowStateReceipt,
 } from "../skill-state/workflow-state-contract";
 import { renderCliWriteReceipt } from "./cli-write-receipt";
+import { applyAmbiguityFloorToEnvelope } from "./deep-interview-ambiguity";
 import { mergeDeepInterviewEnvelope, normalizeDeepInterviewEnvelope } from "./deep-interview-state";
 import { activeSnapshotPath, auditPath, modeStatePath, sessionStateDir } from "./session-layout";
 import {
@@ -847,11 +848,14 @@ async function writeJsonAtomic(
 			forced: options?.force ?? false,
 		},
 	});
-	// `writeResult.revision` is computed inside the writer lock, so it is the revision this
-	// write actually owns. Prefer it over a post-lock file re-read, which a concurrent writer
-	// could have advanced before the read — that race could otherwise let this payload be
-	// published with another writer's newer revision.
-	return { warning, stamped: (await readJsonFile(filePath)) ?? {}, revision: writeResult.revision };
+	// `writeResult.stamped` and `.revision` are computed inside the writer lock, so they are
+	// the envelope/revision this write actually owns. Never post-lock re-read here: a concurrent
+	// writer could advance the file before that read and make this payload publish another
+	// writer's newer revision into the derived active-state cache.
+	if (!writeResult.written || !isPlainObject(writeResult.stamped)) {
+		throw new Error(`state writer did not return a stamped workflow envelope for ${filePath}`);
+	}
+	return { warning, stamped: writeResult.stamped, revision: writeResult.revision };
 }
 
 function parseFieldsFlag(args: readonly string[]): StateProjectionField[] | undefined {
@@ -1155,7 +1159,12 @@ export async function reconcileWorkflowSkillState(options: {
 
 	const merged =
 		mode === "deep-interview"
-			? (mergeDeepInterviewEnvelope(existingPayload, payload) as Record<string, unknown>)
+			? // Enforce the deterministic ambiguity floor on every reconcile so a
+				// self-reported score can never undercut persisted contradiction evidence.
+				(applyAmbiguityFloorToEnvelope(mergeDeepInterviewEnvelope(existingPayload, payload)).envelope as Record<
+					string,
+					unknown
+				>)
 			: mergeWithNullDelete(existingPayload, payload);
 	merged.skill = mode;
 	merged.current_phase = trimmedPhase;
@@ -1352,7 +1361,11 @@ async function handleWrite(
 	if (mode === "deep-interview") {
 		// Deep-interview keeps interview data nested under `state` and merges rounds
 		// losslessly by durable key; never flatten or delete `state` (that drops recorder history).
-		merged = mergeDeepInterviewEnvelope(existingPayload, payload, { replace: hasFlag(args, "--replace") });
+		// The deterministic ambiguity floor is applied after the merge so a reported
+		// score written through the CLI can never undercut persisted contradiction evidence.
+		merged = applyAmbiguityFloorToEnvelope(
+			mergeDeepInterviewEnvelope(existingPayload, payload, { replace: hasFlag(args, "--replace") }),
+		).envelope;
 	} else if (hasFlag(args, "--replace")) {
 		merged = { ...payload };
 	} else {

package/src/skc-runtime/state-writer.ts

@@ -99,7 +99,7 @@ export interface GuardedStateWriterOptions extends StateWriterOptions {
 }
 
 export type GuardedWriteResult =
-	| { path: string; written: true; revision: number }
+	| { path: string; written: true; revision: number; stamped: unknown }
 	| { path: string; written: false; reason: "stale-skip"; revision: number };
 
 export interface StateWriterOptions {
@@ -304,6 +304,18 @@ function activeStateDir(cwd: string, sessionScope?: string | ActiveSessionScope)
 	return layoutActiveStateDir(cwd, requireSessionId(sessionScope, "activeStateDir"));
 }
 
+type ActiveStateCacheInvalidator = (cwd?: string, sessionId?: string) => void;
+var activeStateCacheInvalidator: ActiveStateCacheInvalidator | undefined;
+
+export function setActiveStateCacheInvalidator(invalidator: ActiveStateCacheInvalidator): void {
+	activeStateCacheInvalidator = invalidator;
+}
+
+function invalidateActiveStateCacheForScope(cwd: string, sessionScope?: string | ActiveSessionScope): void {
+	const sessionId = typeof sessionScope === "string" ? sessionScope : sessionScope?.sessionId;
+	activeStateCacheInvalidator?.(cwd, sessionId);
+}
+
 function activeSnapshotPath(cwd: string, sessionScope?: string | ActiveSessionScope): string {
 	return layoutActiveSnapshotPath(cwd, requireSessionId(sessionScope, "activeSnapshotPath"));
 }
@@ -511,7 +523,7 @@ async function writeGuardedResolvedJsonAtomic(
 				const next = stampStateRevision(withWorkflowReceipt(value, buildReceipt(options)), currentRevision + 1);
 				await atomicWrite(filePath, jsonText(next));
 				await maybeAudit(filePath, options);
-				return { path: filePath, written: true, revision: currentRevision + 1 };
+				return { path: filePath, written: true, revision: currentRevision + 1, stamped: next };
 			}
 
 			const incomingSourceRevision =
@@ -526,7 +538,7 @@ async function writeGuardedResolvedJsonAtomic(
 			);
 			await atomicWrite(filePath, jsonText(next));
 			await maybeAudit(filePath, options);
-			return { path: filePath, written: true, revision: currentRevision + 1 };
+			return { path: filePath, written: true, revision: currentRevision + 1, stamped: next };
 		},
 		options.lock,
 	);
@@ -574,7 +586,7 @@ export async function writeGuardedWorkflowEnvelopeAtomic(
 				}
 				await atomicWrite(filePath, jsonText(next));
 				await maybeAudit(filePath, options);
-				return { path: filePath, written: true, revision: currentRevision + 1 };
+				return { path: filePath, written: true, revision: currentRevision + 1, stamped: next };
 			}
 
 			const incomingSourceRevision =
@@ -599,7 +611,7 @@ export async function writeGuardedWorkflowEnvelopeAtomic(
 			}
 			await atomicWrite(filePath, jsonText(next));
 			await maybeAudit(filePath, options);
-			return { path: filePath, written: true, revision: currentRevision + 1 };
+			return { path: filePath, written: true, revision: currentRevision + 1, stamped: next };
 		},
 		options.lock,
 	);
@@ -979,6 +991,7 @@ export async function writeActiveEntry(
 				persistedSourceRevision(entry) || persistedSourceRevision(await readJsonIfPresent(filePath)) + 1,
 		},
 	);
+	invalidateActiveStateCacheForScope(cwd, sessionScope);
 	return filePath;
 }
 
@@ -1003,6 +1016,7 @@ export async function removeActiveEntry(
 			}
 			const deleted = await atomicRemove(filePath);
 			if (deleted) await maybeAudit(filePath, options);
+			if (deleted) invalidateActiveStateCacheForScope(cwd, sessionScope);
 			return { path: filePath, deleted };
 		},
 		options?.lock,
@@ -1049,6 +1063,7 @@ export async function rebuildActiveSnapshot(
 			...entries.map(entry => persistedSourceRevision(entry)),
 		),
 	});
+	invalidateActiveStateCacheForScope(cwd, sessionScope);
 	return snapshotPath;
 }