@narumitw/pi-sync-daemon 0.9.1 → 0.10.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 +11 -0
  2. package/README.md +11 -1
  3. package/dist/cli.js +2 -0
  4. package/dist/client-transport.d.ts +14 -0
  5. package/dist/client-transport.js +66 -0
  6. package/dist/client.d.ts +15 -8
  7. package/dist/client.js +116 -86
  8. package/dist/consent.js +33 -11
  9. package/dist/daemon-debug.d.ts +3 -0
  10. package/dist/daemon-debug.js +33 -0
  11. package/dist/daemon-recovery.d.ts +4 -0
  12. package/dist/daemon-recovery.js +75 -0
  13. package/dist/engine/backends/git/git-backend.d.ts +8 -0
  14. package/dist/engine/backends/git/git-backend.js +39 -12
  15. package/dist/engine/backends/git/git-runner.js +6 -1
  16. package/dist/engine/backends/git/git-storage.js +5 -9
  17. package/dist/engine/backends/publication-encoding.d.ts +3 -0
  18. package/dist/engine/backends/publication-encoding.js +19 -0
  19. package/dist/engine/backends/s3/s3-backend.js +10 -12
  20. package/dist/engine/backends/sync-backend.d.ts +4 -0
  21. package/dist/engine/backends/webdav/webdav-backend.d.ts +0 -2
  22. package/dist/engine/backends/webdav/webdav-backend.js +15 -26
  23. package/dist/engine/backends/webdav/webdav-client.js +10 -0
  24. package/dist/engine/commands/command-types.d.ts +1 -0
  25. package/dist/engine/debug-log.d.ts +27 -0
  26. package/dist/engine/debug-log.js +134 -0
  27. package/dist/engine/paths.d.ts +2 -0
  28. package/dist/engine/paths.js +7 -1
  29. package/dist/engine/settings/config-file.d.ts +10 -1
  30. package/dist/engine/settings/config-file.js +62 -17
  31. package/dist/engine/settings/config.d.ts +7 -0
  32. package/dist/engine/settings/config.js +49 -14
  33. package/dist/engine/snapshot/snapshot-apply.d.ts +2 -1
  34. package/dist/engine/snapshot/snapshot-apply.js +30 -8
  35. package/dist/engine/snapshot/snapshot-codec.js +3 -1
  36. package/dist/engine/snapshot/snapshot-payload.d.ts +4 -0
  37. package/dist/engine/snapshot/snapshot-payload.js +32 -0
  38. package/dist/engine/snapshot/snapshot-transaction-images.d.ts +2 -0
  39. package/dist/engine/snapshot/snapshot-transaction-images.js +34 -0
  40. package/dist/engine/snapshot/snapshot-transaction.d.ts +4 -1
  41. package/dist/engine/snapshot/snapshot-transaction.js +50 -7
  42. package/dist/engine/snapshot/snapshot-types.d.ts +10 -2
  43. package/dist/engine/snapshot/snapshot.d.ts +3 -1
  44. package/dist/engine/snapshot/snapshot.js +64 -25
  45. package/dist/engine/state/lock.d.ts +2 -1
  46. package/dist/engine/state/lock.js +157 -17
  47. package/dist/engine/sync/continuous-sync.d.ts +10 -1
  48. package/dist/engine/sync/continuous-sync.js +35 -11
  49. package/dist/engine/sync/initialization.d.ts +1 -1
  50. package/dist/engine/sync/initialization.js +2 -2
  51. package/dist/engine/sync/local-fields.d.ts +6 -1
  52. package/dist/engine/sync/local-fields.js +42 -19
  53. package/dist/engine/sync/merged-sync.js +13 -10
  54. package/dist/engine/sync/remote-snapshot.js +18 -3
  55. package/dist/engine/sync/session-push.js +13 -4
  56. package/dist/engine/sync/startup-bootstrap.d.ts +1 -0
  57. package/dist/engine/sync/startup-bootstrap.js +105 -0
  58. package/dist/engine/sync/startup-recovery-evidence.d.ts +1 -0
  59. package/dist/engine/sync/startup-recovery-evidence.js +37 -0
  60. package/dist/engine/sync/startup-timings.d.ts +9 -2
  61. package/dist/engine/sync/startup-timings.js +80 -8
  62. package/dist/engine/sync/sync-error-guidance.js +6 -1
  63. package/dist/engine/sync/sync-inspection.js +4 -7
  64. package/dist/engine/sync/sync-local.d.ts +2 -1
  65. package/dist/engine/sync/sync-local.js +3 -1
  66. package/dist/engine/sync/sync-mutations.js +9 -3
  67. package/dist/engine/sync/sync-policy.d.ts +2 -0
  68. package/dist/engine/sync/sync-policy.js +9 -1
  69. package/dist/engine/sync/sync-state.d.ts +8 -3
  70. package/dist/engine/sync/sync-state.js +12 -4
  71. package/dist/engine-service.d.ts +6 -0
  72. package/dist/engine-service.js +54 -10
  73. package/dist/identity.d.ts +5 -2
  74. package/dist/identity.js +36 -6
  75. package/dist/index.d.ts +2 -1
  76. package/dist/index.js +2 -1
  77. package/dist/monitor.js +20 -1
  78. package/dist/paged-review.d.ts +35 -0
  79. package/dist/paged-review.js +177 -0
  80. package/dist/participant-ledger.d.ts +16 -0
  81. package/dist/participant-ledger.js +149 -0
  82. package/dist/protocol.d.ts +15 -0
  83. package/dist/protocol.js +4 -0
  84. package/dist/server.d.ts +7 -0
  85. package/dist/server.js +268 -120
  86. package/dist/service-host.d.ts +2 -1
  87. package/dist/service-host.js +29 -9
  88. package/dist/state-wait-jobs.d.ts +8 -0
  89. package/dist/state-wait-jobs.js +23 -0
  90. package/dist/state-wait.d.ts +7 -0
  91. package/dist/state-wait.js +34 -0
  92. package/docs/architecture.md +22 -0
  93. package/package.json +1 -1
