@narumitw/pi-sync-daemon 0.7.0 → 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 (74) hide show
  1. package/CHANGELOG.md +11 -0
  2. package/README.md +16 -2
  3. package/dist/consent.js +21 -6
  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 +30 -9
  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/settings/config-file.d.ts +9 -2
  24. package/dist/engine/settings/config-file.js +124 -28
  25. package/dist/engine/settings/config.d.ts +3 -0
  26. package/dist/engine/settings/config.js +93 -7
  27. package/dist/engine/settings/settings-management.d.ts +2 -2
  28. package/dist/engine/settings/settings-management.js +16 -8
  29. package/dist/engine/settings/settings-types.d.ts +23 -2
  30. package/dist/engine/settings/settings-validation.js +23 -5
  31. package/dist/engine/snapshot/session-paths.d.ts +1 -1
  32. package/dist/engine/snapshot/session-paths.js +36 -13
  33. package/dist/engine/snapshot/snapshot-apply.d.ts +3 -3
  34. package/dist/engine/snapshot/snapshot-apply.js +23 -4
  35. package/dist/engine/snapshot/snapshot-codec.d.ts +1 -1
  36. package/dist/engine/snapshot/snapshot-codec.js +14 -5
  37. package/dist/engine/snapshot/snapshot-exclude-safety.d.ts +4 -2
  38. package/dist/engine/snapshot/snapshot-exclude-safety.js +76 -19
  39. package/dist/engine/snapshot/snapshot-transaction-images.d.ts +3 -1
  40. package/dist/engine/snapshot/snapshot-transaction-images.js +33 -3
  41. package/dist/engine/snapshot/snapshot-transaction-policy.d.ts +24 -1
  42. package/dist/engine/snapshot/snapshot-transaction-policy.js +106 -2
  43. package/dist/engine/snapshot/snapshot-transaction-verification.d.ts +7 -0
  44. package/dist/engine/snapshot/snapshot-transaction-verification.js +78 -0
  45. package/dist/engine/snapshot/snapshot-transaction.d.ts +1 -12
  46. package/dist/engine/snapshot/snapshot-transaction.js +86 -108
  47. package/dist/engine/snapshot/snapshot-types.d.ts +23 -1
  48. package/dist/engine/snapshot/snapshot-types.js +9 -1
  49. package/dist/engine/snapshot/snapshot.d.ts +6 -4
  50. package/dist/engine/snapshot/snapshot.js +91 -34
  51. package/dist/engine/state/state-types.d.ts +1 -0
  52. package/dist/engine/sync/continuous-sync.js +18 -3
  53. package/dist/engine/sync/continuous-watch.js +4 -1
  54. package/dist/engine/sync/initialization.js +3 -2
  55. package/dist/engine/sync/local-fields.d.ts +3 -1
  56. package/dist/engine/sync/local-fields.js +62 -1
  57. package/dist/engine/sync/merge-apply.js +35 -7
  58. package/dist/engine/sync/merge-journal.d.ts +18 -4
  59. package/dist/engine/sync/merge-journal.js +115 -8
  60. package/dist/engine/sync/merged-sync.d.ts +1 -1
  61. package/dist/engine/sync/merged-sync.js +103 -50
  62. package/dist/engine/sync/remote-snapshot.d.ts +9 -2
  63. package/dist/engine/sync/remote-snapshot.js +56 -17
  64. package/dist/engine/sync/sync-inspection.js +7 -5
  65. package/dist/engine/sync/sync-mutations.d.ts +2 -1
  66. package/dist/engine/sync/sync-mutations.js +110 -47
  67. package/dist/engine/sync/sync-policy.d.ts +24 -8
  68. package/dist/engine/sync/sync-policy.js +127 -16
  69. package/dist/engine/sync/sync-queries.js +8 -1
  70. package/dist/engine/sync/sync-state.d.ts +2 -2
  71. package/dist/engine/sync/sync-state.js +20 -2
  72. package/dist/engine-service.js +24 -2
  73. package/docs/architecture.md +22 -0
  74. package/package.json +2 -1
@@ -6,12 +6,13 @@ import path from "node:path";
6
6
  import { isDeniedPath, posixJoin, safeJoin, toPosix } from "../paths.js";
7
7
  import { agentDir, configuredSessionDir, expandSessionDir } from "./session-paths.js";
8
8
  import { assertAgentDirectorySettingsSize, MAX_AGENT_DIRECTORY_BYTES } from "./snapshot-bounds.js";
9
- import { agentDirectoryAnchor, agentDirectoryPhysicalSessionPath, agentDirectorySessionRoot, } from "./snapshot-exclude-safety.js";
9
+ import { agentDirectoryAnchor, agentDirectoryPhysicalSessionPath, agentDirectorySessionRoot, reservedIgnoreTargetGuard, } from "./snapshot-exclude-safety.js";
10
10
  import { sessionStorageRoot } from "./snapshot-paths.js";
11
11
  export { isDeniedPath } from "../paths.js";
