@narumitw/pi-sync-daemon 0.7.0 → 0.9.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 (93) hide show
  1. package/CHANGELOG.md +21 -0
  2. package/README.md +16 -2
  3. package/dist/cli.js +1 -1
  4. package/dist/consent.d.ts +14 -2
  5. package/dist/consent.js +147 -14
  6. package/dist/engine/backends/git/git-backend.d.ts +2 -3
  7. package/dist/engine/backends/git/git-backend.js +71 -25
  8. package/dist/engine/backends/git/git-storage.d.ts +1 -1
  9. package/dist/engine/backends/git/git-storage.js +30 -9
  10. package/dist/engine/backends/s3/s3-backend.js +8 -0
  11. package/dist/engine/backends/sync-backend.d.ts +1 -0
  12. package/dist/engine/backends/webdav/webdav-backend.js +8 -0
  13. package/dist/engine/commands/command-types.d.ts +2 -1
  14. package/dist/engine/host.d.ts +1 -0
  15. package/dist/engine/ignore/effective-ignore-policy.d.ts +10 -0
  16. package/dist/engine/ignore/effective-ignore-policy.js +33 -0
  17. package/dist/engine/ignore/ignore-edit.d.ts +13 -0
  18. package/dist/engine/ignore/ignore-edit.js +102 -0
  19. package/dist/engine/ignore/ignore-initialization.d.ts +9 -0
  20. package/dist/engine/ignore/ignore-initialization.js +252 -0
  21. package/dist/engine/ignore/ignore-migration-prompt.d.ts +7 -0
  22. package/dist/engine/ignore/ignore-migration-prompt.js +139 -0
  23. package/dist/engine/ignore/ignore-settings.d.ts +30 -0
  24. package/dist/engine/ignore/ignore-settings.js +393 -0
  25. package/dist/engine/ignore/ignore-source.d.ts +27 -0
  26. package/dist/engine/ignore/ignore-source.js +250 -0
  27. package/dist/engine/settings/config-file.d.ts +9 -2
  28. package/dist/engine/settings/config-file.js +124 -28
  29. package/dist/engine/settings/config.d.ts +6 -2
  30. package/dist/engine/settings/config.js +140 -11
  31. package/dist/engine/settings/settings-management.d.ts +5 -3
  32. package/dist/engine/settings/settings-management.js +24 -10
  33. package/dist/engine/settings/settings-types.d.ts +25 -2
  34. package/dist/engine/settings/settings-validation.js +23 -5
  35. package/dist/engine/snapshot/session-paths.d.ts +1 -1
  36. package/dist/engine/snapshot/session-paths.js +41 -13
  37. package/dist/engine/snapshot/snapshot-apply.d.ts +3 -3
  38. package/dist/engine/snapshot/snapshot-apply.js +23 -4
  39. package/dist/engine/snapshot/snapshot-codec.d.ts +1 -1
  40. package/dist/engine/snapshot/snapshot-codec.js +14 -5
  41. package/dist/engine/snapshot/snapshot-exclude-safety.d.ts +4 -2
  42. package/dist/engine/snapshot/snapshot-exclude-safety.js +76 -19
  43. package/dist/engine/snapshot/snapshot-transaction-images.d.ts +3 -1
  44. package/dist/engine/snapshot/snapshot-transaction-images.js +33 -3
  45. package/dist/engine/snapshot/snapshot-transaction-policy.d.ts +30 -2
  46. package/dist/engine/snapshot/snapshot-transaction-policy.js +135 -11
  47. package/dist/engine/snapshot/snapshot-transaction-verification.d.ts +7 -0
  48. package/dist/engine/snapshot/snapshot-transaction-verification.js +78 -0
  49. package/dist/engine/snapshot/snapshot-transaction.d.ts +1 -12
  50. package/dist/engine/snapshot/snapshot-transaction.js +129 -109
  51. package/dist/engine/snapshot/snapshot-types.d.ts +27 -1
  52. package/dist/engine/snapshot/snapshot-types.js +9 -1
  53. package/dist/engine/snapshot/snapshot.d.ts +6 -4
  54. package/dist/engine/snapshot/snapshot.js +91 -34
  55. package/dist/engine/state/state-types.d.ts +1 -0
  56. package/dist/engine/sync/agent-plan.js +1 -0
  57. package/dist/engine/sync/agent-sync.js +8 -1
  58. package/dist/engine/sync/continuous-sync.d.ts +3 -1
  59. package/dist/engine/sync/continuous-sync.js +50 -18
  60. package/dist/engine/sync/continuous-watch.js +4 -1
  61. package/dist/engine/sync/initialization.js +3 -2
  62. package/dist/engine/sync/local-fields.d.ts +3 -1
  63. package/dist/engine/sync/local-fields.js +62 -1
  64. package/dist/engine/sync/merge-acceptance.d.ts +8 -0
  65. package/dist/engine/sync/merge-acceptance.js +29 -0
  66. package/dist/engine/sync/merge-apply.js +42 -11
  67. package/dist/engine/sync/merge-journal.d.ts +24 -4
  68. package/dist/engine/sync/merge-journal.js +134 -8
  69. package/dist/engine/sync/merged-sync.d.ts +1 -1
  70. package/dist/engine/sync/merged-sync.js +128 -83
  71. package/dist/engine/sync/remote-snapshot.d.ts +11 -3
  72. package/dist/engine/sync/remote-snapshot.js +72 -18
  73. package/dist/engine/sync/session-push.js +20 -6
  74. package/dist/engine/sync/sync-inspection.js +7 -5
  75. package/dist/engine/sync/sync-mutations.d.ts +2 -1
  76. package/dist/engine/sync/sync-mutations.js +157 -73
  77. package/dist/engine/sync/sync-policy.d.ts +29 -8
  78. package/dist/engine/sync/sync-policy.js +152 -16
  79. package/dist/engine/sync/sync-queries.js +8 -1
  80. package/dist/engine/sync/sync-state.d.ts +4 -2
  81. package/dist/engine/sync/sync-state.js +15 -2
  82. package/dist/engine/sync/transfer-freshness.d.ts +31 -0
  83. package/dist/engine/sync/transfer-freshness.js +82 -0
  84. package/dist/engine-service.d.ts +1 -1
  85. package/dist/engine-service.js +146 -27
  86. package/dist/monitor.d.ts +4 -1
  87. package/dist/monitor.js +84 -32
  88. package/dist/server.d.ts +1 -0
  89. package/dist/server.js +46 -5
  90. package/dist/service-host.d.ts +1 -1
  91. package/dist/service-host.js +2 -1
  92. package/docs/architecture.md +30 -0
  93. package/package.json +2 -1
