@narumitw/pi-sync 0.49.8 → 0.49.10

package/README.md

@@ -62,6 +62,27 @@ and recovery. Secondary screens provide **Back**; Escape goes back and Ctrl+C cl
 Destructive, credential-bearing, and externally visible operations retain exact specialized previews
 and confirmations.
 
+### Restore sync access
+
+When an operation is currently running, the manager shows its command and process ID, keeps sync and
+settings changes unavailable, and puts **Refresh operation status** first.
+When lock metadata is still protected by an active guard, the manager explains that another pi-sync
+process may be starting or finishing and asks the user to wait before refreshing.
+It never offers lock removal while an owner or guard may still be active.
+
+When a previous operation appears to have stopped without releasing its local lock, the manager shows
+**Sync paused** and puts **Restore sync access… (recommended)** first instead of hiding recovery
+inside **History & recovery…**.
+Unreadable metadata receives a stronger warning because pi-sync cannot verify who owns it.
+Close every other Pi session that may still be syncing, review the local-lock-only confirmation, then
+choose **Remove local lock and continue**.
+The guarded recovery path rechecks metadata and ownership before removal, changes no settings, local
+files, sync state, or remote data, and returns directly to the normal manager when access is restored.
+Cancellation leaves the lock unchanged.
+If ownership changes or a guard is still expiring, pi-sync refuses removal and keeps actionable status
+available for refresh or retry.
+The deterministic fallback remains `/sync unlock --stale` after the same no-other-sync verification.
+
 ### Resolve conflicts in the manager
 
 When **Sync now**, **Pull from remote…**, or **Push to remote…** finds changes that require a human direction choice, the manager opens **Resolve sync conflict** instead of ending at a command-only error.
@@ -338,6 +359,9 @@ packages/pi-sync/
 │   ├── state-directory.ts
 │   ├── settings-management.ts
 │   ├── manager-ui.ts
+│   ├── manager-state.ts
+│   ├── manager-recovery.ts
+│   ├── operation-availability.ts
 │   ├── manager-attention.ts
 │   ├── sync-attention.ts
 │   ├── storage-connections-ui.ts

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-sync",
-	"version": "0.49.8",
+	"version": "0.49.10",
 	"description": "Pi extension that syncs Pi configuration through Git, WebDAV, Cloudflare R2, or S3-compatible storage.",
 	"type": "module",
 	"license": "MIT",

package/src/lock.ts

