@narumitw/pi-sync-daemon 0.6.2 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. package/CHANGELOG.md +8 -0
  2. package/README.md +1 -1
  3. package/dist/consent.js +11 -1
  4. package/dist/engine/backends/git/git-storage.js +11 -6
  5. package/dist/engine/paths.js +1 -1
  6. package/dist/engine/settings/config-file.js +2 -0
  7. package/dist/engine/settings/config.d.ts +2 -4
  8. package/dist/engine/settings/config.js +22 -7
  9. package/dist/engine/settings/settings-management.d.ts +2 -2
  10. package/dist/engine/settings/settings-management.js +27 -33
  11. package/dist/engine/settings/settings-types.d.ts +18 -4
  12. package/dist/engine/settings/settings-validation.js +34 -24
  13. package/dist/engine/snapshot/session-paths.d.ts +5 -3
  14. package/dist/engine/snapshot/session-paths.js +55 -9
  15. package/dist/engine/snapshot/snapshot-apply.d.ts +6 -7
  16. package/dist/engine/snapshot/snapshot-apply.js +88 -21
  17. package/dist/engine/snapshot/snapshot-bounds.d.ts +4 -0
  18. package/dist/engine/snapshot/snapshot-bounds.js +20 -0
  19. package/dist/engine/snapshot/snapshot-codec.js +3 -4
  20. package/dist/engine/snapshot/snapshot-entry-projection.d.ts +10 -0
  21. package/dist/engine/snapshot/snapshot-entry-projection.js +78 -0
  22. package/dist/engine/snapshot/snapshot-exclude-safety.d.ts +7 -2
  23. package/dist/engine/snapshot/snapshot-exclude-safety.js +180 -22
  24. package/dist/engine/snapshot/snapshot-payload.d.ts +2 -0
  25. package/dist/engine/snapshot/snapshot-payload.js +10 -0
  26. package/dist/engine/snapshot/snapshot-reviewed-preimages.d.ts +2 -0
  27. package/dist/engine/snapshot/snapshot-reviewed-preimages.js +60 -0
  28. package/dist/engine/snapshot/snapshot-root-transition.d.ts +4 -0
  29. package/dist/engine/snapshot/snapshot-root-transition.js +16 -0
  30. package/dist/engine/snapshot/snapshot-transaction-images.d.ts +37 -0
  31. package/dist/engine/snapshot/snapshot-transaction-images.js +357 -0
  32. package/dist/engine/snapshot/snapshot-transaction-policy.d.ts +50 -0
  33. package/dist/engine/snapshot/snapshot-transaction-policy.js +172 -0
  34. package/dist/engine/snapshot/snapshot-transaction-stage.d.ts +32 -0
  35. package/dist/engine/snapshot/snapshot-transaction-stage.js +303 -0
  36. package/dist/engine/snapshot/snapshot-transaction.d.ts +2 -1
  37. package/dist/engine/snapshot/snapshot-transaction.js +379 -331
  38. package/dist/engine/snapshot/snapshot-types.d.ts +24 -1
  39. package/dist/engine/snapshot/snapshot.d.ts +19 -2
  40. package/dist/engine/snapshot/snapshot.js +283 -26
  41. package/dist/engine/state/merge-baseline-store.js +20 -9
  42. package/dist/engine/state/state-types.d.ts +2 -0
  43. package/dist/engine/sync/apply-review.d.ts +3 -3
  44. package/dist/engine/sync/apply-review.js +5 -4
  45. package/dist/engine/sync/continuous-sync.js +19 -9
  46. package/dist/engine/sync/continuous-watch.d.ts +4 -1
  47. package/dist/engine/sync/continuous-watch.js +86 -14
  48. package/dist/engine/sync/exclude-policy.d.ts +4 -0
  49. package/dist/engine/sync/exclude-policy.js +8 -1
  50. package/dist/engine/sync/initialization.js +9 -5
  51. package/dist/engine/sync/local-fields.js +27 -8
  52. package/dist/engine/sync/merge-apply.js +155 -40
  53. package/dist/engine/sync/merge-journal.js +13 -4
  54. package/dist/engine/sync/merged-sync.js +21 -18
  55. package/dist/engine/sync/partial-progress.js +5 -3
  56. package/dist/engine/sync/remote-snapshot.d.ts +1 -0
  57. package/dist/engine/sync/remote-snapshot.js +8 -5
  58. package/dist/engine/sync/session-push.js +7 -6
  59. package/dist/engine/sync/sync-decision.d.ts +4 -0
  60. package/dist/engine/sync/sync-decision.js +17 -2
  61. package/dist/engine/sync/sync-inspection.js +3 -3
  62. package/dist/engine/sync/sync-mutations.d.ts +8 -1
  63. package/dist/engine/sync/sync-mutations.js +153 -72
  64. package/dist/engine/sync/sync-policy.d.ts +20 -10
  65. package/dist/engine/sync/sync-policy.js +170 -16
  66. package/dist/engine/sync/sync-queries.js +41 -31
  67. package/dist/engine/sync/sync-state.d.ts +11 -0
  68. package/dist/engine/sync/sync-state.js +24 -5
  69. package/dist/engine/ui/sync-format.js +22 -7
  70. package/docs/architecture.md +6 -0
  71. package/package.json +1 -1
