@hansjm10/volt-coding-agent 0.0.0-bootstrap.0 → 0.1.0

package/dist/daemon/spawn.d.ts

@@ -0,0 +1,53 @@
+import { type PidfileContents } from "./main.ts";
+import { type InvalidVoltdStateFile } from "./state.ts";
+export declare const DAEMON_SHUTDOWN_TIMEOUT_MS = 75000;
+export type DaemonProbeState = "healthy" | "shutting-down" | "protocol-mismatch" | "auth-failed" | "unresponsive" | "not-running";
+export interface DaemonProbeResult {
+    healthy: boolean;
+    state: DaemonProbeState;
+    pid?: number;
+    version?: string;
+    protocolVersion?: number;
+    startedAtMs?: number;
+    socketPath: string;
+    authToken?: string;
+}
+/**
+ * Probe the pidfile-published daemon endpoint first, then fall back to the
+ * legacy default socket path for older daemons and pre-start diagnostics.
+ */
+export declare function probeDaemon(agentDir?: string): Promise<DaemonProbeResult>;
+export declare function resolveDaemonCliInvocation(): {
+    nodeArgs: string[];
+    entry: string;
+};
+export interface SpawnDaemonResult {
+    ok: boolean;
+    pid?: number;
+    socketPath: string;
+    error?: string;
+}
+export interface PublishedDaemonEndpoint {
+    socketPath: string;
+    authToken?: string;
+}
+/** Read the latest complete pidfile endpoint without probing or auto-starting. */
+export declare function readPublishedDaemonEndpoint(agentDir?: string): PublishedDaemonEndpoint | undefined;
+export interface WaitForDaemonExitOptions {
+    agentDir?: string;
+    pid?: number;
+    pidfile?: PidfileContents;
+    socketPath?: string;
+    timeoutMs?: number;
+}
+export declare function waitForDaemonExit(options?: WaitForDaemonExitOptions): Promise<"exited" | "timeout">;
+/** Spawn a detached daemon and wait (up to 5s) for the socket to answer a status probe. */
+export declare function spawnDetachedDaemon(agentDir?: string): Promise<SpawnDaemonResult>;
+export interface EnsureDaemonResult extends DaemonProbeResult {
+    spawned: boolean;
+    error?: string;
+    invalidState?: InvalidVoltdStateFile;
+}
+/** Probe the socket; if no healthy daemon answers, spawn one detached. */
+export declare function ensureDaemonRunning(agentDir?: string): Promise<EnsureDaemonResult>;
+//# sourceMappingURL=spawn.d.ts.map

package/dist/daemon/spawn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn.d.ts","sourceRoot":"","sources":["../../src/daemon/spawn.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,eAAe,EAAe,MAAM,WAAW,CAAC;AAG9D,OAAO,EAAE,KAAK,qBAAqB,EAA0B,MAAM,YAAY,CAAC;AAIhF,eAAO,MAAM,0BAA0B,QAAS,CAAC;AAGjD,MAAM,MAAM,gBAAgB,GACzB,SAAS,GACT,eAAe,GACf,mBAAmB,GACnB,aAAa,GACb,cAAc,GACd,aAAa,CAAC;AAEjB,MAAM,WAAW,iBAAiB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,gBAAgB,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AA2CD;;;GAGG;AACH,wBAAsB,WAAW,CAAC,QAAQ,GAAE,MAAsB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAmB9F;AAED,wBAAgB,0BAA0B,IAAI;IAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAOlF;AAED,MAAM,WAAW,iBAAiB;IACjC,EAAE,EAAE,OAAO,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,uBAAuB;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,kFAAkF;AAClF,wBAAgB,2BAA2B,CAAC,QAAQ,GAAE,MAAsB,GAAG,uBAAuB,GAAG,SAAS,CASjH;AAED,MAAM,WAAW,wBAAwB;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAcD,wBAAsB,iBAAiB,CAAC,OAAO,GAAE,wBAA6B,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAkB7G;AAED,2FAA2F;AAC3F,wBAAsB,mBAAmB,CAAC,QAAQ,GAAE,MAAsB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAkCtG;AAED,MAAM,WAAW,kBAAmB,SAAQ,iBAAiB;IAC5D,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,qBAAqB,CAAC;CACrC;AAED,0EAA0E;AAC1E,wBAAsB,mBAAmB,CAAC,QAAQ,GAAE,MAAsB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA6CvG","sourcesContent":["import { spawn } from \"node:child_process\";\nimport { closeSync, existsSync, openSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { ENV_AGENT_DIR, getAgentDir, getPackageDir, VERSION } from \"../config.ts\";\nimport { type ControlSocketProbe, probeControlSocket } from \"./control-server.ts\";\nimport { type PidfileContents, readPidfile } from \"./main.ts\";\nimport { type DaemonPaths, ensureDaemonDirs, getDaemonPaths } from \"./paths.ts\";\nimport { verifyPidfileProcess } from \"./process-identity.ts\";\nimport { type InvalidVoltdStateFile, inspectVoltdStateFiles } from \"./state.ts\";\n\nconst SPAWN_HEALTH_TIMEOUT_MS = 5000;\nconst SPAWN_HEALTH_POLL_MS = 100;\nexport const DAEMON_SHUTDOWN_TIMEOUT_MS = 75_000;\nconst DAEMON_EXIT_POLL_MS = 200;\n\nexport type DaemonProbeState =\n\t| \"healthy\"\n\t| \"shutting-down\"\n\t| \"protocol-mismatch\"\n\t| \"auth-failed\"\n\t| \"unresponsive\"\n\t| \"not-running\";\n\nexport interface DaemonProbeResult {\n\thealthy: boolean;\n\tstate: DaemonProbeState;\n\tpid?: number;\n\tversion?: string;\n\tprotocolVersion?: number;\n\tstartedAtMs?: number;\n\tsocketPath: string;\n\tauthToken?: string;\n}\n\nfunction daemonProbeFromSocketProbe(\n\tsocketPath: string,\n\tprobe: ControlSocketProbe,\n\tauthToken: string | undefined,\n): DaemonProbeResult {\n\tif (probe.kind === \"healthy\") {\n\t\treturn {\n\t\t\thealthy: true,\n\t\t\tstate: \"healthy\",\n\t\t\tpid: probe.status.pid,\n\t\t\tversion: probe.status.version,\n\t\t\tprotocolVersion: probe.status.protocolVersion,\n\t\t\tstartedAtMs: probe.status.startedAtMs,\n\t\t\tsocketPath,\n\t\t\t...(authToken === undefined ? {} : { authToken }),\n\t\t};\n\t}\n\tif (probe.kind === \"live-rejected\") {\n\t\tconst state: DaemonProbeState =\n\t\t\tprobe.reason === \"protocol_mismatch\"\n\t\t\t\t? \"protocol-mismatch\"\n\t\t\t\t: probe.reason === \"auth_failed\"\n\t\t\t\t\t? \"auth-failed\"\n\t\t\t\t\t: probe.reason === \"shutting_down\"\n\t\t\t\t\t\t? \"shutting-down\"\n\t\t\t\t\t\t: \"unresponsive\";\n\t\treturn {\n\t\t\thealthy: false,\n\t\t\tstate,\n\t\t\t...(probe.version === undefined ? {} : { version: probe.version }),\n\t\t\t...(probe.protocolVersion === undefined ? {} : { protocolVersion: probe.protocolVersion }),\n\t\t\tsocketPath,\n\t\t\t...(authToken === undefined ? {} : { authToken }),\n\t\t};\n\t}\n\tif (probe.kind === \"unresponsive\") {\n\t\treturn { healthy: false, state: \"unresponsive\", socketPath, ...(authToken === undefined ? {} : { authToken }) };\n\t}\n\treturn { healthy: false, state: \"not-running\", socketPath, ...(authToken === undefined ? {} : { authToken }) };\n}\n\n/**\n * Probe the pidfile-published daemon endpoint first, then fall back to the\n * legacy default socket path for older daemons and pre-start diagnostics.\n */\nexport async function probeDaemon(agentDir: string = getAgentDir()): Promise<DaemonProbeResult> {\n\tconst paths = getDaemonPaths(agentDir);\n\tconst pidfile = readPidfile(paths.pidfilePath);\n\tif (pidfile) {\n\t\tconst pidfileProbe = await probeControlSocket(pidfile.socketPath, {\n\t\t\tversion: VERSION,\n\t\t\t...(pidfile.token === undefined ? {} : { authToken: pidfile.token }),\n\t\t});\n\t\tconst pidfileResult = daemonProbeFromSocketProbe(pidfile.socketPath, pidfileProbe, pidfile.token);\n\t\tif (pidfileResult.state !== \"not-running\") {\n\t\t\treturn pidfileResult;\n\t\t}\n\t}\n\tconst probe = await probeControlSocket(paths.socketPath, { version: VERSION });\n\tconst result = daemonProbeFromSocketProbe(paths.socketPath, probe, undefined);\n\tif (result.state !== \"not-running\") {\n\t\treturn result;\n\t}\n\treturn { healthy: false, state: \"not-running\", socketPath: paths.socketPath };\n}\n\nexport function resolveDaemonCliInvocation(): { nodeArgs: string[]; entry: string } {\n\tconst packageDir = getPackageDir();\n\tconst sourceEntry = join(packageDir, \"src\", \"cli.ts\");\n\tif (existsSync(sourceEntry)) {\n\t\treturn { nodeArgs: [\"--conditions\", \"volt-source\"], entry: sourceEntry };\n\t}\n\treturn { nodeArgs: [], entry: join(packageDir, \"dist\", \"cli.js\") };\n}\n\nexport interface SpawnDaemonResult {\n\tok: boolean;\n\tpid?: number;\n\tsocketPath: string;\n\terror?: string;\n}\n\nexport interface PublishedDaemonEndpoint {\n\tsocketPath: string;\n\tauthToken?: string;\n}\n\n/** Read the latest complete pidfile endpoint without probing or auto-starting. */\nexport function readPublishedDaemonEndpoint(agentDir: string = getAgentDir()): PublishedDaemonEndpoint | undefined {\n\tconst pidfile = readPidfile(getDaemonPaths(agentDir).pidfilePath);\n\tif (!pidfile) {\n\t\treturn undefined;\n\t}\n\treturn {\n\t\tsocketPath: pidfile.socketPath,\n\t\t...(pidfile.token === undefined ? {} : { authToken: pidfile.token }),\n\t};\n}\n\nexport interface WaitForDaemonExitOptions {\n\tagentDir?: string;\n\tpid?: number;\n\tpidfile?: PidfileContents;\n\tsocketPath?: string;\n\ttimeoutMs?: number;\n}\n\nfunction processIsGone(pid: number | undefined): boolean {\n\tif (!pid || pid === process.pid) {\n\t\treturn true;\n\t}\n\ttry {\n\t\tprocess.kill(pid, 0);\n\t\treturn false;\n\t} catch (error) {\n\t\treturn !(error instanceof Error && \"code\" in error && (error as NodeJS.ErrnoException).code === \"EPERM\");\n\t}\n}\n\nexport async function waitForDaemonExit(options: WaitForDaemonExitOptions = {}): Promise<\"exited\" | \"timeout\"> {\n\tconst agentDir = options.agentDir ?? getAgentDir();\n\tconst paths = getDaemonPaths(agentDir);\n\tconst deadline = Date.now() + (options.timeoutMs ?? DAEMON_SHUTDOWN_TIMEOUT_MS);\n\tconst targetPid = options.pid ?? options.pidfile?.pid;\n\tconst socketPath = options.socketPath ?? options.pidfile?.socketPath ?? paths.socketPath;\n\twhile (Date.now() < deadline) {\n\t\tconst socketProbe = await probeControlSocket(socketPath, {\n\t\t\tversion: VERSION,\n\t\t\ttimeoutMs: 500,\n\t\t\t...(options.pidfile?.token === undefined ? {} : { authToken: options.pidfile.token }),\n\t\t});\n\t\tif (processIsGone(targetPid) && socketProbe.kind === \"no-listener\") {\n\t\t\treturn \"exited\";\n\t\t}\n\t\tawait new Promise((resolve) => setTimeout(resolve, DAEMON_EXIT_POLL_MS));\n\t}\n\treturn \"timeout\";\n}\n\n/** Spawn a detached daemon and wait (up to 5s) for the socket to answer a status probe. */\nexport async function spawnDetachedDaemon(agentDir: string = getAgentDir()): Promise<SpawnDaemonResult> {\n\tconst paths: DaemonPaths = getDaemonPaths(agentDir);\n\tensureDaemonDirs(paths);\n\tconst { nodeArgs, entry } = resolveDaemonCliInvocation();\n\tconst logFd = openSync(paths.logPath, \"a\", 0o600);\n\tconst child = spawn(process.execPath, [...nodeArgs, entry, \"daemon\", \"run\", \"--foreground\"], {\n\t\tdetached: true,\n\t\twindowsHide: true,\n\t\tstdio: [\"ignore\", logFd, logFd],\n\t\tcwd: agentDir,\n\t\tenv: { ...process.env, [ENV_AGENT_DIR]: agentDir },\n\t});\n\t// An unhandled \"error\" event would crash the calling CLI process; capture it\n\t// and surface it through the health-wait result instead.\n\tlet spawnError: Error | undefined;\n\tchild.once(\"error\", (error) => {\n\t\tspawnError = error;\n\t});\n\tchild.unref();\n\t// The child received duplicated descriptors at spawn; close the parent copy.\n\tcloseSync(logFd);\n\n\tconst deadline = Date.now() + SPAWN_HEALTH_TIMEOUT_MS;\n\twhile (Date.now() < deadline) {\n\t\tif (spawnError) {\n\t\t\treturn { ok: false, socketPath: paths.socketPath, error: `failed to spawn voltd: ${spawnError.message}` };\n\t\t}\n\t\tconst probe = await probeDaemon(agentDir);\n\t\tif (probe.healthy) {\n\t\t\treturn { ok: true, pid: probe.pid, socketPath: probe.socketPath };\n\t\t}\n\t\tawait new Promise((resolve) => setTimeout(resolve, SPAWN_HEALTH_POLL_MS));\n\t}\n\treturn { ok: false, socketPath: paths.socketPath, error: \"daemon did not become healthy within 5s\" };\n}\n\nexport interface EnsureDaemonResult extends DaemonProbeResult {\n\tspawned: boolean;\n\terror?: string;\n\tinvalidState?: InvalidVoltdStateFile;\n}\n\n/** Probe the socket; if no healthy daemon answers, spawn one detached. */\nexport async function ensureDaemonRunning(agentDir: string = getAgentDir()): Promise<EnsureDaemonResult> {\n\tlet probe = await probeDaemon(agentDir);\n\tif (probe.healthy) {\n\t\treturn { ...probe, spawned: false };\n\t}\n\tif (probe.state === \"protocol-mismatch\" || probe.state === \"auth-failed\") {\n\t\treturn { ...probe, spawned: false };\n\t}\n\tif (probe.state === \"unresponsive\") {\n\t\tconst paths = getDaemonPaths(agentDir);\n\t\tconst pidfile = readPidfile(paths.pidfilePath);\n\t\tif (pidfile?.socketPath === probe.socketPath && (await verifyPidfileProcess(pidfile)) === \"match\") {\n\t\t\treturn { ...probe, spawned: false };\n\t\t}\n\t}\n\tif (probe.state === \"shutting-down\") {\n\t\tawait waitForDaemonExit({ agentDir, socketPath: probe.socketPath });\n\t\tprobe = await probeDaemon(agentDir);\n\t\tif (probe.state !== \"not-running\") {\n\t\t\treturn { ...probe, spawned: false };\n\t\t}\n\t}\n\tconst invalidState = inspectVoltdStateFiles(agentDir);\n\tif (invalidState) {\n\t\treturn {\n\t\t\thealthy: false,\n\t\t\tstate: \"not-running\",\n\t\t\tsocketPath: probe.socketPath,\n\t\t\tspawned: false,\n\t\t\terror: invalidState.error,\n\t\t\tinvalidState,\n\t\t};\n\t}\n\tconst spawned = await spawnDetachedDaemon(agentDir);\n\tif (!spawned.ok) {\n\t\treturn {\n\t\t\thealthy: false,\n\t\t\tstate: \"not-running\",\n\t\t\tsocketPath: spawned.socketPath,\n\t\t\tspawned: true,\n\t\t\t...(spawned.error === undefined ? {} : { error: spawned.error }),\n\t\t};\n\t}\n\tconst healthyProbe = await probeDaemon(agentDir);\n\treturn { ...healthyProbe, spawned: true };\n}\n"]}

