@narumitw/pi-sync-daemon 0.6.1 → 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 (72) hide show
  1. package/CHANGELOG.md +15 -0
  2. package/README.md +3 -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/dist/resolver-host.js +1 -1
  71. package/docs/architecture.md +6 -0
  72. package/package.json +4 -4
@@ -4,7 +4,7 @@ import { createSnapshot } from "../snapshot/snapshot.js";
4
4
  import { readStateForConfig, syncStateFingerprint } from "../state/sync-state-store.js";
5
5
  import { throwIfAborted } from "./signals.js";
6
6
  import { createStartupTimings } from "./startup-timings.js";
7
- import { inspectRemoteSelection } from "./sync-policy.js";
7
+ import { inspectRemoteSelection, syncSelectionHasContent } from "./sync-policy.js";
8
8
  import { fileHashMap, hasLocalChanges, remoteChangedSinceState } from "./sync-state.js";
9
9
  /** Advisory baseline-relative observation, never an authorization to transfer files. */
10
10
  export async function inspectSync(config, options, signal, factory = createSyncBackend, timings = createStartupTimings()) {
@@ -26,13 +26,13 @@ export async function inspectSync(config, options, signal, factory = createSyncB
26
26
  ...freshness,
27
27
  head,
28
28
  selectionState: head
29
- ? inspectRemoteSelection(config.include, { selection: head.selection, files: [] }, config.exclude)
29
+ ? inspectRemoteSelection(config.include, { selection: head.selection, files: [] }, config.exclude, config)
30
30
  : undefined,
31
31
  localFiles: local.files.length,
32
32
  localChanged: hasLocalChanges(local, state, config),
33
33
  remoteChanged: remoteChangedSinceState(head, state, config, (left, right) => backend.sameRevision(left, right)),
34
34
  firstSync: !state.lastAppliedSnapshot,
35
- emptyInclude: config.include.length === 0,
35
+ emptyInclude: !syncSelectionHasContent(config),
36
36
  stateIdentity: syncStateFingerprint(state),
37
37
  destination: backend.destination,
38
38
  capability: backend.capability,
@@ -21,7 +21,14 @@ interface PushInput {
21
21
  backend?: SyncBackend;
22
22
  }
23
23
  export declare function push(ctx: ExtensionCommandContext | ExtensionContext, options: CommandOptions, input?: PushInput, factory?: SyncBackendFactory): Promise<"applied" | "cancelled" | undefined>;
24
- export declare function pull(ctx: ExtensionCommandContext | ExtensionContext, options: CommandOptions, factory?: SyncBackendFactory): Promise<"applied" | "cancelled">;
24
+ interface InitialPullEvidence {
25
+ configIdentity: string;
26
+ stateIdentity: string;
27
+ sessionDir: string | undefined;
28
+ localHashes: Record<string, string>;
29
+ head: RemoteHead | undefined;
30
+ }
31
+ export declare function pull(ctx: ExtensionCommandContext | ExtensionContext, options: CommandOptions, factory?: SyncBackendFactory, initial?: InitialPullEvidence): Promise<"applied" | "cancelled">;
25
32
  export declare function syncBoth(ctx: ExtensionCommandContext | ExtensionContext, options: CommandOptions, factory?: SyncBackendFactory): Promise<"applied" | "cancelled" | undefined>;
26
33
  export declare function rollback(ctx: ExtensionCommandContext, options: CommandOptions, factory?: SyncBackendFactory, expectedSelection?: {
27
34
  backendIdentity: string;
@@ -1,7 +1,7 @@
1
1
  import { createSyncBackend } from "../backends/backend-factory.js";
2
2
  import { expectedRemoteHead, } from "../backends/sync-backend.js";
3
3
  import { loadConfig, syncCheckConfigFingerprint } from "../settings/config.js";
4
- import { sessionDirForApply, snapshotOptionsForContext } from "../snapshot/session-paths.js";
4
+ import { effectiveSessionRoot, requireStableMergeSessionRoot, resolvedSnapshotOptionsForContext, sessionDirForApply, } from "../snapshot/session-paths.js";
5
5
  import { createSnapshot, filterSnapshotForConfigPolicy, mergeRemotePreservedFiles, regenerateSnapshotIdentity, scanSnapshot, snapshotIncludesSessions, snapshotWithoutSessions, } from "../snapshot/snapshot.js";
6
6
  import { applySnapshot } from "../snapshot/snapshot-apply.js";
7
7
  import { pruneMergeBaselines } from "../state/merge-baseline-store.js";
@@ -20,8 +20,8 @@ import { throwIfAborted } from "./signals.js";
20
20
  import { createSyncDecision } from "./sync-decision.js";
21
21
  import { errorMessage } from "./sync-errors.js";
22
22
  import { backupLocal, captureMutationOwner, protectedSessionPaths } from "./sync-local.js";
23
- import { inspectRemoteSelection, syncSessionsSelected } from "./sync-policy.js";
24
- import { canPullRemoteSessionsOnFirstSync, canPullRemoteSettingsOnFirstSync, fileHashMap, hasLocalChanges, hasRemoteChanges, remoteChangedSinceState, sameHashes, shouldRefreshSyncedState, snapshotHashesMatchState, snapshotsMatch, syncPolicyChanged, } from "./sync-state.js";
23
+ import { inspectRemoteSelection, syncSelectionHasContent, syncSessionsSelected } from "./sync-policy.js";
24
+ import { acceptedSelection, canPullRemoteSessionsOnFirstSync, canPullRemoteSettingsOnFirstSync, fileHashMap, hasLocalChanges, hasRemoteChanges, remoteChangedSinceState, sameHashes, shouldRefreshSyncedState, snapshotHashesMatchState, snapshotsMatch, syncPolicyChanged, } from "./sync-state.js";
25
25
  const VERSION = 1;
26
26
  const POST_LOCAL_COMMIT_TIMEOUT_MS = 30_000;
27
27
  /** Whole-direction acceptance must never forget withheld state without an explicit recovery choice. */
@@ -58,19 +58,28 @@ export async function push(ctx, options, input, factory = createSyncBackend) {
58
58
  const state = input?.state ?? (await readStateForConfig(config));
59
59
  validateMutation();
60
60
  requireResolvedDirectionalProgress(state, options);
61
+ if (options.auto &&
62
+ (config.scope === "agent-directory" || state.scope !== undefined) &&
63
+ (options.force || !state.lastAppliedSnapshot || syncPolicyChanged(state, config))) {
64
+ throw new Error("Automatic push requires an accepted baseline with matching content policy.");
65
+ }
61
66
  setSyncStatus(ctx, `pushing ${config.setupName}`, { activity: "pushing" });
62
67
  const backend = input?.backend ?? (await factory(config));
63
68
  throwIfAborted(options.signal);
64
- const localRaw = input?.local ?? (await createSnapshot(config.snapshotIdentity, snapshotOptionsForContext(ctx, config)));
69
+ const snapshotOptions = await resolvedSnapshotOptionsForContext(ctx, config, options.signal);
70
+ validateMutation();
71
+ const localRaw = input?.local ?? (await createSnapshot(config.snapshotIdentity, snapshotOptions));
65
72
  const local = portableSnapshot(localRaw, config.localFields);
66
73
  throwIfAborted(options.signal);
67
74
  let head = await backend.readHead(options.signal);
68
75
  let remoteForUpload = await readRemoteSnapshotForUpload(backend, config, head, state, options.signal);
69
76
  if (!options.force &&
70
77
  !remoteForUpload &&
71
- head?.selection &&
72
- inspectRemoteSelection(config.include, { selection: head.selection, files: [] }, config.exclude).kind ===
73
- "different") {
78
+ head &&
79
+ (config.scope === "agent-directory" ||
80
+ (head.selection &&
81
+ inspectRemoteSelection(config.include, { selection: head.selection, files: [] }, config.exclude, config)
82
+ .kind === "different"))) {
74
83
  remoteForUpload = await readSnapshotForHead(backend, head, options.signal);
75
84
  }
76
85
  if (remoteForUpload && !options.force) {
@@ -78,7 +87,9 @@ export async function push(ctx, options, input, factory = createSyncBackend) {
78
87
  }
79
88
  if (remoteChangedSinceState(head, state, config, (left, right) => backend.sameRevision(left, right)) &&
80
89
  !options.force) {
81
- const remoteForConflict = remoteForUpload ? filterSnapshotForConfigPolicy(remoteForUpload, config) : undefined;
90
+ const remoteForConflict = remoteForUpload
91
+ ? filterSnapshotForConfigPolicy(remoteForUpload, config, snapshotOptions)
92
+ : undefined;
82
93
  if (!remoteForConflict || !snapshotHashesMatchState(remoteForConflict, state, config)) {
83
94
  throw createSyncDecision({
84
95
  kind: head ? "remote-or-policy-changed" : "remote-empty",
@@ -99,7 +110,7 @@ export async function push(ctx, options, input, factory = createSyncBackend) {
99
110
  return "cancelled";
100
111
  }
101
112
  const configIdentity = syncCheckConfigFingerprint(config);
102
- let upload = await snapshotForUpload(backend, config, local, head, remoteForUpload, options.signal);
113
+ let upload = await snapshotForUpload(backend, config, local, head, remoteForUpload, snapshotOptions);
103
114
  if (!config.skipSecretScan) {
104
115
  const secrets = scanSnapshot(local);
105
116
  if (secrets.length > 0) {
@@ -120,7 +131,7 @@ export async function push(ctx, options, input, factory = createSyncBackend) {
120
131
  return "cancelled";
121
132
  }
122
133
  validateMutation();
123
- upload = await snapshotForUpload(backend, config, local, head, remoteForUpload, options.signal);
134
+ upload = await snapshotForUpload(backend, config, local, head, remoteForUpload, snapshotOptions);
124
135
  if (!(await confirmPush(ctx, options, config, backend, local, upload, head, remoteForUpload, "Remote changed during review. Push the refreshed plan?"))) {
125
136
  return "cancelled";
126
137
  }
@@ -130,8 +141,11 @@ export async function push(ctx, options, input, factory = createSyncBackend) {
130
141
  if (configIdentity !== syncCheckConfigFingerprint(await loadConfig(options.setup)))
131
142
  throw new Error("Settings changed during push review.");
132
143
  validateMutation();
133
- if (!options.yes || config.localFields !== undefined || (await readMergeJournal(config))) {
134
- const current = await createSnapshot(config.snapshotIdentity, snapshotOptionsForContext(ctx, config));
144
+ if (config.scope === "agent-directory" ||
145
+ !options.yes ||
146
+ config.localFields !== undefined ||
147
+ (await readMergeJournal(config))) {
148
+ const current = await createSnapshot(config.snapshotIdentity, snapshotOptions);
135
149
  if (!sameHashes(fileHashMap(current), fileHashMap(localRaw)))
136
150
  throw new Error("Local content changed during push review; retry from current bytes.");
137
151
  }
@@ -139,6 +153,12 @@ export async function push(ctx, options, input, factory = createSyncBackend) {
139
153
  if (!options.yes && syncStateFingerprint(currentState) !== syncStateFingerprint(state))
140
154
  throw new Error("Baseline changed during push review.");
141
155
  requireResolvedDirectionalProgress(currentState, options);
156
+ if (config.scope === "agent-directory" &&
157
+ snapshotOptions.sessionDir !== (await effectiveSessionRoot(ctx, config, options.signal)))
158
+ throw new Error("Pi session storage changed during push review.");
159
+ validateMutation();
160
+ if (configIdentity !== syncCheckConfigFingerprint(await loadConfig(options.setup)))
161
+ throw new Error("Settings changed during push review.");
142
162
  validateMutation();
143
163
  const result = await backend.publishSnapshot(upload, expectedRemoteHead(head), {
144
164
  signal: options.signal,
@@ -151,8 +171,7 @@ export async function push(ctx, options, input, factory = createSyncBackend) {
151
171
  lastAppliedSnapshot: result.head.snapshotId,
152
172
  lastRemoteRevision: result.head.revision,
153
173
  lastFileHashes: fileHashMap(local),
154
- include: [...config.include],
155
- ...(config.exclude === undefined ? {} : { exclude: [...config.exclude] }),
174
+ ...acceptedSelection(config),
156
175
  ...(config.localFields !== undefined ? { localFields: config.localFields } : {}),
157
176
  }, local, validateCommittedOwner);
158
177
  }
@@ -175,21 +194,34 @@ export async function push(ctx, options, input, factory = createSyncBackend) {
175
194
  }
176
195
  return "applied";
177
196
  }
178
- export async function pull(ctx, options, factory = createSyncBackend) {
197
+ export async function pull(ctx, options, factory = createSyncBackend, initial) {
179
198
  const validateMutation = captureMutationOwner(ctx, options.signal);
180
199
  const validateCommittedOwner = captureMutationOwner(ctx);
181
200
  const config = await loadConfig(options.setup);
182
- throwIfAborted(options.signal);
201
+ validateMutation();
202
+ const configIdentity = syncCheckConfigFingerprint(config);
203
+ if (initial && initial.configIdentity !== configIdentity)
204
+ throw new Error("Settings changed before initial pull; run sync again.");
183
205
  await requireNoMergeJournal(config, options);
184
206
  setSyncStatus(ctx, `pulling ${config.setupName}`, { activity: "pulling" });
185
207
  const backend = await factory(config);
186
208
  const state = await readStateForConfig(config);
187
209
  validateMutation();
210
+ if (initial && initial.stateIdentity !== syncStateFingerprint(state))
211
+ throw new Error("Baseline changed before initial pull; run sync again.");
188
212
  requireResolvedDirectionalProgress(state, options);
189
- const local = await createSnapshot(config.snapshotIdentity, snapshotOptionsForContext(ctx, config));
190
- throwIfAborted(options.signal);
191
- const { head, snapshot: remote } = await readRemoteSnapshot(backend, config, options.signal);
192
- throwIfAborted(options.signal);
213
+ const snapshotOptions = await resolvedSnapshotOptionsForContext(ctx, config, options.signal);
214
+ validateMutation();
215
+ if (initial && initial.sessionDir !== snapshotOptions.sessionDir)
216
+ throw new Error("Pi session storage changed before initial pull; run sync again.");
217
+ const local = await createSnapshot(config.snapshotIdentity, snapshotOptions);
218
+ validateMutation();
219
+ if (initial && !sameHashes(initial.localHashes, fileHashMap(local)))
220
+ throw new Error("Local bytes changed before initial pull; run sync again.");
221
+ const { head, snapshot: remote } = await readRemoteSnapshot(backend, config, options.signal, snapshotOptions);
222
+ validateMutation();
223
+ if (initial && !matchesInitialHead(initial, backend, head))
224
+ throw new Error("Remote changed before initial pull; run sync again.");
193
225
  const localChanged = hasLocalChanges(local, state, config);
194
226
  if (!remote) {
195
227
  throw createSyncDecision({
@@ -210,10 +242,11 @@ export async function pull(ctx, options, factory = createSyncBackend) {
210
242
  setSyncStatus(ctx, undefined);
211
243
  return "cancelled";
212
244
  }
213
- const configIdentity = syncCheckConfigFingerprint(config);
214
245
  const logical = portableSnapshot(remote, config.localFields);
215
246
  const physical = overlayLocalFields(logical, local, config.localFields);
216
- const remoteChanged = hasRemoteChanges(remote, state, config, protectedSessionPaths(ctx));
247
+ if (config.scope === "agent-directory")
248
+ requireStableMergeSessionRoot(local, physical, config.scope);
249
+ const remoteChanged = hasRemoteChanges(remote, state, config, protectedSessionPaths(ctx, snapshotOptions.sessionDir));
217
250
  if (localChanged && remoteChanged && state.lastAppliedSnapshot && !options.force) {
218
251
  throw createSyncDecision({
219
252
  kind: "both-changed",
@@ -226,10 +259,10 @@ export async function pull(ctx, options, factory = createSyncBackend) {
226
259
  directMessage: "Both local and remote changed since last sync. Run /sync diff, then choose /sync pull --force or /sync push --force.",
227
260
  });
228
261
  }
229
- const caseCleanup = options.yes ? [] : await inspectCaseCleanup(physical, options.signal);
262
+ const caseCleanup = options.yes ? [] : await inspectCaseCleanup(physical, snapshotOptions);
230
263
  validateMutation();
231
264
  if (!options.yes &&
232
- !(await confirmTransferReview(ctx, snapshotIncludesSessions(remote) ? "Pull pi settings and sessions?" : "Pull pi settings?", formatPullSummary(config, backend.destination, local, physical, protectedSessionPaths(ctx), caseCleanup.map((item) => item.path)), options.signal, validateMutation))) {
265
+ !(await confirmTransferReview(ctx, snapshotIncludesSessions(remote) ? "Pull pi settings and sessions?" : "Pull pi settings?", formatPullSummary(config, backend.destination, local, physical, protectedSessionPaths(ctx, snapshotOptions.sessionDir), caseCleanup.map((item) => item.path)), options.signal, validateMutation))) {
233
266
  setSyncStatus(ctx, undefined);
234
267
  ctx.ui.notify("Pull cancelled.", "info");
235
268
  return "cancelled";
@@ -240,7 +273,7 @@ export async function pull(ctx, options, factory = createSyncBackend) {
240
273
  validateMutation();
241
274
  const currentHead = await backend.readHead(options.signal);
242
275
  validateMutation();
243
- const current = await createSnapshot(config.snapshotIdentity, snapshotOptionsForContext(ctx, config));
276
+ const current = await createSnapshot(config.snapshotIdentity, snapshotOptions);
244
277
  validateMutation();
245
278
  if (!sameHashes(fileHashMap(current), fileHashMap(local)) || !sameRemoteHead(backend, head, currentHead)) {
246
279
  throw new Error("Local or remote content changed during recovery review; retry from a fresh diff.");
@@ -251,30 +284,38 @@ export async function pull(ctx, options, factory = createSyncBackend) {
251
284
  if (configIdentity !== syncCheckConfigFingerprint(await loadConfig(options.setup)))
252
285
  throw new Error("Settings changed during pull review.");
253
286
  validateMutation();
254
- const refreshed = await createSnapshot(config.snapshotIdentity, snapshotOptionsForContext(ctx, config));
287
+ const refreshed = await createSnapshot(config.snapshotIdentity, snapshotOptions);
255
288
  if (!sameHashes(fileHashMap(local), fileHashMap(refreshed)))
256
289
  throw new Error("Local bytes changed during pull review.");
257
290
  if (!sameRemoteHead(backend, head, await backend.readHead(options.signal)))
258
291
  throw new Error("Remote changed during pull review.");
259
292
  validateMutation();
260
- const backup = await backupLocal(config.snapshotIdentity, snapshotOptionsForContext(ctx, config), options.signal);
261
- const applySessionDir = await sessionDirForApply(ctx, physical);
293
+ const backup = await backupLocal(config.snapshotIdentity, snapshotOptions, options.signal);
294
+ const applySessionDir = await sessionDirForApply(ctx, physical, snapshotOptions);
262
295
  if (recoveringMerge)
263
296
  await requireFreshRecovery();
264
297
  const currentState = await readStateForConfig(config);
265
- if (!options.yes && syncStateFingerprint(currentState) !== syncStateFingerprint(state))
298
+ validateMutation();
299
+ if ((initial || !options.yes) && syncStateFingerprint(currentState) !== syncStateFingerprint(state))
266
300
  throw new Error("Baseline changed during pull review.");
267
301
  requireResolvedDirectionalProgress(currentState, options);
268
302
  if (!options.yes)
269
- await revalidateCaseCleanup(caseCleanup, physical, options.signal);
303
+ await revalidateCaseCleanup(caseCleanup, physical, snapshotOptions);
304
+ if (initial && !matchesInitialHead(initial, backend, await backend.readHead(options.signal)))
305
+ throw new Error("Remote changed during initial pull; run sync again.");
306
+ validateMutation();
307
+ if (config.scope && applySessionDir !== (await effectiveSessionRoot(ctx, config, options.signal)))
308
+ throw new Error("Pi session storage changed during pull review.");
309
+ validateMutation();
310
+ if (configIdentity !== syncCheckConfigFingerprint(await loadConfig(options.setup)))
311
+ throw new Error("Settings changed during pull review.");
270
312
  validateMutation();
271
313
  options.onCommit?.();
272
- const lastFileHashes = await applySnapshot(physical, protectedSessionPaths(ctx), {
273
- include: config.include,
274
- ...(config.exclude === undefined ? {} : { exclude: [...config.exclude] }),
314
+ const lastFileHashes = await applySnapshot(physical, protectedSessionPaths(ctx, snapshotOptions.sessionDir), {
315
+ ...snapshotOptions,
275
316
  sessionDir: applySessionDir,
276
- signal: options.signal,
277
317
  validateMutation,
318
+ ...(config.scope === "agent-directory" ? { reviewedLocal: local } : {}),
278
319
  expectedFileHashes: config.localFields?.length
279
320
  ? { "settings.json": fileHashMap(local)["settings.json"] ?? null }
280
321
  : undefined,
@@ -289,8 +330,7 @@ export async function pull(ctx, options, factory = createSyncBackend) {
289
330
  lastFileHashes: config.localFields?.length
290
331
  ? { ...lastFileHashes, "settings.json": fileHashMap(logical)["settings.json"] }
291
332
  : lastFileHashes,
292
- include: [...config.include],
293
- ...(config.exclude === undefined ? {} : { exclude: [...config.exclude] }),
333
+ ...acceptedSelection(config),
294
334
  ...(config.localFields !== undefined ? { localFields: config.localFields } : {}),
295
335
  }, logical, validateCommittedOwner);
296
336
  await retireMergeJournal(config);
@@ -321,37 +361,65 @@ export async function syncBoth(ctx, options, factory = createSyncBackend) {
321
361
  validateMutation();
322
362
  const pending = await readMergeJournal(config);
323
363
  validateMutation();
324
- if (!config.include.length || !state.lastAppliedSnapshot || pending)
364
+ if (!syncSelectionHasContent(config) || !state.lastAppliedSnapshot || pending)
325
365
  throw new Error("Retry requires an accepted baseline and no pending journal. Use Sync now or reviewed recovery.");
326
366
  return mergeSync(ctx, options, factory);
327
367
  }
328
- if (config.include.length > 0 && options.auto && startupTransferEnabled(config))
368
+ if (syncSelectionHasContent(config) && options.auto && startupTransferEnabled(config))
329
369
  return mergeSync(ctx, options, factory);
330
- if (!options.auto && config.include.length > 0 && (await readMergeJournal(config)))
370
+ if (!options.auto && syncSelectionHasContent(config) && (await readMergeJournal(config)))
331
371
  return mergeSync(ctx, options, factory);
332
372
  const state = await readStateForConfig(config);
333
373
  throwIfAborted(options.signal);
334
- if (!options.auto && config.include.length > 0 && state.lastAppliedSnapshot)
374
+ if (!options.auto && syncSelectionHasContent(config) && state.lastAppliedSnapshot)
335
375
  return mergeSync(ctx, options, factory);
336
- const backend = await factory(config);
337
- const local = await createSnapshot(config.snapshotIdentity, snapshotOptionsForContext(ctx, config));
338
- throwIfAborted(options.signal);
339
- if (config.include.length === 0) {
376
+ if (!syncSelectionHasContent(config)) {
340
377
  if (!options.silent) {
341
378
  ctx.ui.notify(`Sync setup “${config.setupName}” includes no files. Choose included content in /sync Settings before syncing.`, "warning");
342
379
  }
343
380
  return;
344
381
  }
345
- const { head, snapshot: remote } = await readRemoteSnapshot(backend, config, options.signal);
382
+ const backend = await factory(config);
383
+ const snapshotOptions = await resolvedSnapshotOptionsForContext(ctx, config, options.signal);
384
+ validateMutation();
385
+ const local = await createSnapshot(config.snapshotIdentity, snapshotOptions);
386
+ throwIfAborted(options.signal);
387
+ const { head, snapshot: remote } = await readRemoteSnapshot(backend, config, options.signal, snapshotOptions);
346
388
  throwIfAborted(options.signal);
347
389
  const localChanged = hasLocalChanges(local, state, config);
348
- const remoteChanged = remote ? hasRemoteChanges(remote, state, config, protectedSessionPaths(ctx)) : false;
390
+ const remoteChanged = remote
391
+ ? hasRemoteChanges(remote, state, config, protectedSessionPaths(ctx, snapshotOptions.sessionDir))
392
+ : false;
349
393
  if (options.auto)
350
394
  throw new Error("Automatic transfer is not authorized by the current settings.");
351
395
  // Established baselines return through mergeSync above; only initial-source selection remains.
352
396
  const portableLocal = portableSnapshot(local, config.localFields);
397
+ const configIdentity = syncCheckConfigFingerprint(config);
398
+ const pullInitialSource = () => {
399
+ validateMutation();
400
+ return pull(ctx, options, factory, {
401
+ configIdentity,
402
+ stateIdentity: syncStateFingerprint(state),
403
+ sessionDir: snapshotOptions.sessionDir,
404
+ localHashes: fileHashMap(local),
405
+ head,
406
+ });
407
+ };
353
408
  const acceptMatchingState = async (snapshot) => {
354
409
  requireCompatibleRemoteSelection(config, snapshot);
410
+ if (config.scope === "agent-directory") {
411
+ const current = await createSnapshot(config.snapshotIdentity, snapshotOptions);
412
+ const currentState = await readStateForConfig(config);
413
+ const currentHead = await backend.readHead(options.signal);
414
+ if (!sameHashes(fileHashMap(current), fileHashMap(local)) ||
415
+ syncStateFingerprint(currentState) !== syncStateFingerprint(state) ||
416
+ !sameRemoteHead(backend, head, currentHead))
417
+ throw new Error("Initial source changed before baseline acceptance; run sync again.");
418
+ if (snapshotOptions.sessionDir !== (await effectiveSessionRoot(ctx, config, options.signal)) ||
419
+ configIdentity !== syncCheckConfigFingerprint(await loadConfig(options.setup)))
420
+ throw new Error("Settings or Pi session storage changed before baseline acceptance; run sync again.");
421
+ validateMutation();
422
+ }
355
423
  const accepted = portableSnapshot(snapshot, config.localFields);
356
424
  await writeStateForConfig(config, {
357
425
  version: VERSION,
@@ -359,8 +427,7 @@ export async function syncBoth(ctx, options, factory = createSyncBackend) {
359
427
  lastAppliedSnapshot: snapshot.id,
360
428
  lastRemoteRevision: head?.revision,
361
429
  lastFileHashes: fileHashMap(accepted),
362
- include: [...config.include],
363
- ...(config.exclude === undefined ? {} : { exclude: [...config.exclude] }),
430
+ ...acceptedSelection(config),
364
431
  ...(config.localFields !== undefined ? { localFields: config.localFields } : {}),
365
432
  }, accepted, validateMutation);
366
433
  await pruneMergeBaselines(config, await readStateForConfig(config), validateMutation);
@@ -394,7 +461,7 @@ export async function syncBoth(ctx, options, factory = createSyncBackend) {
394
461
  directMessage: "Remote settings match, but local and remote Pi sessions differ. Run /sync diff, then manually choose /sync pull or /sync push.",
395
462
  });
396
463
  }
397
- await pull(ctx, options, factory);
464
+ await pullInitialSource();
398
465
  return;
399
466
  }
400
467
  await acceptMatchingState(remote);
@@ -413,11 +480,11 @@ export async function syncBoth(ctx, options, factory = createSyncBackend) {
413
480
  return;
414
481
  }
415
482
  if (remoteChanged) {
416
- await pull(ctx, options, factory);
483
+ await pullInitialSource();
417
484
  return;
418
485
  }
419
486
  if (localChanged || !remote) {
420
- await push(ctx, options, undefined, factory);
487
+ await push(ctx, options, { config, state, local, backend }, factory);
421
488
  return;
422
489
  }
423
490
  if (shouldRefreshSyncedState(remote, head, state, config, (left, right) => backend.sameRevision(left, right))) {
@@ -448,9 +515,11 @@ export async function rollback(ctx, options, factory = createSyncBackend, expect
448
515
  validatePortableSnapshot(decoded);
449
516
  if (!sameLocalFields(decoded.localFields, config.localFields))
450
517
  throw new Error("Rollback requires the historical snapshot local-field policy to match the configured rules. Review push --force from current local bytes to migrate policy first; choose matching history afterward.");
451
- const selected = filterSnapshotForConfigPolicy(syncSessionsSelected(config) ? decoded : snapshotWithoutSessions(decoded), config);
518
+ const snapshotOptions = await resolvedSnapshotOptionsForContext(ctx, config, options.signal);
519
+ validateMutation();
520
+ const selected = filterSnapshotForConfigPolicy(syncSessionsSelected(config) ? decoded : snapshotWithoutSessions(decoded), config, snapshotOptions);
452
521
  const remote = portableSnapshot(regenerateSnapshotIdentity(selected), config.localFields);
453
- const local = await createSnapshot(config.snapshotIdentity, snapshotOptionsForContext(ctx, config));
522
+ const local = await createSnapshot(config.snapshotIdentity, snapshotOptions);
454
523
  const expectedHead = await backend.readHead(options.signal);
455
524
  const currentRemote = expectedHead ? await readSnapshotForHead(backend, expectedHead, options.signal) : undefined;
456
525
  validateMutation();
@@ -458,10 +527,15 @@ export async function rollback(ctx, options, factory = createSyncBackend, expect
458
527
  return;
459
528
  validateMutation();
460
529
  const physical = overlayLocalFields(remote, local, config.localFields);
461
- const caseCleanup = options.yes ? [] : await inspectCaseCleanup(physical, options.signal);
530
+ if (config.scope === "agent-directory")
531
+ requireStableMergeSessionRoot(local, physical, config.scope);
532
+ const upload = await snapshotForUpload(backend, config, remote, expectedHead, currentRemote, snapshotOptions);
533
+ if (config.scope === "agent-directory")
534
+ validatePortableSnapshot(upload);
535
+ const caseCleanup = options.yes ? [] : await inspectCaseCleanup(physical, snapshotOptions);
462
536
  validateMutation();
463
537
  if (!options.yes) {
464
- const confirmed = await ctx.ui.confirm(snapshotIncludesSessions(remote) ? "Rollback pi settings and sessions?" : "Rollback pi settings?", formatRollbackSummary(config, backend.destination, local, physical, target, protectedSessionPaths(ctx), caseCleanup.map((item) => item.path)), { signal: options.signal });
538
+ const confirmed = await ctx.ui.confirm(snapshotIncludesSessions(remote) ? "Rollback pi settings and sessions?" : "Rollback pi settings?", formatRollbackSummary(config, backend.destination, local, physical, target, protectedSessionPaths(ctx, snapshotOptions.sessionDir), caseCleanup.map((item) => item.path)), { signal: options.signal });
465
539
  validateMutation();
466
540
  if (!confirmed) {
467
541
  ctx.ui.notify("Rollback cancelled.", "info");
@@ -469,7 +543,7 @@ export async function rollback(ctx, options, factory = createSyncBackend, expect
469
543
  }
470
544
  }
471
545
  validateMutation();
472
- const currentLocal = await createSnapshot(config.snapshotIdentity, snapshotOptionsForContext(ctx, config));
546
+ const currentLocal = await createSnapshot(config.snapshotIdentity, snapshotOptions);
473
547
  if (!sameHashes(fileHashMap(currentLocal), fileHashMap(local)))
474
548
  throw new Error("Local bytes changed during rollback review.");
475
549
  if (syncCheckConfigFingerprint(config) !== syncCheckConfigFingerprint(await loadConfig(options.setup)))
@@ -478,22 +552,26 @@ export async function rollback(ctx, options, factory = createSyncBackend, expect
478
552
  throw new Error("Remote changed during rollback review.");
479
553
  validateMutation();
480
554
  throwIfAborted(options.signal);
481
- const backup = await backupLocal(config.snapshotIdentity, snapshotOptionsForContext(ctx, config), options.signal);
482
- const applySessionDir = await sessionDirForApply(ctx, remote);
555
+ const backup = await backupLocal(config.snapshotIdentity, snapshotOptions, options.signal);
556
+ const applySessionDir = await sessionDirForApply(ctx, config.scope ? physical : remote, snapshotOptions);
483
557
  const currentState = await readStateForConfig(config);
484
558
  if (!options.yes && syncStateFingerprint(currentState) !== syncStateFingerprint(state))
485
559
  throw new Error("Baseline changed during rollback review.");
486
560
  requireResolvedDirectionalProgress(currentState, options, false);
487
561
  if (!options.yes)
488
- await revalidateCaseCleanup(caseCleanup, physical, options.signal);
562
+ await revalidateCaseCleanup(caseCleanup, physical, snapshotOptions);
563
+ if (config.scope && applySessionDir !== (await effectiveSessionRoot(ctx, config, options.signal)))
564
+ throw new Error("Pi session storage changed during rollback review.");
565
+ validateMutation();
566
+ if (syncCheckConfigFingerprint(config) !== syncCheckConfigFingerprint(await loadConfig(options.setup)))
567
+ throw new Error("Settings changed during rollback review.");
489
568
  validateMutation();
490
569
  options.onCommit?.();
491
- const lastFileHashes = await applySnapshot(physical, protectedSessionPaths(ctx), {
492
- include: config.include,
493
- ...(config.exclude === undefined ? {} : { exclude: [...config.exclude] }),
570
+ const lastFileHashes = await applySnapshot(physical, protectedSessionPaths(ctx, snapshotOptions.sessionDir), {
571
+ ...snapshotOptions,
494
572
  sessionDir: applySessionDir,
495
- signal: options.signal,
496
573
  validateMutation,
574
+ ...(config.scope === "agent-directory" ? { reviewedLocal: local } : {}),
497
575
  expectedFileHashes: config.localFields?.length
498
576
  ? { "settings.json": fileHashMap(local)["settings.json"] ?? null }
499
577
  : undefined,
@@ -502,11 +580,8 @@ export async function rollback(ctx, options, factory = createSyncBackend, expect
502
580
  validateCommittedOwner();
503
581
  let result;
504
582
  try {
505
- const completionSignal = AbortSignal.timeout(POST_LOCAL_COMMIT_TIMEOUT_MS);
506
- const upload = await snapshotForUpload(backend, config, remote, expectedHead, currentRemote, completionSignal);
507
- validateCommittedOwner();
508
583
  result = await backend.publishSnapshot(upload, expectedRemoteHead(expectedHead), {
509
- signal: completionSignal,
584
+ signal: AbortSignal.timeout(POST_LOCAL_COMMIT_TIMEOUT_MS),
510
585
  });
511
586
  }
512
587
  catch (error) {
@@ -521,8 +596,7 @@ export async function rollback(ctx, options, factory = createSyncBackend, expect
521
596
  lastFileHashes: config.localFields?.length
522
597
  ? { ...lastFileHashes, "settings.json": fileHashMap(remote)["settings.json"] }
523
598
  : lastFileHashes,
524
- include: [...config.include],
525
- ...(config.exclude === undefined ? {} : { exclude: [...config.exclude] }),
599
+ ...acceptedSelection(config),
526
600
  ...(config.localFields !== undefined ? { localFields: config.localFields } : {}),
527
601
  }, remote, validateCommittedOwner);
528
602
  }
@@ -563,11 +637,15 @@ async function readRemoteSnapshotForUpload(backend, config, head, state, signal)
563
637
  }
564
638
  return readSnapshotForHead(backend, head, signal);
565
639
  }
566
- async function snapshotForUpload(backend, config, local, head, remote, signal) {
640
+ async function snapshotForUpload(backend, config, local, head, remote, options) {
567
641
  if (!head)
568
642
  return local;
569
- const snapshot = remote ?? (await readSnapshotForHead(backend, head, signal));
570
- return mergeRemotePreservedFiles(local, snapshot, config);
643
+ const snapshot = remote ?? (await readSnapshotForHead(backend, head, options.signal));
644
+ const remoteScoped = snapshot.selection?.version === 3;
645
+ if (remoteScoped !== (config.scope === "agent-directory")) {
646
+ throw new Error("Converting an existing remote between included paths and agent-directory scope is not supported. Use a separate storage location.");
647
+ }
648
+ return mergeRemotePreservedFiles(local, snapshot, config, options);
571
649
  }
572
650
  async function confirmPush(ctx, options, config, backend, local, upload, head, remote, title = snapshotIncludesSessions(upload) ? "Push pi settings and sessions?" : "Push pi settings?") {
573
651
  throwIfAborted(options.signal);
@@ -586,4 +664,7 @@ function sameRemoteHead(backend, left, right) {
586
664
  return left === right;
587
665
  return backend.sameRevision(left.revision, right.revision);
588
666
  }
667
+ function matchesInitialHead(initial, backend, current) {
668
+ return initial.head?.snapshotId === current?.snapshotId && sameRemoteHead(backend, initial.head, current);
669
+ }
589
670
  export { backupLocal } from "./sync-local.js";
@@ -1,12 +1,13 @@
1
- import type { Snapshot, SnapshotSelection } from "../snapshot/snapshot-types.js";
1
+ import type { DirectoryScope, Snapshot, SnapshotSelection } from "../snapshot/snapshot-types.js";
2
2
  export declare const BUILT_IN_SYNC_ROOTS: readonly ["settings.json", "keybindings.json", "models.json", "AGENTS.md", "APPEND_SYSTEM.md", "skills", "prompts", "themes", "extensions"];
3
3
  export declare const DEFAULT_SYNC_INCLUDE: readonly ["settings.json", "keybindings.json", "models.json", "AGENTS.md", "APPEND_SYSTEM.md", "skills", "prompts", "themes", "extensions"];
4
4
  export type BuiltInSyncFile = (typeof BUILT_IN_SYNC_ROOTS)[number];
5
5
  export declare function normalizeSyncInclude(value: unknown): string[];
6
+ export declare function normalizeDirectoryRules(value: unknown): string[];
6
7
  export declare function portableSnapshotSelection(value: unknown): SnapshotSelection;
7
8
  export declare function snapshotSelectionInclude(snapshot: Pick<Snapshot, "selection">): string[] | undefined;
8
9
  export declare function snapshotSelectionExclude(snapshot: Pick<Snapshot, "selection">): string[] | undefined;
9
- export declare function selectionForSnapshot(include: unknown, exclude?: unknown): SnapshotSelection;
10
+ export declare function selectionForSnapshot(include: unknown, exclude?: unknown, directory?: DirectoryScope): SnapshotSelection;
10
11
  /** Metadata equality, not policy compatibility: bind the whole projection to its immutable image. */
11
12
  export declare function sameSnapshotSelection(left: SnapshotSelection | undefined, right: SnapshotSelection | undefined): boolean;
12
13
  export declare function validateSnapshotSelection(snapshot: Pick<Snapshot, "version" | "selection">): void;
@@ -19,19 +20,20 @@ export declare function compareSyncInclude(local: unknown, remote: unknown): {
19
20
  export type RemoteSelectionState = {
20
21
  kind: "legacy";
21
22
  discovered: string[];
22
- } | {
23
+ } | ({
23
24
  kind: "same";
24
25
  include: string[];
25
26
  exclude?: string[];
26
- } | {
27
+ } & DirectoryScope) | ({
27
28
  kind: "different";
28
29
  include: string[];
29
30
  exclude?: string[];
30
31
  remoteOnly: string[];
31
32
  localOnly: string[];
32
33
  excludeChanged?: boolean;
33
- };
34
- export declare function inspectRemoteSelection(localInclude: unknown, snapshot: Pick<Snapshot, "selection" | "files">, localExclude?: unknown): RemoteSelectionState;
34
+ } & DirectoryScope);
35
+ export declare function syncDirectoryPolicyKey(config: SyncSelectionConfig): string | undefined;
36
+ export declare function inspectRemoteSelection(localInclude: unknown, snapshot: Pick<Snapshot, "selection" | "files">, localExclude?: unknown, directory?: DirectoryScope): RemoteSelectionState;
35
37
  export interface RemoteSelectionDecision {
36
38
  setupName: string;
37
39
  configIdentity: string;
@@ -39,20 +41,22 @@ export interface RemoteSelectionDecision {
39
41
  remoteInclude: readonly string[];
40
42
  localExclude?: readonly string[];
41
43
  remoteExclude?: readonly string[];
44
+ localDirectory?: DirectoryScope;
45
+ remoteDirectory?: DirectoryScope;
42
46
  }
43
47
  export declare class RemoteSelectionMismatchError extends Error {
44
48
  readonly decision: RemoteSelectionDecision;
45
49
  readonly setupName: string;
46
50
  readonly localInclude: string[];
47
51
  readonly remoteInclude: string[];
48
- constructor(setupName: string, localInclude: unknown, remoteInclude: unknown, configIdentity?: string, localExclude?: string[], remoteExclude?: string[]);
52
+ constructor(setupName: string, localInclude: unknown, remoteInclude: unknown, configIdentity?: string, localExclude?: string[], remoteExclude?: string[], localDirectory?: DirectoryScope, remoteDirectory?: DirectoryScope);
49
53
  }
50
54
  export declare function remoteSelectionMismatch(config: {
51
55
  setupName: string;
52
56
  include: unknown;
53
57
  exclude?: string[];
54
- }, remoteInclude: unknown, configIdentity?: string, remoteExclude?: string[]): RemoteSelectionMismatchError;
55
- export declare function formatRemoteSelectionMismatch(setupName: string, localInclude: readonly string[], remoteInclude: readonly string[], localExclude?: readonly string[], remoteExclude?: readonly string[]): string;
58
+ } & DirectoryScope, remoteInclude: unknown, configIdentity?: string, remoteExclude?: string[], remoteDirectory?: DirectoryScope): RemoteSelectionMismatchError;
59
+ export declare function formatRemoteSelectionMismatch(setupName: string, localInclude: readonly string[], remoteInclude: readonly string[], localExclude?: readonly string[], remoteExclude?: readonly string[], localDirectory?: DirectoryScope, remoteDirectory?: DirectoryScope): string;
56
60
  export declare function discoverLegacySnapshotInclude(snapshot: Pick<Snapshot, "files">): string[];
57
61
  export declare function syncIncludeSelection(value: unknown): {
58
62
  include: string[];
@@ -61,7 +65,7 @@ export declare function syncIncludeSelection(value: unknown): {
61
65
  sessions: boolean;
62
66
  };
63
67
  export declare function customIncludePathsByLower(value: unknown): Map<string, string>;
64
- export interface SyncSelectionConfig {
68
+ export interface SyncSelectionConfig extends DirectoryScope {
65
69
  include?: unknown;
66
70
  exclude?: unknown;
67
71
  syncFiles?: unknown;
@@ -69,6 +73,12 @@ export interface SyncSelectionConfig {
69
73
  extraFiles?: unknown;
70
74
  }
71
75
  export declare function includeFromSelectionConfig(config: SyncSelectionConfig): string[];
76
+ export declare function syncSelectionHasContent(config: SyncSelectionConfig): boolean;
77
+ export declare const MAX_AGENT_DIRECTORY_ENTRIES = 65536;
78
+ export declare const MAX_AGENT_DIRECTORY_FILES = 16384;
79
+ export declare function assertAgentDirectoryPathLayout(files: Iterable<string>): void;
80
+ export declare function compileSyncPolicyExclude(config: SyncSelectionConfig): (relativePath: string) => boolean;
81
+ export declare function compileSyncPolicyTraversal(config: SyncSelectionConfig): (relativePath: string) => boolean;
72
82
  export declare function syncSessionsSelected(config: SyncSelectionConfig): boolean;
73
83
  export declare function isConfiguredSnapshotPath(relativePath: string, config: SyncSelectionConfig, _legacyExtraFiles?: Set<string>): boolean;
74
84
  export declare function configuredSnapshotPathMatcher(config: SyncSelectionConfig): (relativePath: string) => boolean;