@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.
- package/CHANGELOG.md +16 -0
- package/README.md +10 -4
- package/dist/build-version.d.ts +1 -0
- package/dist/build-version.js +8 -0
- package/dist/cli.js +52 -11
- package/dist/client.d.ts +26 -3
- package/dist/client.js +302 -39
- package/dist/consent.d.ts +2 -0
- package/dist/consent.js +53 -18
- package/dist/engine/state/state-directory.d.ts +4 -2
- package/dist/engine/state/state-directory.js +22 -20
- package/dist/identity.d.ts +20 -0
- package/dist/identity.js +126 -18
- package/dist/index.d.ts +1 -1
- package/dist/protocol.d.ts +14 -0
- package/dist/protocol.js +7 -0
- package/dist/server.js +158 -13
- package/dist/upgrade-repair.d.ts +10 -0
- package/dist/upgrade-repair.js +55 -0
- package/docs/architecture.md +47 -3
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,21 @@
|
|
|
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
|
+
|
|
9
|
+
## 0.4.0
|
|
10
|
+
|
|
11
|
+
### Minor Changes
|
|
12
|
+
|
|
13
|
+
- 223b0ba: Restore a live Pi session after its heartbeat expires without reloading Pi. The
|
|
14
|
+
daemon distinguishes heartbeat expiry from deliberate disconnection and keeps
|
|
15
|
+
file-queue and session protection in place. Pi Sync reconnects to the same owner
|
|
16
|
+
without resubmitting interrupted operations, and checks participation before
|
|
17
|
+
reporting that it is connected.
|
|
18
|
+
|
|
3
19
|
## 0.3.0
|
|
4
20
|
|
|
5
21
|
### 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`
|
|
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 `
|
|
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
|
|
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
|
|
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) ||
|
|
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(
|
|
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
|
@@ -1,19 +1,22 @@
|
|
|
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);
|
|
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(
|
|
15
|
-
/** Inspect an existing compatible owner without starting
|
|
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>;
|
|
@@ -23,6 +26,8 @@ export interface ConnectionOptions {
|
|
|
23
26
|
callback(callback: Callback, signal: AbortSignal): Promise<unknown>;
|
|
24
27
|
event?(event: ClientEvent): void;
|
|
25
28
|
error?(error: unknown): void;
|
|
29
|
+
/** Each current background observation after admission, including repeated states. */
|
|
30
|
+
contact?(state: ContactState): void;
|
|
26
31
|
}
|
|
27
32
|
export declare class DaemonConnection {
|
|
28
33
|
readonly paths: RuntimePaths;
|
|
@@ -36,17 +41,35 @@ export declare class DaemonConnection {
|
|
|
36
41
|
private callbackTasks;
|
|
37
42
|
private updates;
|
|
38
43
|
private attached;
|
|
44
|
+
private admitting;
|
|
45
|
+
private observedContact;
|
|
46
|
+
private contactRevision;
|
|
47
|
+
private lifecycleRevision;
|
|
48
|
+
private resuming;
|
|
49
|
+
private resumeUncertain;
|
|
50
|
+
private pendingJobs;
|
|
39
51
|
private uncertain;
|
|
40
52
|
private reportedError;
|
|
41
53
|
private commits;
|
|
42
54
|
private completedCallbacks;
|
|
55
|
+
private pausing;
|
|
43
56
|
private disposing;
|
|
44
57
|
private polling;
|
|
45
58
|
private closed;
|
|
46
59
|
constructor(paths: RuntimePaths, identity: Identity, facts: ClientFacts, options: ConnectionOptions);
|
|
60
|
+
/** Latest owner observation, or undefined if contact is unsupported or not observed. */
|
|
61
|
+
get contactState(): ContactState | undefined;
|
|
62
|
+
/** An uncertain attempt must not be retried or turned into a new attach. */
|
|
63
|
+
get contactResumeState(): "idle" | "running" | "uncertain";
|
|
64
|
+
/** Original submitted jobs must finish (or be reconciled) before repairing contact. */
|
|
65
|
+
get hasPendingWork(): boolean;
|
|
47
66
|
attach(signal?: AbortSignal): Promise<this>;
|
|
48
67
|
update(facts: ClientFacts): Promise<void>;
|
|
68
|
+
/** Resume this participant without replacing its callbacks, jobs, or polling. */
|
|
69
|
+
resumeContact(facts: ClientFacts, signal?: AbortSignal): Promise<void>;
|
|
70
|
+
private sameClient;
|
|
49
71
|
run(operation: string, payload: unknown, signal?: AbortSignal, onCommit?: () => void): Promise<unknown>;
|
|
72
|
+
private publishContact;
|
|
50
73
|
private consume;
|
|
51
74
|
private performCallback;
|
|
52
75
|
private wait;
|