@narumitw/pi-sync-daemon 0.9.0 → 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 (102) hide show
  1. package/CHANGELOG.md +19 -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/ignore/ignore-initialization.d.ts +5 -1
  28. package/dist/engine/ignore/ignore-initialization.js +50 -14
  29. package/dist/engine/ignore/ignore-settings.js +11 -14
  30. package/dist/engine/ignore/ignore-source.d.ts +1 -1
  31. package/dist/engine/ignore/ignore-source.js +1 -1
  32. package/dist/engine/paths.d.ts +2 -0
  33. package/dist/engine/paths.js +7 -1
  34. package/dist/engine/settings/config-file.d.ts +10 -1
  35. package/dist/engine/settings/config-file.js +62 -17
  36. package/dist/engine/settings/config.d.ts +7 -0
  37. package/dist/engine/settings/config.js +49 -14
  38. package/dist/engine/snapshot/snapshot-apply.d.ts +2 -1
  39. package/dist/engine/snapshot/snapshot-apply.js +30 -8
  40. package/dist/engine/snapshot/snapshot-codec.js +3 -1
  41. package/dist/engine/snapshot/snapshot-payload.d.ts +4 -0
  42. package/dist/engine/snapshot/snapshot-payload.js +32 -0
  43. package/dist/engine/snapshot/snapshot-transaction-images.d.ts +2 -0
  44. package/dist/engine/snapshot/snapshot-transaction-images.js +34 -0
  45. package/dist/engine/snapshot/snapshot-transaction.d.ts +4 -1
  46. package/dist/engine/snapshot/snapshot-transaction.js +50 -7
  47. package/dist/engine/snapshot/snapshot-types.d.ts +10 -2
  48. package/dist/engine/snapshot/snapshot.d.ts +3 -1
  49. package/dist/engine/snapshot/snapshot.js +64 -25
  50. package/dist/engine/state/lock.d.ts +2 -1
  51. package/dist/engine/state/lock.js +157 -17
  52. package/dist/engine/sync/continuous-sync.d.ts +10 -1
  53. package/dist/engine/sync/continuous-sync.js +35 -11
  54. package/dist/engine/sync/initialization.d.ts +1 -1
  55. package/dist/engine/sync/initialization.js +2 -2
  56. package/dist/engine/sync/local-fields.d.ts +6 -1
  57. package/dist/engine/sync/local-fields.js +42 -19
  58. package/dist/engine/sync/merged-sync.js +13 -10
  59. package/dist/engine/sync/remote-snapshot.js +18 -3
  60. package/dist/engine/sync/session-push.js +13 -4
  61. package/dist/engine/sync/startup-bootstrap.d.ts +1 -0
  62. package/dist/engine/sync/startup-bootstrap.js +105 -0
  63. package/dist/engine/sync/startup-recovery-evidence.d.ts +1 -0
  64. package/dist/engine/sync/startup-recovery-evidence.js +37 -0
  65. package/dist/engine/sync/startup-timings.d.ts +9 -2
  66. package/dist/engine/sync/startup-timings.js +80 -8
  67. package/dist/engine/sync/sync-error-guidance.js +22 -4
  68. package/dist/engine/sync/sync-inspection.js +4 -7
  69. package/dist/engine/sync/sync-local.d.ts +2 -1
  70. package/dist/engine/sync/sync-local.js +3 -1
  71. package/dist/engine/sync/sync-mutations.js +13 -7
  72. package/dist/engine/sync/sync-policy.d.ts +2 -0
  73. package/dist/engine/sync/sync-policy.js +9 -1
  74. package/dist/engine/sync/sync-state.d.ts +8 -3
  75. package/dist/engine/sync/sync-state.js +12 -4
  76. package/dist/engine/ui/sync-format.d.ts +16 -5
  77. package/dist/engine/ui/sync-format.js +23 -55
  78. package/dist/engine/ui/transfer-review.d.ts +2 -1
  79. package/dist/engine/ui/transfer-review.js +3 -3
  80. package/dist/engine-service.d.ts +6 -0
  81. package/dist/engine-service.js +54 -10
  82. package/dist/identity.d.ts +5 -2
  83. package/dist/identity.js +36 -6
  84. package/dist/index.d.ts +2 -1
  85. package/dist/index.js +2 -1
  86. package/dist/monitor.js +20 -1
  87. package/dist/paged-review.d.ts +35 -0
  88. package/dist/paged-review.js +177 -0
  89. package/dist/participant-ledger.d.ts +16 -0
  90. package/dist/participant-ledger.js +149 -0
  91. package/dist/protocol.d.ts +15 -0
  92. package/dist/protocol.js +4 -0
  93. package/dist/server.d.ts +7 -0
  94. package/dist/server.js +268 -120
  95. package/dist/service-host.d.ts +2 -1
  96. package/dist/service-host.js +29 -9
  97. package/dist/state-wait-jobs.d.ts +8 -0
  98. package/dist/state-wait-jobs.js +23 -0
  99. package/dist/state-wait.d.ts +7 -0
  100. package/dist/state-wait.js +34 -0
  101. package/docs/architecture.md +23 -1
  102. package/package.json +1 -1