package/dist/daemon/spawn.js

@@ -0,0 +1,205 @@
+import { spawn } from "node:child_process";
+import { closeSync, existsSync, openSync } from "node:fs";
+import { join } from "node:path";
+import { ENV_AGENT_DIR, getAgentDir, getPackageDir, VERSION } from "../config.js";
+import { probeControlSocket } from "./control-server.js";
+import { readPidfile } from "./main.js";
+import { ensureDaemonDirs, getDaemonPaths } from "./paths.js";
+import { verifyPidfileProcess } from "./process-identity.js";
+import { inspectVoltdStateFiles } from "./state.js";
+const SPAWN_HEALTH_TIMEOUT_MS = 5000;
+const SPAWN_HEALTH_POLL_MS = 100;
+export const DAEMON_SHUTDOWN_TIMEOUT_MS = 75_000;
+const DAEMON_EXIT_POLL_MS = 200;
+function daemonProbeFromSocketProbe(socketPath, probe, authToken) {
+    if (probe.kind === "healthy") {
+        return {
+            healthy: true,
+            state: "healthy",
+            pid: probe.status.pid,
+            version: probe.status.version,
+            protocolVersion: probe.status.protocolVersion,
+            startedAtMs: probe.status.startedAtMs,
+            socketPath,
+            ...(authToken === undefined ? {} : { authToken }),
+        };
+    }
+    if (probe.kind === "live-rejected") {
+        const state = probe.reason === "protocol_mismatch"
+            ? "protocol-mismatch"
+            : probe.reason === "auth_failed"
+                ? "auth-failed"
+                : probe.reason === "shutting_down"
+                    ? "shutting-down"
+                    : "unresponsive";
+        return {
+            healthy: false,
+            state,
+            ...(probe.version === undefined ? {} : { version: probe.version }),
+            ...(probe.protocolVersion === undefined ? {} : { protocolVersion: probe.protocolVersion }),
+            socketPath,
+            ...(authToken === undefined ? {} : { authToken }),
+        };
+    }
+    if (probe.kind === "unresponsive") {
+        return { healthy: false, state: "unresponsive", socketPath, ...(authToken === undefined ? {} : { authToken }) };
+    }
+    return { healthy: false, state: "not-running", socketPath, ...(authToken === undefined ? {} : { authToken }) };
+}
+/**
+ * Probe the pidfile-published daemon endpoint first, then fall back to the
+ * legacy default socket path for older daemons and pre-start diagnostics.
+ */
+export async function probeDaemon(agentDir = getAgentDir()) {
+    const paths = getDaemonPaths(agentDir);
+    const pidfile = readPidfile(paths.pidfilePath);
+    if (pidfile) {
+        const pidfileProbe = await probeControlSocket(pidfile.socketPath, {
+            version: VERSION,
+            ...(pidfile.token === undefined ? {} : { authToken: pidfile.token }),
+        });
+        const pidfileResult = daemonProbeFromSocketProbe(pidfile.socketPath, pidfileProbe, pidfile.token);
+        if (pidfileResult.state !== "not-running") {
+            return pidfileResult;
+        }
+    }
+    const probe = await probeControlSocket(paths.socketPath, { version: VERSION });
+    const result = daemonProbeFromSocketProbe(paths.socketPath, probe, undefined);
+    if (result.state !== "not-running") {
+        return result;
+    }
+    return { healthy: false, state: "not-running", socketPath: paths.socketPath };
+}
+export function resolveDaemonCliInvocation() {
+    const packageDir = getPackageDir();
+    const sourceEntry = join(packageDir, "src", "cli.ts");
+    if (existsSync(sourceEntry)) {
+        return { nodeArgs: ["--conditions", "volt-source"], entry: sourceEntry };
+    }
+    return { nodeArgs: [], entry: join(packageDir, "dist", "cli.js") };
+}
+/** Read the latest complete pidfile endpoint without probing or auto-starting. */
+export function readPublishedDaemonEndpoint(agentDir = getAgentDir()) {
+    const pidfile = readPidfile(getDaemonPaths(agentDir).pidfilePath);
+    if (!pidfile) {
+        return undefined;
+    }
+    return {
+        socketPath: pidfile.socketPath,
+        ...(pidfile.token === undefined ? {} : { authToken: pidfile.token }),
+    };
+}
+function processIsGone(pid) {
+    if (!pid || pid === process.pid) {
+        return true;
+    }
+    try {
+        process.kill(pid, 0);
+        return false;
+    }
+    catch (error) {
+        return !(error instanceof Error && "code" in error && error.code === "EPERM");
+    }
+}
+export async function waitForDaemonExit(options = {}) {
+    const agentDir = options.agentDir ?? getAgentDir();
+    const paths = getDaemonPaths(agentDir);
+    const deadline = Date.now() + (options.timeoutMs ?? DAEMON_SHUTDOWN_TIMEOUT_MS);
+    const targetPid = options.pid ?? options.pidfile?.pid;
+    const socketPath = options.socketPath ?? options.pidfile?.socketPath ?? paths.socketPath;
+    while (Date.now() < deadline) {
+        const socketProbe = await probeControlSocket(socketPath, {
+            version: VERSION,
+            timeoutMs: 500,
+            ...(options.pidfile?.token === undefined ? {} : { authToken: options.pidfile.token }),
+        });
+        if (processIsGone(targetPid) && socketProbe.kind === "no-listener") {
+            return "exited";
+        }
+        await new Promise((resolve) => setTimeout(resolve, DAEMON_EXIT_POLL_MS));
+    }
+    return "timeout";
+}
+/** Spawn a detached daemon and wait (up to 5s) for the socket to answer a status probe. */
+export async function spawnDetachedDaemon(agentDir = getAgentDir()) {
+    const paths = getDaemonPaths(agentDir);
+    ensureDaemonDirs(paths);
+    const { nodeArgs, entry } = resolveDaemonCliInvocation();
+    const logFd = openSync(paths.logPath, "a", 0o600);
+    const child = spawn(process.execPath, [...nodeArgs, entry, "daemon", "run", "--foreground"], {
+        detached: true,
+        windowsHide: true,
+        stdio: ["ignore", logFd, logFd],
+        cwd: agentDir,
+        env: { ...process.env, [ENV_AGENT_DIR]: agentDir },
+    });
+    // An unhandled "error" event would crash the calling CLI process; capture it
+    // and surface it through the health-wait result instead.
+    let spawnError;
+    child.once("error", (error) => {
+        spawnError = error;
+    });
+    child.unref();
+    // The child received duplicated descriptors at spawn; close the parent copy.
+    closeSync(logFd);
+    const deadline = Date.now() + SPAWN_HEALTH_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        if (spawnError) {
+            return { ok: false, socketPath: paths.socketPath, error: `failed to spawn voltd: ${spawnError.message}` };
+        }
+        const probe = await probeDaemon(agentDir);
+        if (probe.healthy) {
+            return { ok: true, pid: probe.pid, socketPath: probe.socketPath };
+        }
+        await new Promise((resolve) => setTimeout(resolve, SPAWN_HEALTH_POLL_MS));
+    }
+    return { ok: false, socketPath: paths.socketPath, error: "daemon did not become healthy within 5s" };
+}
+/** Probe the socket; if no healthy daemon answers, spawn one detached. */
+export async function ensureDaemonRunning(agentDir = getAgentDir()) {
+    let probe = await probeDaemon(agentDir);
+    if (probe.healthy) {
+        return { ...probe, spawned: false };
+    }
+    if (probe.state === "protocol-mismatch" || probe.state === "auth-failed") {
+        return { ...probe, spawned: false };
+    }
+    if (probe.state === "unresponsive") {
+        const paths = getDaemonPaths(agentDir);
+        const pidfile = readPidfile(paths.pidfilePath);
+        if (pidfile?.socketPath === probe.socketPath && (await verifyPidfileProcess(pidfile)) === "match") {
+            return { ...probe, spawned: false };
+        }
+    }
+    if (probe.state === "shutting-down") {
+        await waitForDaemonExit({ agentDir, socketPath: probe.socketPath });
+        probe = await probeDaemon(agentDir);
+        if (probe.state !== "not-running") {
+            return { ...probe, spawned: false };
+        }
+    }
+    const invalidState = inspectVoltdStateFiles(agentDir);
+    if (invalidState) {
+        return {
+            healthy: false,
+            state: "not-running",
+            socketPath: probe.socketPath,
+            spawned: false,
+            error: invalidState.error,
+            invalidState,
+        };
+    }
+    const spawned = await spawnDetachedDaemon(agentDir);
+    if (!spawned.ok) {
+        return {
+            healthy: false,
+            state: "not-running",
+            socketPath: spawned.socketPath,
+            spawned: true,
+            ...(spawned.error === undefined ? {} : { error: spawned.error }),
+        };
+    }
+    const healthyProbe = await probeDaemon(agentDir);
+    return { ...healthyProbe, spawned: true };
+}
+//# sourceMappingURL=spawn.js.map

