@narumitw/pi-sync-daemon 0.6.2 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (97) hide show
  1. package/CHANGELOG.md +19 -0
  2. package/README.md +17 -3
  3. package/dist/consent.js +26 -1
  4. package/dist/engine/backends/git/git-backend.d.ts +1 -1
  5. package/dist/engine/backends/git/git-backend.js +17 -2
  6. package/dist/engine/backends/git/git-storage.d.ts +1 -1
  7. package/dist/engine/backends/git/git-storage.js +39 -13
  8. package/dist/engine/backends/s3/s3-backend.js +8 -0
  9. package/dist/engine/backends/sync-backend.d.ts +1 -0
  10. package/dist/engine/backends/webdav/webdav-backend.js +8 -0
  11. package/dist/engine/ignore/effective-ignore-policy.d.ts +10 -0
  12. package/dist/engine/ignore/effective-ignore-policy.js +33 -0
  13. package/dist/engine/ignore/ignore-edit.d.ts +13 -0
  14. package/dist/engine/ignore/ignore-edit.js +102 -0
  15. package/dist/engine/ignore/ignore-initialization.d.ts +6 -0
  16. package/dist/engine/ignore/ignore-initialization.js +186 -0
  17. package/dist/engine/ignore/ignore-migration-prompt.d.ts +7 -0
  18. package/dist/engine/ignore/ignore-migration-prompt.js +139 -0
  19. package/dist/engine/ignore/ignore-settings.d.ts +15 -0
  20. package/dist/engine/ignore/ignore-settings.js +322 -0
  21. package/dist/engine/ignore/ignore-source.d.ts +27 -0
  22. package/dist/engine/ignore/ignore-source.js +250 -0
  23. package/dist/engine/paths.js +1 -1
  24. package/dist/engine/settings/config-file.d.ts +9 -2
  25. package/dist/engine/settings/config-file.js +126 -28
  26. package/dist/engine/settings/config.d.ts +5 -4
  27. package/dist/engine/settings/config.js +114 -13
  28. package/dist/engine/settings/settings-management.js +34 -32
  29. package/dist/engine/settings/settings-types.d.ts +40 -5
  30. package/dist/engine/settings/settings-validation.js +52 -24
  31. package/dist/engine/snapshot/session-paths.d.ts +6 -4
  32. package/dist/engine/snapshot/session-paths.js +84 -15
  33. package/dist/engine/snapshot/snapshot-apply.d.ts +7 -8
  34. package/dist/engine/snapshot/snapshot-apply.js +107 -21
  35. package/dist/engine/snapshot/snapshot-bounds.d.ts +4 -0
  36. package/dist/engine/snapshot/snapshot-bounds.js +20 -0
  37. package/dist/engine/snapshot/snapshot-codec.d.ts +1 -1
  38. package/dist/engine/snapshot/snapshot-codec.js +15 -7
  39. package/dist/engine/snapshot/snapshot-entry-projection.d.ts +10 -0
  40. package/dist/engine/snapshot/snapshot-entry-projection.js +78 -0
  41. package/dist/engine/snapshot/snapshot-exclude-safety.d.ts +9 -2
  42. package/dist/engine/snapshot/snapshot-exclude-safety.js +239 -24
  43. package/dist/engine/snapshot/snapshot-payload.d.ts +2 -0
  44. package/dist/engine/snapshot/snapshot-payload.js +10 -0
  45. package/dist/engine/snapshot/snapshot-reviewed-preimages.d.ts +2 -0
  46. package/dist/engine/snapshot/snapshot-reviewed-preimages.js +60 -0
  47. package/dist/engine/snapshot/snapshot-root-transition.d.ts +4 -0
  48. package/dist/engine/snapshot/snapshot-root-transition.js +16 -0
  49. package/dist/engine/snapshot/snapshot-transaction-images.d.ts +39 -0
  50. package/dist/engine/snapshot/snapshot-transaction-images.js +387 -0
  51. package/dist/engine/snapshot/snapshot-transaction-policy.d.ts +73 -0
  52. package/dist/engine/snapshot/snapshot-transaction-policy.js +276 -0
  53. package/dist/engine/snapshot/snapshot-transaction-stage.d.ts +32 -0
  54. package/dist/engine/snapshot/snapshot-transaction-stage.js +303 -0
  55. package/dist/engine/snapshot/snapshot-transaction-verification.d.ts +7 -0
  56. package/dist/engine/snapshot/snapshot-transaction-verification.js +78 -0
  57. package/dist/engine/snapshot/snapshot-transaction.d.ts +1 -11
  58. package/dist/engine/snapshot/snapshot-transaction.js +390 -364
  59. package/dist/engine/snapshot/snapshot-types.d.ts +47 -2
  60. package/dist/engine/snapshot/snapshot-types.js +9 -1
  61. package/dist/engine/snapshot/snapshot.d.ts +22 -3
  62. package/dist/engine/snapshot/snapshot.js +357 -43
  63. package/dist/engine/state/merge-baseline-store.js +20 -9
  64. package/dist/engine/state/state-types.d.ts +3 -0
  65. package/dist/engine/sync/apply-review.d.ts +3 -3
  66. package/dist/engine/sync/apply-review.js +5 -4
  67. package/dist/engine/sync/continuous-sync.js +37 -12
  68. package/dist/engine/sync/continuous-watch.d.ts +4 -1
  69. package/dist/engine/sync/continuous-watch.js +90 -15
  70. package/dist/engine/sync/exclude-policy.d.ts +4 -0
  71. package/dist/engine/sync/exclude-policy.js +8 -1
  72. package/dist/engine/sync/initialization.js +9 -4
  73. package/dist/engine/sync/local-fields.d.ts +3 -1
  74. package/dist/engine/sync/local-fields.js +88 -8
  75. package/dist/engine/sync/merge-apply.js +190 -47
  76. package/dist/engine/sync/merge-journal.d.ts +18 -4
  77. package/dist/engine/sync/merge-journal.js +126 -10
  78. package/dist/engine/sync/merged-sync.d.ts +1 -1
  79. package/dist/engine/sync/merged-sync.js +124 -68
  80. package/dist/engine/sync/partial-progress.js +5 -3
  81. package/dist/engine/sync/remote-snapshot.d.ts +10 -2
  82. package/dist/engine/sync/remote-snapshot.js +59 -17
  83. package/dist/engine/sync/session-push.js +7 -6
  84. package/dist/engine/sync/sync-decision.d.ts +4 -0
  85. package/dist/engine/sync/sync-decision.js +17 -2
  86. package/dist/engine/sync/sync-inspection.js +8 -6
  87. package/dist/engine/sync/sync-mutations.d.ts +10 -2
  88. package/dist/engine/sync/sync-mutations.js +245 -101
  89. package/dist/engine/sync/sync-policy.d.ts +36 -10
  90. package/dist/engine/sync/sync-policy.js +285 -20
  91. package/dist/engine/sync/sync-queries.js +49 -32
  92. package/dist/engine/sync/sync-state.d.ts +11 -0
  93. package/dist/engine/sync/sync-state.js +42 -5
  94. package/dist/engine/ui/sync-format.js +22 -7
  95. package/dist/engine-service.js +24 -2
  96. package/docs/architecture.md +28 -0
  97. package/package.json +2 -1
@@ -1,36 +1,51 @@
1
- import { createHash, randomUUID } from "node:crypto";
1
+ import { randomUUID } from "node:crypto";
2
2
  import fs from "node:fs/promises";
3
3
  import path from "node:path";
4
- import { assertWithinRoot, isDeniedPath, isPathInside } from "../paths.js";
5
4
  import { syncDirectory, writeJson } from "../state/json-file.js";
6
5
  import { withLock } from "../state/lock.js";
7
6
  import { syncMutationParents } from "../state/mutation-directory-sync.js";
8
7
  import { stateDir } from "../state/state-directory.js";
9
- import { normalizeSyncExclude, sameSyncExclude } from "../sync/exclude-policy.js";
8
+ import { normalizeSyncExclude } from "../sync/exclude-policy.js";
10
9
  import { mergePathIdentity } from "../sync/file-merge-planner.js";