@@ -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>;
@@ -1,14 +1,80 @@
1
+ import { AsyncLocalStorage } from "node:async_hooks";
1
2
  import { randomUUID } from "node:crypto";
3
+ import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, realpathSync } from "node:fs";
2
4
  import fs from "node:fs/promises";
5
+ import path from "node:path";
3
6
  import lockfile from "proper-lockfile";
7
+ import { canonicalRootGuard } from "../../identity.js";
8
+ import { getEngineRoot } from "../host.js";
4
9
  import { throwIfAborted } from "../sync/signals.js";
5
10
  import { LOCK_GUARD_STALE_MS, LOCK_GUARD_UPDATE_MS } from "./lock-policy.js";
6
11
  import { LOCKFILE_FS_ADAPTER } from "./lockfile-fs.js";
12
+ import { stateDir } from "./state-directory.js";
7
13
  import { ensureStateDir, lockPath } from "./sync-state-store.js";
8
14
  const LOCK_STALE_MS = 30 * 60 * 1000;
9
15
  const MAX_PROCESS_ID = 2_147_483_647;
16
+ const activeLock = new AsyncLocalStorage();
17
+ export function captureStartupReviewLock() {
18
+ const owner = activeLock.getStore();
19
+ if (!owner?.active())
20
+ return;
21
+ const guardPath = `${owner.path}.guard`;
22
+ const originalGuard = lstatSync(guardPath, { bigint: true, throwIfNoEntry: false });
23
+ const originalLock = lstatSync(owner.path, { bigint: true, throwIfNoEntry: false });
24
+ if (!originalGuard?.isDirectory() || !originalLock?.isFile())
25
+ return;
26
+ const validate = () => {
27
+ if (!owner.active() || owner.path !== lockPath())
28
+ return false;
29
+ const guard = lstatSync(guardPath, { bigint: true, throwIfNoEntry: false });
30
+ const candidate = lstatSync(owner.path, { bigint: true, throwIfNoEntry: false });
31
+ if (!guard?.isDirectory() ||
32
+ guard.dev !== originalGuard.dev ||
33
+ guard.ino !== originalGuard.ino ||
34
+ Number(guard.mtimeMs) < Date.now() - LOCK_GUARD_STALE_MS ||
35
+ !candidate?.isFile() ||
36
+ candidate.dev !== originalLock.dev ||
37
+ candidate.ino !== originalLock.ino ||
38
+ candidate.size !== BigInt(owner.contents.length))
39
+ return false;
40
+ const fd = openSync(owner.path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
41
+ try {
42
+ const opened = fstatSync(fd, { bigint: true });
43
+ if (!opened.isFile() || opened.dev !== candidate.dev || opened.ino !== candidate.ino)
44
+ return false;
45
+ const current = Buffer.alloc(owner.contents.length + 1);
46
+ let offset = 0;
47
+ while (offset < current.length) {
48
+ const count = readSync(fd, current, offset, current.length - offset, offset);
49
+ if (!count)
50
+ break;
51
+ offset += count;
52
+ }
53
+ return current.subarray(0, offset).equals(owner.contents);
54
+ }
55
+ finally {
56
+ closeSync(fd);
57
+ }
58
+ };
59
+ return validate() ? validate : undefined;
60
+ }
10
61
  export async function withLock(command, fn, options = {}) {
11
62
  await ensureStateDir();
63
+ const configuredRoot = getEngineRoot();
64
+ const root = realpathSync(configuredRoot);
65
+ const assertRoot = canonicalRootGuard(root);
66
+ const directory = stateDir(root);
67
+ const file = path.join(directory, "lock");
68
+ const original = lstatSync(directory);
69
+ const assertLocation = () => {
70
+ assertRoot();
71
+ if (realpathSync(configuredRoot) !== root || stateDir(root) !== directory)
72
+ throw new Error("Pi Sync operation lock directory changed.");
73
+ const current = lstatSync(directory);
74
+ if (!current.isDirectory() || current.dev !== original.dev || current.ino !== original.ino)
75
+ throw new Error("Pi Sync operation lock directory changed.");
76
+ };
77
+ assertLocation();
12
78
  const lock = {
13
79
  id: randomUUID(),
14
80
  pid: process.pid,
@@ -16,29 +82,34 @@ export async function withLock(command, fn, options = {}) {
16
82
  startedAt: new Date().toISOString(),
17
83
  };
18
84
  let guard;
85
+ let written = false;
19
86
  let result;
20
87
  let failed = false;
21
88
  let failure;
22
89
  try {
23
90
  try {
24
- guard = await acquireGuard();
91
+ guard = await acquireGuard(file, assertLocation);
25
92
  }
26
93
  catch (error) {
27
94
  if (!isLockHeldError(error))
28
95
  throw error;
29
- throw await describeHeldLock();
96
+ assertLocation();
97
+ throw await describeHeldLock(file);
30
98
  }
31
- let inspection = await inspectLock();
99
+ assertLocation();
100
+ let inspection = await inspectLockAt(file);
32
101
  if (inspection.status === "valid" && isStaleLock(inspection.lock)) {
33
102
  if (!options.reclaimStale) {
34
103
  throw new Error(`pi-sync lock is stale (pid ${inspection.lock.pid}). Run /sync unlock --stale, then retry.`);
35
104
  }
36
105
  guard.throwIfCompromised();
37
- const rechecked = await inspectLock();
106
+ const rechecked = await inspectLockAt(file);
38
107
  if (rechecked.status !== "valid" || rechecked.lock.id !== inspection.lock.id || !isStaleLock(rechecked.lock)) {
39
108
  throw new Error("pi-sync lock changed while preparing transaction recovery; retry.");
40
109
  }
41
- await fs.rm(lockPath(), { force: true });
110
+ assertLocation();
111
+ guard.throwIfCompromised();
112
+ await fs.rm(file, { force: true });
42
113
  inspection = { status: "missing" };
43
114
  }
44
115
  if (inspection.status === "valid") {
@@ -47,19 +118,48 @@ export async function withLock(command, fn, options = {}) {
47
118
  if (inspection.status === "unreadable") {
48
119
  throw new Error("pi-sync lock metadata is unreadable. Run /sync unlock --stale after verifying no sync is running.");
49
120
  }
50
- await fs.writeFile(lockPath(), JSON.stringify(lock, null, "\t"), { flag: "wx" });
121
+ assertLocation();
51
122
  guard.throwIfCompromised();
52
- result = await fn();
123
+ const contents = Buffer.from(JSON.stringify(lock, null, "\t"));
124
+ await fs.writeFile(file, contents, { flag: "wx" });
125
+ written = true;
53
126
  guard.throwIfCompromised();
127
+ const held = guard;
128
+ let active = true;
129
+ const ownsLock = () => {
130
+ if (!active || held.isCompromised())
131
+ return false;
132
+ try {
133
+ assertLocation();
134
+ return true;
135
+ }
136
+ catch {
137
+ return false;
138
+ }
139
+ };
140
+ try {
141
+ result = await activeLock.run({ path: file, contents, active: ownsLock }, fn);
142
+ guard.throwIfCompromised();
143
+ }
144
+ finally {
145
+ active = false;
146
+ }
54
147
  }
55
148
  catch (error) {
56
149
  failed = true;
57
150
  failure = error;
58
151
  }
59
152
  try {
60
- const current = await readLock();
61
- if (current?.id === lock.id)
62
- await fs.rm(lockPath(), { force: true });
153
+ if (written && guard) {
154
+ assertLocation();
155
+ guard.throwIfCompromised();
156
+ const current = await inspectLockAt(file);
157
+ if (current.status === "valid" && current.lock.id === lock.id) {
158
+ assertLocation();
159
+ guard.throwIfCompromised();
160
+ await fs.rm(file, { force: true });
161
+ }
162
+ }
63
163
  }
64
164
  catch (error) {
65
165
  if (!failed) {
@@ -79,8 +179,11 @@ export async function withLock(command, fn, options = {}) {
79
179
  return result;
80
180
  }
81
181
  export async function inspectLock() {
182
+ return inspectLockAt(lockPath());
183
+ }
184
+ async function inspectLockAt(file) {
82
185
  try {
83
- const text = await fs.readFile(lockPath(), "utf8");
186
+ const text = await fs.readFile(file, "utf8");
84
187
  if (text.trim().length === 0)
85
188
  return { status: "unreadable" };
86
189
  const parsed = JSON.parse(text);
@@ -209,11 +312,47 @@ async function releaseGuard(guard) {
209
312
  return guard.isCompromised() ? undefined : error;
210
313
  }
211
314
  }
212
- async function acquireGuard() {
315
+ function guardFilesystem(assertLocation) {
316
+ const { mkdir, rmdir, rmdirSync, stat, utimes } = LOCKFILE_FS_ADAPTER;
317
+ function check(callback) {
318
+ try {
319
+ assertLocation();
320
+ return true;
321
+ }
322
+ catch (error) {
323
+ callback(error);
324
+ return false;
325
+ }
326
+ }
327
+ return {
328
+ ...LOCKFILE_FS_ADAPTER,
329
+ mkdir: (file, callback) => {
330
+ if (check(callback))
331
+ mkdir(file, callback);
332
+ },
333
+ rmdir: (...args) => {
334
+ if (check(args[1]))
335
+ rmdir(...args);
336
+ },
337
+ rmdirSync: (...args) => {
338
+ assertLocation();
339
+ return rmdirSync(...args);
340
+ },
341
+ stat: (file, callback) => {
342
+ if (check(callback))
343
+ stat(file, callback);
344
+ },
345
+ utimes: (...args) => {
346
+ if (check(args[3]))
347
+ utimes(...args);
348
+ },
349
+ };
350
+ }
351
+ async function acquireGuard(file = lockPath(), assertLocation) {
213
352
  let compromisedError;
214
- const release = await lockfile.lock(lockPath(), {
215
- fs: LOCKFILE_FS_ADAPTER,
216
- lockfilePath: `${lockPath()}.guard`,
353
+ const release = await lockfile.lock(file, {
354
+ fs: assertLocation ? guardFilesystem(assertLocation) : LOCKFILE_FS_ADAPTER,
355
+ lockfilePath: `${file}.guard`,
217
356
  realpath: false,
218
357
  stale: LOCK_GUARD_STALE_MS,
219
358
  update: LOCK_GUARD_UPDATE_MS,
@@ -230,8 +369,9 @@ async function acquireGuard() {
230
369
  isCompromised: () => compromisedError !== undefined,
231
370
  };
232
371
  }
233
- async function describeHeldLock() {
234
- const current = await readLock();
372
+ async function describeHeldLock(file = lockPath()) {
373
+ const inspection = await inspectLockAt(file);
374
+ const current = inspection.status === "valid" ? inspection.lock : undefined;
235
375
  if (current && isStaleLock(current)) {
236
376
  return new Error("pi-sync lock owner exited; retry shortly while the lock guard expires.");
237
377
  }
@@ -1,5 +1,6 @@
1
1
  import type { EngineContext as ExtensionContext } from "../host.js";
2
2
  import type { AnySyncConfig } from "../settings/settings-types.js";
3
+ import { type ContinuousErrorKind } from "./continuous-errors.js";
3
4
  import { type StartupTimingPublisher } from "./startup-timings.js";
4
5
  import type { SyncLoaders } from "./sync-loaders.js";
5
6
  export declare function continuousEnabled(config: Pick<AnySyncConfig, "continuous" | "agentMode">): boolean;
@@ -9,8 +10,16 @@ export interface ContinuousClock {
9
10
  schedule(ms: number, run: () => void, kind?: "wait" | "authorization"): () => void;
10
11
  }
11
12
  type ContinuousTransfer = <T>(run: (committed: () => void) => Promise<T>) => Promise<T>;
13
+ type CycleOutcome = {
14
+ outcome: "completed" | "failed" | "cancelled" | "blocked" | "skipped";
15
+ reason?: ContinuousErrorKind;
16
+ };
17
+ interface ContinuousDiagnostics {
18
+ timing?(ctx: ExtensionContext, report: string): void;
19
+ cycle?(ctx: ExtensionContext, setup: string, outcome: CycleOutcome): void;
20
+ }
12
21
  /** Created on first enabled session. No module/factory-owned timers or watchers. */
13
- export declare function createContinuousSync(loaders: SyncLoaders, clock?: ContinuousClock, publish?: StartupTimingPublisher): {
22
+ export declare function createContinuousSync(loaders: SyncLoaders, clock?: ContinuousClock, publish?: StartupTimingPublisher, diagnostics?: ContinuousDiagnostics): {
14
23
  start(ctx: ExtensionContext, sessionSignal: AbortSignal, explicitRetry?: boolean | string, debug?: boolean, transfer?: ContinuousTransfer): void;
15
24
  stop(owner?: ExtensionContext["sessionManager"]): Promise<void>;
16
25
  };
@@ -14,7 +14,7 @@ import { watchContinuous } from "./continuous-watch.js";
14
14
  import { assertMergeJournalPolicy, readMergeJournal } from "./merge-journal.js";
15
15
  import { createStartupTimings } from "./startup-timings.js";
16
16
  import { captureMutationOwner } from "./sync-local.js";
17
- import { fileHashMap } from "./sync-state.js";
17
+ import { rawSnapshotHashIdentity } from "./sync-state.js";
18
18
  export function continuousEnabled(config) {
19
19
  return Boolean(config.continuous && config.agentMode);
20
20
  }
@@ -31,7 +31,7 @@ const LOCAL_CHECK_MS = 5_000;
31
31
  const POLL_MS = 60_000;
32
32
  const DEBOUNCE_MS = 1_000;
33
33
  /** Created on first enabled session. No module/factory-owned timers or watchers. */
34
- export function createContinuousSync(loaders, clock = systemClock, publish) {
34
+ export function createContinuousSync(loaders, clock = systemClock, publish, diagnostics) {
35
35
  const startups = new WeakMap();
36
36
  const repairNotices = new WeakSet();
37
37
  let task;
@@ -138,8 +138,10 @@ export function createContinuousSync(loaders, clock = systemClock, publish) {
138
138
  await monitor(ctx, config, binding, lease, signal, retry, startup, transfer);
139
139
  explicitRetry = false;
140
140
  }
141
- else
141
+ else {
142
+ observeCycle(ctx, config, { outcome: "skipped", reason: "contention" });
142
143
  setSyncStatus(ctx, "sync waiting: another local owner", { activity: "idle" });
144
+ }
143
145
  }
144
146
  finally {
145
147
  await lease?.release();
@@ -150,6 +152,7 @@ export function createContinuousSync(loaders, clock = systemClock, publish) {
150
152
  if (signal.aborted)
151
153
  return;
152
154
  const failure = continuousFailure(error);
155
+ observeCycle(ctx, config, { outcome: failure.retry ? "failed" : "blocked", reason: failure.kind });
153
156
  if (!failure.retry && !(error instanceof Error && error.name === "AbortError"))
154
157
  throw error;
155
158
  setSyncStatus(ctx, `sync retry scheduled: ${failure.kind}`, {
@@ -262,8 +265,10 @@ export function createContinuousSync(loaders, clock = systemClock, publish) {
262
265
  if (now >= due) {
263
266
  const timings = createStartupTimings(publish);
264
267
  const report = !startup.reported && startup.debug;
268
+ const timing = !startup.reported && latest.debug ? diagnostics?.timing : undefined;
265
269
  startup.reported = true;
266
270
  let outcome = "stopped";
271
+ let cycleOutcome;
267
272
  const force = explicitRetry || controlChanged;
268
273
  explicitRetry = false;
269
274
  const expectedModel = hashContinuous(ctx.model);
@@ -303,18 +308,22 @@ export function createContinuousSync(loaders, clock = systemClock, publish) {
303
308
  }
304
309
  })().catch(() => { });
305
310
  try {
306
- await performCycle(ctx, config, binding, lease, AbortSignal.any([signal, cycle.signal]), validateCycle, configuration, force, timings, transfer);
311
+ cycleOutcome = await performCycle(ctx, config, binding, lease, AbortSignal.any([signal, cycle.signal]), validateCycle, configuration, force, timings, transfer);
307
312
  outcome = "completed";
308
313
  }
309
314
  catch (error) {
310
- if (signal.aborted || !ctx.isIdle())
315
+ if (signal.aborted || !ctx.isIdle()) {
316
+ cycleOutcome = { outcome: "cancelled" };
311
317
  return;
318
+ }
312
319
  // A settings hint interrupts the old authorization; load it afresh, not as a failed transfer.
313
320
  if (cycle.signal.aborted && cycle.signal.reason?.name !== "TimeoutError") {
321
+ cycleOutcome = { outcome: "cancelled" };
314
322
  pollDue = 0;
315
323
  continue;
316
324
  }
317
325
  const failure = continuousFailure(error);
326
+ cycleOutcome = { outcome: failure.retry ? "failed" : "blocked", reason: failure.kind };
318
327
  let announce = false;
319
328
  await updateContinuousRecord(binding, lease, (current) => {
320
329
  const now = clock.now();
@@ -341,7 +350,9 @@ export function createContinuousSync(loaders, clock = systemClock, publish) {
341
350
  guard.abort();
342
351
  await guardTask;
343
352
  cycle = undefined;
344
- timings.publish(ctx, report, signal, "continuous startup", outcome);
353
+ if (cycleOutcome)
354
+ observeCycle(ctx, latest, cycleOutcome);
355
+ timings.publish(ctx, report, signal, "continuous startup", outcome, timing && ((report) => timing(ctx, report)));
345
356
  }
346
357
  pollDue = clock.now() + POLL_MS + Math.floor(clock.random() * 6_000);
347
358
  closeWatch();
@@ -394,7 +405,7 @@ export function createContinuousSync(loaders, clock = systemClock, publish) {
394
405
  !pending &&
395
406
  current.phase === "blocked" &&
396
407
  ["authentication", "storage", "unknown"].includes(current.error ?? ""))
397
- return;
408
+ return { outcome: "blocked", reason: current.error };
398
409
  setSyncStatus(ctx, "sync checking", { activity: "checking" });
399
410
  const inspectionModule = await timings.measure("inspection import", () => loaders.inspection());
400
411
  validate();
@@ -410,11 +421,11 @@ export function createContinuousSync(loaders, clock = systemClock, publish) {
410
421
  await refresh();
411
422
  let localIdentity = inspection.localIdentity;
412
423
  if (!localIdentity) {
413
- const snapshotModule = await loaders.snapshot();
424
+ const { observeSnapshot } = await import("../snapshot/snapshot.js");
414
425
  validate();
415
- const local = await snapshotModule.createSnapshot(config.snapshotIdentity, snapshotOptions);
426
+ const local = await observeSnapshot(snapshotOptions);
416
427
  validate();
417
- localIdentity = hashContinuous(fileHashMap(local));
428
+ localIdentity = rawSnapshotHashIdentity(local);
418
429
  }
419
430
  const journal = await readMergeJournal(config);
420
431
  validate();
@@ -452,13 +463,14 @@ export function createContinuousSync(loaders, clock = systemClock, publish) {
452
463
  });
453
464
  validate();
454
465
  if (blocked)
455
- return;
466
+ return { outcome: "blocked", reason: current.error };
456
467
  if (!observed.journal &&
457
468
  (observed.inspection.firstSync ||
458
469
  !observed.inspection.head ||
459
470
  observed.inspection.selectionState?.kind !== "same"))
460
471
  throw new ContinuousError("unsafe", "Continuous sync needs an accepted baseline and matching remote selection.");
461
472
  let transferred = false;
473
+ let outcome;
462
474
  if (observed.journal || observed.inspection.localChanged || observed.inspection.remoteChanged) {
463
475
  const operations = await timings.measure("operations import", () => loaders.operations());
464
476
  validate();
@@ -489,6 +501,9 @@ export function createContinuousSync(loaders, clock = systemClock, publish) {
489
501
  const result = await timings.measure("automatic transfer", () => transfer ? transfer(runTransfer) : runTransfer());
490
502
  validate();
491
503
  transferred = result === "applied";
504
+ outcome = {
505
+ outcome: result === "cancelled" ? "cancelled" : transferred && !timings.wasUnchanged() ? "completed" : "skipped",
506
+ };
492
507
  }
493
508
  const state = await guardedLock("continuous-result", () => readStateForConfig(config));
494
509
  validate();
@@ -515,6 +530,15 @@ export function createContinuousSync(loaders, clock = systemClock, publish) {
515
530
  validate();
516
531
  if (announcePartial)
517
532
  ctx.ui.notify("Continuous sync retained unresolved groups. Review /sync conflicts; independent partial progress was preserved.", "warning");
533
+ return unresolved?.length ? { outcome: "blocked", reason: "unsafe" } : outcome;
534
+ }
535
+ function observeCycle(ctx, config, outcome) {
536
+ if (!config.debug)
537
+ return;
538
+ try {
539
+ diagnostics?.cycle?.(ctx, config.setupName, outcome);
540
+ }
541
+ catch { }
518
542
  }
519
543
  }
520
544
  function guardedLock(command, run) {
@@ -1,7 +1,7 @@
1
1
  import type { EngineContext } from "../host.js";
2
2
  import { type StartupTimingPublisher } from "./startup-timings.js";
3
3
  /** Shared engine initialization; the caller establishes process handover before recovery. */
4
- export declare function initializeSync(ctx: EngineContext, signal: AbortSignal, publish?: StartupTimingPublisher): Promise<{
4
+ export declare function initializeSync(ctx: EngineContext, signal: AbortSignal, publish?: StartupTimingPublisher, observe?: (report: string) => void): Promise<{
5
5
  debug: boolean;
6
6
  settings: import("../types.js").PiSyncSettingsV3 | undefined;
7
7
  config?: undefined;
@@ -9,7 +9,7 @@ import { captureMutationOwner } from "./mutation-owner.js";
9
9
  import { createStartupTimings } from "./startup-timings.js";
10
10
  import { errorMessage } from "./sync-errors.js";
11
11
  /** Shared engine initialization; the caller establishes process handover before recovery. */
12
- export async function initializeSync(ctx, signal, publish) {
12
+ export async function initializeSync(ctx, signal, publish, observe) {
13
13
  return withStateDirectoryAccess(async () => {
14
14
  const timings = createStartupTimings(publish);
15
15
  let debug = false;
@@ -74,7 +74,7 @@ export async function initializeSync(ctx, signal, publish) {
74
74
  return { debug, settings };
75
75
  }
76
76
  finally {
77
- timings.publish(ctx, debug, signal, "local initialization", outcome);
77
+ timings.publish(ctx, debug, signal, "local initialization", outcome, observe);
78
78
  }
79
79
  });
80
80
  }
@@ -1,4 +1,4 @@
1
- import { type IgnoreSnapshotSelection, type Snapshot } from "../snapshot/snapshot-types.js";
1
+ import { type IgnoreSnapshotSelection, type Snapshot, type SnapshotObservation } from "../snapshot/snapshot-types.js";
2
2
  export { normalizeLocalFields } from "./local-field-policy.js";
3
3
  /** Shared transport contract: older snapshots cannot carry portable policy metadata. */
4
4
  export declare function validateSnapshotFieldPolicy(snapshot: Pick<Snapshot, "version" | "localFields">): void;
@@ -7,5 +7,10 @@ export declare function validateIgnoreSnapshotIdentity({ id, createdAt, machine,
7
7
  /** Portable transport images must not carry values declared machine-local. Physical journal images are different. */
8
8
  export declare function validatePortableSnapshot(snapshot: Snapshot): void;
9
9
  export declare function sameLocalFields(left: unknown, right: unknown): boolean;
10
+ export declare function portableObservation(observation: SnapshotObservation, fields: string[] | undefined): SnapshotObservation | {
11
+ files: (import("../snapshot/snapshot-types.js").SnapshotFileHash & {
12
+ settingsContent?: Buffer;
13
+ })[];
14
+ };
10
15
  export declare function portableSnapshot(snapshot: Snapshot, fields: string[] | undefined): Snapshot;
11
16
  export declare function overlayLocalFields(portable: Snapshot, local: Snapshot, fields: string[] | undefined): Snapshot;