@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,25 +1,43 @@
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 path from "node:path";
4
5
  import { withEngineMutationQueue as withFileMutationQueue } from "../host.js";
5
6
  import { agentDir } from "../snapshot/session-paths.js";
6
- import { createSnapshot, snapshotTarget } from "../snapshot/snapshot.js";
7
+ import { agentDirectoryConfiguredSessionDir, agentDirectoryInventory, createSnapshot, snapshotTarget, } from "../snapshot/snapshot.js";
7
8
  import { preflightSnapshotApply, preflightSnapshotMutations } from "../snapshot/snapshot-apply.js";
9
+ import { assertAgentDirectorySnapshotBound, MAX_AGENT_DIRECTORY_BYTES } from "../snapshot/snapshot-bounds.js";
10
+ import { assertProjectedAgentDirectoryBudget, recheckAgentDirectoryBudget, } from "../snapshot/snapshot-entry-projection.js";
8
11
  import { assertUnexcludedTargets } from "../snapshot/snapshot-exclude-safety.js";
9
12
  import { assertCanonicalMutationTargets } from "../snapshot/snapshot-mutation-queues.js";
10
13
  import { sessionStorageRoot } from "../snapshot/snapshot-paths.js";
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";
11
17
  import { syncDirectory } from "../state/json-file.js";
12
18
  import { syncMutationParents } from "../state/mutation-directory-sync.js";
13
19
  import { mergePathIdentity } from "./file-merge-planner.js";
20
+ import { configuredSnapshotPathMatcher } from "./sync-policy.js";
14
21
  import { fileHashMap } from "./sync-state.js";
15
22
  /** Read-only filesystem applicability check before publishing a combined result. */
16
23
  export async function preflightMergedTargets(before, after, options, protectedTarget) {
24
+ if (options.scope === "agent-directory")
25
+ assertAgentDirectorySnapshotBound(after.files);
17
26
  const root = agentDir();
27
+ const scan = options.scope === "agent-directory"
28
+ ? (agentDirectoryInventory(before) ?? agentDirectoryInventory(await createSnapshot(before.profile, options)))
29
+ : undefined;
30
+ if (scan)
31
+ options = { ...options, sessionDir: scan.sessionRoot };
18
32
  const beforeHashes = Object.assign(Object.create(null), fileHashMap(before));
19
33
  const afterHashes = Object.assign(Object.create(null), fileHashMap(after));
20
34
  const paths = [...new Set([...Object.keys(beforeHashes), ...Object.keys(afterHashes)])].sort();
21
35
  const changed = new Set(paths.filter((item) => beforeHashes[item] !== afterHashes[item]));
22
- await assertUnexcludedTargets(root, [...changed].map((item) => snapshotTarget(root, item, options.sessionDir)), options);
36
+ requireManagedChanges(changed, options);
37
+ const targets = [...changed].map((item) => snapshotTarget(root, item, options.sessionDir));
38
+ if (options.scope === "agent-directory")
39
+ await assertCanonicalMutationTargets(targets, options);
40
+ await assertUnexcludedTargets(root, targets, options);
23
41
  await assertCanonicalMergedTargets(root, changed, options);
24
42
  await assertDistinctMergedTargets(root, paths, changed, options, protectedTarget, new Set(Object.keys(afterHashes)));
25
43
  const removed = replacementPaths(new Set(paths.filter((item) => changed.has(item) && !afterHashes[item])), afterHashes);
@@ -28,7 +46,26 @@ export async function preflightMergedTargets(before, after, options, protectedTa
28
46
  if (changed.has(relative))
29
47
  await assertFilesystemTarget(root, relative, options, removedTargets, beforeHashes);
30
48
  }
31
- await assertCanonicalMutationTargets([...changed].map((relative) => snapshotTarget(root, relative, options.sessionDir)), options);
49
+ await assertCanonicalMutationTargets(targets, options);
50
+ if (scan) {
51
+ assertProjectedAgentDirectoryBudget(scan, {
52
+ deletes: [...removedTargets],
53
+ writes: after.files
54
+ .filter((file) => changed.has(file.path))
55
+ .map((file) => ({
56
+ target: snapshotTarget(root, file.path, options.sessionDir),
57
+ size: snapshotBase64Size(file.contentBase64, file.path),
58
+ })),
59
+ }, options);
60
+ }
61
+ }
62
+ function requireManagedChanges(paths, options) {
63
+ if (options.scope !== "agent-directory")
64
+ return;
65
+ const configured = configuredSnapshotPathMatcher(options);
66
+ for (const relative of paths)
67
+ if (!configured(relative))
68
+ throw new Error("A merged transfer targets a path outside the configured policy.");
32
69
  }
