@gajae-code/coding-agent 0.16.4 → 0.16.6

package/src/extensibility/skills.ts

@@ -1,5 +1,11 @@
 import * as fs from "node:fs/promises";
-import { getProjectDir, getTrustedHomeDir } from "@gajae-code/utils";
+import {
+	getAgentDir,
+	getAgentProfileAuthority,
+	getProjectDir,
+	getTrustedHomeDir,
+	normalizePathForComparison,
+} from "@gajae-code/utils";
 import { findRepoRoot } from "../capability/fs";
 import { skillCapability } from "../capability/skill";
 import type { SourceMeta } from "../capability/types";
@@ -7,9 +13,12 @@ import type { SkillsSettings } from "../config/settings";
 import { resolveSkillScopeTrust } from "../config/skill-settings-defaults";
 import { type Skill as CapabilitySkill, getCapability } from "../discovery";
 import { loadMarketplaceSkills } from "../discovery/claude-plugins";
-import { compareSkillOrder, scanSkillsFromDir } from "../discovery/helpers";
+import { compareSkillOrder, resolveUserAgentDir, scanSkillsFromDir } from "../discovery/helpers";
 import type { SkillPromptDetails } from "../session/messages";
-import { CANONICAL_GJC_WORKFLOW_SKILLS } from "../skill-state/canonical-skills";
+import {
+	getSkillFilesystemIdentity,
+	isCanonicalGjcWorkflowSkillFilesystemAlias,
+} from "../skill-state/canonical-skills";
 import { expandTilde } from "../tools/path-utils";
 import type { LoadedSubskillActivation } from "./gjc-plugins";
 import { buildSubskillInjection } from "./gjc-plugins/injection";
@@ -114,6 +123,8 @@ export interface LoadSkillsOptions extends SkillsSettings {
 	home?: string;
 	/** Explicit user agent directory for native user-scope skill discovery. */
 	agentDir?: string;
+	/** Resolver-owned classification for the selected agent directory. */
+	profileAuthority?: "default" | "custom";
 }
 
 /**
@@ -124,8 +135,6 @@ export interface LoadSkillsOptions extends SkillsSettings {
  */
 const LOADABLE_SKILL_PROVIDERS = new Set(["native", "claude-plugins"]);
 
-const BUILT_IN_SKILL_NAMES = new Set<string>(CANONICAL_GJC_WORKFLOW_SKILLS.map(name => name.toLowerCase()));
-
 /**
  * Load skills from all configured locations.
  * Returns skills and any validation warnings.
@@ -144,7 +153,17 @@ export async function loadSkills(options: LoadSkillsOptions = {}): Promise<LoadS
 	if (!enabled) {
 		return { skills: [], warnings: [] };
 	}
+	const homeWasInjected = options.home !== undefined;
 	const home = options.home ?? getTrustedHomeDir();
+	const agentDir = options.agentDir ?? (homeWasInjected ? resolveUserAgentDir(home) : getAgentDir());
+	const profileAuthority =
+		options.profileAuthority ??
+		(!homeWasInjected
+			? options.agentDir !== undefined &&
+				normalizePathForComparison(options.agentDir) !== normalizePathForComparison(getAgentDir())
+				? "custom"
+				: getAgentProfileAuthority()
+			: undefined);
 
 	const projectTrusted = resolveSkillScopeTrust(options, "project");
 	const userTrusted = resolveSkillScopeTrust(options, "user");
@@ -175,7 +194,8 @@ export async function loadSkills(options: LoadSkillsOptions = {}): Promise<LoadS
 	const loadContext = {
 		cwd,
 		home,
-		userAgentDir: options.agentDir,
+		userAgentDir: agentDir,
+		profileAuthority,
 		repoRoot: await findRepoRoot(cwd),
 	};
 	const providerResults = await Promise.all(
@@ -258,14 +278,14 @@ export async function loadSkills(options: LoadSkillsOptions = {}): Promise<LoadS
 		// workflow-routing hijack: warn, and let the session merge keep the bundled
 		// definition authoritative (sdk/session.ts). User-scope copies are not
 		// warned about: installed defaults legitimately mirror bundled skills.
-		if (capSkill.level === "project" && BUILT_IN_SKILL_NAMES.has(capSkill.name.toLowerCase())) {
+		if (capSkill.level === "project" && isCanonicalGjcWorkflowSkillFilesystemAlias(capSkill.name)) {
 			collisionWarnings.push({
 				skillPath: capSkill.path,
 				message: `name collision: "${capSkill.name}" is a bundled GJC workflow skill; the bundled definition takes precedence in sessions and this project copy is never used`,
 			});
 		}
 
-		const skillKey = capSkill.name.toLowerCase();
+		const skillKey = getSkillFilesystemIdentity(capSkill.name);
 		const existing = skillMap.get(skillKey);
 		if (existing) {
 			collisionWarnings.push({
@@ -342,7 +362,7 @@ export async function loadSkills(options: LoadSkillsOptions = {}): Promise<LoadS
 		const resolvedPath = customRealPaths[i];
 		if (realPathSet.has(resolvedPath)) continue;
 
-		const skillKey = skill.name.toLowerCase();
+		const skillKey = getSkillFilesystemIdentity(skill.name);
 		const existing = skillMap.get(skillKey);
 		if (existing) {
 			collisionWarnings.push({

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/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 {
@@ -160,6 +162,7 @@ async function joinLocalTransitionQueue(
 ): 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);
@@ -1819,6 +1822,7 @@ async function recoverPendingTransitionRelease(
 	transitionDir: string,
 	recoveryKey: string,
 	quarantineName: string,
+	nonBlocking = false,
 ): Promise<boolean> {
 	let pendingKey = recoveryKey;
 	let pending = pendingTransitionReleases.get(pendingKey);
@@ -1851,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) {
@@ -2097,7 +2104,7 @@ async function runLockPathTransition<T>(
 	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.
 		}
@@ -2108,10 +2115,15 @@ async function runLockPathTransition<T>(
 			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;
@@ -2551,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();
@@ -2608,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.
@@ -2630,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(