@@ -1,3 +1,35 @@
1
+ import { createHash } from "node:crypto";
2
+ const checked = new WeakMap();
3
+ function checkPayload(file, message, materialize = false) {
4
+ const { contentBase64, sha256 } = file;
5
+ if (typeof contentBase64 !== "string" || typeof sha256 !== "string")
6
+ throw new Error(message);
7
+ const cacheable = Object.getOwnPropertyDescriptor(file, "contentBase64")?.value === contentBase64 &&
8
+ Object.getOwnPropertyDescriptor(file, "sha256")?.value === sha256;
9
+ const previous = cacheable ? checked.get(file) : undefined;
10
+ if (previous?.contentBase64 === contentBase64 && previous.sha256 === sha256)
11
+ return materialize ? Buffer.from(contentBase64, "base64") : undefined;
12
+ const content = Buffer.from(contentBase64, "base64");
13
+ if (content.toString("base64") !== contentBase64 || createHash("sha256").update(content).digest("hex") !== sha256)
14
+ throw new Error(message);
15
+ if (cacheable)
16
+ checked.set(file, { contentBase64, sha256 });
17
+ return content;
18
+ }
19
+ export function assertSnapshotFilePayload(file, message) {
20
+ checkPayload(file, message);
21
+ }
22
+ export function materializeSnapshotFilePayload(file, message) {
23
+ return checkPayload(file, message, true);
24
+ }
25
+ export function snapshotFileFromBlob(path, content, sha256, message) {
26
+ if (createHash("sha256").update(content).digest("hex") !== sha256)
27
+ throw new Error(message);
28
+ const contentBase64 = content.toString("base64");
29
+ const file = { path, contentBase64, sha256 };
30
+ checked.set(file, { contentBase64, sha256 });
31
+ return file;
32
+ }
1
33
  export function snapshotBase64Size(value, filePath) {
2
34
  if (typeof value !== "string" || value.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}(?![\s\S])/u.test(value))
3
35
  throw new Error(`Invalid base64 content in snapshot file: ${filePath}`);
@@ -25,6 +25,8 @@ export declare function scopedPathIdentity(target: string, guards: Guards): Prom
25
25
  export declare function scopedIdentity(stat: BigIntStats): string;
26
26
  export declare function installedVacancyIdentityMatches(image: ScopedImage, expected: string): boolean;
27
27
  export declare function stableScopedIdentity(target: string, stat: BigIntStats): string;
