@narumitw/pi-sync-daemon 0.6.2 → 0.8.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 (97) hide show
  1. package/CHANGELOG.md +19 -0
  2. package/README.md +17 -3
  3. package/dist/consent.js +26 -1
  4. package/dist/engine/backends/git/git-backend.d.ts +1 -1
  5. package/dist/engine/backends/git/git-backend.js +17 -2
  6. package/dist/engine/backends/git/git-storage.d.ts +1 -1
  7. package/dist/engine/backends/git/git-storage.js +39 -13
  8. package/dist/engine/backends/s3/s3-backend.js +8 -0
  9. package/dist/engine/backends/sync-backend.d.ts +1 -0
  10. package/dist/engine/backends/webdav/webdav-backend.js +8 -0
  11. package/dist/engine/ignore/effective-ignore-policy.d.ts +10 -0
  12. package/dist/engine/ignore/effective-ignore-policy.js +33 -0
  13. package/dist/engine/ignore/ignore-edit.d.ts +13 -0
  14. package/dist/engine/ignore/ignore-edit.js +102 -0
  15. package/dist/engine/ignore/ignore-initialization.d.ts +6 -0
  16. package/dist/engine/ignore/ignore-initialization.js +186 -0
  17. package/dist/engine/ignore/ignore-migration-prompt.d.ts +7 -0
  18. package/dist/engine/ignore/ignore-migration-prompt.js +139 -0
  19. package/dist/engine/ignore/ignore-settings.d.ts +15 -0
  20. package/dist/engine/ignore/ignore-settings.js +322 -0
  21. package/dist/engine/ignore/ignore-source.d.ts +27 -0
  22. package/dist/engine/ignore/ignore-source.js +250 -0
  23. package/dist/engine/paths.js +1 -1
  24. package/dist/engine/settings/config-file.d.ts +9 -2
  25. package/dist/engine/settings/config-file.js +126 -28
  26. package/dist/engine/settings/config.d.ts +5 -4
  27. package/dist/engine/settings/config.js +114 -13
  28. package/dist/engine/settings/settings-management.js +34 -32
  29. package/dist/engine/settings/settings-types.d.ts +40 -5
  30. package/dist/engine/settings/settings-validation.js +52 -24
  31. package/dist/engine/snapshot/session-paths.d.ts +6 -4
  32. package/dist/engine/snapshot/session-paths.js +84 -15
  33. package/dist/engine/snapshot/snapshot-apply.d.ts +7 -8
  34. package/dist/engine/snapshot/snapshot-apply.js +107 -21
  35. package/dist/engine/snapshot/snapshot-bounds.d.ts +4 -0
  36. package/dist/engine/snapshot/snapshot-bounds.js +20 -0
  37. package/dist/engine/snapshot/snapshot-codec.d.ts +1 -1
  38. package/dist/engine/snapshot/snapshot-codec.js +15 -7
  39. package/dist/engine/snapshot/snapshot-entry-projection.d.ts +10 -0
  40. package/dist/engine/snapshot/snapshot-entry-projection.js +78 -0
  41. package/dist/engine/snapshot/snapshot-exclude-safety.d.ts +9 -2
  42. package/dist/engine/snapshot/snapshot-exclude-safety.js +239 -24
  43. package/dist/engine/snapshot/snapshot-payload.d.ts +2 -0
  44. package/dist/engine/snapshot/snapshot-payload.js +10 -0
  45. package/dist/engine/snapshot/snapshot-reviewed-preimages.d.ts +2 -0
  46. package/dist/engine/snapshot/snapshot-reviewed-preimages.js +60 -0
  47. package/dist/engine/snapshot/snapshot-root-transition.d.ts +4 -0
  48. package/dist/engine/snapshot/snapshot-root-transition.js +16 -0
  49. package/dist/engine/snapshot/snapshot-transaction-images.d.ts +39 -0
  50. package/dist/engine/snapshot/snapshot-transaction-images.js +387 -0
  51. package/dist/engine/snapshot/snapshot-transaction-policy.d.ts +73 -0
  52. package/dist/engine/snapshot/snapshot-transaction-policy.js +276 -0
  53. package/dist/engine/snapshot/snapshot-transaction-stage.d.ts +32 -0
  54. package/dist/engine/snapshot/snapshot-transaction-stage.js +303 -0
  55. package/dist/engine/snapshot/snapshot-transaction-verification.d.ts +7 -0
  56. package/dist/engine/snapshot/snapshot-transaction-verification.js +78 -0
  57. package/dist/engine/snapshot/snapshot-transaction.d.ts +1 -11
  58. package/dist/engine/snapshot/snapshot-transaction.js +390 -364
  59. package/dist/engine/snapshot/snapshot-types.d.ts +47 -2
  60. package/dist/engine/snapshot/snapshot-types.js +9 -1
  61. package/dist/engine/snapshot/snapshot.d.ts +22 -3
  62. package/dist/engine/snapshot/snapshot.js +357 -43
  63. package/dist/engine/state/merge-baseline-store.js +20 -9
  64. package/dist/engine/state/state-types.d.ts +3 -0
  65. package/dist/engine/sync/apply-review.d.ts +3 -3
  66. package/dist/engine/sync/apply-review.js +5 -4
  67. package/dist/engine/sync/continuous-sync.js +37 -12
  68. package/dist/engine/sync/continuous-watch.d.ts +4 -1
  69. package/dist/engine/sync/continuous-watch.js +90 -15
  70. package/dist/engine/sync/exclude-policy.d.ts +4 -0
  71. package/dist/engine/sync/exclude-policy.js +8 -1
  72. package/dist/engine/sync/initialization.js +9 -4
  73. package/dist/engine/sync/local-fields.d.ts +3 -1
  74. package/dist/engine/sync/local-fields.js +88 -8
  75. package/dist/engine/sync/merge-apply.js +190 -47
  76. package/dist/engine/sync/merge-journal.d.ts +18 -4
  77. package/dist/engine/sync/merge-journal.js +126 -10
  78. package/dist/engine/sync/merged-sync.d.ts +1 -1
  79. package/dist/engine/sync/merged-sync.js +124 -68
  80. package/dist/engine/sync/partial-progress.js +5 -3
  81. package/dist/engine/sync/remote-snapshot.d.ts +10 -2
  82. package/dist/engine/sync/remote-snapshot.js +59 -17
  83. package/dist/engine/sync/session-push.js +7 -6
  84. package/dist/engine/sync/sync-decision.d.ts +4 -0
  85. package/dist/engine/sync/sync-decision.js +17 -2
  86. package/dist/engine/sync/sync-inspection.js +8 -6
  87. package/dist/engine/sync/sync-mutations.d.ts +10 -2
  88. package/dist/engine/sync/sync-mutations.js +245 -101
  89. package/dist/engine/sync/sync-policy.d.ts +36 -10
  90. package/dist/engine/sync/sync-policy.js +285 -20
  91. package/dist/engine/sync/sync-queries.js +49 -32
  92. package/dist/engine/sync/sync-state.d.ts +11 -0
  93. package/dist/engine/sync/sync-state.js +42 -5
  94. package/dist/engine/ui/sync-format.js +22 -7
  95. package/dist/engine-service.js +24 -2
  96. package/docs/architecture.md +28 -0
  97. package/package.json +2 -1
