@narumitw/pi-sync-daemon 0.6.2 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. package/CHANGELOG.md +8 -0
  2. package/README.md +1 -1
  3. package/dist/consent.js +11 -1
  4. package/dist/engine/backends/git/git-storage.js +11 -6
  5. package/dist/engine/paths.js +1 -1
  6. package/dist/engine/settings/config-file.js +2 -0
  7. package/dist/engine/settings/config.d.ts +2 -4
  8. package/dist/engine/settings/config.js +22 -7
  9. package/dist/engine/settings/settings-management.d.ts +2 -2
  10. package/dist/engine/settings/settings-management.js +27 -33
  11. package/dist/engine/settings/settings-types.d.ts +18 -4
  12. package/dist/engine/settings/settings-validation.js +34 -24
  13. package/dist/engine/snapshot/session-paths.d.ts +5 -3
  14. package/dist/engine/snapshot/session-paths.js +55 -9
  15. package/dist/engine/snapshot/snapshot-apply.d.ts +6 -7
  16. package/dist/engine/snapshot/snapshot-apply.js +88 -21
  17. package/dist/engine/snapshot/snapshot-bounds.d.ts +4 -0
  18. package/dist/engine/snapshot/snapshot-bounds.js +20 -0
  19. package/dist/engine/snapshot/snapshot-codec.js +3 -4
  20. package/dist/engine/snapshot/snapshot-entry-projection.d.ts +10 -0
  21. package/dist/engine/snapshot/snapshot-entry-projection.js +78 -0
  22. package/dist/engine/snapshot/snapshot-exclude-safety.d.ts +7 -2
  23. package/dist/engine/snapshot/snapshot-exclude-safety.js +180 -22
  24. package/dist/engine/snapshot/snapshot-payload.d.ts +2 -0
  25. package/dist/engine/snapshot/snapshot-payload.js +10 -0
  26. package/dist/engine/snapshot/snapshot-reviewed-preimages.d.ts +2 -0
  27. package/dist/engine/snapshot/snapshot-reviewed-preimages.js +60 -0
  28. package/dist/engine/snapshot/snapshot-root-transition.d.ts +4 -0
  29. package/dist/engine/snapshot/snapshot-root-transition.js +16 -0
  30. package/dist/engine/snapshot/snapshot-transaction-images.d.ts +37 -0
  31. package/dist/engine/snapshot/snapshot-transaction-images.js +357 -0
  32. package/dist/engine/snapshot/snapshot-transaction-policy.d.ts +50 -0
  33. package/dist/engine/snapshot/snapshot-transaction-policy.js +172 -0
  34. package/dist/engine/snapshot/snapshot-transaction-stage.d.ts +32 -0
  35. package/dist/engine/snapshot/snapshot-transaction-stage.js +303 -0
  36. package/dist/engine/snapshot/snapshot-transaction.d.ts +2 -1
  37. package/dist/engine/snapshot/snapshot-transaction.js +379 -331
  38. package/dist/engine/snapshot/snapshot-types.d.ts +24 -1
  39. package/dist/engine/snapshot/snapshot.d.ts +19 -2
  40. package/dist/engine/snapshot/snapshot.js +283 -26
  41. package/dist/engine/state/merge-baseline-store.js +20 -9
  42. package/dist/engine/state/state-types.d.ts +2 -0
  43. package/dist/engine/sync/apply-review.d.ts +3 -3
  44. package/dist/engine/sync/apply-review.js +5 -4
  45. package/dist/engine/sync/continuous-sync.js +19 -9
  46. package/dist/engine/sync/continuous-watch.d.ts +4 -1
  47. package/dist/engine/sync/continuous-watch.js +86 -14
  48. package/dist/engine/sync/exclude-policy.d.ts +4 -0
  49. package/dist/engine/sync/exclude-policy.js +8 -1
  50. package/dist/engine/sync/initialization.js +9 -5
  51. package/dist/engine/sync/local-fields.js +27 -8
  52. package/dist/engine/sync/merge-apply.js +155 -40
  53. package/dist/engine/sync/merge-journal.js +13 -4
  54. package/dist/engine/sync/merged-sync.js +21 -18
  55. package/dist/engine/sync/partial-progress.js +5 -3
  56. package/dist/engine/sync/remote-snapshot.d.ts +1 -0
  57. package/dist/engine/sync/remote-snapshot.js +8 -5
  58. package/dist/engine/sync/session-push.js +7 -6
  59. package/dist/engine/sync/sync-decision.d.ts +4 -0
  60. package/dist/engine/sync/sync-decision.js +17 -2
  61. package/dist/engine/sync/sync-inspection.js +3 -3
  62. package/dist/engine/sync/sync-mutations.d.ts +8 -1
  63. package/dist/engine/sync/sync-mutations.js +153 -72
  64. package/dist/engine/sync/sync-policy.d.ts +20 -10
  65. package/dist/engine/sync/sync-policy.js +170 -16
  66. package/dist/engine/sync/sync-queries.js +41 -31
  67. package/dist/engine/sync/sync-state.d.ts +11 -0
  68. package/dist/engine/sync/sync-state.js +24 -5
  69. package/dist/engine/ui/sync-format.js +22 -7
  70. package/docs/architecture.md +6 -0
  71. package/package.json +1 -1
