@narumitw/pi-sync-daemon 0.6.2 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. package/CHANGELOG.md +8 -0
  2. package/README.md +1 -1
  3. package/dist/consent.js +11 -1
  4. package/dist/engine/backends/git/git-storage.js +11 -6
  5. package/dist/engine/paths.js +1 -1
  6. package/dist/engine/settings/config-file.js +2 -0
  7. package/dist/engine/settings/config.d.ts +2 -4
  8. package/dist/engine/settings/config.js +22 -7
  9. package/dist/engine/settings/settings-management.d.ts +2 -2
  10. package/dist/engine/settings/settings-management.js +27 -33
  11. package/dist/engine/settings/settings-types.d.ts +18 -4
  12. package/dist/engine/settings/settings-validation.js +34 -24
  13. package/dist/engine/snapshot/session-paths.d.ts +5 -3
  14. package/dist/engine/snapshot/session-paths.js +55 -9
  15. package/dist/engine/snapshot/snapshot-apply.d.ts +6 -7
  16. package/dist/engine/snapshot/snapshot-apply.js +88 -21
  17. package/dist/engine/snapshot/snapshot-bounds.d.ts +4 -0
  18. package/dist/engine/snapshot/snapshot-bounds.js +20 -0
  19. package/dist/engine/snapshot/snapshot-codec.js +3 -4
  20. package/dist/engine/snapshot/snapshot-entry-projection.d.ts +10 -0
  21. package/dist/engine/snapshot/snapshot-entry-projection.js +78 -0
  22. package/dist/engine/snapshot/snapshot-exclude-safety.d.ts +7 -2
  23. package/dist/engine/snapshot/snapshot-exclude-safety.js +180 -22
  24. package/dist/engine/snapshot/snapshot-payload.d.ts +2 -0
  25. package/dist/engine/snapshot/snapshot-payload.js +10 -0
  26. package/dist/engine/snapshot/snapshot-reviewed-preimages.d.ts +2 -0
  27. package/dist/engine/snapshot/snapshot-reviewed-preimages.js +60 -0
  28. package/dist/engine/snapshot/snapshot-root-transition.d.ts +4 -0
  29. package/dist/engine/snapshot/snapshot-root-transition.js +16 -0
  30. package/dist/engine/snapshot/snapshot-transaction-images.d.ts +37 -0
  31. package/dist/engine/snapshot/snapshot-transaction-images.js +357 -0
  32. package/dist/engine/snapshot/snapshot-transaction-policy.d.ts +50 -0
  33. package/dist/engine/snapshot/snapshot-transaction-policy.js +172 -0
  34. package/dist/engine/snapshot/snapshot-transaction-stage.d.ts +32 -0
  35. package/dist/engine/snapshot/snapshot-transaction-stage.js +303 -0
  36. package/dist/engine/snapshot/snapshot-transaction.d.ts +2 -1
  37. package/dist/engine/snapshot/snapshot-transaction.js +379 -331
  38. package/dist/engine/snapshot/snapshot-types.d.ts +24 -1
  39. package/dist/engine/snapshot/snapshot.d.ts +19 -2
  40. package/dist/engine/snapshot/snapshot.js +283 -26
  41. package/dist/engine/state/merge-baseline-store.js +20 -9
  42. package/dist/engine/state/state-types.d.ts +2 -0
  43. package/dist/engine/sync/apply-review.d.ts +3 -3
  44. package/dist/engine/sync/apply-review.js +5 -4
  45. package/dist/engine/sync/continuous-sync.js +19 -9
  46. package/dist/engine/sync/continuous-watch.d.ts +4 -1
  47. package/dist/engine/sync/continuous-watch.js +86 -14
  48. package/dist/engine/sync/exclude-policy.d.ts +4 -0
  49. package/dist/engine/sync/exclude-policy.js +8 -1
  50. package/dist/engine/sync/initialization.js +9 -5
  51. package/dist/engine/sync/local-fields.js +27 -8
  52. package/dist/engine/sync/merge-apply.js +155 -40
  53. package/dist/engine/sync/merge-journal.js +13 -4
  54. package/dist/engine/sync/merged-sync.js +21 -18
  55. package/dist/engine/sync/partial-progress.js +5 -3
  56. package/dist/engine/sync/remote-snapshot.d.ts +1 -0
  57. package/dist/engine/sync/remote-snapshot.js +8 -5
  58. package/dist/engine/sync/session-push.js +7 -6
  59. package/dist/engine/sync/sync-decision.d.ts +4 -0
  60. package/dist/engine/sync/sync-decision.js +17 -2
  61. package/dist/engine/sync/sync-inspection.js +3 -3
  62. package/dist/engine/sync/sync-mutations.d.ts +8 -1
  63. package/dist/engine/sync/sync-mutations.js +153 -72
  64. package/dist/engine/sync/sync-policy.d.ts +20 -10
  65. package/dist/engine/sync/sync-policy.js +170 -16
  66. package/dist/engine/sync/sync-queries.js +41 -31
  67. package/dist/engine/sync/sync-state.d.ts +11 -0
  68. package/dist/engine/sync/sync-state.js +24 -5
  69. package/dist/engine/ui/sync-format.js +22 -7
  70. package/docs/architecture.md +6 -0
  71. package/package.json +1 -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 } 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;
