@gajae-code/coding-agent 0.5.1 → 0.5.2

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

@@ -1,6 +1,8 @@
 import { createHash, randomUUID } from "node:crypto";
+import type { Stats } from "node:fs";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
+import { type FileLockOptions, withFileLock } from "../config/file-lock";
 import type { ActiveSubskillEntry, SkillActiveEntry, SkillActiveState } from "../skill-state/active-state";
 import {
 	type AuditEntry,
@@ -80,6 +82,12 @@ export interface StateWriterOptions {
 	cwd?: string;
 	receipt?: StateWriterReceiptContext;
 	audit?: StateWriterAuditContext;
+	/**
+	 * Cross-process lock tuning for read-modify-write paths that route through
+	 * `withWorkflowStateLock` / `updateJsonAtomic`. Omit for the hardened
+	 * `withFileLock` defaults.
+	 */
+	lock?: FileLockOptions;
 }
 
 export interface DeleteIfOwnedOptions extends StateWriterOptions {
@@ -113,7 +121,7 @@ export interface GenericHardPruneTarget {
 export interface GenericHardPruneSelectorContext {
 	path: string;
 	category: WriterCategory | string;
-	stat: Awaited<ReturnType<typeof fs.stat>>;
+	stat: Stats;
 	readJson: () => Promise<unknown>;
 }
 
@@ -388,6 +396,57 @@ export async function writeJsonAtomic(
 	return filePath;
 }
 
+async function readPersistedPhase(filePath: string): Promise<string | undefined> {
+	try {
+		const existing = await readJsonIfPresent(filePath);
+		if (!isPlainObject(existing)) return undefined;
+		// Only an *active* prior envelope is a transition source. A cleared / handed-off
+		// envelope (`active: false`, terminal phase such as `complete` / `handoff`) is outside
+		// active workflow progression, so reactivation from it (e.g. a fresh kickoff) must not
+		// be reported as an invalid transition.
+		if (existing.active !== true) return undefined;
+		const phase = existing.current_phase;
+		return typeof phase === "string" ? phase : undefined;
+	} catch {
+		// Best-effort diagnostic read: a corrupt/unreadable prior envelope simply yields no
+		// `from` phase, so the transition invariant degrades to a no-op rather than failing
+		// the sanctioned write it is observing.
+		return undefined;
+	}
+}
+
+async function recordInvalidWorkflowTransition(args: {
+	filePath: string;
+	skill: CanonicalGjcWorkflowSkill;
+	fromPhase: string;
+	toPhase: string;
+	options?: StateWriterOptions;
+}): Promise<void> {
+	const { filePath, skill, fromPhase, toPhase, options } = args;
+	// Audit-only diagnostic: a successful sanctioned write must NOT emit to stderr — callers
+	// may treat any stderr output as failure or parse stdout/stderr as machine output. The
+	// `invalid_transition_detected` audit entry is the durable, non-intrusive evidence that an
+	// internal write skipped a manifest edge.
+	const cwd = path.resolve(options?.audit?.cwd ?? options?.cwd ?? process.cwd());
+	try {
+		await appendAuditEntry(cwd, {
+			ts: new Date().toISOString(),
+			skill,
+			category: "state",
+			verb: "invalid_transition_detected",
+			owner: options?.audit?.owner ?? "gjc-runtime",
+			mutation_id: options?.audit?.mutationId ?? `${skill}:invalid-transition:${new Date().toISOString()}`,
+			from_phase: fromPhase,
+			to_phase: toPhase,
+			forced: false,
+			paths: [filePath],
+		});
+	} catch {
+		// Audit logging is best-effort diagnostics; never fail a sanctioned write because the
+		// audit append failed (e.g. cwd is not a writable project root).
+	}
+}
+
 export async function writeWorkflowEnvelopeAtomic(
 	targetPath: string,
 	value: unknown,
@@ -404,6 +463,50 @@ export async function writeWorkflowEnvelopeAtomic(
 				.join("; ")}`,
 		);
 	}
+	// #658: internal runtime writers (ralplan/ultragoal/deep-interview/team) persist
+	// envelopes directly, bypassing the `gjc state` CLI transition gate (`isValidTransition`,
+	// historically the sole call site in state-runtime.ts). Re-assert that gate on every
+	// sanctioned envelope write so internal writes cannot persist invalid state-machine phase
+	// transitions silently. Forced writes (`gjc state ... --force`, reconcile repairs) carry
+	// `audit.forced` and bypass, mirroring the CLI's `use --force to bypass`.
+	//
+	// The gate governs ACTIVE workflow progression only. Deactivation/teardown writes
+	// (`active: false`, e.g. `gjc state clear`, which persists the universal `complete`
+	// sentinel that is not a per-skill manifest state) leave the transition graph and are
+	// intentionally exempt.
+	if (options?.audit?.forced !== true && parsed.data.active === true) {
+		const toPhase = parsed.data.current_phase.trim();
+		if (toPhase) {
+			// Lazy import: workflow-manifest dereferences CANONICAL_GJC_WORKFLOW_SKILLS at
+			// module load, and active-state -> state-writer -> workflow-manifest -> active-state
+			// is a load-time cycle. Importing at call time (after init) avoids the TDZ.
+			const { isKnownWorkflowState, isValidTransition } = await import("./workflow-manifest");
+			const skill = parsed.data.skill;
+			// Structural invariant (hard): a `current_phase` absent from the skill's manifest is
+			// never a legitimate internal write, matching the CLI/reconcile unknown-phase gate.
+			if (!isKnownWorkflowState(skill, toPhase)) {
+				throw new Error(
+					`Refusing to write unknown ${skill} phase "${toPhase}" to ${filePath}: not a known ${skill} manifest state (forced writes bypass via audit.forced)`,
+				);
+			}
+			// Transition invariant (#658, diagnostic-only safety net): resolve the prior phase
+			// (caller-supplied `audit.fromPhase`, else the active persisted envelope on disk) and
+			// flag edges the manifest does not define. Intentionally NON-blocking and audit-only
+			// — the CLI path already hard-fails invalid edges before reaching here, and legitimate
+			// internal repairs / ralplan short-mode stage skips move between valid states without a
+			// direct manifest edge. It records an `invalid_transition_detected` audit entry (no
+			// stderr) so such transitions are non-silent without breaking those flows.
+			const fromPhase = (options?.audit?.fromPhase ?? (await readPersistedPhase(filePath)))?.trim();
+			if (
+				fromPhase &&
+				fromPhase !== toPhase &&
+				isKnownWorkflowState(skill, fromPhase) &&
+				!isValidTransition(skill, fromPhase, toPhase)
+			) {
+				await recordInvalidWorkflowTransition({ filePath, skill, fromPhase, toPhase, options });
+			}
+		}
+	}
 	await atomicWrite(filePath, jsonText(stamped));
 	await maybeAudit(filePath, options);
 	return filePath;
@@ -416,17 +519,55 @@ export async function writeTextAtomic(targetPath: string, text: string, options?
 	return filePath;
 }
 
+/**
+ * Serialize a read-modify-write (or any multi-step mutation) against concurrent
+ * writers of the same `.gjc/**` target. Uses the cross-process directory lock
+ * from `withFileLock`, keyed on the resolved file path, so separate CLI/agent
+ * processes (e.g. team-mode workers) cannot interleave one writer's read with
+ * another writer's write and silently drop the first mutation (issue #646).
+ *
+ * The lock is advisory: it only protects callers that route through it, so every
+ * read-modify-write of a given file MUST acquire this lock for the same resolved
+ * path. `atomicWrite`'s temp-file + rename crash-atomicity is preserved; this
+ * layers concurrency-atomicity on top without weakening it.
+ */
+export async function withWorkflowStateLock<T>(
+	targetPath: string,
+	fn: () => Promise<T>,
+	options?: StateWriterOptions,
+): Promise<T> {
+	const filePath = resolveGjcTarget(targetPath, cwdForOptions(options));
+	return lockResolvedWorkflowTarget(filePath, fn, options?.lock);
+}
+
+async function lockResolvedWorkflowTarget<T>(
+	filePath: string,
+	fn: () => Promise<T>,
+	lockOptions?: FileLockOptions,
+): Promise<T> {
+	// `withFileLock` creates the lock dir next to the target with a non-recursive
+	// mkdir, so the parent directory must exist before the lock is acquired.
+	await fs.mkdir(path.dirname(filePath), { recursive: true });
+	return withFileLock(filePath, fn, lockOptions);
+}
+
 export async function updateJsonAtomic<T = unknown>(
 	targetPath: string,
 	mutator: (current: T | undefined) => T | Promise<T>,
 	options?: StateWriterOptions,
 ): Promise<string> {
 	const filePath = resolveGjcTarget(targetPath, cwdForOptions(options));
-	const current = (await readJsonIfPresent(filePath)) as T | undefined;
-	const next = await mutator(current);
-	await atomicWrite(filePath, jsonText(withWorkflowReceipt(next, buildReceipt(options))));
-	await maybeAudit(filePath, options);
-	return filePath;
+	return lockResolvedWorkflowTarget(
+		filePath,
+		async () => {
+			const current = (await readJsonIfPresent(filePath)) as T | undefined;
+			const next = await mutator(current);
+			await atomicWrite(filePath, jsonText(withWorkflowReceipt(next, buildReceipt(options))));
+			await maybeAudit(filePath, options);
+			return filePath;
+		},
+		options?.lock,
+	);
 }
 
 export async function appendJsonl(targetPath: string, entry: unknown, options?: StateWriterOptions): Promise<string> {
@@ -437,6 +578,112 @@ export async function appendJsonl(targetPath: string, entry: unknown, options?:
 	return filePath;
 }
 
+export interface AppendJsonlIdempotentOptions extends StateWriterOptions {
+	/**
+	 * Identity key for an entry. Two entries that produce the same non-`undefined`
+	 * key are duplicates, so only the first is appended. Return `undefined` to opt a
+	 * candidate out of dedup (it is always appended). Use `key` for the common case
+	 * where identity reduces to a single string.
+	 */
+	key?: (entry: unknown) => string | undefined;
+	/**
+	 * Equivalence predicate: return `true` when `existing` already represents
+	 * `candidate`, suppressing the append. Use when identity cannot be reduced to a
+	 * single string key. When both `key` and `equals` are supplied, `equals` wins.
+	 */
+	equals?: (candidate: unknown, existing: unknown) => boolean;
+}
+
+export interface AppendJsonlIdempotentResult {
+	path: string;
+	/** `true` when the entry was written; `false` when an equivalent entry already existed. */
+	appended: boolean;
+	/** The pre-existing entry that suppressed the append, when `appended` is `false`. */
+	duplicate?: unknown;
+}
+
+async function readJsonlEntries(filePath: string): Promise<unknown[]> {
+	let raw: string;
+	try {
+		raw = await fs.readFile(filePath, "utf-8");
+	} catch (error) {
+		if (isErrno(error, "ENOENT")) return [];
+		throw error;
+	}
+	const entries: unknown[] = [];
+	for (const line of raw.split(/\r?\n/)) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		try {
+			entries.push(JSON.parse(trimmed));
+		} catch {
+			// Best-effort: dedup compares parseable rows only. A corrupt line cannot
+			// be matched, so it never suppresses a new append.
+		}
+	}
+	return entries;
+}
+
+function findJsonlDuplicate(
+	existing: readonly unknown[],
+	candidate: unknown,
+	options: AppendJsonlIdempotentOptions,
+): unknown | undefined {
+	if (options.equals) {
+		const equals = options.equals;
+		return existing.find(item => equals(candidate, item));
+	}
+	const key = options.key;
+	if (!key) return undefined;
+	const candidateKey = key(candidate);
+	if (candidateKey === undefined) return undefined;
+	return existing.find(item => key(item) === candidateKey);
+}
+
+/**
+ * Append `entry` to a JSONL file only when no equivalent entry already exists —
+ * the shared idempotent append primitive (issue #660).
+ *
+ * `appendJsonl` is a pure append with no dedup, so every recurring "duplicate
+ * ledger row" bug (#638, #643, #645) had to be patched with bespoke per-call-site
+ * guards. This primitive centralizes the read-check-append cycle: a caller
+ * declares identity once via `key` or `equals` instead of re-deriving the lookup
+ * at each site.
+ *
+ * The read-then-append is serialized through the same cross-process workflow lock
+ * as `updateJsonAtomic`, so two concurrent idempotent appends cannot both observe
+ * "no duplicate" and both write (the #646 TOCTOU that a plain `appendJsonl`
+ * preceded by a manual existence check is still exposed to).
+ *
+ * Scope note: this dedups the *append* only. Call sites whose idempotency must
+ * also skip a coupled mutation — e.g. the plan/state rewrite in #643/#645 — still
+ * need a whole-operation guard; this primitive is the ledger-level half of that.
+ */
+export async function appendJsonlIdempotent(
+	targetPath: string,
+	entry: unknown,
+	options: AppendJsonlIdempotentOptions,
+): Promise<AppendJsonlIdempotentResult> {
+	if (!options.key && !options.equals) {
+		throw new Error("appendJsonlIdempotent requires a `key` or `equals` option to detect duplicates");
+	}
+	const filePath = resolveGjcTarget(targetPath, cwdForOptions(options));
+	return lockResolvedWorkflowTarget(
+		filePath,
+		async () => {
+			const existing = await readJsonlEntries(filePath);
+			const duplicate = findJsonlDuplicate(existing, entry, options);
+			if (duplicate !== undefined) {
+				return { path: filePath, appended: false, duplicate };
+			}
+			await fs.appendFile(filePath, `${JSON.stringify(entry)}\n`, "utf-8");
+			await maybeAudit(filePath, options);
+			return { path: filePath, appended: true };
+		},
+		options.lock,
+	);
+}
+
 export async function appendText(targetPath: string, text: string, options?: StateWriterOptions): Promise<string> {
 	const filePath = resolveGjcTarget(targetPath, cwdForOptions(options));
 	await fs.mkdir(path.dirname(filePath), { recursive: true });
@@ -639,7 +886,7 @@ export async function hardPrune(
 	const removed: string[] = [];
 	for (const target of targets) {
 		const filePath = resolveGjcTarget(target.path, cwd);
-		let stat: Awaited<ReturnType<typeof fs.stat>>;
+		let stat: Stats;
 		try {
 			stat = await fs.stat(filePath);
 		} catch (error) {

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

@@ -11,6 +11,7 @@ import type { GcCollectResult, GcContext, GcPruneOutcome, GcRecord, GcStoreAdapt
 import { GJC_TMUX_PROFILE_VALUE } from "./tmux-common";
 import {
 	type GjcTmuxSessionStatus,
+	type GjcTmuxSessionsForGc,
 	listTmuxSessionsForGc,
 	readTmuxSessionTagsForGc,
 	removeGjcTmuxSession,
@@ -124,7 +125,7 @@ export const tmuxSessionsGcAdapter: GcStoreAdapter = {
 	async collect(ctx: GcContext): Promise<GcCollectResult> {
 		const records: GcRecord[] = [];
 		const errors: GcCollectResult["errors"] = [];
-		let sessions: ReturnType<typeof listTmuxSessionsForGc>;
+		let sessions: GjcTmuxSessionsForGc;
 		try {
 			sessions = listTmuxSessionsForGc(ctx.env);
 		} catch (error) {

package/src/gjc-runtime/ultragoal-guard.ts

@@ -32,6 +32,16 @@ export interface UltragoalGuardDiagnostic {
 	goalId?: string;
 }
 
+export interface UltragoalAskBlockDiagnostic {
+	active: boolean;
+	reason: string;
+	source: "absent" | "durable_state" | "durable_state_unreadable" | "ledger" | "goals_json";
+	goalsPath?: string;
+	ledgerPath?: string;
+	goalIds?: string[];
+	message: string;
+}
+
 export interface CurrentGoalLike {
 	objective: string;
 	status?: string;
@@ -70,6 +80,48 @@ async function hasDurableUltragoalState(cwd: string): Promise<boolean> {
 	}
 }
 
+function isEnoent(error: unknown): boolean {
+	return (
+		typeof error === "object" && error !== null && "code" in error && (error as { code?: unknown }).code === "ENOENT"
+	);
+}
+
+function activeAskDiagnostic(input: {
+	reason: string;
+	source: UltragoalAskBlockDiagnostic["source"];
+	goalsPath?: string;
+	ledgerPath?: string;
+	goalIds?: string[];
+}): UltragoalAskBlockDiagnostic {
+	return {
+		active: true,
+		reason: input.reason,
+		source: input.source,
+		goalsPath: input.goalsPath,
+		ledgerPath: input.ledgerPath,
+		goalIds: input.goalIds,
+		message: `${input.reason} Use \`gjc ultragoal record-review-blockers\` instead of asking the user.`,
+	};
+}
+
+function inactiveAskDiagnostic(input: {
+	reason: string;
+	source: UltragoalAskBlockDiagnostic["source"];
+	goalsPath?: string;
+	ledgerPath?: string;
+	goalIds?: string[];
+}): UltragoalAskBlockDiagnostic {
+	return {
+		active: false,
+		reason: input.reason,
+		source: input.source,
+		goalsPath: input.goalsPath,
+		ledgerPath: input.ledgerPath,
+		goalIds: input.goalIds,
+		message: input.reason,
+	};
+}
+
 function requiredGoals(plan: UltragoalPlan): UltragoalGoal[] {
 	return plan.goals.filter(goal => goal.status !== "superseded");
 }
@@ -278,6 +330,109 @@ export async function readUltragoalVerificationState(input: {
 	return receiptDiagnostic;
 }
 
+export async function isUltragoalAskBlocked(cwd: string): Promise<UltragoalAskBlockDiagnostic> {
+	const paths = getUltragoalPaths(cwd);
+	try {
+		await fs.stat(paths.dir);
+	} catch (error) {
+		if (isEnoent(error)) {
+			return inactiveAskDiagnostic({
+				reason: "No durable .gjc/ultragoal state exists.",
+				source: "absent",
+				goalsPath: paths.goalsPath,
+				ledgerPath: paths.ledgerPath,
+			});
+		}
+		return activeAskDiagnostic({
+			reason: `Durable .gjc/ultragoal state is present but unreadable: ${error instanceof Error ? error.message : String(error)}`,
+			source: "durable_state_unreadable",
+			goalsPath: paths.goalsPath,
+			ledgerPath: paths.ledgerPath,
+		});
+	}
+
+	let plan: UltragoalPlan | null;
+	let ledger: UltragoalLedgerEvent[];
+	try {
+		plan = await readUltragoalPlan(cwd);
+		ledger = await readUltragoalLedger(cwd);
+	} catch (error) {
+		return activeAskDiagnostic({
+			reason: `Unable to read durable Ultragoal state: ${error instanceof Error ? error.message : String(error)}`,
+			source: "durable_state_unreadable",
+			goalsPath: paths.goalsPath,
+			ledgerPath: paths.ledgerPath,
+		});
+	}
+	if (!plan) {
+		return activeAskDiagnostic({
+			reason: "Durable .gjc/ultragoal state exists but goals.json is missing or empty.",
+			source: "durable_state_unreadable",
+			goalsPath: paths.goalsPath,
+			ledgerPath: paths.ledgerPath,
+		});
+	}
+
+	if (plan.goals.some(goal => goal.status === "review_blocked")) {
+		const goalIds = plan.goals.filter(goal => goal.status === "review_blocked").map(goal => goal.id);
+		return activeAskDiagnostic({
+			reason: `Ultragoal has recorded review blockers: ${goalIds.join(", ")}.`,
+			source: "goals_json",
+			goalsPath: paths.goalsPath,
+			ledgerPath: paths.ledgerPath,
+			goalIds,
+		});
+	}
+
+	const runState = getUltragoalRunCompletionState(plan);
+	if (runState.incompleteGoals.length > 0) {
+		const goalIds = runState.incompleteGoals.map(goal => goal.id);
+		return activeAskDiagnostic({
+			reason: `Ultragoal has incomplete required goals: ${goalIds.join(", ")}.`,
+			source: "goals_json",
+			goalsPath: paths.goalsPath,
+			ledgerPath: paths.ledgerPath,
+			goalIds,
+		});
+	}
+
+	const finalReceiptGoal = [...requiredGoals(plan)]
+		.reverse()
+		.find(goal => goal.completionVerification?.receiptKind === "final-aggregate");
+	if (!finalReceiptGoal) {
+		return activeAskDiagnostic({
+			reason: "Ultragoal aggregate completion is missing a final aggregate receipt.",
+			source: "durable_state",
+			goalsPath: paths.goalsPath,
+			ledgerPath: paths.ledgerPath,
+			goalIds: requiredGoals(plan).map(goal => goal.id),
+		});
+	}
+
+	const diagnostic = validateCompletionReceipt({
+		plan,
+		ledger,
+		goal: finalReceiptGoal,
+		receiptKind: "final-aggregate",
+	});
+	if (diagnostic.state !== "active_verified_complete") {
+		return activeAskDiagnostic({
+			reason: diagnostic.message,
+			source: diagnostic.state === "active_dirty_quality_gate" ? "ledger" : "durable_state",
+			goalsPath: paths.goalsPath,
+			ledgerPath: paths.ledgerPath,
+			goalIds: diagnostic.goalId ? [diagnostic.goalId] : undefined,
+		});
+	}
+	return inactiveAskDiagnostic({
+		reason: "Ultragoal run is verified complete.",
+		source: "durable_state",
+		goalsPath: paths.goalsPath,
+		ledgerPath: paths.ledgerPath,
+		goalIds: [finalReceiptGoal.id],
+	});
+}
+
 export async function assertCanCompleteCurrentGoal(input: {
 	cwd: string;
 	currentGoal?: CurrentGoalLike | null;