@sayknow-cli/coding-agent 0.3.16 → 0.4.0

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

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import type { WorkflowHudSummary } from "../skill-state/active-state";
@@ -27,7 +28,17 @@ import {
 } 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 {
+	assertDeepInterviewEnvelopeInputLimits,
+	assertDeepInterviewInputWithinLimit,
+	assertDeepInterviewIntentManifest,
+	assertDeepInterviewIntentReview,
+	assertDeepInterviewStructuredResponseWithinLimit,
+	type DeepInterviewIntentManifest,
+	MAX_DEEP_INTERVIEW_STRUCTURED_RESPONSE_LENGTH,
+	mergeDeepInterviewEnvelope,
+	normalizeDeepInterviewEnvelope,
+} from "./deep-interview-state";
 import { activeSnapshotPath, auditPath, modeStatePath, sessionStateDir } from "./session-layout";
 import {
 	resolveSkcSessionForRead,
@@ -35,6 +46,7 @@ import {
 	SessionResolutionError,
 	writeSessionActivityMarker,
 } from "./session-resolution";
+import { classifyStateArgv, firstStateFlagValue, type StateAction, type StateArgvClassification } from "./state-argv";
 import { renderStateGraph, type StateGraphFormat } from "./state-graph";
 import { migrateAndPersistLegacyState, migrateWorkflowState } from "./state-migrations";
 import {
@@ -61,9 +73,11 @@ import {
 	softDelete,
 	updateWorkflowTransactionJournal,
 	type WorkflowEnvelopeIntegrityMismatch,
+	withWorkflowStateLock,
 	writeGuardedWorkflowEnvelopeAtomic,
 } from "./state-writer";
-import { getSkillManifest, isKnownWorkflowState, isValidTransition, typedArgsFor } from "./workflow-manifest";
+import { assertSafePathComponent, CommandError, flagValue, hasFlag, isPlainObject } from "./workflow-cli-common";
+import { getSkillManifest, isKnownWorkflowState, isValidTransition } from "./workflow-manifest";
 
 /**
  * Native implementation of the `skc state read|write|clear` command surface.
@@ -80,168 +94,21 @@ export interface StateCommandResult {
 }
 
 const SKILL_ACTIVE_STATE_FILE = "skill-active-state.json";
-const TERMINAL_CLEAR_PHASES = new Set(["complete", "completed", "cancelled", "canceled", "failed"]);
-const PATH_COMPONENT_RE = /^[A-Za-z0-9_-][A-Za-z0-9._-]{0,63}$/;
 const KNOWN_MODES: readonly string[] = CANONICAL_SKC_WORKFLOW_SKILLS;
 
-class StateCommandError extends Error {
-	constructor(
-		public readonly exitStatus: number,
-		message: string,
-	) {
-		super(message);
+class StateCommandError extends CommandError {
+	constructor(exitStatus: number, message: string) {
+		super(exitStatus, message);
 		this.name = "StateCommandError";
 	}
 }
 
-function flagValue(args: readonly string[], flag: string): string | undefined {
-	const index = args.indexOf(flag);
-	if (index < 0) return undefined;
-	return args[index + 1];
-}
-
-function hasFlag(args: readonly string[], flag: string): boolean {
-	return args.includes(flag);
-}
-
 const GRAPH_FORMATS = new Set(["ascii", "mermaid", "dot"]);
-const FLAGS_WITH_VALUES = new Set([
-	"--input",
-	"--mode",
-	"--session-id",
-	"--thread-id",
-	"--turn-id",
-	"--to",
-	"--skill",
-	"--format",
-	"--older-than",
-	"--status",
-	"--fields",
-	"--since",
-	"--limit",
-]);
-const ACTION_NAMES = new Set([
-	"read",
-	"write",
-	"clear",
-	"contract",
-	"handoff",
-	"graph",
-	"prune",
-	"gc",
-	"migrate",
-	"status",
-	"doctor",
-]);
-const BOOLEAN_FLAGS = new Set([
-	"--json",
-	"--replace",
-	"--hard",
-	"--dry-run",
-	"--migrate",
-	"--compact",
-	"--history",
-	"--force",
-]);
-const VERB_SPECIFIC_FLAGS = new Set([
-	"--skill",
-	"--format",
-	"--older-than",
-	"--status",
-	"--fields",
-	"--since",
-	"--limit",
-	"--history",
-]);
-
-function flagName(arg: string): string | undefined {
-	if (!arg.startsWith("--")) return undefined;
-	const equalsIndex = arg.indexOf("=");
-	return equalsIndex >= 0 ? arg.slice(0, equalsIndex) : arg;
-}
-
-function manifestFlagNames(action: ParsedInvocation["action"], positionalSkill: string | undefined): Set<string> {
-	const names = new Set<string>();
-	const skills =
-		positionalSkill && KNOWN_MODES.includes(positionalSkill)
-			? [positionalSkill as CanonicalSkcWorkflowSkill]
-			: CANONICAL_SKC_WORKFLOW_SKILLS;
-	for (const skill of skills) {
-		for (const arg of typedArgsFor(skill, action)) names.add(`--${arg.name}`);
-	}
-	return names;
-}
-
-function assertKnownFlags(args: readonly string[], parsed: ParsedInvocation): void {
-	const manifestFlags = manifestFlagNames(parsed.action, parsed.positionalSkill);
-	for (const arg of args) {
-		const flag = flagName(arg);
-		if (!flag) continue;
-		if (
-			FLAGS_WITH_VALUES.has(flag) ||
-			BOOLEAN_FLAGS.has(flag) ||
-			VERB_SPECIFIC_FLAGS.has(flag) ||
-			manifestFlags.has(flag)
-		) {
-			continue;
-		}
-		throw new StateCommandError(2, `unknown skc state flag: ${flag}`);
-	}
+function assertKnownFlags(classification: StateArgvClassification): void {
+	const [unknownFlag] = classification.unknownFlags;
+	if (unknownFlag) throw new StateCommandError(2, `unknown skc state flag: ${unknownFlag}`);
 }
 
-interface ParsedInvocation {
-	action:
-		| "read"
-		| "write"
-		| "clear"
-		| "contract"
-		| "handoff"
-		| "graph"
-		| "prune"
-		| "gc"
-		| "migrate"
-		| "status"
-		| "doctor";
-	positionalSkill?: string;
-}
-
-function parsePositionalArgs(args: readonly string[]): ParsedInvocation {
-	let skipNext = false;
-	const positional: string[] = [];
-	for (const arg of args) {
-		if (skipNext) {
-			skipNext = false;
-			continue;
-		}
-		if (FLAGS_WITH_VALUES.has(arg)) {
-			skipNext = true;
-			continue;
-		}
-		if (!arg.startsWith("-")) positional.push(arg);
-	}
-	// Documented argv shapes:
-	//   skc state read|write|clear|contract ...
-	//   skc state <skill> read|write|contract ...
-	const first = positional[0];
-	const second = positional[1];
-	if (first && ACTION_NAMES.has(first)) {
-		return { action: first as ParsedInvocation["action"], positionalSkill: second };
-	}
-	if (first && second && ACTION_NAMES.has(second)) {
-		return { action: second as ParsedInvocation["action"], positionalSkill: first };
-	}
-	// `skc state <skill>` alone defaults to read for that skill.
-	if (first && !second) {
-		return { action: "read", positionalSkill: first };
-	}
-	return { action: "read" };
-}
-
-function assertSafePathComponent(value: string, label: string): void {
-	if (!PATH_COMPONENT_RE.test(value) || value.includes("..")) {
-		throw new StateCommandError(2, `invalid path component for --${label}: ${value}`);
-	}
-}
 function isKnownMode(mode: string): mode is CanonicalSkcWorkflowSkill {
 	return KNOWN_MODES.includes(mode);
 }
@@ -290,19 +157,16 @@ interface ResolvedSelectors {
 // `clear` resolves like a read (explicit -> payload -> env -> latest-activity marker)
 // per the spec: read/status/clear may fall back to the most-recent session. Commands
 // that create or mutate new state roots still require an explicit/env session id.
-const WRITE_SESSION_ACTIONS = new Set<ParsedInvocation["action"]>(["write", "handoff", "prune", "migrate"]);
+const WRITE_SESSION_ACTIONS = new Set<StateAction>(["write", "handoff", "prune", "migrate"]);
 
-async function resolveSelectors(
-	args: readonly string[],
-	cwd: string,
-	positionalSkill: string | undefined,
-	action: ParsedInvocation["action"],
-): Promise<ResolvedSelectors> {
-	const payload = await readInputJson(flagValue(args, "--input"), cwd);
+async function resolveSelectors(args: readonly string[], cwd: string, action: StateAction): Promise<ResolvedSelectors> {
+	const classification = classifyStateArgv(args);
+	const payload = await readInputJson(firstStateFlagValue(classification, "--input"), cwd);
 
+	const [modeCandidate, positionalCandidate] = classification.runtimeSelectorCandidates;
 	const candidates: Array<string | undefined> = [
-		flagValue(args, "--mode")?.trim() || undefined,
-		positionalSkill?.trim() || undefined,
+		modeCandidate?.value,
+		positionalCandidate?.value,
 		typeof payload?.mode === "string" ? (payload.mode as string).trim() || undefined : undefined,
 		typeof payload?.skill === "string" ? (payload.skill as string).trim() || undefined : undefined,
 	];
@@ -391,7 +255,9 @@ async function describeStaleClearState(
 	existing: Record<string, unknown>,
 ): Promise<string | undefined> {
 	const phase = typeof existing.current_phase === "string" ? existing.current_phase.trim() : undefined;
-	if (phase && TERMINAL_CLEAR_PHASES.has(phase)) return `mode-state is already terminal (${phase})`;
+	if (phase && getSkillManifest(mode).stopReleasingPhases.includes(phase) && phase !== "inactive") {
+		return `mode-state is already terminal (${phase})`;
+	}
 	const activePhase = await readActivePhaseForSkill(cwd, sessionId, mode);
 	if (activePhase && phase && activePhase !== phase) {
 		return `active-state phase ${activePhase} differs from mode-state phase ${phase}`;
@@ -504,22 +370,11 @@ function phaseFromActiveValue(value: unknown): string | undefined {
 	return phase || undefined;
 }
 
-const RALPLAN_CANONICAL_PHASE_OVERRIDES = new Set([
-	"final",
-	"handoff",
-	"complete",
-	"completed",
-	"failed",
-	"cancelled",
-	"canceled",
-	"inactive",
-]);
-
 function modeStatePhase(value: unknown): string | undefined {
 	if (!isPlainObject(value) || typeof value.current_phase !== "string") return undefined;
 	const phase = value.current_phase.trim();
 	if (!phase) return undefined;
-	if (value.active === false && !RALPLAN_CANONICAL_PHASE_OVERRIDES.has(phase)) return undefined;
+	if (value.active === false && !getSkillManifest("ralplan").canonicalOverrides.includes(phase)) return undefined;
 	return phase;
 }
 
@@ -821,6 +676,7 @@ async function writeJsonAtomic(
 		fromPhase?: string;
 		toPhase?: string;
 		owner?: WorkflowStateMutationOwner;
+		lockHeld?: boolean;
 	},
 ): Promise<{ warning?: string; stamped: Record<string, unknown>; revision: number }> {
 	const warning = options?.skill
@@ -850,6 +706,7 @@ async function writeJsonAtomic(
 			toPhase: options?.toPhase,
 			forced: options?.force ?? false,
 		},
+		lockHeld: options?.lockHeld ?? false,
 	});
 	// `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
@@ -938,10 +795,6 @@ async function readAuditWindow(
 	return { entries: selected.reverse(), limit, ...(since ? { since } : {}), truncated: matched > limit };
 }
 
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
-
 /**
  * Shallow-merge `source` into `target`, with the convention that a `source` key whose value is
  * `null` deletes that key from `target`. Nested objects are replaced wholesale (not deep-merged)
@@ -1127,12 +980,23 @@ export async function reconcileWorkflowSkillState(options: {
 	payload: Record<string, unknown>;
 	sourceRevision?: number;
 }): Promise<{ stateFile: string }> {
-	const { cwd, mode, threadId, turnId, active, payload } = options;
-	const { skcSessionId: sessionId } = resolveSkcSessionForWrite(cwd, {
+	const { skcSessionId: sessionId } = resolveSkcSessionForWrite(options.cwd, {
 		payloadSessionId: options.sessionId,
 		envSessionId: process.env.SKC_SESSION_ID,
 	});
+	return withWorkflowStateLock(
+		path.relative(options.cwd, modeStateFile(options.cwd, options.mode, sessionId)),
+		async () => reconcileWorkflowSkillStateUnlocked(options, sessionId),
+	);
+}
+
+async function reconcileWorkflowSkillStateUnlocked(
+	options: Parameters<typeof reconcileWorkflowSkillState>[0],
+	sessionId: string,
+): Promise<{ stateFile: string }> {
+	const { cwd, mode, threadId, turnId, active, payload } = options;
 	const filePath = modeStateFile(cwd, mode, sessionId);
+	if (mode === "deep-interview") assertDeepInterviewStructuredResponseWithinLimit(payload);
 	const existingRead = await readExistingStateForMutation(filePath);
 	const existingPayload = existingRead.kind === "valid" ? existingRead.value : {};
 	const nowIsoStr = nowIso();
@@ -1169,6 +1033,7 @@ export async function reconcileWorkflowSkillState(options: {
 					unknown
 				>)
 			: mergeWithNullDelete(existingPayload, payload);
+	if (mode === "deep-interview") assertDeepInterviewEnvelopeInputLimits(merged);
 	merged.skill = mode;
 	merged.current_phase = trimmedPhase;
 	merged.active = active;
@@ -1181,9 +1046,10 @@ export async function reconcileWorkflowSkillState(options: {
 	if (!validation.valid) throw new StateCommandError(2, validation.error ?? `invalid ${mode} state envelope`);
 
 	if (existingRead.kind === "corrupt") await fs.rm(filePath, { force: true });
-	await writeGuardedWorkflowEnvelopeAtomic(filePath, merged, {
+	const writeResult = await writeGuardedWorkflowEnvelopeAtomic(filePath, merged, {
 		cwd,
 		policy: "source",
+		lockHeld: true,
 		receipt: {
 			cwd,
 			skill: mode,
@@ -1209,8 +1075,7 @@ export async function reconcileWorkflowSkillState(options: {
 			toPhase: trimmedPhase,
 		},
 	});
-	const persisted = (await readJsonFile(filePath)) ?? {};
-	const sourceRevision = options.sourceRevision ?? existingStateRevision(persisted);
+	const sourceRevision = options.sourceRevision ?? writeResult.revision;
 
 	// Reconciliation drives the active-state/HUD update directly (not via the
 	// best-effort syncWorkflowSkillState wrapper) so a failed HUD/active-state write
@@ -1244,12 +1109,8 @@ export async function readWorkflowStateJson(
 	return (await readJsonFile(modeStateFile(cwd, skill, session.skcSessionId))) ?? {};
 }
 
-async function handleRead(
-	args: readonly string[],
-	cwd: string,
-	positionalSkill: string | undefined,
-): Promise<StateCommandResult> {
-	const selectors = await resolveSelectors(args, cwd, positionalSkill, "read");
+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.skcSessionId));
 	const fields = parseFieldsFlag(args);
 	if (mode) {
@@ -1288,12 +1149,8 @@ async function handleRead(
 	return { status: 0, stdout: `${JSON.stringify(existing ?? {}, null, 2)}\n` };
 }
 
-async function handleStatus(
-	args: readonly string[],
-	cwd: string,
-	positionalSkill: string | undefined,
-): Promise<StateCommandResult> {
-	const selectors = await resolveSelectors(args, cwd, positionalSkill, "read");
+async function handleStatus(args: readonly string[], cwd: string): Promise<StateCommandResult> {
+	const selectors = await resolveSelectors(args, cwd, "read");
 	const mode = selectors.mode ?? (await inferModeFromActiveState(cwd, selectors.skcSessionId));
 	if (!mode) {
 		throw new StateCommandError(
@@ -1315,12 +1172,8 @@ async function handleStatus(
 	};
 }
 
-async function handleWrite(
-	args: readonly string[],
-	cwd: string,
-	positionalSkill: string | undefined,
-): Promise<StateCommandResult> {
-	const selectors = await resolveSelectors(args, cwd, positionalSkill, "write");
+async function handleWrite(args: readonly string[], cwd: string): Promise<StateCommandResult> {
+	const selectors = await resolveSelectors(args, cwd, "write");
 	const { skcSessionId: sessionId, threadId, turnId, payload } = selectors;
 	if (!payload) throw new StateCommandError(2, "skc state write requires --input '<json>'");
 	const mode = selectors.mode ?? (await inferModeFromActiveState(cwd, sessionId));
@@ -1330,142 +1183,167 @@ async function handleWrite(
 			"skc state write requires --mode <skill>, positional <skill>, input.skill, or an active workflow in the current session active state",
 		);
 
-	const filePath = modeStateFile(cwd, mode, sessionId);
-	const forced = hasFlag(args, "--force");
-	const existingRead = await readExistingStateForMutation(filePath);
-	if (existingRead.kind === "corrupt" && !forced) {
-		throw new StateCommandError(
-			2,
-			`existing state for ${mode} is corrupt or tampered (${existingRead.error}); use --force to overwrite`,
-		);
-	}
-	const existingPayload = existingRead.kind === "valid" ? existingRead.value : {};
-	const nowIsoStr = nowIso();
-	const mutationId = `${mode}:${nowIsoStr}`;
-	const receipt = buildWorkflowStateReceipt({
-		cwd,
-		skill: mode,
-		owner: "skc-state-cli",
-		command: `skc state ${mode} write`,
-		sessionId,
-		nowIso: nowIsoStr,
-		mutationId,
-	});
-	const innerState = (payload.state as Record<string, unknown> | undefined) ?? {};
-	const incomingPhase =
-		typeof payload.current_phase === "string" && payload.current_phase.trim()
-			? payload.current_phase.trim()
-			: typeof payload.phase === "string" && payload.phase.trim()
-				? payload.phase.trim()
-				: typeof innerState.current_phase === "string" && (innerState.current_phase as string).trim()
-					? (innerState.current_phase as string).trim()
-					: undefined;
-	let merged: Record<string, unknown>;
 	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).
-		// 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 {
-		merged = mergeWithNullDelete(existingPayload, payload);
-		// Flatten payload.state.* into the top-level envelope so downstream consumers
-		// see a single canonical structure with the receipt at top level.
-		if (payload.state && typeof payload.state === "object" && !Array.isArray(payload.state)) {
-			merged = mergeWithNullDelete(merged, payload.state as Record<string, unknown>);
-			delete merged.state;
-		}
-	}
-	const preDefaultValidation = validateWorkflowStateEnvelope(mode, merged);
-	if (!preDefaultValidation.valid) {
-		throw new StateCommandError(2, preDefaultValidation.error ?? `invalid ${mode} state envelope`);
-	}
-	merged.skill = mode;
-	if (incomingPhase) {
-		merged.current_phase = incomingPhase;
-	} else if (typeof merged.current_phase !== "string" || !merged.current_phase.trim()) {
-		const retainedPhase =
-			typeof existingPayload.current_phase === "string" ? existingPayload.current_phase.trim() : "";
-		merged.current_phase = retainedPhase || initialPhaseForSkill(mode);
-	} else {
-		merged.current_phase = merged.current_phase.trim();
-	}
-	merged.version = WORKFLOW_STATE_VERSION;
-	if (typeof merged.active !== "boolean") merged.active = true;
-	merged.updated_at = nowIsoStr;
-	merged.receipt = receipt;
-	if (sessionId && typeof merged.session_id !== "string") merged.session_id = sessionId;
-
-	const fromPhase =
-		typeof existingPayload.current_phase === "string" ? existingPayload.current_phase.trim() : undefined;
-	const toPhase = merged.current_phase as string;
-	const manifestStates = new Set(getSkillManifest(mode).states.map(state => state.id));
-	if (!manifestStates.has(toPhase) && !forced) {
-		throw new StateCommandError(2, `unknown ${mode} phase "${toPhase}"; use --force to bypass`);
-	}
-	if (fromPhase && toPhase && isKnownWorkflowState(mode, fromPhase) && isKnownWorkflowState(mode, toPhase)) {
-		if (!isValidTransition(mode, fromPhase, toPhase) && !forced) {
-			throw new StateCommandError(
-				2,
-				`invalid ${mode} phase transition from ${fromPhase} to ${toPhase}; use --force to bypass`,
-			);
+		try {
+			assertDeepInterviewStructuredResponseWithinLimit(payload);
+		} catch (error) {
+			throw new StateCommandError(2, error instanceof Error ? error.message : String(error));
 		}
 	}
+	const filePath = modeStateFile(cwd, mode, sessionId);
+	const forced = hasFlag(args, "--force");
+	return await withWorkflowStateLock(
+		filePath,
+		async () => {
+			const existingRead = await readExistingStateForMutation(filePath);
+			if (existingRead.kind === "corrupt" && !forced) {
+				throw new StateCommandError(
+					2,
+					`existing state for ${mode} is corrupt or tampered (${existingRead.error}); use --force to overwrite`,
+				);
+			}
+			const existingPayload = existingRead.kind === "valid" ? existingRead.value : {};
+			const nowIsoStr = nowIso();
+			const mutationId = `${mode}:${nowIsoStr}`;
+			const receipt = buildWorkflowStateReceipt({
+				cwd,
+				skill: mode,
+				owner: "skc-state-cli",
+				command: `skc state ${mode} write`,
+				sessionId,
+				nowIso: nowIsoStr,
+				mutationId,
+			});
+			const innerState = (payload.state as Record<string, unknown> | undefined) ?? {};
+			const incomingPhase =
+				typeof payload.current_phase === "string" && payload.current_phase.trim()
+					? payload.current_phase.trim()
+					: typeof payload.phase === "string" && payload.phase.trim()
+						? payload.phase.trim()
+						: typeof innerState.current_phase === "string" && (innerState.current_phase as string).trim()
+							? (innerState.current_phase as string).trim()
+							: undefined;
+			let merged: Record<string, unknown>;
+			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).
+				// 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;
+				try {
+					assertDeepInterviewEnvelopeInputLimits(merged);
+				} catch (error) {
+					throw new StateCommandError(2, error instanceof Error ? error.message : String(error));
+				}
+			} else if (hasFlag(args, "--replace")) {
+				merged = { ...payload };
+			} else {
+				merged = mergeWithNullDelete(existingPayload, payload);
+				// Flatten payload.state.* into the top-level envelope so downstream consumers
+				// see a single canonical structure with the receipt at top level.
+				if (payload.state && typeof payload.state === "object" && !Array.isArray(payload.state)) {
+					merged = mergeWithNullDelete(merged, payload.state as Record<string, unknown>);
+					delete merged.state;
+				}
+			}
+			const preDefaultValidation = validateWorkflowStateEnvelope(mode, merged);
+			if (!preDefaultValidation.valid) {
+				throw new StateCommandError(2, preDefaultValidation.error ?? `invalid ${mode} state envelope`);
+			}
+			merged.skill = mode;
+			if (incomingPhase) {
+				merged.current_phase = incomingPhase;
+			} else if (typeof merged.current_phase !== "string" || !merged.current_phase.trim()) {
+				const retainedPhase =
+					typeof existingPayload.current_phase === "string" ? existingPayload.current_phase.trim() : "";
+				merged.current_phase = retainedPhase || initialPhaseForSkill(mode);
+			} else {
+				merged.current_phase = merged.current_phase.trim();
+			}
+			merged.version = WORKFLOW_STATE_VERSION;
+			if (typeof merged.active !== "boolean") merged.active = true;
+			merged.updated_at = nowIsoStr;
+			merged.receipt = receipt;
+			if (sessionId && typeof merged.session_id !== "string") merged.session_id = sessionId;
+
+			const fromPhase =
+				typeof existingPayload.current_phase === "string" ? existingPayload.current_phase.trim() : undefined;
+			const toPhase = merged.current_phase as string;
+			const manifestStates = new Set(getSkillManifest(mode).states.map(state => state.id));
+			if (!manifestStates.has(toPhase) && !forced) {
+				throw new StateCommandError(2, `unknown ${mode} phase "${toPhase}"; use --force to bypass`);
+			}
+			if (fromPhase && toPhase && isKnownWorkflowState(mode, fromPhase) && isKnownWorkflowState(mode, toPhase)) {
+				if (!isValidTransition(mode, fromPhase, toPhase) && !forced) {
+					throw new StateCommandError(
+						2,
+						`invalid ${mode} phase transition from ${fromPhase} to ${toPhase}; use --force to bypass`,
+					);
+				}
+			}
 
-	const validation = validateWorkflowStateEnvelope(mode, merged);
-	if (!validation.valid) throw new StateCommandError(2, validation.error ?? `invalid ${mode} state envelope`);
-
-	const {
-		warning: outOfBandWarning,
-		stamped,
-		revision: stampedRevision,
-	} = await writeJsonAtomic(cwd, filePath, merged, "write", {
-		sessionId,
-		skill: mode,
-		mutationId,
-		force: forced,
-		fromPhase,
-		toPhase,
-	});
-	const stampedReceipt = isPlainObject(stamped.receipt) ? stamped.receipt : {};
-
-	const phase = typeof merged.current_phase === "string" ? merged.current_phase : undefined;
-	const active = merged.active !== false;
-	// Reflect the lock-owned mode-state revision onto the in-memory payload so the active-state/HUD
-	// sync derives a `sourceRevision` from the revision this write actually owns (computed inside the
-	// writer lock), not the stale pre-write value or a post-lock re-read a concurrent writer could
-	// have advanced; otherwise the active-state writer stale-skips the update and the mirror keeps the
-	// prior phase (e.g. staying "interviewing" after a "handoff" write).
-	merged.state_revision = stampedRevision;
-	await syncWorkflowSkillState({ cwd, mode, sessionId, threadId, turnId, active, phase, payload: merged, receipt });
-	await touchStateActivityMarker(cwd, sessionId, filePath);
+			const validation = validateWorkflowStateEnvelope(mode, merged);
+			if (!validation.valid) throw new StateCommandError(2, validation.error ?? `invalid ${mode} state envelope`);
+
+			const {
+				warning: outOfBandWarning,
+				stamped,
+				revision: stampedRevision,
+			} = await writeJsonAtomic(cwd, filePath, merged, "write", {
+				sessionId,
+				skill: mode,
+				mutationId,
+				force: forced,
+				fromPhase,
+				toPhase,
+				lockHeld: true,
+			});
+			const stampedReceipt = isPlainObject(stamped.receipt) ? stamped.receipt : {};
+
+			const phase = typeof merged.current_phase === "string" ? merged.current_phase : undefined;
+			const active = merged.active !== false;
+			// Reflect the lock-owned mode-state revision onto the in-memory payload so the active-state/HUD
+			// sync derives a `sourceRevision` from the revision this write actually owns (computed inside the
+			// writer lock), not the stale pre-write value or a post-lock re-read a concurrent writer could
+			// have advanced; otherwise the active-state writer stale-skips the update and the mirror keeps the
+			// prior phase (e.g. staying "interviewing" after a "handoff" write).
+			merged.state_revision = stampedRevision;
+			await syncWorkflowSkillState({
+				cwd,
+				mode,
+				sessionId,
+				threadId,
+				turnId,
+				active,
+				phase,
+				payload: merged,
+				receipt,
+			});
+			await touchStateActivityMarker(cwd, sessionId, filePath);
 
-	return {
-		status: 0,
-		stdout: renderCliWriteReceipt({
-			ok: true,
-			skill: mode,
-			state_path: filePath,
-			current_phase: phase,
-			active,
-			mutation_id: typeof stampedReceipt.mutation_id === "string" ? stampedReceipt.mutation_id : mutationId,
-			status: typeof stampedReceipt.status === "string" ? stampedReceipt.status : undefined,
-			content_sha256: stampedReceipt.content_sha256,
-		}),
-		...(outOfBandWarning ? { stderr: `${outOfBandWarning}\n` } : {}),
-	};
+			return {
+				status: 0,
+				stdout: renderCliWriteReceipt({
+					ok: true,
+					skill: mode,
+					state_path: receipt.state_path,
+					current_phase: phase,
+					active,
+					mutation_id: typeof stampedReceipt.mutation_id === "string" ? stampedReceipt.mutation_id : mutationId,
+					status: typeof stampedReceipt.status === "string" ? stampedReceipt.status : undefined,
+					content_sha256: stampedReceipt.content_sha256,
+				}),
+				...(outOfBandWarning ? { stderr: `${outOfBandWarning}\n` } : {}),
+			};
+		},
+		{ cwd },
+	);
 }
 
-async function handleClear(
-	args: readonly string[],
-	cwd: string,
-	positionalSkill: string | undefined,
-): Promise<StateCommandResult> {
-	const selectors = await resolveSelectors(args, cwd, positionalSkill, "clear");
+async function handleClear(args: readonly string[], cwd: string): Promise<StateCommandResult> {
+	const selectors = await resolveSelectors(args, cwd, "clear");
 	const { skcSessionId: sessionId, threadId, turnId } = selectors;
 	const mode = selectors.mode ?? (await inferModeFromActiveState(cwd, sessionId));
 	if (!mode)
@@ -1476,74 +1354,143 @@ async function handleClear(
 
 	const filePath = modeStateFile(cwd, mode, sessionId);
 	const forced = hasFlag(args, "--force");
-	const existingRead = await readExistingStateForMutation(filePath);
-	if (existingRead.kind === "corrupt" && !forced) {
+	return await withWorkflowStateLock(
+		filePath,
+		async () => {
+			const existingRead = await readExistingStateForMutation(filePath);
+			if (existingRead.kind === "corrupt" && !forced) {
+				throw new StateCommandError(
+					2,
+					`existing state for ${mode} is corrupt or tampered (${existingRead.error}); use --force to overwrite`,
+				);
+			}
+			const existing = existingRead.kind === "valid" ? existingRead.value : {};
+			const staleReason = await describeStaleClearState(cwd, sessionId, mode, existing);
+			if (staleReason && !forced) {
+				throw new StateCommandError(
+					2,
+					`existing state for ${mode} is stale (${staleReason}); use --force to clear`,
+				);
+			}
+			const clearedAt = nowIso();
+			const cleared: Record<string, unknown> = {
+				skill: mode,
+				...existing,
+				active: false,
+				current_phase: "complete",
+				updated_at: clearedAt,
+				version: WORKFLOW_STATE_VERSION,
+			};
+			cleared.skill = mode;
+			const mutationId = `${mode}:clear:${clearedAt}`;
+			const receipt = buildWorkflowStateReceipt({
+				cwd,
+				skill: mode,
+				owner: "skc-state-cli",
+				command: `skc state ${mode} clear`,
+				sessionId,
+				nowIso: clearedAt,
+				mutationId,
+			});
+			cleared.receipt = receipt;
+			const { warning: outOfBandWarning, stamped } = await writeJsonAtomic(cwd, filePath, cleared, "clear", {
+				sessionId,
+				skill: mode,
+				mutationId,
+				force: forced,
+				fromPhase: typeof existing.current_phase === "string" ? existing.current_phase : undefined,
+				toPhase: "complete",
+				lockHeld: true,
+			});
+			const stampedReceipt = isPlainObject(stamped.receipt) ? stamped.receipt : {};
+
+			await syncWorkflowSkillState({
+				cwd,
+				mode,
+				sessionId,
+				threadId,
+				turnId,
+				active: false,
+				phase: "complete",
+				payload: cleared,
+			});
+			await touchStateActivityMarker(cwd, sessionId, filePath);
+			return {
+				status: 0,
+				stdout: renderCliWriteReceipt({
+					ok: true,
+					skill: mode,
+					state_path: receipt.state_path,
+					active: false,
+					current_phase: typeof cleared.current_phase === "string" ? cleared.current_phase : undefined,
+					mutation_id: typeof stampedReceipt.mutation_id === "string" ? stampedReceipt.mutation_id : mutationId,
+					status: typeof stampedReceipt.status === "string" ? stampedReceipt.status : undefined,
+					content_sha256: stampedReceipt.content_sha256,
+				}),
+				...(outOfBandWarning ? { stderr: `${outOfBandWarning}\n` } : {}),
+			};
+		},
+		{ cwd },
+	);
+}
+
+const DEEP_INTERVIEW_INTENT_ID_RE = /(?:artifact|surface|integration|constraint):[a-z0-9][a-z0-9._/-]{0,127}/g;
+
+async function assertDeepInterviewHandoffReady(state: Record<string, unknown>): Promise<void> {
+	const specPath = typeof state.spec_path === "string" ? state.spec_path : undefined;
+	const expectedSha = typeof state.spec_sha256 === "string" ? state.spec_sha256 : undefined;
+	let content: string | undefined;
+	if (specPath) {
+		try {
+			content = await fs.readFile(specPath, "utf-8");
+		} catch (error) {
+			throw new StateCommandError(
+				2,
+				`deep-interview handoff cannot read persisted spec: ${error instanceof Error ? error.message : String(error)}`,
+			);
+		}
+		const boundedContent = content.endsWith("\n") ? content.slice(0, -1) : content;
+		assertDeepInterviewInputWithinLimit(
+			boundedContent,
+			MAX_DEEP_INTERVIEW_STRUCTURED_RESPONSE_LENGTH,
+			"persisted deep-interview spec",
+		);
+	}
+	const envelope = normalizeDeepInterviewEnvelope(state);
+	const inner = envelope.state;
+	if (!inner) return;
+	if (inner.intent_contract === undefined) {
+		if (inner.intent_contract_required === true)
+			throw new StateCommandError(2, "deep-interview handoff requires a locked Round 0 intent contract");
+		return;
+	}
+	assertDeepInterviewIntentManifest(inner.intent_contract);
+	if (!specPath || !expectedSha || content === undefined)
+		throw new StateCommandError(2, "deep-interview handoff requires a persisted intent-validated spec");
+	if (createHash("sha256").update(content).digest("hex") !== expectedSha)
+		throw new StateCommandError(2, "deep-interview handoff spec hash mismatch");
+	const observedIds = [...new Set(content.match(DEEP_INTERVIEW_INTENT_ID_RE) ?? [])].sort();
+	const rounds = Array.isArray(inner.rounds)
+		? inner.rounds
+				.filter(
+					(round): round is Record<string, unknown> =>
+						Boolean(round) && typeof round === "object" && !Array.isArray(round),
+				)
+				.map(round => ({ round: round.round, answer_hash: round.answer_hash }))
+		: [];
+	try {
+		assertDeepInterviewIntentReview(
+			inner.intent_review,
+			inner.intent_contract as DeepInterviewIntentManifest,
+			observedIds,
+			rounds,
+		);
+	} catch (error) {
 		throw new StateCommandError(
 			2,
-			`existing state for ${mode} is corrupt or tampered (${existingRead.error}); use --force to overwrite`,
+			`deep-interview handoff intent validation failed: ${error instanceof Error ? error.message : String(error)}`,
 		);
 	}
-	const existing = existingRead.kind === "valid" ? existingRead.value : {};
-	const staleReason = await describeStaleClearState(cwd, sessionId, mode, existing);
-	if (staleReason && !forced) {
-		throw new StateCommandError(2, `existing state for ${mode} is stale (${staleReason}); use --force to clear`);
-	}
-	const clearedAt = nowIso();
-	const cleared: Record<string, unknown> = {
-		skill: mode,
-		...existing,
-		active: false,
-		current_phase: "complete",
-		updated_at: clearedAt,
-		version: WORKFLOW_STATE_VERSION,
-	};
-	cleared.skill = mode;
-	const mutationId = `${mode}:clear:${clearedAt}`;
-	const receipt = buildWorkflowStateReceipt({
-		cwd,
-		skill: mode,
-		owner: "skc-state-cli",
-		command: `skc state ${mode} clear`,
-		sessionId,
-		nowIso: clearedAt,
-		mutationId,
-	});
-	cleared.receipt = receipt;
-	const { warning: outOfBandWarning, stamped } = await writeJsonAtomic(cwd, filePath, cleared, "clear", {
-		sessionId,
-		skill: mode,
-		mutationId,
-		force: forced,
-		fromPhase: typeof existing.current_phase === "string" ? existing.current_phase : undefined,
-		toPhase: "complete",
-	});
-	const stampedReceipt = isPlainObject(stamped.receipt) ? stamped.receipt : {};
-
-	await syncWorkflowSkillState({
-		cwd,
-		mode,
-		sessionId,
-		threadId,
-		turnId,
-		active: false,
-		phase: "complete",
-		payload: cleared,
-	});
-	await touchStateActivityMarker(cwd, sessionId, filePath);
-	return {
-		status: 0,
-		stdout: renderCliWriteReceipt({
-			ok: true,
-			skill: mode,
-			state_path: filePath,
-			active: false,
-			current_phase: typeof cleared.current_phase === "string" ? cleared.current_phase : undefined,
-			mutation_id: typeof stampedReceipt.mutation_id === "string" ? stampedReceipt.mutation_id : mutationId,
-			status: typeof stampedReceipt.status === "string" ? stampedReceipt.status : undefined,
-			content_sha256: stampedReceipt.content_sha256,
-		}),
-		...(outOfBandWarning ? { stderr: `${outOfBandWarning}\n` } : {}),
-	};
 }
 
 /**
@@ -1565,12 +1512,8 @@ async function handleClear(
  * the phase remains in `skill-active-state.json` until a chain call (or
  * explicit `clear`) demotes it.
  */
-async function handleHandoff(
-	args: readonly string[],
-	cwd: string,
-	positionalSkill: string | undefined,
-): Promise<StateCommandResult> {
-	const selectors = await resolveSelectors(args, cwd, positionalSkill, "handoff");
+async function handleHandoffUnlocked(args: readonly string[], cwd: string): Promise<StateCommandResult> {
+	const selectors = await resolveSelectors(args, cwd, "handoff");
 	const { skcSessionId: sessionId, threadId, turnId } = selectors;
 	const caller = selectors.mode ?? (await inferModeFromActiveState(cwd, sessionId));
 	if (!caller) {
@@ -1619,18 +1562,19 @@ async function handleHandoff(
 		nowIso: handoffAt,
 		mutationId,
 	});
+	const normalizedCaller =
+		caller === "deep-interview"
+			? (normalizeDeepInterviewEnvelope(migrateWorkflowState(existingCaller, caller).state) as Record<
+					string,
+					unknown
+				>)
+			: migrateWorkflowState(existingCaller, caller).state;
+	if (caller === "deep-interview") await assertDeepInterviewHandoffReady(normalizedCaller);
 
 	// Runtime callees have no native mode-state to clear later, so do not
 	// persist them as active-state entries; the prompt observer tracks them
 	// in memory the same way direct `/skill:<runtime>` invocation does.
 	if (!calleeIsWorkflow) {
-		const normalizedCaller =
-			caller === "deep-interview"
-				? (normalizeDeepInterviewEnvelope(migrateWorkflowState(existingCaller, caller).state) as Record<
-						string,
-						unknown
-					>)
-				: migrateWorkflowState(existingCaller, caller).state;
 		const mergedCallerState: Record<string, unknown> = {
 			...normalizedCaller,
 			skill: caller,
@@ -1727,13 +1671,6 @@ async function handleHandoff(
 	});
 
 	const calleeInitial = initialPhaseForSkill(callee);
-	const normalizedCaller =
-		caller === "deep-interview"
-			? (normalizeDeepInterviewEnvelope(migrateWorkflowState(existingCaller, caller).state) as Record<
-					string,
-					unknown
-				>)
-			: migrateWorkflowState(existingCaller, caller).state;
 	const normalizedCallee =
 		callee === "deep-interview"
 			? (normalizeDeepInterviewEnvelope(migrateWorkflowState(existingCallee, callee).state) as Record<
@@ -1884,12 +1821,22 @@ async function handleHandoff(
 	};
 }
 
-async function handleContract(
-	args: readonly string[],
-	cwd: string,
-	positionalSkill: string | undefined,
-): Promise<StateCommandResult> {
-	const { mode } = await resolveSelectors(args, cwd, positionalSkill, "read");
+async function handleHandoff(args: readonly string[], cwd: string): Promise<StateCommandResult> {
+	const selectors = await resolveSelectors(args, cwd, "handoff");
+	// Serialize concurrent handoffs on a dedicated sentinel lock, NOT on the
+	// derived `skill-active-state.json` cache. The inner transaction
+	// (applyHandoffToActiveState / syncSkillActiveState -> rebuildActiveSnapshot)
+	// re-locks that cache file, and `withFileLock` is not reentrant: holding the
+	// active-state lock here made the inner rebuild self-contend and fail after
+	// all retries whenever `cwd === process.cwd()` (the real CLI case). Pass
+	// `{ cwd }` so the sentinel resolves against the handoff cwd rather than
+	// `process.cwd()`.
+	const handoffLock = path.join(sessionStateDir(cwd, selectors.skcSessionId), "handoff");
+	return withWorkflowStateLock(handoffLock, async () => handleHandoffUnlocked(args, cwd), { cwd });
+}
+
+async function handleContract(args: readonly string[], cwd: string): Promise<StateCommandResult> {
+	const { mode } = await resolveSelectors(args, cwd, "read");
 	if (!mode) {
 		throw new StateCommandError(2, "skc state contract requires --mode <skill>, positional <skill>, or input.skill");
 	}
@@ -2117,12 +2064,8 @@ async function handleGraph(
 	};
 }
 
-async function handlePrune(
-	args: readonly string[],
-	cwd: string,
-	positionalSkill: string | undefined,
-): Promise<StateCommandResult> {
-	const selectors = await resolveSelectors(args, cwd, positionalSkill, "prune");
+async function handlePrune(args: readonly string[], cwd: string): Promise<StateCommandResult> {
+	const selectors = await resolveSelectors(args, cwd, "prune");
 	const mode = selectors.mode ?? (await inferModeFromActiveState(cwd, selectors.skcSessionId));
 	if (!mode) {
 		throw new StateCommandError(
@@ -2187,12 +2130,8 @@ async function handleGc(
 	return { status: 0, stdout: `${JSON.stringify(summary, null, 2)}\n` };
 }
 
-async function handleMigrate(
-	args: readonly string[],
-	cwd: string,
-	positionalSkill: string | undefined,
-): Promise<StateCommandResult> {
-	const selectors = await resolveSelectors(args, cwd, positionalSkill, "migrate");
+async function handleMigrate(args: readonly string[], cwd: string): Promise<StateCommandResult> {
+	const selectors = await resolveSelectors(args, cwd, "migrate");
 	const mode = selectors.mode ?? (await inferModeFromActiveState(cwd, selectors.skcSessionId));
 	if (!mode) {
 		throw new StateCommandError(
@@ -2223,37 +2162,34 @@ async function handleMigrate(
 
 export async function runNativeStateCommand(args: string[], cwd = process.cwd()): Promise<StateCommandResult> {
 	try {
-		const parsed = parsePositionalArgs(args);
-		assertKnownFlags(args, parsed);
-		switch (parsed.action) {
+		const parsed = classifyStateArgv(args);
+		assertKnownFlags(parsed);
+		switch (parsed.effectiveAction) {
 			case "read":
-				if (hasFlag(args, "--migrate")) return await handleMigrate(args, cwd, parsed.positionalSkill);
-				return await handleRead(args, cwd, parsed.positionalSkill);
+				return await handleRead(args, cwd);
 			case "write":
-				return await handleWrite(args, cwd, parsed.positionalSkill);
+				return await handleWrite(args, cwd);
 			case "clear":
-				return await handleClear(args, cwd, parsed.positionalSkill);
+				return await handleClear(args, cwd);
 			case "contract":
-				return await handleContract(args, cwd, parsed.positionalSkill);
+				return await handleContract(args, cwd);
 			case "status":
-				return await handleStatus(args, cwd, parsed.positionalSkill);
+				return await handleStatus(args, cwd);
 			case "doctor":
 				return await handleDoctor(args, cwd, parsed.positionalSkill);
 			case "handoff":
-				return await handleHandoff(args, cwd, parsed.positionalSkill);
+				return await handleHandoff(args, cwd);
 			case "graph":
 				return await handleGraph(args, cwd, parsed.positionalSkill);
 			case "prune":
-				return await handlePrune(args, cwd, parsed.positionalSkill);
+				return await handlePrune(args, cwd);
 			case "gc":
 				return await handleGc(args, cwd, parsed.positionalSkill);
 			case "migrate":
-				return await handleMigrate(args, cwd, parsed.positionalSkill);
-			default:
-				return { status: 2, stderr: `Unknown skc state command: ${parsed.action}\n` };
+				return await handleMigrate(args, cwd);
 		}
 	} catch (error) {
-		if (error instanceof StateCommandError) return { status: error.exitStatus, stderr: `${error.message}\n` };
+		if (error instanceof CommandError) return { status: error.exitStatus, stderr: `${error.message}\n` };
 		if (error instanceof SessionResolutionError) return { status: 2, stderr: `${error.message}\n` };
 		return { status: 1, stderr: `${error instanceof Error ? error.message : String(error)}\n` };
 	}