@narumitw/pi-sync-daemon 0.7.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (93) hide show
  1. package/CHANGELOG.md +21 -0
  2. package/README.md +16 -2
  3. package/dist/cli.js +1 -1
  4. package/dist/consent.d.ts +14 -2
  5. package/dist/consent.js +147 -14
  6. package/dist/engine/backends/git/git-backend.d.ts +2 -3
  7. package/dist/engine/backends/git/git-backend.js +71 -25
  8. package/dist/engine/backends/git/git-storage.d.ts +1 -1
  9. package/dist/engine/backends/git/git-storage.js +30 -9
  10. package/dist/engine/backends/s3/s3-backend.js +8 -0
  11. package/dist/engine/backends/sync-backend.d.ts +1 -0
  12. package/dist/engine/backends/webdav/webdav-backend.js +8 -0
  13. package/dist/engine/commands/command-types.d.ts +2 -1
  14. package/dist/engine/host.d.ts +1 -0
  15. package/dist/engine/ignore/effective-ignore-policy.d.ts +10 -0
  16. package/dist/engine/ignore/effective-ignore-policy.js +33 -0
  17. package/dist/engine/ignore/ignore-edit.d.ts +13 -0
  18. package/dist/engine/ignore/ignore-edit.js +102 -0
  19. package/dist/engine/ignore/ignore-initialization.d.ts +9 -0
  20. package/dist/engine/ignore/ignore-initialization.js +252 -0
  21. package/dist/engine/ignore/ignore-migration-prompt.d.ts +7 -0
  22. package/dist/engine/ignore/ignore-migration-prompt.js +139 -0
  23. package/dist/engine/ignore/ignore-settings.d.ts +30 -0
  24. package/dist/engine/ignore/ignore-settings.js +393 -0
  25. package/dist/engine/ignore/ignore-source.d.ts +27 -0
  26. package/dist/engine/ignore/ignore-source.js +250 -0
  27. package/dist/engine/settings/config-file.d.ts +9 -2
  28. package/dist/engine/settings/config-file.js +124 -28
  29. package/dist/engine/settings/config.d.ts +6 -2
  30. package/dist/engine/settings/config.js +140 -11
  31. package/dist/engine/settings/settings-management.d.ts +5 -3
  32. package/dist/engine/settings/settings-management.js +24 -10
  33. package/dist/engine/settings/settings-types.d.ts +25 -2
  34. package/dist/engine/settings/settings-validation.js +23 -5
  35. package/dist/engine/snapshot/session-paths.d.ts +1 -1
  36. package/dist/engine/snapshot/session-paths.js +41 -13
  37. package/dist/engine/snapshot/snapshot-apply.d.ts +3 -3
  38. package/dist/engine/snapshot/snapshot-apply.js +23 -4
  39. package/dist/engine/snapshot/snapshot-codec.d.ts +1 -1
  40. package/dist/engine/snapshot/snapshot-codec.js +14 -5
  41. package/dist/engine/snapshot/snapshot-exclude-safety.d.ts +4 -2
  42. package/dist/engine/snapshot/snapshot-exclude-safety.js +76 -19
  43. package/dist/engine/snapshot/snapshot-transaction-images.d.ts +3 -1
  44. package/dist/engine/snapshot/snapshot-transaction-images.js +33 -3
  45. package/dist/engine/snapshot/snapshot-transaction-policy.d.ts +30 -2
  46. package/dist/engine/snapshot/snapshot-transaction-policy.js +135 -11
  47. package/dist/engine/snapshot/snapshot-transaction-verification.d.ts +7 -0
  48. package/dist/engine/snapshot/snapshot-transaction-verification.js +78 -0
  49. package/dist/engine/snapshot/snapshot-transaction.d.ts +1 -12
  50. package/dist/engine/snapshot/snapshot-transaction.js +129 -109
  51. package/dist/engine/snapshot/snapshot-types.d.ts +27 -1
  52. package/dist/engine/snapshot/snapshot-types.js +9 -1
  53. package/dist/engine/snapshot/snapshot.d.ts +6 -4
  54. package/dist/engine/snapshot/snapshot.js +91 -34
  55. package/dist/engine/state/state-types.d.ts +1 -0
  56. package/dist/engine/sync/agent-plan.js +1 -0
  57. package/dist/engine/sync/agent-sync.js +8 -1
  58. package/dist/engine/sync/continuous-sync.d.ts +3 -1
  59. package/dist/engine/sync/continuous-sync.js +50 -18
  60. package/dist/engine/sync/continuous-watch.js +4 -1
  61. package/dist/engine/sync/initialization.js +3 -2
  62. package/dist/engine/sync/local-fields.d.ts +3 -1
  63. package/dist/engine/sync/local-fields.js +62 -1
  64. package/dist/engine/sync/merge-acceptance.d.ts +8 -0
  65. package/dist/engine/sync/merge-acceptance.js +29 -0
  66. package/dist/engine/sync/merge-apply.js +42 -11
  67. package/dist/engine/sync/merge-journal.d.ts +24 -4
  68. package/dist/engine/sync/merge-journal.js +134 -8
  69. package/dist/engine/sync/merged-sync.d.ts +1 -1
  70. package/dist/engine/sync/merged-sync.js +128 -83
  71. package/dist/engine/sync/remote-snapshot.d.ts +11 -3
  72. package/dist/engine/sync/remote-snapshot.js +72 -18
  73. package/dist/engine/sync/session-push.js +20 -6
  74. package/dist/engine/sync/sync-inspection.js +7 -5
  75. package/dist/engine/sync/sync-mutations.d.ts +2 -1
  76. package/dist/engine/sync/sync-mutations.js +157 -73
  77. package/dist/engine/sync/sync-policy.d.ts +29 -8
  78. package/dist/engine/sync/sync-policy.js +152 -16
  79. package/dist/engine/sync/sync-queries.js +8 -1
  80. package/dist/engine/sync/sync-state.d.ts +4 -2
  81. package/dist/engine/sync/sync-state.js +15 -2
  82. package/dist/engine/sync/transfer-freshness.d.ts +31 -0
  83. package/dist/engine/sync/transfer-freshness.js +82 -0
  84. package/dist/engine-service.d.ts +1 -1
  85. package/dist/engine-service.js +146 -27
  86. package/dist/monitor.d.ts +4 -1
  87. package/dist/monitor.js +84 -32
  88. package/dist/server.d.ts +1 -0
  89. package/dist/server.js +46 -5
  90. package/dist/service-host.d.ts +1 -1
  91. package/dist/service-host.js +2 -1
  92. package/docs/architecture.md +30 -0
  93. package/package.json +2 -1
