@narumitw/pi-sync-daemon 0.4.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.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,11 @@
1
1
  # @narumitw/pi-sync-daemon
2
2
 
3
+ ## 0.5.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 1f44df7: On the first active connection after an update, Pi Sync can replace an older daemon only if compatible, authenticated IPC works and no retained unattended grant blocks the upgrade. The replacement waits for the old daemon to release its identity and exit. If any check fails, follow the [manual recovery guide](https://github.com/narumiruna/pi-extensions/blob/main/packages/pi-sync/docs/daemon-migration.md#ownership-and-upgrade). Passive and shutdown paths do not start a replacement. If an interactive session switch cannot upgrade the daemon, keep file protection when the old owner can still accept the session. Use `status` to find the pending or last recorded owner. When `repair-upgrade` successfully repairs a pending upgrade after verifying exit, it revokes all retained unattended grants and keeps the recovery records in one private archive across retries. It does not start a daemon.
8
+
3
9
  ## 0.4.0
4
10
 
5
11
  ### Minor Changes
package/README.md CHANGED
@@ -38,11 +38,13 @@ node packages/pi-sync-daemon/dist/cli.js status --root /tmp/my-pi-sync-daemon-sm
38
38
  node packages/pi-sync-daemon/dist/cli.js stop --root /tmp/my-pi-sync-daemon-smoke
