@gajae-code/coding-agent 0.11.10 → 0.12.0

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

@@ -1,6 +1,9 @@
 import { createHash } from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
+// Subpath import keeps this module native-free for the gjc-state-gates shards:
+// the package barrel pulls procmgr/ptree → @gajae-code/natives.
+import * as logger from "@gajae-code/utils/logger";
 import type { WorkflowHudSummary } from "../skill-state/active-state";
 import {
 	applyHandoffToActiveState,
@@ -265,7 +268,21 @@ async function describeStaleClearState(
 	return undefined;
 }
 
-async function readJsonFile(filePath: string): Promise<Record<string, unknown> | null> {
+/**
+ * Route a workflow-state warning through the TUI-safe centralized file logger
+ * (console transport off by default) so interactive sessions never paint raw
+ * bytes into the alternate-screen stream (#3002). CLI command handlers may also
+ * collect the warning via an `onWarning` sink to surface it on the structured
+ * {@link StateCommandResult.stderr} channel, so `gjc state` automation still
+ * distinguishes corrupt state from absent state.
+ */
+function emitStateWarning(warning: string, context?: Record<string, unknown>): void {
+	logger.warn(warning, context);
+}
+
+type StateWarningSink = (warning: string) => void;
+
+async function readJsonFile(filePath: string, onWarning?: StateWarningSink): Promise<Record<string, unknown> | null> {
 	try {
 		const raw = await fs.readFile(filePath, "utf-8");
 		const parsed = JSON.parse(raw);
@@ -276,18 +293,22 @@ async function readJsonFile(filePath: string): Promise<Record<string, unknown> |
 	} catch (error) {
 		const err = error as NodeJS.ErrnoException;
 		if (err.code === "ENOENT") return null;
-		process.stderr.write(`WARNING: failed to read ${filePath}; ignoring corrupt state: ${err.message}\n`);
+		const warning = `WARNING: failed to read ${filePath}; ignoring corrupt state: ${err.message}`;
+		emitStateWarning(warning, { filePath, error: err.message });
+		onWarning?.(warning);
 		return null;
 	}
 }
 
-async function readJsonValue(filePath: string): Promise<unknown | null> {
+async function readJsonValue(filePath: string, onWarning?: StateWarningSink): Promise<unknown | null> {
 	try {
 		return JSON.parse(await fs.readFile(filePath, "utf-8"));
 	} catch (error) {
 		const err = error as NodeJS.ErrnoException;
 		if (err.code === "ENOENT") return null;
-		process.stderr.write(`WARNING: failed to read ${filePath}; ignoring corrupt state: ${err.message}\n`);
+		const warning = `WARNING: failed to read ${filePath}; ignoring corrupt state: ${err.message}`;
+		emitStateWarning(warning, { filePath, error: err.message });
+		onWarning?.(warning);
 		return null;
 	}
 }
@@ -836,7 +857,8 @@ function buildHudForMode(
 					: typeof payload.mode === "string"
 						? (payload.mode as string)
 						: undefined;
-			const verdict = typeof payload.verdict === "string" ? (payload.verdict as string) : undefined;
+			const rawVerdict = payload.last_review_verdict ?? payload.verdict;
+			const verdict = typeof rawVerdict === "string" ? rawVerdict : undefined;
 			const iteration = typeof payload.iteration === "number" ? (payload.iteration as number) : undefined;
 			const pendingApproval = payload.pending_approval === true || stage === "final";
 			return buildRalplanHudSummary({
@@ -1101,21 +1123,30 @@ export async function readWorkflowStateJson(
 	cwd: string,
 	skill: CanonicalGjcWorkflowSkill,
 	sessionId?: string,
+	onWarning?: StateWarningSink,
 ): Promise<Record<string, unknown>> {
 	const session = await resolveGjcSessionForRead(cwd, {
 		payloadSessionId: sessionId,
 		envSessionId: process.env.GJC_SESSION_ID,
 	});
-	return (await readJsonFile(modeStateFile(cwd, skill, session.gjcSessionId))) ?? {};
+	return (await readJsonFile(modeStateFile(cwd, skill, session.gjcSessionId), onWarning)) ?? {};
 }
 
 async function handleRead(args: readonly string[], cwd: string): Promise<StateCommandResult> {
 	const selectors = await resolveSelectors(args, cwd, "read");
 	const mode = selectors.mode ?? (await inferModeFromActiveState(cwd, selectors.gjcSessionId));
 	const fields = parseFieldsFlag(args);
+	// Corrupt-state warnings are TUI-safe file-logged inside the readers; the CLI
+	// path also surfaces them on the command result so `gjc state read`
+	// automation can tell corrupt state from absent state (#3002).
+	const warnings: string[] = [];
+	const warningStderr = (): Pick<StateCommandResult, "stderr"> =>
+		warnings.length ? { stderr: warnings.map(warning => `${warning}\n`).join("") } : {};
 	if (mode) {
 		const filePath = modeStateFile(cwd, mode, selectors.gjcSessionId);
-		const existing = await readWorkflowStateJson(cwd, mode, selectors.gjcSessionId);
+		const existing = await readWorkflowStateJson(cwd, mode, selectors.gjcSessionId, warning =>
+			warnings.push(warning),
+		);
 		const envelope = { skill: mode, state: existing, storage_path: filePath };
 		const manifest = getSkillManifest(mode);
 		if (fields) {
@@ -1125,6 +1156,7 @@ async function handleRead(args: readonly string[], cwd: string): Promise<StateCo
 				stdout: hasFlag(args, "--json")
 					? `${JSON.stringify(projected, null, 2)}\n`
 					: renderStateMarkdown(mode, projected, manifest),
+				...warningStderr(),
 			};
 		}
 		if (hasFlag(args, "--compact")) {
@@ -1134,6 +1166,7 @@ async function handleRead(args: readonly string[], cwd: string): Promise<StateCo
 				stdout: hasFlag(args, "--json")
 					? `${JSON.stringify(compact, null, 2)}\n`
 					: renderStateMarkdown(mode, envelope, manifest),
+				...warningStderr(),
 			};
 		}
 		return {
@@ -1141,12 +1174,13 @@ async function handleRead(args: readonly string[], cwd: string): Promise<StateCo
 			stdout: hasFlag(args, "--json")
 				? `${JSON.stringify(envelope, null, 2)}\n`
 				: renderStateMarkdown(mode, envelope, manifest),
+			...warningStderr(),
 		};
 	}
 	const filePath = activeStateFile(cwd, selectors.gjcSessionId);
-	const existingRaw = await readJsonValue(filePath);
+	const existingRaw = await readJsonValue(filePath, warning => warnings.push(warning));
 	const existing = isPlainObject(existingRaw) ? existingRaw : null;
-	return { status: 0, stdout: `${JSON.stringify(existing ?? {}, null, 2)}\n` };
+	return { status: 0, stdout: `${JSON.stringify(existing ?? {}, null, 2)}\n`, ...warningStderr() };
 }
 
 async function handleStatus(args: readonly string[], cwd: string): Promise<StateCommandResult> {
@@ -1159,7 +1193,8 @@ async function handleStatus(args: readonly string[], cwd: string): Promise<State
 		);
 	}
 	const filePath = modeStateFile(cwd, mode, selectors.gjcSessionId);
-	const existing = await readWorkflowStateJson(cwd, mode, selectors.gjcSessionId);
+	const warnings: string[] = [];
+	const existing = await readWorkflowStateJson(cwd, mode, selectors.gjcSessionId, warning => warnings.push(warning));
 	const summary = buildStateStatusSummary(
 		mode,
 		{ skill: mode, state: existing, storage_path: filePath },
@@ -1169,6 +1204,7 @@ async function handleStatus(args: readonly string[], cwd: string): Promise<State
 	return {
 		status: 0,
 		stdout: hasFlag(args, "--json") ? `${JSON.stringify(summary, null, 2)}\n` : renderStateStatusLine(summary),
+		...(warnings.length ? { stderr: warnings.map(warning => `${warning}\n`).join("") } : {}),
 	};
 }
 
@@ -1603,7 +1639,7 @@ async function handleHandoffUnlocked(args: readonly string[], cwd: string): Prom
 			toPhase: "handoff",
 		});
 		await updateWorkflowTransactionJournal(cwd, sessionId, mutationId, { steps: ["caller-mode-state"] });
-		if (callerWrite.warning) process.stderr.write(`${callerWrite.warning}\n`);
+		if (callerWrite.warning) emitStateWarning(callerWrite.warning);
 		const stampedCallerReceipt = isPlainObject(callerWrite.stamped.receipt) ? callerWrite.stamped.receipt : {};
 		await syncSkillActiveState({
 			cwd,
@@ -1646,6 +1682,7 @@ async function handleHandoffUnlocked(args: readonly string[], cwd: string): Prom
 					active_state: activeStateFile(cwd, sessionId),
 				},
 			}),
