@narumitw/pi-sync-daemon 0.3.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 CHANGED
@@ -1,5 +1,15 @@
1
1
  # @narumitw/pi-sync-daemon
2
2
 
3
+ ## 0.4.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 223b0ba: Restore a live Pi session after its heartbeat expires without reloading Pi. The
8
+ daemon distinguishes heartbeat expiry from deliberate disconnection and keeps
9
+ file-queue and session protection in place. Pi Sync reconnects to the same owner
10
+ without resubmitting interrupted operations, and checks participation before
11
+ reporting that it is connected.
12
+
3
13
  ## 0.3.0
4
14
 
5
15
  ### Minor Changes
package/dist/client.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { type RuntimePaths } from "./identity.js";
2
- import { type Callback, type ClientEvent, type ClientFacts, type ClientHandoff, type Identity, type RemoteError } from "./protocol.js";
2
+ import { type Callback, type ClientEvent, type ClientFacts, type ClientHandoff, type ClientContact as ContactState, type Identity, type RemoteError } from "./protocol.js";
3
3
  export declare class DaemonError extends Error {
4
4
  readonly remote: RemoteError;
5
5
  constructor(remote: RemoteError);
@@ -23,6 +23,8 @@ export interface ConnectionOptions {
23
23
  callback(callback: Callback, signal: AbortSignal): Promise<unknown>;
24
24
  event?(event: ClientEvent): void;
25
25
  error?(error: unknown): void;
26
+ /** Each current background observation after admission, including repeated states. */
27
+ contact?(state: ContactState): void;
26
28
  }
27
29
  export declare class DaemonConnection {
28
30
  readonly paths: RuntimePaths;
@@ -36,17 +38,35 @@ export declare class DaemonConnection {
36
38
  private callbackTasks;
37
39
  private updates;
38
40
  private attached;
41
+ private admitting;
42
+ private observedContact;
43
+ private contactRevision;
44
+ private lifecycleRevision;
45
+ private resuming;
46
+ private resumeUncertain;
47
+ private pendingJobs;
39
48
  private uncertain;
40
49
  private reportedError;
41
50
  private commits;
42
51
  private completedCallbacks;
52
+ private pausing;
43
53
  private disposing;
44
54
  private polling;
45
55
  private closed;
46
56
  constructor(paths: RuntimePaths, identity: Identity, facts: ClientFacts, options: ConnectionOptions);
57
+ /** Latest owner observation, or undefined if contact is unsupported or not observed. */
58
+ get contactState(): ContactState | undefined;
59
+ /** An uncertain attempt must not be retried or turned into a new attach. */
60
+ get contactResumeState(): "idle" | "running" | "uncertain";
61
+ /** Original submitted jobs must finish (or be reconciled) before repairing contact. */
62
+ get hasPendingWork(): boolean;
47
63
  attach(signal?: AbortSignal): Promise<this>;
48
64
  update(facts: ClientFacts): Promise<void>;
65
+ /** Resume this participant without replacing its callbacks, jobs, or polling. */
66
+ resumeContact(facts: ClientFacts, signal?: AbortSignal): Promise<void>;
67
+ private sameClient;
49
68
  run(operation: string, payload: unknown, signal?: AbortSignal, onCommit?: () => void): Promise<unknown>;
69
+ private publishContact;
50
70
  private consume;
51
71
  private performCallback;
52
72
  private wait;
package/dist/client.js CHANGED
@@ -47,9 +47,9 @@ export async function requestDaemon(paths, identity, method, params, signal) {
47
47
  })
48
48
  .catch(reject);
49
49
  });
50
- // Attach can wait behind a complete apply. Its connection-owned signal/dispose
51
- // cancels that wait; an idle timeout must not let startup escape the admission fence.
52
- request.setTimeout(method === "attach" ? 0 : 30_000, () => request.destroy(new Error("Daemon request timed out.")));
50
+ // Admission can wait behind a complete apply. The request owner's signal
51
+ // cancels that wait; an idle timeout must not let admission escape the fence.
52
+ request.setTimeout(method === "attach" || method === "resume-contact" ? 0 : 30_000, () => request.destroy(new Error("Daemon request timed out.")));
53
53
  request.once("error", reject);
54
54
  request.end(body);
55
55
  });
