@narumitw/pi-sync 0.49.14 → 0.50.0

package/src/{snapshot.ts → snapshot/snapshot.ts}

@@ -3,11 +3,11 @@ import type { Dirent } from "node:fs";
 import fs from "node:fs/promises";
 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 { isDeniedPath, posixJoin, safeJoin, toPosix } from "../paths.js";
+import { agentDir, configuredSessionDir } from "./session-paths.js";
 import { sessionStorageRoot } from "./snapshot-paths.js";
 
-export { isDeniedPath } from "./paths.js";
+export { isDeniedPath } from "../paths.js";
 export { sessionStorageRoot } from "./snapshot-paths.js";
 
 import {
@@ -23,10 +23,10 @@ import {
 	selectionForSnapshot,
 	snapshotSelectionInclude,
 	syncIncludeSelection,
-} from "./sync-policy.js";
-import type { Snapshot, SnapshotFile, SnapshotOptions } from "./types.js";
+} from "../sync/sync-policy.js";
+import type { Snapshot, SnapshotFile, SnapshotOptions } from "./snapshot-types.js";
 
-export { canonicalSnapshotPathForConfig, isConfiguredSnapshotPath } from "./sync-policy.js";
+export { canonicalSnapshotPathForConfig, isConfiguredSnapshotPath } from "../sync/sync-policy.js";
 
 const VERSION = 1;
 const TOP_LEVEL_FILES: readonly string[] = DEFAULT_SYNC_INCLUDE.filter((name) =>
@@ -96,12 +96,13 @@ export async function createSnapshot(
 	profile: string,
 	options: SnapshotOptions = {},
 ): Promise<Snapshot> {
+	options.signal?.throwIfAborted();
 	const include = effectiveInclude(options);
 	const syncSessions = include.includes("sessions");
-	const files = await collectFiles(agentDir(), {
-		include,
-		sessionDir: options.sessionDir ?? (await configuredSessionDir()),
-	});
+	const sessionDir = options.sessionDir ?? (await configuredSessionDir());
+	options.signal?.throwIfAborted();
+	const files = await collectFiles(agentDir(), { include, sessionDir, signal: options.signal });
+	options.signal?.throwIfAborted();
 	return {
 		version: VERSION,
 		id: snapshotId(),
@@ -127,48 +128,61 @@ export async function collectFiles(
 	root: string,
 	options: SnapshotOptions = {},
 ): Promise<SnapshotFile[]> {
+	const signal = options.signal;
+	signal?.throwIfAborted();
 	const results: SnapshotFile[] = [];
 	const entries = await fs.readdir(root, { withFileTypes: true });
+	signal?.throwIfAborted();
 	const selection = syncIncludeSelection(effectiveInclude(options));
 	const selectedFiles = new Set<string>(selection.builtIns);
 	for (const entry of entries) {
 		if (entry.isDirectory() && TOP_LEVEL_DIRS.has(entry.name) && selectedFiles.has(entry.name)) {
-			await collectDirectory(results, root, entry.name);
+			await collectDirectory(results, root, entry.name, { signal });
 		}
 	}
 	for (const fileName of TOP_LEVEL_FILES) {
 		if (!selectedFiles.has(fileName)) continue;
 		const entry = selectTopLevelFileEntry(entries, fileName);
-		if (entry) await addFile(results, root, entry.name, fileName);
+		if (entry) await addFile(results, root, entry.name, fileName, signal);
 	}
 	for (const relativePath of selection.custom) {
-		await collectIncludedPath(results, root, relativePath);
+		await collectIncludedPath(results, root, relativePath, signal);
 	}
 	if (selection.sessions) {
 		try {
 			await collectDirectory(results, sessionStorageRoot(root, options.sessionDir), "", {
 				sessionsOnly: true,
 				virtualPrefix: "sessions",
+				signal,
 			});
 		} catch (error) {
 			if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
 		}
 	}
+	signal?.throwIfAborted();
 	return results.sort((left, right) => left.path.localeCompare(right.path));
 }
 
-async function collectIncludedPath(results: SnapshotFile[], root: string, relativePath: string) {
+async function collectIncludedPath(
+	results: SnapshotFile[],
+	root: string,
+	relativePath: string,
+	signal?: AbortSignal,
+) {
+	signal?.throwIfAborted();
 	const absolutePath = safeJoin(root, relativePath);
 	try {
 		const stat = await fs.lstat(absolutePath);
-		if (stat.isFile()) await addFile(results, root, relativePath);
-		else if (stat.isDirectory()) await collectDirectory(results, root, relativePath);
+		signal?.throwIfAborted();
+		if (stat.isFile()) await addFile(results, root, relativePath, relativePath, signal);
+		else if (stat.isDirectory()) await collectDirectory(results, root, relativePath, { signal });
 	} catch (error) {
 		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
 		if (!relativePath.includes("/")) {
 			const entries = await fs.readdir(root, { withFileTypes: true });
+			signal?.throwIfAborted();
 			const entry = selectTopLevelFileEntry(entries, relativePath);
-			if (entry) await addFile(results, root, entry.name, relativePath);
+			if (entry) await addFile(results, root, entry.name, relativePath, signal);
 		}
 	}
 }
@@ -177,10 +191,12 @@ async function collectDirectory(
 	results: SnapshotFile[],
 	root: string,
 	relativeDirectory: string,
-	options: { sessionsOnly?: boolean; virtualPrefix?: string } = {},
+	options: { sessionsOnly?: boolean; virtualPrefix?: string; signal?: AbortSignal } = {},
 ) {
+	options.signal?.throwIfAborted();
 	const absoluteDirectory = path.join(root, relativeDirectory);
 	for (const entry of await fs.readdir(absoluteDirectory, { withFileTypes: true })) {
+		options.signal?.throwIfAborted();
 		const relativePath = relativeDirectory ? posixJoin(relativeDirectory, entry.name) : entry.name;
 		const snapshotPath = options.virtualPrefix
 			? posixJoin(options.virtualPrefix, relativePath)
@@ -189,7 +205,7 @@ async function collectDirectory(
 		if (entry.isDirectory()) {
 			await collectDirectory(results, root, relativePath, options);
 		} else if (entry.isFile() && (!options.sessionsOnly || isSessionFilePath(snapshotPath))) {
-			await addFile(results, root, relativePath, snapshotPath);
+			await addFile(results, root, relativePath, snapshotPath, options.signal);
 		}
 	}
 }
@@ -199,10 +215,13 @@ async function addFile(
 	root: string,
 	relativePath: string,
 	snapshotPath = relativePath,
+	signal?: AbortSignal,
 ) {
+	signal?.throwIfAborted();
 	if (!isSafeSnapshotPath(snapshotPath)) return;
 	const absolutePath = safeJoin(root, relativePath);
-	const content = await fs.readFile(absolutePath);
+	const content = await fs.readFile(absolutePath, { signal });
+	signal?.throwIfAborted();
 	results.push({
 		path: snapshotPath,
 		contentBase64: content.toString("base64"),

package/src/state/json-file.ts

@@ -0,0 +1,20 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export async function readJsonIfExists<T>(filePath: string): Promise<T | undefined> {
+	try {
+		return JSON.parse(await fs.readFile(filePath, "utf8")) as T;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+		throw error;
+	}
+}
+
+export async function writeJson(filePath: string, value: unknown) {
+	await fs.mkdir(path.dirname(filePath), { recursive: true });
+	const temp = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
+	await fs.writeFile(temp, `${JSON.stringify(value, null, "\t")}\n`, { mode: 0o600 });
+	if (process.platform !== "win32") await fs.chmod(temp, 0o600);
+	await fs.rename(temp, filePath);
+}

package/src/{lock.ts → state/lock.ts}

@@ -2,10 +2,11 @@ import { randomUUID } from "node:crypto";
 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 type { CommandOptions } from "../commands/command-types.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";
+import type { LockFile } from "./state-types.js";
+import { ensureStateDir, lockPath } from "./sync-state-store.js";
 
 const LOCK_STALE_MS = 30 * 60 * 1000;
 const MAX_PROCESS_ID = 2_147_483_647;

package/src/{operation-availability.ts → state/operation-availability.ts}

@@ -1,6 +1,6 @@
+import { errorMessage } from "../sync/sync-errors.js";
 import { inspectLock, isLockGuardHeld, isStaleLock, type LockInspection } from "./lock.js";
-import { errorMessage } from "./manager-helpers.js";
-import type { LockFile } from "./types.js";
+import type { LockFile } from "./state-types.js";
 
 export type OperationAvailability =
 	| { kind: "free" }

package/src/state/state-types.ts

@@ -0,0 +1,20 @@
+export interface SyncState {
+	version: number;
+	profile: string;
+	lastAppliedSnapshot?: string;
+	lastRemoteRevision?: string;
+	lastRemoteEtag?: string;
+	lastFileHashes: Record<string, string>;
+	include?: string[];
+	/** Legacy state fields are read only so v3 can detect and replace stale policy state. */
+	syncFiles?: string[];
+	syncSessions?: boolean;
+	extraFiles?: string[];
+}
+
+export interface LockFile {
+	id: string;
+	pid: number;
+	command: string;
+	startedAt: string;
+}

package/src/state/sync-state-store.ts

@@ -0,0 +1,62 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { backendIdentityCoordinates } from "../backends/backend-identity.js";
+import { safeName } from "../paths.js";
+import type { AnySyncConfig } from "../settings/settings-types.js";
+import { readJsonIfExists, writeJson } from "./json-file.js";
+import { stateDir } from "./state-directory.js";
+import type { SyncState } from "./state-types.js";
+
+const STATE_VERSION = 2;
+
+/** Bounded observation token; do not retain the full baseline in passive UI state. */
+export function syncStateFingerprint(state: SyncState) {
+	return createHash("sha256").update(JSON.stringify(state)).digest("hex");
+}
+
+export async function readState(profile: string): Promise<SyncState> {
+	return (
+		(await readJsonIfExists<SyncState>(statePath(profile))) ?? {
+			version: STATE_VERSION,
+			profile,
+			lastFileHashes: {},
+		}
+	);
+}
+
+export async function writeState(profile: string, state: SyncState) {
+	await writeJson(statePath(profile), state);
+}
+
+export async function readStateForConfig(config: AnySyncConfig): Promise<SyncState> {
+	return (
+		(await readJsonIfExists<SyncState>(statePathForConfig(config))) ?? {
+			version: STATE_VERSION,
+			profile: config.snapshotIdentity,
+			lastFileHashes: {},
+		}
+	);
+}
+
+export async function writeStateForConfig(config: AnySyncConfig, state: SyncState) {
+	await writeJson(statePathForConfig(config), state);
+}
+
+export function statePathForConfig(config: AnySyncConfig) {
+	const identity = backendIdentityCoordinates(config);
+	const hash = createHash("sha256").update(identity).digest("hex").slice(0, 16);
+	return path.join(stateDir(), "setups", `${config.backend.type}-${hash}.state.json`);
+}
+
+function statePath(profile: string) {
+	return path.join(stateDir(), `${safeName(profile)}.state.json`);
+}
+
+export function lockPath() {
+	return path.join(stateDir(), "lock");
+}
+
+export async function ensureStateDir() {
+	await fs.mkdir(stateDir(), { recursive: true });
+}

package/src/sync/automatic-sync.ts

@@ -0,0 +1,103 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { setSyncSetupCompletions } from "../commands/command.js";
+import type { CommandOptions } from "../commands/command-types.js";
+import { loadConfig, loadPartialConfig } from "../settings/config.js";
+import { isMissingConfigError } from "../settings/config-errors.js";
+import { consumeLocalConfigMigrationNotice } from "../settings/config-file.js";
+import { configuredSyncSetupNames } from "../settings/settings-store.js";
+import { snapshotOptionsForContext } from "../snapshot/session-paths.js";
+import { recoverSnapshotTransactionsOnStartup } from "../snapshot/snapshot-transaction.js";
+import { withLock } from "../state/lock.js";
+import { stateDirectoryMigrationNotice } from "../state/state-directory.js";
+import { ensureStateDir, readStateForConfig } from "../state/sync-state-store.js";
+import { safeTerminalText } from "../ui/terminal-text.js";
+import { throwIfAborted } from "./signals.js";
+import { errorMessage } from "./sync-errors.js";
+import type { SyncLoaders } from "./sync-loaders.js";
+
+const AUTO_SYNC_OPTIONS: CommandOptions = {
+	yes: true,
+	force: false,
+	stale: false,
+	silent: true,
+	reload: false,
+	auto: true,
+	args: [],
+};
+
+const STATUS_KEY = "sync";
+
+export async function startSession(ctx: ExtensionContext, signal: AbortSignal) {
+	throwIfAborted(signal);
+	const stateNotice = stateDirectoryMigrationNotice();
+	if (stateNotice && ctx.hasUI) ctx.ui.notify(stateNotice, "warning");
+	// Recovery can restore managed files: finish it before Pi accepts user edits.
+	// Unlike remote inspection, it must never be detached behind startup.
+	await recoverSnapshotTransactionsOnStartup();
+	throwIfAborted(signal);
+	try {
+		const names = await configuredSyncSetupNames();
+		throwIfAborted(signal);
+		setSyncSetupCompletions(names);
+	} catch {
+		if (signal.aborted) return;
+		setSyncSetupCompletions([]);
+	}
+	const migrationNotice = consumeLocalConfigMigrationNotice();
+	if (migrationNotice && ctx.hasUI) ctx.ui.notify(migrationNotice, "warning");
+	throwIfAborted(signal);
+	if (!ctx.hasUI) return;
+	try {
+		const config = await loadConfig();
+		throwIfAborted(signal);
+		return config.automatic ? config : undefined;
+	} catch (error) {
+		throwIfAborted(signal);
+		if (!isMissingConfigError(error)) {
+			ctx.ui.notify(
+				`pi-sync startup check skipped: ${safeTerminalText(errorMessage(error))}`,
+				"warning",
+			);
+		}
+	}
+}
+
+export async function autoPushSessions(
+	ctx: ExtensionContext,
+	signal: AbortSignal,
+	loaders: SyncLoaders,
+) {
+	try {
+		const partial = await loadPartialConfig();
+		throwIfAborted(signal);
+		if (!partial.automatic) return;
+		if (!partial.include.includes("sessions")) return;
+		await ensureStateDir();
+		throwIfAborted(signal);
+		const config = await loadConfig();
+		throwIfAborted(signal);
+		if (!config.include.includes("sessions")) return;
+		const [operations, snapshotModule, syncStateModule] = await Promise.all([
+			loaders.operations(),
+			loaders.snapshot(),
+			loaders.syncState(),
+		]);
+		throwIfAborted(signal);
+		await withLock("auto-session-push", async () => {
+			throwIfAborted(signal);
+			const state = await readStateForConfig(config);
+			throwIfAborted(signal);
+			const local = await snapshotModule.createSnapshot(config.snapshotIdentity, {
+				...snapshotOptionsForContext(ctx, config),
+				signal,
+			});
+			throwIfAborted(signal);
+			if (!syncStateModule.hasLocalChanges(local, state, config)) return;
+			await operations.push(ctx, { ...AUTO_SYNC_OPTIONS, signal }, { config, state, local });
+		});
+	} catch (error) {
+		if (signal.aborted || isMissingConfigError(error)) return;
+		ctx.ui.setStatus(STATUS_KEY, undefined);
+		ctx.ui.notify(`pi-sync session push skipped: ${errorMessage(error)}`, "warning");
+	}
+}

package/src/{remote-snapshot.ts → sync/remote-snapshot.ts}

@@ -1,6 +1,9 @@
-import { syncConfigReviewFingerprint } from "./config.js";
-import type { RemoteHead, SyncBackend } from "./sync-backend.js";
-import { safeTerminalText } from "./sync-format.js";
+import type { RemoteHead, SyncBackend } from "../backends/sync-backend.js";
+import { syncConfigReviewFingerprint } from "../settings/config.js";
+import type { AnySyncConfig } from "../settings/settings-types.js";
+import { filterSnapshotForConfigPolicy } from "../snapshot/snapshot.js";
+import type { Snapshot } from "../snapshot/snapshot-types.js";
+import { safeTerminalText } from "../ui/terminal-text.js";
 import {
 	inspectRemoteSelection,
 	type RemoteSelectionState,
@@ -8,7 +11,6 @@ import {
 	sameSyncInclude,
 	snapshotSelectionInclude,
 } from "./sync-policy.js";
-import type { AnySyncConfig, Snapshot } from "./types.js";
 
 export async function readSnapshotForHead(
 	backend: SyncBackend,
@@ -58,3 +60,24 @@ export function formatRemoteSelectionStatus(state: RemoteSelectionState | undefi
 function safeList(values: readonly string[]) {
 	return values.length > 0 ? values.map(safeTerminalText).join(", ") : "none";
 }
+
+export async function readRemoteSnapshot(
+	backend: SyncBackend,
+	config: AnySyncConfig,
+	signal?: AbortSignal,
+	options: { allowSelectionDifference?: boolean } = {},
+) {
+	const head = await backend.readHead(signal);
+	if (!head) return { head: undefined, snapshot: undefined, selectionState: undefined };
+	const snapshot = await readSnapshotForHead(backend, head, signal);
+	const selectionState = inspectRemoteSelection(config.include, snapshot);
+	if (!options.allowSelectionDifference && selectionState.kind === "different") {
+		const configIdentity = syncConfigReviewFingerprint(config);
+		throw remoteSelectionMismatch(config, selectionState.include, configIdentity);
+	}
+	return {
+		head,
+		snapshot: filterSnapshotForConfigPolicy(snapshot, config),
+		selectionState,
+	};
+}

package/src/{setup-switch.ts → sync/setup-switch.ts}

@@ -1,16 +1,15 @@
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import { setSyncSetupCompletions } from "./command.js";
+import { setSyncSetupCompletions } from "../commands/command.js";
 import {
-	configuredSyncSetupNames,
 	loadConfig,
-	normalizeOnSwitch,
 	syncConfigReviewIdentity,
 	syncSetupReviewIdentity,
-	updateLocalConfig,
-} from "./config.js";
+} from "../settings/config.js";
+import { configuredSyncSetupNames, updateLocalConfig } from "../settings/settings-store.js";
+import type { OnSwitchAction } from "../settings/settings-types.js";
+import { normalizeOnSwitch } from "../settings/settings-validation.js";
+import { safeTerminalText } from "../ui/terminal-text.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";
 

package/src/sync/signals.ts

@@ -0,0 +1,10 @@
+export function throwIfAborted(signal?: AbortSignal) {
+	if (!signal?.aborted) return;
+	throw signal.reason instanceof Error
+		? signal.reason
+		: new DOMException("The operation was aborted", "AbortError");
+}
+
+export function combineSignals(primary: AbortSignal, secondary?: AbortSignal) {
+	return secondary ? AbortSignal.any([primary, secondary]) : primary;
+}

package/src/sync/startup-check.ts

@@ -0,0 +1,128 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { loadConfigForCheck, syncCheckConfigFingerprint } from "../settings/config.js";
+import { isMissingConfigError } from "../settings/config-errors.js";
+import type { AnySyncConfig } from "../settings/settings-types.js";
+import { snapshotOptionsForContext } from "../snapshot/session-paths.js";
+import { withLock } from "../state/lock.js";
+import { withStateDirectoryAccess } from "../state/state-directory.js";
+import { readStateForConfig, syncStateFingerprint } from "../state/sync-state-store.js";
+import type { SyncAttentionController } from "../ui/sync-attention.js";
+import { safeTerminalText } from "../ui/terminal-text.js";
+import { combineSignals, throwIfAborted } from "./signals.js";
+import { errorMessage } from "./sync-errors.js";
+import type { SyncLoaders } from "./sync-loaders.js";
+
+const STATUS_KEY = "sync";
+
+/** One owned task per extension session, never keyed by the shared headless UI. */
+export function createStartupCheck(
+	loaders: SyncLoaders,
+	attention: SyncAttentionController,
+	timeoutMs = 30_000,
+) {
+	let active:
+		| {
+				controller: AbortController;
+				promise: Promise<void>;
+				owner: ExtensionContext["sessionManager"];
+		  }
+		| undefined;
+
+	return {
+		start(ctx: ExtensionContext, sessionSignal: AbortSignal, initialConfig?: AnySyncConfig) {
+			if (!ctx.hasUI || sessionSignal.aborted) return;
+			if (active) throw new Error("Previous startup check has not been drained.");
+			const controller = new AbortController();
+			const signal = combineSignals(sessionSignal, controller.signal);
+			const task = { controller, owner: ctx.sessionManager, promise: Promise.resolve() };
+			active = task;
+			const isCurrent = () =>
+				!sessionSignal.aborted && active === task && task.owner === ctx.sessionManager;
+			const timer = setTimeout(
+				() => controller.abort(new DOMException("Startup check timed out", "TimeoutError")),
+				timeoutMs,
+			);
+			let config: AnySyncConfig | undefined;
+			let checking = false;
+			// Handle every detached rejection here; Pi's awaited event runner cannot catch it.
+			task.promise = Promise.resolve()
+				.then(async () => {
+					try {
+						throwIfAborted(signal);
+						config = initialConfig ?? (await loadConfigForCheck());
+						throwIfAborted(signal);
+						if (!config.automatic) return;
+						const captured = config;
+						const identity = syncCheckConfigFingerprint(captured);
+						checking = true;
+						ctx.ui.setStatus(STATUS_KEY, "checking in background");
+						const { inspectSync } = await loaders.inspection();
+						throwIfAborted(signal);
+						const currentConfig = await loadConfigForCheck();
+						throwIfAborted(signal);
+						if (syncCheckConfigFingerprint(currentConfig) !== identity) return;
+						// Lock order: state migration guard → sync operation → backend cache.
+						// Read heads may write only private cache data. Never call doctor/syncBoth.
+						const inspection = await withStateDirectoryAccess(() => {
+							throwIfAborted(signal);
+							return withLock("startup-check", () => {
+								throwIfAborted(signal);
+								return inspectSync(captured, snapshotOptionsForContext(ctx, captured), signal);
+							});
+						});
+						throwIfAborted(signal);
+						const latest = await loadConfigForCheck();
+						throwIfAborted(signal);
+						if (syncCheckConfigFingerprint(latest) !== identity) return;
+						const state = await withStateDirectoryAccess(() => readStateForConfig(latest));
+						throwIfAborted(signal);
+						if (syncStateFingerprint(state) !== inspection.stateIdentity || !isCurrent()) return;
+						attention.observe({
+							setupName: captured.setupName,
+							configIdentity: identity,
+							checkedAt: new Date().toISOString(),
+							inspection,
+						});
+						if (ctx.mode === "rpc") attention.notifyObservation(ctx);
+					} catch (error) {
+						if (!isCurrent() || sessionSignal.aborted || isMissingConfigError(error)) return;
+						if (signal.aborted && controller.signal.reason?.name !== "TimeoutError") return;
+						// A settings edit invalidates failures as well as successful observations.
+						if (config) {
+							const latest = await loadConfigForCheck().catch(() => undefined);
+							if (
+								!isCurrent() ||
+								(signal.aborted && controller.signal.reason?.name !== "TimeoutError")
+							)
+								return;
+							if (
+								!latest ||
+								syncCheckConfigFingerprint(latest) !== syncCheckConfigFingerprint(config)
+							)
+								return;
+						}
+						ctx.ui.notify(
+							`pi-sync startup check skipped: ${safeTerminalText(errorMessage(error))}. Run /sync status to retry. No startup transfer was performed.`,
+							"warning",
+						);
+					} finally {
+						clearTimeout(timer);
+						if (isCurrent() && checking) attention.publish(ctx);
+						if (active === task) active = undefined;
+					}
+				})
+				.catch(() => {
+					// UI teardown can itself throw. No unhandled rejection or retained timer.
+					clearTimeout(timer);
+					if (active === task) active = undefined;
+				});
+		},
+		async stop() {
+			const task = active;
+			if (!task) return;
+			task.controller.abort(new DOMException("Startup check cancelled", "AbortError"));
+			// Drain the actual work, including child/ref cleanup, before foreground guards.
+			await task.promise;
+		},
+	};
+}

package/src/{sync-decision.ts → sync/sync-decision.ts}

@@ -1,9 +1,12 @@
-import { syncConfigReviewIdentity } from "./config.js";
+import { syncConfigReviewIdentity } from "../settings/config.js";
+import type { AnySyncConfig } from "../settings/settings-types.js";
+import type { Snapshot } from "../snapshot/snapshot-types.js";
+import type { SyncState } from "../state/state-types.js";
+import { formatDiff, formatSnapshotOnlyDiff } from "../ui/sync-format.js";
+import { safeTerminalText } from "../ui/terminal-text.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";
-import type { AnySyncConfig, Snapshot, SyncState } from "./types.js";
 
 export type SyncDecisionKind =
 	| "remote-or-policy-changed"

package/src/sync/sync-error-guidance.ts

@@ -0,0 +1,53 @@
+import { errorMessage } from "./sync-errors.js";
+
+/** Add recovery advice without changing backend outcome semantics or printing error causes. */
+export function syncErrorGuidance(error: unknown): string {
+	const detail = errorMessage(error);
+	const message = detail.length > 1200 ? `${detail.slice(0, 1200)}… (details truncated)` : detail;
+	const code = (error as NodeJS.ErrnoException | undefined)?.code;
+	const status = (error as { status?: number } | undefined)?.status;
+	let next: string;
+	if (code === "ENOSPC") {
+		next = "Free disk space for the private pi-sync settings/state directory, then retry.";
+	} else if (code && ["EACCES", "EPERM", "EROFS"].includes(code)) {
+		next = "Check write access to the private pi-sync settings/state directory, then retry.";
+	} else if (code && ["EBUSY", "EIO", "EMFILE", "ENFILE"].includes(code)) {
+		next =
+			"Check local disk availability and other processes using the private settings file, then retry.";
+	} else if (/changed while|type changed|reopen/iu.test(message)) {
+		next = "Reopen the item in /sync and review its current settings before saving again.";
+	} else if (
+		status === 401 ||
+		status === 403 ||
+		/Permission denied|Authentication failed|HTTP (401|403)|failed \((401|403)\)/iu.test(message)
+	) {
+		next =
+			"Check the storage connection's credentials and remote permissions in /sync → More → Storage connections.";
+	} else if (status === 404 || /HTTP 404|failed \(404\)/iu.test(message)) {
+		next =
+			"Verify the connection address and setup's bucket, branch, or path with your provider; this response alone does not prove which resource is missing.";
+	} else if (status !== undefined && status >= 500) {
+		next = "Check your storage provider's service status, then retry Check setup before syncing.";
+	} else if (
+		/timed out|timeout|request failed|resolve host|Could not resolve|ENOTFOUND|ECONNREFUSED/iu.test(
+			message,
+		)
+	) {
+		next =
+			"Check the server address and network connection, then run /sync doctor for the affected setup.";
+	} else if (/strong ETag|If-Match|If-None-Match|precondition|conditional header/iu.test(message)) {
+		next =
+			"Ask your provider to check strong ETags and conditional writes, including proxy behavior, or choose compatible storage. Do not bypass these safety checks.";
+	} else if (/spawn git ENOENT/iu.test(message)) {
+		next = "Install Git 2.30 or newer and make sure Pi can find git on PATH, then retry.";
+	} else if (/response exceeds.*byte limit/iu.test(message)) {
+		next =
+			"Verify the storage endpoint; the server returned an unexpectedly large response. Check your provider's logs before retrying.";
+	} else if (/settings|config|already exists|duplicates|same normalized/iu.test(message)) {
+		next =
+			"Correct the named field or item in /sync. If the settings file is invalid, repair it before retrying; do not replace it with defaults.";
+	} else {
+		next = "Open /sync → More → Check setup and review the reported checks before retrying.";
+	}
+	return `${message}\n${next}`;
+}