@gajae-code/coding-agent 0.5.1 → 0.5.2

package/src/config/settings-schema.ts

@@ -2,6 +2,7 @@ import type { Effort } from "@gajae-code/ai/model-thinking";
 import { TASK_SIMPLE_MODES } from "../task/simple-mode";
 import { getThinkingLevelMetadata } from "../thinking-metadata";
 import { EDIT_MODES } from "../utils/edit-mode";
+import { CONFIGURABLE_SEARCH_PROVIDER_IDS } from "../web/search/types";
 
 const THINKING_EFFORTS = ["minimal", "low", "medium", "high", "xhigh", "max"] as readonly Effort[];
 
@@ -164,6 +165,7 @@ interface EnumDef<T extends readonly string[]> {
 interface ArrayDef<T> {
 	type: "array";
 	default: T[];
+	items?: { enum: readonly string[] };
 	ui?: UiBase;
 }
 
@@ -832,6 +834,55 @@ export const SETTINGS_SCHEMA = {
 		},
 	},
 
+	"task.serviceTier": {
+		type: "enum",
+		values: [
+			"inherit",
+			"none",
+			"auto",
+			"default",
+			"flex",
+			"scale",
+			"priority",
+			"openai-only",
+			"claude-only",
+		] as const,
+		default: "inherit",
+		ui: {
+			tab: "tasks",
+			label: "Subagent Service Tier",
+			description:
+				'Service tier applied to task-tool subagents only. "inherit" copies the main session tier; any explicit value overrides it for subagents without touching the main session.',
+			options: [
+				{
+					value: "inherit",
+					label: "Inherit",
+					description: "Use the main session's service tier (default)",
+				},
+				{ value: "none", label: "None", description: "Omit service_tier for subagents" },
+				{ value: "auto", label: "Auto", description: "Use provider default tier selection (OpenAI)" },
+				{ value: "default", label: "Default", description: "Standard priority processing (OpenAI)" },
+				{ value: "flex", label: "Flex", description: "Flexible capacity tier when available (OpenAI)" },
+				{ value: "scale", label: "Scale", description: "Scale Tier credits when available (OpenAI)" },
+				{
+					value: "priority",
+					label: "Priority",
+					description: "Priority on every supported provider (OpenAI `service_tier`, Anthropic fast mode)",
+				},
+				{
+					value: "openai-only",
+					label: "Priority (OpenAI only)",
+					description: "Priority on OpenAI/OpenAI-Codex requests; ignored elsewhere",
+				},
+				{
+					value: "claude-only",
+					label: "Priority (Claude only)",
+					description: "Anthropic fast mode on direct Claude requests; ignored elsewhere (incl. Bedrock/Vertex)",
+				},
+			],
+		},
+	},
+
 	// Retries
 	"retry.enabled": { type: "boolean", default: true },
 
@@ -2068,6 +2119,17 @@ export const SETTINGS_SCHEMA = {
 		ui: { tab: "tools", label: "Web Search", description: "Enable the web_search tool for web searching" },
 	},
 
