@narumitw/pi-sync-daemon 0.0.0-stage → 0.3.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 (267) hide show
  1. package/CHANGELOG.md +22 -0
  2. package/LICENSE +21 -0
  3. package/README.md +91 -2
  4. package/dist/cli.d.ts +2 -0
  5. package/dist/cli.js +127 -0
  6. package/dist/client.d.ts +57 -0
  7. package/dist/client.js +534 -0
  8. package/dist/consent.d.ts +24 -0
  9. package/dist/consent.js +205 -0
  10. package/dist/document.d.ts +10 -0
  11. package/dist/document.js +6 -0
  12. package/dist/endpoint.d.ts +8 -0
  13. package/dist/endpoint.js +91 -0
  14. package/dist/engine/backends/backend-factory.d.ts +6 -0
  15. package/dist/engine/backends/backend-factory.js +16 -0
  16. package/dist/engine/backends/backend-identity.d.ts +3 -0
  17. package/dist/engine/backends/backend-identity.js +38 -0
  18. package/dist/engine/backends/backend-types.d.ts +70 -0
  19. package/dist/engine/backends/backend-types.js +1 -0
  20. package/dist/engine/backends/git/git-backend.d.ts +55 -0
  21. package/dist/engine/backends/git/git-backend.js +700 -0
  22. package/dist/engine/backends/git/git-config.d.ts +5 -0
  23. package/dist/engine/backends/git/git-config.js +118 -0
  24. package/dist/engine/backends/git/git-runner.d.ts +25 -0
  25. package/dist/engine/backends/git/git-runner.js +232 -0
  26. package/dist/engine/backends/git/git-storage.d.ts +39 -0
  27. package/dist/engine/backends/git/git-storage.js +226 -0
  28. package/dist/engine/backends/s3/s3-backend.d.ts +32 -0
  29. package/dist/engine/backends/s3/s3-backend.js +436 -0
  30. package/dist/engine/backends/s3/s3-client.d.ts +36 -0
  31. package/dist/engine/backends/s3/s3-client.js +352 -0
  32. package/dist/engine/backends/s3/s3-conditions.d.ts +4 -0
  33. package/dist/engine/backends/s3/s3-conditions.js +66 -0
  34. package/dist/engine/backends/snapshot-pointer.d.ts +6 -0
  35. package/dist/engine/backends/snapshot-pointer.js +22 -0
  36. package/dist/engine/backends/sync-backend.d.ts +71 -0
  37. package/dist/engine/backends/sync-backend.js +23 -0
  38. package/dist/engine/backends/webdav/webdav-backend.d.ts +34 -0
  39. package/dist/engine/backends/webdav/webdav-backend.js +534 -0
  40. package/dist/engine/backends/webdav/webdav-client.d.ts +36 -0
  41. package/dist/engine/backends/webdav/webdav-client.js +326 -0
  42. package/dist/engine/backends/webdav/webdav-config.d.ts +5 -0
  43. package/dist/engine/backends/webdav/webdav-config.js +73 -0
  44. package/dist/engine/commands/command-types.d.ts +31 -0
  45. package/dist/engine/commands/command-types.js +1 -0
  46. package/dist/engine/host.d.ts +70 -0
  47. package/dist/engine/host.js +16 -0
  48. package/dist/engine/paths.d.ts +9 -0
  49. package/dist/engine/paths.js +71 -0
  50. package/dist/engine/settings/config-errors.d.ts +1 -0
  51. package/dist/engine/settings/config-errors.js +4 -0
  52. package/dist/engine/settings/config-file.d.ts +33 -0
  53. package/dist/engine/settings/config-file.js +630 -0
  54. package/dist/engine/settings/config.d.ts +24 -0
  55. package/dist/engine/settings/config.js +200 -0
  56. package/dist/engine/settings/settings-management.d.ts +24 -0
  57. package/dist/engine/settings/settings-management.js +191 -0
  58. package/dist/engine/settings/settings-store.d.ts +8 -0
  59. package/dist/engine/settings/settings-store.js +41 -0
  60. package/dist/engine/settings/settings-types.d.ts +134 -0
  61. package/dist/engine/settings/settings-types.js +1 -0
  62. package/dist/engine/settings/settings-validation.d.ts +15 -0
  63. package/dist/engine/settings/settings-validation.js +356 -0
  64. package/dist/engine/snapshot/session-paths.d.ts +12 -0
  65. package/dist/engine/snapshot/session-paths.js +91 -0
  66. package/dist/engine/snapshot/snapshot-apply.d.ts +22 -0
  67. package/dist/engine/snapshot/snapshot-apply.js +262 -0
  68. package/dist/engine/snapshot/snapshot-case-replacement.d.ts +15 -0
  69. package/dist/engine/snapshot/snapshot-case-replacement.js +82 -0
  70. package/dist/engine/snapshot/snapshot-codec.d.ts +6 -0
  71. package/dist/engine/snapshot/snapshot-codec.js +53 -0
  72. package/dist/engine/snapshot/snapshot-exclude-safety.d.ts +7 -0
  73. package/dist/engine/snapshot/snapshot-exclude-safety.js +47 -0
  74. package/dist/engine/snapshot/snapshot-mutation-queues.d.ts +9 -0
  75. package/dist/engine/snapshot/snapshot-mutation-queues.js +133 -0
  76. package/dist/engine/snapshot/snapshot-paths.d.ts +1 -0
  77. package/dist/engine/snapshot/snapshot-paths.js +11 -0
  78. package/dist/engine/snapshot/snapshot-root-transition.d.ts +25 -0
  79. package/dist/engine/snapshot/snapshot-root-transition.js +122 -0
  80. package/dist/engine/snapshot/snapshot-transaction-directory.d.ts +2 -0
  81. package/dist/engine/snapshot/snapshot-transaction-directory.js +16 -0
  82. package/dist/engine/snapshot/snapshot-transaction-plan.d.ts +12 -0
  83. package/dist/engine/snapshot/snapshot-transaction-plan.js +68 -0
  84. package/dist/engine/snapshot/snapshot-transaction.d.ts +15 -0
  85. package/dist/engine/snapshot/snapshot-transaction.js +787 -0
  86. package/dist/engine/snapshot/snapshot-types.d.ts +48 -0
  87. package/dist/engine/snapshot/snapshot-types.js +1 -0
  88. package/dist/engine/snapshot/snapshot.d.ts +30 -0
  89. package/dist/engine/snapshot/snapshot.js +364 -0
  90. package/dist/engine/state/json-file.d.ts +6 -0
  91. package/dist/engine/state/json-file.js +49 -0
  92. package/dist/engine/state/lock-policy.d.ts +2 -0
  93. package/dist/engine/state/lock-policy.js +2 -0
  94. package/dist/engine/state/lock.d.ts +20 -0
  95. package/dist/engine/state/lock.js +259 -0
  96. package/dist/engine/state/lockfile-fs.d.ts +13 -0
  97. package/dist/engine/state/lockfile-fs.js +13 -0
  98. package/dist/engine/state/merge-baseline-store.d.ts +11 -0
  99. package/dist/engine/state/merge-baseline-store.js +187 -0
  100. package/dist/engine/state/mutation-directory-sync.d.ts +5 -0
  101. package/dist/engine/state/mutation-directory-sync.js +34 -0
  102. package/dist/engine/state/operation-availability.d.ts +49 -0
  103. package/dist/engine/state/operation-availability.js +40 -0
  104. package/dist/engine/state/state-directory.d.ts +14 -0
  105. package/dist/engine/state/state-directory.js +225 -0
  106. package/dist/engine/state/state-types.d.ts +27 -0
  107. package/dist/engine/state/state-types.js +1 -0
  108. package/dist/engine/state/sync-state-store.d.ts +11 -0
  109. package/dist/engine/state/sync-state-store.js +54 -0
  110. package/dist/engine/sync/agent-candidate.d.ts +44 -0
  111. package/dist/engine/sync/agent-candidate.js +207 -0
  112. package/dist/engine/sync/agent-plan.d.ts +8 -0
  113. package/dist/engine/sync/agent-plan.js +84 -0
  114. package/dist/engine/sync/agent-policy.d.ts +9 -0
  115. package/dist/engine/sync/agent-policy.js +10 -0
  116. package/dist/engine/sync/agent-refusal-retry.d.ts +4 -0
  117. package/dist/engine/sync/agent-refusal-retry.js +39 -0
  118. package/dist/engine/sync/agent-request.d.ts +14 -0
  119. package/dist/engine/sync/agent-request.js +13 -0
  120. package/dist/engine/sync/agent-runner.d.ts +6 -0
  121. package/dist/engine/sync/agent-runner.js +183 -0
  122. package/dist/engine/sync/agent-store.d.ts +7 -0
  123. package/dist/engine/sync/agent-store.js +177 -0
  124. package/dist/engine/sync/agent-sync.d.ts +4 -0
  125. package/dist/engine/sync/agent-sync.js +132 -0
  126. package/dist/engine/sync/apply-review.d.ts +8 -0
  127. package/dist/engine/sync/apply-review.js +51 -0
  128. package/dist/engine/sync/conflict-artifact-ownership.d.ts +4 -0
  129. package/dist/engine/sync/conflict-artifact-ownership.js +53 -0
  130. package/dist/engine/sync/conflict-artifacts.d.ts +32 -0
  131. package/dist/engine/sync/conflict-artifacts.js +158 -0
  132. package/dist/engine/sync/conflict-groups.d.ts +9 -0
  133. package/dist/engine/sync/conflict-groups.js +76 -0
  134. package/dist/engine/sync/conflict-preview.d.ts +4 -0
  135. package/dist/engine/sync/conflict-preview.js +53 -0
  136. package/dist/engine/sync/conflict-resolution.d.ts +13 -0
  137. package/dist/engine/sync/conflict-resolution.js +53 -0
  138. package/dist/engine/sync/conflict-retention.d.ts +5 -0
  139. package/dist/engine/sync/conflict-retention.js +61 -0
  140. package/dist/engine/sync/conflict-review.d.ts +4 -0
  141. package/dist/engine/sync/conflict-review.js +73 -0
  142. package/dist/engine/sync/content-conflicts.d.ts +10 -0
  143. package/dist/engine/sync/content-conflicts.js +70 -0
  144. package/dist/engine/sync/continuous-errors.d.ts +14 -0
  145. package/dist/engine/sync/continuous-errors.js +66 -0
  146. package/dist/engine/sync/continuous-lease.d.ts +9 -0
  147. package/dist/engine/sync/continuous-lease.js +206 -0
  148. package/dist/engine/sync/continuous-record.d.ts +31 -0
  149. package/dist/engine/sync/continuous-record.js +199 -0
  150. package/dist/engine/sync/continuous-storage.d.ts +14 -0
  151. package/dist/engine/sync/continuous-storage.js +59 -0
  152. package/dist/engine/sync/continuous-sync.d.ts +15 -0
  153. package/dist/engine/sync/continuous-sync.js +496 -0
  154. package/dist/engine/sync/continuous-watch.d.ts +3 -0
  155. package/dist/engine/sync/continuous-watch.js +65 -0
  156. package/dist/engine/sync/exclude-policy.d.ts +5 -0
  157. package/dist/engine/sync/exclude-policy.js +79 -0
  158. package/dist/engine/sync/field-migration.d.ts +5 -0
  159. package/dist/engine/sync/field-migration.js +20 -0
  160. package/dist/engine/sync/file-merge-planner.d.ts +36 -0
  161. package/dist/engine/sync/file-merge-planner.js +123 -0
  162. package/dist/engine/sync/initialization.d.ts +12 -0
  163. package/dist/engine/sync/initialization.js +75 -0
  164. package/dist/engine/sync/json-document.d.ts +29 -0
  165. package/dist/engine/sync/json-document.js +172 -0
  166. package/dist/engine/sync/local-field-policy.d.ts +2 -0
  167. package/dist/engine/sync/local-field-policy.js +26 -0
  168. package/dist/engine/sync/local-fields.d.ts +9 -0
  169. package/dist/engine/sync/local-fields.js +116 -0
  170. package/dist/engine/sync/merge-apply.d.ts +5 -0
  171. package/dist/engine/sync/merge-apply.js +386 -0
  172. package/dist/engine/sync/merge-journal.d.ts +31 -0
  173. package/dist/engine/sync/merge-journal.js +179 -0
  174. package/dist/engine/sync/merge-transfer-error.d.ts +3 -0
  175. package/dist/engine/sync/merge-transfer-error.js +64 -0
  176. package/dist/engine/sync/merged-sync.d.ts +6 -0
  177. package/dist/engine/sync/merged-sync.js +618 -0
  178. package/dist/engine/sync/mutation-owner.d.ts +2 -0
  179. package/dist/engine/sync/mutation-owner.js +18 -0
  180. package/dist/engine/sync/package-merge.d.ts +3 -0
  181. package/dist/engine/sync/package-merge.js +82 -0
  182. package/dist/engine/sync/partial-progress.d.ts +15 -0
  183. package/dist/engine/sync/partial-progress.js +39 -0
  184. package/dist/engine/sync/remote-snapshot.d.ts +28 -0
  185. package/dist/engine/sync/remote-snapshot.js +62 -0
  186. package/dist/engine/sync/resolver-stream.d.ts +4 -0
  187. package/dist/engine/sync/resolver-stream.js +34 -0
  188. package/dist/engine/sync/session-merge.d.ts +3 -0
  189. package/dist/engine/sync/session-merge.js +178 -0
  190. package/dist/engine/sync/session-push.d.ts +5 -0
  191. package/dist/engine/sync/session-push.js +32 -0
  192. package/dist/engine/sync/settings-conflicts.d.ts +8 -0
  193. package/dist/engine/sync/settings-conflicts.js +56 -0
  194. package/dist/engine/sync/settings-merge.d.ts +13 -0
  195. package/dist/engine/sync/settings-merge.js +93 -0
  196. package/dist/engine/sync/signals.d.ts +2 -0
  197. package/dist/engine/sync/signals.js +8 -0
  198. package/dist/engine/sync/startup-timings.d.ts +11 -0
  199. package/dist/engine/sync/startup-timings.js +44 -0
  200. package/dist/engine/sync/sync-decision.d.ts +35 -0
  201. package/dist/engine/sync/sync-decision.js +66 -0
  202. package/dist/engine/sync/sync-error-guidance.d.ts +2 -0
  203. package/dist/engine/sync/sync-error-guidance.js +55 -0
  204. package/dist/engine/sync/sync-errors.d.ts +9 -0
  205. package/dist/engine/sync/sync-errors.js +18 -0
  206. package/dist/engine/sync/sync-inspection.d.ts +26 -0
  207. package/dist/engine/sync/sync-inspection.js +40 -0
  208. package/dist/engine/sync/sync-loaders.d.ts +7 -0
  209. package/dist/engine/sync/sync-loaders.js +8 -0
  210. package/dist/engine/sync/sync-local.d.ts +5 -0
  211. package/dist/engine/sync/sync-local.js +40 -0
  212. package/dist/engine/sync/sync-mutations.d.ts +30 -0
  213. package/dist/engine/sync/sync-mutations.js +589 -0
  214. package/dist/engine/sync/sync-operations.d.ts +2 -0
  215. package/dist/engine/sync/sync-operations.js +3 -0
  216. package/dist/engine/sync/sync-policy.d.ts +85 -0
  217. package/dist/engine/sync/sync-policy.js +356 -0
  218. package/dist/engine/sync/sync-queries.d.ts +7 -0
  219. package/dist/engine/sync/sync-queries.js +195 -0
  220. package/dist/engine/sync/sync-state.d.ts +31 -0
  221. package/dist/engine/sync/sync-state.js +92 -0
  222. package/dist/engine/sync/text-merge.d.ts +19 -0
  223. package/dist/engine/sync/text-merge.js +124 -0
  224. package/dist/engine/types.d.ts +5 -0
  225. package/dist/engine/types.js +2 -0
  226. package/dist/engine/ui/merge-review.d.ts +2 -0
  227. package/dist/engine/ui/merge-review.js +7 -0
  228. package/dist/engine/ui/merged-sync-summary.d.ts +25 -0
  229. package/dist/engine/ui/merged-sync-summary.js +86 -0
  230. package/dist/engine/ui/sync-format.d.ts +13 -0
  231. package/dist/engine/ui/sync-format.js +150 -0
  232. package/dist/engine/ui/sync-status.d.ts +9 -0
  233. package/dist/engine/ui/sync-status.js +30 -0
  234. package/dist/engine/ui/terminal-text.d.ts +3 -0
  235. package/dist/engine/ui/terminal-text.js +9 -0
  236. package/dist/engine/ui/transfer-changes.d.ts +12 -0
  237. package/dist/engine/ui/transfer-changes.js +24 -0
  238. package/dist/engine/ui/transfer-review.d.ts +3 -0
  239. package/dist/engine/ui/transfer-review.js +19 -0
  240. package/dist/engine-service.d.ts +14 -0
  241. package/dist/engine-service.js +322 -0
  242. package/dist/identity.d.ts +20 -0
  243. package/dist/identity.js +133 -0
  244. package/dist/idle-exit.d.ts +17 -0
  245. package/dist/idle-exit.js +77 -0
  246. package/dist/index.d.ts +8 -0
  247. package/dist/index.js +4 -0
  248. package/dist/lifecycle-log.d.ts +7 -0
  249. package/dist/lifecycle-log.js +53 -0
  250. package/dist/lifecycle.d.ts +2 -0
  251. package/dist/lifecycle.js +21 -0
  252. package/dist/model-signature.d.ts +2 -0
  253. package/dist/model-signature.js +7 -0
  254. package/dist/monitor.d.ts +14 -0
  255. package/dist/monitor.js +272 -0
  256. package/dist/participant-admission.d.ts +5 -0
  257. package/dist/participant-admission.js +30 -0
  258. package/dist/protocol.d.ts +102 -0
  259. package/dist/protocol.js +97 -0
  260. package/dist/resolver-host.d.ts +11 -0
  261. package/dist/resolver-host.js +78 -0
  262. package/dist/server.d.ts +24 -0
  263. package/dist/server.js +808 -0
  264. package/dist/service-host.d.ts +7 -0
  265. package/dist/service-host.js +174 -0
  266. package/docs/architecture.md +162 -0
  267. package/package.json +54 -4