@@ -1,7 +1,6 @@
1
1
  import { randomUUID } from "node:crypto";
2
2
  import fs from "node:fs/promises";
3
3
  import path from "node:path";
4
- import { isPathInside } from "../paths.js";
5
4
  import { syncDirectory, writeJson } from "../state/json-file.js";
6
5
  import { withLock } from "../state/lock.js";
7
6
  import { syncMutationParents } from "../state/mutation-directory-sync.js";
@@ -18,10 +17,11 @@ import { withMissingTargetQueues, withTargetQueues } from "./snapshot-mutation-q
18
17
  import { sessionStorageRoot } from "./snapshot-paths.js";
19
18
  import { prepareSessionRootTransition, resolveTransitionSessionRoot, stableAgentDirectorySettingsImage, } from "./snapshot-root-transition.js";
20
19
  import { pendingTransactionEntries, transactionRoot } from "./snapshot-transaction-directory.js";
21
- import { legacyImage, MAX_TRANSACTION_JOURNAL_BYTES, ownedLegacyPostTree, ownedScopedPostTree, ownedScopedSubset, readTransactionJournal, removeScopedImage, scopedDescendant, scopedIdentity, scopedPathIdentity, scopedTransactionImage, stableScopedIdentity, } from "./snapshot-transaction-images.js";
20
+ import { legacyImage, MAX_TRANSACTION_JOURNAL_BYTES, ownedScopedPostTree, readTransactionJournal, recheckScopedImage, removeScopedImage, scopedDescendant, scopedIdentity, scopedPathIdentity, scopedTransactionImage, stableScopedIdentity, } from "./snapshot-transaction-images.js";
22
21
  import { indexTransactionPlan } from "./snapshot-transaction-plan.js";
23
- import { AGENT_DIRECTORY_JOURNAL_VERSION, assertAllowedTarget, assertRecoveryPolicy, isScopedJournal, isStrictlyInside, transactionHasSessionTargets, validateJournal, validateJournalPolicy, } from "./snapshot-transaction-policy.js";
22
+ import { AGENT_DIRECTORY_JOURNAL_VERSION, assertAllowedTarget, assertRecoveryPolicy, assertSafeParents, BOUND_DIRECTORY_JOURNAL_VERSION, BOUND_INCLUDED_PATHS_JOURNAL_VERSION, IGNORE_POLICY_JOURNAL_VERSION, ignorePolicyValidator, ignoreSourceBinding, isScopedJournal, isStrictlyInside, recoveryPolicyKey, StaleIgnorePolicyError, touchesProtectedTarget, transactionHasSessionTargets, validateJournal, validateJournalPolicy, } from "./snapshot-transaction-policy.js";
24
23
  import { assertNoUnclaimedLegacyStage, buildScopedRecoveryStage, cleanScopedLegacyStage, cleanScopedWorkspace, inspectScopedRecoveryStage, prepareLegacyRecoveryStage, recoveryStagePath, } from "./snapshot-transaction-stage.js";
24
+ import { verifyTarget } from "./snapshot-transaction-verification.js";
25
25
  const JOURNAL_VERSION = 4;
26
26
  class ScopedRemovalError extends Error {
27
27
  }