+			...(callerWrite.warning ? { stderr: `${callerWrite.warning}\n` } : {}),
 		};
 	}
 
@@ -1746,7 +1783,7 @@ async function handleHandoffUnlocked(args: readonly string[], cwd: string): Prom
 	);
 	const stampedCallerReceipt = isPlainObject(callerWrite.stamped.receipt) ? callerWrite.stamped.receipt : {};
 	const stampedCalleeReceipt = isPlainObject(calleeWrite.stamped.receipt) ? calleeWrite.stamped.receipt : {};
-	for (const warning of warnings) process.stderr.write(`${warning}\n`);
+	for (const warning of warnings) emitStateWarning(warning);
 	if (process.env.GJC_STATE_HANDOFF_FAIL_AFTER_CALLER === mutationId) {
 		throw new StateCommandError(1, `injected handoff failure after caller write for ${mutationId}`);
 	}
@@ -1818,6 +1855,7 @@ async function handleHandoffUnlocked(args: readonly string[], cwd: string): Prom
 				active_state: activeStateFile(cwd, sessionId),
 			},
 		}),
+		...(warnings.length ? { stderr: warnings.map(warning => `${warning}\n`).join("") } : {}),
 	};
 }
 

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

@@ -11,7 +11,6 @@ import {
 	type WorkflowStateMutationOwner,
 	type WorkflowStateReceipt,
 } from "../skill-state/workflow-state-contract";
