@narumitw/pi-sync-daemon 0.3.0 → 0.5.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.
@@ -11,16 +11,12 @@ const MIGRATION_LOCK_NAME = ".pi-sync-state-migration.lock";
11
11
  const MIGRATION_LOCK_STALE_MS = 30_000;
12
12
  const MIGRATION_LOCK_UPDATE_MS = 10_000;
13
13
  const sharedStateDirectoryGuards = new Map();
14
- export function stateDir() {
15
- const roots = inspectStateRoots();
16
- if (roots.canonical)
17
- return canonicalStateDir();
18
- if (roots.legacy)
19
- return legacyStateDir();
20
- return canonicalStateDir();
14
+ export function stateDir(root = getAgentDir()) {
15
+ const roots = inspectStateRoots(root);
16
+ return roots.legacy ? legacyStateDir(root) : canonicalStateDir(root);
21
17
  }
22
- export function legacyStateDir() {
23
- return path.join(getAgentDir(), LEGACY_DIRECTORY_NAME);
18
+ export function legacyStateDir(root = getAgentDir()) {
19
+ return path.join(root, LEGACY_DIRECTORY_NAME);
24
20
  }
25
21
  export function stateDirectoryMigrationNotice() {
26
22
  const roots = inspectStateRoots();
@@ -131,11 +127,15 @@ async function acquireSharedStateDirectoryGuard() {
131
127
  };
132
128
  }
133
129
  }
134
- async function acquireStateDirectoryGuard() {
130
+ /** Protect path selection and a synchronous access outside the engine host. */
131
+ export async function withStateDirectoryGuardForRoot(root, access) {
132
+ return runWithStateDirectoryGuard(await acquireStateDirectoryGuard(root), async () => access());
133
+ }
134
+ async function acquireStateDirectoryGuard(root = getAgentDir()) {
135
135
  let compromisedError;
136
- const release = await lockfile.lock(getAgentDir(), {
136
+ const release = await lockfile.lock(root, {
137
137
  fs: LOCKFILE_FS_ADAPTER,
138
- lockfilePath: migrationLockPath(),
138
+ lockfilePath: migrationLockPath(root),
139
139
  realpath: false,
140
140
  stale: MIGRATION_LOCK_STALE_MS,
141
141
  update: MIGRATION_LOCK_UPDATE_MS,
@@ -181,17 +181,19 @@ async function runWithStateDirectoryGuard(guard, fn) {
181
181
  function isLockHeldError(error) {
182
182
  return error.code === "ELOCKED";
183
183
  }
184
- function canonicalStateDir() {
185
- return path.join(getAgentDir(), CANONICAL_DIRECTORY_NAME);
184
+ function canonicalStateDir(root = getAgentDir()) {
185
+ return path.join(root, CANONICAL_DIRECTORY_NAME);
186
186
  }
187
- function migrationLockPath() {
188
- return path.join(getAgentDir(), MIGRATION_LOCK_NAME);
187
+ function migrationLockPath(root = getAgentDir()) {
188
+ return path.join(root, MIGRATION_LOCK_NAME);
189
189
  }
190
- function inspectStateRoots() {
191
- const canonical = isDirectoryRoot(canonicalStateDir(), "canonical");
192
- const legacy = isDirectoryRoot(legacyStateDir(), "legacy");
190
+ function inspectStateRoots(root = getAgentDir()) {
191
+ const canonicalPath = canonicalStateDir(root);
192
+ const legacyPath = legacyStateDir(root);
193
+ const canonical = isDirectoryRoot(canonicalPath, "canonical");
194
+ const legacy = isDirectoryRoot(legacyPath, "legacy");
193
195
  if (canonical && legacy) {
194
- throw new Error(`Both legacy ${legacyStateDir()} and canonical ${canonicalStateDir()} pi-sync state directories exist. Close all Pi sessions and reconcile the directories manually; pi-sync will not merge or delete either directory.`);
196
+ throw new Error(`Both legacy ${legacyPath} and canonical ${canonicalPath} pi-sync state directories exist. Close all Pi sessions and reconcile the directories manually; pi-sync will not merge or delete either directory.`);
195
197
  }
196
198
  return { canonical, legacy };
197
199
  }
@@ -14,7 +14,27 @@ export interface DaemonPaths extends RuntimePaths {
14
14
  }
15
15
  export declare function daemonPaths(paths: RuntimePaths, instance: string): DaemonPaths;
16
16
  export declare function privateDirectory(directory: string): Promise<void>;
17
+ type OwnerRecord = Pick<Identity, "version" | "root" | "instance" | "pid">;
18
+ type ProcessIdentity = {
19
+ pid: number;
20
+ birth?: string;
21
+ };
22
+ /** The exit barrier records an authenticated owner without keeping its IPC token. */
23
+ export type UpgradeOwner = OwnerRecord & ProcessIdentity;
24
+ export declare function upgradeFile(paths: RuntimePaths): string;
25
+ /** One private archive per upgrade instance, including across partial repair retries. */
26
+ export declare function upgradeArchivePath(paths: RuntimePaths, owner: Pick<UpgradeOwner, "instance">): string;
27
+ /** A repair must finish explicitly once it starts changing consent or moving evidence. */
28
+ export declare function upgradeRepairStarted(paths: RuntimePaths, owner: Pick<UpgradeOwner, "instance">): Promise<boolean>;
29
+ export declare function readUpgradeOwner(paths: RuntimePaths): Promise<UpgradeOwner | undefined>;
30
+ export declare function recordUpgradeOwner(paths: RuntimePaths, { version, root, instance, pid, birth }: UpgradeOwner): Promise<void>;
31
+ export declare function clearUpgradeOwner(paths: RuntimePaths): Promise<void>;
17
32
  export declare function readIdentity(paths: RuntimePaths): Promise<Identity | undefined>;
18
33
  export declare function processExists(pid: number): boolean;
34
+ /** Linux start ticks from a procfs view that agrees with the caller's PID namespace. */
35
+ export declare function readProcessBirth(pid: number): Promise<string | undefined>;
36
+ /** A marked owner must be visible in the same PID namespace before absence proves exit. */
37
+ export declare function processExited({ pid, birth }: ProcessIdentity): Promise<boolean>;
19
38
  export declare function publishIdentity(paths: RuntimePaths, identity: Identity): Promise<void>;
20
39
  export declare function readJsonBody(source: AsyncIterable<Uint8Array>): Promise<unknown>;
40
+ export {};
package/dist/identity.js CHANGED
@@ -60,33 +60,81 @@ export async function privateDirectory(directory) {
60
60
  (process.platform !== "win32" && (stat.mode & 0o077) !== 0))
61
61
  throw new Error("Unsafe daemon runtime directory.");
62
62
  }
63
+ const birthPattern = /^[a-f0-9]{8}-(?:[a-f0-9]{4}-){3}[a-f0-9]{12}:([1-9][0-9]{0,9})\.([1-9][0-9]{0,9}):(0|[1-9][0-9]{0,19})$/u;
64
+ export function upgradeFile(paths) {
65
+ return path.join(paths.directory, "upgrade-owner.json");
66
+ }
67
+ /** One private archive per upgrade instance, including across partial repair retries. */
68
+ export function upgradeArchivePath(paths, owner) {
69
+ return path.join(paths.directory, `upgrade-recovery-${owner.instance}`);
70
+ }
71
+ /** A repair must finish explicitly once it starts changing consent or moving evidence. */
72
+ export async function upgradeRepairStarted(paths, owner) {
73
+ try {
74
+ await fs.lstat(upgradeArchivePath(paths, owner));
75
+ return true;
76
+ }
77
+ catch (error) {
78
+ if (error.code === "ENOENT")
79
+ return false;
80
+ throw error;
81
+ }
82
+ }
83
+ export async function readUpgradeOwner(paths) {
84
+ const value = await readPrivateRecord(upgradeFile(paths));
85
+ if (value === undefined)
86
+ return;
87
+ if (!validOwner(value, paths.root) || (value.birth !== undefined && !validBirth(value.birth)))
88
+ throw new Error("Invalid daemon upgrade record; state retained.");
89
+ const { version, root, instance, pid, birth } = value;
90
+ return birth === undefined ? { version, root, instance, pid } : { version, root, instance, pid, birth };
91
+ }
92
+ export function recordUpgradeOwner(paths, { version, root, instance, pid, birth }) {
93
+ return publishPrivateRecord(paths, upgradeFile(paths), { version, root, instance, pid, birth });
94
+ }
95
+ export function clearUpgradeOwner(paths) {
96
+ return fs.rm(upgradeFile(paths), { force: true });
97
+ }
63
98
  export async function readIdentity(paths) {
99
+ const value = await readPrivateRecord(paths.identity);
100
+ if (value === undefined)
101
+ return;
102
+ if (!validOwner(value, paths.root) || typeof value.token !== "string" || !/^[a-f0-9]{64}$/u.test(value.token))
103
+ throw new Error("Invalid or incompatible daemon identity; state retained.");
104
+ return { ...value, token: value.token };
105
+ }
106
+ function validBirth(value) {
107
+ const fields = typeof value === "string" && birthPattern.exec(value);
108
+ return (!!fields &&
109
+ Number(fields[1]) <= 0xffff_ffff &&
110
+ Number(fields[2]) <= 0xffff_ffff &&
111
+ BigInt(fields[3]) <= 0xffffffffffffffffn);
112
+ }
113
+ function validOwner(value, root) {
114
+ return (record(value) &&
115
+ value.version === 1 &&
116
+ value.root === root &&
117
+ typeof value.instance === "string" &&
118
+ /^[a-f0-9-]{36}$/u.test(value.instance) &&
119
+ Number.isSafeInteger(value.pid) &&
120
+ Number(value.pid) >= 1 &&
121
+ Number(value.pid) <= 2_147_483_647);
122
+ }
123
+ async function readPrivateRecord(file) {
64
124
  let handle;
65
125
  try {
66
- const before = await fs.lstat(paths.identity);
126
+ const before = await fs.lstat(file);
67
127
  if (!before.isFile() ||
68
128
  before.isSymbolicLink() ||
69
129
  before.size > 8192 ||
70
130
  (process.getuid && before.uid !== process.getuid()) ||
71
131
  (process.platform !== "win32" && (before.mode & 0o077) !== 0))
72
132
  throw new Error("Unsafe daemon identity file.");
73
- handle = await fs.open(paths.identity, "r");
133
+ handle = await fs.open(file, "r");
74
134
  const opened = await handle.stat();
75
135
  if (before.dev !== opened.dev || before.ino !== opened.ino)
76
136
  throw new Error("Daemon identity changed while opening.");
77
- const value = JSON.parse(await handle.readFile("utf8"));
78
- if (!record(value) ||
79
- value.version !== 1 ||
80
- value.root !== paths.root ||
81
- typeof value.instance !== "string" ||
82
- !/^[a-f0-9-]{36}$/u.test(value.instance) ||
83
- !Number.isSafeInteger(value.pid) ||
84
- Number(value.pid) < 1 ||
85
- Number(value.pid) > 2_147_483_647 ||
86
- typeof value.token !== "string" ||
87
- !/^[a-f0-9]{64}$/u.test(value.token))
88
- throw new Error("Invalid or incompatible daemon identity; state retained.");
89
- return value;
137
+ return JSON.parse(await handle.readFile("utf8"));
90
138
  }
91
139
  catch (error) {
92
140
  if (error.code === "ENOENT")
@@ -106,14 +154,74 @@ export function processExists(pid) {
106
154
  return error.code !== "ESRCH";
107
155
  }
108
156
  }
109
- export async function publishIdentity(paths, identity) {
157
+ async function readPidNamespace() {
158
+ const scope = await fs.readlink("/proc/self/ns/pid");
159
+ return /^pid:\[([0-9]+)\]$/u.exec(scope)?.[1];
160
+ }
161
+ /** Linux start ticks from a procfs view that agrees with the caller's PID namespace. */
162
+ export async function readProcessBirth(pid) {
163
+ if (process.platform !== "linux")
164
+ return;
165
+ try {
166
+ const [status, pidNamespace, timeScope, boot, stat] = await Promise.all([
167
+ fs.readFile("/proc/self/status", "utf8"),
168
+ readPidNamespace(),
169
+ fs.readlink("/proc/self/ns/time"),
170
+ fs.readFile("/proc/sys/kernel/random/boot_id", "utf8"),
171
+ fs.readFile(`/proc/${pid}/stat`, "utf8"),
172
+ ]);
173
+ if (/^NSpid:[\t ]+([0-9]+)[\t ]*$/mu.exec(status)?.[1] !== String(process.pid))
174
+ return;
175
+ // The kernel offsets start ticks using the reader's time namespace.
176
+ const timeNamespace = /^time:\[([0-9]+)\]$/u.exec(timeScope)?.[1];
177
+ if (pidNamespace === undefined || timeNamespace === undefined || !stat.startsWith(`${pid} (`))
178
+ return;
179
+ // The parenthesized comm can contain spaces, parentheses, and newlines. Starttime is field 22.
180
+ const end = stat.lastIndexOf(") ");
181
+ if (end < String(pid).length + 2)
182
+ return;
183
+ const ticks = stat
184
+ .slice(end + 2)
185
+ .trim()
186
+ .split(/\s+/u)[19];
187
+ const birth = `${boot.trim()}:${pidNamespace}.${timeNamespace}:${ticks}`;
188
+ if (validBirth(birth))
189
+ return birth;
190
+ }
191
+ catch {
192
+ // Missing or unreadable procfs is not evidence of process exit.
193
+ }
194
+ }
195
+ /** A marked owner must be visible in the same PID namespace before absence proves exit. */
196
+ export async function processExited({ pid, birth }) {
197
+ const exists = processExists(pid);
198
+ if (birth === undefined)
199
+ return !exists; // Legacy PID-only records.
200
+ if (process.platform !== "linux" || !validBirth(birth))
201
+ return false;
202
+ const namespaces = birth.split(":")[1];
203
+ if (!exists) {
204
+ try {
205
+ return (await readPidNamespace()) === namespaces.split(".")[0];
206
+ }
207
+ catch {
208
+ return false;
209
+ }
210
+ }
211
+ const current = await readProcessBirth(pid);
212
+ return current !== undefined && current !== birth && current.split(":")[1] === namespaces;
213
+ }
214
+ export function publishIdentity(paths, identity) {
215
+ return publishPrivateRecord(paths, paths.identity, identity);
216
+ }
217
+ async function publishPrivateRecord(paths, file, value) {
110
218
  const temporary = path.join(paths.directory, `.${randomUUID()}.json`);
111
219
  const handle = await fs.open(temporary, "wx", 0o600);
112
220
  try {
113
- await handle.writeFile(JSON.stringify(identity));
221
+ await handle.writeFile(JSON.stringify(value));
114
222
  await handle.sync();
115
223
  await handle.close();
116
- await fs.rename(temporary, paths.identity);
224
+ await fs.rename(temporary, file);
117
225
  }
118
226
  finally {
119
227
  await handle.close().catch(() => { });
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,14 +1,16 @@
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";
7
+ import { DAEMON_BUILD_VERSION } from "./build-version.js";
6
8
  import { endpointOwner } from "./endpoint.js";
7
- import { canonicalRootGuard, daemonPaths, privateDirectory, processExists, publishIdentity, readIdentity, readJsonBody, runtimePaths, } from "./identity.js";
9
+ import { canonicalRootGuard, daemonPaths, privateDirectory, processExists, publishIdentity, readIdentity, readJsonBody, readUpgradeOwner, runtimePaths, } from "./identity.js";
8
10
  import { createIdleExit } from "./idle-exit.js";
9
11
  import { withCleanup } from "./lifecycle.js";
10
12
  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";
13
+ import { ClientContactExpiredError, DaemonStoppingError, MAX_MESSAGE_BYTES, MAX_REVIEW_BYTES, operationPrefix, PROTOCOL_VERSION, REVIEW_PAGE_CHARS, record, remoteError, validateFacts, validateHandoff, validId, } from "./protocol.js";
12
14
  export async function startServer(root, execute, hooks = {}) {
13
15
  const base = await runtimePaths(root);
14
16
  const identity = {
@@ -50,6 +52,7 @@ export async function startServer(root, execute, hooks = {}) {
50
52
  const peersFile = path.join(paths.directory, "clients.json");
51
53
  let sequence = 0;
52
54
  let closed = false;
55
+ let stopRequested = false;
53
56
  let automaticClosing = false;
54
57
  let peerWriteFailed = false;
55
58
  let idleExit;
@@ -59,23 +62,23 @@ export async function startServer(root, execute, hooks = {}) {
59
62
  let closing;
60
63
  let peerWrites = Promise.resolve();
61
64
  let heartbeat;
62
- function savePeers() {
65
+ function savePeers(candidate) {
63
66
  idleExit?.changed();
64
- const operation = peerWrites.then(writePeers);
67
+ const operation = peerWrites.then(() => writePeers(candidate));
65
68
  peerWrites = operation.catch(() => {
66
69
  peerWriteFailed = true;
67
70
  hooks.failure?.();
68
71
  });
69
72
  return operation;
70
73
  }
71
- async function writePeers() {
74
+ async function writePeers(candidate) {
72
75
  const temporary = path.join(paths.directory, `.${randomUUID()}.clients`);
73
76
  const data = {
74
77
  version: 1,
75
78
  root: paths.root,
76
79
  clients: [...participants.values()]
77
80
  .filter((peer) => processExists(peer.facts.pid))
78
- .map((peer) => ({ ...peer.facts, handoff: peer.handoff })),
81
+ .map((peer) => ({ ...(candidate?.peer === peer ? candidate.facts : peer.facts), handoff: peer.handoff })),
79
82
  };
80
83
  const handle = await fs.open(temporary, "wx", 0o600);
81
84
  try {
@@ -186,8 +189,16 @@ export async function startServer(root, execute, hooks = {}) {
186
189
  const liveClientFacts = () => [...participants.values()].filter((peer) => processExists(peer.facts.pid)).map((peer) => peer.facts);
187
190
  const participantFacts = () => [...participants.values()]
188
191
  .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));
192
+ .map((peer) => peer.closing || peer.suspected ? { ...(peer.resumeFacts ?? peer.facts), idle: false } : peer.facts);
193
+ const contactState = (peer) => {
194
+ if (closed || stopRequested || compromised || peer.publishing || peer.closing || !processExists(peer.facts.pid))
195
+ return "inactive";
196
+ if (peer.connected)
197
+ return "active";
198
+ return peer.expiry ? "expired" : "inactive";
199
+ };
190
200
  const poll = (peer, cursor, job) => ({
201
+ contact: contactState(peer),
191
202
  cursor: sequence,
192
203
  callbacks: [...peer.callbacks.values()],
193
204
  events: peer.events.filter((event) => event.id > (typeof cursor === "number" && Number.isSafeInteger(cursor) ? cursor : 0)),
@@ -238,6 +249,18 @@ export async function startServer(root, execute, hooks = {}) {
238
249
  Buffer.byteLength(JSON.stringify([...peer.callbacks.values(), callback])) > MAX_MESSAGE_BYTES / 8)
239
250
  throw new Error("Callback exceeds its byte limit; no review was approved.");
240
251
  job.peers.add(target);
252
+ const reservation = record(data) && typeof data.reservation === "string" ? data.reservation : undefined;
253
+ if (kind === "queue-acquire" || cleanup) {
254
+ // A lost acquire response is not proof that Pi never acquired the queue.
255
+ // Bound retained evidence even if a failing or malformed executor keeps requesting grants.
256
+ peer.reservations ??= new Set();
257
+ if (!reservation)
258
+ peer.resumeUnsafe = true;
259
+ else if (peer.reservations.size < 64)
260
+ peer.reservations.add(reservation);
261
+ else if (!peer.reservations.has(reservation))
262
+ peer.resumeUnsafe = true;
263
+ }
241
264
  return new Promise((resolve, reject) => {
242
265
  let timer;
243
266
  const effectiveSignal = cleanup ? undefined : signal;
@@ -249,6 +272,8 @@ export async function startServer(root, execute, hooks = {}) {
249
272
  if (!pending.delete(callback.id))
250
273
  return;
251
274
  peer.callbacks.delete(callback.id);
275
+ if (cleanup && reservation && error === undefined && value === true)
276
+ peer.reservations?.delete(reservation);
252
277
  sequence++;
253
278
  if (error)
254
279
  reject(error);
@@ -344,6 +369,12 @@ export async function startServer(root, execute, hooks = {}) {
344
369
  .catch((error) => {
345
370
  job.view.phase = "failed";
346
371
  job.view.error = remoteError(error);
372
+ if (job.committed)
373
+ for (const id of new Set([client, ...job.peers])) {
374
+ const affected = participants.get(id);
375
+ if (affected)
376
+ affected.resumeUnsafe = true;
377
+ }
347
378
  })
348
379
  .finally(() => {
349
380
  for (const waiting of [...pending.values()])
@@ -355,16 +386,93 @@ export async function startServer(root, execute, hooks = {}) {
355
386
  jobs.set(id, job);
356
387
  return job;
357
388
  }
389
+ function invalidateExpiry(peer) {
390
+ peer.expiry?.abort(new DOMException("Client is no longer eligible to resume contact", "AbortError"));
391
+ peer.expiry = undefined;
392
+ peer.resumeFacts = undefined;
393
+ }
394
+ async function resumeContact(facts, disconnect) {
395
+ const peer = requireParticipant(facts.id, true);
396
+ const expiry = peer.expiry;
397
+ const matchesSession = (old) => old.pid === facts.pid &&
398
+ old.generation === facts.generation &&
399
+ old.cwd === facts.cwd &&
400
+ old.sessionId === facts.sessionId &&
401
+ old.sessionFile === facts.sessionFile &&
402
+ old.sessionDir === facts.sessionDir &&
403
+ old.mode === facts.mode &&
404
+ old.hasUI === facts.hasUI;
405
+ if (!expiry || contactState(peer) !== "expired" || peer.resumeFacts || !matchesSession(peer.facts))
406
+ throw new Error("Client is not eligible to resume contact for this session.");
407
+ const signal = disconnect ? AbortSignal.any([disconnect, expiry.signal]) : expiry.signal;
408
+ const candidate = structuredClone(facts);
409
+ const recheck = () => {
410
+ assertOwner();
411
+ signal.throwIfAborted();
412
+ if (peerWriteFailed)
413
+ throw new Error("Daemon client ledger persistence is uncertain; reconcile with the existing owner before reconnecting.");
414
+ if (participants.get(facts.id) !== peer ||
415
+ peer.expiry !== expiry ||
416
+ contactState(peer) !== "expired" ||
417
+ !matchesSession(peer.facts))
418
+ throw new Error("Client is no longer eligible to resume contact.");
419
+ };
420
+ const affected = (job) => job.client === facts.id || job.peers.has(facts.id);
421
+ const running = (job) => affected(job) && job.view.phase === "running";
422
+ const stopped = Promise.withResolvers();
423
+ const abort = addAbortListener(signal, () => stopped.reject(signal.reason));
424
+ try {
425
+ recheck();
426
+ // Expose the new binding to the monitor, but only as a non-ready, busy suspect.
427
+ peer.resumeFacts = { ...candidate, ready: false };
428
+ // Never wait for jobs or monitor transitions inside admission: they can need the fence.
429
+ await Promise.race([
430
+ Promise.all([hooks.factsChanged?.(), ...[...jobs.values()].filter(running).map((job) => job.promise)]),
431
+ stopped.promise,
432
+ ]);
433
+ recheck();
434
+ return await admission.run(async () => {
435
+ const safe = () => {
436
+ recheck();
437
+ if (peer.resumeUnsafe ||
438
+ peer.reservations?.size ||
439
+ peer.callbacks.size ||
440
+ [...jobs.values()].some(running) ||
441
+ [...backgroundJobs].some((job) => job.committed && affected(job)))
442
+ throw new Error("Client work or file-queue cleanup is uncertain; reconcile with the existing owner before reconnecting.");
443
+ };
444
+ safe();
445
+ // The staged facts have the same location and identity. Even if cancelled mid-write,
446
+ // the on-disk record does not authorize work or confer expiry eligibility on restart.
447
+ await savePeers({ peer, facts: candidate });
448
+ safe();
449
+ peer.facts = candidate;
450
+ peer.seen = Date.now();
451
+ peer.expiry = undefined;
452
+ peer.resumeFacts = undefined;
453
+ peer.suspected = false;
454
+ peer.connected = true;
455
+ hooks.idle?.();
456
+ return poll(peer, 0);
457
+ }, signal);
458
+ }
459
+ finally {
460
+ abort[Symbol.dispose]();
461
+ if (peer.expiry === expiry)
462
+ peer.resumeFacts = undefined;
463
+ }
464
+ }
358
465
  async function detach(id, retain = false, handoff) {
359
466
  const peer = participants.get(id);
360
467
  if (!peer) {
361
468
  if (closedClients.size < 10_000)
362
469
  closedClients.add(id);
363
- return { cursor: sequence, callbacks: [], events: [] };
470
+ return { contact: "inactive", cursor: sequence, callbacks: [], events: [] };
364
471
  }
365
472
  if (closedClients.has(id))
366
473
  return poll(peer, 0);
367
474
  peer.closing = true;
475
+ invalidateExpiry(peer);
368
476
  for (const waiting of [...pending.values()])
369
477
  if (waiting.target === id && !waiting.callback.kind.startsWith("queue-"))
370
478
  waiting.reject(new Error("Client detaching."));
@@ -395,7 +503,13 @@ export async function startServer(root, execute, hooks = {}) {
395
503
  if (!cleanup)
396
504
  assertOwner();
397
505
  if (method === "hello")
398
- return { version: PROTOCOL_VERSION, root: identity.root, instance: identity.instance, pid: identity.pid };
506
+ return {
507
+ version: PROTOCOL_VERSION,
508
+ buildVersion: DAEMON_BUILD_VERSION,
509
+ root: identity.root,
510
+ instance: identity.instance,
511
+ pid: identity.pid,
512
+ };
399
513
  if (method === "attach") {
400
514
  const attached = await admission.run(async () => {
401
515
  assertOwner();
@@ -416,8 +530,12 @@ export async function startServer(root, execute, hooks = {}) {
416
530
  (old.facts.pid !== params.pid ||
417
531
  ((old.connected || old.suspected) && old.facts.generation !== params.generation)))
418
532
  throw new Error("Client identity collision.");
533
+ if (old)
534
+ invalidateExpiry(old);
419
535
  participants.set(params.id, {
420
536
  facts: structuredClone(params),
537
+ reservations: old?.reservations,
538
+ resumeUnsafe: old?.resumeUnsafe,
421
539
  callbacks: old?.callbacks ?? new Map(),
422
540
  events: old?.events ?? [],
423
541
  connected: true,
@@ -464,6 +582,10 @@ export async function startServer(root, execute, hooks = {}) {
464
582
  assertOwner();
465
583
  return poll(attached, 0);
466
584
  }
585
+ if (method === "resume-contact") {
586
+ validateFacts(params);
587
+ return resumeContact(params, signal);
588
+ }
467
589
  if (!record(params))
468
590
  throw new Error("Invalid request parameters.");
469
591
  const contact = typeof params.client === "string" ? participants.get(params.client) : undefined;
@@ -476,10 +598,13 @@ export async function startServer(root, execute, hooks = {}) {
476
598
  }
477
599
  if (method === "update") {
478
600
  validateFacts(params.facts);
479
- const peer = requireParticipant(params.facts.id);
601
+ const peer = requireParticipant(params.facts.id, true);
480
602
  const old = peer.facts;
481
603
  if (old.pid !== params.facts.pid || old.generation !== params.facts.generation)
482
604
  throw new Error("Client generation mismatch.");
605
+ if (contactState(peer) === "expired")
606
+ throw new ClientContactExpiredError();
607
+ requireParticipant(params.facts.id);
483
608
  peer.facts = structuredClone(params.facts);
484
609
  const published = peer.facts;
485
610
  try {
@@ -491,7 +616,15 @@ export async function startServer(root, execute, hooks = {}) {
491
616
  throw error;
492
617
  }
493
618
  await hooks.factsChanged?.();
494
- return poll(peer, 0);
619
+ assertOwner();
620
+ if (participants.get(params.facts.id) !== peer)
621
+ throw new Error("Client changed during update.");
622
+ const reply = poll(peer, 0);
623
+ if (reply.contact === "expired")
624
+ throw new ClientContactExpiredError();
625
+ if (reply.contact !== "active")
626
+ throw new Error("Client is not attached or is closing.");
627
+ return reply;
495
628
  }
496
629
  if (["detach", "pause", "handoff"].includes(method)) {
497
630
  if (!validId(params.client))
@@ -564,6 +697,7 @@ export async function startServer(root, execute, hooks = {}) {
564
697
  return job.view;
565
698
  }
566
699
  if (method === "stop") {
700
+ stopRequested = true;
567
701
  setImmediate(() => {
568
702
  void close().catch(() => { });
569
703
  });
@@ -600,12 +734,14 @@ export async function startServer(root, execute, hooks = {}) {
600
734
  respond(response, 403, { error: { name: "Error", message: "Invalid daemon identity or protocol." } });
601
735
  return;
602
736
  }
603
- if (body.method === "attach") {
737
+ if (body.method === "attach" || body.method === "resume-contact") {
604
738
  admissionController = new AbortController();
605
739
  response.once("close", disconnect);
740
+ if (response.destroyed)
741
+ disconnect();
606
742
  }
607
743
  const operation = handle(body.method, body.params, admissionController?.signal);
608
- if (["attach", "update", "detach", "pause", "handoff"].includes(body.method)) {
744
+ if (["attach", "resume-contact", "update", "detach", "pause", "handoff"].includes(body.method)) {
609
745
  peerOperations.add(operation);
610
746
  void operation.finally(() => peerOperations.delete(operation)).catch(() => { });
611
747
  }
@@ -624,6 +760,9 @@ export async function startServer(root, execute, hooks = {}) {
624
760
  const endpoint = endpointOwner(server, paths);
625
761
  try {
626
762
  assertOwner();
763
+ if (await readUpgradeOwner(paths))
764
+ throw new Error("A daemon upgrade is pending; use normal startup to verify the previous owner.");
765
+ assertOwner();
627
766
  await endpoint.listen();
628
767
  assertOwner();
629
768
  await publishIdentity(paths, identity);
@@ -652,6 +791,10 @@ export async function startServer(root, execute, hooks = {}) {
652
791
  continue;
653
792
  peer.connected = false;
654
793
  peer.suspected = !exited;
794
+ if (exited)
795
+ invalidateExpiry(peer);
796
+ else if (!peer.closing && !peer.publishing)
797
+ peer.expiry = new AbortController();
655
798
  changed = true;
656
799
  for (const job of [...jobs.values(), ...backgroundJobs])
657
800
  if (!job.committed && (job.client === id || job.peers.has(id)))
@@ -730,6 +873,8 @@ export async function startServer(root, execute, hooks = {}) {
730
873
  return closing;
731
874
  closing = (async () => {
732
875
  closed = true;
876
+ for (const peer of participants.values())
877
+ invalidateExpiry(peer);
733
878
  clearInterval(heartbeat);
734
879
  for (const waiting of [...pending.values()])
735
880
  if (!waiting.callback.kind.startsWith("queue-"))
@@ -0,0 +1,10 @@
1
+ /** Explicit repair never launches or sends requests to a daemon. */
2
+ export declare function repairUpgrade(root: string): Promise<{
3
+ repaired: boolean;
4
+ revokedGrants?: undefined;
5
+ archive?: undefined;
6
+ } | {
7
+ repaired: boolean;
8
+ revokedGrants: number;
9
+ archive: string;
10
+ }>;