@gajae-code/coding-agent 0.17.2 → 0.17.5

package/src/extensibility/gjc-plugins/runtime-adapters.ts

@@ -3,6 +3,7 @@ import type { Dirent } from "node:fs";
 import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
+import { redactCrashSecrets, safeErrorDescription } from "@gajae-code/utils";
 import { bindPluginMcpToPublicNetwork } from "../../runtime-mcp/plugin-network-boundary";
 import type { MCPStdioPreparedLaunch, MCPStdioSpawnLaunch } from "../../runtime-mcp/types";
 import { loadCustomTools } from "../custom-tools/loader";
@@ -20,7 +21,13 @@ import { isV2Tool } from "./migration";
 import { gjcPluginInstallRoot, resolveWithinRoot } from "./paths";
 import { loadEffectiveGjcPluginRegistry, registryPathForScope, registryRootForScope } from "./registry";
 import { type SessionQuarantine, type SessionValidationResult, validateSessionBundles } from "./session-validation";
-import type { GjcPluginRegistryEntry, GjcPluginScope, JsonSchema202012, NormalizedToolSurfaceV2 } from "./types";
+import type {
+	GjcBundleIdentity,
+	GjcPluginRegistryEntry,
+	GjcPluginScope,
+	JsonSchema202012,
+	NormalizedToolSurfaceV2,
+} from "./types";
 
 export interface AlwaysOnPluginTools {
 	tools: CustomTool[];
@@ -32,6 +39,23 @@ export interface GjcPluginToolDeclaration extends NormalizedToolSurfaceV2 {
 	scope: GjcPluginScope;
 }
 
+export interface GjcPluginMcpServerProvenance {
+	identity: GjcBundleIdentity;
+	surfaceId: string;
+}
+
+// Plugin MCP manifests reject per-server timeout controls; generated transports
+// share one bounded window so startup evidence reaches a terminal result.
+const PLUGIN_MCP_STARTUP_TIMEOUT_MS = 5_000;
+const MAX_PLUGIN_MCP_DIAGNOSTIC_LENGTH = 1_024;
+
+/** Bound and scrub plugin-controlled MCP causes before they enter logs or runtime findings. */
+export function safePluginMcpDiagnostic(value: unknown): string {
+	const message = safeErrorDescription(value).replace(/[\u0000-\u001f\u007f-\u009f]/gu, "");
+	const normalized = message.replace(/\b(Bearer|Basic|Token)(?=[A-Za-z0-9._~+/=-]{8,})/giu, "$1 ");
+	return redactCrashSecrets(normalized).slice(0, MAX_PLUGIN_MCP_DIAGNOSTIC_LENGTH);
+}
+
 function isWithin(root: string, target: string): boolean {
 	const rel = path.relative(root, target);
 	return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
@@ -557,7 +581,9 @@ async function prepareVerifiedStdioLaunch(input: {
 		throw new Error("Authenticated plugin MCP stdio launch capsules are available only on Linux");
 	}
 	if (input.launcher === "bun") {
-		throw new Error("Authenticated plugin MCP Bun launch capsules are unavailable");
+		throw new Error(
+			"Authenticated plugin MCP Bun launch capsules are unavailable: Bun's clearable runtime plugin hooks cannot enforce the authenticated module-loading boundary required to restrict plugin imports to verified capsule bytes",
+		);
 	}
 	const registerCleanup = input.registerCleanup;
 	if (!registerCleanup) {
@@ -1045,18 +1071,22 @@ export async function renderSkillAdvertisement(input: {
  * Convert active plugin-bundle MCP surfaces into runtime MCPServerConfig entries,
  * applying install + runtime MCP policy (URL scheme/private-range deny, DNS
  * re-resolution for http/sse, stdio root-confinement) before connection. Servers
- * failing policy are quarantined and excluded. Returns {} when none.
+ * failing policy are quarantined and excluded. The provenance map contains
+ * only servers present in `configs`, so connection errors can be attributed to
+ * the authenticated bundle and stable surface that supplied each server.
  */
 export async function buildPluginMcpConfigs(input: { cwd: string }): Promise<{
 	configs: Record<string, any>;
 	quarantine: SessionQuarantine[];
+	serverProvenance: ReadonlyMap<string, GjcPluginMcpServerProvenance>;
 }> {
 	const { effective, active, quarantine } = await loadValidatedPluginRegistry(input.cwd, true);
-	if (effective.length === 0) return { configs: {}, quarantine: [] };
+	if (effective.length === 0) return { configs: {}, quarantine: [], serverProvenance: new Map() };
 
 	// A manifest-controlled MCP name such as "constructor" or "toString" must
 	// remain an ordinary own key rather than interacting with Object.prototype.
 	const configs: Record<string, any> = Object.create(null) as Record<string, any>;
+	const serverProvenance = new Map<string, GjcPluginMcpServerProvenance>();
 	for (const entry of active) {
 		const disabled = new Set(entry.disabledSurfaceIds);
 		let compiledMcps: Map<string, (typeof entry.surfaces.mcps)[number]> | undefined;
@@ -1119,7 +1149,7 @@ export async function buildPluginMcpConfigs(input: { cwd: string }): Promise<{
 						command,
 						args: initialArgs,
 						cwd: invocation.cwd,
-						timeout: 5_000,
+						timeout: PLUGIN_MCP_STARTUP_TIMEOUT_MS,
 						// Third-party plugin MCP processes must not inherit host secrets;
 						// only a minimal OS allowlist (PATH/HOME/temp/locale) is provided.
 						noInheritEnv: true,
@@ -1207,18 +1237,26 @@ export async function buildPluginMcpConfigs(input: { cwd: string }): Promise<{
 					// resolution path expands ${env:...}/shell templates, which would let
 					// a third-party bundle exfiltrate host secrets. Plugin-bundle MCP
 					// servers connect without bundle-declared headers.
-					configs[m.name] = bindPluginMcpToPublicNetwork({ type: cfg.transport, url: url.toString() });
+					configs[m.name] = bindPluginMcpToPublicNetwork({
+						type: cfg.transport,
+						url: url.toString(),
+						timeout: PLUGIN_MCP_STARTUP_TIMEOUT_MS,
+					});
 				}
+				serverProvenance.set(m.name, {
+					identity: bundleIdentity(entry.scope, entry.name),
+					surfaceId: `mcp:${m.name}`,
+				});
 			} catch (error) {
 				quarantine.push({
 					identity: bundleIdentity(entry.scope, entry.name),
 					plugin: entry.name,
 					surfaceId: m.extensionId,
 					code: "security_policy",
-					message: error instanceof Error ? error.message : String(error),
+					message: safePluginMcpDiagnostic(error),
 				});
 			}
 		}
 	}
-	return { configs, quarantine };
+	return { configs, quarantine, serverProvenance };
 }

package/src/extensibility/runtime-skill-discovery.ts

@@ -54,6 +54,16 @@ export interface RuntimeSkillDiscoveryResult {
 	candidates: RuntimeSkillDiscoveryCandidate[];
 	/** Deduped skill metadata the query filter ran against, including bundled entries; candidates.length <= scanned. */
 	scanned: number;
+	/**
+	 * Skills left after the query filter, before the page slice: the denominator
+	 * a page is a page *of*. `scanned` counts everything the filter ran against,
+	 * so it cannot serve this role.
+	 */
+	matching: number;
+	/** Normalized zero-based offset the returned page starts at. */
+	offset: number;
+	/** Offset of the next page, present only while one exists; omitted on the final page. */
+	nextOffset?: number;
 	diagnostics: RuntimeSkillDiscoveryDiagnostics;
 }
 
@@ -65,6 +75,8 @@ export interface DiscoverRuntimeSkillsOptions {
 	profileAuthority?: "default" | "custom";
 	query?: string;
 	limit?: number;
+	/** Zero-based index into the matching set the returned page starts at; defaults to 0. */
+	offset?: number;
 	source?: RuntimeSkillDiscoveryScope | "all";
 	policy?: SkillsSettings;
 }
@@ -74,11 +86,26 @@ function getRuntimeHome(): string {
 }
 
 const DEFAULT_LIMIT = 20;
-const MAX_LIMIT = 50;
+/**
+ * Upper bound every caller's `limit` clamps to. Exported so `gjc skills discover`
+ * can default a human to the widest page the library will serve instead of the
+ * model-context-sized `DEFAULT_LIMIT`.
+ */
+export const SKILL_DISCOVERY_MAX_LIMIT = 50;
 const MAX_DIAGNOSTICS = 10;
 function normalizeLimit(limit: number | undefined): number {
 	if (limit === undefined || !Number.isFinite(limit)) return DEFAULT_LIMIT;
-	return Math.max(1, Math.min(MAX_LIMIT, Math.trunc(limit)));
+	return Math.max(1, Math.min(SKILL_DISCOVERY_MAX_LIMIT, Math.trunc(limit)));
+}
+
+/**
+ * Offsets are clamped from below only. An offset past the end is a legitimate
+ * empty final page (the catalog shrank between pages), not an error, so it is
+ * reported rather than silently snapped back onto the last populated page.
+ */
+function normalizeOffset(offset: number | undefined): number {
+	if (offset === undefined || !Number.isFinite(offset) || offset < 0) return 0;
+	return Math.trunc(offset);
 }
 
 interface ProjectScanDir {
@@ -558,9 +585,40 @@ export async function discoverRuntimeSkills(
 		seenNames,
 		diagnostics,
 	);
+	const limit = normalizeLimit(options.limit);
+	const offset = normalizeOffset(options.offset);
+	const matching = candidates.length;
+	const page = candidates.slice(offset, offset + limit);
+	// Continuation is omitted on the final page, so "is there more" is the
+	// presence of the field rather than a value the caller has to compare.
+	const nextOffset = offset + page.length < matching ? offset + page.length : undefined;
+	// Appended directly instead of through pushDiagnostic: these are the only
+	// messages that explain why a skill the caller can see on disk is absent
+	// from the result, and the reported case (several stale
+	// skills.customDirectories entries, one "does not exist" message each)
+	// fills the MAX_DIAGNOSTICS budget before the slice is ever reached. A
+	// dropped paging notice makes the truncation invisible again.
+	if (page.length === 0) {
+		if (offset > 0 && matching > 0) {
+			diagnostics.push(
+				`no skills at offset ${offset}; ${matching} matching skill${matching === 1 ? "" : "s"} total, pass --offset 0 to start over`,
+			);
+		}
+	} else if (nextOffset !== undefined) {
+		diagnostics.push(
+			`showing ${offset + 1}-${offset + page.length} of ${matching} matching skills; pass --offset ${nextOffset} for the next page, or narrow the query`,
+		);
+	} else if (offset > 0) {
+		// Final page of a multi-page walk: no continuation to offer, but the
+		// caller still needs to know this page is not the whole matching set.
+		diagnostics.push(`showing ${offset + 1}-${offset + page.length} of ${matching} matching skills`);
+	}
 	return {
-		candidates: candidates.slice(0, normalizeLimit(options.limit)),
+		candidates: page,
 		scanned,
+		matching,
+		offset,
+		...(nextOffset === undefined ? {} : { nextOffset }),
 		diagnostics: { messages: diagnostics },
 	};
 }

package/src/extensibility/shared-events.ts

@@ -93,9 +93,11 @@ export interface SessionCompactEvent {
 	fromExtension: boolean;
 }
 
-/** Fired on process exit (SIGINT/SIGTERM) */
+/** Fired during session teardown, including process exit and SDK host self-reap. */
 export interface SessionShutdownEvent {
 	type: "session_shutdown";
+	/** Set only when the SDK host reaped itself after detached-idle grace. */
+	reason?: "detached_idle";
 }
 
 /** Preparation data for tree navigation (used by session_before_tree event) */

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

@@ -14,7 +14,7 @@ import {
 	readFileLockObservationForGc,
 } from "../config/file-lock";
 import { loadInstallationHostId, loadLegacyInstallationHostId } from "../config/machine-identity";
-import { readLinuxProcStartTimeSync } from "./linux-proc";
+import { type LinuxProcPidProbeResult, probeLinuxProcPidSync, readLinuxProcStartTimeSync } from "./linux-proc";
 
 /** SHA-256 of the empty payload; the constant identity of every verified-empty receipt. */
 const EMPTY_FILE_SHA256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
@@ -122,6 +122,10 @@ function lockRetryExhausted(budget: LockRetryBudget): boolean {
 	return lockRetryRemainingMs(budget) <= 0;
 }
 
+function lockRetryTotalWaitExhausted(budget: LockRetryBudget): boolean {
+	return Math.max(0, performance.now() - budget.firstAttemptAt) >= LOCK_ACQUIRE_MAX_WAIT_MS;
+}
+
 async function waitForLockRetry(budget: LockRetryBudget): Promise<boolean> {
 	budget.attempts++;
 	const remainingMs = lockRetryRemainingMs(budget);
@@ -501,6 +505,13 @@ export const SessionStateLockTestHooks: {
 	 * configuration.
 	 */
 	probeProcessSignal?: (pid: number) => void;
+	/**
+	 * @internal How an owner pid's `/proc` entry is read. Whether a killed pid is still an
+	 * unreaped zombie depends on when its parent happens to reap it, so it cannot be
+	 * arranged deterministically from a test. Production code never sets it, and it is
+	 * never serialized or exposed as runtime configuration.
+	 */
+	probeLinuxProcPid?: (pid: number) => LinuxProcPidProbeResult;
 	/**
 	 * @internal Runs inside a NEW owner record's write, after the exclusive create has
 	 * taken the pathname and before the record's bytes land. Throwing from it fails that
@@ -560,6 +571,33 @@ export type SessionStateLockUnavailableReason =
 	| "transition_claim_timeout"
 	| "unsafe_lock_path_type";
 
+/**
+ * Why a stale-transition reclaim refused, as a bounded classifier.
+ *
+ * `transition_claim_timeout` collapsed several structurally different refusals into
+ * one message, so an operator could not tell a foreign-host tombstone from a
+ * live owner from a directory an external process was stamping — the gap #5606
+ * asked for. Every member is a fixed enum: never a path, token, host id, pid or
+ * raw errno, because this rides on an error message users paste into reports.
+ */
+export type TransitionReclaimRefusal =
+	/** The claim vanished, or its owner sidecar was absent/unparseable/invalid. */
+	| "claim_or_owner_unreadable"
+	/** A released tombstone carrying no `owner_host_id` at all. */
+	| "released_owner_unprovenanced"
+	/** A released tombstone belonging to a different installation. */
+	| "released_owner_foreign_host"
+	/** A released tombstone still inside `RELEASED_TRANSITION_GRACE_MS`. */
+	| "released_owner_within_grace"
+	/** The owner is alive, or its liveness could not be disproven. */
+	| "owner_live_or_unverifiable"
+	/** The claim changed between inspection and capture — an external writer. */
+	| "claim_generation_changed"
+	/** The claim was not empty when captured, so it is not ours to remove. */
+	| "claim_not_empty"
+	/** The claim's canonical path or directory snapshot could not be taken. */
+	| "claim_capture_failed";
+
 interface SessionStateLockUnavailableDetails {
 	lockPath: string;
 	reason: SessionStateLockUnavailableReason;
@@ -750,6 +788,28 @@ function lockUnavailable(
 	});
 }
 
+/**
+ * `transition_claim_timeout` with the reclaim refusal that kept repeating.
+ *
+ * The bare classifier could not distinguish several structurally different
+ * refusals, so an operator had no way to tell which action would help (#5606).
+ * The suffix is a fixed enum member and nothing else — this string reaches user
+ * reports, so it must never carry a path, token, host id, pid or errno.
+ */
+function transitionClaimTimeout(
+	transitionDir: string,
+	budget: LockRetryBudget,
+	cause: unknown,
+	refusal: TransitionReclaimRefusal | undefined,
+): SessionStateLockUnavailableError {
+	const error = lockUnavailable(transitionDir, "transition_claim_timeout", budget, cause);
+	if (refusal === undefined) return error;
+	return Object.assign(error, {
+		reclaimRefusal: refusal,
+		message: `${error.message.replace(/\.$/, "")} (reclaim refused: ${refusal}).`,
+	});
+}
+
 function lockDiagnostic(
 	error: unknown,
 	lockPath: string,
@@ -941,7 +1001,17 @@ function probeOwnerProcess(pid: number): OwnerProcessLiveness {
 	try {
 		const probe = SessionStateLockTestHooks.probeProcessSignal;
 		if (probe) probe(pid);
-		else process.kill(pid, 0);
+		else {
+			// Linux keeps a killed child as a zombie until its parent reaps it. `kill(pid, 0)`
+			// still succeeds for that zombie even though it can no longer hold the lock, so
+			// inspect `/proc` first and treat the terminal `Z` state as proof of death.
+			if (process.platform === "linux") {
+				const proc = (SessionStateLockTestHooks.probeLinuxProcPid ?? probeLinuxProcPidSync)(pid);
+				if (proc.kind === "absent") return "dead";
+				if (proc.kind === "live" && proc.state === "Z") return "dead";
+			}
+			process.kill(pid, 0);
+		}
 		return "alive";
 	} catch (error) {
 		const code = (error as NodeJS.ErrnoException).code;
@@ -1846,12 +1916,27 @@ async function releaseTransitionClaim(
 	}
 }
 
-async function reclaimStaleTransitionClaim(transitionDir: string, quarantineName: string): Promise<boolean> {
+/**
+ * Outcome of one stale-transition reclaim attempt. `reclaimed` drives the
+ * caller's retry accounting exactly as the previous boolean did; `refusal`
+ * exists only so the eventual `transition_claim_timeout` can name which
+ * precondition said no (#5606).
+ */
+interface TransitionReclaimOutcome {
+	reclaimed: boolean;
+	reclaimReason?: "released_handoff" | "dead_owner";
+	refusal?: TransitionReclaimRefusal;
+}
+
+async function reclaimStaleTransitionClaim(
+	transitionDir: string,
+	quarantineName: string,
+): Promise<TransitionReclaimOutcome> {
 	let stat: fsSync.BigIntStats;
 	try {
 		stat = await fs.lstat(transitionDir, { bigint: true });
 	} catch {
-		return false;
+		return { reclaimed: false, refusal: "claim_or_owner_unreadable" };
 	}
 	// Regular-file claims belong to the superseded protocol. They retain the old
 	// exact-identity stale path; released PID-1 tombstones deliberately require
@@ -1865,41 +1950,46 @@ async function reclaimStaleTransitionClaim(transitionDir: string, quarantineName
 			},
 			quarantineName,
 		);
-		return reclaimed === "owner_removed";
+		return {
+			reclaimed: reclaimed === "owner_removed",
+			...(reclaimed === "owner_removed" ? { reclaimReason: "dead_owner" as const } : {}),
+		};
 	}
 	if (!stat.isDirectory()) throw new SessionStateLockUnavailableError();
 	const ownerSnapshot = await captureRegularLockOwner(`${transitionDir}.owner`);
-	if (!ownerSnapshot) return false;
+	if (!ownerSnapshot) return { reclaimed: false, refusal: "claim_or_owner_unreadable" };
 	let owner: unknown;
 	try {
 		owner = JSON.parse(ownerSnapshot.bytes);
 	} catch {
-		return false;
+		return { reclaimed: false, refusal: "claim_or_owner_unreadable" };
 	}
-	if (!validLockOwner(owner)) return false;
+	if (!validLockOwner(owner)) return { reclaimed: false, refusal: "claim_or_owner_unreadable" };
 	await SessionStateLockTestHooks.afterTransitionStaleInspection?.(transitionDir);
 	if (owner.released === true) {
 		// A released record is safe only when it is qualified by this installation.
 		// Never let a shared-volume tombstone, an absent identity, or a legacy foreign
 		// identity authorize removal of a claim this process cannot own.
-		if (owner.owner_host_id === undefined) return false;
+		if (owner.owner_host_id === undefined) return { reclaimed: false, refusal: "released_owner_unprovenanced" };
 		const currentHost = await currentOwnerHostId();
 		const legacyHost = await currentLegacyOwnerHostId();
-		if (owner.owner_host_id !== currentHost && owner.owner_host_id !== legacyHost) return false;
-		if (Date.now() - Number(ownerSnapshot.mtimeNs / 1_000_000n) < RELEASED_TRANSITION_GRACE_MS) return false;
+		if (owner.owner_host_id !== currentHost && owner.owner_host_id !== legacyHost)
+			return { reclaimed: false, refusal: "released_owner_foreign_host" };
+		if (Date.now() - Number(ownerSnapshot.mtimeNs / 1_000_000n) < RELEASED_TRANSITION_GRACE_MS)
+			return { reclaimed: false, refusal: "released_owner_within_grace" };
 	} else if (await lockOwnerIsAlive(owner)) {
 		// Only a host-qualified owner whose pid is PROVEN dead (ESRCH, or a live pid
 		// with a provably different incarnation) authorizes reclaim. The generation
 		// + exact-tree checks below then bind the removal to the very directory
 		// inspected here, on every platform; a claim stranded by a force-quit
 		// (`postmortem.quit`) would otherwise wall the session directory forever.
-		return false;
+		return { reclaimed: false, refusal: "owner_live_or_unverifiable" };
 	}
 	const generation = transitionGenerationFromStat(stat);
 	const nativePath = await canonicalOwnedTransitionPath(transitionDir).catch(() => null);
-	if (!nativePath) return false;
+	if (!nativePath) return { reclaimed: false, refusal: "claim_capture_failed" };
 	const captured = nativeSessionStateLock().snapshotDirectoryTree(nativePath);
-	if (!captured.ok || !captured.snapshot) return false;
+	if (!captured.ok || !captured.snapshot) return { reclaimed: false, refusal: "claim_capture_failed" };
 	const root = captured.snapshot.entries.find(entry => entry.relativePath === "");
 	if (
 		root?.kind !== "directory" ||
@@ -1909,12 +1999,15 @@ async function reclaimStaleTransitionClaim(transitionDir: string, quarantineName
 		root.mtimeNs !== String(generation.mtimeNs) ||
 		root.ctimeNs !== String(generation.ctimeNs)
 	)
-		return false;
-	if (captured.snapshot.entries.length !== 1) return false;
+		return { reclaimed: false, refusal: "claim_generation_changed" };
+	if (captured.snapshot.entries.length !== 1) return { reclaimed: false, refusal: "claim_not_empty" };
 	const removed = nativeSessionStateLock().exactRemoveDirectoryTree(nativePath, captured.snapshot);
 	if (removed.ok || removed.code === "not_found") {
 		exactUnlinkOwnerRecord(`${transitionDir}.owner`, ownerSnapshot, quarantineName);
-		return removed.ok;
+		return {
+			reclaimed: removed.ok,
+			...(removed.ok ? { reclaimReason: owner.released === true ? "released_handoff" : "dead_owner" } : {}),
+		};
 	}
 	if (
 		removed.code === "cleanup_pending" &&
@@ -1931,7 +2024,7 @@ async function reclaimStaleTransitionClaim(transitionDir: string, quarantineName
 		// successor populated the detached path.
 		await removeTransitionDir(removed.detachedPath);
 		exactUnlinkOwnerRecord(`${transitionDir}.owner`, ownerSnapshot, quarantineName);
-		return true;
+		return { reclaimed: true, reclaimReason: owner.released === true ? "released_handoff" : "dead_owner" };
 	}
 	throw new SessionStateLockUnavailableError(
 		new Error(`Stale transition claim could not be reclaimed (${removed.code ?? "unknown"}).`),
@@ -2310,6 +2403,7 @@ async function runLockPathTransition<T>(
 		throw new SessionStateLockUnavailableError(new Error("Safe transition ownership is unsupported."));
 	const transitionDir = `${lockFile}${LOCK_TRANSITION_RESOURCE_SUFFIX}`;
 	const ownerFile = `${transitionDir}.owner`;
+	let lastReclaimRefusal: TransitionReclaimRefusal | undefined;
 
 	for (;;) {
 		if (ownerAccessStrategy() === "unsupported" && fsSync.existsSync(transitionDir))
@@ -2332,18 +2426,37 @@ async function runLockPathTransition<T>(
 			// Claims are held only for pathname bookkeeping, so a changed claim identity is
 			// proof that contenders are cycling through rather than that one is wedged.
 			const observedClaim = await observedLockHolderIdentity(transitionDir);
-			const reclaimed = await reclaimStaleTransitionClaim(transitionDir, quarantineName);
-			creditLockHandoffProgress(budget, observedClaim, reclaimed);
+			const outcome = await reclaimStaleTransitionClaim(transitionDir, quarantineName);
+			creditLockHandoffProgress(budget, observedClaim, outcome.reclaimed);
+			// Remember the LAST refusal: on a wedged claim every retry refuses for the
+			// same reason, and that reason is the actionable one. Carrying it onto the
+			// timeout is the whole point — `transition_claim_timeout` alone cannot tell
+			// a foreign-host tombstone from a live owner from an external writer
+			// restamping the claim directory (#5606).
+			if (outcome.refusal !== undefined) lastReclaimRefusal = outcome.refusal;
 			// 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);
+			if (outcome.reclaimed) {
+				if (lockRetryExhausted(budget)) {
+					// Only a released tombstone is the previous holder's explicit handoff.
+					// Ordinary dead-owner reclaims remain bounded by the original deadline,
+					// even though both reclaim paths unlink their owner sidecar.
+					const ownerStillPresent = await fs.lstat(`${transitionDir}.owner`).then(
+						() => true,
+						error => (error as NodeJS.ErrnoException).code !== "ENOENT",
+					);
+					if (
+						outcome.reclaimReason !== "released_handoff" ||
+						ownerStillPresent ||
+						lockRetryTotalWaitExhausted(budget)
+					)
+						throw transitionClaimTimeout(transitionDir, budget, error, lastReclaimRefusal);
+				}
 				continue;
 			}
 			if (!(await waitForLockRetry(budget)))
-				throw lockUnavailable(transitionDir, "transition_claim_timeout", budget, error);
+				throw transitionClaimTimeout(transitionDir, budget, error, lastReclaimRefusal);
 			continue;
 		}
 		const pendingSetup: PendingTransitionRelease = {
@@ -2753,6 +2866,34 @@ async function observedLockHolderIdentity(lockPath: string): Promise<string | un
 	return `d:${stat.dev}:${stat.ino}:${stat.ctimeNs}`;
 }
 
+/**
+ * Classify one stale-transition reclaim attempt.
+ *
+ * @internal exported as the seam the refusal classifier is tested through. Driving
+ * a real `transition_claim_timeout` would mean waiting out `LOCK_ACQUIRE_MAX_WAIT_MS`
+ * (60s) per case, and `tryWithSessionStateFileLock` throws BUSY before the timeout
+ * is ever built, so the per-branch reasons have no other reachable surface (#5606).
+ */
+export async function classifyTransitionReclaimForTests(
+	transitionDir: string,
+	quarantineName: string,
+): Promise<TransitionReclaimOutcome> {
+	return reclaimStaleTransitionClaim(transitionDir, quarantineName);
+}
+
+/**
+ * Build the timeout error exactly as the transition loop does.
+ *
+ * @internal exported so the message contract — a bounded enum suffix and nothing
+ * else — is pinned without a 60s wait (#5606).
+ */
+export function transitionClaimTimeoutForTests(
+	transitionDir: string,
+	refusal: TransitionReclaimRefusal | undefined,
+): SessionStateLockUnavailableError {
+	return transitionClaimTimeout(transitionDir, lockRetryBudget(), new Error("EEXIST"), refusal);
+}
+
 /**
  * Decide what actually occupies the lock path, without following it.
  *