28
+ export declare function verifyUnchangedFile(target: string, content: Buffer, guards: Guards): Promise<BigIntStats>;
29
+ export declare function recheckUnchangedFile(target: string, stat: BigIntStats, guards: Guards): Promise<void>;
28
30
  export declare function readTransactionJournal(file: string, guards: Guards, maxBytes?: number): Promise<string | undefined>;
29
31
  export declare function scopedTransactionImage(target: string, guards: Guards, copyTo?: string, checkPath?: (source: string) => Promise<void>, beforeCopyFile?: (handle: FileHandle) => Promise<void>): Promise<ScopedImage>;
30
32
  export declare function ownedScopedSubset(image: ScopedImage, expected: ScopedImage): boolean;
@@ -125,6 +125,40 @@ async function readStableFile(target, original, guards, consume) {
125
125
  }
126
126
  await recheck(target, original, guards);
127
127
  }
128
+ export async function verifyUnchangedFile(target, content, guards) {
129
+ const stat = await lstat(target, guards);
130
+ if (!stat?.isFile() || stat.nlink !== 1n || stat.size !== BigInt(content.length))
131
+ skippedPreimageChanged();
132
+ await recheckUnchangedFile(target, stat, guards);
133
+ await readStableFile(target, stat, guards, (chunk, offset) => {
134
+ if (!chunk.equals(content.subarray(offset, offset + chunk.length)))
135
+ skippedPreimageChanged();
136
+ });
137
+ return stat;
138
+ }
139
+ export async function recheckUnchangedFile(target, stat, guards) {
140
+ validate(guards);
141
+ let canonical;
142
+ try {
143
+ canonical = await fs.realpath(target);
144
+ }
145
+ catch (error) {
146
+ validate(guards);
147
+ const code = error.code;
148
+ if (code === "ENOENT" || code === "ENOTDIR")
149
+ skippedPreimageChanged();
150
+ throw error;
151
+ }
152
+ validate(guards);
153
+ if (canonical !== target)
154
+ skippedPreimageChanged();
155
+ const current = await lstat(target, guards);
156
+ if (!current || !sameObservation(stat, current))
157
+ skippedPreimageChanged();
158
+ }
159
+ function skippedPreimageChanged() {
160
+ throw new Error("Skipped file preimage changed before apply; snapshot installation refused.");
161
+ }
128
162
  export async function readTransactionJournal(file, guards, maxBytes = MAX_TRANSACTION_JOURNAL_BYTES) {
129
163
  const stat = await lstat(file, guards);
130
164
  if (!stat)
@@ -1,5 +1,8 @@
1
1
  import { type TransactionOptions } from "./snapshot-transaction-policy.js";
2
2
  import type { SnapshotApplyPlan } from "./snapshot-types.js";
3
- export declare function applySnapshotTransaction(plan: SnapshotApplyPlan, options?: TransactionOptions): Promise<void>;
3
+ export type SkippedSnapshotWrite = SnapshotApplyPlan["writes"][number] & {
4
+ preimage: string;
5
+ };
6
+ export declare function applySnapshotTransaction(plan: SnapshotApplyPlan, options?: TransactionOptions, skipped?: readonly SkippedSnapshotWrite[]): Promise<void>;
4
7
  export declare function recoverSnapshotTransactionsOnStartup(options?: TransactionOptions): Promise<void>;
5
8
  export declare function recoverPendingSnapshotTransactions(options?: TransactionOptions): Promise<void>;
@@ -9,15 +9,15 @@ import { normalizeSyncExclude } from "../sync/exclude-policy.js";
9
9
  import { mergePathIdentity } from "../sync/file-merge-planner.js";
10
10
  import { includeFromSelectionConfig, selectionForSnapshot } from "../sync/sync-policy.js";
11
11
  import { agentDir, configuredSessionDir } from "./session-paths.js";
12
- import { agentDirectoryConfiguredSessionDir } from "./snapshot.js";
12
+ import { agentDirectoryConfiguredSessionDir, scanAgentDirectoryInventory } from "./snapshot.js";
13
13
  import { caseReplacementSpelling, coalesceCaseReplacements } from "./snapshot-case-replacement.js";
14
- import { recheckAgentDirectoryBudget } from "./snapshot-entry-projection.js";
14
+ import { assertProjectedAgentDirectoryBudget, recheckAgentDirectoryBudget } from "./snapshot-entry-projection.js";
15
15
  import { assertUnexcludedTargets } from "./snapshot-exclude-safety.js";
16
16
  import { withMissingTargetQueues, withTargetQueues } from "./snapshot-mutation-queues.js";
17
17
  import { sessionStorageRoot } from "./snapshot-paths.js";
18
18
  import { prepareSessionRootTransition, resolveTransitionSessionRoot, stableAgentDirectorySettingsImage, } from "./snapshot-root-transition.js";
19
19
  import { pendingTransactionEntries, transactionRoot } from "./snapshot-transaction-directory.js";
20
- import { legacyImage, MAX_TRANSACTION_JOURNAL_BYTES, ownedScopedPostTree, readTransactionJournal, recheckScopedImage, removeScopedImage, scopedDescendant, scopedIdentity, scopedPathIdentity, scopedTransactionImage, stableScopedIdentity, } from "./snapshot-transaction-images.js";
20
+ import { legacyImage, MAX_TRANSACTION_JOURNAL_BYTES, ownedScopedPostTree, readTransactionJournal, recheckScopedImage, recheckUnchangedFile, removeScopedImage, scopedDescendant, scopedIdentity, scopedPathIdentity, scopedTransactionImage, stableScopedIdentity, verifyUnchangedFile, } from "./snapshot-transaction-images.js";
21
21
  import { indexTransactionPlan } from "./snapshot-transaction-plan.js";
22
22
  import { AGENT_DIRECTORY_JOURNAL_VERSION, assertAllowedTarget, assertRecoveryPolicy, assertSafeParents, BOUND_DIRECTORY_JOURNAL_VERSION, BOUND_INCLUDED_PATHS_JOURNAL_VERSION, IGNORE_POLICY_JOURNAL_VERSION, ignorePolicyValidator, ignoreSourceBinding, isScopedJournal, isStrictlyInside, recoveryPolicyKey, StaleIgnorePolicyError, touchesProtectedTarget, transactionHasSessionTargets, validateJournal, validateJournalPolicy, } from "./snapshot-transaction-policy.js";
23
23
  import { assertNoUnclaimedLegacyStage, buildScopedRecoveryStage, cleanScopedLegacyStage, cleanScopedWorkspace, inspectScopedRecoveryStage, prepareLegacyRecoveryStage, recoveryStagePath, } from "./snapshot-transaction-stage.js";
@@ -25,7 +25,7 @@ import { verifyTarget } from "./snapshot-transaction-verification.js";
25
25
  const JOURNAL_VERSION = 4;
26
26
  class ScopedRemovalError extends Error {
27
27
  }
28
- export async function applySnapshotTransaction(plan, options = {}) {
28
+ export async function applySnapshotTransaction(plan, options = {}, skipped = []) {
29
29
  options.validateMutation?.();
30
30
  const root = path.resolve(agentDir());
31
31
  if (options.scope === "agent-directory") {
@@ -90,7 +90,10 @@ export async function applySnapshotTransaction(plan, options = {}) {
90
90
  expectedPreimages.set(target, evidence.image);
91
91
  }
92
92
  }
93
+ const skippedPreimages = new Map(skipped.map(({ target, preimage }) => [target, preimage]));
93
94
  for (const [target, expected] of expectedPreimages) {
95
+ if (skippedPreimages.get(target) === expected)
96
+ continue;
94
97
  if (scoped || options.reservedIgnoreNames?.length)
95
98
  await assertUnexcludedTargets(root, [target], options);
96
99
  const current = scoped ? (await scopedTransactionImage(target, options)).value : await legacyImage(target);
@@ -101,7 +104,29 @@ export async function applySnapshotTransaction(plan, options = {}) {
101
104
  }
102
105
  if (validateIgnorePolicy)
103
106
  await validateIgnorePolicy();
104
- const transaction = await prepareTransaction(coalesced.plan, targets, { ...options, expectedPreimages }, coalesced.replacements);
107
+ const mutationTargets = skipped.length ? targets.filter((target) => !skippedPreimages.has(target)) : targets;
108
+ const writes = skipped.length ? plan.writes.filter(({ target }) => !skippedPreimages.has(target)) : plan.writes;
109
+ if (mutationTargets.length === 0) {
110
+ if (options.validateApplyReview)
111
+ await options.validateApplyReview();
112
+ if (scoped) {
113
+ const pendingStateEntry = stateDir(root);
114
+ const inventory = await scanAgentDirectoryInventory(root, options, pendingStateEntry);
115
+ options.validateMutation?.();
116
+ options.signal?.throwIfAborted();
117
+ assertProjectedAgentDirectoryBudget(inventory, { deletes: [], writes: [{ target: pendingStateEntry }] }, options);
118
+ }
119
+ if (validateIgnorePolicy)
120
+ await validateIgnorePolicy();
121
+ await verifySkippedWrites(root, skipped, heldKeys, options);
122
+ options.validateMutation?.();
123
+ options.signal?.throwIfAborted();
124
+ return;
125
+ }
126
+ const mutationPlan = skipped.length
127
+ ? { ...coalesced.plan, writes: coalesced.plan.writes.filter(({ target }) => !skippedPreimages.has(target)) }
128
+ : coalesced.plan;
129
+ const transaction = await prepareTransaction(mutationPlan, mutationTargets, { ...options, expectedPreimages }, coalesced.replacements);
105
130
  const entriesByTarget = new Map(transaction.journal.entries.flatMap((entry) => [
106
131
  [entry.target, entry],
107
132
  ...(entry.afterTarget ? [[entry.afterTarget, entry]] : []),
@@ -135,7 +160,7 @@ export async function applySnapshotTransaction(plan, options = {}) {
135
160
  await retireRemovalIntent(transaction.directory, transaction.journal, transaction.journal.entries.filter((entry) => entry.removalPending && (entry.afterImage !== "missing" || (entry.postFiles?.length ?? 0) > 0)), options);
136
161
  // Only this uninterrupted call knows which deleted writes have not attempted installation yet.
137
162
  const uninstalledWrites = new Set(transaction.deletedWrites);
138
- for (const item of plan.writes) {
163
+ for (const item of writes) {
139
164
  options.signal?.throwIfAborted();
140
165
  const entry = entriesByTarget.get(item.target);
141
166
  if (!entry)
@@ -194,7 +219,7 @@ export async function applySnapshotTransaction(plan, options = {}) {
194
219
  }
195
220
  options.validateMutation?.();
196
221
  options.signal?.throwIfAborted();
197
- await syncMutationParents(targets, [transaction.journal.root, ...(transaction.journal.sessionRoot ? [transaction.journal.sessionRoot] : [])], options);
222
+ await syncMutationParents(mutationTargets, [transaction.journal.root, ...(transaction.journal.sessionRoot ? [transaction.journal.sessionRoot] : [])], options);
198
223
  options.validateMutation?.();
199
224
  options.signal?.throwIfAborted();
200
225
  if (validateIgnorePolicy)
@@ -202,6 +227,9 @@ export async function applySnapshotTransaction(plan, options = {}) {
202
227
  });
203
228
  if (validateIgnorePolicy)
204
229
  await validateIgnorePolicy();
230
+ await verifySkippedWrites(root, skipped, heldKeys, options);
231
+ options.validateMutation?.();
232
+ options.signal?.throwIfAborted();
205
233
  }
206
234
  catch (error) {
207
235
  // Aborted owners cannot roll back files after another session has replaced them.
@@ -226,6 +254,21 @@ export async function applySnapshotTransaction(plan, options = {}) {
226
254
  await completeTransaction(transaction.directory, transaction.journal);
227
255
  });
228
256
  }
257
+ async function verifySkippedWrites(root, skipped, heldKeys, options) {
258
+ if (!skipped.length)
259
+ return;
260
+ await assertUnexcludedTargets(root, skipped.map(({ target }) => target), options, { recursive: false });
261
+ const sessionRoot = options.sessionDir ? sessionStorageRoot(root, options.sessionDir) : undefined;
262
+ const verified = [];
263
+ for (const { target, content } of skipped) {
264
+ if (!heldKeys.has(target) || touchesProtectedTarget(target, options.protectedTargets))
265
+ throw new Error("Skipped file lost its transaction queue or session protection changed; review is required.");
266
+ await assertSafeParents(root, sessionRoot, target);
267
+ verified.push({ target, stat: await verifyUnchangedFile(target, content, options) });
268
+ }
269
+ for (const { target, stat } of verified)
270
+ await recheckUnchangedFile(target, stat, options);
271
+ }
229
272
  export async function recoverSnapshotTransactionsOnStartup(options = {}) {
230
273
  if (!(await pendingTransactionEntries()).some((entry) => entry.isDirectory()))
231
274
  return;
@@ -1,8 +1,16 @@
1
- export interface SnapshotFile {
1
+ export interface SnapshotFileHash {
2
2
  path: string;
3
- contentBase64: string;
4
3
  sha256: string;
5
4
  }
5
+ export interface SnapshotFile extends SnapshotFileHash {
6
+ contentBase64: string;
7
+ }
8
+ export interface SnapshotObservation {
9
+ scope: DirectoryScope["scope"];
10
+ files: Array<SnapshotFileHash & {
11
+ settingsContent?: Buffer;
12
+ }>;
13
+ }
6
14
  export interface EffectiveIgnorePolicy {
7
15
  filename: string;
8
16
  sourceDigest: string;
@@ -2,10 +2,12 @@ import { reservedIgnoreTargetGuard } from "./snapshot-exclude-safety.js";
2
2
  export { isDeniedPath } from "../paths.js";
3
3
  export { sessionStorageRoot } from "./snapshot-paths.js";
4
4
  import { type SyncSelectionConfig } from "../sync/sync-policy.js";
5
- import { type AgentDirectoryInventory, type Snapshot, type SnapshotFile, type SnapshotOptions } from "./snapshot-types.js";
5
+ import { type AgentDirectoryInventory, type Snapshot, type SnapshotFile, type SnapshotObservation, type SnapshotOptions } from "./snapshot-types.js";
6
6
  export { canonicalSnapshotPathForConfig, isConfiguredSnapshotPath } from "../sync/sync-policy.js";
7
7
  export declare function agentDirectoryInventory(snapshot: Pick<Snapshot, "files">): AgentDirectoryInventory | undefined;
8
8
  export declare function regenerateSnapshotIdentity(snapshot: Snapshot): Snapshot;
9
+ export declare function observeSnapshot(options?: SnapshotOptions, retainSettings?: boolean): Promise<SnapshotObservation>;
10
+ export declare function snapshotWithObservedInventory(snapshot: Snapshot, observation: SnapshotObservation): Snapshot | undefined;
9
11
  export declare function createSnapshot(profile: string, options?: SnapshotOptions): Promise<Snapshot>;
10
12
  export declare function collectFiles(root: string, options?: SnapshotOptions, excluded?: (relativePath: string, directory?: boolean) => boolean): Promise<SnapshotFile[]>;
11
13
  export declare function agentDirectoryConfiguredSessionDir(signal?: AbortSignal, root?: string, options?: Pick<SnapshotOptions, "reservedIgnoreNames">): Promise<string | undefined>;
@@ -71,7 +71,11 @@ export function regenerateSnapshotIdentity(snapshot) {
71
71
  machine: os.hostname(),
72
72
  };
73
73
  }
74
- export async function createSnapshot(profile, options = {}) {
74
+ const SCAN_FILE_BATCH_SIZE = 8;
75
+ function materializeSnapshotFile(filePath, content) {
76
+ return { path: filePath, contentBase64: content.toString("base64"), sha256: sha256(content) };
77
+ }
78
+ async function collectSnapshotFiles(options, materialize) {
75
79
  options.signal?.throwIfAborted();
76
80
  const include = effectiveInclude(options);
77
81
  const policy = { ...options, include };
@@ -83,8 +87,39 @@ export async function createSnapshot(profile, options = {}) {
83
87
  : (options.sessionDir ?? (needsSessionConfig ? await configuredSessionDir(options) : undefined));
84
88
  options.signal?.throwIfAborted();
85
89
  const collectionOptions = { ...policy, sessionDir };
86
- const collected = options.scope === "agent-directory" ? await collectAgentDirectory(agentDir(), collectionOptions) : undefined;
87
- const files = collected?.files ?? (await collectFiles(agentDir(), collectionOptions, excluded));
90
+ const collected = options.scope === "agent-directory"
91
+ ? await collectAgentDirectory(agentDir(), collectionOptions, materialize)
92
+ : undefined;
93
+ const files = collected?.files ?? (await collectSelectedFiles(agentDir(), collectionOptions, excluded, materialize));
94
+ options.signal?.throwIfAborted();
95
+ return { files, inventory: collected?.inventory, include, syncSessions };
96
+ }
97
+ export async function observeSnapshot(options = {}, retainSettings = false) {
98
+ const { files, inventory } = await collectSnapshotFiles(options, (filePath, content) => ({
99
+ path: filePath,
100
+ sha256: sha256(content),
101
+ ...(retainSettings && filePath === "settings.json" ? { settingsContent: content } : {}),
102
+ }));
103
+ options.signal?.throwIfAborted();
104
+ const observation = { files, scope: options.scope };
105
+ if (inventory)
106
+ scanInventories.set(observation, inventory);
107
+ return observation;
108
+ }
109
+ export function snapshotWithObservedInventory(snapshot, observation) {
110
+ if (snapshot.selection?.scope !== observation.scope ||
111
+ snapshot.files.length !== observation.files.length ||
112
+ observation.files.some((file, index) => file.path !== snapshot.files[index]?.path || file.sha256 !== snapshot.files[index]?.sha256))
113
+ return undefined;
114
+ const inventory = scanInventories.get(observation);
115
+ if (!inventory)
116
+ return observation.scope === undefined ? snapshot : undefined;
117
+ const refreshed = { ...snapshot };
118
+ scanInventories.set(refreshed, inventory);
119
+ return refreshed;
120
+ }
121
+ export async function createSnapshot(profile, options = {}) {
122
+ const { files, inventory, include, syncSessions } = await collectSnapshotFiles(options, materializeSnapshotFile);
88
123
  options.signal?.throwIfAborted();
89
124
  const selection = selectionForSnapshot(include, options.exclude, options);
90
125
  const snapshot = {
@@ -103,8 +138,8 @@ export async function createSnapshot(profile, options = {}) {
103
138
  selection,
104
139
  files,
105
140
  };
106
- if (collected)
107
- scanInventories.set(snapshot, collected.inventory);
141
+ if (inventory)
142
+ scanInventories.set(snapshot, inventory);
108
143
  return snapshot;
109
144
  }
110
145
  function effectiveInclude(options) {
@@ -120,10 +155,13 @@ function effectiveInclude(options) {
120
155
  }
121
156
  export async function collectFiles(root, options = {}, excluded = compileSyncPolicyExclude(options)) {
122
157
  if (options.scope === "agent-directory")
123
- return (await collectAgentDirectory(root, options)).files;
158
+ return (await collectAgentDirectory(root, options, materializeSnapshotFile)).files;
159
+ return collectSelectedFiles(root, options, excluded, materializeSnapshotFile);
160
+ }
161
+ async function collectSelectedFiles(root, options, excluded, materialize) {
124
162
  const signal = options.signal;
125
163
  const guardReserved = reservedIgnoreTargetGuard(root, options);
126
- const collection = { signal, excluded, guardReserved };
164
+ const collection = { signal, excluded, guardReserved, materialize };
127
165
  signal?.throwIfAborted();
128
166
  const results = [];
129
167
  const entries = await fs.readdir(root, { withFileTypes: true });
@@ -189,6 +227,16 @@ async function recheck({ absolute, canonical, stat }, signal) {
189
227
  if (!sameScannedPath((await identify(absolute, canonical, signal)).stat, stat))
190
228
  changedScan();
191
229
  }
230
+ async function forEachScannedFile(files, signal, run) {
231
+ for (let offset = 0; offset < files.length; offset += SCAN_FILE_BATCH_SIZE) {
232
+ signal?.throwIfAborted();
233
+ const settled = await Promise.allSettled(files.slice(offset, offset + SCAN_FILE_BATCH_SIZE).map((file, index) => run(file, index + offset)));
234
+ signal?.throwIfAborted();
235
+ for (const result of settled)
236
+ if (result.status === "rejected")
237
+ throw result.reason;
238
+ }
239
+ }
192
240
  async function readScannedFile(candidate, signal) {
193
241
  await recheck(candidate, signal);
194
242
  const handle = await fs.open(candidate.absolute, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
@@ -254,9 +302,9 @@ export function agentDirectorySessionDirFromSettings(content) {
254
302
  return value ? expandSessionDir(value) : undefined;
255
303
  }
256
304
  export async function scanAgentDirectoryInventory(root, options, pendingStateEntry) {
257
- return (await collectAgentDirectory(root, options, false, pendingStateEntry)).inventory;
305
+ return (await collectAgentDirectory(root, options, undefined, pendingStateEntry)).inventory;
258
306
  }
259
- async function collectAgentDirectory(root, options, readContents = true, pendingStateEntry) {
307
+ async function collectAgentDirectory(root, options, materialize, pendingStateEntry) {
260
308
  const signal = options.signal;
261
309
  const excluded = compileSyncPolicyExclude(options);
262
310
  const canTraverse = compileSyncPolicyTraversal(options);
@@ -347,15 +395,11 @@ async function collectAgentDirectory(root, options, readContents = true, pending
347
395
  await walk(sessionDirectory, "sessions", true);
348
396
  assertAgentDirectoryPathLayout(candidates.map((candidate) => candidate.snapshotPath));
349
397
  const results = [];
350
- if (readContents) {
351
- for (const candidate of candidates) {
398
+ if (materialize) {
399
+ await forEachScannedFile(candidates, signal, async (candidate, index) => {
352
400
  const content = await readScannedFile(candidate, signal);
353
- results.push({
354
- path: candidate.snapshotPath,
355
- contentBase64: content.toString("base64"),
356
- sha256: sha256(content),
357
- });
358
- }
401
+ results[index] = materialize(candidate.snapshotPath, content);
402
+ });
359
403
  }
360
404
  for (const directory of directories)
361
405
  await recheck(directory, signal);
@@ -369,8 +413,7 @@ async function collectAgentDirectory(root, options, readContents = true, pending
369
413
  (sessionDirectory.stat.dev !== currentSessionDirectory.stat.dev ||
370
414
  sessionDirectory.stat.ino !== currentSessionDirectory.stat.ino)))
371
415
  changedScan();
372
- for (const candidate of candidates)
373
- await recheck(candidate, signal);
416
+ await forEachScannedFile(candidates, signal, (candidate) => recheck(candidate, signal));
374
417
  signal?.throwIfAborted();
375
418
  return {
376
419
  files: results.sort((left, right) => left.path.localeCompare(right.path)),
@@ -439,18 +482,14 @@ export async function readLegacySnapshotSource(absolutePath, guardReserved, sign
439
482
  changedScan();
440
483
  return readScannedFile(candidate, signal);
441
484
  }
442
- async function addFile(results, root, relativePath, snapshotPath, { signal, guardReserved }) {
485
+ async function addFile(results, root, relativePath, snapshotPath, { signal, guardReserved, materialize }) {
443
486
  signal?.throwIfAborted();
444
487
  if (!isSafeSnapshotPath(snapshotPath))
445
488
  return;
446
489
  const absolutePath = safeJoin(root, relativePath);
447
490
  const content = await readLegacySnapshotSource(absolutePath, guardReserved, signal);
448
491
  signal?.throwIfAborted();
449
- results.push({
450
- path: snapshotPath,
451
- contentBase64: content.toString("base64"),
452
- sha256: sha256(content),
453
- });
492
+ results.push(materialize(snapshotPath, content));
454
493
  }
455
494
  export function isSessionPath(relativePath) {
456
495
  return toPosix(relativePath).startsWith("sessions/");
@@ -1,5 +1,5 @@
1
1
  import type { CommandOptions } from "../commands/command-types.js";
2
- import type { EngineContext as ExtensionCommandContext } from "../host.js";
2
+ import { type EngineContext as ExtensionCommandContext } from "../host.js";
3
3
  import type { LockFile } from "./state-types.js";
4
4
  export type LockInspection = {
5
5
  status: "missing";
@@ -9,6 +9,7 @@ export type LockInspection = {
9
9
  status: "valid";
10
10
  lock: LockFile;
11
11
  };
12
+ export declare function captureStartupReviewLock(): (() => boolean) | undefined;
12
13
  export declare function withLock<T>(command: string, fn: () => Promise<T>, options?: {
13
14
  reclaimStale?: boolean;
14
15
  }): Promise<T>;