@@ -32,11 +34,28 @@ export async function configuredSessionDir() {
32
34
  }
33
35
  return settings?.sessionDir ? expandSessionDir(settings.sessionDir) : undefined;
34
36
  }
35
- export async function effectiveSessionRoot(ctx) {
36
- return path.resolve(sessionStorageRoot(agentDir(), sessionDirFromContext(ctx) ?? (await configuredSessionDir())));
37
+ export async function effectiveSessionRoot(ctx, policy, signal) {
38
+ const sessionDir = sessionDirFromContext(ctx);
39
+ if (policy?.scope === "agent-directory") {
40
+ const root = agentDir();
41
+ if (sessionDir !== undefined || ctx.sessionManager.usesDefaultSessionDir?.())
42
+ return agentDirectorySessionRoot(root, sessionDir);
43
+ if (!configuredSnapshotPathMatcher(policy)("settings.json"))
44
+ throw new Error("Pi session storage is unknown and settings.json is excluded. Use an active Pi context to sync.");
45
+ const { agentDirectoryConfiguredSessionDir } = await import("./snapshot.js");
46
+ signal?.throwIfAborted();
47
+ return agentDirectorySessionRoot(root, await agentDirectoryConfiguredSessionDir(signal));
48
+ }
49
+ return path.resolve(sessionStorageRoot(agentDir(), sessionDir ?? (await configuredSessionDir())));
37
50
  }
38
- export async function sessionDirForApply(ctx, snapshot) {
51
+ export async function sessionDirForApply(ctx, snapshot, options = {}) {
39
52
  const contextSessionDir = sessionDirFromContext(ctx);
53
+ if (options.scope === "agent-directory") {
54
+ const root = await effectiveSessionRoot(ctx, options, options.signal);
55
+ if (root !== agentDirectorySessionRoot(agentDir(), options.sessionDir))
56
+ throw new Error("Pi session storage changed during transfer; retry from a fresh review.");
57
+ return root;
58
+ }
40
59
  const localSessionDir = await configuredSessionDir();
41
60
  if (contextSessionDir && path.resolve(contextSessionDir) !== path.resolve(localSessionDir ?? "")) {
42
61
  return contextSessionDir;
@@ -44,15 +63,30 @@ export async function sessionDirForApply(ctx, snapshot) {
44
63
  return sessionDirFromSnapshot(snapshot) ?? contextSessionDir;
45
64
  }
46
65
  /** Hash-only merge plans cannot describe installation into a different session root. */
47
- export function requireStableMergeSessionRoot(before, after) {
66
+ export function requireStableMergeSessionRoot(before, after, scope) {
67
+ const scoped = scope === "agent-directory";
68
+ const settings = (snapshot) => {
69
+ const files = snapshot.files.filter((file) => (scoped ? file.path.toLowerCase() : file.path) === "settings.json");
70
+ if (files.length > 1)
71
+ throw new Error("Multiple Pi settings paths cannot establish a stable session root.");
72
+ return files[0];
73
+ };
74
+ const previous = settings(before);
75
+ const next = settings(after);
76
+ if (scoped && previous?.sha256 === next?.sha256)
77
+ return;
48
78
  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.");
79
+ if (path.resolve(sessionStorageRoot(root, sessionDirFromSettingsFile(previous))) !==
80
+ path.resolve(sessionStorageRoot(root, sessionDirFromSettingsFile(next)))) {
81
+ throw new Error(scoped
82
+ ? "Agent-directory transfer would change Pi session storage. Configure session storage on this machine before syncing."
83
+ : "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
84
  }
53
85
  }
54
86
  function sessionDirFromSnapshot(snapshot) {
55
- const settingsFile = snapshot.files.find((file) => file.path === "settings.json");
87
+ return sessionDirFromSettingsFile(snapshot.files.find((file) => file.path === "settings.json"));
88
+ }
89
+ function sessionDirFromSettingsFile(settingsFile) {
56
90
  if (!settingsFile)
57
91
  return undefined;
58
92
  let settings;
@@ -83,9 +117,21 @@ export function expandSessionDir(value) {
83
117
  return value === "~" || value.startsWith("~/") ? path.join(os.homedir(), value.slice(2)) : value;
84
118
  }
85
119
  export function snapshotOptionsForContext(ctx, config) {
120
+ const defaultScopedSessionDir = config.scope === "agent-directory" && ctx.sessionManager.usesDefaultSessionDir?.()
121
+ ? sessionStorageRoot(agentDir())
122
+ : undefined;
86
123
  return {
87
124
  include: config.include,
125
+ ...(config.scope === undefined ? {} : { scope: config.scope }),
88
126
  ...(config.exclude === undefined ? {} : { exclude: config.exclude }),
89
- sessionDir: sessionDirFromContext(ctx),
127
+ ...(config.reinclude === undefined ? {} : { reinclude: config.reinclude }),
128
+ sessionDir: sessionDirFromContext(ctx) ?? defaultScopedSessionDir,
129
+ };
130
+ }
131
+ export async function resolvedSnapshotOptionsForContext(ctx, config, signal) {
132
+ return {
133
+ ...snapshotOptionsForContext(ctx, config),
134
+ ...(config.scope === "agent-directory" ? { sessionDir: await effectiveSessionRoot(ctx, config, signal) } : {}),
135
+ signal,
90
136
  };
91
137
  }
@@ -1,17 +1,16 @@
1
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<{
2
+ export declare function applySnapshot(snapshot: Snapshot, protectedRelativePaths?: Set<string>, options?: Pick<SnapshotOptions, "include" | "exclude" | "scope" | "reinclude" | "sessionDir" | "syncFiles" | "syncSessions" | "extraFiles" | "signal" | "validateMutation" | "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">;
15
14
  export declare function preflightSnapshotMutations(root: string, plan: {
16
15
  deletes: string[];
17
16
  writes: Array<{
@@ -3,10 +3,15 @@ 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 } 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";
11
16
  function sha256(value) {
12
17
  return createHash("sha256").update(value).digest("hex");
@@ -16,14 +21,17 @@ function fileHashMap(snapshot) {
16
21
  }
17
22
  export async function applySnapshot(snapshot, protectedRelativePaths = new Set(), options = {}) {
18
23
  const root = agentDir();
19
- const { sessionDir } = options;
20
- const excluded = compileSyncExclude(options.exclude);
24
+ if (snapshot.version === 5 && options.scope !== "agent-directory")
25
+ throw new Error("Agent-directory snapshot apply requires the local agent-directory policy.");
26
+ const sessionDir = options.scope === "agent-directory"
27
+ ? sessionStorageRoot(root, options.sessionDir ?? (await agentDirectoryConfiguredSessionDir(options.signal, root)))
28
+ : options.sessionDir;
29
+ options.validateMutation?.();
30
+ options = { ...options, sessionDir };
31
+ const excluded = excludedApplyPath(root, options);
21
32
  snapshot = { ...snapshot, files: snapshot.files.filter((file) => !excluded(file.path)) };
22
33
  const transactionOptions = {
23
- sessionDir,
24
- exclude: options.exclude,
25
- signal: options.signal,
26
- validateMutation: options.validateMutation,
34
+ ...options,
27
35
  protectedTargets: [...protectedRelativePaths].map((relative) => snapshotTarget(root, relative, sessionDir)),
28
36
  expectedPreimages: new Map(Object.entries(options.expectedFileHashes ?? {})
29
37
  .filter(([relative]) => !excluded(relative))
@@ -36,22 +44,66 @@ export async function applySnapshot(snapshot, protectedRelativePaths = new Set()
36
44
  await recoverPendingSnapshotTransactions(transactionOptions);
37
45
  const current = await createSnapshot(snapshot.profile, {
38
46
  ...options,
39
- ...(options.include === undefined ? { syncSessions: snapshotIncludesSessions(snapshot) } : {}),
47
+ ...(options.scope === undefined && options.include === undefined
48
+ ? { syncSessions: snapshotIncludesSessions(snapshot) }
49
+ : {}),
40
50
  sessionDir,
41
51
  });
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);
52
+ const inventory = agentDirectoryInventory(current);
53
+ if (options.reviewedLocal && !sameReviewedFiles(current, options.reviewedLocal))
54
+ throw new Error("Reviewed local files changed before apply; reopen the transfer preview.");
55
+ if (options.scope === "agent-directory") {
56
+ assertAgentDirectorySnapshotBound([
57
+ ...snapshot.files.filter(({ path }) => !protectedRelativePaths.has(path)),
58
+ ...current.files.filter(({ path }) => protectedRelativePaths.has(path)),
59
+ ]);
60
+ }
61
+ const plan = await addTopLevelCaseVariantDeletes(root, protectSnapshotApplyPlan(root, preflightSnapshotApply(root, snapshot, current, options), protectedRelativePaths, sessionDir), snapshot, options);
62
+ if (inventory) {
63
+ assertProjectedAgentDirectoryBudget(inventory, {
64
+ deletes: plan.deletes,
65
+ writes: [
66
+ ...plan.writes.map(({ target, content }) => ({ target, size: content.length })),
67
+ { target: stateDir(root) },
68
+ ],
69
+ }, options);
70
+ await preflightSnapshotMutations(root, plan, sessionDir, options);
71
+ }
72
+ if (options.reviewedLocal || inventory) {
73
+ const images = reviewedSnapshotPreimages(root, sessionDir, current.files, plan, inventory);
74
+ const reviewed = options.reviewedLocal;
75
+ if (reviewed && inventory) {
76
+ const approved = reviewedSnapshotPreimages(root, sessionDir, reviewed.files, plan, agentDirectoryInventory(reviewed));
77
+ if ([...images].some(([target, image]) => image !== approved.get(target)))
78
+ throw new Error("Reviewed directory preimage changed before apply; reopen the transfer preview.");
79
+ }
80
+ for (const [target, image] of images) {
81
+ const existing = transactionOptions.expectedPreimages.get(target);
82
+ if (existing !== undefined && existing !== image)
83
+ throw new Error("Reviewed preimage evidence is inconsistent.");
84
+ transactionOptions.expectedPreimages.set(target, image);
85
+ }
86
+ }
87
+ if (!inventory)
88
+ await preflightSnapshotMutations(root, plan, sessionDir, options);
44
89
  await applySnapshotTransaction(plan, transactionOptions);
45
90
  return appliedFileHashMap(snapshot, current, protectedRelativePaths);
46
91
  }
92
+ function sameReviewedFiles(scanned, reviewed) {
93
+ const hashes = new Map(scanned.files.map((file) => [file.path, file.sha256]));
94
+ return (scanned.files.length === reviewed.files.length &&
95
+ reviewed.files.every((file) => hashes.get(file.path) === file.sha256));
96
+ }
47
97
  export function preflightSnapshotApply(root, snapshot, current, options = {}) {
48
98
  const seenPaths = new Set();
49
99
  const remotePaths = new Set();
50
100
  const writes = [];
51
101
  const deletes = [];
52
- const excluded = compileSyncExclude(options.exclude);
102
+ const excluded = excludedApplyPath(root, options);
53
103
  for (const file of snapshot.files) {
54
104
  const normalized = toPosix(file.path);
105
+ if (options.scope === "agent-directory" && excluded(normalized))
106
+ continue;
55
107
  if (!isSafeSnapshotPath(file.path)) {
56
108
  throw new Error(`Unsafe path in snapshot: ${file.path}`);
57
109
  }
@@ -71,6 +123,11 @@ export function preflightSnapshotApply(root, snapshot, current, options = {}) {
71
123
  writes.push({ target, content });
72
124
  }
73
125
  const deletePaths = new Set();
126
+ const inventory = options.scope === "agent-directory" ? agentDirectoryInventory(current) : undefined;
127
+ for (const { target } of writes) {
128
+ if (inventory?.entries.get(target) === "directory")
129
+ deletePaths.add(target);
130
+ }
74
131
  for (const file of current.files) {
75
132
  const normalized = toPosix(file.path);
76
133
  if (excluded(normalized))
@@ -96,11 +153,14 @@ export function protectSnapshotApplyPlan(root, plan, protectedRelativePaths, ses
96
153
  deletes: plan.deletes.filter((target) => !protectedTargets.has(target)),
97
154
  };
98
155
  }
99
- export async function addTopLevelCaseVariantDeletes(root, plan, snapshot) {
156
+ export async function addTopLevelCaseVariantDeletes(root, plan, snapshot, options = {}) {
157
+ if (options.scope === "agent-directory" || snapshot.selection?.version === 3)
158
+ return plan;
159
+ const excluded = compileSyncPolicyExclude(options);
100
160
  const topLevelPaths = new Map();
101
161
  for (const file of snapshot.files) {
102
162
  const normalized = toPosix(file.path);
103
- if (!normalized.includes("/") && isSafeSnapshotPath(file.path)) {
163
+ if (!normalized.includes("/") && isSafeSnapshotPath(file.path) && !excluded(normalized)) {
104
164
  topLevelPaths.set(normalized.toLowerCase(), normalized);
105
165
  }
106
166
  }
@@ -118,7 +178,10 @@ export async function addTopLevelCaseVariantDeletes(root, plan, snapshot) {
118
178
  const deletes = new Set(plan.deletes);
119
179
  for (const entry of entries) {
120
180
  const canonicalPath = topLevelPaths.get(entry.name.toLowerCase());
121
- if (canonicalPath && entry.name !== canonicalPath && (entry.isFile() || entry.isSymbolicLink())) {
181
+ if (canonicalPath &&
182
+ entry.name !== canonicalPath &&
183
+ !excluded(entry.name) &&
184
+ (entry.isFile() || entry.isSymbolicLink())) {
122
185
  deletes.add(safeJoin(root, entry.name));
123
186
  }
124
187
  }
@@ -152,11 +215,13 @@ function isSafeSnapshotPath(relativePath) {
152
215
  path.posix.normalize(normalized) === normalized &&
153
216
  !isDeniedPath(normalized));
154
217
  }
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");
218
+ function excludedApplyPath(root, options) {
219
+ const excluded = compileSyncPolicyExclude(options);
220
+ if (options.scope !== "agent-directory")
221
+ return excluded;
222
+ const physicalSessionPath = agentDirectoryPhysicalSessionPath(root, options.sessionDir);
223
+ return (relative) => excluded(relative) ||
224
+ (/^sessions(?:\/|$)/iu.test(relative) ? !isSessionFilePath(relative) : physicalSessionPath(relative));
160
225
  }
161
226
  export async function preflightSnapshotMutations(root, plan, sessionDir, options = {}) {
162
227
  assertMutationCurrent(options);
@@ -233,6 +298,8 @@ async function ensureSafeDirectory(root, directory, deletePaths, options) {
233
298
  }
234
299
  }
235
300
  else {
301
+ if (options.scope === "agent-directory")
302
+ return true;
236
303
  await fs.mkdir(current);
237
304
  assertMutationCurrent(options);
238
305
  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
+ }
@@ -10,7 +10,7 @@ const gzipAsync = promisify(gzip);
10
10
  export async function encodeSnapshot(snapshot) {
11
11
  snapshotSelectionInclude(snapshot);
12
12
  validateSnapshotSelection(snapshot);
13
- if (snapshot.version === 4) {
13
+ if (snapshot.version === 4 || snapshot.version === 5) {
14
14
  const { validatePortableSnapshot } = await import("../sync/local-fields.js");
15
15
  validatePortableSnapshot(snapshot);
16
16
  }
@@ -35,12 +35,11 @@ export async function decodeSnapshot(buffer, options = {}) {
35
35
  await pipeline(Readable.from([buffer]), createGunzip(), sink, { signal: options.signal });
36
36
  throwIfAborted(options.signal);
37
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)) {
38
+ if (![VERSION, 2, 3, 4, 5].includes(parsed.version) || !Array.isArray(parsed.files)) {
40
39
  throw new Error("Unsupported snapshot format.");
41
40
  }
42
41
  validateSnapshotSelection(parsed);
43
- if (parsed.version === 2 || parsed.version === 3 || parsed.version === 4) {
42
+ if (parsed.version !== VERSION) {
44
43
  const { normalizeLocalFields, validatePortableSnapshot } = await import("../sync/local-fields.js");
45
44
  validatePortableSnapshot(parsed);
46
45
  if (parsed.localFields !== undefined)
@@ -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,12 @@
1
+ import { type SyncSelectionConfig } from "../sync/sync-policy.js";
2
+ export declare function agentDirectoryAnchor(root: string, boundary: string): string;
3
+ export declare function agentDirectorySessionRoot(root: string, sessionDir?: string): string;
4
+ export declare function agentDirectoryPhysicalSessionPath(root: string, sessionDir?: string): (relativePath: string) => boolean;
1
5
  /** 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[];
6
+ export declare function assertUnexcludedTargets(root: string, targets: Iterable<string>, options: SyncSelectionConfig & {
4
7
  sessionDir?: string;
5
8
  signal?: AbortSignal;
6
9
  validateMutation?: () => void;
10
+ }, { recursive }?: {
11
+ recursive?: boolean;
7
12
  }): Promise<void>;