@narumitw/pi-sync-daemon 0.8.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 (54) hide show
  1. package/CHANGELOG.md +10 -0
  2. package/dist/cli.js +1 -1
  3. package/dist/consent.d.ts +14 -2
  4. package/dist/consent.js +134 -16
  5. package/dist/engine/backends/git/git-backend.d.ts +1 -2
  6. package/dist/engine/backends/git/git-backend.js +61 -30
  7. package/dist/engine/commands/command-types.d.ts +2 -1
  8. package/dist/engine/host.d.ts +1 -0
  9. package/dist/engine/ignore/ignore-initialization.d.ts +3 -0
  10. package/dist/engine/ignore/ignore-initialization.js +93 -27
  11. package/dist/engine/ignore/ignore-settings.d.ts +16 -1
  12. package/dist/engine/ignore/ignore-settings.js +85 -14
  13. package/dist/engine/settings/config-file.js +1 -1
  14. package/dist/engine/settings/config.d.ts +3 -2
  15. package/dist/engine/settings/config.js +71 -28
  16. package/dist/engine/settings/settings-management.d.ts +3 -1
  17. package/dist/engine/settings/settings-management.js +8 -2
  18. package/dist/engine/settings/settings-types.d.ts +2 -0
  19. package/dist/engine/snapshot/session-paths.js +7 -2
  20. package/dist/engine/snapshot/snapshot-apply.d.ts +1 -1
  21. package/dist/engine/snapshot/snapshot-transaction-policy.d.ts +7 -2
  22. package/dist/engine/snapshot/snapshot-transaction-policy.js +37 -17
  23. package/dist/engine/snapshot/snapshot-transaction.js +55 -13
  24. package/dist/engine/snapshot/snapshot-types.d.ts +4 -0
  25. package/dist/engine/sync/agent-plan.js +1 -0
  26. package/dist/engine/sync/agent-sync.js +8 -1
  27. package/dist/engine/sync/continuous-sync.d.ts +3 -1
  28. package/dist/engine/sync/continuous-sync.js +32 -15
  29. package/dist/engine/sync/merge-acceptance.d.ts +8 -0
  30. package/dist/engine/sync/merge-acceptance.js +29 -0
  31. package/dist/engine/sync/merge-apply.js +7 -4
  32. package/dist/engine/sync/merge-journal.d.ts +6 -0
  33. package/dist/engine/sync/merge-journal.js +33 -14
  34. package/dist/engine/sync/merged-sync.js +31 -39
  35. package/dist/engine/sync/remote-snapshot.d.ts +2 -1
  36. package/dist/engine/sync/remote-snapshot.js +17 -2
  37. package/dist/engine/sync/session-push.js +20 -6
  38. package/dist/engine/sync/sync-mutations.js +71 -50
  39. package/dist/engine/sync/sync-policy.d.ts +5 -0
  40. package/dist/engine/sync/sync-policy.js +28 -3
  41. package/dist/engine/sync/sync-state.d.ts +2 -0
  42. package/dist/engine/sync/sync-state.js +3 -8
  43. package/dist/engine/sync/transfer-freshness.d.ts +31 -0
  44. package/dist/engine/sync/transfer-freshness.js +82 -0
  45. package/dist/engine-service.d.ts +1 -1
  46. package/dist/engine-service.js +124 -27
  47. package/dist/monitor.d.ts +4 -1
  48. package/dist/monitor.js +84 -32
  49. package/dist/server.d.ts +1 -0
  50. package/dist/server.js +46 -5
  51. package/dist/service-host.d.ts +1 -1
  52. package/dist/service-host.js +2 -1
  53. package/docs/architecture.md +13 -5
  54. package/package.json +1 -1
@@ -4,7 +4,7 @@ import { DEFAULT_IGNORE_FILENAME, validateIgnoreFilename } from "../ignore/ignor
4
4
  import { assertWithinRoot, isDeniedPath, isPathInside } from "../paths.js";
5
5
  import { normalizeSyncExclude, sameSyncExclude } from "../sync/exclude-policy.js";
6
6
  import { mergePathIdentity } from "../sync/file-merge-planner.js";
7
- import { portableSnapshotSelection, sameSnapshotSelection, selectionForSnapshot, syncDirectoryPolicyKey, } from "../sync/sync-policy.js";
7
+ import { localIgnorePolicyKey, portableSnapshotSelection, sameSnapshotSelection, selectionForSnapshot, syncDirectoryPolicyKey, } from "../sync/sync-policy.js";
8
8
  import { agentDir } from "./session-paths.js";
9
9
  import { isCaseReplacement } from "./snapshot-case-replacement.js";
10
10
  import { sessionStorageRoot } from "./snapshot-paths.js";
@@ -13,16 +13,25 @@ export const LEGACY_AGENT_DIRECTORY_JOURNAL_VERSION = 8;
13
13
  export const FIXED_WORKSPACE_JOURNAL_VERSION = 9;
14
14
  export const AGENT_DIRECTORY_JOURNAL_VERSION = 10;
15
15
  export const IGNORE_POLICY_JOURNAL_VERSION = 11;
