@narumitw/pi-sync-daemon 0.2.0 → 0.4.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.
- package/CHANGELOG.md +19 -0
- package/README.md +4 -2
- package/dist/cli.js +7 -8
- package/dist/client.d.ts +24 -2
- package/dist/client.js +235 -31
- package/dist/engine-service.d.ts +3 -0
- package/dist/engine-service.js +8 -1
- package/dist/idle-exit.d.ts +17 -0
- package/dist/idle-exit.js +77 -0
- package/dist/index.d.ts +2 -2
- package/dist/index.js +1 -1
- package/dist/monitor.d.ts +3 -0
- package/dist/monitor.js +35 -8
- package/dist/protocol.d.ts +19 -0
- package/dist/protocol.js +14 -0
- package/dist/server.d.ts +6 -0
- package/dist/server.js +235 -16
- package/docs/architecture.md +51 -2
- package/package.json +1 -1
package/dist/server.js
CHANGED
|
@@ -1,13 +1,15 @@
|
|
|
1
1
|
import { createHash, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
|
|
2
|
+
import { addAbortListener } from "node:events";
|
|
2
3
|
import fs from "node:fs/promises";
|
|
3
4
|
import { createServer } from "node:http";
|
|
4
5
|
import path from "node:path";
|
|
5
6
|
import lockfile from "proper-lockfile";
|
|
6
7
|
import { endpointOwner } from "./endpoint.js";
|
|
7
8
|
import { canonicalRootGuard, daemonPaths, privateDirectory, processExists, publishIdentity, readIdentity, readJsonBody, runtimePaths, } from "./identity.js";
|
|
9
|
+
import { createIdleExit } from "./idle-exit.js";
|
|
8
10
|
import { withCleanup } from "./lifecycle.js";
|
|
9
11
|
import { ParticipantAdmission } from "./participant-admission.js";
|
|
10
|
-
import { MAX_MESSAGE_BYTES, MAX_REVIEW_BYTES, operationPrefix, PROTOCOL_VERSION, REVIEW_PAGE_CHARS, record, remoteError, validateFacts, validateHandoff, validId, } from "./protocol.js";
|
|
12
|
+
import { ClientContactExpiredError, DaemonStoppingError, MAX_MESSAGE_BYTES, MAX_REVIEW_BYTES, operationPrefix, PROTOCOL_VERSION, REVIEW_PAGE_CHARS, record, remoteError, validateFacts, validateHandoff, validId, } from "./protocol.js";
|
|
11
13
|
export async function startServer(root, execute, hooks = {}) {
|
|
12
14
|
const base = await runtimePaths(root);
|
|
13
15
|
const identity = {
|
|
@@ -49,23 +51,33 @@ export async function startServer(root, execute, hooks = {}) {
|
|
|
49
51
|
const peersFile = path.join(paths.directory, "clients.json");
|
|
50
52
|
let sequence = 0;
|
|
51
53
|
let closed = false;
|
|
54
|
+
let stopRequested = false;
|
|
55
|
+
let automaticClosing = false;
|
|
56
|
+
let peerWriteFailed = false;
|
|
57
|
+
let idleExit;
|
|
58
|
+
let expiring;
|
|
59
|
+
const peerOperations = new Set();
|
|
52
60
|
let queue = Promise.resolve();
|
|
53
61
|
let closing;
|
|
54
62
|
let peerWrites = Promise.resolve();
|
|
55
63
|
let heartbeat;
|
|
56
|
-
function savePeers() {
|
|
57
|
-
|
|
58
|
-
|
|
64
|
+
function savePeers(candidate) {
|
|
65
|
+
idleExit?.changed();
|
|
66
|
+
const operation = peerWrites.then(() => writePeers(candidate));
|
|
67
|
+
peerWrites = operation.catch(() => {
|
|
68
|
+
peerWriteFailed = true;
|
|
69
|
+
hooks.failure?.();
|
|
70
|
+
});
|
|
59
71
|
return operation;
|
|
60
72
|
}
|
|
61
|
-
async function writePeers() {
|
|
73
|
+
async function writePeers(candidate) {
|
|
62
74
|
const temporary = path.join(paths.directory, `.${randomUUID()}.clients`);
|
|
63
75
|
const data = {
|
|
64
76
|
version: 1,
|
|
65
77
|
root: paths.root,
|
|
66
78
|
clients: [...participants.values()]
|
|
67
79
|
.filter((peer) => processExists(peer.facts.pid))
|
|
68
|
-
.map((peer) => ({ ...peer.facts, handoff: peer.handoff })),
|
|
80
|
+
.map((peer) => ({ ...(candidate?.peer === peer ? candidate.facts : peer.facts), handoff: peer.handoff })),
|
|
69
81
|
};
|
|
70
82
|
const handle = await fs.open(temporary, "wx", 0o600);
|
|
71
83
|
try {
|
|
@@ -153,6 +165,8 @@ export async function startServer(root, execute, hooks = {}) {
|
|
|
153
165
|
}
|
|
154
166
|
};
|
|
155
167
|
const assertOwner = () => {
|
|
168
|
+
if (automaticClosing && !compromised)
|
|
169
|
+
throw new DaemonStoppingError();
|
|
156
170
|
if (closed || compromised)
|
|
157
171
|
throw new Error("Daemon ownership is no longer valid.");
|
|
158
172
|
assertRoot();
|
|
@@ -174,8 +188,16 @@ export async function startServer(root, execute, hooks = {}) {
|
|
|
174
188
|
const liveClientFacts = () => [...participants.values()].filter((peer) => processExists(peer.facts.pid)).map((peer) => peer.facts);
|
|
175
189
|
const participantFacts = () => [...participants.values()]
|
|
176
190
|
.filter((peer) => !peer.publishing && (peer.connected || peer.suspected) && processExists(peer.facts.pid))
|
|
177
|
-
.map((peer) =>
|
|
191
|
+
.map((peer) => peer.closing || peer.suspected ? { ...(peer.resumeFacts ?? peer.facts), idle: false } : peer.facts);
|
|
192
|
+
const contactState = (peer) => {
|
|
193
|
+
if (closed || stopRequested || compromised || peer.publishing || peer.closing || !processExists(peer.facts.pid))
|
|
194
|
+
return "inactive";
|
|
195
|
+
if (peer.connected)
|
|
196
|
+
return "active";
|
|
197
|
+
return peer.expiry ? "expired" : "inactive";
|
|
198
|
+
};
|
|
178
199
|
const poll = (peer, cursor, job) => ({
|
|
200
|
+
contact: contactState(peer),
|
|
179
201
|
cursor: sequence,
|
|
180
202
|
callbacks: [...peer.callbacks.values()],
|
|
181
203
|
events: peer.events.filter((event) => event.id > (typeof cursor === "number" && Number.isSafeInteger(cursor) ? cursor : 0)),
|
|
@@ -226,6 +248,18 @@ export async function startServer(root, execute, hooks = {}) {
|
|
|
226
248
|
Buffer.byteLength(JSON.stringify([...peer.callbacks.values(), callback])) > MAX_MESSAGE_BYTES / 8)
|
|
227
249
|
throw new Error("Callback exceeds its byte limit; no review was approved.");
|
|
228
250
|
job.peers.add(target);
|
|
251
|
+
const reservation = record(data) && typeof data.reservation === "string" ? data.reservation : undefined;
|
|
252
|
+
if (kind === "queue-acquire" || cleanup) {
|
|
253
|
+
// A lost acquire response is not proof that Pi never acquired the queue.
|
|
254
|
+
// Bound retained evidence even if a failing or malformed executor keeps requesting grants.
|
|
255
|
+
peer.reservations ??= new Set();
|
|
256
|
+
if (!reservation)
|
|
257
|
+
peer.resumeUnsafe = true;
|
|
258
|
+
else if (peer.reservations.size < 64)
|
|
259
|
+
peer.reservations.add(reservation);
|
|
260
|
+
else if (!peer.reservations.has(reservation))
|
|
261
|
+
peer.resumeUnsafe = true;
|
|
262
|
+
}
|
|
229
263
|
return new Promise((resolve, reject) => {
|
|
230
264
|
let timer;
|
|
231
265
|
const effectiveSignal = cleanup ? undefined : signal;
|
|
@@ -237,6 +271,8 @@ export async function startServer(root, execute, hooks = {}) {
|
|
|
237
271
|
if (!pending.delete(callback.id))
|
|
238
272
|
return;
|
|
239
273
|
peer.callbacks.delete(callback.id);
|
|
274
|
+
if (cleanup && reservation && error === undefined && value === true)
|
|
275
|
+
peer.reservations?.delete(reservation);
|
|
240
276
|
sequence++;
|
|
241
277
|
if (error)
|
|
242
278
|
reject(error);
|
|
@@ -332,6 +368,12 @@ export async function startServer(root, execute, hooks = {}) {
|
|
|
332
368
|
.catch((error) => {
|
|
333
369
|
job.view.phase = "failed";
|
|
334
370
|
job.view.error = remoteError(error);
|
|
371
|
+
if (job.committed)
|
|
372
|
+
for (const id of new Set([client, ...job.peers])) {
|
|
373
|
+
const affected = participants.get(id);
|
|
374
|
+
if (affected)
|
|
375
|
+
affected.resumeUnsafe = true;
|
|
376
|
+
}
|
|
335
377
|
})
|
|
336
378
|
.finally(() => {
|
|
337
379
|
for (const waiting of [...pending.values()])
|
|
@@ -343,16 +385,93 @@ export async function startServer(root, execute, hooks = {}) {
|
|
|
343
385
|
jobs.set(id, job);
|
|
344
386
|
return job;
|
|
345
387
|
}
|
|
388
|
+
function invalidateExpiry(peer) {
|
|
389
|
+
peer.expiry?.abort(new DOMException("Client is no longer eligible to resume contact", "AbortError"));
|
|
390
|
+
peer.expiry = undefined;
|
|
391
|
+
peer.resumeFacts = undefined;
|
|
392
|
+
}
|
|
393
|
+
async function resumeContact(facts, disconnect) {
|
|
394
|
+
const peer = requireParticipant(facts.id, true);
|
|
395
|
+
const expiry = peer.expiry;
|
|
396
|
+
const matchesSession = (old) => old.pid === facts.pid &&
|
|
397
|
+
old.generation === facts.generation &&
|
|
398
|
+
old.cwd === facts.cwd &&
|
|
399
|
+
old.sessionId === facts.sessionId &&
|
|
400
|
+
old.sessionFile === facts.sessionFile &&
|
|
401
|
+
old.sessionDir === facts.sessionDir &&
|
|
402
|
+
old.mode === facts.mode &&
|
|
403
|
+
old.hasUI === facts.hasUI;
|
|
404
|
+
if (!expiry || contactState(peer) !== "expired" || peer.resumeFacts || !matchesSession(peer.facts))
|
|
405
|
+
throw new Error("Client is not eligible to resume contact for this session.");
|
|
406
|
+
const signal = disconnect ? AbortSignal.any([disconnect, expiry.signal]) : expiry.signal;
|
|
407
|
+
const candidate = structuredClone(facts);
|
|
408
|
+
const recheck = () => {
|
|
409
|
+
assertOwner();
|
|
410
|
+
signal.throwIfAborted();
|
|
411
|
+
if (peerWriteFailed)
|
|
412
|
+
throw new Error("Daemon client ledger persistence is uncertain; reconcile with the existing owner before reconnecting.");
|
|
413
|
+
if (participants.get(facts.id) !== peer ||
|
|
414
|
+
peer.expiry !== expiry ||
|
|
415
|
+
contactState(peer) !== "expired" ||
|
|
416
|
+
!matchesSession(peer.facts))
|
|
417
|
+
throw new Error("Client is no longer eligible to resume contact.");
|
|
418
|
+
};
|
|
419
|
+
const affected = (job) => job.client === facts.id || job.peers.has(facts.id);
|
|
420
|
+
const running = (job) => affected(job) && job.view.phase === "running";
|
|
421
|
+
const stopped = Promise.withResolvers();
|
|
422
|
+
const abort = addAbortListener(signal, () => stopped.reject(signal.reason));
|
|
423
|
+
try {
|
|
424
|
+
recheck();
|
|
425
|
+
// Expose the new binding to the monitor, but only as a non-ready, busy suspect.
|
|
426
|
+
peer.resumeFacts = { ...candidate, ready: false };
|
|
427
|
+
// Never wait for jobs or monitor transitions inside admission: they can need the fence.
|
|
428
|
+
await Promise.race([
|
|
429
|
+
Promise.all([hooks.factsChanged?.(), ...[...jobs.values()].filter(running).map((job) => job.promise)]),
|
|
430
|
+
stopped.promise,
|
|
431
|
+
]);
|
|
432
|
+
recheck();
|
|
433
|
+
return await admission.run(async () => {
|
|
434
|
+
const safe = () => {
|
|
435
|
+
recheck();
|
|
436
|
+
if (peer.resumeUnsafe ||
|
|
437
|
+
peer.reservations?.size ||
|
|
438
|
+
peer.callbacks.size ||
|
|
439
|
+
[...jobs.values()].some(running) ||
|
|
440
|
+
[...backgroundJobs].some((job) => job.committed && affected(job)))
|
|
441
|
+
throw new Error("Client work or file-queue cleanup is uncertain; reconcile with the existing owner before reconnecting.");
|
|
442
|
+
};
|
|
443
|
+
safe();
|
|
444
|
+
// The staged facts have the same location and identity. Even if cancelled mid-write,
|
|
445
|
+
// the on-disk record does not authorize work or confer expiry eligibility on restart.
|
|
446
|
+
await savePeers({ peer, facts: candidate });
|
|
447
|
+
safe();
|
|
448
|
+
peer.facts = candidate;
|
|
449
|
+
peer.seen = Date.now();
|
|
450
|
+
peer.expiry = undefined;
|
|
451
|
+
peer.resumeFacts = undefined;
|
|
452
|
+
peer.suspected = false;
|
|
453
|
+
peer.connected = true;
|
|
454
|
+
hooks.idle?.();
|
|
455
|
+
return poll(peer, 0);
|
|
456
|
+
}, signal);
|
|
457
|
+
}
|
|
458
|
+
finally {
|
|
459
|
+
abort[Symbol.dispose]();
|
|
460
|
+
if (peer.expiry === expiry)
|
|
461
|
+
peer.resumeFacts = undefined;
|
|
462
|
+
}
|
|
463
|
+
}
|
|
346
464
|
async function detach(id, retain = false, handoff) {
|
|
347
465
|
const peer = participants.get(id);
|
|
348
466
|
if (!peer) {
|
|
349
467
|
if (closedClients.size < 10_000)
|
|
350
468
|
closedClients.add(id);
|
|
351
|
-
return { cursor: sequence, callbacks: [], events: [] };
|
|
469
|
+
return { contact: "inactive", cursor: sequence, callbacks: [], events: [] };
|
|
352
470
|
}
|
|
353
471
|
if (closedClients.has(id))
|
|
354
472
|
return poll(peer, 0);
|
|
355
473
|
peer.closing = true;
|
|
474
|
+
invalidateExpiry(peer);
|
|
356
475
|
for (const waiting of [...pending.values()])
|
|
357
476
|
if (waiting.target === id && !waiting.callback.kind.startsWith("queue-"))
|
|
358
477
|
waiting.reject(new Error("Client detaching."));
|
|
@@ -375,6 +494,8 @@ export async function startServer(root, execute, hooks = {}) {
|
|
|
375
494
|
return result;
|
|
376
495
|
}
|
|
377
496
|
async function handle(method, params, signal) {
|
|
497
|
+
if (automaticClosing && method !== "stop")
|
|
498
|
+
throw new DaemonStoppingError();
|
|
378
499
|
const cleanup = ["answer", "poll", "cancel", "detach", "pause", "handoff", "stop"].includes(method);
|
|
379
500
|
if (!published && !cleanup)
|
|
380
501
|
throw new Error("Daemon readiness is not published.");
|
|
@@ -402,8 +523,12 @@ export async function startServer(root, execute, hooks = {}) {
|
|
|
402
523
|
(old.facts.pid !== params.pid ||
|
|
403
524
|
((old.connected || old.suspected) && old.facts.generation !== params.generation)))
|
|
404
525
|
throw new Error("Client identity collision.");
|
|
526
|
+
if (old)
|
|
527
|
+
invalidateExpiry(old);
|
|
405
528
|
participants.set(params.id, {
|
|
406
529
|
facts: structuredClone(params),
|
|
530
|
+
reservations: old?.reservations,
|
|
531
|
+
resumeUnsafe: old?.resumeUnsafe,
|
|
407
532
|
callbacks: old?.callbacks ?? new Map(),
|
|
408
533
|
events: old?.events ?? [],
|
|
409
534
|
connected: true,
|
|
@@ -450,6 +575,10 @@ export async function startServer(root, execute, hooks = {}) {
|
|
|
450
575
|
assertOwner();
|
|
451
576
|
return poll(attached, 0);
|
|
452
577
|
}
|
|
578
|
+
if (method === "resume-contact") {
|
|
579
|
+
validateFacts(params);
|
|
580
|
+
return resumeContact(params, signal);
|
|
581
|
+
}
|
|
453
582
|
if (!record(params))
|
|
454
583
|
throw new Error("Invalid request parameters.");
|
|
455
584
|
const contact = typeof params.client === "string" ? participants.get(params.client) : undefined;
|
|
@@ -462,10 +591,13 @@ export async function startServer(root, execute, hooks = {}) {
|
|
|
462
591
|
}
|
|
463
592
|
if (method === "update") {
|
|
464
593
|
validateFacts(params.facts);
|
|
465
|
-
const peer = requireParticipant(params.facts.id);
|
|
594
|
+
const peer = requireParticipant(params.facts.id, true);
|
|
466
595
|
const old = peer.facts;
|
|
467
596
|
if (old.pid !== params.facts.pid || old.generation !== params.facts.generation)
|
|
468
597
|
throw new Error("Client generation mismatch.");
|
|
598
|
+
if (contactState(peer) === "expired")
|
|
599
|
+
throw new ClientContactExpiredError();
|
|
600
|
+
requireParticipant(params.facts.id);
|
|
469
601
|
peer.facts = structuredClone(params.facts);
|
|
470
602
|
const published = peer.facts;
|
|
471
603
|
try {
|
|
@@ -477,7 +609,15 @@ export async function startServer(root, execute, hooks = {}) {
|
|
|
477
609
|
throw error;
|
|
478
610
|
}
|
|
479
611
|
await hooks.factsChanged?.();
|
|
480
|
-
|
|
612
|
+
assertOwner();
|
|
613
|
+
if (participants.get(params.facts.id) !== peer)
|
|
614
|
+
throw new Error("Client changed during update.");
|
|
615
|
+
const reply = poll(peer, 0);
|
|
616
|
+
if (reply.contact === "expired")
|
|
617
|
+
throw new ClientContactExpiredError();
|
|
618
|
+
if (reply.contact !== "active")
|
|
619
|
+
throw new Error("Client is not attached or is closing.");
|
|
620
|
+
return reply;
|
|
481
621
|
}
|
|
482
622
|
if (["detach", "pause", "handoff"].includes(method)) {
|
|
483
623
|
if (!validId(params.client))
|
|
@@ -550,6 +690,7 @@ export async function startServer(root, execute, hooks = {}) {
|
|
|
550
690
|
return job.view;
|
|
551
691
|
}
|
|
552
692
|
if (method === "stop") {
|
|
693
|
+
stopRequested = true;
|
|
553
694
|
setImmediate(() => {
|
|
554
695
|
void close().catch(() => { });
|
|
555
696
|
});
|
|
@@ -586,11 +727,18 @@ export async function startServer(root, execute, hooks = {}) {
|
|
|
586
727
|
respond(response, 403, { error: { name: "Error", message: "Invalid daemon identity or protocol." } });
|
|
587
728
|
return;
|
|
588
729
|
}
|
|
589
|
-
if (body.method === "attach") {
|
|
730
|
+
if (body.method === "attach" || body.method === "resume-contact") {
|
|
590
731
|
admissionController = new AbortController();
|
|
591
732
|
response.once("close", disconnect);
|
|
733
|
+
if (response.destroyed)
|
|
734
|
+
disconnect();
|
|
735
|
+
}
|
|
736
|
+
const operation = handle(body.method, body.params, admissionController?.signal);
|
|
737
|
+
if (["attach", "resume-contact", "update", "detach", "pause", "handoff"].includes(body.method)) {
|
|
738
|
+
peerOperations.add(operation);
|
|
739
|
+
void operation.finally(() => peerOperations.delete(operation)).catch(() => { });
|
|
592
740
|
}
|
|
593
|
-
respond(response, 200, { result: await
|
|
741
|
+
respond(response, 200, { result: await operation });
|
|
594
742
|
}
|
|
595
743
|
catch (error) {
|
|
596
744
|
if (!response.destroyed)
|
|
@@ -617,7 +765,15 @@ export async function startServer(root, execute, hooks = {}) {
|
|
|
617
765
|
throw error;
|
|
618
766
|
}, () => withCleanup(() => endpoint.close(), release));
|
|
619
767
|
}
|
|
620
|
-
|
|
768
|
+
function expireClients() {
|
|
769
|
+
expiring ??= expire().finally(() => {
|
|
770
|
+
expiring = undefined;
|
|
771
|
+
});
|
|
772
|
+
return expiring;
|
|
773
|
+
}
|
|
774
|
+
async function expire() {
|
|
775
|
+
if (closed)
|
|
776
|
+
return;
|
|
621
777
|
let changed = false;
|
|
622
778
|
for (const [id, peer] of participants) {
|
|
623
779
|
const exited = !processExists(peer.facts.pid);
|
|
@@ -625,6 +781,10 @@ export async function startServer(root, execute, hooks = {}) {
|
|
|
625
781
|
continue;
|
|
626
782
|
peer.connected = false;
|
|
627
783
|
peer.suspected = !exited;
|
|
784
|
+
if (exited)
|
|
785
|
+
invalidateExpiry(peer);
|
|
786
|
+
else if (!peer.closing && !peer.publishing)
|
|
787
|
+
peer.expiry = new AbortController();
|
|
628
788
|
changed = true;
|
|
629
789
|
for (const job of [...jobs.values(), ...backgroundJobs])
|
|
630
790
|
if (!job.committed && (job.client === id || job.peers.has(id)))
|
|
@@ -646,8 +806,56 @@ export async function startServer(root, execute, hooks = {}) {
|
|
|
646
806
|
await hooks.factsChanged?.();
|
|
647
807
|
}
|
|
648
808
|
}
|
|
809
|
+
const lifetime = async () => closed || compromised || peerWriteFailed ? "pause" : ((await hooks.lifetime?.()) ?? "pause");
|
|
810
|
+
if (hooks.lifetime) {
|
|
811
|
+
idleExit = createIdleExit({
|
|
812
|
+
live: () => liveClientFacts().length > 0,
|
|
813
|
+
policy: lifetime,
|
|
814
|
+
quiesce: async () => {
|
|
815
|
+
for (const job of [...jobs.values(), ...backgroundJobs])
|
|
816
|
+
if (!job.committed)
|
|
817
|
+
job.controller.abort(new DOMException("Daemon idle shutdown", "AbortError"));
|
|
818
|
+
await hooks.quiesce?.();
|
|
819
|
+
await Promise.allSettled([...jobs.values()].map((job) => job.promise));
|
|
820
|
+
await Promise.allSettled([...peerOperations]);
|
|
821
|
+
await expiring;
|
|
822
|
+
await peerWrites;
|
|
823
|
+
},
|
|
824
|
+
close: (current) => admission.run(async () => {
|
|
825
|
+
if (!current() || closed || peerWriteFailed || peerOperations.size)
|
|
826
|
+
return false;
|
|
827
|
+
await peerWrites;
|
|
828
|
+
const owned = await known();
|
|
829
|
+
const policy = await lifetime();
|
|
830
|
+
if (!owned ||
|
|
831
|
+
policy !== "exit" ||
|
|
832
|
+
!current() ||
|
|
833
|
+
closed ||
|
|
834
|
+
compromised ||
|
|
835
|
+
peerWriteFailed ||
|
|
836
|
+
peerOperations.size ||
|
|
837
|
+
backgroundJobs.size ||
|
|
838
|
+
pending.size ||
|
|
839
|
+
[...jobs.values()].some((job) => job.view.phase === "queued" || job.view.phase === "running"))
|
|
840
|
+
return false;
|
|
841
|
+
assertRoot();
|
|
842
|
+
// Fence new admissions synchronously, then close outside the gate and monitor transition.
|
|
843
|
+
automaticClosing = true;
|
|
844
|
+
closed = true;
|
|
845
|
+
setImmediate(() => {
|
|
846
|
+
void close().catch(() => { });
|
|
847
|
+
});
|
|
848
|
+
return true;
|
|
849
|
+
}),
|
|
850
|
+
resume: () => hooks.idle?.(),
|
|
851
|
+
failed: () => hooks.failure?.(),
|
|
852
|
+
});
|
|
853
|
+
void idleExit.tick();
|
|
854
|
+
}
|
|
649
855
|
heartbeat = setInterval(() => {
|
|
650
|
-
void expireClients()
|
|
856
|
+
void expireClients()
|
|
857
|
+
.then(() => idleExit?.tick())
|
|
858
|
+
.catch(() => { });
|
|
651
859
|
}, 1_000);
|
|
652
860
|
heartbeat.unref();
|
|
653
861
|
async function close() {
|
|
@@ -655,6 +863,8 @@ export async function startServer(root, execute, hooks = {}) {
|
|
|
655
863
|
return closing;
|
|
656
864
|
closing = (async () => {
|
|
657
865
|
closed = true;
|
|
866
|
+
for (const peer of participants.values())
|
|
867
|
+
invalidateExpiry(peer);
|
|
658
868
|
clearInterval(heartbeat);
|
|
659
869
|
for (const waiting of [...pending.values()])
|
|
660
870
|
if (!waiting.callback.kind.startsWith("queue-"))
|
|
@@ -662,6 +872,7 @@ export async function startServer(root, execute, hooks = {}) {
|
|
|
662
872
|
for (const job of [...jobs.values(), ...backgroundJobs])
|
|
663
873
|
if (!job.committed)
|
|
664
874
|
job.controller.abort(new DOMException("Daemon stopping", "AbortError"));
|
|
875
|
+
await idleExit?.dispose();
|
|
665
876
|
let closeError;
|
|
666
877
|
try {
|
|
667
878
|
await hooks.close?.();
|
|
@@ -671,15 +882,21 @@ export async function startServer(root, execute, hooks = {}) {
|
|
|
671
882
|
}
|
|
672
883
|
await Promise.allSettled([...jobs.values()].map((job) => job.promise));
|
|
673
884
|
await admission.run(async () => { });
|
|
885
|
+
await Promise.allSettled([...peerOperations]);
|
|
886
|
+
await expiring;
|
|
887
|
+
await peerWrites;
|
|
674
888
|
for (const waiting of [...pending.values()])
|
|
675
889
|
waiting.reject(new Error("Daemon stopping."));
|
|
890
|
+
// A failed engine drain must retain the live owner, not permit an implicit restart.
|
|
891
|
+
if (closeError)
|
|
892
|
+
throw closeError;
|
|
676
893
|
await endpoint.close();
|
|
677
894
|
if (await known())
|
|
678
895
|
await fs.rm(paths.identity, { force: true });
|
|
679
896
|
await release();
|
|
680
|
-
|
|
681
|
-
throw closeError;
|
|
897
|
+
hooks.stopped?.();
|
|
682
898
|
})().catch((error) => {
|
|
899
|
+
hooks.failure?.();
|
|
683
900
|
closing = undefined;
|
|
684
901
|
throw error;
|
|
685
902
|
});
|
|
@@ -716,6 +933,8 @@ export async function startServer(root, execute, hooks = {}) {
|
|
|
716
933
|
participants: participantFacts,
|
|
717
934
|
liveClients: liveClientFacts,
|
|
718
935
|
expireClients,
|
|
936
|
+
// The heartbeat and deterministic lifecycle tests use the same evaluation boundary.
|
|
937
|
+
checkLifetime: () => idleExit?.tick() ?? Promise.resolve(),
|
|
719
938
|
isIdle: () => !closed && [...jobs.values()].every((job) => job.view.phase !== "queued" && job.view.phase !== "running"),
|
|
720
939
|
get closed() {
|
|
721
940
|
return closed;
|
package/docs/architecture.md
CHANGED
|
@@ -79,7 +79,12 @@ Terminal formatting utilities are not interactive components. No daemon-owned me
|
|
|
79
79
|
| Missing independent credentials | Public SDK failure; no parent-runtime key extraction | Synthetic resolver tests |
|
|
80
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
81
|
| Model output / stale candidate / refusal | Candidate only / revalidate all evidence / retain budget and refusal policy | Existing agent suites |
|
|
82
|
-
|
|
|
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 |
|
|
83
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 |
|
|
84
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 |
|
|
85
90
|
| Config/model/consent changes during unattended review | Reject before publication, preserving new data | Consent tests |
|
|
@@ -90,6 +95,50 @@ Terminal formatting utilities are not interactive components. No daemon-owned me
|
|
|
90
95
|
|
|
91
96
|
The source-linked matrix is the audit contract, not a list of already completed checks. The implementation plan records actual results separately.
|
|
92
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. A cancelled or submitted operation is never replayed by this recovery.
|
|
109
|
+
|
|
110
|
+
### Recovering expired contact
|
|
111
|
+
|
|
112
|
+
A running daemon can expire a Pi session's heartbeat after a computer sleeps. A
|
|
113
|
+
cleanup poll still returns callbacks and job results. Its optional version-1
|
|
114
|
+
`contact` field distinguishes `expired` from `active` and `inactive`. Only a
|
|
115
|
+
heartbeat expired by this daemon instance gets `expired`. A facts update from
|
|
116
|
+
the matching expired client returns `ClientContactExpiredError`. An older
|
|
117
|
+
service can omit `contact`, which does not authorize repair.
|
|
118
|
+
|
|
119
|
+
`DaemonConnection.resumeContact()` sends the same client's current facts to
|
|
120
|
+
the authenticated owner with `resume-contact`. The daemon retains the existing
|
|
121
|
+
participant, protects the live session, and fences publication with the same
|
|
122
|
+
admission gate used by attach. Deliberate pauses, handoffs, retired identities,
|
|
123
|
+
and peers loaded from disk are not eligible. Cleanup polling stays available
|
|
124
|
+
while admission waits. Unknown work outcomes and unconfirmed queue releases
|
|
125
|
+
block repair. Pi Sync supplies non-ready, busy facts during admission, then
|
|
126
|
+
publishes fresh facts after confirmation. The binding and consent checks still
|
|
127
|
+
apply. A failed or uncertain repair does not start a replacement owner, release
|
|
128
|
+
uncertain grants, or resubmit work.
|
|
129
|
+
|
|
130
|
+
## Repository lifetime smoke
|
|
131
|
+
|
|
132
|
+
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.
|
|
133
|
+
|
|
134
|
+
```sh
|
|
135
|
+
npm exec -- tsc -p tsconfig.test.json
|
|
136
|
+
cp -R packages/pi-sync/test/fixtures node_modules/.cache/pi-extensions-test/packages/pi-sync/test/
|
|
137
|
+
node node_modules/.cache/pi-extensions-test/packages/pi-sync/test/idle-exit-cli-smoke.js
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
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.
|
|
141
|
+
|
|
93
142
|
## Cross-process apply protocol
|
|
94
143
|
|
|
95
144
|
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.
|
|
@@ -116,7 +165,7 @@ Each POSIX instance binds inside an exclusively created 0700 directory; this par
|
|
|
116
165
|
|
|
117
166
|
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.
|
|
118
167
|
|
|
119
|
-
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; repair persistence and revoke the retained grant before an explicit restart.
|
|
168
|
+
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.
|
|
120
169
|
|
|
121
170
|
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.
|
|
122
171
|
|