@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
@@ -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)) {
@@ -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>;
@@ -19,7 +19,9 @@ export function protectedSessionPaths(ctx, sessionRoot = sessionDirFromContext(c
19
19
  export { captureMutationOwner } from "./mutation-owner.js";
20
20
  export async function backupLocal(profile, options = {}, signal) {
21
21
  throwIfAborted(signal);
22
- const snapshot = await createSnapshot(profile, { ...options, signal });
22
+ return backupSnapshot(await createSnapshot(profile, { ...options, signal }), signal);
23
+ }
24
+ export async function backupSnapshot(snapshot, signal) {
23
25
  throwIfAborted(signal);
24
26
  const backupDirectory = path.join(stateDir(), "backups");
25
27
  await fs.mkdir(backupDirectory, { recursive: true, mode: 0o700 });
@@ -422,6 +422,7 @@ export async function syncBoth(ctx, options, factory = createSyncBackend) {
422
422
  if (!options.auto && syncSelectionHasContent(config) && state.lastAppliedSnapshot)
423
423
  return mergeSync(ctx, options, factory);
424
424
  if (!syncSelectionHasContent(config)) {
425
+ options.noteDebugOutcome?.("skipped");
425
426
  if (!options.silent) {
426
427
  ctx.ui.notify(`Sync setup “${config.setupName}” includes no files. Choose included content in /sync Settings before syncing.`, "warning");
427
428
  }
@@ -512,7 +513,8 @@ export async function syncBoth(ctx, options, factory = createSyncBackend) {
512
513
  directMessage: "Remote settings match, but local and remote Pi sessions differ. Run /sync diff, then manually choose /sync pull or /sync push.",
513
514
  });
514
515
  }
515
- await pullInitialSource();
516
+ if ((await pullInitialSource()) === "cancelled")
517
+ options.noteDebugOutcome?.("cancelled");
516
518
  return;
517
519
  }
518
520
  await acceptMatchingState(remote);
@@ -531,16 +533,20 @@ export async function syncBoth(ctx, options, factory = createSyncBackend) {
531
533
  return;
532
534
  }
533
535
  if (remoteChanged) {
534
- await pullInitialSource();
536
+ if ((await pullInitialSource()) === "cancelled")
537
+ options.noteDebugOutcome?.("cancelled");
535
538
  return;
536
539
  }
537
540
  if (localChanged || !remote) {
538
- await push(ctx, options, { config, state, local, backend }, factory);
541
+ if ((await push(ctx, options, { config, state, local, backend }, factory)) === "cancelled")
542
+ options.noteDebugOutcome?.("cancelled");
539
543
  return;
540
544
  }
541
545
  if (shouldRefreshSyncedState(remote, head, state, config, (left, right) => backend.sameRevision(left, right))) {
542
546
  await acceptMatchingState(remote);
543
547
  }
548
+ else
549
+ options.noteDebugOutcome?.("skipped");
544
550
  if (!options.silent)
545
551
  ctx.ui.notify("pi-sync is already up to date.", "info");
546
552
  }
@@ -11,6 +11,8 @@ export declare function selectionForSnapshot(include: unknown, exclude?: unknown
11
11
  /** Metadata equality, not policy compatibility: bind the whole projection to its immutable image. */
12
12
  export declare function sameSnapshotSelection(left: SnapshotSelection | undefined, right: SnapshotSelection | undefined): boolean;
13
13
  export declare function validateSnapshotSelection(snapshot: Pick<Snapshot, "version" | "selection">): void;
14
+ export declare function assertSnapshotPathExcludesDebugLog(filePath: unknown): void;
15
+ export declare function assertSnapshotExcludesDebugLog(snapshot: Pick<Snapshot, "files">): void;
14
16
  export declare function requireLegacyTransferPolicy(snapshot: Partial<Pick<Snapshot, "version" | "selection">>): void;
15
17
  export declare function sameSyncInclude(left: unknown, right: unknown): boolean;
16
18
  export declare function compareSyncInclude(local: unknown, remote: unknown): {
@@ -1,6 +1,6 @@
1
1
  import { createHash } from "node:crypto";
2
2
  import path from "node:path";
3
- import { isDeniedPath, toPosix } from "../paths.js";
3
+ import { DEBUG_LOG_FILENAME, isDebugLogPath, isDeniedPath, toPosix } from "../paths.js";
4
4
  import { IGNORE_SNAPSHOT_VERSION, } from "../snapshot/snapshot-types.js";
5
5
  import { compilePathRules, compileSyncExclude, normalizeSyncExclude, sameSyncExclude } from "./exclude-policy.js";
6
6
  export const BUILT_IN_SYNC_ROOTS = [
@@ -202,6 +202,14 @@ export function validateSnapshotSelection(snapshot) {
202
202
  if ((snapshot.version === IGNORE_SNAPSHOT_VERSION) !== (selection?.version === 4))
203
203
  throw new Error("Ignore-file policy requires snapshot version 6 and selection version 4.");
204
204
  }
205
+ export function assertSnapshotPathExcludesDebugLog(filePath) {
206
+ if (typeof filePath === "string" && isDebugLogPath(filePath))
207
+ throw new Error(`Snapshot contains the local-only ${DEBUG_LOG_FILENAME}. Review the old snapshot before retrying sync.`);
208
+ }
209
+ export function assertSnapshotExcludesDebugLog(snapshot) {
210
+ for (const file of snapshot.files)
211
+ assertSnapshotPathExcludesDebugLog(file?.path);
212
+ }
205
213
  export function requireLegacyTransferPolicy(snapshot) {
206
214
  if (snapshot.version === IGNORE_SNAPSHOT_VERSION || snapshot.selection?.version === 4)
207
215
  throw new Error("This setup cannot transfer an ignore-file snapshot without a reviewed local ignore policy.");
@@ -1,5 +1,5 @@
1
1
  import type { RemoteHead } from "../backends/sync-backend.js";
2
- import type { Snapshot } from "../snapshot/snapshot-types.js";
2
+ import type { Snapshot, SnapshotFileHash, SnapshotObservation } from "../snapshot/snapshot-types.js";
3
3
  import type { SyncState } from "../state/state-types.js";
4
4
  import { type SyncSelectionConfig } from "./sync-policy.js";
5
5
  type SyncPolicyConfig = SyncSelectionConfig & {
@@ -7,13 +7,18 @@ type SyncPolicyConfig = SyncSelectionConfig & {
7
7
  setupName?: string;
8
8
  ignoreSourceIdentity?: string;
9
9
  };
10
- export declare function hasLocalChanges(local: Snapshot, state: SyncState, config: SyncPolicyConfig): boolean;
10
+ export declare function hasLocalChanges(local: Snapshot | SnapshotObservation, state: SyncState, config: SyncPolicyConfig): boolean;
11
11
  export declare function remoteChangedSinceState(head: RemoteHead | undefined, state: SyncState, config: SyncPolicyConfig, sameRevision: (left: string, right: string) => boolean): boolean;
12
12
  export declare function hasRemoteChanges(remote: Snapshot, state: SyncState, config: SyncPolicyConfig, ignoredPaths?: Set<string>): boolean;
13
13
  export declare function sameHashes(left: Record<string, string>, right: Record<string, string>): boolean;
14
- export declare function fileHashMap(snapshot: Snapshot): {
14
+ export declare function fileHashMap(snapshot: {
15
+ files: readonly SnapshotFileHash[];
16
+ }): {
15
17
  [k: string]: string;
16
18
  };
19
+ export declare function rawSnapshotHashIdentity(snapshot: {
20
+ files: readonly SnapshotFileHash[];
21
+ }): string;
17
22
  export declare function snapshotHashesMatchState(snapshot: Snapshot, state: SyncState, config: SyncPolicyConfig, ignoredPaths?: Set<string>): boolean;
18
23
  export declare function snapshotsMatch(left: Snapshot, right: Snapshot): boolean;
19
24
  export declare function syncPolicyChanged(state: SyncState, config: SyncPolicyConfig): boolean;
@@ -1,14 +1,17 @@
1
+ import { createHash } from "node:crypto";
1
2
  import { toPosix } from "../paths.js";
2
3
  import { canonicalSnapshotPathForConfig, filterSnapshotForConfigPolicy, isSessionPath } from "../snapshot/snapshot.js";
3
4
  import { sameSyncExclude } from "./exclude-policy.js";
4
- import { portableSnapshot, sameLocalFields } from "./local-fields.js";
5
+ import { portableObservation, portableSnapshot, sameLocalFields } from "./local-fields.js";
5
6
  import { compareIgnorePolicy, configuredSnapshotPathMatcher, customIncludePathsByLower, includeFromSelectionConfig, localIgnorePolicyKey, normalizeSyncInclude, syncDirectoryPolicyKey, syncSessionsSelected, } from "./sync-policy.js";
6
7
  export function hasLocalChanges(local, state, config) {
7
- return ((Boolean(state.lastAppliedSnapshot) &&
8
+ if (state.lastAppliedSnapshot &&
8
9
  (state.scope !== config.scope ||
9
10
  !sameLocalFields(state.localFields, config.localFields) ||
10
- !sameSelectionRules(state, config))) ||
11
- !sameHashes(fileHashMap(portableSnapshot(local, config.localFields)), stateHashMapForConfig(state, config)));
11
+ !sameSelectionRules(state, config)))
12
+ return true;
13
+ const portable = "version" in local ? portableSnapshot(local, config.localFields) : portableObservation(local, config.localFields);
14
+ return !sameHashes(fileHashMap(portable), stateHashMapForConfig(state, config));
12
15
  }
13
16
  export function remoteChangedSinceState(head, state, config, sameRevision) {
14
17
  if (!head)
@@ -46,6 +49,11 @@ export function sameHashes(left, right) {
46
49
  export function fileHashMap(snapshot) {
47
50
  return Object.fromEntries(snapshot.files.map((file) => [file.path, file.sha256]));
48
51
  }
52
+ export function rawSnapshotHashIdentity(snapshot) {
53
+ return createHash("sha256")
54
+ .update(JSON.stringify(fileHashMap(snapshot)))
55
+ .digest("hex");
56
+ }
49
57
  function stateHashMapForConfig(state, config) {
50
58
  const includePaths = customIncludePathsByLower(includeFromSelectionConfig(config));
51
59
  const configured = configuredSnapshotPathMatcher(config);
@@ -1,9 +1,15 @@
1
+ import { captureStartupReviewLock } from "./engine/state/lock.js";
1
2
  import { type Execute } from "./protocol.js";
2
3
  /** Engine dispatch is loaded only by the service, never by the public IPC client. */
3
4
  export declare function createEngineService(root: string, ignoreFileSettingsAvailable?: boolean): {
4
5
  execute: Execute;
5
6
  bind: (value: Awaited<ReturnType<typeof import("./server.js").startServer>>) => void;
6
7
  hooks: {
8
+ diagnostic: import("./daemon-debug.js").DaemonDiagnosticSink;
9
+ startup: {
10
+ captureReviewLock: typeof captureStartupReviewLock;
11
+ probe(fingerprint: string, signal: AbortSignal, reviewLock?: () => boolean): Promise<(() => boolean) | undefined>;
12
+ };
7
13
  factsChanged: () => Promise<void>;
8
14
  idle: () => void;
9
15
  close: () => Promise<void>;