@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
@@ -2,6 +2,8 @@ import fs from "node:fs/promises";
2
2
  import os from "node:os";
3
3
  import path from "node:path";
4
4
  import { getEngineRoot as getAgentDir, } from "../host.js";
5
+ import { configuredSnapshotPathMatcher } from "../sync/sync-policy.js";
6
+ import { agentDirectorySessionRoot, reservedIgnoreTargetGuard } from "./snapshot-exclude-safety.js";
5
7
  import { sessionStorageRoot } from "./snapshot-paths.js";
6
8
  export function sessionDirFromContext(ctx) {
7
9
  const manager = ctx.sessionManager;
@@ -12,10 +14,19 @@ export function sessionDirFromContext(ctx) {
12
14
  const getSessionDir = manager.getSessionDir;
13
15
  return typeof getSessionDir === "function" ? getSessionDir.call(manager) : undefined;
14
16
  }
15
- export async function configuredSessionDir() {
17
+ export async function configuredSessionDir(options = {}) {
18
+ const root = agentDir();
19
+ const target = path.join(root, "settings.json");
20
+ const guardReserved = reservedIgnoreTargetGuard(root, options);
16
21
  let content;
17
22
  try {
18
- content = await fs.readFile(path.join(agentDir(), "settings.json"), "utf8");
23
+ if (guardReserved) {
24
+ const { readLegacySnapshotSource } = await import("./snapshot.js");
25
+ content = (await readLegacySnapshotSource(target, guardReserved, options.signal)).toString("utf8");
26
+ }
27
+ else {
28
+ content = await fs.readFile(target, "utf8");
29
+ }
19
30
  }
20
31
  catch (error) {
21
32
  if (error.code === "ENOENT")
@@ -32,27 +43,69 @@ export async function configuredSessionDir() {
32
43
  }
33
44
  return settings?.sessionDir ? expandSessionDir(settings.sessionDir) : undefined;
34
45
  }
35
- export async function effectiveSessionRoot(ctx) {
36
- return path.resolve(sessionStorageRoot(agentDir(), sessionDirFromContext(ctx) ?? (await configuredSessionDir())));
46
+ export async function effectiveSessionRoot(ctx, policy, signal) {
47
+ const sessionDir = sessionDirFromContext(ctx);
48
+ const root = agentDir();
49
+ if (policy?.scope === "agent-directory") {
50
+ if (sessionDir !== undefined || ctx.sessionManager.usesDefaultSessionDir?.())
51
+ return agentDirectorySessionRoot(root, sessionDir, policy.ignorePolicy, policy.reservedIgnoreNames);
52
+ if (!configuredSnapshotPathMatcher(policy)("settings.json"))
53
+ throw new Error("Pi session storage is unknown and settings.json is excluded. Use an active Pi context to sync.");
54
+ const { agentDirectoryConfiguredSessionDir } = await import("./snapshot.js");
55
+ signal?.throwIfAborted();
56
+ const configured = await agentDirectoryConfiguredSessionDir(signal, root, policy);
57
+ return agentDirectorySessionRoot(root, configured, policy.ignorePolicy, policy.reservedIgnoreNames);
58
+ }
59
+ const resolved = sessionStorageRoot(root, sessionDir ?? (await configuredSessionDir({ ...policy, signal })));
60
+ const guardReserved = reservedIgnoreTargetGuard(root, policy ?? {});
61
+ if (guardReserved)
62
+ await guardReserved(resolved);
63
+ return resolved;
37
64
  }
38
- export async function sessionDirForApply(ctx, snapshot) {
65
+ export async function sessionDirForApply(ctx, snapshot, options = {}) {
39
66
  const contextSessionDir = sessionDirFromContext(ctx);
40
- const localSessionDir = await configuredSessionDir();
41
- if (contextSessionDir && path.resolve(contextSessionDir) !== path.resolve(localSessionDir ?? "")) {
42
- return contextSessionDir;
67
+ if (options.scope === "agent-directory") {
68
+ const root = await effectiveSessionRoot(ctx, options, options.signal);
69
+ if (root !==
70
+ agentDirectorySessionRoot(agentDir(), options.sessionDir, options.ignorePolicy, options.reservedIgnoreNames))
71
+ throw new Error("Pi session storage changed during transfer; retry from a fresh review.");
72
+ return root;
43
73
  }
44
- return sessionDirFromSnapshot(snapshot) ?? contextSessionDir;
74
+ const localSessionDir = await configuredSessionDir(options);
75
+ const sessionDir = contextSessionDir && path.resolve(contextSessionDir) !== path.resolve(localSessionDir ?? "")
76
+ ? contextSessionDir
77
+ : (sessionDirFromSnapshot(snapshot) ?? contextSessionDir);
78
+ const root = agentDir();
79
+ const guardReserved = reservedIgnoreTargetGuard(root, options);
80
+ if (guardReserved)
81
+ await guardReserved(sessionStorageRoot(root, sessionDir));
82
+ return sessionDir;
45
83
  }
46
84
  /** Hash-only merge plans cannot describe installation into a different session root. */
47
- export function requireStableMergeSessionRoot(before, after) {
85
+ export function requireStableMergeSessionRoot(before, after, scope) {
86
+ const scoped = scope === "agent-directory";
87
+ const settings = (snapshot) => {
88
+ const files = snapshot.files.filter((file) => (scoped ? file.path.toLowerCase() : file.path) === "settings.json");
89
+ if (files.length > 1)
90
+ throw new Error("Multiple Pi settings paths cannot establish a stable session root.");
91
+ return files[0];
92
+ };
93
+ const previous = settings(before);
94
+ const next = settings(after);
95
+ if (scoped && previous?.sha256 === next?.sha256)
96
+ return;
48
97
  const root = agentDir();
49
- if (path.resolve(sessionStorageRoot(root, sessionDirFromSnapshot(before))) !==
50
- path.resolve(sessionStorageRoot(root, sessionDirFromSnapshot(after)))) {
51
- throw new Error("Merged transfer changes the session root; no local apply or baseline acceptance is allowed. Review /sync diff and choose an explicit push or pull direction.");
98
+ if (path.resolve(sessionStorageRoot(root, sessionDirFromSettingsFile(previous))) !==
99
+ path.resolve(sessionStorageRoot(root, sessionDirFromSettingsFile(next)))) {
100
+ throw new Error(scoped
101
+ ? "Agent-directory transfer would change Pi session storage. Configure session storage on this machine before syncing."
102
+ : "Merged transfer changes the session root; no local apply or baseline acceptance is allowed. Review /sync diff and choose an explicit push or pull direction.");
52
103
  }
53
104
  }
54
105
  function sessionDirFromSnapshot(snapshot) {
55
- const settingsFile = snapshot.files.find((file) => file.path === "settings.json");
106
+ return sessionDirFromSettingsFile(snapshot.files.find((file) => file.path === "settings.json"));
107
+ }
108
+ function sessionDirFromSettingsFile(settingsFile) {
56
109
  if (!settingsFile)
57
110
  return undefined;
58
111
  let settings;
@@ -83,9 +136,25 @@ export function expandSessionDir(value) {
83
136
  return value === "~" || value.startsWith("~/") ? path.join(os.homedir(), value.slice(2)) : value;
84
137
  }
85
138
  export function snapshotOptionsForContext(ctx, config) {
139
+ const defaultScopedSessionDir = config.scope === "agent-directory" && ctx.sessionManager.usesDefaultSessionDir?.()
140
+ ? sessionStorageRoot(agentDir())
141
+ : undefined;
86
142
  return {
87
143
  include: config.include,
144
+ ...(config.scope === undefined ? {} : { scope: config.scope }),
145
+ ...(config.ignorePolicy
146
+ ? { ignorePolicy: config.ignorePolicy, validateIgnorePolicy: config.validateIgnorePolicy }
147
+ : {}),
88
148
  ...(config.exclude === undefined ? {} : { exclude: config.exclude }),
89
- sessionDir: sessionDirFromContext(ctx),
149
+ ...(config.reinclude === undefined ? {} : { reinclude: config.reinclude }),
150
+ ...(config.reservedIgnoreNames === undefined ? {} : { reservedIgnoreNames: config.reservedIgnoreNames }),
151
+ sessionDir: sessionDirFromContext(ctx) ?? defaultScopedSessionDir,
152
+ };
153
+ }
154
+ export async function resolvedSnapshotOptionsForContext(ctx, config, signal) {
155
+ return {
156
+ ...snapshotOptionsForContext(ctx, config),
157
+ ...(config.scope === "agent-directory" ? { sessionDir: await effectiveSessionRoot(ctx, config, signal) } : {}),
158
+ signal,
90
159
  };
91
160
  }
@@ -1,17 +1,16 @@
1
- import type { Snapshot, SnapshotApplyPlan, SnapshotOptions } from "./snapshot-types.js";
2
- export declare function applySnapshot(snapshot: Snapshot, protectedRelativePaths?: Set<string>, options?: Pick<SnapshotOptions, "include" | "exclude" | "sessionDir" | "syncFiles" | "syncSessions" | "extraFiles" | "signal" | "validateMutation" | "expectedFileHashes">): Promise<{
1
+ import { type Snapshot, type SnapshotApplyPlan, type SnapshotOptions } from "./snapshot-types.js";
2
+ export declare function applySnapshot(snapshot: Snapshot, protectedRelativePaths?: Set<string>, options?: Pick<SnapshotOptions, "include" | "exclude" | "scope" | "reinclude" | "ignorePolicy" | "reservedIgnoreNames" | "sessionDir" | "syncFiles" | "syncSessions" | "extraFiles" | "signal" | "validateMutation" | "validateIgnorePolicy" | "expectedFileHashes"> & {
3
+ reviewedLocal?: Pick<Snapshot, "files">;
4
+ }): Promise<{
3
5
  [k: string]: string;
4
6
  }>;
5
- export declare function preflightSnapshotApply(root: string, snapshot: Snapshot, current: Snapshot, options?: {
6
- sessionDir?: string;
7
- exclude?: string[];
8
- }): SnapshotApplyPlan;
7
+ export declare function preflightSnapshotApply(root: string, snapshot: Snapshot, current: Snapshot, options?: SnapshotOptions): SnapshotApplyPlan;
9
8
  export declare function protectSnapshotApplyPlan(root: string, plan: SnapshotApplyPlan, protectedRelativePaths: Set<string>, sessionDir?: string): SnapshotApplyPlan;
10
- export declare function addTopLevelCaseVariantDeletes(root: string, plan: SnapshotApplyPlan, snapshot: Pick<Snapshot, "files">): Promise<SnapshotApplyPlan>;
9
+ export declare function addTopLevelCaseVariantDeletes(root: string, plan: SnapshotApplyPlan, snapshot: Pick<Snapshot, "files" | "selection">, options?: SnapshotOptions): Promise<SnapshotApplyPlan>;
11
10
  export declare function appliedFileHashMap(snapshot: Snapshot, current: Snapshot, protectedRelativePaths: Set<string>): {
12
11
  [k: string]: string;
13
12
  };
14
- type MutationGuards = Pick<SnapshotOptions, "signal" | "validateMutation" | "exclude">;
13
+ type MutationGuards = Pick<SnapshotOptions, "signal" | "validateMutation" | "exclude" | "scope" | "include" | "reinclude" | "ignorePolicy" | "reservedIgnoreNames">;
15
14
  export declare function preflightSnapshotMutations(root: string, plan: {
16
15
  deletes: string[];
17
16
  writes: Array<{
@@ -3,27 +3,51 @@ import fs from "node:fs/promises";
3
3
  import path from "node:path";
4
4
  import { assertWithinRoot, isDeniedPath, isPathInside, parentPaths, safeJoin, toPosix } from "../paths.js";
5
5
  import { syncDirectory } from "../state/json-file.js";
6
- import { compileSyncExclude } from "../sync/exclude-policy.js";
6
+ import { stateDir } from "../state/state-directory.js";
7
+ import { compileSyncPolicyExclude, requireLegacyTransferPolicy, sameSnapshotSelection, selectionForSnapshot, } from "../sync/sync-policy.js";
7
8
  import { agentDir } from "./session-paths.js";
8
- import { createSnapshot, isSessionFilePath, isSessionPath, sessionStorageRoot, snapshotIncludesSessions, snapshotTarget, } from "./snapshot.js";
9
- import { assertUnexcludedTargets } from "./snapshot-exclude-safety.js";
9
+ import { agentDirectoryConfiguredSessionDir, agentDirectoryInventory, createSnapshot, isSessionFilePath, isSessionPath, sessionStorageRoot, snapshotIncludesSessions, snapshotTarget, } from "./snapshot.js";
10
+ import { assertAgentDirectorySnapshotBound } from "./snapshot-bounds.js";
11
+ import { assertProjectedAgentDirectoryBudget } from "./snapshot-entry-projection.js";
12
+ import { agentDirectoryPhysicalSessionPath, assertUnexcludedTargets } from "./snapshot-exclude-safety.js";
13
+ import { decodeBase64Strict } from "./snapshot-payload.js";
14
+ import { reviewedSnapshotPreimages } from "./snapshot-reviewed-preimages.js";
10
15
  import { applySnapshotTransaction, recoverPendingSnapshotTransactions } from "./snapshot-transaction.js";
16
+ import { ignorePolicyValidator } from "./snapshot-transaction-policy.js";
17
+ import { IGNORE_SNAPSHOT_VERSION, } from "./snapshot-types.js";
11
18
  function sha256(value) {
12
19
  return createHash("sha256").update(value).digest("hex");
13
20
  }
14
21
  function fileHashMap(snapshot) {
15
22
  return Object.fromEntries(snapshot.files.map((file) => [file.path, file.sha256]));
16
23
  }
24
+ function assertSnapshotApplyPolicy(snapshot, options) {
25
+ if (snapshot.version !== IGNORE_SNAPSHOT_VERSION) {
26
+ requireLegacyTransferPolicy(snapshot);
27
+ if (options.ignorePolicy)
28
+ throw new Error("Project the snapshot into the reviewed local ignore-file policy before applying it.");
29
+ return;
30
+ }
31
+ if (options.scope !== "agent-directory" || !options.ignorePolicy)
32
+ requireLegacyTransferPolicy(snapshot);
33
+ if (!sameSnapshotSelection(snapshot.selection, selectionForSnapshot(undefined, undefined, options)))
34
+ throw new Error("Snapshot does not match the local ignore-file policy; review and project it before applying it.");
35
+ }
17
36
  export async function applySnapshot(snapshot, protectedRelativePaths = new Set(), options = {}) {
37
+ assertSnapshotApplyPolicy(snapshot, options);
38
+ const validateIgnorePolicy = ignorePolicyValidator(options);
18
39
  const root = agentDir();
19
- const { sessionDir } = options;
20
- const excluded = compileSyncExclude(options.exclude);
40
+ if (snapshot.version === 5 && options.scope !== "agent-directory")
41
+ throw new Error("Agent-directory snapshot apply requires the local agent-directory policy.");
42
+ const sessionDir = options.scope === "agent-directory"
43
+ ? sessionStorageRoot(root, options.sessionDir ?? (await agentDirectoryConfiguredSessionDir(options.signal, root, options)))
44
+ : options.sessionDir;
45
+ options.validateMutation?.();
46
+ options = { ...options, sessionDir };
47
+ const excluded = excludedApplyPath(root, options);
21
48
  snapshot = { ...snapshot, files: snapshot.files.filter((file) => !excluded(file.path)) };
22
49
  const transactionOptions = {
23
- sessionDir,
24
- exclude: options.exclude,
25
- signal: options.signal,
26
- validateMutation: options.validateMutation,
50
+ ...options,
27
51
  protectedTargets: [...protectedRelativePaths].map((relative) => snapshotTarget(root, relative, sessionDir)),
28
52
  expectedPreimages: new Map(Object.entries(options.expectedFileHashes ?? {})
29
53
  .filter(([relative]) => !excluded(relative))
@@ -33,25 +57,72 @@ export async function applySnapshot(snapshot, protectedRelativePaths = new Set()
33
57
  ])),
34
58
  };
35
59
  options.validateMutation?.();
60
+ if (validateIgnorePolicy)
61
+ await validateIgnorePolicy();
36
62
  await recoverPendingSnapshotTransactions(transactionOptions);
37
63
  const current = await createSnapshot(snapshot.profile, {
38
64
  ...options,
39
- ...(options.include === undefined ? { syncSessions: snapshotIncludesSessions(snapshot) } : {}),
65
+ ...(options.scope === undefined && options.include === undefined
66
+ ? { syncSessions: snapshotIncludesSessions(snapshot) }
67
+ : {}),
40
68
  sessionDir,
41
69
  });
42
- const plan = await addTopLevelCaseVariantDeletes(root, protectSnapshotApplyPlan(root, preflightSnapshotApply(root, snapshot, current, { sessionDir, exclude: options.exclude }), protectedRelativePaths, sessionDir), snapshot);
43
- await preflightSnapshotMutations(root, plan, sessionDir, options);
70
+ const inventory = agentDirectoryInventory(current);
71
+ if (options.reviewedLocal && !sameReviewedFiles(current, options.reviewedLocal))
72
+ throw new Error("Reviewed local files changed before apply; reopen the transfer preview.");
73
+ if (options.scope === "agent-directory") {
74
+ assertAgentDirectorySnapshotBound([
75
+ ...snapshot.files.filter(({ path }) => !protectedRelativePaths.has(path)),
76
+ ...current.files.filter(({ path }) => protectedRelativePaths.has(path)),
77
+ ]);
78
+ }
79
+ const plan = await addTopLevelCaseVariantDeletes(root, protectSnapshotApplyPlan(root, preflightSnapshotApply(root, snapshot, current, options), protectedRelativePaths, sessionDir), snapshot, options);
80
+ if (inventory) {
81
+ assertProjectedAgentDirectoryBudget(inventory, {
82
+ deletes: plan.deletes,
83
+ writes: [
84
+ ...plan.writes.map(({ target, content }) => ({ target, size: content.length })),
85
+ { target: stateDir(root) },
86
+ ],
87
+ }, options);
88
+ await preflightSnapshotMutations(root, plan, sessionDir, options);
89
+ }
90
+ if (options.reviewedLocal || inventory) {
91
+ const images = reviewedSnapshotPreimages(root, sessionDir, current.files, plan, inventory);
92
+ const reviewed = options.reviewedLocal;
93
+ if (reviewed && inventory) {
94
+ const approved = reviewedSnapshotPreimages(root, sessionDir, reviewed.files, plan, agentDirectoryInventory(reviewed));
95
+ if ([...images].some(([target, image]) => image !== approved.get(target)))
96
+ throw new Error("Reviewed directory preimage changed before apply; reopen the transfer preview.");
97
+ }
98
+ for (const [target, image] of images) {
99
+ const existing = transactionOptions.expectedPreimages.get(target);
100
+ if (existing !== undefined && existing !== image)
101
+ throw new Error("Reviewed preimage evidence is inconsistent.");
102
+ transactionOptions.expectedPreimages.set(target, image);
103
+ }
104
+ }
105
+ if (!inventory)
106
+ await preflightSnapshotMutations(root, plan, sessionDir, options);
44
107
  await applySnapshotTransaction(plan, transactionOptions);
45
108
  return appliedFileHashMap(snapshot, current, protectedRelativePaths);
46
109
  }
110
+ function sameReviewedFiles(scanned, reviewed) {
111
+ const hashes = new Map(scanned.files.map((file) => [file.path, file.sha256]));
112
+ return (scanned.files.length === reviewed.files.length &&
113
+ reviewed.files.every((file) => hashes.get(file.path) === file.sha256));
114
+ }
47
115
  export function preflightSnapshotApply(root, snapshot, current, options = {}) {
116
+ assertSnapshotApplyPolicy(snapshot, options);
48
117
  const seenPaths = new Set();
49
118
  const remotePaths = new Set();
50
119
  const writes = [];
51
120
  const deletes = [];
52
- const excluded = compileSyncExclude(options.exclude);
121
+ const excluded = excludedApplyPath(root, options);
53
122
  for (const file of snapshot.files) {
54
123
  const normalized = toPosix(file.path);
124
+ if (options.scope === "agent-directory" && excluded(normalized))
125
+ continue;
55
126
  if (!isSafeSnapshotPath(file.path)) {
56
127
  throw new Error(`Unsafe path in snapshot: ${file.path}`);
57
128
  }
@@ -71,6 +142,11 @@ export function preflightSnapshotApply(root, snapshot, current, options = {}) {
71
142
  writes.push({ target, content });
72
143
  }
73
144
  const deletePaths = new Set();
145
+ const inventory = options.scope === "agent-directory" ? agentDirectoryInventory(current) : undefined;
146
+ for (const { target } of writes) {
147
+ if (inventory?.entries.get(target) === "directory")
148
+ deletePaths.add(target);
149
+ }
74
150
  for (const file of current.files) {
75
151
  const normalized = toPosix(file.path);
76
152
  if (excluded(normalized))
@@ -96,11 +172,14 @@ export function protectSnapshotApplyPlan(root, plan, protectedRelativePaths, ses
96
172
  deletes: plan.deletes.filter((target) => !protectedTargets.has(target)),
97
173
  };
98
174
  }
99
- export async function addTopLevelCaseVariantDeletes(root, plan, snapshot) {
175
+ export async function addTopLevelCaseVariantDeletes(root, plan, snapshot, options = {}) {
176
+ if (options.scope === "agent-directory" || snapshot.selection?.scope === "agent-directory")
177
+ return plan;
178
+ const excluded = compileSyncPolicyExclude(options);
100
179
  const topLevelPaths = new Map();
101
180
  for (const file of snapshot.files) {
102
181
  const normalized = toPosix(file.path);
103
- if (!normalized.includes("/") && isSafeSnapshotPath(file.path)) {
182
+ if (!normalized.includes("/") && isSafeSnapshotPath(file.path) && !excluded(normalized)) {
104
183
  topLevelPaths.set(normalized.toLowerCase(), normalized);
105
184
  }
106
185
  }
@@ -118,7 +197,10 @@ export async function addTopLevelCaseVariantDeletes(root, plan, snapshot) {
118
197
  const deletes = new Set(plan.deletes);
119
198
  for (const entry of entries) {
120
199
  const canonicalPath = topLevelPaths.get(entry.name.toLowerCase());
121
- if (canonicalPath && entry.name !== canonicalPath && (entry.isFile() || entry.isSymbolicLink())) {
200
+ if (canonicalPath &&
201
+ entry.name !== canonicalPath &&
202
+ !excluded(entry.name) &&
203
+ (entry.isFile() || entry.isSymbolicLink())) {
122
204
  deletes.add(safeJoin(root, entry.name));
123
205
  }
124
206
  }
@@ -152,11 +234,13 @@ function isSafeSnapshotPath(relativePath) {
152
234
  path.posix.normalize(normalized) === normalized &&
153
235
  !isDeniedPath(normalized));
154
236
  }
155
- function decodeBase64Strict(value, filePath) {
156
- if (!/^[A-Za-z0-9+/]*={0,2}$/.test(value) || value.length % 4 !== 0) {
157
- throw new Error(`Invalid base64 content in snapshot file: ${filePath}`);
158
- }
159
- return Buffer.from(value, "base64");
237
+ function excludedApplyPath(root, options) {
238
+ const excluded = compileSyncPolicyExclude(options);
239
+ if (options.scope !== "agent-directory")
240
+ return excluded;
241
+ const physicalSessionPath = agentDirectoryPhysicalSessionPath(root, options.sessionDir, options.ignorePolicy, options.reservedIgnoreNames);
242
+ return (relative) => excluded(relative) ||
243
+ (/^sessions(?:\/|$)/iu.test(relative) ? !isSessionFilePath(relative) : physicalSessionPath(relative));
160
244
  }
161
245
  export async function preflightSnapshotMutations(root, plan, sessionDir, options = {}) {
162
246
  assertMutationCurrent(options);
@@ -233,6 +317,8 @@ async function ensureSafeDirectory(root, directory, deletePaths, options) {
233
317
  }
234
318
  }
235
319
  else {
320
+ if (options.scope === "agent-directory")
321
+ return true;
236
322
  await fs.mkdir(current);
237
323
  assertMutationCurrent(options);
238
324
  await syncDirectory(path.dirname(current));
@@ -0,0 +1,4 @@
1
+ import type { SnapshotFile } from "./snapshot-types.js";
2
+ export declare const MAX_AGENT_DIRECTORY_BYTES: number;
3
+ export declare function assertAgentDirectorySettingsSize(bytes: number): void;
4
+ export declare function assertAgentDirectorySnapshotBound(files: readonly SnapshotFile[]): void;
@@ -0,0 +1,20 @@
1
+ import { assertAgentDirectoryPathLayout } from "../sync/sync-policy.js";
2
+ import { snapshotBase64Size } from "./snapshot-payload.js";
3
+ export const MAX_AGENT_DIRECTORY_BYTES = 64 * 1024 * 1024;
4
+ const MAX_AGENT_DIRECTORY_SETTINGS_BYTES = 1024 * 1024;
5
+ export function assertAgentDirectorySettingsSize(bytes) {
6
+ if (bytes > MAX_AGENT_DIRECTORY_SETTINGS_BYTES)
7
+ throw new Error("Pi settings.json exceeds the 1 MiB session metadata byte bound.");
8
+ }
9
+ export function assertAgentDirectorySnapshotBound(files) {
10
+ assertAgentDirectoryPathLayout(files.map((file) => file.path));
11
+ let bytes = 0;
12
+ for (const file of files) {
13
+ const size = snapshotBase64Size(file.contentBase64, file.path);
14
+ if (file.path.toLowerCase() === "settings.json")
15
+ assertAgentDirectorySettingsSize(size);
16
+ bytes += size;
17
+ if (bytes > MAX_AGENT_DIRECTORY_BYTES)
18
+ throw new Error("Projected agent directory exceeds the 64 MiB scan byte bound.");
19
+ }
20
+ }
@@ -1,4 +1,4 @@
1
- import type { Snapshot } from "./snapshot-types.js";
1
+ import { type Snapshot } from "./snapshot-types.js";
2
2
  export declare function encodeSnapshot(snapshot: Snapshot): Promise<NonSharedBuffer>;
3
3
  export declare function decodeSnapshot(buffer: Buffer, options?: {
4
4
  signal?: AbortSignal;
@@ -1,16 +1,21 @@
1
+ import { isUtf8 } from "node:buffer";
1
2
  import { Readable, Writable } from "node:stream";
2
3
  import { pipeline } from "node:stream/promises";
3
4
  import { promisify } from "node:util";
4
5
  import { createGunzip, gzip } from "node:zlib";
5
6
  import { throwIfAborted } from "../sync/signals.js";
6
7
  import { snapshotSelectionInclude, validateSnapshotSelection } from "../sync/sync-policy.js";
8
+ import { IGNORE_SNAPSHOT_VERSION, isSupportedSnapshotVersion } from "./snapshot-types.js";
7
9
  const VERSION = 1;
8
10
  const MAX_DECOMPRESSED_SNAPSHOT_BYTES = 512 * 1024 * 1024;
9
11
  const gzipAsync = promisify(gzip);
10
12
  export async function encodeSnapshot(snapshot) {
11
- snapshotSelectionInclude(snapshot);
13
+ if (!isSupportedSnapshotVersion(snapshot?.version))
14
+ throw new Error("Unsupported snapshot format.");
15
+ if (snapshot.version !== IGNORE_SNAPSHOT_VERSION)
16
+ snapshotSelectionInclude(snapshot);
12
17
  validateSnapshotSelection(snapshot);
13
- if (snapshot.version === 4) {
18
+ if (snapshot.version === 4 || snapshot.version === 5 || snapshot.version === IGNORE_SNAPSHOT_VERSION) {
14
19
  const { validatePortableSnapshot } = await import("../sync/local-fields.js");
15
20
  validatePortableSnapshot(snapshot);
16
21
  }
@@ -34,13 +39,15 @@ export async function decodeSnapshot(buffer, options = {}) {
34
39
  });
35
40
  await pipeline(Readable.from([buffer]), createGunzip(), sink, { signal: options.signal });
36
41
  throwIfAborted(options.signal);
37
- const parsed = JSON.parse(Buffer.concat(chunks, total).toString("utf8"));
38
- if ((parsed.version !== VERSION && parsed.version !== 2 && parsed.version !== 3 && parsed.version !== 4) ||
39
- !Array.isArray(parsed.files)) {
42
+ const payload = Buffer.concat(chunks, total);
43
+ const parsed = JSON.parse(payload.toString("utf8"));
44
+ if (!isSupportedSnapshotVersion(parsed?.version) || !Array.isArray(parsed.files)) {
40
45
  throw new Error("Unsupported snapshot format.");
41
46
  }
47
+ if (parsed.version === IGNORE_SNAPSHOT_VERSION && !isUtf8(payload))
48
+ throw new Error("Invalid snapshot UTF-8.");
42
49
  validateSnapshotSelection(parsed);
43
- if (parsed.version === 2 || parsed.version === 3 || parsed.version === 4) {
50
+ if (parsed.version !== VERSION) {
44
51
  const { normalizeLocalFields, validatePortableSnapshot } = await import("../sync/local-fields.js");
45
52
  validatePortableSnapshot(parsed);
46
53
  if (parsed.localFields !== undefined)
@@ -48,6 +55,7 @@ export async function decodeSnapshot(buffer, options = {}) {
48
55
  }
49
56
  else if (parsed.localFields !== undefined)
50
57
  throw new Error("Portable field policy requires snapshot version 2.");
51
- snapshotSelectionInclude(parsed);
58
+ if (parsed.version !== IGNORE_SNAPSHOT_VERSION)
59
+ snapshotSelectionInclude(parsed);
52
60
  return parsed;
53
61
  }
@@ -0,0 +1,10 @@
1
+ import { type SyncSelectionConfig } from "../sync/sync-policy.js";
2
+ import { type AgentDirectoryScanOptions } from "./snapshot.js";
3
+ import type { AgentDirectoryInventory, SnapshotApplyPlan } from "./snapshot-types.js";
4
+ export declare function recheckAgentDirectoryBudget(root: string, plan: SnapshotApplyPlan, options: AgentDirectoryScanOptions, pendingStateEntry?: string): Promise<void>;
5
+ export declare function assertProjectedAgentDirectoryBudget({ root, sessionRoot, scanSessions, entries, fileSizes, routingDirectories, walkedDirectories, }: AgentDirectoryInventory, plan: Pick<SnapshotApplyPlan, "deletes"> & {
6
+ writes: readonly {
7
+ target: string;
8
+ size?: number;
9
+ }[];
10
+ }, options: SyncSelectionConfig): void;
@@ -0,0 +1,78 @@
1
+ import path from "node:path";
2
+ import { isPathInside, toPosix } from "../paths.js";
3
+ import { compileSyncPolicyTraversal, MAX_AGENT_DIRECTORY_ENTRIES, MAX_AGENT_DIRECTORY_FILES, } from "../sync/sync-policy.js";
4
+ import { scanAgentDirectoryInventory } from "./snapshot.js";
5
+ import { MAX_AGENT_DIRECTORY_BYTES } from "./snapshot-bounds.js";
6
+ export async function recheckAgentDirectoryBudget(root, plan, options, pendingStateEntry) {
7
+ const inventory = await scanAgentDirectoryInventory(root, options, pendingStateEntry);
8
+ options.signal?.throwIfAborted();
9
+ options.validateMutation?.();
10
+ assertProjectedAgentDirectoryBudget(inventory, { deletes: plan.deletes, writes: plan.writes.map(({ target, content }) => ({ target, size: content.length })) }, options);
11
+ }
12
+ export function assertProjectedAgentDirectoryBudget({ root, sessionRoot, scanSessions, entries, fileSizes, routingDirectories, walkedDirectories, }, plan, options) {
13
+ const removed = new Map(plan.deletes.map((target) => [target, true]));
14
+ const isRemoved = (target) => {
15
+ const known = removed.get(target);
16
+ if (known !== undefined)
17
+ return known;
18
+ const parent = path.dirname(target);
19
+ const value = parent !== target && isRemoved(parent);
20
+ removed.set(target, value);
21
+ return value;
22
+ };
23
+ let count = 0;
24
+ const files = new Map(plan.writes.flatMap(({ target, size }) => (size === undefined ? [] : [[target, size]])));
25
+ for (const target of entries.keys()) {
26
+ if (!isRemoved(target)) {
27
+ count++;
28
+ const size = fileSizes.get(target);
29
+ if (size !== undefined && !files.has(target))
30
+ files.set(target, size);
31
+ }
32
+ }
33
+ if (files.size > MAX_AGENT_DIRECTORY_FILES)
34
+ throw new Error("Projected agent directory exceeds the scan file bound.");
35
+ let bytes = 0;
36
+ for (const size of files.values())
37
+ bytes += size;
38
+ if (bytes > MAX_AGENT_DIRECTORY_BYTES)
39
+ throw new Error("Projected agent directory exceeds the 64 MiB scan byte bound.");
40
+ const introduced = new Set();
41
+ for (const { target } of plan.writes) {
42
+ const boundary = isPathInside(root, target) ? root : sessionRoot;
43
+ for (let entry = target; entry !== boundary; entry = path.dirname(entry)) {
44
+ if (introduced.has(entry) || (!isRemoved(entry) && (entries.has(entry) || routingDirectories.has(entry))))
45
+ break;
46
+ introduced.add(entry);
47
+ }
48
+ }
49
+ const canTraverse = compileSyncPolicyTraversal(options);
50
+ const walked = new Map([
51
+ [root, true],
52
+ [sessionRoot, scanSessions],
53
+ ]);
54
+ const willWalk = (directory) => {
55
+ const known = walked.get(directory);
56
+ if (known !== undefined)
57
+ return known;
58
+ let value = false;
59
+ if (!introduced.has(directory))
60
+ value = walkedDirectories.has(directory) && !isRemoved(directory);
61
+ else if (isPathInside(sessionRoot, directory)) {
62
+ value =
63
+ canTraverse(`sessions/${toPosix(path.relative(sessionRoot, directory))}`) && willWalk(path.dirname(directory));
64
+ }
65
+ else if (isPathInside(root, directory)) {
66
+ const relative = toPosix(path.relative(root, directory));
67
+ value = !/^sessions(?:\/|$)/iu.test(relative) && canTraverse(relative) && willWalk(path.dirname(directory));
68
+ }
69
+ walked.set(directory, value);
70
+ return value;
71
+ };
72
+ for (const target of introduced) {
73
+ if (willWalk(path.dirname(target)))
74
+ count++;
75
+ }
76
+ if (count > MAX_AGENT_DIRECTORY_ENTRIES)
77
+ throw new Error("Projected agent directory exceeds the scan entry bound.");
78
+ }
@@ -1,7 +1,14 @@
1
+ import { type SyncSelectionConfig } from "../sync/sync-policy.js";
2
+ import type { DirectoryScope, EffectiveIgnorePolicy } from "./snapshot-types.js";
3
+ export declare function agentDirectoryAnchor(root: string, boundary: string): string;
4
+ export declare function agentDirectorySessionRoot(root: string, sessionDir?: string, ignorePolicy?: EffectiveIgnorePolicy, reservedIgnoreNames?: DirectoryScope["reservedIgnoreNames"]): string;
5
+ export declare function agentDirectoryPhysicalSessionPath(root: string, sessionDir?: string, ignorePolicy?: EffectiveIgnorePolicy, reservedIgnoreNames?: DirectoryScope["reservedIgnoreNames"]): (relativePath: string) => boolean;
6
+ export declare function reservedIgnoreTargetGuard(root: string, options: Pick<DirectoryScope, "reservedIgnoreNames">): ((target: string) => Promise<string>) | undefined;
1
7
  /** Metadata-only preflight: an ancestor replacement must not capture/remove excluded descendants. */
2
- export declare function assertUnexcludedTargets(root: string, targets: Iterable<string>, options: {
3
- exclude?: readonly string[];
8
+ export declare function assertUnexcludedTargets(root: string, targets: Iterable<string>, options: SyncSelectionConfig & {
4
9
  sessionDir?: string;
5
10
  signal?: AbortSignal;
6
11
  validateMutation?: () => void;
12
+ }, { recursive }?: {
13
+ recursive?: boolean;
7
14
  }): Promise<void>;