@gajae-code/coding-agent 0.3.0 → 0.3.2

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

@@ -21,10 +21,12 @@ import {
 	buildWorkflowStateReceipt,
 	canonicalWorkflowSkill,
 	describeWorkflowStateContract,
+	WORKFLOW_STATE_VERSION,
 	type WorkflowStateReceipt,
 } from "../skill-state/workflow-state-contract";
+import { renderCliWriteReceipt } from "./cli-write-receipt";
 import { renderStateGraph, type StateGraphFormat } from "./state-graph";
-import { migrateAndPersistLegacyState } from "./state-migrations";
+import { migrateAndPersistLegacyState, migrateWorkflowState } from "./state-migrations";
 import {
 	buildStateStatusSummary,
 	compactProjectStateJson,
@@ -44,6 +46,7 @@ import {
 	detectWorkflowEnvelopeIntegrityMismatch,
 	type GenericHardPruneTarget,
 	hardPrune,
+	readExistingStateForMutation,
 	type StateWriterAuditContext,
 	softDelete,
 	updateWorkflowTransactionJournal,
@@ -116,6 +119,7 @@ const ACTION_NAMES = new Set([
 	"gc",
 	"migrate",
 	"status",
+	"doctor",
 ]);
 const BOOLEAN_FLAGS = new Set([
 	"--json",
@@ -174,7 +178,18 @@ function assertKnownFlags(args: readonly string[], parsed: ParsedInvocation): vo
 }
 
 interface ParsedInvocation {
-	action: "read" | "write" | "clear" | "contract" | "handoff" | "graph" | "prune" | "gc" | "migrate" | "status";
+	action:
+		| "read"
+		| "write"
+		| "clear"
+		| "contract"
+		| "handoff"
+		| "graph"
+		| "prune"
+		| "gc"
+		| "migrate"
+		| "status"
+		| "doctor";
 	positionalSkill?: string;
 }
 
@@ -344,7 +359,8 @@ async function readJsonFile(filePath: string): Promise<Record<string, unknown> |
 	} catch (error) {
 		const err = error as NodeJS.ErrnoException;
 		if (err.code === "ENOENT") return null;
-		throw new StateCommandError(1, `failed to read ${filePath}: ${err.message}`);
+		process.stderr.write(`WARNING: failed to read ${filePath}; ignoring corrupt state: ${err.message}\n`);
+		return null;
 	}
 }
 
@@ -354,8 +370,285 @@ async function readJsonValue(filePath: string): Promise<unknown | null> {
 	} catch (error) {
 		const err = error as NodeJS.ErrnoException;
 		if (err.code === "ENOENT") return null;
-		throw new StateCommandError(1, `failed to read ${filePath}: ${err.message}`);
+		process.stderr.write(`WARNING: failed to read ${filePath}; ignoring corrupt state: ${err.message}\n`);
+		return null;
+	}
+}
+
+type DoctorProblemType = "orphan_journal" | "checksum_mismatch" | "schema_violation" | "stale_active_state";
+
+interface DoctorProblem {
+	type: DoctorProblemType;
+	skill?: CanonicalGjcWorkflowSkill;
+	path: string;
+	message: string;
+	fixCommand: string;
+}
+
+interface DoctorSummary {
+	ok: boolean;
+	root: string;
+	summary: {
+		skills_scanned: number;
+		files_scanned: number;
+		journals_scanned: number;
+		findings_total: number;
+		by_kind: Record<DoctorProblemType, number>;
+	};
+	problems: DoctorProblem[];
+}
+
+async function readRawJson(filePath: string): Promise<{ exists: boolean; value?: unknown; error?: string }> {
+	try {
+		return { exists: true, value: JSON.parse(await fs.readFile(filePath, "utf-8")) };
+	} catch (error) {
+		const err = error as NodeJS.ErrnoException;
+		if (err.code === "ENOENT") return { exists: false };
+		return { exists: true, error: err.message };
+	}
+}
+
+async function listJsonFiles(dir: string): Promise<string[]> {
+	let entries: string[];
+	try {
+		entries = await fs.readdir(dir);
+	} catch (error) {
+		const err = error as NodeJS.ErrnoException;
+		if (err.code === "ENOENT") return [];
+		throw error;
+	}
+	return entries
+		.filter(entry => entry.endsWith(".json"))
+		.sort()
+		.map(entry => path.join(dir, entry));
+}
+
+function doctorProblem(
+	type: DoctorProblemType,
+	pathValue: string,
+	message: string,
+	fixCommand: string,
+	skill?: CanonicalGjcWorkflowSkill,
+): DoctorProblem {
+	return skill
+		? { type, skill, path: pathValue, message, fixCommand }
+		: { type, path: pathValue, message, fixCommand };
+}
+
+function activeEntryDir(cwd: string, sessionId: string | undefined): string {
+	return path.join(stateDirFor(cwd, sessionId), "active");
+}
+
+function skillFromActiveValue(value: unknown): string | undefined {
+	return isPlainObject(value) && typeof value.skill === "string" ? value.skill : undefined;
+}
+
+function activeFlag(value: unknown): boolean {
+	return isPlainObject(value) && value.active !== false;
+}
+
+async function collectDoctorSummary(
+	cwd: string,
+	skill: CanonicalGjcWorkflowSkill | undefined,
+	sessionId: string | undefined,
+): Promise<DoctorSummary> {
+	const root = path.join(cwd, ".gjc", "state");
+	const skills = skill ? [skill] : [...CANONICAL_GJC_WORKFLOW_SKILLS];
+	const problems: DoctorProblem[] = [];
+	let filesScanned = 0;
+	let journalsScanned = 0;
+
+	for (const currentSkill of skills) {
+		const filePath = modeStateFile(cwd, currentSkill, sessionId);
+		const raw = await readRawJson(filePath);
+		if (!raw.exists) continue;
+		filesScanned += 1;
+		if (raw.error) {
+			problems.push(
+				doctorProblem(
+					"schema_violation",
+					filePath,
+					`mode-state JSON is unreadable: ${raw.error}`,
+					`gjc state ${currentSkill} migrate`,
+					currentSkill,
+				),
+			);
+			continue;
+		}
+		const validation = validateWorkflowStateEnvelope(currentSkill, raw.value);
+		if (!validation.valid) {
+			problems.push(
+				doctorProblem(
+					"schema_violation",
+					filePath,
+					validation.error ?? `invalid ${currentSkill} state envelope`,
+					`gjc state ${currentSkill} migrate`,
+					currentSkill,
+				),
+			);
+		}
+		const mismatch = await detectWorkflowEnvelopeIntegrityMismatch(filePath);
+		if (mismatch) {
+			problems.push(
+				doctorProblem(
+					"checksum_mismatch",
+					filePath,
+					`expected sha256 ${mismatch.expected} but found ${mismatch.actual}`,
+					`gjc state ${currentSkill} migrate`,
+					currentSkill,
+				),
+			);
+		}
+	}
+
+	const journalFiles = await listJsonFiles(path.join(root, "transactions"));
+	for (const journalPath of journalFiles) {
+		journalsScanned += 1;
+		const raw = await readRawJson(journalPath);
+		const value = raw.value;
+		const status = isPlainObject(value) && typeof value.status === "string" ? value.status : undefined;
+		const paths =
+			isPlainObject(value) && Array.isArray(value.paths) ? value.paths.filter(p => typeof p === "string") : [];
+		const hasLiveMutation = status === "pending" && paths.some(filePath => path.resolve(filePath).startsWith(root));
+		if (!hasLiveMutation) {
+			problems.push(
+				doctorProblem(
+					"orphan_journal",
+					journalPath,
+					"transaction journal has no matching live mutation",
+					"gjc state prune --hard",
+				),
+			);
+		}
 	}
+
+	const inspectActiveScope = async (scopeSessionId: string | undefined): Promise<void> => {
+		const snapshotPath = activeStateFile(cwd, scopeSessionId);
+		const snapshot = await readRawJson(snapshotPath);
+		if (snapshot.exists) filesScanned += 1;
+		const entryFiles = await listJsonFiles(activeEntryDir(cwd, scopeSessionId));
+		const entrySkills = new Set<string>();
+		for (const entryPath of entryFiles) {
+			filesScanned += 1;
+			const entry = await readRawJson(entryPath);
+			const entrySkill = skillFromActiveValue(entry.value) ?? path.basename(entryPath, ".json");
+			entrySkills.add(entrySkill);
+			const canonical = canonicalWorkflowSkill(entrySkill);
+			if (canonical && !skills.includes(canonical)) continue;
+			const statePath = canonical
+				? modeStateFile(cwd, canonical, scopeSessionId)
+				: path.join(root, `${entrySkill}-state.json`);
+			const state = await readRawJson(statePath);
+			if (activeFlag(entry.value) && (!state.exists || !activeFlag(state.value))) {
+				problems.push(
+					doctorProblem(
+						"stale_active_state",
+						entryPath,
+						`active entry for ${entrySkill} does not match a live active mode-state`,
+						canonical ? `gjc state ${canonical} clear` : "gjc state prune --hard",
+						canonical ?? undefined,
+					),
+				);
+			}
+		}
+		if (isPlainObject(snapshot.value)) {
+			const activeSkills = Array.isArray(snapshot.value.active_skills) ? snapshot.value.active_skills : [];
+			for (const entry of activeSkills) {
+				const entrySkill = skillFromActiveValue(entry);
+				if (!entrySkill) continue;
+				const canonical = canonicalWorkflowSkill(entrySkill);
+				if (canonical && !skills.includes(canonical)) continue;
+				if (activeFlag(entry) && !entrySkills.has(entrySkill)) {
+					problems.push(
+						doctorProblem(
+							"stale_active_state",
+							snapshotPath,
+							`active snapshot lists ${entrySkill} but no raw per-skill active entry exists`,
+							canonical ? `gjc state ${canonical} clear` : "gjc state prune --hard",
+							canonical ?? undefined,
+						),
+					);
+				}
+			}
+		}
+	};
+
+	await inspectActiveScope(sessionId);
+	if (!sessionId) {
+		const sessionsDir = path.join(root, "sessions");
+		let sessions: string[] = [];
+		try {
+			const entries = await fs.readdir(sessionsDir, { withFileTypes: true });
+			sessions = entries
+				.filter(entry => entry.isDirectory())
+				.map(entry => entry.name)
+				.sort();
+		} catch (error) {
+			const err = error as NodeJS.ErrnoException;
+			if (err.code !== "ENOENT") throw error;
+		}
+		for (const rawSession of sessions) await inspectActiveScope(decodeURIComponent(rawSession));
+	}
+
+	problems.sort(
+		(a, b) =>
+			a.type.localeCompare(b.type) || (a.skill ?? "").localeCompare(b.skill ?? "") || a.path.localeCompare(b.path),
+	);
+	const byKind: Record<DoctorProblemType, number> = {
+		orphan_journal: 0,
+		checksum_mismatch: 0,
+		schema_violation: 0,
+		stale_active_state: 0,
+	};
+	for (const problem of problems) byKind[problem.type] += 1;
+	return {
+		ok: problems.length === 0,
+		root,
+		summary: {
+			skills_scanned: skills.length,
+			files_scanned: filesScanned,
+			journals_scanned: journalsScanned,
+			findings_total: problems.length,
+			by_kind: byKind,
+		},
+		problems,
+	};
+}
+
+function renderDoctorText(summary: DoctorSummary): string {
+	const lines = [
+		`ok: ${summary.ok}`,
+		`root: ${summary.root}`,
+		`skills_scanned: ${summary.summary.skills_scanned}`,
+		`files_scanned: ${summary.summary.files_scanned}`,
+		`journals_scanned: ${summary.summary.journals_scanned}`,
+		`findings_total: ${summary.summary.findings_total}`,
+		`counts: ${Object.entries(summary.summary.by_kind)
+			.map(([kind, count]) => `${kind}=${count}`)
+			.join(", ")}`,
+	];
+	for (const problem of summary.problems) {
+		lines.push(
+			`finding: kind=${problem.type} skill=${problem.skill ?? "-"} path=${problem.path} message=${problem.message} fix=${problem.fixCommand}`,
+		);
+	}
+	return `${lines.join("\n")}\n`;
+}
+
+async function handleDoctor(
+	args: readonly string[],
+	cwd: string,
+	positionalSkill: string | undefined,
+): Promise<StateCommandResult> {
+	const rawSkill = flagValue(args, "--skill")?.trim() || flagValue(args, "--mode")?.trim() || positionalSkill?.trim();
+	if (rawSkill) assertKnownMode(rawSkill);
+	const sessionId = flagValue(args, "--session-id")?.trim() || undefined;
+	if (sessionId) assertSafePathComponent(sessionId, "session-id");
+	const summary = await collectDoctorSummary(cwd, rawSkill as CanonicalGjcWorkflowSkill | undefined, sessionId);
+	return {
+		status: summary.ok ? 0 : 1,
+		stdout: hasFlag(args, "--json") ? `${JSON.stringify(summary, null, 2)}\n` : renderDoctorText(summary),
+	};
 }
 
 async function warnAndAuditOutOfBandIfNeeded(
@@ -364,7 +657,14 @@ async function warnAndAuditOutOfBandIfNeeded(
 	skill: CanonicalGjcWorkflowSkill,
 	options?: { mutationId?: string; forced?: boolean },
 ): Promise<string | undefined> {
-	const mismatch = await detectWorkflowEnvelopeIntegrityMismatch(filePath);
+	let mismatch: Awaited<ReturnType<typeof detectWorkflowEnvelopeIntegrityMismatch>>;
+	try {
+		mismatch = await detectWorkflowEnvelopeIntegrityMismatch(filePath);
+	} catch {
+		// Unparseable/corrupt state has no recoverable checksum to compare; the strict
+		// mutation reader already gates unforced overwrites, so fail-open here.
+		return undefined;
+	}
 	if (!mismatch) return undefined;
 	const message = `WARNING: workflow mode-state out-of-band edit detected for ${skill}: ${filePath} expected sha256 ${mismatch.expected} but found ${mismatch.actual}`;
 	await appendAuditEntry(cwd, {
@@ -394,7 +694,7 @@ async function writeJsonAtomic(
 		fromPhase?: string;
 		toPhase?: string;
 	},
-): Promise<string | undefined> {
+): Promise<{ warning?: string; stamped: Record<string, unknown> }> {
 	const warning = options?.skill
 		? await warnAndAuditOutOfBandIfNeeded(cwd, filePath, options.skill, {
 				mutationId: options.mutationId,
@@ -417,7 +717,7 @@ async function writeJsonAtomic(
 			forced: options?.force ?? false,
 		},
 	});
-	return warning;
+	return { warning, stamped: (await readJsonFile(filePath)) ?? {} };
 }
 
 function parseFieldsFlag(args: readonly string[]): StateProjectionField[] | undefined {
@@ -752,8 +1052,15 @@ async function handleWrite(
 		);
 
 	const filePath = modeStateFile(cwd, mode, sessionId);
-	const existingRaw = await readJsonValue(filePath);
-	const existing = isPlainObject(existingRaw) ? existingRaw : null;
+	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({
@@ -765,10 +1072,6 @@ async function handleWrite(
 		nowIso: nowIsoStr,
 		mutationId,
 	});
-	if (existingRaw !== null && !isPlainObject(existingRaw)) {
-		throw new StateCommandError(2, `existing state for ${mode} must be a JSON object before write`);
-	}
-	const existingPayload = existing ?? {};
 	const innerState = (payload.state as Record<string, unknown> | undefined) ?? {};
 	const incomingPhase =
 		typeof payload.current_phase === "string" && payload.current_phase.trim()
@@ -797,19 +1100,26 @@ async function handleWrite(
 	merged.skill = mode;
 	if (incomingPhase) {
 		merged.current_phase = incomingPhase;
-	} else if (typeof merged.current_phase !== "string") {
-		merged.current_phase =
-			typeof existingPayload.current_phase === "string" ? existingPayload.current_phase : "active";
+	} 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();
 	}
-	if (typeof merged.version !== "number") merged.version = 1;
+	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 : undefined;
-	const toPhase = typeof merged.current_phase === "string" ? merged.current_phase : undefined;
-	const forced = hasFlag(args, "--force");
+	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(
@@ -822,13 +1132,14 @@ async function handleWrite(
 	const validation = validateWorkflowStateEnvelope(mode, merged);
 	if (!validation.valid) throw new StateCommandError(2, validation.error ?? `invalid ${mode} state envelope`);
 
-	const outOfBandWarning = await writeJsonAtomic(cwd, filePath, merged, "write", {
+	const { warning: outOfBandWarning, stamped } = await writeJsonAtomic(cwd, filePath, merged, "write", {
 		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;
@@ -836,7 +1147,16 @@ async function handleWrite(
 
 	return {
 		status: 0,
-		stdout: `${JSON.stringify({ skill: mode, state: merged, receipt }, null, 2)}\n`,
+		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` } : {}),
 	};
 }
@@ -856,19 +1176,44 @@ async function handleClear(
 		);
 
 	const filePath = modeStateFile(cwd, mode, sessionId);
-	const existing = (await readJsonFile(filePath)) ?? {};
+	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 existing = existingRead.kind === "valid" ? existingRead.value : {};
+	const clearedAt = nowIso();
 	const cleared: Record<string, unknown> = {
+		skill: mode,
 		...existing,
 		active: false,
 		current_phase: "complete",
-		updated_at: nowIso(),
+		updated_at: clearedAt,
+		version: WORKFLOW_STATE_VERSION,
 	};
-	const outOfBandWarning = await writeJsonAtomic(cwd, filePath, cleared, "clear", {
+	cleared.skill = mode;
+	const mutationId = `${mode}:clear:${clearedAt}`;
+	const receipt = buildWorkflowStateReceipt({
+		cwd,
+		skill: mode,
+		owner: "gjc-state-cli",
+		command: `gjc state ${mode} clear`,
+		sessionId,
+		nowIso: clearedAt,
+		mutationId,
+	});
+	cleared.receipt = receipt;
+	const { warning: outOfBandWarning, stamped } = await writeJsonAtomic(cwd, filePath, cleared, "clear", {
 		skill: mode,
-		force: hasFlag(args, "--force"),
+		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,
@@ -882,7 +1227,16 @@ async function handleClear(
 	});
 	return {
 		status: 0,
-		stdout: `${JSON.stringify(cleared, null, 2)}\n`,
+		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` } : {}),
 	};
 }
@@ -932,14 +1286,29 @@ async function handleHandoff(
 
 	const callerPath = modeStateFile(cwd, caller, sessionId);
 	const calleePath = modeStateFile(cwd, callee, sessionId);
-	const existingCaller = await readJsonFile(callerPath);
-	if (!existingCaller) {
+	const forced = hasFlag(args, "--force");
+	const callerRead = await readExistingStateForMutation(callerPath);
+	if (callerRead.kind === "corrupt" && !forced) {
+		throw new StateCommandError(
+			2,
+			`existing state for ${caller} is corrupt or tampered (${callerRead.error}); use --force to overwrite`,
+		);
+	}
+	if (callerRead.kind === "absent") {
 		throw new StateCommandError(
 			2,
 			`gjc state ${caller} handoff: caller is not active (no mode-state file at ${callerPath})`,
 		);
 	}
-	const existingCallee = (await readJsonFile(calleePath)) ?? {};
+	const calleeRead = await readExistingStateForMutation(calleePath);
+	if (calleeRead.kind === "corrupt" && !forced) {
+		throw new StateCommandError(
+			2,
+			`existing state for ${callee} is corrupt or tampered (${calleeRead.error}); use --force to overwrite`,
+		);
+	}
+	const existingCaller = callerRead.kind === "valid" ? callerRead.value : {};
+	const existingCallee = calleeRead.kind === "valid" ? calleeRead.value : {};
 
 	const handoffAt = nowIso();
 	const mutationId = `${caller}:handoff:${callee}:${handoffAt}`;
@@ -963,10 +1332,12 @@ async function handleHandoff(
 	});
 
 	const calleeInitial = initialPhaseForSkill(callee);
+	const normalizedCaller = migrateWorkflowState(existingCaller, caller).state;
+	const normalizedCallee = migrateWorkflowState(existingCallee, callee).state;
 	const mergedCalleeState: Record<string, unknown> = {
-		...existingCallee,
+		...normalizedCallee,
 		skill: callee,
-		version: typeof existingCallee.version === "number" ? existingCallee.version : 1,
+		version: WORKFLOW_STATE_VERSION,
 		active: true,
 		current_phase: calleeInitial,
 		handoff_from: caller,
@@ -978,8 +1349,9 @@ async function handleHandoff(
 		mergedCalleeState.session_id = sessionId;
 	}
 	const mergedCallerState: Record<string, unknown> = {
-		...existingCaller,
+		...normalizedCaller,
 		skill: caller,
+		version: WORKFLOW_STATE_VERSION,
 		active: false,
 		current_phase: "handoff",
 		handoff_to: callee,
@@ -1004,26 +1376,29 @@ async function handleHandoff(
 	// root aggregate. strict:true on the active-state read tolerates ENOENT
 	// only; corrupt JSON / IO failures propagate as non-zero CLI status.
 	const force = hasFlag(args, "--force");
-	const warnings = [
-		await writeJsonAtomic(cwd, calleePath, mergedCalleeState, "handoff", {
-			skill: callee,
-			mutationId,
-			force,
-			fromPhase: typeof existingCallee.current_phase === "string" ? existingCallee.current_phase : undefined,
-			toPhase: calleeInitial,
-		}),
-		await updateWorkflowTransactionJournal(cwd, mutationId, { steps: ["callee-mode-state"] }).then(() => undefined),
-		await writeJsonAtomic(cwd, callerPath, mergedCallerState, "handoff", {
-			skill: caller,
-			mutationId,
-			force,
-			fromPhase: typeof existingCaller.current_phase === "string" ? existingCaller.current_phase : undefined,
-			toPhase: "handoff",
-		}),
-		await updateWorkflowTransactionJournal(cwd, mutationId, {
-			steps: ["callee-mode-state", "caller-mode-state"],
-		}).then(() => undefined),
-	].filter((warning): warning is string => typeof warning === "string");
+	const calleeWrite = await writeJsonAtomic(cwd, calleePath, mergedCalleeState, "handoff", {
+		skill: callee,
+		mutationId,
+		force,
+		fromPhase: typeof existingCallee.current_phase === "string" ? existingCallee.current_phase : undefined,
+		toPhase: calleeInitial,
+	});
+	await updateWorkflowTransactionJournal(cwd, mutationId, { steps: ["callee-mode-state"] });
+	const callerWrite = await writeJsonAtomic(cwd, callerPath, mergedCallerState, "handoff", {
+		skill: caller,
+		mutationId,
+		force,
+		fromPhase: typeof existingCaller.current_phase === "string" ? existingCaller.current_phase : undefined,
+		toPhase: "handoff",
+	});
+	await updateWorkflowTransactionJournal(cwd, mutationId, {
+		steps: ["callee-mode-state", "caller-mode-state"],
+	});
+	const warnings = [calleeWrite.warning, callerWrite.warning].filter(
+		(warning): warning is string => typeof warning === "string",
+	);
+	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`);
 	if (process.env.GJC_STATE_HANDOFF_FAIL_AFTER_CALLER === mutationId) {
 		throw new StateCommandError(1, `injected handoff failure after caller write for ${mutationId}`);
@@ -1068,17 +1443,33 @@ async function handleHandoff(
 
 	return {
 		status: 0,
-		stdout: `${JSON.stringify(
-			{
-				from: caller,
-				to: callee,
-				handoff_at: handoffAt,
-				caller_state: mergedCallerState,
-				callee_state: mergedCalleeState,
+		stdout: renderCliWriteReceipt({
+			ok: true,
+			from: caller,
+			to: callee,
+			handoff_at: handoffAt,
+			phases: {
+				from: mergedCallerState.current_phase,
+				to: mergedCalleeState.current_phase,
 			},
-			null,
-			2,
-		)}\n`,
+			receipts: {
+				from: {
+					mutation_id: stampedCallerReceipt.mutation_id,
+					status: stampedCallerReceipt.status,
+					content_sha256: stampedCallerReceipt.content_sha256,
+				},
+				to: {
+					mutation_id: stampedCalleeReceipt.mutation_id,
+					status: stampedCalleeReceipt.status,
+					content_sha256: stampedCalleeReceipt.content_sha256,
+				},
+			},
+			paths: {
+				from: callerPath,
+				to: calleePath,
+				active_state: activeStateFile(cwd, sessionId),
+			},
+		}),
 	};
 }
 
@@ -1392,9 +1783,13 @@ async function handleMigrate(
 		);
 	}
 	const filePath = modeStateFile(cwd, mode, selectors.sessionId);
+	const forced = hasFlag(args, "--force");
 	const mismatchWarning = await warnAndAuditOutOfBandIfNeeded(cwd, filePath, mode, {
-		forced: hasFlag(args, "--force"),
+		forced,
 	});
+	if (mismatchWarning && !forced) {
+		throw new StateCommandError(2, `${mismatchWarning}; use --force to migrate tampered mode-state`);
+	}
 	const result = await migrateAndPersistLegacyState({
 		cwd,
 		skill: mode,
@@ -1424,6 +1819,8 @@ export async function runNativeStateCommand(args: string[], cwd = process.cwd())
 				return await handleContract(args, cwd, parsed.positionalSkill);
 			case "status":
 				return await handleStatus(args, cwd, parsed.positionalSkill);
+			case "doctor":
+				return await handleDoctor(args, cwd, parsed.positionalSkill);
 			case "handoff":
 				return await handleHandoff(args, cwd, parsed.positionalSkill);
 			case "graph":