@narumitw/pi-sync-daemon 0.7.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (93) hide show
  1. package/CHANGELOG.md +21 -0
  2. package/README.md +16 -2
  3. package/dist/cli.js +1 -1
  4. package/dist/consent.d.ts +14 -2
  5. package/dist/consent.js +147 -14
  6. package/dist/engine/backends/git/git-backend.d.ts +2 -3
  7. package/dist/engine/backends/git/git-backend.js +71 -25
  8. package/dist/engine/backends/git/git-storage.d.ts +1 -1
  9. package/dist/engine/backends/git/git-storage.js +30 -9
  10. package/dist/engine/backends/s3/s3-backend.js +8 -0
  11. package/dist/engine/backends/sync-backend.d.ts +1 -0
  12. package/dist/engine/backends/webdav/webdav-backend.js +8 -0
  13. package/dist/engine/commands/command-types.d.ts +2 -1
  14. package/dist/engine/host.d.ts +1 -0
  15. package/dist/engine/ignore/effective-ignore-policy.d.ts +10 -0
  16. package/dist/engine/ignore/effective-ignore-policy.js +33 -0
  17. package/dist/engine/ignore/ignore-edit.d.ts +13 -0
  18. package/dist/engine/ignore/ignore-edit.js +102 -0
  19. package/dist/engine/ignore/ignore-initialization.d.ts +9 -0
  20. package/dist/engine/ignore/ignore-initialization.js +252 -0
  21. package/dist/engine/ignore/ignore-migration-prompt.d.ts +7 -0
  22. package/dist/engine/ignore/ignore-migration-prompt.js +139 -0
  23. package/dist/engine/ignore/ignore-settings.d.ts +30 -0
  24. package/dist/engine/ignore/ignore-settings.js +393 -0
  25. package/dist/engine/ignore/ignore-source.d.ts +27 -0
  26. package/dist/engine/ignore/ignore-source.js +250 -0
  27. package/dist/engine/settings/config-file.d.ts +9 -2
  28. package/dist/engine/settings/config-file.js +124 -28
  29. package/dist/engine/settings/config.d.ts +6 -2
  30. package/dist/engine/settings/config.js +140 -11
  31. package/dist/engine/settings/settings-management.d.ts +5 -3
  32. package/dist/engine/settings/settings-management.js +24 -10
  33. package/dist/engine/settings/settings-types.d.ts +25 -2
  34. package/dist/engine/settings/settings-validation.js +23 -5
  35. package/dist/engine/snapshot/session-paths.d.ts +1 -1
  36. package/dist/engine/snapshot/session-paths.js +41 -13
  37. package/dist/engine/snapshot/snapshot-apply.d.ts +3 -3
  38. package/dist/engine/snapshot/snapshot-apply.js +23 -4
  39. package/dist/engine/snapshot/snapshot-codec.d.ts +1 -1
  40. package/dist/engine/snapshot/snapshot-codec.js +14 -5
  41. package/dist/engine/snapshot/snapshot-exclude-safety.d.ts +4 -2
  42. package/dist/engine/snapshot/snapshot-exclude-safety.js +76 -19
  43. package/dist/engine/snapshot/snapshot-transaction-images.d.ts +3 -1
  44. package/dist/engine/snapshot/snapshot-transaction-images.js +33 -3
  45. package/dist/engine/snapshot/snapshot-transaction-policy.d.ts +30 -2
  46. package/dist/engine/snapshot/snapshot-transaction-policy.js +135 -11
  47. package/dist/engine/snapshot/snapshot-transaction-verification.d.ts +7 -0
  48. package/dist/engine/snapshot/snapshot-transaction-verification.js +78 -0
  49. package/dist/engine/snapshot/snapshot-transaction.d.ts +1 -12
  50. package/dist/engine/snapshot/snapshot-transaction.js +129 -109
  51. package/dist/engine/snapshot/snapshot-types.d.ts +27 -1
  52. package/dist/engine/snapshot/snapshot-types.js +9 -1
  53. package/dist/engine/snapshot/snapshot.d.ts +6 -4
  54. package/dist/engine/snapshot/snapshot.js +91 -34
  55. package/dist/engine/state/state-types.d.ts +1 -0
  56. package/dist/engine/sync/agent-plan.js +1 -0
  57. package/dist/engine/sync/agent-sync.js +8 -1
  58. package/dist/engine/sync/continuous-sync.d.ts +3 -1
  59. package/dist/engine/sync/continuous-sync.js +50 -18
  60. package/dist/engine/sync/continuous-watch.js +4 -1
  61. package/dist/engine/sync/initialization.js +3 -2
  62. package/dist/engine/sync/local-fields.d.ts +3 -1
  63. package/dist/engine/sync/local-fields.js +62 -1
  64. package/dist/engine/sync/merge-acceptance.d.ts +8 -0
  65. package/dist/engine/sync/merge-acceptance.js +29 -0
  66. package/dist/engine/sync/merge-apply.js +42 -11
  67. package/dist/engine/sync/merge-journal.d.ts +24 -4
  68. package/dist/engine/sync/merge-journal.js +134 -8
  69. package/dist/engine/sync/merged-sync.d.ts +1 -1
  70. package/dist/engine/sync/merged-sync.js +128 -83
  71. package/dist/engine/sync/remote-snapshot.d.ts +11 -3
  72. package/dist/engine/sync/remote-snapshot.js +72 -18
  73. package/dist/engine/sync/session-push.js +20 -6
  74. package/dist/engine/sync/sync-inspection.js +7 -5
  75. package/dist/engine/sync/sync-mutations.d.ts +2 -1
  76. package/dist/engine/sync/sync-mutations.js +157 -73
  77. package/dist/engine/sync/sync-policy.d.ts +29 -8
  78. package/dist/engine/sync/sync-policy.js +152 -16
  79. package/dist/engine/sync/sync-queries.js +8 -1
  80. package/dist/engine/sync/sync-state.d.ts +4 -2
  81. package/dist/engine/sync/sync-state.js +15 -2
  82. package/dist/engine/sync/transfer-freshness.d.ts +31 -0
  83. package/dist/engine/sync/transfer-freshness.js +82 -0
  84. package/dist/engine-service.d.ts +1 -1
  85. package/dist/engine-service.js +146 -27
  86. package/dist/monitor.d.ts +4 -1
  87. package/dist/monitor.js +84 -32
  88. package/dist/server.d.ts +1 -0
  89. package/dist/server.js +46 -5
  90. package/dist/service-host.d.ts +1 -1
  91. package/dist/service-host.js +2 -1
  92. package/docs/architecture.md +30 -0
  93. package/package.json +2 -1
