@gajae-code/coding-agent 0.12.0 → 0.12.1

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";
@@ -22,7 +23,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,6 +34,7 @@ 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";
 
@@ -74,6 +76,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 +403,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 +884,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 +1217,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 +1426,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 +1479,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 +1503,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 +1548,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 +1609,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 +1695,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 +1704,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 +1729,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 +1814,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,6 +1843,8 @@ async function buildRalplanHud(options: {
 		criticPasses,
 		reviewPassBudget: options.reviewPassBudget,
 		verdict,
+		autoHandoff,
+		planningStuck,
 		pendingApproval: options.pendingApproval,
 		latestSummary: options.latestSummary,
 		updatedAt: new Date().toISOString(),
@@ -1534,7 +1893,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 +1908,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 +1925,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 +1959,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 +1976,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 +1987,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 +2029,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 +2042,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 +2055,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 +2070,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 +2093,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 +2244,7 @@ async function handleConsensusHandoff(args: readonly string[], cwd: string): Pro
 	});
 
 	const summary = {
+		session_id: resolved.sessionId,
 		skill: "ralplan",
 		mode,
 		state_path: statePath,

package/src/gjc-runtime/team-launch.ts

@@ -36,6 +36,7 @@ export function buildWorkerCommand(
 	worker: GjcTeamWorker,
 	platform: NodeJS.Platform = process.platform,
 	promptOverride?: string,
+	env: NodeJS.ProcessEnv = process.env,
 ): string {
 	const quote = platform === "win32" ? powershellQuote : shellQuote;
 	const envAssignment = (key: string, value: string): string =>
@@ -74,6 +75,13 @@ export function buildWorkerCommand(
 			"GJC_TEAM_WORKER_MEMORY_GUARD_PATH",
 			workerMemoryGuardLedgerPath(path.join(config.state_root, config.team_name), worker.id),
 		),
+		// The worker derives its heartbeat cadence from the same window the leader
+		// enforces. tmux panes do not inherit the launching shell's environment, so
+		// without this a tightened window would leave workers publishing on the
+		// default cadence and reported stale while they are working.
+		...(env.GJC_TEAM_HEARTBEAT_STALE_MS?.trim()
+			? [envAssignment("GJC_TEAM_HEARTBEAT_STALE_MS", env.GJC_TEAM_HEARTBEAT_STALE_MS.trim())]
+			: []),
 	];
 	const joined = envLines.join(" ");
 	const clearInheritedSession = config.gjc_session_id