package/dist/daemon/spawn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn.js","sourceRoot":"","sources":["../../src/daemon/spawn.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC1D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAClF,OAAO,EAA2B,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAClF,OAAO,EAAwB,WAAW,EAAE,MAAM,WAAW,CAAC;AAC9D,OAAO,EAAoB,gBAAgB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAChF,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAA8B,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEhF,MAAM,uBAAuB,GAAG,IAAI,CAAC;AACrC,MAAM,oBAAoB,GAAG,GAAG,CAAC;AACjC,MAAM,CAAC,MAAM,0BAA0B,GAAG,MAAM,CAAC;AACjD,MAAM,mBAAmB,GAAG,GAAG,CAAC;AAqBhC,SAAS,0BAA0B,CAClC,UAAkB,EAClB,KAAyB,EACzB,SAA6B,EACT;IACpB,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC9B,OAAO;YACN,OAAO,EAAE,IAAI;YACb,KAAK,EAAE,SAAS;YAChB,GAAG,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG;YACrB,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,OAAO;YAC7B,eAAe,EAAE,KAAK,CAAC,MAAM,CAAC,eAAe;YAC7C,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,WAAW;YACrC,UAAU;YACV,GAAG,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC;SACjD,CAAC;IACH,CAAC;IACD,IAAI,KAAK,CAAC,IAAI,KAAK,eAAe,EAAE,CAAC;QACpC,MAAM,KAAK,GACV,KAAK,CAAC,MAAM,KAAK,mBAAmB;YACnC,CAAC,CAAC,mBAAmB;YACrB,CAAC,CAAC,KAAK,CAAC,MAAM,KAAK,aAAa;gBAC/B,CAAC,CAAC,aAAa;gBACf,CAAC,CAAC,KAAK,CAAC,MAAM,KAAK,eAAe;oBACjC,CAAC,CAAC,eAAe;oBACjB,CAAC,CAAC,cAAc,CAAC;QACrB,OAAO;YACN,OAAO,EAAE,KAAK;YACd,KAAK;YACL,GAAG,CAAC,KAAK,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;YAClE,GAAG,CAAC,KAAK,CAAC,eAAe,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,KAAK,CAAC,eAAe,EAAE,CAAC;YAC1F,UAAU;YACV,GAAG,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC;SACjD,CAAC;IACH,CAAC;IACD,IAAI,KAAK,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;QACnC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,GAAG,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;IACjH,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,GAAG,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;AAAA,CAC/G;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,QAAQ,GAAW,WAAW,EAAE,EAA8B;IAC/F,MAAM,KAAK,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;IACvC,MAAM,OAAO,GAAG,WAAW,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IAC/C,IAAI,OAAO,EAAE,CAAC;QACb,MAAM,YAAY,GAAG,MAAM,kBAAkB,CAAC,OAAO,CAAC,UAAU,EAAE;YACjE,OAAO,EAAE,OAAO;YAChB,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;SACpE,CAAC,CAAC;QACH,MAAM,aAAa,GAAG,0BAA0B,CAAC,OAAO,CAAC,UAAU,EAAE,YAAY,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QAClG,IAAI,aAAa,CAAC,KAAK,KAAK,aAAa,EAAE,CAAC;YAC3C,OAAO,aAAa,CAAC;QACtB,CAAC;IACF,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,kBAAkB,CAAC,KAAK,CAAC,UAAU,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;IAC/E,MAAM,MAAM,GAAG,0BAA0B,CAAC,KAAK,CAAC,UAAU,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;IAC9E,IAAI,MAAM,CAAC,KAAK,KAAK,aAAa,EAAE,CAAC;QACpC,OAAO,MAAM,CAAC;IACf,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC;AAAA,CAC9E;AAED,MAAM,UAAU,0BAA0B,GAA0C;IACnF,MAAM,UAAU,GAAG,aAAa,EAAE,CAAC;IACnC,MAAM,WAAW,GAAG,IAAI,CAAC,UAAU,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;IACtD,IAAI,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;QAC7B,OAAO,EAAE,QAAQ,EAAE,CAAC,cAAc,EAAE,aAAa,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC;IAC1E,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC;AAAA,CACnE;AAcD,kFAAkF;AAClF,MAAM,UAAU,2BAA2B,CAAC,QAAQ,GAAW,WAAW,EAAE,EAAuC;IAClH,MAAM,OAAO,GAAG,WAAW,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,WAAW,CAAC,CAAC;IAClE,IAAI,CAAC,OAAO,EAAE,CAAC;QACd,OAAO,SAAS,CAAC;IAClB,CAAC;IACD,OAAO;QACN,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;KACpE,CAAC;AAAA,CACF;AAUD,SAAS,aAAa,CAAC,GAAuB,EAAW;IACxD,IAAI,CAAC,GAAG,IAAI,GAAG,KAAK,OAAO,CAAC,GAAG,EAAE,CAAC;QACjC,OAAO,IAAI,CAAC;IACb,CAAC;IACD,IAAI,CAAC;QACJ,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACrB,OAAO,KAAK,CAAC;IACd,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,OAAO,CAAC,CAAC,KAAK,YAAY,KAAK,IAAI,MAAM,IAAI,KAAK,IAAK,KAA+B,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC;IAC1G,CAAC;AAAA,CACD;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,OAAO,GAA6B,EAAE,EAAiC;IAC9G,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,WAAW,EAAE,CAAC;IACnD,MAAM,KAAK,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;IACvC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,OAAO,CAAC,SAAS,IAAI,0BAA0B,CAAC,CAAC;IAChF,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC;IACtD,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,OAAO,CAAC,OAAO,EAAE,UAAU,IAAI,KAAK,CAAC,UAAU,CAAC;IACzF,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAC;QAC9B,MAAM,WAAW,GAAG,MAAM,kBAAkB,CAAC,UAAU,EAAE;YACxD,OAAO,EAAE,OAAO;YAChB,SAAS,EAAE,GAAG;YACd,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;SACrF,CAAC,CAAC;QACH,IAAI,aAAa,CAAC,SAAS,CAAC,IAAI,WAAW,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;YACpE,OAAO,QAAQ,CAAC;QACjB,CAAC;QACD,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC;IAC1E,CAAC;IACD,OAAO,SAAS,CAAC;AAAA,CACjB;AAED,2FAA2F;AAC3F,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,QAAQ,GAAW,WAAW,EAAE,EAA8B;IACvG,MAAM,KAAK,GAAgB,cAAc,CAAC,QAAQ,CAAC,CAAC;IACpD,gBAAgB,CAAC,KAAK,CAAC,CAAC;IACxB,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,0BAA0B,EAAE,CAAC;IACzD,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;IAClD,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,GAAG,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,cAAc,CAAC,EAAE;QAC5F,QAAQ,EAAE,IAAI;QACd,WAAW,EAAE,IAAI;QACjB,KAAK,EAAE,CAAC,QAAQ,EAAE,KAAK,EAAE,KAAK,CAAC;QAC/B,GAAG,EAAE,QAAQ;QACb,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,aAAa,CAAC,EAAE,QAAQ,EAAE;KAClD,CAAC,CAAC;IACH,6EAA6E;IAC7E,yDAAyD;IACzD,IAAI,UAA6B,CAAC;IAClC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC;QAC9B,UAAU,GAAG,KAAK,CAAC;IAAA,CACnB,CAAC,CAAC;IACH,KAAK,CAAC,KAAK,EAAE,CAAC;IACd,6EAA6E;IAC7E,SAAS,CAAC,KAAK,CAAC,CAAC;IAEjB,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,uBAAuB,CAAC;IACtD,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAC;QAC9B,IAAI,UAAU,EAAE,CAAC;YAChB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,KAAK,EAAE,0BAA0B,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC;QAC3G,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC,QAAQ,CAAC,CAAC;QAC1C,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;YACnB,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC;QACnE,CAAC;QACD,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,KAAK,EAAE,yCAAyC,EAAE,CAAC;AAAA,CACrG;AAQD,0EAA0E;AAC1E,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,QAAQ,GAAW,WAAW,EAAE,EAA+B;IACxG,IAAI,KAAK,GAAG,MAAM,WAAW,CAAC,QAAQ,CAAC,CAAC;IACxC,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;QACnB,OAAO,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IACrC,CAAC;IACD,IAAI,KAAK,CAAC,KAAK,KAAK,mBAAmB,IAAI,KAAK,CAAC,KAAK,KAAK,aAAa,EAAE,CAAC;QAC1E,OAAO,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IACrC,CAAC;IACD,IAAI,KAAK,CAAC,KAAK,KAAK,cAAc,EAAE,CAAC;QACpC,MAAM,KAAK,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;QACvC,MAAM,OAAO,GAAG,WAAW,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;QAC/C,IAAI,OAAO,EAAE,UAAU,KAAK,KAAK,CAAC,UAAU,IAAI,CAAC,MAAM,oBAAoB,CAAC,OAAO,CAAC,CAAC,KAAK,OAAO,EAAE,CAAC;YACnG,OAAO,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QACrC,CAAC;IACF,CAAC;IACD,IAAI,KAAK,CAAC,KAAK,KAAK,eAAe,EAAE,CAAC;QACrC,MAAM,iBAAiB,CAAC,EAAE,QAAQ,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC;QACpE,KAAK,GAAG,MAAM,WAAW,CAAC,QAAQ,CAAC,CAAC;QACpC,IAAI,KAAK,CAAC,KAAK,KAAK,aAAa,EAAE,CAAC;YACnC,OAAO,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QACrC,CAAC;IACF,CAAC;IACD,MAAM,YAAY,GAAG,sBAAsB,CAAC,QAAQ,CAAC,CAAC;IACtD,IAAI,YAAY,EAAE,CAAC;QAClB,OAAO;YACN,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,aAAa;YACpB,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,YAAY,CAAC,KAAK;YACzB,YAAY;SACZ,CAAC;IACH,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IACpD,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC;QACjB,OAAO;YACN,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,aAAa;YACpB,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,OAAO,EAAE,IAAI;YACb,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;SAChE,CAAC;IACH,CAAC;IACD,MAAM,YAAY,GAAG,MAAM,WAAW,CAAC,QAAQ,CAAC,CAAC;IACjD,OAAO,EAAE,GAAG,YAAY,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAAA,CAC1C","sourcesContent":["import { spawn } from \"node:child_process\";\nimport { closeSync, existsSync, openSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { ENV_AGENT_DIR, getAgentDir, getPackageDir, VERSION } from \"../config.ts\";\nimport { type ControlSocketProbe, probeControlSocket } from \"./control-server.ts\";\nimport { type PidfileContents, readPidfile } from \"./main.ts\";\nimport { type DaemonPaths, ensureDaemonDirs, getDaemonPaths } from \"./paths.ts\";\nimport { verifyPidfileProcess } from \"./process-identity.ts\";\nimport { type InvalidVoltdStateFile, inspectVoltdStateFiles } from \"./state.ts\";\n\nconst SPAWN_HEALTH_TIMEOUT_MS = 5000;\nconst SPAWN_HEALTH_POLL_MS = 100;\nexport const DAEMON_SHUTDOWN_TIMEOUT_MS = 75_000;\nconst DAEMON_EXIT_POLL_MS = 200;\n\nexport type DaemonProbeState =\n\t| \"healthy\"\n\t| \"shutting-down\"\n\t| \"protocol-mismatch\"\n\t| \"auth-failed\"\n\t| \"unresponsive\"\n\t| \"not-running\";\n\nexport interface DaemonProbeResult {\n\thealthy: boolean;\n\tstate: DaemonProbeState;\n\tpid?: number;\n\tversion?: string;\n\tprotocolVersion?: number;\n\tstartedAtMs?: number;\n\tsocketPath: string;\n\tauthToken?: string;\n}\n\nfunction daemonProbeFromSocketProbe(\n\tsocketPath: string,\n\tprobe: ControlSocketProbe,\n\tauthToken: string | undefined,\n): DaemonProbeResult {\n\tif (probe.kind === \"healthy\") {\n\t\treturn {\n\t\t\thealthy: true,\n\t\t\tstate: \"healthy\",\n\t\t\tpid: probe.status.pid,\n\t\t\tversion: probe.status.version,\n\t\t\tprotocolVersion: probe.status.protocolVersion,\n\t\t\tstartedAtMs: probe.status.startedAtMs,\n\t\t\tsocketPath,\n\t\t\t...(authToken === undefined ? {} : { authToken }),\n\t\t};\n\t}\n\tif (probe.kind === \"live-rejected\") {\n\t\tconst state: DaemonProbeState =\n\t\t\tprobe.reason === \"protocol_mismatch\"\n\t\t\t\t? \"protocol-mismatch\"\n\t\t\t\t: probe.reason === \"auth_failed\"\n\t\t\t\t\t? \"auth-failed\"\n\t\t\t\t\t: probe.reason === \"shutting_down\"\n\t\t\t\t\t\t? \"shutting-down\"\n\t\t\t\t\t\t: \"unresponsive\";\n\t\treturn {\n\t\t\thealthy: false,\n\t\t\tstate,\n\t\t\t...(probe.version === undefined ? {} : { version: probe.version }),\n\t\t\t...(probe.protocolVersion === undefined ? {} : { protocolVersion: probe.protocolVersion }),\n\t\t\tsocketPath,\n\t\t\t...(authToken === undefined ? {} : { authToken }),\n\t\t};\n\t}\n\tif (probe.kind === \"unresponsive\") {\n\t\treturn { healthy: false, state: \"unresponsive\", socketPath, ...(authToken === undefined ? {} : { authToken }) };\n\t}\n\treturn { healthy: false, state: \"not-running\", socketPath, ...(authToken === undefined ? {} : { authToken }) };\n}\n\n/**\n * Probe the pidfile-published daemon endpoint first, then fall back to the\n * legacy default socket path for older daemons and pre-start diagnostics.\n */\nexport async function probeDaemon(agentDir: string = getAgentDir()): Promise<DaemonProbeResult> {\n\tconst paths = getDaemonPaths(agentDir);\n\tconst pidfile = readPidfile(paths.pidfilePath);\n\tif (pidfile) {\n\t\tconst pidfileProbe = await probeControlSocket(pidfile.socketPath, {\n\t\t\tversion: VERSION,\n\t\t\t...(pidfile.token === undefined ? {} : { authToken: pidfile.token }),\n\t\t});\n\t\tconst pidfileResult = daemonProbeFromSocketProbe(pidfile.socketPath, pidfileProbe, pidfile.token);\n\t\tif (pidfileResult.state !== \"not-running\") {\n\t\t\treturn pidfileResult;\n\t\t}\n\t}\n\tconst probe = await probeControlSocket(paths.socketPath, { version: VERSION });\n\tconst result = daemonProbeFromSocketProbe(paths.socketPath, probe, undefined);\n\tif (result.state !== \"not-running\") {\n\t\treturn result;\n\t}\n\treturn { healthy: false, state: \"not-running\", socketPath: paths.socketPath };\n}\n\nexport function resolveDaemonCliInvocation(): { nodeArgs: string[]; entry: string } {\n\tconst packageDir = getPackageDir();\n\tconst sourceEntry = join(packageDir, \"src\", \"cli.ts\");\n\tif (existsSync(sourceEntry)) {\n\t\treturn { nodeArgs: [\"--conditions\", \"volt-source\"], entry: sourceEntry };\n\t}\n\treturn { nodeArgs: [], entry: join(packageDir, \"dist\", \"cli.js\") };\n}\n\nexport interface SpawnDaemonResult {\n\tok: boolean;\n\tpid?: number;\n\tsocketPath: string;\n\terror?: string;\n}\n\nexport interface PublishedDaemonEndpoint {\n\tsocketPath: string;\n\tauthToken?: string;\n}\n\n/** Read the latest complete pidfile endpoint without probing or auto-starting. */\nexport function readPublishedDaemonEndpoint(agentDir: string = getAgentDir()): PublishedDaemonEndpoint | undefined {\n\tconst pidfile = readPidfile(getDaemonPaths(agentDir).pidfilePath);\n\tif (!pidfile) {\n\t\treturn undefined;\n\t}\n\treturn {\n\t\tsocketPath: pidfile.socketPath,\n\t\t...(pidfile.token === undefined ? {} : { authToken: pidfile.token }),\n\t};\n}\n\nexport interface WaitForDaemonExitOptions {\n\tagentDir?: string;\n\tpid?: number;\n\tpidfile?: PidfileContents;\n\tsocketPath?: string;\n\ttimeoutMs?: number;\n}\n\nfunction processIsGone(pid: number | undefined): boolean {\n\tif (!pid || pid === process.pid) {\n\t\treturn true;\n\t}\n\ttry {\n\t\tprocess.kill(pid, 0);\n\t\treturn false;\n\t} catch (error) {\n\t\treturn !(error instanceof Error && \"code\" in error && (error as NodeJS.ErrnoException).code === \"EPERM\");\n\t}\n}\n\nexport async function waitForDaemonExit(options: WaitForDaemonExitOptions = {}): Promise<\"exited\" | \"timeout\"> {\n\tconst agentDir = options.agentDir ?? getAgentDir();\n\tconst paths = getDaemonPaths(agentDir);\n\tconst deadline = Date.now() + (options.timeoutMs ?? DAEMON_SHUTDOWN_TIMEOUT_MS);\n\tconst targetPid = options.pid ?? options.pidfile?.pid;\n\tconst socketPath = options.socketPath ?? options.pidfile?.socketPath ?? paths.socketPath;\n\twhile (Date.now() < deadline) {\n\t\tconst socketProbe = await probeControlSocket(socketPath, {\n\t\t\tversion: VERSION,\n\t\t\ttimeoutMs: 500,\n\t\t\t...(options.pidfile?.token === undefined ? {} : { authToken: options.pidfile.token }),\n\t\t});\n\t\tif (processIsGone(targetPid) && socketProbe.kind === \"no-listener\") {\n\t\t\treturn \"exited\";\n\t\t}\n\t\tawait new Promise((resolve) => setTimeout(resolve, DAEMON_EXIT_POLL_MS));\n\t}\n\treturn \"timeout\";\n}\n\n/** Spawn a detached daemon and wait (up to 5s) for the socket to answer a status probe. */\nexport async function spawnDetachedDaemon(agentDir: string = getAgentDir()): Promise<SpawnDaemonResult> {\n\tconst paths: DaemonPaths = getDaemonPaths(agentDir);\n\tensureDaemonDirs(paths);\n\tconst { nodeArgs, entry } = resolveDaemonCliInvocation();\n\tconst logFd = openSync(paths.logPath, \"a\", 0o600);\n\tconst child = spawn(process.execPath, [...nodeArgs, entry, \"daemon\", \"run\", \"--foreground\"], {\n\t\tdetached: true,\n\t\twindowsHide: true,\n\t\tstdio: [\"ignore\", logFd, logFd],\n\t\tcwd: agentDir,\n\t\tenv: { ...process.env, [ENV_AGENT_DIR]: agentDir },\n\t});\n\t// An unhandled \"error\" event would crash the calling CLI process; capture it\n\t// and surface it through the health-wait result instead.\n\tlet spawnError: Error | undefined;\n\tchild.once(\"error\", (error) => {\n\t\tspawnError = error;\n\t});\n\tchild.unref();\n\t// The child received duplicated descriptors at spawn; close the parent copy.\n\tcloseSync(logFd);\n\n\tconst deadline = Date.now() + SPAWN_HEALTH_TIMEOUT_MS;\n\twhile (Date.now() < deadline) {\n\t\tif (spawnError) {\n\t\t\treturn { ok: false, socketPath: paths.socketPath, error: `failed to spawn voltd: ${spawnError.message}` };\n\t\t}\n\t\tconst probe = await probeDaemon(agentDir);\n\t\tif (probe.healthy) {\n\t\t\treturn { ok: true, pid: probe.pid, socketPath: probe.socketPath };\n\t\t}\n\t\tawait new Promise((resolve) => setTimeout(resolve, SPAWN_HEALTH_POLL_MS));\n\t}\n\treturn { ok: false, socketPath: paths.socketPath, error: \"daemon did not become healthy within 5s\" };\n}\n\nexport interface EnsureDaemonResult extends DaemonProbeResult {\n\tspawned: boolean;\n\terror?: string;\n\tinvalidState?: InvalidVoltdStateFile;\n}\n\n/** Probe the socket; if no healthy daemon answers, spawn one detached. */\nexport async function ensureDaemonRunning(agentDir: string = getAgentDir()): Promise<EnsureDaemonResult> {\n\tlet probe = await probeDaemon(agentDir);\n\tif (probe.healthy) {\n\t\treturn { ...probe, spawned: false };\n\t}\n\tif (probe.state === \"protocol-mismatch\" || probe.state === \"auth-failed\") {\n\t\treturn { ...probe, spawned: false };\n\t}\n\tif (probe.state === \"unresponsive\") {\n\t\tconst paths = getDaemonPaths(agentDir);\n\t\tconst pidfile = readPidfile(paths.pidfilePath);\n\t\tif (pidfile?.socketPath === probe.socketPath && (await verifyPidfileProcess(pidfile)) === \"match\") {\n\t\t\treturn { ...probe, spawned: false };\n\t\t}\n\t}\n\tif (probe.state === \"shutting-down\") {\n\t\tawait waitForDaemonExit({ agentDir, socketPath: probe.socketPath });\n\t\tprobe = await probeDaemon(agentDir);\n\t\tif (probe.state !== \"not-running\") {\n\t\t\treturn { ...probe, spawned: false };\n\t\t}\n\t}\n\tconst invalidState = inspectVoltdStateFiles(agentDir);\n\tif (invalidState) {\n\t\treturn {\n\t\t\thealthy: false,\n\t\t\tstate: \"not-running\",\n\t\t\tsocketPath: probe.socketPath,\n\t\t\tspawned: false,\n\t\t\terror: invalidState.error,\n\t\t\tinvalidState,\n\t\t};\n\t}\n\tconst spawned = await spawnDetachedDaemon(agentDir);\n\tif (!spawned.ok) {\n\t\treturn {\n\t\t\thealthy: false,\n\t\t\tstate: \"not-running\",\n\t\t\tsocketPath: spawned.socketPath,\n\t\t\tspawned: true,\n\t\t\t...(spawned.error === undefined ? {} : { error: spawned.error }),\n\t\t};\n\t}\n\tconst healthyProbe = await probeDaemon(agentDir);\n\treturn { ...healthyProbe, spawned: true };\n}\n"]}

