@gajae-code/coding-agent 0.16.3 → 0.16.6

package/src/gjc-runtime/empty-delete-gc.ts

@@ -7,11 +7,15 @@ import { randomUUID } from "node:crypto";
 import type { BigIntStats } from "node:fs";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import { exactUnlinkDirect, type NativeExactUnlinkResult } from "@gajae-code/natives";
+import { exactUnlinkDirect, type NativeExactUnlinkResult, snapshotDirectoryTree } from "@gajae-code/natives";
 
 export const EMPTY_DELETE_PREFIX = ".gjc-delete-";
 const EMPTY_DELETE_RECEIPT_PATTERN =
 	/^\.gjc-delete-session-state-lock-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.json$/u;
+// session-storage uses a GC UUID; managed-session-scope uses stableOperationName's
+// SHA-256 plus a numbered attempt. Neither arbitrary labels nor other receipts qualify.
+const EMPTY_ARTIFACT_REMOVAL_ROOT_PATTERN =
+	/^\.gjc-delete-(?:gc-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}-artifacts|[0-9a-f]{64}-artifacts-[1-9]\d*)\.removing$/u;
 const EMPTY_FILE_SHA256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
 
 export interface EmptyDeleteIdentity {
@@ -22,7 +26,7 @@ export interface EmptyDeleteIdentity {
 	mtimeNs: bigint;
 	parentDev: bigint;
 	parentIno: bigint;
-	sha256: string;
+	sha256?: string;
 }
 
 export interface EmptyDeleteGcRecord {
@@ -51,12 +55,15 @@ export interface EmptyDeleteGcReport {
 export interface EmptyDeleteGcOptions {
 	roots: string[];
 	prune: boolean;
+	/** Disk artifact GC must not remove unrelated file receipts. */
+	artifactRootsOnly?: boolean;
 }
 
 export interface EmptyDeleteGcDependencies {
 	/** Internal seam for deterministic collect-to-prune race tests. */
 	collect?: (root: string) => Promise<EmptyDeleteGcRecord[]>;
 	exactUnlinkDirect?: typeof exactUnlinkDirect;
+	rmdir?: (directory: string) => Promise<void>;
 }
 
 function isUnsafeName(name: string): boolean {
@@ -100,6 +107,64 @@ function isEmptyDeleteReceiptName(name: string): boolean {
 	return EMPTY_DELETE_RECEIPT_PATTERN.test(name);
 }
 
+function isEmptyArtifactRemovalRootName(name: string): boolean {
+	return EMPTY_ARTIFACT_REMOVAL_ROOT_PATTERN.test(name);
+}
+
+function artifactRootReason(file: string, stat: BigIntStats): string {
+	if (!stat.isDirectory()) return "not_directory";
+	// The native snapshot opens every component with O_NOFOLLOW and enumerates
+	// with fdopendir/readdir on the retained directory handle. A root-only snapshot
+	// proves zero entries; pathname readdir alone cannot supply that authority.
+	const result = snapshotDirectoryTree(file);
+	if (!result.ok || !result.snapshot) return `entry_unverifiable: ${result.code ?? "unknown"}`;
+	const snapshot = result.snapshot;
+	if (snapshot.rootDev !== stat.dev.toString() || snapshot.rootIno !== stat.ino.toString()) return "identity_drift";
+	return snapshot.entries.length === 1 && snapshot.entries[0].relativePath === ""
+		? "empty_artifact_removal_root"
+		: "non_empty";
+}
+
+async function removeEmptyArtifactRoot(
+	record: EmptyDeleteGcRecord,
+	rmdir: (directory: string) => Promise<void>,
+): Promise<void> {
+	try {
+		const expected = record.identity;
+		if (!expected) {
+			record.action = "kept";
+			record.reason = "identity_missing";
+			return;
+		}
+		const parent = await fs.lstat(path.dirname(record.path), { bigint: true });
+		const stat = await fs.lstat(record.path, { bigint: true });
+		if (
+			!parent.isDirectory() ||
+			parent.dev !== expected.parentDev ||
+			parent.ino !== expected.parentIno ||
+			!stat.isDirectory() ||
+			stat.dev !== expected.dev ||
+			stat.ino !== expected.ino
+		) {
+			record.action = "kept";
+			record.reason = "identity_drift";
+			return;
+		}
+		const reason = artifactRootReason(record.path, stat);
+		if (reason !== "empty_artifact_removal_root") {
+			record.action = "kept";
+			record.reason = reason;
+			return;
+		}
+		// Never recursive: a writer winning after the empty check makes this fail closed.
+		await rmdir(record.path);
+		record.action = "removed";
+	} catch (error) {
+		record.action = "kept";
+		record.reason = `entry_remove_failed: ${error instanceof Error ? error.message : String(error)}`;
+	}
+}
+
 function sameRootIdentity(left: BigIntStats, right: BigIntStats): boolean {
 	return left.isDirectory() && right.isDirectory() && left.dev === right.dev && left.ino === right.ino;
 }
@@ -150,7 +215,7 @@ export async function collectEmptyDeleteReceipts(
 		throw error;
 	}
 	for (const name of names) {
-		if (isUnsafeName(name) || !isEmptyDeleteReceiptName(name)) continue;
+		if (isUnsafeName(name) || (!isEmptyDeleteReceiptName(name) && !isEmptyArtifactRemovalRootName(name))) continue;
 		const file = path.join(resolvedRoot, name);
 		let stat: BigIntStats;
 		try {
@@ -169,6 +234,17 @@ export async function collectEmptyDeleteReceipts(
 			records.push({ root, path: file, action: "kept", reason: "symlink" });
 			continue;
 		}
+		if (isEmptyArtifactRemovalRootName(name)) {
+			const reason = artifactRootReason(file, stat);
+			records.push({
+				root,
+				path: file,
+				action: reason === "empty_artifact_removal_root" ? "would_remove" : "kept",
+				reason,
+				identity: { ...identityOf(stat), parentDev: rootStat.dev, parentIno: rootStat.ino },
+			});
+			continue;
+		}
 		if (!stat.isFile()) {
 			records.push({ root, path: file, action: "kept", reason: "not_regular" });
 			continue;
@@ -232,6 +308,12 @@ export async function runEmptyDeleteGc(
 			continue;
 		}
 		for (const record of records) {
+			if (
+				options.artifactRootsOnly &&
+				record.path !== root &&
+				!isEmptyArtifactRemovalRootName(path.basename(record.path))
+			)
+				continue;
 			if (record.action === "would_remove" && !options.prune) record.observationOnly = true;
 			if (
 				record.action === "skipped" &&
@@ -244,7 +326,15 @@ export async function runEmptyDeleteGc(
 			) {
 				report.errors.push(`${record.path}: ${record.reason}`);
 			}
-			if (record.action === "would_remove" && options.prune) {
+			if (
+				record.action === "would_remove" &&
+				options.prune &&
+				isEmptyArtifactRemovalRootName(path.basename(record.path))
+			) {
+				await removeEmptyArtifactRoot(record, deps.rmdir ?? fs.rmdir);
+				if (record.reason.startsWith("entry_remove_failed:"))
+					report.errors.push(`${record.path}: ${record.reason}`);
+			} else if (record.action === "would_remove" && options.prune) {
 				try {
 					if (!record.identity) {
 						record.action = "kept";

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

@@ -1704,6 +1704,35 @@ async function runGcDiskArtifacts(input: {
 	const sessionIndex = new SessionIndex(agentDir);
 	try {
 		await sessionIndex.withLocked(async () => {
+			// Quarantine roots can outlive every transcript, so enumerate project
+			// directories independently of survivors, under the same index lock.
+			let projects: Dirent[] = [];
+			try {
+				projects = await fsp.readdir(surface.root, { withFileTypes: true });
+			} catch (error) {
+				if (!isEnoent(error))
+					errors.push({ surface: "artifacts", scope: surface.root, message: gcDiskErrorText(error) });
+			}
+			for (const project of projects) {
+				if (!project.isDirectory() || project.isSymbolicLink()) continue;
+				const directory = path.join(surface.root, project.name);
+				const cleanup = await runEmptyDeleteGc({ roots: [directory], prune, artifactRootsOnly: true });
+				for (const message of cleanup.errors) errors.push({ surface: "artifacts", scope: directory, message });
+				for (const receipt of cleanup.records) {
+					const failed = receipt.reason.startsWith("entry_remove_failed:");
+					surface.records.push({
+						surface: "artifacts",
+						id: `${project.name}/${path.basename(receipt.path)}`,
+						path: receipt.path,
+						bytes: 0,
+						age_days: receipt.identity ? gcDiskAgeDays(now, Number(receipt.identity.mtimeNs / 1_000_000n)) : 0,
+						action: receipt.action === "removed" ? "reclaimed" : failed ? "reclaim_failed" : "keep",
+						reason: receipt.reason,
+						...(receipt.action === "kept" || receipt.action === "skipped" ? { withheld: true as const } : {}),
+						...(failed ? { error: receipt.reason } : {}),
+					});
+				}
+			}
 			// Recomputed over survivors: whichever transcript the sessions surface left
 			// newest in a project directory is the `--continue` target, and a resumed
 			// session still reads its own `artifact://` handles.

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

@@ -66,6 +66,20 @@ export function parseLinuxProcState(stat: string | null | undefined): string | n
 	return parseLinuxProcIdentity(stat)?.state ?? null;
 }
 
+/** Parse field 4 (`ppid`) from a `/proc/<pid>/stat` record. */
+export function parseLinuxProcParentPid(stat: string | null | undefined): number | null {
+	if (!stat || stat.includes("\0") || stat.includes("\r")) return null;
+	const record = stat.endsWith("\n") ? stat.slice(0, -1) : stat;
+	const close = record.lastIndexOf(")");
+	if (close < 0) return null;
+	const fields = record
+		.slice(close + 1)
+		.trim()
+		.split(/[ \t]+/);
+	const parentPid = Number.parseInt(fields[1] ?? "", 10);
+	return Number.isSafeInteger(parentPid) && parentPid >= 0 ? parentPid : 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" };

package/src/gjc-runtime/repository-binding.ts

@@ -106,7 +106,7 @@ function normalizeRelativeSubdir(relative: string): string {
 		.replaceAll("\\", "/")
 		.replace(/^\.\/+/u, "")
 		.replace(/\/+$/u, "");
-	if (normalized === "" || normalized === ".") {
+	if (normalized === "") {
 		throw new RepositoryBindingError("invalid_binding", "relativeSubdir must be a non-empty relative path");
 	}
 	if (path.isAbsolute(normalized) || normalized.split("/").includes("..")) {

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

@@ -37,18 +37,20 @@ const EMPTY_FILE_SHA256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca4959
  */
 const LOCK_ACQUIRE_RETRY_MS = 5;
 const LOCK_ACQUIRE_MAX_RETRY_MS = 100;
-const LOCK_ACQUIRE_TIMEOUT_MS = 2_000;
+const LOCK_ACQUIRE_TIMEOUT_MS = 5_000;
 const LOCK_STALE_MS = 30_000;
 const RELEASED_TRANSITION_GRACE_MS = 1_000;
+const SESSION_STATE_LOCK_BUSY = Symbol("session-state-lock-busy");
 
 interface LockRetryBudget {
 	startedAt: number;
 	nextDelayMs: number;
 	attempts: number;
+	nonBlocking: boolean;
 }
 
-function lockRetryBudget(): LockRetryBudget {
-	return { startedAt: performance.now(), nextDelayMs: LOCK_ACQUIRE_RETRY_MS, attempts: 0 };
+function lockRetryBudget(nonBlocking = false): LockRetryBudget {
+	return { startedAt: performance.now(), nextDelayMs: LOCK_ACQUIRE_RETRY_MS, attempts: 0, nonBlocking };
 }
 
 function lockRetryElapsedMs(budget: LockRetryBudget): number {
@@ -146,7 +148,44 @@ interface PendingTransitionRelease {
 	recovery?: Promise<boolean>;
 }
 
+interface LocalTransitionQueue {
+	waiters: Array<() => void>;
+}
+
 const pendingTransitionReleases = new Map<string, PendingTransitionRelease>();
+const localTransitionQueues = new Map<string, LocalTransitionQueue>();
+
+async function joinLocalTransitionQueue(
+	key: string,
+	transitionDir: string,
+	retryBudget?: LockRetryBudget,
+): Promise<LocalTransitionQueue | undefined> {
+	const queue = localTransitionQueues.get(key);
+	if (!queue) return undefined;
+	if (retryBudget?.nonBlocking) throw SESSION_STATE_LOCK_BUSY;
+	const ready = Promise.withResolvers<void>();
+	const queuedAt = performance.now();
+	SessionStateLockTestHooks.afterLocalTransitionQueued?.(transitionDir);
+	queue.waiters.push(ready.resolve);
+	await ready.promise;
+	if (retryBudget) retryBudget.startedAt += Math.max(0, performance.now() - queuedAt);
+	return queue;
+}
+
+function claimLocalTransitionQueue(key: string): LocalTransitionQueue {
+	const queue: LocalTransitionQueue = { waiters: [] };
+	localTransitionQueues.set(key, queue);
+	return queue;
+}
+
+function releaseLocalTransitionQueue(key: string, queue: LocalTransitionQueue): void {
+	const next = queue.waiters.shift();
+	if (next) {
+		next();
+		return;
+	}
+	if (localTransitionQueues.get(key) === queue) localTransitionQueues.delete(key);
+}
 
 function clearPendingTransitionRelease(key: string, pending?: PendingTransitionRelease): void {
 	const current = pendingTransitionReleases.get(key);
@@ -413,6 +452,8 @@ export const SessionStateLockTestHooks: {
 	forcedQuarantineName?: string;
 	/** @internal Observes bounded acquisition retries without changing their timing. */
 	afterAcquireContention?: (lockFile: string, attempt: number, elapsedMs: number) => void;
+	/** @internal Observes process-local admission without altering on-disk ownership. */
+	afterLocalTransitionQueued?: (transitionDir: string) => void;
 	/** @internal Runs after transition mkdir contention and before stale-claim inspection. */
 	afterTransitionClaimContention?: (transitionDir: string) => void | Promise<void>;
 } = {};
@@ -1781,6 +1822,7 @@ async function recoverPendingTransitionRelease(
 	transitionDir: string,
 	recoveryKey: string,
 	quarantineName: string,
+	nonBlocking = false,
 ): Promise<boolean> {
 	let pendingKey = recoveryKey;
 	let pending = pendingTransitionReleases.get(pendingKey);
@@ -1813,7 +1855,10 @@ async function recoverPendingTransitionRelease(
 	// for a contender while that release is still in progress. The owner that armed
 	// it flips this bit only when a phase actually throws.
 	if (!pending.recoverable) return false;
-	if (pending.recovery) return await pending.recovery;
+	if (pending.recovery) {
+		if (nonBlocking) throw SESSION_STATE_LOCK_BUSY;
+		return await pending.recovery;
+	}
 	const recovery = (async (): Promise<boolean> => {
 		const ownerFile = `${transitionDir}.owner`;
 		if (!pending.generation) {
@@ -1993,7 +2038,14 @@ async function recoverPendingTransitionRelease(
 	}
 }
 
-/** Run one pathname transition under an atomic `mkdir`/`rmdir` claim. */
+/**
+ * Run one pathname transition under an atomic `mkdir`/`rmdir` claim.
+ *
+ * Same-process contenders join the current claim owner's lifetime before consuming their
+ * bounded filesystem-contention budget. The on-disk protocol remains authoritative across
+ * processes; this queue only prevents a descheduled local owner from timing out its own
+ * successor while it still legitimately holds the claim.
+ */
 async function withLockPathTransition<T>(
 	lockFile: string,
 	transition: () => Promise<T>,
@@ -2003,25 +2055,75 @@ async function withLockPathTransition<T>(
 	if (ownerAccessStrategy() === "unsupported")
 		throw new SessionStateLockUnavailableError(new Error("Safe transition ownership is unsupported."));
 	const transitionDir = `${lockFile}${LOCK_TRANSITION_RESOURCE_SUFFIX}`;
-	const ownerFile = `${transitionDir}.owner`;
 	const recoveryKey = await transitionRecoveryKey(transitionDir);
+	const localKey = recoveryKey;
 	const owner = await newLockOwner();
 	const budget = retryBudget ?? lockRetryBudget();
+	let localTurn = await joinLocalTransitionQueue(localKey, transitionDir, budget);
+	const claimLocalTurn = (): void => {
+		localTurn ??= claimLocalTransitionQueue(localKey);
+	};
+	const joinLocalTurn = async (): Promise<boolean> => {
+		if (localTurn) return false;
+		const joined = await joinLocalTransitionQueue(localKey, transitionDir, budget);
+		if (!joined) return false;
+		localTurn = joined;
+		return true;
+	};
+	try {
+		return await runLockPathTransition(
+			lockFile,
+			recoveryKey,
+			owner,
+			budget,
+			claimLocalTurn,
+			joinLocalTurn,
+			transition,
+			quarantineName,
+		);
+	} finally {
+		if (localTurn) releaseLocalTransitionQueue(localKey, localTurn);
+	}
+}
+
+async function runLockPathTransition<T>(
+	lockFile: string,
+	recoveryKey: string,
+	owner: SessionStateLockOwner,
+	budget: LockRetryBudget,
+	claimLocalTurn: () => void,
+	joinLocalTurn: () => Promise<boolean>,
+	transition: () => Promise<T>,
+	quarantineName = lockQuarantineName(),
+): Promise<T> {
+	if (ownerAccessStrategy() === "unsupported")
+		throw new SessionStateLockUnavailableError(new Error("Safe transition ownership is unsupported."));
+	const transitionDir = `${lockFile}${LOCK_TRANSITION_RESOURCE_SUFFIX}`;
+	const ownerFile = `${transitionDir}.owner`;
+
 	for (;;) {
 		if (ownerAccessStrategy() === "unsupported" && fsSync.existsSync(transitionDir))
 			throw new SessionStateLockUnavailableError(new Error("Safe transition ownership is unsupported."));
-		if (await recoverPendingTransitionRelease(transitionDir, recoveryKey, quarantineName)) {
+		if (await recoverPendingTransitionRelease(transitionDir, recoveryKey, quarantineName, budget.nonBlocking)) {
 			// The claim this process stranded in an earlier failed release is gone;
 			// fall through and retry the mkdir immediately.
 		}
+		if (await joinLocalTurn()) continue;
 		try {
 			await fs.mkdir(transitionDir, { mode: 0o700 });
+			claimLocalTurn();
 			await fs.chmod(transitionDir, 0o700);
 		} catch (error) {
 			const code = (error as NodeJS.ErrnoException).code;
-			if (code !== "EEXIST" && !isTransientLockError(error)) throw new SessionStateLockUnavailableError(error);
+			if (code !== "EEXIST" && (budget.nonBlocking || !isTransientLockError(error)))
+				throw new SessionStateLockUnavailableError(error);
+			if (await joinLocalTurn()) continue;
 			await SessionStateLockTestHooks.afterTransitionClaimContention?.(transitionDir);
-			if (await reclaimStaleTransitionClaim(transitionDir, quarantineName)) {
+			const reclaimed = await reclaimStaleTransitionClaim(transitionDir, quarantineName);
+			// One safe reclaim may make progress, but a try-acquire never follows a
+			// succession of contenders. A later maintenance pass can take the freed claim.
+			if (budget.nonBlocking) throw SESSION_STATE_LOCK_BUSY;
+			if (reclaimed) {
 				if (lockRetryExhausted(budget))
 					throw lockUnavailable(transitionDir, "transition_claim_timeout", budget, error);
 				continue;
@@ -2461,8 +2563,33 @@ export async function reclaimStaleSessionStateLock(lockFile: string, quarantineN
  * lock file itself and may run for as long as it needs.
  */
 export async function withSessionStateFileLock<T>(stateFile: string, operation: () => Promise<T>): Promise<T> {
+	return await runWithSessionStateFileLock(stateFile, operation, lockRetryBudget());
+}
+
+/**
+ * Try one admission without joining a live owner's queue or backing off on contention.
+ * A stale reclaim may return `acquired: false` after making the next attempt possible.
+ * Once admitted, the operation and identity-safe release use the normal lock protocol;
+ * their failures propagate rather than being reported as contention.
+ */
+export async function tryWithSessionStateFileLock<T>(
+	stateFile: string,
+	operation: () => Promise<T>,
+): Promise<{ acquired: true; value: T } | { acquired: false }> {
+	try {
+		return { acquired: true, value: await runWithSessionStateFileLock(stateFile, operation, lockRetryBudget(true)) };
+	} catch (error) {
+		if (error === SESSION_STATE_LOCK_BUSY) return { acquired: false };
+		throw error;
+	}
+}
+
+async function runWithSessionStateFileLock<T>(
+	stateFile: string,
+	operation: () => Promise<T>,
+	budget: LockRetryBudget,
+): Promise<T> {
 	const lockFile = `${stateFile}.lock`;
-	const budget = lockRetryBudget();
 	let owner: SessionStateLockOwner;
 	try {
 		owner = await newLockOwner();
@@ -2518,6 +2645,11 @@ export async function withSessionStateFileLock<T>(stateFile: string, operation:
 			if (callbackFailure && error === callbackError) throw error;
 			// A fault after the lock was taken belongs to the operation, not to acquisition.
 			if (held) throw lockDiagnostic(error, lockFile, "lock_release_failed");
+			if (error === SESSION_STATE_LOCK_BUSY) throw error;
+			// Typed protocol failures include transition setup/release faults. A
+			// try-acquire must not downgrade those into a successful busy response.
+			if (budget.nonBlocking && error instanceof SessionStateLockUnavailableError)
+				throw lockDiagnostic(error, lockFile, "lock_inspection_failed", budget);
 			// Without a safe owner-record access strategy, retrying cannot make the
 			// transition claim removable. Preserve it as a fail-closed fence instead
 			// of spinning until the acquisition budget expires.
@@ -2540,6 +2672,7 @@ export async function withSessionStateFileLock<T>(stateFile: string, operation:
 			);
 			if (reclaim === "owner_unprovenanced")
 				throw lockUnavailable(lockFile, "lock_owner_record_unprovenanced", budget);
+			if (budget.nonBlocking) throw SESSION_STATE_LOCK_BUSY;
 			if (reclaim === "legacy_directory_unprovenanced") lastReason = "legacy_directory_owner_unprovenanced";
 			else if (reclaim === "owner_live_or_unverifiable") lastReason = "lock_owner_live_or_unverifiable";
 			else if (reclaim === "owner_record_fresh") lastReason = "lock_owner_record_fresh";

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

@@ -1004,9 +1004,13 @@ export function eventAffectsCoordinatorRuntimeState(event: RuntimeStateEvent): b
 }
 
 class PreviousRuntimeStateReadError extends Error {
-	constructor(cause?: unknown) {
+	constructor(cause?: unknown, detail?: string) {
 		const lockDetail = cause instanceof SessionStateLockUnavailableError ? ` ${cause.message}` : "";
-		super(`Existing runtime state marker is invalid or unreadable; refusing to overwrite.${lockDetail}`);
+		super(
+			detail
+				? `Existing runtime state marker violates the lifecycle contract: ${detail}; refusing to overwrite.`
+				: `Existing runtime state marker is invalid or unreadable; refusing to overwrite.${lockDetail}`,
+		);
 		this.name = "PreviousRuntimeStateReadError";
 		if (cause !== undefined) this.cause = cause;
 	}
@@ -1016,7 +1020,7 @@ class PreviousRuntimeStateReadError extends Error {
  * A readable, well-formed marker recorded against a different workspace path.
  *
  * Separate from {@link PreviousRuntimeStateReadError} because the two demand different
- * operator responses: an unreadable marker points at file damage, while a foreign marker
+ * operator responses: an invalid marker points at file damage or lifecycle contradictions, while a foreign marker
  * points at the same session directory being reachable from two checkouts.
  */
 class ForeignRuntimeStateError extends Error {
@@ -1084,11 +1088,29 @@ function isAbsentStateFileError(error: unknown): boolean {
 
 function parsePreviousPayload(raw: string): Record<string, unknown> {
 	const payload: unknown = JSON.parse(raw);
-	if (!validPreviousRuntimeStatePayload(payload)) throw new PreviousRuntimeStateReadError();
+	if (!validPreviousRuntimeStateShape(payload)) throw new PreviousRuntimeStateReadError();
+	// Structural validation above bounds every interpolated value to a known state
+	// or boolean; never include arbitrary marker contents in a terminal diagnostic.
+	if (payload.ready_for_input !== undefined) {
+		const expectedReady = payload.state === "ready_for_input";
+		if (payload.ready_for_input !== expectedReady)
+			throw new PreviousRuntimeStateReadError(
+				undefined,
+				`ready_for_input must be ${expectedReady} when state is ${payload.state} (received ${payload.ready_for_input})`,
+			);
+	}
+	if (payload.live !== undefined && payload.live !== null) {
+		const expectedLive = payload.state === "running";
+		if (payload.live !== expectedLive)
+			throw new PreviousRuntimeStateReadError(
+				undefined,
+				`live must be ${expectedLive} when state is ${payload.state} (received ${payload.live})`,
+			);
+	}
 	return payload;
 }
 
-function validPreviousRuntimeStatePayload(value: unknown): value is Record<string, unknown> {
+function validPreviousRuntimeStateShape(value: unknown): value is Record<string, unknown> {
 	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
 	const payload = value as Record<string, unknown>;
 	if (
@@ -1125,12 +1147,6 @@ function validPreviousRuntimeStatePayload(value: unknown): value is Record<strin
 		(typeof payload.updated_at !== "string" || !Number.isFinite(Date.parse(payload.updated_at)))
 	)
 		return false;
-	if (payload.ready_for_input !== undefined) {
-		const expectedReady = payload.state === "ready_for_input";
-		if (payload.ready_for_input !== expectedReady) return false;
-	}
-	if (payload.live !== undefined && payload.live !== null && payload.live !== (payload.state === "running"))
-		return false;
 	return true;
 }
 

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

@@ -533,40 +533,41 @@ async function writeGuardedResolvedJsonAtomic(
 	value: unknown,
 	options: GuardedStateWriterOptions,
 ): Promise<GuardedWriteResult> {
-	return lockResolvedWorkflowTarget(
-		filePath,
-		async () => {
-			const current = await readJsonIfPresentTolerant(filePath);
-			const currentRevision = persistedStateRevision(current);
-
-			if (options.policy === "source") {
-				if (options.expectedRevision !== undefined && options.expectedRevision !== currentRevision) {
-					throw new StateWriteConflictError(filePath, options.expectedRevision, currentRevision);
-				}
-				const next = stampStateRevision(withWorkflowReceipt(value, buildReceipt(options)), currentRevision + 1);
-				await atomicWrite(filePath, jsonText(next));
-				await maybeAudit(filePath, options);
-				return { path: filePath, written: true, revision: currentRevision + 1, stamped: next };
-			}
+	const write = async (): Promise<GuardedWriteResult> => {
+		const current = await readJsonIfPresentTolerant(filePath);
+		const currentRevision = persistedStateRevision(current);
 
-			const valueSourceRevision = isPlainObject(value) ? persistedSourceRevision(value) : 0;
-			const incomingSourceRevision =
-				options.sourceRevision ??
-				(valueSourceRevision || (options.advanceSourceRevision ? persistedSourceRevision(current) + 1 : 0));
-			if (current !== undefined && incomingSourceRevision <= persistedSourceRevision(current)) {
-				return { path: filePath, written: false, reason: "stale-skip", revision: currentRevision };
+		if (options.policy === "source") {
+			if (options.expectedRevision !== undefined && options.expectedRevision !== currentRevision) {
+				throw new StateWriteConflictError(filePath, options.expectedRevision, currentRevision);
 			}
-			const next = stampStateRevision(
-				withWorkflowReceipt(value, buildReceipt(options)),
-				currentRevision + 1,
-				incomingSourceRevision,
-			);
+			const next = stampStateRevision(withWorkflowReceipt(value, buildReceipt(options)), currentRevision + 1);
 			await atomicWrite(filePath, jsonText(next));
 			await maybeAudit(filePath, options);
 			return { path: filePath, written: true, revision: currentRevision + 1, stamped: next };
-		},
-		options.lock,
-	);
+		}
+
+		const valueSourceRevision = isPlainObject(value) ? persistedSourceRevision(value) : 0;
+		const incomingSourceRevision =
+			options.sourceRevision ??
+			(valueSourceRevision || (options.advanceSourceRevision ? persistedSourceRevision(current) + 1 : 0));
+		if (current !== undefined && incomingSourceRevision <= persistedSourceRevision(current)) {
+			return { path: filePath, written: false, reason: "stale-skip", revision: currentRevision };
+		}
+		const next = stampStateRevision(
+			withWorkflowReceipt(value, buildReceipt(options)),
+			currentRevision + 1,
+			incomingSourceRevision,
+		);
+		await atomicWrite(filePath, jsonText(next));
+		await maybeAudit(filePath, options);
+		return { path: filePath, written: true, revision: currentRevision + 1, stamped: next };
+	};
+	// `withFileLock` deliberately serializes same-process callers too, so a caller
+	// that already holds this target's lock (via `withWorkflowStateLock`) must say
+	// so rather than deadlocking against itself — the same `lockHeld` contract the
+	// envelope writers already use.
+	return options.lockHeld ? write() : lockResolvedWorkflowTarget(filePath, write, options.lock);
 }
 
 export async function writeGuardedJsonAtomic(