@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
@@ -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();
@@ -8,6 +8,9 @@ import { syncPolicyChanged } from "./sync-state.js";
8
8
  async function readValidatedSnapshotForHead(backend, head, signal) {
9
9
  const snapshot = await backend.readSnapshot(head.snapshotRef, signal);
10
10
  throwIfAborted(signal);
11
+ return validateSnapshotForHead(snapshot, head);
12
+ }
13
+ function validateSnapshotForHead(snapshot, head) {
11
14
  validatePortableSnapshot(snapshot);
12
15
  if (snapshot.id !== head.snapshotId) {
13
16
  throw new Error(`Remote head ${head.snapshotId} resolved to unexpected snapshot ${snapshot.id}.`);
@@ -105,10 +108,10 @@ function safeList(values) {
105
108
  return values.length > 0 ? values.map(safeTerminalText).join(", ") : "none";
106
109
  }
107
110
  export async function readRemoteSnapshot(backend, config, signal, options = {}) {
108
- const head = await backend.readHead(signal);
109
- if (!head)
111
+ const observed = await readCurrentSnapshot(backend, config.scope === "agent-directory", signal);
112
+ if (!observed)
110
113
  return { head: undefined, snapshot: undefined, selectionState: undefined };
111
- const rawSnapshot = await readValidatedSnapshotForHead(backend, head, signal);
114
+ const { head, snapshot: rawSnapshot } = observed;
112
115
  const selectionState = inspectRemoteSelection(config.include, rawSnapshot, config.exclude, config);
113
116
  if (!options.allowSelectionDifference && selectionState.kind === "different")
114
117
  throw selectionMismatch(config, selectionState);
@@ -117,3 +120,15 @@ export async function readRemoteSnapshot(backend, config, signal, options = {})
117
120
  : filterSnapshotForConfigPolicy(rawSnapshot, config, { sessionDir: options.sessionDir });
118
121
  return { head, snapshot, selectionState };
119
122
  }
123
+ async function readCurrentSnapshot(backend, singleObservation, signal) {
124
+ if (singleObservation && backend.readHeadAndSnapshot) {
125
+ const observed = await backend.readHeadAndSnapshot(signal);
126
+ throwIfAborted(signal);
127
+ if (observed)
128
+ validateSnapshotForHead(observed.snapshot, observed.head);
129
+ return observed;
130
+ }
131
+ const head = await backend.readHead(signal);
132
+ throwIfAborted(signal);
133
+ return head && { head, snapshot: await readValidatedSnapshotForHead(backend, head, signal) };
134
+ }
@@ -9,6 +9,7 @@ import { syncSessionsSelected } from "./sync-policy.js";
9
9
  import { hasLocalChanges, syncPolicyChanged } from "./sync-state.js";
10
10
  /** Existing legacy policy; service ownership/consent is established by its caller. */
11
11
  export async function pushSessionsOnShutdown(ctx, options, loaders = { operations: () => import("./sync-operations.js") }) {
12
+ const note = options.noteDebugOutcome;
12
13
  const validate = captureMutationOwner(ctx, options.signal);
13
14
  const config = await loadConfigForCheck(undefined, options.signal);
14
15
  validate();
@@ -25,23 +26,31 @@ export async function pushSessionsOnShutdown(ctx, options, loaders = { operation
25
26
  if (fingerprint !== syncCheckConfigFingerprint(latest))
26
27
  throw new Error("Settings changed before automatic session push.");
27
28
  };
28
- if (!config.automatic || !syncSessionsSelected(config))
29
+ if (!config.automatic || !syncSessionsSelected(config)) {
30
+ note?.("skipped");
29
31
  return;
32
+ }
30
33
  await withStateDirectoryAccess(() => withLock("auto-session-push", async () => {
31
34
  await refresh();
32
35
  const state = await readStateForConfig(config);
33
36
  await refresh();
34
- if ((config.scope || state.scope) && (!state.lastAppliedSnapshot || syncPolicyChanged(state, config)))
37
+ if ((config.scope || state.scope) && (!state.lastAppliedSnapshot || syncPolicyChanged(state, config))) {
38
+ note?.("blocked");
35
39
  return;
40
+ }
36
41
  const snapshotOptions = await resolvedSnapshotOptionsForContext(ctx, config, options.signal);
37
42
  await refresh();
38
43
  const local = await createSnapshot(config.snapshotIdentity, snapshotOptions);
39
44
  await refresh();
40
- if (!hasLocalChanges(local, state, config))
45
+ if (!hasLocalChanges(local, state, config)) {
46
+ note?.("skipped");
41
47
  return;
48
+ }
42
49
  const operations = await loaders.operations();
43
50
  await refresh();
44
- await operations.push(ctx, { ...options, auto: true, yes: true, silent: true, reload: false }, { config, state, local });
51
+ const result = await operations.push(ctx, { ...options, auto: true, yes: true, silent: true, reload: false }, { config, state, local });
45
52
  validate();
53
+ if (result === "cancelled")
54
+ note?.("cancelled");
46
55
  }));
47
56
  }
@@ -0,0 +1 @@
1
+ export declare function captureStartupBootstrap(root: string, expected: string, signal: AbortSignal, reviewOwnsLock?: () => boolean): (() => boolean) | undefined;
@@ -0,0 +1,105 @@
1
+ import { closeSync, constants, fstatSync, lstatSync, openSync, readSync } from "node:fs";
2
+ import path from "node:path";
3
+ import { readConsent } from "../../consent.js";
4
+ import { documentFingerprint } from "../../document.js";
5
+ import { MAX_SETTINGS_BYTES } from "../../protocol.js";
6
+ import { configFromSettings } from "../settings/config.js";
7
+ import { legacyLocalConfigPath, localConfigPath } from "../settings/config-file.js";
8
+ import { validateSettingsDocument } from "../settings/settings-validation.js";
9
+ import { stateDirectoryMigrationNotice } from "../state/state-directory.js";
10
+ import { statePathForConfig } from "../state/sync-state-store.js";
11
+ import { startupRecoveryEvidence } from "./startup-recovery-evidence.js";
12
+ function inspect(target) {
13
+ return lstatSync(target, { bigint: true, throwIfNoEntry: false });
14
+ }
15
+ function sameFile(before, now) {
16
+ return (now?.isFile() &&
17
+ now.dev === before.dev &&
18
+ now.ino === before.ino &&
19
+ now.size === before.size &&
20
+ now.mode === before.mode &&
21
+ now.ctimeNs === before.ctimeNs &&
22
+ now.mtimeNs === before.mtimeNs);
23
+ }
24
+ function readCanonicalSettings() {
25
+ const target = localConfigPath();
26
+ const mayNeedWrite = () => Boolean(inspect(legacyLocalConfigPath()) || inspect(`${target}.mutation-lock`));
27
+ if (mayNeedWrite())
28
+ return;
29
+ const before = inspect(target);
30
+ if (!before?.isFile() ||
31
+ before.size > MAX_SETTINGS_BYTES ||
32
+ (process.getuid && before.uid !== BigInt(process.getuid())) ||
33
+ (process.platform !== "win32" && (before.mode & 511n) !== 384n))
34
+ return;
35
+ const fd = openSync(target, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
36
+ try {
37
+ if (!sameFile(before, fstatSync(fd, { bigint: true })))
38
+ return;
39
+ const bytes = Buffer.alloc(Number(before.size) + 1);
40
+ let offset = 0;
41
+ while (offset < bytes.length) {
42
+ const count = readSync(fd, bytes, offset, bytes.length - offset, offset);
43
+ if (!count)
44
+ break;
45
+ offset += count;
46
+ }
47
+ if (offset !== Number(before.size) ||
48
+ !sameFile(before, fstatSync(fd, { bigint: true })) ||
49
+ !sameFile(before, inspect(target)) ||
50
+ mayNeedWrite())
51
+ return;
52
+ return {
53
+ bytes: bytes.subarray(0, offset),
54
+ fingerprint: documentFingerprint({
55
+ bytes: bytes.subarray(0, offset).toString("base64"),
56
+ identity: { dev: Number(before.dev), ino: Number(before.ino) },
57
+ }),
58
+ };
59
+ }
60
+ finally {
61
+ closeSync(fd);
62
+ }
63
+ }
64
+ export function captureStartupBootstrap(root, expected, signal, reviewOwnsLock) {
65
+ signal.throwIfAborted();
66
+ if (stateDirectoryMigrationNotice())
67
+ return;
68
+ const recovery = startupRecoveryEvidence(root, reviewOwnsLock);
69
+ if (recovery === undefined)
70
+ return;
71
+ const consent = readConsent(root);
72
+ if (!consent)
73
+ return;
74
+ const document = readCanonicalSettings();
75
+ if (document?.fingerprint !== expected)
76
+ return;
77
+ let parsed;
78
+ try {
79
+ parsed = JSON.parse(document.bytes.toString("utf8"));
80
+ }
81
+ catch {
82
+ return;
83
+ }
84
+ const settings = validateSettingsDocument(parsed);
85
+ if (!settings.activeSyncSetup)
86
+ return;
87
+ const config = configFromSettings(settings);
88
+ if (config.reservedIgnoreNames)
89
+ return;
90
+ const stateFile = statePathForConfig(config);
91
+ const noMergeJournal = () => {
92
+ const setupDirectory = inspect(path.dirname(stateFile));
93
+ return !setupDirectory || (setupDirectory.isDirectory() && !inspect(`${stateFile}.merge-journal.json`));
94
+ };
95
+ const consentToken = JSON.stringify(consent);
96
+ const validate = () => {
97
+ signal.throwIfAborted();
98
+ return (readCanonicalSettings()?.fingerprint === expected &&
99
+ !stateDirectoryMigrationNotice() &&
100
+ JSON.stringify(readConsent(root)) === consentToken &&
101
+ noMergeJournal() &&
102
+ startupRecoveryEvidence(root, reviewOwnsLock) === recovery);
103
+ };
104
+ return noMergeJournal() && startupRecoveryEvidence(root, reviewOwnsLock) === recovery ? validate : undefined;
105
+ }
@@ -0,0 +1 @@
1
+ export declare function startupRecoveryEvidence(root: string, reviewOwnsLock?: () => boolean): string | undefined;
@@ -0,0 +1,37 @@
1
+ import { lstatSync, opendirSync } from "node:fs";
2
+ import path from "node:path";
3
+ import { stateDir } from "../state/state-directory.js";
4
+ function stamp(info) {
5
+ return info && `${info.dev}:${info.ino}:${info.ctimeNs}:${info.mtimeNs}`;
6
+ }
7
+ function inspect(target) {
8
+ return lstatSync(target, { bigint: true, throwIfNoEntry: false });
9
+ }
10
+ export function startupRecoveryEvidence(root, reviewOwnsLock) {
11
+ const state = stateDir(root);
12
+ const transactions = path.join(state, "transactions");
13
+ const guard = path.join(root, ".pi-sync-state-migration.lock");
14
+ const lock = path.join(state, "lock");
15
+ const protectedState = () => state === stateDir(root) &&
16
+ !inspect(guard) &&
17
+ (reviewOwnsLock ? reviewOwnsLock() : !inspect(lock) && !inspect(`${lock}.guard`));
18
+ if (!protectedState())
19
+ return;
20
+ const parent = inspect(state);
21
+ const pending = inspect(transactions);
22
+ if (pending) {
23
+ if (!pending.isDirectory())
24
+ return;
25
+ const directory = opendirSync(transactions, { bufferSize: 1 });
26
+ try {
27
+ if (directory.readSync())
28
+ return;
29
+ }
30
+ finally {
31
+ directory.closeSync();
32
+ }
33
+ }
34
+ if (!protectedState() || stamp(parent) !== stamp(inspect(state)) || stamp(pending) !== stamp(inspect(transactions)))
35
+ return;
36
+ return JSON.stringify([state, stamp(parent), stamp(pending)]);
37
+ }
@@ -1,11 +1,18 @@
1
1
  import type { EngineContext as ExtensionContext } from "../host.js";
2
- type StartupStage = "daemon initialization" | "transaction recovery" | "settings read" | "config resolution" | "inspection import" | "inspection and guards" | "backend initialization" | "local snapshot" | "sync state read" | "remote head" | "operations import" | "automatic transfer" | "transfer authorization" | "transfer backend initialization" | "transfer journal read" | "transfer journal recovery" | "transfer state read" | "transfer local snapshot" | "transfer remote head" | "transfer snapshot download" | "transfer unchanged verification" | "transfer merge planning" | "transfer settings merge" | "transfer content merge" | "transfer preflight" | "transfer backup" | "transfer journal write" | "transfer remote publication" | "transfer local apply" | "transfer baseline write" | "transfer cleanup";
2
+ declare const startupStages: readonly ["daemon initialization", "transaction recovery", "settings read", "config resolution", "inspection import", "inspection and guards", "backend initialization", "local snapshot", "sync state read", "remote head", "operations import", "automatic transfer", "transfer authorization", "transfer backend initialization", "transfer journal read", "transfer journal recovery", "transfer state read", "transfer local snapshot", "transfer remote head", "transfer snapshot download", "transfer unchanged verification", "transfer merge planning", "transfer settings merge", "transfer content merge", "transfer preflight", "transfer backup", "transfer journal write", "transfer remote publication", "transfer local apply", "transfer baseline write", "transfer cleanup"];
3
+ declare const startupScopes: readonly ["local initialization", "background startup", "continuous startup", "daemon inspection", "daemon transfer"];
4
+ declare const outcomes: readonly ["completed", "stopped"];
5
+ type StartupStage = (typeof startupStages)[number];
6
+ type StartupScope = (typeof startupScopes)[number];
7
+ type StartupOutcome = (typeof outcomes)[number];
8
+ export declare function isStartupTimingReport(value: string): boolean;
3
9
  export type StartupTimingPublisher = (ctx: ExtensionContext, report: string) => void;
4
10
  /** Fixed labels and durations only: never retain errors, paths, settings, or payloads. */
5
11
  export declare function createStartupTimings(publishReport?: StartupTimingPublisher): {
6
12
  markUnchanged(): void;
13
+ wasUnchanged: () => boolean;
7
14
  measure<T>(stage: StartupStage, run: () => T | Promise<T>): Promise<T>;
8
- publish(ctx: ExtensionContext, enabled: boolean, sessionSignal: AbortSignal, scope: "local initialization" | "background startup" | "continuous startup" | "daemon inspection" | "daemon transfer", outcome?: "completed" | "stopped"): void;
15
+ publish(ctx: ExtensionContext, enabled: boolean, sessionSignal: AbortSignal, scope: StartupScope, outcome?: StartupOutcome, observe?: (report: string) => void): void;
9
16
  };
10
17
  export type StartupTimings = ReturnType<typeof createStartupTimings>;
11
18
  export {};
@@ -1,4 +1,68 @@
1
1
  import { performance } from "node:perf_hooks";
2
+ const startupStages = [
3
+ "daemon initialization",
4
+ "transaction recovery",
5
+ "settings read",
6
+ "config resolution",
7
+ "inspection import",
8
+ "inspection and guards",
9
+ "backend initialization",
10
+ "local snapshot",
11
+ "sync state read",
12
+ "remote head",
13
+ "operations import",
14
+ "automatic transfer",
15
+ "transfer authorization",
16
+ "transfer backend initialization",
17
+ "transfer journal read",
18
+ "transfer journal recovery",
19
+ "transfer state read",
20
+ "transfer local snapshot",
21
+ "transfer remote head",
22
+ "transfer snapshot download",
23
+ "transfer unchanged verification",
24
+ "transfer merge planning",
25
+ "transfer settings merge",
26
+ "transfer content merge",
27
+ "transfer preflight",
28
+ "transfer backup",
29
+ "transfer journal write",
30
+ "transfer remote publication",
31
+ "transfer local apply",
32
+ "transfer baseline write",
33
+ "transfer cleanup",
34
+ ];
35
+ const startupScopes = [
36
+ "local initialization",
37
+ "background startup",
38
+ "continuous startup",
39
+ "daemon inspection",
40
+ "daemon transfer",
41
+ ];
42
+ const outcomes = ["completed", "stopped"];
43
+ const unchangedLine = "transfer result: unchanged (fast path)";
44
+ const end = "(?![\\s\\S])";
45
+ const duration = "(?:0|[1-9][0-9]{0,15})\\.[0-9] ms";
46
+ const headingPattern = new RegExp(`^pi-sync debug: (?:${startupScopes.join("|")}) \\((?:${outcomes.join("|")})\\)${end}`, "u");
47
+ const stagePattern = new RegExp(`^(${startupStages.join("|")}): ${duration}(?: \\((?:[2-9]|[1-9][0-9]{1,15}) calls\\))?(?: \\(interrupted\\))?${end}`, "u");
48
+ const totalPattern = new RegExp(`^total: ${duration}${end}`, "u");
49
+ export function isStartupTimingReport(value) {
50
+ if (value.length > 4096)
51
+ return false;
52
+ const lines = value.split("\n");
53
+ if (!headingPattern.test(lines.shift() ?? "") || !totalPattern.test(lines.pop() ?? ""))
54
+ return false;
55
+ if (lines.at(-1) === unchangedLine)
56
+ lines.pop();
57
+ const seen = new Set();
58
+ for (const line of lines) {
59
+ const stage = stagePattern.exec(line)?.[1];
60
+ if (!stage || seen.has(stage))
61
+ return false;
62
+ seen.add(stage);
63
+ }
64
+ return true;
65
+ }
2
66
  /** Fixed labels and durations only: never retain errors, paths, settings, or payloads. */
3
67
  export function createStartupTimings(publishReport = (ctx, report) => ctx.ui.notify(report, "info")) {
4
68
  const started = performance.now();
@@ -8,6 +72,7 @@ export function createStartupTimings(publishReport = (ctx, report) => ctx.ui.not
8
72
  markUnchanged() {
9
73
  unchanged = true;
10
74
  },
75
+ wasUnchanged: () => unchanged,
11
76
  async measure(stage, run) {
12
77
  const start = performance.now();
13
78
  let completed = false;
@@ -25,16 +90,23 @@ export function createStartupTimings(publishReport = (ctx, report) => ctx.ui.not
25
90
  });
26
91
  }
27
92
  },
28
- publish(ctx, enabled, sessionSignal, scope, outcome = "completed") {
29
- if (!enabled || !ctx.hasUI || sessionSignal.aborted)
93
+ publish(ctx, enabled, sessionSignal, scope, outcome = "completed", observe) {
94
+ const display = enabled && ctx.hasUI && !sessionSignal.aborted;
95
+ if (!display && !observe)
30
96
  return;
97
+ const report = [
98
+ `pi-sync debug: ${scope} (${outcome})`,
99
+ ...Array.from(stages, ([stage, value]) => `${stage}: ${value.ms.toFixed(1)} ms${value.calls > 1 ? ` (${value.calls} calls)` : ""}${value.interrupted ? " (interrupted)" : ""}`),
100
+ ...(unchanged ? [unchangedLine] : []),
101
+ `total: ${(performance.now() - started).toFixed(1)} ms`,
102
+ ].join("\n");
103
+ try {
104
+ observe?.(report);
105
+ }
106
+ catch { }
31
107
  try {
32
- publishReport(ctx, [
33
- `pi-sync debug: ${scope} (${outcome})`,
34
- ...Array.from(stages, ([stage, value]) => `${stage}: ${value.ms.toFixed(1)} ms${value.calls > 1 ? ` (${value.calls} calls)` : ""}${value.interrupted ? " (interrupted)" : ""}`),
35
- ...(unchanged ? ["transfer result: unchanged (fast path)"] : []),
36
- `total: ${(performance.now() - started).toFixed(1)} ms`,
37
- ].join("\n"));
108
+ if (display)
109
+ publishReport(ctx, report);
38
110
  }
39
111
  catch {
40
112
  // Diagnostics must not change sync behavior if the UI is unavailable during teardown.
@@ -1,3 +1,4 @@
1
+ import { OWNERSHIP_CLEANUP_REQUIRED } from "../../protocol.js";
1
2
  import { errorMessage } from "./sync-errors.js";
2
3
  /** Add recovery advice without changing backend outcome semantics or printing error causes. */
3
4
  export function syncErrorGuidance(error) {
@@ -6,7 +7,11 @@ export function syncErrorGuidance(error) {
6
7
  const code = error?.code;
7
8
  const status = error?.status;
8
9
  let next;
9
- if (code === "ENOSPC") {
10
+ if (code === OWNERSHIP_CLEANUP_REQUIRED) {
11
+ next =
12
+ "Open /sync and choose Stop daemon for recovery, or run /sync daemon recover. Do not retry the transfer yet.";
13
+ }
14
+ else if (code === "ENOSPC") {
10
15
  next = "Free disk space for the private pi-sync settings/state directory, then retry.";
11
16
  }
12
17
  else if (code && ["EACCES", "EPERM", "EROFS"].includes(code)) {
@@ -15,20 +20,33 @@ export function syncErrorGuidance(error) {
15
20
  else if (code && ["EBUSY", "EIO", "EMFILE", "ENFILE"].includes(code)) {
16
21
  next = "Check local disk availability and other processes using the private settings file, then retry.";
17
22
  }
23
+ else if (/\bagent directory exceeds the scan entry bound\b/iu.test(message)) {
24
+ next =
25
+ "Reduce the number of entries Pi Sync must scan before retrying. Exclude whole subdirectories to skip their contents. Use /sync config to review the active scope.";
26
+ }
27
+ else if (/\bprojected agent directory exceeds the (64 MiB scan byte|scan file) bound\b/iu.test(message)) {
28
+ next =
29
+ "The resulting files would exceed the sync limit. Review the current scope with /sync config and reduce the local or incoming sync content before retrying.";
30
+ }
31
+ else if (/\bagent directory exceeds the (64 MiB scan byte|scan file) bound\b/iu.test(message)) {
32
+ next =
33
+ "Reduce the files managed by this setup before retrying. Use /sync config to find the active ignore file, or edit Agent directory scope in /sync → Settings for legacy rules.";
34
+ }
18
35
  else if (/changed while|type changed|reopen/iu.test(message)) {
19
36
  next = "Reopen the item in /sync and review its current settings before saving again.";
20
37
  }
21
38
  else if (status === 401 ||
22
39
  status === 403 ||
23
40
  /Permission denied|Authentication failed|HTTP (401|403)|failed \((401|403)\)/iu.test(message)) {
24
- next = "Check the storage connection's credentials and remote permissions in /sync → More → Storage connections.";
41
+ next =
42
+ "Check the storage connection's credentials and remote permissions. In the TUI, open /sync → Settings → Manage storage connections.";
25
43
  }
26
44
  else if (status === 404 || /HTTP 404|failed \(404\)/iu.test(message)) {
27
45
  next =
28
46
  "Verify the connection address and setup's bucket, branch, or path with your provider; this response alone does not prove which resource is missing.";
29
47
  }
30
48
  else if (status !== undefined && status >= 500) {
31
- next = "Check your storage provider's service status, then retry Check setup before syncing.";
49
+ next = "Check your storage provider's service status, then run /sync doctor before syncing.";
32
50
  }
33
51
  else if (/timed out|timeout|request failed|resolve host|Could not resolve|ENOTFOUND|ECONNREFUSED/iu.test(message)) {
34
52
  next = "Check the server address and network connection, then run /sync doctor for the affected setup.";
@@ -49,7 +67,7 @@ export function syncErrorGuidance(error) {
49
67
  "Correct the named field or item in /sync. If the settings file is invalid, repair it before retrying; do not replace it with defaults.";
50
68
  }
51
69
  else {
52
- next = "Open /sync → More → Check setup and review the reported checks before retrying.";
70
+ next = "For setup and storage checks, run /sync doctor or choose Diagnostics in /sync.";
53
71
  }
54
72
  return `${message}\n${next}`;
55
73
  }
@@ -1,18 +1,17 @@
1
- import { createHash } from "node:crypto";
2
1
  import { createSyncBackend } from "../backends/backend-factory.js";
3
- import { createSnapshot } from "../snapshot/snapshot.js";
2
+ import { observeSnapshot } from "../snapshot/snapshot.js";
4
3
  import { readStateForConfig, syncStateFingerprint } from "../state/sync-state-store.js";
5
4
  import { inspectHeadSelection } from "./remote-snapshot.js";
6
5
  import { throwIfAborted } from "./signals.js";
7
6
  import { createStartupTimings } from "./startup-timings.js";
8
7
  import { syncSelectionHasContent } from "./sync-policy.js";
9
- import { fileHashMap, hasLocalChanges, remoteChangedSinceState } from "./sync-state.js";
8
+ import { hasLocalChanges, rawSnapshotHashIdentity, remoteChangedSinceState } from "./sync-state.js";
10
9
  /** Advisory baseline-relative observation, never an authorization to transfer files. */
11
10
  export async function inspectSync(config, options, signal, factory = createSyncBackend, timings = createStartupTimings()) {
12
11
  throwIfAborted(signal);
13
12
  const backend = await timings.measure("backend initialization", () => factory(config));
14
13
  throwIfAborted(signal);
15
- const local = await timings.measure("local snapshot", () => createSnapshot(config.snapshotIdentity, { ...options, signal }));
14
+ const local = await timings.measure("local snapshot", () => observeSnapshot({ ...options, signal }, Boolean(config.localFields?.length)));
16
15
  throwIfAborted(signal);
17
16
  const state = await timings.measure("sync state read", () => readStateForConfig(config));
18
17
  throwIfAborted(signal);
@@ -21,9 +20,7 @@ export async function inspectSync(config, options, signal, factory = createSyncB
21
20
  const selectionState = head ? await inspectHeadSelection(backend, config, head, signal) : undefined;
22
21
  throwIfAborted(signal);
23
22
  const freshness = {
24
- localIdentity: createHash("sha256")
25
- .update(JSON.stringify(fileHashMap(local)))
26
- .digest("hex"),
23
+ localIdentity: rawSnapshotHashIdentity(local),
27
24
  };
28
25
  return {
29
26
  ...freshness,
@@ -1,5 +1,6 @@
1
1
  import type { EngineContext as ExtensionCommandContext, EngineContext as ExtensionContext } from "../host.js";
2
- import type { SnapshotOptions } from "../snapshot/snapshot-types.js";
2
+ import type { Snapshot, SnapshotOptions } from "../snapshot/snapshot-types.js";
3
3
  export declare function protectedSessionPaths(ctx: ExtensionCommandContext | ExtensionContext, sessionRoot?: string | undefined): Set<string>;
4
4
  export { captureMutationOwner } from "./mutation-owner.js";
5
5
  export declare function backupLocal(profile: string, options?: SnapshotOptions, signal?: AbortSignal): Promise<string>;
6
+ export declare function backupSnapshot(snapshot: Snapshot, signal?: AbortSignal): Promise<string>;