12
12
  export { sessionStorageRoot } from "./snapshot-paths.js";
13
13
  import { compileSyncExclude } from "../sync/exclude-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";
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";
15
16
  export { canonicalSnapshotPathForConfig, isConfiguredSnapshotPath } from "../sync/sync-policy.js";
16
17
  const VERSION = 1;
17
18
  const scanInventories = new WeakMap();
@@ -79,20 +80,27 @@ export async function createSnapshot(profile, options = {}) {
79
80
  const needsSessionConfig = syncSessions || !excluded("settings.json");
80
81
  const sessionDir = options.scope === "agent-directory"
81
82
  ? options.sessionDir
82
- : (options.sessionDir ?? (needsSessionConfig ? await configuredSessionDir() : undefined));
83
+ : (options.sessionDir ?? (needsSessionConfig ? await configuredSessionDir(options) : undefined));
83
84
  options.signal?.throwIfAborted();
84
85
  const collectionOptions = { ...policy, sessionDir };
85
86
  const collected = options.scope === "agent-directory" ? await collectAgentDirectory(agentDir(), collectionOptions) : undefined;
86
87
  const files = collected?.files ?? (await collectFiles(agentDir(), collectionOptions, excluded));
87
88
  options.signal?.throwIfAborted();
89
+ const selection = selectionForSnapshot(include, options.exclude, options);
88
90
  const snapshot = {
89
- version: options.scope === "agent-directory" ? 5 : options.exclude === undefined ? VERSION : 4,
91
+ version: selection.version === 4
92
+ ? IGNORE_SNAPSHOT_VERSION
93
+ : options.scope === "agent-directory"
94
+ ? 5
95
+ : options.exclude === undefined
96
+ ? VERSION
97
+ : 4,
90
98
  id: snapshotId(),
91
99
  createdAt: new Date().toISOString(),
92
100
  machine: os.hostname(),
93
101
  profile,
94
- syncSessions,
95
- selection: selectionForSnapshot(include, options.exclude, options),
102
+ syncSessions: selection.version === 4 ? files.some((file) => isSessionPath(file.path)) : syncSessions,
103
+ selection,
96
104
  files,
97
105
  };
98
106
  if (collected)
@@ -110,10 +118,12 @@ function effectiveInclude(options) {
110
118
  ...(options.syncSessions ? ["sessions"] : []),
111
119
  ];
112
120
  }