@@ -3,14 +3,28 @@ export interface SnapshotFile {
3
3
  contentBase64: string;
4
4
  sha256: string;
5
5
  }
6
+ export interface DirectoryScope {
7
+ scope?: "agent-directory";
8
+ reinclude?: readonly string[];
9
+ }
6
10
  export type SnapshotSelection = {
7
11
  version: 1;
8
12
  include: string[];
9
13
  exclude?: never;
14
+ scope?: never;
15
+ reinclude?: never;
10
16
  } | {
11
17
  version: 2;
12
18
  include: string[];
13
19
  exclude: string[];
20
+ scope?: never;
21
+ reinclude?: never;
22
+ } | {
23
+ version: 3;
24
+ scope: "agent-directory";
25
+ include: string[];
26
+ exclude: string[];
27
+ reinclude: string[];
14
28
  };
15
29
  export interface Snapshot {
16
30
  version: number;
@@ -25,7 +39,16 @@ export interface Snapshot {
25
39
  localFields?: string[];
26
40
  files: SnapshotFile[];
27
41
  }
28
- export interface SnapshotOptions {
42
+ export interface AgentDirectoryInventory {
43
+ root: string;
44
+ sessionRoot: string;
45
+ scanSessions: boolean;
46
+ entries: ReadonlyMap<string, "file" | "directory" | "unreviewed">;
47
+ fileSizes: ReadonlyMap<string, number>;
48
+ walkedDirectories: ReadonlySet<string>;
49
+ routingDirectories: ReadonlySet<string>;
50
+ }
51
+ export interface SnapshotOptions extends DirectoryScope {
29
52
  signal?: AbortSignal;
30
53
  /** Caller-owned session/generation guard, rechecked at file-mutation boundaries. */
31
54
  validateMutation?: () => void;
@@ -1,11 +1,25 @@
1
1
  export { isDeniedPath } from "../paths.js";
2
2
  export { sessionStorageRoot } from "./snapshot-paths.js";
3
3
  import { type SyncSelectionConfig } from "../sync/sync-policy.js";
4
- import type { Snapshot, SnapshotFile, SnapshotOptions } from "./snapshot-types.js";
4
+ import type { AgentDirectoryInventory, Snapshot, SnapshotFile, SnapshotOptions } from "./snapshot-types.js";
5
5
  export { canonicalSnapshotPathForConfig, isConfiguredSnapshotPath } from "../sync/sync-policy.js";
6
+ export declare function agentDirectoryInventory(snapshot: Pick<Snapshot, "files">): AgentDirectoryInventory | undefined;
6
7
  export declare function regenerateSnapshotIdentity(snapshot: Snapshot): Snapshot;
7
8
  export declare function createSnapshot(profile: string, options?: SnapshotOptions): Promise<Snapshot>;
8
9
  export declare function collectFiles(root: string, options?: SnapshotOptions, excluded?: (relativePath: string) => boolean): Promise<SnapshotFile[]>;
10
+ export declare function agentDirectoryConfiguredSessionDir(signal?: AbortSignal, root?: string): Promise<string | undefined>;
11
+ export declare function readAgentDirectorySettings(signal?: AbortSignal, root?: string): Promise<Buffer<ArrayBuffer> | undefined>;
12
+ export declare function agentDirectorySessionDirFromSettings(content: Buffer): string | undefined;
13
+ export type AgentDirectoryScanOptions = SyncSelectionConfig & Pick<SnapshotOptions, "sessionDir" | "signal" | "validateMutation">;
14
+ export declare function scanAgentDirectoryInventory(root: string, options: AgentDirectoryScanOptions, pendingStateEntry?: string): Promise<{
15
+ root: string;
16
+ sessionRoot: string;
17
+ scanSessions: boolean;
18
+ entries: Map<string, "directory" | "file" | "unreviewed">;
19
+ fileSizes: Map<string, number>;
20
+ walkedDirectories: Set<string>;
21
+ routingDirectories: Set<string>;
22
+ }>;
9
23
  export declare function isSessionPath(relativePath: string): boolean;
10
24
  export declare function isSessionFilePath(relativePath: string): boolean;
11
25
  export declare function sessionSnapshotPathFromAbsolute(sessionFile: string, configuredSessionDir?: string): string | undefined;
@@ -13,6 +27,7 @@ export declare function snapshotTarget(root: string, relativePath: string, confi
13
27
  export declare function snapshotIncludesSessions(snapshot: Snapshot): boolean;
14
28
  export declare function filterSnapshotForConfigPolicy(snapshot: Snapshot, config: SyncSelectionConfig, options?: {
15
29
  regenerateId?: boolean;
30
+ sessionDir?: string;
16
31
  }): {
17
32
  id: string;
18
33
  createdAt: string;
@@ -26,5 +41,7 @@ export declare function filterSnapshotForConfigPolicy(snapshot: Snapshot, config
26
41
  };
27
42
  export declare function snapshotWithoutSessions(snapshot: Snapshot): Snapshot;
28
43
  export declare function scanSnapshot(snapshot: Snapshot): string[];
29
- export declare function mergeRemotePreservedFiles(local: Snapshot, remote: Snapshot, config: SyncSelectionConfig): Snapshot;
44
+ export declare function mergeRemotePreservedFiles(local: Snapshot, remote: Snapshot, config: SyncSelectionConfig, options?: {
45
+ sessionDir?: string;
46
+ }): Snapshot;
30
47
  export declare function mergeRemoteSessionFiles(local: Snapshot, remote: Snapshot): Snapshot;
@@ -1,16 +1,23 @@
1
1
  import { createHash, randomUUID } from "node:crypto";
2
+ import { constants } from "node:fs";
2
3
  import fs from "node:fs/promises";
3
4
  import os from "node:os";
4
5
  import path from "node:path";
5
6
  import { isDeniedPath, posixJoin, safeJoin, toPosix } from "../paths.js";
6
- import { agentDir, configuredSessionDir } from "./session-paths.js";
7
+ import { agentDir, configuredSessionDir, expandSessionDir } from "./session-paths.js";
8
+ import { assertAgentDirectorySettingsSize, MAX_AGENT_DIRECTORY_BYTES } from "./snapshot-bounds.js";
9
+ import { agentDirectoryAnchor, agentDirectoryPhysicalSessionPath, agentDirectorySessionRoot, } from "./snapshot-exclude-safety.js";
7
10
  import { sessionStorageRoot } from "./snapshot-paths.js";
8
11
  export { isDeniedPath } from "../paths.js";
9
12
  export { sessionStorageRoot } from "./snapshot-paths.js";
10
13
  import { compileSyncExclude } from "../sync/exclude-policy.js";
11
- import { canonicalSnapshotPathForConfig, configuredSnapshotPathMatcher, customIncludePathsByLower, DEFAULT_SYNC_INCLUDE, includeFromSelectionConfig, isPreservableUnmanagedSnapshotPath, normalizeExtraFiles, normalizeSyncFiles, sameSnapshotSelection, selectionForSnapshot, snapshotSelectionExclude, snapshotSelectionInclude, syncIncludeSelection, } from "../sync/sync-policy.js";
14
+ import { assertAgentDirectoryPathLayout, canonicalSnapshotPathForConfig, compileSyncPolicyExclude, compileSyncPolicyTraversal, configuredSnapshotPathMatcher, customIncludePathsByLower, DEFAULT_SYNC_INCLUDE, includeFromSelectionConfig, isPreservableUnmanagedSnapshotPath, MAX_AGENT_DIRECTORY_ENTRIES, MAX_AGENT_DIRECTORY_FILES, normalizeExtraFiles, normalizeSyncFiles, sameSnapshotSelection, selectionForSnapshot, snapshotSelectionExclude, snapshotSelectionInclude, syncIncludeSelection, syncSessionsSelected, } from "../sync/sync-policy.js";
12
15
  export { canonicalSnapshotPathForConfig, isConfiguredSnapshotPath } from "../sync/sync-policy.js";
13
16
  const VERSION = 1;
17
+ const scanInventories = new WeakMap();
18
+ export function agentDirectoryInventory(snapshot) {
19
+ return scanInventories.get(snapshot);
20
+ }
14
21
  const TOP_LEVEL_FILES = DEFAULT_SYNC_INCLUDE.filter((name) => name.includes("."));
15
22
  const TOP_LEVEL_DIRS = new Set(DEFAULT_SYNC_INCLUDE.filter((name) => !name.includes(".")));
16
23
  const SECRET_PATTERNS = [
@@ -66,32 +73,37 @@ export function regenerateSnapshotIdentity(snapshot) {
66
73
  export async function createSnapshot(profile, options = {}) {
67
74
  options.signal?.throwIfAborted();
68
75
  const include = effectiveInclude(options);
69
- const excluded = compileSyncExclude(options.exclude);
70
- const syncSessions = include.includes("sessions") && !excluded("sessions");
76
+ const policy = { ...options, include };
77
+ const excluded = compileSyncPolicyExclude(policy);
78
+ const syncSessions = syncSessionsSelected(policy);
71
79
  const needsSessionConfig = syncSessions || !excluded("settings.json");
72
- const sessionDir = options.sessionDir ?? (needsSessionConfig ? await configuredSessionDir() : undefined);
80
+ const sessionDir = options.scope === "agent-directory"
81
+ ? options.sessionDir
82
+ : (options.sessionDir ?? (needsSessionConfig ? await configuredSessionDir() : undefined));
73
83
  options.signal?.throwIfAborted();
74
- const files = await collectFiles(agentDir(), {
75
- include,
76
- exclude: options.exclude,
77
- sessionDir,
78
- signal: options.signal,
79
- }, excluded);
84
+ const collectionOptions = { ...policy, sessionDir };
85
+ const collected = options.scope === "agent-directory" ? await collectAgentDirectory(agentDir(), collectionOptions) : undefined;
86
+ const files = collected?.files ?? (await collectFiles(agentDir(), collectionOptions, excluded));
80
87
  options.signal?.throwIfAborted();
81
- return {
82
- version: options.exclude === undefined ? VERSION : 4,
88
+ const snapshot = {
89
+ version: options.scope === "agent-directory" ? 5 : options.exclude === undefined ? VERSION : 4,
83
90
  id: snapshotId(),
84
91
  createdAt: new Date().toISOString(),
85
92
  machine: os.hostname(),
86
93
  profile,
87
94
  syncSessions,
88
- selection: selectionForSnapshot(include, options.exclude),
95
+ selection: selectionForSnapshot(include, options.exclude, options),
89
96
  files,
90
97
  };
98
+ if (collected)
99
+ scanInventories.set(snapshot, collected.inventory);
100
+ return snapshot;
91
101
  }
92
102
  function effectiveInclude(options) {
93
103
  if (options.include)
94
104
  return options.include;
105
+ if (options.scope === "agent-directory")
106
+ return [];
95
107
  return [
96
108
  ...normalizeSyncFiles(options.syncFiles),
97
109
  ...normalizeExtraFiles(options.extraFiles),
@@ -99,6 +111,8 @@ function effectiveInclude(options) {
99
111
  ];
100
112
  }
101
113
  export async function collectFiles(root, options = {}, excluded = compileSyncExclude(options.exclude)) {
114
+ if (options.scope === "agent-directory")
115
+ return (await collectAgentDirectory(root, options)).files;
102
116
  const signal = options.signal;
103
117
  signal?.throwIfAborted();
104
118
  const results = [];
@@ -142,6 +156,222 @@ export async function collectFiles(root, options = {}, excluded = compileSyncExc
142
156
  signal?.throwIfAborted();
143
157
  return results.sort((left, right) => left.path.localeCompare(right.path));
144
158
  }
159
+ function sameScannedPath(left, right) {
160
+ return (left.dev === right.dev &&
161
+ left.ino === right.ino &&
162
+ left.mode === right.mode &&
163
+ left.nlink === right.nlink &&
164
+ left.size === right.size &&
165
+ left.mtimeMs === right.mtimeMs &&
166
+ left.ctimeMs === right.ctimeMs);
167
+ }
168
+ function changedScan() {
169
+ throw new Error("Agent directory changed or has an unsafe filesystem layout; no snapshot was collected.");
170
+ }
171
+ async function identify(absolute, canonical, signal) {
172
+ signal?.throwIfAborted();
173
+ const stat = await fs.lstat(absolute);
174
+ if (stat.isSymbolicLink() || (await fs.realpath(absolute)) !== canonical)
175
+ changedScan();
176
+ signal?.throwIfAborted();
177
+ return { absolute, canonical, stat };
178
+ }
179
+ async function recheck({ absolute, canonical, stat }, signal) {
180
+ if (!sameScannedPath((await identify(absolute, canonical, signal)).stat, stat))
181
+ changedScan();
182
+ }
183
+ async function readScannedFile(candidate, signal) {
184
+ await recheck(candidate, signal);
185
+ const handle = await fs.open(candidate.absolute, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
186
+ try {
187
+ if (!sameScannedPath(await handle.stat(), candidate.stat))
188
+ changedScan();
189
+ await recheck(candidate, signal);
190
+ const content = Buffer.alloc(candidate.stat.size);
191
+ for (let offset = 0; offset < content.length;) {
192
+ signal?.throwIfAborted();
193
+ const { bytesRead } = await handle.read(content, offset, content.length - offset, offset);
194
+ if (bytesRead === 0)
195
+ changedScan();
196
+ offset += bytesRead;
197
+ }
198
+ if (!sameScannedPath(await handle.stat(), candidate.stat))
199
+ changedScan();
200
+ return content;
201
+ }
202
+ finally {
203
+ await handle.close();
204
+ }
205
+ }
206
+ export async function agentDirectoryConfiguredSessionDir(signal, root = agentDir()) {
207
+ const content = await readAgentDirectorySettings(signal, root);
208
+ return content === undefined ? undefined : agentDirectorySessionDirFromSettings(content);
209
+ }
210
+ export async function readAgentDirectorySettings(signal, root = agentDir()) {
211
+ const absolute = path.resolve(root);
212
+ const canonical = path.join(await fs.realpath(path.dirname(absolute)), path.basename(absolute));
213
+ await identify(absolute, canonical, signal);
214
+ let settings;
215
+ try {
216
+ settings = await identify(path.join(absolute, "settings.json"), path.join(canonical, "settings.json"), signal);
217
+ }
218
+ catch (error) {
219
+ if (error.code === "ENOENT")
220
+ return undefined;
221
+ throw error;
222
+ }
223
+ if (!settings.stat.isFile() || settings.stat.nlink !== 1)
224
+ changedScan();
225
+ assertAgentDirectorySettingsSize(settings.stat.size);
226
+ const content = await readScannedFile(settings, signal);
227
+ await recheck(settings, signal);
228
+ return content;
229
+ }
230
+ export function agentDirectorySessionDirFromSettings(content) {
231
+ assertAgentDirectorySettingsSize(content.length);
232
+ let value;
233
+ try {
234
+ value = JSON.parse(content.toString("utf8").replace(/^\uFEFF/u, ""))
235
+ ?.sessionDir;
236
+ }
237
+ catch {
238
+ throw new Error("Pi settings.json cannot be parsed; repair the file before syncing.");
239
+ }
240
+ if (value !== undefined && typeof value !== "string")
241
+ throw new Error("Pi sessionDir must be a string.");
242
+ return value ? expandSessionDir(value) : undefined;
243
+ }
244
+ export async function scanAgentDirectoryInventory(root, options, pendingStateEntry) {
245
+ return (await collectAgentDirectory(root, options, false, pendingStateEntry)).inventory;
246
+ }
247
+ async function collectAgentDirectory(root, options, readContents = true, pendingStateEntry) {
248
+ const signal = options.signal;
249
+ const excluded = compileSyncPolicyExclude(options);
250
+ const canTraverse = compileSyncPolicyTraversal(options);
251
+ const sessionDir = options.sessionDir ?? (await agentDirectoryConfiguredSessionDir(signal, root));
252
+ const isPhysicalSessionPath = agentDirectoryPhysicalSessionPath(root, sessionDir);
253
+ const sessionRoot = agentDirectorySessionRoot(root, sessionDir);
254
+ const directories = [];
255
+ const candidates = [];
256
+ const entries = new Map();
257
+ const routingDirectories = new Set();
258
+ let bytes = 0;
259
+ async function walk(directory, prefix, sessions) {
260
+ if (!directory.stat.isDirectory())
261
+ changedScan();
262
+ directories.push(directory);
263
+ const children = [];
264
+ for await (const entry of await fs.opendir(directory.absolute)) {
265
+ signal?.throwIfAborted();
266
+ const absolute = path.join(directory.absolute, entry.name);
267
+ entries.set(absolute, "unreviewed");
268
+ const allowance = pendingStateEntry !== undefined && entries.has(pendingStateEntry) ? 1 : 0;
269
+ if (entries.size > MAX_AGENT_DIRECTORY_ENTRIES + allowance)
270
+ throw new Error("Agent directory exceeds the scan entry bound.");
271
+ children.push(entry);
272
+ }
273
+ await recheck(directory, signal);
274
+ for (const entry of children) {
275
+ signal?.throwIfAborted();
276
+ const snapshotPath = posixJoin(prefix, entry.name);
277
+ if (!sessions && (/^sessions(?:\/|$)/iu.test(snapshotPath) || isPhysicalSessionPath(snapshotPath)))
278
+ continue;
279
+ if (entry.isDirectory() ? !canTraverse(snapshotPath) : !entry.isFile() || excluded(snapshotPath))
280
+ continue;
281
+ if (!entry.isDirectory() && sessions && !isSessionFilePath(snapshotPath))
282
+ continue;
283
+ const candidate = await identify(path.join(directory.absolute, entry.name), path.join(directory.canonical, entry.name), signal);
284
+ if (entry.isDirectory()) {
285
+ if (!excluded(snapshotPath))
286
+ entries.set(candidate.absolute, "directory");
287
+ await walk(candidate, snapshotPath, sessions);
288
+ }
289
+ else {
290
+ if (!candidate.stat.isFile() || candidate.stat.nlink !== 1)
291
+ changedScan();
292
+ if (snapshotPath.toLowerCase() === "settings.json")
293
+ assertAgentDirectorySettingsSize(candidate.stat.size);
294
+ bytes += candidate.stat.size;
295
+ if (bytes > MAX_AGENT_DIRECTORY_BYTES)
296
+ throw new Error("Agent directory exceeds the 64 MiB scan byte bound.");
297
+ if (candidates.length >= MAX_AGENT_DIRECTORY_FILES)
298
+ throw new Error("Agent directory exceeds the scan file bound.");
299
+ entries.set(candidate.absolute, "file");
300
+ candidates.push({ ...candidate, snapshotPath });
301
+ }
302
+ }
303
+ await recheck(directory, signal);
304
+ }
305
+ const absoluteRoot = path.resolve(root);
306
+ const canonicalRoot = path.join(await fs.realpath(path.dirname(absoluteRoot)), path.basename(absoluteRoot));
307
+ const selectedSessions = syncSessionsSelected(options);
308
+ async function identifySessionRoot(routing) {
309
+ if (!sessionDir && !selectedSessions)
310
+ return undefined;
311
+ let absolute = agentDirectoryAnchor(absoluteRoot, sessionRoot);
312
+ const parts = path.relative(absolute, sessionRoot).split(path.sep);
313
+ let canonical = await fs.realpath(absolute);
314
+ let directory;
315
+ try {
316
+ for (const part of parts) {
317
+ absolute = path.join(absolute, part);
318
+ canonical = path.join(canonical, part);
319
+ directory = await identify(absolute, canonical, signal);
320
+ if (!directory.stat.isDirectory())
321
+ changedScan();
322
+ routing?.add(absolute);
323
+ }
324
+ }
325
+ catch (error) {
326
+ if (error.code === "ENOENT")
327
+ return undefined;
328
+ throw error;
329
+ }
330
+ return directory;
331
+ }
332
+ const sessionDirectory = await identifySessionRoot(routingDirectories);
333
+ await walk(await identify(absoluteRoot, canonicalRoot, signal), "", false);
334
+ if (selectedSessions && sessionDirectory)
335
+ await walk(sessionDirectory, "sessions", true);
336
+ assertAgentDirectoryPathLayout(candidates.map((candidate) => candidate.snapshotPath));
337
+ const results = [];
338
+ if (readContents) {
339
+ for (const candidate of candidates) {
340
+ const content = await readScannedFile(candidate, signal);
341
+ results.push({
342
+ path: candidate.snapshotPath,
343
+ contentBase64: content.toString("base64"),
344
+ sha256: sha256(content),
345
+ });
346
+ }
347
+ }
348
+ for (const directory of directories)
349
+ await recheck(directory, signal);
350
+ if (options.sessionDir === undefined && (await agentDirectoryConfiguredSessionDir(signal, root)) !== sessionDir)
351
+ changedScan();
352
+ const currentSessionDirectory = await identifySessionRoot();
353
+ if (Boolean(sessionDirectory) !== Boolean(currentSessionDirectory) ||
354
+ (sessionDirectory &&
355
+ currentSessionDirectory &&
356
+ (sessionDirectory.stat.dev !== currentSessionDirectory.stat.dev ||
357
+ sessionDirectory.stat.ino !== currentSessionDirectory.stat.ino)))
358
+ changedScan();
359
+ for (const candidate of candidates)
360
+ await recheck(candidate, signal);
361
+ signal?.throwIfAborted();
362
+ return {
363
+ files: results.sort((left, right) => left.path.localeCompare(right.path)),
364
+ inventory: {
365
+ root: absoluteRoot,
366
+ sessionRoot,
367
+ scanSessions: selectedSessions,
368
+ entries,
369
+ fileSizes: new Map(candidates.map(({ absolute, stat }) => [absolute, stat.size])),
370
+ walkedDirectories: new Set(directories.map(({ absolute }) => absolute)),
371
+ routingDirectories,
372
+ },
373
+ };
374
+ }
145
375
  async function collectIncludedPath(results, root, relativePath, signal, excluded) {
146
376
  signal?.throwIfAborted();
147
377
  const absolutePath = safeJoin(root, relativePath);
@@ -217,6 +447,8 @@ export function snapshotTarget(root, relativePath, configuredSessionDir) {
217
447
  return safeJoin(root, relativePath);
218
448
  }
219
449
  export function snapshotIncludesSessions(snapshot) {
450
+ if (snapshot.selection?.version === 3)
451
+ return syncSessionsSelected(snapshot.selection);
220
452
  return (snapshot.syncSessions === true ||
221
453
  (snapshotSelectionInclude(snapshot)?.includes("sessions") === true &&
222
454
  !compileSyncExclude(snapshotSelectionExclude(snapshot))("sessions")) ||
@@ -224,14 +456,17 @@ export function snapshotIncludesSessions(snapshot) {
224
456
  }
225
457
  export function filterSnapshotForConfigPolicy(snapshot, config, options = {}) {
226
458
  const include = includeFromSelectionConfig(config);
227
- const includePaths = customIncludePathsByLower(include);
228
- const exclude = config.exclude ?? (snapshot.version === 4 ? [] : undefined);
459
+ const wholeDirectory = config.scope === "agent-directory";
460
+ const exclude = config.exclude ?? (snapshot.version >= 4 ? [] : undefined);
461
+ const files = wholeDirectory
462
+ ? filterAgentDirectoryFiles(snapshot.files, config, options.sessionDir)
463
+ : canonicalizeSnapshotFilesForConfig(snapshot.files, config, customIncludePathsByLower(include));
229
464
  const filtered = {
230
465
  ...snapshot,
231
- version: exclude === undefined ? snapshot.version : 4,
232
- syncSessions: include.includes("sessions") && !compileSyncExclude(exclude)("sessions") ? snapshot.syncSessions : false,
233
- selection: selectionForSnapshot(include, exclude),
234
- files: canonicalizeSnapshotFilesForConfig(snapshot.files, config, includePaths),
466
+ version: wholeDirectory ? 5 : exclude === undefined ? snapshot.version : 4,
467
+ syncSessions: syncSessionsSelected(config) ? snapshot.syncSessions : false,
468
+ selection: selectionForSnapshot(include, exclude, config),
469
+ files,
235
470
  };
236
471
  if (!options.regenerateId || snapshotsMatch(snapshot, filtered))
237
472
  return filtered;
@@ -242,6 +477,19 @@ export function filterSnapshotForConfigPolicy(snapshot, config, options = {}) {
242
477
  machine: os.hostname(),
243
478
  };
244
479
  }
480
+ function filterAgentDirectoryFiles(files, config, sessionDir) {
481
+ const configured = configuredSnapshotPathMatcher(config);
482
+ const isPhysicalSessionPath = sessionDir ? agentDirectoryPhysicalSessionPath(agentDir(), sessionDir) : undefined;
483
+ const projected = files.filter((file) => {
484
+ if (!isSafeSnapshotPath(file.path) || !configured(file.path))
485
+ return false;
486
+ if (/^sessions(?:\/|$)/iu.test(file.path))
487
+ return isSessionFilePath(file.path);
488
+ return !isPhysicalSessionPath?.(file.path);
489
+ });
490
+ assertAgentDirectoryPathLayout(projected.map((file) => file.path));
491
+ return projected.sort((left, right) => left.path.localeCompare(right.path));
492
+ }
245
493
  function canonicalizeSnapshotFilesForConfig(files, config, includePaths) {
246
494
  const configuredFiles = [];
247
495
  const extraCandidates = new Map();
@@ -287,7 +535,11 @@ export function snapshotWithoutSessions(snapshot) {
287
535
  createdAt: new Date().toISOString(),
288
536
  machine: os.hostname(),
289
537
  syncSessions: false,
290
- ...(include ? { selection: selectionForSnapshot(include, snapshotSelectionExclude(snapshot)) } : {}),
538
+ ...(include
539
+ ? {
540
+ selection: selectionForSnapshot(include, snapshotSelectionExclude(snapshot), snapshot.selection?.version === 3 ? snapshot.selection : undefined),
541
+ }
542
+ : {}),
291
543
  files,
292
544
  };
293
545
  }
@@ -307,11 +559,13 @@ export function scanSnapshot(snapshot) {
307
559
  }
308
560
  return findings;
309
561
  }
310
- export function mergeRemotePreservedFiles(local, remote, config) {
562
+ export function mergeRemotePreservedFiles(local, remote, config, options = {}) {
563
+ if (config.scope === "agent-directory")
564
+ return filterSnapshotForConfigPolicy(local, config, { ...options, regenerateId: true });
311
565
  const localPathNames = new Set(local.files.map((file) => file.path.toLowerCase()));
312
566
  const preservedPathNames = new Set();
313
567
  const configured = configuredSnapshotPathMatcher(config);
314
- const excluded = compileSyncExclude(config.exclude);
568
+ const excluded = compileSyncPolicyExclude(config);
315
569
  const preserved = remote.files.filter((file) => {
316
570
  const normalized = toPosix(file.path);
317
571
  const lower = normalized.toLowerCase();
@@ -338,8 +592,11 @@ export function mergeRemotePreservedFiles(local, remote, config) {
338
592
  };
339
593
  }
340
594
  export function mergeRemoteSessionFiles(local, remote) {
341
- const excluded = compileSyncExclude(snapshotSelectionExclude(local));
342
- if (excluded("sessions"))
595
+ const directory = local.selection?.version === 3 ? local.selection : undefined;
596
+ const excluded = directory
597
+ ? compileSyncPolicyExclude(directory)
598
+ : compileSyncExclude(snapshotSelectionExclude(local));
599
+ if (directory ? !syncSessionsSelected(directory) : excluded("sessions"))
343
600
  return local;
344
601
  const remoteSessions = remote.files.filter((file) => {
345
602
  const normalized = toPosix(file.path);
@@ -356,7 +613,7 @@ export function mergeRemoteSessionFiles(local, remote) {
356
613
  syncSessions: true,
357
614
  ...(localInclude
358
615
  ? {
359
- selection: selectionForSnapshot(localInclude.includes("sessions") ? localInclude : [...localInclude, "sessions"], snapshotSelectionExclude(local)),
616
+ selection: selectionForSnapshot(localInclude.includes("sessions") ? localInclude : [...localInclude, "sessions"], snapshotSelectionExclude(local), directory),
360
617
  }
361
618
  : {}),
362
619
  files: [...local.files.filter((file) => !isSessionPath(file.path)), ...remoteSessions].sort((left, right) => left.path.localeCompare(right.path)),
@@ -6,6 +6,7 @@ import { compileSyncExclude, normalizeSyncExclude } from "../sync/exclude-policy
6
6
  import { collidingPaths, planFileMerge } from "../sync/file-merge-planner.js";
7
7
  import { parseSettingsDocument } from "../sync/json-document.js";
8
8
  import { validateSession } from "../sync/session-merge.js";
9
+ import { configuredSnapshotPathMatcher, syncDirectoryPolicyKey } from "../sync/sync-policy.js";
9
10
  import { isMergeTextPath, text } from "../sync/text-merge.js";
10
11
  import { syncDirectory, writeJson } from "./json-file.js";
11
12
  import { statePathForConfig, syncStateFingerprint } from "./sync-state-store.js";
@@ -33,11 +34,19 @@ function identity(config) {
33
34
  backendIdentityCoordinates(config),
34
35
  config.include,
35
36
  config.localFields ?? [],
36
- ...(config.exclude === undefined
37
- ? []
38
- : ["exclude", normalizeSyncExclude(config.exclude).map((rule) => rule.toLowerCase())]),
37
+ ...(config.scope === "agent-directory"
38
+ ? [syncDirectoryPolicyKey(config)]
39
+ : config.exclude === undefined
40
+ ? []
41
+ : ["exclude", normalizeSyncExclude(config.exclude).map((rule) => rule.toLowerCase())]),
39
42
  ]);
40
43
  }
44
+ function baselinePathMatcher(config) {
45
+ if (config.scope === "agent-directory")
46
+ return configuredSnapshotPathMatcher(config);
47
+ const excluded = compileSyncExclude(config.exclude);
48
+ return (filePath) => !excluded(filePath);
49
+ }
41
50
  function directory(config) {
42
51
  return `${statePathForConfig(config)}.ancestors`;
43
52
  }
@@ -55,9 +64,9 @@ function baselinePath(config, state) {
55
64
  /** Stage before accepted state, retain its previous ancestor until journal retirement. Never bootstrap from current edits. */
56
65
  export async function stageMergeBaseline(config, snapshot, accepted, previous) {
57
66
  const collisions = collidingPaths(snapshot.files.map((file) => file.path));
58
- const excluded = compileSyncExclude(config.exclude);
67
+ const configured = baselinePathMatcher(config);
59
68
  const files = snapshot.files.filter((file) => {
60
- return (!excluded(file.path) &&
69
+ return (configured(file.path) &&
61
70
  !collisions.has(file.path) &&
62
71
  accepted.lastFileHashes[file.path] === file.sha256 &&
63
72
  (file.path === "settings.json" || config.mergeContent || (config.agentMode && isMergeTextPath(file.path))) &&
@@ -73,7 +82,7 @@ export async function stageMergeBaseline(config, snapshot, accepted, previous) {
73
82
  /* Keep unknown evidence; missing bytes are never invented. */
74
83
  }
75
84
  for (const ancestor of ancestors)
76
- if (!excluded(ancestor.path) &&
85
+ if (configured(ancestor.path) &&
77
86
  !collisions.has(ancestor.path) &&
78
87
  accepted.lastFileHashes[ancestor.path] === ancestor.sha256 &&
79
88
  !stagedPaths.has(ancestor.path)) {
@@ -128,8 +137,8 @@ export async function readMergeAncestors(config, state) {
128
137
  return;
129
138
  throw new Error("Merge ancestor is invalid; preserve its private cache and review the conflict.");
130
139
  }
131
- const excluded = compileSyncExclude(config.exclude);
132
- return record.files.filter((file) => !excluded(file.path));
140
+ const configured = baselinePathMatcher(config);
141
+ return record.files.filter((file) => configured(file.path));
133
142
  }
134
143
  /** A no-op must not skip seeding or repairing ancestors required by later merges. */
135
144
  export async function hasCurrentMergeBaseline(config, snapshot, state) {
@@ -138,7 +147,9 @@ export async function hasCurrentMergeBaseline(config, snapshot, state) {
138
147
  if (!ancestors)
139
148
  return false;
140
149
  const hashes = new Map(ancestors.map((file) => [file.path, file.sha256]));
141
- return snapshot.files.every((file) => !(file.path === "settings.json" || config.mergeContent || (config.agentMode && isMergeTextPath(file.path))) ||
150
+ const configured = configuredSnapshotPathMatcher(config);
151
+ return snapshot.files.every((file) => (config.scope === "agent-directory" && !configured(file.path)) ||
152
+ !(file.path === "settings.json" || config.mergeContent || (config.agentMode && isMergeTextPath(file.path))) ||
142
153
  !eligible(file) ||
143
154
  hashes.get(file.path) === file.sha256);
144
155
  }
@@ -7,6 +7,8 @@ export interface SyncState {
7
7
  lastFileHashes: Record<string, string>;
8
8
  include?: string[];
9
9
  exclude?: string[];
10
+ scope?: "agent-directory";
11
+ reinclude?: string[];
10
12
  localFields?: string[];
11
13
  lastObservedSnapshot?: string;
12
14
  lastObservedRevision?: string;
@@ -1,8 +1,8 @@
1
- import type { Snapshot } from "../snapshot/snapshot-types.js";
1
+ import type { Snapshot, SnapshotOptions } from "../snapshot/snapshot-types.js";
2
2
  export interface CaseCleanupReview {
3
3
  path: string;
4
4
  fingerprint: string;
5
5
  }
6
6
  /** Inspect the apply engine's additional alias removals, which logical snapshots omit. */
7
- export declare function inspectCaseCleanup(snapshot: Snapshot, signal?: AbortSignal): Promise<CaseCleanupReview[]>;
8
- export declare function revalidateCaseCleanup(expected: readonly CaseCleanupReview[], snapshot: Snapshot, signal?: AbortSignal): Promise<void>;
7
+ export declare function inspectCaseCleanup(snapshot: Snapshot, options: SnapshotOptions): Promise<CaseCleanupReview[]>;
8
+ export declare function revalidateCaseCleanup(expected: readonly CaseCleanupReview[], snapshot: Snapshot, options: SnapshotOptions): Promise<void>;
@@ -6,10 +6,11 @@ import { agentDir } from "../snapshot/session-paths.js";
6
6
  import { addTopLevelCaseVariantDeletes } from "../snapshot/snapshot-apply.js";
7
7
  import { throwIfAborted } from "./signals.js";
8
8
  /** Inspect the apply engine's additional alias removals, which logical snapshots omit. */
9
- export async function inspectCaseCleanup(snapshot, signal) {
9
+ export async function inspectCaseCleanup(snapshot, options) {
10
+ const { signal } = options;
10
11
  throwIfAborted(signal);
11
12
  const root = agentDir();
12
- const plan = await addTopLevelCaseVariantDeletes(root, { writes: [], deletes: [] }, snapshot);
13
+ const plan = await addTopLevelCaseVariantDeletes(root, { writes: [], deletes: [] }, snapshot, options);
13
14
  throwIfAborted(signal);
14
15
  const review = [];
15
16
  for (const target of plan.deletes.sort()) {
@@ -44,8 +45,8 @@ export async function inspectCaseCleanup(snapshot, signal) {
44
45
  }
45
46
  return review;
46
47
  }
47
- export async function revalidateCaseCleanup(expected, snapshot, signal) {
48
- const current = await inspectCaseCleanup(snapshot, signal);
48
+ export async function revalidateCaseCleanup(expected, snapshot, options) {
49
+ const current = await inspectCaseCleanup(snapshot, options);
49
50
  if (JSON.stringify(current) !== JSON.stringify(expected))
50
51
  throw new Error("Case-variant paths changed during transfer review; reopen the preview.");
51
52
  }