@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,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;
@@ -1,6 +1,7 @@
1
1
  import { createHash } from "node:crypto";
2
2
  import { regenerateSnapshotIdentity } from "../snapshot/snapshot.js";
3
3
  import { assertAgentDirectorySnapshotBound } from "../snapshot/snapshot-bounds.js";
4
+ import { assertSnapshotFilePayload } from "../snapshot/snapshot-payload.js";
4
5
  import { IGNORE_SNAPSHOT_VERSION, isSupportedSnapshotVersion, } from "../snapshot/snapshot-types.js";
5
6
  import { jsonEqual, parseSettingsDocument, renderSettingsMembers, } from "./json-document.js";
6
7
  import { normalizeLocalFields } from "./local-field-policy.js";
@@ -68,10 +69,7 @@ function validateIgnoreSnapshotFiles(files) {
68
69
  typeof file.sha256 !== "string" ||
69
70
  file.sha256.length !== 64)
70
71
  throw new Error("Invalid ignore snapshot file.");
71
- const content = Buffer.from(file.contentBase64, "base64");
72
- if (content.toString("base64") !== file.contentBase64 ||
73
- createHash("sha256").update(content).digest("hex") !== file.sha256)
74
- throw new Error("Ignore snapshot file checksum or encoding mismatch.");
72
+ assertSnapshotFilePayload(file, "Ignore snapshot file checksum or encoding mismatch.");
75
73
  }
76
74
  }
77
75
  /** Portable transport images must not carry values declared machine-local. Physical journal images are different. */
@@ -123,10 +121,47 @@ function file(content) {
123
121
  };
124
122
  }
125
123
  function requireCanonicalFieldSettingsPath(snapshot) {
126
- if (snapshot.selection?.scope &&
127
- snapshot.files.some(({ path }) => path !== "settings.json" && path.toLowerCase() === "settings.json"))
124
+ assertCanonicalFieldSettingsPath(snapshot.files, snapshot.selection?.scope);
125
+ }
126
+ function assertCanonicalFieldSettingsPath(files, scope) {
127
+ if (scope && files.some(({ path }) => path !== "settings.json" && path.toLowerCase() === "settings.json"))
128
128
  throw new Error("Directory scope requires the exact settings.json spelling when machine-local fields are configured.");
129
129
  }