113
- export async function collectFiles(root, options = {}, excluded = compileSyncExclude(options.exclude)) {
121
+ export async function collectFiles(root, options = {}, excluded = compileSyncPolicyExclude(options)) {
114
122
  if (options.scope === "agent-directory")
115
123
  return (await collectAgentDirectory(root, options)).files;
116
124
  const signal = options.signal;
125
+ const guardReserved = reservedIgnoreTargetGuard(root, options);
126
+ const collection = { signal, excluded, guardReserved };
117
127
  signal?.throwIfAborted();
118
128
  const results = [];
119
129
  const entries = await fs.readdir(root, { withFileTypes: true });
@@ -125,7 +135,7 @@ export async function collectFiles(root, options = {}, excluded = compileSyncExc
125
135
  TOP_LEVEL_DIRS.has(entry.name) &&
126
136
  selectedFiles.has(entry.name) &&
127
137
  !excluded(entry.name)) {
128
- await collectDirectory(results, root, entry.name, { signal, excluded });
138
+ await collectDirectory(results, root, entry.name, collection);
129
139
  }
130
140
  }
131
141
  for (const fileName of TOP_LEVEL_FILES) {
@@ -133,19 +143,18 @@ export async function collectFiles(root, options = {}, excluded = compileSyncExc
133
143
  continue;
134
144
  const entry = selectTopLevelFileEntry(entries, fileName);
135
145
  if (entry)
136
- await addFile(results, root, entry.name, fileName, signal);
146
+ await addFile(results, root, entry.name, fileName, collection);
137
147
  }
138
148
  for (const relativePath of selection.custom) {
139
149
  if (!excluded(relativePath))
140
- await collectIncludedPath(results, root, relativePath, signal, excluded);
150
+ await collectIncludedPath(results, root, relativePath, collection);
141
151
  }
142
152
  if (selection.sessions && !excluded("sessions")) {
143
153
  try {
144
154
  await collectDirectory(results, sessionStorageRoot(root, options.sessionDir), "", {
155
+ ...collection,
145
156
  sessionsOnly: true,
146
- excluded,
147
157
  virtualPrefix: "sessions",
148
- signal,
149
158
  });
150
159
  }
151
160
  catch (error) {
@@ -203,11 +212,14 @@ async function readScannedFile(candidate, signal) {
203
212
  await handle.close();
204
213
  }
205
214
  }
206
- export async function agentDirectoryConfiguredSessionDir(signal, root = agentDir()) {
207
- const content = await readAgentDirectorySettings(signal, root);
215
+ export async function agentDirectoryConfiguredSessionDir(signal, root = agentDir(), options = {}) {
216
+ const content = await readAgentDirectorySettings(signal, root, options);
208
217
  return content === undefined ? undefined : agentDirectorySessionDirFromSettings(content);
209
218
  }
210
- export async function readAgentDirectorySettings(signal, root = agentDir()) {
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"));
211
223
  const absolute = path.resolve(root);
212
224
  const canonical = path.join(await fs.realpath(path.dirname(absolute)), path.basename(absolute));
213
225
  await identify(absolute, canonical, signal);
@@ -248,9 +260,9 @@ async function collectAgentDirectory(root, options, readContents = true, pending
248
260
  const signal = options.signal;
249
261
  const excluded = compileSyncPolicyExclude(options);
250
262
  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);
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);
254
266
  const directories = [];
255
267
  const candidates = [];
256
268
  const entries = new Map();
@@ -282,7 +294,7 @@ async function collectAgentDirectory(root, options, readContents = true, pending
282
294
  continue;
283
295
  const candidate = await identify(path.join(directory.absolute, entry.name), path.join(directory.canonical, entry.name), signal);
284
296
  if (entry.isDirectory()) {
285
- if (!excluded(snapshotPath))
297
+ if (!excluded(snapshotPath, true))
286
298
  entries.set(candidate.absolute, "directory");
287
299
  await walk(candidate, snapshotPath, sessions);
288
300
  }
@@ -347,7 +359,8 @@ async function collectAgentDirectory(root, options, readContents = true, pending
347
359
  }
348
360
  for (const directory of directories)
349
361
  await recheck(directory, signal);
350
- if (options.sessionDir === undefined && (await agentDirectoryConfiguredSessionDir(signal, root)) !== sessionDir)
362
+ if (options.sessionDir === undefined &&
363
+ (await agentDirectoryConfiguredSessionDir(signal, root, options)) !== sessionDir)
351
364
  changedScan();
352
365
  const currentSessionDirectory = await identifySessionRoot();
353
366
  if (Boolean(sessionDirectory) !== Boolean(currentSessionDirectory) ||
@@ -372,16 +385,17 @@ async function collectAgentDirectory(root, options, readContents = true, pending
372
385
  },
373
386
  };
374
387
  }
375
- async function collectIncludedPath(results, root, relativePath, signal, excluded) {
388
+ async function collectIncludedPath(results, root, relativePath, options) {
389
+ const { signal } = options;
376
390
  signal?.throwIfAborted();
377
391
  const absolutePath = safeJoin(root, relativePath);
378
392
  try {
379
393
  const stat = await fs.lstat(absolutePath);
380
394
  signal?.throwIfAborted();
381
395
  if (stat.isFile())
382
- await addFile(results, root, relativePath, relativePath, signal);
396
+ await addFile(results, root, relativePath, relativePath, options);
383
397
  else if (stat.isDirectory())
384
- await collectDirectory(results, root, relativePath, { signal, excluded });
398
+ await collectDirectory(results, root, relativePath, options);
385
399
  }
386
400
  catch (error) {
387
401
  if (error.code !== "ENOENT")
@@ -391,33 +405,46 @@ async function collectIncludedPath(results, root, relativePath, signal, excluded
391
405
  signal?.throwIfAborted();
392
406
  const entry = selectTopLevelFileEntry(entries, relativePath);
393
407
  if (entry)
394
- await addFile(results, root, entry.name, relativePath, signal);
408
+ await addFile(results, root, entry.name, relativePath, options);
395
409
  }
396
410
  }
397
411
  }
398
- async function collectDirectory(results, root, relativeDirectory, options = {}) {
412
+ async function collectDirectory(results, root, relativeDirectory, options) {
399
413
  options.signal?.throwIfAborted();
400
414
  const absoluteDirectory = path.join(root, relativeDirectory);
415
+ if (options.guardReserved)
416
+ await options.guardReserved(absoluteDirectory);
417
+ options.signal?.throwIfAborted();
401
418
  for (const entry of await fs.readdir(absoluteDirectory, { withFileTypes: true })) {
402
419
  options.signal?.throwIfAborted();
403
420
  const relativePath = relativeDirectory ? posixJoin(relativeDirectory, entry.name) : entry.name;
404
421
  const snapshotPath = options.virtualPrefix ? posixJoin(options.virtualPrefix, relativePath) : relativePath;
405
- if (isDeniedPath(snapshotPath) || options.excluded?.(snapshotPath))
422
+ if (isDeniedPath(snapshotPath) || options.excluded(snapshotPath))
406
423
  continue;
407
424
  if (entry.isDirectory()) {
408
425
  await collectDirectory(results, root, relativePath, options);
409
426
  }
410
427
  else if (entry.isFile() && (!options.sessionsOnly || isSessionFilePath(snapshotPath))) {
411
- await addFile(results, root, relativePath, snapshotPath, options.signal);
428
+ await addFile(results, root, relativePath, snapshotPath, options);
412
429
  }
413
430
  }
414
431
  }
415
- 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 }) {
416
443
  signal?.throwIfAborted();
417
444
  if (!isSafeSnapshotPath(snapshotPath))
418
445
  return;
419
446
  const absolutePath = safeJoin(root, relativePath);
420
- const content = await fs.readFile(absolutePath, { signal });
447
+ const content = await readLegacySnapshotSource(absolutePath, guardReserved, signal);
421
448
  signal?.throwIfAborted();
422
449
  results.push({
423
450
  path: snapshotPath,
@@ -449,6 +476,8 @@ export function snapshotTarget(root, relativePath, configuredSessionDir) {
449
476
  export function snapshotIncludesSessions(snapshot) {
450
477
  if (snapshot.selection?.version === 3)
451
478
  return syncSessionsSelected(snapshot.selection);
479
+ if (snapshot.selection?.version === 4)
480
+ return snapshot.files.some((file) => isSessionPath(file.path));
452
481
  return (snapshot.syncSessions === true ||
453
482
  (snapshotSelectionInclude(snapshot)?.includes("sessions") === true &&
454
483
  !compileSyncExclude(snapshotSelectionExclude(snapshot))("sessions")) ||
@@ -457,15 +486,28 @@ export function snapshotIncludesSessions(snapshot) {
457
486
  export function filterSnapshotForConfigPolicy(snapshot, config, options = {}) {
458
487
  const include = includeFromSelectionConfig(config);
459
488
  const wholeDirectory = config.scope === "agent-directory";
489
+ if (!wholeDirectory || !config.ignorePolicy)
490
+ requireLegacyTransferPolicy(snapshot);
460
491
  const exclude = config.exclude ?? (snapshot.version >= 4 ? [] : undefined);
492
+ const selection = selectionForSnapshot(include, exclude, config);
461
493
  const files = wholeDirectory
462
494
  ? filterAgentDirectoryFiles(snapshot.files, config, options.sessionDir)
463
495
  : canonicalizeSnapshotFilesForConfig(snapshot.files, config, customIncludePathsByLower(include));
464
496
  const filtered = {
465
497
  ...snapshot,
466
- version: wholeDirectory ? 5 : exclude === undefined ? snapshot.version : 4,
467
- syncSessions: syncSessionsSelected(config) ? snapshot.syncSessions : false,
468
- selection: selectionForSnapshot(include, exclude, config),
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,
469
511
  files,
470
512
  };
471
513
  if (!options.regenerateId || snapshotsMatch(snapshot, filtered))
@@ -479,7 +521,9 @@ export function filterSnapshotForConfigPolicy(snapshot, config, options = {}) {
479
521
  }
480
522
  function filterAgentDirectoryFiles(files, config, sessionDir) {
481
523
  const configured = configuredSnapshotPathMatcher(config);
482
- const isPhysicalSessionPath = sessionDir ? agentDirectoryPhysicalSessionPath(agentDir(), sessionDir) : undefined;
524
+ const isPhysicalSessionPath = sessionDir
525
+ ? agentDirectoryPhysicalSessionPath(agentDir(), sessionDir, config.ignorePolicy, config.reservedIgnoreNames)
526
+ : undefined;
483
527
  const projected = files.filter((file) => {
484
528
  if (!isSafeSnapshotPath(file.path) || !configured(file.path))
485
529
  return false;
@@ -522,11 +566,12 @@ function isPreferredExtraCandidate(left, right) {
522
566
  return left.originalPath.localeCompare(right.originalPath) < 0;
523
567
  }
524
568
  export function snapshotWithoutSessions(snapshot) {
569
+ requireLegacyTransferPolicy(snapshot);
525
570
  const files = snapshot.files.filter((file) => !isSessionPath(file.path));
526
571
  const include = snapshotSelectionInclude(snapshot)?.filter((item) => item !== "sessions");
527
572
  if (files.length === snapshot.files.length &&
528
573
  snapshot.syncSessions !== true &&
529
- include?.length === snapshot.selection?.include.length) {
574
+ include?.length === snapshot.selection?.include?.length) {
530
575
  return snapshot;
531
576
  }
532
577
  return {
@@ -560,8 +605,18 @@ export function scanSnapshot(snapshot) {
560
605
  return findings;
561
606
  }
562
607
  export function mergeRemotePreservedFiles(local, remote, config, options = {}) {
608
+ if (config.scope !== "agent-directory" || !config.ignorePolicy) {
609
+ requireLegacyTransferPolicy(local);
610
+ requireLegacyTransferPolicy(remote);
611
+ }
563
612
  if (config.scope === "agent-directory")
564
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
+ }
565
620
  const localPathNames = new Set(local.files.map((file) => file.path.toLowerCase()));
566
621
  const preservedPathNames = new Set();
567
622
  const configured = configuredSnapshotPathMatcher(config);
@@ -592,6 +647,8 @@ export function mergeRemotePreservedFiles(local, remote, config, options = {}) {
592
647
  };
593
648
  }
594
649
  export function mergeRemoteSessionFiles(local, remote) {
650
+ requireLegacyTransferPolicy(local);
651
+ requireLegacyTransferPolicy(remote);
595
652
  const directory = local.selection?.version === 3 ? local.selection : undefined;
596
653
  const excluded = directory
597
654
  ? compileSyncPolicyExclude(directory)
@@ -9,6 +9,7 @@ export interface SyncState {
9
9
  exclude?: string[];
10
10
  scope?: "agent-directory";
11
11
  reinclude?: string[];
12
+ ignorePolicyKey?: string;
12
13
  localFields?: string[];
13
14
  lastObservedSnapshot?: string;
14
15
  lastObservedRevision?: string;
@@ -1,5 +1,6 @@
1
1
  import { loadConfigForCheck, syncCheckConfigFingerprint } from "../settings/config.js";
2
2
  import { resolvedSnapshotOptionsForContext } from "../snapshot/session-paths.js";
3
+ import { ignorePolicyValidator } from "../snapshot/snapshot-transaction-policy.js";
3
4
  import { withLock } from "../state/lock.js";
4
5
  import { withStateDirectoryAccess } from "../state/state-directory.js";
5
6
  import { readStateForConfig } from "../state/sync-state-store.js";
@@ -10,7 +11,7 @@ import { acquireContinuousLease } from "./continuous-lease.js";
10
11
  import { normalizeContinuousClock, readContinuousRecord, reserveContinuousRequest, updateContinuousRecord, } from "./continuous-record.js";
11
12
  import { continuousBinding, hashContinuous } from "./continuous-storage.js";
12
13
  import { watchContinuous } from "./continuous-watch.js";
13
- import { readMergeJournal } from "./merge-journal.js";
14
+ import { assertMergeJournalPolicy, readMergeJournal } from "./merge-journal.js";
14
15
  import { createStartupTimings } from "./startup-timings.js";
15
16
  import { captureMutationOwner } from "./sync-local.js";
16
17
  import { fileHashMap } from "./sync-state.js";
@@ -242,7 +243,12 @@ export function createContinuousSync(loaders, clock = systemClock, publish) {
242
243
  await updateContinuousRecord(binding, lease, (current) => normalizeContinuousClock(current, now));
243
244
  validate();
244
245
  }
245
- const configuration = hashContinuous([{ ...config, showStatus: undefined, debug: undefined }, ctx.model]);
246
+ const configuration = hashContinuous([
247
+ config.ignorePolicy
248
+ ? syncCheckConfigFingerprint(config)
249
+ : { ...config, showStatus: undefined, debug: undefined },
250
+ ctx.model,
251
+ ]);
246
252
  const controlChanged = record.configuration !== configuration;
247
253
  if (controlChanged || explicitRetry) {
248
254
  record.next = 0;
@@ -269,7 +275,9 @@ export function createContinuousSync(loaders, clock = systemClock, publish) {
269
275
  // transfer adopt authorization that changed after this cycle's inspection.
270
276
  const validateCycle = (latest) => {
271
277
  validate();
272
- if ((latest && syncCheckConfigFingerprint(latest) !== expectedConfig) ||
278
+ if ((latest &&
279
+ (syncCheckConfigFingerprint(latest) !== expectedConfig ||
280
+ (ctx.backgroundAuthorized && !ctx.backgroundAuthorized(latest)))) ||
273
281
  hashContinuous(ctx.model) !== expectedModel)
274
282
  activeCycle.abort(new DOMException("Continuous authorization changed", "AbortError"));
275
283
  activeCycle.signal.throwIfAborted();
@@ -373,6 +381,8 @@ export function createContinuousSync(loaders, clock = systemClock, publish) {
373
381
  // A newly pending journal may prove an uncertain commit. It is never authority to republish.
374
382
  const pending = await guardedLock("continuous-journal", () => readMergeJournal(config));
375
383
  validate();
384
+ if (pending)
385
+ assertMergeJournalPolicy(pending, config);
376
386
  if (!force &&
377
387
  !pending &&
378
388
  current.phase === "blocked" &&
@@ -385,6 +395,9 @@ export function createContinuousSync(loaders, clock = systemClock, publish) {
385
395
  validate();
386
396
  const snapshotOptions = await resolvedSnapshotOptionsForContext(ctx, config, signal);
387
397
  validate();
398
+ const validateIgnore = ignorePolicyValidator({ ...snapshotOptions, validateMutation: validate });
399
+ if (validateIgnore)
400
+ await validateIgnore();
388
401
  const inspection = await inspectionModule.inspectSync(config, snapshotOptions, signal, undefined, timings);
389
402
  validate();
390
403
  let localIdentity = inspection.localIdentity;
@@ -397,6 +410,8 @@ export function createContinuousSync(loaders, clock = systemClock, publish) {
397
410
  }
398
411
  const journal = await readMergeJournal(config);
399
412
  validate();
413
+ if (journal)
414
+ assertMergeJournalPolicy(journal, config);
400
415
  return { inspection, journal, localIdentity };
401
416
  }));
402
417
  validate();
@@ -40,7 +40,10 @@ export async function watchContinuous(config, changed, options = {}) {
40
40
  const target = path.resolve(directory, String(file));
41
41
  if (!relativeWithin(directory, target))
42
42
  return;
43
- if (target === path.join(root, "pi-sync.json"))
43
+ if (target === path.join(root, "pi-sync.json") ||
44
+ (config.ignorePolicy &&
45
+ path.dirname(target) === root &&
46
+ path.basename(target).toLowerCase() === config.ignorePolicy.filename.toLowerCase()))
44
47
  changed(true);
45
48
  else if (scoped) {
46
49
  const relative = scopedPath(target);
@@ -1,4 +1,4 @@
1
- import { configFromSettings, loadConfig } from "../settings/config.js";
1
+ import { loadConfig } from "../settings/config.js";
2
2
  import { isMissingConfigError } from "../settings/config-errors.js";
3
3
  import { consumeLocalConfigMigrationNotice } from "../settings/config-file.js";
4
4
  import { readLocalConfigObject } from "../settings/settings-store.js";
@@ -29,7 +29,8 @@ export async function initializeSync(ctx, signal, publish) {
29
29
  validate();
30
30
  const settings = await readLocalConfigObject();
31
31
  validate();
32
- const config = settings?.activeSyncSetup ? configFromSettings(settings) : undefined;
32
+ const config = settings?.activeSyncSetup ? await loadConfig() : undefined;
33
+ validate();
33
34
  const sessionDir = config?.scope === "agent-directory"
34
35
  ? await effectiveSessionRoot(ctx, config, signal)
35
36
  : sessionDirFromContext(ctx);
@@ -1,7 +1,9 @@
1
- import type { Snapshot } from "../snapshot/snapshot-types.js";
1
+ import { type IgnoreSnapshotSelection, type Snapshot } from "../snapshot/snapshot-types.js";
2
2
  export { normalizeLocalFields } from "./local-field-policy.js";
3
3
  /** Shared transport contract: older snapshots cannot carry portable policy metadata. */
4
4
  export declare function validateSnapshotFieldPolicy(snapshot: Pick<Snapshot, "version" | "localFields">): void;
5
+ export declare function validateIgnoreSnapshotSessionFlag(selection: IgnoreSnapshotSelection, syncSessions: unknown): void;
6
+ export declare function validateIgnoreSnapshotIdentity({ id, createdAt, machine, profile, }: Pick<Snapshot, "id" | "createdAt" | "machine" | "profile">): void;
5
7
  /** Portable transport images must not carry values declared machine-local. Physical journal images are different. */
6
8
  export declare function validatePortableSnapshot(snapshot: Snapshot): void;
7
9
  export declare function sameLocalFields(left: unknown, right: unknown): boolean;
@@ -1,13 +1,14 @@
1
1
  import { createHash } from "node:crypto";
2
2
  import { regenerateSnapshotIdentity } from "../snapshot/snapshot.js";
3
3
  import { assertAgentDirectorySnapshotBound } from "../snapshot/snapshot-bounds.js";
4
+ import { IGNORE_SNAPSHOT_VERSION, isSupportedSnapshotVersion, } from "../snapshot/snapshot-types.js";
4
5
  import { jsonEqual, parseSettingsDocument, renderSettingsMembers, } from "./json-document.js";
5
6
  import { normalizeLocalFields } from "./local-field-policy.js";
6
7
  import { compileSyncPolicyExclude, configuredSnapshotPathMatcher, validateSnapshotSelection } from "./sync-policy.js";
7
8
  export { normalizeLocalFields } from "./local-field-policy.js";
8
9
  /** Shared transport contract: older snapshots cannot carry portable policy metadata. */
9
10
  export function validateSnapshotFieldPolicy(snapshot) {
10
- if (![1, 2, 3, 4, 5].includes(snapshot.version))
11
+ if (!isSupportedSnapshotVersion(snapshot.version))
11
12
  throw new Error("Unsupported snapshot format.");
12
13
  if (snapshot.version === 1 && snapshot.localFields !== undefined)
13
14
  throw new Error("Portable field policy requires snapshot version 2.");
@@ -17,16 +18,76 @@ export function validateSnapshotFieldPolicy(snapshot) {
17
18
  normalizeLocalFields(snapshot.localFields);
18
19
  }
19
20
  }
21
+ export function validateIgnoreSnapshotSessionFlag(selection, syncSessions) {
22
+ if ((syncSessions !== undefined && typeof syncSessions !== "boolean") ||
23
+ (syncSessions === true && !selection.sessions))
24
+ throw new Error("Invalid ignore snapshot session metadata.");
25
+ }
26
+ export function validateIgnoreSnapshotIdentity({ id, createdAt, machine, profile, }) {
27
+ if (typeof id !== "string" ||
28
+ id.length > 512 ||
29
+ id === "." ||
30
+ id === ".." ||
31
+ !/^[A-Za-z0-9._-]+(?![\s\S])/u.test(id) ||
32
+ typeof createdAt !== "string" ||
33
+ createdAt.length > 64 ||
34
+ /[\p{Cc}\p{Cs}]/u.test(createdAt) ||
35
+ Number.isNaN(Date.parse(createdAt)) ||
36
+ typeof machine !== "string" ||
37
+ machine.length > 256 ||
38
+ /[\p{Cc}\p{Cs}]/u.test(machine) ||
39
+ typeof profile !== "string" ||
40
+ !profile ||
41
+ profile.length > 256 ||
42
+ /[\p{Cc}\p{Cs}]/u.test(profile))
43
+ throw new Error("Invalid ignore snapshot identity.");
44
+ }
45
+ function validateIgnoreSnapshotEnvelope(snapshot, selection) {
46
+ validateIgnoreSnapshotIdentity(snapshot);
47
+ validateIgnoreSnapshotSessionFlag(selection, snapshot.syncSessions);
48
+ if (!Array.isArray(snapshot.files) ||
49
+ Object.keys(snapshot).some((key) => ![
50
+ "version",
51
+ "id",
52
+ "createdAt",
53
+ "machine",
54
+ "profile",
55
+ "syncSessions",
56
+ "selection",
57
+ "localFields",
58
+ "files",
59
+ ].includes(key)))
60
+ throw new Error("Invalid ignore snapshot payload.");
61
+ }
62
+ function validateIgnoreSnapshotFiles(files) {
63
+ for (const file of files) {
64
+ if (Object.keys(file).length !== 3 ||
65
+ !Object.hasOwn(file, "path") ||
66
+ !Object.hasOwn(file, "contentBase64") ||
67
+ !Object.hasOwn(file, "sha256") ||
68
+ typeof file.sha256 !== "string" ||
69
+ file.sha256.length !== 64)
70
+ throw new Error("Invalid ignore snapshot file.");
71
+ const content = Buffer.from(file.contentBase64, "base64");
72
+ if (content.toString("base64") !== file.contentBase64 ||
73
+ createHash("sha256").update(content).digest("hex") !== file.sha256)
74
+ throw new Error("Ignore snapshot file checksum or encoding mismatch.");
75
+ }
76
+ }
20
77
  /** Portable transport images must not carry values declared machine-local. Physical journal images are different. */
21
78
  export function validatePortableSnapshot(snapshot) {
22
79
  validateSnapshotFieldPolicy(snapshot);
23
80
  validateSnapshotSelection(snapshot);
24
81
  const selection = snapshot.selection;
82
+ if (selection?.version === 4)
83
+ validateIgnoreSnapshotEnvelope(snapshot, selection);
25
84
  if (selection?.scope) {
26
85
  const selected = configuredSnapshotPathMatcher(selection);
27
86
  if (snapshot.files.some((file) => typeof file?.path !== "string" || !selected(file.path)))
28
87
  throw new Error("Portable snapshot retains excluded or unsafe agent-directory paths.");
29
88
  assertAgentDirectorySnapshotBound(snapshot.files);
89
+ if (snapshot.version === IGNORE_SNAPSHOT_VERSION)
90
+ validateIgnoreSnapshotFiles(snapshot.files);
30
91
  }
31
92
  else {
32
93
  const excludedPath = compileSyncPolicyExclude(selection ?? {});
@@ -12,6 +12,8 @@ import { assertUnexcludedTargets } from "../snapshot/snapshot-exclude-safety.js"
12
12
  import { assertCanonicalMutationTargets } from "../snapshot/snapshot-mutation-queues.js";
13
13
  import { sessionStorageRoot } from "../snapshot/snapshot-paths.js";
14
14
  import { snapshotBase64Size } from "../snapshot/snapshot-payload.js";
15
+ import { recheckScopedImage, scopedTransactionImage } from "../snapshot/snapshot-transaction-images.js";
16
+ import { ignorePolicyValidator } from "../snapshot/snapshot-transaction-policy.js";
15
17
  import { syncDirectory } from "../state/json-file.js";
16
18
  import { syncMutationParents } from "../state/mutation-directory-sync.js";
17
19
  import { mergePathIdentity } from "./file-merge-planner.js";
@@ -251,6 +253,7 @@ async function assertFilesystemTarget(root, relative, options, removedTargets =
251
253
  }
252
254
  /** Roll forward only while each target is still its reviewed preimage or committed postimage. */
253
255
  export async function applyMergedSnapshot(before, after, protectedPaths, options, validate, protectedTarget) {
256
+ const validateIgnore = ignorePolicyValidator(options);
254
257
  const root = agentDir();
255
258
  if (options.scope === "agent-directory" && options.sessionDir === undefined) {
256
259
  options = {
@@ -312,6 +315,8 @@ export async function applyMergedSnapshot(before, after, protectedPaths, options
312
315
  if (target)
313
316
  return withFileMutationQueue(target, () => acquire(index + 1));
314
317
  await validate();
318
+ if (validateIgnore)
319
+ await validateIgnore();
315
320
  await assertCanonicalMergedTargets(root, changed, options);
316
321
  await validate();
317
322
  const current = await createSnapshot(before.profile, options);
@@ -378,6 +383,10 @@ export async function applyMergedSnapshot(before, after, protectedPaths, options
378
383
  const removedTargets = new Set([...removed].map((item) => snapshotTarget(root, item, options.sessionDir)));
379
384
  await assertCanonicalMergedTargets(root, changed, options);
380
385
  await validate();
386
+ const requireReviewedHash = (relative, hash) => {
387
+ if (hash !== beforeHashes[relative] && hash !== afterHashes[relative])
388
+ throw new Error("Local content changed at the apply boundary; journal retained, newer bytes untouched.");
389
+ };
381
390
  const revalidateTarget = async (target) => {
382
391
  await validate();
383
392
  const relative = relativeByTarget.get(target);
@@ -388,11 +397,22 @@ export async function applyMergedSnapshot(before, after, protectedPaths, options
388
397
  await assertUnexcludedTargets(root, [target], options);
389
398
  }
390
399
  await assertFilesystemTarget(root, relative, options, removedTargets, currentHashes);
400
+ if (validateIgnore) {
401
+ const image = await scopedTransactionImage(target, options);
402
+ if (image.kind === "directory" && (!removed.has(relative) || image.children.length))
403
+ throw new Error("Reviewed directory has remaining contents; journal retained for review.");
404
+ requireReviewedHash(relative, image.kind === "file" ? image.value.slice("file:".length) : undefined);
405
+ await validateIgnore();
406
+ await recheckScopedImage(target, image, options);
407
+ return image.kind;
408
+ }
391
409
  await validate();
410
+ let kind = "missing";
392
411
  let hash;
393
412
  try {
394
413
  const stat = await fs.lstat(target);
395
414
  if (stat.isDirectory() && removed.has(relative)) {
415
+ kind = "directory";
396
416
  if ((await fs.readdir(target)).length)
397
417
  throw new Error("Reviewed directory has remaining contents; journal retained for review.");
398
418
  }
@@ -400,6 +420,7 @@ export async function applyMergedSnapshot(before, after, protectedPaths, options
400
420
  if (!stat.isFile() || stat.nlink > 1)
401
421
  throw new Error("Merged transfer target is no longer an independent regular file.");
402
422
  hash = await hashReviewedFile(target, stat, options);
423
+ kind = "file";
403
424
  }
404
425
  }
405
426
  catch (error) {
@@ -408,19 +429,22 @@ export async function applyMergedSnapshot(before, after, protectedPaths, options
408
429
  }
409
430
  options.signal?.throwIfAborted();
410
431
  options.validateMutation?.();
411
- if (hash !== beforeHashes[relative] && hash !== afterHashes[relative])
412
- throw new Error("Local content changed at the apply boundary; journal retained, newer bytes untouched.");
432
+ requireReviewedHash(relative, hash);
433
+ return kind;
413
434
  };
414
435
  if (options.scope === "agent-directory" && plan.deletes.length)
415
436
  await recheckAgentDirectoryBudget(root, plan, options);
416
437
  for (const target of plan.deletes) {
417
- await revalidateTarget(target);
438
+ let kind = await revalidateTarget(target);
418
439
  try {
419
- const stat = await fs.lstat(target);
420
- await validate();
421
- if (stat.isDirectory())
440
+ if (!validateIgnore) {
441
+ const stat = await fs.lstat(target);
442
+ await validate();
443
+ kind = stat.isDirectory() ? "directory" : "file";
444
+ }
445
+ if (kind === "directory")
422
446
  await fs.rmdir(target); // Only an empty, reviewed directory may be replaced.
423
- else
447
+ else if (kind === "file")
424
448
  await fs.rm(target, { force: true });
425
449
  }
426
450
  catch (error) {
@@ -451,6 +475,8 @@ export async function applyMergedSnapshot(before, after, protectedPaths, options
451
475
  // Writers registered after deletion must finish first; never accept their
452
476
  // bytes as our own, even if they match a recognizable pre/postimage.
453
477
  await requireAbsentDestinations();
478
+ if (validateIgnore)
479
+ await validateIgnore();
454
480
  await writeTargets();
455
481
  }
456
482
  await requireAbsentDestinations();
@@ -465,6 +491,8 @@ export async function applyMergedSnapshot(before, after, protectedPaths, options
465
491
  const relative = relativeByTarget.get(item.target);
466
492
  if (!relative)
467
493
  throw new Error("Unowned merge write target.");
494
+ if (validateIgnore)
495
+ await validateIgnore();
468
496
  await assertFilesystemTarget(root, relative, options, new Set());
469
497
  await fs.mkdir(path.dirname(item.target), { recursive: true });
470
498
  const temporary = path.join(path.dirname(item.target), `.pi-sync.json.${randomUUID()}.apply`);