16
+ export const BOUND_DIRECTORY_JOURNAL_VERSION = 12;
17
+ export const BOUND_INCLUDED_PATHS_JOURNAL_VERSION = 13;
18
+ function isLocallyBoundJournal(journal) {
19
+ return (journal.version === BOUND_DIRECTORY_JOURNAL_VERSION || journal.version === BOUND_INCLUDED_PATHS_JOURNAL_VERSION);
20
+ }
21
+ export function recoveryPolicyKey(options) {
22
+ return options.setupName || options.reservedIgnoreNames !== undefined ? localIgnorePolicyKey(options) : undefined;
23
+ }
16
24
  export function isScopedJournal(journal) {
17
25
  return [
18
26
  LEGACY_AGENT_DIRECTORY_JOURNAL_VERSION,
19
27
  FIXED_WORKSPACE_JOURNAL_VERSION,
20
28
  AGENT_DIRECTORY_JOURNAL_VERSION,
21
29
  IGNORE_POLICY_JOURNAL_VERSION,
30
+ BOUND_DIRECTORY_JOURNAL_VERSION,
22
31
  ].includes(journal.version);
23
32
  }
24
33
  function usesSlottedWorkspace(journal) {
25
- return journal.version === AGENT_DIRECTORY_JOURNAL_VERSION || journal.version === IGNORE_POLICY_JOURNAL_VERSION;
34
+ return journal.version >= AGENT_DIRECTORY_JOURNAL_VERSION && isScopedJournal(journal);
26
35
  }
