@gajae-code/coding-agent 0.17.2 → 0.17.4

package/src/coordinator-mcp/session-reaper.ts

@@ -57,10 +57,12 @@ export function selectReapableSessions(
 /**
  * Only a stale/absent endpoint makes a session permanently unreapable, so it is
  * the sole failure that advances the force-eviction counter. Every other reap
- * failure (close_failed, broker unavailability, filesystem errors) is transient
- * and must keep retrying without ever escalating to force eviction. The server
- * wires `reapSession` to throw `new Error(reason)`, so the reason code is the
- * error message here.
+ * failure (a close_failed without a stale endpoint, broker unavailability,
+ * filesystem errors) is transient and must keep retrying without ever escalating
+ * to force eviction. The server wires `reapSession` to throw `new Error(reason)`,
+ * except that a close the broker answered with endpoint_stale (close_failed with
+ * that detail) is thrown as endpoint_stale, so the reason code is the error
+ * message here.
  */
 function isEndpointStaleReapError(err: unknown): boolean {
 	return (err instanceof Error ? err.message : String(err)) === "endpoint_stale";

package/src/crash/record-loader.ts

@@ -17,6 +17,7 @@ import {
 	type CrashFingerprint,
 	type CrashProvenance,
 	computeCrashFingerprint,
+	computeHandledErrorFingerprint,
 	parseCrashRecordMarker,
 } from "@gajae-code/utils";
 
@@ -60,8 +61,11 @@ function findBoundFingerprint(
 			// suffix omission against the marker rather than trusting its syntax.
 			if (remaining.length > 0) stackCandidates.push(remaining.slice(0, -1).join("\n").trimEnd());
 			for (const stack of stackCandidates) {
-				const fingerprint = computeCrashFingerprint({ name, message, stack });
-				if (fingerprint.fingerprint === markerFingerprint) return fingerprint;
+				const input = { name, message, stack };
+				const fatalFingerprint = computeCrashFingerprint(input);
+				if (fatalFingerprint.fingerprint === markerFingerprint) return fatalFingerprint;
+				const handledFingerprint = computeHandledErrorFingerprint(input);
+				if (handledFingerprint.fingerprint === markerFingerprint) return handledFingerprint;
 			}
 		}
 	}

package/src/daemon/operator-contract.ts

@@ -12,6 +12,8 @@
  * (automation); the default human output stays a concise per-daemon result.
  */
 
+import { replaceTabs, truncateToWidth } from "@gajae-code/tui";
+import { sanitizeDisplayLine } from "@gajae-code/utils";
 import type { DaemonAction, DaemonOperationResult, DaemonRecovery, DaemonStatus } from "./control-types";
 
 /** Canonical daemon actions accepted as the leading verb. */
@@ -39,8 +41,14 @@ export function resolveDaemonAction(token: string | undefined): DaemonAction | u
 	return DAEMON_ACTION_ALIASES[token];
 }
 
-/** Exit codes for `gjc daemon`. Backward compatible: success 0, any failure 1. */
-export const DAEMON_EXIT = { ok: 0, failure: 1 } as const;
+/** Public input failures exit 2; operational failures retain exit 1. */
+export const DAEMON_EXIT = { ok: 0, failure: 1, usage: 2 } as const;
+
+/** A refused result may follow a successful stop or spawn; snapshots and prose
+ * do not prove that no effect occurred. Only completed results prove applied. */
+export function daemonOperationOutcome(result: DaemonOperationResult): "applied" | "unknown" {
+	return result.ok ? "applied" : "unknown";
+}
 
 /** Human-facing headline when a spawn/reload is refused by a live foreign identity. */
 export const OWNERSHIP_MISMATCH_MESSAGE =
@@ -59,6 +67,10 @@ export function ownershipMismatchRecovery(): DaemonRecovery {
 	};
 }
 