@@ -226,10 +226,18 @@ export class DaemonConnection {
226
226
  callbackTasks = new Set();
227
227
  updates = Promise.resolve();
228
228
  attached = false;
229
+ admitting = false;
230
+ observedContact;
231
+ contactRevision = 0;
232
+ lifecycleRevision = 0;
233
+ resuming;
234
+ resumeUncertain = false;
235
+ pendingJobs = 0;
229
236
  uncertain = false;
230
237
  reportedError = false;
231
238
  commits = new Map();
232
239
  completedCallbacks = new Set();
240
+ pausing;
233
241
  disposing;
234
242
  polling;
235
243
  closed = false;
@@ -239,9 +247,29 @@ export class DaemonConnection {
239
247
  this.facts = facts;
240
248
  this.options = options;
241
249
  }
250
+ /** Latest owner observation, or undefined if contact is unsupported or not observed. */
251
+ get contactState() {
252
+ return this.observedContact;
253
+ }
254
+ /** An uncertain attempt must not be retried or turned into a new attach. */
255
+ get contactResumeState() {
256
+ return this.resumeUncertain ? "uncertain" : this.resuming ? "running" : "idle";
257
+ }
258
+ /** Original submitted jobs must finish (or be reconciled) before repairing contact. */
259
+ get hasPendingWork() {
260
+ return this.pendingJobs > 0 || this.uncertain;
261
+ }
242
262
  async attach(signal) {
243
- if (this.closed || this.uncertain)
263
+ if (this.closed ||
264
+ this.hasPendingWork ||
265
+ this.contactResumeState !== "idle" ||
266
+ this.admitting ||
267
+ this.pausing ||
268
+ this.disposing)
244
269
  throw new Error("Daemon client is unavailable; reconnect after draining work.");
270
+ this.admitting = true;
271
+ this.lifecycleRevision++;
272
+ this.contactRevision++;
245
273
  const request = requestDaemon(this.paths, this.identity, "attach", this.facts, signal ? AbortSignal.any([signal, this.controller.signal]) : this.controller.signal);
246
274
  // Poll during attach: stopping a previous controller may need release answers
247
275
  // from this reattached participant before the attach response can complete.
@@ -250,7 +278,7 @@ export class DaemonConnection {
250
278
  try {
251
279
  const result = await request;
252
280
  admitted = true;
253
- this.consume(result);
281
+ this.publishContact(this.consume(result));
254
282
  this.attached = true;
255
283
  return this;
256
284
  }
@@ -279,24 +307,111 @@ export class DaemonConnection {
279
307
  }
280
308
  });
281
309
  }
310
+ finally {
311
+ this.admitting = false;
312
+ }
282
313
  }