39
39
  ```
40
40
 
41
- `start` reports the same instance when a compatible service already owns the directory. Connecting alone does not configure a backend or authorize transfers. Use the Pi client's reviewed setup flow for synchronization.
41
+ `start` reuses a compatible owner on the same or a newer build. It stops an older owner and waits
42
+ for it to exit before launching the new build, unless the stop cannot be verified or unattended
43
+ permission needs review. Connecting alone does not configure a backend or authorize transfers. Use the Pi client's reviewed setup flow for synchronization.
42
44
 
43
45
  ## 💬 Commands
44
46
 
45
- `pi-sync-daemon <start|status|stop|restart|serve> --root <agent-directory>` uses an explicit root. `status` and `stop` never launch an absent service. `restart` drains the compatible owner before replacement; an incompatible or unreachable live owner fails closed. `serve` is the internal foreground launch target, not an OS registration command.
47
+ `pi-sync-daemon <start|status|stop|restart|repair-upgrade|serve> --root <agent-directory>` uses an explicit root. `status`, `stop`, and `repair-upgrade` never launch a service. `restart` drains the compatible owner before replacement; an incompatible or unreachable live owner fails closed. `serve` is the internal foreground launch target, not an OS registration command. Use `repair-upgrade` only for a blocked, pending upgrade. It verifies the old owner's exit, revokes all retained unattended grants for the root, and archives the recovery records.
46
48
 
47
49
  Pi starts the service only after configured interactive synchronization is needed or an explicit setup/command authorizes it. Closing Pi detaches that client; the daemon owns the shared lifetime decision. After no registered live client PID remains for that canonical root, a fixed 30-second grace period starts unless a valid after-exit grant keeps the service running. Explicit CLI `start` without clients follows the same rule. A client arriving before shutdown becomes final cancels automatic exit. `/new`, `/reload`, fork, and resume retain protection while their Pi process is alive. Use `/sync daemon` for status, reviewed old-process handover, and setup-bound unattended authorization.
48
50
 
@@ -70,9 +72,13 @@ Close or upgrade every old Pi process before reviewed handover. An absent operat
70
72
 
71
73
  Automatic exit first stops new automatic work, cancels cancellable work, and drains writes, queue-release acknowledgements, persistence, and owned callbacks before releasing ownership. It adds no final sync or model request. Uncertain consent publication, failed revocation, or cleanup failure keeps the owner paused with evidence retained; automatic restart must not restore an older grant. Repair persistence and use the existing revocation/repair path before explicit restart. The next eligible interactive client or explicit command can restart through singleton startup only after the old owner's exit is proven; print/JSON never launch a replacement.
72
74
 
73
- Stop the service before package updates, local rebuilds, or rollback, verify owner exit, and preserve pending journals and backups. A compatible connection does not upgrade a running implementation; restart explicitly after installation. Do not downgrade over pending/newer recovery evidence or restore old settings over newer bytes. Expired or old-instance operation IDs must reconcile existing journals rather than replay a possible commit. The bounded per-instance result ledger requires an explicit drained restart when full.
75
+ Stop the service and verify owner exit before an in-place rebuild or rollback. Preserve pending
76
+ journals and backups. Rebuilding without changing the package version does not replace the running
77
+ owner. See the [daemon upgrade guide](https://github.com/narumiruna/pi-extensions/blob/main/packages/pi-sync/docs/daemon-migration.md#ownership-and-upgrade) for package updates and manual recovery. Do not downgrade over pending/newer recovery evidence or restore old settings over newer bytes. Expired or old-instance operation IDs must reconcile existing journals rather than replay a possible commit. The bounded per-instance result ledger requires an explicit drained restart when full.
74
78
 
75
- CLI `status` reports the private lifecycle-log path. It retains at most 8 KiB of timestamps and lifecycle phases, not exception text, credentials, model output, or sync content; older entries roll over. It is diagnostic evidence, not a recovery journal. Child stdio is detached and discarded.
79
+ CLI `status` reports `recordedPid` from a validated identity file and `pid` only after a verified handshake. A pending upgrade has a separate `pendingUpgradePid`. `running: null` means the handshake failed, with or without a pending upgrade. Unknown status proves neither exit nor compatibility. Use diagnostics from an already available compatible version; if you cannot identify the owner, stop and preserve the records. Status does not expose the IPC token.
80
+
81
+ A verified handshake also reports the private lifecycle-log path. The log retains at most 8 KiB of timestamps and lifecycle phases, not exception text, credentials, model output, or sync content; older entries roll over. It is diagnostic evidence, not a recovery journal. Child stdio is detached and discarded.
76
82
 
77
83
  The source-linked [architecture and safety contract](docs/architecture.md) defines ownership, resolver capability checks, write coordination, and the decision matrix. It distinguishes required checks from completed evidence.
78
84
 
@@ -0,0 +1 @@
1
+ export declare const DAEMON_BUILD_VERSION: string;
@@ -0,0 +1,8 @@
1
+ import { readFileSync } from "node:fs";
2
+ import { valid } from "semver";
3
+ // Capture the installed build at module load. A later package update must not
4
+ // change the version advertised by an already running process.
5
+ const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
6
+ if (typeof version !== "string" || valid(version) !== version)
7
+ throw new Error("Invalid Pi Sync daemon build version.");
8
+ export const DAEMON_BUILD_VERSION = version;
package/dist/cli.js CHANGED
@@ -1,18 +1,27 @@
1
1
  #!/usr/bin/env node
2
2
  import path from "node:path";
3
3
  import { setTimeout as delay } from "node:timers/promises";
4
+ import { valid } from "semver";
4
5
  import { ensureDaemon, requestDaemon } from "./client.js";
5
- import { privateDirectory, processExists, readIdentity, runtimePaths } from "./identity.js";
6
+ import { privateDirectory, processExists, processExited, readIdentity, readUpgradeOwner, runtimePaths, } from "./identity.js";
6
7
  import { openLifecycleLog } from "./lifecycle-log.js";
7
8
  import { record } from "./protocol.js";
8
9
  export async function main(args) {
9
10
  const [command = "help", flag, root, ...extra] = args;
10
11
  if (["help", "--help", "-h"].includes(command)) {
11
- console.log("pi-sync-daemon <start|status|stop|restart|serve> --root <canonical-agent-directory>\nLocal synchronization owner; no OS service registration. status/stop never start a service.");
12
+ console.log("pi-sync-daemon <start|status|stop|restart|repair-upgrade|serve> --root <canonical-agent-directory>\nLocal synchronization owner; no OS service registration. status/stop/repair-upgrade never start a service.\nrepair-upgrade revokes all retained unattended grants after verified exit and archives the pending upgrade records.");
12
13
  return;
13
14
  }
14
- if (!["start", "status", "stop", "restart", "serve"].includes(command) || flag !== "--root" || !root || extra.length)
15
+ if (!["start", "status", "stop", "restart", "repair-upgrade", "serve"].includes(command) ||
16
+ flag !== "--root" ||
17
+ !root ||
18
+ extra.length)
15
19
  throw new Error("Use pi-sync-daemon --help for the supported commands.");
20
+ if (command === "repair-upgrade") {
21
+ const { repairUpgrade } = await import("./upgrade-repair.js");
22
+ console.log(JSON.stringify(await repairUpgrade(root)));
23
+ return;
24
+ }
16
25
  if (command === "serve") {
17
26
  process.send?.({ type: "booting" });
18
27
  const { createEngineService } = await import("./engine-service.js");
@@ -82,6 +91,43 @@ export async function main(args) {
82
91
  }
83
92
  const paths = await runtimePaths(root);
84
93
  const identity = await readIdentity(paths);
94
+ if (command === "status") {
95
+ const pending = await readUpgradeOwner(paths);
96
+ const summary = {
97
+ root: paths.root,
98
+ ...(identity && { recordedPid: identity.pid }),
99
+ ...(pending && { pendingUpgradePid: pending.pid }),
100
+ };
101
+ if (!identity ||
102
+ (pending?.instance === identity.instance && pending.pid === identity.pid && (await processExited(pending)))) {
103
+ console.log(JSON.stringify({ running: false, ...summary }));
104
+ return;
105
+ }
106
+ try {
107
+ const status = await requestDaemon(paths, identity, "hello", {});
108
+ if (!record(status) ||
109
+ status.version !== 1 ||
110
+ status.root !== paths.root ||
111
+ status.instance !== identity.instance ||
112
+ status.pid !== identity.pid)
113
+ throw new Error("Daemon identity mismatch; no replacement was attempted.");
114
+ const build = typeof status.buildVersion === "string" ? valid(status.buildVersion) : null;
115
+ console.log(JSON.stringify({
116
+ running: true,
117
+ ...summary,
118
+ version: status.version,
119
+ instance: identity.instance,
120
+ pid: identity.pid,
121
+ ...(build && { buildVersion: build }),
122
+ lifecycleLog: path.join(paths.directory, "lifecycle.log"),
123
+ }));
124
+ }
125
+ catch {
126
+ // A failed hello does not prove the recorded owner exited.
127
+ console.log(JSON.stringify({ running: null, ...summary }));
128
+ }
129
+ return;
130
+ }
85
131
  if (!identity) {
86
132
  if (command === "restart") {
87
133
  await main(["start", "--root", root]);
@@ -90,13 +136,6 @@ export async function main(args) {
90
136
  console.log(JSON.stringify({ running: false, root: paths.root }));
91
137
  return;
92
138
  }
93
- if (command === "status") {
94
- const status = await requestDaemon(paths, identity, "hello", {});
95
- if (!record(status) || status.instance !== identity.instance)
96
- throw new Error("Daemon identity mismatch; no replacement was attempted.");
97
- console.log(JSON.stringify({ running: true, ...status, lifecycleLog: path.join(paths.directory, "lifecycle.log") }));
98
- return;
99
- }
100
139
  await requestDaemon(paths, identity, "stop", {});
101
140
  const deadline = Date.now() + 30_000;
102
141
  while (await readIdentity(paths)) {
@@ -121,7 +160,9 @@ if (import.meta.main) {
121
160
  type: "error",
122
161
  message: "Daemon initialization failed; private state retained. Check endpoint ownership and compatible versions.",
123
162
  });
124
- console.error("pi-sync-daemon failed; private state retained. Check root, endpoint ownership, and version compatibility.");
163
+ console.error(process.argv[2] === "repair-upgrade"
164
+ ? "Pi Sync upgrade repair failed. Check the pending PID, wait for confirmed exit, and check consent storage. Do not delete recovery files."
165
+ : "pi-sync-daemon failed; private state retained. Check root, endpoint ownership, and version compatibility.");
125
166
  process.exitCode = 1;
126
167
  });
127
168
  }
package/dist/client.d.ts CHANGED
@@ -5,15 +5,18 @@ export declare class DaemonError extends Error {
5
5
  constructor(remote: RemoteError);
6
6
  }
7
7
  export declare function requestDaemon(paths: RuntimePaths, identity: Identity, method: string, params: unknown, signal?: AbortSignal): Promise<unknown>;
8
+ export declare function acquireStartupLock(paths: RuntimePaths, signal?: AbortSignal): Promise<() => Promise<void>>;
8
9
  /** Explicit startup only: callers decide whether configuration or a user action authorizes it. */
9
10
  export declare function ensureDaemon(root: string, signal?: AbortSignal): Promise<{
11
+ needsUpgrade: boolean;
10
12
  paths: import("./identity.js").DaemonPaths;
11
13
  identity: Identity;
12
14
  }>;
13
15
  /** Wait only for a previously authenticated owner; never kill it or infer exit from lost contact. */
14
- export declare function waitForDaemonExit(identity: Identity, signal?: AbortSignal): Promise<void>;
15
- /** Inspect an existing compatible owner without starting one. */
16
+ export declare function waitForDaemonExit({ pid }: Pick<Identity, "pid">, signal?: AbortSignal): Promise<void>;
17
+ /** Inspect an existing protocol-compatible owner without starting or replacing it. */
16
18
  export declare function findDaemon(root: string): Promise<{
19
+ needsUpgrade: boolean;
17
20
  paths: import("./identity.js").DaemonPaths;
18
21
  identity: Identity;
19
22
  } | undefined>;
package/dist/client.js CHANGED
@@ -4,7 +4,9 @@ import { request as httpRequest } from "node:http";
4
4
  import { setTimeout as delay } from "node:timers/promises";
5
5
  import { fileURLToPath } from "node:url";
6
6
  import lockfile from "proper-lockfile";
7
- import { daemonPaths, privateDirectory, processExists, readIdentity, readJsonBody, runtimePaths, } from "./identity.js";
7
+ import { lt, valid } from "semver";
8
+ import { DAEMON_BUILD_VERSION } from "./build-version.js";
9
+ import { canonicalRootGuard, clearUpgradeOwner, daemonPaths, privateDirectory, processExists, processExited, readIdentity, readJsonBody, readProcessBirth, readUpgradeOwner, recordUpgradeOwner, runtimePaths, upgradeRepairStarted, } from "./identity.js";
8
10
  import { withCleanup } from "./lifecycle.js";
9
11
  import { MAX_MESSAGE_BYTES, MAX_REVIEW_BYTES, operationPrefix, REVIEW_PAGE_CHARS, record, } from "./protocol.js";
10
12
  export class DaemonError extends Error {
@@ -62,35 +64,119 @@ async function hello(paths, identity, signal) {
62
64
  value.instance !== identity.instance ||
63
65
  value.pid !== identity.pid)
64
66
  throw new Error("Daemon handshake mismatch.");
67
+ const version = value.buildVersion;
68
+ if (Object.hasOwn(value, "buildVersion") && (typeof version !== "string" || valid(version) !== version))
69
+ throw new Error("Invalid daemon build version.");
70
+ // The old @narumitw/sync-daemon used the same wire protocol without a build version.
71
+ return { needsUpgrade: typeof version !== "string" || lt(version, DAEMON_BUILD_VERSION) };
72
+ }
73
+ async function checkUpgradeConsent(paths, assertRoot, signal) {
74
+ const { readConsent } = await import("./consent.js");
75
+ const { withStateDirectoryGuardForRoot } = await import("./engine/state/state-directory.js");
76
+ signal?.throwIfAborted();
77
+ await withStateDirectoryGuardForRoot(paths.root, () => {
78
+ signal?.throwIfAborted();
79
+ assertRoot();
80
+ // An older owner cannot report an in-memory revocation failure.
81
+ const consent = readConsent(paths.root);
82
+ if (consent && Object.values(consent.setups).some((setup) => setup.afterExit))
83
+ throw new Error("Review or revoke unattended Pi Sync permission before restarting the older daemon.");
84
+ });
85
+ signal?.throwIfAborted();
86
+ assertRoot();
87
+ }
88
+ async function finishUpgrade(paths, owner, assertRoot, signal) {
89
+ await waitForProcessExit(owner, signal);
90
+ if ((await readIdentity(paths))?.instance === owner.instance)
91
+ throw new Error("The daemon exited without releasing its identity.");
92
+ await checkUpgradeConsent(paths, assertRoot, signal);
93
+ await clearUpgradeOwner(paths);
94
+ signal?.throwIfAborted();
95
+ assertRoot();
96
+ }
97
+ async function drainForUpgrade(paths, owner, { recorded, birth }, assertRoot, signal) {
98
+ await checkUpgradeConsent(paths, assertRoot, signal);
99
+ const barrier = recorded ?? { ...owner, birth };
100
+ try {
101
+ // Publish this before stop can remove the identity. A retry keeps the original evidence.
102
+ if (!recorded)
103
+ await recordUpgradeOwner(paths, barrier);
104
+ assertRoot();
105
+ const reply = await requestDaemon(paths, owner, "stop", {}, signal);
106
+ if (!record(reply) || reply.stopping !== true)
107
+ throw new Error("Daemon did not acknowledge stop.");
108
+ }
109
+ catch (error) {
110
+ signal?.throwIfAborted();
111
+ throw new Error("Pi Sync could not upgrade the older daemon safely. Check `pi-sync-daemon status --root <agent-directory>`. Do not force a second owner or remove recovery files.", { cause: error });
112
+ }
113
+ await finishUpgrade(paths, barrier, assertRoot, signal);
114
+ }
115
+ export async function acquireStartupLock(paths, signal) {
116
+ // Include the handshake, stop, exit wait, boot, and final handshake budgets.
117
+ const deadline = performance.now() + 150_000;
118
+ for (;;) {
119
+ signal?.throwIfAborted();
120
+ try {
121
+ return await lockfile.lock(paths.directory, {
122
+ realpath: false,
123
+ lockfilePath: paths.startup,
124
+ stale: 30_000,
125
+ update: 5_000,
126
+ });
127
+ }
128
+ catch (error) {
129
+ signal?.throwIfAborted();
130
+ if (error.code !== "ELOCKED")
131
+ throw error;
132
+ if (performance.now() >= deadline)
133
+ throw new Error("Timed out waiting to start the Pi Sync daemon.", { cause: error });
134
+ await delay(50, undefined, { signal });
135
+ }
136
+ }
65
137
  }
66
138
  /** Explicit startup only: callers decide whether configuration or a user action authorizes it. */
67
139
  export async function ensureDaemon(root, signal) {
68
140
  const paths = await runtimePaths(root);
141
+ const assertRoot = canonicalRootGuard(paths.root);
69
142
  signal?.throwIfAborted();
70
143
  await privateDirectory(paths.directory);
71
144
  signal?.throwIfAborted();
72
- const release = await lockfile.lock(paths.directory, {
73
- realpath: false,
74
- lockfilePath: paths.startup,
75
- stale: 30_000,
76
- update: 5_000,
77
- retries: { retries: 100, factor: 1, minTimeout: 50, maxTimeout: 50 },
78
- });
145
+ const release = await acquireStartupLock(paths, signal);
79
146
  try {
80
147
  signal?.throwIfAborted();
81
148
  let waited = false;
149
+ let upgraded = false;
82
150
  for (;;) {
151
+ signal?.throwIfAborted();
152
+ const upgrade = await readUpgradeOwner(paths);
153
+ if (upgrade && (await upgradeRepairStarted(paths, upgrade)))
154
+ throw new Error("A daemon upgrade repair is incomplete. Run `pi-sync-daemon repair-upgrade` for this root.");
83
155
  const existing = await readIdentity(paths);
156
+ if (upgrade && existing?.instance === upgrade.instance && existing.pid !== upgrade.pid)
157
+ throw new Error("The recorded upgrade owner changed; private state was retained.");
158
+ if (upgrade && (existing?.instance !== upgrade.instance || (await processExited(upgrade)))) {
159
+ await finishUpgrade(paths, upgrade, assertRoot, signal);
160
+ upgraded = true;
161
+ continue;
162
+ }
84
163
  if (!existing)
85
164
  break;
165
+ // A sample taken only after hello could describe an unrelated process reusing the PID.
166
+ const beforeHello = upgrade ? undefined : await readProcessBirth(existing.pid);
167
+ let status;
86
168
  try {
87
- await hello(paths, existing, signal);
88
- signal?.throwIfAborted();
89
- return { paths: daemonPaths(paths, existing.instance), identity: existing };
169
+ status = await hello(paths, existing, signal);
90
170
  }
91
171
  catch (error) {
92
172
  if (signal?.aborted)
93
173
  throw signal.reason;
174
+ if (upgrade) {
175
+ // The stop may have been accepted even if the old endpoint no longer replies.
176
+ await finishUpgrade(paths, upgrade, assertRoot, signal);
177
+ upgraded = true;
178
+ continue;
179
+ }
94
180
  if (error instanceof DaemonError && error.remote.name === "DaemonStoppingError" && !waited) {
95
181
  waited = true;
96
182
  await waitForDaemonExit(existing, signal);
@@ -100,7 +186,23 @@ export async function ensureDaemon(root, signal) {
100
186
  throw new Error("A daemon owner is alive but unavailable; use diagnostics instead of starting a second owner.", { cause: error });
101
187
  break;
102
188
  }
189
+ signal?.throwIfAborted();
190
+ assertRoot();
191
+ if (!status.needsUpgrade) {
192
+ if (upgrade)
193
+ throw new Error("The recorded upgrade owner changed; private state was retained.");
194
+ return { paths: daemonPaths(paths, existing.instance), identity: existing, ...status };
195
+ }
196
+ if (upgraded)
197
+ throw new Error("An older Pi Sync daemon started again. Close or upgrade other Pi sessions, then use /reload.");
198
+ const birth = beforeHello === undefined ? undefined : await readProcessBirth(existing.pid);
199
+ if (birth !== undefined && birth !== beforeHello)
200
+ throw new Error("The daemon process changed during authentication; private state was retained.");
201
+ await drainForUpgrade(paths, existing, { recorded: upgrade, birth }, assertRoot, signal);
202
+ upgraded = true;
103
203
  }
204
+ signal?.throwIfAborted();
205
+ assertRoot();
104
206
  const executable = process.versions.bun ? "node" : process.execPath;
105
207
  const child = spawn(executable, [fileURLToPath(new URL("./cli.js", import.meta.url)), "serve", "--root", paths.root], {
106
208
  detached: true,
@@ -152,26 +254,33 @@ export async function ensureDaemon(root, signal) {
152
254
  child.unref();
153
255
  });
154
256
  // Never kill a published shared daemon on caller cancellation.
155
- await hello(paths, ready, signal);
257
+ const status = await hello(paths, ready, signal);
156
258
  signal?.throwIfAborted();
157
- return { paths: daemonPaths(paths, ready.instance), identity: ready };
259
+ assertRoot();
260
+ if (status.needsUpgrade)
261
+ throw new Error("The daemon installation changed during startup. Use /reload to retry.");
262
+ return { paths: daemonPaths(paths, ready.instance), identity: ready, ...status };
158
263
  }
159
264
  finally {
160
265
  await release();
161
266
  }
162
267
  }
163
268
  /** Wait only for a previously authenticated owner; never kill it or infer exit from lost contact. */
164
- export async function waitForDaemonExit(identity, signal) {
269
+ export async function waitForDaemonExit({ pid }, signal) {
270
+ await waitForProcessExit({ pid }, signal);
271
+ }
272
+ async function waitForProcessExit(owner, signal) {
165
273
  const deadline = Date.now() + 30_000;
166
274
  signal?.throwIfAborted();
167
- while (processExists(identity.pid)) {
275
+ while (!(await processExited(owner))) {
276
+ signal?.throwIfAborted();
168
277
  if (Date.now() >= deadline)
169
278
  throw new Error("Closing daemon is still alive; replacement was not attempted.");
170
279
  await delay(25, undefined, { signal });
171
280
  }
172
281
  signal?.throwIfAborted();
173
282
  }
174
- /** Inspect an existing compatible owner without starting one. */
283
+ /** Inspect an existing protocol-compatible owner without starting or replacing it. */
175
284
  export async function findDaemon(root) {
176
285
  let paths;
177
286
  try {
@@ -186,14 +295,14 @@ export async function findDaemon(root) {
186
295
  if (!identity || !processExists(identity.pid))
187
296
  return undefined;
188
297
  try {
189
- await hello(paths, identity);
298
+ const status = await hello(paths, identity);
299
+ return { paths: daemonPaths(paths, identity.instance), identity, ...status };
190
300
  }
191
301
  catch (error) {
192
302
  if (error instanceof DaemonError && error.remote.name === "DaemonStoppingError")
193
303
  return undefined;
194
304
  throw error;
195
305
  }
196
- return { paths: daemonPaths(paths, identity.instance), identity };
197
306
  }
198
307
  /** Gracefully stop an existing compatible owner without creating a new service. */
199
308
  export async function stopDaemon(root) {
package/dist/consent.d.ts CHANGED
@@ -17,6 +17,8 @@ export declare class ConsentPublicationError extends Error {
17
17
  }
18
18
  /** A different interactive binding cannot silently resume an older unattended grant after exit/restart. */
19
19
  export declare function revokeChangedBindings(root: string, peers: readonly ClientFacts[]): void;
20
+ /** Explicit offline repair only. The caller must exclude daemon owners and state migration. */
21
+ export declare function revokeRetainedGrants(root: string): number;
20
22
  export declare function readConsent(root: string): Consent | undefined;
21
23
  export declare function consentFingerprint(root: string, config: AnySyncConfig): string;
22
24
  export declare function requireHandover(execution: Execution): Promise<void>;
package/dist/consent.js CHANGED
@@ -4,18 +4,40 @@ import path from "node:path";
4
4
  import { syncCheckConfigFingerprint } from "./engine/settings/config.js";
5
5
  import { stateDir } from "./engine/state/state-directory.js";
6
6
  import { record } from "./protocol.js";
7
- function file() {
8
- return path.join(stateDir(), "daemon.json");
7
+ function file(root) {
8
+ return path.join(stateDir(root), "daemon.json");
9
9
  }
10
10
  export class ConsentPublicationError extends Error {
11
11
  }
12
+ const FORMATTED_CONSENT_BYTES = 65_536;
13
+ // Each legacy grant already uses at least 64 bytes for its fingerprint. Reserving one byte per
14
+ // grant covers all legacy writes, including compact files, when `true` becomes `false`.
15
+ const MAX_CONSENT_BYTES = FORMATTED_CONSENT_BYTES + FORMATTED_CONSENT_BYTES / 64;
16
+ function compactConsentWithRevocationReserve(value) {
17
+ const compact = JSON.stringify(value);
18
+ const grantCount = Object.values(value.setups).filter((setup) => setup.afterExit).length;
19
+ if (Buffer.byteLength(compact) + grantCount > MAX_CONSENT_BYTES)
20
+ throw new Error("Daemon consent exceeds its storage bound; existing evidence retained.");
21
+ return compact;
22
+ }
23
+ function syncConsentDirectory(target) {
24
+ if (process.platform === "win32")
25
+ return;
26
+ const directory = openSync(path.dirname(target), "r");
27
+ try {
28
+ fsyncSync(directory);
29
+ }
30
+ finally {
31
+ closeSync(directory);
32
+ }
33
+ }
12
34
  /** A small synchronous publication keeps approval, metadata revocation, and rename in one event-loop turn. */
13
35
  function publishConsent(value) {
14
36
  try {
15
- const target = file();
16
- const content = `${JSON.stringify(value, null, "\t")}\n`;
17
- if (Buffer.byteLength(content) > 65_536)
18
- throw new Error("Daemon consent exceeds its storage bound; existing evidence retained.");
37
+ const target = file(value.root);
38
+ const compact = compactConsentWithRevocationReserve(value);
39
+ const formatted = `${JSON.stringify(value, null, "\t")}\n`;
40
+ const content = Buffer.byteLength(formatted) <= FORMATTED_CONSENT_BYTES ? formatted : compact;
19
41
  mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
20
42
  const temporary = `${target}.${process.pid}.${randomBytes(16).toString("hex")}.tmp`;
21
43
  const handle = openSync(temporary, "wx", 0o600);
@@ -28,15 +50,7 @@ function publishConsent(value) {
28
50
  closeSync(handle);
29
51
  }
30
52
  renameSync(temporary, target);
31
- if (process.platform !== "win32") {
32
- const directory = openSync(path.dirname(target), "r");
33
- try {
34
- fsyncSync(directory);
35
- }
36
- finally {
37
- closeSync(directory);
38
- }
39
- }
53
+ syncConsentDirectory(target);
40
54
  }
41
55
  finally {
42
56
  rmSync(temporary, { force: true });
@@ -67,14 +81,33 @@ export function revokeChangedBindings(root, peers) {
67
81
  if (changed)
68
82
  publishConsent(consent);
69
83
  }
84
+ /** Explicit offline repair only. The caller must exclude daemon owners and state migration. */
85
+ export function revokeRetainedGrants(root) {
86
+ const consent = readConsent(root);
87
+ if (!consent)
88
+ return 0;
89
+ let revoked = 0;
90
+ for (const saved of Object.values(consent.setups)) {
91
+ if (!saved.afterExit)
92
+ continue;
93
+ saved.afterExit = false;
94
+ revoked += 1;
95
+ }
96
+ if (revoked)
97
+ publishConsent(consent);
98
+ // A prior attempt may have renamed the synced file but failed to sync the directory.
99
+ else
100
+ syncConsentDirectory(file(root));
101
+ return revoked;
102
+ }
70
103
  export function readConsent(root) {
71
- const target = file();
104
+ const target = file(root);
72
105
  let handle;
73
106
  try {
74
107
  const before = lstatSync(target);
75
108
  if (!before.isFile() ||
76
109
  before.isSymbolicLink() ||
77
- before.size > 65_536 ||
110
+ before.size > MAX_CONSENT_BYTES ||
78
111
  (process.getuid && before.uid !== process.getuid()) ||
79
112
  (process.platform !== "win32" && before.mode & 0o077))
80
113
  throw new Error("Unsafe daemon consent document; evidence retained.");
@@ -109,7 +142,9 @@ export function readConsent(root) {
109
142
  !["stored", "environment", "models_json_key", "models_json_command"].includes(String(entry.model.authSource)))))
110
143
  throw new Error("Invalid daemon setup consent.");
111
144
  }
112
- return value;
145
+ const consent = value;
146
+ compactConsentWithRevocationReserve(consent);
147
+ return consent;
113
148
  }
114
149
  catch (error) {
115
150
  if (error.code === "ENOENT")
@@ -7,8 +7,10 @@ export type StateDirectoryPreparation = {
7
7
  status: "deferred";
8
8
  message: string;
9
9
  };
10
- export declare function stateDir(): string;
11
- export declare function legacyStateDir(): string;
10
+ export declare function stateDir(root?: string): string;
11
+ export declare function legacyStateDir(root?: string): string;
12
12
  export declare function stateDirectoryMigrationNotice(): "Legacy pi-sync state is still stored in .pisync. Close other Pi sessions, then run /sync migrate-state to move it to pi-sync/." | undefined;
13
13
  export declare function withStateDirectoryAccess<T>(fn: () => Promise<T>): Promise<T>;
14
14
  export declare function migrateLegacyStateDirectory(): Promise<StateDirectoryPreparation>;
15
+ /** Protect path selection and a synchronous access outside the engine host. */
16
+ export declare function withStateDirectoryGuardForRoot<T>(root: string, access: () => T): Promise<T>;
@@ -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/server.js CHANGED
@@ -4,8 +4,9 @@ import fs from "node:fs/promises";
4
4
  import { createServer } from "node:http";
5
5
  import path from "node:path";
6
6
  import lockfile from "proper-lockfile";
7
+ import { DAEMON_BUILD_VERSION } from "./build-version.js";
7
8
  import { endpointOwner } from "./endpoint.js";
8
- 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";
9
10
  import { createIdleExit } from "./idle-exit.js";
10
11
  import { withCleanup } from "./lifecycle.js";
11
12
  import { ParticipantAdmission } from "./participant-admission.js";
@@ -502,7 +503,13 @@ export async function startServer(root, execute, hooks = {}) {
502
503
  if (!cleanup)
503
504
  assertOwner();
504
505
  if (method === "hello")
505
- 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
+ };
506
513
  if (method === "attach") {
507
514
  const attached = await admission.run(async () => {
508
515
  assertOwner();
@@ -753,6 +760,9 @@ export async function startServer(root, execute, hooks = {}) {
753
760
  const endpoint = endpointOwner(server, paths);
754
761
  try {
755
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();
756
766
  await endpoint.listen();
757
767
  assertOwner();
758
768
  await publishIdentity(paths, identity);
@@ -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
+ }>;
@@ -0,0 +1,55 @@
1
+ import fs from "node:fs/promises";
2
+ import path from "node:path";
3
+ import lockfile from "proper-lockfile";
4
+ import { acquireStartupLock } from "./client.js";
5
+ import { revokeRetainedGrants } from "./consent.js";
6
+ import { withStateDirectoryGuardForRoot } from "./engine/state/state-directory.js";
7
+ import { canonicalRootGuard, privateDirectory, processExited, readIdentity, readUpgradeOwner, runtimePaths, upgradeArchivePath, upgradeFile, } from "./identity.js";
8
+ /** Explicit repair never launches or sends requests to a daemon. */
9
+ export async function repairUpgrade(root) {
10
+ const paths = await runtimePaths(root);
11
+ const assertRoot = canonicalRootGuard(paths.root);
12
+ await privateDirectory(paths.directory);
13
+ const releaseStartup = await acquireStartupLock(paths);
14
+ try {
15
+ const pending = await readUpgradeOwner(paths);
16
+ if (!pending)
17
+ return { repaired: false };
18
+ // Exclude direct `serve`. Use a distinct lock key so proper-lockfile can track both locks.
19
+ const releaseOwner = await lockfile.lock(paths.owner, {
20
+ realpath: false,
21
+ lockfilePath: paths.owner,
22
+ stale: 30_000,
23
+ update: 5_000,
24
+ });
25
+ try {
26
+ const identity = await readIdentity(paths);
27
+ if (identity && (identity.instance !== pending.instance || identity.pid !== pending.pid))
28
+ throw new Error("The recorded upgrade owner changed; private state was retained.");
29
+ if (!(await processExited(pending)))
30
+ throw new Error("Cannot verify that the old Pi Sync daemon has exited; private state was retained.");
31
+ assertRoot();
32
+ // The archive also marks a repair in progress before consent or recovery records change.
33
+ const archive = upgradeArchivePath(paths, pending);
34
+ await privateDirectory(archive);
35
+ const revokedGrants = await withStateDirectoryGuardForRoot(paths.root, () => {
36
+ assertRoot();
37
+ return revokeRetainedGrants(paths.root);
38
+ });
39
+ assertRoot();
40
+ // Keep the original bytes private. Move the barrier last so interrupted repair can be retried.
41
+ if (identity)
42
+ await fs.rename(paths.identity, path.join(archive, path.basename(paths.identity)));
43
+ assertRoot();
44
+ const barrier = upgradeFile(paths);
45
+ await fs.rename(barrier, path.join(archive, path.basename(barrier)));
46
+ return { repaired: true, revokedGrants, archive };
47
+ }
48
+ finally {
49
+ await releaseOwner();
50
+ }
51
+ }
52
+ finally {
53
+ await releaseStartup();
54
+ }
55
+ }
@@ -103,7 +103,7 @@ When no registered live PID remains and no valid explicit after-exit grant cover
103
103
 
104
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
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.
106
+ After quiescence, the authenticated final fence returns `RemoteError.name = "DaemonStoppingError"` to rejected admissions and handshakes on the existing version-1 protocol. `ensureDaemon()` recognizes this idle-stop 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
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
109
 
@@ -139,6 +139,30 @@ node node_modules/.cache/pi-extensions-test/packages/pi-sync/test/idle-exit-cli-
139
139
 
140
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
141
 
142
+ ## Package upgrades
143
+
144
+ The authenticated `hello` response reports the running package build separately from its protocol
145
+ version. Older releases did not report a build. During active startup, the client holds the existing
146
+ startup lock, sends an authenticated `stop` to an older or unversioned owner, and waits for owner exit
147
+ and identity release. A private exit record survives cancellation and timeout. It keeps the PID
148
+ and, when available, a verified Linux process birth marker. For a marked owner, `ESRCH` confirms
149
+ absence only in the recorded PID namespace. A PID-only record still requires `ESRCH`. Later callers
150
+ use the record even if the old identity file is gone. Concurrent startup can wait for the drain
151
+ under a bounded, cancellable lock wait. The client checks the root again before launching a replacement.
152
+ It does not stop a newer build or start a replacement for an unreachable live owner. A retained unattended grant blocks
153
+ implicit replacement because a legacy owner cannot report a failed revocation. The client reads
154
+ consent under the state migration guard and releases it before sending stop. Passive attachment can
155
+ protect live sessions without starting a replacement or submitting sync operations on the old build.
156
+ An interactive session switch attempts the same protection-only attachment if the upgrade fails.
157
+
158
+ For a blocked pending upgrade, `repair-upgrade` checks exit under the startup and owner locks.
159
+ It revokes retained unattended grants under the state migration guard on all platforms. On
160
+ non-Windows platforms, it also syncs the consent directory before archiving the upgrade barrier.
161
+ Consent storage reserves one byte per retained grant so that revocation fits even for compact JSON
162
+ at the old size limit. Repair reuses the same private archive if interrupted. Normal startup
163
+ cannot clear an incomplete repair. The command does not start the daemon. Clean shutdowns still
164
+ clear the barrier without manual repair.
165
+
142
166
  ## Cross-process apply protocol
143
167
 
144
168
  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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@narumitw/pi-sync-daemon",
3
- "version": "0.4.0",
3
+ "version": "0.5.0",
4
4
  "description": "A local synchronization daemon with a versioned client API.",
5
5
  "type": "module",
6
6
  "license": "MIT",