@gajae-code/coding-agent 0.16.3 → 0.16.4

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

@@ -1,16 +1,17 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import { getPluginsDir, getTrustedHomeDir } from "@gajae-code/utils";
-import { findRepoRoot, invalidate as invalidateFsCache } from "../capability/fs";
+import { getTrustedHomeDir } from "@gajae-code/utils";
+import { findRepoRoot } from "../capability/fs";
 import type { Skill as CapabilitySkill } from "../capability/skill";
 import type { SkillsSettings } from "../config/settings-schema";
 import { resolveSkillScopeTrust } from "../config/skill-settings-defaults";
 import { scanClaudeProjectSkills, scanClaudeUserSkills } from "../discovery/claude";
+import { loadMarketplaceSkills } from "../discovery/claude-plugins";
 import { scanCodexProjectSkills, scanCodexUserSkills } from "../discovery/codex";
-import { compareSkillOrder, listClaudePluginRoots, SOURCE_PATHS, scanSkillsFromDir } from "../discovery/helpers";
+import { compareSkillOrder, SOURCE_PATHS, scanSkillsFromDir } from "../discovery/helpers";
 import { CANONICAL_GJC_WORKFLOW_SKILLS } from "../skill-state/canonical-skills";
 import { expandTilde } from "../tools/path-utils";
-import type { Skill } from "./skills";
+import { loadSkills, type Skill } from "./skills";
 
 export type RuntimeSkillDiscoverySource = "project" | "user";
 
@@ -152,18 +153,6 @@ function getUseWhen(skill: CapabilitySkill): string[] | undefined {
 	return values.length > 0 ? values : undefined;
 }
 