+	"web_search.fallback": {
+		type: "array",
+		default: EMPTY_STRING_ARRAY,
+		items: { enum: CONFIGURABLE_SEARCH_PROVIDER_IDS },
+		ui: {
+			tab: "tools",
+			label: "Web Search Fallback",
+			description: "Ordered fallback web search providers after the active model native provider",
+		},
+	},
+
 	"browser.enabled": {
 		type: "boolean",
 		default: true,

package/src/defaults/gjc/skills/ultragoal/SKILL.md

@@ -191,10 +191,10 @@ An ultragoal story cannot be checkpointed `complete` until the active agent has
    - code-side: maintainability, tests, integration points, and unsafe shortcuts.
 5. Delegate an `executor` QA/red-team lane to build and run the e2e/read-teaming QA suite appropriate for the story. This lane must try to break the change, not just confirm the happy path. It must start from the approved plan/spec/acceptance criteria, then user-facing contracts, and only then implementation code as supporting evidence. Plan/code mismatches are blockers, not items to paper over with implementation intent.
 6. The executor QA/red-team lane must prove evidence by the real surface under test:
-   - GUI/web surfaces require browser automation plus a screenshot or image verdict.
-   - CLI surfaces require logs or terminal transcripts from real invocation.
-   - API/package surfaces require external consumer or black-box tests through the public interface.
-   - Algorithm/math surfaces require boundary, property, adversarial, and failure-mode cases.
+   - GUI/web surfaces require a valid automation transcript plus a non-uniform screenshot. Bare `inlineEvidence` text or typed receipts never prove live GUI/web execution.
+   - CLI surfaces require runtime argv replay: `replaySafe: true`, an allowlisted argv `command`, and replayed normalized stdout matching `recordedStdout`; unsafe commands require audited `replayExempt` metadata plus a structurally valid fallback artifact.
+   - Native/desktop/tui surfaces require a structurally valid screenshot, PTY capture with terminal control codes, or app-automation transcript.
+   - API/package/algorithm/math surfaces require a real artifact file or typed receipt. Bare `inlineEvidence` text alone is not sufficient for any surface.
 7. The executor QA/red-team lane must report a matrix using `executorQa.contractCoverage`, `executorQa.surfaceEvidence`, `executorQa.adversarialCases`, and `executorQa.artifactRefs`. Not-applicable rows are allowed only in `contractCoverage` and `surfaceEvidence`; each `status: "not_applicable"` row requires `contractRef` plus `reason`. `adversarialCases` rows cannot be not-applicable.
 8. Run a final code review pass and fold it into the strict quality gate. Clean means `architectReview.architectureStatus`, `architectReview.productStatus`, and `architectReview.codeStatus` are all `"CLEAR"`, `architectReview.recommendation` is `"APPROVE"`, executor QA statuses are `"passed"`, iteration is `"passed"` with `fullRerun: true`, every evidence field is non-empty, every required matrix row is present, and every blockers array is empty. `COMMENT`, `WATCH`, `REQUEST CHANGES`, `BLOCK`, missing evidence, missing or shallow matrix rows, plan/code mismatches, or non-empty blockers are non-clean.
 9. If any lane finds an issue, do **not** checkpoint `complete` and do **not** call `goal({"op":"complete"})`. Record durable blocker work instead:
@@ -204,6 +204,8 @@ An ultragoal story cannot be checkpointed `complete` until the active agent has
 10. Complete or steer through the blocker story, then rerun the full blocking verification loop. Repeat until all verifier lanes are clean.
 11. Only after the loop is clean, checkpoint the story as complete with a structured quality gate and a fresh active `goal({"op":"get"})` snapshot. The checkpoint creates a receipt; `goals.json.status` alone is not proof. In aggregate mode, the final aggregate receipt must exist before `goal({"op":"complete"})` is allowed.
 
+While an Ultragoal run is active, the `ask` tool is blocked for all agents. Record unresolved review decisions as durable blockers with `gjc ultragoal record-review-blockers` instead of prompting interactively.
+
 The native `checkpoint --status complete` command rejects missing or shallow gates. `--quality-gate-json` must include:
 
 ```json
@@ -229,13 +231,19 @@ The native `checkpoint --status complete` command rejects missing or shallow gat
         "id": "browser-run",
         "kind": "browser-automation",
         "path": "artifacts/browser-run.json",
-        "description": "browser automation transcript invoking the approved user-facing flow"
+        "description": "valid automation transcript with actions, monotonic timestamps, and selectors"
       },
       {
         "id": "gui-screenshot",
         "kind": "screenshot",
         "path": "artifacts/gui-screenshot.png",
-        "description": "screenshot or image-verdict evidence for the GUI/web result"
+        "description": "non-uniform screenshot evidence for the GUI/web result"
+      },
+      {
+        "id": "cli-replay",
+        "kind": "command-replay",
+        "path": "artifacts/cli-replay.json",
+        "description": "artifact file containing argv-only CLI replay JSON: schemaVersion 1, kind cli-replay, replaySafe true, allowlisted command, recordedStdout"
       },
       {
         "id": "adversarial-report",
@@ -265,15 +273,23 @@ The native `checkpoint --status complete` command rejects missing or shallow gat
       {
         "id": "surface-gui",
         "contractRef": "user-facing surface or public interface under test",
-        "surface": "gui|web|cli|api|package|algorithm|math",
+        "surface": "gui|web|cli|api|package|algorithm|math|native|desktop|tui",
         "invocation": "real browser action, CLI command, API/package consumer call, or algorithm/property check",
         "verdict": "passed",
         "artifactRefs": ["browser-run", "gui-screenshot"]
       },
+      {
+        "id": "surface-cli",
+        "contractRef": "CLI or command-line interface under test",
+        "surface": "cli",
+        "invocation": "argv replay executed by the Ultragoal runtime",
+        "verdict": "passed",
+        "artifactRefs": ["cli-replay"]
+      },
       {
         "id": "surface-out-of-scope",
         "contractRef": "surface intentionally outside this story",
-        "surface": "gui|web|cli|api|package|algorithm|math",
+        "surface": "gui|web|cli|api|package|algorithm|math|native|desktop|tui",
         "status": "not_applicable",
         "reason": "why this surface does not apply to the current story"
       }
@@ -300,6 +316,12 @@ The native `checkpoint --status complete` command rejects missing or shallow gat
 }
 ```
 
+For CLI replay artifacts, the JSON at `path` must be an object like `{"schemaVersion":1,"kind":"cli-replay","replaySafe":true,"command":["bun","-e","console.log(\"ultragoal-cli-ok\")"],"recordedStdout":"ultragoal-cli-ok\n"}`. Use `replayExempt` only for audited unsafe/non-deterministic invocations, with a substantive reason, approver, and same-surface fallback artifacts.
+
+## Review mode
+
+`gjc ultragoal review` runs the same hardened gate against an already implemented PR, branch, or worktree. Use `--pr <number>` for a PR, `--branch <ref>` for a branch diff, omit both for the current worktree, and pass `--spec <path>` when a real contract exists. `--mode review-only` emits the verdict/findings without creating fix work; `--mode review-start` records review blockers for follow-up. Review mode validates the same `executorQa` shape and live-surface artifacts as `checkpoint --status complete`. A thin or derived-only contract can never clean-pass: the verdict is capped at `inconclusive: weak-contract` until a supplied spec or equivalent strong acceptance criteria are available.
+
 Receipts are freshness-scoped:
 - Per-goal receipts remain fresh for their target goal unless that goal, its blocker metadata, or its supersession metadata changes.
 - Normal later `goal_started` or clean receipt-backed `goal_checkpointed` events for other goals do not stale older per-goal receipts.

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

@@ -388,6 +388,34 @@ export async function appendOrMergeDeepInterviewRound(
 	return { action: result.action, record: result.record };
 }
 
+/**
+ * The chronological scored predecessor of the round currently being scored: the
+ * scored round with the greatest `round` strictly less than `currentRound`, with
+ * the same durable key excluded. Selecting by `round` (not array position) ensures
+ * an out-of-order re-score of an earlier round compares against its true prior, never
+ * a later ("future") scored round that happens to sit later in the array.
+ *
+ * Fail-safe: if `currentRound` is not a finite number, or a candidate's `round` is
+ * not finite, that comparison is treated as non-matching, so no prior is selected
+ * rather than risking a spurious comparison against an unrelated round.
+ */
+function latestPriorScoredRound(
+	rounds: readonly DeepInterviewRoundRecord[],
+	currentKey: string,
+	currentRound: number,
+): DeepInterviewRoundRecord | undefined {
+	if (!Number.isFinite(currentRound)) return undefined;
+	let prior: DeepInterviewRoundRecord | undefined;
+	for (const candidate of rounds) {
+		if (candidate.lifecycle !== "scored") continue;
+		if (candidate.round_key === currentKey) continue;
+		if (!Number.isFinite(candidate.round)) continue;
+		if (!(candidate.round < currentRound)) continue;
+		if (prior === undefined || candidate.round > prior.round) prior = candidate;
+	}
+	return prior;
+}
+
 /** Merge scoring output into the same round record, transitioning to `scored`. */
 export async function enrichDeepInterviewRoundScoring(
 	cwd: string,
@@ -399,6 +427,18 @@ export async function enrichDeepInterviewRoundScoring(
 	const interviewId = input.interviewId ?? interviewIdOf(envelope);
 	const rounds = readRounds(envelope);
 	const { rounds: nextRounds, record } = enrichRoundWithScoring(rounds, { ...input, interviewId });
+	// Fail closed: a scored transition that violates the bidirectional invariant
+	// (an active trigger that improves the affected dimension or fails to raise
+	// overall ambiguity, or a disputed/unresolved trigger lacking a rationale) must
+	// never be persisted — storing it lets the interview falsely converge. Validate
+	// against the most recent prior scored round before writing any durable state.
+	const prior = latestPriorScoredRound(rounds, record.round_key, record.round);
+	const validation = validateDeepInterviewScoredTransition(prior, record);
+	if (!validation.ok) {
+		throw new Error(
+			`deep-interview scored transition for round ${record.round} is invalid and was refused: ${validation.violations.join("; ")}`,
+		);
+	}
 	(envelope.state as Record<string, unknown>).rounds = nextRounds;
 	(envelope.state as Record<string, unknown>).current_ambiguity = input.ambiguity;
 	await persistEnvelope(cwd, statePath, envelope, options.sessionId, "gjc deep-interview score-round");

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

@@ -1,4 +1,5 @@
 import * as path from "node:path";
+import { safeStderrWrite } from "@gajae-code/utils";
 import type { Args } from "../cli/args";
 import {
 	buildGjcTmuxProfileCommands,
@@ -280,7 +281,7 @@ export function launchDefaultTmuxIfNeeded(context: TmuxLaunchContext): boolean {
 			cleanupCreatedTmuxSession(plan, spawnSync, options);
 			const failure =
 				profile.failures.find(item => item.command.args.includes("@gjc-profile")) ?? profile.failures[0];
-			(context.diagnosticWriter ?? process.stderr.write.bind(process.stderr))(
+			(context.diagnosticWriter ?? safeStderrWrite)(
 				formatTmuxLaunchDiagnostic("profile tagging failed", failure?.stderr),
 			);
 			return true;
@@ -289,8 +290,6 @@ export function launchDefaultTmuxIfNeeded(context: TmuxLaunchContext): boolean {
 	if (created.exitCode !== 0) return false;
 	const attached = spawnSync(plan.tmuxCommand, ["attach-session", "-t", plan.sessionName], options);
 	if (attached.exitCode === 0) return true;
-	(context.diagnosticWriter ?? process.stderr.write.bind(process.stderr))(
-		formatTmuxLaunchDiagnostic("attach failed", attached.stderr),
-	);
+	(context.diagnosticWriter ?? safeStderrWrite)(formatTmuxLaunchDiagnostic("attach failed", attached.stderr));
 	return true;
 }

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

@@ -13,7 +13,12 @@ import {
 } from "./ledger-event-renderer";
 import { isRestrictedRoleAgentBash } from "./restricted-role-agent-bash";
 import { migrateWorkflowState } from "./state-migrations";
-import { appendJsonl, readExistingStateForMutation, writeArtifact, writeWorkflowEnvelopeAtomic } from "./state-writer";
+import {
+	appendJsonlIdempotent,
+	readExistingStateForMutation,
+	writeArtifact,
+	writeWorkflowEnvelopeAtomic,
+} from "./state-writer";
 
 /**
  * Native implementation of `gjc ralplan`.
@@ -186,7 +191,37 @@ async function readActiveRunId(cwd: string, sessionId: string | undefined): Prom
 	return candidate;
 }
 
-async function persistActiveRunId(cwd: string, sessionId: string | undefined, runId: string): Promise<void> {
+/**
+ * Run-state phases that an artifact write must never reopen. Once ralplan has
+ * reached a terminal/handed-off phase, a stray `--write` must not regress
+ * `current_phase` back to a stage — that would silently re-arm a chain guard or
+ * undo Stop semantics. Every other phase advances to track the stage just
+ * persisted so run-state stays coherent with the active ralplan stage.
+ */
+const PHASE_LOCK = new Set([
+	"final",
+	"handoff",
+	"complete",
+	"completed",
+	"failed",
+	"cancelled",
+	"canceled",
+	"inactive",
+]);
+
+/** Phase that keeps run-state coherent with the stage just written, preserving locked phases. */
+function advanceCurrentPhase(existingPhase: unknown, stage: RalplanStage): string {
+	const current = typeof existingPhase === "string" ? existingPhase.trim() : "";
+	if (current && PHASE_LOCK.has(current)) return current;
+	return stage;
+}
+
+async function persistActiveRunId(
+	cwd: string,
+	sessionId: string | undefined,
+	runId: string,
+	stage: RalplanStage,
+): Promise<void> {
 	const statePath = ralplanStatePath(cwd, sessionId);
 	const existingRead = await readExistingStateForMutation(statePath);
 	if (existingRead.kind === "corrupt") {
@@ -197,11 +232,25 @@ async function persistActiveRunId(cwd: string, sessionId: string | undefined, ru
 	}
 	let existing: Record<string, unknown> = existingRead.kind === "valid" ? existingRead.value : {};
 
-	if (existing.run_id === runId && existing.version === WORKFLOW_STATE_VERSION) return;
+	// A new run_id is a fresh run, not a stray write on the prior run: never inherit a
+	// previous run's terminal/locked phase (which would start the new run already
+	// "complete"/"handoff" and disarm the Stop hook). PHASE_LOCK only guards same-run writes.
+	const isNewRun = existing.run_id !== runId;
+	const nextPhase = isNewRun ? stage : advanceCurrentPhase(existing.current_phase, stage);
+	if (
+		existing.run_id === runId &&
+		existing.version === WORKFLOW_STATE_VERSION &&
+		existing.current_phase === nextPhase &&
+		(existing.active === true || PHASE_LOCK.has(nextPhase))
+	) {
+		return;
+	}
 	existing.run_id = runId;
 	if (typeof existing.skill !== "string") existing.skill = "ralplan";
-	if (typeof existing.active !== "boolean") existing.active = true;
-	if (typeof existing.current_phase !== "string") existing.current_phase = "planner";
+	// A successful persist means ralplan is actively writing this run's artifacts, so always
+	// re-assert active. Fallback-only init left active:false after a clear (#644, sibling of #638).
+	existing.active = true;
+	existing.current_phase = nextPhase;
 	existing = migrateWorkflowState(existing, "ralplan").state;
 	existing.updated_at = new Date().toISOString();
 	await writeWorkflowEnvelopeAtomic(statePath, existing, {
@@ -381,8 +430,6 @@ async function resolveArtifactArgs(args: readonly string[], cwd: string): Promis
 	const explicitRunId = flagValue(args, "--run-id")?.trim();
 	const runId = explicitRunId || (await readActiveRunId(cwd, sessionId)) || sessionIdRaw || defaultRunId();
 	assertSafePathComponent(runId, "run-id");
-	// Persist the active run id so later writes in the same loop land in the same directory.
-	await persistActiveRunId(cwd, sessionId, runId);
 
 	const artifact = await resolveArtifactContent(rawArtifact, cwd);
 	return { stage: stage as RalplanStage, stageN, runId, artifact, sessionId, json: hasFlag(args, "--json") };
@@ -398,18 +445,34 @@ interface PersistedArtifact {
 	pendingApprovalPath?: string;
 }
 
-async function persistArtifact(resolved: ResolvedArtifactArgs, cwd: string): Promise<PersistedArtifact> {
+/**
+ * Content-addressed identity for an `index.jsonl` row: a repeated `--write` of the
+ * same `(stage, stage_n)` at identical content (same sha256) is the #638 duplicate
+ * the append must collapse. Rows missing these fields opt out of dedup.
+ */
+function ralplanIndexKey(entry: unknown): string | undefined {
+	if (!entry || typeof entry !== "object" || Array.isArray(entry)) return undefined;
+	const record = entry as Record<string, unknown>;
+	const { stage, stage_n, sha256 } = record;
+	if (typeof stage !== "string" || typeof stage_n !== "number" || typeof sha256 !== "string") return undefined;
+	return `${stage}\u0000${stage_n}\u0000${sha256}`;
+}
+
+async function persistArtifact(
+	resolved: ResolvedArtifactArgs,
+	cwd: string,
+	content: string,
+	sha256: string,
+): Promise<PersistedArtifact> {
 	const runDir = path.join(cwd, ".gjc", "plans", "ralplan", resolved.runId);
 
 	const fileName = `stage-${pad2(resolved.stageN)}-${resolved.stage}.md`;
 	const filePath = path.join(runDir, fileName);
-	const content = resolved.artifact.endsWith("\n") ? resolved.artifact : `${resolved.artifact}\n`;
 	await writeArtifact(filePath, content, {
 		cwd,
 		audit: { category: "artifact", verb: "write", owner: "gjc-runtime", skill: "ralplan" },
 	});
 
-	const sha256 = createHash("sha256").update(content).digest("hex");
 	const createdAt = new Date().toISOString();
 	const indexEntry = {
 		stage: resolved.stage,
@@ -418,9 +481,10 @@ async function persistArtifact(resolved: ResolvedArtifactArgs, cwd: string): Pro
 		created_at: createdAt,
 		sha256,
 	};
-	await appendJsonl(path.join(runDir, "index.jsonl"), indexEntry, {
+	await appendJsonlIdempotent(path.join(runDir, "index.jsonl"), indexEntry, {
 		cwd,
 		audit: { category: "ledger", verb: "append", owner: "gjc-runtime", skill: "ralplan" },
+		key: ralplanIndexKey,
 	});
 
 	let pendingApprovalPath: string | undefined;
@@ -443,6 +507,56 @@ async function persistArtifact(resolved: ResolvedArtifactArgs, cwd: string): Pro
 	};
 }
 
+/** The persisted `(stage, stage_n)` artifact recorded in a run's `index.jsonl`. */
+interface ExistingStageArtifact {
+	path: string;
+	sha256: string;
+	createdAt: string;
+}
+
+/**
+ * Find the most recent `index.jsonl` row for a `(stage, stage_n)` pair so a
+ * repeated `--write` can dedupe instead of silently clobbering the artifact and
+ * appending a duplicate ledger row. Best-effort: a missing or unreadable index
+ * yields `undefined`, treated as "no prior artifact". The ledger is the source of
+ * truth for dedup because it is exactly what a duplicate write would corrupt.
+ */
+async function findExistingStageArtifact(
+	cwd: string,
+	runId: string,
+	stage: RalplanStage,
+	stageN: number,
+): Promise<ExistingStageArtifact | undefined> {
+	const indexPath = path.join(cwd, ".gjc", "plans", "ralplan", runId, "index.jsonl");
+	let text: string;
+	try {
+		text = await fs.readFile(indexPath, "utf8");
+	} catch {
+		return undefined;
+	}
+	let match: ExistingStageArtifact | undefined;
+	for (const line of text.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 (record.stage !== stage || record.stage_n !== stageN) continue;
+		if (typeof record.path !== "string" || typeof record.sha256 !== "string") continue;
+		match = {
+			path: record.path,
+			sha256: record.sha256,
+			createdAt: typeof record.created_at === "string" ? record.created_at : "",
+		};
+	}
+	return match;
+}
+
 /**
  * Read and parse the run's `index.jsonl` rows. Best-effort: returns [] when the
  * file is absent or unreadable so HUD sync never fails on a missing index.
@@ -518,7 +632,26 @@ async function buildRalplanHud(options: {
 async function handleArtifactWrite(args: readonly string[], cwd: string): Promise<RalplanCommandResult> {
 	const plannerState = parsePlannerStateArgs(args);
 	const resolved = await resolveArtifactArgs(args, cwd);
-	const persisted = await persistArtifact(resolved, cwd);
+	const content = resolved.artifact.endsWith("\n") ? resolved.artifact : `${resolved.artifact}\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.
+	const existingArtifact = await findExistingStageArtifact(cwd, resolved.runId, resolved.stage, resolved.stageN);
+	if (existingArtifact) {
+		if (existingArtifact.sha256 !== sha256) {
+			throw new RalplanCommandError(
+				2,
+				`refusing to overwrite ralplan ${resolved.stage} stage ${resolved.stageN} at ${existingArtifact.path}: an artifact with different content already exists (existing sha256=${existingArtifact.sha256}, new sha256=${sha256}). Use a new --stage_n to record another pass.`,
+			);
+		}
+		return buildDeduplicatedResult(resolved, existingArtifact, sha256, cwd);
+	}
+
+	// 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);
 	if (plannerState) {
 		await applyPlannerStateUpdate(cwd, resolved.sessionId, plannerState);
 	}
@@ -547,6 +680,35 @@ async function handleArtifactWrite(args: readonly string[], cwd: string): Promis
 	return { status: 0, stdout };
 }
 
+/**
+ * Deterministic no-op receipt for an identical repeated `--write`: report the
+ * already-persisted artifact without rewriting the file, appending a ledger row, or
+ * churning run-state. `deduplicated: true` lets callers distinguish it from a fresh write.
+ */
+function buildDeduplicatedResult(
+	resolved: ResolvedArtifactArgs,
+	existing: ExistingStageArtifact,
+	sha256: string,
+	cwd: string,
+): RalplanCommandResult {
+	const payload: Record<string, unknown> = {
+		run_id: resolved.runId,
+		path: existing.path,
+		stage: resolved.stage,
+		stage_n: resolved.stageN,
+		sha256,
+		created_at: existing.createdAt,
+		deduplicated: true,
+	};
+	if (resolved.stage === "final") {
+		payload.pending_approval_path = path.join(cwd, ".gjc", "plans", "ralplan", resolved.runId, "pending-approval.md");
+	}
+	const stdout = resolved.json
+		? `${JSON.stringify(payload, null, 2)}\n`
+		: `ralplan ${resolved.stage} stage ${resolved.stageN} already persisted at ${existing.path} (identical content; no changes written).\n`;
+	return { status: 0, stdout };
+}
+
 /* -------------------------------- handoff -------------------------------- */
 
 interface ConsensusHandoffArgs {

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

@@ -52,6 +52,7 @@ import {
 	type StateWriterAuditContext,
 	softDelete,
 	updateWorkflowTransactionJournal,
+	type WorkflowEnvelopeIntegrityMismatch,
 	writeWorkflowEnvelopeAtomic,
 } from "./state-writer";
 import { getSkillManifest, isKnownWorkflowState, isValidTransition, typedArgsFor } from "./workflow-manifest";
@@ -659,7 +660,7 @@ async function warnAndAuditOutOfBandIfNeeded(
 	skill: CanonicalGjcWorkflowSkill,
 	options?: { mutationId?: string; forced?: boolean },
 ): Promise<string | undefined> {
-	let mismatch: Awaited<ReturnType<typeof detectWorkflowEnvelopeIntegrityMismatch>>;
+	let mismatch: WorkflowEnvelopeIntegrityMismatch | undefined;
 	try {
 		mismatch = await detectWorkflowEnvelopeIntegrityMismatch(filePath);
 	} catch {