@gajae-code/coding-agent 0.12.0 → 0.12.2

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

@@ -1,4 +1,5 @@
 import { createHash, randomBytes } from "node:crypto";
+import type { Dirent } from "node:fs";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { getConfigRootDir } from "@gajae-code/utils";
@@ -12,6 +13,12 @@ import {
 	type RalplanIndexRow,
 	summarizeRalplanIndex,
 } from "./ledger-event-renderer";
+import {
+	type IndexedReviewArtifact,
+	parseReviewConflictDocument,
+	reviewArtifactIndexKey,
+	serializeReviewConflictDocument,
+} from "./ralplan-review-conflicts";
 import {
 	assertCwdMatchesRepositoryBinding,
 	assertPathUnderRepositoryBinding,
@@ -22,7 +29,7 @@ import {
 	RepositoryBindingError,
 } from "./repository-binding";
 import { GJC_RALPLAN_ARTIFACT_ENV, isRestrictedRoleAgentBash } from "./restricted-role-agent-bash";
-import { gjcRoot, modeStatePath, sessionPlansDir } from "./session-layout";
+import { gjcRoot, modeStatePath, sessionIdFromDirName, sessionPlansDir } from "./session-layout";
 import { resolveGjcSessionForWrite, writeSessionActivityMarker } from "./session-resolution";
 import { migrateWorkflowState } from "./state-migrations";
 import { runNativeStateCommand } from "./state-runtime";
@@ -33,9 +40,9 @@ import {
 	writeArtifact,
 	writeWorkflowEnvelopeAtomic,
 } from "./state-writer";
+import { probeGjcTeamAvailability } from "./team-runtime";
 import { assertSafePathComponent, CommandError, flagValue, hasFlag } from "./workflow-cli-common";
 import { getSkillManifest } from "./workflow-manifest";
-
 /**
  * Native implementation of `gjc ralplan`.
  *
@@ -51,9 +58,11 @@ import { getSkillManifest } from "./workflow-manifest";
  * 2. **Artifact write**: `gjc ralplan --write --stage <type> --stage_n <N>
  *    (--artifact <path-or-string> | --artifact-env GJC_RALPLAN_ARTIFACT)
  *    [--run-id <id>] [--session-id <id>] [--lane-verdict <token>] [--json]` persists Planner / Architect
- *    / Critic / revision / post-interview / ADR / final markdown under `.gjc/plans/ralplan/<run-id>/`, maintains
- *    an `index.jsonl` audit log, copies `final` stages to `pending-approval.md`, and advances
- *    the HUD chip to reflect the latest persisted stage.
+ *    / Critic / disposition / revision / post-interview / ADR / final artifacts under
+ *    `.gjc/plans/ralplan/<run-id>/`, maintains an `index.jsonl` audit log, copies `final`
+ *    stages to `pending-approval.md`, and advances the HUD chip to reflect the latest
+ *    persisted stage. Disposition stage artifacts are fail-closed JSON documents that
+ *    record typed review conflicts with authoritative same-pass source receipts (#2902).
  */
 
 export interface RalplanCommandResult {
@@ -62,7 +71,16 @@ export interface RalplanCommandResult {
 	stderr?: string;
 }
 
-const KNOWN_STAGES = ["planner", "architect", "critic", "revision", "post-interview", "adr", "final"] as const;
+const KNOWN_STAGES = [
+	"planner",
+	"architect",
+	"critic",
+	"disposition",
+	"revision",
+	"post-interview",
+	"adr",
+	"final",
+] as const;
 type RalplanStage = (typeof KNOWN_STAGES)[number];
 /** Default consensus iterations (planner + revision openers) per run. Matches SKILL.md re-review cap. */
 export const RALPLAN_DEFAULT_MAX_ITERATIONS = 5;
@@ -74,6 +92,16 @@ export const PLANNING_STUCK_MARKER = "PLANNING-STUCK";
 export const RALPLAN_DEFAULT_MAX_REVIEW_PASSES_PER_LANE = 1;
 /** Inclusive upper bound for `gjc.ralplan.maxReviewPassesPerLane` settings overrides. */
 export const RALPLAN_MAX_REVIEW_PASSES_PER_LANE_LIMIT = 10;
+export type RalplanAutoHandoffTarget = "off" | "ultragoal" | "team";
+
+export interface RalplanAutoHandoffResolution {
+	configuredTarget: RalplanAutoHandoffTarget;
+	effectiveTarget: RalplanAutoHandoffTarget;
+	degradationReason: string | null;
+	source: string;
+}
+
+const RALPLAN_AUTO_HANDOFF_TARGETS = new Set<RalplanAutoHandoffTarget>(["off", "ultragoal", "team"]);
 
 const RALPLAN_ITERATION_OPENER_STAGES = new Set<RalplanStage>(["planner", "revision"]);
 
@@ -391,6 +419,115 @@ export async function resolveRalplanMaxIterations(cwd: string): Promise<{ maxIte
 	if (user !== null) return { maxIterations: user, source: userPath };
 	return { maxIterations: RALPLAN_DEFAULT_MAX_ITERATIONS, source: "default" };
 }
+function parseRalplanAutoHandoffTarget(value: unknown): RalplanAutoHandoffTarget | undefined {
+	return typeof value === "string" && RALPLAN_AUTO_HANDOFF_TARGETS.has(value as RalplanAutoHandoffTarget)
+		? (value as RalplanAutoHandoffTarget)
+		: undefined;
+}
+
+type RalplanAutoHandoffOptions = {
+	planningStuck?: boolean;
+	teamAvailabilityProbe?: () => { available: true } | { available: false; reason: string };
+};
+
+type RalplanAutoHandoffSetting =
+	| { kind: "absent" }
+	| { kind: "valid"; value: RalplanAutoHandoffTarget }
+	| { kind: "invalid"; reason: string };
+
+function parsePresentRalplanAutoHandoff(value: unknown): RalplanAutoHandoffSetting {
+	const target = parseRalplanAutoHandoffTarget(value);
+	return target === undefined
+		? {
+				kind: "invalid",
+				reason: "expected gjc.ralplan.autoHandoff to be one of off, ultragoal, team",
+			}
+		: { kind: "valid", value: target };
+}
+
+function parseRalplanAutoHandoffSettings(parsed: unknown): RalplanAutoHandoffSetting {
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return { kind: "absent" };
+	const settings = parsed as Record<string, unknown>;
+	if (Object.hasOwn(settings, "gjc.ralplan.autoHandoff")) {
+		return parsePresentRalplanAutoHandoff(settings["gjc.ralplan.autoHandoff"]);
+	}
+	const gjc = settings.gjc;
+	if (!gjc || typeof gjc !== "object" || Array.isArray(gjc)) return { kind: "absent" };
+	const ralplan = (gjc as Record<string, unknown>).ralplan;
+	if (!ralplan || typeof ralplan !== "object" || Array.isArray(ralplan)) return { kind: "absent" };
+	const ralplanSettings = ralplan as Record<string, unknown>;
+	if (!Object.hasOwn(ralplanSettings, "autoHandoff")) return { kind: "absent" };
+	return parsePresentRalplanAutoHandoff(ralplanSettings.autoHandoff);
+}
+
+async function readSettingsAutoHandoff(settingsPath: string): Promise<RalplanAutoHandoffSetting> {
+	let raw: string;
+	try {
+		raw = await Bun.file(settingsPath).text();
+	} catch (error) {
+		if (getErrorCode(error) === "ENOENT") return { kind: "absent" };
+		return {
+			kind: "invalid",
+			reason: `unable to read settings: ${error instanceof Error ? error.message : String(error)}`,
+		};
+	}
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (error) {
+		return {
+			kind: "invalid",
+			reason: `malformed JSON: ${error instanceof Error ? error.message : String(error)}`,
+		};
+	}
+	return parseRalplanAutoHandoffSettings(parsed);
+}
+
+export async function resolveRalplanAutoHandoff(
+	cwd: string,
+	options: RalplanAutoHandoffOptions = {},
+): Promise<RalplanAutoHandoffResolution> {
+	const projectPath = path.join(gjcRoot(cwd), "settings.json");
+	const project = await readSettingsAutoHandoff(projectPath);
+	if (project.kind === "invalid") {
+		throw new RalplanCommandError(2, `invalid ralplan settings at ${projectPath}: ${project.reason}`);
+	}
+	if (project.kind === "valid") {
+		return resolveRalplanAutoHandoffTarget(project.value, projectPath, options);
+	}
+	const userPath = path.join(getConfigRootDir(), "settings.json");
+	const user = await readSettingsAutoHandoff(userPath);
+	if (user.kind === "invalid") {
+		throw new RalplanCommandError(2, `invalid ralplan settings at ${userPath}: ${user.reason}`);
+	}
+	return resolveRalplanAutoHandoffTarget(
+		user.kind === "valid" ? user.value : "off",
+		user.kind === "valid" ? userPath : "default",
+		options,
+	);
+}
+
+function resolveRalplanAutoHandoffTarget(
+	configuredTarget: RalplanAutoHandoffTarget,
+	source: string,
+	options: RalplanAutoHandoffOptions,
+): RalplanAutoHandoffResolution {
+	if (options.planningStuck) {
+		return { configuredTarget, effectiveTarget: "off", degradationReason: "planning_stuck", source };
+	}
+	if (configuredTarget !== "team")
+		return { configuredTarget, effectiveTarget: configuredTarget, degradationReason: null, source };
+
+	const availability = (options.teamAvailabilityProbe ?? probeGjcTeamAvailability)();
+	return availability.available
+		? { configuredTarget, effectiveTarget: "team", degradationReason: null, source }
+		: {
+				configuredTarget,
+				effectiveTarget: "off",
+				degradationReason: `team_unavailable:${availability.reason}`,
+				source,
+			};
+}
 
 function parseMaxReviewPassesPerLaneValue(value: unknown): number | null {
 	return parseBoundedPositiveInteger(value, RALPLAN_MAX_REVIEW_PASSES_PER_LANE_LIMIT);
@@ -763,6 +900,8 @@ async function persistActiveRunId(cwd: string, sessionId: string, runId: string,
 				for (const key of Object.keys(existing)) {
 					if (key.startsWith("last_review_verdict")) delete existing[key];
 				}
+				delete existing.planning_stuck;
+				delete existing.auto_handoff;
 			}
 			if (
 				existing.run_id === runId &&
@@ -1094,6 +1233,194 @@ async function applyLaneVerdictUpdate(
 		{ cwd },
 	);
 }
+function ralplanPlanningStuckIndexKey(entry: unknown): string | undefined {
+	if (!entry || typeof entry !== "object" || Array.isArray(entry)) return undefined;
+	const record = entry as Record<string, unknown>;
+	return record.planning_stuck === true ? "planning_stuck" : undefined;
+}
+
+async function recordRalplanPlanningStuck(
+	cwd: string,
+	sessionId: string,
+	runId: string,
+	reason: string,
+): Promise<void> {
+	const runDir = path.join(sessionPlansDir(cwd, sessionId), "ralplan", runId);
+	await appendJsonlIdempotent(
+		path.join(runDir, "index.jsonl"),
+		{
+			event: "planning_stuck",
+			planning_stuck: true,
+			marker: PLANNING_STUCK_MARKER,
+			reason,
+			created_at: new Date().toISOString(),
+		},
+		{
+			cwd,
+			audit: {
+				category: "ledger",
+				verb: "append",
+				owner: "gjc-runtime",
+				skill: "ralplan",
+				sessionId,
+			},
+			key: ralplanPlanningStuckIndexKey,
+		},
+	);
+	const statePath = ralplanStatePath(cwd, sessionId);
+	await withWorkflowStateLock(
+		statePath,
+		async () => {
+			const existingRead = await readExistingStateForMutation(statePath);
+			if (existingRead.kind === "corrupt") return;
+			let existing: Record<string, unknown> = existingRead.kind === "valid" ? existingRead.value : {};
+			if (existing.run_id !== runId) return;
+			existing.planning_stuck = { marker: PLANNING_STUCK_MARKER, reason };
+			existing = migrateWorkflowState(existing, "ralplan").state;
+			existing.updated_at = new Date().toISOString();
+			await writeWorkflowEnvelopeAtomic(statePath, existing, {
+				cwd,
+				lockHeld: true,
+				receipt: { cwd, skill: "ralplan", owner: "gjc-runtime", command: "gjc ralplan planning-stuck", sessionId },
+				audit: { category: "state", verb: "write", owner: "gjc-runtime", skill: "ralplan", sessionId },
+			});
+		},
+		{ cwd },
+	);
+}
+
+async function readRalplanFinalAdmission(
+	cwd: string,
+	sessionId: string,
+	runId: string,
+): Promise<RalplanAutoHandoffResolution | undefined> {
+	const index = await loadRalplanIndexForCap(cwd, sessionId, runId);
+	if (index.rawText === undefined) return undefined;
+	let finalAdmission: RalplanAutoHandoffResolution | undefined;
+	for (const line of index.rawText.split(/\r?\n/)) {
+		try {
+			const row = JSON.parse(line) as Record<string, unknown>;
+			if (row.stage === "final" && typeof row.path === "string" && typeof row.sha256 === "string") {
+				finalAdmission = parseRalplanFinalAdmission(row.auto_handoff) ?? unavailableRalplanFinalAdmission();
+			}
+		} catch {
+			// The artifact dedupe guard handles malformed ledger records separately.
+		}
+	}
+	return finalAdmission;
+}
+
+async function readRalplanPlanningStuck(cwd: string, sessionId: string, runId: string): Promise<boolean> {
+	const index = await loadRalplanIndexForCap(cwd, sessionId, runId);
+	if (index.rawText === undefined) return index.indexPresent;
+	if (index.indexPresent && index.rawLineCount > 0 && index.parseableLines === 0) return true;
+	for (const line of index.rawText.split(/\r?\n/)) {
+		if (!line.trim()) continue;
+		try {
+			const row = JSON.parse(line) as Record<string, unknown>;
+			if (row.planning_stuck === true) return true;
+		} catch {
+			return true;
+		}
+	}
+	return false;
+}
+
+async function persistRalplanFinalAdmission(
+	cwd: string,
+	sessionId: string,
+	runId: string,
+	admission: RalplanAutoHandoffResolution,
+): Promise<void> {
+	const statePath = ralplanStatePath(cwd, sessionId);
+	await withWorkflowStateLock(
+		statePath,
+		async () => {
+			const existingRead = await readExistingStateForMutation(statePath);
+			if (existingRead.kind === "corrupt") {
+				throw new RalplanCommandError(
+					2,
+					`existing ralplan state is corrupt or tampered (${existingRead.error}); refusing to record final admission`,
+				);
+			}
+			let existing: Record<string, unknown> = existingRead.kind === "valid" ? existingRead.value : {};
+			if (existing.run_id !== runId) return;
+			existing.auto_handoff = admission;
+			existing = migrateWorkflowState(existing, "ralplan").state;
+			existing.updated_at = new Date().toISOString();
+			await writeWorkflowEnvelopeAtomic(statePath, existing, {
+				cwd,
+				lockHeld: true,
+				receipt: { cwd, skill: "ralplan", owner: "gjc-runtime", command: "gjc ralplan final-admission", sessionId },
+				audit: { category: "state", verb: "write", owner: "gjc-runtime", skill: "ralplan", sessionId },
+			});
+		},
+		{ cwd },
+	);
+}
+
+async function findExistingRalplanRunOwners(cwd: string, runId: string): Promise<string[]> {
+	let entries: Dirent<string>[];
+	try {
+		entries = await fs.readdir(gjcRoot(cwd), { withFileTypes: true });
+	} catch (error) {
+		const err = error as NodeJS.ErrnoException;
+		if (err.code === "ENOENT" || err.code === "ENOTDIR") return [];
+		throw error;
+	}
+
+	const owners = await Promise.all(
+		entries.map(async entry => {
+			if (!entry.isDirectory()) return undefined;
+			const sessionId = sessionIdFromDirName(entry.name);
+			if (!sessionId) return undefined;
+
+			const stateRead = await readExistingStateForMutation(ralplanStatePath(cwd, sessionId));
+			const stateOwnsRun =
+				stateRead.kind === "valid" &&
+				typeof stateRead.value.run_id === "string" &&
+				stateRead.value.run_id.trim() === runId;
+			if (stateOwnsRun) return sessionId;
+
+			try {
+				const stat = await fs.stat(path.join(sessionPlansDir(cwd, sessionId), "ralplan", runId));
+				return stat.isDirectory() ? sessionId : undefined;
+			} catch (error) {
+				const err = error as NodeJS.ErrnoException;
+				if (err.code === "ENOENT" || err.code === "ENOTDIR") return undefined;
+				throw error;
+			}
+		}),
+	);
+	return owners.filter((owner): owner is string => owner !== undefined).sort();
+}
+
+async function resolveArtifactSessionId(args: readonly string[], cwd: string, explicitRunId: string | undefined) {
+	const flagSessionId = flagValue(args, "--session-id");
+	const currentSession = resolveGjcSessionForWrite(cwd, {
+		flagValue: flagSessionId,
+		envSessionId: process.env.GJC_SESSION_ID,
+	});
+	if (!explicitRunId) return currentSession.gjcSessionId;
+
+	const owners = await findExistingRalplanRunOwners(cwd, explicitRunId);
+	if (owners.length === 0) return currentSession.gjcSessionId;
+	if (owners.length > 1) {
+		throw new RalplanCommandError(
+			2,
+			`ralplan run ${explicitRunId} has multiple owner sessions (${owners.join(", ")}); repair the fragmented run before writing`,
+		);
+	}
+
+	const ownerSessionId = owners[0]!;
+	if (flagSessionId !== undefined && currentSession.gjcSessionId !== ownerSessionId) {
+		throw new RalplanCommandError(
+			2,
+			`ralplan run ${explicitRunId} is owned by session ${ownerSessionId}, not ${currentSession.gjcSessionId}`,
+		);
+	}
+	return ownerSessionId;
+}
 
 async function resolveArtifactArgs(args: readonly string[], cwd: string): Promise<ResolvedArtifactArgs> {
 	const stage = flagValue(args, "--stage");
@@ -1115,20 +1442,18 @@ async function resolveArtifactArgs(args: readonly string[], cwd: string): Promis
 		throw new RalplanCommandError(2, `--artifact-env must be ${GJC_RALPLAN_ARTIFACT_ENV}`);
 	}
 
-	const session = resolveGjcSessionForWrite(cwd, {
-		flagValue: flagValue(args, "--session-id"),
-		envSessionId: process.env.GJC_SESSION_ID,
-	});
-	const sessionId = session.gjcSessionId;
+	const explicitRunId = flagValue(args, "--run-id")?.trim();
+	if (explicitRunId) assertSafePathComponent(explicitRunId, "run-id");
+
+	const sessionId = await resolveArtifactSessionId(args, cwd, explicitRunId);
 	assertSafePathComponent(sessionId, "session-id");
 	const sessionIdRaw = sessionId;
 
 	// Precedence for run_id:
 	//   1. explicit --run-id flag
-	//   2. existing run_id field in .gjc/state[/sessions/<id>]/ralplan-state.json
-	//   3. explicit --session-id flag (use as run id)
+	//   2. existing run_id field in the resolved owner session's ralplan state
+	//   3. resolved owner session id
 	//   4. freshly generated default run id
-	const explicitRunId = flagValue(args, "--run-id")?.trim();
 	const runId = explicitRunId || (await readActiveRunId(cwd, sessionId)) || sessionIdRaw || defaultRunId();
 	assertSafePathComponent(runId, "run-id");
 
@@ -1170,6 +1495,7 @@ async function persistArtifact(
 	cwd: string,
 	content: string,
 	sha256: string,
+	finalAdmission?: RalplanAutoHandoffResolution,
 ): Promise<PersistedArtifact> {
 	const runDir = path.join(sessionPlansDir(cwd, resolved.sessionId), "ralplan", resolved.runId);
 
@@ -1193,6 +1519,7 @@ async function persistArtifact(
 		path: filePath,
 		created_at: createdAt,
 		sha256,
+		...(finalAdmission ? { auto_handoff: finalAdmission } : {}),
 	};
 	await appendJsonlIdempotent(path.join(runDir, "index.jsonl"), indexEntry, {
 		cwd,
@@ -1237,6 +1564,35 @@ interface ExistingStageArtifact {
 	path: string;
 	sha256: string;
 	createdAt: string;
+	autoHandoff?: RalplanAutoHandoffResolution;
+}
+
+function parseRalplanFinalAdmission(value: unknown): RalplanAutoHandoffResolution | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const admission = value as Record<string, unknown>;
+	if (
+		!RALPLAN_AUTO_HANDOFF_TARGETS.has(admission.configuredTarget as RalplanAutoHandoffTarget) ||
+		!RALPLAN_AUTO_HANDOFF_TARGETS.has(admission.effectiveTarget as RalplanAutoHandoffTarget) ||
+		(typeof admission.degradationReason !== "string" && admission.degradationReason !== null) ||
+		typeof admission.source !== "string"
+	) {
+		return undefined;
+	}
+	return {
+		configuredTarget: admission.configuredTarget as RalplanAutoHandoffTarget,
+		effectiveTarget: admission.effectiveTarget as RalplanAutoHandoffTarget,
+		degradationReason: typeof admission.degradationReason === "string" ? admission.degradationReason : null,
+		source: admission.source,
+	};
+}
+
+function unavailableRalplanFinalAdmission(): RalplanAutoHandoffResolution {
+	return {
+		configuredTarget: "off",
+		effectiveTarget: "off",
+		degradationReason: "admission_unavailable",
+		source: "ledger",
+	};
 }
 
 /**
@@ -1269,6 +1625,7 @@ function findExistingStageArtifact(
 			path: record.path,
 			sha256: record.sha256,
 			createdAt: typeof record.created_at === "string" ? record.created_at : "",
+			...(stage === "final" ? { autoHandoff: parseRalplanFinalAdmission(record.auto_handoff) } : {}),
 		};
 	}
 	return match;
@@ -1354,6 +1711,7 @@ async function repairMissingStageArtifactLedger(
 	cwd: string,
 	resolved: Pick<ResolvedArtifactArgs, "sessionId" | "runId" | "stage" | "stageN">,
 	onDisk: OnDiskStageArtifact,
+	finalAdmission?: RalplanAutoHandoffResolution,
 ): Promise<ExistingStageArtifact> {
 	const createdAt = new Date().toISOString();
 	const indexEntry = {
@@ -1362,6 +1720,7 @@ async function repairMissingStageArtifactLedger(
 		path: onDisk.path,
 		created_at: createdAt,
 		sha256: onDisk.sha256,
+		...(finalAdmission ? { auto_handoff: finalAdmission } : {}),
 	};
 	const result = await appendJsonlIdempotent(
 		path.join(sessionPlansDir(cwd, resolved.sessionId), "ralplan", resolved.runId, "index.jsonl"),
@@ -1386,10 +1745,18 @@ async function repairMissingStageArtifactLedger(
 				path: record.path,
 				sha256: record.sha256,
 				createdAt: typeof record.created_at === "string" ? record.created_at : createdAt,
+				...(resolved.stage === "final"
+					? { autoHandoff: parseRalplanFinalAdmission(record.auto_handoff) ?? unavailableRalplanFinalAdmission() }
+					: {}),
 			};
 		}
 	}
-	return { path: onDisk.path, sha256: onDisk.sha256, createdAt };
+	return {
+		path: onDisk.path,
+		sha256: onDisk.sha256,
+		createdAt,
+		...(resolved.stage === "final" ? { autoHandoff: finalAdmission ?? unavailableRalplanFinalAdmission() } : {}),
+	};
 }
 
 /**
@@ -1463,12 +1830,18 @@ async function buildRalplanHud(options: {
 	let architectPasses: number | undefined;
 	let criticPasses: number | undefined;
 	let verdict: string | undefined;
+	let autoHandoff: RalplanAutoHandoffResolution | undefined;
+	let planningStuck = false;
 	if (options.runId && options.sessionId) {
-		const [rows, lastReviewVerdict] = await Promise.all([
+		const [rows, lastReviewVerdict, persistedAutoHandoff, persistedPlanningStuck] = await Promise.all([
 			readRalplanIndexRows(options.cwd, options.sessionId, options.runId),
 			readRalplanLastReviewVerdict(options.cwd, options.sessionId),
+			readRalplanFinalAdmission(options.cwd, options.sessionId, options.runId),
+			readRalplanPlanningStuck(options.cwd, options.sessionId, options.runId),
 		]);
 		verdict = lastReviewVerdict;
+		autoHandoff = persistedAutoHandoff;
+		planningStuck = persistedPlanningStuck;
 		if (rows.length > 0) {
 			const summary = summarizeRalplanIndex(rows);
 			iterationFromIndex = summary.iteration;
@@ -1486,12 +1859,62 @@ async function buildRalplanHud(options: {
 		criticPasses,
 		reviewPassBudget: options.reviewPassBudget,
 		verdict,
+		autoHandoff,
+		planningStuck,
 		pendingApproval: options.pendingApproval,
 		latestSummary: options.latestSummary,
 		updatedAt: new Date().toISOString(),
 	});
 }
 
+/**
+ * Disposition-stage artifacts are machine-checkable JSON. Validate, enforce
+ * authoritative same-pass provenance against the run index, and re-serialize to
+ * canonical form so join gates and re-review share one shape (#2902 / #3013).
+ */
+function normalizeDispositionArtifact(raw: string, expectedStageN: number, indexText: string | undefined): string {
+	try {
+		const indexedArtifacts = buildIndexedReviewArtifacts(indexText);
+		const doc = parseReviewConflictDocument(raw, {
+			expectedStageN,
+			indexedArtifacts,
+		});
+		return serializeReviewConflictDocument(doc);
+	} catch (error) {
+		throw new RalplanCommandError(
+			2,
+			`invalid ralplan disposition artifact: ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
+}
+
+/** Parse complete path/sha256 rows from a run `index.jsonl` snapshot for provenance. */
+function buildIndexedReviewArtifacts(indexText: string | undefined): Map<string, IndexedReviewArtifact> {
+	const map = new Map<string, IndexedReviewArtifact>();
+	if (indexText === undefined) return map;
+	for (const line of indexText.split(/\r?\n/)) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		let row: unknown;
+		try {
+			row = JSON.parse(trimmed);
+		} catch {
+			continue;
+		}
+		if (!row || typeof row !== "object" || Array.isArray(row)) continue;
+		const record = row as Record<string, unknown>;
+		if (typeof record.stage !== "string") continue;
+		if (typeof record.stage_n !== "number" || !Number.isInteger(record.stage_n)) continue;
+		if (typeof record.path !== "string" || typeof record.sha256 !== "string") continue;
+		// Last complete row for an identity wins (matches findExistingStageArtifact).
+		map.set(reviewArtifactIndexKey(record.stage, record.stage_n), {
+			path: record.path,
+			sha256: record.sha256,
+		});
+	}
+	return map;
+}
+
 async function handleArtifactWrite(args: readonly string[], cwd: string): Promise<RalplanCommandResult> {
 	const resolved = await resolveArtifactArgs(args, cwd);
 	const persistedRoleState = parsePersistedRoleStateArgs(args, resolved.stage);
@@ -1514,14 +1937,20 @@ async function handleArtifactWrite(args: readonly string[], cwd: string): Promis
 			// Non-file / missing path is inline content; resolveArtifactContent already handled it.
 		}
 	}
-	const content = resolved.artifact.endsWith("\n") ? resolved.artifact : `${resolved.artifact}\n`;
-	const sha256 = createHash("sha256").update(content).digest("hex");
 
-	// Read the ledger once before persistence. The dedupe guard and both gates
-	// consume this same snapshot so no additional ledger read can slip between gate
-	// evaluation and persistence.
+	// Read the ledger once before persistence. The dedupe guard, both gates, and
+	// disposition provenance consume this same snapshot so no additional ledger
+	// read can slip between gate evaluation and persistence.
 	const indexLoad = await loadRalplanIndexForCap(cwd, resolved.sessionId, resolved.runId);
 
+	// Disposition stage: fail-closed parse/normalize with authoritative receipts (#2902).
+	const normalizedArtifact =
+		resolved.stage === "disposition"
+			? normalizeDispositionArtifact(resolved.artifact, resolved.stageN, indexLoad.rawText)
+			: resolved.artifact;
+	const content = normalizedArtifact.endsWith("\n") ? normalizedArtifact : `${normalizedArtifact}\n`;
+	const sha256 = createHash("sha256").update(content).digest("hex");
+
 	// Duplicate-write guard: a second `--write` for the same (stage, stage_n) must not
 	// silently clobber the artifact or append a duplicate ledger row. Classify before any
 	// state mutation so a conflict never regresses run-state phase.
@@ -1534,7 +1963,7 @@ async function handleArtifactWrite(args: readonly string[], cwd: string): Promis
 			);
 		}
 		if (resolved.stage === "final") await ensureFinalPendingApproval(cwd, resolved, existingArtifact);
-		return buildDeduplicatedResult(resolved, existingArtifact, sha256, cwd, repositoryBinding);
+		return await buildDeduplicatedResult(resolved, existingArtifact, sha256, cwd, repositoryBinding);
 	}
 
 	// `persistArtifact` writes the artifact before its ledger row. If a process crashed
@@ -1549,7 +1978,12 @@ async function handleArtifactWrite(args: readonly string[], cwd: string): Promis
 			);
 		}
 		if (resolved.stage === "final") await ensureFinalPendingApproval(cwd, resolved, onDiskArtifact);
-		const repairedArtifact = await repairMissingStageArtifactLedger(cwd, resolved, onDiskArtifact);
+		const repairedArtifact = await repairMissingStageArtifactLedger(
+			cwd,
+			resolved,
+			onDiskArtifact,
+			resolved.stage === "final" ? unavailableRalplanFinalAdmission() : undefined,
+		);
 		let appliedPersistedRoleState: PersistedRoleStateUpdate | undefined;
 		if (
 			persistedRoleState &&
@@ -1561,7 +1995,7 @@ async function handleArtifactWrite(args: readonly string[], cwd: string): Promis
 		if (laneVerdict && (await applyLaneVerdictUpdate(cwd, resolved.sessionId, laneVerdict, resolved.runId))) {
 			appliedLaneVerdict = laneVerdict;
 		}
-		return buildDeduplicatedResult(
+		return await buildDeduplicatedResult(
 			resolved,
 			repairedArtifact,
 			sha256,
@@ -1595,6 +2029,7 @@ async function handleArtifactWrite(args: readonly string[], cwd: string): Promis
 		iterationFloor: onDiskOpeners,
 	});
 	if (!capDecision.allowed) {
+		await recordRalplanPlanningStuck(cwd, resolved.sessionId, resolved.runId, capDecision.reason);
 		return buildPlanningStuckResult({
 			json: resolved.json,
 			stage: resolved.stage,
@@ -1611,6 +2046,7 @@ async function handleArtifactWrite(args: readonly string[], cwd: string): Promis
 		onDiskLaneCounts: onDiskLaneArtifacts,
 	});
 	if (!laneBudgetDecision.allowed) {
+		await recordRalplanPlanningStuck(cwd, resolved.sessionId, resolved.runId, laneBudgetDecision.reason);
 		return buildLaneBudgetStuckResult({
 			json: resolved.json,
 			stage: resolved.stage,
@@ -1621,15 +2057,27 @@ async function handleArtifactWrite(args: readonly string[], cwd: string): Promis
 		});
 	}
 
+	let autoHandoff: RalplanAutoHandoffResolution | undefined;
+	if (resolved.stage === "final") {
+		// Resolve and validate the configured admission before any final artifact or
+		// state write. The ledger row below is the durable receipt for deduplicated
+		// retries; state is only a current-session projection.
+		autoHandoff = await resolveRalplanAutoHandoff(cwd, {
+			planningStuck: await readRalplanPlanningStuck(cwd, resolved.sessionId, resolved.runId),
+		});
+	}
 	// Keep run-state `current_phase` coherent with the stage being persisted.
 	await persistActiveRunId(cwd, resolved.sessionId, resolved.runId, resolved.stage);
-	const persisted = await persistArtifact(resolved, cwd, content, sha256);
+	const persisted = await persistArtifact(resolved, cwd, content, sha256, autoHandoff);
 	if (persistedRoleState) {
 		await applyPersistedRoleStateUpdate(cwd, resolved.sessionId, persistedRoleState);
 	}
 	if (laneVerdict) {
 		await applyLaneVerdictUpdate(cwd, resolved.sessionId, laneVerdict);
 	}
+	if (autoHandoff) {
+		await persistRalplanFinalAdmission(cwd, resolved.sessionId, resolved.runId, autoHandoff);
+	}
 	await writeSessionActivityMarker(cwd, resolved.sessionId, { writer: "ralplan-runtime", path: persisted.path });
 	await syncRalplanHud({
 		cwd,
@@ -1651,6 +2099,7 @@ async function handleArtifactWrite(args: readonly string[], cwd: string): Promis
 			: undefined;
 
 	const payload: Record<string, unknown> = {
+		session_id: resolved.sessionId,
 		run_id: persisted.runId,
 		path: persisted.path,
 		stage: persisted.stage,
@@ -1663,6 +2112,7 @@ async function handleArtifactWrite(args: readonly string[], cwd: string): Promis
 	if (persistedRoleState) payload[`${persistedRoleState.role}_state`] = persistedRoleStatePayload(persistedRoleState);
 	if (reviewBudgetWarning) payload.review_budget_warning = reviewBudgetWarning;
 	if (laneVerdict) payload.lane_verdict = { lane: laneVerdict.lane, verdict: laneVerdict.verdict };
+	if (autoHandoff) payload.auto_handoff = autoHandoff;
 
 	const stdout = resolved.json
 		? `${JSON.stringify(payload, null, 2)}\n`
@@ -1675,7 +2125,14 @@ async function handleArtifactWrite(args: readonly string[], cwd: string): Promis
  * do not rewrite artifacts, append rows, or churn run state; a crash-gap repair may
  * complete riding persisted role/lane metadata before returning this receipt.
  */
-function buildDeduplicatedResult(
+function applyRalplanPlanningStuckOverride(
+	admission: RalplanAutoHandoffResolution,
+	planningStuck: boolean,
+): RalplanAutoHandoffResolution {
+	return planningStuck ? { ...admission, effectiveTarget: "off", degradationReason: "planning_stuck" } : admission;
+}
+
+async function buildDeduplicatedResult(
 	resolved: ResolvedArtifactArgs,
 	existing: ExistingStageArtifact,
 	sha256: string,
@@ -1683,8 +2140,9 @@ function buildDeduplicatedResult(
 	repositoryBinding: RepositoryBinding,
 	laneVerdict?: LaneVerdictUpdate,
 	persistedRoleState?: PersistedRoleStateUpdate,
-): RalplanCommandResult {
+): Promise<RalplanCommandResult> {
 	const payload: Record<string, unknown> = {
+		session_id: resolved.sessionId,
 		run_id: resolved.runId,
 		path: existing.path,
 		stage: resolved.stage,
@@ -1705,6 +2163,11 @@ function buildDeduplicatedResult(
 			resolved.runId,
 			"pending-approval.md",
 		);
+		const planningStuck = await readRalplanPlanningStuck(cwd, resolved.sessionId, resolved.runId);
+		payload.auto_handoff = applyRalplanPlanningStuckOverride(
+			existing.autoHandoff ?? unavailableRalplanFinalAdmission(),
+			planningStuck,
+		);
 	}
 	const stdout = resolved.json
 		? `${JSON.stringify(payload, null, 2)}\n`
@@ -1851,6 +2314,7 @@ async function handleConsensusHandoff(args: readonly string[], cwd: string): Pro
 	});
 
 	const summary = {
+		session_id: resolved.sessionId,
 		skill: "ralplan",
 		mode,
 		state_path: statePath,