+function safeDaemonText(value: string): string {
+	return truncateToWidth(replaceTabs(sanitizeDisplayLine(value).replaceAll(/[\u2028\u2029]/gu, " ")), 512);
+}
+
 function timestamp(ms: number | undefined): string | undefined {
 	if (ms === undefined) return undefined;
 	const date = new Date(ms);
@@ -73,31 +85,31 @@ export function formatDaemonStatus(status: DaemonStatus, opts: { verbose?: boole
 	const lines: string[] = [];
 	if (!status.configured) {
 		lines.push(`${status.kind}: not configured`);
-		if (status.runtime.warning) lines.push(`  warning: ${status.runtime.warning}`);
+		if (status.runtime.warning) lines.push(`  warning: ${safeDaemonText(status.runtime.warning)}`);
 		return lines.join("\n");
 	}
 
 	const meta: string[] = [];
 	if (status.pid !== undefined) meta.push(`pid ${status.pid}`);
-	if (status.ownerId) meta.push(`owner ${status.ownerId}`);
+	if (status.ownerId) meta.push(`owner ${safeDaemonText(status.ownerId)}`);
 	const rootCount = status.rootCount ?? status.roots?.length ?? 0;
 	if (rootCount > 0) meta.push(`${rootCount} root${rootCount === 1 ? "" : "s"}`);
 
 	let head = `${status.kind}: ${status.health}`;
 	if (meta.length > 0) head += ` (${meta.join(", ")})`;
-	if (status.detail) head += ` — ${status.detail}`;
+	if (status.detail) head += ` — ${safeDaemonText(status.detail)}`;
 	lines.push(head);
-	if (status.runtime.warning) lines.push(`  warning: ${status.runtime.warning}`);
+	if (status.runtime.warning) lines.push(`  warning: ${safeDaemonText(status.runtime.warning)}`);
 
 	if (opts.verbose) {
-		lines.push(`  runtime: ${status.runtime.mode} (${status.runtime.execPath})`);
+		lines.push(`  runtime: ${status.runtime.mode} (${safeDaemonText(status.runtime.execPath)})`);
 		const started = timestamp(status.startedAt);
 		if (started) lines.push(`  started: ${started}`);
 		const heartbeat = timestamp(status.heartbeatAt);
 		if (heartbeat) lines.push(`  heartbeat: ${heartbeat}`);
 		const roots = status.roots ?? [];
 		lines.push(`  roots: ${rootCount}`);
-		for (const root of roots) lines.push(`    - ${root}`);
+		for (const root of roots) lines.push(`    - ${safeDaemonText(root)}`);
 	}
 
 	return lines.join("\n");
@@ -108,13 +120,15 @@ export function formatDaemonStatus(status: DaemonStatus, opts: { verbose?: boole
  * <message>` head line, then any warnings, then actionable recovery steps.
  */
 export function formatDaemonResult(result: DaemonOperationResult): string {
-	const lines = [`${result.kind} ${result.action}: ${result.ok ? "ok" : "failed"} — ${result.message}`];
-	for (const warning of result.warnings) lines.push(`  warning: ${warning}`);
+	const lines = [
+		`${result.kind} ${result.action}: ${result.ok ? "ok" : "failed"} — ${safeDaemonText(result.message)}`,
+	];
+	for (const warning of result.warnings) lines.push(`  warning: ${safeDaemonText(warning)}`);
 	if (result.recovery) {
-		lines.push(`  ${result.recovery.summary}`);
+		lines.push(`  ${safeDaemonText(result.recovery.summary)}`);
 		lines.push("  to recover:");
 		result.recovery.steps.forEach((step, i) => {
-			lines.push(`    ${i + 1}. ${step}`);
+			lines.push(`    ${i + 1}. ${safeDaemonText(step)}`);
 		});
 	}
 	return lines.join("\n");

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

@@ -458,7 +458,7 @@ Because unselected goals stay schedulable, ordinary source progress moves whole-
 
 `adopt` runs in the target repository and starts a genuinely fresh run: new pending goals, fresh timestamps, the target repository's own binding, and no inherited receipts, quality gates, validation batches, steering or activated objective. The source brief and every selected objective are carried verbatim, together with the unresolved obligations recorded against those goals — requirements are carried forward in full, never summarized down. Dependency groups travel as explicit obligations with source-to-target id mapping: the source's batch metadata and receipts are not inherited, but the requirement to validate those goals together is.
 
-Selection and authorization must be explicit. Only unfinished goals (`pending`, `failed`, `blocked`, `review_blocked`) may be handed off; the source run must be quiescent with no `active` goal; there is no implicit or wildcard selection; and a selection that takes only part of a validation batch, or splits a review blocker from the goal it still blocks, is rejected rather than silently dropping that obligation. Adoption fails closed on changed offered work, an altered or unfenced offer, an offer path that escapes the source worktree, a target the offer does not name, a linked worktree that is not the exact named target, an occupied target session, and any duplicate or simultaneous adoption anywhere in the target repository. A retry reconciles the exact recorded operation or fails closed — a matching operation id is never authority to overwrite target work it did not write, and a published plan that has disappeared is never reconstructed.
+Selection and authorization must be explicit. Only unfinished goals (`pending`, `failed`, `blocked`, `review_blocked`) may be handed off; the source run must be quiescent with no `active` goal; there is no implicit or wildcard selection; and a selection that takes only part of a validation batch, or splits a review blocker from the goal it still blocks, is rejected rather than silently dropping that obligation. Adoption fails closed on changed offered work, an altered or unfenced offer, an offer path that escapes the source worktree, a target the offer does not name, a different linked worktree from the exact named target, an occupied target session, and any duplicate or simultaneous adoption anywhere in the target repository. A linked worktree is a valid target when the offer names that exact worktree; the source and target may therefore be sibling worktrees, but aliases of the same source worktree remain self-transfers and are rejected using physical path identity, and an unavailable bound worktree root is refused rather than compared lexically. A retry reconciles the exact recorded operation or fails closed — a matching operation id is never authority to overwrite target work it did not write, and a published plan that has disappeared is never reconstructed.
 
 Until publication completes, the target refuses to execute: a visible `goals.json` is not admission evidence, the adoption record is. `start`/`complete-goals` and `checkpoint` reject while an adoption remains pending.
 

package/src/eval/js/context-manager.ts

@@ -1,4 +1,5 @@
 import { isCompiledBinary, logger, Snowflake } from "@gajae-code/utils";
+import { isDesignedError } from "@gajae-code/utils/error-classification";
 import { registerResourceOwner } from "../../runtime/process-lifecycle";
 import type { ToolSession } from "../../tools";
 import { ToolAbortError, ToolError } from "../../tools/tool-errors";
@@ -460,13 +461,11 @@ function reasonToError(reason: unknown, fallback: string): Error {
 }
 
 function errorFromPayload(payload: RunErrorPayload): Error {
-	if (payload.isAbort) {
-		const err = new ToolAbortError(payload.message || "Execution aborted");
-		if (payload.stack) err.stack = payload.stack;
-		return err;
-	}
-	const ctor = payload.isToolError ? ToolError : Error;
-	const error = new ctor(payload.message);
+	const error = payload.isDesigned
+		? payload.isAbort
+			? new ToolAbortError(payload.message || "Execution aborted")
+			: new ToolError(payload.message)
+		: new Error(payload.message);
 	if (payload.name) error.name = payload.name;
 	if (payload.stack) error.stack = payload.stack;
 	return error;
@@ -479,7 +478,8 @@ function toErrorPayload(error: unknown): RunErrorPayload {
 			message: error.message,
 			stack: error.stack,
 			isAbort: error.name === "AbortError" || error.name === "ToolAbortError",
-			isToolError: error instanceof ToolError || error.name === "ToolError",
+			isToolError: error instanceof ToolError,
+			isDesigned: isDesignedError(error),
 		};
 	}
 	return { message: String(error) };

package/src/eval/js/worker-core.ts

@@ -1,4 +1,5 @@
-import { ToolError } from "../../tools/tool-errors";
+import { isDesignedError } from "@gajae-code/utils/error-classification";
+import { ToolAbortError, ToolError } from "../../tools/tool-errors";
 import { JsRuntime, type RuntimeHooks } from "./shared/runtime";
 import type { RunErrorPayload, SessionSnapshot, ToolReply, Transport, WorkerInbound } from "./worker-protocol";
 
@@ -24,15 +25,19 @@ function errorPayload(error: unknown): RunErrorPayload {
 			message: error.message,
 			stack: error.stack,
 			isAbort: error.name === "AbortError" || error.name === "ToolAbortError",
-			isToolError: error.name === "ToolError" || error instanceof ToolError,
+			isToolError: error instanceof ToolError,
+			isDesigned: isDesignedError(error),
 		};
 	}
 	return { message: String(error) };
 }
 
 function errorFromPayload(payload: RunErrorPayload): Error {
-	const ctor = payload.isToolError ? ToolError : Error;
-	const error = new ctor(payload.message);
+	const error = payload.isDesigned
+		? payload.isAbort
+			? new ToolAbortError(payload.message)
+			: new ToolError(payload.message)
+		: new Error(payload.message);
 	if (payload.name) error.name = payload.name;
 	if (payload.stack) error.stack = payload.stack;
 	return error;

package/src/eval/js/worker-protocol.ts

@@ -13,6 +13,8 @@ export interface RunErrorPayload {
 	stack?: string;
 	isAbort?: boolean;
 	isToolError?: boolean;
+	/** Set only when the originating error carried the trusted designed marker. */
+	isDesigned?: boolean;
 }
 
 export type ToolReply = { ok: true; value: unknown } | { ok: false; error: RunErrorPayload };

package/src/extensibility/extensions/runner.ts

@@ -192,6 +192,7 @@ type RunnerEmitResult<TEvent extends RunnerEmitEvent> = TEvent extends { type: "
 type Handler = Extension["handlers"] extends Map<string, Array<infer T>> ? T : never;
 type IndexedHandler = { ext: Extension; handler: Handler; registrationOrder: number };
 type IndexedFunctionHook = IndexedHandler & { registration: FunctionHookRegistration };
+type CommandAliasTarget = { extensionPath: string; commandName: string };
 
 export type FunctionHookDispatchResult<TEvent extends ExtensionEvent> =
 	| { action: "continue"; event: TEvent; transformed?: boolean }
@@ -272,6 +273,7 @@ export class ExtensionRunner {
 	#getCredentialSessionId: () => string = () => "";
 	#isIdleFn: () => boolean = () => true;
 	#getActivePromptHandleFn: () => string | undefined = () => undefined;
+	#getSessionWorkLeaseFn: ExtensionContextActions["getSessionWorkLease"] = undefined;
 	#waitForIdleFn: () => Promise<void> = async () => {};
 	#abortFn: () => void | Promise<void> = () => {};
 	#abortPromptAndWaitFn: NonNullable<ExtensionContextActions["abortPromptAndWait"]> = async () => {
@@ -328,6 +330,9 @@ export class ExtensionRunner {
 	#reloadHandler: () => Promise<void> = async () => {};
 	#shutdownHandler: ShutdownHandler = () => {};
 	#commandDiagnostics: Array<{ type: string; message: string; path: string }> = [];
+	#commandAliases = new Map<string, RegisteredCommand>();
+	#commandAliasAssignments = new Map<string, string>();
+	#commandAliasTargets = new Map<string, CommandAliasTarget>();
 	#initialized = false;
 	/**
 	 * Buffer for `credential_disabled` events received via {@link emitCredentialDisabled}
@@ -424,6 +429,7 @@ export class ExtensionRunner {
 		this.#getCredentialSessionId = contextActions.getCredentialSessionId ?? (() => "");
 		this.#isIdleFn = contextActions.isIdle;
 		this.#getActivePromptHandleFn = contextActions.getActivePromptHandle ?? (() => undefined);
+		this.#getSessionWorkLeaseFn = contextActions.getSessionWorkLease;
 		this.#abortFn = contextActions.abort;
 		this.#abortPromptAndWaitFn =
 			contextActions.abortPromptAndWait ??
@@ -701,16 +707,49 @@ export class ExtensionRunner {
 
 	getRegisteredCommands(reserved?: Set<string>): RegisteredCommand[] {
 		this.#commandDiagnostics = [];
+		this.#commandAliases.clear();
 
 		const commands = new Map<string, RegisteredCommand>();
 		for (const ext of this.extensions) {
 			for (const command of ext.commands.values()) {
 				if (reserved?.has(command.name)) {
-					const message = `Extension command '${command.name}' from ${ext.path} conflicts with built-in commands. Skipping.`;
-					this.#commandDiagnostics.push({ type: "warning", message, path: ext.path });
-					if (!this.hasUI()) {
-						logger.warn(message);
+					const assignmentKey = `${ext.path}\u0000${command.name}`;
+					let alias = this.#commandAliasAssignments.get(assignmentKey);
+					const aliasTarget = alias ? this.#commandAliasTargets.get(alias) : undefined;
+					const aliasOwnedByCommand =
+						aliasTarget?.extensionPath === ext.path && aliasTarget.commandName === command.name;
+					if (
+						!alias ||
+						reserved.has(alias) ||
+						commands.has(alias) ||
+						(aliasTarget !== undefined && !aliasOwnedByCommand)
+					) {
+						let candidate = alias ?? `extension:${command.name}`;
+						while (
+							reserved.has(candidate) ||
+							commands.has(candidate) ||
+							this.#commandAliases.has(candidate) ||
+							(this.#commandAliasTargets.has(candidate) &&
+								(this.#commandAliasTargets.get(candidate)?.extensionPath !== ext.path ||
+									this.#commandAliasTargets.get(candidate)?.commandName !== command.name))
+						)
+							candidate = `extension:${candidate}`;
+						if (
+							alias &&
+							this.#commandAliasTargets.get(alias)?.extensionPath === ext.path &&
+							this.#commandAliasTargets.get(alias)?.commandName === command.name
+						) {
+							this.#commandAliasTargets.delete(alias);
+						}
+						alias = candidate;
+						this.#commandAliasAssignments.set(assignmentKey, alias);
 					}
+					this.#commandAliasTargets.set(alias, { extensionPath: ext.path, commandName: command.name });
+					const namespaced = { ...command, name: alias };
+					this.#commandAliases.set(alias, namespaced);
+					commands.set(alias, namespaced);
+					const message = `Extension command '${command.name}' from ${ext.path} was renamed to '${alias}' to avoid a built-in command collision.`;
+					this.#commandDiagnostics.push({ type: "info", message, path: ext.path });
 					continue;
 				}
 
@@ -725,6 +764,14 @@ export class ExtensionRunner {
 	}
 
 	getCommand(name: string): RegisteredCommand | undefined {
+		const aliased = this.#commandAliases.get(name);
+		if (aliased) return aliased;
+		const aliasTarget = this.#commandAliasTargets.get(name);
+		if (aliasTarget) {
+			const extension = this.extensions.find(ext => ext.path === aliasTarget.extensionPath);
+			const command = extension?.commands.get(aliasTarget.commandName);
+			if (command) return { ...command, name };
+		}
 		for (let index = this.extensions.length - 1; index >= 0; index -= 1) {
 			const command = this.extensions[index]?.commands.get(name);
 			if (command) {
@@ -754,6 +801,7 @@ export class ExtensionRunner {
 				return getModel();
 			},
 			getActivePromptHandle: () => this.#getActivePromptHandleFn(),
+			getSessionWorkLease: () => this.#getSessionWorkLeaseFn?.(),
 			isIdle: () => this.#isIdleFn(),
 			abort: () => this.#abortFn(),
 			abortPromptAndWait: (handle, options) => this.#abortPromptAndWaitFn(handle, options),

package/src/extensibility/extensions/types.ts

@@ -58,6 +58,7 @@ import type {
 } from "../../session/client-bridge";
 import type { CustomMessage } from "../../session/messages";
 import type { ReadonlySessionManager, SessionManager } from "../../session/session-manager";
+import type { SessionWorkLease } from "../../session/session-work-lease";
 import type {
 	BashToolDetails,
 	BashToolInput,
@@ -482,6 +483,8 @@ export interface ExtensionContext {
 	isIdle(): boolean;
 	/** Stable resource ownership identifier for the active prompt run. */
 	getActivePromptHandle(): string | undefined;
+	/** The session's authoritative host-liveness lease. */
+	getSessionWorkLease?(): SessionWorkLease | undefined;
 	/** Abort the current agent operation */
 	abort(): void | Promise<void>;
 	/** Abort and prove whether resources for a specific prompt settled. */
@@ -1569,6 +1572,11 @@ export type SendUserMessageHandler = (
 		 * grants root abort ownership.
 		 */
 		onQueuedPromoted?: (promotion: { startsOwnRun?: boolean; removed?: boolean }) => void;
+		/**
+		 * Fired synchronously when a plain prompt's dispatch resolves at queue
+		 * time instead of run end (diverted into an in-flight run's steering).
+		 */
+		onDispatchDisposition?: (promotion: { startsOwnRun: boolean }) => void;
 		preflightSignal?: AbortSignal;
 		/** Internal SDK correlation owner for an exact queued follow-up. */
 	},
@@ -1660,6 +1668,8 @@ export interface ExtensionContextActions {
 	isIdle: () => boolean;
 	/** Stable resource ownership identifier for the active prompt run. */
 	getActivePromptHandle?: () => string | undefined;
+	/** The session's authoritative host-liveness lease. */
+	getSessionWorkLease?: () => SessionWorkLease | undefined;
 	abort: () => void | Promise<void>;
 	abortPromptAndWait?: (handle: string, options: { graceMs: number }) => Promise<RunSettlementProof>;
 

package/src/extensibility/gjc-plugins/registry.ts

@@ -1,6 +1,14 @@
 import { createHash, randomBytes } from "node:crypto";
 import * as fs from "node:fs/promises";
+import * as os from "node:os";
 import * as path from "node:path";
+import {
+	exactUnlink,
+	linkNoReplacePath,
+	type NativeExactFileIdentity,
+	type NativeNoReplaceResult,
+	renameNoReplacePath,
+} from "@gajae-code/natives";
 import { compileGjcPluginBundle } from "./compiler";
 import { migrateGjcPluginEntries } from "./migration";
 import { gjcPluginProjectRoot, gjcPluginUserRoot } from "./paths";
@@ -11,6 +19,11 @@ const LOCK_FILENAME = "registry.lock";
 const LOCK_TIMEOUT_MS = 5000;
 const LOCK_RETRY_MS = 50;
 
+export const RegistryLockTestHooks: {
+	beforeEviction?: (lockPath: string, raw: string) => void | Promise<void>;
+	beforePublish?: (stagingPath: string, lockPath: string) => void | Promise<void>;
+} = {};
+
 export function registryRootForScope(scope: GjcPluginScope, cwd: string): string {
 	return scope === "user" ? gjcPluginUserRoot() : gjcPluginProjectRoot(cwd);
 }
@@ -323,57 +336,203 @@ export async function readRegistry(
 	if (!migrated.changed && discovered.length === 0) return registry;
 	// Re-check under the lock before persisting. Migration and legacy-root
 	// discovery are one transaction, never a normal runtime loader path.
-	return await withRegistryLock(scope, cwd, async () => {
-		const latest = await readRegistryRaw(scope, cwd);
-		const latestDiscovered = await discoverLegacyEntries(scope, cwd, latest.plugins);
-		const latestMigrated = await migrateGjcPluginEntries([...latest.plugins, ...latestDiscovered]);
-		if (latestMigrated.changed || latestDiscovered.length > 0) {
-			const next: GjcPluginRegistry = { ...latest, plugins: sortRegistryEntries(latestMigrated.entries) };
-			await writeRegistryUnlocked(next, cwd, scope);
-			return next;
+	// Contention (a concurrent install elsewhere) must not fail startup reads:
+	// the effective registry is already computed, so degrade to returning it
+	// unpersisted and let a later uncontended session write the migrated
+	// state. Mutating install paths keep their fail-loud install_conflict.
+	try {
+		return await withRegistryLock(scope, cwd, async () => {
+			const latest = await readRegistryRaw(scope, cwd);
+			const latestDiscovered = await discoverLegacyEntries(scope, cwd, latest.plugins);
+			const latestMigrated = await migrateGjcPluginEntries([...latest.plugins, ...latestDiscovered]);
+			if (latestMigrated.changed || latestDiscovered.length > 0) {
+				const next: GjcPluginRegistry = { ...latest, plugins: sortRegistryEntries(latestMigrated.entries) };
+				await writeRegistryUnlocked(next, cwd, scope);
+				return next;
+			}
+			return latest;
+		});
+	} catch (error) {
+		if (error instanceof GjcPluginLoadError && error.code === "install_conflict") {
+			return { ...registry, plugins: sortRegistryEntries(migrated.entries) };
 		}
-		return latest;
+		throw error;
+	}
+}
+
+const LOCK_NONCE_PATTERN = /^[0-9a-f]{16}$/;
+
+interface RegistryLockToken {
+	pid: number;
+	/** Host segment of a host-tagged token; null for legacy `pid-nonce` tokens. */
+	host: string | null;
+}
+
+function parseRegistryLockToken(raw: string): RegistryLockToken | null {
+	const parts = raw.trim().split("-");
+	if (parts.length < 2) return null;
+	const pid = Number(parts[0]);
+	const nonce = parts[parts.length - 1];
+	if (!Number.isInteger(pid) || pid <= 0 || !LOCK_NONCE_PATTERN.test(nonce)) return null;
+	// Hostnames may contain '-', so everything between the first and last
+	// segment is the host; a single middle segment that is empty (or absent)
+	// means a legacy token.
+	const host = parts.slice(1, -1).join("-");
+	return { pid, host: host.length > 0 ? host : null };
+}
+
+/**
+ * A holder is assumed alive unless provably dead: ourselves, a live PID
+ * (EPERM counts — the process exists under another user), or a lock written
+ * on another host (a project registry can live on shared storage, where a
+ * local PID probe would be meaningless) all stay fail-closed.
+ */
+function registryLockHolderAlive(holder: RegistryLockToken): boolean {
+	if (holder.pid === process.pid) return true;
+	if (holder.host !== null && holder.host !== os.hostname()) return true;
+	try {
+		process.kill(holder.pid, 0);
+		return true;
+	} catch (error) {
+		return (error as NodeJS.ErrnoException)?.code === "EPERM";
+	}
+}
+
+async function captureRegistryLockIdentity(lockPath: string): Promise<NativeExactFileIdentity | null> {
+	try {
+		const [bytes, stat, parent] = await Promise.all([
+			fs.readFile(lockPath),
+			fs.lstat(lockPath, { bigint: true }),
+			fs.stat(path.dirname(lockPath), { bigint: true }),
+		]);
+		if (!stat.isFile()) return null;
+		return {
+			dev: stat.dev,
+			ino: stat.ino,
+			nlink: stat.nlink,
+			parentDev: parent.dev,
+			parentIno: parent.ino,
+			size: stat.size,
+			mtimeNs: stat.mtimeNs,
+			sha256: createHash("sha256").update(bytes).digest("hex"),
+		};
+	} catch (error) {
+		if (isEnoent(error)) return null;
+		throw error;
+	}
+}
+
+async function evictRegistryLock(lockPath: string, raw: string): Promise<boolean> {
+	const identity = await captureRegistryLockIdentity(lockPath);
+	if (!identity) return false;
+	const expectedHash = createHash("sha256").update(raw).digest("hex");
+	if (identity.sha256 !== expectedHash) return false;
+	await RegistryLockTestHooks.beforeEviction?.(lockPath, raw);
+	const result = exactUnlink(lockPath, {
+		...identity,
+		quarantineName: `${LOCK_FILENAME}.evict-${process.pid}-${randomBytes(4).toString("hex")}`,
 	});
+	return result.ok || result.code === "cleanup_pending";
+}
+
+function publishRegistryLock(stagingPath: string, lockPath: string): NativeNoReplaceResult {
+	let result = renameNoReplacePath(stagingPath, lockPath);
+	if (
+		!result.ok &&
+		result.mutationState === "not_committed" &&
+		(result.reason === "atomic_unavailable" || result.reason === "invalid_request")
+	) {
+		// linkat is the no-overwrite fallback on filesystems without a
+		// no-replace rename. Both paths expose the complete token only after the
+		// atomic claim, so a crash cannot publish an empty or partial lock.
+		result = linkNoReplacePath(stagingPath, lockPath);
+	}
+	return result;
 }
 
 async function acquireLock(lockPath: string): Promise<() => Promise<void>> {
 	await fs.mkdir(path.dirname(lockPath), { recursive: true });
-	const token = `${process.pid}-${randomBytes(8).toString("hex")}`;
+	const token = `${process.pid}-${os.hostname()}-${randomBytes(8).toString("hex")}`;
 	const deadline = Date.now() + LOCK_TIMEOUT_MS;
 	for (;;) {
+		const stagingPath = `${lockPath}.tmp-${process.pid}-${randomBytes(4).toString("hex")}`;
+		let publication: NativeNoReplaceResult | undefined;
 		try {
-			const handle = await fs.open(lockPath, "wx");
-			try {
-				await handle.writeFile(token);
-			} finally {
-				await handle.close();
+			await fs.writeFile(stagingPath, token, { encoding: "utf8", flag: "wx", mode: 0o600 });
+			await RegistryLockTestHooks.beforePublish?.(stagingPath, lockPath);
+			publication = publishRegistryLock(stagingPath, lockPath);
+			if (publication.ok) {
+				let released = false;
+				return async () => {
+					if (released) return;
+					released = true;
+					// Owner-safe release: only remove the lock if it is still ours.
+					try {
+						const current = await fs.readFile(lockPath, "utf8");
+						if (current === token) await fs.rm(lockPath, { force: true });
+					} catch {
+						// Lock already gone; nothing to release.
+					}
+				};
+			}
+			if (publication.reason !== "destination_exists") {
+				throw new Error(
+					`Failed to publish GJC plugin registry lock at ${lockPath}: ${publication.code ?? publication.reason}`,
+				);
 			}
-			let released = false;
-			return async () => {
-				if (released) return;
-				released = true;
-				// Owner-safe release: only remove the lock if it is still ours.
-				try {
-					const current = await fs.readFile(lockPath, "utf8");
-					if (current === token) await fs.rm(lockPath, { force: true });
-				} catch {
-					// Lock already gone; nothing to release.
-				}
-			};
 		} catch (error) {
-			if ((error as NodeJS.ErrnoException)?.code !== "EEXIST") throw error;
-			// Fail-closed: never auto-evict an existing lock (a live holder may run
-			// longer than the timeout). Time out instead and leave the lock for
-			// diagnostics/manual cleanup. A lease/heartbeat protocol can be added
-			// later if automatic stale recovery becomes necessary.
-			if (Date.now() > deadline) {
-				throw new GjcPluginLoadError(
-					"install_conflict",
-					`Timed out acquiring GJC plugin registry lock at ${lockPath}; remove it manually if no install is running`,
+			if (publication?.reason === "destination_exists") {
+				// Continue into stale inspection below.
+			} else if (
+				publication === undefined &&
+				["EACCES", "EPERM"].includes((error as NodeJS.ErrnoException)?.code ?? "")
+			) {
+				// A read-only registry directory can still contain a lock left by a
+				// dead writer. Inspect that lock and return the normal bounded
+				// install_conflict rather than surfacing the staging-file permission
+				// error immediately.
+				const lockExists = await fs.stat(lockPath).then(
+					() => true,
+					(error: unknown) => !isEnoent(error),
 				);
+				if (!lockExists) throw error;
+			} else throw error;
+		} finally {
+			if (publication?.mutationState !== "unknown") await fs.rm(stagingPath, { force: true }).catch(() => {});
+		}
+
+		// Stale recovery: a writer that died mid-transaction never releases
+		// its lock, and without recovery that lock poisons every later
+		// session until manual cleanup. Evict only a provably dead holder:
+		// a host-tagged token on this host. Legacy `pid-nonce` tokens have no
+		// trustworthy host identity, so they always fail closed: a local PID
+		// probe cannot prove that a remote holder on shared storage is dead.
+		// Live holders still fail closed below — they may legitimately outlive
+		// our timeout.
+		const raw = await fs.readFile(lockPath, "utf8").catch(() => null);
+		const holder = raw === null ? null : parseRegistryLockToken(raw);
+		if (raw !== null && holder !== null && holder.host !== null && !registryLockHolderAlive(holder)) {
+			try {
+				// exactUnlink verifies the observed inode, parent, size, mtime,
+				// and bytes inside the removal primitive. A replacement published
+				// after this read is therefore never consumed by stale recovery.
+				await evictRegistryLock(lockPath, raw);
+			} catch {
+				// Raced with another evictor or a fresh holder, or the removal
+				// itself failed (lockfile owned by another user, read-only mount,
+				// EBUSY/EPERM on Windows). Fall through to the shared deadline
+				// and backoff below either way: a removal that keeps failing must
+				// end in the bounded install_conflict timeout, never an unbounded
+				// spin.
 			}
-			await new Promise(resolve => setTimeout(resolve, LOCK_RETRY_MS));
 		}
+		if (Date.now() > deadline) {
+			throw new GjcPluginLoadError(
+				"install_conflict",
+				`Timed out acquiring GJC plugin registry lock at ${lockPath}; remove it manually if no install is running`,
+			);
+		}
+		await new Promise(resolve => setTimeout(resolve, LOCK_RETRY_MS));
 	}
 }