33
70
  function replacementPaths(removed, afterHashes) {
34
71
  for (const relative of [...removed]) {
@@ -95,22 +132,52 @@ async function assertDistinctMergedTargets(root, paths, changed, options, protec
95
132
  keys.set(key, relative);
96
133
  }
97
134
  }
98
- async function assertReviewedTree(directory, relative, beforeHashes) {
135
+ async function hashReviewedFile(target, stat, options) {
136
+ if (options.scope !== "agent-directory")
137
+ return createHash("sha256")
138
+ .update(await fs.readFile(target))
139
+ .digest("hex");
140
+ const handle = await fs.open(target, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
141
+ try {
142
+ const opened = await handle.stat();
143
+ options.signal?.throwIfAborted();
144
+ options.validateMutation?.();
145
+ if (!opened.isFile() || opened.nlink !== 1 || opened.dev !== stat.dev || opened.ino !== stat.ino)
146
+ throw new Error("Reviewed file changed at the merge boundary.");
147
+ const hash = createHash("sha256");
148
+ let total = 0;
149
+ for await (const bytes of handle.createReadStream({ autoClose: false, signal: options.signal })) {
150
+ options.signal?.throwIfAborted();
151
+ options.validateMutation?.();
152
+ total += bytes.length;
153
+ if (total > MAX_AGENT_DIRECTORY_BYTES)
154
+ throw new Error("Reviewed file exceeds the merge byte limit.");
155
+ hash.update(bytes);
156
+ }
157
+ return hash.digest("hex");
158
+ }
159
+ finally {
160
+ await handle.close();
161
+ }
162
+ }
163
+ async function assertReviewedTree(directory, relative, beforeHashes, options, removedTargets) {
99
164
  for (const name of await fs.readdir(directory)) {
165
+ options.signal?.throwIfAborted();
166
+ options.validateMutation?.();
100
167
  const child = path.join(directory, name);
101
168
  const childRelative = `${relative}/${name}`;
102
169
  const stat = await fs.lstat(child);
170
+ options.signal?.throwIfAborted();
171
+ options.validateMutation?.();
103
172
  if (stat.isDirectory()) {
104
- await assertReviewedTree(child, childRelative, beforeHashes);
105
- }
106
- else if (stat.isFile() &&
107
- stat.nlink === 1 &&
108
- beforeHashes[childRelative] ===
109
- createHash("sha256")
110
- .update(await fs.readFile(child))
111
- .digest("hex")) {
173
+ if (options.scope === "agent-directory" && (!removedTargets.has(child) || beforeHashes[childRelative]))
174
+ throw new Error("Reviewed directory contains an unreviewed directory; use a reviewed directional transfer.");
175
+ await assertReviewedTree(child, childRelative, beforeHashes, options, removedTargets);
112
176
  }
113
- else {
177
+ else if (!stat.isFile() ||
178
+ stat.nlink !== 1 ||
179
+ beforeHashes[childRelative] === undefined ||
180
+ beforeHashes[childRelative] !== (await hashReviewedFile(child, stat, options))) {
114
181
  throw new Error("Reviewed directory contains unknown or changed files; publication refused.");
115
182
  }
116
183
  }
@@ -146,47 +213,65 @@ async function assertFilesystemTarget(root, relative, options, removedTargets =
146
213
  const boundary = relative.startsWith("sessions/") && options.sessionDir
147
214
  ? path.resolve(sessionStorageRoot(root, options.sessionDir))
148
215
  : path.resolve(root);
216
+ const parents = [];
149
217
  for (let parent = path.dirname(target); mergePathIdentity(parent) !== mergePathIdentity(boundary); parent = path.dirname(parent)) {
150
- options.signal?.throwIfAborted();
151
218
  if (path.dirname(parent) === parent)
152
219
  throw new Error("Unowned merged target.");
220
+ parents.push(parent);
221
+ }
222
+ const statTarget = async (file) => {
223
+ options.signal?.throwIfAborted();
224
+ options.validateMutation?.();
153
225
  try {
154
- const stat = await fs.lstat(parent);
155
- if ((!stat.isDirectory() || stat.isSymbolicLink()) &&
156
- !(stat.isFile() && stat.nlink === 1 && removedTargets.has(parent)))
157
- throw new Error("Unsafe merge filesystem layout; review the selected paths before transfer.");
226
+ return await fs.lstat(file);
158
227
  }
159
228
  catch (error) {
160
- const code = error.code;
161
- if (code !== "ENOENT")
229
+ if (error.code !== "ENOENT")
162
230
  throw error;
231
+ return undefined;
163
232
  }
233
+ finally {
234
+ options.signal?.throwIfAborted();
235
+ options.validateMutation?.();
236
+ }
237
+ };
238
+ for (const parent of parents.reverse()) {
239
+ const stat = await statTarget(parent);
240
+ if (!stat || stat.isDirectory())
241
+ continue;
242
+ if (stat.isFile() && stat.nlink === 1 && removedTargets.has(parent))
243
+ return;
244
+ throw new Error("Unsafe merge filesystem layout; review the selected paths before transfer.");
164
245
  }
165
- options.signal?.throwIfAborted();
166
- try {
167
- const stat = await fs.lstat(target);
168
- if ((!stat.isFile() && !removedTargets.has(target)) || (stat.isFile() && stat.nlink > 1))
169
- throw new Error("Merge target is non-regular or hard-linked; review a directional operation before transfer.");
170
- if (stat.isDirectory() && beforeHashes)
171
- await assertReviewedTree(target, relative, beforeHashes);
172
- }
173
- catch (error) {
174
- const code = error.code;
175
- if (code !== "ENOENT" && !(code === "ENOTDIR" && removedTargets.size > 0))
176
- throw error;
177
- }
246
+ const stat = await statTarget(target);
247
+ if (!stat)
248
+ return;
249
+ if ((!stat.isFile() && !removedTargets.has(target)) || (stat.isFile() && stat.nlink > 1))
250
+ throw new Error("Merge target is non-regular or hard-linked; review a directional operation before transfer.");
251
+ if (stat.isDirectory() && beforeHashes)
252
+ await assertReviewedTree(target, relative, beforeHashes, options, removedTargets);
178
253
  }
179
254
  /** Roll forward only while each target is still its reviewed preimage or committed postimage. */
180
255
  export async function applyMergedSnapshot(before, after, protectedPaths, options, validate, protectedTarget) {
256
+ const validateIgnore = ignorePolicyValidator(options);
181
257
  const root = agentDir();
258
+ if (options.scope === "agent-directory" && options.sessionDir === undefined) {
259
+ options = {
260
+ ...options,
261
+ sessionDir: sessionStorageRoot(root, await agentDirectoryConfiguredSessionDir(options.signal, root)),
262
+ };
263
+ options.validateMutation?.();
264
+ options.signal?.throwIfAborted();
265
+ }
182
266
  const beforeHashes = Object.assign(Object.create(null), fileHashMap(before));
183
267
  const afterHashes = Object.assign(Object.create(null), fileHashMap(after));
184
268
  const paths = [...new Set([...Object.keys(beforeHashes), ...Object.keys(afterHashes)])].sort();
185
269
  const replacements = replacementPaths(new Set(paths.filter((item) => beforeHashes[item] && !afterHashes[item])), afterHashes);
270
+ const replacementTargets = new Set([...replacements].map((relative) => snapshotTarget(root, relative, options.sessionDir)));
186
271
  const intermediateDirectories = [...replacements].filter((item) => !beforeHashes[item] && !afterHashes[item]);
187
- const changed = [
188
- ...new Set([...paths.filter((item) => beforeHashes[item] !== afterHashes[item]), ...intermediateDirectories]),
189
- ].sort();
272
+ const changedFiles = paths.filter((item) => beforeHashes[item] !== afterHashes[item]);
273
+ requireManagedChanges(changedFiles, options);
274
+ const changed = [...new Set([...changedFiles, ...intermediateDirectories])].sort();
190
275
  const protectedKeys = new Set([...protectedPaths].map(mergePathIdentity));
191
276
  if (changed.some((item) => protectedKeys.has(mergePathIdentity(item)))) {
192
277
  throw new Error("A merged transfer targets the current session; review is required.");
@@ -197,6 +282,8 @@ export async function applyMergedSnapshot(before, after, protectedPaths, options
197
282
  const targetSet = new Set(targets);
198
283
  await assertDistinctMergedTargets(root, paths, new Set(changed), options, protectedTarget, new Set(Object.keys(afterHashes)));
199
284
  await assertCanonicalMutationTargets(targets, options);
285
+ if (options.scope === "agent-directory")
286
+ await assertUnexcludedTargets(root, targets, options);
200
287
  // Existing case aliases share Pi's non-reentrant realpath queue. Reserve the
201
288
  // missing destination separately only after deleting its reviewed preimage.
202
289
  const targetsByQueue = new Map();
@@ -228,6 +315,8 @@ export async function applyMergedSnapshot(before, after, protectedPaths, options
228
315
  if (target)
229
316
  return withFileMutationQueue(target, () => acquire(index + 1));
230
317
  await validate();
318
+ if (validateIgnore)
319
+ await validateIgnore();
231
320
  await assertCanonicalMergedTargets(root, changed, options);
232
321
  await validate();
233
322
  const current = await createSnapshot(before.profile, options);
@@ -255,6 +344,15 @@ export async function applyMergedSnapshot(before, after, protectedPaths, options
255
344
  const plan = preflightSnapshotApply(root, after, current, options);
256
345
  plan.writes = plan.writes.filter((item) => targetSet.has(item.target));
257
346
  plan.deletes = plan.deletes.filter((target) => targetSet.has(target));
347
+ if (options.scope === "agent-directory") {
348
+ const written = new Set(plan.writes.map((item) => item.target));
349
+ const replaced = new Set([...plan.deletes, ...written]);
350
+ const targetFor = (relative) => snapshotTarget(root, relative, options.sessionDir);
351
+ assertAgentDirectorySnapshotBound([
352
+ ...current.files.filter((file) => !replaced.has(targetFor(file.path))),
353
+ ...after.files.filter((file) => written.has(targetFor(file.path))),
354
+ ]);
355
+ }
258
356
  await preflightSnapshotMutations(root, plan, options.sessionDir, options);
259
357
  const deletedTargets = new Set(plan.deletes);
260
358
  for (const relative of intermediateDirectories) {
@@ -265,32 +363,64 @@ export async function applyMergedSnapshot(before, after, protectedPaths, options
265
363
  }
266
364
  }
267
365
  }
366
+ const scan = agentDirectoryInventory(current);
367
+ if (scan) {
368
+ for (const { target } of plan.writes) {
369
+ if (!deletedTargets.has(target))
370
+ continue;
371
+ const relative = relativeByTarget.get(target);
372
+ if (!relative)
373
+ throw new Error("Unowned merge write target.");
374
+ await assertFilesystemTarget(root, relative, options, replacementTargets, beforeHashes);
375
+ }
376
+ assertProjectedAgentDirectoryBudget(scan, { deletes: plan.deletes, writes: plan.writes.map(({ target, content }) => ({ target, size: content.length })) }, options);
377
+ }
268
378
  // A parent must remain until every reviewed leaf and intermediate directory is gone.
269
379
  plan.deletes.sort((left, right) => right.split(path.sep).length - left.split(path.sep).length || left.localeCompare(right));
270
- const removed = replacementPaths(new Set(paths.filter((relative) => deletedTargets.has(snapshotTarget(root, relative, options.sessionDir)))), afterHashes);
380
+ const removed = scan
381
+ ? replacements
382
+ : replacementPaths(new Set(paths.filter((relative) => deletedTargets.has(snapshotTarget(root, relative, options.sessionDir)))), afterHashes);
271
383
  const removedTargets = new Set([...removed].map((item) => snapshotTarget(root, item, options.sessionDir)));
272
384
  await assertCanonicalMergedTargets(root, changed, options);
273
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
+ };
274
390
  const revalidateTarget = async (target) => {
275
391
  await validate();
276
392
  const relative = relativeByTarget.get(target);
277
393
  if (!relative)
278
394
  throw new Error("Unowned merge target.");
395
+ if (options.scope === "agent-directory") {
396
+ await assertCanonicalMutationTargets([target], options);
397
+ await assertUnexcludedTargets(root, [target], options);
398
+ }
279
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
+ }
280
409
  await validate();
410
+ let kind = "missing";
281
411
  let hash;
282
412
  try {
283
413
  const stat = await fs.lstat(target);
284
414
  if (stat.isDirectory() && removed.has(relative)) {
415
+ kind = "directory";
285
416
  if ((await fs.readdir(target)).length)
286
417
  throw new Error("Reviewed directory has remaining contents; journal retained for review.");
287
418
  }
288
419
  else {
289
420
  if (!stat.isFile() || stat.nlink > 1)
290
421
  throw new Error("Merged transfer target is no longer an independent regular file.");
291
- hash = createHash("sha256")
292
- .update(await fs.readFile(target))
293
- .digest("hex");
422
+ hash = await hashReviewedFile(target, stat, options);
423
+ kind = "file";
294
424
  }
295
425
  }
296
426
  catch (error) {
@@ -299,17 +429,22 @@ export async function applyMergedSnapshot(before, after, protectedPaths, options
299
429
  }
300
430
  options.signal?.throwIfAborted();
301
431
  options.validateMutation?.();
302
- if (hash !== beforeHashes[relative] && hash !== afterHashes[relative])
303
- throw new Error("Local content changed at the apply boundary; journal retained, newer bytes untouched.");
432
+ requireReviewedHash(relative, hash);
433
+ return kind;
304
434
  };
435
+ if (options.scope === "agent-directory" && plan.deletes.length)
436
+ await recheckAgentDirectoryBudget(root, plan, options);
305
437
  for (const target of plan.deletes) {
306
- await revalidateTarget(target);
438
+ let kind = await revalidateTarget(target);
307
439
  try {
308
- const stat = await fs.lstat(target);
309
- await validate();
310
- 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")
311
446
  await fs.rmdir(target); // Only an empty, reviewed directory may be replaced.
312
- else
447
+ else if (kind === "file")
313
448
  await fs.rm(target, { force: true });
314
449
  }
315
450
  catch (error) {
@@ -340,16 +475,24 @@ export async function applyMergedSnapshot(before, after, protectedPaths, options
340
475
  // Writers registered after deletion must finish first; never accept their
341
476
  // bytes as our own, even if they match a recognizable pre/postimage.
342
477
  await requireAbsentDestinations();
478
+ if (validateIgnore)
479
+ await validateIgnore();
343
480
  await writeTargets();
344
481
  }
345
482
  await requireAbsentDestinations();
346
483
  await acquireDestinations(0);
347
484
  async function writeTargets() {
485
+ if (plan.writes.length && options.scope === "agent-directory") {
486
+ await validate();
487
+ await recheckAgentDirectoryBudget(root, { deletes: [], writes: plan.writes }, options);
488
+ }
348
489
  for (const item of plan.writes) {
349
490
  await validate();
350
491
  const relative = relativeByTarget.get(item.target);
351
492
  if (!relative)
352
493
  throw new Error("Unowned merge write target.");
494
+ if (validateIgnore)
495
+ await validateIgnore();
353
496
  await assertFilesystemTarget(root, relative, options, new Set());
354
497
  await fs.mkdir(path.dirname(item.target), { recursive: true });
355
498
  const temporary = path.join(path.dirname(item.target), `.pi-sync.json.${randomUUID()}.apply`);
@@ -1,9 +1,18 @@
1
- import type { RemoteHead } from "../backends/sync-backend.js";
1
+ import type { RemoteHead, SyncBackend } from "../backends/sync-backend.js";
2
+ import type { CommandOptions } from "../commands/command-types.js";
3
+ import type { EngineContext } from "../host.js";
2
4
  import type { AnySyncConfig } from "../settings/settings-types.js";
3
- import type { Snapshot } from "../snapshot/snapshot-types.js";
5
+ import { type TransactionJournalPolicy } from "../snapshot/snapshot-transaction-policy.js";
6
+ import { type Snapshot } from "../snapshot/snapshot-types.js";
4
7
  import type { PartialProgress } from "./partial-progress.js";
5
- export interface MergeJournal {
8
+ type MergeJournalPolicy = {
6
9
  version: 1;
10
+ ignoreSource?: never;
11
+ } | {
12
+ version: 2;
13
+ ignoreSource: NonNullable<TransactionJournalPolicy["ignoreSource"]>;
14
+ };
15
+ export type MergeJournal = MergeJournalPolicy & {
7
16
  identity: string;
8
17
  before: Snapshot;
9
18
  after: Snapshot;
@@ -19,13 +28,18 @@ export interface MergeJournal {
19
28
  /** Effective collection/apply root; absent legacy evidence cannot authorize session recovery. */
20
29
  sessionRoot?: string;
21
30
  warnings?: string[];
22
- }
31
+ };
32
+ export declare function mergeJournalPolicy(config: AnySyncConfig): MergeJournalPolicy;
33
+ export declare function assertMergeJournalPolicy(journal: MergeJournal, config: AnySyncConfig): void;
23
34
  export declare function mergeJournalIdentity(config: AnySyncConfig, backendIdentity: string): string;
24
35
  export declare function mergeJournalPath(config: AnySyncConfig): string;
25
36
  export declare function readMergeJournal(config: AnySyncConfig): Promise<MergeJournal | undefined>;
26
37
  export declare function writeMergeJournal(config: AnySyncConfig, journal: MergeJournal): Promise<void>;
27
38
  export declare function clearMergeJournal(config: AnySyncConfig): Promise<void>;
28
39
  export declare function retireMergeJournal(config: AnySyncConfig): Promise<void>;
40
+ export declare function reviewInactiveIgnoreMerge(ctx: EngineContext, config: AnySyncConfig, backend: SyncBackend, journal: MergeJournal, head: RemoteHead, options: CommandOptions, validateFresh: () => Promise<void>, isCurrent?: () => boolean): Promise<"archived" | "cancelled">;
41
+ export declare function sameMergeRecoveryHead(backend: SyncBackend, left: RemoteHead | undefined, right: RemoteHead | undefined): boolean;
29
42
  export declare function requireNoMergeJournal(config: AnySyncConfig, options?: {
30
43
  force?: boolean;
31
44
  }): Promise<void>;
45
+ export {};
@@ -1,21 +1,65 @@
1
1
  import { randomUUID } from "node:crypto";
2
2
  import fs from "node:fs/promises";
3
3
  import path from "node:path";
4
+ import { assertRecoveryPolicy, IGNORE_POLICY_JOURNAL_VERSION, ignorePolicyValidator, ignoreSourceBinding, validateJournalPolicy, } from "../snapshot/snapshot-transaction-policy.js";
5
+ import { IGNORE_SNAPSHOT_VERSION } from "../snapshot/snapshot-types.js";
4
6
  import { readJsonIfExists, syncDirectory, writeJson } from "../state/json-file.js";
5
- import { statePathForConfig, syncStateFingerprint } from "../state/sync-state-store.js";
7
+ import { readStateForConfig, statePathForConfig, syncStateFingerprint } from "../state/sync-state-store.js";
8
+ import { confirmMergeReview } from "../ui/merge-review.js";
9
+ import { safeTerminalText } from "../ui/terminal-text.js";
6
10
  import { normalizeSyncExclude } from "./exclude-policy.js";
7
11
  import { planFileMerge } from "./file-merge-planner.js";
8
12
  import { portableSnapshot, sameLocalFields, validatePortableSnapshot, validateSnapshotFieldPolicy, } from "./local-fields.js";
13
+ import { configuredSnapshotPathMatcher, sameSnapshotSelection, syncDirectoryPolicyKey, validateSnapshotSelection, } from "./sync-policy.js";
9
14
  import { fileHashMap, sameHashes } from "./sync-state.js";
15
+ export function mergeJournalPolicy(config) {
16
+ return config.ignorePolicy ? { version: 2, ignoreSource: ignoreSourceBinding(config.ignorePolicy) } : { version: 1 };
17
+ }
18
+ function ignoreRecoveryPolicy(journal) {
19
+ return {
20
+ version: IGNORE_POLICY_JOURNAL_VERSION,
21
+ ignoreSource: journal.ignoreSource,
22
+ selection: journal.upload.selection,
23
+ };
24
+ }
25
+ export function assertMergeJournalPolicy(journal, config) {
26
+ if (journal.version === 1 && !config.ignorePolicy && config.pathPolicy !== "ignore-file")
27
+ return;
28
+ if (journal.version !== 2)
29
+ throw new Error("Pending merge lacks ignore-file policy evidence; preserve its journal for reviewed recovery.");
30
+ assertRecoveryPolicy(ignoreRecoveryPolicy(journal), config);
31
+ try {
32
+ const identity = JSON.parse(journal.identity);
33
+ if (!Array.isArray(identity) ||
34
+ typeof identity[1] !== "string" ||
35
+ journal.identity !== mergeJournalIdentity(config, identity[1]))
36
+ throw new Error("Inconsistent merge identity.");
37
+ }
38
+ catch {
39
+ throw new Error("Pending merge belongs to a different setup or local policy; preserve its journal.");
40
+ }
41
+ const configured = configuredSnapshotPathMatcher(config);
42
+ for (const snapshot of [
43
+ journal.before,
44
+ journal.after,
45
+ journal.accepted,
46
+ journal.applyOnly ? undefined : journal.upload,
47
+ ]) {
48
+ if (snapshot?.files.some((file) => !configured(file.path)))
49
+ throw new Error("Pending merge contains paths outside the current ignore-file policy; preserve its journal.");
50
+ }
51
+ }
10
52
  export function mergeJournalIdentity(config, backendIdentity) {
11
53
  return JSON.stringify([
12
54
  config.setupName,
13
55
  backendIdentity,
14
56
  [...config.include].sort(),
15
57
  config.localFields ?? null,
16
- ...(config.exclude === undefined
17
- ? []
18
- : ["exclude", normalizeSyncExclude(config.exclude).map((rule) => rule.toLowerCase())]),
58
+ ...(config.scope === "agent-directory"
59
+ ? [syncDirectoryPolicyKey(config)]
60
+ : config.exclude === undefined
61
+ ? []
62
+ : ["exclude", normalizeSyncExclude(config.exclude).map((rule) => rule.toLowerCase())]),
19
63
  ]);
20
64
  }
21
65
  export function mergeJournalPath(config) {
@@ -35,9 +79,11 @@ export async function readMergeJournal(config) {
35
79
  // A JSON parser error may quote sensitive journal contents; do not retain it in a public error.
36
80
  throw new Error("Cannot read the private merge journal; preserve it and review recovery.");
37
81
  }
38
- if (!journal)
82
+ if (journal === undefined)
39
83
  return;
40
- if (journal.version !== 1 ||
84
+ if (!journal ||
85
+ (journal.version !== 1 && journal.version !== 2) ||
86
+ (journal.version === 1 && journal.ignoreSource !== undefined) ||
41
87
  typeof journal.identity !== "string" ||
42
88
  typeof journal.backup !== "string" ||
43
89
  typeof journal.stateIdentity !== "string" ||
@@ -66,6 +112,11 @@ export async function readMergeJournal(config) {
66
112
  throw new Error("Unsupported or damaged merge journal; preserve it and review recovery before syncing.");
67
113
  // Verify every path and byte, including the unmanaged remote files retained for publication.
68
114
  try {
115
+ if (journal.version === 2) {
116
+ validateJournalPolicy(ignoreRecoveryPolicy(journal));
117
+ if ([journal.expectedHead.selection, journal.committedHead?.selection].some((selection) => selection !== undefined && !sameSnapshotSelection(selection, journal.upload.selection)))
118
+ throw new Error("Inconsistent merge head policy.");
119
+ }
69
120
  const pinnedPaths = new Set(journal.progress?.groups.flatMap((group) => group.paths) ?? []);
70
121
  for (const snapshot of [
71
122
  journal.before,
@@ -74,13 +125,22 @@ export async function readMergeJournal(config) {
74
125
  ...(journal.accepted ? [journal.accepted] : []),
75
126
  ]) {
76
127
  validateSnapshotFieldPolicy(snapshot);
77
- if ((snapshot.version !== 1 && snapshot.version !== 2 && snapshot.version !== 3 && snapshot.version !== 4) ||
128
+ validateSnapshotSelection(snapshot);
129
+ if ((journal.version === 2
130
+ ? snapshot.version !== IGNORE_SNAPSHOT_VERSION ||
131
+ !sameSnapshotSelection(snapshot.selection, journal.upload.selection)
132
+ : ![1, 2, 3, 4, 5].includes(snapshot.version)) ||
78
133
  typeof snapshot.id !== "string" ||
79
134
  typeof snapshot.profile !== "string" ||
80
135
  snapshot.files.length > 16_384 ||
81
136
  snapshot.files.reduce((bytes, file) => bytes + (typeof file?.contentBase64 === "string" ? file.contentBase64.length * 0.75 : Infinity), 0) >
82
137
  64 * 1024 * 1024)
83
138
  throw new Error("Invalid journal input.");
139
+ if (snapshot.selection?.scope) {
140
+ const configured = configuredSnapshotPathMatcher(snapshot.selection);
141
+ if (snapshot.files.some((file) => typeof file?.path !== "string" || !configured(file.path)))
142
+ throw new Error("Journal retains paths outside its recorded directory policy.");
143
+ }
84
144
  const plan = planFileMerge({ baseline: {}, local: snapshot.files, remote: [], selectionCompatible: true });
85
145
  if (plan.kind !== "planned" ||
86
146
  plan.conflicts.some((conflict) => conflict.reason !== "path-collision" || !pinnedPaths.has(conflict.path)))
@@ -163,17 +223,73 @@ export async function clearMergeJournal(config) {
163
223
  await syncDirectory(path.dirname(mergeJournalPath(config)));
164
224
  }
165
225
  export async function retireMergeJournal(config) {
166
- if (!(await readMergeJournal(config)))
226
+ const journal = await readMergeJournal(config);
227
+ if (!journal)
167
228
  return;
229
+ assertMergeJournalPolicy(journal, config);
230
+ const validateIgnore = ignorePolicyValidator(config);
231
+ if (validateIgnore)
232
+ await validateIgnore();
233
+ if (journal.version === 2)
234
+ throw new Error(ignoreMergeRecoveryGuidance);
235
+ await archiveMergeJournal(config);
236
+ }
237
+ async function archiveMergeJournal(config) {
168
238
  const file = mergeJournalPath(config);
169
239
  await fs.rename(file, `${file}.${randomUUID()}.resolved`);
170
240
  await syncDirectory(path.dirname(file));
171
241
  }
242
+ export async function reviewInactiveIgnoreMerge(ctx, config, backend, journal, head, options, validateFresh, isCurrent) {
243
+ if (!isCurrent ||
244
+ options.auto ||
245
+ options.background ||
246
+ options.agentAcceptance ||
247
+ options.yes ||
248
+ !ctx.hasUI ||
249
+ (ctx.mode !== "tui" && ctx.mode !== "rpc")) {
250
+ throw new Error(ignoreMergeRecoveryGuidance);
251
+ }
252
+ await validateFresh();
253
+ if (!(await confirmMergeReview(ctx, "Archive the inactive merge journal?", [
254
+ `Setup: ${safeTerminalText(config.setupName)}`,
255
+ "The original remote head and accepted baseline still match the journal, but local files changed.",
256
+ "Archive only the journal. Keep its backup and all current local and remote files. Do not change the baseline.",
257
+ "Run Sync now again to review a fresh plan.",
258
+ ].join("\n"), options.signal, isCurrent, "archive journal only")))
259
+ return "cancelled";
260
+ const state = await readStateForConfig(config);
261
+ await validateFresh();
262
+ const latest = await backend.readHead(options.signal);
263
+ if (!isCurrent())
264
+ return "cancelled";
265
+ if (!sameMergeRecoveryHead(backend, head, latest) || syncStateFingerprint(state) !== journal.stateIdentity) {
266
+ throw new Error("Remote head or sync baseline changed during recovery review; journal and backup retained.");
267
+ }
268
+ await archiveMergeJournal(config);
269
+ if (!options.silent && isCurrent())
270
+ ctx.ui.notify("Archived the inactive merge journal. Local files, remote files, baseline and backup were kept. Run Sync now again for a fresh plan.", "info");
271
+ return "archived";
272
+ }
273
+ export function sameMergeRecoveryHead(backend, left, right) {
274
+ if (!left || !right)
275
+ return left === right;
276
+ return (backend.sameRevision(left.revision, right.revision) &&
277
+ left.snapshotId === right.snapshotId &&
278
+ left.snapshotRef === right.snapshotRef &&
279
+ sameSnapshotSelection(left.selection, right.selection));
280
+ }
281
+ const ignoreMergeRecoveryGuidance = "An ignore-file merged transfer needs recovery; directional --force cannot bypass it. Inactive journal archiving requires foreground review where supported; --yes does not approve it. Preserve the journal, backup and current files if recovery is unavailable. Do not downgrade or restore old bytes blindly.";
172
282
  export async function requireNoMergeJournal(config, options = {}) {
173
283
  const journal = await readMergeJournal(config);
174
- if (options.force || !journal)
284
+ if (!journal)
175
285
  return;
176
- if (journal) {
286
+ assertMergeJournalPolicy(journal, config);
287
+ const validateIgnore = ignorePolicyValidator(config);
288
+ if (validateIgnore)
289
+ await validateIgnore();
290
+ if (journal.version === 2)
291
+ throw new Error(ignoreMergeRecoveryGuidance);
292
+ if (!options.force) {
177
293
  throw new Error("A merged transfer needs recovery. Run /sync sync to reconcile it. If newer local edits or remote revisions prevent recovery, review /sync diff and explicitly choose push --force or pull --force; the selected directional result will archive the old journal, not restore old bytes. Keep its backup; do not downgrade while recovery is pending.");
178
294
  }
179
295
  }
@@ -3,4 +3,4 @@ import type { CommandOptions } from "../commands/command-types.js";
3
3
  import type { EngineContext as ExtensionCommandContext, EngineContext as ExtensionContext } from "../host.js";
4
4
  import { type ConflictResolution } from "./conflict-resolution.js";
5
5
  /** Established-baseline sync only. First-source selection remains in the existing command flow. */
6
- export declare function mergeSync(ctx: ExtensionContext | ExtensionCommandContext, options: CommandOptions, factory?: SyncBackendFactory, resolution?: ConflictResolution): Promise<"applied" | "cancelled" | undefined>;
6
+ export declare function mergeSync(ctx: ExtensionContext | ExtensionCommandContext, options: CommandOptions, factory?: SyncBackendFactory, resolution?: ConflictResolution): Promise<"applied" | "archived" | "cancelled" | undefined>;