@narumitw/pi-sync 0.49.3 → 0.49.5

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
@@ -232,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
 ```
 
@@ -254,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.
@@ -279,17 +302,20 @@ 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
 │   ├── config.ts
 │   ├── config-file.ts
+│   ├── state-directory.ts
 │   ├── settings-management.ts
 │   ├── manager-ui.ts
 │   ├── 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.5",
 	"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/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/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

@@ -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;
@@ -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/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") ||