@@ -29,9 +29,10 @@ interface InitialPullEvidence {
29
29
  head: RemoteHead | undefined;
30
30
  }
31
31
  export declare function pull(ctx: ExtensionCommandContext | ExtensionContext, options: CommandOptions, factory?: SyncBackendFactory, initial?: InitialPullEvidence): Promise<"applied" | "cancelled">;
32
- export declare function syncBoth(ctx: ExtensionCommandContext | ExtensionContext, options: CommandOptions, factory?: SyncBackendFactory): Promise<"applied" | "cancelled" | undefined>;
32
+ export declare function syncBoth(ctx: ExtensionCommandContext | ExtensionContext, options: CommandOptions, factory?: SyncBackendFactory): Promise<"applied" | "archived" | "cancelled" | undefined>;
33
33
  export declare function rollback(ctx: ExtensionCommandContext, options: CommandOptions, factory?: SyncBackendFactory, expectedSelection?: {
34
34
  backendIdentity: string;
35
35
  setup?: string;
36
+ snapshotId?: string;
36
37
  }): Promise<void>;
37
38
  export { backupLocal } from "./sync-local.js";
@@ -2,11 +2,12 @@ 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
4
  import { effectiveSessionRoot, requireStableMergeSessionRoot, resolvedSnapshotOptionsForContext, sessionDirForApply, } from "../snapshot/session-paths.js";
5
- import { createSnapshot, filterSnapshotForConfigPolicy, mergeRemotePreservedFiles, regenerateSnapshotIdentity, scanSnapshot, snapshotIncludesSessions, snapshotWithoutSessions, } from "../snapshot/snapshot.js";
5
+ import { createSnapshot, filterSnapshotForConfigPolicy, regenerateSnapshotIdentity, scanSnapshot, snapshotIncludesSessions, snapshotWithoutSessions, } from "../snapshot/snapshot.js";
6
6
  import { applySnapshot } from "../snapshot/snapshot-apply.js";
7
+ import { ignorePolicyValidator } from "../snapshot/snapshot-transaction-policy.js";
7
8
  import { pruneMergeBaselines } from "../state/merge-baseline-store.js";
8
9
  import { readStateForConfig, syncStateFingerprint, writeStateForConfig } from "../state/sync-state-store.js";
9
- import { countPreservedRemoteFiles, formatPullSummary, formatPushSummary, formatRollbackSummary, } from "../ui/sync-format.js";
10
+ import { countPreservedRemoteFiles, formatPublicationPreview, formatPullSummary, formatPushSummary, formatRollbackSummary, } from "../ui/sync-format.js";
10
11
  import { setSyncStatus } from "../ui/sync-status.js";
11
12
  import { confirmTransferReview } from "../ui/transfer-review.js";
12
13
  import { startupTransferEnabled } from "./agent-policy.js";
@@ -15,20 +16,16 @@ import { confirmFieldMigration } from "./field-migration.js";
15
16
  import { overlayLocalFields, portableSnapshot, sameLocalFields, validatePortableSnapshot } from "./local-fields.js";
16
17
  import { readMergeJournal, requireNoMergeJournal, retireMergeJournal } from "./merge-journal.js";
17
18
  import { mergeSync } from "./merged-sync.js";
18
- import { readRemoteSnapshot, readSnapshotForHead, requireCompatibleRemoteSelection } from "./remote-snapshot.js";
19
+ import { readRemoteSnapshot, readRemoteSnapshotForUpload, readSnapshotForHead, requireCompatibleRemoteSelection, sameRemoteHead, snapshotForUpload, } from "./remote-snapshot.js";
19
20
  import { throwIfAborted } from "./signals.js";
20
21
  import { createSyncDecision } from "./sync-decision.js";
21
22
  import { errorMessage } from "./sync-errors.js";
22
23
  import { backupLocal, captureMutationOwner, protectedSessionPaths } from "./sync-local.js";
23
- import { inspectRemoteSelection, syncSelectionHasContent, syncSessionsSelected } from "./sync-policy.js";
24
+ import { formatIgnorePolicyComparison, inspectRemoteSelection, requireLegacyTransferPolicy, syncSelectionHasContent, syncSessionsSelected, } from "./sync-policy.js";
24
25
  import { acceptedSelection, canPullRemoteSessionsOnFirstSync, canPullRemoteSettingsOnFirstSync, fileHashMap, hasLocalChanges, hasRemoteChanges, remoteChangedSinceState, sameHashes, shouldRefreshSyncedState, snapshotHashesMatchState, snapshotsMatch, syncPolicyChanged, } from "./sync-state.js";
26
+ import { directionalApplyGuards, requireIgnoreBaselineReview, requireResolvedDirectionalProgress, validateDirectionalPublication, } from "./transfer-freshness.js";
25
27
  const VERSION = 1;
26
28
  const POST_LOCAL_COMMIT_TIMEOUT_MS = 30_000;
