@gajae-code/coding-agent 0.11.10 → 0.11.11

package/src/extensibility/extensions/runner.ts

@@ -201,6 +201,7 @@ export class ExtensionRunner {
 	#getAllToolsFn: ExtensionContext["getAllTools"] = () => [];
 	#getResolveToolFn: ExtensionContext["resolveTool"] = () => undefined;
 	#cycleModelFn: ExtensionContextActions["cycleModel"] = undefined;
+	#setModelProfileFn: ExtensionContextActions["setModelProfile"] = undefined;
 	#cycleThinkingLevelFn: ExtensionContextActions["cycleThinkingLevel"] = undefined;
 	#setQueueModeFn: ExtensionContextActions["setQueueMode"] = undefined;
 	#getSkillStateFn: ExtensionContextActions["getSkillState"] = undefined;
@@ -313,6 +314,7 @@ export class ExtensionRunner {
 		this.#getAllToolsFn = contextActions.getAllTools ?? (() => []);
 		this.#getResolveToolFn = contextActions.resolveTool ?? (() => undefined);
 		this.#cycleModelFn = contextActions.cycleModel;
+		this.#setModelProfileFn = contextActions.setModelProfile;
 		this.#cycleThinkingLevelFn = contextActions.cycleThinkingLevel;
 		this.#setQueueModeFn = contextActions.setQueueMode;
 		this.#getSkillStateFn = contextActions.getSkillState;
@@ -562,6 +564,7 @@ export class ExtensionRunner {
 			getAllTools: () => this.#getAllToolsFn(),
 			resolveTool: name => this.#getResolveToolFn(name),
 			cycleModel: async () => await this.#cycleModelFn?.(),
+			setModelProfile: async name => (await this.#setModelProfileFn?.(name)) ?? false,
 			cycleThinkingLevel: () => this.#cycleThinkingLevelFn?.(),
 			setQueueMode: (kind, mode) => this.#setQueueModeFn?.(kind, mode) ?? false,
 			invokeSkill: async (name, args) => await this.#invokeSkillFn?.(name, args),
@@ -581,6 +584,7 @@ export class ExtensionRunner {
 			setSdkPermissionProvider: provider => this.#setSdkPermissionProviderFn?.(provider),
 			sdkBindings: () => [
 				...(this.#cycleModelFn ? ["cycleModel"] : []),
+				...(this.#setModelProfileFn ? ["setModelProfile"] : []),
 				...(this.#cycleThinkingLevelFn ? ["cycleThinkingLevel"] : []),
 				...(this.#setQueueModeFn ? ["setQueueMode"] : []),
 				...(this.#getSkillStateFn ? ["getSkillState"] : []),

package/src/extensibility/extensions/types.ts

@@ -290,6 +290,18 @@ export interface ExtensionTranscriptEntry {
 	textSummary: string;
 	ts: string;
 	body?: string;
+	/**
+	 * Durable, image-free message blocks used by rich transcript consumers such
+	 * as ACP replay. Binary image payloads intentionally remain unavailable.
+	 */
+	content?: Array<
+		| { type: "text"; text: string }
+		| { type: "thinking"; thinking: string }
+		| { type: "toolCall"; id: string; name: string; arguments: unknown }
+	>;
+	toolCallId?: string;
+	toolName?: string;
+	isError?: boolean;
 }
 
 export interface ContextUsage {
@@ -361,6 +373,7 @@ export interface ExtensionContext {
 	resolveTool(name: string): Pick<Tool, "safeSummary" | "safeSummaryFields"> | undefined;
 	/** Session control seams used by the SDK host. */
 	cycleModel(): Promise<{ model: Model; thinkingLevel: ThinkingLevel | undefined } | undefined>;
+	setModelProfile?(name: string): Promise<boolean>;
 	cycleThinkingLevel(): ThinkingLevel | undefined;
 	setQueueMode(kind: "steering" | "follow_up" | "interrupt", mode: unknown): boolean;
 	getSkillState(): unknown;
@@ -1429,6 +1442,7 @@ export interface ExtensionContextActions {
 	clearContext?: () => Promise<boolean>;
 	/** Session control and query seams exposed to the per-session SDK host. */
 	cycleModel?: () => Promise<{ model: Model; thinkingLevel: ThinkingLevel | undefined } | undefined>;
+	setModelProfile?: (name: string) => Promise<boolean>;
 	cycleThinkingLevel?: () => ThinkingLevel | undefined;
 	setQueueMode?: (kind: "steering" | "follow_up" | "interrupt", mode: unknown) => boolean;
 	getSkillState?: () => unknown;

package/src/gjc-runtime/deep-interview-ambiguity.ts

@@ -207,8 +207,22 @@ export function deriveAmbiguityMilestone(
 
 export function scoreToUnits(score: number): number {
 	if (!Number.isFinite(score) || score < 0 || score > 1) throw new RangeError("score must be finite in [0, 1]");
-	const units = score * 10_000;
-	if (!Number.isSafeInteger(units)) throw new RangeError("score must be expressed in integral 1e-4 units");
+	/**
+	 * Scores carry at most four decimal places, but `score * 10_000` misses the
+	 * integer grid for ordinary values: `0.69 * 10_000` is `6900.000000000001` and
+	 * `0.07 * 10_000` is `700.0000000000001`. Ambiguity is fed straight back in as
+	 * `units / 10_000`, so testing the float product rejected most real scores.
+	 *
+	 * Decide from the shortest round-trip decimal instead. That is exact: every
+	 * genuine 1e-4 value has at most four fraction digits, while off-grid
+	 * precision keeps its digits (`0.00005`, `0.05000000000000001`) and is
+	 * rejected. An epsilon on the product cannot separate those two cases -- both
+	 * residuals are ~1e-13. The `[0, 1]` guard plus the four-digit cap already
+	 * bound the result to an integer in `[0, 10_000]`.
+	 */
+	const decimal = /^(\d+)(?:\.(\d{1,4}))?$/.exec(String(score));
+	if (!decimal) throw new RangeError("score must be expressed in integral 1e-4 units");
+	const units = Number(decimal[1]) * 10_000 + Number((decimal[2] ?? "").padEnd(4, "0"));
 	return units;
 }
 

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

@@ -937,8 +937,20 @@ function canonicalJsonValue(value: unknown): unknown {
 		if (value === undefined) throw new TypeError("canonical JSON rejects undefined");
 		return value;
 	}
+	/**
+	 * Object properties set to `undefined` are dropped, matching `JSON.stringify`:
+	 * an omitted optional key and a present-but-undefined one must digest
+	 * identically. Decoded requests routinely materialize every optional key (an
+	 * omitted `targeting` becomes `targeting: undefined`), so rejecting them here
+	 * would make every request carrying an absent optional field unserializable.
+	 * Array elements and the top-level value stay strict: `undefined` there is a
+	 * real encoding bug, not an absent field.
+	 */
 	const output: Record<string, unknown> = {};
-	for (const key of Object.keys(value).sort()) output[key] = canonicalJsonValue(value[key]);
+	for (const key of Object.keys(value).sort()) {
+		if (value[key] === undefined) continue;
+		output[key] = canonicalJsonValue(value[key]);
+	}
 	return output;
 }
 
@@ -1004,7 +1016,7 @@ export function deepInterviewAnswerIdentityEqual(
 			component: a.component ?? null,
 			dimension: a.dimension ?? null,
 			question_text: a.question_text ?? null,
-			question_hash: a.question_hash,
+			question_hash: a.question_hash ?? null,
 			selected_options: a.selected_options ?? [],
 			custom_input: a.custom_input ?? null,
 		}) ===
@@ -1016,7 +1028,7 @@ export function deepInterviewAnswerIdentityEqual(
 			component: b.component ?? null,
 			dimension: b.dimension ?? null,
 			question_text: b.question_text ?? null,
-			question_hash: b.question_hash,
+			question_hash: b.question_hash ?? null,
 			selected_options: b.selected_options ?? [],
 			custom_input: b.custom_input ?? null,
 		})
@@ -1061,10 +1073,20 @@ export function applyDeepInterviewRoundResultV1(
 		typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1;
 	if (!dimensions.every(dimension => finiteScore(result.global_scores[dimension])))
 		throw new Error("DI_STATE_SCHEMA_INVALID");
+	/**
+	 * Rounds must be scored in order, but the Round 0 topology gate is not a
+	 * scorable round: the recorder persists it as an `answered` shell to bind the
+	 * locked intent contract, `apply-round-result` rejects `--round 0`, and
+	 * `validateDeepInterviewV1Envelope` refuses to persist a round-0 record that
+	 * is anything other than an answered, score-less shell. Counting it here would
+	 * deadlock every later round forever, so the gate is excluded by identity
+	 * rather than by an ordering range.
+	 */
 	if (
 		rounds.some(
 			round =>
 				round.lifecycle !== "scored" &&
+				round.round !== 0 &&
 				(round.round < shell.round || (round.round === shell.round && round.round_key < shell.round_key)),
 		)
 	)

package/src/gjc-runtime/linux-proc.ts

@@ -1,26 +1,30 @@
 /**
- * Shared helpers for reading Linux `/proc/<pid>/stat` process start time.
+ * Shared helpers for reading Linux `/proc/<pid>/stat` process identity fields.
  *
  * The `comm` field (field 2, wrapped in parentheses) may itself contain spaces
  * and parentheses, so the only robust anchor is the *last* `)` in the stat
  * string. Field 22 (the process start time in clock ticks since boot) is the
- * 20th whitespace-separated token after that closing paren (index 19).
- *
- * Every caller previously parsed this format independently, with subtly
- * different failure handling. This module fails closed: any malformed input
- * (missing `)`, non-numeric field 22, unreadable `/proc` file, non-Linux
- * platform) yields `null` rather than an inconsistent sentinel.
+ * 20th whitespace-separated token after that closing paren (index 19). Field 7
+ * (`tty_nr`) is the 5th token after the closing paren (index 4).
  */
 
 import * as nodeFsSync from "node:fs";
 import * as nodeFs from "node:fs/promises";
 
-/**
- * Parse field 22 (process start time, in clock ticks since boot) from one
- * `/proc/<pid>/stat` record. Returns the raw numeric token, or `null` when the
- * record shape is malformed or field 22 is absent/non-numeric.
- */
-export function parseLinuxProcStartTime(stat: string | null | undefined): string | null {
+export interface LinuxProcStatIdentity {
+	startTime: string;
+	ttyDevice: string;
+}
+
+export type LinuxProcPidProbeResult =
+	| ({ kind: "live" } & LinuxProcStatIdentity)
+	| { kind: "absent" }
+	| {
+			kind: "unverifiable";
+			reason: "unsupported_platform" | "invalid_pid" | "permission_denied" | "read_error" | "malformed_stat";
+	  };
+
+function parseLinuxProcIdentity(stat: string | null | undefined): LinuxProcStatIdentity | null {
 	if (!stat || stat.includes("\0") || stat.includes("\r")) return null;
 	const record = stat.endsWith("\n") ? stat.slice(0, -1) : stat;
 	if (!record || record.includes("\n")) return null;
@@ -32,40 +36,70 @@ export function parseLinuxProcStartTime(stat: string | null | undefined): string
 	const suffix = record.slice(close + 1);
 	if (!/^[ \t]+/.test(suffix)) return null;
 	const fields = suffix.trim().split(/[ \t]+/);
-	if (fields.length < 20 || !/^[RSDTtXZPI]$/.test(fields[0])) return null;
-
+	if (fields.length < 20 || !/^[A-Za-z]$/.test(fields[0])) return null;
+	const ttyDevice = fields[4];
 	const startTime = fields[19];
-	return /^\d+$/.test(startTime) ? startTime : null;
+	if (!ttyDevice || !/^-?\d+$/.test(ttyDevice) || !/^\d+$/.test(startTime)) return null;
+	return { startTime, ttyDevice };
 }
 
-/**
- * Read `/proc/<pid>/stat` synchronously and return the parsed start time.
- * Returns `null` on non-Linux platforms, unreadable files, or malformed input.
- */
-export function readLinuxProcStartTimeSync(pid: number): string | null {
-	if (process.platform !== "linux") return null;
-	if (!Number.isSafeInteger(pid) || pid <= 0) return null;
+function classifyProcReadError(error: unknown): Extract<LinuxProcPidProbeResult, { kind: "absent" | "unverifiable" }> {
+	const code = (error as NodeJS.ErrnoException | undefined)?.code;
+	if (code === "ENOENT" || code === "ESRCH") return { kind: "absent" };
+	if (code === "EACCES" || code === "EPERM") return { kind: "unverifiable", reason: "permission_denied" };
+	return { kind: "unverifiable", reason: "read_error" };
+}
+
+/** Parse field 22 (start time) from a `/proc/<pid>/stat` record. */
+export function parseLinuxProcStartTime(stat: string | null | undefined): string | null {
+	return parseLinuxProcIdentity(stat)?.startTime ?? null;
+}
+
+/** Parse field 7 (`tty_nr`) from a `/proc/<pid>/stat` record. */
+export function parseLinuxProcTtyDevice(stat: string | null | undefined): string | null {
+	return parseLinuxProcIdentity(stat)?.ttyDevice ?? null;
+}
+
+export function probeLinuxProcPidSync(pid: number): LinuxProcPidProbeResult {
+	if (!Number.isSafeInteger(pid) || pid <= 0) return { kind: "unverifiable", reason: "invalid_pid" };
+	if (process.platform !== "linux") return { kind: "unverifiable", reason: "unsupported_platform" };
 	let stat: string;
 	try {
 		stat = nodeFsSync.readFileSync(`/proc/${pid}/stat`, "utf8");
-	} catch {
-		return null;
+	} catch (error) {
+		return classifyProcReadError(error);
 	}
-	return parseLinuxProcStartTime(stat);
+	const identity = parseLinuxProcIdentity(stat);
+	return identity ? { kind: "live", ...identity } : { kind: "unverifiable", reason: "malformed_stat" };
 }
 
-/**
- * Read `/proc/<pid>/stat` asynchronously and return the parsed start time.
- * Returns `null` on non-Linux platforms, unreadable files, or malformed input.
- */
-export async function readLinuxProcStartTime(pid: number): Promise<string | null> {
-	if (process.platform !== "linux") return null;
-	if (!Number.isSafeInteger(pid) || pid <= 0) return null;
+export async function probeLinuxProcPid(pid: number): Promise<LinuxProcPidProbeResult> {
+	if (!Number.isSafeInteger(pid) || pid <= 0) return { kind: "unverifiable", reason: "invalid_pid" };
+	if (process.platform !== "linux") return { kind: "unverifiable", reason: "unsupported_platform" };
 	let stat: string;
 	try {
 		stat = await nodeFs.readFile(`/proc/${pid}/stat`, "utf8");
-	} catch {
-		return null;
+	} catch (error) {
+		return classifyProcReadError(error);
 	}
-	return parseLinuxProcStartTime(stat);
+	const identity = parseLinuxProcIdentity(stat);
+	return identity ? { kind: "live", ...identity } : { kind: "unverifiable", reason: "malformed_stat" };
+}
+
+/**
+ * Read `/proc/<pid>/stat` synchronously and return the parsed start time.
+ * Returns `null` when the probe is absent or unverifiable.
+ */
+export function readLinuxProcStartTimeSync(pid: number): string | null {
+	const probe = probeLinuxProcPidSync(pid);
+	return probe.kind === "live" ? probe.startTime : null;
+}
+
+/**
+ * Read `/proc/<pid>/stat` asynchronously and return the parsed start time.
+ * Returns `null` when the probe is absent or unverifiable.
+ */
+export async function readLinuxProcStartTime(pid: number): Promise<string | null> {
+	const probe = await probeLinuxProcPid(pid);
+	return probe.kind === "live" ? probe.startTime : null;
 }

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

@@ -1,5 +1,6 @@
 import { createHash, randomBytes } from "node:crypto";
 import * as fs from "node:fs/promises";
+import * as os from "node:os";
 import * as path from "node:path";
 import { syncSkillActiveState } from "../skill-state/active-state";
 import { buildRalplanHudSummary } from "../skill-state/workflow-hud";
@@ -21,7 +22,7 @@ import {
 	RepositoryBindingError,
 } from "./repository-binding";
 import { GJC_RALPLAN_ARTIFACT_ENV, isRestrictedRoleAgentBash } from "./restricted-role-agent-bash";
-import { modeStatePath, sessionPlansDir } from "./session-layout";
+import { gjcRoot, modeStatePath, sessionPlansDir } from "./session-layout";
 import { resolveGjcSessionForWrite, writeSessionActivityMarker } from "./session-resolution";
 import { migrateWorkflowState } from "./state-migrations";
 import { runNativeStateCommand } from "./state-runtime";
@@ -63,6 +64,231 @@ export interface RalplanCommandResult {
 
 const KNOWN_STAGES = ["planner", "architect", "critic", "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;
+/** Inclusive upper bound for `gjc.ralplan.maxIterations` settings overrides. */
+export const RALPLAN_MAX_ITERATIONS_LIMIT = 20;
+/** Operator-visible stuck signal for headless/CI orchestration (#3165). */
+export const PLANNING_STUCK_MARKER = "PLANNING-STUCK";
+
+const RALPLAN_ITERATION_OPENER_STAGES = new Set<RalplanStage>(["planner", "revision"]);
+
+export type RalplanIterationCapDecision =
+	| {
+			allowed: true;
+			currentIterations: number;
+			projectedIterations: number;
+			maxIterations: number;
+	  }
+	| {
+			allowed: false;
+			currentIterations: number;
+			projectedIterations: number;
+			maxIterations: number;
+			reason: string;
+	  };
+
+/**
+ * Pure consensus-iteration budget gate (#3165).
+ *
+ * A `planner` or `revision` write opens a new iteration (same definition as
+ * `summarizeRalplanIndex`). Other stages never open iterations and are always
+ * allowed by this gate — including `final` after the cap is already reached.
+ *
+ * `iterationFloor` raises the observed opener count when on-disk evidence or a
+ * recovered ledger is higher than the parsed index (fail-closed vs wipe/truncate).
+ */
+export function evaluateRalplanIterationCap(input: {
+	rows: readonly RalplanIndexRow[];
+	stage: string;
+	maxIterations?: number;
+	/** Minimum opener count (e.g. on-disk stage-*-{planner,revision}.md). */
+	iterationFloor?: number;
+}): RalplanIterationCapDecision {
+	const maxIterations =
+		typeof input.maxIterations === "number" &&
+		Number.isInteger(input.maxIterations) &&
+		input.maxIterations >= 1 &&
+		input.maxIterations <= RALPLAN_MAX_ITERATIONS_LIMIT
+			? input.maxIterations
+			: RALPLAN_DEFAULT_MAX_ITERATIONS;
+	const fromIndex = summarizeRalplanIndex(input.rows).iteration;
+	const floor =
+		typeof input.iterationFloor === "number" && Number.isInteger(input.iterationFloor) && input.iterationFloor > 0
+			? input.iterationFloor
+			: 0;
+	const currentIterations = Math.max(fromIndex, floor);
+	if (!RALPLAN_ITERATION_OPENER_STAGES.has(input.stage as RalplanStage)) {
+		return {
+			allowed: true,
+			currentIterations,
+			projectedIterations: currentIterations,
+			maxIterations,
+		};
+	}
+	const projectedIterations = currentIterations + 1;
+	if (projectedIterations > maxIterations) {
+		const ledgerNote = floor > fromIndex ? ` (ledger under-count: index=${fromIndex}, on-disk openers=${floor})` : "";
+		return {
+			allowed: false,
+			currentIterations,
+			projectedIterations,
+			maxIterations,
+			reason:
+				`ralplan consensus iteration cap exceeded: opening ${input.stage} would start ` +
+				`iteration ${projectedIterations} (max ${maxIterations})${ledgerNote}`,
+		};
+	}
+	return {
+		allowed: true,
+		currentIterations,
+		projectedIterations,
+		maxIterations,
+	};
+}
+
+/** Filename pattern for persisted planner/revision stage artifacts. */
+const OPENER_ARTIFACT_RE = /^stage-\d{2,}-(planner|revision)\.md$/;
+
+/**
+ * Count on-disk planner/revision stage artifacts for a run. Used as a floor when
+ * `index.jsonl` is missing, empty, truncated, or otherwise under-counts openers.
+ */
+export async function countRalplanOnDiskOpeners(cwd: string, sessionId: string, runId: string): Promise<number> {
+	const runDir = path.join(sessionPlansDir(cwd, sessionId), "ralplan", runId);
+	try {
+		const entries = await fs.readdir(runDir);
+		let count = 0;
+		for (const name of entries) {
+			if (OPENER_ARTIFACT_RE.test(name)) count += 1;
+		}
+		return count;
+	} catch {
+		return 0;
+	}
+}
+
+/**
+ * Load index rows for cap enforcement. Unlike HUD reads, returns structural
+ * signals so callers can fail closed when the ledger is empty/malformed while
+ * opener artifacts already exist on disk.
+ */
+export async function loadRalplanIndexForCap(
+	cwd: string,
+	sessionId: string,
+	runId: string,
+): Promise<{ rows: RalplanIndexRow[]; indexPresent: boolean; parseableLines: number; rawLineCount: number }> {
+	const indexPath = path.join(sessionPlansDir(cwd, sessionId), "ralplan", runId, "index.jsonl");
+	try {
+		const text = await fs.readFile(indexPath, "utf8");
+		const lines = text.split(/\r?\n/).filter(line => line.trim().length > 0);
+		const rows: RalplanIndexRow[] = [];
+		for (const line of lines) {
+			const row = parseRalplanIndexLine(line);
+			if (row) rows.push(row);
+		}
+		return {
+			rows,
+			indexPresent: true,
+			parseableLines: rows.length,
+			rawLineCount: lines.length,
+		};
+	} catch (error) {
+		const code =
+			error && typeof error === "object" && "code" in error ? (error as { code?: string }).code : undefined;
+		if (code === "ENOENT") {
+			return { rows: [], indexPresent: false, parseableLines: 0, rawLineCount: 0 };
+		}
+		// Unreadable index: treat as present-but-untrusted empty parse.
+		return { rows: [], indexPresent: true, parseableLines: 0, rawLineCount: 0 };
+	}
+}
+
+function parseMaxIterationsValue(value: unknown): number | null {
+	return typeof value === "number" &&
+		Number.isFinite(value) &&
+		Number.isInteger(value) &&
+		value >= 1 &&
+		value <= RALPLAN_MAX_ITERATIONS_LIMIT
+		? value
+		: null;
+}
+
+async function readSettingsMaxIterations(settingsPath: string): Promise<number | null> {
+	try {
+		const raw = await Bun.file(settingsPath).text();
+		const parsed = JSON.parse(raw) as Record<string, unknown>;
+		const flat = parseMaxIterationsValue(parsed["gjc.ralplan.maxIterations"]);
+		if (flat !== null) return flat;
+		const gjc = parsed.gjc;
+		if (gjc && typeof gjc === "object") {
+			const ralplan = (gjc as Record<string, unknown>).ralplan;
+			if (ralplan && typeof ralplan === "object") {
+				return parseMaxIterationsValue((ralplan as Record<string, unknown>).maxIterations);
+			}
+		}
+		return null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Resolve ralplan consensus iteration cap. Project `./.gjc/settings.json` overrides
+ * user settings, else default 5.
+ */
+export async function resolveRalplanMaxIterations(cwd: string): Promise<{ maxIterations: number; source: string }> {
+	const projectPath = path.join(gjcRoot(cwd), "settings.json");
+	const project = await readSettingsMaxIterations(projectPath);
+	if (project !== null) return { maxIterations: project, source: projectPath };
+	const userDir = process.env.GJC_CONFIG_DIR?.trim() || path.join(os.homedir(), ".gjc");
+	const userPath = path.join(userDir, "settings.json");
+	const user = await readSettingsMaxIterations(userPath);
+	if (user !== null) return { maxIterations: user, source: userPath };
+	return { maxIterations: RALPLAN_DEFAULT_MAX_ITERATIONS, source: "default" };
+}
+
+function buildPlanningStuckResult(input: {
+	json: boolean;
+	stage: RalplanStage;
+	stageN: number;
+	runId: string;
+	decision: Extract<RalplanIterationCapDecision, { allowed: false }>;
+	source: string;
+}): RalplanCommandResult {
+	const detail =
+		`${PLANNING_STUCK_MARKER}: ${input.decision.reason} ` +
+		`(run_id=${input.runId}, stage=${input.stage}, stage_n=${input.stageN}, source=${input.source}). ` +
+		`Stop opening planner/revision passes; escalate the best existing plan via final/pending-approval without auto-implementation.`;
+	if (input.json) {
+		return {
+			status: 3,
+			stdout: `${JSON.stringify(
+				{
+					ok: false,
+					planning_stuck: true,
+					marker: PLANNING_STUCK_MARKER,
+					run_id: input.runId,
+					stage: input.stage,
+					stage_n: input.stageN,
+					iteration: input.decision.currentIterations,
+					projected_iteration: input.decision.projectedIterations,
+					max_iterations: input.decision.maxIterations,
+					max_iterations_source: input.source,
+					reason: input.decision.reason,
+				},
+				null,
+				2,
+			)}\n`,
+			stderr: `${detail}\n`,
+		};
+	}
+	return {
+		status: 3,
+		stdout: `${PLANNING_STUCK_MARKER}\n`,
+		stderr: `${detail}\n`,
+	};
+}
 
 const KNOWN_ARCHITECT_KINDS = new Set(["openai-code"]);
 const KNOWN_CRITIC_KINDS = new Set(["openai-code"]);
@@ -738,6 +964,31 @@ async function handleArtifactWrite(args: readonly string[], cwd: string): Promis
 		return buildDeduplicatedResult(resolved, existingArtifact, sha256, cwd, repositoryBinding);
 	}
 
+	// Consensus iteration budget (#3165): refuse new planner/revision openers past the cap.
+	// Dedupe returns above so identical re-writes never stuck-signal. Non-openers (architect,
+	// critic, final, …) remain allowed so operators can escalate without auto-implementation.
+	// On-disk opener artifacts floor the count so a wiped/truncated/malformed index.jsonl cannot
+	// under-count and fail open after prior planner/revision writes.
+	const indexLoad = await loadRalplanIndexForCap(cwd, resolved.sessionId, resolved.runId);
+	const onDiskOpeners = await countRalplanOnDiskOpeners(cwd, resolved.sessionId, resolved.runId);
+	const { maxIterations, source: maxIterationsSource } = await resolveRalplanMaxIterations(cwd);
+	const capDecision = evaluateRalplanIterationCap({
+		rows: indexLoad.rows,
+		stage: resolved.stage,
+		maxIterations,
+		iterationFloor: onDiskOpeners,
+	});
+	if (!capDecision.allowed) {
+		return buildPlanningStuckResult({
+			json: resolved.json,
+			stage: resolved.stage,
+			stageN: resolved.stageN,
+			runId: resolved.runId,
+			decision: capDecision,
+			source: maxIterationsSource,
+		});
+	}
+
 	// 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);