@@ -0,0 +1,7 @@
1
+ import { type EngineContext } from "./engine/host.js";
2
+ import type { Execution } from "./protocol.js";
3
+ /** One service process owns one root; tests must use a separate process per root. */
4
+ export declare function installServiceHost(root: string): {
5
+ run<T>(execution: Execution, action: () => Promise<T>): Promise<T>;
6
+ };
7
+ export declare function createServiceContext(execution: Execution): EngineContext;
@@ -0,0 +1,174 @@
1
+ import { AsyncLocalStorage } from "node:async_hooks";
2
+ import { randomUUID } from "node:crypto";
3
+ import fs from "node:fs/promises";
4
+ import path from "node:path";
5
+ import lockfile from "proper-lockfile";
6
+ import { readConsent } from "./consent.js";
7
+ import { configureEngineHost } from "./engine/host.js";
8
+ import { canonicalRootGuard, processExists } from "./identity.js";
9
+ import { withCleanup } from "./lifecycle.js";
10
+ const scope = new AsyncLocalStorage();
11
+ /** One service process owns one root; tests must use a separate process per root. */
12
+ export function installServiceHost(root) {
13
+ let poisoned = false;
14
+ const assertRoot = canonicalRootGuard(root);
15
+ function current() {
16
+ const value = scope.getStore();
17
+ if (!value)
18
+ throw new Error("Engine access requires a daemon job.");
19
+ return value;
20
+ }
21
+ function protectedTarget(target, execution) {
22
+ const normalized = path.resolve(target);
23
+ if (execution.liveClients().some((peer) => peer.sessionFile && path.resolve(peer.sessionFile) === normalized))
24
+ throw new Error("A live client's session is protected, including after orderly exit.");
25
+ }
26
+ async function reserve(targets, action) {
27
+ const owner = current();
28
+ assertRoot();
29
+ if (poisoned)
30
+ throw new Error("Daemon ownership cleanup is uncertain; stop and reconcile before retrying.");
31
+ const missing = [...new Set(targets)].filter((target) => !owner.held.has(target)).sort();
32
+ if (!missing.length)
33
+ return action();
34
+ if (!owner.peers)
35
+ return owner.execution.withParticipants((peers) => scope.run({ ...owner, peers }, () => reserve(targets, action)));
36
+ owner.execution.validate();
37
+ for (const target of missing)
38
+ protectedTarget(target, owner.execution);
39
+ const peers = owner.peers.toSorted((a, b) => a.id.localeCompare(b.id));
40
+ const requested = [];
41
+ return withCleanup(async () => {
42
+ for (const peer of peers) {
43
+ owner.execution.validate();
44
+ const reservation = randomUUID();
45
+ requested.push({ client: peer.id, reservation });
46
+ await owner.execution.request("queue-acquire", { reservation, targets: missing, generation: peer.generation, background: !owner.execution.clientId }, peer.id);
47
+ owner.execution.validate();
48
+ }
49
+ for (const target of missing)
50
+ protectedTarget(target, owner.execution);
51
+ return await scope.run({ ...owner, held: new Set([...owner.held, ...missing]) }, action);
52
+ }, async () => {
53
+ // Release by request identity even when a grant response was lost. A cancelled
54
+ // prompt is not evidence that a granted remote writer stopped.
55
+ const results = await Promise.allSettled(requested.map(({ client, reservation }) => {
56
+ const peer = peers.find((peer) => peer.id === client);
57
+ return peer && !processExists(peer.pid)
58
+ ? Promise.resolve(true)
59
+ : owner.execution.request("queue-release", { reservation }, client);
60
+ }));
61
+ const failure = results.find((result) => result.status === "rejected");
62
+ if (failure?.status === "rejected") {
63
+ poisoned = true;
64
+ throw new Error("File-queue release is uncertain; stop the daemon and keep grants quarantined until owner exit.", { cause: failure.reason });
65
+ }
66
+ });
67
+ }
68
+ configureEngineHost({
69
+ allowConfigMigration: () => Boolean(readConsent(root)),
70
+ root: () => {
71
+ assertRoot();
72
+ if (poisoned)
73
+ throw new Error("Daemon ownership cleanup is uncertain; stop and reconcile before restarting.");
74
+ return root;
75
+ },
76
+ reserveTargets: reserve,
77
+ mutate: async (target, action) => reserve([target], async () => {
78
+ const owner = current();
79
+ protectedTarget(target, owner.execution);
80
+ const { withFileMutationQueue } = await import("@earendil-works/pi-coding-agent");
81
+ owner.execution.validate();
82
+ return withFileMutationQueue(target, async () => {
83
+ const settings = path.resolve(target) === path.join(root, "settings.json");
84
+ let release;
85
+ if (settings) {
86
+ // Pi's absent-file branch does not reread after locking. Do not race it.
87
+ const info = await fs.lstat(target).catch((error) => {
88
+ if (error.code === "ENOENT")
89
+ return undefined;
90
+ throw error;
91
+ });
92
+ if (!info && owner.execution.liveClients().length)
93
+ throw new Error("Cannot create settings.json while a Pi client is alive; create it through Pi first.");
94
+ if (info?.isSymbolicLink())
95
+ throw new Error("Refusing an aliased settings file.");
96
+ release = await lockfile.lock(target, { realpath: false });
97
+ }
98
+ return withCleanup(async () => {
99
+ owner.execution.validate();
100
+ protectedTarget(target, owner.execution);
101
+ return action();
102
+ }, async () => {
103
+ try {
104
+ await release?.();
105
+ }
106
+ catch (error) {
107
+ poisoned = true;
108
+ throw error;
109
+ }
110
+ });
111
+ });
112
+ }),
113
+ review: async (_ctx, request, signal, isCurrent) => {
114
+ if (!isCurrent() || signal?.aborted)
115
+ return false;
116
+ const result = await current().execution.request("merge-review", request, undefined, signal);
117
+ return result === true && isCurrent() && !signal?.aborted;
118
+ },
119
+ status: (_ctx, value, presentation) => current().execution.emit("status", { value, presentation }),
120
+ });
121
+ return {
122
+ run(execution, action) {
123
+ return scope.run({ execution, held: new Set() }, action);
124
+ },
125
+ };
126
+ }
127
+ export function createServiceContext(execution) {
128
+ const initial = execution.facts();
129
+ if (!initial)
130
+ throw new Error("This operation needs an attached client.");
131
+ const facts = () => execution.facts() ?? initial;
132
+ const ask = async (kind, payload, signal) => {
133
+ execution.validate();
134
+ return execution.request(kind, payload, undefined, signal);
135
+ };
136
+ return {
137
+ cwd: initial.cwd,
138
+ mode: initial.mode,
139
+ get hasUI() {
140
+ return facts().hasUI;
141
+ },
142
+ // Resolver initialization replaces these only for explicitly model-capable jobs.
143
+ modelRegistry: {
144
+ streamSimple: () => {
145
+ throw new Error("The standalone resolver is unavailable.");
146
+ },
147
+ },
148
+ sessionManager: {
149
+ getSessionFile: () => facts().sessionFile,
150
+ getSessionId: () => facts().sessionId ?? "",
151
+ getCwd: () => facts().cwd,
152
+ getSessionDir: () => facts().sessionDir ?? path.join(execution.root, "sessions"),
153
+ usesDefaultSessionDir: () => facts().sessionDir === undefined,
154
+ },
155
+ get protectedSessionFiles() {
156
+ return execution.liveClients().flatMap((peer) => (peer.sessionFile ? [peer.sessionFile] : []));
157
+ },
158
+ isIdle: () => execution.participants().every((peer) => peer.idle),
159
+ reload: async () => {
160
+ await ask("reload", {});
161
+ },
162
+ ui: {
163
+ notify: (message, level = "info") => execution.emit("notify", { message, level }),
164
+ setStatus: (_key, value) => execution.emit("status", { value }),
165
+ confirm: async (title, message, options) => (await ask("confirm", { title, message }, options?.signal)) === true,
166
+ select: async (title, items, options) => {
167
+ const result = await ask("select", { title, items, helpText: options?.helpText }, options?.signal);
168
+ if (typeof result !== "string" || !items.includes(result))
169
+ return undefined;
170
+ return result;
171
+ },
172
+ },
173
+ };
174
+ }
@@ -0,0 +1,162 @@
1
+ # Ownership and safety contract
2
+
3
+ This package owns the existing Pi Sync engine and a root-bound local service. Process lifetime is not permission to transfer files or invoke a model. The current implementation is under development; this document does not establish release readiness.
4
+
5
+ ## Boundaries
6
+
7
+ ```mermaid
8
+ flowchart LR
9
+ Pi[Pi presentation and live session] -->|Authenticated local protocol| API[Daemon API]
10
+ API --> Jobs[Serialized jobs]
11
+ Jobs --> Engine[Existing synchronization engine]
12
+ Engine --> Files[Selected files and recovery journals]
13
+ Engine --> Backend[Git WebDAV S3 R2]
14
+ Engine --> Resolver[Isolated resolver]
15
+ Engine -->|Acquire and acknowledge release| PiQueue[Participating Pi mutation queues]
16
+ ```
17
+
18
+ `src/index.ts` exposes the lightweight IPC client, wire types, and hashes. It must not import the service, backend, watcher, or model runtime. `src/engine-service.ts` dispatches a closed operation set. `src/engine/host.ts` defines the engine's process boundary. The daemon never imports another extension or loads user extensions.
19
+
20
+ `@narumitw/pi-sync-daemon` is a non-extension library and Node service in `packages/pi-sync-daemon/`, with `pi-sync-daemon` as its executable. The `pi-` prefix identifies its Pi Sync scope; it does not declare `pi.extensions`. The rename preserves existing IPC namespaces, authorization digests, and settings/state formats. The Pi client retains its own UI, commands, and status protocol.
21
+
22
+ ## Authoritative documents
23
+
24
+ | Document | Writer | Coordination and recovery |
25
+ | --- | --- | --- |
26
+ | `pi-sync.json` and compatible legacy configuration | Daemon settings writer | Existing complete read/validate/update queue, cross-process config lock, private same-directory replacement, exact source identity/bytes check |
27
+ | `settings.json` selected by synchronization | Daemon apply transaction; Pi core remains an independent writer | Participating public file queues plus the actual Pi settings-file lock; revalidate preimages inside ownership |
28
+ | Selected settings/resources/sessions | Daemon apply transaction; tools/editors remain independent writers | Public client queue reservations, protected-session union, original preimages/backups/journals |
29
+ | `pi-sync/`, legacy `.pisync/` | Existing engine state writer in daemon | Existing operation lock, explicit migration guard, journal recovery; no automatic destructive migration |
30
+ | IPC identity/client ledger | Local server | Private root-bound namespace; atomic identity publication; ambiguous and orderly retired live sessions survive restart |
31
+ | `pi-sync/daemon.json` | Daemon consent owner | Bounded private atomic publication in one event-loop turn; exact policy/config/binding checks after review; interactive binding changes durably revoke prior unattended grants |
32
+ | `auth.json`, `models.json` | Public Pi SDK APIs only | No private credential parsing or parent credential copying; settle SDK credential writes before exit |
33
+
34
+ Read-only display state is not a second settings writer. A client proposes a validated new document with the exact source fingerprint; the authoritative writer checks the fingerprint under its settings lock. A stale editor must reopen rather than merge a stale approval automatically. Invalid existing JSON remains intact. Unknown fields remain in the proposed source clone.
35
+
36
+ ## Context inventory
37
+
38
+ | Former Pi dependency | Engine host boundary | Source |
39
+ | --- | --- | --- |
40
+ | `getAgentDir()` | Explicit canonical service root | `engine/host.ts`, `engine/snapshot/session-paths.ts` |
41
+ | `ctx.cwd`, session directory/current session | Plain client facts, generation-bound getters | `protocol.ts`, `service-host.ts` |
42
+ | `ctx.isIdle()` | Current participating-client facts, not a captured Pi context | `service-host.ts` |
43
+ | Protected sessions and missing-settings guard | All live client PIDs, including retired clients; separate from active participation | `server.ts`, `service-host.ts` |
44
+ | `ctx.ui.notify`, status | Bounded events | `server.ts`, `service-host.ts` |
45
+ | Confirm/select/exact merge review | Job-bound callbacks; revalidation after response | `service-host.ts`, `engine/ui/merge-review.ts` |
46
+ | Reload | Explicit client callback after the existing user confirmation | `engine/sync/sync-mutations.ts` |
47
+ | `ctx.model`, `modelRegistry.streamSimple` | Explicit selected model identity/signature; independent public SDK runtime | `model-signature.ts`, `resolver-host.ts` |
48
+ | `withFileMutationQueue` | Participating Pi queue grants plus daemon-local queue | `service-host.ts`, Pi adapter `daemon/apply-gate.ts` |
49
+
50
+ Terminal formatting utilities are not interactive components. No daemon-owned menu, editor, or Pi custom UI is permitted. Exact review content stays data until the client renders it with its original UI and sanitization rules.
51
+
52
+ ## Decision and failure matrix
53
+
54
+ | Branch/equivalence class | Required outcome | Verification |
55
+ | --- | --- | --- |
56
+ | First client / simultaneous clients | Canonical root startup lock; one lifetime owner; readiness identity matches version/root/instance | Process singleton tests |
57
+ | Distinct canonical roots / root aliases | Independent owners / same canonical owner | Server and process tests |
58
+ | Existing healthy identity | Connect; do not spawn | Handshake tests |
59
+ | Existing live but unreachable owner | Refuse a second owner | Startup failure tests |
60
+ | Dead known owner / another instance endpoint / replaced endpoint or ancestor | Use a fresh private instance namespace / leave old entries intact / retire the current namespace and retain unknown entries before Node closes | Endpoint tests |
61
+ | Incompatible version/root/instance/token | Reject before any operation | Protocol tests |
62
+ | Same operation ID, identical input | Return existing result; never redispatch | Replay tests |
63
+ | Same ID, changed input / expired result | Refuse; reconcile existing journal | Replay/eviction tests |
64
+ | Cancel before submit / queued / waiting for review | Tombstone / abort before dispatch / abort UI callback | Cancellation tests |
65
+ | Cancel or detach after commit | Finish existing journal/publication bookkeeping, not a second publication | Recovery tests |
66
+ | Active sessions in two clients | Protect their union, including alternate session roots | Multi-client apply tests |
67
+ | Lost connection with live PID / timeout | Retain protection and queue uncertainty; not proof of exit | Ambiguous-disconnection tests |
68
+ | Confirmed daemon exit | Release quarantined Pi grants only after ESRCH | Apply-gate tests |
69
+ | Busy participating client / changed generation | Stop or refuse automatic work; invalidate stale approval | Lifecycle tests |
70
+ | Directional sync / remote-selection decision across IPC | Restore the typed decision for command and recovery routing; preserve the existing resolution menu | Actual daemon error-routing tests |
71
+ | Pi edit/write during apply, inside or outside the agent root | Hold the actual public Pi queue; recheck preimages | Real `createEditTool` race tests |
72
+ | Reviewed external session destination / different peer session roots | Reserve every participant's canonical target queues; do not restrict coordination to its current roots | Actual two-client Pi RPC pull tests |
73
+ | Client joins during queue grant, apply, or release | Delay attach publication through the full reservation lifetime; include the new client in the next batch | Admission tests for print, JSON, and RPC clients, nested writes, cancellation, shutdown, and hook re-entry |
74
+ | Pi core settings update, existing file | Share its `proper-lockfile` file lock | Settings writer race tests |
75
+ | Missing `settings.json` with a live Pi | Refuse creation; Pi's missing-file branch does not reread after lock | Missing-settings contract test |
76
+ | Arbitrary unregistered writer | Existing optimistic checks only; no universal filesystem CAS claim | Existing snapshot race suites and documented limitation |
77
+ | No authorized model / parent-only provider | Resolver unavailable; no fallback model or extension loading | Resolver-host tests |
78
+ | Different serialized model definition, including key order | Resolver unavailable; preserve conflict and legacy request-budget identity | Signature and provider tests |
79
+ | Missing independent credentials | Public SDK failure; no parent-runtime key extraction | Synthetic resolver tests |
80
+ | No resolver request / cancellation after credential runtime creation | Metadata uses memory credentials without auth refresh / settle already-started SDK credential writes before releasing owner | Resolver lifecycle tests |
81
+ | Model output / stale candidate / refusal | Candidate only / revalidate all evidence / retain budget and refusal policy | Existing agent suites |
82
+ | No registered live PID and no valid active-setup after-exit grant / explicit CLI start without clients | Fixed 30-second grace, then quiesce and drain before safe exit; no final sync or inference | Lifecycle timer and process tests |
83
+ | Registered live PID, including passive, disconnected, publishing, or retired clients / uncertain PID probe | Retain lifetime and session protection; detach or heartbeat loss is not proof of exit | Live-PID and lifecycle tests |
84
+ | Client arrives during grace or quiescing, before final closing boundary | Cancel automatic exit; preserve one owner through admission | Admission and reattachment race tests |
85
+ | Valid active-setup grant / temporarily unavailable provider or backend | Retain lifetime under existing consent, fingerprint, and binding rules; no new work permission or availability probe | Consent and monitor tests |
86
+ | Uncertain consent publication, failed revocation, or cleanup failure | Stay paused; retain evidence and repair/revoke before explicit restart, without restoring an older grant | Consent failure and shutdown tests |
87
+ | Recognized closing owner / next eligible interactive client | Bounded cancellable wait; prove old-owner exit before singleton replacement; passive clients never launch | Closing-owner startup tests |
88
+ | Print/JSON, no existing service / existing service | No launch / passive protection and automatic-work pause; never an implicit unattended grant | Bootstrap and actual-session-facts tests |
89
+ | Orderly exit / ambiguous disconnection / replacement handoff | Retain live-PID file protection without active participation / pause and retain protection / require matching published successor | Server, handoff, and native post-exit model tests |
90
+ | Config/model/consent changes during unattended review | Reject before publication, preserving new data | Consent tests |
91
+ | Interactive model/cwd/session-root changes after grant | Durably revoke older grants; reverting or restarting does not restore permission | Consent restart tests |
92
+ | Legacy continuous/agent options Off | Remain Off; service lifetime does not change policy | Policy regression suites |
93
+ | Validated foreground sync for the active setup | Retry a persistent Continuous block once without resetting calls or candidate attempts | Actual Pi RPC authentication-repair test; typed-failure accounting tests |
94
+ | Other setup / cancelled or replaced origin / disabled policy / shutdown | Never force an unrelated or stale retry; retain intent while only busy | Monitor lifecycle and setup-scope tests |
95
+
96
+ The source-linked matrix is the audit contract, not a list of already completed checks. The implementation plan records actual results separately.
97
+
98
+ ## Automatic service lifetime
99
+
100
+ The daemon owns lifetime for one canonical agent directory and its registered client PIDs, not every Pi process on the machine. Live disconnected, passive, publishing, and orderly retired clients count. `/reload`, `/new`, fork, and resume do not close the shared owner while their Pi process remains alive. An empty participant list, detach, transport failure, or heartbeat timeout is not proof of process exit.
101
+
102
+ When no registered live PID remains and no valid explicit after-exit grant covers the active setup, start a fixed 30-second grace period. The same policy applies to a service explicitly started without clients. A client arriving before the final closing boundary cancels automatic exit. Grants for other setups, revoked grants, and stale fingerprints do not preserve lifetime. Temporary provider or backend unavailability does not itself revoke a valid grant. Lifetime checks reuse existing consent authority without calling a model, contacting a provider or storage, executing credential commands, or changing authorization. No setting, environment variable, or keep-alive flag controls this policy.
103
+
104
+ After grace, stop new automatic work and cancel cancellable work. Drain foreground and monitor work, committed writes, admission, queue-release acknowledgements, peer persistence, and owned callbacks before endpoint and owner-lock release. Do not add a closing sync or model request. Preserve journals, backups, request accounting, and existing transfer permissions. Recheck liveness, consent, generation, and ownership after asynchronous reads or drains; the final admission boundary must let an earlier queued attach win and make a later attach observe closing. Cleanup failure is not successful exit.
105
+
106
+ After quiescence, the authenticated final fence returns `RemoteError.name = "DaemonStoppingError"` to rejected admissions and handshakes on the existing version-1 protocol. `ensureDaemon()` recognizes only this error and waits at most 30 seconds for the recorded PID to exit before singleton startup. The lightweight public `waitForDaemonExit(identity, signal)` helper provides the same cancellable process-exit check for an attach race; it never kills the owner or treats lost contact as exit. Pi Sync retries only an unpublished connection, at most once, and does not replay submitted operations. A rejected first attach preserves this stopping error after local disposal when no callbacks or prior attachment can own grants; a failed cleanup transport remains available as the error cause. Other combined attach and cleanup failures remain aggregate errors and do not authorize a retry. `DaemonConnection.attach(signal)` cancels queued admission without stopping the shared owner; the signal does not own the established connection's lifetime. The next eligible interactive client or explicit command may start after proven owner exit. An incompatible identity, uncertain ownership, or unreachable live owner still fails closed. Print/JSON never launch a service. Manual stop and restart retain explicit behavior. Authorization uncertainty and failed revocation remain paused, not cleared by an implicit restart that could restore an older persisted grant.
107
+
108
+ A later command can reconnect after a cancelled or failed unpublished attach. First, Pi Sync confirms the old connection's detach and drain, then releases its local queue grants. It uses a fresh client ID and generation for the next connection. Daemon retirement records stay intact, so late requests cannot revive the old attempt. Failed cleanup blocks a new identity and operation; it does not release uncertain grants. The established connection keeps its identity. A cancelled or submitted operation is never replayed by this recovery.
109
+
110
+ ## Repository lifetime smoke
111
+
112
+ After the repository build, run the standalone real-clock smoke from the repository root. It loads the built package directory through real Pi RPC, tests no-client CLI exit and last-Pi exit, restarts through the next eligible Pi, and retains an explicitly reviewed grant beyond the grace period. It uses only owned loopback provider/storage fixtures and preserves recovery bytes. It takes about two minutes; it is not a Vitest case.
113
+
114
+ ```sh
115
+ npm exec -- tsc -p tsconfig.test.json
116
+ cp -R packages/pi-sync/test/fixtures node_modules/.cache/pi-extensions-test/packages/pi-sync/test/
117
+ node node_modules/.cache/pi-extensions-test/packages/pi-sync/test/idle-exit-cli-smoke.js
118
+ ```
119
+
120
+ Do not rebuild while a smoke-owned daemon is running. Linux containers need an init process to reap detached children. This smoke does not verify native Windows behavior, terminal logout, physical power loss, or real-data cutover.
121
+
122
+ ## Cross-process apply protocol
123
+
124
+ Acquire target queues in deterministic client-ID and canonical-target order. Each reservation has a job-bound ID and the peer's session generation. The client holds Pi's public queues until the daemon acknowledges completion with a `queue-release` callback. Release uses the reservation ID even if the grant response was lost. A cancelled UI callback does not release an acquired grant. If IPC disappears, hold the grant until explicit release or proof that its daemon process exited. A timeout is not such proof.
125
+
126
+ Batch reservations cover the transaction, not only each rename. `Execution.withParticipants()` fences attach publication from the peer snapshot through every grant, nested write, and acknowledged release. Nested reservations share that fence instead of reacquiring it. An attach queued behind an apply cannot finish startup until the reservation ends; the next batch includes that client. Cancelled waiters cannot publish later, and shutdown drains admission. Attach has no idle request timeout: a legitimate long apply must not let startup escape the fence. Transport disconnection cancels queued admission, and the Pi adapter pauses or disposes its partial connection without waiting for attach to finish. Other local requests retain their timeout. Monitoring hooks run outside the fence because they can await a queued background reservation.
127
+
128
+ Nested writes retain the transaction's queue ownership. Validate paths and canonical parents before reservation and recheck session protection and preimages after every await that can change them. The daemon's own Pi queue alone is insufficient.
129
+
130
+ A queue grant coordinates access; it does not authorize a filesystem write. The engine owns destination selection, transfer review, path preflight, and session protection. A reviewed session destination can be outside the agent directory and every participant's current session root. Each client must reserve those bounded absolute canonical targets without imposing a second current-root policy. Otherwise a directional root transition or a peer with a different session root can block an otherwise valid transfer.
131
+
132
+ Pi core's settings storage has separate existing-file and missing-file branches (`FileSettingsStorage.withLock()` in the installed SDK). Existing files lock before reading. Missing files compute the update before acquiring the file lock and do not reread afterward. Therefore creation with live Pi clients is refused, rather than claiming that the shared lock repairs this branch.
133
+
134
+ These guarantees cover cooperating registered clients. Unregistered old Pi versions, external editors, shell commands, and arbitrary extensions remain independent writers. Preserve conservative preimage checks, recovery evidence, and explicit upgrade preconditions.
135
+
136
+ ## Explicit Continuous retry
137
+
138
+ Validated `/sync sync` and manager **Sync now** requests record the requesting client's last target setup. Startup transfers, status reads, and separate refusal retries do not set this intent. Keep intents separate across clients, and retain them while another client is busy. Cancellation, session-generation replacement, disabled Continuous policy, and service shutdown cannot carry an old intent into a later activation.
139
+
140
+ At the next eligible monitor start, recheck the origin, generation, and cancellation signal, then consume the intents once. Pass a matching setup name to the existing Continuous instance. The engine checks that name after its own settings read and lease acquisition, so an intervening setup change cannot force another binding. This bypasses a repaired persistent failure, not request accounting: existing calls, candidate attempts, leases, consent, and budget limits remain authoritative.
141
+
142
+ ## Native runtime boundaries
143
+
144
+ Each POSIX instance binds inside an exclusively created 0700 directory; this parent, not a post-bind pathname chmod, is the access boundary. Node/libuv unlinks its original Unix socket pathname even when a regular file or ancestor symlink replaced it. After jobs and release acknowledgements drain, move the instance directory entry into a private retained container before closing Node's listener. Delete only the recognized socket and empty owned directories. Keep unknown files/symlinks for recovery. If the namespace cannot be retired, retain the live closed-to-work owner and require a permissions repair and explicit stop retry.
145
+
146
+ The model signature hashes the exact existing JSON serialization. Equal hashes preserve the engine's existing candidate keys and Continuous configuration identity; a definition with different serialization is unavailable, not a reason to reset budgets. Static metadata uses an in-memory credential store and no refresh. Only an actual resolver transport creates the public SDK credential runtime. Its final public `transformHeaders` hook revalidates capability and evidence after auth awaits, without returning header values to Pi.
147
+
148
+ Unattended permission stores a setup/policy digest and an independent model/location binding, not a former Pi context. Normal closed clients remain in the durable protected-session ledger while their PID is alive but do not block zero-client scheduling; ambiguous losses and replacement gaps do. `Execution.liveClients()` supplies file protection and the missing-settings guard, while `Execution.participants()` supplies queue reservations and work eligibility. An unrelated attach or daemon restart does not remove retired protection. Only confirmed PID exit or a matching published replacement releases the corresponding record. A consent publication failure latches automatic work off for that service instance and prevents automatic exit from silently clearing the barrier. Failed revocation or uncertain consent must not restore an older persisted grant through implicit restart; retain the paused owner and evidence, repair persistence, and revoke the retained grant before an explicit restart.
149
+
150
+ The resolver uses independently available agent-root `auth.json`/`models.json` configuration and the environment captured at service start. Credential commands execute non-interactively from the canonical agent root, not from a former Pi working directory. Handover must disclose this provider/account boundary; changing the service environment requires a restart. Parent runtime accounts, registered providers, and conversations are not copied.
151
+
152
+ Persistent credential semantics remain those of the supported public SDK, including its path/lock assumptions; stop the service and drain Pi before relocating the agent root or replacing auth storage out of band. Do not claim a stronger credential-store filesystem CAS than the SDK provides.
153
+
154
+ ## Legacy-process handover
155
+
156
+ An absent operation lock proves only that no observed transfer holds it, not that an idle old Pi process is absent. Before first daemon-owned mutation, require an explicit reviewed handover that instructs the operator to close or upgrade every old Pi process. Hold the existing operation lock while publishing the private root-bound handover record. Never silently fall back to the old engine. Existing operation locks still prevent competing observed transfers; older binaries cannot be made to honor a new marker retroactively.
157
+
158
+ Rollback requires explicit service stop and verified owner exit, preserved journals/backups, and closing all upgraded clients before running an older engine. Do not restore old settings bytes or downgrade over a pending/newer journal.
159
+
160
+ ## Platforms
161
+
162
+ Use a private Unix-domain socket on POSIX and a root/user-bound named pipe on Windows. No TCP listener is needed. POSIX ownership, mode, and inode checks are testable on Linux. Native Windows ACL/process behavior and macOS terminal/logout behavior require native maintainer evidence before advertising new guarantees; retain the previous package's limitations explicitly in the migration record.
package/package.json CHANGED
@@ -1,6 +1,56 @@
1
1
  {
2
2
  "name": "@narumitw/pi-sync-daemon",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.3.0",
4
+ "description": "A local synchronization daemon with a versioned client API.",
5
+ "type": "module",
6
+ "license": "MIT",
7
+ "engines": {
8
+ "node": ">=22.19.0"
9
+ },
10
+ "main": "./dist/index.js",
11
+ "types": "./dist/index.d.ts",
12
+ "exports": {
13
+ ".": {
14
+ "types": "./dist/index.d.ts",
15
+ "default": "./dist/index.js"
16
+ },
17
+ "./engine/*": {
18
+ "types": "./dist/engine/*.d.ts",
19
+ "default": "./dist/engine/*.js"
20
+ }
21
+ },
22
+ "bin": {
23
+ "pi-sync-daemon": "./dist/cli.js"
24
+ },
25
+ "files": [
26
+ "dist",
27
+ "docs",
28
+ "README.md",
29
+ "LICENSE",
30
+ "CHANGELOG.md"
31
+ ],
32
+ "scripts": {
33
+ "build": "node scripts/build.mjs",
34
+ "typecheck": "tsc --noEmit",
35
+ "prepack": "npm run build"
36
+ },
37
+ "dependencies": {
38
+ "@earendil-works/pi-ai": "^1.5.2",
39
+ "@earendil-works/pi-coding-agent": "^1.5.2",
40
+ "@earendil-works/pi-tui": "^1.5.2",
41
+ "fast-xml-parser": "^5.12.0",
42
+ "minimatch": "^11.0.3",
43
+ "proper-lockfile": "^4.1.2",
44
+ "semver": "^7.8.6"
45
+ },
46
+ "devDependencies": {
47
+ "@types/proper-lockfile": "^4.1.4",
48
+ "@types/semver": "^7.8.0",
49
+ "typescript": "7.0.2"
50
+ },
51
+ "repository": {
52
+ "type": "git",
53
+ "url": "https://github.com/narumiruna/pi-extensions",
54
+ "directory": "packages/pi-sync-daemon"
55
+ }
56
+ }