package/dist/daemon/state.d.ts

@@ -0,0 +1,145 @@
+import { type IrohRemoteClient, type IrohRemoteHostState, type IrohRemotePairingSecretTombstone, type IrohRemotePendingPairingTicket, type IrohRemoteRevokedClient, type IrohRemoteWorkspace, type IrohRemoteWorkspaceWorktree } from "../core/remote/iroh/state.ts";
+/**
+ * Persistent daemon state. The pairing/client sections reuse the legacy host
+ * state shapes verbatim (push targets and live-activity registrations stay
+ * embedded in each client, as `src/core/remote/iroh/push.ts` expects). The Iroh
+ * identity survives migration; pre-grant client authority is intentionally not imported.
+ */
+export interface VoltdStateFileV1 {
+    version: 1;
+    /** Iroh secret key bytes; MUST survive migration so the saved host identity remains stable. */
+    irohSecretKey?: number[];
+    clients: IrohRemoteClient[];
+    revokedClients: IrohRemoteRevokedClient[];
+    workspaces: IrohRemoteWorkspace[];
+    worktrees: IrohRemoteWorkspaceWorktree[];
+    pendingPairingTickets: IrohRemotePendingPairingTicket[];
+    pairingSecretTombstones: IrohRemotePairingSecretTombstone[];
+    settings: {
+        /** Detached headless runtime retention TTL. */
+        detachedRuntimeTtlMs: number;
+        /** Tool allowlist applied ONLY to daemon-owned headless runtimes. */
+        allowTools: string[] | null;
+        /** Active daemon theme (theme_set); undefined falls back to the default theme. */
+        themeName?: string;
+        /** Push sanitized resolved theme tokens to capable phones (§9.5); OFF by default. */
+        themeTokenPush?: boolean;
+        /** Hold a keep-awake (prevent system sleep) assertion while the daemon runs; OFF by default. */
+        keepAwakeEnabled?: boolean;
+        /**
+         * Bearer token presented to relay servers (access.shared_token). Seeded
+         * from VOLT_IROH_RELAY_AUTH_TOKEN and persisted so bare restarts keep
+         * authenticating; pairing tickets carry it to phones.
+         */
+        relayAuthToken?: string;
+        /** Worktree cleanup policies (design §5.3); all opt-in except pruneOnStart. */
+        worktreeCleanup?: WorktreeCleanupSettings;
+    };
+}
+export interface WorktreeCleanupSettings {
+    /** Remove clean, fully merged worktrees after the TTL once their runtime is disposed. */
+    retention?: {
+        enabled: boolean;
+        ttlMs: number;
+    };
+    /** Reconcile worktree records/checkouts during daemon startup (default true). */
+    pruneOnStart?: boolean;
+}
+export interface ResolvedWorktreeCleanupPolicy {
+    retention: {
+        enabled: boolean;
+        ttlMs: number;
+    } | undefined;
+    pruneOnStart: boolean;
+}
+/** Apply worktree-cleanup defaults: retention off, pruneOnStart on. */
+export declare function resolveWorktreeCleanupPolicy(settings: Pick<VoltdStateFileV1["settings"], "worktreeCleanup">): ResolvedWorktreeCleanupPolicy;
+export declare function createEmptyVoltdState(): VoltdStateFileV1;
+export declare function voltdStateToHostState(state: VoltdStateFileV1): IrohRemoteHostState;
+export declare function hostStateToVoltdState(hostState: IrohRemoteHostState, settings: VoltdStateFileV1["settings"]): VoltdStateFileV1;
+export declare function parseVoltdState(value: unknown): VoltdStateFileV1;
+export declare function getLegacyRemoteStatePath(agentDir: string): string;
+export interface LegacyRemoteStateMigration {
+    state: VoltdStateFileV1;
+    droppedAccess: {
+        clients: number;
+        revokedClients: number;
+        pendingPairingTickets: number;
+    };
+}
+/**
+ * One-time migration from remote/iroh-host.json. A pre-grant file keeps the
+ * Iroh identity plus validated workspace/worktree metadata, but deliberately
+ * drops every old authority-bearing record. Those clients must pair again
+ * under an explicit RPC grant; expected pre-grant migration is not corruption.
+ */
+export declare function migrateLegacyRemoteState(agentDir: string, statePath: string): LegacyRemoteStateMigration | null;
+export interface VoltdStateStoreOptions {
+    agentDir: string;
+    statePath: string;
+    /** Debounce for coalescing writes; flushes synchronously on close(). */
+    debounceMs?: number;
+    /** Durable writer seam for deterministic persistence-concurrency tests. */
+    writeStateFile?: (path: string, content: string) => Promise<void>;
+}
+export interface LoadVoltdStateResult {
+    state: VoltdStateFileV1;
+    migratedFromLegacyState: boolean;
+    legacyDroppedAccess?: LegacyRemoteStateMigration["droppedAccess"];
+}
+export interface InvalidVoltdStateFile {
+    path: string;
+    error: string;
+}
+/** Inspect persisted daemon state without modifying or migrating it. */
+export declare function inspectVoltdStateFiles(agentDir: string): InvalidVoltdStateFile | undefined;
+export interface RecoverableVoltdStateBackup {
+    path: string;
+    preservedIdentity: boolean;
+}
+/** Find the newest validated daemon-state backup that can be safely regenerated. */
+export declare function findRecoverableVoltdStateBackup(agentDir: string): RecoverableVoltdStateBackup | undefined;
+/** Replace current state from a validated backup, preserving the source and backing up the current file. */
+export declare function recoverVoltdStateFromBackup(agentDir: string, backupPath: string): Promise<{
+    previousStateBackupPath?: string;
+    preservedIdentity: boolean;
+}>;
+/** Back up invalid state and regenerate validated non-authority data when possible. */
+export declare function regenerateInvalidVoltdState(agentDir: string): Promise<{
+    backupPath: string;
+    preservedIdentity: boolean;
+}>;
+/** Debounced, atomic (tmp + rename, 0600) persistence for VoltdStateFileV1. */
+export declare class VoltdStateStore {
+    private readonly statePath;
+    private readonly agentDir;
+    private readonly debounceMs;
+    private readonly writeStateFile;
+    private current;
+    private flushTimer;
+    private pendingFlush;
+    private stateRevision;
+    private persistedRevision;
+    private migrated;
+    private legacyDroppedAccess;
+    constructor(options: VoltdStateStoreOptions);
+    load(): Promise<LoadVoltdStateResult>;
+    get state(): VoltdStateFileV1;
+    /** Replace the host-state portion (used as the state-manager write hook). */
+    setHostState(hostState: IrohRemoteHostState): void;
+    getHostState(): IrohRemoteHostState;
+    updateSettings(settings: Partial<VoltdStateFileV1["settings"]>): void;
+    scheduleFlush(): void;
+    /**
+     * Force an immediate durable write, cancelling any pending debounce. Use after
+     * minting state that must survive a crash the moment it exists (e.g. the freshly
+     * generated Iroh identity, before the endpoint starts accepting pairings).
+     */
+    flush(): Promise<void>;
+    /** Flush pending changes and stop the debounce timer (graceful shutdown). */
+    close(): Promise<void>;
+    private markStateChanged;
+    private enqueueWrite;
+    private writeNow;
+}
+//# sourceMappingURL=state.d.ts.map

