@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/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
- const operation = peerWrites.then(writePeers);
58
- peerWrites = operation.catch(() => { });
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) => (peer.closing || peer.suspected ? { ...peer.facts, idle: false } : peer.facts));
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
- return poll(peer, 0);
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 handle(body.method, body.params, admissionController?.signal) });
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
- async function expireClients() {
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().catch(() => { });
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
- if (closeError)
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;
@@ -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
- | Last Pi exit without reviewed daemon-era permission | Service may stay alive; no unattended transfer or inference | Zero-client tests |
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
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@narumitw/pi-sync-daemon",
3
- "version": "0.2.0",
3
+ "version": "0.4.0",
4
4
  "description": "A local synchronization daemon with a versioned client API.",
5
5
  "type": "module",
6
6
  "license": "MIT",