@narumitw/pi-sync 0.49.3 → 0.49.4

package/README.md

@@ -11,8 +11,9 @@
 - Immutable snapshots, secret scanning, local locks, conflict checks, pull backups, transactional apply, and recovery journals.
 - Exact reviewed storage paths that do not change when a local sync setup is renamed.
 - One ordered `sync.include` list for Pi roots, safe agent-relative paths, and the privacy-sensitive `sessions` root.
+- Portable, credential-free snapshot selection with explicit cross-environment review and adoption.
 - Atomic private settings writes that preserve unknown fields and reject stale concurrent edits.
-- Fail-closed validation for missing references, mixed backend fields, duplicate remote locations, unsafe paths, malformed credentials, and credential-bearing Git URLs.
+- Fail-closed validation for missing references, mixed backend fields, duplicate remote locations, unsafe or oversized selection policies, malformed credentials, and credential-bearing Git URLs.
 
 ## 📦 Install
 
@@ -29,7 +30,7 @@ pi -e npm:@narumitw/pi-sync
 Try a local checkout:
 
 ```bash
-pi -e ./extensions/pi-sync
+pi -e ./packages/pi-sync
 ```
 
 ## 🚀 Quick start
@@ -63,7 +64,9 @@ and confirmations.
 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. The flow names the current sync setup and explains whether local content, remote content, or
-the included-content policy changed.
+the included-content policy changed. If the active remote snapshot explicitly selects different
+content, automatic sync and pulls pause until you adopt the remote policy in Settings or publish the
+local policy with a reviewed force push.
 
 Choose **Review differences (recommended)** to inspect the exact affected paths without changing
 local files, remote data, or sync state. Then choose one reviewed direction:
@@ -193,11 +196,28 @@ Safe agent-relative custom files or directories may also be included. Absolute p
 An empty array is valid. It means no useful transfer is selected: **Sync now** reports the condition and does not claim that the setup is up to date. Unselected content remains unmanaged locally and is preserved when republishing existing remote snapshots.
 
 The Included Content editor is a standard bounded multi-select backed by one in-memory draft. Toggles
-never write settings. Leaving the editor opens an exact Include/Exclude review with **Save changes**,
+never write settings. **Add custom path…** accepts a safe agent-relative file or directory even when
+it does not exist locally yet, allowing a new environment to select content that exists only in the
+remote snapshot. Leaving the editor opens an exact Include/Exclude review with **Save changes**,
 **Discard changes**, and **Continue editing**; only reviewed Save publishes, while Continue preserves
 the draft and Discard/cancellation preserves the settings bytes. RPC remains a read-only summary with
 the manual `sync.include` path.
 
+Every new snapshot stores the normalized included-content selection separately from the files that
+happened to exist. This preserves selected-but-missing paths without syncing `pi-sync.json`, storage
+credentials, automatic-sync preferences, or setup names. **Settings → Remote included content** reads
+the active snapshot and offers **Adopt remote included content**, **Keep local included content**,
+**Review paths**, and **Cancel** when local and remote selections differ. Adoption revalidates the
+remote head, saves local settings atomically, and does not pull files or write sync state; review
+**Sync now** separately. A reviewed force push keeps local selection and explicitly replaces the
+remote policy while preserving eligible unmanaged remote files.
+
+Automatic sync and pull, including forced pull, pause on an explicit remote-policy difference rather
+than silently expanding local scope. Status reports matches and exact local-only/remote-only paths.
+Old snapshots remain readable. Because they have no authoritative selection, pi-sync offers only a
+clearly labeled read-only partial discovery from safe remote file roots; selected-but-missing and
+preserved-unmanaged intent cannot be reconstructed. Use **Add custom path…** for any needed path.
+
 Adding `sessions` requires a privacy acknowledgement in interactive flows. Session JSONL can contain prompts, tool output, file paths, images, and secrets. Automatic apply protects the currently open session file; restart Pi or resume a pulled session to use newly synchronized conversations.
 
 ### Unsupported old settings and recovery