130
+ function portableSettingsContent(content, excluded) {
131
+ const document = parseSettingsDocument(content);
132
+ const object = Object.create(null);
133
+ for (const key of [...document.root.members.keys()].sort())
134
+ if (!excluded.has(key))
135
+ object[key] = document.root.members.get(key)?.node.value;
136
+ const canonical = (value) => Array.isArray(value)
137
+ ? value.map(canonical)
138
+ : value && typeof value === "object"
139
+ ? Object.fromEntries(Object.entries(value)
140
+ .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
141
+ .map(([key, child]) => [key, canonical(child)]))
142
+ : value;
143
+ return Buffer.from(`${JSON.stringify(canonical(object))}\n`);
144
+ }
145
+ export function portableObservation(observation, fields) {
146
+ if (fields === undefined)
147
+ return observation;
148
+ const excluded = new Set(normalizeLocalFields(fields));
149
+ if (excluded.size === 0)
150
+ return observation;
151
+ assertCanonicalFieldSettingsPath(observation.files, observation.scope);
152
+ return {
153
+ files: observation.files.map((entry) => {
154
+ if (entry.path !== "settings.json")
155
+ return entry;
156
+ if (entry.settingsContent === undefined)
157
+ throw new Error("Missing settings bytes for portable observation.");
158
+ return {
159
+ path: entry.path,
160
+ sha256: createHash("sha256").update(portableSettingsContent(entry.settingsContent, excluded)).digest("hex"),
161
+ };
162
+ }),
163
+ };
164
+ }
130
165
  export function portableSnapshot(snapshot, fields) {
131
166
  if (fields === undefined)
132
167
  return snapshot;
@@ -136,19 +171,7 @@ export function portableSnapshot(snapshot, fields) {
136
171
  const files = snapshot.files.map((entry) => {
137
172
  if (entry.path !== "settings.json" || excluded.size === 0)
138
173
  return entry;
139
- const document = parseSettingsDocument(Buffer.from(entry.contentBase64, "base64"));
140
- const object = Object.create(null);
141
- for (const key of [...document.root.members.keys()].sort())
142
- if (!excluded.has(key))
143
- object[key] = document.root.members.get(key)?.node.value;
144
- const canonical = (value) => Array.isArray(value)
145
- ? value.map(canonical)
146
- : value && typeof value === "object"
147
- ? Object.fromEntries(Object.entries(value)
148
- .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
149
- .map(([key, child]) => [key, canonical(child)]))
150
- : value;
151
- return file(Buffer.from(`${JSON.stringify(canonical(object))}\n`));
174
+ return file(portableSettingsContent(Buffer.from(entry.contentBase64, "base64"), excluded));
152
175
  });
153
176
  return regenerateSnapshotIdentity({
154
177
  ...snapshot,
@@ -2,7 +2,7 @@ import { createSyncBackend } from "../backends/backend-factory.js";
2
2
  import { expectedRemoteHead, SyncBackendConflictError } from "../backends/sync-backend.js";
3
3
  import { loadConfig, syncCheckConfigFingerprint } from "../settings/config.js";
4
4
  import { effectiveSessionRoot, requireStableMergeSessionRoot, snapshotOptionsForContext, } from "../snapshot/session-paths.js";
5
- import { createSnapshot, filterSnapshotForConfigPolicy, mergeRemotePreservedFiles, regenerateSnapshotIdentity, scanSnapshot, } from "../snapshot/snapshot.js";
5
+ import { createSnapshot, filterSnapshotForConfigPolicy, mergeRemotePreservedFiles, observeSnapshot, regenerateSnapshotIdentity, scanSnapshot, snapshotWithObservedInventory, } from "../snapshot/snapshot.js";
6
6
  import { ignorePolicyValidator } from "../snapshot/snapshot-transaction-policy.js";
7
7
  import { hasCurrentMergeBaseline, pruneMergeBaselines, readMergeAncestors } from "../state/merge-baseline-store.js";
8
8
  import { readStateForConfig, statePathForConfig, syncStateFingerprint } from "../state/sync-state-store.js";
@@ -27,7 +27,7 @@ import { formatRemoteSelectionStatus, readSnapshotForHead, requireCompatibleRemo
27
27
  import { resolveSettingsConflicts } from "./settings-conflicts.js";
28
28
  import { createStartupTimings } from "./startup-timings.js";
29
29
  import { createSyncDecision } from "./sync-decision.js";
30
- import { backupLocal, captureMutationOwner, protectedSessionPaths } from "./sync-local.js";
30
+ import { backupSnapshot, captureMutationOwner, protectedSessionPaths } from "./sync-local.js";
31
31
  import { configuredSnapshotPathMatcher, inspectRemoteSelection, syncSessionsSelected } from "./sync-policy.js";
32
32
  import { fileHashMap, hasLocalChanges, hasRemoteChanges, sameHashes, syncPolicyChanged } from "./sync-state.js";
33
33
  import { TEXT_MERGE_WORK_LIMIT } from "./text-merge.js";
@@ -163,7 +163,7 @@ export async function mergeSync(ctx, options, factory = createSyncBackend, resol
163
163
  if (!(await hasCurrentMergeBaseline(config, local, state)))
164
164
  return false;
165
165
  await validate();
166
- const currentLocal = await timings.measure("transfer local snapshot", () => createSnapshot(config.snapshotIdentity, snapshotOptions));
166
+ const currentLocal = await timings.measure("transfer local snapshot", () => observeSnapshot(snapshotOptions));
167
167
  await validate();
168
168
  const currentState = await timings.measure("transfer state read", () => readStateForConfig(config));
169
169
  await validate();
@@ -362,7 +362,7 @@ export async function mergeSync(ctx, options, factory = createSyncBackend, resol
362
362
  throw new ContinuousError("stale", "Remote changed before baseline acceptance; retry from a fresh observation.");
363
363
  progress = await persistProgress();
364
364
  await validate();
365
- const currentLocal = await timings.measure("transfer local snapshot", () => createSnapshot(config.snapshotIdentity, snapshotOptions));
365
+ const currentLocal = await timings.measure("transfer local snapshot", () => observeSnapshot(snapshotOptions));
366
366
  await validate();
367
367
  if (!sameHashes(fileHashMap(currentLocal), fileHashMap(localRaw)) ||
368
368
  syncStateFingerprint(await timings.measure("transfer state read", () => readStateForConfig(config))) !==
@@ -411,8 +411,10 @@ export async function mergeSync(ctx, options, factory = createSyncBackend, resol
411
411
  return "cancelled";
412
412
  }
413
413
  await validate();
414
- const refreshed = await timings.measure("transfer local snapshot", () => createSnapshot(config.snapshotIdentity, snapshotOptions));
415
- if (!sameHashes(fileHashMap(refreshed), fileHashMap(localRaw)))
414
+ const refreshObservation = await timings.measure("transfer local snapshot", () => observeSnapshot(snapshotOptions));
415
+ validateOwner();
416
+ const refreshed = snapshotWithObservedInventory(localRaw, refreshObservation);
417
+ if (!refreshed)
416
418
  throw new ContinuousError("stale", "Local content changed during review; no merged transfer was performed.");
417
419
  if (syncStateFingerprint(await timings.measure("transfer state read", () => readStateForConfig(config))) !==
418
420
  syncStateFingerprint(state))
@@ -426,7 +428,7 @@ export async function mergeSync(ctx, options, factory = createSyncBackend, resol
426
428
  await validate();
427
429
  progress = await persistProgress();
428
430
  await validate();
429
- const backup = await timings.measure("transfer backup", () => backupLocal(config.snapshotIdentity, snapshotOptions, options.signal));
431
+ const backup = await timings.measure("transfer backup", () => backupSnapshot(regenerateSnapshotIdentity(refreshed), options.signal));
430
432
  await validateFresh();
431
433
  const journal = {
432
434
  ...mergeJournalPolicy(config),
@@ -446,9 +448,10 @@ export async function mergeSync(ctx, options, factory = createSyncBackend, resol
446
448
  // No backend call has begun: a stale candidate can be retired without ambiguous publication.
447
449
  const atCommitState = syncStateFingerprint(await timings.measure("transfer state read", () => readStateForConfig(config)));
448
450
  await validate();
449
- const atCommit = await timings.measure("transfer local snapshot", () => createSnapshot(config.snapshotIdentity, snapshotOptions));
451
+ const commitObservation = await timings.measure("transfer local snapshot", () => observeSnapshot(snapshotOptions));
450
452
  await validate();
451
- if (!sameHashes(fileHashMap(atCommit), fileHashMap(localRaw)) || atCommitState !== journal.stateIdentity) {
453
+ const atCommit = snapshotWithObservedInventory(refreshed, commitObservation);
454
+ if (!atCommit || atCommitState !== journal.stateIdentity) {
452
455
  await validateFresh();
453
456
  await clearMergeJournal(config);
454
457
  throw new ContinuousError("stale", "Local content or baseline changed before publication; candidate retired without transfer. Review a fresh sync.");
@@ -546,7 +549,7 @@ async function completeJournal(ctx, config, backend, journal, { validate, valida
546
549
  const readRetirementEvidence = async () => {
547
550
  const state = await timings.measure("transfer state read", () => readStateForConfig(config));
548
551
  await validateFresh();
549
- const local = await timings.measure("transfer local snapshot", () => createSnapshot(config.snapshotIdentity, snapshotOptions));
552
+ const local = await timings.measure("transfer local snapshot", () => observeSnapshot(snapshotOptions));
550
553
  validateMutation();
551
554
  const latest = await timings.measure("transfer remote head", () => backend.readHead(signal));
552
555
  validateMutation();