@@ -152,7 +152,9 @@ export function isStaleLock(lock: LockFile) {
 }
 
 export async function unlock(ctx: ExtensionCommandContext, options: CommandOptions) {
+	throwIfAborted(options.signal);
 	await ensureStateDir();
+	throwIfAborted(options.signal);
 	let guard: Guard;
 	try {
 		guard = await acquireGuard();
@@ -179,7 +181,9 @@ export async function unlock(ctx: ExtensionCommandContext, options: CommandOptio
 }
 
 async function unlockGuarded(ctx: ExtensionCommandContext, options: CommandOptions) {
+	throwIfAborted(options.signal);
 	let inspection = await inspectLock();
+	throwIfAborted(options.signal);
 	if (inspection.status === "missing") {
 		ctx.ui.notify("No pi-sync lock is present.", "info");
 		return;
@@ -193,12 +197,19 @@ async function unlockGuarded(ctx: ExtensionCommandContext, options: CommandOptio
 			return;
 		}
 		inspection = await inspectLock();
+		throwIfAborted(options.signal);
 		if (inspection.status === "unreadable") {
 			// Legacy writers expose an empty file before writing owner metadata, so no
 			// automatic test can prove this file is abandoned. The explicit --stale
 			// flag is the user's confirmation that no legacy sync is still running.
+			throwIfAborted(options.signal);
 			await fs.rm(lockPath(), { force: true });
-			ctx.ui.notify("Removed unreadable pi-sync lock.", "info");
+			if (!options.signal?.aborted) {
+				ctx.ui.notify(
+					"Removed unreadable pi-sync lock. No settings, files, sync state, or remote data were changed.",
+					"info",
+				);
+			}
 			return;
 		}
 		if (inspection.status === "missing") {
@@ -210,8 +221,21 @@ async function unlockGuarded(ctx: ExtensionCommandContext, options: CommandOptio
 		ctx.ui.notify("Lock owner is still live; refusing to remove it.", "warning");
 		return;
 	}
+	throwIfAborted(options.signal);
 	await fs.rm(lockPath(), { force: true });
-	ctx.ui.notify("Removed stale pi-sync lock.", "info");
+	if (!options.signal?.aborted) {
+		ctx.ui.notify(
+			"Removed stale pi-sync lock. No settings, files, sync state, or remote data were changed.",
+			"info",
+		);
+	}
+}
+
+function throwIfAborted(signal?: AbortSignal) {
+	if (!signal?.aborted) return;
+	throw signal.reason instanceof Error
+		? signal.reason
+		: new DOMException("The operation was aborted", "AbortError");
 }
 
 async function releaseGuard(guard: Guard) {

package/src/manager-recovery.ts

@@ -0,0 +1,65 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { runConfirmation } from "@narumitw/pi-tui-kit";
+import type { RunRoute } from "./cancellable-operation.js";
+import { errorMessage, safeTerminalText } from "./manager-helpers.js";
+import type { ManagerDescription } from "./manager-state.js";
+import { inspectOperationAvailability, operationCanRecover } from "./operation-availability.js";
+
+export type RecoveryDisposition = "restored" | "stay" | "close";
+
+export async function recoverSyncAccess(
+	ctx: ExtensionCommandContext,
+	manager: ManagerDescription,
+	runRoute: RunRoute,
+	sessionSignal: AbortSignal | undefined,
+	actionSignal: AbortSignal,
+): Promise<RecoveryDisposition> {
+	const operation = manager.operation;
+	if (!operation || !operationCanRecover(operation)) {
+		ctx.ui.notify(
+			"Operation status changed. Refresh the manager before retrying recovery.",
+			"warning",
+		);
+		return "stay";
+	}
+	const signal = sessionSignal ? AbortSignal.any([sessionSignal, actionSignal]) : actionSignal;
+	if (signal.aborted) return "close";
+	const unreadable = operation.kind === "recoverable-unreadable";
+	const details = unreadable
+		? "Pi-sync cannot verify who owns the unreadable lock. Close other Pi sessions that may be syncing before continuing."
+		: `The recorded ${safeTerminalText(operation.lock.command)} operation (pid ${operation.lock.pid}) appears to have stopped. Close other Pi sessions that may still be syncing before continuing.`;
+	const confirmation = await runConfirmation(ctx, {
+		title: "Restore sync access?",
+		message: [
+			details,
+			"",
+			"This removes only the local operation lock.",
+			"It does not change settings, local files, sync state, or remote data.",
+		].join("\n"),
+		confirmLabel: "Remove local lock and continue",
+		cancelLabel: "Cancel",
+		signal,
+		isCurrent: () => !signal.aborted,
+		onError: (_currentCtx, error) => {
+			ctx.ui.notify(
+				`Recovery confirmation failed: ${safeTerminalText(errorMessage(error))}`,
+				"error",
+			);
+		},
+	});
+	if (confirmation.kind === "stale") return "close";
+	if (confirmation.kind === "closed") {
+		if (confirmation.reason === "close") return "close";
+		if (!signal.aborted) {
+			ctx.ui.notify("Recovery cancelled; the local operation lock was not changed.", "info");
+		}
+		return "stay";
+	}
+	if (confirmation.kind !== "confirmed") return "stay";
+	if (signal.aborted) return "close";
+	await runRoute(unreadable ? "unlock --stale" : "unlock", signal);
+	if (signal.aborted) return "close";
+	const latest = await inspectOperationAvailability();
+	if (signal.aborted) return "close";
+	return latest.kind === "free" ? "restored" : "stay";
+}

package/src/manager-state.ts

@@ -1,3 +1,4 @@
+import { truncateToWidth } from "@earendil-works/pi-tui";
 import {
 	activeLocalConfigPath,
 	isCloudflareR2Endpoint,
@@ -5,8 +6,13 @@ import {
 	readLocalConfigObject,
 	readStateForConfig,
 } from "./config.js";
-import { inspectLock, isStaleLock } from "./lock.js";
 import { errorMessage, ownRecord, safeTerminalText } from "./manager-helpers.js";
+import {
+	inspectOperationAvailability,
+	type OperationAvailability,
+	operationBlocksChanges,
+	operationCanRecover,
+} from "./operation-availability.js";
 import { type SyncAttentionState, syncAttentionMatchesConfig } from "./sync-attention.js";
 import { compareSyncInclude, syncIncludeSelection } from "./sync-policy.js";
 import { countValidSyncSetups } from "./sync-setups-ui.js";
@@ -23,6 +29,7 @@ export const MAIN_MENU_ACTIONS = [
 export interface ManagerDescription {
 	title: string;
 	actions: string[];
+	operation?: OperationAvailability;
 	attention?: SyncAttentionState;
 	attentionBlocksSync?: boolean;
 	attentionReviewDisabled?: boolean;
@@ -31,6 +38,7 @@ export interface ManagerDescription {
 export async function describeManagerState(
 	signal?: AbortSignal,
 	attention?: SyncAttentionState,
+	inspectOperation: () => Promise<OperationAvailability> = inspectOperationAvailability,
 ): Promise<ManagerDescription> {
 	let raw: Record<string, unknown> | undefined;
 	try {
@@ -71,10 +79,8 @@ export async function describeManagerState(
 	}
 	try {
 		const config = await loadConfig();
-		const lock = await inspectLock();
-		const liveLock = lock.status === "valid" && !isStaleLock(lock.lock);
-		const recoverableLock =
-			lock.status === "unreadable" || (lock.status === "valid" && isStaleLock(lock.lock));
+		const operation = await inspectOperation();
+		const changesBlocked = operationBlocksChanges(operation);
 		const selection = syncIncludeSelection(config.include);
 		let currentAttention: SyncAttentionState | undefined;
 		if (attention) {
@@ -96,72 +102,61 @@ export async function describeManagerState(
 				)
 			: undefined;
 		const noSyncedContent = config.include.length === 0;
-		const syncState =
-			liveLock || recoverableLock
-				? undefined
-				: await readStateForConfig(config).catch(() => undefined);
-		const lastAppliedSnapshot =
-			liveLock || recoverableLock
-				? "Unavailable while operations are locked"
-				: syncState?.lastAppliedSnapshot
-					? safeTerminalText(syncState.lastAppliedSnapshot)
-					: syncState
-						? "Never synced"
-						: "Unavailable";
+		const syncState = changesBlocked
+			? undefined
+			: await readStateForConfig(config).catch(() => undefined);
+		const lastAppliedSnapshot = changesBlocked
+			? "Unavailable while operations are locked"
+			: syncState?.lastAppliedSnapshot
+				? safeTerminalText(syncState.lastAppliedSnapshot)
+				: syncState
+					? "Never synced"
+					: "Unavailable";
 		const canSwitch = (await countValidSyncSetups(configuredTargets, signal)) > 1;
 		const mainActions = MAIN_MENU_ACTIONS.filter(
 			(action) => action !== "Switch sync setup" || canSwitch,
 		);
+		const ordinaryTitle = [
+			"Manage sync",
+			"",
+			`Current sync setup: ${safeTerminalText(config.setupName)}`,
+			`Storage: ${backendStorageDescription(config)}`,
+			`Included: ${selection.builtIns.length} built-in group${selection.builtIns.length === 1 ? "" : "s"} · ${selection.custom.length} extra path${selection.custom.length === 1 ? "" : "s"} · Sessions ${selection.sessions ? "on" : "off"}`,
+			`Automatic sync: ${config.automatic ? "On" : "Off"}`,
+			`Last applied: ${lastAppliedSnapshot}`,
+			...(currentAttention
+				? [
+						currentAttention.decision.setupName === config.setupName
+							? "Sync status: Review needed"
+							: `Sync status: Review needed for setup ${safeTerminalText(currentAttention.decision.setupName)}`,
+						attentionComparison?.remoteOnly.length === 0 &&
+						attentionComparison.localOnly.length === 0
+							? "Only the synced-content order differs."
+							: `Remote-only paths: ${attentionComparison?.remoteOnly.length ?? 0} · Device-only paths: ${attentionComparison?.localOnly.length ?? 0}`,
+						"Nothing has been changed.",
+					]
+				: ["Remote status: Not checked"]),
+			...(noSyncedContent
+				? [
+						"",
+						"No included content is selected. Choose included content in Settings before syncing.",
+					]
+				: []),
+			"",
+			"What do you want to do?",
+		];
 		return {
-			title: [
-				"Manage sync",
-				"",
-				`Current sync setup: ${safeTerminalText(config.setupName)}`,
-				`Storage: ${backendStorageDescription(config)}`,
-				`Included: ${selection.builtIns.length} built-in group${selection.builtIns.length === 1 ? "" : "s"} · ${selection.custom.length} extra path${selection.custom.length === 1 ? "" : "s"} · Sessions ${selection.sessions ? "on" : "off"}`,
-				`Automatic sync: ${config.automatic ? "On" : "Off"}`,
-				`Last applied: ${lastAppliedSnapshot}`,
-				...(currentAttention
-					? [
-							currentAttention.decision.setupName === config.setupName
-								? "Sync status: Review needed"
-								: `Sync status: Review needed for setup ${safeTerminalText(currentAttention.decision.setupName)}`,
-							attentionComparison?.remoteOnly.length === 0 &&
-							attentionComparison.localOnly.length === 0
-								? "Only the synced-content order differs."
-								: `Remote-only paths: ${attentionComparison?.remoteOnly.length ?? 0} · Device-only paths: ${attentionComparison?.localOnly.length ?? 0}`,
-							"Nothing has been changed.",
-						]
-					: ["Remote status: Not checked"]),
-				...(noSyncedContent
-					? [
-							"",
-							"No included content is selected. Choose included content in Settings before syncing.",
-						]
-					: []),
-				...(liveLock
-					? [
-							"",
-							`Operation in progress: ${safeTerminalText(lock.lock.command)} (pid ${lock.lock.pid}). Sync and settings changes are disabled.`,
-						]
-					: []),
-				...(recoverableLock
-					? ["", "Recovery required: lock metadata is stale or unreadable."]
-					: []),
-				"",
-				"What do you want to do?",
-			].join("\n"),
-			actions:
-				liveLock || recoverableLock
-					? ["Status & changes", "History & recovery…", "Help"]
-					: noSyncedContent
-						? ["Settings", ...(canSwitch ? ["Switch sync setup"] : []), "Status & changes", "More…"]
-						: mainActions,
+			title: (changesBlocked
+				? ["Manage sync", ...operationStatusLines(operation)]
+				: ordinaryTitle
+			).join("\n"),
+			actions: operationActions(operation, noSyncedContent, canSwitch, mainActions),
+			operation,
 			...(currentAttention
 				? {
 						attention: currentAttention,
 						attentionBlocksSync: currentAttention.decision.setupName === config.setupName,
-						attentionReviewDisabled: liveLock || recoverableLock,
+						attentionReviewDisabled: changesBlocked,
 					}
 				: {}),
 		};
@@ -183,6 +178,57 @@ export async function describeManagerState(
 	}
 }
 
+function operationActions(
+	operation: OperationAvailability,
+	noSyncedContent: boolean,
+	canSwitch: boolean,
+	mainActions: string[],
+) {
+	if (operationCanRecover(operation)) {
+		return [
+			"Restore sync access… (recommended)",
+			"Status & changes",
+			"History & recovery…",
+			"Help",
+		];
+	}
+	if (operation.kind !== "free") {
+		return ["Refresh operation status", "Status & changes", "History & recovery…", "Help"];
+	}
+	return noSyncedContent
+		? ["Settings", ...(canSwitch ? ["Switch sync setup"] : []), "Status & changes", "More…"]
+		: mainActions;
+}
+
+function operationStatusLines(operation: OperationAvailability): string[] {
+	switch (operation.kind) {
+		case "free":
+			return [];
+		case "live": {
+			const command = truncateToWidth(safeTerminalText(operation.lock.command), 16, "…");
+			return [
+				`Running: ${command} (pid ${operation.lock.pid}). Wait, then refresh; Settings and More return.`,
+			];
+		}
+		case "busy":
+			return [
+				"Pi-sync may be starting or finishing. Wait, then refresh; Settings and More remain unavailable.",
+			];
+		case "recoverable-stale":
+			return [
+				"Sync paused: old lock remains. Close other Pi sessions then restore; Settings and More return.",
+			];
+		case "recoverable-unreadable":
+			return [
+				"Sync paused: owner unknown. Close other Pi sessions then restore; Settings and More return.",
+			];
+		case "inspection-error":
+			return [
+				"Lock check failed. Fix path access, then refresh; Settings and More remain unavailable.",
+			];
+	}
+}
+
 export function backendStorageDescription(config: AnySyncConfig) {
 	const connection = safeTerminalText(config.connectionName);
 	switch (config.backend.type) {

package/src/manager-ui.ts

@@ -13,7 +13,6 @@ import {
 	syncConfigReviewIdentity,
 } from "./config.js";
 import { showAddGitTarget, showEditGitTarget, showGitSetup } from "./git-ui.js";
-import { inspectLock, isStaleLock } from "./lock.js";
 import {
 	attentionMainMenuItems,
 	blockedSyncMenuItem,
@@ -27,8 +26,10 @@ import {
 	requiredInput,
 	safeTerminalText,
 } from "./manager-helpers.js";
+import { recoverSyncAccess } from "./manager-recovery.js";
 import { dispatchManagerResult } from "./manager-result-dispatcher.js";
 import { backendStorageDescription, describeManagerState } from "./manager-state.js";
+import { operationCanRecover } from "./operation-availability.js";
 import { chooseS3Credentials } from "./s3-credentials-ui.js";
 import {
 	addSyncSetup,
@@ -68,28 +69,34 @@ export async function showSyncManager(
 		| "history"
 		| "doctor"
 		| "unlock"
+		| "recover"
+		| "refresh"
 		| "help"
 		| "init"
 		| "back";
 	interface State {
 		manager: Awaited<ReturnType<typeof describeManagerState>>;
-		canRecover: boolean;
 	}
 	const menu = defineMenu<State, Screen, Action, ExtensionCommandContext>({
 		start: "main",
 		screens: {
-			main: ({ state }) => ({
-				kind: "actions",
-				title: "Manage sync",
-				lines: state.manager.title.split("\n").slice(1),
-				items: [
-					...attentionMainMenuItems(state.manager),
-					...state.manager.actions.map(
-						(label) => blockedSyncMenuItem(label, state.manager) ?? syncMainMenuItem(label),
-					),
-				],
-				hint: "close",
-			}),
+			main: ({ state }) => {
+				const attentionItems = attentionMainMenuItems(state.manager);
+				const managerItems = state.manager.actions.map(
+					(label) => blockedSyncMenuItem(label, state.manager) ?? syncMainMenuItem(label),
+				);
+				const operationFirst =
+					state.manager.operation !== undefined && state.manager.operation.kind !== "free";
+				return {
+					kind: "actions",
+					title: "Manage sync",
+					lines: state.manager.title.split("\n").slice(1),
+					items: operationFirst
+						? [...managerItems, ...attentionItems]
+						: [...attentionItems, ...managerItems],
+					hint: "close",
+				};
+			},
 			more: () => ({
 				kind: "actions",
 				title: "More options",
@@ -114,7 +121,7 @@ export async function showSyncManager(
 				items: [
 					{ id: "history", label: "Browse history", action: "history" },
 					{ id: "doctor", label: "Check setup", action: "doctor" },
-					...(state.canRecover
+					...(state.manager.operation && operationCanRecover(state.manager.operation)
 						? [{ id: "unlock", label: "Recover stale operation", action: "unlock" as const }]
 						: []),
 					{ id: "back", label: "Back", action: "back" },
@@ -242,10 +249,28 @@ export async function showSyncManager(
 				await runRoute("doctor");
 				return { kind: "stay" };
 			},
-			unlock: async () => {
-				await runRoute("unlock --stale");
-				return { kind: "stay" };
+			unlock: async ({ state, signal: actionSignal }) => {
+				const result = await recoverSyncAccess(
+					ctx,
+					state.manager,
+					runRoute,
+					sessionSignal,
+					actionSignal,
+				);
+				if (result === "close") return { kind: "close" };
+				return result === "restored" ? { kind: "to", screen: "main" } : { kind: "stay" };
 			},
+			recover: async ({ state, signal: actionSignal }) => {
+				const result = await recoverSyncAccess(
+					ctx,
+					state.manager,
+					runRoute,
+					sessionSignal,
+					actionSignal,
+				);
+				return { kind: result === "close" ? "close" : "stay" };
+			},
+			refresh: async () => ({ kind: "stay" }),
 			help: async () => {
 				await runRoute("help");
 				return { kind: "close" };
@@ -260,18 +285,11 @@ export async function showSyncManager(
 	await runMenu(ctx, menu, {
 		getState: async () => {
 			const pendingAttention = options.getAttention?.();
-			const [manager, lock] = await Promise.all([
-				describeManagerState(sessionSignal, pendingAttention),
-				inspectLock(),
-			]);
+			const manager = await describeManagerState(sessionSignal, pendingAttention);
 			if (pendingAttention && options.getAttention?.() === pendingAttention && !manager.attention) {
 				options.onSelectionResolved?.(pendingAttention);
 			}
-			return {
-				manager,
-				canRecover:
-					lock.status === "unreadable" || (lock.status === "valid" && isStaleLock(lock.lock)),
-			};
+			return { manager };
 		},
 		signal: sessionSignal,
 		isCurrent: () => !sessionSignal?.aborted,
@@ -282,18 +300,38 @@ function syncMainMenuItem(
 	label: string,
 ): ActionMenuItem<
 	"main" | "more" | "recovery",
-	"sync" | "switch" | "diff" | "settings" | "setups" | "connections" | "help" | "init"
+	| "sync"
+	| "switch"
+	| "diff"
+	| "settings"
+	| "setups"
+	| "connections"
+	| "recover"
+	| "refresh"
+	| "help"
+	| "init"
 > {
 	if (label === "More…") return { id: "more", label, to: "more" };
 	if (label === "History & recovery…") return { id: "recovery", label, to: "recovery" };
 	const actions = new Map<
 		string,
-		"sync" | "switch" | "diff" | "settings" | "setups" | "connections" | "help" | "init"
+		| "sync"
+		| "switch"
+		| "diff"
+		| "settings"
+		| "setups"
+		| "connections"
+		| "recover"
+		| "refresh"
+		| "help"
+		| "init"
 	>([
 		["Sync now (recommended)", "sync"],
 		["Switch sync setup", "switch"],
 		["Status & changes", "diff"],
 		["Settings", "settings"],
+		["Restore sync access… (recommended)", "recover"],
+		["Refresh operation status", "refresh"],
 		["Sync setups…", "setups"],
 		["Storage connections…", "connections"],
 		["Help", "help"],

package/src/operation-availability.ts

@@ -0,0 +1,64 @@
+import { inspectLock, isLockGuardHeld, isStaleLock, type LockInspection } from "./lock.js";
+import { errorMessage } from "./manager-helpers.js";
+import type { LockFile } from "./types.js";
+
+export type OperationAvailability =
+	| { kind: "free" }
+	| { kind: "live"; lock: LockFile }
+	| { kind: "busy"; lock?: LockFile; metadata: LockInspection["status"] }
+	| { kind: "recoverable-stale"; lock: LockFile }
+	| { kind: "recoverable-unreadable" }
+	| { kind: "inspection-error"; message: string };
+
+interface OperationInspectionDependencies {
+	inspectMetadata(): Promise<LockInspection>;
+	inspectGuard(): Promise<boolean>;
+}
+
+const DEFAULT_INSPECTION_DEPENDENCIES: OperationInspectionDependencies = {
+	inspectMetadata: inspectLock,
+	inspectGuard: isLockGuardHeld,
+};
+
+export async function inspectOperationAvailability(
+	dependencies: OperationInspectionDependencies = DEFAULT_INSPECTION_DEPENDENCIES,
+): Promise<OperationAvailability> {
+	try {
+		const metadata = await dependencies.inspectMetadata();
+		const guardHeld = await dependencies.inspectGuard();
+		return classifyOperationAvailability(metadata, guardHeld);
+	} catch (error) {
+		return { kind: "inspection-error", message: errorMessage(error) };
+	}
+}
+
+export function classifyOperationAvailability(
+	metadata: LockInspection,
+	guardHeld: boolean,
+): OperationAvailability {
+	if (metadata.status === "valid" && !isStaleLock(metadata.lock)) {
+		return { kind: "live", lock: metadata.lock };
+	}
+	if (guardHeld) {
+		return {
+			kind: "busy",
+			metadata: metadata.status,
+			...(metadata.status === "valid" ? { lock: metadata.lock } : {}),
+		};
+	}
+	if (metadata.status === "valid") {
+		return { kind: "recoverable-stale", lock: metadata.lock };
+	}
+	if (metadata.status === "unreadable") return { kind: "recoverable-unreadable" };
+	return { kind: "free" };
+}
+
+export function operationBlocksChanges(availability: OperationAvailability) {
+	return availability.kind !== "free";
+}
+
+export function operationCanRecover(availability: OperationAvailability) {
+	return (
+		availability.kind === "recoverable-stale" || availability.kind === "recoverable-unreadable"
+	);
+}

package/src/state-directory.ts

@@ -22,6 +22,14 @@ interface StateDirectoryGuard {
 	throwIfCompromised: () => void;
 }
 
+interface SharedStateDirectoryGuard {
+	guard: Promise<StateDirectoryGuard>;
+	users: number;
+	closing?: Promise<void>;
+}
+
+const sharedStateDirectoryGuards = new Map<string, SharedStateDirectoryGuard>();
+
 export function stateDir() {
 	const roots = inspectStateRoots();
 	if (roots.canonical) return canonicalStateDir();
@@ -40,7 +48,9 @@ export function stateDirectoryMigrationNotice() {
 }
 
 export async function withStateDirectoryAccess<T>(fn: () => Promise<T>): Promise<T> {
-	return runWithStateDirectoryGuard(await acquireStateDirectoryGuard(), fn);
+	const roots = inspectStateRoots();
+	if (!roots.legacy) return fn();
+	return runWithStateDirectoryGuard(await acquireSharedStateDirectoryGuard(), fn);
 }
 
 export async function migrateLegacyStateDirectory(): Promise<StateDirectoryPreparation> {
@@ -87,6 +97,50 @@ export async function migrateLegacyStateDirectory(): Promise<StateDirectoryPrepa
 	});
 }
 
+async function acquireSharedStateDirectoryGuard(): Promise<StateDirectoryGuard> {
+	const key = migrationLockPath();
+	for (;;) {
+		let shared = sharedStateDirectoryGuards.get(key);
+		if (shared?.closing) {
+			await shared.closing;
+			continue;
+		}
+		if (!shared) {
+			shared = { guard: acquireStateDirectoryGuard(), users: 0 };
+			sharedStateDirectoryGuards.set(key, shared);
+		}
+		shared.users += 1;
+		let guard: StateDirectoryGuard;
+		try {
+			guard = await shared.guard;
+		} catch (error) {
+			if (sharedStateDirectoryGuards.get(key) === shared) {
+				sharedStateDirectoryGuards.delete(key);
+			}
+			throw error;
+		}
+		let released = false;
+		return {
+			throwIfCompromised: guard.throwIfCompromised,
+			release: async () => {
+				if (released) return;
+				released = true;
+				shared.users -= 1;
+				if (shared.users > 0) return;
+				const closing = guard.release();
+				shared.closing = closing;
+				try {
+					await closing;
+				} finally {
+					if (sharedStateDirectoryGuards.get(key) === shared) {
+						sharedStateDirectoryGuards.delete(key);
+					}
+				}
+			},
+		};
+	}
+}
+
 async function acquireStateDirectoryGuard(): Promise<StateDirectoryGuard> {
 	let compromisedError: Error | undefined;
 	const release = await lockfile.lock(getAgentDir(), {