@@ -1,16 +1,24 @@
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, reservedIgnoreTargetGuard, } 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, isIgnoreControlPath, isPreservableUnmanagedSnapshotPath, MAX_AGENT_DIRECTORY_ENTRIES, MAX_AGENT_DIRECTORY_FILES, normalizeExtraFiles, normalizeSyncFiles, requireLegacyTransferPolicy, sameSnapshotSelection, selectionForSnapshot, snapshotSelectionExclude, snapshotSelectionInclude, syncIncludeSelection, syncSessionsSelected, } from "../sync/sync-policy.js";
15
+ import { IGNORE_SNAPSHOT_VERSION, } from "./snapshot-types.js";
12
16
  export { canonicalSnapshotPathForConfig, isConfiguredSnapshotPath } from "../sync/sync-policy.js";
13
17
  const VERSION = 1;
18
+ const scanInventories = new WeakMap();
19
+ export function agentDirectoryInventory(snapshot) {
20
+ return scanInventories.get(snapshot);
21
+ }
14
22
  const TOP_LEVEL_FILES = DEFAULT_SYNC_INCLUDE.filter((name) => name.includes("."));
15
23
  const TOP_LEVEL_DIRS = new Set(DEFAULT_SYNC_INCLUDE.filter((name) => !name.includes(".")));