@@ -279,7 +299,7 @@ Pi exposes terminal components rather than a semantic/ARIA tree. Release validat
 ## 🗂️ Package layout
 
 ```text
-extensions/pi-sync/
+packages/pi-sync/
 ├── src/
 │   ├── index.ts
 │   ├── sync.ts
@@ -290,6 +310,8 @@ extensions/pi-sync/
 │   ├── storage-connections-ui.ts
 │   ├── sync-setups-ui.ts
 │   ├── file-selection.ts
+│   ├── remote-selection-ui.ts
+│   ├── remote-snapshot.ts
 │   ├── sync-operations.ts
 │   ├── sync-backend.ts
 │   ├── backend-factory.ts      # lazy selected-backend loader

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-sync",
-	"version": "0.49.3",
+	"version": "0.49.4",
 	"description": "Pi extension that syncs Pi configuration through Git, WebDAV, Cloudflare R2, or S3-compatible storage.",
 	"type": "module",
 	"license": "MIT",
@@ -30,6 +30,9 @@
 			"./src/index.ts"
 		]
 	},
+	"piExtension": {
+		"lifecycle": "stable"
+	},
 	"scripts": {
 		"check": "biome check . && npm run typecheck",
 		"format": "biome check --write .",
@@ -42,8 +45,8 @@
 	},
 	"devDependencies": {
 		"@biomejs/biome": "2.5.7",
-		"@earendil-works/pi-coding-agent": "0.83.0",
-		"@earendil-works/pi-tui": "0.83.0",
+		"@earendil-works/pi-coding-agent": "0.84.1",
+		"@earendil-works/pi-tui": "0.84.1",
 		"@types/proper-lockfile": "^4.1.4",
 		"typescript": "7.0.2"
 	},
@@ -54,6 +57,6 @@
 	"repository": {
 		"type": "git",
 		"url": "https://github.com/narumiruna/pi-extensions",
-		"directory": "extensions/pi-sync"
+		"directory": "packages/pi-sync"
 	}
 }

package/src/file-selection.ts

@@ -6,12 +6,14 @@ import { updateSyncSetup } from "./settings-management.js";
 import {
 	BUILT_IN_SYNC_ROOTS,
 	isSafeCustomIncludePath,
+	normalizeSyncInclude,
 	syncIncludeSelection,
 } from "./sync-policy.js";
 
 const BUILT_IN_PREFIX = "builtin:";
 const CUSTOM_PREFIX = "custom:";
 const SESSIONS_ID = "sessions";
+const ADD_CUSTOM_ID = "add-custom";
 
 interface SelectionDraft {
 	builtIns: Set<string>;
@@ -107,7 +109,7 @@ async function showDraftEditor(
 	customCandidates: string[],
 	signal?: AbortSignal,
 ) {
-	const menu = defineMenu<undefined, "editor", "toggle", ExtensionCommandContext>({
+	const menu = defineMenu<undefined, "editor", "toggle" | "addCustom", ExtensionCommandContext>({
 		start: "editor",
 		screens: {
 			editor: () => ({
@@ -139,6 +141,15 @@ async function showDraftEditor(
 					},
 				],
 				action: "toggle",
+				actions: [
+					{
+						id: ADD_CUSTOM_ID,
+						label: "Add custom path…",
+						description:
+							"Include an agent-relative file or directory even when it exists only remotely.",
+						action: "addCustom",
+					},
+				],
 				hint: "close",
 				doneLabel: "Review changes",
 			}),
@@ -148,6 +159,45 @@ async function showDraftEditor(
 				updateDraft(draft, itemId, selected === true);
 				return { kind: "stay" };
 			},
+			addCustom: async ({ ctx: actionCtx, signal: actionSignal }) => {
+				const entered = await actionCtx.ui.input(
+					"Add included content",
+					"Agent-relative path, for example custom.toml or snippets",
+					{ signal: actionSignal },
+				);
+				if (actionSignal.aborted) return { kind: "stay" };
+				const requested = entered?.trim();
+				if (!requested) return { kind: "stay" };
+				const existing = customCandidates.find(
+					(candidate) => candidate.toLowerCase() === requested.toLowerCase(),
+				);
+				const relativePath = existing ?? requested;
+				if (draft.custom.has(relativePath)) return { kind: "stay" };
+				try {
+					if (!isSafeCustomIncludePath(relativePath)) {
+						throw new Error("Enter a safe agent-relative file or directory path.");
+					}
+					normalizeSyncInclude([
+						...draft.builtIns,
+						...draft.custom,
+						...(draft.sessions ? ["sessions"] : []),
+						relativePath,
+					]);
+				} catch (error) {
+					if (actionSignal.aborted) return { kind: "stay" };
+					actionCtx.ui.notify(
+						`Could not add included content: ${safeTerminalText(error instanceof Error ? error.message : String(error))}`,
+						"error",
+					);
+					return { kind: "stay" };
+				}
+				if (!existing) {
+					customCandidates.push(relativePath);
+					customCandidates.sort((left, right) => left.localeCompare(right));
+				}
+				draft.custom.add(relativePath);
+				return { kind: "stay" };
+			},
 		},
 	});
 	await runMenu(ctx, menu, {

package/src/git-backend.ts

@@ -140,6 +140,7 @@ export class GitSyncBackend implements SyncBackend {
 			...(manifest.snapshotSyncSessions === undefined
 				? {}
 				: { syncSessions: manifest.snapshotSyncSessions }),
+			...(manifest.selection === undefined ? {} : { selection: manifest.selection }),
 			files,
 		};
 		validateGitSnapshot(snapshot, manifest, this.config.destination.namespace);
@@ -174,6 +175,7 @@ export class GitSyncBackend implements SyncBackend {
 			...(snapshot.syncSessions === undefined
 				? {}
 				: { snapshotSyncSessions: snapshot.syncSessions }),
+			...(snapshot.selection === undefined ? {} : { selection: snapshot.selection }),
 			files: files.map(({ path: filePath, sha256: fileSha, size }) => ({
 				path: filePath,
 				sha256: fileSha,
@@ -688,6 +690,7 @@ function remoteHead(sha: string, manifest: GitManifest, identity: string): Remot
 		createdAt: manifest.createdAt,
 		machine: manifest.machine,
 		syncSessions: manifest.syncSessions,
+		...(manifest.selection === undefined ? {} : { selection: manifest.selection }),
 	};
 }
 

package/src/git-storage.ts

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
-import type { Snapshot } from "./types.js";
+import { portableSnapshotSelection, snapshotSelectionInclude } from "./sync-policy.js";
+import type { Snapshot, SnapshotSelection } from "./types.js";
 
 export const GIT_MANIFEST_VERSION = 2;
 export const MAX_GIT_MANIFEST_BYTES = 1024 * 1024;
@@ -23,6 +24,7 @@ export interface GitManifest {
 	profile: string;
 	syncSessions: boolean;
 	snapshotSyncSessions?: boolean;
+	selection?: SnapshotSelection;
 	files: GitManifestFile[];
 }
 
@@ -81,11 +83,13 @@ export function requireGitManifest(value: unknown): GitManifest {
 			"profile",
 			"syncSessions",
 			...(manifest.snapshotSyncSessions === undefined ? [] : ["snapshotSyncSessions"]),
+			...(manifest.selection === undefined ? [] : ["selection"]),
 			"files",
 		])
 	) {
 		throw new Error("Git publication manifest is malformed.");
 	}
+	if (manifest.selection !== undefined) portableSnapshotSelection(manifest.selection);
 	let total = 0;
 	const paths = new Set<string>();
 	for (const rawFile of manifest.files) {
@@ -126,6 +130,12 @@ export function validateGitSnapshot(snapshot: Snapshot, manifest: GitManifest, n
 		snapshot.profile !== manifest.profile ||
 		snapshot.syncSessions !== manifest.snapshotSyncSessions ||
 		syncSessions !== manifest.syncSessions ||
+		!sameOptionalInclude(
+			snapshotSelectionInclude(snapshot),
+			manifest.selection === undefined
+				? undefined
+				: portableSnapshotSelection(manifest.selection).include,
+		) ||
 		prepared.length !== manifest.files.length ||
 		prepared.some((file, index) => {
 			const expected = manifest.files[index];
@@ -142,6 +152,7 @@ export function validateGitSnapshot(snapshot: Snapshot, manifest: GitManifest, n
 }
 
 export function prepareGitSnapshot(snapshot: Snapshot, namespace: string) {
+	snapshotSelectionInclude(snapshot);
 	if (
 		snapshot.version !== SNAPSHOT_VERSION ||
 		typeof snapshot.id !== "string" ||
@@ -242,6 +253,11 @@ export function validateGitPublicationTree(
 	return manifest.files.map((file) => byPath.get(filePath(file.path)) as GitTreeEntry);
 }
 
+function sameOptionalInclude(left: string[] | undefined, right: string[] | undefined) {
+	if (!left || !right) return left === right;
+	return left.length === right.length && left.every((item, index) => item === right[index]);
+}
+
 function isSafeSnapshotPath(value: unknown): value is string {
 	return (
 		typeof value === "string" &&

package/src/remote-selection-ui.ts

@@ -0,0 +1,279 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { defineMenu, runMenu } from "@narumitw/pi-tui-kit";
+import { createSyncBackend, type SyncBackendFactory } from "./backend-factory.js";
+import { loadConfig, loadPartialConfig } from "./config.js";
+import { readSnapshotForHead } from "./remote-snapshot.js";
+import { updateSyncSetup } from "./settings-management.js";
+import type { RemoteHead, SyncBackend } from "./sync-backend.js";
+import { errorMessage, safeTerminalText } from "./sync-format.js";
+import {
+	inspectRemoteSelection,
+	type RemoteSelectionState,
+	sameSyncInclude,
+} from "./sync-policy.js";
+import type { AnySyncConfig } from "./types.js";
+
+const STATUS_KEY = "sync";
+
+export async function showRemoteSelectionReview(
+	ctx: ExtensionCommandContext,
+	setupName?: string,
+	signal?: AbortSignal,
+	factory: SyncBackendFactory = createSyncBackend,
+) {
+	try {
+		const config = await loadConfig(setupName);
+		if (signal?.aborted) return;
+		const storageReview = await loadPartialConfig(config.setupName);
+		if (signal?.aborted) return;
+		ctx.ui.setStatus(STATUS_KEY, `checking remote selection for ${config.setupName}`);
+		const backend = await factory(config);
+		if (signal?.aborted) return;
+		const head = await backend.readHead(signal);
+		if (signal?.aborted) return;
+		if (!head) {
+			ctx.ui.setStatus(STATUS_KEY, undefined);
+			ctx.ui.notify("Remote storage has no snapshot or included-content policy yet.", "info");
+			return;
+		}
+		const snapshot = await readSnapshotForHead(backend, head, signal);
+		if (signal?.aborted) return;
+		const state = inspectRemoteSelection(config.include, snapshot);
+		ctx.ui.setStatus(STATUS_KEY, undefined);
+
+		if (ctx.mode !== "tui") {
+			ctx.ui.notify(
+				formatRemoteSelectionSummary(config, state),
+				state.kind === "different" ? "warning" : "info",
+			);
+			return;
+		}
+		if (state.kind === "same") {
+			ctx.ui.notify("Remote included content already matches this sync setup.", "info");
+			return;
+		}
+		if (state.kind === "legacy") {
+			await showLegacyDiscovery(ctx, config, state.discovered, signal);
+			return;
+		}
+		await showSelectionDifference(ctx, config, storageReview, backend, head, state, signal);
+	} catch (error) {
+		if (signal?.aborted) return;
+		ctx.ui.notify(`Could not review remote included content: ${errorMessage(error)}`, "error");
+	} finally {
+		ctx.ui.setStatus(STATUS_KEY, undefined);
+	}
+}
+
+async function showSelectionDifference(
+	ctx: ExtensionCommandContext,
+	config: AnySyncConfig,
+	storageReview: Awaited<ReturnType<typeof loadPartialConfig>>,
+	backend: SyncBackend,
+	reviewedHead: RemoteHead,
+	state: Extract<RemoteSelectionState, { kind: "different" }>,
+	sessionSignal?: AbortSignal,
+) {
+	type Screen = "choice" | "review";
+	type Action = "adopt" | "keep" | "cancel";
+	const menu = defineMenu<undefined, Screen, Action, ExtensionCommandContext>({
+		start: "choice",
+		screens: {
+			choice: () => ({
+				kind: "actions",
+				title: `Remote included content · ${safeTerminalText(config.setupName)}`,
+				lines: [
+					"The remote selection differs from this local sync setup.",
+					"No settings or files have been changed.",
+				],
+				items: [
+					{
+						id: "adopt",
+						label: "Adopt remote included content",
+						description: "Save the reviewed remote paths locally without pulling files.",
+						action: "adopt",
+					},
+					{
+						id: "keep",
+						label: "Keep local included content",
+						description: "Make no settings change; a reviewed force push can publish it later.",
+						action: "keep",
+					},
+					{
+						id: "review",
+						label: "Review paths",
+						description: "Compare exact local-only and remote-only selection paths.",
+						to: "review",
+					},
+					{ id: "cancel", label: "Cancel", action: "cancel" },
+				],
+				hint: "close",
+			}),
+			review: () => ({
+				kind: "review",
+				title: `Review remote included content · ${safeTerminalText(config.setupName)}`,
+				content: formatSelectionDifference(config.include, state),
+				format: { kind: "text" },
+				viewportSize: "adaptive",
+				hint: "back",
+			}),
+		},
+		actions: {
+			adopt: async ({ signal: actionSignal }) => {
+				const signal = sessionSignal
+					? AbortSignal.any([sessionSignal, actionSignal])
+					: actionSignal;
+				try {
+					if (!config.include.includes("sessions") && state.include.includes("sessions")) {
+						const acknowledged = await ctx.ui.confirm(
+							"Adopt session conversations?",
+							"Session JSONL may contain prompts, tool output, file paths, images, and secrets. This saves the selection only; it does not pull files.",
+							{ signal },
+						);
+						if (signal.aborted) return { kind: "close" as const };
+						if (!acknowledged) return { kind: "stay" as const };
+					}
+					if (signal.aborted) return { kind: "close" as const };
+					const currentHead = await backend.readHead(signal);
+					if (signal.aborted) return { kind: "close" as const };
+					if (!currentHead || !backend.sameRevision(reviewedHead.revision, currentHead.revision)) {
+						throw new Error(
+							"Remote changed while the included-content review was open; reopen it.",
+						);
+					}
+					const currentSnapshot = await readSnapshotForHead(backend, currentHead, signal);
+					if (signal.aborted) return { kind: "close" as const };
+					const currentState = inspectRemoteSelection(config.include, currentSnapshot);
+					if (
+						currentState.kind === "legacy" ||
+						!sameSyncInclude(currentState.include, state.include)
+					) {
+						throw new Error(
+							"Remote included content changed while the review was open; reopen it.",
+						);
+					}
+					await updateSyncSetup(
+						config.setupName,
+						(setup) => ({
+							...setup,
+							sync: { ...setup.sync, include: [...state.include] },
+						}),
+						{
+							expectedStorage: storageReview,
+							expectedInclude: config.include,
+							signal,
+						},
+					);
+					if (signal.aborted) return { kind: "close" as const };
+					ctx.ui.notify(
+						`Saved remote included content for sync setup “${safeTerminalText(config.setupName)}”. No files were pulled; review Sync now separately.`,
+						"info",
+					);
+					return { kind: "close" as const };
+				} catch (error) {
+					if (signal.aborted) return { kind: "close" as const };
+					ctx.ui.notify(`Could not adopt remote included content: ${errorMessage(error)}`, "error");
+					return { kind: "close" as const };
+				}
+			},
+			keep: async () => {
+				ctx.ui.notify(
+					"Kept local included content. No settings or files changed; use a reviewed force push to publish the local selection.",
+					"info",
+				);
+				return { kind: "close" };
+			},
+			cancel: async () => ({ kind: "close" }),
+		},
+	});
+	await runMenu(ctx, menu, {
+		getState: () => undefined,
+		signal: sessionSignal,
+		isCurrent: () => !sessionSignal?.aborted,
+	});
+}
+
+async function showLegacyDiscovery(
+	ctx: ExtensionCommandContext,
+	config: AnySyncConfig,
+	discovered: string[],
+	signal?: AbortSignal,
+) {
+	const menu = defineMenu<undefined, "choice" | "review", "back", ExtensionCommandContext>({
+		start: "choice",
+		screens: {
+			choice: () => ({
+				kind: "actions",
+				title: `Remote included content · ${safeTerminalText(config.setupName)}`,
+				lines: [
+					"This legacy snapshot has no portable included-content policy.",
+					"Discovered paths are partial and read-only; preserved files may not have been selected.",
+				],
+				items: [
+					{ id: "review", label: "Review discovered paths", to: "review" },
+					{ id: "back", label: "Back", action: "back" },
+				],
+				hint: "close",
+			}),
+			review: () => ({
+				kind: "review",
+				title: "Partial discovery from legacy snapshot",
+				content: [
+					"Partial discovery only — not an authoritative selection.",
+					"",
+					...(discovered.length > 0
+						? discovered.map((item) => `Discovered: ${safeTerminalText(item)}`)
+						: ["No safe paths were discovered."]),
+					"",
+					"Use Add custom path… in the local Included Content editor if needed.",
+				].join("\n"),
+				format: { kind: "text" },
+				viewportSize: "adaptive",
+				hint: "back",
+			}),
+		},
+		actions: { back: async () => ({ kind: "close" }) },
+	});
+	await runMenu(ctx, menu, {
+		getState: () => undefined,
+		signal,
+		isCurrent: () => !signal?.aborted,
+	});
+}
+
+function formatSelectionDifference(
+	localInclude: readonly string[],
+	state: Extract<RemoteSelectionState, { kind: "different" }>,
+) {
+	return [
+		"Remote-only selection:",
+		...(state.remoteOnly.length > 0
+			? state.remoteOnly.map((item) => `+ ${safeTerminalText(item)}`)
+			: ["(none)"]),
+		"",
+		"Local-only selection:",
+		...(state.localOnly.length > 0
+			? state.localOnly.map((item) => `- ${safeTerminalText(item)}`)
+			: ["(none)"]),
+		"",
+		`Remote order: ${state.include.map(safeTerminalText).join(", ") || "none"}`,
+		`Local order: ${localInclude.map(safeTerminalText).join(", ") || "none"}`,
+		"",
+		"Adopting saves settings only and does not pull files.",
+	].join("\n");
+}
+
+function formatRemoteSelectionSummary(config: AnySyncConfig, state: RemoteSelectionState) {
+	if (state.kind === "same") {
+		return `Remote included content for “${safeTerminalText(config.setupName)}” matches local settings.`;
+	}
+	if (state.kind === "legacy") {
+		return `Remote snapshot for “${safeTerminalText(config.setupName)}” has no portable included-content policy; ${state.discovered.length} safe path${state.discovered.length === 1 ? " was" : "s were"} discovered, but the result is partial and read-only.`;
+	}
+	return [
+		`Remote included content for “${safeTerminalText(config.setupName)}” differs from local settings.`,
+		`Remote-only: ${state.remoteOnly.map(safeTerminalText).join(", ") || "none"}`,
+		`Local-only: ${state.localOnly.map(safeTerminalText).join(", ") || "none"}`,
+		"Use TUI Settings to review or adopt it; RPC is read-only.",
+	].join("\n");
+}

package/src/remote-snapshot.ts

@@ -0,0 +1,59 @@
+import type { RemoteHead, SyncBackend } from "./sync-backend.js";
+import { safeTerminalText } from "./sync-format.js";
+import {
+	inspectRemoteSelection,
+	RemoteSelectionMismatchError,
+	type RemoteSelectionState,
+	sameSyncInclude,
+	snapshotSelectionInclude,
+} from "./sync-policy.js";
+import type { AnySyncConfig, Snapshot } from "./types.js";
+
+export async function readSnapshotForHead(
+	backend: SyncBackend,
+	head: RemoteHead,
+	signal?: AbortSignal,
+) {
+	const snapshot = await backend.readSnapshot(head.snapshotRef, signal);
+	if (signal?.aborted) {
+		throw signal.reason instanceof Error
+			? signal.reason
+			: new DOMException("The operation was aborted", "AbortError");
+	}
+	if (snapshot.id !== head.snapshotId) {
+		throw new Error(
+			`Remote head ${head.snapshotId} resolved to unexpected snapshot ${snapshot.id}.`,
+		);
+	}
+	if (head.selection) {
+		const snapshotInclude = snapshotSelectionInclude(snapshot);
+		if (!snapshotInclude || !sameSyncInclude(head.selection.include, snapshotInclude)) {
+			throw new Error("Remote head selection does not match its immutable snapshot.");
+		}
+	}
+	return snapshot;
+}
+
+export function requireCompatibleRemoteSelection(config: AnySyncConfig, snapshot: Snapshot) {
+	const state = inspectRemoteSelection(config.include, snapshot);
+	if (state.kind === "different") {
+		throw new RemoteSelectionMismatchError(config.include, state.include);
+	}
+}
+
+export function formatRemoteSelectionStatus(state: RemoteSelectionState | undefined) {
+	if (!state) return "remote included content: unavailable (remote is empty)";
+	if (state.kind === "same") return "remote included content: matches this setup";
+	if (state.kind === "legacy") {
+		return `remote included content: unavailable in legacy snapshot (${state.discovered.length} path${state.discovered.length === 1 ? "" : "s"} discovered, partial)`;
+	}
+	return [
+		"remote included content: differs from this setup",
+		`remote-only selection: ${safeList(state.remoteOnly)}`,
+		`local-only selection: ${safeList(state.localOnly)}`,
+	].join("\n");
+}
+
+function safeList(values: readonly string[]) {
+	return values.length > 0 ? values.map(safeTerminalText).join(", ") : "none";
+}

package/src/s3-backend.ts

@@ -14,6 +14,7 @@ import {
 	SyncBackendConflictError,
 	SyncBackendPublicationOutcomeUnknownError,
 } from "./sync-backend.js";
+import { portableSnapshotSelection } from "./sync-policy.js";
 import type { LatestPointer, RemoteObject, ResolvedS3Backend, Snapshot } from "./types.js";
 
 const VERSION = 1;
@@ -274,6 +275,7 @@ export function pointerFor(
 		syncSessions:
 			snapshot.syncSessions === true ||
 			snapshot.files.some((file) => file.path.startsWith("sessions/")),
+		...(snapshot.selection === undefined ? {} : { selection: snapshot.selection }),
 	};
 }
 
@@ -330,6 +332,7 @@ function remoteHead(pointer: LatestPointer, identity: string, etag?: string): Re
 		createdAt: pointer.createdAt,
 		machine: pointer.machine,
 		syncSessions: pointer.syncSessions === true,
+		...(pointer.selection === undefined ? {} : { selection: pointer.selection }),
 	};
 }
 
@@ -377,6 +380,7 @@ function requirePointer(
 	) {
 		throw new Error(message);
 	}
+	if (value.selection !== undefined) portableSnapshotSelection(value.selection);
 	return value;
 }
 

package/src/settings-ui.ts

@@ -25,7 +25,7 @@ export async function showSyncSettings(
 	const initial = await loadConfig();
 	if (signal?.aborted) return;
 	const setupName = initial.setupName;
-	type Action = "automatic" | "on-switch" | "include";
+	type Action = "automatic" | "on-switch" | "include" | "remote-include";
 	const menu = defineMenu<
 		Awaited<ReturnType<typeof loadConfig>>,
 		"settings",
@@ -65,6 +65,14 @@ export async function showSyncSettings(
 						currentValue: "Open editor",
 						action: "include",
 					},
+					{
+						id: "remoteInclude",
+						label: "Remote included content",
+						description:
+							"Compare portable remote selection, then adopt it or keep local settings without pulling files.",
+						currentValue: "Review",
+						action: "remote-include",
+					},
 				],
 			}),
 		},
@@ -114,6 +122,13 @@ export async function showSyncSettings(
 				await runRoute("files", editorSignal, undefined, setupName);
 				return editorSignal.aborted ? { kind: "rejected" } : { kind: "stay" };
 			},
+			"remote-include": async ({ signal: actionSignal }) => {
+				const reviewSignal = signal ? AbortSignal.any([signal, actionSignal]) : actionSignal;
+				const { showRemoteSelectionReview } = await import("./remote-selection-ui.js");
+				if (reviewSignal.aborted) return { kind: "rejected" };
+				await showRemoteSelectionReview(ctx, setupName, reviewSignal);
+				return reviewSignal.aborted ? { kind: "rejected" } : { kind: "stay" };
+			},
 		},
 	});
 	await runMenu(ctx, menu, {

package/src/snapshot-codec.ts

@@ -2,6 +2,7 @@ import { Readable, Writable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { promisify } from "node:util";
 import { createGunzip, gzip } from "node:zlib";
+import { snapshotSelectionInclude } from "./sync-policy.js";
 import type { Snapshot } from "./types.js";
 
 const VERSION = 1;
@@ -9,6 +10,7 @@ const MAX_DECOMPRESSED_SNAPSHOT_BYTES = 512 * 1024 * 1024;
 const gzipAsync = promisify(gzip);
 
 export async function encodeSnapshot(snapshot: Snapshot) {
+	snapshotSelectionInclude(snapshot);
 	return gzipAsync(Buffer.from(JSON.stringify(snapshot), "utf8"));
 }
 
@@ -37,6 +39,7 @@ export async function decodeSnapshot(
 	if (parsed.version !== VERSION || !Array.isArray(parsed.files)) {
 		throw new Error("Unsupported snapshot format.");
 	}
+	snapshotSelectionInclude(parsed);
 	return parsed;
 }
 

package/src/snapshot.ts

@@ -18,6 +18,8 @@ import {
 	normalizeExtraFiles,
 	normalizeSyncFiles,
 	type SyncSelectionConfig,
+	selectionForSnapshot,
+	snapshotSelectionInclude,
 	syncIncludeSelection,
 } from "./sync-policy.js";
 import type { Snapshot, SnapshotFile, SnapshotOptions } from "./types.js";
@@ -74,6 +76,8 @@ function snapshotsMatch(left: Snapshot, right: Snapshot) {
 	const leftHashes = new Map(left.files.map((file) => [file.path, file.sha256]));
 	const rightHashes = new Map(right.files.map((file) => [file.path, file.sha256]));
 	return (
+		left.syncSessions === right.syncSessions &&
+		sameOptionalInclude(snapshotSelectionInclude(left), snapshotSelectionInclude(right)) &&
 		leftHashes.size === rightHashes.size &&
 		[...leftHashes].every(([filePath, hash]) => rightHashes.get(filePath) === hash)
 	);
@@ -109,6 +113,7 @@ export async function createSnapshot(
 		machine: os.hostname(),
 		profile,
 		syncSessions,
+		selection: selectionForSnapshot(include),
 		files,
 	};
 }
@@ -249,7 +254,11 @@ export function snapshotTarget(root: string, relativePath: string, configuredSes
 }
 
 export function snapshotIncludesSessions(snapshot: Snapshot) {
-	return snapshot.syncSessions === true || snapshot.files.some((file) => isSessionPath(file.path));
+	return (
+		snapshot.syncSessions === true ||
+		snapshotSelectionInclude(snapshot)?.includes("sessions") === true ||
+		snapshot.files.some((file) => isSessionPath(file.path))
+	);
 }
 
 export function filterSnapshotForConfigPolicy(
@@ -262,6 +271,7 @@ export function filterSnapshotForConfigPolicy(
 	const filtered = {
 		...snapshot,
 		syncSessions: include.includes("sessions") ? snapshot.syncSessions : false,
+		selection: selectionForSnapshot(include),
 		files: canonicalizeSnapshotFilesForConfig(snapshot.files, config, includePaths),
 	};
 	if (!options.regenerateId || snapshotsMatch(snapshot, filtered)) return filtered;
@@ -319,13 +329,21 @@ function isPreferredExtraCandidate(
 
 export function snapshotWithoutSessions(snapshot: Snapshot) {
 	const files = snapshot.files.filter((file) => !isSessionPath(file.path));
-	if (files.length === snapshot.files.length && snapshot.syncSessions !== true) return snapshot;
+	const include = snapshotSelectionInclude(snapshot)?.filter((item) => item !== "sessions");
+	if (
+		files.length === snapshot.files.length &&
+		snapshot.syncSessions !== true &&
+		include?.length === snapshot.selection?.include.length
+	) {
+		return snapshot;
+	}
 	return {
 		...snapshot,
 		id: snapshotId(),
 		createdAt: new Date().toISOString(),
 		machine: os.hostname(),
 		syncSessions: false,
+		...(include ? { selection: selectionForSnapshot(include) } : {}),
 		files,
 	};
 }
@@ -387,14 +405,27 @@ export function mergeRemoteSessionFiles(local: Snapshot, remote: Snapshot) {
 		return isSessionFilePath(normalized) && isSafeSnapshotPath(file.path);
 	});
 	if (remoteSessions.length === 0 && !snapshotIncludesSessions(remote)) return local;
+	const localInclude = snapshotSelectionInclude(local);
 	return {
 		...local,
 		id: snapshotId(),
 		createdAt: new Date().toISOString(),
 		machine: os.hostname(),
 		syncSessions: true,
+		...(localInclude
+			? {
+					selection: selectionForSnapshot(
+						localInclude.includes("sessions") ? localInclude : [...localInclude, "sessions"],
+					),
+				}
+			: {}),
 		files: [...local.files.filter((file) => !isSessionPath(file.path)), ...remoteSessions].sort(
 			(left, right) => left.path.localeCompare(right.path),
 		),
 	};
 }
+
+function sameOptionalInclude(left: string[] | undefined, right: string[] | undefined) {
+	if (!left || !right) return left === right;
+	return left.length === right.length && left.every((item, index) => item === right[index]);
+}

package/src/sync-backend.ts

@@ -1,4 +1,4 @@
-import type { Snapshot } from "./types.js";
+import type { Snapshot, SnapshotSelection } from "./types.js";
 
 export type PublicationCapability =
 	| "read-check-write-verify"
@@ -15,6 +15,8 @@ export interface RemoteHead {
 	createdAt: string;
 	machine: string;
 	syncSessions: boolean;
+	/** Validated lightweight projection; revalidate it against the immutable snapshot before adoption. */
+	selection?: SnapshotSelection;
 }
 
 export interface RemoteHistoryEntry {

package/src/sync-format.ts

@@ -1,5 +1,6 @@
 import { agentDir } from "./config.js";
 import type { PublicationCapability, RemoteHead } from "./sync-backend.js";
+import { inspectRemoteSelection } from "./sync-policy.js";
 import { fileHashMap } from "./sync-state.js";
 import type { CommonSyncConfig, Snapshot } from "./types.js";
 
@@ -50,6 +51,11 @@ export function formatPushSummary(
 		`Sessions: ${upload.syncSessions ? "included — may contain private conversations" : "not included"}`,
 		head ? `Remote latest: ${head.snapshotId}` : "Remote latest: empty",
 		"Publication effect: the backend's active head will reference the new immutable snapshot.",
+		...(remote && inspectRemoteSelection(config.include, remote).kind === "different"
+			? [
+					"Included-content policy effect: replace the differing remote selection with this setup's local selection.",
+				]
+			: []),
 		formatPublicationPreview(remote, upload),
 		preservedRemoteFileCount > 0
 			? `Possible secrets in locally managed files were scanned before this prompt; ${preservedRemoteFileCount} preserved remote file(s) were not rescanned.`

package/src/sync-operations.ts

@@ -11,6 +11,11 @@ import {
 	writeStateForConfig,
 } from "./config.js";
 import { inspectLock, isLockGuardHeld, isStaleLock, withLock } from "./lock.js";
+import {
+	formatRemoteSelectionStatus,
+	readSnapshotForHead,
+	requireCompatibleRemoteSelection,
+} from "./remote-snapshot.js";
 import {
 	createSnapshot,
 	filterSnapshotForConfigPolicy,
@@ -41,6 +46,7 @@ import {
 	publicationCapabilityDescription,
 	safeTerminalText,
 } from "./sync-format.js";
+import { inspectRemoteSelection, RemoteSelectionMismatchError } from "./sync-policy.js";
 import {
 	canPullRemoteSessionsOnFirstSync,
 	canPullRemoteSettingsOnFirstSync,
@@ -124,6 +130,9 @@ export async function status(
 	throwIfAborted(options.signal);
 	const head = await backend.readHead(options.signal);
 	throwIfAborted(options.signal);
+	const selectionState = head
+		? inspectRemoteSelection(config.include, { selection: head.selection, files: [] })
+		: undefined;
 	const localChanged = hasLocalChanges(local, state, config);
 
 	const remoteText = head
@@ -143,12 +152,15 @@ export async function status(
 			`included content: ${config.include.join(", ") || "none"}`,
 			`sessions: ${config.include.includes("sessions") ? "included" : "excluded"}`,
 			remoteText,
+			formatRemoteSelectionStatus(selectionState),
 			`local files: ${local.files.length}`,
 			`local changed since last sync: ${localChanged ? "yes" : "no"}`,
 			`remote changed since last sync: ${remoteChanged ? "yes" : "no"}`,
 			...warnings,
 		].join("\n"),
-		localChanged || remoteChanged || warnings.length > 0 ? "warning" : "info",
+		localChanged || remoteChanged || selectionState?.kind === "different" || warnings.length > 0
+			? "warning"
+			: "info",
 	);
 }
 
@@ -166,7 +178,12 @@ export async function diff(
 		snapshotOptionsForContext(ctx, config),
 	);
 	throwIfAborted(options.signal);
-	const { snapshot: remote } = await readRemoteSnapshot(backend, config, options.signal);
+	const { snapshot: remote, selectionState } = await readRemoteSnapshot(
+		backend,
+		config,
+		options.signal,
+		{ allowSelectionDifference: true },
+	);
 	throwIfAborted(options.signal);
 	ctx.ui.setStatus(STATUS_KEY, undefined);
 
@@ -177,9 +194,10 @@ export async function diff(
 		`storage location: ${safeTerminalText(backend.destination)}`,
 		`included content: ${config.include.join(", ") || "none"}`,
 		`sessions: ${config.include.includes("sessions") ? "included" : "excluded"}`,
+		formatRemoteSelectionStatus(selectionState),
 		...warnings,
 	].join("\n");
-	const level = warnings.length > 0 ? "warning" : "info";
+	const level = warnings.length > 0 || selectionState?.kind === "different" ? "warning" : "info";
 	if (!remote) {
 		ctx.ui.notify(
 			`${header}\n\n${formatSnapshotOnlyDiff("Remote is empty. Local push would upload", local)}`,
@@ -299,6 +317,18 @@ export async function push(
 		state,
 		options.signal,
 	);
+	if (
+		!options.force &&
+		!remoteForUpload &&
+		head?.selection &&
+		inspectRemoteSelection(config.include, { selection: head.selection, files: [] }).kind ===
+			"different"
+	) {
+		remoteForUpload = await readSnapshotForHead(backend, head, options.signal);
+	}
+	if (remoteForUpload && !options.force) {
+		requireCompatibleRemoteSelection(config, remoteForUpload);
+	}
 	if (
 		remoteChangedSinceState(head, state, config, (left, right) =>
 			backend.sameRevision(left, right),
@@ -886,16 +916,20 @@ 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 };
-	const snapshot = await backend.readSnapshot(head.snapshotRef, signal);
-	if (snapshot.id !== head.snapshotId) {
-		throw new Error(
-			`Remote head ${head.snapshotId} resolved to unexpected snapshot ${snapshot.id}.`,
-		);
+	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") {
+		throw new RemoteSelectionMismatchError(config.include, selectionState.include);
 	}
-	return { head, snapshot: filterSnapshotForConfigPolicy(snapshot, config) };
+	return {
+		head,
+		snapshot: filterSnapshotForConfigPolicy(snapshot, config),
+		selectionState,
+	};
 }
 
 async function confirmPush(

package/src/sync-policy.ts

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { isDeniedPath, toPosix } from "./paths.js";
+import type { Snapshot, SnapshotSelection } from "./types.js";
 
 export const BUILT_IN_SYNC_ROOTS = [
 	"settings.json",
@@ -15,6 +16,15 @@ export const BUILT_IN_SYNC_ROOTS = [
 
 export const DEFAULT_SYNC_INCLUDE = [...BUILT_IN_SYNC_ROOTS] as const;
 export type BuiltInSyncFile = (typeof BUILT_IN_SYNC_ROOTS)[number];
+const SNAPSHOT_SELECTION_VERSION = 1;
+const MAX_SYNC_INCLUDE_ITEMS = 1_024;
+const MAX_SYNC_INCLUDE_PATH_BYTES = 4_096;
+const MAX_SYNC_INCLUDE_TOTAL_BYTES = 256 * 1_024;
+
+interface IncludePathNode {
+	selected?: string;
+	children: Map<string, IncludePathNode>;
+}
 
 const BUILT_IN_BY_LOWER = new Map<string, BuiltInSyncFile>(
 	BUILT_IN_SYNC_ROOTS.map((fileName) => [fileName.toLowerCase(), fileName]),
@@ -34,12 +44,31 @@ export function normalizeSyncInclude(value: unknown): string[] {
 	if (!Array.isArray(value)) {
 		throw new Error("Invalid pi-sync settings: sync.include must be an array.");
 	}
+	if (value.length > MAX_SYNC_INCLUDE_ITEMS) {
+		throw new Error(
+			`Invalid pi-sync settings: sync.include has too many items; limit: ${MAX_SYNC_INCLUDE_ITEMS}.`,
+		);
+	}
 	const result: string[] = [];
 	const seen = new Set<string>();
+	const pathRoot: IncludePathNode = { children: new Map() };
+	let totalBytes = 0;
 	for (const item of value) {
 		if (typeof item !== "string") {
 			throw new Error("Invalid pi-sync settings: sync.include items must be strings.");
 		}
+		const itemBytes = Buffer.byteLength(item, "utf8");
+		if (itemBytes > MAX_SYNC_INCLUDE_PATH_BYTES) {
+			throw new Error(
+				`Invalid pi-sync settings: sync.include item is too long; limit: ${MAX_SYNC_INCLUDE_PATH_BYTES} bytes.`,
+			);
+		}
+		totalBytes += itemBytes;
+		if (totalBytes > MAX_SYNC_INCLUDE_TOTAL_BYTES) {
+			throw new Error(
+				`Invalid pi-sync settings: sync.include is too large; limit: ${MAX_SYNC_INCLUDE_TOTAL_BYTES} bytes.`,
+			);
+		}
 		const trimmed = item.trim();
 		const builtIn = BUILT_IN_BY_LOWER.get(trimmed.toLowerCase());
 		const normalized = builtIn ?? (trimmed.toLowerCase() === "sessions" ? "sessions" : trimmed);
@@ -48,19 +77,34 @@ export function normalizeSyncInclude(value: unknown): string[] {
 		if (seen.has(identity)) {
 			throw new Error(`Invalid pi-sync settings: duplicate sync.include item: ${item}`);
 		}
-		for (const previous of seen) {
-			if (identity.startsWith(`${previous}/`) || previous.startsWith(`${identity}/`)) {
-				throw new Error(
-					`Invalid pi-sync settings: overlapping sync.include items are ambiguous: ${item}`,
-				);
-			}
-		}
+		addIncludePath(pathRoot, identity, item);
 		seen.add(identity);
 		result.push(normalized);
 	}
 	return result;
 }
 
+function addIncludePath(root: IncludePathNode, identity: string, source: string) {
+	let node = root;
+	for (const segment of identity.split("/")) {
+		if (node.selected !== undefined) throwOverlappingInclude(source);
+		let child = node.children.get(segment);
+		if (!child) {
+			child = { children: new Map() };
+			node.children.set(segment, child);
+		}
+		node = child;
+	}
+	if (node.children.size > 0) throwOverlappingInclude(source);
+	node.selected = identity;
+}
+
+function throwOverlappingInclude(item: string): never {
+	throw new Error(
+		`Invalid pi-sync settings: overlapping sync.include items are ambiguous: ${item}`,
+	);
+}
+
 function validateAgentRelativeInclude(value: string) {
 	const normalized = toPosix(value);
 	const topLevel = normalized.split("/")[0]?.toLowerCase();
@@ -89,6 +133,138 @@ function validateAgentRelativeInclude(value: string) {
 	}
 }
 
+export function portableSnapshotSelection(value: unknown): SnapshotSelection {
+	const selection = value as Partial<SnapshotSelection> | null;
+	if (
+		!selection ||
+		typeof selection !== "object" ||
+		Array.isArray(selection) ||
+		selection.version !== SNAPSHOT_SELECTION_VERSION ||
+		!Object.hasOwn(selection, "include") ||
+		Object.keys(selection).some((key) => key !== "version" && key !== "include")
+	) {
+		throw new Error("Invalid snapshot selection policy.");
+	}
+	return {
+		version: SNAPSHOT_SELECTION_VERSION,
+		include: normalizeSyncInclude(selection.include),
+	};
+}
+
+export function snapshotSelectionInclude(snapshot: Pick<Snapshot, "selection">) {
+	return snapshot.selection === undefined
+		? undefined
+		: portableSnapshotSelection(snapshot.selection).include;
+}
+
+export function selectionForSnapshot(include: unknown): SnapshotSelection {
+	return { version: SNAPSHOT_SELECTION_VERSION, include: normalizeSyncInclude(include) };
+}
+
+export function sameSyncInclude(left: unknown, right: unknown) {
+	const normalizedLeft = normalizeSyncInclude(left);
+	const normalizedRight = normalizeSyncInclude(right);
+	return (
+		normalizedLeft.length === normalizedRight.length &&
+		normalizedLeft.every((item, index) => item === normalizedRight[index])
+	);
+}
+
+export function compareSyncInclude(local: unknown, remote: unknown) {
+	const localInclude = normalizeSyncInclude(local);
+	const remoteInclude = normalizeSyncInclude(remote);
+	const localSet = new Set(localInclude);
+	const remoteSet = new Set(remoteInclude);
+	return {
+		same: sameSyncInclude(localInclude, remoteInclude),
+		remoteOnly: remoteInclude.filter((item) => !localSet.has(item)),
+		localOnly: localInclude.filter((item) => !remoteSet.has(item)),
+	};
+}
+
+export type RemoteSelectionState =
+	| { kind: "legacy"; discovered: string[] }
+	| { kind: "same"; include: string[] }
+	| {
+			kind: "different";
+			include: string[];
+			remoteOnly: string[];
+			localOnly: string[];
+	  };
+
+export function inspectRemoteSelection(
+	localInclude: unknown,
+	snapshot: Pick<Snapshot, "selection" | "files">,
+): RemoteSelectionState {
+	const remoteInclude = snapshotSelectionInclude(snapshot);
+	if (!remoteInclude) {
+		return { kind: "legacy", discovered: discoverLegacySnapshotInclude(snapshot) };
+	}
+	const comparison = compareSyncInclude(localInclude, remoteInclude);
+	return comparison.same
+		? { kind: "same", include: remoteInclude }
+		: { kind: "different", include: remoteInclude, ...comparison };
+}
+
+export class RemoteSelectionMismatchError extends Error {
+	readonly localInclude: string[];
+	readonly remoteInclude: string[];
+
+	constructor(localInclude: unknown, remoteInclude: unknown) {
+		const local = normalizeSyncInclude(localInclude);
+		const remote = normalizeSyncInclude(remoteInclude);
+		super(
+			"Remote included content differs from this sync setup. Review Remote included content in /sync Settings, or use a reviewed force push to keep local selection.",
+		);
+		this.name = "RemoteSelectionMismatchError";
+		this.localInclude = local;
+		this.remoteInclude = remote;
+	}
+}
+
+export function discoverLegacySnapshotInclude(snapshot: Pick<Snapshot, "files">) {
+	const builtIns = new Set<BuiltInSyncFile>();
+	const custom = new Set<string>();
+	let sessions = false;
+	for (const file of snapshot.files) {
+		const normalized = toPosix(file.path);
+		if (
+			!normalized ||
+			file.path.includes("\\") ||
+			normalized.length > 4096 ||
+			normalized.startsWith("../") ||
+			path.posix.isAbsolute(normalized) ||
+			path.posix.normalize(normalized) !== normalized ||
+			// biome-ignore lint/suspicious/noControlCharactersInRegex: Ignore unsafe legacy paths.
+			/[\u0000-\u001f\u007f-\u009f]/u.test(normalized) ||
+			isDeniedPath(normalized)
+		) {
+			continue;
+		}
+		const [topLevel, ...rest] = normalized.split("/");
+		if (!topLevel) continue;
+		if (topLevel === "sessions" && rest.length > 0) {
+			sessions = true;
+			continue;
+		}
+		const builtIn = BUILT_IN_BY_LOWER.get(topLevel.toLowerCase());
+		if (
+			builtIn &&
+			((TOP_LEVEL_DIRS.has(builtIn) && rest.length > 0) ||
+				(!TOP_LEVEL_DIRS.has(builtIn) && rest.length === 0))
+		) {
+			builtIns.add(builtIn);
+			continue;
+		}
+		if (isSafeCustomIncludePath(topLevel)) custom.add(topLevel);
+	}
+	return [
+		...BUILT_IN_SYNC_ROOTS.filter((item) => builtIns.has(item)),
+		...[...custom].sort((left, right) => left.localeCompare(right)),
+		...(sessions ? ["sessions"] : []),
+	];
+}
+
 export function syncIncludeSelection(value: unknown) {
 	const include = normalizeSyncInclude(value);
 	const builtIns = include.filter((item): item is BuiltInSyncFile =>

package/src/types.ts

@@ -193,6 +193,11 @@ export interface SnapshotFile {
 	sha256: string;
 }
 
+export interface SnapshotSelection {
+	version: 1;
+	include: string[];
+}
+
 export interface Snapshot {
 	version: number;
 	id: string;
@@ -201,6 +206,8 @@ export interface Snapshot {
 	/** Backend-scoped remote identity retained in the snapshot wire format. */
 	profile: string;
 	syncSessions?: boolean;
+	/** Portable, credential-free included-content intent. Absent on legacy snapshots. */
+	selection?: SnapshotSelection;
 	files: SnapshotFile[];
 }
 
@@ -212,6 +219,8 @@ export interface LatestPointer {
 	createdAt: string;
 	machine: string;
 	syncSessions?: boolean;
+	/** Lightweight projection; the immutable snapshot remains authoritative. */
+	selection?: SnapshotSelection;
 }
 
 export interface RemoteObject<T> {

package/src/webdav-backend.ts

@@ -11,6 +11,7 @@ import {
 	SyncBackendConflictError,
 	SyncBackendPublicationOutcomeUnknownError,
 } from "./sync-backend.js";
+import { portableSnapshotSelection } from "./sync-policy.js";
 import type { LatestPointer, RemoteObject, ResolvedWebDavBackend, Snapshot } from "./types.js";
 import { WebDavClient, WebDavHttpError, WebDavPreconditionError } from "./webdav-client.js";
 
@@ -427,6 +428,7 @@ function pointerFor(
 		syncSessions:
 			snapshot.syncSessions === true ||
 			snapshot.files.some((file) => file.path.startsWith("sessions/")),
+		...(snapshot.selection === undefined ? {} : { selection: snapshot.selection }),
 	};
 }
 
@@ -438,6 +440,7 @@ function remoteHead(pointer: LatestPointer, identity: string, etag?: string): Re
 		createdAt: pointer.createdAt,
 		machine: pointer.machine,
 		syncSessions: pointer.syncSessions === true,
+		...(pointer.selection === undefined ? {} : { selection: pointer.selection }),
 	};
 }
 
@@ -503,6 +506,7 @@ function requirePointer(value: LatestPointer | undefined, expectedProfile: strin
 	) {
 		throw new Error("Remote latest pointer is malformed.");
 	}
+	if (value.selection !== undefined) portableSnapshotSelection(value.selection);
 	return value;
 }