@@ -29,9 +29,10 @@ export async function applySnapshotTransaction(plan, options = {}) {
29
29
  options.validateMutation?.();
30
30
  const root = path.resolve(agentDir());
31
31
  if (options.scope === "agent-directory") {
32
- const sessionDir = options.sessionDir ?? (await agentDirectoryConfiguredSessionDir(options.signal, root));
32
+ const sessionDir = options.sessionDir ?? (await agentDirectoryConfiguredSessionDir(options.signal, root, options));
33
33
  options = { ...options, sessionDir: sessionStorageRoot(root, sessionDir) };
34
34
  }
35
+ const validateIgnorePolicy = ignorePolicyValidator(options);
35
36
  await recoverPendingSnapshotTransactions(options);
36
37
  const coalesced = await coalesceCaseReplacements(root, plan);
37
38
  options.validateMutation?.();
@@ -40,10 +41,11 @@ export async function applySnapshotTransaction(plan, options = {}) {
40
41
  if (targets.length > 16_384)
41
42
  throw new Error("Snapshot transaction exceeds its target bound; review a smaller transfer.");
42
43
  return withTargetQueues(targets, options, async (heldKeys) => {
44
+ if (validateIgnorePolicy)
45
+ await validateIgnorePolicy();
43
46
  await assertUnexcludedTargets(root, [...targets, ...coalesced.replacements.values()], options);
44
47
  options.signal?.throwIfAborted();
45
- if (targets.some((target) => options.protectedTargets?.some((protectedTarget) => mergePathIdentity(target) === mergePathIdentity(protectedTarget) ||
46
- isPathInside(mergePathIdentity(target), mergePathIdentity(protectedTarget)))))
48
+ if (targets.some((target) => touchesProtectedTarget(target, options.protectedTargets)))
47
49
  throw new Error("Snapshot transaction targets the current session; review is required.");
48
50
  for (const [before, after] of coalesced.replacements) {
49
51
  if ((await caseReplacementSpelling(before, after)) !== before)
@@ -53,6 +55,7 @@ export async function applySnapshotTransaction(plan, options = {}) {
53
55
  }
54
56
  const originalTargets = new Map([...coalesced.replacements].map(([before, after]) => [after, before]));
55
57
  const scoped = options.scope === "agent-directory";
58
+ /** Fresh apply authorization only; recovery remains bound to durable journal images. */
56
59
  const expectedPreimages = new Map([...(options.expectedPreimages ?? [])]
57
60
  .filter(([target]) => !scoped || !originalTargets.has(target))
58
61
  .map(([target, expected]) => [originalTargets.get(target) ?? target, expected]));
@@ -88,7 +91,7 @@ export async function applySnapshotTransaction(plan, options = {}) {
88
91
  }
89
92
  }
90
93
  for (const [target, expected] of expectedPreimages) {
91
- if (scoped)
94
+ if (scoped || options.reservedIgnoreNames?.length)
92
95
  await assertUnexcludedTargets(root, [target], options);
93
96
  const current = scoped ? (await scopedTransactionImage(target, options)).value : await legacyImage(target);
94
97
  options.validateMutation?.();
@@ -96,6 +99,8 @@ export async function applySnapshotTransaction(plan, options = {}) {
96
99
  if (current !== expected)
97
100
  throw new Error("Reviewed file preimage changed before apply; snapshot installation refused.");
98
101
  }
102
+ if (validateIgnorePolicy)
103
+ await validateIgnorePolicy();
99
104
  const transaction = await prepareTransaction(coalesced.plan, targets, { ...options, expectedPreimages }, coalesced.replacements);
100
105
  const entriesByTarget = new Map(transaction.journal.entries.flatMap((entry) => [
101
106
  [entry.target, entry],
@@ -104,6 +109,8 @@ export async function applySnapshotTransaction(plan, options = {}) {
104
109
  // A released additional key cannot authorize rollback, even for recognized raced bytes.
105
110
  const changesQueueKey = transaction.journal.entries.some((entry) => !heldKeys.has(entry.target) || (entry.afterTarget && !heldKeys.has(entry.afterTarget)));
106
111
  try {
112
+ if (options.validateApplyReview)
113
+ await options.validateApplyReview();
107
114
  if (scoped && transaction.deletes.length)
108
115
  await recheckAgentDirectoryBudget(root, plan, options, stateDir(root));
109
116
  for (const target of transaction.deletes.sort((a, b) => a.length - b.length)) {
@@ -117,8 +124,14 @@ export async function applySnapshotTransaction(plan, options = {}) {
117
124
  await withMissingTargetQueues(transaction.journal.entries
118
125
  .filter((entry) => entry.removalPending)
119
126
  .flatMap((entry) => [entry.target, ...(entry.afterTarget ? [entry.afterTarget] : [])]), heldKeys, options, async () => {
127
+ if (options.validateApplyReview && transaction.journal.entries.some((entry) => entry.removalPending))
128
+ await options.validateApplyReview();
129
+ if (validateIgnorePolicy)
130
+ await validateIgnorePolicy();
120
131
  if (scoped && plan.writes.length)
121
132
  await recheckAgentDirectoryBudget(root, { deletes: [], writes: plan.writes }, options);
133
+ if (validateIgnorePolicy)
134
+ await validateIgnorePolicy();
122
135
  await retireRemovalIntent(transaction.directory, transaction.journal, transaction.journal.entries.filter((entry) => entry.removalPending && (entry.afterImage !== "missing" || (entry.postFiles?.length ?? 0) > 0)), options);
123
136
  // Only this uninterrupted call knows which deleted writes have not attempted installation yet.
124
137
  const uninstalledWrites = new Set(transaction.deletedWrites);
@@ -128,11 +141,13 @@ export async function applySnapshotTransaction(plan, options = {}) {
128
141
  if (!entry)
129
142
  throw new Error("Unowned transaction target.");
130
143
  const deletedByThisCall = uninstalledWrites.delete(entry.target);
131
- if (options.scope === "agent-directory")
144
+ if (options.scope === "agent-directory" || options.reservedIgnoreNames?.length)
132
145
  await assertUnexcludedTargets(transaction.journal.root, [item.target], options);
133
146
  await verifyTarget(transaction.directory, entry, transaction.journal, options, deletedByThisCall);
134
147
  options.validateMutation?.();
135
148
  options.signal?.throwIfAborted();
149
+ if (validateIgnorePolicy)
150
+ await validateIgnorePolicy();
136
151
  await fs.mkdir(path.dirname(item.target), { recursive: true });
137
152
  options.validateMutation?.();
138
153
  options.signal?.throwIfAborted();
@@ -156,9 +171,20 @@ export async function applySnapshotTransaction(plan, options = {}) {
156
171
  finally {
157
172
  await handle.close();
158
173
  }
159
- await verifyTarget(transaction.directory, entry, transaction.journal, options, deletedByThisCall);
174
+ const verified = await verifyTarget(transaction.directory, entry, transaction.journal, options, deletedByThisCall);
160
175
  options.signal?.throwIfAborted();
161
176
  options.validateMutation?.();
177
+ if (validateIgnorePolicy) {
178
+ await validateIgnorePolicy();
179
+ if (verified.scoped)
180
+ await recheckScopedImage(item.target, verified.scoped, options);
181
+ else {
182
+ await assertUnexcludedTargets(root, [item.target], options);
183
+ await verifyTarget(transaction.directory, entry, transaction.journal, options, deletedByThisCall);
184
+ }
185
+ }
186
+ options.validateMutation?.();
187
+ options.signal?.throwIfAborted();
162
188
  await fs.rename(temp, item.target);
163
189
  await syncDirectory(path.dirname(item.target));
164
190
  }
@@ -171,13 +197,17 @@ export async function applySnapshotTransaction(plan, options = {}) {
171
197
  await syncMutationParents(targets, [transaction.journal.root, ...(transaction.journal.sessionRoot ? [transaction.journal.sessionRoot] : [])], options);
172
198
  options.validateMutation?.();
173
199
  options.signal?.throwIfAborted();
200
+ if (validateIgnorePolicy)
201
+ await validateIgnorePolicy();
174
202
  });
203
+ if (validateIgnorePolicy)
204
+ await validateIgnorePolicy();
175
205
  }
176
206
  catch (error) {
177
207
  // Aborted owners cannot roll back files after another session has replaced them.
178
208
  if (options.signal?.aborted)
179
209
  throw new Error("Snapshot apply cancelled; guarded transaction evidence retained for review.");
180
- if (error instanceof ScopedRemovalError)
210
+ if (error instanceof ScopedRemovalError || error instanceof StaleIgnorePolicyError)
181
211
  throw error;
182
212
  // Additional queues have been released. Recovery must reserve missing keys afresh.
183
213
  if (changesQueueKey)
@@ -226,14 +256,16 @@ export async function recoverPendingSnapshotTransactions(options = {}) {
226
256
  throw new Error("Cannot recover malformed pi-sync transaction; preserve private evidence for review.");
227
257
  }
228
258
  validateJournalPolicy(journal);
229
- if (!journal.completed)
259
+ if (!journal.completed) {
230
260
  assertRecoveryPolicy(journal, options);
261
+ ignorePolicyValidator(options);
262
+ }
231
263
  let sessionDir = options.sessionDir;
232
264
  if (sessionDir === undefined && !journal.completed) {
233
265
  if (options.scope === "agent-directory")
234
- sessionDir = await agentDirectoryConfiguredSessionDir(options.signal);
266
+ sessionDir = await agentDirectoryConfiguredSessionDir(options.signal, agentDir(), options);
235
267
  else if (options.resolveConfiguredSessionDir && transactionHasSessionTargets(journal))
236
- sessionDir = await configuredSessionDir();
268
+ sessionDir = await configuredSessionDir(options);
237
269
  }
238
270
  options.validateMutation?.();
239
271
  options.signal?.throwIfAborted();
@@ -256,6 +288,8 @@ async function prepareTransaction(plan, targets, options, replacements = new Map
256
288
  const { sessionDir } = options;
257
289
  const root = path.resolve(agentDir());
258
290
  const wholeDirectory = options.scope === "agent-directory";
291
+ const ignoreSource = options.ignorePolicy ? ignoreSourceBinding(options.ignorePolicy) : undefined;
292
+ const localPolicyKey = recoveryPolicyKey(options);
259
293
  const sessionRoot = sessionDir || wholeDirectory ? path.resolve(sessionStorageRoot(root, sessionDir)) : undefined;
260
294
  const indexed = indexTransactionPlan(plan, targets);
261
295
  const directory = path.join(transactionRoot(), randomUUID());
@@ -267,7 +301,7 @@ async function prepareTransaction(plan, targets, options, replacements = new Map
267
301
  options.validateMutation?.();
268
302
  assertAllowedTarget(root, sessionRoot, target);
269
303
  await assertSafeParents(root, sessionRoot, target);
270
- if (wholeDirectory)
304
+ if (wholeDirectory || options.reservedIgnoreNames?.length)
271
305
  await assertUnexcludedTargets(root, [target], options);
272
306
  const entry = { target, backupName: `${index}`, kind: "missing" };
273
307
  if (replacements.has(target))
@@ -305,14 +339,22 @@ async function prepareTransaction(plan, targets, options, replacements = new Map
305
339
  ? undefined
306
340
  : await prepareSessionRootTransition(directory, root, effectiveRoot, entries, plan, options);
307
341
  const journal = {
308
- version: wholeDirectory
309
- ? AGENT_DIRECTORY_JOURNAL_VERSION
310
- : sessionRootTransition
311
- ? 7
312
- : replacements.size
313
- ? 5
314
- : JOURNAL_VERSION,
342
+ version: localPolicyKey
343
+ ? wholeDirectory
344
+ ? BOUND_DIRECTORY_JOURNAL_VERSION
345
+ : BOUND_INCLUDED_PATHS_JOURNAL_VERSION
346
+ : ignoreSource
347
+ ? IGNORE_POLICY_JOURNAL_VERSION
348
+ : wholeDirectory
349
+ ? AGENT_DIRECTORY_JOURNAL_VERSION
350
+ : sessionRootTransition
351
+ ? 7
352
+ : replacements.size
353
+ ? 5
354
+ : JOURNAL_VERSION,
315
355
  root,
356
+ ignoreSource,
357
+ localPolicyKey,
316
358
  ...(wholeDirectory
317
359
  ? { selection: selectionForSnapshot(includeFromSelectionConfig(options), options.exclude, options) }
318
360
  : options.exclude === undefined
@@ -392,12 +434,16 @@ async function restoreTransaction(directory, journal, options, heldKeys) {
392
434
  async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
393
435
  validateJournal(directory, journal, options.sessionDir);
394
436
  const scoped = isScopedJournal(journal);
437
+ const validateIgnorePolicy = ignorePolicyValidator(options);
395
438
  options.validateMutation?.();
396
439
  options.signal?.throwIfAborted();
440
+ if (validateIgnorePolicy) {
441
+ assertRecoveryPolicy(journal, options);
442
+ await validateIgnorePolicy();
443
+ }
397
444
  await assertUnexcludedTargets(journal.root, journal.entries.flatMap((entry) => [entry.target, ...(entry.afterTarget ? [entry.afterTarget] : [])]), options);
398
445
  for (const entry of journal.entries) {
399
- if (options.protectedTargets?.some((target) => mergePathIdentity(target) === mergePathIdentity(entry.target) ||
400
- isPathInside(mergePathIdentity(entry.target), mergePathIdentity(target))))
446
+ if (touchesProtectedTarget(entry.target, options.protectedTargets))
401
447
  throw new Error("Pending transaction touches the current session; resume a different session before guarded recovery.");
402
448
  const { value, before } = await verifyTarget(directory, entry, journal, options);
403
449
  if (scoped) {
@@ -430,7 +476,7 @@ async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
430
476
  options.validateMutation?.();
431
477
  options.signal?.throwIfAborted();
432
478
  }
433
- if (scoped && journal.version !== AGENT_DIRECTORY_JOURNAL_VERSION) {
479
+ if (scoped && journal.version < AGENT_DIRECTORY_JOURNAL_VERSION) {
434
480
  journal.version = AGENT_DIRECTORY_JOURNAL_VERSION;
435
481
  for (const entry of journal.entries)
436
482
  delete entry.recoveryStaged;
@@ -443,8 +489,11 @@ async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
443
489
  const { value: current, before } = await verifyTarget(directory, entry, journal, options);
444
490
  const spellingMatches = async () => !entry.afterTarget || (await caseReplacementSpelling(entry.target, entry.afterTarget)) === entry.target;
445
491
  if (current === before && (await spellingMatches())) {
446
- if (entry.recoveryWorkspace)
492
+ if (entry.recoveryWorkspace) {
493
+ if (validateIgnorePolicy)
494
+ await validateIgnorePolicy();
447
495
  await cleanScopedWorkspace(directory, entry, options);
496
+ }
448
497
  continue;
449
498
  }
450
499
  options.signal?.throwIfAborted();
@@ -460,6 +509,8 @@ async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
460
509
  const temporary = await prepareLegacyRecoveryStage(directory, entry, options, () => persistJournal(directory, journal));
461
510
  if (entry.kind === "file") {
462
511
  try {
512
+ options.validateMutation?.();
513
+ options.signal?.throwIfAborted();
463
514
  await fs.mkdir(path.dirname(entry.target), { recursive: true });
464
515
  await fs.copyFile(path.join(directory, "before", entry.backupName), temporary);
465
516
  // Windows requires write access to flush an existing regular file.
@@ -500,6 +551,13 @@ async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
500
551
  options.signal?.throwIfAborted();
501
552
  if (atInstall === before && (await spellingMatches()))
502
553
  return;
554
+ if (validateIgnorePolicy) {
555
+ await validateIgnorePolicy();
556
+ await assertUnexcludedTargets(journal.root, [entry.target], options);
557
+ await verifyTarget(directory, entry, journal, options, atRename === "missing");
558
+ }
559
+ options.validateMutation?.();
560
+ options.signal?.throwIfAborted();
503
561
  await fs.rename(temporary, entry.target);
504
562
  await syncDirectory(path.dirname(entry.target));
505
563
  });
@@ -510,6 +568,8 @@ async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
510
568
  continue;
511
569
  }
512
570
  try {
571
+ options.validateMutation?.();
572
+ options.signal?.throwIfAborted();
513
573
  await fs.mkdir(path.dirname(entry.target), { recursive: true });
514
574
  await assertSafeParents(journal.root, journal.sessionRoot, entry.target);
515
575
  if (entry.kind === "directory") {
@@ -545,6 +605,13 @@ async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
545
605
  options.signal?.throwIfAborted();
546
606
  if (atInstall === before)
547
607
  return;
608
+ if (validateIgnorePolicy) {
609
+ await validateIgnorePolicy();
610
+ await assertUnexcludedTargets(journal.root, [entry.target], options);
611
+ await verifyTarget(directory, entry, journal, options, atRename === "missing");
612
+ }
613
+ options.validateMutation?.();
614
+ options.signal?.throwIfAborted();
548
615
  await fs.rename(temporary, entry.target);
549
616
  await syncDirectory(path.dirname(entry.target));
550
617
  });
@@ -556,15 +623,23 @@ async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
556
623
  await syncMutationParents(journal.entries.map((entry) => entry.target), [journal.root, ...(journal.sessionRoot ? [journal.sessionRoot] : [])], options);
557
624
  options.validateMutation?.();
558
625
  options.signal?.throwIfAborted();
626
+ if (validateIgnorePolicy)
627
+ await validateIgnorePolicy();
559
628
  await completeTransaction(directory, journal);
560
629
  }
561
630
  async function restoreScopedEntry(directory, journal, entry, options, heldKeys, before, spellingMatches) {
631
+ const validateIgnorePolicy = ignorePolicyValidator(options);
562
632
  options.validateMutation?.();
563
633
  options.signal?.throwIfAborted();
634
+ if (validateIgnorePolicy)
635
+ await validateIgnorePolicy();
564
636
  await fs.mkdir(path.dirname(entry.target), { recursive: true });
565
637
  await assertSafeParents(journal.root, journal.sessionRoot, entry.target);
566
- if (!entry.vacantInstall)
638
+ if (!entry.vacantInstall) {
639
+ if (validateIgnorePolicy)
640
+ await validateIgnorePolicy();
567
641
  await buildScopedRecoveryStage(directory, entry, options, () => persistJournal(directory, journal));
642
+ }
568
643
  const verifyStage = async () => {
569
644
  const stage = await inspectScopedRecoveryStage(directory, entry, options, true);
570
645
  if (!stage || stage.image.kind === "missing" || stage.image.value !== before || stage.partial.kind !== "missing")
@@ -572,7 +647,7 @@ async function restoreScopedEntry(directory, journal, entry, options, heldKeys,
572
647
  if (entry.vacantInstall && scopedIdentity(stage.image.stat) !== entry.vacantInstall)
573
648
  throw new Error("Recovery vacancy has a different staging image; preserve evidence for review.");
574
649
  const identity = stableScopedIdentity(stage.payload, stage.image.stat);
575
- return { payload: stage.payload, identity };
650
+ return { payload: stage.payload, identity, image: stage.image };
576
651
  };
577
652
  await verifyStage();
578
653
  const { value: verified } = await verifyTarget(directory, entry, journal, options);
@@ -587,6 +662,8 @@ async function restoreScopedEntry(directory, journal, entry, options, heldKeys,
587
662
  }))) {
588
663
  const queueTargets = needsVacantTarget ? [entry.target, ...(entry.afterTarget ? [entry.afterTarget] : [])] : [];
589
664
  await withMissingTargetQueues(queueTargets, heldKeys, options, async () => {
665
+ if (validateIgnorePolicy)
666
+ await validateIgnorePolicy();
590
667
  const { value: atRename } = await verifyTarget(directory, entry, journal, options);
591
668
  if (atRename === before && (await spellingMatches()))
592
669
  return;
@@ -594,6 +671,8 @@ async function restoreScopedEntry(directory, journal, entry, options, heldKeys,
594
671
  throw new Error("Transaction target changed after removal; preserve evidence for review.");
595
672
  const stage = await verifyStage();
596
673
  if (needsVacantTarget && !entry.vacantInstall) {
674
+ if (validateIgnorePolicy)
675
+ await validateIgnorePolicy();
597
676
  entry.vacantInstall = stage.identity;
598
677
  delete entry.removalPending;
599
678
  delete entry.replacementStarted;
@@ -612,13 +691,18 @@ async function restoreScopedEntry(directory, journal, entry, options, heldKeys,
612
691
  }
613
692
  if ((await scopedPathIdentity(stage.payload, options)) !== stage.identity)
614
693
  throw new Error("Staged recovery image changed before restoration; preserve evidence for review.");
615
- const { value: atInstall } = await verifyTarget(directory, entry, journal, options);
616
- if (atInstall === before && (await spellingMatches()))
694
+ const atInstall = await verifyTarget(directory, entry, journal, options);
695
+ if (atInstall.value === before && (await spellingMatches()))
617
696
  return;
618
- if (atInstall !== atRename)
697
+ if (atInstall.value !== atRename)
619
698
  throw new Error("Transaction target changed before restoration; preserve evidence for review.");
620
699
  options.validateMutation?.();
621
700
  options.signal?.throwIfAborted();
701
+ if (validateIgnorePolicy && atInstall.scoped) {
702
+ await validateIgnorePolicy();
703
+ await recheckScopedImage(stage.payload, stage.image, options);
704
+ await recheckScopedImage(entry.target, atInstall.scoped, options);
705
+ }
622
706
  await fs.rename(stage.payload, entry.target);
623
707
  await syncDirectory(path.dirname(entry.target));
624
708
  await syncDirectory(path.dirname(stage.payload));
@@ -627,58 +711,16 @@ async function restoreScopedEntry(directory, journal, entry, options, heldKeys,
627
711
  });
628
712
  }
629
713
  }
714
+ if (validateIgnorePolicy)
715
+ await validateIgnorePolicy();
630
716
  await cleanScopedWorkspace(directory, entry, options);
631
717
  }
632
- async function verifyTarget(directory, entry, journal, options, deletedByThisCall = false) {
633
- await assertSafeParents(journal.root, journal.sessionRoot, entry.target);
634
- const isScoped = isScopedJournal(journal);
635
- // Hash the potentially large backup before observing the live target, not after it.
636
- const backup = isScoped && entry.kind !== "missing"
637
- ? await scopedTransactionImage(path.join(directory, "before", entry.backupName), options)
638
- : undefined;
639
- const before = isScoped ? (backup?.value ?? "missing") : await legacyBeforeImage(directory, entry);
640
- if ((backup && backup.kind !== entry.kind) || (journal.version >= 2 && before !== entry.beforeImage))
641
- throw new Error("Transaction backup changed; preserve evidence for review.");
642
- const spelling = entry.afterTarget ? await caseReplacementSpelling(entry.target, entry.afterTarget) : entry.target;
643
- const scoped = isScoped ? await scopedTransactionImage(entry.target, options) : undefined;
644
- const value = scoped?.value ?? (await legacyImage(entry.target));
645
- const result = { value, before, scoped };
646
- const postFiles = entry.postFiles ?? [];
647
- if (entry.vacantInstall) {
648
- if (scoped?.kind === "missing" ||
649
- (scoped && value === before && spelling === entry.target && scopedIdentity(scoped.stat) === entry.vacantInstall))
650
- return result;
651
- }
652
- else if (value === "missing") {
653
- if (value === before ||
654
- deletedByThisCall ||
655
- (journal.version >= 4 && entry.removalPending && !entry.replacementStarted))
656
- return result;
657
- }
658
- else if (scoped && entry.scopedRemoval) {
659
- const removal = entry.scopedRemoval;
660
- if ((removal.image === "before"
661
- ? backup && ownedScopedSubset(scoped, backup)
662
- : value === entry.afterImage || ownedScopedPostTree(scoped, postFiles, false)) &&
663
- scoped.kind !== "missing" &&
664
- scopedIdentity(scoped.stat) === removal.identity)
665
- return result;
666
- }
667
- else if (value === before || (journal.version >= 2 && value === entry.afterImage)) {
668
- return result;
669
- }
670
- else if (journal.version >= 2) {
671
- const requireComplete = journal.version < 4 || entry.replacementStarted === true || !entry.removalPending;
672
- if (scoped
673
- ? ownedScopedPostTree(scoped, postFiles, true)
674
- : await ownedLegacyPostTree(entry.target, postFiles, requireComplete))
675
- return result;
676
- }
677
- throw new Error("Transaction target has unrecognized or newer bytes; automatic rollback refused. Preserve the transaction and review its backup with Pi closed.");
678
- }
679
718
  async function removeOwnedTarget(directory, entry, journal, options, { apply, restoringBefore } = {}) {
680
719
  const scoped = isScopedJournal(journal);
720
+ const validateIgnorePolicy = ignorePolicyValidator(options);
681
721
  try {
722
+ if (validateIgnorePolicy)
723
+ await validateIgnorePolicy();
682
724
  await assertUnexcludedTargets(journal.root, [entry.target, ...(entry.afterTarget ? [entry.afterTarget] : [])], options);
683
725
  const current = await verifyTarget(directory, entry, journal, options);
684
726
  options.validateMutation?.();
@@ -733,16 +775,23 @@ async function removeOwnedTarget(directory, entry, journal, options, { apply, re
733
775
  if (current.value !== verified.value)
734
776
  throw new Error("Transaction removal image changed.");
735
777
  await assertUnexcludedTargets(journal.root, [entry.target], options);
736
- await removeScopedImage(entry.target, current.scoped, options);
778
+ await removeScopedImage(entry.target, current.scoped, options, validateIgnorePolicy);
737
779
  }
738
780
  else {
781
+ if (validateIgnorePolicy) {
782
+ await validateIgnorePolicy();
783
+ await assertUnexcludedTargets(journal.root, [entry.target], options);
784
+ await verifyTarget(directory, entry, journal, options);
785
+ }
786
+ options.validateMutation?.();
787
+ options.signal?.throwIfAborted();
739
788
  await fs.rm(entry.target, { recursive: true, force: true });
740
789
  }
741
790
  await syncDirectory(path.dirname(entry.target));
742
791
  return true;
743
792
  }
744
793
  catch (error) {
745
- if (!scoped)
794
+ if (!scoped || error instanceof StaleIgnorePolicyError)
746
795
  throw error;
747
796
  throw new ScopedRemovalError("Scoped transaction removal stopped; preserve transaction and backup for review.", {
748
797
  cause: error,
@@ -785,41 +834,12 @@ async function retireRestorationIntent(directory, journal, entry, options) {
785
834
  function persistJournal(directory, journal) {
786
835
  return writeJson(path.join(directory, "journal.json"), journal, { maxBytes: MAX_TRANSACTION_JOURNAL_BYTES });
787
836
  }
788
- async function legacyBeforeImage(directory, entry) {
789
- if (entry.kind === "missing")
790
- return "missing";
791
- const backup = path.join(directory, "before", entry.backupName);
792
- if (entry.kind === "symlink")
793
- return `symlink:${entry.linkTarget}`;
794
- const value = await legacyImage(backup);
795
- if (value === "missing")
796
- throw new Error("Transaction backup is missing; preserve evidence for review.");
797
- return value;
798
- }
799
- async function assertSafeParents(root, sessionRoot, target) {
800
- assertAllowedTarget(root, sessionRoot, target);
801
- const boundary = isPathInside(root, target) ? root : sessionRoot;
802
- for (let parent = path.dirname(target); boundary && mergePathIdentity(parent) !== mergePathIdentity(boundary); parent = path.dirname(parent)) {
803
- if (path.dirname(parent) === parent)
804
- throw new Error("Transaction parent did not reach its owned boundary.");
805
- try {
806
- const stat = await fs.lstat(parent);
807
- if ((!stat.isDirectory() && !stat.isFile()) || stat.isSymbolicLink())
808
- throw new Error("Unsafe transaction parent.");
809
- }
810
- catch (error) {
811
- const code = error.code;
812
- if (code !== "ENOENT" && code !== "ENOTDIR")
813
- throw error;
814
- }
815
- }
816
- }
817
837
  async function completeTransaction(directory, journal) {
818
838
  // Publish completion before deleting any backup. A surviving journal after power loss
819
839
  // may only retry cleanup, never roll back already accepted files.
820
840
  await writeJson(path.join(directory, "journal.json"), {
821
841
  ...journal,
822
- version: isScopedJournal(journal) ? journal.version : journal.sessionRootTransition ? 7 : 6,
842
+ version: isScopedJournal(journal) || journal.localPolicyKey ? journal.version : journal.sessionRootTransition ? 7 : 6,
823
843
  completed: true,
824
844
  }, {
825
845
  maxBytes: MAX_TRANSACTION_JOURNAL_BYTES,
@@ -3,9 +3,30 @@ export interface SnapshotFile {
3
3
  contentBase64: string;
4
4
  sha256: string;
5
5
  }
6
+ export interface EffectiveIgnorePolicy {
7
+ filename: string;
8
+ sourceDigest: string;
9
+ fingerprint: string;
10
+ sessions: boolean;
11
+ reservedNames: readonly string[];
12
+ matches(path: string, directory?: boolean): boolean;
13
+ }
6
14
  export interface DirectoryScope {
7
15
  scope?: "agent-directory";
8
16
  reinclude?: readonly string[];
17
+ ignorePolicy?: EffectiveIgnorePolicy;
18
+ reservedIgnoreNames?: readonly string[];
19
+ }
20
+ export declare const IGNORE_SNAPSHOT_VERSION = 6;
21
+ export declare function isSupportedSnapshotVersion(version: unknown): version is 1 | 2 | 3 | 4 | 5 | 6;
22
+ export interface IgnoreSnapshotSelection {
23
+ version: 4;
24
+ scope: "agent-directory";
25
+ fingerprint: string;
26
+ sessions: boolean;
27
+ include?: never;
28
+ exclude?: never;
29
+ reinclude?: never;
9
30
  }
10
31
  export type SnapshotSelection = {
11
32
  version: 1;
@@ -25,7 +46,7 @@ export type SnapshotSelection = {
25
46
  include: string[];
26
47
  exclude: string[];
27
48
  reinclude: string[];
28
- };
49
+ } | IgnoreSnapshotSelection;
29
50
  export interface Snapshot {
30
51
  version: number;
31
52
  id: string;
@@ -49,9 +70,14 @@ export interface AgentDirectoryInventory {
49
70
  routingDirectories: ReadonlySet<string>;
50
71
  }
51
72
  export interface SnapshotOptions extends DirectoryScope {
73
+ setupName?: string;
74
+ recoverySetupKey?: string;
75
+ ignoreSourceIdentity?: string;
52
76
  signal?: AbortSignal;
53
77
  /** Caller-owned session/generation guard, rechecked at file-mutation boundaries. */
54
78
  validateMutation?: () => void;
79
+ validateIgnorePolicy?: () => Promise<void>;
80
+ validateApplyReview?: () => Promise<void>;
55
81
  /** Reviewed regular-file preimages; null means the path was absent. Checked under mutation queues. */
56
82
  expectedFileHashes?: Readonly<Record<string, string | null>>;
57
83
  include?: string[];
@@ -1 +1,9 @@
1
- export {};
1
+ export const IGNORE_SNAPSHOT_VERSION = 6;
2
+ export function isSupportedSnapshotVersion(version) {
3
+ return (version === 1 ||
4
+ version === 2 ||
5
+ version === 3 ||
6
+ version === 4 ||
7
+ version === 5 ||
8
+ version === IGNORE_SNAPSHOT_VERSION);
9
+ }
@@ -1,14 +1,15 @@
1
+ import { reservedIgnoreTargetGuard } from "./snapshot-exclude-safety.js";
1
2
  export { isDeniedPath } from "../paths.js";
2
3
  export { sessionStorageRoot } from "./snapshot-paths.js";
3
4
  import { type SyncSelectionConfig } from "../sync/sync-policy.js";
4
- import type { AgentDirectoryInventory, Snapshot, SnapshotFile, SnapshotOptions } from "./snapshot-types.js";
5
+ import { type AgentDirectoryInventory, type Snapshot, type SnapshotFile, type SnapshotOptions } from "./snapshot-types.js";
5
6
  export { canonicalSnapshotPathForConfig, isConfiguredSnapshotPath } from "../sync/sync-policy.js";
6
7
  export declare function agentDirectoryInventory(snapshot: Pick<Snapshot, "files">): AgentDirectoryInventory | undefined;
7
8
  export declare function regenerateSnapshotIdentity(snapshot: Snapshot): Snapshot;
8
9
  export declare function createSnapshot(profile: string, options?: SnapshotOptions): Promise<Snapshot>;
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>;
10
+ export declare function collectFiles(root: string, options?: SnapshotOptions, excluded?: (relativePath: string, directory?: boolean) => boolean): Promise<SnapshotFile[]>;
11
+ export declare function agentDirectoryConfiguredSessionDir(signal?: AbortSignal, root?: string, options?: Pick<SnapshotOptions, "reservedIgnoreNames">): Promise<string | undefined>;
12
+ export declare function readAgentDirectorySettings(signal?: AbortSignal, root?: string, options?: Pick<SnapshotOptions, "reservedIgnoreNames">): Promise<Buffer<ArrayBuffer> | undefined>;
12
13
  export declare function agentDirectorySessionDirFromSettings(content: Buffer): string | undefined;
13
14
  export type AgentDirectoryScanOptions = SyncSelectionConfig & Pick<SnapshotOptions, "sessionDir" | "signal" | "validateMutation">;
14
15
  export declare function scanAgentDirectoryInventory(root: string, options: AgentDirectoryScanOptions, pendingStateEntry?: string): Promise<{
@@ -20,6 +21,7 @@ export declare function scanAgentDirectoryInventory(root: string, options: Agent
20
21
  walkedDirectories: Set<string>;
21
22
  routingDirectories: Set<string>;
22
23
  }>;
24
+ export declare function readLegacySnapshotSource(absolutePath: string, guardReserved: ReturnType<typeof reservedIgnoreTargetGuard>, signal?: AbortSignal): Promise<Buffer<ArrayBuffer>>;
23
25
  export declare function isSessionPath(relativePath: string): boolean;
24
26
  export declare function isSessionFilePath(relativePath: string): boolean;
25
27
  export declare function sessionSnapshotPathFromAbsolute(sessionFile: string, configuredSessionDir?: string): string | undefined;