10
+ import { includeFromSelectionConfig, selectionForSnapshot } from "../sync/sync-policy.js";
11
11
  import { agentDir, configuredSessionDir } from "./session-paths.js";
12
- import { caseReplacementSpelling, coalesceCaseReplacements, isCaseReplacement } from "./snapshot-case-replacement.js";
12
+ import { agentDirectoryConfiguredSessionDir } from "./snapshot.js";
13
+ import { caseReplacementSpelling, coalesceCaseReplacements } from "./snapshot-case-replacement.js";
14
+ import { recheckAgentDirectoryBudget } from "./snapshot-entry-projection.js";
13
15
  import { assertUnexcludedTargets } from "./snapshot-exclude-safety.js";
14
16
  import { withMissingTargetQueues, withTargetQueues } from "./snapshot-mutation-queues.js";
15
17
  import { sessionStorageRoot } from "./snapshot-paths.js";
16
- import { prepareSessionRootTransition, resolveTransitionSessionRoot, validateSessionRootTransition, } from "./snapshot-root-transition.js";
18
+ import { prepareSessionRootTransition, resolveTransitionSessionRoot, stableAgentDirectorySettingsImage, } from "./snapshot-root-transition.js";
17
19
  import { pendingTransactionEntries, transactionRoot } from "./snapshot-transaction-directory.js";
18
- import { fileImage, indexTransactionPlan } from "./snapshot-transaction-plan.js";
20
+ import { legacyImage, MAX_TRANSACTION_JOURNAL_BYTES, ownedScopedPostTree, readTransactionJournal, recheckScopedImage, removeScopedImage, scopedDescendant, scopedIdentity, scopedPathIdentity, scopedTransactionImage, stableScopedIdentity, } from "./snapshot-transaction-images.js";
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";
23
+ import { assertNoUnclaimedLegacyStage, buildScopedRecoveryStage, cleanScopedLegacyStage, cleanScopedWorkspace, inspectScopedRecoveryStage, prepareLegacyRecoveryStage, recoveryStagePath, } from "./snapshot-transaction-stage.js";
24
+ import { verifyTarget } from "./snapshot-transaction-verification.js";
19
25
  const JOURNAL_VERSION = 4;