package/dist/daemon/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/daemon/state.ts"],"names":[],"mappings":"AAGA,OAAO,EAEN,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,gCAAgC,EACrC,KAAK,8BAA8B,EACnC,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACxB,KAAK,2BAA2B,EAEhC,MAAM,8BAA8B,CAAC;AAItC;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAChC,OAAO,EAAE,CAAC,CAAC;IACX,+FAA+F;IAC/F,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,cAAc,EAAE,uBAAuB,EAAE,CAAC;IAC1C,UAAU,EAAE,mBAAmB,EAAE,CAAC;IAClC,SAAS,EAAE,2BAA2B,EAAE,CAAC;IACzC,qBAAqB,EAAE,8BAA8B,EAAE,CAAC;IACxD,uBAAuB,EAAE,gCAAgC,EAAE,CAAC;IAC5D,QAAQ,EAAE;QACT,+CAA+C;QAC/C,oBAAoB,EAAE,MAAM,CAAC;QAC7B,qEAAqE;QACrE,UAAU,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QAC5B,kFAAkF;QAClF,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,sFAAqF;QACrF,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,gGAAgG;QAChG,gBAAgB,CAAC,EAAE,OAAO,CAAC;QAC3B;;;;WAIG;QACH,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,gFAA+E;QAC/E,eAAe,CAAC,EAAE,uBAAuB,CAAC;KAC1C,CAAC;CACF;AAED,MAAM,WAAW,uBAAuB;IACvC,yFAAyF;IACzF,SAAS,CAAC,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAChD,iFAAiF;IACjF,YAAY,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,6BAA6B;IAC7C,SAAS,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IAC3D,YAAY,EAAE,OAAO,CAAC;CACtB;AAED,uEAAuE;AACvE,wBAAgB,4BAA4B,CAC3C,QAAQ,EAAE,IAAI,CAAC,gBAAgB,CAAC,UAAU,CAAC,EAAE,iBAAiB,CAAC,GAC7D,6BAA6B,CAO/B;AA6BD,wBAAgB,qBAAqB,IAAI,gBAAgB,CAexD;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,gBAAgB,GAAG,mBAAmB,CAUlF;AAED,wBAAgB,qBAAqB,CACpC,SAAS,EAAE,mBAAmB,EAC9B,QAAQ,EAAE,gBAAgB,CAAC,UAAU,CAAC,GACpC,gBAAgB,CAYlB;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAwChE;AAED,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED,MAAM,WAAW,0BAA0B;IAC1C,KAAK,EAAE,gBAAgB,CAAC;IACxB,aAAa,EAAE;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,cAAc,EAAE,MAAM,CAAC;QACvB,qBAAqB,EAAE,MAAM,CAAC;KAC9B,CAAC;CACF;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,0BAA0B,GAAG,IAAI,CAkC/G;AAuBD,MAAM,WAAW,sBAAsB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAClE;AAED,MAAM,WAAW,oBAAoB;IACpC,KAAK,EAAE,gBAAgB,CAAC;IACxB,uBAAuB,EAAE,OAAO,CAAC;IACjC,mBAAmB,CAAC,EAAE,0BAA0B,CAAC,eAAe,CAAC,CAAC;CAClE;AAID,MAAM,WAAW,qBAAqB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACd;AAcD,wEAAwE;AACxE,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,qBAAqB,GAAG,SAAS,CAoB1F;AAgCD,MAAM,WAAW,2BAA2B;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,iBAAiB,EAAE,OAAO,CAAC;CAC3B;AAED,oFAAoF;AACpF,wBAAgB,+BAA+B,CAAC,QAAQ,EAAE,MAAM,GAAG,2BAA2B,GAAG,SAAS,CAiBzG;AAED,4GAA4G;AAC5G,wBAAsB,2BAA2B,CAChD,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GAChB,OAAO,CAAC;IAAE,uBAAuB,CAAC,EAAE,MAAM,CAAC;IAAC,iBAAiB,EAAE,OAAO,CAAA;CAAE,CAAC,CAoB3E;AAED,uFAAuF;AACvF,wBAAsB,2BAA2B,CAChD,QAAQ,EAAE,MAAM,GACd,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,iBAAiB,EAAE,OAAO,CAAA;CAAE,CAAC,CAmB7D;AAED,+EAA+E;AAC/E,qBAAa,eAAe;IAC3B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAmD;IAClF,OAAO,CAAC,OAAO,CAA+B;IAC9C,OAAO,CAAC,UAAU,CAA6B;IAC/C,OAAO,CAAC,YAAY,CAAoC;IACxD,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,mBAAmB,CAA0D;IAErF,YAAY,OAAO,EAAE,sBAAsB,EAK1C;IAEK,IAAI,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAmD1C;IAED,IAAI,KAAK,IAAI,gBAAgB,CAK5B;IAED,6EAA6E;IAC7E,YAAY,CAAC,SAAS,EAAE,mBAAmB,GAAG,IAAI,CAGjD;IAED,YAAY,IAAI,mBAAmB,CAElC;IAED,cAAc,CAAC,QAAQ,EAAE,OAAO,CAAC,gBAAgB,CAAC,UAAU,CAAC,CAAC,GAAG,IAAI,CAGpE;IAED,aAAa,IAAI,IAAI,CAUpB;IAED;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAc3B;IAED,6EAA6E;IACvE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAE3B;IAED,OAAO,CAAC,gBAAgB;IAIxB,OAAO,CAAC,YAAY;YAON,QAAQ;CAStB","sourcesContent":["import { existsSync, readdirSync, readFileSync, statSync } from \"node:fs\";\nimport { rename } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport {\n\tcreateEmptyIrohRemoteHostState,\n\ttype IrohRemoteClient,\n\ttype IrohRemoteHostState,\n\ttype IrohRemotePairingSecretTombstone,\n\ttype IrohRemotePendingPairingTicket,\n\ttype IrohRemoteRevokedClient,\n\ttype IrohRemoteWorkspace,\n\ttype IrohRemoteWorkspaceWorktree,\n\tparseIrohRemoteHostState,\n} from \"../core/remote/iroh/state.ts\";\nimport { DEFAULT_INTEGRATED_DETACHED_RUNTIME_TTL_MS } from \"../remote/integrated-runtime-retention.ts\";\nimport { writeDurableAtomicFile } from \"../utils/durable-atomic-write.ts\";\n\n/**\n * Persistent daemon state. The pairing/client sections reuse the legacy host\n * state shapes verbatim (push targets and live-activity registrations stay\n * embedded in each client, as `src/core/remote/iroh/push.ts` expects). The Iroh\n * identity survives migration; pre-grant client authority is intentionally not imported.\n */\nexport interface VoltdStateFileV1 {\n\tversion: 1;\n\t/** Iroh secret key bytes; MUST survive migration so the saved host identity remains stable. */\n\tirohSecretKey?: number[];\n\tclients: IrohRemoteClient[];\n\trevokedClients: IrohRemoteRevokedClient[];\n\tworkspaces: IrohRemoteWorkspace[];\n\tworktrees: IrohRemoteWorkspaceWorktree[];\n\tpendingPairingTickets: IrohRemotePendingPairingTicket[];\n\tpairingSecretTombstones: IrohRemotePairingSecretTombstone[];\n\tsettings: {\n\t\t/** Detached headless runtime retention TTL. */\n\t\tdetachedRuntimeTtlMs: number;\n\t\t/** Tool allowlist applied ONLY to daemon-owned headless runtimes. */\n\t\tallowTools: string[] | null;\n\t\t/** Active daemon theme (theme_set); undefined falls back to the default theme. */\n\t\tthemeName?: string;\n\t\t/** Push sanitized resolved theme tokens to capable phones (§9.5); OFF by default. */\n\t\tthemeTokenPush?: boolean;\n\t\t/** Hold a keep-awake (prevent system sleep) assertion while the daemon runs; OFF by default. */\n\t\tkeepAwakeEnabled?: boolean;\n\t\t/**\n\t\t * Bearer token presented to relay servers (access.shared_token). Seeded\n\t\t * from VOLT_IROH_RELAY_AUTH_TOKEN and persisted so bare restarts keep\n\t\t * authenticating; pairing tickets carry it to phones.\n\t\t */\n\t\trelayAuthToken?: string;\n\t\t/** Worktree cleanup policies (design §5.3); all opt-in except pruneOnStart. */\n\t\tworktreeCleanup?: WorktreeCleanupSettings;\n\t};\n}\n\nexport interface WorktreeCleanupSettings {\n\t/** Remove clean, fully merged worktrees after the TTL once their runtime is disposed. */\n\tretention?: { enabled: boolean; ttlMs: number };\n\t/** Reconcile worktree records/checkouts during daemon startup (default true). */\n\tpruneOnStart?: boolean;\n}\n\nexport interface ResolvedWorktreeCleanupPolicy {\n\tretention: { enabled: boolean; ttlMs: number } | undefined;\n\tpruneOnStart: boolean;\n}\n\n/** Apply worktree-cleanup defaults: retention off, pruneOnStart on. */\nexport function resolveWorktreeCleanupPolicy(\n\tsettings: Pick<VoltdStateFileV1[\"settings\"], \"worktreeCleanup\">,\n): ResolvedWorktreeCleanupPolicy {\n\tconst cleanup = settings.worktreeCleanup;\n\tconst retention =\n\t\tcleanup?.retention?.enabled && cleanup.retention.ttlMs > 0\n\t\t\t? { enabled: true, ttlMs: cleanup.retention.ttlMs }\n\t\t\t: undefined;\n\treturn { retention, pruneOnStart: cleanup?.pruneOnStart !== false };\n}\n\nfunction parseWorktreeCleanupSettings(value: unknown): WorktreeCleanupSettings | undefined {\n\tif (typeof value !== \"object\" || value === null || Array.isArray(value)) {\n\t\treturn undefined;\n\t}\n\tconst record = value as Record<string, unknown>;\n\tconst retentionRecord =\n\t\ttypeof record.retention === \"object\" && record.retention !== null && !Array.isArray(record.retention)\n\t\t\t? (record.retention as Record<string, unknown>)\n\t\t\t: undefined;\n\tconst retention =\n\t\tretentionRecord !== undefined &&\n\t\ttypeof retentionRecord.enabled === \"boolean\" &&\n\t\ttypeof retentionRecord.ttlMs === \"number\" &&\n\t\tNumber.isInteger(retentionRecord.ttlMs) &&\n\t\tretentionRecord.ttlMs > 0\n\t\t\t? { enabled: retentionRecord.enabled, ttlMs: retentionRecord.ttlMs }\n\t\t\t: undefined;\n\tconst pruneOnStart = typeof record.pruneOnStart === \"boolean\" ? record.pruneOnStart : undefined;\n\tif (retention === undefined && pruneOnStart === undefined) {\n\t\treturn undefined;\n\t}\n\treturn {\n\t\t...(retention === undefined ? {} : { retention }),\n\t\t...(pruneOnStart === undefined ? {} : { pruneOnStart }),\n\t};\n}\n\nexport function createEmptyVoltdState(): VoltdStateFileV1 {\n\treturn {\n\t\tversion: 1,\n\t\tirohSecretKey: undefined,\n\t\tclients: [],\n\t\trevokedClients: [],\n\t\tworkspaces: [],\n\t\tworktrees: [],\n\t\tpendingPairingTickets: [],\n\t\tpairingSecretTombstones: [],\n\t\tsettings: {\n\t\t\tdetachedRuntimeTtlMs: DEFAULT_INTEGRATED_DETACHED_RUNTIME_TTL_MS,\n\t\t\tallowTools: null,\n\t\t},\n\t};\n}\n\nexport function voltdStateToHostState(state: VoltdStateFileV1): IrohRemoteHostState {\n\treturn {\n\t\thostSecretKey: state.irohSecretKey,\n\t\tclients: state.clients,\n\t\trevokedClients: state.revokedClients,\n\t\tworkspaces: state.workspaces,\n\t\tworktrees: state.worktrees,\n\t\tpendingPairingTickets: state.pendingPairingTickets,\n\t\tpairingSecretTombstones: state.pairingSecretTombstones,\n\t};\n}\n\nexport function hostStateToVoltdState(\n\thostState: IrohRemoteHostState,\n\tsettings: VoltdStateFileV1[\"settings\"],\n): VoltdStateFileV1 {\n\treturn {\n\t\tversion: 1,\n\t\tirohSecretKey: hostState.hostSecretKey,\n\t\tclients: hostState.clients,\n\t\trevokedClients: hostState.revokedClients ?? [],\n\t\tworkspaces: hostState.workspaces,\n\t\tworktrees: hostState.worktrees ?? [],\n\t\tpendingPairingTickets: hostState.pendingPairingTickets ?? [],\n\t\tpairingSecretTombstones: hostState.pairingSecretTombstones ?? [],\n\t\tsettings,\n\t};\n}\n\nexport function parseVoltdState(value: unknown): VoltdStateFileV1 {\n\tif (typeof value !== \"object\" || value === null || Array.isArray(value)) {\n\t\tthrow new Error(\"voltd state must be an object\");\n\t}\n\tconst record = value as Record<string, unknown>;\n\tif (record.version !== 1) {\n\t\tthrow new Error(`unsupported voltd state version: ${String(record.version)}`);\n\t}\n\tconst hostState = parseIrohRemoteHostState({\n\t\t...record,\n\t\thostSecretKey: record.irohSecretKey,\n\t});\n\tconst settings = typeof record.settings === \"object\" && record.settings !== null ? record.settings : {};\n\tconst settingsRecord = settings as Record<string, unknown>;\n\tconst detachedRuntimeTtlMs =\n\t\ttypeof settingsRecord.detachedRuntimeTtlMs === \"number\" &&\n\t\tNumber.isInteger(settingsRecord.detachedRuntimeTtlMs) &&\n\t\tsettingsRecord.detachedRuntimeTtlMs > 0\n\t\t\t? settingsRecord.detachedRuntimeTtlMs\n\t\t\t: DEFAULT_INTEGRATED_DETACHED_RUNTIME_TTL_MS;\n\tconst allowTools = Array.isArray(settingsRecord.allowTools)\n\t\t? settingsRecord.allowTools.filter((tool): tool is string => typeof tool === \"string\")\n\t\t: null;\n\tconst themeName = typeof settingsRecord.themeName === \"string\" ? settingsRecord.themeName : undefined;\n\tconst themeTokenPush = settingsRecord.themeTokenPush === true;\n\tconst keepAwakeEnabled = settingsRecord.keepAwakeEnabled === true;\n\tconst relayAuthToken =\n\t\ttypeof settingsRecord.relayAuthToken === \"string\" && settingsRecord.relayAuthToken.length > 0\n\t\t\t? settingsRecord.relayAuthToken\n\t\t\t: undefined;\n\tconst worktreeCleanup = parseWorktreeCleanupSettings(settingsRecord.worktreeCleanup);\n\treturn hostStateToVoltdState(hostState, {\n\t\tdetachedRuntimeTtlMs,\n\t\tallowTools,\n\t\t...(themeName === undefined ? {} : { themeName }),\n\t\t...(themeTokenPush ? { themeTokenPush } : {}),\n\t\t...(keepAwakeEnabled ? { keepAwakeEnabled } : {}),\n\t\t...(relayAuthToken === undefined ? {} : { relayAuthToken }),\n\t\t...(worktreeCleanup === undefined ? {} : { worktreeCleanup }),\n\t});\n}\n\nexport function getLegacyRemoteStatePath(agentDir: string): string {\n\treturn join(agentDir, \"remote\", \"iroh-host.json\");\n}\n\nexport interface LegacyRemoteStateMigration {\n\tstate: VoltdStateFileV1;\n\tdroppedAccess: {\n\t\tclients: number;\n\t\trevokedClients: number;\n\t\tpendingPairingTickets: number;\n\t};\n}\n\n/**\n * One-time migration from remote/iroh-host.json. A pre-grant file keeps the\n * Iroh identity plus validated workspace/worktree metadata, but deliberately\n * drops every old authority-bearing record. Those clients must pair again\n * under an explicit RPC grant; expected pre-grant migration is not corruption.\n */\nexport function migrateLegacyRemoteState(agentDir: string, statePath: string): LegacyRemoteStateMigration | null {\n\tif (existsSync(statePath)) {\n\t\treturn null;\n\t}\n\tconst legacyPath = getLegacyRemoteStatePath(agentDir);\n\tif (!existsSync(legacyPath)) {\n\t\treturn null;\n\t}\n\tconst parsedJson: unknown = JSON.parse(readFileSync(legacyPath, \"utf8\"));\n\tlet legacyState: IrohRemoteHostState;\n\tlet droppedAccess = { clients: 0, revokedClients: 0, pendingPairingTickets: 0 };\n\ttry {\n\t\tlegacyState = parseIrohRemoteHostState(parsedJson);\n\t} catch (error) {\n\t\tif (!isPreGrantLegacyHostState(parsedJson)) {\n\t\t\tthrow error;\n\t\t}\n\t\tconst record = parsedJson as Record<string, unknown>;\n\t\tdroppedAccess = {\n\t\t\tclients: Array.isArray(record.clients) ? record.clients.length : 0,\n\t\t\trevokedClients: Array.isArray(record.revokedClients) ? record.revokedClients.length : 0,\n\t\t\tpendingPairingTickets: Array.isArray(record.pendingPairingTickets) ? record.pendingPairingTickets.length : 0,\n\t\t};\n\t\tlegacyState = parseIrohRemoteHostState({\n\t\t\t...record,\n\t\t\tclients: [],\n\t\t\trevokedClients: [],\n\t\t\tpendingPairingTickets: [],\n\t\t});\n\t}\n\treturn {\n\t\tstate: hostStateToVoltdState(legacyState, createEmptyVoltdState().settings),\n\t\tdroppedAccess,\n\t};\n}\n\nfunction isPreGrantLegacyHostState(value: unknown): value is Record<string, unknown> {\n\tif (typeof value !== \"object\" || value === null || Array.isArray(value)) {\n\t\treturn false;\n\t}\n\tconst record = value as Record<string, unknown>;\n\tfor (const field of [\"clients\", \"revokedClients\", \"pendingPairingTickets\"] as const) {\n\t\tconst entries = record[field];\n\t\tif (!Array.isArray(entries)) {\n\t\t\tcontinue;\n\t\t}\n\t\tif (\n\t\t\tentries.some(\n\t\t\t\t(entry) => typeof entry === \"object\" && entry !== null && !Array.isArray(entry) && !(\"rpcGrant\" in entry),\n\t\t\t)\n\t\t) {\n\t\t\treturn true;\n\t\t}\n\t}\n\treturn false;\n}\n\nexport interface VoltdStateStoreOptions {\n\tagentDir: string;\n\tstatePath: string;\n\t/** Debounce for coalescing writes; flushes synchronously on close(). */\n\tdebounceMs?: number;\n\t/** Durable writer seam for deterministic persistence-concurrency tests. */\n\twriteStateFile?: (path: string, content: string) => Promise<void>;\n}\n\nexport interface LoadVoltdStateResult {\n\tstate: VoltdStateFileV1;\n\tmigratedFromLegacyState: boolean;\n\tlegacyDroppedAccess?: LegacyRemoteStateMigration[\"droppedAccess\"];\n}\n\nconst DEFAULT_STATE_DEBOUNCE_MS = 250;\n\nexport interface InvalidVoltdStateFile {\n\tpath: string;\n\terror: string;\n}\n\nfunction stateFileErrorMessage(path: string, error: unknown): string {\n\tconst reason = error instanceof Error ? error.message : String(error);\n\treturn `Daemon state file ${path} is invalid or incompatible: ${reason}`;\n}\n\nfunction invalidStateFileError(path: string, error: unknown): Error {\n\treturn new Error(\n\t\t`${stateFileErrorMessage(path, error)}. Confirm regeneration from /remote or run ` +\n\t\t\t\"`volt daemon regenerate-state`; existing phones will need to pair again.\",\n\t);\n}\n\n/** Inspect persisted daemon state without modifying or migrating it. */\nexport function inspectVoltdStateFiles(agentDir: string): InvalidVoltdStateFile | undefined {\n\tconst statePath = join(agentDir, \"daemon\", \"state.json\");\n\tif (existsSync(statePath)) {\n\t\ttry {\n\t\t\tparseVoltdState(JSON.parse(readFileSync(statePath, \"utf8\")));\n\t\t\treturn undefined;\n\t\t} catch (error) {\n\t\t\treturn { path: statePath, error: stateFileErrorMessage(statePath, error) };\n\t\t}\n\t}\n\tconst legacyPath = getLegacyRemoteStatePath(agentDir);\n\tif (!existsSync(legacyPath)) {\n\t\treturn undefined;\n\t}\n\ttry {\n\t\tmigrateLegacyRemoteState(agentDir, statePath);\n\t\treturn undefined;\n\t} catch (error) {\n\t\treturn { path: legacyPath, error: stateFileErrorMessage(legacyPath, error) };\n\t}\n}\n\nfunction regeneratePreGrantVoltdState(value: unknown): VoltdStateFileV1 | undefined {\n\tif (!isPreGrantLegacyHostState(value)) {\n\t\treturn undefined;\n\t}\n\tconst record = value as Record<string, unknown>;\n\ttry {\n\t\treturn parseVoltdState({\n\t\t\t...record,\n\t\t\tclients: [],\n\t\t\trevokedClients: [],\n\t\t\tpendingPairingTickets: [],\n\t\t});\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\nfunction readRecoverableVoltdState(path: string): VoltdStateFileV1 | undefined {\n\ttry {\n\t\tconst value: unknown = JSON.parse(readFileSync(path, \"utf8\"));\n\t\ttry {\n\t\t\treturn parseVoltdState(value);\n\t\t} catch {\n\t\t\treturn regeneratePreGrantVoltdState(value);\n\t\t}\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\nexport interface RecoverableVoltdStateBackup {\n\tpath: string;\n\tpreservedIdentity: boolean;\n}\n\n/** Find the newest validated daemon-state backup that can be safely regenerated. */\nexport function findRecoverableVoltdStateBackup(agentDir: string): RecoverableVoltdStateBackup | undefined {\n\tconst daemonDir = join(agentDir, \"daemon\");\n\tif (!existsSync(daemonDir)) {\n\t\treturn undefined;\n\t}\n\tconst candidates = readdirSync(daemonDir)\n\t\t.filter((name) => /^state\\.json\\.(?:corrupt|invalid)-\\d+$/.test(name))\n\t\t.map((name) => {\n\t\t\tconst path = join(daemonDir, name);\n\t\t\treturn { path, modifiedAtMs: statSync(path).mtimeMs, state: readRecoverableVoltdState(path) };\n\t\t})\n\t\t.filter((candidate): candidate is typeof candidate & { state: VoltdStateFileV1 } => candidate.state !== undefined)\n\t\t.sort((left, right) => right.modifiedAtMs - left.modifiedAtMs);\n\tconst candidate = candidates[0];\n\treturn candidate\n\t\t? { path: candidate.path, preservedIdentity: candidate.state.irohSecretKey !== undefined }\n\t\t: undefined;\n}\n\n/** Replace current state from a validated backup, preserving the source and backing up the current file. */\nexport async function recoverVoltdStateFromBackup(\n\tagentDir: string,\n\tbackupPath: string,\n): Promise<{ previousStateBackupPath?: string; preservedIdentity: boolean }> {\n\tconst candidate = findRecoverableVoltdStateBackup(agentDir);\n\tif (!candidate || candidate.path !== backupPath) {\n\t\tthrow new Error(\"The selected daemon-state recovery backup is no longer available.\");\n\t}\n\tconst recovered = readRecoverableVoltdState(backupPath);\n\tif (!recovered) {\n\t\tthrow new Error(\"The selected daemon-state backup is no longer recoverable.\");\n\t}\n\tconst statePath = join(agentDir, \"daemon\", \"state.json\");\n\tlet previousStateBackupPath: string | undefined;\n\tif (existsSync(statePath)) {\n\t\tpreviousStateBackupPath = `${statePath}.invalid-${Date.now()}`;\n\t\tawait rename(statePath, previousStateBackupPath);\n\t}\n\tawait writeDurableAtomicFile(statePath, `${JSON.stringify(recovered, null, 2)}\\n`);\n\treturn {\n\t\t...(previousStateBackupPath === undefined ? {} : { previousStateBackupPath }),\n\t\tpreservedIdentity: recovered.irohSecretKey !== undefined,\n\t};\n}\n\n/** Back up invalid state and regenerate validated non-authority data when possible. */\nexport async function regenerateInvalidVoltdState(\n\tagentDir: string,\n): Promise<{ backupPath: string; preservedIdentity: boolean }> {\n\tconst invalid = inspectVoltdStateFiles(agentDir);\n\tif (!invalid) {\n\t\tthrow new Error(\"Daemon state is valid; regeneration is not needed.\");\n\t}\n\tlet regenerated: VoltdStateFileV1 | undefined;\n\tif (invalid.path === join(agentDir, \"daemon\", \"state.json\")) {\n\t\ttry {\n\t\t\tregenerated = regeneratePreGrantVoltdState(JSON.parse(readFileSync(invalid.path, \"utf8\")));\n\t\t} catch {\n\t\t\t// Malformed JSON cannot be partially recovered. The original is still backed up below.\n\t\t}\n\t}\n\tconst backupPath = `${invalid.path}.invalid-${Date.now()}`;\n\tawait rename(invalid.path, backupPath);\n\tif (regenerated) {\n\t\tawait writeDurableAtomicFile(invalid.path, `${JSON.stringify(regenerated, null, 2)}\\n`);\n\t}\n\treturn { backupPath, preservedIdentity: regenerated?.irohSecretKey !== undefined };\n}\n\n/** Debounced, atomic (tmp + rename, 0600) persistence for VoltdStateFileV1. */\nexport class VoltdStateStore {\n\tprivate readonly statePath: string;\n\tprivate readonly agentDir: string;\n\tprivate readonly debounceMs: number;\n\tprivate readonly writeStateFile: (path: string, content: string) => Promise<void>;\n\tprivate current: VoltdStateFileV1 | undefined;\n\tprivate flushTimer: NodeJS.Timeout | undefined;\n\tprivate pendingFlush: Promise<void> = Promise.resolve();\n\tprivate stateRevision = 0;\n\tprivate persistedRevision = 0;\n\tprivate migrated = false;\n\tprivate legacyDroppedAccess: LegacyRemoteStateMigration[\"droppedAccess\"] | undefined;\n\n\tconstructor(options: VoltdStateStoreOptions) {\n\t\tthis.statePath = options.statePath;\n\t\tthis.agentDir = options.agentDir;\n\t\tthis.debounceMs = options.debounceMs ?? DEFAULT_STATE_DEBOUNCE_MS;\n\t\tthis.writeStateFile = options.writeStateFile ?? writeDurableAtomicFile;\n\t}\n\n\tasync load(): Promise<LoadVoltdStateResult> {\n\t\tif (this.current) {\n\t\t\treturn {\n\t\t\t\tstate: this.current,\n\t\t\t\tmigratedFromLegacyState: this.migrated,\n\t\t\t\t...(this.legacyDroppedAccess === undefined ? {} : { legacyDroppedAccess: this.legacyDroppedAccess }),\n\t\t\t};\n\t\t}\n\t\tlet migration: LegacyRemoteStateMigration | null;\n\t\ttry {\n\t\t\tmigration = migrateLegacyRemoteState(this.agentDir, this.statePath);\n\t\t} catch (error) {\n\t\t\tthrow invalidStateFileError(getLegacyRemoteStatePath(this.agentDir), error);\n\t\t}\n\t\tif (migration) {\n\t\t\tthis.current = migration.state;\n\t\t\tthis.markStateChanged();\n\t\t\tthis.migrated = true;\n\t\t\tthis.legacyDroppedAccess = migration.droppedAccess;\n\t\t\tawait this.enqueueWrite();\n\t\t\tconst legacyPath = getLegacyRemoteStatePath(this.agentDir);\n\t\t\ttry {\n\t\t\t\tawait rename(legacyPath, `${legacyPath}.migrated`);\n\t\t\t} catch (error) {\n\t\t\t\t// A daemon started concurrently (before the single-instance socket bind)\n\t\t\t\t// may have already migrated and renamed the legacy file. Its absence is\n\t\t\t\t// benign: the migrated content is identical and already persisted, so a\n\t\t\t\t// racing start must not crash here — it will fail cleanly at the socket\n\t\t\t\t// bind instead.\n\t\t\t\tif ((error as NodeJS.ErrnoException).code !== \"ENOENT\") {\n\t\t\t\t\tthrow error;\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn {\n\t\t\t\tstate: this.current,\n\t\t\t\tmigratedFromLegacyState: true,\n\t\t\t\tlegacyDroppedAccess: migration.droppedAccess,\n\t\t\t};\n\t\t}\n\t\tif (existsSync(this.statePath)) {\n\t\t\ttry {\n\t\t\t\tthis.current = parseVoltdState(JSON.parse(readFileSync(this.statePath, \"utf8\")));\n\t\t\t} catch (error) {\n\t\t\t\tthrow invalidStateFileError(this.statePath, error);\n\t\t\t}\n\t\t} else {\n\t\t\tthis.current = createEmptyVoltdState();\n\t\t\tthis.markStateChanged();\n\t\t\tawait this.enqueueWrite();\n\t\t}\n\t\treturn { state: this.current, migratedFromLegacyState: false };\n\t}\n\n\tget state(): VoltdStateFileV1 {\n\t\tif (!this.current) {\n\t\t\tthrow new Error(\"voltd state not loaded\");\n\t\t}\n\t\treturn this.current;\n\t}\n\n\t/** Replace the host-state portion (used as the state-manager write hook). */\n\tsetHostState(hostState: IrohRemoteHostState): void {\n\t\tthis.current = hostStateToVoltdState(hostState, this.state.settings);\n\t\tthis.scheduleFlush();\n\t}\n\n\tgetHostState(): IrohRemoteHostState {\n\t\treturn this.current ? voltdStateToHostState(this.current) : createEmptyIrohRemoteHostState();\n\t}\n\n\tupdateSettings(settings: Partial<VoltdStateFileV1[\"settings\"]>): void {\n\t\tthis.current = { ...this.state, settings: { ...this.state.settings, ...settings } };\n\t\tthis.scheduleFlush();\n\t}\n\n\tscheduleFlush(): void {\n\t\tthis.markStateChanged();\n\t\tif (this.flushTimer) {\n\t\t\treturn;\n\t\t}\n\t\tthis.flushTimer = setTimeout(() => {\n\t\t\tthis.flushTimer = undefined;\n\t\t\tvoid this.enqueueWrite().catch(() => {});\n\t\t}, this.debounceMs);\n\t\tthis.flushTimer.unref?.();\n\t}\n\n\t/**\n\t * Force an immediate durable write, cancelling any pending debounce. Use after\n\t * minting state that must survive a crash the moment it exists (e.g. the freshly\n\t * generated Iroh identity, before the endpoint starts accepting pairings).\n\t */\n\tasync flush(): Promise<void> {\n\t\tif (this.flushTimer) {\n\t\t\tclearTimeout(this.flushTimer);\n\t\t\tthis.flushTimer = undefined;\n\t\t}\n\t\tif (this.current) {\n\t\t\t// Force an explicit current-snapshot revision. Besides preserving flush's\n\t\t\t// historical semantics, this catches callers that deliberately mutate the\n\t\t\t// loaded state object before requesting durability.\n\t\t\tthis.markStateChanged();\n\t\t\tawait this.enqueueWrite();\n\t\t} else {\n\t\t\tawait this.pendingFlush;\n\t\t}\n\t}\n\n\t/** Flush pending changes and stop the debounce timer (graceful shutdown). */\n\tasync close(): Promise<void> {\n\t\tawait this.flush();\n\t}\n\n\tprivate markStateChanged(): void {\n\t\tthis.stateRevision++;\n\t}\n\n\tprivate enqueueWrite(): Promise<void> {\n\t\tconst write = this.pendingFlush.then(() => this.writeNow());\n\t\tthis.pendingFlush = write.catch(() => {});\n\t\treturn write;\n\t}\n\n\t/** Must only be invoked through enqueueWrite so atomic renames cannot overtake one another. */\n\tprivate async writeNow(): Promise<void> {\n\t\tif (!this.current || this.persistedRevision >= this.stateRevision) {\n\t\t\treturn;\n\t\t}\n\t\tconst revision = this.stateRevision;\n\t\tconst content = `${JSON.stringify(this.current, null, 2)}\\n`;\n\t\tawait this.writeStateFile(this.statePath, content);\n\t\tthis.persistedRevision = Math.max(this.persistedRevision, revision);\n\t}\n}\n"]}