27
36
  export function isRecoveryStageId(value) {
28
37
  return (typeof value === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u.test(value));
@@ -55,10 +64,12 @@ function sameIgnoreSource(left, right) {
55
64
  export class StaleIgnorePolicyError extends Error {
56
65
  }
57
66
  export function ignorePolicyValidator(options) {
58
- if (!options.ignorePolicy && options.version !== 4)
67
+ const scopedIgnore = options.ignorePolicy !== undefined || options.version === 4;
68
+ if (!scopedIgnore && options.reservedIgnoreNames === undefined && !options.validateIgnorePolicy)
59
69
  return;
60
70
  const validateIgnorePolicy = options.validateIgnorePolicy;
61
- if (!options.ignorePolicy || options.scope !== "agent-directory" || typeof validateIgnorePolicy !== "function")
71
+ if ((scopedIgnore && (!options.ignorePolicy || options.scope !== "agent-directory")) ||
72
+ typeof validateIgnorePolicy !== "function")
62
73
  throw new Error("Ignore-file mutation requires an explicit local policy and a freshness check.");
63
74
  return async () => {
64
75
  options.validateMutation?.();
@@ -77,9 +88,15 @@ export function ignorePolicyValidator(options) {
77
88
  };
78
89
  }
79
90
  export function validateJournalPolicy(journal) {
80
- if (!journal || (![1, 2, 3, 4, 5, 6, 7].includes(journal.version) && !isScopedJournal(journal)))
91
+ if (!journal ||
92
+ (![1, 2, 3, 4, 5, 6, 7].includes(journal.version) && !isScopedJournal(journal) && !isLocallyBoundJournal(journal)))
81
93
  throw new Error("Unsupported pi-sync transaction journal; preserve evidence for review.");
82
- if (journal.version === IGNORE_POLICY_JOURNAL_VERSION) {
94
+ if (isLocallyBoundJournal(journal)
95
+ ? typeof journal.localPolicyKey !== "string" || !/^[0-9a-f]{64}$/u.test(journal.localPolicyKey)
96
+ : journal.localPolicyKey !== undefined)
97
+ throw new Error("Invalid transaction local policy binding; preserve evidence for review.");
98
+ if (journal.version === IGNORE_POLICY_JOURNAL_VERSION ||
99
+ (journal.version === BOUND_DIRECTORY_JOURNAL_VERSION && journal.selection?.version === 4)) {
83
100
  const binding = journal.ignoreSource;
84
101
  try {
85
102
  if (journal.exclude === undefined &&
@@ -109,9 +126,11 @@ export function validateJournalPolicy(journal) {
109
126
  normalizeSyncExclude(journal.exclude);
110
127
  }
111
128
  export function assertRecoveryPolicy(journal, options) {
112
- if (journal.version === IGNORE_POLICY_JOURNAL_VERSION || options.ignorePolicy || options.version === 4) {
113
- if (journal.version === IGNORE_POLICY_JOURNAL_VERSION &&
114
- journal.ignoreSource &&
129
+ const localKey = recoveryPolicyKey(options);
130
+ if (journal.localPolicyKey !== localKey)
131
+ throw new Error("Pending transaction has different setup or ignore policy evidence; preserve its backup for reviewed recovery.");
132
+ if (journal.ignoreSource || options.ignorePolicy || options.version === 4) {
133
+ if (journal.ignoreSource &&
115
134
  options.scope === "agent-directory" &&
116
135
  options.ignorePolicy &&
117
136
  sameIgnoreSource(journal.ignoreSource, ignoreSourceBinding(options.ignorePolicy)) &&
@@ -130,16 +149,18 @@ export function assertRecoveryPolicy(journal, options) {
130
149
  export function validateJournal(directory, journal, sessionDir) {
131
150
  validateJournalPolicy(journal);
132
151
  const wholeDirectory = isScopedJournal(journal);
152
+ const scopedWorkspace = wholeDirectory && journal.version >= FIXED_WORKSPACE_JOURNAL_VERSION;
133
153
  if (!Array.isArray(journal.entries) || journal.entries.length > 16_384)
134
154
  throw new Error("Unsupported pi-sync transaction journal; preserve evidence for review.");
135
155
  if (journal.completed !== undefined &&
136
- ((!wholeDirectory && ![6, 7].includes(journal.version)) || journal.completed !== true))
156
+ ((!wholeDirectory && ![6, 7, BOUND_INCLUDED_PATHS_JOURNAL_VERSION].includes(journal.version)) ||
157
+ journal.completed !== true))
137
158
  throw new Error("Invalid transaction completion evidence.");
138
159
  const root = path.resolve(agentDir());
139
160
  if (typeof journal.root !== "string" || path.resolve(journal.root) !== root)
140
161
  throw new Error("Transaction root no longer matches the Pi agent directory.");
141
162
  if (journal.sessionRootTransition !== undefined) {
142
- if (journal.version !== 7 || typeof journal.sessionRoot !== "string")
163
+ if (![7, BOUND_INCLUDED_PATHS_JOURNAL_VERSION].includes(journal.version) || typeof journal.sessionRoot !== "string")
143
164
  throw new Error("Invalid session root-transition version.");
144
165
  validateSessionRootTransition(journal.sessionRootTransition);
145
166
  }
@@ -170,7 +191,7 @@ export function validateJournal(directory, journal, sessionDir) {
170
191
  assertWithinRoot(directory, path.join(directory, "before", entry.backupName));
171
192
  assertAllowedTarget(root, journal.sessionRoot, entry.target);
172
193
  if (entry.afterTarget !== undefined &&
173
- ((!wholeDirectory && ![5, 6, 7].includes(journal.version)) ||
194
+ ((!wholeDirectory && ![5, 6, 7, BOUND_INCLUDED_PATHS_JOURNAL_VERSION].includes(journal.version)) ||
174
195
  typeof entry.afterTarget !== "string" ||
175
196
  !isCaseReplacement(root, entry.target, entry.afterTarget) ||
176
197
  path.resolve(entry.afterTarget) !== entry.afterTarget ||
@@ -183,8 +204,7 @@ export function validateJournal(directory, journal, sessionDir) {
183
204
  (entry.afterImage === undefined ? !journal.completed : typeof entry.afterImage !== "string") ||
184
205
  (entry.postFiles === undefined ? !journal.completed : !Array.isArray(entry.postFiles))))
185
206
  throw new Error("Invalid transaction postimage evidence.");
186
- if (entry.recoveryStaged !== undefined &&
187
- (typeof entry.recoveryStaged !== "boolean" || journal.version >= FIXED_WORKSPACE_JOURNAL_VERSION))
207
+ if (entry.recoveryStaged !== undefined && (typeof entry.recoveryStaged !== "boolean" || scopedWorkspace))
188
208
  throw new Error("Invalid recovery staging evidence.");
189
209
  if (entry.removalPending !== undefined && (journal.version < 3 || typeof entry.removalPending !== "boolean"))
190
210
  throw new Error("Invalid transaction removal evidence.");
@@ -194,7 +214,7 @@ export function validateJournal(directory, journal, sessionDir) {
194
214
  if (entry.removalPending && entry.replacementStarted)
195
215
  throw new Error("Conflicting transaction replacement evidence.");
196
216
  if ((entry.recoveryWorkspace !== undefined &&
197
- (journal.version < FIXED_WORKSPACE_JOURNAL_VERSION ||
217
+ (!scopedWorkspace ||
198
218
  !isScopedIdentity(entry.recoveryWorkspace) ||
199
219
  entry.recoveryStaged ||
200
220
  !["file", "directory"].includes(entry.kind))) ||
@@ -203,7 +223,7 @@ export function validateJournal(directory, journal, sessionDir) {
203
223
  !entry.recoveryWorkspace ||
204
224
  !isRecoveryStageId(entry.recoveryWorkspaceId))) ||
205
225
  (entry.scopedRemoval !== undefined &&
206
- (journal.version < FIXED_WORKSPACE_JOURNAL_VERSION ||
226
+ (!scopedWorkspace ||
207
227
  !entry.removalPending ||
208
228
  !["before", "after"].includes(entry.scopedRemoval?.image) ||
209
229
  !isScopedIdentity(entry.scopedRemoval?.identity) ||
@@ -211,7 +231,7 @@ export function validateJournal(directory, journal, sessionDir) {
211
231
  ? !["file", "directory"].includes(entry.kind)
212
232
  : entry.afterImage === "missing" && !entry.postFiles?.length))) ||
213
233
  (entry.vacantInstall !== undefined &&
214
- (journal.version < FIXED_WORKSPACE_JOURNAL_VERSION ||
234
+ (!scopedWorkspace ||
215
235
  !entry.recoveryWorkspace ||
216
236
  !isScopedIdentity(entry.vacantInstall) ||
217
237
  entry.removalPending ||
@@ -19,7 +19,7 @@ import { prepareSessionRootTransition, resolveTransitionSessionRoot, stableAgent
19
19
  import { pendingTransactionEntries, transactionRoot } from "./snapshot-transaction-directory.js";
20
20
  import { legacyImage, MAX_TRANSACTION_JOURNAL_BYTES, ownedScopedPostTree, readTransactionJournal, recheckScopedImage, removeScopedImage, scopedDescendant, scopedIdentity, scopedPathIdentity, scopedTransactionImage, stableScopedIdentity, } from "./snapshot-transaction-images.js";
21
21
  import { indexTransactionPlan } from "./snapshot-transaction-plan.js";
22
- import { AGENT_DIRECTORY_JOURNAL_VERSION, assertAllowedTarget, assertRecoveryPolicy, assertSafeParents, IGNORE_POLICY_JOURNAL_VERSION, ignorePolicyValidator, ignoreSourceBinding, isScopedJournal, isStrictlyInside, StaleIgnorePolicyError, touchesProtectedTarget, transactionHasSessionTargets, validateJournal, validateJournalPolicy, } from "./snapshot-transaction-policy.js";
22
+ import { AGENT_DIRECTORY_JOURNAL_VERSION, assertAllowedTarget, assertRecoveryPolicy, assertSafeParents, BOUND_DIRECTORY_JOURNAL_VERSION, BOUND_INCLUDED_PATHS_JOURNAL_VERSION, IGNORE_POLICY_JOURNAL_VERSION, ignorePolicyValidator, ignoreSourceBinding, isScopedJournal, isStrictlyInside, recoveryPolicyKey, StaleIgnorePolicyError, touchesProtectedTarget, transactionHasSessionTargets, validateJournal, validateJournalPolicy, } from "./snapshot-transaction-policy.js";
23
23
  import { assertNoUnclaimedLegacyStage, buildScopedRecoveryStage, cleanScopedLegacyStage, cleanScopedWorkspace, inspectScopedRecoveryStage, prepareLegacyRecoveryStage, recoveryStagePath, } from "./snapshot-transaction-stage.js";
24
24
  import { verifyTarget } from "./snapshot-transaction-verification.js";
25
25
  const JOURNAL_VERSION = 4;
@@ -109,6 +109,8 @@ export async function applySnapshotTransaction(plan, options = {}) {
109
109
  // A released additional key cannot authorize rollback, even for recognized raced bytes.
110
110
  const changesQueueKey = transaction.journal.entries.some((entry) => !heldKeys.has(entry.target) || (entry.afterTarget && !heldKeys.has(entry.afterTarget)));
111
111
  try {
112
+ if (options.validateApplyReview)
113
+ await options.validateApplyReview();
112
114
  if (scoped && transaction.deletes.length)
113
115
  await recheckAgentDirectoryBudget(root, plan, options, stateDir(root));
114
116
  for (const target of transaction.deletes.sort((a, b) => a.length - b.length)) {
@@ -122,6 +124,8 @@ export async function applySnapshotTransaction(plan, options = {}) {
122
124
  await withMissingTargetQueues(transaction.journal.entries
123
125
  .filter((entry) => entry.removalPending)
124
126
  .flatMap((entry) => [entry.target, ...(entry.afterTarget ? [entry.afterTarget] : [])]), heldKeys, options, async () => {
127
+ if (options.validateApplyReview && transaction.journal.entries.some((entry) => entry.removalPending))
128
+ await options.validateApplyReview();
125
129
  if (validateIgnorePolicy)
126
130
  await validateIgnorePolicy();
127
131
  if (scoped && plan.writes.length)
@@ -170,10 +174,17 @@ export async function applySnapshotTransaction(plan, options = {}) {
170
174
  const verified = await verifyTarget(transaction.directory, entry, transaction.journal, options, deletedByThisCall);
171
175
  options.signal?.throwIfAborted();
172
176
  options.validateMutation?.();
173
- if (validateIgnorePolicy && verified.scoped) {
177
+ if (validateIgnorePolicy) {
174
178
  await validateIgnorePolicy();
175
- await recheckScopedImage(item.target, verified.scoped, options);
179
+ if (verified.scoped)
180
+ await recheckScopedImage(item.target, verified.scoped, options);
181
+ else {
182
+ await assertUnexcludedTargets(root, [item.target], options);
183
+ await verifyTarget(transaction.directory, entry, transaction.journal, options, deletedByThisCall);
184
+ }
176
185
  }
186
+ options.validateMutation?.();
187
+ options.signal?.throwIfAborted();
177
188
  await fs.rename(temp, item.target);
178
189
  await syncDirectory(path.dirname(item.target));
179
190
  }
@@ -278,6 +289,7 @@ async function prepareTransaction(plan, targets, options, replacements = new Map
278
289
  const root = path.resolve(agentDir());
279
290
  const wholeDirectory = options.scope === "agent-directory";
280
291
  const ignoreSource = options.ignorePolicy ? ignoreSourceBinding(options.ignorePolicy) : undefined;
292
+ const localPolicyKey = recoveryPolicyKey(options);
281
293
  const sessionRoot = sessionDir || wholeDirectory ? path.resolve(sessionStorageRoot(root, sessionDir)) : undefined;
282
294
  const indexed = indexTransactionPlan(plan, targets);
283
295
  const directory = path.join(transactionRoot(), randomUUID());
@@ -327,17 +339,22 @@ async function prepareTransaction(plan, targets, options, replacements = new Map
327
339
  ? undefined
328
340
  : await prepareSessionRootTransition(directory, root, effectiveRoot, entries, plan, options);
329
341
  const journal = {
330
- version: ignoreSource
331
- ? IGNORE_POLICY_JOURNAL_VERSION
332
- : wholeDirectory
333
- ? AGENT_DIRECTORY_JOURNAL_VERSION
334
- : sessionRootTransition
335
- ? 7
336
- : replacements.size
337
- ? 5
338
- : JOURNAL_VERSION,
342
+ version: localPolicyKey
343
+ ? wholeDirectory
344
+ ? BOUND_DIRECTORY_JOURNAL_VERSION
345
+ : BOUND_INCLUDED_PATHS_JOURNAL_VERSION
346
+ : ignoreSource
347
+ ? IGNORE_POLICY_JOURNAL_VERSION
348
+ : wholeDirectory
349
+ ? AGENT_DIRECTORY_JOURNAL_VERSION
350
+ : sessionRootTransition
351
+ ? 7
352
+ : replacements.size
353
+ ? 5
354
+ : JOURNAL_VERSION,
339
355
  root,
340
356
  ignoreSource,
357
+ localPolicyKey,
341
358
  ...(wholeDirectory
342
359
  ? { selection: selectionForSnapshot(includeFromSelectionConfig(options), options.exclude, options) }
343
360
  : options.exclude === undefined
@@ -492,6 +509,8 @@ async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
492
509
  const temporary = await prepareLegacyRecoveryStage(directory, entry, options, () => persistJournal(directory, journal));
493
510
  if (entry.kind === "file") {
494
511
  try {
512
+ options.validateMutation?.();
513
+ options.signal?.throwIfAborted();
495
514
  await fs.mkdir(path.dirname(entry.target), { recursive: true });
496
515
  await fs.copyFile(path.join(directory, "before", entry.backupName), temporary);
497
516
  // Windows requires write access to flush an existing regular file.
@@ -532,6 +551,13 @@ async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
532
551
  options.signal?.throwIfAborted();
533
552
  if (atInstall === before && (await spellingMatches()))
534
553
  return;
554
+ if (validateIgnorePolicy) {
555
+ await validateIgnorePolicy();
556
+ await assertUnexcludedTargets(journal.root, [entry.target], options);
557
+ await verifyTarget(directory, entry, journal, options, atRename === "missing");
558
+ }
559
+ options.validateMutation?.();
560
+ options.signal?.throwIfAborted();
535
561
  await fs.rename(temporary, entry.target);
536
562
  await syncDirectory(path.dirname(entry.target));
537
563
  });
@@ -542,6 +568,8 @@ async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
542
568
  continue;
543
569
  }
544
570
  try {
571
+ options.validateMutation?.();
572
+ options.signal?.throwIfAborted();
545
573
  await fs.mkdir(path.dirname(entry.target), { recursive: true });
546
574
  await assertSafeParents(journal.root, journal.sessionRoot, entry.target);
547
575
  if (entry.kind === "directory") {
@@ -577,6 +605,13 @@ async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
577
605
  options.signal?.throwIfAborted();
578
606
  if (atInstall === before)
579
607
  return;
608
+ if (validateIgnorePolicy) {
609
+ await validateIgnorePolicy();
610
+ await assertUnexcludedTargets(journal.root, [entry.target], options);
611
+ await verifyTarget(directory, entry, journal, options, atRename === "missing");
612
+ }
613
+ options.validateMutation?.();
614
+ options.signal?.throwIfAborted();
580
615
  await fs.rename(temporary, entry.target);
581
616
  await syncDirectory(path.dirname(entry.target));
582
617
  });
@@ -743,6 +778,13 @@ async function removeOwnedTarget(directory, entry, journal, options, { apply, re
743
778
  await removeScopedImage(entry.target, current.scoped, options, validateIgnorePolicy);
744
779
  }
745
780
  else {
781
+ if (validateIgnorePolicy) {
782
+ await validateIgnorePolicy();
783
+ await assertUnexcludedTargets(journal.root, [entry.target], options);
784
+ await verifyTarget(directory, entry, journal, options);
785
+ }
786
+ options.validateMutation?.();
787
+ options.signal?.throwIfAborted();
746
788
  await fs.rm(entry.target, { recursive: true, force: true });
747
789
  }
748
790
  await syncDirectory(path.dirname(entry.target));
@@ -797,7 +839,7 @@ async function completeTransaction(directory, journal) {
797
839
  // may only retry cleanup, never roll back already accepted files.
798
840
  await writeJson(path.join(directory, "journal.json"), {
799
841
  ...journal,
800
- version: isScopedJournal(journal) ? journal.version : journal.sessionRootTransition ? 7 : 6,
842
+ version: isScopedJournal(journal) || journal.localPolicyKey ? journal.version : journal.sessionRootTransition ? 7 : 6,
801
843
  completed: true,
802
844
  }, {
803
845
  maxBytes: MAX_TRANSACTION_JOURNAL_BYTES,
@@ -70,10 +70,14 @@ export interface AgentDirectoryInventory {
70
70
  routingDirectories: ReadonlySet<string>;
71
71
  }
72
72
  export interface SnapshotOptions extends DirectoryScope {
73
+ setupName?: string;
74
+ recoverySetupKey?: string;
75
+ ignoreSourceIdentity?: string;
73
76
  signal?: AbortSignal;
74
77
  /** Caller-owned session/generation guard, rechecked at file-mutation boundaries. */
75
78
  validateMutation?: () => void;
76
79
  validateIgnorePolicy?: () => Promise<void>;
80
+ validateApplyReview?: () => Promise<void>;
77
81
  /** Reviewed regular-file preimages; null means the path was absent. Checked under mutation queues. */
78
82
  expectedFileHashes?: Readonly<Record<string, string | null>>;
79
83
  include?: string[];
@@ -45,6 +45,7 @@ export async function resolveAgentPlan(ctx, options, config, backend, state, loc
45
45
  1,
46
46
  backend.identity,
47
47
  syncConfigReviewIdentity(config),
48
+ ...(config.configDocumentFingerprint ? [config.configDocumentFingerprint] : []),
48
49
  syncStateFingerprint(state),
49
50
  head.revision,
50
51
  fileHashMap(localRaw),
@@ -66,8 +66,9 @@ export async function withAgentSyncLock(ctx, options, run) {
66
66
  if (!(await confirmAgentRefusalRetry(ctx, options.setup, request.evidence, validate, options.signal)))
67
67
  return "cancelled";
68
68
  }
69
+ const reserve = background?.reserve;
69
70
  const raw = cached === undefined || retry
70
- ? await runAgentResolver(ctx, request.evidence, validate, options.signal, background ? (signal) => background.reserve(request.key, signal) : undefined)
71
+ ? await runAgentResolver(ctx, request.evidence, validate, options.signal, reserve ? (signal) => reserve(request.key, signal) : undefined)
71
72
  : JSON.stringify(cached);
72
73
  let candidate;
73
74
  try {
@@ -84,6 +85,12 @@ export async function withAgentSyncLock(ctx, options, run) {
84
85
  await withLock("agent-cache-save", async () => {
85
86
  await assertOwner();
86
87
  options.signal?.throwIfAborted();
88
+ if (background) {
89
+ background.validate();
90
+ await request.validate(options.signal);
91
+ options.signal?.throwIfAborted();
92
+ background.validate();
93
+ }
87
94
  await saveAgentCandidate(request.key, candidate);
88
95
  });
89
96
  let retryCacheCommitted = false;
@@ -8,8 +8,10 @@ export interface ContinuousClock {
8
8
  random(): number;
9
9
  schedule(ms: number, run: () => void, kind?: "wait" | "authorization"): () => void;
10
10
  }
11
+ type ContinuousTransfer = <T>(run: (committed: () => void) => Promise<T>) => Promise<T>;
11
12
  /** Created on first enabled session. No module/factory-owned timers or watchers. */
12
13
  export declare function createContinuousSync(loaders: SyncLoaders, clock?: ContinuousClock, publish?: StartupTimingPublisher): {
13
- start(ctx: ExtensionContext, sessionSignal: AbortSignal, explicitRetry?: boolean | string, debug?: boolean): void;
14
+ start(ctx: ExtensionContext, sessionSignal: AbortSignal, explicitRetry?: boolean | string, debug?: boolean, transfer?: ContinuousTransfer): void;
14
15
  stop(owner?: ExtensionContext["sessionManager"]): Promise<void>;
15
16
  };
17
+ export {};
@@ -37,7 +37,7 @@ export function createContinuousSync(loaders, clock = systemClock, publish) {
37
37
  let task;
38
38
  return {
39
39
  // A setup name binds retry to the configuration loaded after asynchronous eligibility checks.
40
- start(ctx, sessionSignal, explicitRetry = false, debug = false) {
40
+ start(ctx, sessionSignal, explicitRetry = false, debug = false, transfer) {
41
41
  if ((!ctx.backgroundAuthorized?.() && (!ctx.hasUI || (ctx.mode !== "tui" && ctx.mode !== "rpc"))) ||
42
42
  sessionSignal.aborted ||
43
43
  task)
@@ -68,7 +68,7 @@ export function createContinuousSync(loaders, clock = systemClock, publish) {
68
68
  let explicit = explicitRetry;
69
69
  while (!signal.aborted) {
70
70
  try {
71
- await run(ctx, signal, explicit, startup);
71
+ await run(ctx, signal, explicit, startup, transfer);
72
72
  return;
73
73
  }
74
74
  catch {
@@ -112,12 +112,12 @@ export function createContinuousSync(loaders, clock = systemClock, publish) {
112
112
  await current.promise;
113
113
  },
114
114
  };
115
- async function run(ctx, signal, explicitRetry, startup) {
115
+ async function run(ctx, signal, explicitRetry, startup, transfer) {
116
116
  const validateOwner = captureMutationOwner(ctx, signal);
117
117
  try {
118
118
  while (!signal.aborted) {
119
119
  validateOwner();
120
- const config = await loadConfigForCheck();
120
+ const config = await loadConfigForCheck(undefined, signal);
121
121
  validateOwner();
122
122
  if (!continuousEnabled(config) || (ctx.backgroundAuthorized && !ctx.backgroundAuthorized(config)))
123
123
  return;
@@ -135,7 +135,7 @@ export function createContinuousSync(loaders, clock = systemClock, publish) {
135
135
  });
136
136
  if (lease) {
137
137
  const retry = typeof explicitRetry === "string" ? explicitRetry === config.setupName : explicitRetry;
138
- await monitor(ctx, config, binding, lease, signal, retry, startup);
138
+ await monitor(ctx, config, binding, lease, signal, retry, startup, transfer);
139
139
  explicitRetry = false;
140
140
  }
141
141
  else
@@ -158,7 +158,7 @@ export function createContinuousSync(loaders, clock = systemClock, publish) {
158
158
  });
159
159
  }
160
160
  validateOwner();
161
- const current = await loadConfigForCheck();
161
+ const current = await loadConfigForCheck(undefined, signal);
162
162
  if (!continuousEnabled(current) || (ctx.backgroundAuthorized && !ctx.backgroundAuthorized(current)))
163
163
  return;
164
164
  validateOwner();
@@ -178,7 +178,7 @@ export function createContinuousSync(loaders, clock = systemClock, publish) {
178
178
  }
179
179
  }
180
180
  }
181
- async function monitor(ctx, initial, binding, lease, parent, explicitRetry, startup) {
181
+ async function monitor(ctx, initial, binding, lease, parent, explicitRetry, startup, transfer) {
182
182
  const signal = AbortSignal.any([parent, lease.signal]);
183
183
  const validateOwner = captureMutationOwner(ctx, signal);
184
184
  let config = initial;
@@ -220,7 +220,7 @@ export function createContinuousSync(loaders, clock = systemClock, publish) {
220
220
  validate();
221
221
  while (!signal.aborted && ctx.isIdle()) {
222
222
  validate();
223
- const latest = await loadConfigForCheck();
223
+ const latest = await loadConfigForCheck(undefined, signal);
224
224
  validate();
225
225
  if (!continuousEnabled(latest) ||
226
226
  (ctx.backgroundAuthorized && !ctx.backgroundAuthorized(latest)) ||
@@ -228,6 +228,9 @@ export function createContinuousSync(loaders, clock = systemClock, publish) {
228
228
  return;
229
229
  validate();
230
230
  if (syncCheckConfigFingerprint(latest) !== syncCheckConfigFingerprint(config)) {
231
+ if (config.reservedIgnoreNames !== undefined || latest.reservedIgnoreNames !== undefined)
232
+ return;
233
+ explicitRetry = false;
231
234
  closeWatch();
232
235
  config = latest;
233
236
  closeWatch = await openWatch();
@@ -289,7 +292,7 @@ export function createContinuousSync(loaders, clock = systemClock, publish) {
289
292
  return;
290
293
  try {
291
294
  validate();
292
- const latest = await loadConfigForCheck();
295
+ const latest = await loadConfigForCheck(undefined, guardSignal);
293
296
  if (guardSignal.aborted)
294
297
  return;
295
298
  validateCycle(latest);
@@ -300,7 +303,7 @@ export function createContinuousSync(loaders, clock = systemClock, publish) {
300
303
  }
301
304
  })().catch(() => { });
302
305
  try {
303
- await performCycle(ctx, config, binding, lease, AbortSignal.any([signal, cycle.signal]), validateCycle, configuration, force, timings);
306
+ await performCycle(ctx, config, binding, lease, AbortSignal.any([signal, cycle.signal]), validateCycle, configuration, force, timings, transfer);
304
307
  outcome = "completed";
305
308
  }
306
309
  catch (error) {
@@ -370,11 +373,15 @@ export function createContinuousSync(loaders, clock = systemClock, publish) {
370
373
  cycle?.abort();
371
374
  }
372
375
  }
373
- async function performCycle(ctx, config, binding, lease, signal, validateOwner, configuration, force, timings) {
376
+ async function performCycle(ctx, config, binding, lease, signal, validateOwner, configuration, force, timings, transfer) {
374
377
  const validate = (latest) => {
375
378
  signal.throwIfAborted();
376
379
  validateOwner(latest);
377
380
  };
381
+ const refresh = async () => {
382
+ validate();
383
+ validate(await loadConfigForCheck(undefined, signal));
384
+ };
378
385
  validate();
379
386
  const current = await readContinuousRecord(binding);
380
387
  validate();
@@ -398,8 +405,9 @@ export function createContinuousSync(loaders, clock = systemClock, publish) {
398
405
  const validateIgnore = ignorePolicyValidator({ ...snapshotOptions, validateMutation: validate });
399
406
  if (validateIgnore)
400
407
  await validateIgnore();
408
+ await refresh();
401
409
  const inspection = await inspectionModule.inspectSync(config, snapshotOptions, signal, undefined, timings);
402
- validate();
410
+ await refresh();
403
411
  let localIdentity = inspection.localIdentity;
404
412
  if (!localIdentity) {
405
413
  const snapshotModule = await loaders.snapshot();
@@ -455,7 +463,7 @@ export function createContinuousSync(loaders, clock = systemClock, publish) {
455
463
  const operations = await timings.measure("operations import", () => loaders.operations());
456
464
  validate();
457
465
  setSyncStatus(ctx, "sync syncing", { activity: "working" });
458
- const result = await timings.measure("automatic transfer", () => withStateDirectoryAccess(() => withAgentSyncLock(ctx, {
466
+ const runTransfer = (onCommit) => withStateDirectoryAccess(() => withAgentSyncLock(ctx, {
459
467
  args: [],
460
468
  yes: true,
461
469
  force: false,
@@ -465,11 +473,20 @@ export function createContinuousSync(loaders, clock = systemClock, publish) {
465
473
  auto: true,
466
474
  signal,
467
475
  startupTimings: timings,
476
+ onCommit,
468
477
  background: {
469
478
  validate,
470
- reserve: (key, requestSignal) => reserveContinuousRequest(binding, lease, key, () => clock.now(), requestSignal),
479
+ reserve: async (key, requestSignal) => {
480
+ await refresh();
481
+ await reserveContinuousRequest(binding, lease, key, () => clock.now(), requestSignal);
482
+ await refresh();
483
+ },
471
484
  },
472
- }, (options) => operations.syncBoth(ctx, options))));
485
+ }, async (options) => {
486
+ await refresh();
487
+ return operations.syncBoth(ctx, options);
488
+ }));
489
+ const result = await timings.measure("automatic transfer", () => transfer ? transfer(runTransfer) : runTransfer());
473
490
  validate();
474
491
  transferred = result === "applied";
475
492
  }
@@ -0,0 +1,8 @@
1
+ import type { RemoteHead } from "../backends/sync-backend.js";
2
+ import type { AnySyncConfig } from "../settings/settings-types.js";
3
+ import type { Snapshot } from "../snapshot/snapshot-types.js";
4
+ import type { SyncState } from "../state/state-types.js";
5
+ import { type PartialProgress } from "./partial-progress.js";
6
+ export declare function matchesAcceptedState(state: SyncState, config: AnySyncConfig, head: RemoteHead, snapshot: Snapshot, progress?: PartialProgress): boolean;
7
+ export declare function acceptedState(config: AnySyncConfig, head: RemoteHead, snapshot: Snapshot, progress?: PartialProgress, canonical?: boolean): SyncState;
8
+ export declare function writeAcceptedState(config: AnySyncConfig, head: RemoteHead, snapshot: Snapshot, validate: () => Promise<void>, progress?: PartialProgress): Promise<void>;
@@ -0,0 +1,29 @@
1
+ import { stageMergeBaseline } from "../state/merge-baseline-store.js";
2
+ import { syncStateFingerprint, writeStateForConfig } from "../state/sync-state-store.js";
3
+ import { portableSnapshot } from "./local-fields.js";
4
+ import { progressState } from "./partial-progress.js";
5
+ import { acceptedSelection, fileHashMap } from "./sync-state.js";
6
+ export function matchesAcceptedState(state, config, head, snapshot, progress) {
7
+ return [true, false].some((canonical) => syncStateFingerprint(state) === syncStateFingerprint(acceptedState(config, head, snapshot, progress, canonical)));
8
+ }
9
+ export function acceptedState(config, head, snapshot, progress, canonical = true) {
10
+ if (progress)
11
+ return progressState(config, head, snapshot, progress);
12
+ return {
13
+ version: 1,
14
+ profile: config.snapshotIdentity,
15
+ lastAppliedSnapshot: head.snapshotId,
16
+ lastRemoteRevision: head.revision,
17
+ lastFileHashes: fileHashMap(canonical ? portableSnapshot(snapshot, config.localFields) : snapshot),
18
+ ...acceptedSelection(config),
19
+ ...(config.localFields !== undefined ? { localFields: config.localFields } : {}),
20
+ };
21
+ }
22
+ export async function writeAcceptedState(config, head, snapshot, validate, progress) {
23
+ const accepted = portableSnapshot(snapshot, config.localFields);
24
+ const state = acceptedState(config, head, accepted, progress);
25
+ await stageMergeBaseline(config, accepted, state, progress?.previous);
26
+ await validate();
27
+ await writeStateForConfig(config, state);
28
+ await validate();
29
+ }
@@ -258,7 +258,7 @@ export async function applyMergedSnapshot(before, after, protectedPaths, options
258
258
  if (options.scope === "agent-directory" && options.sessionDir === undefined) {
259
259
  options = {
260
260
  ...options,
261
- sessionDir: sessionStorageRoot(root, await agentDirectoryConfiguredSessionDir(options.signal, root)),
261
+ sessionDir: sessionStorageRoot(root, await agentDirectoryConfiguredSessionDir(options.signal, root, options)),
262
262
  };
263
263
  options.validateMutation?.();
264
264
  options.signal?.throwIfAborted();
@@ -282,8 +282,7 @@ export async function applyMergedSnapshot(before, after, protectedPaths, options
282
282
  const targetSet = new Set(targets);
283
283
  await assertDistinctMergedTargets(root, paths, new Set(changed), options, protectedTarget, new Set(Object.keys(afterHashes)));
284
284
  await assertCanonicalMutationTargets(targets, options);
285
- if (options.scope === "agent-directory")
286
- await assertUnexcludedTargets(root, targets, options);
285
+ await assertUnexcludedTargets(root, targets, options);
287
286
  // Existing case aliases share Pi's non-reentrant realpath queue. Reserve the
288
287
  // missing destination separately only after deleting its reviewed preimage.
289
288
  const targetsByQueue = new Map();
@@ -383,6 +382,8 @@ export async function applyMergedSnapshot(before, after, protectedPaths, options
383
382
  const removedTargets = new Set([...removed].map((item) => snapshotTarget(root, item, options.sessionDir)));
384
383
  await assertCanonicalMergedTargets(root, changed, options);
385
384
  await validate();
385
+ if (options.validateApplyReview)
386
+ await options.validateApplyReview();
386
387
  const requireReviewedHash = (relative, hash) => {
387
388
  if (hash !== beforeHashes[relative] && hash !== afterHashes[relative])
388
389
  throw new Error("Local content changed at the apply boundary; journal retained, newer bytes untouched.");
@@ -392,7 +393,7 @@ export async function applyMergedSnapshot(before, after, protectedPaths, options
392
393
  const relative = relativeByTarget.get(target);
393
394
  if (!relative)
394
395
  throw new Error("Unowned merge target.");
395
- if (options.scope === "agent-directory") {
396
+ if (validateIgnore || options.scope === "agent-directory") {
396
397
  await assertCanonicalMutationTargets([target], options);
397
398
  await assertUnexcludedTargets(root, [target], options);
398
399
  }
@@ -475,6 +476,8 @@ export async function applyMergedSnapshot(before, after, protectedPaths, options
475
476
  // Writers registered after deletion must finish first; never accept their
476
477
  // bytes as our own, even if they match a recognizable pre/postimage.
477
478
  await requireAbsentDestinations();
479
+ if (deferredTargets.length && options.validateApplyReview)
480
+ await options.validateApplyReview();
478
481
  if (validateIgnore)
479
482
  await validateIgnore();
480
483
  await writeTargets();
@@ -8,9 +8,15 @@ import type { PartialProgress } from "./partial-progress.js";
8
8
  type MergeJournalPolicy = {
9
9
  version: 1;
10
10
  ignoreSource?: never;
11
+ localPolicyKey?: never;
11
12
  } | {
12
13
  version: 2;
13
14
  ignoreSource: NonNullable<TransactionJournalPolicy["ignoreSource"]>;
15
+ localPolicyKey?: never;
16
+ } | {
17
+ version: 3;
18
+ ignoreSource?: TransactionJournalPolicy["ignoreSource"];
19
+ localPolicyKey: string;
14
20
  };
15
21
  export type MergeJournal = MergeJournalPolicy & {
16
22
  identity: string;