27
- /** Whole-direction acceptance must never forget withheld state without an explicit recovery choice. */
28
- function requireResolvedDirectionalProgress(state, options, allowForce = true) {
29
- if (state.unresolved?.length && (options.auto || !options.force || !allowForce))
30
- throw new Error("Unresolved partial conflicts remain. Review /sync conflicts or explicitly choose push --force or pull --force; automatic transfer and rollback cannot accept unresolved groups.");
31
- }
32
29
  export class PublicationStatePersistenceError extends Error {
33
30
  head;
34
31
  backupPath;
@@ -50,16 +47,23 @@ export class RollbackPublicationError extends Error {
50
47
  }
51
48
  }
52
49
  export async function push(ctx, options, input, factory = createSyncBackend) {
53
- const validateMutation = captureMutationOwner(ctx, options.signal);
50
+ const validateOwner = captureMutationOwner(ctx, options.signal);
54
51
  const validateCommittedOwner = captureMutationOwner(ctx);
55
- const config = input?.config ?? (await loadConfig(options.setup));
56
- throwIfAborted(options.signal);
52
+ const config = input?.config ?? (await loadConfig(options.setup, options.signal));
53
+ const validateMutation = () => {
54
+ validateOwner();
55
+ options.background?.validate(config);
56
+ };
57
+ validateMutation();
57
58
  await requireNoMergeJournal(config, options);
58
59
  const state = input?.state ?? (await readStateForConfig(config));
59
60
  validateMutation();
60
61
  requireResolvedDirectionalProgress(state, options);
61
62
  if (options.auto &&
62
- (config.scope === "agent-directory" || state.scope !== undefined) &&
63
+ (config.scope === "agent-directory" ||
64
+ state.scope !== undefined ||
65
+ config.reservedIgnoreNames !== undefined ||
66
+ state.ignorePolicyKey !== undefined) &&
63
67
  (options.force || !state.lastAppliedSnapshot || syncPolicyChanged(state, config))) {
64
68
  throw new Error("Automatic push requires an accepted baseline with matching content policy.");
65
69
  }
@@ -68,20 +72,21 @@ export async function push(ctx, options, input, factory = createSyncBackend) {
68
72
  throwIfAborted(options.signal);
69
73
  const snapshotOptions = await resolvedSnapshotOptionsForContext(ctx, config, options.signal);
70
74
  validateMutation();
75
+ const validateIgnorePolicy = ignorePolicyValidator({ ...snapshotOptions, validateMutation });
71
76
  const localRaw = input?.local ?? (await createSnapshot(config.snapshotIdentity, snapshotOptions));
72
77
  const local = portableSnapshot(localRaw, config.localFields);
78
+ if (validateIgnorePolicy)
79
+ await validateIgnorePolicy();
73
80
  throwIfAborted(options.signal);
74
81
  let head = await backend.readHead(options.signal);
75
- let remoteForUpload = await readRemoteSnapshotForUpload(backend, config, head, state, options.signal);
76
- if (!options.force &&
77
- !remoteForUpload &&
78
- head &&
79
- (config.scope === "agent-directory" ||
80
- (head.selection &&
81
- inspectRemoteSelection(config.include, { selection: head.selection, files: [] }, config.exclude, config)
82
- .kind === "different"))) {
83
- remoteForUpload = await readSnapshotForHead(backend, head, options.signal);
82
+ let remoteForUpload = await readRemoteSnapshotForUpload(backend, config, head, state, options);
83
+ validateMutation();
84
+ if (config.ignorePolicy && remoteForUpload && options.force && (options.auto || options.yes || !ctx.hasUI)) {
85
+ const comparison = inspectRemoteSelection(config.include, remoteForUpload, config.exclude, config);
86
+ if (comparison.kind === "different")
87
+ requireCompatibleRemoteSelection(config, remoteForUpload);
84
88
  }
89
+ requireIgnoreBaselineReview(ctx, config, state, options);
85
90
  if (remoteForUpload && !options.force) {
86
91
  requireCompatibleRemoteSelection(config, remoteForUpload);
87
92
  }
@@ -104,7 +109,8 @@ export async function push(ctx, options, input, factory = createSyncBackend) {
104
109
  }
105
110
  }
106
111
  if (!remoteForUpload && head && (config.localFields !== undefined || !options.yes))
107
- remoteForUpload = await readSnapshotForHead(backend, head, options.signal);
112
+ remoteForUpload = await readSnapshotForHead(backend, head, options.signal, config);
113
+ validateMutation();
108
114
  if (!(await confirmFieldMigration(ctx, config, state, remoteForUpload, options.force, options.signal))) {
109
115
  setSyncStatus(ctx, undefined);
110
116
  return "cancelled";
@@ -117,14 +123,17 @@ export async function push(ctx, options, input, factory = createSyncBackend) {
117
123
  throw new Error(`Refusing to push possible secrets:\n${secrets.map((s) => `- ${s}`).join("\n")}`);
118
124
  }
119
125
  }
120
- if (!(await confirmPush(ctx, options, config, backend, local, upload, head, remoteForUpload))) {
126
+ if (!(await confirmPush(ctx, options, config, backend, local, upload, head, remoteForUpload, validateMutation))) {
121
127
  return "cancelled";
122
128
  }
123
129
  if (options.force) {
124
130
  const refreshedHead = await backend.readHead(options.signal);
131
+ validateMutation();
125
132
  if (!sameRemoteHead(backend, head, refreshedHead)) {
133
+ if (config.ignorePolicy)
134
+ throw new Error("Remote changed during ignore-file push review; reopen the review.");
126
135
  head = refreshedHead;
127
- remoteForUpload = head ? await readSnapshotForHead(backend, head, options.signal) : undefined;
136
+ remoteForUpload = head ? await readSnapshotForHead(backend, head, options.signal, config) : undefined;
128
137
  validateMutation();
129
138
  if (!(await confirmFieldMigration(ctx, config, state, remoteForUpload, options.force, options.signal))) {
130
139
  setSyncStatus(ctx, undefined);
@@ -132,7 +141,7 @@ export async function push(ctx, options, input, factory = createSyncBackend) {
132
141
  }
133
142
  validateMutation();
134
143
  upload = await snapshotForUpload(backend, config, local, head, remoteForUpload, snapshotOptions);
135
- if (!(await confirmPush(ctx, options, config, backend, local, upload, head, remoteForUpload, "Remote changed during review. Push the refreshed plan?"))) {
144
+ if (!(await confirmPush(ctx, options, config, backend, local, upload, head, remoteForUpload, validateMutation, "Remote changed during review. Push the refreshed plan?"))) {
136
145
  return "cancelled";
137
146
  }
138
147
  }
@@ -142,6 +151,7 @@ export async function push(ctx, options, input, factory = createSyncBackend) {
142
151
  throw new Error("Settings changed during push review.");
143
152
  validateMutation();
144
153
  if (config.scope === "agent-directory" ||
154
+ validateIgnorePolicy ||
145
155
  !options.yes ||
146
156
  config.localFields !== undefined ||
147
157
  (await readMergeJournal(config))) {
@@ -150,7 +160,7 @@ export async function push(ctx, options, input, factory = createSyncBackend) {
150
160
  throw new Error("Local content changed during push review; retry from current bytes.");
151
161
  }
152
162
  const currentState = await readStateForConfig(config);
153
- if (!options.yes && syncStateFingerprint(currentState) !== syncStateFingerprint(state))
163
+ if ((validateIgnorePolicy || !options.yes) && syncStateFingerprint(currentState) !== syncStateFingerprint(state))
154
164
  throw new Error("Baseline changed during push review.");
155
165
  requireResolvedDirectionalProgress(currentState, options);
156
166
  if (config.scope === "agent-directory" &&
@@ -160,9 +170,22 @@ export async function push(ctx, options, input, factory = createSyncBackend) {
160
170
  if (configIdentity !== syncCheckConfigFingerprint(await loadConfig(options.setup)))
161
171
  throw new Error("Settings changed during push review.");
162
172
  validateMutation();
173
+ const validatePublication = validateIgnorePolicy || options.background
174
+ ? () => validateDirectionalPublication(ctx, config, snapshotOptions, state, fileHashMap(localRaw), validateIgnorePolicy ??
175
+ (async () => {
176
+ if (configIdentity !== syncCheckConfigFingerprint(await loadConfig(options.setup, options.signal)))
177
+ throw new Error("Settings changed before push publication.");
178
+ validateMutation();
179
+ }), "push")
180
+ : undefined;
181
+ if (validateIgnorePolicy) {
182
+ validatePortableSnapshot(upload);
183
+ await validateIgnorePolicy();
184
+ }
163
185
  const result = await backend.publishSnapshot(upload, expectedRemoteHead(head), {
164
186
  signal: options.signal,
165
187
  onCommit: options.onCommit,
188
+ ...(validatePublication ? { validateIgnorePolicy: validatePublication } : {}),
166
189
  });
167
190
  try {
168
191
  await writeStateForConfig(config, {
@@ -212,6 +235,7 @@ export async function pull(ctx, options, factory = createSyncBackend, initial) {
212
235
  requireResolvedDirectionalProgress(state, options);
213
236
  const snapshotOptions = await resolvedSnapshotOptionsForContext(ctx, config, options.signal);
214
237
  validateMutation();
238
+ const validateIgnorePolicy = ignorePolicyValidator({ ...snapshotOptions, validateMutation });
215
239
  if (initial && initial.sessionDir !== snapshotOptions.sessionDir)
216
240
  throw new Error("Pi session storage changed before initial pull; run sync again.");
217
241
  const local = await createSnapshot(config.snapshotIdentity, snapshotOptions);
@@ -222,6 +246,7 @@ export async function pull(ctx, options, factory = createSyncBackend, initial) {
222
246
  validateMutation();
223
247
  if (initial && !matchesInitialHead(initial, backend, head))
224
248
  throw new Error("Remote changed before initial pull; run sync again.");
249
+ requireIgnoreBaselineReview(ctx, config, state, options);
225
250
  const localChanged = hasLocalChanges(local, state, config);
226
251
  if (!remote) {
227
252
  throw createSyncDecision({
@@ -246,7 +271,8 @@ export async function pull(ctx, options, factory = createSyncBackend, initial) {
246
271
  const physical = overlayLocalFields(logical, local, config.localFields);
247
272
  if (config.scope === "agent-directory")
248
273
  requireStableMergeSessionRoot(local, physical, config.scope);
249
- const remoteChanged = hasRemoteChanges(remote, state, config, protectedSessionPaths(ctx, snapshotOptions.sessionDir));
274
+ const reviewedProtectedPaths = protectedSessionPaths(ctx, snapshotOptions.sessionDir);
275
+ const remoteChanged = hasRemoteChanges(remote, state, config, reviewedProtectedPaths);
250
276
  if (localChanged && remoteChanged && state.lastAppliedSnapshot && !options.force) {
251
277
  throw createSyncDecision({
252
278
  kind: "both-changed",
@@ -262,7 +288,7 @@ export async function pull(ctx, options, factory = createSyncBackend, initial) {
262
288
  const caseCleanup = options.yes ? [] : await inspectCaseCleanup(physical, snapshotOptions);
263
289
  validateMutation();
264
290
  if (!options.yes &&
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))) {
291
+ !(await confirmTransferReview(ctx, snapshotIncludesSessions(remote) ? "Pull pi settings and sessions?" : "Pull pi settings?", formatPullSummary(config, backend.destination, local, physical, reviewedProtectedPaths, caseCleanup.map((item) => item.path)), options.signal, validateMutation))) {
266
292
  setSyncStatus(ctx, undefined);
267
293
  ctx.ui.notify("Pull cancelled.", "info");
268
294
  return "cancelled";
@@ -296,7 +322,8 @@ export async function pull(ctx, options, factory = createSyncBackend, initial) {
296
322
  await requireFreshRecovery();
297
323
  const currentState = await readStateForConfig(config);
298
324
  validateMutation();
299
- if ((initial || !options.yes) && syncStateFingerprint(currentState) !== syncStateFingerprint(state))
325
+ if ((validateIgnorePolicy || initial || !options.yes) &&
326
+ syncStateFingerprint(currentState) !== syncStateFingerprint(state))
300
327
  throw new Error("Baseline changed during pull review.");
301
328
  requireResolvedDirectionalProgress(currentState, options);
302
329
  if (!options.yes)
@@ -310,12 +337,33 @@ export async function pull(ctx, options, factory = createSyncBackend, initial) {
310
337
  if (configIdentity !== syncCheckConfigFingerprint(await loadConfig(options.setup)))
311
338
  throw new Error("Settings changed during pull review.");
312
339
  validateMutation();
313
- options.onCommit?.();
314
- const lastFileHashes = await applySnapshot(physical, protectedSessionPaths(ctx, snapshotOptions.sessionDir), {
340
+ if (validateIgnorePolicy) {
341
+ if (!sameRemoteHead(backend, head, await backend.readHead(options.signal)))
342
+ throw new Error("Remote changed during pull review.");
343
+ await validateIgnorePolicy();
344
+ }
345
+ const protectedPaths = protectedSessionPaths(ctx, snapshotOptions.sessionDir);
346
+ const applyGuards = directionalApplyGuards({
347
+ ctx,
348
+ config,
349
+ backend,
350
+ state,
351
+ sessionDir: snapshotOptions.sessionDir,
352
+ head,
353
+ protectedPaths: reviewedProtectedPaths,
354
+ signal: options.signal,
355
+ onCommit: options.onCommit,
356
+ validateMutation,
357
+ validateIgnorePolicy,
358
+ });
359
+ applyGuards.validateMutation();
360
+ if (!validateIgnorePolicy)
361
+ options.onCommit?.();
362
+ const lastFileHashes = await applySnapshot(physical, protectedPaths, {
315
363
  ...snapshotOptions,
316
364
  sessionDir: applySessionDir,
317
- validateMutation,
318
- ...(config.scope === "agent-directory" ? { reviewedLocal: local } : {}),
365
+ ...applyGuards,
366
+ ...(config.scope === "agent-directory" || validateIgnorePolicy ? { reviewedLocal: local } : {}),
319
367
  expectedFileHashes: config.localFields?.length
320
368
  ? { "settings.json": fileHashMap(local)["settings.json"] ?? null }
321
369
  : undefined,
@@ -419,6 +467,9 @@ export async function syncBoth(ctx, options, factory = createSyncBackend) {
419
467
  configIdentity !== syncCheckConfigFingerprint(await loadConfig(options.setup)))
420
468
  throw new Error("Settings or Pi session storage changed before baseline acceptance; run sync again.");
421
469
  validateMutation();
470
+ const validateIgnorePolicy = ignorePolicyValidator({ ...snapshotOptions, validateMutation });
471
+ if (validateIgnorePolicy)
472
+ await validateIgnorePolicy();
422
473
  }
423
474
  const accepted = portableSnapshot(snapshot, config.localFields);
424
475
  await writeStateForConfig(config, {
@@ -500,7 +551,9 @@ export async function rollback(ctx, options, factory = createSyncBackend, expect
500
551
  if (!target)
501
552
  throw new Error("Usage: /sync rollback <snapshot-id> [--yes]");
502
553
  const config = await loadConfig(options.setup);
503
- throwIfAborted(options.signal);
554
+ validateMutation();
555
+ if (config.ignorePolicy && (options.yes || options.auto || !ctx.hasUI))
556
+ throw new Error("Ignore-file rollback requires a separate foreground review; --yes cannot confirm it.");
504
557
  const backend = await factory(config);
505
558
  if (expectedSelection &&
506
559
  (backend.identity !== expectedSelection.backendIdentity || config.setupName !== expectedSelection.setup)) {
@@ -510,32 +563,50 @@ export async function rollback(ctx, options, factory = createSyncBackend, expect
510
563
  await requireNoMergeJournal(config);
511
564
  const state = await readStateForConfig(config);
512
565
  validateMutation();
566
+ requireIgnoreBaselineReview(ctx, config, state, options);
513
567
  requireResolvedDirectionalProgress(state, options, false);
514
568
  const decoded = await backend.readSnapshot(target, options.signal);
569
+ validateMutation();
515
570
  validatePortableSnapshot(decoded);
571
+ if (!config.ignorePolicy)
572
+ requireLegacyTransferPolicy(decoded);
573
+ if (config.ignorePolicy && expectedSelection?.snapshotId && decoded.id !== expectedSelection.snapshotId)
574
+ throw new Error("Historical snapshot changed while history was open; reopen history and retry.");
516
575
  if (!sameLocalFields(decoded.localFields, config.localFields))
517
576
  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.");
518
577
  const snapshotOptions = await resolvedSnapshotOptionsForContext(ctx, config, options.signal);
519
578
  validateMutation();
520
- const selected = filterSnapshotForConfigPolicy(syncSessionsSelected(config) ? decoded : snapshotWithoutSessions(decoded), config, snapshotOptions);
579
+ const validateIgnorePolicy = ignorePolicyValidator({ ...snapshotOptions, validateMutation });
580
+ const selected = filterSnapshotForConfigPolicy(config.ignorePolicy || syncSessionsSelected(config) ? decoded : snapshotWithoutSessions(decoded), config, snapshotOptions);
521
581
  const remote = portableSnapshot(regenerateSnapshotIdentity(selected), config.localFields);
522
582
  const local = await createSnapshot(config.snapshotIdentity, snapshotOptions);
523
583
  const expectedHead = await backend.readHead(options.signal);
524
- const currentRemote = expectedHead ? await readSnapshotForHead(backend, expectedHead, options.signal) : undefined;
584
+ const currentRemote = expectedHead
585
+ ? await readSnapshotForHead(backend, expectedHead, options.signal, config)
586
+ : undefined;
525
587
  validateMutation();
588
+ if (config.ignorePolicy && currentRemote)
589
+ requireCompatibleRemoteSelection(config, currentRemote);
526
590
  if (!(await confirmFieldMigration(ctx, config, state, currentRemote, true, options.signal)))
527
591
  return;
528
592
  validateMutation();
529
593
  const physical = overlayLocalFields(remote, local, config.localFields);
530
594
  if (config.scope === "agent-directory")
531
595
  requireStableMergeSessionRoot(local, physical, config.scope);
532
- const upload = await snapshotForUpload(backend, config, remote, expectedHead, currentRemote, snapshotOptions);
596
+ const upload = config.ignorePolicy
597
+ ? remote
598
+ : await snapshotForUpload(backend, config, remote, expectedHead, currentRemote, snapshotOptions);
533
599
  if (config.scope === "agent-directory")
534
600
  validatePortableSnapshot(upload);
535
601
  const caseCleanup = options.yes ? [] : await inspectCaseCleanup(physical, snapshotOptions);
536
602
  validateMutation();
603
+ const reviewedProtectedPaths = protectedSessionPaths(ctx, snapshotOptions.sessionDir);
537
604
  if (!options.yes) {
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 });
605
+ const title = snapshotIncludesSessions(remote) ? "Rollback pi settings and sessions?" : "Rollback pi settings?";
606
+ const summary = formatRollbackSummary(config, backend.destination, local, physical, target, reviewedProtectedPaths, caseCleanup.map((item) => item.path));
607
+ const confirmed = config.ignorePolicy
608
+ ? await confirmTransferReview(ctx, title, `Historical files are projected through this device's current ignore rules. Historical rules are not adopted. Retained history is not erased.\n\n${summary}\n\nRemote publication:\n${formatPublicationPreview(currentRemote, upload)}`, options.signal, validateMutation)
609
+ : await ctx.ui.confirm(title, summary, { signal: options.signal });
539
610
  validateMutation();
540
611
  if (!confirmed) {
541
612
  ctx.ui.notify("Rollback cancelled.", "info");
@@ -555,7 +626,7 @@ export async function rollback(ctx, options, factory = createSyncBackend, expect
555
626
  const backup = await backupLocal(config.snapshotIdentity, snapshotOptions, options.signal);
556
627
  const applySessionDir = await sessionDirForApply(ctx, config.scope ? physical : remote, snapshotOptions);
557
628
  const currentState = await readStateForConfig(config);
558
- if (!options.yes && syncStateFingerprint(currentState) !== syncStateFingerprint(state))
629
+ if ((validateIgnorePolicy || !options.yes) && syncStateFingerprint(currentState) !== syncStateFingerprint(state))
559
630
  throw new Error("Baseline changed during rollback review.");
560
631
  requireResolvedDirectionalProgress(currentState, options, false);
561
632
  if (!options.yes)
@@ -566,12 +637,33 @@ export async function rollback(ctx, options, factory = createSyncBackend, expect
566
637
  if (syncCheckConfigFingerprint(config) !== syncCheckConfigFingerprint(await loadConfig(options.setup)))
567
638
  throw new Error("Settings changed during rollback review.");
568
639
  validateMutation();
569
- options.onCommit?.();
570
- const lastFileHashes = await applySnapshot(physical, protectedSessionPaths(ctx, snapshotOptions.sessionDir), {
640
+ if (validateIgnorePolicy) {
641
+ if (!sameRemoteHead(backend, expectedHead, await backend.readHead(options.signal)))
642
+ throw new Error("Remote changed during rollback review.");
643
+ await validateIgnorePolicy();
644
+ }
645
+ const protectedPaths = protectedSessionPaths(ctx, snapshotOptions.sessionDir);
646
+ const applyGuards = directionalApplyGuards({
647
+ ctx,
648
+ config,
649
+ backend,
650
+ state,
651
+ sessionDir: snapshotOptions.sessionDir,
652
+ head: expectedHead,
653
+ protectedPaths: reviewedProtectedPaths,
654
+ signal: options.signal,
655
+ onCommit: options.onCommit,
656
+ validateMutation,
657
+ validateIgnorePolicy,
658
+ });
659
+ applyGuards.validateMutation();
660
+ if (!validateIgnorePolicy)
661
+ options.onCommit?.();
662
+ const lastFileHashes = await applySnapshot(physical, protectedPaths, {
571
663
  ...snapshotOptions,
572
664
  sessionDir: applySessionDir,
573
- validateMutation,
574
- ...(config.scope === "agent-directory" ? { reviewedLocal: local } : {}),
665
+ ...applyGuards,
666
+ ...(config.scope === "agent-directory" || validateIgnorePolicy ? { reviewedLocal: local } : {}),
575
667
  expectedFileHashes: config.localFields?.length
576
668
  ? { "settings.json": fileHashMap(local)["settings.json"] ?? null }
577
669
  : undefined,
@@ -580,8 +672,18 @@ export async function rollback(ctx, options, factory = createSyncBackend, expect
580
672
  validateCommittedOwner();
581
673
  let result;
582
674
  try {
675
+ const signal = AbortSignal.timeout(POST_LOCAL_COMMIT_TIMEOUT_MS);
676
+ const validatePolicy = ignorePolicyValidator({
677
+ ...snapshotOptions,
678
+ signal,
679
+ validateMutation: validateCommittedOwner,
680
+ });
681
+ const validatePublication = validatePolicy
682
+ ? () => validateDirectionalPublication(ctx, config, { ...snapshotOptions, sessionDir: applySessionDir, signal }, state, lastFileHashes, validatePolicy, "rollback")
683
+ : undefined;
583
684
  result = await backend.publishSnapshot(upload, expectedRemoteHead(expectedHead), {
584
- signal: AbortSignal.timeout(POST_LOCAL_COMMIT_TIMEOUT_MS),
685
+ signal,
686
+ ...(validatePublication ? { validateIgnorePolicy: validatePublication } : {}),
585
687
  });
586
688
  }
587
689
  catch (error) {
@@ -628,30 +730,17 @@ async function maybeReload(ctx, signal, validateMutation = captureMutationOwner(
628
730
  await ctx.reload();
629
731
  }
630
732
  }
631
- async function readRemoteSnapshotForUpload(backend, config, head, state, signal) {
632
- if (!head ||
633
- (head.snapshotId === state.lastAppliedSnapshot &&
634
- !syncPolicyChanged(state, config) &&
635
- (!state.lastRemoteRevision || backend.sameRevision(head.revision, state.lastRemoteRevision)))) {
636
- return undefined;
637
- }
638
- return readSnapshotForHead(backend, head, signal);
639
- }
640
- async function snapshotForUpload(backend, config, local, head, remote, options) {
641
- if (!head)
642
- return local;
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);
649
- }
650
- async function confirmPush(ctx, options, config, backend, local, upload, head, remote, title = snapshotIncludesSessions(upload) ? "Push pi settings and sessions?" : "Push pi settings?") {
651
- throwIfAborted(options.signal);
733
+ async function confirmPush(ctx, options, config, backend, local, upload, head, remote, validateMutation, title = snapshotIncludesSessions(upload) ? "Push pi settings and sessions?" : "Push pi settings?") {
734
+ validateMutation();
652
735
  if (options.yes)
653
736
  return true;
654
- const confirmed = await confirmTransferReview(ctx, title, formatPushSummary(config, backend.destination, upload, head, countPreservedRemoteFiles(local, upload), remote), options.signal, captureMutationOwner(ctx, options.signal));
737
+ const summary = formatPushSummary(config, backend.destination, upload, head, countPreservedRemoteFiles(local, upload), remote);
738
+ const comparison = config.ignorePolicy && remote
739
+ ? inspectRemoteSelection(config.include, remote, config.exclude, config).ignorePolicyComparison
740
+ : undefined;
741
+ const confirmed = await confirmTransferReview(ctx, title, comparison && comparison !== "match"
742
+ ? `${formatIgnorePolicyComparison(comparison)}\nOnly files selected by this device's rules are published. Remote rules are not adopted.\n\n${summary}`
743
+ : summary, options.signal, validateMutation);
655
744
  throwIfAborted(options.signal);
656
745
  if (confirmed)
657
746
  return true;
@@ -659,12 +748,7 @@ async function confirmPush(ctx, options, config, backend, local, upload, head, r
659
748
  ctx.ui.notify("Push cancelled.", "info");
660
749
  return false;
661
750
  }
662
- function sameRemoteHead(backend, left, right) {
663
- if (!left || !right)
664
- return left === right;
665
- return backend.sameRevision(left.revision, right.revision);
666
- }
667
751
  function matchesInitialHead(initial, backend, current) {
668
- return initial.head?.snapshotId === current?.snapshotId && sameRemoteHead(backend, initial.head, current);
752
+ return sameRemoteHead(backend, initial.head, current);
669
753
  }
670
754
  export { backupLocal } from "./sync-local.js";
@@ -1,4 +1,4 @@
1
- import type { DirectoryScope, Snapshot, SnapshotSelection } from "../snapshot/snapshot-types.js";
1
+ import { type DirectoryScope, type Snapshot, type 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];
@@ -11,28 +11,41 @@ export declare function selectionForSnapshot(include: unknown, exclude?: unknown
11
11
  /** Metadata equality, not policy compatibility: bind the whole projection to its immutable image. */
12
12
  export declare function sameSnapshotSelection(left: SnapshotSelection | undefined, right: SnapshotSelection | undefined): boolean;
13
13
  export declare function validateSnapshotSelection(snapshot: Pick<Snapshot, "version" | "selection">): void;
14
+ export declare function requireLegacyTransferPolicy(snapshot: Partial<Pick<Snapshot, "version" | "selection">>): void;
14
15
  export declare function sameSyncInclude(left: unknown, right: unknown): boolean;
15
16
  export declare function compareSyncInclude(local: unknown, remote: unknown): {
16
17
  same: boolean;
17
18
  remoteOnly: string[];
18
19
  localOnly: string[];
19
20
  };
21
+ export type IgnorePolicyComparison = "match" | "mismatch" | "local-ignore-remote-legacy" | "local-legacy-remote-ignore";
22
+ type PortableDirectoryScope = Pick<DirectoryScope, "scope" | "reinclude">;
20
23
  export type RemoteSelectionState = {
21
24
  kind: "legacy";
22
25
  discovered: string[];
26
+ ignorePolicyComparison?: never;
23
27
  } | ({
24
28
  kind: "same";
25
29
  include: string[];
26
30
  exclude?: string[];
27
- } & DirectoryScope) | ({
31
+ ignorePolicyComparison?: "match";
32
+ } & PortableDirectoryScope) | ({
28
33
  kind: "different";
29
34
  include: string[];
30
35
  exclude?: string[];
31
36
  remoteOnly: string[];
32
37
  localOnly: string[];
33
38
  excludeChanged?: boolean;
34
- } & DirectoryScope);
39
+ ignorePolicyComparison?: Exclude<IgnorePolicyComparison, "match">;
40
+ } & PortableDirectoryScope);
41
+ export declare function compareIgnorePolicy(local: DirectoryScope["ignorePolicy"], remote: SnapshotSelection | undefined): IgnorePolicyComparison | undefined;
42
+ export declare function formatIgnorePolicyComparison(comparison: IgnorePolicyComparison): "Remote ignore-file policy differs. Edit local rules to match, or review publishing this device's policy." | "Remote ignore-file policy matches this device." | "Remote uses a legacy content policy. Review publishing this device's ignore-file policy." | "Remote uses an ignore-file policy. Configure matching local rules before transferring.";
35
43
  export declare function syncDirectoryPolicyKey(config: SyncSelectionConfig): string | undefined;
44
+ export declare function localIgnorePolicyKey(config: SyncSelectionConfig & {
45
+ setupName?: string;
46
+ ignoreSourceIdentity?: string;
47
+ recoverySetupKey?: string;
48
+ }): string | undefined;
36
49
  export declare function inspectRemoteSelection(localInclude: unknown, snapshot: Pick<Snapshot, "selection" | "files">, localExclude?: unknown, directory?: DirectoryScope): RemoteSelectionState;
37
50
  export interface RemoteSelectionDecision {
38
51
  setupName: string;
@@ -41,21 +54,24 @@ export interface RemoteSelectionDecision {
41
54
  remoteInclude: readonly string[];
42
55
  localExclude?: readonly string[];
43
56
  remoteExclude?: readonly string[];
44
- localDirectory?: DirectoryScope;
45
- remoteDirectory?: DirectoryScope;
57
+ localDirectory?: PortableDirectoryScope;
58
+ remoteDirectory?: PortableDirectoryScope;
59
+ ignorePolicyComparison?: IgnorePolicyComparison;
46
60
  }
47
61
  export declare class RemoteSelectionMismatchError extends Error {
48
62
  readonly decision: RemoteSelectionDecision;
49
63
  readonly setupName: string;
50
64
  readonly localInclude: string[];
51
65
  readonly remoteInclude: string[];
52
- constructor(setupName: string, localInclude: unknown, remoteInclude: unknown, configIdentity?: string, localExclude?: string[], remoteExclude?: string[], localDirectory?: DirectoryScope, remoteDirectory?: DirectoryScope);
66
+ constructor(setupName: string, localInclude: unknown, remoteInclude: unknown, configIdentity?: string, localExclude?: string[], remoteExclude?: string[], localDirectory?: DirectoryScope, remoteDirectory?: PortableDirectoryScope, ignorePolicyComparison?: IgnorePolicyComparison);
53
67
  }
54
68
  export declare function remoteSelectionMismatch(config: {
55
69
  setupName: string;
56
70
  include: unknown;
57
71
  exclude?: string[];
58
- } & DirectoryScope, remoteInclude: unknown, configIdentity?: string, remoteExclude?: string[], remoteDirectory?: DirectoryScope): RemoteSelectionMismatchError;
72
+ } & DirectoryScope, remoteInclude: unknown, configIdentity?: string, remoteExclude?: string[], remoteDirectory?: PortableDirectoryScope & {
73
+ ignorePolicyComparison?: IgnorePolicyComparison;
74
+ }): RemoteSelectionMismatchError;
59
75
  export declare function formatRemoteSelectionMismatch(setupName: string, localInclude: readonly string[], remoteInclude: readonly string[], localExclude?: readonly string[], remoteExclude?: readonly string[], localDirectory?: DirectoryScope, remoteDirectory?: DirectoryScope): string;
60
76
  export declare function discoverLegacySnapshotInclude(snapshot: Pick<Snapshot, "files">): string[];
61
77
  export declare function syncIncludeSelection(value: unknown): {
@@ -66,6 +82,9 @@ export declare function syncIncludeSelection(value: unknown): {
66
82
  };
67
83
  export declare function customIncludePathsByLower(value: unknown): Map<string, string>;
68
84
  export interface SyncSelectionConfig extends DirectoryScope {
85
+ version?: number;
86
+ fingerprint?: string;
87
+ sessions?: boolean;
69
88
  include?: unknown;
70
89
  exclude?: unknown;
71
90
  syncFiles?: unknown;
@@ -74,10 +93,11 @@ export interface SyncSelectionConfig extends DirectoryScope {
74
93
  }
75
94
  export declare function includeFromSelectionConfig(config: SyncSelectionConfig): string[];
76
95
  export declare function syncSelectionHasContent(config: SyncSelectionConfig): boolean;
96
+ export declare function isIgnoreControlPath(relativePath: string, reservedNames?: ReadonlySet<string>): boolean;
77
97
  export declare const MAX_AGENT_DIRECTORY_ENTRIES = 65536;
78
98
  export declare const MAX_AGENT_DIRECTORY_FILES = 16384;
79
99
  export declare function assertAgentDirectoryPathLayout(files: Iterable<string>): void;
80
- export declare function compileSyncPolicyExclude(config: SyncSelectionConfig): (relativePath: string) => boolean;
100
+ export declare function compileSyncPolicyExclude(config: SyncSelectionConfig): (relativePath: string, directory?: boolean) => boolean;
81
101
  export declare function compileSyncPolicyTraversal(config: SyncSelectionConfig): (relativePath: string) => boolean;
82
102
  export declare function syncSessionsSelected(config: SyncSelectionConfig): boolean;
83
103
  export declare function isConfiguredSnapshotPath(relativePath: string, config: SyncSelectionConfig, _legacyExtraFiles?: Set<string>): boolean;
@@ -93,3 +113,4 @@ export declare function normalizeExtraFiles(value: unknown): string[];
93
113
  export declare const extraFilePathsByLower: typeof customIncludePathsByLower;
94
114
  export declare const isSafeExtraFileName: typeof isSafeCustomIncludePath;
95
115
  export declare const selectedSyncFileSet: (value: unknown) => Set<"AGENTS.md" | "APPEND_SYSTEM.md" | "extensions" | "keybindings.json" | "models.json" | "prompts" | "settings.json" | "skills" | "themes">;
116
+ export {};