26
+ class ScopedRemovalError extends Error {
27
+ }
20
28
  export async function applySnapshotTransaction(plan, options = {}) {
21
29
  options.validateMutation?.();
30
+ const root = path.resolve(agentDir());
31
+ if (options.scope === "agent-directory") {
32
+ const sessionDir = options.sessionDir ?? (await agentDirectoryConfiguredSessionDir(options.signal, root, options));
33
+ options = { ...options, sessionDir: sessionStorageRoot(root, sessionDir) };
34
+ }
35
+ const validateIgnorePolicy = ignorePolicyValidator(options);
22
36
  await recoverPendingSnapshotTransactions(options);
23
- const coalesced = await coalesceCaseReplacements(path.resolve(agentDir()), plan);
37
+ const coalesced = await coalesceCaseReplacements(root, plan);
24
38
  options.validateMutation?.();
25
39
  options.signal?.throwIfAborted();
26
40
  const targets = [...new Set([...coalesced.plan.deletes, ...coalesced.plan.writes.map((item) => item.target)])].sort();
27
41
  if (targets.length > 16_384)
28
42
  throw new Error("Snapshot transaction exceeds its target bound; review a smaller transfer.");
29
43
  return withTargetQueues(targets, options, async (heldKeys) => {
30
- await assertUnexcludedTargets(agentDir(), targets, options);
44
+ if (validateIgnorePolicy)
45
+ await validateIgnorePolicy();
46
+ await assertUnexcludedTargets(root, [...targets, ...coalesced.replacements.values()], options);
31
47
  options.signal?.throwIfAborted();
32
- if (targets.some((target) => options.protectedTargets?.some((protectedTarget) => mergePathIdentity(target) === mergePathIdentity(protectedTarget) ||
33
- isPathInside(mergePathIdentity(target), mergePathIdentity(protectedTarget)))))
48
+ if (targets.some((target) => touchesProtectedTarget(target, options.protectedTargets)))
34
49
  throw new Error("Snapshot transaction targets the current session; review is required.");
35
50
  for (const [before, after] of coalesced.replacements) {
36
51
  if ((await caseReplacementSpelling(before, after)) !== before)
@@ -39,13 +54,14 @@ export async function applySnapshotTransaction(plan, options = {}) {
39
54
  options.signal?.throwIfAborted();
40
55
  }
41
56
  const originalTargets = new Map([...coalesced.replacements].map(([before, after]) => [after, before]));
42
- const expectedPreimages = new Map([...(options.expectedPreimages ?? [])].map(([target, expected]) => [
43
- originalTargets.get(target) ?? target,
44
- expected,
45
- ]));
57
+ const scoped = options.scope === "agent-directory";
58
+ /** Fresh apply authorization only; recovery remains bound to durable journal images. */
59
+ const expectedPreimages = new Map([...(options.expectedPreimages ?? [])]
60
+ .filter(([target]) => !scoped || !originalTargets.has(target))
61
+ .map(([target, expected]) => [originalTargets.get(target) ?? target, expected]));
46
62
  // A case-sensitive spelling replacement has two targets, unlike a coalesced physical alias.
47
63
  // Bind both the source bytes and destination absence/bytes before capturing their backups.
48
- for (const [target, expected] of options.expectedPreimages ?? []) {
64
+ for (const [target, expected] of scoped ? [] : (options.expectedPreimages ?? [])) {
49
65
  if (originalTargets.has(target))
50
66
  continue;
51
67
  const variants = coalesced.plan.deletes.filter((candidate) => candidate !== target &&
@@ -56,7 +72,7 @@ export async function applySnapshotTransaction(plan, options = {}) {
56
72
  const original = variants[0];
57
73
  if (!original)
58
74
  continue;
59
- const destination = await image(target);
75
+ const destination = await legacyImage(target);
60
76
  options.validateMutation?.();
61
77
  options.signal?.throwIfAborted();
62
78
  if (destination !== "missing" && destination !== expected)
@@ -64,13 +80,27 @@ export async function applySnapshotTransaction(plan, options = {}) {
64
80
  expectedPreimages.set(original, expected);
65
81
  expectedPreimages.set(target, destination);
66
82
  }
83
+ if (options.scope === "agent-directory") {
84
+ const evidence = await stableAgentDirectorySettingsImage(root, plan, options);
85
+ if (evidence) {
86
+ const target = originalTargets.get(evidence.target) ?? evidence.target;
87
+ const reviewed = expectedPreimages.get(target);
88
+ if (reviewed !== undefined && reviewed !== evidence.image)
89
+ throw new Error("Reviewed Pi settings changed before apply; snapshot installation refused.");
90
+ expectedPreimages.set(target, evidence.image);
91
+ }
92
+ }
67
93
  for (const [target, expected] of expectedPreimages) {
68
- const current = await image(target);
94
+ if (scoped || options.reservedIgnoreNames?.length)
95
+ await assertUnexcludedTargets(root, [target], options);
96
+ const current = scoped ? (await scopedTransactionImage(target, options)).value : await legacyImage(target);
69
97
  options.validateMutation?.();
70
98
  options.signal?.throwIfAborted();
71
99
  if (current !== expected)
72
100
  throw new Error("Reviewed file preimage changed before apply; snapshot installation refused.");
73
101
  }
102
+ if (validateIgnorePolicy)
103
+ await validateIgnorePolicy();
74
104
  const transaction = await prepareTransaction(coalesced.plan, targets, { ...options, expectedPreimages }, coalesced.replacements);
75
105
  const entriesByTarget = new Map(transaction.journal.entries.flatMap((entry) => [
76
106
  [entry.target, entry],
@@ -79,17 +109,25 @@ export async function applySnapshotTransaction(plan, options = {}) {
79
109
  // A released additional key cannot authorize rollback, even for recognized raced bytes.
80
110
  const changesQueueKey = transaction.journal.entries.some((entry) => !heldKeys.has(entry.target) || (entry.afterTarget && !heldKeys.has(entry.afterTarget)));
81
111
  try {
112
+ if (scoped && transaction.deletes.length)
113
+ await recheckAgentDirectoryBudget(root, plan, options, stateDir(root));
82
114
  for (const target of transaction.deletes.sort((a, b) => a.length - b.length)) {
83
115
  options.signal?.throwIfAborted();
84
116
  const entry = entriesByTarget.get(target);
85
117
  if (!entry)
86
118
  throw new Error("Unowned transaction target.");
87
- await removeOwnedTarget(transaction.directory, entry, transaction.journal, options);
119
+ await removeOwnedTarget(transaction.directory, entry, transaction.journal, options, { apply: true });
88
120
  await syncDirectory(path.dirname(target));
89
121
  }
90
122
  await withMissingTargetQueues(transaction.journal.entries
91
123
  .filter((entry) => entry.removalPending)
92
124
  .flatMap((entry) => [entry.target, ...(entry.afterTarget ? [entry.afterTarget] : [])]), heldKeys, options, async () => {
125
+ if (validateIgnorePolicy)
126
+ await validateIgnorePolicy();
127
+ if (scoped && plan.writes.length)
128
+ await recheckAgentDirectoryBudget(root, { deletes: [], writes: plan.writes }, options);
129
+ if (validateIgnorePolicy)
130
+ await validateIgnorePolicy();
93
131
  await retireRemovalIntent(transaction.directory, transaction.journal, transaction.journal.entries.filter((entry) => entry.removalPending && (entry.afterImage !== "missing" || (entry.postFiles?.length ?? 0) > 0)), options);
94
132
  // Only this uninterrupted call knows which deleted writes have not attempted installation yet.
95
133
  const uninstalledWrites = new Set(transaction.deletedWrites);
@@ -99,9 +137,13 @@ export async function applySnapshotTransaction(plan, options = {}) {
99
137
  if (!entry)
100
138
  throw new Error("Unowned transaction target.");
101
139
  const deletedByThisCall = uninstalledWrites.delete(entry.target);
102
- await verifyTarget(transaction.directory, entry, transaction.journal, deletedByThisCall);
140
+ if (options.scope === "agent-directory" || options.reservedIgnoreNames?.length)
141
+ await assertUnexcludedTargets(transaction.journal.root, [item.target], options);
142
+ await verifyTarget(transaction.directory, entry, transaction.journal, options, deletedByThisCall);
103
143
  options.validateMutation?.();
104
144
  options.signal?.throwIfAborted();
145
+ if (validateIgnorePolicy)
146
+ await validateIgnorePolicy();
105
147
  await fs.mkdir(path.dirname(item.target), { recursive: true });
106
148
  options.validateMutation?.();
107
149
  options.signal?.throwIfAborted();
@@ -125,9 +167,13 @@ export async function applySnapshotTransaction(plan, options = {}) {
125
167
  finally {
126
168
  await handle.close();
127
169
  }
128
- await verifyTarget(transaction.directory, entry, transaction.journal, deletedByThisCall);
170
+ const verified = await verifyTarget(transaction.directory, entry, transaction.journal, options, deletedByThisCall);
129
171
  options.signal?.throwIfAborted();
130
172
  options.validateMutation?.();
173
+ if (validateIgnorePolicy && verified.scoped) {
174
+ await validateIgnorePolicy();
175
+ await recheckScopedImage(item.target, verified.scoped, options);
176
+ }
131
177
  await fs.rename(temp, item.target);
132
178
  await syncDirectory(path.dirname(item.target));
133
179
  }
@@ -140,12 +186,18 @@ export async function applySnapshotTransaction(plan, options = {}) {
140
186
  await syncMutationParents(targets, [transaction.journal.root, ...(transaction.journal.sessionRoot ? [transaction.journal.sessionRoot] : [])], options);
141
187
  options.validateMutation?.();
142
188
  options.signal?.throwIfAborted();
189
+ if (validateIgnorePolicy)
190
+ await validateIgnorePolicy();
143
191
  });
192
+ if (validateIgnorePolicy)
193
+ await validateIgnorePolicy();
144
194
  }
145
195
  catch (error) {
146
196
  // Aborted owners cannot roll back files after another session has replaced them.
147
197
  if (options.signal?.aborted)
148
198
  throw new Error("Snapshot apply cancelled; guarded transaction evidence retained for review.");
199
+ if (error instanceof ScopedRemovalError || error instanceof StaleIgnorePolicyError)
200
+ throw error;
149
201
  // Additional queues have been released. Recovery must reserve missing keys afresh.
150
202
  if (changesQueueKey)
151
203
  throw new Error("Snapshot apply failed; guarded transaction evidence retained for review.", {
@@ -181,24 +233,28 @@ export async function recoverPendingSnapshotTransactions(options = {}) {
181
233
  const directory = path.join(transactionRoot(), entry.name);
182
234
  let journal;
183
235
  try {
184
- const file = path.join(directory, "journal.json");
185
- const stat = await fs.lstat(file);
186
- if (!stat.isFile() || stat.size > 32 * 1024 * 1024)
187
- throw new Error("Invalid journal file.");
188
- journal = JSON.parse(await fs.readFile(file, "utf8"));
189
- }
190
- catch (error) {
236
+ const content = await readTransactionJournal(path.join(directory, "journal.json"), options);
191
237
  // Unknown evidence is not disposable, including interrupted preparation directories.
192
- if (error.code === "ENOENT")
238
+ if (content === undefined)
193
239
  continue;
240
+ journal = JSON.parse(content);
241
+ }
242
+ catch {
243
+ options.validateMutation?.();
244
+ options.signal?.throwIfAborted();
194
245
  throw new Error("Cannot recover malformed pi-sync transaction; preserve private evidence for review.");
195
246
  }
247
+ validateJournalPolicy(journal);
248
+ if (!journal.completed) {
249
+ assertRecoveryPolicy(journal, options);
250
+ ignorePolicyValidator(options);
251
+ }
196
252
  let sessionDir = options.sessionDir;
197
- if (sessionDir === undefined &&
198
- options.resolveConfiguredSessionDir &&
199
- !journal.completed &&
200
- transactionHasSessionTargets(journal)) {
201
- sessionDir = await configuredSessionDir();
253
+ if (sessionDir === undefined && !journal.completed) {
254
+ if (options.scope === "agent-directory")
255
+ sessionDir = await agentDirectoryConfiguredSessionDir(options.signal, agentDir(), options);
256
+ else if (options.resolveConfiguredSessionDir && transactionHasSessionTargets(journal))
257
+ sessionDir = await configuredSessionDir(options);
202
258
  }
203
259
  options.validateMutation?.();
204
260
  options.signal?.throwIfAborted();
@@ -210,8 +266,6 @@ export async function recoverPendingSnapshotTransactions(options = {}) {
210
266
  options.signal?.throwIfAborted();
211
267
  }
212
268
  validateJournal(directory, journal, sessionDir);
213
- if (!journal.completed && !sameSyncExclude(journal.exclude, options.exclude))
214
- throw new Error("Pending transaction has a different exclude policy; preserve its backup for reviewed recovery.");
215
269
  if (journal.completed) {
216
270
  await removeTransaction(directory);
217
271
  continue;
@@ -222,7 +276,9 @@ export async function recoverPendingSnapshotTransactions(options = {}) {
222
276
  async function prepareTransaction(plan, targets, options, replacements = new Map()) {
223
277
  const { sessionDir } = options;
224
278
  const root = path.resolve(agentDir());
225
- const sessionRoot = sessionDir ? path.resolve(sessionStorageRoot(root, sessionDir)) : undefined;
279
+ const wholeDirectory = options.scope === "agent-directory";
280
+ const ignoreSource = options.ignorePolicy ? ignoreSourceBinding(options.ignorePolicy) : undefined;
281
+ const sessionRoot = sessionDir || wholeDirectory ? path.resolve(sessionStorageRoot(root, sessionDir)) : undefined;
226
282
  const indexed = indexTransactionPlan(plan, targets);
227
283
  const directory = path.join(transactionRoot(), randomUUID());
228
284
  const backupDirectory = path.join(directory, "before");
@@ -233,52 +289,25 @@ async function prepareTransaction(plan, targets, options, replacements = new Map
233
289
  options.validateMutation?.();
234
290
  assertAllowedTarget(root, sessionRoot, target);
235
291
  await assertSafeParents(root, sessionRoot, target);
292
+ if (wholeDirectory || options.reservedIgnoreNames?.length)
293
+ await assertUnexcludedTargets(root, [target], options);
236
294
  const entry = { target, backupName: `${index}`, kind: "missing" };
237
295
  if (replacements.has(target))
238
296
  entry.afterTarget = replacements.get(target);
239
297
  const backup = path.join(backupDirectory, entry.backupName);
240
- try {
241
- const stat = await fs.lstat(target);
242
- if (stat.isSymbolicLink()) {
243
- entry.kind = "symlink";
244
- entry.linkTarget = await fs.readlink(target);
245
- }
246
- else if (stat.isDirectory()) {
247
- entry.kind = "directory";
248
- await fs.cp(target, backup, {
249
- recursive: true,
250
- dereference: false,
251
- verbatimSymlinks: true,
252
- preserveTimestamps: true,
253
- filter: () => {
254
- options.signal?.throwIfAborted();
255
- options.validateMutation?.();
256
- return true;
257
- },
258
- });
259
- }
260
- else if (stat.isFile()) {
261
- entry.kind = "file";
262
- await fs.copyFile(target, backup);
263
- await fs.chmod(backup, stat.mode);
264
- }
265
- else
266
- throw new Error("Unsupported existing snapshot target.");
298
+ if (wholeDirectory) {
299
+ const captured = await scopedTransactionImage(target, options, backup, (source) => assertUnexcludedTargets(root, [source], options, { recursive: false }));
300
+ entry.kind = captured.kind;
301
+ entry.beforeImage = captured.value;
267
302
  }
268
- catch (error) {
269
- const code = error.code;
270
- if (code !== "ENOENT" && code !== "ENOTDIR")
271
- throw error;
303
+ else {
304
+ await captureLegacyBackup(target, backup, entry, options);
272
305
  }
273
- entry.beforeImage =
274
- entry.kind === "symlink"
275
- ? `symlink:${entry.linkTarget}`
276
- : entry.kind === "missing"
277
- ? "missing"
278
- : await image(backup, true);
279
306
  options.validateMutation?.();
280
307
  options.signal?.throwIfAborted();
281
308
  const expected = options.expectedPreimages?.get(target);
309
+ if (wholeDirectory && entry.kind === "directory" && expected === undefined)
310
+ throw new Error("Scoped directory replacement requires a reviewed preimage.");
282
311
  if (expected !== undefined && entry.beforeImage !== expected)
283
312
  throw new Error("Reviewed file preimage changed during backup; private preparation evidence retained.");
284
313
  if (entry.afterTarget) {
@@ -294,23 +323,79 @@ async function prepareTransaction(plan, targets, options, replacements = new Map
294
323
  // File fsync does not persist the name linking each backup into this directory.
295
324
  await syncDirectory(backupDirectory);
296
325
  const effectiveRoot = sessionRoot ?? path.join(root, "sessions");
297
- const sessionRootTransition = await prepareSessionRootTransition(directory, root, effectiveRoot, entries, plan, options);
326
+ const sessionRootTransition = wholeDirectory
327
+ ? undefined
328
+ : await prepareSessionRootTransition(directory, root, effectiveRoot, entries, plan, options);
298
329
  const journal = {
299
- version: sessionRootTransition ? 7 : replacements.size ? 5 : JOURNAL_VERSION,
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,
300
339
  root,
301
- ...(options.exclude === undefined ? {} : { exclude: normalizeSyncExclude(options.exclude) }),
340
+ ignoreSource,
341
+ ...(wholeDirectory
342
+ ? { selection: selectionForSnapshot(includeFromSelectionConfig(options), options.exclude, options) }
343
+ : options.exclude === undefined
344
+ ? {}
345
+ : { exclude: normalizeSyncExclude(options.exclude) }),
302
346
  sessionRoot: sessionRootTransition ? effectiveRoot : sessionRoot,
303
347
  sessionRootTransition,
304
348
  entries,
305
349
  };
306
350
  options.signal?.throwIfAborted();
307
351
  options.validateMutation?.();
308
- await writeJson(path.join(directory, "journal.json"), journal, { maxBytes: 32 * 1024 * 1024 });
352
+ await writeJson(path.join(directory, "journal.json"), journal, { maxBytes: MAX_TRANSACTION_JOURNAL_BYTES });
309
353
  await syncDirectory(transactionRoot());
310
354
  await syncDirectory(stateDir());
311
355
  await syncDirectory(path.dirname(stateDir()));
312
356
  return { directory, journal, deletes: indexed.deletes, deletedWrites: indexed.deletedWrites };
313
357
  }
358
+ async function captureLegacyBackup(target, backup, entry, options) {
359
+ try {
360
+ const stat = await fs.lstat(target);
361
+ if (stat.isSymbolicLink()) {
362
+ entry.kind = "symlink";
363
+ entry.linkTarget = await fs.readlink(target);
364
+ }
365
+ else if (stat.isDirectory()) {
366
+ entry.kind = "directory";
367
+ await fs.cp(target, backup, {
368
+ recursive: true,
369
+ dereference: false,
370
+ verbatimSymlinks: true,
371
+ preserveTimestamps: true,
372
+ filter: () => {
373
+ options.signal?.throwIfAborted();
374
+ options.validateMutation?.();
375
+ return true;
376
+ },
377
+ });
378
+ }
379
+ else if (stat.isFile()) {
380
+ entry.kind = "file";
381
+ await fs.copyFile(target, backup);
382
+ await fs.chmod(backup, stat.mode);
383
+ }
384
+ else
385
+ throw new Error("Unsupported existing snapshot target.");
386
+ }
387
+ catch (error) {
388
+ const code = error.code;
389
+ if (code !== "ENOENT" && code !== "ENOTDIR")
390
+ throw error;
391
+ }
392
+ entry.beforeImage =
393
+ entry.kind === "symlink"
394
+ ? `symlink:${entry.linkTarget}`
395
+ : entry.kind === "missing"
396
+ ? "missing"
397
+ : await legacyImage(backup, true);
398
+ }
314
399
  async function restoreTransaction(directory, journal, options, heldKeys) {
315
400
  validateJournal(directory, journal, options.sessionDir);
316
401
  const missingSpellings = [];
@@ -331,15 +416,34 @@ async function restoreTransaction(directory, journal, options, heldKeys) {
331
416
  }
332
417
  async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
333
418
  validateJournal(directory, journal, options.sessionDir);
419
+ const scoped = isScopedJournal(journal);
420
+ const validateIgnorePolicy = ignorePolicyValidator(options);
334
421
  options.validateMutation?.();
335
422
  options.signal?.throwIfAborted();
423
+ if (validateIgnorePolicy) {
424
+ assertRecoveryPolicy(journal, options);
425
+ await validateIgnorePolicy();
426
+ }
427
+ await assertUnexcludedTargets(journal.root, journal.entries.flatMap((entry) => [entry.target, ...(entry.afterTarget ? [entry.afterTarget] : [])]), options);
336
428
  for (const entry of journal.entries) {
337
- if (options.protectedTargets?.some((target) => mergePathIdentity(target) === mergePathIdentity(entry.target) ||
338
- isPathInside(mergePathIdentity(entry.target), mergePathIdentity(target))))
429
+ if (touchesProtectedTarget(entry.target, options.protectedTargets))
339
430
  throw new Error("Pending transaction touches the current session; resume a different session before guarded recovery.");
340
- await verifyTarget(directory, entry, journal);
431
+ const { value, before } = await verifyTarget(directory, entry, journal, options);
432
+ if (scoped) {
433
+ await assertNoUnclaimedLegacyStage(directory, entry, options);
434
+ const stage = await inspectScopedRecoveryStage(directory, entry, options);
435
+ if (entry.recoveryWorkspace && !stage && value !== before)
436
+ throw new Error("Recovery workspace is missing; preserve evidence for review.");
437
+ if (entry.vacantInstall && value === "missing") {
438
+ if (!stage ||
439
+ stage.image.kind === "missing" ||
440
+ stage.image.value !== before ||
441
+ stage.partial.kind !== "missing" ||
442
+ scopedIdentity(stage.image.stat) !== entry.vacantInstall)
443
+ throw new Error("Recovery vacancy has no verified staging image; preserve evidence for review.");
444
+ }
445
+ }
341
446
  }
342
- // Recover copies left by a process crash even when the target is already restored.
343
447
  for (const entry of journal.entries) {
344
448
  if (!entry.recoveryStaged)
345
449
  continue;
@@ -348,21 +452,45 @@ async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
348
452
  await assertSafeParents(journal.root, journal.sessionRoot, entry.target);
349
453
  options.validateMutation?.();
350
454
  options.signal?.throwIfAborted();
351
- await fs.rm(recoveryStagePath(directory, entry), { recursive: true, force: true });
455
+ if (scoped)
456
+ await cleanScopedLegacyStage(directory, entry, options);
457
+ else
458
+ await fs.rm(recoveryStagePath(directory, entry), { recursive: true, force: true });
352
459
  options.validateMutation?.();
353
460
  options.signal?.throwIfAborted();
354
461
  }
462
+ if (scoped && journal.version < AGENT_DIRECTORY_JOURNAL_VERSION) {
463
+ journal.version = AGENT_DIRECTORY_JOURNAL_VERSION;
464
+ for (const entry of journal.entries)
465
+ delete entry.recoveryStaged;
466
+ options.validateMutation?.();
467
+ options.signal?.throwIfAborted();
468
+ await persistJournal(directory, journal);
469
+ }
355
470
  // Verify the complete group before removing any path. Recheck each destructive boundary.
356
471
  for (const entry of [...journal.entries].sort((a, b) => a.target.length - b.target.length)) {
357
- const current = await verifyTarget(directory, entry, journal);
358
- const before = await beforeImage(directory, entry);
472
+ const { value: current, before } = await verifyTarget(directory, entry, journal, options);
359
473
  const spellingMatches = async () => !entry.afterTarget || (await caseReplacementSpelling(entry.target, entry.afterTarget)) === entry.target;
360
- if (current === before && (await spellingMatches()))
474
+ if (current === before && (await spellingMatches())) {
475
+ if (entry.recoveryWorkspace) {
476
+ if (validateIgnorePolicy)
477
+ await validateIgnorePolicy();
478
+ await cleanScopedWorkspace(directory, entry, options);
479
+ }
361
480
  continue;
481
+ }
362
482
  options.signal?.throwIfAborted();
363
483
  options.validateMutation?.();
484
+ if (entry.kind === "missing") {
485
+ await removeOwnedTarget(directory, entry, journal, options, { restoringBefore: before });
486
+ continue;
487
+ }
488
+ if (scoped) {
489
+ await restoreScopedEntry(directory, journal, entry, options, heldKeys, before, spellingMatches);
490
+ continue;
491
+ }
492
+ const temporary = await prepareLegacyRecoveryStage(directory, entry, options, () => persistJournal(directory, journal));
364
493
  if (entry.kind === "file") {
365
- const temporary = await prepareRecoveryStage(directory, journal, entry, options);
366
494
  try {
367
495
  await fs.mkdir(path.dirname(entry.target), { recursive: true });
368
496
  await fs.copyFile(path.join(directory, "before", entry.backupName), temporary);
@@ -374,7 +502,7 @@ async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
374
502
  finally {
375
503
  await handle.close();
376
504
  }
377
- const verified = await verifyTarget(directory, entry, journal);
505
+ const { value: verified } = await verifyTarget(directory, entry, journal, options);
378
506
  options.validateMutation?.();
379
507
  options.signal?.throwIfAborted();
380
508
  if (verified === before && (await spellingMatches()))
@@ -386,20 +514,20 @@ async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
386
514
  await removeOwnedTarget(directory, entry, journal, options);
387
515
  }
388
516
  else if (verified.startsWith("directory:") &&
389
- !(await removeOwnedTarget(directory, entry, journal, options, before)))
517
+ !(await removeOwnedTarget(directory, entry, journal, options, { restoringBefore: before })))
390
518
  continue;
391
519
  await withMissingTargetQueues(entry.afterTarget && (needsCaseQueue || verified === "missing")
392
520
  ? [entry.target, entry.afterTarget]
393
521
  : verified.startsWith("directory:")
394
522
  ? [entry.target]
395
523
  : [], heldKeys, options, async () => {
396
- const atRename = await verifyTarget(directory, entry, journal);
524
+ const { value: atRename } = await verifyTarget(directory, entry, journal, options);
397
525
  options.validateMutation?.();
398
526
  options.signal?.throwIfAborted();
399
527
  if (atRename === before && (await spellingMatches()))
400
528
  return;
401
529
  await retireRestorationIntent(directory, journal, entry, options);
402
- const atInstall = await verifyTarget(directory, entry, journal, atRename === "missing");
530
+ const { value: atInstall } = await verifyTarget(directory, entry, journal, options, atRename === "missing");
403
531
  options.validateMutation?.();
404
532
  options.signal?.throwIfAborted();
405
533
  if (atInstall === before && (await spellingMatches()))
@@ -413,11 +541,6 @@ async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
413
541
  }
414
542
  continue;
415
543
  }
416
- if (entry.kind === "missing") {
417
- await removeOwnedTarget(directory, entry, journal, options, before);
418
- continue;
419
- }
420
- const temporary = await prepareRecoveryStage(directory, journal, entry, options);
421
544
  try {
422
545
  await fs.mkdir(path.dirname(entry.target), { recursive: true });
423
546
  await assertSafeParents(journal.root, journal.sessionRoot, entry.target);
@@ -436,20 +559,20 @@ async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
436
559
  }
437
560
  else if (entry.linkTarget !== undefined)
438
561
  await fs.symlink(entry.linkTarget, temporary);
439
- if ((await image(temporary, true)) !== before)
562
+ if ((await legacyImage(temporary, true)) !== before)
440
563
  throw new Error("Staged recovery image differs from the backup; evidence retained.");
441
564
  options.validateMutation?.();
442
565
  options.signal?.throwIfAborted();
443
- if (!(await removeOwnedTarget(directory, entry, journal, options, before)))
566
+ if (!(await removeOwnedTarget(directory, entry, journal, options, { restoringBefore: before })))
444
567
  continue;
445
568
  await withMissingTargetQueues([entry.target], heldKeys, options, async () => {
446
- const atRename = await verifyTarget(directory, entry, journal);
569
+ const { value: atRename } = await verifyTarget(directory, entry, journal, options);
447
570
  options.validateMutation?.();
448
571
  options.signal?.throwIfAborted();
449
572
  if (atRename === before)
450
573
  return;
451
574
  await retireRestorationIntent(directory, journal, entry, options);
452
- const atInstall = await verifyTarget(directory, entry, journal, atRename === "missing");
575
+ const { value: atInstall } = await verifyTarget(directory, entry, journal, options, atRename === "missing");
453
576
  options.validateMutation?.();
454
577
  options.signal?.throwIfAborted();
455
578
  if (atInstall === before)
@@ -465,54 +588,173 @@ async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
465
588
  await syncMutationParents(journal.entries.map((entry) => entry.target), [journal.root, ...(journal.sessionRoot ? [journal.sessionRoot] : [])], options);
466
589
  options.validateMutation?.();
467
590
  options.signal?.throwIfAborted();
591
+ if (validateIgnorePolicy)
592
+ await validateIgnorePolicy();
468
593
  await completeTransaction(directory, journal);
469
594
  }
470
- async function verifyTarget(directory, entry, journal, deletedByThisCall = false) {
595
+ async function restoreScopedEntry(directory, journal, entry, options, heldKeys, before, spellingMatches) {
596
+ const validateIgnorePolicy = ignorePolicyValidator(options);
597
+ options.validateMutation?.();
598
+ options.signal?.throwIfAborted();
599
+ if (validateIgnorePolicy)
600
+ await validateIgnorePolicy();
601
+ await fs.mkdir(path.dirname(entry.target), { recursive: true });
471
602
  await assertSafeParents(journal.root, journal.sessionRoot, entry.target);
472
- // Hash the potentially large backup before observing the live target, not after it.
473
- const before = await beforeImage(directory, entry);
474
- if (journal.version >= 2 && before !== entry.beforeImage)
475
- throw new Error("Transaction backup changed; preserve evidence for review.");
476
- if (entry.afterTarget)
477
- await caseReplacementSpelling(entry.target, entry.afterTarget);
478
- const current = await image(entry.target);
479
- if (current === before)
480
- return current;
481
- if (current === "missing") {
482
- if (deletedByThisCall || (journal.version >= 4 && entry.removalPending && !entry.replacementStarted))
483
- return current;
603
+ if (!entry.vacantInstall) {
604
+ if (validateIgnorePolicy)
605
+ await validateIgnorePolicy();
606
+ await buildScopedRecoveryStage(directory, entry, options, () => persistJournal(directory, journal));
484
607
  }
485
- else if (journal.version >= 2 &&
486
- (current === entry.afterImage ||
487
- (await ownedPostTree(entry.target, entry.postFiles ?? [], journal.version < 4 || entry.replacementStarted === true || !entry.removalPending))))
488
- return current;
489
- throw new Error("Transaction target has unrecognized or newer bytes; automatic rollback refused. Preserve the transaction and review its backup with Pi closed.");
608
+ const verifyStage = async () => {
609
+ const stage = await inspectScopedRecoveryStage(directory, entry, options, true);
610
+ if (!stage || stage.image.kind === "missing" || stage.image.value !== before || stage.partial.kind !== "missing")
611
+ throw new Error("Staged recovery image changed; evidence retained.");
612
+ if (entry.vacantInstall && scopedIdentity(stage.image.stat) !== entry.vacantInstall)
613
+ throw new Error("Recovery vacancy has a different staging image; preserve evidence for review.");
614
+ const identity = stableScopedIdentity(stage.payload, stage.image.stat);
615
+ return { payload: stage.payload, identity, image: stage.image };
616
+ };
617
+ await verifyStage();
618
+ const { value: verified } = await verifyTarget(directory, entry, journal, options);
619
+ if (verified !== before || !(await spellingMatches())) {
620
+ const needsCaseQueue = entry.afterTarget !== undefined &&
621
+ (await caseReplacementSpelling(entry.target, entry.afterTarget)) === entry.afterTarget;
622
+ const needsRemoval = verified !== "missing" && (needsCaseQueue || verified.startsWith("directory:") || entry.kind === "directory");
623
+ const needsVacantTarget = needsRemoval || verified === "missing";
624
+ if (!needsRemoval ||
625
+ (await removeOwnedTarget(directory, entry, journal, options, {
626
+ restoringBefore: needsCaseQueue ? undefined : before,
627
+ }))) {
628
+ const queueTargets = needsVacantTarget ? [entry.target, ...(entry.afterTarget ? [entry.afterTarget] : [])] : [];
629
+ await withMissingTargetQueues(queueTargets, heldKeys, options, async () => {
630
+ if (validateIgnorePolicy)
631
+ await validateIgnorePolicy();
632
+ const { value: atRename } = await verifyTarget(directory, entry, journal, options);
633
+ if (atRename === before && (await spellingMatches()))
634
+ return;
635
+ if (needsVacantTarget && atRename !== "missing")
636
+ throw new Error("Transaction target changed after removal; preserve evidence for review.");
637
+ const stage = await verifyStage();
638
+ if (needsVacantTarget && !entry.vacantInstall) {
639
+ if (validateIgnorePolicy)
640
+ await validateIgnorePolicy();
641
+ entry.vacantInstall = stage.identity;
642
+ delete entry.removalPending;
643
+ delete entry.replacementStarted;
644
+ delete entry.scopedRemoval;
645
+ for (const child of journal.entries) {
646
+ if (isStrictlyInside(entry.target, child.target))
647
+ delete child.scopedRemoval;
648
+ }
649
+ options.validateMutation?.();
650
+ options.signal?.throwIfAborted();
651
+ await syncDirectory(path.dirname(entry.target));
652
+ options.validateMutation?.();
653
+ options.signal?.throwIfAborted();
654
+ await persistJournal(directory, journal);
655
+ await verifyStage();
656
+ }
657
+ if ((await scopedPathIdentity(stage.payload, options)) !== stage.identity)
658
+ throw new Error("Staged recovery image changed before restoration; preserve evidence for review.");
659
+ const atInstall = await verifyTarget(directory, entry, journal, options);
660
+ if (atInstall.value === before && (await spellingMatches()))
661
+ return;
662
+ if (atInstall.value !== atRename)
663
+ throw new Error("Transaction target changed before restoration; preserve evidence for review.");
664
+ options.validateMutation?.();
665
+ options.signal?.throwIfAborted();
666
+ if (validateIgnorePolicy && atInstall.scoped) {
667
+ await validateIgnorePolicy();
668
+ await recheckScopedImage(stage.payload, stage.image, options);
669
+ await recheckScopedImage(entry.target, atInstall.scoped, options);
670
+ }
671
+ await fs.rename(stage.payload, entry.target);
672
+ await syncDirectory(path.dirname(entry.target));
673
+ await syncDirectory(path.dirname(stage.payload));
674
+ if ((await verifyTarget(directory, entry, journal, options)).value !== before)
675
+ throw new Error("Restored transaction image changed; evidence retained.");
676
+ });
677
+ }
678
+ }
679
+ if (validateIgnorePolicy)
680
+ await validateIgnorePolicy();
681
+ await cleanScopedWorkspace(directory, entry, options);
490
682
  }
491
- async function removeOwnedTarget(directory, entry, journal, options, restoringBefore) {
492
- await assertUnexcludedTargets(journal.root, [entry.target], options);
493
- const current = await verifyTarget(directory, entry, journal);
494
- options.validateMutation?.();
495
- options.signal?.throwIfAborted();
496
- if (restoringBefore !== undefined && current === restoringBefore)
497
- return false;
498
- // Persist intent before removal, including descendants affected by a recursive delete.
499
- // Until replacement is armed, interrupted removal can recognize absence without accepting unknown bytes.
500
- upgradeRemovalEvidence(journal);
501
- for (const affected of journal.entries) {
502
- if (affected.target === entry.target || isStrictlyInside(entry.target, affected.target)) {
683
+ async function removeOwnedTarget(directory, entry, journal, options, { apply, restoringBefore } = {}) {
684
+ const scoped = isScopedJournal(journal);
685
+ const validateIgnorePolicy = ignorePolicyValidator(options);
686
+ try {
687
+ if (validateIgnorePolicy)
688
+ await validateIgnorePolicy();
689
+ await assertUnexcludedTargets(journal.root, [entry.target, ...(entry.afterTarget ? [entry.afterTarget] : [])], options);
690
+ const current = await verifyTarget(directory, entry, journal, options);
691
+ options.validateMutation?.();
692
+ options.signal?.throwIfAborted();
693
+ if (restoringBefore !== undefined && current.value === restoringBefore)
694
+ return false;
695
+ if (scoped && apply && current.value !== current.before)
696
+ throw new Error("Reviewed removal image changed; preserve evidence for review.");
697
+ // Until replacement is armed, interrupted removal can recognize absence without accepting unknown bytes.
698
+ upgradeRemovalEvidence(journal);
699
+ for (const affected of journal.entries) {
700
+ if (affected.target !== entry.target && !isStrictlyInside(entry.target, affected.target))
701
+ continue;
503
702
  affected.removalPending = true;
504
703
  affected.replacementStarted = false;
704
+ if (affected.vacantInstall)
705
+ throw new Error("Transaction removal overlaps a recovery vacancy; preserve evidence for review.");
706
+ if (!current.scoped)
707
+ continue;
708
+ const relative = path.relative(entry.target, affected.target);
709
+ const observed = scopedDescendant(current.scoped, relative);
710
+ if (!observed || observed.kind === "missing")
711
+ continue;
712
+ const observedPath = path.join(entry.target, relative);
713
+ const mayChange = observed.kind === "directory" && observed.children.length > 0;
714
+ if (affected.scopedRemoval) {
715
+ if (mayChange)
716
+ stableScopedIdentity(observedPath, observed.stat);
717
+ continue;
718
+ }
719
+ const image = observed.value === affected.beforeImage
720
+ ? "before"
721
+ : observed.value === affected.afterImage || ownedScopedPostTree(observed, affected.postFiles ?? [], true)
722
+ ? "after"
723
+ : undefined;
724
+ if (!image)
725
+ continue;
726
+ affected.scopedRemoval = {
727
+ image,
728
+ identity: mayChange ? stableScopedIdentity(observedPath, observed.stat) : scopedIdentity(observed.stat),
729
+ };
505
730
  }
731
+ options.validateMutation?.();
732
+ options.signal?.throwIfAborted();
733
+ await persistJournal(directory, journal);
734
+ const verified = await verifyTarget(directory, entry, journal, options);
735
+ options.validateMutation?.();
736
+ options.signal?.throwIfAborted();
737
+ if (restoringBefore !== undefined && verified.value === restoringBefore)
738
+ return false;
739
+ if (current.scoped) {
740
+ if (current.value !== verified.value)
741
+ throw new Error("Transaction removal image changed.");
742
+ await assertUnexcludedTargets(journal.root, [entry.target], options);
743
+ await removeScopedImage(entry.target, current.scoped, options, validateIgnorePolicy);
744
+ }
745
+ else {
746
+ await fs.rm(entry.target, { recursive: true, force: true });
747
+ }
748
+ await syncDirectory(path.dirname(entry.target));
749
+ return true;
750
+ }
751
+ catch (error) {
752
+ if (!scoped || error instanceof StaleIgnorePolicyError)
753
+ throw error;
754
+ throw new ScopedRemovalError("Scoped transaction removal stopped; preserve transaction and backup for review.", {
755
+ cause: error,
756
+ });
506
757
  }
507
- await writeJson(path.join(directory, "journal.json"), journal, { maxBytes: 32 * 1024 * 1024 });
508
- const verified = await verifyTarget(directory, entry, journal);
509
- options.validateMutation?.();
510
- options.signal?.throwIfAborted();
511
- if (restoringBefore !== undefined && verified === restoringBefore)
512
- return false;
513
- await fs.rm(entry.target, { recursive: true, force: true });
514
- await syncDirectory(path.dirname(entry.target));
515
- return true;
516
758
  }
517
759
  function upgradeRemovalEvidence(journal) {
518
760
  if (journal.version < JOURNAL_VERSION) {
@@ -531,8 +773,9 @@ async function retireRemovalIntent(directory, journal, entries, options) {
531
773
  for (const entry of entries) {
532
774
  entry.removalPending = false;
533
775
  entry.replacementStarted = true;
776
+ delete entry.scopedRemoval;
534
777
  }
535
- await writeJson(path.join(directory, "journal.json"), journal, { maxBytes: 32 * 1024 * 1024 });
778
+ await writeJson(path.join(directory, "journal.json"), journal, { maxBytes: MAX_TRANSACTION_JOURNAL_BYTES });
536
779
  options.validateMutation?.();
537
780
  options.signal?.throwIfAborted();
538
781
  }
@@ -546,235 +789,18 @@ async function retireRestorationIntent(directory, journal, entry, options) {
546
789
  }
547
790
  await retireRemovalIntent(directory, journal, [entry], options);
548
791
  }
549
- function recoveryStagePath(directory, entry) {
550
- const token = createHash("sha256").update(directory).update("\\0").update(entry.backupName).digest("hex");
551
- return path.join(path.dirname(entry.target), `.pi-sync.json.${token}.${entry.kind === "file" ? "restore" : "restore-tree"}`);
552
- }
553
- async function prepareRecoveryStage(directory, journal, entry, options) {
554
- const temporary = recoveryStagePath(directory, entry);
555
- if (!entry.recoveryStaged) {
556
- try {
557
- await fs.lstat(temporary);
558
- throw new Error("Unowned recovery staging path; preserve evidence for review.");
559
- }
560
- catch (error) {
561
- if (error.code !== "ENOENT")
562
- throw error;
563
- }
564
- options.validateMutation?.();
565
- options.signal?.throwIfAborted();
566
- entry.recoveryStaged = true;
567
- await writeJson(path.join(directory, "journal.json"), journal, { maxBytes: 32 * 1024 * 1024 });
568
- options.validateMutation?.();
569
- options.signal?.throwIfAborted();
570
- }
571
- return temporary;
572
- }
573
- async function beforeImage(directory, entry) {
574
- if (entry.kind === "missing")
575
- return "missing";
576
- if (entry.kind === "symlink")
577
- return `symlink:${entry.linkTarget}`;
578
- const value = await image(path.join(directory, "before", entry.backupName));
579
- if (value === "missing")
580
- throw new Error("Transaction backup is missing; preserve evidence for review.");
581
- return value;
582
- }
583
- async function image(target, durable = false) {
584
- let stat;
585
- try {
586
- stat = await fs.lstat(target);
587
- }
588
- catch (error) {
589
- const code = error.code;
590
- if (code === "ENOENT" || code === "ENOTDIR")
591
- return "missing";
592
- throw error;
593
- }
594
- if (stat.isSymbolicLink())
595
- return `symlink:${await fs.readlink(target)}`;
596
- if (stat.isFile()) {
597
- const content = await fs.readFile(target);
598
- if (durable) {
599
- // Keep POSIX read-only backup permissions; Windows flushing requires write access.
600
- const handle = await fs.open(target, process.platform === "win32" ? "r+" : "r");
601
- try {
602
- await handle.sync();
603
- }
604
- finally {
605
- await handle.close();
606
- }
607
- }
608
- return fileImage(content);
609
- }
610
- if (!stat.isDirectory())
611
- throw new Error("Unsupported transaction image.");
612
- const entries = [];
613
- for (const name of (await fs.readdir(target)).sort())
614
- entries.push([name, await image(path.join(target, name), durable)]);
615
- if (durable)
616
- await syncDirectory(target);
617
- return `directory:${createHash("sha256").update(JSON.stringify(entries)).digest("hex")}`;
618
- }
619
- async function ownedPostTree(target, files, requireComplete) {
620
- if (!files.length)
621
- return false;
622
- const expected = new Map(files.map((file) => [mergePathIdentity(file.relative), file.image]));
623
- const prefixes = new Set();
624
- for (const relative of expected.keys()) {
625
- for (let parent = path.dirname(relative); parent !== "." && parent !== path.dirname(parent); parent = path.dirname(parent))
626
- prefixes.add(parent);
627
- }
628
- const seen = new Set();
629
- async function visit(directory) {
630
- let stat;
631
- try {
632
- stat = await fs.lstat(directory);
633
- }
634
- catch {
635
- return false;
636
- }
637
- if (!stat.isDirectory() || stat.isSymbolicLink())
638
- return false;
639
- for (const name of await fs.readdir(directory)) {
640
- const child = path.join(directory, name);
641
- const relative = mergePathIdentity(path.relative(target, child));
642
- const stat = await fs.lstat(child);
643
- if (stat.isDirectory() && !stat.isSymbolicLink()) {
644
- if (!prefixes.has(relative) || !(await visit(child)))
645
- return false;
646
- }
647
- else {
648
- if (expected.get(relative) !== (await image(child)))
649
- return false;
650
- seen.add(relative);
651
- }
652
- }
653
- return true;
654
- }
655
- return (await visit(target)) && (!requireComplete || [...expected.keys()].every((key) => seen.has(key)));
656
- }
657
- function validateJournal(directory, journal, sessionDir) {
658
- if (![1, 2, 3, 4, 5, 6, 7].includes(journal.version) ||
659
- !Array.isArray(journal.entries) ||
660
- journal.entries.length > 16_384)
661
- throw new Error("Unsupported pi-sync transaction journal; preserve evidence for review.");
662
- if (journal.exclude !== undefined && !Array.isArray(journal.exclude))
663
- throw new Error("Invalid transaction exclude policy; preserve evidence.");
664
- normalizeSyncExclude(journal.exclude);
665
- if (journal.completed !== undefined && (![6, 7].includes(journal.version) || journal.completed !== true))
666
- throw new Error("Invalid transaction completion evidence.");
667
- const root = path.resolve(agentDir());
668
- if (typeof journal.root !== "string" || path.resolve(journal.root) !== root)
669
- throw new Error("Transaction root no longer matches the Pi agent directory.");
670
- if (journal.sessionRootTransition !== undefined) {
671
- if (journal.version !== 7 || typeof journal.sessionRoot !== "string")
672
- throw new Error("Invalid session root-transition version.");
673
- validateSessionRootTransition(journal.sessionRootTransition);
674
- }
675
- else if (journal.version === 7)
676
- throw new Error("Missing session root-transition evidence.");
677
- const trustedSessionRoot = sessionDir
678
- ? path.resolve(sessionStorageRoot(root, sessionDir))
679
- : path.join(root, "sessions");
680
- if (journal.sessionRoot !== undefined &&
681
- (typeof journal.sessionRoot !== "string" ||
682
- !path.isAbsolute(journal.sessionRoot) ||
683
- path.resolve(journal.sessionRoot) !== journal.sessionRoot ||
684
- (!journal.completed && transactionHasSessionTargets(journal) && journal.sessionRoot !== trustedSessionRoot)))
685
- throw new Error("Transaction session root is not owned by this context; preserve evidence for review.");
686
- for (const entry of journal.entries) {
687
- if (!entry ||
688
- typeof entry.target !== "string" ||
689
- !path.isAbsolute(entry.target) ||
690
- path.resolve(entry.target) !== entry.target ||
691
- typeof entry.backupName !== "string" ||
692
- !/^\d+$/u.test(entry.backupName) ||
693
- !["missing", "file", "directory", "symlink"].includes(entry.kind))
694
- throw new Error("Invalid pi-sync transaction entry.");
695
- assertWithinRoot(directory, path.join(directory, "before", entry.backupName));
696
- assertAllowedTarget(root, journal.sessionRoot, entry.target);
697
- if (entry.afterTarget !== undefined &&
698
- (![5, 6, 7].includes(journal.version) ||
699
- typeof entry.afterTarget !== "string" ||
700
- !isCaseReplacement(root, entry.target, entry.afterTarget) ||
701
- path.resolve(entry.afterTarget) !== entry.afterTarget ||
702
- entry.kind !== "file"))
703
- throw new Error("Invalid transaction case replacement evidence.");
704
- if (entry.afterTarget)
705
- assertAllowedTarget(root, journal.sessionRoot, entry.afterTarget);
706
- if (journal.version >= 2 &&
707
- ((entry.beforeImage === undefined ? !journal.completed : typeof entry.beforeImage !== "string") ||
708
- (entry.afterImage === undefined ? !journal.completed : typeof entry.afterImage !== "string") ||
709
- (entry.postFiles === undefined ? !journal.completed : !Array.isArray(entry.postFiles))))
710
- throw new Error("Invalid transaction postimage evidence.");
711
- if (entry.recoveryStaged !== undefined && typeof entry.recoveryStaged !== "boolean")
712
- throw new Error("Invalid recovery staging evidence.");
713
- if (entry.removalPending !== undefined && (journal.version < 3 || typeof entry.removalPending !== "boolean"))
714
- throw new Error("Invalid transaction removal evidence.");
715
- if (entry.replacementStarted !== undefined &&
716
- (journal.version < 4 || typeof entry.replacementStarted !== "boolean"))
717
- throw new Error("Invalid transaction replacement evidence.");
718
- if (entry.removalPending && entry.replacementStarted)
719
- throw new Error("Conflicting transaction replacement evidence.");
720
- for (const file of entry.postFiles ?? []) {
721
- if (typeof file.relative !== "string" ||
722
- typeof file.image !== "string" ||
723
- !isStrictlyInside(entry.target, path.resolve(entry.target, file.relative)))
724
- throw new Error("Invalid transaction subtree evidence.");
725
- }
726
- }
727
- }
728
- function transactionHasSessionTargets(journal) {
729
- const root = path.resolve(agentDir());
730
- return (Array.isArray(journal.entries) &&
731
- journal.entries.some((entry) => typeof entry?.target === "string" &&
732
- (!isPathInside(root, entry.target) ||
733
- isPathInside(path.join(root, "sessions"), entry.target) ||
734
- (typeof journal.sessionRoot === "string" && isPathInside(journal.sessionRoot, entry.target)))));
735
- }
736
- function isStrictlyInside(root, target) {
737
- return path.relative(path.resolve(root), path.resolve(target)) !== "" && isPathInside(root, target);
738
- }
739
- function assertAllowedTarget(root, sessionRoot, target) {
740
- const resolved = path.resolve(target);
741
- if (isStrictlyInside(root, resolved)) {
742
- if (isDeniedPath(path.relative(root, resolved)))
743
- throw new Error("Transaction targets denied private storage.");
744
- assertWithinRoot(root, resolved);
745
- return;
746
- }
747
- if (sessionRoot && isStrictlyInside(sessionRoot, resolved)) {
748
- if (isDeniedPath(`sessions/${path.relative(sessionRoot, resolved)}`))
749
- throw new Error("Transaction targets denied session storage.");
750
- assertWithinRoot(sessionRoot, resolved);
751
- return;
752
- }
753
- throw new Error("Transaction target is outside configured roots.");
754
- }
755
- async function assertSafeParents(root, sessionRoot, target) {
756
- assertAllowedTarget(root, sessionRoot, target);
757
- const boundary = isPathInside(root, target) ? root : sessionRoot;
758
- for (let parent = path.dirname(target); boundary && mergePathIdentity(parent) !== mergePathIdentity(boundary); parent = path.dirname(parent)) {
759
- if (path.dirname(parent) === parent)
760
- throw new Error("Transaction parent did not reach its owned boundary.");
761
- try {
762
- const stat = await fs.lstat(parent);
763
- if ((!stat.isDirectory() && !stat.isFile()) || stat.isSymbolicLink())
764
- throw new Error("Unsafe transaction parent.");
765
- }
766
- catch (error) {
767
- const code = error.code;
768
- if (code !== "ENOENT" && code !== "ENOTDIR")
769
- throw error;
770
- }
771
- }
792
+ function persistJournal(directory, journal) {
793
+ return writeJson(path.join(directory, "journal.json"), journal, { maxBytes: MAX_TRANSACTION_JOURNAL_BYTES });
772
794
  }
773
795
  async function completeTransaction(directory, journal) {
774
796
  // Publish completion before deleting any backup. A surviving journal after power loss
775
797
  // may only retry cleanup, never roll back already accepted files.
776
- await writeJson(path.join(directory, "journal.json"), { ...journal, version: journal.sessionRootTransition ? 7 : 6, completed: true }, {
777
- maxBytes: 32 * 1024 * 1024,
798
+ await writeJson(path.join(directory, "journal.json"), {
799
+ ...journal,
800
+ version: isScopedJournal(journal) ? journal.version : journal.sessionRootTransition ? 7 : 6,
801
+ completed: true,
802
+ }, {
803
+ maxBytes: MAX_TRANSACTION_JOURNAL_BYTES,
778
804
  });
779
805
  await removeTransaction(directory);
780
806
  }