@gajae-code/coding-agent 0.5.0 → 0.5.2

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

@@ -5,9 +5,20 @@ import { syncSkillActiveState } from "../skill-state/active-state";
 import { buildRalplanHudSummary } from "../skill-state/workflow-hud";
 import { WORKFLOW_STATE_VERSION } from "../skill-state/workflow-state-contract";
 import { renderCliWriteReceipt } from "./cli-write-receipt";
+import {
+	formatRalplanStagePresence,
+	parseRalplanIndexLine,
+	type RalplanIndexRow,
+	summarizeRalplanIndex,
+} 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`.
@@ -180,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") {
@@ -191,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, {
@@ -375,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") };
@@ -392,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,
@@ -412,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;
@@ -437,12 +507,82 @@ 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.
+ */
+async function readRalplanIndexRows(cwd: string, runId: string): Promise<RalplanIndexRow[]> {
+	try {
+		const indexPath = path.join(cwd, ".gjc", "plans", "ralplan", runId, "index.jsonl");
+		const text = await fs.readFile(indexPath, "utf8");
+		const rows: RalplanIndexRow[] = [];
+		for (const line of text.split(/\r?\n/)) {
+			const row = parseRalplanIndexLine(line);
+			if (row) rows.push(row);
+		}
+		return rows;
+	} catch {
+		return [];
+	}
+}
+
 async function syncRalplanHud(options: {
 	cwd: string;
 	sessionId?: string;
 	stage: string;
 	pendingApproval: boolean;
 	iteration?: number;
+	runId?: string;
 	latestSummary?: string;
 }): Promise<void> {
 	try {
@@ -453,23 +593,65 @@ async function syncRalplanHud(options: {
 			phase: options.stage,
 			sessionId: options.sessionId,
 			source: "gjc-ralplan-native",
-			hud: buildRalplanHudSummary({
-				stage: options.stage,
-				iteration: options.iteration,
-				pendingApproval: options.pendingApproval,
-				latestSummary: options.latestSummary,
-				updatedAt: new Date().toISOString(),
-			}),
+			hud: await buildRalplanHud(options),
 		});
 	} catch {
 		// HUD sync is best-effort and must not change command semantics.
 	}
 }
 
+async function buildRalplanHud(options: {
+	cwd: string;
+	stage: string;
+	pendingApproval: boolean;
+	iteration?: number;
+	latestSummary?: string;
+	runId?: string;
+}) {
+	let iterationFromIndex: number | undefined;
+	let stages: string | undefined;
+	if (options.runId) {
+		const rows = await readRalplanIndexRows(options.cwd, options.runId);
+		if (rows.length > 0) {
+			const summary = summarizeRalplanIndex(rows);
+			iterationFromIndex = summary.iteration;
+			stages = formatRalplanStagePresence(summary.currentStages);
+		}
+	}
+	return buildRalplanHudSummary({
+		stage: options.stage,
+		iteration: options.iteration,
+		iterationFromIndex,
+		stages,
+		pendingApproval: options.pendingApproval,
+		latestSummary: options.latestSummary,
+		updatedAt: new Date().toISOString(),
+	});
+}
+
 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);
 	}
@@ -477,6 +659,7 @@ async function handleArtifactWrite(args: readonly string[], cwd: string): Promis
 		cwd,
 		sessionId: resolved.sessionId,
 		stage: persisted.stage,
+		runId: persisted.runId,
 		pendingApproval: persisted.stage === "final",
 		iteration: persisted.stageN,
 		latestSummary: `persisted ${persisted.stage} stage ${persisted.stageN}`,
@@ -497,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 {
@@ -617,6 +829,7 @@ async function handleConsensusHandoff(args: readonly string[], cwd: string): Pro
 		cwd,
 		sessionId: resolved.sessionId,
 		stage: "planner",
+		runId,
 		pendingApproval: false,
 		iteration: 1,
 		latestSummary: `${mode} run · ${resolved.interactive ? "interactive" : "automated"}`,

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

@@ -118,8 +118,13 @@ export interface StateStatusSummary {
 
 function compactStateFields(state: Record<string, unknown>): Array<[string, string]> {
 	const fields: Array<[string, string]> = [];
+	const nested = isRecord(state.state) ? state.state : undefined;
 	for (const key of COMPACT_ELIDE_KEYS) {
-		const value = state[key];
+		const value = Array.isArray(state[key])
+			? state[key]
+			: nested && Array.isArray(nested[key])
+				? nested[key]
+				: undefined;
 		if (Array.isArray(value)) fields.push([key, `${value.length} entries (elided)`]);
 	}
 	return fields;
@@ -133,9 +138,13 @@ export function compactProjectStateJson(
 	const state = stateObject(stateJson);
 	const compact = projectStateFields(skill, stateJson, manifest, STATE_FIELD_ALLOWLIST);
 	const elisions: Record<string, unknown> = {};
+	const nested = isRecord(state.state) ? state.state : undefined;
 	for (const key of COMPACT_ELIDE_KEYS) {
-		const value = state[key];
-		if (Array.isArray(value)) elisions[key] = { type: "array", count: value.length, pointer: `/${key}` };
+		if (Array.isArray(state[key])) {
+			elisions[key] = { type: "array", count: (state[key] as unknown[]).length, pointer: `/${key}` };
+		} else if (nested && Array.isArray(nested[key])) {
+			elisions[key] = { type: "array", count: (nested[key] as unknown[]).length, pointer: `/state/${key}` };
+		}
 	}
 	if (Object.keys(elisions).length) compact.elided = elisions;
 	return compact;

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

@@ -11,10 +11,10 @@ import {
 } from "../skill-state/active-state";
 import { initialPhaseForSkill } from "../skill-state/initial-phase";
 import {
-	buildDeepInterviewHudSummary,
 	buildRalplanHudSummary,
 	buildTeamHudSummary,
 	buildUltragoalHudSummary,
+	deriveDeepInterviewHud,
 } from "../skill-state/workflow-hud";
 import {
 	type AuditEntry,
@@ -26,6 +26,7 @@ import {
 	type WorkflowStateReceipt,
 } from "../skill-state/workflow-state-contract";
 import { renderCliWriteReceipt } from "./cli-write-receipt";
+import { mergeDeepInterviewEnvelope, normalizeDeepInterviewEnvelope } from "./deep-interview-state";
 import { renderStateGraph, type StateGraphFormat } from "./state-graph";
 import { migrateAndPersistLegacyState, migrateWorkflowState } from "./state-migrations";
 import {
@@ -51,6 +52,7 @@ import {
 	type StateWriterAuditContext,
 	softDelete,
 	updateWorkflowTransactionJournal,
+	type WorkflowEnvelopeIntegrityMismatch,
 	writeWorkflowEnvelopeAtomic,
 } from "./state-writer";
 import { getSkillManifest, isKnownWorkflowState, isValidTransition, typedArgsFor } from "./workflow-manifest";
@@ -658,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 {
@@ -833,31 +835,9 @@ function buildHudForMode(
 ): WorkflowHudSummary | undefined {
 	const updatedAt = new Date().toISOString();
 	const phase = typeof payload.current_phase === "string" ? payload.current_phase : undefined;
-	const stateField = isPlainObject(payload.state) ? (payload.state as Record<string, unknown>) : {};
 	switch (mode) {
-		case "deep-interview": {
-			const pick = <T>(key: string, guard: (value: unknown) => value is T): T | undefined => {
-				const v = (stateField as Record<string, unknown>)[key] ?? (payload as Record<string, unknown>)[key];
-				return guard(v) ? v : undefined;
-			};
-			const isNumber = (v: unknown): v is number => typeof v === "number";
-			const isString = (v: unknown): v is string => typeof v === "string";
-			const isArray = (v: unknown): v is unknown[] => Array.isArray(v);
-			const ambiguity = pick("current_ambiguity", isNumber);
-			const threshold = pick("threshold", isNumber);
-			const rounds = pick("rounds", isArray);
-			const targetComponent = pick("last_targeted_component_id", isString);
-			const weakestDimension = pick("weakest_dimension", isString);
-			return buildDeepInterviewHudSummary({
-				phase,
-				ambiguity,
-				threshold,
-				roundCount: rounds?.length,
-				targetComponent,
-				weakestDimension,
-				updatedAt,
-			});
-		}
+		case "deep-interview":
+			return deriveDeepInterviewHud(payload, { updatedAt });
 		case "ralplan": {
 			const stage =
 				typeof payload.current_phase === "string"
@@ -888,6 +868,24 @@ function buildHudForMode(
 				counts[status] = (counts[status] ?? 0) + 1;
 			}
 			const currentGoalRaw = goals.find(g => g.status === "active") ?? goals.find(g => g.status === "pending");
+			const rawLedger = payload.latestLedgerEvent;
+			const latestLedgerEvent =
+				rawLedger && typeof rawLedger === "object" && !Array.isArray(rawLedger)
+					? {
+							event:
+								typeof (rawLedger as Record<string, unknown>).event === "string"
+									? ((rawLedger as Record<string, unknown>).event as string)
+									: undefined,
+							goalId:
+								typeof (rawLedger as Record<string, unknown>).goalId === "string"
+									? ((rawLedger as Record<string, unknown>).goalId as string)
+									: undefined,
+							timestamp:
+								typeof (rawLedger as Record<string, unknown>).timestamp === "string"
+									? ((rawLedger as Record<string, unknown>).timestamp as string)
+									: undefined,
+						}
+					: undefined;
 			const status = typeof payload.status === "string" ? (payload.status as string) : (phase ?? "pending");
 			return buildUltragoalHudSummary({
 				status,
@@ -900,6 +898,7 @@ function buildHudForMode(
 					: undefined,
 				counts,
 				goals: goals.map(g => ({ id: g.id as string, title: g.title as string, status: g.status as string })),
+				latestLedgerEvent,
 				updatedAt,
 			});
 		}
@@ -1009,7 +1008,10 @@ export async function reconcileWorkflowSkillState(options: {
 	receipt.from_phase = fromPhase;
 	receipt.to_phase = trimmedPhase;
 
-	const merged = mergeWithNullDelete(existingPayload, payload);
+	const merged =
+		mode === "deep-interview"
+			? (mergeDeepInterviewEnvelope(existingPayload, payload) as Record<string, unknown>)
+			: mergeWithNullDelete(existingPayload, payload);
 	merged.skill = mode;
 	merged.current_phase = trimmedPhase;
 	merged.active = active;
@@ -1173,7 +1175,11 @@ async function handleWrite(
 					? (innerState.current_phase as string).trim()
 					: undefined;
 	let merged: Record<string, unknown>;
-	if (hasFlag(args, "--replace")) {
+	if (mode === "deep-interview") {
+		// Deep-interview keeps interview data nested under `state` and merges rounds
+		// losslessly by durable key; never flatten or delete `state` (that drops recorder history).
+		merged = mergeDeepInterviewEnvelope(existingPayload, payload, { replace: hasFlag(args, "--replace") });
+	} else if (hasFlag(args, "--replace")) {
 		merged = { ...payload };
 	} else {
 		merged = mergeWithNullDelete(existingPayload, payload);
@@ -1423,8 +1429,20 @@ async function handleHandoff(
 	});
 
 	const calleeInitial = initialPhaseForSkill(callee);
-	const normalizedCaller = migrateWorkflowState(existingCaller, caller).state;
-	const normalizedCallee = migrateWorkflowState(existingCallee, callee).state;
+	const normalizedCaller =
+		caller === "deep-interview"
+			? (normalizeDeepInterviewEnvelope(migrateWorkflowState(existingCaller, caller).state) as Record<
+					string,
+					unknown
+				>)
+			: migrateWorkflowState(existingCaller, caller).state;
+	const normalizedCallee =
+		callee === "deep-interview"
+			? (normalizeDeepInterviewEnvelope(migrateWorkflowState(existingCallee, callee).state) as Record<
+					string,
+					unknown
+				>)
+			: migrateWorkflowState(existingCallee, callee).state;
 	const mergedCalleeState: Record<string, unknown> = {
 		...normalizedCallee,
 		skill: callee,