16
24
  const SECRET_PATTERNS = [
@@ -66,40 +74,56 @@ export function regenerateSnapshotIdentity(snapshot) {
66
74
  export async function createSnapshot(profile, options = {}) {
67
75
  options.signal?.throwIfAborted();
68
76
  const include = effectiveInclude(options);
69
- const excluded = compileSyncExclude(options.exclude);
70
- const syncSessions = include.includes("sessions") && !excluded("sessions");
77
+ const policy = { ...options, include };
78
+ const excluded = compileSyncPolicyExclude(policy);
79
+ const syncSessions = syncSessionsSelected(policy);
71
80
  const needsSessionConfig = syncSessions || !excluded("settings.json");
72
- const sessionDir = options.sessionDir ?? (needsSessionConfig ? await configuredSessionDir() : undefined);
81
+ const sessionDir = options.scope === "agent-directory"
82
+ ? options.sessionDir
83
+ : (options.sessionDir ?? (needsSessionConfig ? await configuredSessionDir(options) : undefined));
73
84
  options.signal?.throwIfAborted();
74
- const files = await collectFiles(agentDir(), {
75
- include,
76
- exclude: options.exclude,
77
- sessionDir,
78
- signal: options.signal,
79
- }, excluded);
85
+ const collectionOptions = { ...policy, sessionDir };
86
+ const collected = options.scope === "agent-directory" ? await collectAgentDirectory(agentDir(), collectionOptions) : undefined;
87
+ const files = collected?.files ?? (await collectFiles(agentDir(), collectionOptions, excluded));
80
88
  options.signal?.throwIfAborted();
81
- return {
82
- version: options.exclude === undefined ? VERSION : 4,
89
+ const selection = selectionForSnapshot(include, options.exclude, options);
90
+ const snapshot = {
91
+ version: selection.version === 4
92
+ ? IGNORE_SNAPSHOT_VERSION
93
+ : options.scope === "agent-directory"
94
+ ? 5
95
+ : options.exclude === undefined
96
+ ? VERSION
97
+ : 4,
83
98
  id: snapshotId(),
84
99
  createdAt: new Date().toISOString(),
85
100
  machine: os.hostname(),
86
101
  profile,
87
- syncSessions,
88
- selection: selectionForSnapshot(include, options.exclude),
102
+ syncSessions: selection.version === 4 ? files.some((file) => isSessionPath(file.path)) : syncSessions,
103
+ selection,
89
104
  files,
90
105
  };
106
+ if (collected)
107
+ scanInventories.set(snapshot, collected.inventory);
108
+ return snapshot;
91
109
  }
92
110
  function effectiveInclude(options) {
93
111
  if (options.include)
94
112
  return options.include;
113
+ if (options.scope === "agent-directory")
114
+ return [];
95
115
  return [
96
116
  ...normalizeSyncFiles(options.syncFiles),
97
117
  ...normalizeExtraFiles(options.extraFiles),
98
118
  ...(options.syncSessions ? ["sessions"] : []),
99
119
  ];
100
120
  }
101
- export async function collectFiles(root, options = {}, excluded = compileSyncExclude(options.exclude)) {
121
+ export async function collectFiles(root, options = {}, excluded = compileSyncPolicyExclude(options)) {
122
+ if (options.scope === "agent-directory")
123
+ return (await collectAgentDirectory(root, options)).files;
102
124
  const signal = options.signal;
125
+ const guardReserved = reservedIgnoreTargetGuard(root, options);
126
+ const collection = { signal, excluded, guardReserved };
103
127
  signal?.throwIfAborted();
104
128
  const results = [];
105
129
  const entries = await fs.readdir(root, { withFileTypes: true });
@@ -111,7 +135,7 @@ export async function collectFiles(root, options = {}, excluded = compileSyncExc
111
135
  TOP_LEVEL_DIRS.has(entry.name) &&
112
136
  selectedFiles.has(entry.name) &&
113
137
  !excluded(entry.name)) {
114
- await collectDirectory(results, root, entry.name, { signal, excluded });
138
+ await collectDirectory(results, root, entry.name, collection);
115
139
  }
116
140
  }
117
141
  for (const fileName of TOP_LEVEL_FILES) {
@@ -119,19 +143,18 @@ export async function collectFiles(root, options = {}, excluded = compileSyncExc
119
143
  continue;
120
144
  const entry = selectTopLevelFileEntry(entries, fileName);
121
145
  if (entry)
122
- await addFile(results, root, entry.name, fileName, signal);
146
+ await addFile(results, root, entry.name, fileName, collection);
123
147
  }
124
148
  for (const relativePath of selection.custom) {
125
149
  if (!excluded(relativePath))
126
- await collectIncludedPath(results, root, relativePath, signal, excluded);
150
+ await collectIncludedPath(results, root, relativePath, collection);
127
151
  }
128
152
  if (selection.sessions && !excluded("sessions")) {
129
153
  try {
130
154
  await collectDirectory(results, sessionStorageRoot(root, options.sessionDir), "", {
155
+ ...collection,
131
156
  sessionsOnly: true,
132
- excluded,
133
157
  virtualPrefix: "sessions",
134
- signal,
135
158
  });
136
159
  }
137
160
  catch (error) {
@@ -142,16 +165,237 @@ export async function collectFiles(root, options = {}, excluded = compileSyncExc
142
165
  signal?.throwIfAborted();
143
166
  return results.sort((left, right) => left.path.localeCompare(right.path));
144
167
  }
145
- async function collectIncludedPath(results, root, relativePath, signal, excluded) {
168
+ function sameScannedPath(left, right) {
169
+ return (left.dev === right.dev &&
170
+ left.ino === right.ino &&
171
+ left.mode === right.mode &&
172
+ left.nlink === right.nlink &&
173
+ left.size === right.size &&
174
+ left.mtimeMs === right.mtimeMs &&
175
+ left.ctimeMs === right.ctimeMs);
176
+ }
177
+ function changedScan() {
178
+ throw new Error("Agent directory changed or has an unsafe filesystem layout; no snapshot was collected.");
179
+ }
180
+ async function identify(absolute, canonical, signal) {
181
+ signal?.throwIfAborted();
182
+ const stat = await fs.lstat(absolute);
183
+ if (stat.isSymbolicLink() || (await fs.realpath(absolute)) !== canonical)
184
+ changedScan();
185
+ signal?.throwIfAborted();
186
+ return { absolute, canonical, stat };
187
+ }
188
+ async function recheck({ absolute, canonical, stat }, signal) {
189
+ if (!sameScannedPath((await identify(absolute, canonical, signal)).stat, stat))
190
+ changedScan();
191
+ }
192
+ async function readScannedFile(candidate, signal) {
193
+ await recheck(candidate, signal);
194
+ const handle = await fs.open(candidate.absolute, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
195
+ try {
196
+ if (!sameScannedPath(await handle.stat(), candidate.stat))
197
+ changedScan();
198
+ await recheck(candidate, signal);
199
+ const content = Buffer.alloc(candidate.stat.size);
200
+ for (let offset = 0; offset < content.length;) {
201
+ signal?.throwIfAborted();
202
+ const { bytesRead } = await handle.read(content, offset, content.length - offset, offset);
203
+ if (bytesRead === 0)
204
+ changedScan();
205
+ offset += bytesRead;
206
+ }
207
+ if (!sameScannedPath(await handle.stat(), candidate.stat))
208
+ changedScan();
209
+ return content;
210
+ }
211
+ finally {
212
+ await handle.close();
213
+ }
214
+ }
215
+ export async function agentDirectoryConfiguredSessionDir(signal, root = agentDir(), options = {}) {
216
+ const content = await readAgentDirectorySettings(signal, root, options);
217
+ return content === undefined ? undefined : agentDirectorySessionDirFromSettings(content);
218
+ }
219
+ export async function readAgentDirectorySettings(signal, root = agentDir(), options = {}) {
220
+ const guardReserved = reservedIgnoreTargetGuard(root, options);
221
+ if (guardReserved)
222
+ await guardReserved(path.join(root, "settings.json"));
223
+ const absolute = path.resolve(root);
224
+ const canonical = path.join(await fs.realpath(path.dirname(absolute)), path.basename(absolute));
225
+ await identify(absolute, canonical, signal);
226
+ let settings;
227
+ try {
228
+ settings = await identify(path.join(absolute, "settings.json"), path.join(canonical, "settings.json"), signal);
229
+ }
230
+ catch (error) {
231
+ if (error.code === "ENOENT")
232
+ return undefined;
233
+ throw error;
234
+ }
235
+ if (!settings.stat.isFile() || settings.stat.nlink !== 1)
236
+ changedScan();
237
+ assertAgentDirectorySettingsSize(settings.stat.size);
238
+ const content = await readScannedFile(settings, signal);
239
+ await recheck(settings, signal);
240
+ return content;
241
+ }
242
+ export function agentDirectorySessionDirFromSettings(content) {
243
+ assertAgentDirectorySettingsSize(content.length);
244
+ let value;
245
+ try {
246
+ value = JSON.parse(content.toString("utf8").replace(/^\uFEFF/u, ""))
247
+ ?.sessionDir;
248
+ }
249
+ catch {
250
+ throw new Error("Pi settings.json cannot be parsed; repair the file before syncing.");
251
+ }
252
+ if (value !== undefined && typeof value !== "string")
253
+ throw new Error("Pi sessionDir must be a string.");
254
+ return value ? expandSessionDir(value) : undefined;
255
+ }
256
+ export async function scanAgentDirectoryInventory(root, options, pendingStateEntry) {
257
+ return (await collectAgentDirectory(root, options, false, pendingStateEntry)).inventory;
258
+ }
259
+ async function collectAgentDirectory(root, options, readContents = true, pendingStateEntry) {
260
+ const signal = options.signal;
261
+ const excluded = compileSyncPolicyExclude(options);
262
+ const canTraverse = compileSyncPolicyTraversal(options);
263
+ const sessionDir = options.sessionDir ?? (await agentDirectoryConfiguredSessionDir(signal, root, options));
264
+ const isPhysicalSessionPath = agentDirectoryPhysicalSessionPath(root, sessionDir, options.ignorePolicy, options.reservedIgnoreNames);
265
+ const sessionRoot = agentDirectorySessionRoot(root, sessionDir, options.ignorePolicy, options.reservedIgnoreNames);
266
+ const directories = [];
267
+ const candidates = [];
268
+ const entries = new Map();
269
+ const routingDirectories = new Set();
270
+ let bytes = 0;
271
+ async function walk(directory, prefix, sessions) {
272
+ if (!directory.stat.isDirectory())
273
+ changedScan();
274
+ directories.push(directory);
275
+ const children = [];
276
+ for await (const entry of await fs.opendir(directory.absolute)) {
277
+ signal?.throwIfAborted();
278
+ const absolute = path.join(directory.absolute, entry.name);
279
+ entries.set(absolute, "unreviewed");
280
+ const allowance = pendingStateEntry !== undefined && entries.has(pendingStateEntry) ? 1 : 0;
281
+ if (entries.size > MAX_AGENT_DIRECTORY_ENTRIES + allowance)
282
+ throw new Error("Agent directory exceeds the scan entry bound.");
283
+ children.push(entry);
284
+ }
285
+ await recheck(directory, signal);
286
+ for (const entry of children) {
287
+ signal?.throwIfAborted();
288
+ const snapshotPath = posixJoin(prefix, entry.name);
289
+ if (!sessions && (/^sessions(?:\/|$)/iu.test(snapshotPath) || isPhysicalSessionPath(snapshotPath)))
290
+ continue;
291
+ if (entry.isDirectory() ? !canTraverse(snapshotPath) : !entry.isFile() || excluded(snapshotPath))
292
+ continue;
293
+ if (!entry.isDirectory() && sessions && !isSessionFilePath(snapshotPath))
294
+ continue;
295
+ const candidate = await identify(path.join(directory.absolute, entry.name), path.join(directory.canonical, entry.name), signal);
296
+ if (entry.isDirectory()) {
297
+ if (!excluded(snapshotPath, true))
298
+ entries.set(candidate.absolute, "directory");
299
+ await walk(candidate, snapshotPath, sessions);
300
+ }
301
+ else {
302
+ if (!candidate.stat.isFile() || candidate.stat.nlink !== 1)
303
+ changedScan();
304
+ if (snapshotPath.toLowerCase() === "settings.json")
305
+ assertAgentDirectorySettingsSize(candidate.stat.size);
306
+ bytes += candidate.stat.size;
307
+ if (bytes > MAX_AGENT_DIRECTORY_BYTES)
308
+ throw new Error("Agent directory exceeds the 64 MiB scan byte bound.");
309
+ if (candidates.length >= MAX_AGENT_DIRECTORY_FILES)
310
+ throw new Error("Agent directory exceeds the scan file bound.");
311
+ entries.set(candidate.absolute, "file");
312
+ candidates.push({ ...candidate, snapshotPath });
313
+ }
314
+ }
315
+ await recheck(directory, signal);
316
+ }
317
+ const absoluteRoot = path.resolve(root);
318
+ const canonicalRoot = path.join(await fs.realpath(path.dirname(absoluteRoot)), path.basename(absoluteRoot));
319
+ const selectedSessions = syncSessionsSelected(options);
320
+ async function identifySessionRoot(routing) {
321
+ if (!sessionDir && !selectedSessions)
322
+ return undefined;
323
+ let absolute = agentDirectoryAnchor(absoluteRoot, sessionRoot);
324
+ const parts = path.relative(absolute, sessionRoot).split(path.sep);
325
+ let canonical = await fs.realpath(absolute);
326
+ let directory;
327
+ try {
328
+ for (const part of parts) {
329
+ absolute = path.join(absolute, part);
330
+ canonical = path.join(canonical, part);
331
+ directory = await identify(absolute, canonical, signal);
332
+ if (!directory.stat.isDirectory())
333
+ changedScan();
334
+ routing?.add(absolute);
335
+ }
336
+ }
337
+ catch (error) {
338
+ if (error.code === "ENOENT")
339
+ return undefined;
340
+ throw error;
341
+ }
342
+ return directory;
343
+ }
344
+ const sessionDirectory = await identifySessionRoot(routingDirectories);
345
+ await walk(await identify(absoluteRoot, canonicalRoot, signal), "", false);
346
+ if (selectedSessions && sessionDirectory)
347
+ await walk(sessionDirectory, "sessions", true);
348
+ assertAgentDirectoryPathLayout(candidates.map((candidate) => candidate.snapshotPath));
349
+ const results = [];
350
+ if (readContents) {
351
+ for (const candidate of candidates) {
352
+ const content = await readScannedFile(candidate, signal);
353
+ results.push({
354
+ path: candidate.snapshotPath,
355
+ contentBase64: content.toString("base64"),
356
+ sha256: sha256(content),
357
+ });
358
+ }
359
+ }
360
+ for (const directory of directories)
361
+ await recheck(directory, signal);
362
+ if (options.sessionDir === undefined &&
363
+ (await agentDirectoryConfiguredSessionDir(signal, root, options)) !== sessionDir)
364
+ changedScan();
365
+ const currentSessionDirectory = await identifySessionRoot();
366
+ if (Boolean(sessionDirectory) !== Boolean(currentSessionDirectory) ||
367
+ (sessionDirectory &&
368
+ currentSessionDirectory &&
369
+ (sessionDirectory.stat.dev !== currentSessionDirectory.stat.dev ||
370
+ sessionDirectory.stat.ino !== currentSessionDirectory.stat.ino)))
371
+ changedScan();
372
+ for (const candidate of candidates)
373
+ await recheck(candidate, signal);
374
+ signal?.throwIfAborted();
375
+ return {
376
+ files: results.sort((left, right) => left.path.localeCompare(right.path)),
377
+ inventory: {
378
+ root: absoluteRoot,
379
+ sessionRoot,
380
+ scanSessions: selectedSessions,
381
+ entries,
382
+ fileSizes: new Map(candidates.map(({ absolute, stat }) => [absolute, stat.size])),
383
+ walkedDirectories: new Set(directories.map(({ absolute }) => absolute)),
384
+ routingDirectories,
385
+ },
386
+ };
387
+ }
388
+ async function collectIncludedPath(results, root, relativePath, options) {
389
+ const { signal } = options;
146
390
  signal?.throwIfAborted();
147
391
  const absolutePath = safeJoin(root, relativePath);
148
392
  try {
149
393
  const stat = await fs.lstat(absolutePath);
150
394
  signal?.throwIfAborted();
151
395
  if (stat.isFile())
152
- await addFile(results, root, relativePath, relativePath, signal);
396
+ await addFile(results, root, relativePath, relativePath, options);
153
397
  else if (stat.isDirectory())
154
- await collectDirectory(results, root, relativePath, { signal, excluded });
398
+ await collectDirectory(results, root, relativePath, options);
155
399
  }
156
400
  catch (error) {
157
401
  if (error.code !== "ENOENT")
@@ -161,33 +405,46 @@ async function collectIncludedPath(results, root, relativePath, signal, excluded
161
405
  signal?.throwIfAborted();
162
406
  const entry = selectTopLevelFileEntry(entries, relativePath);
163
407
  if (entry)
164
- await addFile(results, root, entry.name, relativePath, signal);
408
+ await addFile(results, root, entry.name, relativePath, options);
165
409
  }
166
410
  }
167
411
  }
168
- async function collectDirectory(results, root, relativeDirectory, options = {}) {
412
+ async function collectDirectory(results, root, relativeDirectory, options) {
169
413
  options.signal?.throwIfAborted();
170
414
  const absoluteDirectory = path.join(root, relativeDirectory);
415
+ if (options.guardReserved)
416
+ await options.guardReserved(absoluteDirectory);
417
+ options.signal?.throwIfAborted();
171
418
  for (const entry of await fs.readdir(absoluteDirectory, { withFileTypes: true })) {
172
419
  options.signal?.throwIfAborted();
173
420
  const relativePath = relativeDirectory ? posixJoin(relativeDirectory, entry.name) : entry.name;
174
421
  const snapshotPath = options.virtualPrefix ? posixJoin(options.virtualPrefix, relativePath) : relativePath;
175
- if (isDeniedPath(snapshotPath) || options.excluded?.(snapshotPath))
422
+ if (isDeniedPath(snapshotPath) || options.excluded(snapshotPath))
176
423
  continue;
177
424
  if (entry.isDirectory()) {
178
425
  await collectDirectory(results, root, relativePath, options);
179
426
  }
180
427
  else if (entry.isFile() && (!options.sessionsOnly || isSessionFilePath(snapshotPath))) {
181
- await addFile(results, root, relativePath, snapshotPath, options.signal);
428
+ await addFile(results, root, relativePath, snapshotPath, options);
182
429
  }
183
430
  }
184
431
  }
185
- async function addFile(results, root, relativePath, snapshotPath = relativePath, signal) {
432
+ export async function readLegacySnapshotSource(absolutePath, guardReserved, signal) {
433
+ if (!guardReserved)
434
+ return fs.readFile(absolutePath, { signal });
435
+ signal?.throwIfAborted();
436
+ const canonical = await guardReserved(absolutePath);
437
+ const candidate = await identify(absolutePath, canonical, signal);
438
+ if (!candidate.stat.isFile() || candidate.stat.nlink !== 1)
439
+ changedScan();
440
+ return readScannedFile(candidate, signal);
441
+ }
442
+ async function addFile(results, root, relativePath, snapshotPath, { signal, guardReserved }) {
186
443
  signal?.throwIfAborted();
187
444
  if (!isSafeSnapshotPath(snapshotPath))
188
445
  return;
189
446
  const absolutePath = safeJoin(root, relativePath);
190
- const content = await fs.readFile(absolutePath, { signal });
447
+ const content = await readLegacySnapshotSource(absolutePath, guardReserved, signal);
191
448
  signal?.throwIfAborted();
192
449
  results.push({
193
450
  path: snapshotPath,
@@ -217,6 +474,10 @@ export function snapshotTarget(root, relativePath, configuredSessionDir) {
217
474
  return safeJoin(root, relativePath);
218
475
  }
219
476
  export function snapshotIncludesSessions(snapshot) {
477
+ if (snapshot.selection?.version === 3)
478
+ return syncSessionsSelected(snapshot.selection);
479
+ if (snapshot.selection?.version === 4)
480
+ return snapshot.files.some((file) => isSessionPath(file.path));
220
481
  return (snapshot.syncSessions === true ||
221
482
  (snapshotSelectionInclude(snapshot)?.includes("sessions") === true &&
222
483
  !compileSyncExclude(snapshotSelectionExclude(snapshot))("sessions")) ||
@@ -224,14 +485,30 @@ export function snapshotIncludesSessions(snapshot) {
224
485
  }
225
486
  export function filterSnapshotForConfigPolicy(snapshot, config, options = {}) {
226
487
  const include = includeFromSelectionConfig(config);
227
- const includePaths = customIncludePathsByLower(include);
228
- const exclude = config.exclude ?? (snapshot.version === 4 ? [] : undefined);
488
+ const wholeDirectory = config.scope === "agent-directory";
489
+ if (!wholeDirectory || !config.ignorePolicy)
490
+ requireLegacyTransferPolicy(snapshot);
491
+ const exclude = config.exclude ?? (snapshot.version >= 4 ? [] : undefined);
492
+ const selection = selectionForSnapshot(include, exclude, config);
493
+ const files = wholeDirectory
494
+ ? filterAgentDirectoryFiles(snapshot.files, config, options.sessionDir)
495
+ : canonicalizeSnapshotFilesForConfig(snapshot.files, config, customIncludePathsByLower(include));
229
496
  const filtered = {
230
497
  ...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),
498
+ version: selection.version === 4
499
+ ? IGNORE_SNAPSHOT_VERSION
500
+ : wholeDirectory
501
+ ? 5
502
+ : exclude === undefined
503
+ ? snapshot.version
504
+ : 4,
505
+ syncSessions: selection.version === 4
506
+ ? files.some((file) => isSessionPath(file.path))
507
+ : syncSessionsSelected(config)
508
+ ? snapshot.syncSessions
509
+ : false,
510
+ selection,
511
+ files,
235
512
  };
236
513
  if (!options.regenerateId || snapshotsMatch(snapshot, filtered))
237
514
  return filtered;
@@ -242,6 +519,21 @@ export function filterSnapshotForConfigPolicy(snapshot, config, options = {}) {
242
519
  machine: os.hostname(),
243
520
  };
244
521
  }
522
+ function filterAgentDirectoryFiles(files, config, sessionDir) {
523
+ const configured = configuredSnapshotPathMatcher(config);
524
+ const isPhysicalSessionPath = sessionDir
525
+ ? agentDirectoryPhysicalSessionPath(agentDir(), sessionDir, config.ignorePolicy, config.reservedIgnoreNames)
526
+ : undefined;
527
+ const projected = files.filter((file) => {
528
+ if (!isSafeSnapshotPath(file.path) || !configured(file.path))
529
+ return false;
530
+ if (/^sessions(?:\/|$)/iu.test(file.path))
531
+ return isSessionFilePath(file.path);
532
+ return !isPhysicalSessionPath?.(file.path);
533
+ });
534
+ assertAgentDirectoryPathLayout(projected.map((file) => file.path));
535
+ return projected.sort((left, right) => left.path.localeCompare(right.path));
536
+ }
245
537
  function canonicalizeSnapshotFilesForConfig(files, config, includePaths) {
246
538
  const configuredFiles = [];
247
539
  const extraCandidates = new Map();
@@ -274,11 +566,12 @@ function isPreferredExtraCandidate(left, right) {
274
566
  return left.originalPath.localeCompare(right.originalPath) < 0;
275
567
  }
276
568
  export function snapshotWithoutSessions(snapshot) {
569
+ requireLegacyTransferPolicy(snapshot);
277
570
  const files = snapshot.files.filter((file) => !isSessionPath(file.path));
278
571
  const include = snapshotSelectionInclude(snapshot)?.filter((item) => item !== "sessions");
279
572
  if (files.length === snapshot.files.length &&
280
573
  snapshot.syncSessions !== true &&
281
- include?.length === snapshot.selection?.include.length) {
574
+ include?.length === snapshot.selection?.include?.length) {
282
575
  return snapshot;
283
576
  }
284
577
  return {
@@ -287,7 +580,11 @@ export function snapshotWithoutSessions(snapshot) {
287
580
  createdAt: new Date().toISOString(),
288
581
  machine: os.hostname(),
289
582
  syncSessions: false,
290
- ...(include ? { selection: selectionForSnapshot(include, snapshotSelectionExclude(snapshot)) } : {}),
583
+ ...(include
584
+ ? {
585
+ selection: selectionForSnapshot(include, snapshotSelectionExclude(snapshot), snapshot.selection?.version === 3 ? snapshot.selection : undefined),
586
+ }
587
+ : {}),
291
588
  files,
292
589
  };
293
590
  }
@@ -307,11 +604,23 @@ export function scanSnapshot(snapshot) {
307
604
  }
308
605
  return findings;
309
606
  }
310
- export function mergeRemotePreservedFiles(local, remote, config) {
607
+ export function mergeRemotePreservedFiles(local, remote, config, options = {}) {
608
+ if (config.scope !== "agent-directory" || !config.ignorePolicy) {
609
+ requireLegacyTransferPolicy(local);
610
+ requireLegacyTransferPolicy(remote);
611
+ }
612
+ if (config.scope === "agent-directory")
613
+ return filterSnapshotForConfigPolicy(local, config, { ...options, regenerateId: true });
614
+ if (config.reservedIgnoreNames !== undefined) {
615
+ const names = new Set(config.reservedIgnoreNames);
616
+ const files = local.files.filter((file) => !isIgnoreControlPath(toPosix(file.path), names));
617
+ if (files.length !== local.files.length)
618
+ local = regenerateSnapshotIdentity({ ...local, files });
619
+ }
311
620
  const localPathNames = new Set(local.files.map((file) => file.path.toLowerCase()));
312
621
  const preservedPathNames = new Set();
313
622
  const configured = configuredSnapshotPathMatcher(config);
314
- const excluded = compileSyncExclude(config.exclude);
623
+ const excluded = compileSyncPolicyExclude(config);
315
624
  const preserved = remote.files.filter((file) => {
316
625
  const normalized = toPosix(file.path);
317
626
  const lower = normalized.toLowerCase();
@@ -338,8 +647,13 @@ export function mergeRemotePreservedFiles(local, remote, config) {
338
647
  };
339
648
  }
340
649
  export function mergeRemoteSessionFiles(local, remote) {
341
- const excluded = compileSyncExclude(snapshotSelectionExclude(local));
342
- if (excluded("sessions"))
650
+ requireLegacyTransferPolicy(local);
651
+ requireLegacyTransferPolicy(remote);
652
+ const directory = local.selection?.version === 3 ? local.selection : undefined;
653
+ const excluded = directory
654
+ ? compileSyncPolicyExclude(directory)
655
+ : compileSyncExclude(snapshotSelectionExclude(local));
656
+ if (directory ? !syncSessionsSelected(directory) : excluded("sessions"))
343
657
  return local;
344
658
  const remoteSessions = remote.files.filter((file) => {
345
659
  const normalized = toPosix(file.path);
@@ -356,7 +670,7 @@ export function mergeRemoteSessionFiles(local, remote) {
356
670
  syncSessions: true,
357
671
  ...(localInclude
358
672
  ? {
359
- selection: selectionForSnapshot(localInclude.includes("sessions") ? localInclude : [...localInclude, "sessions"], snapshotSelectionExclude(local)),
673
+ selection: selectionForSnapshot(localInclude.includes("sessions") ? localInclude : [...localInclude, "sessions"], snapshotSelectionExclude(local), directory),
360
674
  }
361
675
  : {}),
362
676
  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,9 @@ export interface SyncState {
7
7
  lastFileHashes: Record<string, string>;
8
8
  include?: string[];
9
9
  exclude?: string[];
10
+ scope?: "agent-directory";
11
+ reinclude?: string[];
12
+ ignorePolicyKey?: string;
10
13
  localFields?: string[];
11
14
  lastObservedSnapshot?: string;
12
15
  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>;