283
- update(facts) {
314
+ async update(facts) {
315
+ const lifecycle = this.lifecycleRevision;
316
+ if (this.admitting || this.pausing || this.disposing)
317
+ throw new Error("Daemon client is changing; wait before updating facts.");
284
318
  const update = this.updates.then(async () => {
285
- if (this.closed || this.uncertain)
319
+ if (this.closed || this.uncertain || this.resumeUncertain || lifecycle !== this.lifecycleRevision)
286
320
  throw new Error("Daemon client is unavailable; reconnect after draining work.");
287
- const result = await requestDaemon(this.paths, this.identity, "update", { facts }, this.controller.signal);
321
+ const revision = this.contactRevision;
322
+ let result;
323
+ try {
324
+ result = await requestDaemon(this.paths, this.identity, "update", { facts }, this.controller.signal);
325
+ }
326
+ catch (error) {
327
+ if (this.attached &&
328
+ revision === this.contactRevision &&
329
+ this.sameClient(facts) &&
330
+ error instanceof DaemonError &&
331
+ error.remote.name === "ClientContactExpiredError")
332
+ this.publishContact("expired");
333
+ throw error;
334
+ }
288
335
  if (this.closed)
289
336
  throw new Error("Daemon client closed during update.");
337
+ if (revision !== this.contactRevision)
338
+ throw new Error("Daemon client changed during update.");
339
+ const contact = this.consume(result);
340
+ if (revision !== this.contactRevision)
341
+ throw new Error("Daemon client changed during update.");
290
342
  Object.assign(this.facts, facts);
291
- this.consume(result);
343
+ this.publishContact(contact);
292
344
  });
293
345
  this.updates = update.catch(() => { });
294
346
  return update;
295
347
  }
348
+ /** Resume this participant without replacing its callbacks, jobs, or polling. */
349
+ async resumeContact(facts, signal) {
350
+ signal?.throwIfAborted();
351
+ if (this.contactResumeState !== "idle")
352
+ throw new Error("Daemon contact resume is running or uncertain.");
353
+ const check = () => {
354
+ if (!this.attached || this.admitting || this.pausing || this.disposing || this.closed || this.hasPendingWork)
355
+ throw new Error("Daemon client is unavailable; reconnect after draining work.");
356
+ if (!this.sameClient(facts) || this.contactState !== "expired")
357
+ throw new Error("No confirmed contact expiry for this daemon client.");
358
+ };
359
+ facts = structuredClone(facts);
360
+ check();
361
+ const resume = new AbortController();
362
+ this.resuming = resume;
363
+ const ownedSignal = signal ? AbortSignal.any([signal, resume.signal]) : resume.signal;
364
+ let sent = false;
365
+ const attempt = this.updates.then(async () => {
366
+ ownedSignal.throwIfAborted();
367
+ check();
368
+ sent = true;
369
+ const reply = await requestDaemon(this.paths, this.identity, "resume-contact", facts, ownedSignal);
370
+ ownedSignal.throwIfAborted();
371
+ const contact = this.consume(reply);
372
+ ownedSignal.throwIfAborted();
373
+ if (contact !== "active")
374
+ throw new Error("Daemon did not confirm resumed contact.");
375
+ Object.assign(this.facts, facts);
376
+ this.publishContact(contact);
377
+ });
378
+ this.updates = attempt.catch(() => { });
379
+ // Reject a queued repair on cancellation even if the earlier update has not finished.
380
+ const cancellation = Promise.withResolvers();
381
+ const abort = () => cancellation.reject(ownedSignal.reason);
382
+ ownedSignal.addEventListener("abort", abort, { once: true });
383
+ try {
384
+ await Promise.race([attempt, cancellation.promise]);
385
+ }
386
+ catch (error) {
387
+ if (sent) {
388
+ // The protocol does not distinguish definite pre-publication refusal from a lost acknowledgement.
389
+ this.resumeUncertain = true;
390
+ for (const { controller, kind } of this.callbacks.values())
391
+ if (kind !== "queue-release")
392
+ controller.abort();
393
+ }
394
+ throw error;
395
+ }
396
+ finally {
397
+ this.resuming = undefined;
398
+ ownedSignal.removeEventListener("abort", abort);
399
+ }
400
+ }
401
+ sameClient(facts) {
402
+ return facts.id === this.facts.id && facts.pid === this.facts.pid && facts.generation === this.facts.generation;
403
+ }
296
404
  async run(operation, payload, signal, onCommit) {
297
- if (this.closed || this.uncertain)
298
- throw new Error("Daemon client is unavailable; reconnect after draining work.");
405
+ if (this.closed ||
406
+ this.uncertain ||
407
+ this.contactResumeState !== "idle" ||
408
+ this.pausing ||
409
+ this.disposing ||
410
+ this.contactState === "expired" ||
411
+ this.contactState === "inactive")
412
+ throw new Error("Daemon client is unavailable; confirm contact and drain work before submitting.");
299
413
  signal?.throwIfAborted();
414
+ this.pendingJobs++;
300
415
  const id = `${operationPrefix(this.identity)}${randomUUID()}`;
301
416
  const abort = () => {
302
417
  void requestDaemon(this.paths, this.identity, "cancel", { id, client: this.facts.id }, this.controller.signal).catch(() => { });
@@ -313,11 +428,11 @@ export class DaemonConnection {
313
428
  const reply = await requestDaemon(this.paths, this.identity, "poll", { client: this.facts.id, cursor: this.cursor, job: id }, this.controller.signal);
314
429
  this.consume(reply);
315
430
  const job = record(reply) ? reply.job : undefined;
316
- if (job?.phase === "failed") {
431
+ if (job?.id === id && job.phase === "failed") {
317
432
  terminal = true;
318
433
  throw new DaemonError(job.error ?? { name: "Error", message: "Daemon operation failed." });
319
434
  }
320
- if (job?.phase === "done") {
435
+ if (job?.id === id && job.phase === "done") {
321
436
  terminal = true;
322
437
  signal?.throwIfAborted();
323
438
  return job.result;
@@ -343,7 +458,11 @@ export class DaemonConnection {
343
458
  throw new Error("Operation outcome is uncertain; reload to reconnect and reconcile, never replay the write.", { cause: error });
344
459
  }
345
460
  }
346
- });
461
+ }).finally(() => this.pendingJobs--);
462
+ }
463
+ publishContact(contact) {
464
+ this.contactRevision++;
465
+ this.observedContact = contact;
347
466
  }
348
467
  consume(reply) {
349
468
  if (!record(reply) ||
@@ -353,8 +472,11 @@ export class DaemonConnection {
353
472
  !Array.isArray(reply.callbacks) ||
354
473
  !Array.isArray(reply.events))
355
474
  throw new Error("Invalid daemon poll response.");
475
+ const { contact } = reply;
476
+ if (contact !== undefined && contact !== "active" && contact !== "expired" && contact !== "inactive")
477
+ throw new Error("Invalid daemon contact state.");
356
478
  if (reply.cursor < this.cursor)
357
- return;
479
+ return contact;
358
480
  for (const event of reply.events)
359
481
  if (event.id > this.cursor) {
360
482
  if (event.kind === "commit" && record(event.payload) && typeof event.payload.job === "string") {
@@ -381,7 +503,7 @@ export class DaemonConnection {
381
503
  let value;
382
504
  let failed = false;
383
505
  try {
384
- if (this.uncertain && callback.kind !== "queue-release")
506
+ if ((this.uncertain || this.resumeUncertain) && callback.kind !== "queue-release")
385
507
  throw new Error("Client is draining uncertain work.");
386
508
  value = await this.performCallback(callback, controller.signal);
387
509
  }
@@ -406,6 +528,7 @@ export class DaemonConnection {
406
528
  });
407
529
  this.callbackTasks.add(task);
408
530
  }
531
+ return contact;
409
532
  }
410
533
  async performCallback(callback, signal) {
411
534
  const reference = callback.review;
@@ -475,9 +598,25 @@ export class DaemonConnection {
475
598
  async poll() {
476
599
  while (!this.closed) {
477
600
  try {
601
+ const revision = this.contactRevision;
478
602
  const reply = await requestDaemon(this.paths, this.identity, "poll", { client: this.facts.id, cursor: this.cursor }, this.controller.signal);
479
- this.consume(reply);
480
- this.reportedError = false;
603
+ // An older poll must not undo typed update expiry or a successful resume.
604
+ if (revision === this.contactRevision) {
605
+ const contact = this.consume(reply);
606
+ this.reportedError = false;
607
+ if (revision === this.contactRevision &&
608
+ this.attached &&
609
+ !this.admitting &&
610
+ !this.pausing &&
611
+ !this.disposing &&
612
+ !this.closed) {
613
+ // A new observation fences older facts replies; identical polls do not.
614
+ if (contact !== this.observedContact)
615
+ this.publishContact(contact);
616
+ if (contact !== undefined)
617
+ this.options.contact?.(contact);
618
+ }
619
+ }
481
620
  await this.wait(100);
482
621
  }
483
622
  catch (error) {
@@ -495,16 +634,31 @@ export class DaemonConnection {
495
634
  }
496
635
  }
497
636
  async pause() {
498
- if (this.closed)
637
+ if (this.closed || this.disposing)
499
638
  throw new Error("Daemon client is closed.");
500
- const reply = await requestDaemon(this.paths, this.identity, "pause", { client: this.facts.id });
501
- this.consume(reply);
639
+ if (this.pausing)
640
+ return this.pausing;
641
+ this.resuming?.abort(new DOMException("Client paused", "AbortError"));
642
+ this.lifecycleRevision++;
643
+ this.contactRevision++;
644
+ this.pausing = (async () => {
645
+ const reply = await requestDaemon(this.paths, this.identity, "pause", { client: this.facts.id });
646
+ const contact = this.consume(reply);
647
+ if (!this.disposing)
648
+ this.publishContact(contact);
649
+ })().finally(() => {
650
+ this.pausing = undefined;
651
+ });
652
+ return this.pausing;
502
653
  }
503
654
  async dispose(handoff) {
504
655
  if (this.disposing)
505
656
  return this.disposing;
506
657
  if (this.closed)
507
658
  return;
659
+ this.resuming?.abort(new DOMException("Client disposed", "AbortError"));
660
+ this.lifecycleRevision++;
661
+ this.contactRevision++;
508
662
  this.disposing = (async () => {
509
663
  this.polling ??= this.poll();
510
664
  // Cancel UI before drain, but keep polling for acknowledged queue-release callbacks.
package/dist/index.d.ts CHANGED
@@ -4,5 +4,5 @@ export type { DocumentView } from "./document.js";
4
4
  export { documentFingerprint } from "./document.js";
5
5
  export type { EngineContext, EngineHost, EngineSession, ReviewRequest } from "./engine/host.js";
6
6
  export { modelSignature } from "./model-signature.js";
7
- export type { Callback, ClientEvent, ClientFacts, ClientHandoff, Identity, JobView, RemoteError } from "./protocol.js";
7
+ export type { Callback, ClientContact as ContactState, ClientEvent, ClientFacts, ClientHandoff, Identity, JobView, RemoteError, } from "./protocol.js";
8
8
  export { MAX_SETTINGS_BYTES, PROTOCOL_VERSION } from "./protocol.js";
@@ -5,6 +5,11 @@ export declare class DaemonStoppingError extends Error {
5
5
  name: string;
6
6
  constructor();
7
7
  }
8
+ /** This owner expired this client's heartbeat; a normal facts update cannot restore participation. */
9
+ export declare class ClientContactExpiredError extends Error {
10
+ name: string;
11
+ constructor();
12
+ }
8
13
  export declare const MAX_MESSAGE_BYTES: number;
9
14
  export declare const REVIEW_PAGE_CHARS: number;
10
15
  export declare const MAX_REVIEW_BYTES: number;
@@ -79,6 +84,15 @@ export interface JobView {
79
84
  result?: unknown;
80
85
  error?: RemoteError;
81
86
  }
87
+ export type ClientContact = "active" | "expired" | "inactive";
88
+ export interface PollReply {
89
+ cursor: number;
90
+ callbacks: Callback[];
91
+ events: ClientEvent[];
92
+ job?: JobView;
93
+ /** Absent on owners without protocol-v1 contact resume support. */
94
+ contact?: ClientContact;
95
+ }
82
96
  export interface Execution {
83
97
  readonly root: string;
84
98
  readonly clientId: string | undefined;
package/dist/protocol.js CHANGED
@@ -8,6 +8,13 @@ export class DaemonStoppingError extends Error {
8
8
  super("Daemon is closing after its idle grace period; wait for owner exit before reconnecting.");
9
9
  }
10
10
  }
11
+ /** This owner expired this client's heartbeat; a normal facts update cannot restore participation. */
12
+ export class ClientContactExpiredError extends Error {
13
+ name = "ClientContactExpiredError";
14
+ constructor() {
15
+ super("Client contact expired; resume the same session before publishing facts.");
16
+ }
17
+ }
11
18
  export const MAX_MESSAGE_BYTES = 4 * 1024 * 1024;
12
19
  export const REVIEW_PAGE_CHARS = 64 * 1024;
13
20
  export const MAX_REVIEW_BYTES = 16 * 1024 * 1024;
package/dist/server.js CHANGED
@@ -1,4 +1,5 @@
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";
@@ -8,7 +9,7 @@ import { canonicalRootGuard, daemonPaths, privateDirectory, processExists, publi
8
9
  import { createIdleExit } from "./idle-exit.js";
9
10
  import { withCleanup } from "./lifecycle.js";
10
11
  import { ParticipantAdmission } from "./participant-admission.js";
11
- import { DaemonStoppingError, 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";
12
13
  export async function startServer(root, execute, hooks = {}) {
13
14
  const base = await runtimePaths(root);
14
15
  const identity = {
@@ -50,6 +51,7 @@ export async function startServer(root, execute, hooks = {}) {
50
51
  const peersFile = path.join(paths.directory, "clients.json");
51
52
  let sequence = 0;
52
53
  let closed = false;
54
+ let stopRequested = false;
53
55
  let automaticClosing = false;
54
56
  let peerWriteFailed = false;
55
57
  let idleExit;
@@ -59,23 +61,23 @@ export async function startServer(root, execute, hooks = {}) {
59
61
  let closing;
60
62
  let peerWrites = Promise.resolve();
61
63
  let heartbeat;
62
- function savePeers() {
64
+ function savePeers(candidate) {
63
65
  idleExit?.changed();
64
- const operation = peerWrites.then(writePeers);
66
+ const operation = peerWrites.then(() => writePeers(candidate));
65
67
  peerWrites = operation.catch(() => {
66
68
  peerWriteFailed = true;
67
69
  hooks.failure?.();
68
70
  });
69
71
  return operation;
70
72
  }
71
- async function writePeers() {
73
+ async function writePeers(candidate) {
72
74
  const temporary = path.join(paths.directory, `.${randomUUID()}.clients`);
73
75
  const data = {
74
76
  version: 1,
75
77
  root: paths.root,
76
78
  clients: [...participants.values()]
77
79
  .filter((peer) => processExists(peer.facts.pid))
78
- .map((peer) => ({ ...peer.facts, handoff: peer.handoff })),
80
+ .map((peer) => ({ ...(candidate?.peer === peer ? candidate.facts : peer.facts), handoff: peer.handoff })),
79
81
  };
80
82
  const handle = await fs.open(temporary, "wx", 0o600);
81
83
  try {
@@ -186,8 +188,16 @@ export async function startServer(root, execute, hooks = {}) {
186
188
  const liveClientFacts = () => [...participants.values()].filter((peer) => processExists(peer.facts.pid)).map((peer) => peer.facts);
187
189
  const participantFacts = () => [...participants.values()]
188
190
  .filter((peer) => !peer.publishing && (peer.connected || peer.suspected) && processExists(peer.facts.pid))
189
- .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
+ };
190
199
  const poll = (peer, cursor, job) => ({
200
+ contact: contactState(peer),
191
201
  cursor: sequence,
192
202
  callbacks: [...peer.callbacks.values()],
193
203
  events: peer.events.filter((event) => event.id > (typeof cursor === "number" && Number.isSafeInteger(cursor) ? cursor : 0)),
@@ -238,6 +248,18 @@ export async function startServer(root, execute, hooks = {}) {
238
248
  Buffer.byteLength(JSON.stringify([...peer.callbacks.values(), callback])) > MAX_MESSAGE_BYTES / 8)
239
249
  throw new Error("Callback exceeds its byte limit; no review was approved.");
240
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
+ }
241
263
  return new Promise((resolve, reject) => {
242
264
  let timer;
243
265
  const effectiveSignal = cleanup ? undefined : signal;
@@ -249,6 +271,8 @@ export async function startServer(root, execute, hooks = {}) {
249
271
  if (!pending.delete(callback.id))
250
272
  return;
251
273
  peer.callbacks.delete(callback.id);
274
+ if (cleanup && reservation && error === undefined && value === true)
275
+ peer.reservations?.delete(reservation);
252
276
  sequence++;
253
277
  if (error)
254
278
  reject(error);
@@ -344,6 +368,12 @@ export async function startServer(root, execute, hooks = {}) {
344
368
  .catch((error) => {
345
369
  job.view.phase = "failed";
346
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
+ }
347
377
  })
348
378
  .finally(() => {
349
379
  for (const waiting of [...pending.values()])
@@ -355,16 +385,93 @@ export async function startServer(root, execute, hooks = {}) {
355
385
  jobs.set(id, job);
356
386
  return job;
357
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
+ }
358
464
  async function detach(id, retain = false, handoff) {
359
465
  const peer = participants.get(id);
360
466
  if (!peer) {
361
467
  if (closedClients.size < 10_000)
362
468
  closedClients.add(id);
363
- return { cursor: sequence, callbacks: [], events: [] };
469
+ return { contact: "inactive", cursor: sequence, callbacks: [], events: [] };
364
470
  }
365
471
  if (closedClients.has(id))
366
472
  return poll(peer, 0);
367
473
  peer.closing = true;
474
+ invalidateExpiry(peer);
368
475
  for (const waiting of [...pending.values()])
369
476
  if (waiting.target === id && !waiting.callback.kind.startsWith("queue-"))
370
477
  waiting.reject(new Error("Client detaching."));
@@ -416,8 +523,12 @@ export async function startServer(root, execute, hooks = {}) {
416
523
  (old.facts.pid !== params.pid ||
417
524
  ((old.connected || old.suspected) && old.facts.generation !== params.generation)))
418
525
  throw new Error("Client identity collision.");
526
+ if (old)
527
+ invalidateExpiry(old);
419
528
  participants.set(params.id, {
420
529
  facts: structuredClone(params),
530
+ reservations: old?.reservations,
531
+ resumeUnsafe: old?.resumeUnsafe,
421
532
  callbacks: old?.callbacks ?? new Map(),
422
533
  events: old?.events ?? [],
423
534
  connected: true,
@@ -464,6 +575,10 @@ export async function startServer(root, execute, hooks = {}) {
464
575
  assertOwner();
465
576
  return poll(attached, 0);
466
577
  }
578
+ if (method === "resume-contact") {
579
+ validateFacts(params);
580
+ return resumeContact(params, signal);
581
+ }
467
582
  if (!record(params))
468
583
  throw new Error("Invalid request parameters.");
469
584
  const contact = typeof params.client === "string" ? participants.get(params.client) : undefined;
@@ -476,10 +591,13 @@ export async function startServer(root, execute, hooks = {}) {
476
591
  }
477
592
  if (method === "update") {
478
593
  validateFacts(params.facts);
479
- const peer = requireParticipant(params.facts.id);
594
+ const peer = requireParticipant(params.facts.id, true);
480
595
  const old = peer.facts;
481
596
  if (old.pid !== params.facts.pid || old.generation !== params.facts.generation)
482
597
  throw new Error("Client generation mismatch.");
598
+ if (contactState(peer) === "expired")
599
+ throw new ClientContactExpiredError();
600
+ requireParticipant(params.facts.id);
483
601
  peer.facts = structuredClone(params.facts);
484
602
  const published = peer.facts;
485
603
  try {
@@ -491,7 +609,15 @@ export async function startServer(root, execute, hooks = {}) {
491
609
  throw error;
492
610
  }
493
611
  await hooks.factsChanged?.();
494
- 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;
495
621
  }
496
622
  if (["detach", "pause", "handoff"].includes(method)) {
497
623
  if (!validId(params.client))
@@ -564,6 +690,7 @@ export async function startServer(root, execute, hooks = {}) {
564
690
  return job.view;
565
691
  }
566
692
  if (method === "stop") {
693
+ stopRequested = true;
567
694
  setImmediate(() => {
568
695
  void close().catch(() => { });
569
696
  });
@@ -600,12 +727,14 @@ export async function startServer(root, execute, hooks = {}) {
600
727
  respond(response, 403, { error: { name: "Error", message: "Invalid daemon identity or protocol." } });
601
728
  return;
602
729
  }
603
- if (body.method === "attach") {
730
+ if (body.method === "attach" || body.method === "resume-contact") {
604
731
  admissionController = new AbortController();
605
732
  response.once("close", disconnect);
733
+ if (response.destroyed)
734
+ disconnect();
606
735
  }
607
736
  const operation = handle(body.method, body.params, admissionController?.signal);
608
- if (["attach", "update", "detach", "pause", "handoff"].includes(body.method)) {
737
+ if (["attach", "resume-contact", "update", "detach", "pause", "handoff"].includes(body.method)) {
609
738
  peerOperations.add(operation);
610
739
  void operation.finally(() => peerOperations.delete(operation)).catch(() => { });
611
740
  }
@@ -652,6 +781,10 @@ export async function startServer(root, execute, hooks = {}) {
652
781
  continue;
653
782
  peer.connected = false;
654
783
  peer.suspected = !exited;
784
+ if (exited)
785
+ invalidateExpiry(peer);
786
+ else if (!peer.closing && !peer.publishing)
787
+ peer.expiry = new AbortController();
655
788
  changed = true;
656
789
  for (const job of [...jobs.values(), ...backgroundJobs])
657
790
  if (!job.committed && (job.client === id || job.peers.has(id)))
@@ -730,6 +863,8 @@ export async function startServer(root, execute, hooks = {}) {
730
863
  return closing;
731
864
  closing = (async () => {
732
865
  closed = true;
866
+ for (const peer of participants.values())
867
+ invalidateExpiry(peer);
733
868
  clearInterval(heartbeat);
734
869
  for (const waiting of [...pending.values()])
735
870
  if (!waiting.callback.kind.startsWith("queue-"))
@@ -105,7 +105,27 @@ After grace, stop new automatic work and cancel cancellable work. Drain foregrou
105
105
 
106
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
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.
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.
109
129
 
110
130
  ## Repository lifetime smoke
111
131
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@narumitw/pi-sync-daemon",
3
- "version": "0.3.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",