@@ -1,25 +1,41 @@
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";
11
15
  import { syncDirectory } from "../state/json-file.js";
12
16
  import { syncMutationParents } from "../state/mutation-directory-sync.js";
13
17
  import { mergePathIdentity } from "./file-merge-planner.js";
18
+ import { configuredSnapshotPathMatcher } from "./sync-policy.js";
14
19
  import { fileHashMap } from "./sync-state.js";
15
20
  /** Read-only filesystem applicability check before publishing a combined result. */
16
21
  export async function preflightMergedTargets(before, after, options, protectedTarget) {
22
+ if (options.scope === "agent-directory")
23
+ assertAgentDirectorySnapshotBound(after.files);
17
24
  const root = agentDir();
25
+ const scan = options.scope === "agent-directory"
26
+ ? (agentDirectoryInventory(before) ?? agentDirectoryInventory(await createSnapshot(before.profile, options)))
27
+ : undefined;
28
+ if (scan)
29
+ options = { ...options, sessionDir: scan.sessionRoot };
18
30
  const beforeHashes = Object.assign(Object.create(null), fileHashMap(before));
19
31
  const afterHashes = Object.assign(Object.create(null), fileHashMap(after));
20
32
  const paths = [...new Set([...Object.keys(beforeHashes), ...Object.keys(afterHashes)])].sort();
21
33
  const changed = new Set(paths.filter((item) => beforeHashes[item] !== afterHashes[item]));
22
- await assertUnexcludedTargets(root, [...changed].map((item) => snapshotTarget(root, item, options.sessionDir)), options);
34
+ requireManagedChanges(changed, options);
35
+ const targets = [...changed].map((item) => snapshotTarget(root, item, options.sessionDir));
36
+ if (options.scope === "agent-directory")
37
+ await assertCanonicalMutationTargets(targets, options);
38
+ await assertUnexcludedTargets(root, targets, options);
23
39
  await assertCanonicalMergedTargets(root, changed, options);
24
40
  await assertDistinctMergedTargets(root, paths, changed, options, protectedTarget, new Set(Object.keys(afterHashes)));
25
41
  const removed = replacementPaths(new Set(paths.filter((item) => changed.has(item) && !afterHashes[item])), afterHashes);
@@ -28,7 +44,26 @@ export async function preflightMergedTargets(before, after, options, protectedTa
28
44
  if (changed.has(relative))
29
45
  await assertFilesystemTarget(root, relative, options, removedTargets, beforeHashes);
30
46
  }
31
- await assertCanonicalMutationTargets([...changed].map((relative) => snapshotTarget(root, relative, options.sessionDir)), options);
47
+ await assertCanonicalMutationTargets(targets, options);
48
+ if (scan) {
49
+ assertProjectedAgentDirectoryBudget(scan, {
50
+ deletes: [...removedTargets],
51
+ writes: after.files
52
+ .filter((file) => changed.has(file.path))
53
+ .map((file) => ({
54
+ target: snapshotTarget(root, file.path, options.sessionDir),
55
+ size: snapshotBase64Size(file.contentBase64, file.path),
56
+ })),
57
+ }, options);
58
+ }
59
+ }
60
+ function requireManagedChanges(paths, options) {
61
+ if (options.scope !== "agent-directory")
62
+ return;
63
+ const configured = configuredSnapshotPathMatcher(options);
64
+ for (const relative of paths)
65
+ if (!configured(relative))
66
+ throw new Error("A merged transfer targets a path outside the configured policy.");
32
67
  }