-import { validateDeepInterviewV1Envelope } from "./deep-interview-state";
 import {
 	activeEntryPath as layoutActiveEntryPath,
 	activeSnapshotPath as layoutActiveSnapshotPath,
@@ -78,47 +77,6 @@ export interface WorkflowEnvelopeIntegrityMismatch {
 	expected: string;
 	actual: string;
 }
-export type WorkflowReceiptVerification =
-	| "legacy"
-	| "native-valid"
-	| "receipt-malformed"
-	| "receipt-missing"
-	| "checksum-mismatch";
-
-export interface GuardedWorkflowEnvelopeTransformOptions extends StateWriterOptions {
-	expectedRevision: number;
-	/** Additional native schema validation applied to both current and candidate envelopes. */
-	validate?: (value: Record<string, unknown>, legacy: boolean) => void;
-	transform: (
-		current: Record<string, unknown>,
-		context: { revision: number; legacy: boolean },
-	) =>
-		| { kind: "noop" }
-		| { kind: "write"; value: Record<string, unknown> }
-		| Promise<{ kind: "noop" } | { kind: "write"; value: Record<string, unknown> }>;
-}
-
-export interface GuardedWorkflowEnvelopeWarning {
-	code: "DI_POST_COMMIT_AUDIT_FAILED";
-	message: string;
-}
-
-export type GuardedWorkflowEnvelopeTransformResult =
-	| { path: string; written: false; reason: "noop"; revision: number; warnings: [] }
-	| {
-			path: string;
-			written: true;
-			revision: number;
-			stamped: Record<string, unknown>;
-			warnings: GuardedWorkflowEnvelopeWarning[];
-	  };
-
-export class GuardedWorkflowEnvelopeError extends Error {
-	constructor(public readonly code: string) {
-		super(code);
-		this.name = "GuardedWorkflowEnvelopeError";
-	}
-}
 
 export interface WorkflowTransactionJournal {
 	version: 1;
@@ -138,7 +96,6 @@ export interface GuardedStateWriterOptions extends StateWriterOptions {
 	policy: StateWritePolicy;
 	expectedRevision?: number;
 	sourceRevision?: number;
-	lockHeld?: boolean;
 }
 
 export type GuardedWriteResult =
@@ -150,13 +107,17 @@ export interface StateWriterOptions {
 	receipt?: StateWriterReceiptContext;
 	audit?: StateWriterAuditContext;
 	sourceRevision?: number;
-	orderingRevision?: number;
 	/**
 	 * Cross-process lock tuning for read-modify-write paths that route through
 	 * `withWorkflowStateLock` / `updateJsonAtomic`. Omit for the hardened
 	 * `withFileLock` defaults.
 	 */
 	lock?: FileLockOptions;
+	/**
+	 * Caller already holds the workflow state lock for this target path (via
+	 * `withWorkflowStateLock`). Skip re-acquisition to avoid self-deadlock.
+	 */
+	lockHeld?: boolean;
 }
 
 export class StateWriteConflictError extends Error {
@@ -298,49 +259,6 @@ export function workflowEnvelopeContentSha256(value: unknown): string {
 		.update(JSON.stringify(canonicalizeJson(withoutReceiptChecksum(value))))
 		.digest("hex");
 }
-export function isNativeDeepInterviewV1(value: Record<string, unknown>): boolean {
-	if (value.skill !== "deep-interview") return false;
-	return value.schema_version === 1 || (isPlainObject(value.state) && value.state.schema_version === 1);
-}
-
-export function verifyWorkflowEnvelopeReceiptValue(value: unknown, filePath: string): WorkflowReceiptVerification {
-	if (!isPlainObject(value)) return "receipt-malformed";
-	const native = isNativeDeepInterviewV1(value);
-	if (!Object.hasOwn(value, "receipt")) return native ? "receipt-missing" : "legacy";
-	if (!isPlainObject(value.receipt) || !isPlainObject(value.receipt.content_sha256)) return "receipt-malformed";
-
-	const receipt = value.receipt as Record<string, unknown>;
-	const checksum = receipt.content_sha256 as Record<string, unknown>;
-	if (
-		typeof value.skill !== "string" ||
-		receipt.version !== 1 ||
-		receipt.skill !== value.skill ||
-		(receipt.skill !== "deep-interview" &&
-			receipt.skill !== "ralplan" &&
-			receipt.skill !== "ultragoal" &&
-			receipt.skill !== "team") ||
-		(receipt.owner !== "gjc-state-cli" && receipt.owner !== "gjc-runtime" && receipt.owner !== "gjc-hook") ||
-		typeof receipt.command !== "string" ||
-		typeof receipt.state_path !== "string" ||
-		typeof receipt.storage_path !== "string" ||
-		typeof receipt.mutated_at !== "string" ||
-		!Number.isFinite(Date.parse(receipt.mutated_at)) ||
-		typeof receipt.fresh_until !== "string" ||
-		!Number.isFinite(Date.parse(receipt.fresh_until)) ||
-		(receipt.status !== "fresh" && receipt.status !== "stale") ||
-		typeof receipt.mutation_id !== "string" ||
-		checksum.algorithm !== "sha256" ||
-		typeof checksum.value !== "string" ||
-		!/^[0-9a-f]{64}$/.test(checksum.value) ||
-		typeof checksum.covered_path !== "string" ||
-		path.resolve(checksum.covered_path) !== path.resolve(filePath) ||
-		typeof checksum.computed_at !== "string" ||
-		!Number.isFinite(Date.parse(checksum.computed_at))
-	) {
-		return "receipt-malformed";
-	}
-	return workflowEnvelopeContentSha256(value) === checksum.value ? "native-valid" : "checksum-mismatch";
-}
 
 export function stampWorkflowEnvelopeChecksum<T>(value: T, filePath: string, computedAt = new Date().toISOString()): T {
 	if (!value || typeof value !== "object" || Array.isArray(value)) return value;
@@ -507,11 +425,6 @@ function persistedSourceRevision(value: unknown): number {
 	const revision = value.source_state_revision;
 	return typeof revision === "number" && Number.isFinite(revision) ? revision : persistedStateRevision(value);
 }
-function persistedCommittedModeRevision(value: unknown): number {
-	if (!isPlainObject(value)) return 0;
-	const revision = value.committed_mode_state_revision;
-	return typeof revision === "number" && Number.isFinite(revision) ? revision : 0;
-}
 
 function withoutCandidateRevision(value: unknown): unknown {
 	if (!isPlainObject(value)) return value;
@@ -620,12 +533,7 @@ async function writeGuardedResolvedJsonAtomic(
 
 			const incomingSourceRevision =
 				options.sourceRevision ?? (isPlainObject(value) ? persistedStateRevision(value) : 0);
-			if (
-				current !== undefined &&
-				(options.orderingRevision !== undefined
-					? options.orderingRevision <= persistedCommittedModeRevision(current)
-					: incomingSourceRevision <= persistedSourceRevision(current))
-			) {
+			if (current !== undefined && incomingSourceRevision <= persistedSourceRevision(current)) {
 				return { path: filePath, written: false, reason: "stale-skip", revision: currentRevision };
 			}
 			const next = stampStateRevision(
@@ -659,7 +567,6 @@ export async function writeGuardedWorkflowEnvelopeAtomic(
 	const write = async (): Promise<GuardedWriteResult> => {
 		const current = await readJsonIfPresentTolerant(filePath);
 		const currentRevision = persistedStateRevision(current);
-
 		if (options.policy === "source") {
 			if (options.expectedRevision !== undefined && options.expectedRevision !== currentRevision) {
 				throw new StateWriteConflictError(filePath, options.expectedRevision, currentRevision);
@@ -683,15 +590,9 @@ export async function writeGuardedWorkflowEnvelopeAtomic(
 			await maybeAudit(filePath, options);
 			return { path: filePath, written: true, revision: currentRevision + 1, stamped: next };
 		}
-
 		const incomingSourceRevision =
 			options.sourceRevision ?? (isPlainObject(value) ? persistedStateRevision(value) : 0);
-		if (
-			current !== undefined &&
-			(options.orderingRevision !== undefined
-				? options.orderingRevision <= persistedCommittedModeRevision(current)
-				: incomingSourceRevision <= persistedSourceRevision(current))
-		) {
+		if (current !== undefined && incomingSourceRevision <= persistedSourceRevision(current)) {
 			return { path: filePath, written: false, reason: "stale-skip", revision: currentRevision };
 		}
 		const next = stampWorkflowEnvelopeRevisionAndChecksum(
@@ -715,67 +616,6 @@ export async function writeGuardedWorkflowEnvelopeAtomic(
 	};
 	return options.lockHeld ? write() : lockResolvedWorkflowTarget(filePath, write, options.lock);
 }
-export async function transformGuardedWorkflowEnvelopeAtomic(
-	targetPath: string,
-	options: GuardedWorkflowEnvelopeTransformOptions,
-): Promise<GuardedWorkflowEnvelopeTransformResult> {
-	const filePath = resolveGjcTarget(targetPath, cwdForOptions(options));
-	return lockResolvedWorkflowTarget(
-		filePath,
-		async () => {
-			const read = await readExistingStateForMutation(filePath);
-			if (read.kind === "absent") throw new GuardedWorkflowEnvelopeError("DI_STATE_ABSENT");
-			if (read.kind === "corrupt") throw new GuardedWorkflowEnvelopeError("DI_STATE_CORRUPT");
-			const receipt = verifyWorkflowEnvelopeReceiptValue(read.value, filePath);
-			if (receipt === "receipt-malformed") throw new GuardedWorkflowEnvelopeError("DI_RECEIPT_MALFORMED");
-			if (receipt === "receipt-missing") throw new GuardedWorkflowEnvelopeError("DI_RECEIPT_MISSING");
-			if (receipt === "checksum-mismatch") throw new GuardedWorkflowEnvelopeError("DI_RECEIPT_CHECKSUM_MISMATCH");
-			const legacy = receipt === "legacy";
-			try {
-				if (isNativeDeepInterviewV1(read.value)) validateDeepInterviewV1Envelope(read.value);
-				options.validate?.(read.value, legacy);
-			} catch {
-				throw new GuardedWorkflowEnvelopeError("DI_STATE_SCHEMA_INVALID");
-			}
-			const phase = read.value.current_phase;
-			if (phase === "complete" || phase === "handoff" || read.value.active === false) {
-				throw new GuardedWorkflowEnvelopeError("DI_PHASE_NOT_REPAIRABLE");
-			}
-			const revision = persistedStateRevision(read.value);
-			if (revision !== options.expectedRevision) throw new GuardedWorkflowEnvelopeError("DI_REVISION_CONFLICT");
-			const transformed = await options.transform(read.value, { revision, legacy });
-			if (transformed.kind === "noop")
-				return { path: filePath, written: false, reason: "noop", revision, warnings: [] };
-			try {
-				if (isNativeDeepInterviewV1(transformed.value)) validateDeepInterviewV1Envelope(transformed.value);
-				options.validate?.(transformed.value, false);
-			} catch {
-				throw new GuardedWorkflowEnvelopeError("DI_STATE_SCHEMA_INVALID");
-			}
-			const stamped = stampWorkflowEnvelopeRevisionAndChecksum(
-				transformed.value,
-				filePath,
-				revision + 1,
-				undefined,
-				options,
-			) as Record<string, unknown>;
-			const parsed = RequiredOnWriteEnvelopeSchema.safeParse(stamped);
-			if (!parsed.success) throw new GuardedWorkflowEnvelopeError("DI_STATE_SCHEMA_INVALID");
-			await atomicWrite(filePath, jsonText(stamped));
-			const warnings: GuardedWorkflowEnvelopeWarning[] = [];
-			try {
-				await maybeAudit(filePath, options);
-			} catch (error) {
-				warnings.push({
-					code: "DI_POST_COMMIT_AUDIT_FAILED",
-					message: error instanceof Error ? error.message : String(error),
-				});
-			}
-			return { path: filePath, written: true, revision: revision + 1, stamped, warnings };
-		},
-		options.lock,
-	);
-}
 
 export async function writeJsonAtomic(
 	targetPath: string,
@@ -845,63 +685,71 @@ export async function writeWorkflowEnvelopeAtomic(
 	options?: StateWriterOptions,
 ): Promise<string> {
 	const filePath = resolveGjcTarget(targetPath, cwdForOptions(options));
-	const withReceipt = withWorkflowReceipt(value, buildReceipt(options));
-	const stamped = stampWorkflowEnvelopeChecksum(withReceipt, filePath);
-	const parsed = RequiredOnWriteEnvelopeSchema.safeParse(stamped);
-	if (!parsed.success) {
-		throw new Error(
-			`Refusing to write invalid workflow state envelope to ${filePath}: ${parsed.error.issues
-				.map(issue => `${issue.path.join(".") || "<root>"}: ${issue.message}`)
-				.join("; ")}`,
-		);
-	}
-	// #658: internal runtime writers (ralplan/ultragoal/deep-interview/team) persist
-	// envelopes directly, bypassing the `gjc state` CLI transition gate (`isValidTransition`,
-	// historically the sole call site in state-runtime.ts). Re-assert that gate on every
-	// sanctioned envelope write so internal writes cannot persist invalid state-machine phase
-	// transitions silently. Forced writes (`gjc state ... --force`, reconcile repairs) carry
-	// `audit.forced` and bypass, mirroring the CLI's `use --force to bypass`.
-	//
-	// The gate governs ACTIVE workflow progression only. Deactivation/teardown writes
-	// (`active: false`, e.g. `gjc state clear`, which persists the universal `complete`
-	// sentinel that is not a per-skill manifest state) leave the transition graph and are
-	// intentionally exempt.
-	if (options?.audit?.forced !== true && parsed.data.active === true) {
-		const toPhase = parsed.data.current_phase.trim();
-		if (toPhase) {
-			// Lazy import: workflow-manifest dereferences CANONICAL_GJC_WORKFLOW_SKILLS at
-			// module load, and active-state -> state-writer -> workflow-manifest -> active-state
-			// is a load-time cycle. Importing at call time (after init) avoids the TDZ.
-			const { isKnownWorkflowState, isValidTransition } = await import("./workflow-manifest");
-			const skill = parsed.data.skill;
-			// Structural invariant (hard): a `current_phase` absent from the skill's manifest is
-			// never a legitimate internal write, matching the CLI/reconcile unknown-phase gate.
-			if (!isKnownWorkflowState(skill, toPhase)) {
-				throw new Error(
-					`Refusing to write unknown ${skill} phase "${toPhase}" to ${filePath}: not a known ${skill} manifest state (forced writes bypass via audit.forced)`,
-				);
-			}
-			// Transition invariant (#658, diagnostic-only safety net): resolve the prior phase
-			// (caller-supplied `audit.fromPhase`, else the active persisted envelope on disk) and
-			// flag edges the manifest does not define. Intentionally NON-blocking and audit-only
-			// — the CLI path already hard-fails invalid edges before reaching here, and legitimate
-			// internal repairs / ralplan short-mode stage skips move between valid states without a
-			// direct manifest edge. It records an `invalid_transition_detected` audit entry (no
-			// stderr) so such transitions are non-silent without breaking those flows.
-			const fromPhase = (options?.audit?.fromPhase ?? (await readPersistedPhase(filePath)))?.trim();
-			if (
-				fromPhase &&
-				fromPhase !== toPhase &&
-				isKnownWorkflowState(skill, fromPhase) &&
-				!isValidTransition(skill, fromPhase, toPhase)
-			) {
-				await recordInvalidWorkflowTransition({ filePath, skill, fromPhase, toPhase, options });
+	const write = async (): Promise<string> => {
+		const withReceipt = withWorkflowReceipt(value, buildReceipt(options));
+		const stamped = stampWorkflowEnvelopeChecksum(withReceipt, filePath);
+		const parsed = RequiredOnWriteEnvelopeSchema.safeParse(stamped);
+		if (!parsed.success) {
+			throw new Error(
+				`Refusing to write invalid workflow state envelope to ${filePath}: ${parsed.error.issues
+					.map(issue => `${issue.path.join(".") || "<root>"}: ${issue.message}`)
+					.join("; ")}`,
+			);
+		}
+		// #658: internal runtime writers (ralplan/ultragoal/deep-interview/team) persist
+		// envelopes directly, bypassing the `gjc state` CLI transition gate (`isValidTransition`,
+		// historically the sole call site in state-runtime.ts). Re-assert that gate on every
+		// sanctioned envelope write so internal writes cannot persist invalid state-machine phase
+		// transitions silently. Forced writes (`gjc state ... --force`, reconcile repairs) carry
+		// `audit.forced` and bypass, mirroring the CLI's `use --force to bypass`.
+		//
+		// The gate governs ACTIVE workflow progression only. Deactivation/teardown writes
+		// (`active: false`, e.g. `gjc state clear`, which persists the universal `complete`
+		// sentinel that is not a per-skill manifest state) leave the transition graph and are
+		// intentionally exempt.
+		if (options?.audit?.forced !== true && parsed.data.active === true) {
+			const toPhase = parsed.data.current_phase.trim();
+			if (toPhase) {
+				// Lazy import: workflow-manifest dereferences CANONICAL_GJC_WORKFLOW_SKILLS at
+				// module load, and active-state -> state-writer -> workflow-manifest -> active-state
+				// is a load-time cycle. Importing at call time (after init) avoids the TDZ.
+				const { isKnownWorkflowState, isValidTransition } = await import("./workflow-manifest");
+				const skill = parsed.data.skill;
+				// Structural invariant (hard): a `current_phase` absent from the skill's manifest is
+				// never a legitimate internal write, matching the CLI/reconcile unknown-phase gate.
+				if (!isKnownWorkflowState(skill, toPhase)) {
+					throw new Error(
+						`Refusing to write unknown ${skill} phase "${toPhase}" to ${filePath}: not a known ${skill} manifest state (forced writes bypass via audit.forced)`,
+					);
+				}
+				// Transition invariant (#658, diagnostic-only safety net): resolve the prior phase
+				// (caller-supplied `audit.fromPhase`, else the active persisted envelope on disk) and
+				// flag edges the manifest does not define. Intentionally NON-blocking and audit-only
+				// — the CLI path already hard-fails invalid edges before reaching here, and legitimate
+				// internal repairs / ralplan short-mode stage skips move between valid states without a
+				// direct manifest edge. It records an `invalid_transition_detected` audit entry (no
+				// stderr) so such transitions are non-silent without breaking those flows.
+				const fromPhase = (options?.audit?.fromPhase ?? (await readPersistedPhase(filePath)))?.trim();
+				if (
+					fromPhase &&
+					fromPhase !== toPhase &&
+					isKnownWorkflowState(skill, fromPhase) &&
+					!isValidTransition(skill, fromPhase, toPhase)
+				) {
+					await recordInvalidWorkflowTransition({ filePath, skill, fromPhase, toPhase, options });
+				}
 			}
 		}
-	}
-	await atomicWrite(filePath, jsonText(stamped));
-	await maybeAudit(filePath, options);
-	return filePath;
+		await atomicWrite(filePath, jsonText(stamped));
+		await maybeAudit(filePath, options);
+		return filePath;
+	};
+	// Serialize with every other writer of the same state path. Without this, a
+	// revision-preserving envelope write (seed/spec persistence) can interleave
+	// inside a staged apply's check-then-write window and be silently overwritten
+	// (#3387 architect finding 1). Callers already inside `withWorkflowStateLock`
+	// for this path pass `lockHeld: true`.
+	return options?.lockHeld ? write() : lockResolvedWorkflowTarget(filePath, write, options?.lock);
 }
 
 export async function writeTextAtomic(targetPath: string, text: string, options?: StateWriterOptions): Promise<string> {