@@ -1,4 +1,5 @@
1
1
  import type { ResolvedS3Backend, ResolvedSyncBackend } from "../backends/backend-types.js";
2
+ import type { EffectiveIgnorePolicy, SnapshotOptions } from "../snapshot/snapshot-types.js";
2
3
  export type StorageConnectionType = "s3" | "git" | "webdav";
3
4
  export type OnSwitchAction = "ask-before-pull" | "pull-after-switch" | "switch-only";
4
5
  export interface S3CredentialsSettings {
@@ -59,7 +60,6 @@ export interface WebDavSyncSetupStorageSettings extends CommonSyncSetupStorageSe
59
60
  }
60
61
  export type SyncSetupStorageSettings = S3SyncSetupStorageSettings | GitSyncSetupStorageSettings | WebDavSyncSetupStorageSettings;
61
62
  interface CommonSyncPolicySettings {
62
- exclude?: string[];
63
63
  automatic: boolean;
64
64
  /** Explicit opt-in, separate from the legacy observe/shutdown policy. */
65
65
  automaticTransfer?: boolean;
@@ -76,14 +76,28 @@ interface CommonSyncPolicySettings {
76
76
  }
77
77
  export type SyncPolicySettings = CommonSyncPolicySettings & ({
78
78
  scope?: never;
79
+ pathPolicy?: never;
80
+ ignoreFile?: never;
79
81
  include: string[];
82
+ exclude?: string[];
80
83
  reinclude?: never;
81
84
  sessions?: never;
82
85
  } | {
83
86
  scope: "agent-directory";
87
+ pathPolicy?: never;
88
+ ignoreFile?: never;
84
89
  include?: never;
90
+ exclude?: string[];
85
91
  reinclude?: string[];
86
92
  sessions?: boolean;
93
+ } | {
94
+ scope: "agent-directory";
95
+ pathPolicy: "ignore-file";
96
+ ignoreFile?: string;
97
+ include?: never;
98
+ exclude?: never;
99
+ reinclude?: never;
100
+ sessions?: boolean;
87
101
  });
88
102
  export interface SyncSetupSettings {
89
103
  storage: SyncSetupStorageSettings;
@@ -91,7 +105,7 @@ export interface SyncSetupSettings {
91
105
  [key: string]: unknown;
92
106
  }
93
107
  export interface PiSyncSettingsV3 {
94
- version: 3 | 4 | 5 | 6 | 7;
108
+ version: 3 | 4 | 5 | 6 | 7 | 8;
95
109
  activeSyncSetup?: string;
96
110
  onSwitch: OnSwitchAction;
97
111
  skipSecretScan?: boolean;
@@ -109,6 +123,13 @@ export interface SyncConfig<Backend extends ResolvedSyncBackend = ResolvedS3Back
109
123
  snapshotIdentity: string;
110
124
  include: string[];
111
125
  scope?: "agent-directory";
126
+ pathPolicy?: "ignore-file";
127
+ ignoreFile?: string;
128
+ reservedIgnoreNames?: readonly string[];
129
+ ignorePolicy?: EffectiveIgnorePolicy;
130
+ validateIgnorePolicy?: SnapshotOptions["validateIgnorePolicy"];
131
+ ignoreSourceIdentity?: string;
132
+ configDocumentFingerprint?: string;
112
133
  exclude?: string[];
113
134
  reinclude?: string[];
114
135
  automatic: boolean;
@@ -134,6 +155,8 @@ export interface PartialConfig {
134
155
  storagePath: string;
135
156
  include: string[];
136
157
  scope?: "agent-directory";
158
+ pathPolicy?: "ignore-file";
159
+ ignoreFile?: string;
137
160
  exclude?: string[];
138
161
  reinclude?: string[];
139
162
  automatic: boolean;
@@ -1,6 +1,7 @@
1
1
  import { normalizeEndpointIdentity } from "../backends/backend-identity.js";
2
2
  import { normalizeGitBranch, normalizeGitDirectory, normalizeGitRemote, normalizeGitRemoteIdentity, } from "../backends/git/git-config.js";
3
3
  import { normalizeWebDavIdentityUrl, normalizeWebDavPath, normalizeWebDavUrl, validateWebDavCredentials, } from "../backends/webdav/webdav-config.js";
4
+ import { validateIgnoreFilename } from "../ignore/ignore-source.js";
4
5
  import { normalizeSyncExclude } from "../sync/exclude-policy.js";
5
6
  import { normalizeLocalFields } from "../sync/local-field-policy.js";
6
7
  import { normalizeDirectoryRules, normalizeSyncInclude } from "../sync/sync-policy.js";
@@ -14,8 +15,8 @@ export function normalizeOnSwitch(value) {
14
15
  }
15
16
  export function validateSettingsDocument(value) {
16
17
  const version = value.version;
17
- if (version !== 3 && version !== 4 && version !== 5 && version !== 6 && version !== 7) {
18
- throw new Error(`Unsupported pi-sync settings: version 3, 4, 5, 6 or 7 is required. Keep the existing ${CONFIG_FILE_NAME} for recovery and use a compatible pi-sync client or review a separate supported setup; do not downgrade portable policies. pi-sync will not migrate or overwrite unsupported settings.`);
18
+ if (version !== 3 && version !== 4 && version !== 5 && version !== 6 && version !== 7 && version !== 8) {
19
+ throw new Error(`Unsupported pi-sync settings: version 3 through 8 is required. Keep the existing ${CONFIG_FILE_NAME} for recovery and use a compatible pi-sync client or review a separate supported setup; do not downgrade portable policies. pi-sync will not migrate or overwrite unsupported settings.`);
19
20
  }
20
21
  rejectLegacyFields(value, [
21
22
  "profiles",
@@ -149,7 +150,24 @@ function validateSyncSetup(name, value, connections, version) {
149
150
  }
150
151
  }
151
152
  const localFields = normalizeLocalFields(sync.localFields);
152
- if (Object.hasOwn(sync, "scope")) {
153
+ if (Object.hasOwn(sync, "pathPolicy")) {
154
+ if (sync.pathPolicy !== "ignore-file")
155
+ throw new Error("Invalid pi-sync settings: unsupported sync.pathPolicy.");
156
+ if (version < 8)
157
+ throw new Error("sync.pathPolicy requires explicit settings version 8.");
158
+ if (!Object.hasOwn(sync, "scope") || sync.scope !== "agent-directory")
159
+ throw new Error("Invalid pi-sync settings: sync.pathPolicy requires agent-directory scope.");
160
+ for (const key of ["include", "exclude", "reinclude"]) {
161
+ if (Object.hasOwn(sync, key))
162
+ throw new Error(`Invalid pi-sync settings: ignore-file policy cannot use sync.${key}.`);
163
+ }
164
+ if (Object.hasOwn(sync, "ignoreFile"))
165
+ validateIgnoreFilename(sync.ignoreFile);
166
+ }
167
+ else if (Object.hasOwn(sync, "ignoreFile")) {
168
+ throw new Error("Invalid pi-sync settings: sync.ignoreFile requires ignore-file pathPolicy.");
169
+ }
170
+ else if (Object.hasOwn(sync, "scope")) {
153
171
  if (sync.scope !== "agent-directory")
154
172
  throw new Error("Invalid pi-sync settings: unsupported sync.scope.");
155
173
  if (version < 7)
@@ -158,8 +176,6 @@ function validateSyncSetup(name, value, connections, version) {
158
176
  throw new Error("Invalid pi-sync settings: agent-directory scope cannot use sync.include.");
159
177
  normalizeDirectoryRules(sync.exclude);
160
178
  normalizeDirectoryRules(sync.reinclude);
161
- if (sync.sessions !== undefined && typeof sync.sessions !== "boolean")
162
- throw new Error("Invalid pi-sync settings: sync.sessions must be boolean.");
163
179
  }
164
180
  else {
165
181
  if (Object.hasOwn(sync, "sessions") || Object.hasOwn(sync, "reinclude"))
@@ -171,6 +187,8 @@ function validateSyncSetup(name, value, connections, version) {
171
187
  if (localFields.length > 0 && !include.includes("settings.json"))
172
188
  throw new Error("Nonempty localFields requires settings.json in sync.include.");
173
189
  }
190
+ if (sync.sessions !== undefined && typeof sync.sessions !== "boolean")
191
+ throw new Error("Invalid pi-sync settings: sync.sessions must be boolean.");
174
192
  if (sync.localFields !== undefined && version < 4)
175
193
  throw new Error("localFields requires explicit settings version 4; older binaries must refuse portable state.");
176
194
  if (sync.exclude !== undefined && version < 6)
@@ -3,7 +3,7 @@ import type { AnySyncConfig } from "../settings/settings-types.js";
3
3
  import { type SyncSelectionConfig } from "../sync/sync-policy.js";
4
4
  import type { Snapshot, SnapshotOptions } from "./snapshot-types.js";
5
5
  export declare function sessionDirFromContext(ctx: ExtensionCommandContext | ExtensionContext): string | undefined;
6
- export declare function configuredSessionDir(): Promise<string | undefined>;
6
+ export declare function configuredSessionDir(options?: Pick<SnapshotOptions, "reservedIgnoreNames" | "signal">): Promise<string | undefined>;
7
7
  export declare function effectiveSessionRoot(ctx: ExtensionCommandContext | ExtensionContext, policy?: SyncSelectionConfig, signal?: AbortSignal): Promise<string>;
8
8
  export declare function sessionDirForApply(ctx: ExtensionCommandContext | ExtensionContext, snapshot: Snapshot, options?: SnapshotOptions): Promise<string | undefined>;
9
9
  /** Hash-only merge plans cannot describe installation into a different session root. */
@@ -1,9 +1,10 @@
1
1
  import fs from "node:fs/promises";
2
2
  import os from "node:os";
3
3
  import path from "node:path";
4
+ import { backendIdentityCoordinates } from "../backends/backend-identity.js";
4
5
  import { getEngineRoot as getAgentDir, } from "../host.js";
5
6
  import { configuredSnapshotPathMatcher } from "../sync/sync-policy.js";
6
- import { agentDirectorySessionRoot } from "./snapshot-exclude-safety.js";
7
+ import { agentDirectorySessionRoot, reservedIgnoreTargetGuard } from "./snapshot-exclude-safety.js";
7
8
  import { sessionStorageRoot } from "./snapshot-paths.js";
8
9
  export function sessionDirFromContext(ctx) {
9
10
  const manager = ctx.sessionManager;
@@ -14,10 +15,19 @@ export function sessionDirFromContext(ctx) {
14
15
  const getSessionDir = manager.getSessionDir;
15
16
  return typeof getSessionDir === "function" ? getSessionDir.call(manager) : undefined;
16
17
  }
17
- export async function configuredSessionDir() {
18
+ export async function configuredSessionDir(options = {}) {
19
+ const root = agentDir();
20
+ const target = path.join(root, "settings.json");
21
+ const guardReserved = reservedIgnoreTargetGuard(root, options);
18
22
  let content;
19
23
  try {
20
- content = await fs.readFile(path.join(agentDir(), "settings.json"), "utf8");
24
+ if (guardReserved) {
25
+ const { readLegacySnapshotSource } = await import("./snapshot.js");
26
+ content = (await readLegacySnapshotSource(target, guardReserved, options.signal)).toString("utf8");
27
+ }
28
+ else {
29
+ content = await fs.readFile(target, "utf8");
30
+ }
21
31
  }
22
32
  catch (error) {
23
33
  if (error.code === "ENOENT")
@@ -36,31 +46,41 @@ export async function configuredSessionDir() {
36
46
  }
37
47
  export async function effectiveSessionRoot(ctx, policy, signal) {
38
48
  const sessionDir = sessionDirFromContext(ctx);
49
+ const root = agentDir();
39
50
  if (policy?.scope === "agent-directory") {
40
- const root = agentDir();
41
51
  if (sessionDir !== undefined || ctx.sessionManager.usesDefaultSessionDir?.())
42
- return agentDirectorySessionRoot(root, sessionDir);
52
+ return agentDirectorySessionRoot(root, sessionDir, policy.ignorePolicy, policy.reservedIgnoreNames);
43
53
  if (!configuredSnapshotPathMatcher(policy)("settings.json"))
44
54
  throw new Error("Pi session storage is unknown and settings.json is excluded. Use an active Pi context to sync.");
45
55
  const { agentDirectoryConfiguredSessionDir } = await import("./snapshot.js");
46
56
  signal?.throwIfAborted();
47
- return agentDirectorySessionRoot(root, await agentDirectoryConfiguredSessionDir(signal));
57
+ const configured = await agentDirectoryConfiguredSessionDir(signal, root, policy);
58
+ return agentDirectorySessionRoot(root, configured, policy.ignorePolicy, policy.reservedIgnoreNames);
48
59
  }
49
- return path.resolve(sessionStorageRoot(agentDir(), sessionDir ?? (await configuredSessionDir())));
60
+ const resolved = sessionStorageRoot(root, sessionDir ?? (await configuredSessionDir({ ...policy, signal })));
61
+ const guardReserved = reservedIgnoreTargetGuard(root, policy ?? {});
62
+ if (guardReserved)
63
+ await guardReserved(resolved);
64
+ return resolved;
50
65
  }
51
66
  export async function sessionDirForApply(ctx, snapshot, options = {}) {
52
67
  const contextSessionDir = sessionDirFromContext(ctx);
53
68
  if (options.scope === "agent-directory") {
54
69
  const root = await effectiveSessionRoot(ctx, options, options.signal);
55
- if (root !== agentDirectorySessionRoot(agentDir(), options.sessionDir))
70
+ if (root !==
71
+ agentDirectorySessionRoot(agentDir(), options.sessionDir, options.ignorePolicy, options.reservedIgnoreNames))
56
72
  throw new Error("Pi session storage changed during transfer; retry from a fresh review.");
57
73
  return root;
58
74
  }
59
- const localSessionDir = await configuredSessionDir();
60
- if (contextSessionDir && path.resolve(contextSessionDir) !== path.resolve(localSessionDir ?? "")) {
61
- return contextSessionDir;
62
- }
63
- return sessionDirFromSnapshot(snapshot) ?? contextSessionDir;
75
+ const localSessionDir = await configuredSessionDir(options);
76
+ const sessionDir = contextSessionDir && path.resolve(contextSessionDir) !== path.resolve(localSessionDir ?? "")
77
+ ? contextSessionDir
78
+ : (sessionDirFromSnapshot(snapshot) ?? contextSessionDir);
79
+ const root = agentDir();
80
+ const guardReserved = reservedIgnoreTargetGuard(root, options);
81
+ if (guardReserved)
82
+ await guardReserved(sessionStorageRoot(root, sessionDir));
83
+ return sessionDir;
64
84
  }
65
85
  /** Hash-only merge plans cannot describe installation into a different session root. */
66
86
  export function requireStableMergeSessionRoot(before, after, scope) {
@@ -123,8 +143,16 @@ export function snapshotOptionsForContext(ctx, config) {
123
143
  return {
124
144
  include: config.include,
125
145
  ...(config.scope === undefined ? {} : { scope: config.scope }),
146
+ ...(config.setupName === undefined ? {} : { setupName: config.setupName }),
147
+ ...(config.backend && (config.ignorePolicy || config.reservedIgnoreNames !== undefined)
148
+ ? { recoverySetupKey: JSON.stringify([backendIdentityCoordinates(config), config.localFields]) }
149
+ : {}),
150
+ ...(config.ignorePolicy ? { ignorePolicy: config.ignorePolicy } : {}),
151
+ ...(config.ignoreSourceIdentity === undefined ? {} : { ignoreSourceIdentity: config.ignoreSourceIdentity }),
152
+ ...(config.validateIgnorePolicy === undefined ? {} : { validateIgnorePolicy: config.validateIgnorePolicy }),
126
153
  ...(config.exclude === undefined ? {} : { exclude: config.exclude }),
127
154
  ...(config.reinclude === undefined ? {} : { reinclude: config.reinclude }),
155
+ ...(config.reservedIgnoreNames === undefined ? {} : { reservedIgnoreNames: config.reservedIgnoreNames }),
128
156
  sessionDir: sessionDirFromContext(ctx) ?? defaultScopedSessionDir,
129
157
  };
130
158
  }
@@ -1,5 +1,5 @@
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" | "scope" | "reinclude" | "sessionDir" | "syncFiles" | "syncSessions" | "extraFiles" | "signal" | "validateMutation" | "expectedFileHashes"> & {
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" | "setupName" | "recoverySetupKey" | "ignoreSourceIdentity" | "sessionDir" | "syncFiles" | "syncSessions" | "extraFiles" | "signal" | "validateMutation" | "validateIgnorePolicy" | "validateApplyReview" | "expectedFileHashes"> & {
3
3
  reviewedLocal?: Pick<Snapshot, "files">;
4
4
  }): Promise<{
5
5
  [k: string]: string;
@@ -10,7 +10,7 @@ export declare function addTopLevelCaseVariantDeletes(root: string, plan: Snapsh
10
10
  export declare function appliedFileHashMap(snapshot: Snapshot, current: Snapshot, protectedRelativePaths: Set<string>): {
11
11
  [k: string]: string;
12
12
  };
13
- type MutationGuards = Pick<SnapshotOptions, "signal" | "validateMutation" | "exclude" | "scope" | "include" | "reinclude">;
13
+ type MutationGuards = Pick<SnapshotOptions, "signal" | "validateMutation" | "exclude" | "scope" | "include" | "reinclude" | "ignorePolicy" | "reservedIgnoreNames">;
14
14
  export declare function preflightSnapshotMutations(root: string, plan: {
15
15
  deletes: string[];
16
16
  writes: Array<{
@@ -4,7 +4,7 @@ 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
6
  import { stateDir } from "../state/state-directory.js";
7
- import { compileSyncPolicyExclude } from "../sync/sync-policy.js";
7
+ import { compileSyncPolicyExclude, requireLegacyTransferPolicy, sameSnapshotSelection, selectionForSnapshot, } from "../sync/sync-policy.js";
8
8
  import { agentDir } from "./session-paths.js";
9
9
  import { agentDirectoryConfiguredSessionDir, agentDirectoryInventory, createSnapshot, isSessionFilePath, isSessionPath, sessionStorageRoot, snapshotIncludesSessions, snapshotTarget, } from "./snapshot.js";
10
10
  import { assertAgentDirectorySnapshotBound } from "./snapshot-bounds.js";
@@ -13,18 +13,34 @@ import { agentDirectoryPhysicalSessionPath, assertUnexcludedTargets } from "./sn
13
13
  import { decodeBase64Strict } from "./snapshot-payload.js";
14
14
  import { reviewedSnapshotPreimages } from "./snapshot-reviewed-preimages.js";
15
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";
16
18
  function sha256(value) {
17
19
  return createHash("sha256").update(value).digest("hex");
18
20
  }
19
21
  function fileHashMap(snapshot) {
20
22
  return Object.fromEntries(snapshot.files.map((file) => [file.path, file.sha256]));
21
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
+ }
22
36
  export async function applySnapshot(snapshot, protectedRelativePaths = new Set(), options = {}) {
37
+ assertSnapshotApplyPolicy(snapshot, options);
38
+ const validateIgnorePolicy = ignorePolicyValidator(options);
23
39
  const root = agentDir();
24
40
  if (snapshot.version === 5 && options.scope !== "agent-directory")
25
41
  throw new Error("Agent-directory snapshot apply requires the local agent-directory policy.");
26
42
  const sessionDir = options.scope === "agent-directory"
27
- ? sessionStorageRoot(root, options.sessionDir ?? (await agentDirectoryConfiguredSessionDir(options.signal, root)))
43
+ ? sessionStorageRoot(root, options.sessionDir ?? (await agentDirectoryConfiguredSessionDir(options.signal, root, options)))
28
44
  : options.sessionDir;
29
45
  options.validateMutation?.();
30
46
  options = { ...options, sessionDir };
@@ -41,6 +57,8 @@ export async function applySnapshot(snapshot, protectedRelativePaths = new Set()
41
57
  ])),
42
58
  };
43
59
  options.validateMutation?.();
60
+ if (validateIgnorePolicy)
61
+ await validateIgnorePolicy();
44
62
  await recoverPendingSnapshotTransactions(transactionOptions);
45
63
  const current = await createSnapshot(snapshot.profile, {
46
64
  ...options,
@@ -95,6 +113,7 @@ function sameReviewedFiles(scanned, reviewed) {
95
113
  reviewed.files.every((file) => hashes.get(file.path) === file.sha256));
96
114
  }
97
115
  export function preflightSnapshotApply(root, snapshot, current, options = {}) {
116
+ assertSnapshotApplyPolicy(snapshot, options);
98
117
  const seenPaths = new Set();
99
118
  const remotePaths = new Set();
100
119
  const writes = [];
@@ -154,7 +173,7 @@ export function protectSnapshotApplyPlan(root, plan, protectedRelativePaths, ses
154
173
  };
155
174
  }
156
175
  export async function addTopLevelCaseVariantDeletes(root, plan, snapshot, options = {}) {
157
- if (options.scope === "agent-directory" || snapshot.selection?.version === 3)
176
+ if (options.scope === "agent-directory" || snapshot.selection?.scope === "agent-directory")
158
177
  return plan;
159
178
  const excluded = compileSyncPolicyExclude(options);
160
179
  const topLevelPaths = new Map();
@@ -219,7 +238,7 @@ function excludedApplyPath(root, options) {
219
238
  const excluded = compileSyncPolicyExclude(options);
220
239
  if (options.scope !== "agent-directory")
221
240
  return excluded;
222
- const physicalSessionPath = agentDirectoryPhysicalSessionPath(root, options.sessionDir);
241
+ const physicalSessionPath = agentDirectoryPhysicalSessionPath(root, options.sessionDir, options.ignorePolicy, options.reservedIgnoreNames);
223
242
  return (relative) => excluded(relative) ||
224
243
  (/^sessions(?:\/|$)/iu.test(relative) ? !isSessionFilePath(relative) : physicalSessionPath(relative));
225
244
  }
@@ -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 || snapshot.version === 5) {
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,10 +39,13 @@ 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 (![VERSION, 2, 3, 4, 5].includes(parsed.version) || !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)) {
39
45
  throw new Error("Unsupported snapshot format.");
40
46
  }
47
+ if (parsed.version === IGNORE_SNAPSHOT_VERSION && !isUtf8(payload))
48
+ throw new Error("Invalid snapshot UTF-8.");
41
49
  validateSnapshotSelection(parsed);
42
50
  if (parsed.version !== VERSION) {
43
51
  const { normalizeLocalFields, validatePortableSnapshot } = await import("../sync/local-fields.js");
@@ -47,6 +55,7 @@ export async function decodeSnapshot(buffer, options = {}) {
47
55
  }
48
56
  else if (parsed.localFields !== undefined)
49
57
  throw new Error("Portable field policy requires snapshot version 2.");
50
- snapshotSelectionInclude(parsed);
58
+ if (parsed.version !== IGNORE_SNAPSHOT_VERSION)
59
+ snapshotSelectionInclude(parsed);
51
60
  return parsed;
52
61
  }
@@ -1,7 +1,9 @@
1
1
  import { type SyncSelectionConfig } from "../sync/sync-policy.js";
2
+ import type { DirectoryScope, EffectiveIgnorePolicy } from "./snapshot-types.js";
2
3
  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;
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;
5
7
  /** Metadata-only preflight: an ancestor replacement must not capture/remove excluded descendants. */
6
8
  export declare function assertUnexcludedTargets(root: string, targets: Iterable<string>, options: SyncSelectionConfig & {
7
9
  sessionDir?: string;
@@ -3,7 +3,7 @@ import fs from "node:fs/promises";
3
3
  import path from "node:path";
4
4
  import { isPathInside, toPosix } from "../paths.js";
5
5
  import { mergePathIdentity } from "../sync/file-merge-planner.js";
6
- import { compileSyncPolicyExclude, compileSyncPolicyTraversal, configuredSnapshotPathMatcher, } from "../sync/sync-policy.js";
6
+ import { compileSyncPolicyExclude, compileSyncPolicyTraversal, configuredSnapshotPathMatcher, isIgnoreControlPath, } from "../sync/sync-policy.js";
7
7
  import { sessionStorageRoot } from "./snapshot-paths.js";
8
8
  function directoryStat(absolute) {
9
9
  try {
@@ -56,31 +56,75 @@ export function agentDirectoryAnchor(root, boundary) {
56
56
  }
57
57
  return anchor;
58
58
  }
59
- export function agentDirectorySessionRoot(root, sessionDir) {
59
+ export function agentDirectorySessionRoot(root, sessionDir, ignorePolicy, reservedIgnoreNames) {
60
60
  const sessionRoot = sessionStorageRoot(root, sessionDir);
61
61
  if (physicalRelative(sessionRoot, root) !== undefined)
62
62
  throw new Error("Pi session storage overlaps the agent directory root.");
63
63
  const relative = physicalRelative(root, sessionRoot);
64
64
  if (relative !== undefined) {
65
+ const logical = toPosix(relative);
65
66
  const canTraverse = compileSyncPolicyTraversal({ scope: "agent-directory", include: ["sessions"] });
66
- if (!canTraverse(toPosix(relative)))
67
+ const reserved = ignorePolicy || reservedIgnoreNames
68
+ ? new Set([
69
+ ...(ignorePolicy ? [ignorePolicy.filename, ...ignorePolicy.reservedNames] : []),
70
+ ...(reservedIgnoreNames ?? []),
71
+ ].map((name) => name.toLowerCase()))
72
+ : undefined;
73
+ if (!canTraverse(logical) || (reserved && isIgnoreControlPath(logical, reserved)))
67
74
  throw new Error("Pi session storage overlaps protected agent files.");
68
75
  }
69
76
  return sessionRoot;
70
77
  }
71
- export function agentDirectoryPhysicalSessionPath(root, sessionDir) {
72
- const sessionRoot = agentDirectorySessionRoot(root, sessionDir);
78
+ export function agentDirectoryPhysicalSessionPath(root, sessionDir, ignorePolicy, reservedIgnoreNames) {
79
+ const sessionRoot = agentDirectorySessionRoot(root, sessionDir, ignorePolicy, reservedIgnoreNames);
73
80
  const nested = physicalRelative(root, sessionRoot) !== undefined;
74
81
  return (relativePath) => nested && physicalRelative(sessionRoot, path.resolve(root, relativePath)) !== undefined;
75
82
  }
83
+ async function realpathWithMissingTail(target) {
84
+ let ancestor = path.resolve(target);
85
+ for (;;) {
86
+ try {
87
+ const resolved = await fs.realpath(ancestor);
88
+ return path.resolve(resolved, path.relative(ancestor, target));
89
+ }
90
+ catch (error) {
91
+ const code = error.code;
92
+ const parent = path.dirname(ancestor);
93
+ if (parent === ancestor || (code !== "ENOENT" && code !== "ENOTDIR"))
94
+ throw error;
95
+ ancestor = parent;
96
+ }
97
+ }
98
+ }
99
+ export function reservedIgnoreTargetGuard(root, options) {
100
+ if (options.reservedIgnoreNames === undefined)
101
+ return undefined;
102
+ const reserved = new Set(options.reservedIgnoreNames);
103
+ function check(agentRoot, target) {
104
+ const relative = physicalRelative(agentRoot, target);
105
+ if (physicalRelative(target, agentRoot) !== undefined ||
106
+ (relative !== undefined && isIgnoreControlPath(toPosix(relative), reserved)))
107
+ throw new Error("Transfer would access a protected ignore rule path or its ancestor.");
108
+ }
109
+ return async (target) => {
110
+ check(root, target);
111
+ const canonicalRoot = await realpathWithMissingTail(root);
112
+ const canonicalTarget = await realpathWithMissingTail(target);
113
+ check(canonicalRoot, canonicalTarget);
114
+ return canonicalTarget;
115
+ };
116
+ }
76
117
  /** Metadata-only preflight: an ancestor replacement must not capture/remove excluded descendants. */
77
118
  export async function assertUnexcludedTargets(root, targets, options, { recursive = true } = {}) {
78
119
  const wholeDirectory = options.scope === "agent-directory";
79
- if (!wholeDirectory && (options.exclude === undefined || (Array.isArray(options.exclude) && !options.exclude.length)))
120
+ const guardReserved = reservedIgnoreTargetGuard(root, options);
121
+ if (!wholeDirectory &&
122
+ !guardReserved &&
123
+ (options.exclude === undefined || (Array.isArray(options.exclude) && !options.exclude.length)))
80
124
  return;
81
125
  const excluded = compileSyncPolicyExclude(options);
82
126
  const sessionRoot = wholeDirectory
83
- ? agentDirectorySessionRoot(root, options.sessionDir)
127
+ ? agentDirectorySessionRoot(root, options.sessionDir, options.ignorePolicy, options.reservedIgnoreNames)
84
128
  : sessionStorageRoot(root, options.sessionDir);
85
129
  const configured = configuredSnapshotPathMatcher(options);
86
130
  let visited = 0;
@@ -93,11 +137,16 @@ export async function assertUnexcludedTargets(root, targets, options, { recursiv
93
137
  if (++visited > 16_384)
94
138
  throw new Error("Exclude safety preflight exceeds its path bound; review a smaller transfer.");
95
139
  };
96
- const refuse = () => {
140
+ function refuse() {
97
141
  throw new Error("Transfer would replace an excluded path or directory descendant; no replacement is authorized.");
98
- };
142
+ }
99
143
  async function visit(target) {
100
144
  validate();
145
+ if (guardReserved) {
146
+ await guardReserved(target);
147
+ validate();
148
+ }
149
+ let logicalPath;
101
150
  let sessionPath;
102
151
  if (wholeDirectory) {
103
152
  if (physicalRelative(target, sessionRoot) !== undefined)
@@ -105,14 +154,16 @@ export async function assertUnexcludedTargets(root, targets, options, { recursiv
105
154
  const sessionRelative = physicalRelative(sessionRoot, target);
106
155
  if (sessionRelative !== undefined) {
107
156
  sessionPath = `sessions/${toPosix(sessionRelative)}`;
108
- if (excluded(sessionPath))
109
- refuse();
157
+ logicalPath = sessionPath;
110
158
  }
111
159
  else {
112
160
  const relative = physicalRelative(root, target);
113
- if (relative === undefined || /^sessions(?:\/|$)/iu.test(toPosix(relative)) || excluded(toPosix(relative)))
161
+ if (!relative || /^sessions(?:\/|$)/iu.test(toPosix(relative)))
114
162
  refuse();
163
+ logicalPath = toPosix(relative);
115
164
  }
165
+ if (!options.ignorePolicy && excluded(logicalPath))
166
+ refuse();
116
167
  }
117
168
  else {
118
169
  const candidates = [];
@@ -120,22 +171,28 @@ export async function assertUnexcludedTargets(root, targets, options, { recursiv
120
171
  candidates.push(toPosix(path.relative(root, target)));
121
172
  if (isPathInside(sessionRoot, target))
122
173
  candidates.push(`sessions/${toPosix(path.relative(sessionRoot, target))}`);
123
- if (candidates.some(excluded))
174
+ if (candidates.some((candidate) => excluded(candidate)))
124
175
  refuse();
125
176
  }
126
- let stat;
177
+ let observed;
127
178
  try {
128
- stat = await fs.lstat(target);
179
+ observed = await fs.lstat(target);
129
180
  }
130
181
  catch (error) {
131
- validate();
132
182
  const code = error.code;
133
- if (code !== "ENOENT" && code !== "ENOTDIR")
183
+ if (code !== "ENOENT" && code !== "ENOTDIR") {
184
+ validate();
134
185
  throw error;
135
- return;
186
+ }
136
187
  }
137
188
  validate();
138
- if (wholeDirectory && !stat.isDirectory() && (!stat.isFile() || stat.nlink !== 1)) {
189
+ if (options.ignorePolicy && logicalPath !== undefined && excluded(logicalPath, observed?.isDirectory()))
190
+ refuse();
191
+ if (!observed)
192
+ return;
193
+ const stat = observed;
194
+ if ((wholeDirectory && !stat.isDirectory() && (!stat.isFile() || stat.nlink !== 1)) ||
195
+ (guardReserved && stat.isFile() && stat.nlink !== 1)) {
139
196
  throw new Error("Refusing an unsafe symlink, hard link, or special file during snapshot mutation.");
140
197
  }
141
198
  if (sessionPath && stat.isFile() && !configured(sessionPath))
@@ -23,13 +23,15 @@ export type ScopedImage = {
23
23
  } | ScopedNode;
24
24
  export declare function scopedPathIdentity(target: string, guards: Guards): Promise<string>;
25
25
  export declare function scopedIdentity(stat: BigIntStats): string;
26
+ export declare function installedVacancyIdentityMatches(image: ScopedImage, expected: string): boolean;
26
27
  export declare function stableScopedIdentity(target: string, stat: BigIntStats): string;
27
28
  export declare function readTransactionJournal(file: string, guards: Guards, maxBytes?: number): Promise<string | undefined>;
28
29
  export declare function scopedTransactionImage(target: string, guards: Guards, copyTo?: string, checkPath?: (source: string) => Promise<void>, beforeCopyFile?: (handle: FileHandle) => Promise<void>): Promise<ScopedImage>;
29
30
  export declare function ownedScopedSubset(image: ScopedImage, expected: ScopedImage): boolean;
30
31
  export declare function matchesScopedFilePrefix(source: string, original: ScopedImage, partial: ScopedImage, guards: Guards): Promise<boolean>;
31
32
  export declare function scopedDescendant(image: ScopedImage, relative: string): ScopedImage | undefined;
32
- export declare function removeScopedImage(target: string, image: ScopedImage, guards: Guards): Promise<void>;
33
+ export declare function recheckScopedImage(target: string, image: ScopedImage, guards: Guards): Promise<void>;
34
+ export declare function removeScopedImage(target: string, image: ScopedImage, guards: Guards, validateIgnorePolicy?: () => Promise<void>): Promise<void>;
33
35
  export declare function legacyImage(target: string, durable?: boolean): Promise<string>;
34
36
  type PostFiles = NonNullable<TransactionEntry["postFiles"]>;
35
37
  export declare function ownedScopedPostTree(image: ScopedImage, files: PostFiles, requireComplete: boolean): boolean;