33
68
  function replacementPaths(removed, afterHashes) {
34
69
  for (const relative of [...removed]) {
@@ -95,22 +130,52 @@ async function assertDistinctMergedTargets(root, paths, changed, options, protec
95
130
  keys.set(key, relative);
96
131
  }
97
132
  }
98
- async function assertReviewedTree(directory, relative, beforeHashes) {
133
+ async function hashReviewedFile(target, stat, options) {
134
+ if (options.scope !== "agent-directory")
135
+ return createHash("sha256")
136
+ .update(await fs.readFile(target))
137
+ .digest("hex");
138
+ const handle = await fs.open(target, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
139
+ try {
140
+ const opened = await handle.stat();
141
+ options.signal?.throwIfAborted();
142
+ options.validateMutation?.();
143
+ if (!opened.isFile() || opened.nlink !== 1 || opened.dev !== stat.dev || opened.ino !== stat.ino)
144
+ throw new Error("Reviewed file changed at the merge boundary.");
145
+ const hash = createHash("sha256");
146
+ let total = 0;
147
+ for await (const bytes of handle.createReadStream({ autoClose: false, signal: options.signal })) {
148
+ options.signal?.throwIfAborted();
149
+ options.validateMutation?.();
150
+ total += bytes.length;
151
+ if (total > MAX_AGENT_DIRECTORY_BYTES)
152
+ throw new Error("Reviewed file exceeds the merge byte limit.");
153
+ hash.update(bytes);
154
+ }
155
+ return hash.digest("hex");
156
+ }
157
+ finally {
158
+ await handle.close();
159
+ }
160
+ }
161
+ async function assertReviewedTree(directory, relative, beforeHashes, options, removedTargets) {
99
162
  for (const name of await fs.readdir(directory)) {
163
+ options.signal?.throwIfAborted();
164
+ options.validateMutation?.();
100
165
  const child = path.join(directory, name);
101
166
  const childRelative = `${relative}/${name}`;
102
167
  const stat = await fs.lstat(child);
168
+ options.signal?.throwIfAborted();
169
+ options.validateMutation?.();
103
170
  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")) {
171
+ if (options.scope === "agent-directory" && (!removedTargets.has(child) || beforeHashes[childRelative]))
172
+ throw new Error("Reviewed directory contains an unreviewed directory; use a reviewed directional transfer.");
173
+ await assertReviewedTree(child, childRelative, beforeHashes, options, removedTargets);
112
174
  }
113
- else {
175
+ else if (!stat.isFile() ||
176
+ stat.nlink !== 1 ||
177
+ beforeHashes[childRelative] === undefined ||
178
+ beforeHashes[childRelative] !== (await hashReviewedFile(child, stat, options))) {
114
179
  throw new Error("Reviewed directory contains unknown or changed files; publication refused.");
115
180
  }
116
181
  }
@@ -146,47 +211,64 @@ async function assertFilesystemTarget(root, relative, options, removedTargets =
146
211
  const boundary = relative.startsWith("sessions/") && options.sessionDir
147
212
  ? path.resolve(sessionStorageRoot(root, options.sessionDir))
148
213
  : path.resolve(root);
214
+ const parents = [];
149
215
  for (let parent = path.dirname(target); mergePathIdentity(parent) !== mergePathIdentity(boundary); parent = path.dirname(parent)) {
150
- options.signal?.throwIfAborted();
151
216
  if (path.dirname(parent) === parent)
152
217
  throw new Error("Unowned merged target.");
218
+ parents.push(parent);
219
+ }
220
+ const statTarget = async (file) => {
221
+ options.signal?.throwIfAborted();
222
+ options.validateMutation?.();
153
223
  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.");
224
+ return await fs.lstat(file);
158
225
  }
159
226
  catch (error) {
160
- const code = error.code;
161
- if (code !== "ENOENT")
227
+ if (error.code !== "ENOENT")
162
228
  throw error;
229
+ return undefined;
163
230
  }
231
+ finally {
232
+ options.signal?.throwIfAborted();
233
+ options.validateMutation?.();
234
+ }
235
+ };
236
+ for (const parent of parents.reverse()) {
237
+ const stat = await statTarget(parent);
238
+ if (!stat || stat.isDirectory())
239
+ continue;
240
+ if (stat.isFile() && stat.nlink === 1 && removedTargets.has(parent))
241
+ return;
242
+ throw new Error("Unsafe merge filesystem layout; review the selected paths before transfer.");
164
243
  }
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
- }
244
+ const stat = await statTarget(target);
245
+ if (!stat)
246
+ return;
247
+ if ((!stat.isFile() && !removedTargets.has(target)) || (stat.isFile() && stat.nlink > 1))
248
+ throw new Error("Merge target is non-regular or hard-linked; review a directional operation before transfer.");
249
+ if (stat.isDirectory() && beforeHashes)
250
+ await assertReviewedTree(target, relative, beforeHashes, options, removedTargets);
178
251
  }
179
252
  /** Roll forward only while each target is still its reviewed preimage or committed postimage. */
180
253
  export async function applyMergedSnapshot(before, after, protectedPaths, options, validate, protectedTarget) {
181
254
  const root = agentDir();
255
+ if (options.scope === "agent-directory" && options.sessionDir === undefined) {
256
+ options = {
257
+ ...options,
258
+ sessionDir: sessionStorageRoot(root, await agentDirectoryConfiguredSessionDir(options.signal, root)),
259
+ };
260
+ options.validateMutation?.();
261
+ options.signal?.throwIfAborted();
262
+ }
182
263
  const beforeHashes = Object.assign(Object.create(null), fileHashMap(before));
183
264
  const afterHashes = Object.assign(Object.create(null), fileHashMap(after));
184
265
  const paths = [...new Set([...Object.keys(beforeHashes), ...Object.keys(afterHashes)])].sort();
185
266
  const replacements = replacementPaths(new Set(paths.filter((item) => beforeHashes[item] && !afterHashes[item])), afterHashes);
267
+ const replacementTargets = new Set([...replacements].map((relative) => snapshotTarget(root, relative, options.sessionDir)));
186
268
  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();
269
+ const changedFiles = paths.filter((item) => beforeHashes[item] !== afterHashes[item]);
270
+ requireManagedChanges(changedFiles, options);
271
+ const changed = [...new Set([...changedFiles, ...intermediateDirectories])].sort();
190
272
  const protectedKeys = new Set([...protectedPaths].map(mergePathIdentity));
191
273
  if (changed.some((item) => protectedKeys.has(mergePathIdentity(item)))) {
192
274
  throw new Error("A merged transfer targets the current session; review is required.");
@@ -197,6 +279,8 @@ export async function applyMergedSnapshot(before, after, protectedPaths, options
197
279
  const targetSet = new Set(targets);
198
280
  await assertDistinctMergedTargets(root, paths, new Set(changed), options, protectedTarget, new Set(Object.keys(afterHashes)));
199
281
  await assertCanonicalMutationTargets(targets, options);
282
+ if (options.scope === "agent-directory")
283
+ await assertUnexcludedTargets(root, targets, options);
200
284
  // Existing case aliases share Pi's non-reentrant realpath queue. Reserve the
201
285
  // missing destination separately only after deleting its reviewed preimage.
202
286
  const targetsByQueue = new Map();
@@ -255,6 +339,15 @@ export async function applyMergedSnapshot(before, after, protectedPaths, options
255
339
  const plan = preflightSnapshotApply(root, after, current, options);
256
340
  plan.writes = plan.writes.filter((item) => targetSet.has(item.target));
257
341
  plan.deletes = plan.deletes.filter((target) => targetSet.has(target));
342
+ if (options.scope === "agent-directory") {
343
+ const written = new Set(plan.writes.map((item) => item.target));
344
+ const replaced = new Set([...plan.deletes, ...written]);
345
+ const targetFor = (relative) => snapshotTarget(root, relative, options.sessionDir);
346
+ assertAgentDirectorySnapshotBound([
347
+ ...current.files.filter((file) => !replaced.has(targetFor(file.path))),
348
+ ...after.files.filter((file) => written.has(targetFor(file.path))),
349
+ ]);
350
+ }
258
351
  await preflightSnapshotMutations(root, plan, options.sessionDir, options);
259
352
  const deletedTargets = new Set(plan.deletes);
260
353
  for (const relative of intermediateDirectories) {
@@ -265,9 +358,23 @@ export async function applyMergedSnapshot(before, after, protectedPaths, options
265
358
  }
266
359
  }
267
360
  }
361
+ const scan = agentDirectoryInventory(current);
362
+ if (scan) {
363
+ for (const { target } of plan.writes) {
364
+ if (!deletedTargets.has(target))
365
+ continue;
366
+ const relative = relativeByTarget.get(target);
367
+ if (!relative)
368
+ throw new Error("Unowned merge write target.");
369
+ await assertFilesystemTarget(root, relative, options, replacementTargets, beforeHashes);
370
+ }
371
+ assertProjectedAgentDirectoryBudget(scan, { deletes: plan.deletes, writes: plan.writes.map(({ target, content }) => ({ target, size: content.length })) }, options);
372
+ }
268
373
  // A parent must remain until every reviewed leaf and intermediate directory is gone.
269
374
  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);
375
+ const removed = scan
376
+ ? replacements
377
+ : replacementPaths(new Set(paths.filter((relative) => deletedTargets.has(snapshotTarget(root, relative, options.sessionDir)))), afterHashes);
271
378
  const removedTargets = new Set([...removed].map((item) => snapshotTarget(root, item, options.sessionDir)));
272
379
  await assertCanonicalMergedTargets(root, changed, options);
273
380
  await validate();
@@ -276,6 +383,10 @@ export async function applyMergedSnapshot(before, after, protectedPaths, options
276
383
  const relative = relativeByTarget.get(target);
277
384
  if (!relative)
278
385
  throw new Error("Unowned merge target.");
386
+ if (options.scope === "agent-directory") {
387
+ await assertCanonicalMutationTargets([target], options);
388
+ await assertUnexcludedTargets(root, [target], options);
389
+ }
279
390
  await assertFilesystemTarget(root, relative, options, removedTargets, currentHashes);
280
391
  await validate();
281
392
  let hash;
@@ -288,9 +399,7 @@ export async function applyMergedSnapshot(before, after, protectedPaths, options
288
399
  else {
289
400
  if (!stat.isFile() || stat.nlink > 1)
290
401
  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");
402
+ hash = await hashReviewedFile(target, stat, options);
294
403
  }
295
404
  }
296
405
  catch (error) {
@@ -302,6 +411,8 @@ export async function applyMergedSnapshot(before, after, protectedPaths, options
302
411
  if (hash !== beforeHashes[relative] && hash !== afterHashes[relative])
303
412
  throw new Error("Local content changed at the apply boundary; journal retained, newer bytes untouched.");
304
413
  };
414
+ if (options.scope === "agent-directory" && plan.deletes.length)
415
+ await recheckAgentDirectoryBudget(root, plan, options);
305
416
  for (const target of plan.deletes) {
306
417
  await revalidateTarget(target);
307
418
  try {
@@ -345,6 +456,10 @@ export async function applyMergedSnapshot(before, after, protectedPaths, options
345
456
  await requireAbsentDestinations();
346
457
  await acquireDestinations(0);
347
458
  async function writeTargets() {
459
+ if (plan.writes.length && options.scope === "agent-directory") {
460
+ await validate();
461
+ await recheckAgentDirectoryBudget(root, { deletes: [], writes: plan.writes }, options);
462
+ }
348
463
  for (const item of plan.writes) {
349
464
  await validate();
350
465
  const relative = relativeByTarget.get(item.target);
@@ -6,6 +6,7 @@ import { statePathForConfig, syncStateFingerprint } from "../state/sync-state-st
6
6
  import { normalizeSyncExclude } from "./exclude-policy.js";
7
7
  import { planFileMerge } from "./file-merge-planner.js";
8
8
  import { portableSnapshot, sameLocalFields, validatePortableSnapshot, validateSnapshotFieldPolicy, } from "./local-fields.js";
9
+ import { configuredSnapshotPathMatcher, syncDirectoryPolicyKey, validateSnapshotSelection } from "./sync-policy.js";
9
10
  import { fileHashMap, sameHashes } from "./sync-state.js";
10
11
  export function mergeJournalIdentity(config, backendIdentity) {
11
12
  return JSON.stringify([
@@ -13,9 +14,11 @@ export function mergeJournalIdentity(config, backendIdentity) {
13
14
  backendIdentity,
14
15
  [...config.include].sort(),
15
16
  config.localFields ?? null,
16
- ...(config.exclude === undefined
17
- ? []
18
- : ["exclude", normalizeSyncExclude(config.exclude).map((rule) => rule.toLowerCase())]),
17
+ ...(config.scope === "agent-directory"
18
+ ? [syncDirectoryPolicyKey(config)]
19
+ : config.exclude === undefined
20
+ ? []
21
+ : ["exclude", normalizeSyncExclude(config.exclude).map((rule) => rule.toLowerCase())]),
19
22
  ]);
20
23
  }
21
24
  export function mergeJournalPath(config) {
@@ -74,13 +77,19 @@ export async function readMergeJournal(config) {
74
77
  ...(journal.accepted ? [journal.accepted] : []),
75
78
  ]) {
76
79
  validateSnapshotFieldPolicy(snapshot);
77
- if ((snapshot.version !== 1 && snapshot.version !== 2 && snapshot.version !== 3 && snapshot.version !== 4) ||
80
+ validateSnapshotSelection(snapshot);
81
+ if (![1, 2, 3, 4, 5].includes(snapshot.version) ||
78
82
  typeof snapshot.id !== "string" ||
79
83
  typeof snapshot.profile !== "string" ||
80
84
  snapshot.files.length > 16_384 ||
81
85
  snapshot.files.reduce((bytes, file) => bytes + (typeof file?.contentBase64 === "string" ? file.contentBase64.length * 0.75 : Infinity), 0) >
82
86
  64 * 1024 * 1024)
83
87
  throw new Error("Invalid journal input.");
88
+ if (snapshot.selection?.scope) {
89
+ const configured = configuredSnapshotPathMatcher(snapshot.selection);
90
+ if (snapshot.files.some((file) => typeof file?.path !== "string" || !configured(file.path)))
91
+ throw new Error("Journal retains paths outside its recorded directory policy.");
92
+ }
84
93
  const plan = planFileMerge({ baseline: {}, local: snapshot.files, remote: [], selectionCompatible: true });
85
94
  if (plan.kind !== "planned" ||
86
95
  plan.conflicts.some((conflict) => conflict.reason !== "path-collision" || !pinnedPaths.has(conflict.path)))
@@ -27,7 +27,7 @@ import { createStartupTimings } from "./startup-timings.js";
27
27
  import { createSyncDecision } from "./sync-decision.js";
28
28
  import { backupLocal, captureMutationOwner, protectedSessionPaths } from "./sync-local.js";
29
29
  import { configuredSnapshotPathMatcher, inspectRemoteSelection, syncSessionsSelected } from "./sync-policy.js";
30
- import { fileHashMap, hasLocalChanges, hasRemoteChanges, sameHashes, syncPolicyChanged } from "./sync-state.js";
30
+ import { acceptedSelection, fileHashMap, hasLocalChanges, hasRemoteChanges, sameHashes, syncPolicyChanged, } from "./sync-state.js";
31
31
  import { TEXT_MERGE_WORK_LIMIT } from "./text-merge.js";
32
32
  const MAX_ATTEMPTS = 3;
33
33
  /** Established-baseline sync only. First-source selection remains in the existing command flow. */
@@ -57,7 +57,9 @@ export async function mergeSync(ctx, options, factory = createSyncBackend, resol
57
57
  validateRetryAuthorization(config);
58
58
  const configToken = syncCheckConfigFingerprint(config);
59
59
  const modelToken = JSON.stringify(ctx.model);
60
- const sessionRoot = syncSessionsSelected(config) ? await effectiveSessionRoot(ctx) : undefined;
60
+ const sessionRoot = config.scope === "agent-directory" || syncSessionsSelected(config)
61
+ ? await effectiveSessionRoot(ctx, config, options.signal)
62
+ : undefined;
61
63
  validateOwner();
62
64
  const snapshotOptions = {
63
65
  ...snapshotOptionsForContext(ctx, config),
@@ -72,7 +74,7 @@ export async function mergeSync(ctx, options, factory = createSyncBackend, resol
72
74
  if (configToken !== syncCheckConfigFingerprint(latest))
73
75
  throw new Error("Sync setup or settings changed during transfer; reopen sync.");
74
76
  if (sessionRoot !== undefined) {
75
- const currentRoot = await effectiveSessionRoot(ctx);
77
+ const currentRoot = await effectiveSessionRoot(ctx, latest, options.signal);
76
78
  validateOwner();
77
79
  if (currentRoot !== sessionRoot)
78
80
  throw new Error("Session storage root changed during transfer; evidence retained for review.");
@@ -130,8 +132,8 @@ export async function mergeSync(ctx, options, factory = createSyncBackend, resol
130
132
  !state.unresolved?.length &&
131
133
  head.snapshotId === state.lastAppliedSnapshot &&
132
134
  backend.sameRevision(head.revision, state.lastRemoteRevision) &&
133
- inspectRemoteSelection(config.include, { selection: head.selection, files: [] }, config.exclude).kind ===
134
- "same" &&
135
+ inspectRemoteSelection(config.include, { selection: head.selection, files: [] }, config.exclude, config)
136
+ .kind === "same" &&
135
137
  matchesAcceptedState(state, config, head, local)) {
136
138
  const unchanged = await timings.measure("transfer unchanged verification", async () => {
137
139
  if (!(await hasCurrentMergeBaseline(config, local, state)))
@@ -162,7 +164,7 @@ export async function mergeSync(ctx, options, factory = createSyncBackend, resol
162
164
  }
163
165
  }
164
166
  const remote = rawRemote
165
- ? portableSnapshot(filterSnapshotForConfigPolicy(rawRemote, config), rawRemote.localFields)
167
+ ? portableSnapshot(filterSnapshotForConfigPolicy(rawRemote, config, { sessionDir: sessionRoot }), rawRemote.localFields)
166
168
  : undefined;
167
169
  if (rawRemote) {
168
170
  requireCompatibleRemoteSelection(config, rawRemote);
@@ -197,7 +199,7 @@ export async function mergeSync(ctx, options, factory = createSyncBackend, resol
197
199
  throw review("Included content changed; review the selection before merging.", "remote-or-policy-changed");
198
200
  if (!head || !remote || !rawRemote)
199
201
  throw review("The established remote is missing; choose an explicit recovery direction.", "remote-empty");
200
- const selectionState = inspectRemoteSelection(config.include, rawRemote, config.exclude);
202
+ const selectionState = inspectRemoteSelection(config.include, rawRemote, config.exclude, config);
201
203
  const selectionCompatible = selectionState.kind === "same";
202
204
  let plan = await timings.measure("transfer merge planning", () => planFileMerge({
203
205
  baseline: state.lastFileHashes,
@@ -315,19 +317,19 @@ export async function mergeSync(ctx, options, factory = createSyncBackend, resol
315
317
  files: acceptedMergeFiles(plan.decisions, local.files, withheld),
316
318
  });
317
319
  const after = overlayLocalFields(accepted, localRaw, config.localFields);
318
- if (syncSessionsSelected(config))
319
- requireStableMergeSessionRoot(localRaw, after);
320
+ if (sessionRoot !== undefined)
321
+ requireStableMergeSessionRoot(localRaw, after, config.scope);
320
322
  const publication = regenerateSnapshotIdentity({
321
323
  ...accepted,
322
- version: accepted.version === 4 ? 4 : config.partialSync ? 3 : accepted.version,
324
+ version: config.partialSync && accepted.version < 3 ? 3 : accepted.version,
323
325
  files: [
324
326
  ...accepted.files.filter((file) => !withheld.has(file.path)),
325
327
  ...remote.files.filter((file) => withheld.has(file.path)),
326
328
  ],
327
329
  });
328
- const upload = mergeRemotePreservedFiles(publication, rawRemote, config);
330
+ const upload = mergeRemotePreservedFiles(publication, rawRemote, config, { sessionDir: sessionRoot });
329
331
  const publish = !sameHashes(fileHashMap(publication), fileHashMap(remote)) ||
330
- Boolean(config.partialSync && rawRemote.version !== 3 && rawRemote.version !== 4);
332
+ Boolean(config.partialSync && rawRemote.version < 3);
331
333
  const apply = !sameHashes(fileHashMap(localRaw), fileHashMap(after));
332
334
  if (!publish && !apply) {
333
335
  const beforeEvidence = await timings.measure("transfer remote head", () => backend.readHead(options.signal));
@@ -494,7 +496,9 @@ async function completeJournal(ctx, config, backend, journal, validate, timings,
494
496
  !sameLocalFields(journal.upload.localFields, config.localFields))
495
497
  throw new Error("Merge journal belongs to a different setup, selection or local-field policy; preserve it for reviewed recovery.");
496
498
  await validate();
497
- const sessionRoot = syncSessionsSelected(config) ? await effectiveSessionRoot(ctx) : undefined;
499
+ const sessionRoot = config.scope === "agent-directory" || syncSessionsSelected(config)
500
+ ? await effectiveSessionRoot(ctx, config, signal)
501
+ : undefined;
498
502
  await validate();
499
503
  if (sessionRoot !== undefined && journal.sessionRoot !== sessionRoot) {
500
504
  throw new Error("Merge journal session root is missing or differs from this context; preserve evidence and use reviewed directional recovery.");
@@ -562,10 +566,10 @@ async function completeJournal(ctx, config, backend, journal, validate, timings,
562
566
  if (syncStateFingerprint(state) !== journal.stateIdentity) {
563
567
  throw new Error("Sync baseline changed after the interrupted merge; preserve its journal and review recovery.");
564
568
  }
565
- if (inspectRemoteSelection(config.include, observed, config.exclude).kind !== "same")
569
+ if (inspectRemoteSelection(config.include, observed, config.exclude, config).kind !== "same")
566
570
  throw new Error("Pending merge has unavailable remote selection metadata; preserve its journal and choose a reviewed explicit direction.");
567
- if (syncSessionsSelected(config))
568
- requireStableMergeSessionRoot(journal.before, journal.after);
571
+ if (sessionRoot !== undefined)
572
+ requireStableMergeSessionRoot(journal.before, journal.after, config.scope);
569
573
  await validate();
570
574
  const validateOwner = captureMutationOwner(ctx, signal);
571
575
  const validateMutation = () => {
@@ -603,8 +607,7 @@ function acceptedState(config, head, snapshot, progress, canonical = true) {
603
607
  lastAppliedSnapshot: head.snapshotId,
604
608
  lastRemoteRevision: head.revision,
605
609
  lastFileHashes: fileHashMap(canonical ? portableSnapshot(snapshot, config.localFields) : snapshot),
606
- include: [...config.include],
607
- ...(config.exclude === undefined ? {} : { exclude: [...config.exclude] }),
610
+ ...acceptedSelection(config),
608
611
  ...(config.localFields !== undefined ? { localFields: config.localFields } : {}),
609
612
  };
610
613
  }
@@ -1,4 +1,4 @@
1
- import { fileHashMap } from "./sync-state.js";
1
+ import { acceptedSelection, fileHashMap } from "./sync-state.js";
2
2
  /** Withholding preserves the complete local version, including explicit absence. */
3
3
  export function acceptedMergeFiles(decisions, localFiles, withheld) {
4
4
  const localByPath = new Map(localFiles.map((file) => [file.path, file]));
@@ -29,8 +29,10 @@ export function progressState(config, head, snapshot, progress) {
29
29
  version: 3,
30
30
  profile: config.snapshotIdentity,
31
31
  lastFileHashes: hashes,
32
- include: [...config.include],
33
- exclude: config.exclude === undefined ? undefined : [...config.exclude],
32
+ ...acceptedSelection(config),
33
+ ...(config.exclude === undefined ? { exclude: undefined } : {}),
34
+ ...(config.scope === undefined ? { scope: undefined } : {}),
35
+ ...(config.reinclude === undefined ? { reinclude: undefined } : {}),
34
36
  localFields: config.localFields,
35
37
  lastObservedSnapshot: head.snapshotId,
36
38
  lastObservedRevision: head.revision,
@@ -7,6 +7,7 @@ export declare function requireCompatibleRemoteSelection(config: AnySyncConfig,
7
7
  export declare function formatRemoteSelectionStatus(state: RemoteSelectionState | undefined): string;
8
8
  export declare function readRemoteSnapshot(backend: SyncBackend, config: AnySyncConfig, signal?: AbortSignal, options?: {
9
9
  allowSelectionDifference?: boolean;
10
+ sessionDir?: string;
10
11
  }): Promise<{
11
12
  head: undefined;
12
13
  snapshot: undefined;
@@ -21,9 +21,9 @@ export async function readSnapshotForHead(backend, head, signal) {
21
21
  export function requireCompatibleRemoteSelection(config, snapshot) {
22
22
  if (!sameLocalFields(config.localFields, snapshot.localFields))
23
23
  throw new Error("Remote local-field policy differs; confirm a reviewed directional migration. Old history is not erased.");
24
- const state = inspectRemoteSelection(config.include, snapshot, config.exclude);
24
+ const state = inspectRemoteSelection(config.include, snapshot, config.exclude, config);
25
25
  if (state.kind === "different") {
26
- throw remoteSelectionMismatch(config, state.include, syncConfigReviewFingerprint(config), state.exclude);
26
+ throw remoteSelectionMismatch(config, state.include, syncConfigReviewFingerprint(config), state.exclude, state);
27
27
  }
28
28
  }
29
29
  export function formatRemoteSelectionStatus(state) {
@@ -39,6 +39,9 @@ export function formatRemoteSelectionStatus(state) {
39
39
  `remote-only selection: ${safeList(state.remoteOnly)}`,
40
40
  `local-only selection: ${safeList(state.localOnly)}`,
41
41
  `remote excluded paths: ${safeList(state.exclude ?? [])}`,
42
+ ...(state.scope
43
+ ? [`remote scope: ${state.scope}`, `remote re-included paths: ${safeList(state.reinclude ?? [])}`]
44
+ : []),
42
45
  ].join("\n");
43
46
  }
44
47
  function safeList(values) {
@@ -49,14 +52,14 @@ export async function readRemoteSnapshot(backend, config, signal, options = {})
49
52
  if (!head)
50
53
  return { head: undefined, snapshot: undefined, selectionState: undefined };
51
54
  const snapshot = await readSnapshotForHead(backend, head, signal);
52
- const selectionState = inspectRemoteSelection(config.include, snapshot, config.exclude);
55
+ const selectionState = inspectRemoteSelection(config.include, snapshot, config.exclude, config);
53
56
  if (!options.allowSelectionDifference && selectionState.kind === "different") {
54
57
  const configIdentity = syncConfigReviewFingerprint(config);
55
- throw remoteSelectionMismatch(config, selectionState.include, configIdentity, selectionState.exclude);
58
+ throw remoteSelectionMismatch(config, selectionState.include, configIdentity, selectionState.exclude, selectionState);
56
59
  }
57
60
  return {
58
61
  head,
59
- snapshot: filterSnapshotForConfigPolicy(snapshot, config),
62
+ snapshot: filterSnapshotForConfigPolicy(snapshot, config, { sessionDir: options.sessionDir }),
60
63
  selectionState,
61
64
  };
62
65
  }
@@ -1,12 +1,12 @@
1
1
  import { loadConfig } from "../settings/config.js";
2
- import { snapshotOptionsForContext } from "../snapshot/session-paths.js";
2
+ import { resolvedSnapshotOptionsForContext } from "../snapshot/session-paths.js";
3
3
  import { createSnapshot } from "../snapshot/snapshot.js";
4
4
  import { withLock } from "../state/lock.js";
5
5
  import { withStateDirectoryAccess } from "../state/state-directory.js";
6
6
  import { readStateForConfig } from "../state/sync-state-store.js";
7
7
  import { captureMutationOwner } from "./sync-local.js";
8
8
  import { syncSessionsSelected } from "./sync-policy.js";
9
- import { hasLocalChanges } from "./sync-state.js";
9
+ import { hasLocalChanges, syncPolicyChanged } from "./sync-state.js";
10
10
  /** Existing legacy policy; service ownership/consent is established by its caller. */
11
11
  export async function pushSessionsOnShutdown(ctx, options, loaders = { operations: () => import("./sync-operations.js") }) {
12
12
  const validate = captureMutationOwner(ctx, options.signal);
@@ -17,10 +17,11 @@ export async function pushSessionsOnShutdown(ctx, options, loaders = { operation
17
17
  await withStateDirectoryAccess(() => withLock("auto-session-push", async () => {
18
18
  const state = await readStateForConfig(config);
19
19
  validate();
20
- const local = await createSnapshot(config.snapshotIdentity, {
21
- ...snapshotOptionsForContext(ctx, config),
22
- signal: options.signal,
23
- });
20
+ if ((config.scope || state.scope) && (!state.lastAppliedSnapshot || syncPolicyChanged(state, config)))
21
+ return;
22
+ const snapshotOptions = await resolvedSnapshotOptionsForContext(ctx, config, options.signal);
23
+ validate();
24
+ const local = await createSnapshot(config.snapshotIdentity, snapshotOptions);
24
25
  validate();
25
26
  if (!hasLocalChanges(local, state, config))
26
27
  return;
@@ -17,6 +17,10 @@ export interface SyncDecision {
17
17
  currentInclude: readonly string[];
18
18
  previousExclude?: readonly string[];
19
19
  currentExclude?: readonly string[];
20
+ previousScope?: "agent-directory";
21
+ currentScope?: "agent-directory";
22
+ previousReinclude?: readonly string[];
23
+ currentReinclude?: readonly string[];
20
24
  review: string;
21
25
  directions: readonly SyncResolutionDirection[];
22
26
  directMessage: string;
@@ -37,10 +37,16 @@ export function createSyncDecision(options) {
37
37
  ...(policyChanged
38
38
  ? [
39
39
  "",
40
- `Previously included: ${safeList(previousInclude)}`,
41
- `Currently included: ${safeList(currentInclude)}`,
40
+ `Previously included: ${selectionLabel(state.scope, previousInclude)}`,
41
+ `Currently included: ${selectionLabel(config.scope, currentInclude)}`,
42
42
  `Previously excluded: ${safeList(state.exclude ?? [])}`,
43
43
  `Currently excluded: ${safeList(config.exclude ?? [])}`,
44
+ ...(state.scope || config.scope
45
+ ? [
46
+ `Previously re-included: ${safeList(state.reinclude ?? [])}`,
47
+ `Currently re-included: ${safeList(config.reinclude ?? [])}`,
48
+ ]
49
+ : []),
44
50
  ]
45
51
  : []),
46
52
  "",
@@ -56,11 +62,20 @@ export function createSyncDecision(options) {
56
62
  currentInclude,
57
63
  ...(policyChanged && state.exclude !== undefined ? { previousExclude: [...state.exclude] } : {}),
58
64
  ...(config.exclude === undefined ? {} : { currentExclude: [...config.exclude] }),
65
+ ...(policyChanged && state.scope !== undefined ? { previousScope: state.scope } : {}),
66
+ ...(config.scope === undefined ? {} : { currentScope: config.scope }),
67
+ ...(policyChanged && state.reinclude !== undefined ? { previousReinclude: [...state.reinclude] } : {}),
68
+ ...(config.reinclude === undefined ? {} : { currentReinclude: [...config.reinclude] }),
59
69
  review,
60
70
  directions: kind === "remote-empty" ? ["push"] : ["push", "pull"],
61
71
  directMessage: options.directMessage,
62
72
  });
63
73
  }
74
+ function selectionLabel(scope, include) {
75
+ return scope === "agent-directory"
76
+ ? `eligible files in the Pi agent directory (sessions ${include.includes("sessions") ? "opted in" : "off"})`
77
+ : safeList(include);
78
+ }
64
79
  function safeList(values) {
65
80
  return values.length > 0 ? values.map(safeTerminalText).join(", ") : "none";
66
81
  }