-function toRuntimeSkill(skill: CapabilitySkill, source: RuntimeSkillDiscoverySource): Skill {
-	return {
-		name: skill.name,
-		description: typeof skill.frontmatter?.description === "string" ? skill.frontmatter.description : "",
-		filePath: skill.path,
-		baseDir: skill.path.replace(/[\\/]SKILL\.md$/, ""),
-		source: `runtime:${source}`,
-		hide: skill.frontmatter?.hide === true,
-		_source: { ...skill._source, providerName: "Runtime skill discovery" },
-	};
-}
-
 function sourceEnabled(source: RuntimeSkillDiscoverySource, policy: SkillsSettings | undefined): boolean {
 	if (policy?.enabled !== true) return false;
 	return resolveSkillScopeTrust(policy, source);
@@ -202,7 +191,7 @@ async function realPathOrSelf(filePath: string): Promise<string> {
 }
 
 interface ScanJobResult {
-	items: Array<{ skill: CapabilitySkill; source: RuntimeSkillDiscoverySource }>;
+	items: Array<{ skill: CapabilitySkill; source: RuntimeSkillDiscoverySource; providerPriority: number }>;
 	warnings: string[];
 	label: string;
 }
@@ -234,23 +223,16 @@ function pushDiagnostic(diagnostics: string[], message: string): void {
 	if (diagnostics.length < MAX_DIAGNOSTICS) diagnostics.push(message);
 }
 
-async function collectPluginSkillDirs(
+async function collectPluginSkills(
 	home: string,
 	cwd: string,
-): Promise<Array<{ dir: string; pluginName: string; level: "user" | "project" }>> {
-	// Ensure the underlying installed_plugins.json fs cache is current — install/upgrade
-	// writers already invalidate via clearPluginRootsAndCaches; this is a defensive
-	// fallback so a stale in-memory cache cannot mask a disabled/removed plugin.
-	invalidateFsCache(`${getPluginsDir(home)}/installed_plugins.json`);
+	allowedLevels: ReadonlySet<"user" | "project">,
+): Promise<{ items: CapabilitySkill[]; warnings: string[] }> {
 	try {
-		const { roots } = await listClaudePluginRoots(home, cwd);
-		return roots.map(root => ({
-			dir: `${root.path}/skills`,
-			pluginName: root.plugin,
-			level: root.scope,
-		}));
-	} catch {
-		return [];
+		const result = await loadMarketplaceSkills({ cwd, home, repoRoot: await findRepoRoot(cwd) }, allowedLevels);
+		return { items: result.items, warnings: result.warnings ?? [] };
+	} catch (error) {
+		return { items: [], warnings: [`marketplace skill scan failed: ${String(error)}`] };
 	}
 }
 
@@ -287,6 +269,7 @@ async function scanProjectOrUserDir(
 	level: "project" | "user",
 	label: string,
 	source: RuntimeSkillDiscoverySource,
+	providerPriority: number,
 ): Promise<ScanJobResult> {
 	const result = await scanSkillsFromDir(ctx, {
 		dir,
@@ -295,7 +278,7 @@ async function scanProjectOrUserDir(
 		requireDescription: true,
 	});
 	return {
-		items: result.items.map(skill => ({ skill, source })),
+		items: result.items.map(skill => ({ skill, source, providerPriority })),
 		warnings: result.warnings ?? [],
 		label,
 	};
@@ -355,8 +338,9 @@ function reportConventionImportCandidates(
 ): void {
 	for (const scan of scans.sort((a, b) => a.host.localeCompare(b.host) || a.dir.localeCompare(b.dir))) {
 		for (const skill of scan.skills) {
-			if (seenNames.has(skill.name)) continue;
-			seenNames.add(skill.name);
+			const normalizedName = skill.name.toLowerCase();
+			if (seenNames.has(normalizedName)) continue;
+			seenNames.add(normalizedName);
 			pushDiagnostic(
 				diagnostics,
 				`skill "${skill.name}" found at ${skill.path} (${scan.host} convention): import sources are not loaded directly; copy it into a trusted .gjc/skills directory to enable it, e.g. mkdir -p .gjc/skills/${skill.name} && cp ${skill.path} .gjc/skills/${skill.name}/SKILL.md`,
@@ -405,55 +389,46 @@ export async function discoverRuntimeSkills(
 	const projectContext = { cwd: options.cwd, home, repoRoot: projectDirs.repoRoot };
 	if ((source === "all" || source === "project") && sourceEnabled("project", policy)) {
 		for (const { dir, label } of projectDirs.scans) {
-			scanJobs.push(scanProjectOrUserDir(projectContext, dir, "project", label, "project"));
+			scanJobs.push(scanProjectOrUserDir(projectContext, dir, "project", label, "project", 100));
 		}
 	}
 	if ((source === "all" || source === "user") && sourceEnabled("user", policy)) {
 		for (const dir of getUserSkillDirs(home)) {
 			scanJobs.push(
-				scanProjectOrUserDir({ cwd: options.cwd, home, repoRoot: home }, dir, "user", `user ${dir}`, "user"),
+				scanProjectOrUserDir({ cwd: options.cwd, home, repoRoot: home }, dir, "user", `user ${dir}`, "user", 100),
 			);
 		}
 	}
 	if ((source === "all" || source === "user") && policy?.enabled === true) {
 		for (const dir of getCustomSkillDirs(policy, home)) {
 			scanJobs.push(
-				scanProjectOrUserDir({ cwd: options.cwd, home, repoRoot: home }, dir, "user", `custom ${dir}`, "user"),
+				scanProjectOrUserDir({ cwd: options.cwd, home, repoRoot: home }, dir, "user", `custom ${dir}`, "user", 0),
 			);
 		}
 	}
 
-	// Marketplace plugin skills: version-stable, enabled-only.
-	// Uses the same trust gate as native user/project scopes and the same
-	// discovery root (<installPath>/skills) the capability provider uses,
-	// namespaced as `plugin:skillName`.
+	// Marketplace plugin skills come from the same provider used to populate
+	// session.skills, so discovery, slash commands, SDK state, and exact-name
+	// invocation cannot drift on manifest paths, namespacing, or enabled roots.
 	if (policy?.enabled === true) {
-		const pluginDirs = await collectPluginSkillDirs(home, options.cwd);
-		for (const entry of pluginDirs) {
-			if (entry.level === "project" && !(source === "all" || source === "project")) continue;
-			if (entry.level === "user" && !(source === "all" || source === "user")) continue;
-			if (!sourceEnabled(entry.level, policy)) continue;
-			const label = `plugin ${entry.pluginName} skills`;
-			scanJobs.push(
-				(async () => {
-					const pluginCtx = { cwd: options.cwd, home, repoRoot: home };
-					const result = await scanSkillsFromDir(pluginCtx, {
-						dir: entry.dir,
-						providerId: "plugin",
-						level: entry.level,
-						requireDescription: true,
-					});
-					for (const skill of result.items) {
-						skill.name = `${entry.pluginName}:${skill.name}`;
-					}
-					return {
-						items: result.items.map(skill => ({ skill, source: entry.level as RuntimeSkillDiscoverySource })),
-						warnings: result.warnings ?? [],
-						label,
-					};
-				})(),
-			);
+		const allowedLevels = new Set<"user" | "project">();
+		if ((source === "all" || source === "project") && sourceEnabled("project", policy)) {
+			allowedLevels.add("project");
+		}
+		if ((source === "all" || source === "user") && sourceEnabled("user", policy)) {
+			allowedLevels.add("user");
 		}
+		scanJobs.push(
+			collectPluginSkills(home, options.cwd, allowedLevels).then(result => ({
+				items: result.items.map(skill => ({
+					skill,
+					source: skill.level as RuntimeSkillDiscoverySource,
+					providerPriority: 70,
+				})),
+				warnings: result.warnings,
+				label: "marketplace plugin skills",
+			})),
+		);
 	}
 	if (policy?.enabled === true && policy.customDirectories && policy.customDirectories.length > 0) {
 		for (const dir of getCustomSkillDirs(policy, home)) {
@@ -466,6 +441,7 @@ export async function discoverRuntimeSkills(
 	const seenNames = new Set<string>();
 	const seenPaths = new Set<string>();
 	const candidates: RuntimeSkillDiscoveryCandidate[] = [];
+	const orderedItems: ScanJobResult["items"] = [];
 	for (const entry of settled) {
 		if ("error" in entry) {
 			pushDiagnostic(diagnostics, `skill scan failed: ${entry.error}`);
@@ -476,29 +452,34 @@ export async function discoverRuntimeSkills(
 				pushDiagnostic(diagnostics, `${entry.label}: ${warning}`);
 			}
 		}
-		for (const item of entry.items) {
-			if (!isAllowedByPolicy(item.skill, policy, diagnostics)) continue;
-			const realPath = await realPathOrSelf(item.skill.path);
-			if (seenPaths.has(realPath) || seenNames.has(item.skill.name)) {
-				pushDiagnostic(
-					diagnostics,
-					`skill "${item.skill.name}" already resolved from a higher-precedence location; ignoring ${item.skill.path}`,
-				);
-				continue;
-			}
-			seenPaths.add(realPath);
-			seenNames.add(item.skill.name);
-
-			const candidate: RuntimeSkillDiscoveryCandidate = {
-				name: item.skill.name,
-				description:
-					typeof item.skill.frontmatter?.description === "string" ? item.skill.frontmatter.description : "",
-				source: item.source,
-				path: item.skill.path,
-				useWhen: getUseWhen(item.skill),
-			};
-			if (matchesQuery(candidate, options.query ?? "")) candidates.push(candidate);
+		orderedItems.push(...entry.items);
+	}
+	orderedItems.sort((a, b) => {
+		const levelOrder = { project: 0, user: 1 } as const;
+		return levelOrder[a.source] - levelOrder[b.source] || b.providerPriority - a.providerPriority;
+	});
+	for (const item of orderedItems) {
+		if (!isAllowedByPolicy(item.skill, policy, diagnostics)) continue;
+		const realPath = await realPathOrSelf(item.skill.path);
+		const normalizedName = item.skill.name.toLowerCase();
+		if (seenPaths.has(realPath) || seenNames.has(normalizedName)) {
+			pushDiagnostic(
+				diagnostics,
+				`skill "${item.skill.name}" already resolved from a higher-precedence location; ignoring ${item.skill.path}`,
+			);
+			continue;
 		}
+		seenPaths.add(realPath);
+		seenNames.add(normalizedName);
+
+		const candidate: RuntimeSkillDiscoveryCandidate = {
+			name: item.skill.name,
+			description: typeof item.skill.frontmatter?.description === "string" ? item.skill.frontmatter.description : "",
+			source: item.source,
+			path: item.skill.path,
+			useWhen: getUseWhen(item.skill),
+		};
+		if (matchesQuery(candidate, options.query ?? "")) candidates.push(candidate);
 	}
 	candidates.sort((a, b) => compareSkillOrder(a.name, a.path, b.name, b.path));
 	reportConventionImportCandidates(
@@ -520,67 +501,12 @@ export async function findRuntimeSkillByName(
 ): Promise<Skill | undefined> {
 	const normalized = name.trim();
 	if (!normalized) return undefined;
-	const scanJobs: Array<Promise<{ skill: CapabilitySkill; source: RuntimeSkillDiscoverySource }[]>> = [];
-	const projectDirs = await getProjectSkillDirs(cwd, home);
-	const projectContext = { cwd, home, repoRoot: projectDirs.repoRoot };
-	if (sourceEnabled("project", policy)) {
-		scanJobs.push(
-			...projectDirs.scans.map(scan =>
-				scanSkillsFromDir(projectContext, {
-					dir: scan.dir,
-					providerId: "runtime",
-					level: "project",
-					requireDescription: true,
-				}).then(result => result.items.map(skill => ({ skill, source: "project" as const }))),
-			),
-		);
-	}
-	if (sourceEnabled("user", policy)) {
-		for (const dir of getUserSkillDirs(home)) {
-			scanJobs.push(
-				scanSkillsFromDir(
-					{ cwd, home, repoRoot: home },
-					{ dir, providerId: "runtime", level: "user", requireDescription: true },
-				).then(result => result.items.map(skill => ({ skill, source: "user" as const }))),
-			);
-		}
-	}
-	if (policy?.enabled === true) {
-		for (const dir of getCustomSkillDirs(policy, home)) {
-			scanJobs.push(
-				scanSkillsFromDir(
-					{ cwd, home, repoRoot: home },
-					{ dir, providerId: "runtime", level: "user", requireDescription: true },
-				).then(result => result.items.map(skill => ({ skill, source: "user" as const }))),
-			);
-		}
-	}
-	if (policy?.enabled === true) {
-		try {
-			const pluginDirs = await collectPluginSkillDirs(home, cwd);
-			for (const entry of pluginDirs) {
-				if (!sourceEnabled(entry.level, policy)) continue;
-				scanJobs.push(
-					scanSkillsFromDir(
-						{ cwd, home, repoRoot: home },
-						{
-							dir: entry.dir,
-							providerId: "plugin",
-							level: entry.level,
-							requireDescription: true,
-						},
-					).then(result => {
-						for (const skill of result.items) skill.name = `${entry.pluginName}:${skill.name}`;
-						return result.items.map(skill => ({ skill, source: entry.level as RuntimeSkillDiscoverySource }));
-					}),
-				);
-			}
-		} catch {}
-	}
-	for (const entry of (await Promise.all(scanJobs)).flat()) {
-		if (entry.skill.name === normalized && isAllowedByPolicy(entry.skill, policy, [])) {
-			return toRuntimeSkill(entry.skill, entry.source);
-		}
-	}
-	return undefined;
+	if (BUILT_IN_SKILL_NAMES.has(normalized)) return undefined;
+	const loaded = await loadSkills({
+		...policy,
+		cwd,
+		home,
+		agentDir: path.join(home, SOURCE_PATHS.native.userAgent),
+	});
+	return loaded.skills.find(skill => skill.name === normalized);
 }

package/src/extensibility/shared-events.ts

@@ -188,7 +188,7 @@ export interface AgentEndEvent {
 	sdkRunToken?: string;
 	/** Indicates whether the loop ended normally, suspended, cancelled, or entered maintenance. */
 	stopReason?: "completed" | "paused" | "cancelled" | "maintenance";
-	/** Present for maintenance checkpoints; non-aborted checkpoints are not terminal. */
+	/** Present for maintenance checkpoints; only committed maintenance outcomes are non-terminal. */
 	maintenanceOutcome?: MidRunMaintenanceOutcome;
 }
 

package/src/extensibility/skills.ts

@@ -6,6 +6,7 @@ import type { SourceMeta } from "../capability/types";
 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 type { SkillPromptDetails } from "../session/messages";
 import { CANONICAL_GJC_WORKFLOW_SKILLS } from "../skill-state/canonical-skills";
@@ -116,11 +117,12 @@ export interface LoadSkillsOptions extends SkillsSettings {
 }
 
 /**
- * Skill providers loaded into sessions. Only native `.gjc` skills are live
- * filesystem skills; Claude/Codex convention skills are explicit import
+ * Skill providers loaded into sessions. Native `.gjc` skills and installed
+ * marketplace plugin skills are both live filesystem skills, so both are
+ * enumerated into sessions; Claude/Codex convention skills are explicit import
  * sources into `.gjc` (see skill-management.ts) and are never loaded directly.
  */
-const LOADABLE_SKILL_PROVIDERS = new Set(["native"]);
+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()));
 
@@ -149,7 +151,8 @@ export async function loadSkills(options: LoadSkillsOptions = {}): Promise<LoadS
 
 	// Skill scope trust decides which canonical locations are loaded: project
 	// scope covers `.gjc/skills` (walk-up), user scope covers `~/.gjc/agent/skills`
-	// and the legacy user roots. Claude/Codex convention skills are import
+	// and the legacy user roots, and installed marketplace plugins are gated by the
+	// scope they were installed into. Claude/Codex convention skills are import
 	// sources into `.gjc`, never loaded directly.
 	function isSourceEnabled(source: SourceMeta): boolean {
 		const { provider, level } = source;
@@ -162,16 +165,33 @@ export async function loadSkills(options: LoadSkillsOptions = {}): Promise<LoadS
 	// Use capability API to load all skills. `all` (rather than `items`) keeps
 	// shadowed duplicates so this function can apply the documented precedence
 	// itself: project scope beats user scope.
-	const nativeProvider = getCapability<CapabilitySkill>(skillCapability.id)?.providers.find(
-		provider => provider.id === "native",
-	);
-	if (!nativeProvider) throw new Error("Native skill provider is unavailable");
-	const result = await nativeProvider.load({
+	const providers =
+		getCapability<CapabilitySkill>(skillCapability.id)?.providers.filter(provider =>
+			LOADABLE_SKILL_PROVIDERS.has(provider.id),
+		) ?? [];
+	if (!providers.some(provider => provider.id === "native")) {
+		throw new Error("Native skill provider is unavailable");
+	}
+	const loadContext = {
 		cwd,
 		home,
 		userAgentDir: options.agentDir,
 		repoRoot: await findRepoRoot(cwd),
-	});
+	};
+	const providerResults = await Promise.all(
+		providers.map(async provider => {
+			const allowedLevels = new Set<"user" | "project">();
+			if (projectTrusted) allowedLevels.add("project");
+			if (userTrusted) allowedLevels.add("user");
+			return {
+				provider,
+				result:
+					provider.id === "claude-plugins"
+						? await loadMarketplaceSkills(loadContext, allowedLevels)
+						: await provider.load(loadContext),
+			};
+		}),
+	);
 
 	const skillMap = new Map<string, Skill>();
 	const realPathSet = new Set<string>();
@@ -197,8 +217,11 @@ export async function loadSkills(options: LoadSkillsOptions = {}): Promise<LoadS
 	// precedence. `all` is already in native provider order with project dirs
 	// before user dirs; a stable sort by level lifts every project item above
 	// every user item, giving: project `.gjc/skills` > user roots.
-	const filteredSkills = result.items
-		.filter(capSkill => {
+	const filteredSkills = providerResults
+		.flatMap(({ provider, result }) =>
+			result.items.map(capSkill => ({ capSkill, providerPriority: provider.priority })),
+		)
+		.filter(({ capSkill }) => {
 			if (!isSourceEnabled(capSkill._source)) return false;
 			if (disabledSkillNames.has(capSkill.name)) return false;
 			if (matchesIgnorePatterns(capSkill.name)) return false;
@@ -207,12 +230,12 @@ export async function loadSkills(options: LoadSkillsOptions = {}): Promise<LoadS
 		})
 		.sort((a, b) => {
 			const levelOrder = { project: 0, user: 1 } as const;
-			return levelOrder[a.level] - levelOrder[b.level];
+			return levelOrder[a.capSkill.level] - levelOrder[b.capSkill.level] || b.providerPriority - a.providerPriority;
 		});
 
 	// Batch resolve all real paths in parallel
 	const realPaths = await Promise.all(
-		filteredSkills.map(async capSkill => {
+		filteredSkills.map(async ({ capSkill }) => {
 			try {
 				return await fs.realpath(capSkill.path);
 			} catch {
@@ -223,7 +246,7 @@ export async function loadSkills(options: LoadSkillsOptions = {}): Promise<LoadS
 
 	// Process skills with resolved paths
 	for (let i = 0; i < filteredSkills.length; i++) {
-		const capSkill = filteredSkills[i];
+		const { capSkill } = filteredSkills[i];
 		const resolvedPath = realPaths[i];
 
 		// Skip silently if we've already loaded this exact file (via symlink)
@@ -338,7 +361,12 @@ export async function loadSkills(options: LoadSkillsOptions = {}): Promise<LoadS
 
 	return {
 		skills,
-		warnings: [...(result.warnings ?? []).map(w => ({ skillPath: "", message: w })), ...collisionWarnings],
+		warnings: [
+			...providerResults.flatMap(({ result }) =>
+				(result.warnings ?? []).map(message => ({ skillPath: "", message })),
+			),
+			...collisionWarnings,
+		],
 	};
 }
 

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

@@ -146,7 +146,43 @@ 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;
+	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 +449,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>;
 } = {};
@@ -1993,7 +2031,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,10 +2048,52 @@ 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."));
@@ -2014,12 +2101,15 @@ async function withLockPathTransition<T>(
 			// 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 (await joinLocalTurn()) continue;
 			await SessionStateLockTestHooks.afterTransitionClaimContention?.(transitionDir);
 			if (await reclaimStaleTransitionClaim(transitionDir, quarantineName)) {
 				if (lockRetryExhausted(budget))