@narumitw/pi-sync 0.49.4 → 0.49.6

package/README.md

@@ -252,6 +252,7 @@ The menu is preferred, while deterministic routes remain available:
 /sync sync [--setup <name>]
 /sync history [--setup <name>]
 /sync rollback <snapshot-id> [--setup <name>]
+/sync migrate-state [--yes]
 /sync unlock --stale
 ```
 
@@ -274,17 +275,19 @@ dialog/notification protocol and does not gain settings mutation. Print and JSON
 | WebDAV | Verified strong conditional requests | Private settings username/app password | `<url>/<storage.path>` |
 | R2/S3 | Read-check-write-verify | Private settings credentials | `<bucket>/<storage.path>` |
 
-Git requires Git 2.30 or newer and a SHA-1-format remote repository. HTTPS userinfo, URL passwords, local paths, `file`, `git`, `ext`, and remote-helper transports are rejected. When editing a Git setup, changing its storage path also requires a new owned branch so the existing branch remains readable at its reviewed path. The private bare cache under `.pisync/git/` is rebuildable.
+Git requires Git 2.30 or newer and a SHA-1-format remote repository. HTTPS userinfo, URL passwords, local paths, `file`, `git`, `ext`, and remote-helper transports are rejected. When editing a Git setup, changing its storage path also requires a new owned branch so the existing branch remains readable at its reviewed path. The private bare cache under `<agent-dir>/pi-sync/git/` is rebuildable.
 
 WebDAV requires HTTPS except loopback tests. URL credentials, query strings, fragments, unsafe redirects, weak/missing ETags, and ignored conditional headers fail closed. `/sync doctor` verifies collection and conditional-write behavior with an isolated probe.
 
 S3/R2 stages immutable bundles, rechecks the visible head before publication, and verifies afterward. Unlike Git/WebDAV, generic S3 does not provide an atomic compare-and-swap for `latest.json`; status review remains important for simultaneous writers.
 
-Before pull or rollback, pi-sync writes a backup under `.pisync/backups/`. Apply preflights paths and checksums, journals all mutations, restores the prior state after failures, and recovers interrupted journals on startup. Removing a local setup or connection never deletes remote data.
+Before pull or rollback, pi-sync writes a backup under `<agent-dir>/pi-sync/backups/`. Apply preflights paths and checksums, journals all mutations, restores the prior state after failures, and recovers interrupted journals on startup. Removing a local setup or connection never deletes remote data.
+
+The operational state root is `<agent-dir>/pi-sync/`. An existing installation continues using `<agent-dir>/.pisync/` and shows migration guidance on startup; it is never moved merely because no sync is active. Close every other Pi process, then run `/sync migrate-state` and confirm the review (or pass `--yes` for an already reviewed RPC workflow). The command serializes against every upgraded state/cache user and atomically renames `.pisync/` only when no legacy sync lock or guard is active. Close Pi instances running older pi-sync versions during the migration because they do not understand the migration guard. If both roots exist, or either root is a symlink or non-directory, pi-sync refuses stateful work instead of merging, following, or deleting data. Preserve both roots before manual recovery; with every Pi process closed and no destination conflict, rollback is an atomic rename from `pi-sync/` back to `.pisync/`.
 
 ## 🛡️ Safety notes
 
-- Canonical, legacy, temporary, and recovery settings paths are denied from snapshots.
+- Canonical, legacy, temporary, and recovery settings paths are denied from snapshots; both `pi-sync/` and `.pisync/` state roots are permanently denied.
 - Push scans managed local content for common secret patterns.
 - Remote snapshot references, checksums, paths, manifests, response sizes, and publication revisions are validated.
 - Symlink parents, path escapes, duplicate paths, and unsafe file/directory replacement fail before local mutation.
@@ -302,9 +305,12 @@ Pi exposes terminal components rather than a semantic/ARIA tree. Release validat
 packages/pi-sync/
 ├── src/
 │   ├── index.ts
-│   ├── sync.ts
+│   ├── sync-extension.ts      # Lightweight Pi entry runtime and cached lazy loaders
+│   ├── sync.ts                # Compatibility barrel for package-local helpers
+│   ├── sync-errors.ts         # Lightweight setup/decision error contracts
 │   ├── config.ts
 │   ├── config-file.ts
+│   ├── state-directory.ts
 │   ├── settings-management.ts
 │   ├── manager-ui.ts
 │   ├── storage-connections-ui.ts
@@ -318,7 +324,8 @@ packages/pi-sync/
 │   ├── s3-backend.ts
 │   ├── webdav-backend.ts
 │   ├── git-backend.ts
-│   ├── snapshot.ts
+│   ├── snapshot-paths.ts      # Eager recovery-safe session path helpers
+│   ├── snapshot.ts            # Loaded only for snapshot operations/session push
 │   └── *.ts
 ├── test/
 ├── README.md

package/package.json

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

package/src/command.ts

@@ -19,6 +19,7 @@ export const SYNC_COMMANDS = [
 	{ name: "sync", description: "Push or pull as needed" },
 	{ name: "history", description: "Show recent remote snapshots" },
 	{ name: "rollback", description: "Apply a previous snapshot", usageSuffix: " <snapshot>" },
+	{ name: "migrate-state", description: "Move legacy state into pi-sync/" },
 	{ name: "unlock", description: "Remove a stale local lock", usageSuffix: " --stale" },
 ] as const;
 
@@ -60,6 +61,7 @@ const SYNC_FLAG_COMPLETIONS: Record<string, readonly CommandArgumentCompletion[]
 	],
 	history: [SETUP_FLAG_COMPLETION],
 	rollback: [...YES_FLAG_COMPLETIONS, SETUP_FLAG_COMPLETION],
+	"migrate-state": YES_FLAG_COMPLETIONS,
 	unlock: [{ value: "--stale", label: "--stale", description: "Remove only a stale lock" }],
 };
 
@@ -119,7 +121,10 @@ export function validateCommandOptions(command: string, options: CommandOptions)
 	if (options.setup && !setupAllowed.has(command)) {
 		throw new Error(`--setup is not supported by /sync ${command}.`);
 	}
-	if ((options.yes || options.force) && !["push", "pull", "sync", "rollback"].includes(command)) {
+	if (options.yes && !["push", "pull", "sync", "rollback", "migrate-state"].includes(command)) {
+		throw new Error(`Confirmation/force options are not supported by /sync ${command}.`);
+	}
+	if (options.force && !["push", "pull", "sync", "rollback"].includes(command)) {
 		throw new Error(`Confirmation/force options are not supported by /sync ${command}.`);
 	}
 	if (options.stale && command !== "unlock") {

package/src/config.ts

@@ -26,6 +26,7 @@ import {
 	normalizeGitRemoteIdentity,
 } from "./git-config.js";
 import { safeName } from "./paths.js";
+import { stateDir } from "./state-directory.js";
 import { normalizeSyncInclude } from "./sync-policy.js";
 import type {
 	AnySyncConfig,
@@ -751,9 +752,7 @@ function expandHome(value: string) {
 	return value === "~" || value.startsWith("~/") ? path.join(os.homedir(), value.slice(2)) : value;
 }
 
-export function stateDir() {
-	return path.join(agentDir(), ".pisync");
-}
+export { stateDir } from "./state-directory.js";
 
 export function localConfigTemplate(): PiSyncSettingsV3 {
 	return {

package/src/git-backend.ts

@@ -1,7 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import {
 	normalizeGitBranch,
 	normalizeGitDirectory,
@@ -23,6 +22,7 @@ import {
 	validateGitSnapshot,
 } from "./git-storage.js";
 import { posixJoin } from "./paths.js";
+import { stateDir } from "./state-directory.js";
 import {
 	type BackendDiagnostic,
 	type ExpectedRemoteHead,
@@ -74,7 +74,7 @@ export class GitSyncBackend implements SyncBackend {
 		if (!this.allowLocalRemotes) assertProductionRemote(config.profile.remote);
 		this.identity = gitBackendIdentity(config);
 		this.destination = gitDestination(config);
-		this.cacheRoot = options.cacheRoot ?? path.join(getAgentDir(), ".pisync", "git");
+		this.cacheRoot = options.cacheRoot ?? path.join(stateDir(), "git");
 		this.cacheDir = path.join(this.cacheRoot, this.identity.slice("git:".length), "repository.git");
 		this.commandTimeoutMs = options.commandTimeoutMs ?? COMMAND_TIMEOUT_MS;
 		this.postCommitTimeoutMs = options.postCommitTimeoutMs ?? POST_COMMIT_TIMEOUT_MS;

package/src/index.ts

@@ -1 +1 @@
-export { default } from "./sync.js";
+export { default } from "./sync-extension.js";

package/src/lock-policy.ts

@@ -0,0 +1,2 @@
+export const LOCK_GUARD_STALE_MS = 30_000;
+export const LOCK_GUARD_UPDATE_MS = 10_000;

package/src/lock.ts

@@ -1,53 +1,15 @@
 import { randomUUID } from "node:crypto";
-import {
-	mkdir,
-	mkdirSync,
-	realpath,
-	realpathSync,
-	rmdir,
-	rmdirSync,
-	stat,
-	statSync,
-	utimes,
-	utimesSync,
-} from "node:fs";
 import fs from "node:fs/promises";
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import lockfile from "proper-lockfile";
 import { ensureStateDir, lockPath } from "./config.js";
+import { LOCK_GUARD_STALE_MS, LOCK_GUARD_UPDATE_MS } from "./lock-policy.js";
+import { LOCKFILE_FS_ADAPTER } from "./lockfile-fs.js";
 import type { CommandOptions, LockFile } from "./types.js";
 
 const LOCK_STALE_MS = 30 * 60 * 1000;
-const GUARD_STALE_MS = 30_000;
-const GUARD_UPDATE_MS = 10_000;
 const MAX_PROCESS_ID = 2_147_483_647;
 
-type LockfileFsAdapter = {
-	mkdir: typeof mkdir;
-	mkdirSync: typeof mkdirSync;
-	realpath: typeof realpath;
-	realpathSync: typeof realpathSync;
-	rmdir: typeof rmdir;
-	rmdirSync: typeof rmdirSync;
-	stat: typeof stat;
-	statSync: typeof statSync;
-	utimes: typeof utimes;
-	utimesSync: typeof utimesSync;
-};
-
-const LOCKFILE_FS_ADAPTER: LockfileFsAdapter = {
-	mkdir,
-	mkdirSync,
-	realpath,
-	realpathSync,
-	rmdir,
-	rmdirSync,
-	stat,
-	statSync,
-	utimes,
-	utimesSync,
-};
-
 interface Guard {
 	release: () => Promise<void>;
 	throwIfCompromised: () => void;
@@ -175,7 +137,7 @@ export function isLockGuardHeld() {
 		fs: LOCKFILE_FS_ADAPTER,
 		lockfilePath: `${lockPath()}.guard`,
 		realpath: false,
-		stale: GUARD_STALE_MS,
+		stale: LOCK_GUARD_STALE_MS,
 	});
 }
 
@@ -267,8 +229,8 @@ async function acquireGuard(): Promise<Guard> {
 		fs: LOCKFILE_FS_ADAPTER,
 		lockfilePath: `${lockPath()}.guard`,
 		realpath: false,
-		stale: GUARD_STALE_MS,
-		update: GUARD_UPDATE_MS,
+		stale: LOCK_GUARD_STALE_MS,
+		update: LOCK_GUARD_UPDATE_MS,
 		onCompromised: (error) => {
 			compromisedError = error;
 		},

package/src/lockfile-fs.ts

@@ -0,0 +1,25 @@
+import {
+	mkdir,
+	mkdirSync,
+	realpath,
+	realpathSync,
+	rmdir,
+	rmdirSync,
+	stat,
+	statSync,
+	utimes,
+	utimesSync,
+} from "node:fs";
+
+export const LOCKFILE_FS_ADAPTER = {
+	mkdir,
+	mkdirSync,
+	realpath,
+	realpathSync,
+	rmdir,
+	rmdirSync,
+	stat,
+	statSync,
+	utimes,
+	utimesSync,
+};

package/src/paths.ts

@@ -9,6 +9,8 @@ export function isDeniedPath(relativePath: string) {
 		segments.includes("node_modules") ||
 		segments.includes(".git") ||
 		segments.includes(".pisync") ||
+		segments.includes("pi-sync") ||
+		segments.includes(".pi-sync-state-migration.lock") ||
 		base === ".env" ||
 		base.startsWith(".env.") ||
 		base.endsWith(".env") ||

package/src/setup-switch.ts

@@ -8,9 +8,12 @@ import {
 	syncSetupReviewIdentity,
 	updateLocalConfig,
 } from "./config.js";
+import { SetupPullRequiresUiError } from "./sync-errors.js";
 import { safeTerminalText } from "./sync-format.js";
 import type { OnSwitchAction } from "./types.js";
 
+export { SetupPullRequiresUiError } from "./sync-errors.js";
+
 export const SETUP_SWITCH_ACTION_OPTIONS: ReadonlyArray<{
 	label: string;
 	value: OnSwitchAction;
@@ -34,8 +37,6 @@ export async function saveOnSwitch(action: OnSwitchAction, signal?: AbortSignal)
 
 export type SetupPullOutcome = "applied" | "cancelled";
 
-export class SetupPullRequiresUiError extends Error {}
-
 export interface SetupSwitchResult {
 	pullApplied: boolean;
 }

package/src/snapshot-paths.ts

@@ -0,0 +1,13 @@
+import path from "node:path";
+
+function expandHome(value: string) {
+	if (value === "~") return process.env.HOME ?? value;
+	if (value.startsWith("~/")) return path.join(process.env.HOME ?? "~", value.slice(2));
+	return value;
+}
+
+export function sessionStorageRoot(root: string, configuredSessionDir?: string) {
+	return configuredSessionDir
+		? path.resolve(expandHome(configuredSessionDir))
+		: path.resolve(root, "sessions");
+}

package/src/snapshot-transaction.ts

@@ -4,7 +4,7 @@ import path from "node:path";
 import { agentDir, stateDir } from "./config.js";
 import { withLock } from "./lock.js";
 import { assertWithinRoot, isPathInside } from "./paths.js";
-import { sessionStorageRoot } from "./snapshot.js";
+import { sessionStorageRoot } from "./snapshot-paths.js";
 import type { SnapshotApplyPlan } from "./types.js";
 
 const JOURNAL_VERSION = 1;

package/src/snapshot.ts

@@ -5,8 +5,10 @@ import os from "node:os";
 import path from "node:path";
 import { agentDir, configuredSessionDir } from "./config.js";
 import { isDeniedPath, posixJoin, safeJoin, toPosix } from "./paths.js";
+import { sessionStorageRoot } from "./snapshot-paths.js";
 
 export { isDeniedPath } from "./paths.js";
+export { sessionStorageRoot } from "./snapshot-paths.js";
 
 import {
 	canonicalSnapshotPathForConfig,
@@ -39,12 +41,6 @@ const SECRET_PATTERNS = [
 	/gh[pousr]_[A-Za-z0-9_]{20,}/,
 ];
 
-function expandHome(value: string) {
-	if (value === "~") return process.env.HOME ?? value;
-	if (value.startsWith("~/")) return path.join(process.env.HOME ?? "~", value.slice(2));
-	return value;
-}
-
 function selectTopLevelFileEntry(entries: Dirent[], fileName: string) {
 	const exact = entries.find((entry) => entry.isFile() && entry.name === fileName);
 	if (exact) return exact;
@@ -223,12 +219,6 @@ export function isSessionFilePath(relativePath: string) {
 	return isSessionPath(normalized) && normalized.endsWith(".jsonl");
 }
 
-export function sessionStorageRoot(root: string, configuredSessionDir?: string) {
-	return configuredSessionDir
-		? path.resolve(expandHome(configuredSessionDir))
-		: path.resolve(root, "sessions");
-}
-
 export function sessionSnapshotPathFromAbsolute(
 	sessionFile: string,
 	configuredSessionDir?: string,

package/src/state-directory.ts

@@ -0,0 +1,184 @@
+import { lstatSync } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import lockfile from "proper-lockfile";
+import { LOCK_GUARD_STALE_MS } from "./lock-policy.js";
+import { LOCKFILE_FS_ADAPTER } from "./lockfile-fs.js";
+
+const CANONICAL_DIRECTORY_NAME = "pi-sync";
+const LEGACY_DIRECTORY_NAME = ".pisync";
+const MIGRATION_LOCK_NAME = ".pi-sync-state-migration.lock";
+const MIGRATION_LOCK_STALE_MS = 30_000;
+const MIGRATION_LOCK_UPDATE_MS = 10_000;
+
+export type StateDirectoryPreparation =
+	| { status: "ready" }
+	| { status: "migrated"; message: string }
+	| { status: "deferred"; message: string };
+
+interface StateDirectoryGuard {
+	release: () => Promise<void>;
+	throwIfCompromised: () => void;
+}
+
+export function stateDir() {
+	const roots = inspectStateRoots();
+	if (roots.canonical) return canonicalStateDir();
+	if (roots.legacy) return legacyStateDir();
+	return canonicalStateDir();
+}
+
+export function legacyStateDir() {
+	return path.join(getAgentDir(), LEGACY_DIRECTORY_NAME);
+}
+
+export function stateDirectoryMigrationNotice() {
+	const roots = inspectStateRoots();
+	if (!roots.legacy) return undefined;
+	return "Legacy pi-sync state is still stored in .pisync. Close other Pi sessions, then run /sync migrate-state to move it to pi-sync/.";
+}
+
+export async function withStateDirectoryAccess<T>(fn: () => Promise<T>): Promise<T> {
+	return runWithStateDirectoryGuard(await acquireStateDirectoryGuard(), fn);
+}
+
+export async function migrateLegacyStateDirectory(): Promise<StateDirectoryPreparation> {
+	const initial = inspectStateRoots();
+	if (initial.canonical || !initial.legacy) return { status: "ready" };
+
+	let guard: StateDirectoryGuard;
+	try {
+		guard = await acquireStateDirectoryGuard();
+	} catch (error) {
+		if (!isLockHeldError(error)) throw error;
+		return {
+			status: "deferred",
+			message:
+				"pi-sync state migration was deferred because another state user is active. Close other Pi sessions and retry.",
+		};
+	}
+	return runWithStateDirectoryGuard(guard, async () => {
+		const roots = inspectStateRoots();
+		if (roots.canonical || !roots.legacy) return { status: "ready" };
+
+		const legacyLock = path.join(legacyStateDir(), "lock");
+		const legacyGuardHeld = await lockfile.check(legacyLock, {
+			fs: LOCKFILE_FS_ADAPTER,
+			lockfilePath: `${legacyLock}.guard`,
+			realpath: false,
+			stale: LOCK_GUARD_STALE_MS,
+		});
+		if (legacyGuardHeld || (await pathExists(legacyLock))) {
+			return {
+				status: "deferred",
+				message:
+					"pi-sync state migration was deferred because the legacy directory is busy. Close other Pi sessions, clear any confirmed stale sync lock, and retry.",
+			};
+		}
+		guard.throwIfCompromised();
+		await fs.rename(legacyStateDir(), canonicalStateDir());
+		guard.throwIfCompromised();
+		inspectStateRoots();
+		return {
+			status: "migrated",
+			message: `Migrated pi-sync state from ${legacyStateDir()} to ${canonicalStateDir()}.`,
+		};
+	});
+}
+
+async function acquireStateDirectoryGuard(): Promise<StateDirectoryGuard> {
+	let compromisedError: Error | undefined;
+	const release = await lockfile.lock(getAgentDir(), {
+		fs: LOCKFILE_FS_ADAPTER,
+		lockfilePath: migrationLockPath(),
+		realpath: false,
+		stale: MIGRATION_LOCK_STALE_MS,
+		update: MIGRATION_LOCK_UPDATE_MS,
+		retries: { retries: 20, minTimeout: 10, maxTimeout: 50 },
+		onCompromised: (error) => {
+			compromisedError = error;
+		},
+	});
+	return {
+		release,
+		throwIfCompromised: () => {
+			if (compromisedError) throw compromisedError;
+		},
+	};
+}
+
+async function runWithStateDirectoryGuard<T>(guard: StateDirectoryGuard, fn: () => Promise<T>) {
+	let result: T | undefined;
+	let failed = false;
+	let failure: unknown;
+	try {
+		guard.throwIfCompromised();
+		result = await fn();
+		guard.throwIfCompromised();
+	} catch (error) {
+		failed = true;
+		failure = error;
+	}
+	try {
+		await guard.release();
+	} catch (error) {
+		if (!failed) {
+			failed = true;
+			failure = error;
+		}
+	}
+	if (failed) throw failure;
+	return result as T;
+}
+
+function isLockHeldError(error: unknown) {
+	return (error as NodeJS.ErrnoException).code === "ELOCKED";
+}
+
+function canonicalStateDir() {
+	return path.join(getAgentDir(), CANONICAL_DIRECTORY_NAME);
+}
+
+function migrationLockPath() {
+	return path.join(getAgentDir(), MIGRATION_LOCK_NAME);
+}
+
+function inspectStateRoots() {
+	const canonical = isDirectoryRoot(canonicalStateDir(), "canonical");
+	const legacy = isDirectoryRoot(legacyStateDir(), "legacy");
+	if (canonical && legacy) {
+		throw new Error(
+			`Both legacy ${legacyStateDir()} and canonical ${canonicalStateDir()} pi-sync state directories exist. Close all Pi sessions and reconcile the directories manually; pi-sync will not merge or delete either directory.`,
+		);
+	}
+	return { canonical, legacy };
+}
+
+function isDirectoryRoot(directory: string, label: string) {
+	try {
+		const entry = lstatSync(directory);
+		if (entry.isSymbolicLink()) {
+			throw new Error(
+				`Refusing to use ${label} pi-sync state directory symbolic link: ${directory}`,
+			);
+		}
+		if (!entry.isDirectory()) {
+			throw new Error(`${label} pi-sync state path is not a directory: ${directory}`);
+		}
+		return true;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+		throw error;
+	}
+}
+
+async function pathExists(filePath: string) {
+	try {
+		await fs.lstat(filePath);
+		return true;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+		throw error;
+	}
+}

package/src/sync-decision.ts

@@ -1,4 +1,5 @@
 import { syncConfigReviewIdentity } from "./config.js";
+import { SyncDecisionRequiredError } from "./sync-errors.js";
 import { formatDiff, formatSnapshotOnlyDiff, safeTerminalText } from "./sync-format.js";
 import { includeFromSelectionConfig } from "./sync-policy.js";
 import { syncPolicyChanged } from "./sync-state.js";
@@ -29,15 +30,10 @@ export interface SyncDecision {
 	directMessage: string;
 }
 
-export class SyncDecisionRequiredError extends Error {
-	readonly decision: SyncDecision;
-
-	constructor(decision: SyncDecision) {
-		super(decision.directMessage);
-		this.name = "SyncDecisionRequiredError";
-		this.decision = decision;
-	}
-}
+export {
+	isSyncDecisionRequiredError,
+	SyncDecisionRequiredError,
+} from "./sync-errors.js";
 
 interface CreateSyncDecisionOptions {
 	kind: SyncDecisionKind;
@@ -104,10 +100,6 @@ export function createSyncDecision(options: CreateSyncDecisionOptions) {
 	});
 }
 
-export function isSyncDecisionRequiredError(error: unknown): error is SyncDecisionRequiredError {
-	return error instanceof SyncDecisionRequiredError;
-}
-
 function safeList(values: readonly string[]) {
 	return values.length > 0 ? values.map(safeTerminalText).join(", ") : "none";
 }

package/src/sync-errors.ts

@@ -0,0 +1,23 @@
+import type { SyncDecision } from "./sync-decision.js";
+
+export class SetupPullRequiresUiError extends Error {}
+
+export class SyncDecisionRequiredError extends Error {
+	readonly decision: SyncDecision;
+
+	constructor(decision: SyncDecision) {
+		super(decision.directMessage);
+		this.name = "SyncDecisionRequiredError";
+		this.decision = decision;
+	}
+}
+
+export function isSyncDecisionRequiredError(error: unknown): error is SyncDecisionRequiredError {
+	return error instanceof SyncDecisionRequiredError;
+}
+
+export function errorMessage(error: unknown) {
+	const message = error instanceof Error ? error.message : String(error);
+	// biome-ignore lint/suspicious/noControlCharactersInRegex: Escape untrusted terminal controls.
+	return message.replace(/[\u0000-\u001f\u007f-\u009f]/gu, "?");
+}