@elpapi42/pi-fleet 0.1.0-beta.1 → 0.1.0-beta.13

package/dist/installer.mjs

@@ -1,28 +1,252 @@
 // src/entry/installer.ts
 import { execFile } from "node:child_process";
-import { dirname as dirname2, join as join5 } from "node:path";
+import { dirname as dirname3, join as join6 } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { promisify } from "node:util";
 
-// src/platform/install/service-installer.ts
+// src/pi/external-installation.ts
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
 import { constants } from "node:fs";
-import { access, chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { createReadStream } from "node:fs";
+import { access, realpath, stat } from "node:fs/promises";
+import { delimiter, dirname, isAbsolute, join } from "node:path";
+var VERSION_TIMEOUT_MS = 3e3;
+var MAX_VERSION_OUTPUT_BYTES = 4 * 1024;
+var ExternalPiResolutionError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "ExternalPiResolutionError";
+  }
+};
+async function resolveExternalPiInstallation(options = {}) {
+  const env = options.env ?? process.env;
+  const selectedPath = await resolveSelectedPath(env);
+  const nodePath = options.nodePath ?? await resolveNodePath(env);
+  await inspectNode(nodePath);
+  const executionEnv = externalPiExecutionEnvironment(env, selectedPath, nodePath);
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    const observation = await observeInstallation(selectedPath, executionEnv, options);
+    if (observation !== null) {
+      return {
+        selectedPath,
+        nodePath,
+        ...observation
+      };
+    }
+  }
+  throw new ExternalPiResolutionError(
+    "pi_installation_changed",
+    "Pi changed while its installation was being observed."
+  );
+}
+function externalPiExecutionEnvironment(env, selectedPath, nodePath) {
+  return {
+    ...env,
+    PATH: [dirname(nodePath), dirname(selectedPath), env.PATH].filter((value) => value !== void 0 && value.length > 0).join(delimiter)
+  };
+}
+async function observeInstallation(selectedPath, env, options) {
+  const beforeRealPath = await inspectExecutable(selectedPath, "Pi");
+  const beforeHash = await hashFile(beforeRealPath);
+  const versionOutput = await (options.versionCommand ?? ((executable) => readVersion(executable, env, options.versionTimeoutMs, options.maxVersionOutputBytes)))(selectedPath);
+  const version = parseVersion(versionOutput);
+  const afterRealPath = await inspectExecutable(selectedPath, "Pi");
+  const afterHash = await hashFile(afterRealPath);
+  if (beforeRealPath !== afterRealPath || beforeHash !== afterHash) return null;
+  return {
+    realPath: afterRealPath,
+    version,
+    fingerprint: createHash("sha256").update(JSON.stringify([selectedPath, afterRealPath, version, afterHash])).digest("hex")
+  };
+}
+async function resolveSelectedPath(env) {
+  const explicit = env.PIFLEET_PI_EXECUTABLE;
+  if (explicit !== void 0) {
+    if (!isAbsolute(explicit)) {
+      throw new ExternalPiResolutionError(
+        "invalid_arguments",
+        "PIFLEET_PI_EXECUTABLE must be an absolute path."
+      );
+    }
+    return explicit;
+  }
+  return resolvePathExecutable(env, "pi", "Pi", "pi_not_found");
+}
+async function resolveNodePath(env) {
+  return resolvePathExecutable(env, "node", "Node", "pi_not_executable");
+}
+async function resolvePathExecutable(env, name, label, missingCode) {
+  const path = env.PATH;
+  if (path === void 0 || path.length === 0) {
+    throw new ExternalPiResolutionError(missingCode, `${label} was not found on PATH.`);
+  }
+  for (const directory of path.split(delimiter)) {
+    if (!isAbsolute(directory)) {
+      throw new ExternalPiResolutionError(
+        "invalid_arguments",
+        `PATH entries used to select ${label} must be absolute paths.`
+      );
+    }
+    const candidate = join(directory, name);
+    try {
+      await inspectExecutable(candidate, label);
+      return candidate;
+    } catch (error) {
+      if (!(error instanceof ExternalPiResolutionError) || error.code !== "pi_not_executable" && error.code !== "pi_not_found") {
+        throw error;
+      }
+    }
+  }
+  throw new ExternalPiResolutionError(missingCode, `${label} was not found on PATH.`);
+}
+async function inspectExecutable(path, label) {
+  try {
+    const target = await realpath(path);
+    const metadata = await stat(target);
+    if (!metadata.isFile()) {
+      throw new ExternalPiResolutionError("pi_not_executable", `${label} is not a file: ${path}`);
+    }
+    await access(path, constants.X_OK);
+    return target;
+  } catch (error) {
+    if (error instanceof ExternalPiResolutionError) throw error;
+    if (error.code === "ENOENT") {
+      throw new ExternalPiResolutionError("pi_not_found", `${label} was not found: ${path}`);
+    }
+    throw new ExternalPiResolutionError("pi_not_executable", `${label} is not executable: ${path}`);
+  }
+}
+async function inspectNode(nodePath) {
+  if (!isAbsolute(nodePath)) {
+    throw new ExternalPiResolutionError("invalid_arguments", "Node must be an absolute path.");
+  }
+  try {
+    await inspectExecutable(nodePath, "Node");
+  } catch {
+    throw new ExternalPiResolutionError("pi_not_executable", `Node is not executable: ${nodePath}`);
+  }
+}
+async function hashFile(path) {
+  const hash = createHash("sha256");
+  await new Promise((resolveHash, rejectHash) => {
+    const stream = createReadStream(path);
+    stream.on("data", (chunk) => hash.update(chunk));
+    stream.once("error", rejectHash);
+    stream.once("end", resolveHash);
+  });
+  return hash.digest("hex");
+}
+async function readVersion(executable, env, timeoutMs = VERSION_TIMEOUT_MS, maxOutputBytes = MAX_VERSION_OUTPUT_BYTES) {
+  const child = spawn(executable, ["--version"], {
+    detached: process.platform !== "win32",
+    env,
+    shell: false,
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  const chunks = [];
+  let outputBytes = 0;
+  let terminalError = null;
+  let terminated = false;
+  const terminate = () => {
+    if (terminated) return;
+    terminated = true;
+    if (process.platform !== "win32" && child.pid !== void 0) {
+      try {
+        process.kill(-child.pid, "SIGKILL");
+        return;
+      } catch {
+      }
+    }
+    child.kill("SIGKILL");
+  };
+  child.stdout.on("data", (chunk) => {
+    if (terminalError !== null) return;
+    outputBytes += chunk.byteLength;
+    if (outputBytes > maxOutputBytes) {
+      terminalError = new ExternalPiResolutionError(
+        "pi_version_unavailable",
+        "Pi version output exceeded its limit."
+      );
+      terminate();
+      return;
+    }
+    chunks.push(chunk);
+  });
+  child.stderr.resume();
+  return new Promise((resolveVersion, rejectVersion) => {
+    const timer = setTimeout(() => {
+      terminalError = new ExternalPiResolutionError(
+        "pi_version_unavailable",
+        "Pi version command timed out."
+      );
+      terminate();
+    }, timeoutMs);
+    child.once("error", () => {
+      terminalError ??= new ExternalPiResolutionError(
+        "pi_version_unavailable",
+        "Pi version command failed."
+      );
+    });
+    child.once("close", (code) => {
+      clearTimeout(timer);
+      if (terminalError !== null) {
+        rejectVersion(terminalError);
+        return;
+      }
+      if (code !== 0) {
+        rejectVersion(
+          new ExternalPiResolutionError("pi_version_unavailable", "Pi version command failed.")
+        );
+        return;
+      }
+      try {
+        resolveVersion(new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks)));
+      } catch {
+        rejectVersion(
+          new ExternalPiResolutionError(
+            "pi_version_unavailable",
+            "Pi version command returned invalid UTF-8."
+          )
+        );
+      }
+    });
+  });
+}
+function parseVersion(output) {
+  const match = /^(?:pi\s+)?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)\s*$/i.exec(output);
+  if (match?.[1] === void 0) {
+    throw new ExternalPiResolutionError(
+      "pi_version_unavailable",
+      "Pi version command returned an invalid version."
+    );
+  }
+  return match[1];
+}
+
+// src/platform/install/service-installer.ts
+import { constants as constants2 } from "node:fs";
+import { access as access2, chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname as dirname2, join as join2 } from "node:path";
 
 // src/platform/install/service-definition.ts
-import { isAbsolute } from "node:path";
+import { isAbsolute as isAbsolute2 } from "node:path";
 function systemdUserUnit(options) {
   validate(options);
-  const environment = options.stateRoot === void 0 ? "" : `Environment=PIFLEET_STATE_ROOT=${systemdEscape(options.stateRoot)}
+  const environment = environmentEntries(options).map(([key, value]) => {
+    const assignment = `${key}=${value}`;
+    return `Environment=${/^[A-Za-z0-9_./:@=-]+$/.test(assignment) ? assignment : systemdQuote(assignment)}
 `;
+  }).join("");
   return `[Unit]
-Description=Pi Fleet user runtime
+Description=pi-fleet user runtime
 After=default.target
 
 [Service]
 Type=simple
-ExecStart=${systemdEscape(options.nodePath)} ${systemdEscape(options.runtimePath)}
+ExecStart=${systemdArgument(options.nodePath)} ${systemdArgument(options.runtimePath)}
 ${environment}Restart=on-failure
 RestartSec=1
 TimeoutStopSec=10
@@ -35,8 +259,9 @@ WantedBy=default.target
 }
 function launchdAgentPlist(options) {
   validate(options);
-  const environment = options.stateRoot === void 0 ? "" : `    <key>EnvironmentVariables</key>
-    <dict><key>PIFLEET_STATE_ROOT</key><string>${xmlEscape(options.stateRoot)}</string></dict>
+  const entries = environmentEntries(options);
+  const environment = entries.length === 0 ? "" : `    <key>EnvironmentVariables</key>
+    <dict>${entries.map(([key, value]) => `<key>${xmlEscape(key)}</key><string>${xmlEscape(value)}</string>`).join("")}</dict>
 `;
   return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
@@ -55,27 +280,62 @@ ${environment}    <key>RunAtLoad</key><true/>
 </plist>
 `;
 }
+function environmentEntries(options) {
+  return [
+    ...options.stateRoot === void 0 ? [] : [["PIFLEET_STATE_ROOT", options.stateRoot]],
+    ...options.piExecutablePath === void 0 ? [] : [["PIFLEET_PI_EXECUTABLE", options.piExecutablePath]],
+    ...options.piNodePath === void 0 ? [] : [["PIFLEET_PI_NODE", options.piNodePath]]
+  ];
+}
 function validate(options) {
-  if (!isAbsolute(options.nodePath) || !isAbsolute(options.runtimePath)) {
+  const paths = [
+    options.nodePath,
+    options.runtimePath,
+    options.piExecutablePath,
+    options.piNodePath
+  ].filter((value) => value !== void 0);
+  if (paths.some((path) => !isAbsolute2(path))) {
     throw new Error("Service executables must use absolute paths");
   }
+  if (paths.some((path) => /[\0\n\r]/.test(path))) {
+    throw new Error("Service paths cannot contain control characters");
+  }
+}
+function systemdArgument(value) {
+  return /^[A-Za-z0-9_./:@-]+$/.test(value) ? value : systemdQuote(value);
 }
-function systemdEscape(value) {
-  if (!/^[A-Za-z0-9_./:@-]+$/.test(value)) throw new Error(`Unsafe systemd path ${value}`);
-  return value;
+function systemdQuote(value) {
+  if (/[\0\n\r]/.test(value)) throw new Error("Unsafe systemd value");
+  return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
 }
 function xmlEscape(value) {
   return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
 }
 
 // src/platform/install/service-installer.ts
+var ServiceRepairDeferredError = class extends Error {
+  code = "runtime_upgrade_deferred";
+  constructor() {
+    super(
+      "The installed pi-fleet service differs from the requested runtime or Pi selection. Automatic replacement is deferred because runtime quiescence cannot be proven; finish active work, stop the existing service explicitly, then install or repair again."
+    );
+    this.name = "ServiceRepairDeferredError";
+  }
+};
 async function installUserService(options) {
   const home = options.home ?? homedir();
   if (options.platform === "linux") {
-    const path = join(home, ".config", "systemd", "user", "pi-fleet.service");
+    const path = join2(home, ".config", "systemd", "user", "pi-fleet.service");
     const effectiveDefinition = await preserveInstalledStateRoot(path, options.definition, "linux");
     const definition = systemdUserUnit(effectiveDefinition);
     const needsRepair = await serviceDefinitionNeedsRepair(path, definition, effectiveDefinition);
+    const installed = await exists(path);
+    await preflightInstalledReplacement({
+      installed,
+      needsRepair,
+      replaceExisting: options.replaceExisting,
+      ownershipPreflight: options.ownershipPreflight
+    });
     if (needsRepair) {
       await atomicWrite(path, definition);
       await options.executor.run("systemctl", ["--user", "daemon-reload"]);
@@ -87,38 +347,47 @@ async function installUserService(options) {
     return path;
   }
   if (options.platform === "darwin") {
-    const path = join(home, "Library", "LaunchAgents", "works.elpapi.pifleet.plist");
+    const path = join2(home, "Library", "LaunchAgents", "works.elpapi.pifleet.plist");
     const effectiveDefinition = await preserveInstalledStateRoot(
       path,
       options.definition,
       "darwin"
     );
-    await atomicWrite(path, launchdAgentPlist(effectiveDefinition));
+    const definition = launchdAgentPlist(effectiveDefinition);
+    const needsRepair = await serviceDefinitionNeedsRepair(path, definition, effectiveDefinition);
+    const installed = await exists(path);
+    await preflightInstalledReplacement({
+      installed,
+      needsRepair,
+      replaceExisting: options.replaceExisting,
+      ownershipPreflight: options.ownershipPreflight
+    });
+    if (needsRepair) await atomicWrite(path, definition);
     const domain = `gui/${options.uid ?? process.getuid?.() ?? 0}`;
     await options.executor.run("launchctl", ["bootout", domain, path]).catch(() => void 0);
     await options.executor.run("launchctl", ["bootstrap", domain, path]);
     await options.executor.run("launchctl", ["kickstart", `${domain}/works.elpapi.pifleet`]);
     return path;
   }
-  throw new Error(`Native Pi Fleet supervision is unsupported on ${options.platform}`);
+  throw new Error(`Native pi-fleet supervision is unsupported on ${options.platform}`);
 }
 async function uninstallUserService(options) {
   const home = options.home ?? homedir();
   if (options.platform === "linux") {
-    const path = join(home, ".config", "systemd", "user", "pi-fleet.service");
+    const path = join2(home, ".config", "systemd", "user", "pi-fleet.service");
     await options.executor.run("systemctl", ["--user", "disable", "--now", "pi-fleet.service"]);
     await rm(path, { force: true });
     await options.executor.run("systemctl", ["--user", "daemon-reload"]);
     return;
   }
   if (options.platform === "darwin") {
-    const path = join(home, "Library", "LaunchAgents", "works.elpapi.pifleet.plist");
+    const path = join2(home, "Library", "LaunchAgents", "works.elpapi.pifleet.plist");
     const domain = `gui/${options.uid ?? process.getuid?.() ?? 0}`;
     await options.executor.run("launchctl", ["bootout", domain, path]).catch(() => void 0);
     await rm(path, { force: true });
     return;
   }
-  throw new Error(`Native Pi Fleet supervision is unsupported on ${options.platform}`);
+  throw new Error(`Native pi-fleet supervision is unsupported on ${options.platform}`);
 }
 async function serviceDefinitionNeedsRepair(path, expectedContents, definition) {
   const current = await readFile(path, "utf8").catch((error) => {
@@ -127,13 +396,20 @@ async function serviceDefinitionNeedsRepair(path, expectedContents, definition)
   });
   if (current !== expectedContents) return true;
   try {
-    await access(definition.nodePath, constants.X_OK);
-    await access(definition.runtimePath, constants.R_OK);
+    await access2(definition.nodePath, constants2.X_OK);
+    await access2(definition.runtimePath, constants2.R_OK);
     return false;
   } catch {
     return true;
   }
 }
+async function preflightInstalledReplacement(options) {
+  if (!options.installed || !options.needsRepair) return;
+  if (options.replaceExisting !== true || options.ownershipPreflight === void 0) {
+    throw new ServiceRepairDeferredError();
+  }
+  await options.ownershipPreflight();
+}
 async function preserveInstalledStateRoot(path, definition, platform) {
   if (definition.stateRoot !== void 0) return definition;
   const current = await readFile(path, "utf8").catch((error) => {
@@ -146,8 +422,16 @@ async function preserveInstalledStateRoot(path, definition, platform) {
   const stateRoot = platform === "linux" ? encoded : encoded.replaceAll("&apos;", "'").replaceAll("&quot;", '"').replaceAll("&gt;", ">").replaceAll("&lt;", "<").replaceAll("&amp;", "&");
   return { ...definition, stateRoot };
 }
+async function exists(path) {
+  try {
+    await access2(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
 async function atomicWrite(path, contents) {
-  await mkdir(dirname(path), { recursive: true, mode: 448 });
+  await mkdir(dirname2(path), { recursive: true, mode: 448 });
   const temporary = `${path}.tmp-${process.pid}`;
   await writeFile(temporary, contents, { mode: 384 });
   await chmod(temporary, 384);
@@ -155,18 +439,18 @@ async function atomicWrite(path, contents) {
 }
 
 // src/platform/install/runtime-release.ts
-import { createHash as createHash2, randomUUID } from "node:crypto";
-import { chmod as chmod2, cp, lstat as lstat2, mkdir as mkdir2, readFile as readFile3, rename as rename2, rm as rm2, stat as stat2 } from "node:fs/promises";
-import { join as join3, resolve as resolve2, sep as sep2 } from "node:path";
+import { createHash as createHash3, randomUUID } from "node:crypto";
+import { chmod as chmod2, cp, lstat as lstat2, mkdir as mkdir2, readFile as readFile3, rename as rename2, rm as rm2, writeFile as writeFile2 } from "node:fs/promises";
+import { join as join4, posix, resolve as resolve2, sep as sep2 } from "node:path";
 
 // src/platform/install/tree-integrity.ts
-import { createHash } from "node:crypto";
-import { lstat, readFile as readFile2, readdir, stat } from "node:fs/promises";
-import { join as join2, relative, resolve, sep } from "node:path";
+import { createHash as createHash2 } from "node:crypto";
+import { lstat, readFile as readFile2, readdir, realpath as realpath2, stat as stat2 } from "node:fs/promises";
+import { join as join3, relative, resolve, sep } from "node:path";
 async function hashDirectoryTree(root, manifestPath) {
   const resolvedRoot = resolve(root);
   const entries = await collectFiles(resolvedRoot, resolvedRoot);
-  const hash = createHash("sha256");
+  const hash = createHash2("sha256");
   let bytes = 0;
   for (const entry of entries) {
     const contents = await readFile2(entry.absolutePath);
@@ -188,9 +472,9 @@ async function hashDirectoryTree(root, manifestPath) {
 async function collectFiles(root, directory) {
   const output = [];
   for (const name of (await readdir(directory)).sort()) {
-    const absolutePath = join2(directory, name);
+    const absolutePath = join3(directory, name);
     const linkInfo = await lstat(absolutePath);
-    const info = linkInfo.isSymbolicLink() ? await stat(absolutePath) : linkInfo;
+    const info = linkInfo.isSymbolicLink() ? await stat2(absolutePath) : linkInfo;
     if (info.isDirectory()) {
       if (linkInfo.isSymbolicLink()) {
         throw new Error(`Runtime dependency tree contains a directory symlink: ${absolutePath}`);
@@ -201,6 +485,14 @@ async function collectFiles(root, directory) {
     if (!info.isFile()) {
       throw new Error(`Runtime dependency tree contains an unsupported entry: ${absolutePath}`);
     }
+    if (linkInfo.isSymbolicLink()) {
+      const target = await realpath2(absolutePath);
+      if (target !== root && !target.startsWith(`${root}${sep}`)) {
+        throw new Error(
+          `Runtime dependency tree contains an external file symlink: ${absolutePath}`
+        );
+      }
+    }
     const relativePath = relative(root, absolutePath).split(sep).join("/");
     if (relativePath.length === 0 || relativePath.startsWith("../")) {
       throw new Error(`Runtime dependency path escapes its root: ${absolutePath}`);
@@ -211,75 +503,296 @@ async function collectFiles(root, directory) {
 }
 
 // src/platform/install/runtime-release.ts
+var requiredRuntimeArtifacts = /* @__PURE__ */ new Set([
+  "package.json",
+  "bin/pifleet.mjs",
+  "bin/pifleet-runtime.mjs",
+  "dist/cli.mjs",
+  "dist/runtime.mjs",
+  "dist/journal-sqlite-worker.mjs",
+  "dist/client.mjs",
+  "dist/client-meta.json",
+  "dist/client/index.d.ts",
+  "dist/client/sdk-facade.d.ts",
+  "dist/client/contracts.d.ts"
+]);
+var dependencyTreePath = "node_modules";
 async function materializeRuntime(options) {
   const sourceRoot = resolve2(options.sourceRoot);
+  const manifestBytes = await readFile3(join4(sourceRoot, "dist", "runtime-manifest.json"));
+  const sourceManifest = await parseRuntimeManifest(manifestBytes, sourceRoot);
+  if (sourceManifest.closure !== void 0) {
+    await verifyRuntime(sourceRoot);
+    return sourceRoot;
+  }
+  await verifyRuntimeFiles(sourceRoot, sourceManifest);
+  await verifyDependencyIdentities(sourceRoot, sourceManifest.dependencies);
+  const sourceTreeRoot = resolveInside(sourceRoot, dependencyTreePath);
+  const sourceTreeBefore = await hashDirectoryTree(sourceTreeRoot, dependencyTreePath);
+  const sourceManifestSha256 = createHash3("sha256").update(manifestBytes).digest("hex");
+  const materializedManifest = {
+    ...sourceManifest,
+    closure: { sourceManifestSha256, tree: sourceTreeBefore }
+  };
+  const materializedManifestBytes = serializeManifest(materializedManifest);
+  const closureHash = createHash3("sha256").update(sourceManifestSha256).update("\0").update(JSON.stringify(sourceTreeBefore)).digest("hex").slice(0, 16);
   const applicationRoot = resolve2(options.applicationRoot);
   await ensurePrivateDirectory(applicationRoot);
-  const manifestBytes = await readFile3(join3(sourceRoot, "dist", "runtime-manifest.json"));
-  const manifest = JSON.parse(manifestBytes.toString("utf8"));
-  const manifestHash = createHash2("sha256").update(manifestBytes).digest("hex").slice(0, 16);
-  const releasesRoot = join3(applicationRoot, "releases");
+  const releasesRoot = join4(applicationRoot, "releases");
   await ensurePrivateDirectory(releasesRoot);
-  const destination = join3(releasesRoot, `${manifest.package.version}-${manifestHash}`);
+  const destination = join4(releasesRoot, `${sourceManifest.package.version}-${closureHash}`);
   if (await pathExists(destination)) {
-    await verifyRuntime(destination, manifest);
+    await verifyExpectedRuntime(destination, materializedManifest, materializedManifestBytes);
     return destination;
   }
-  const staging = join3(releasesRoot, `.staging-${randomUUID()}`);
+  const staging = join4(releasesRoot, `.staging-${randomUUID()}`);
   await mkdir2(staging, { mode: 448 });
   try {
-    await cp(join3(sourceRoot, "dist"), join3(staging, "dist"), {
+    await cp(join4(sourceRoot, "dist"), join4(staging, "dist"), {
       recursive: true,
       dereference: true
     });
-    await cp(join3(sourceRoot, "bin"), join3(staging, "bin"), { recursive: true, dereference: true });
-    await cp(join3(sourceRoot, "package.json"), join3(staging, "package.json"));
-    for (const tree of manifest.trees) {
-      const source = resolveInside(sourceRoot, tree.path);
-      const destination2 = resolveInside(staging, tree.path);
-      await mkdir2(resolve2(destination2, ".."), { recursive: true, mode: 448 });
-      await cp(source, destination2, { recursive: true, dereference: true });
-    }
-    await verifyRuntime(staging, manifest);
+    await cp(join4(sourceRoot, "bin"), join4(staging, "bin"), {
+      recursive: true,
+      dereference: true
+    });
+    await cp(join4(sourceRoot, "package.json"), join4(staging, "package.json"));
+    await cp(sourceTreeRoot, join4(staging, dependencyTreePath), {
+      recursive: true,
+      dereference: true
+    });
+    await options.hooks?.afterDependencyCopy?.();
+    const stagedTree = await hashDirectoryTree(
+      join4(staging, dependencyTreePath),
+      dependencyTreePath
+    );
+    assertSameTree(sourceTreeBefore, stagedTree, "copied dependency closure");
+    const sourceTreeAfter = await hashDirectoryTree(sourceTreeRoot, dependencyTreePath);
+    assertSameTree(sourceTreeBefore, sourceTreeAfter, "source dependency closure");
+    await writeFile2(join4(staging, "dist", "runtime-manifest.json"), materializedManifestBytes);
+    await verifyExpectedRuntime(staging, materializedManifest, materializedManifestBytes);
     await chmod2(staging, 448);
-    await rename2(staging, destination);
+    try {
+      await rename2(staging, destination);
+    } catch (error) {
+      if (!isDestinationRace(error) || !await pathExists(destination)) throw error;
+      await verifyExpectedRuntime(destination, materializedManifest, materializedManifestBytes);
+    }
     return destination;
-  } catch (error) {
+  } finally {
     await rm2(staging, { recursive: true, force: true });
-    throw error;
   }
 }
-async function verifyRuntime(root, manifest) {
-  const expected = manifest ?? JSON.parse(
-    await readFile3(join3(root, "dist", "runtime-manifest.json"), "utf8")
-  );
+async function verifyRuntime(root) {
   const resolvedRoot = resolve2(root);
-  for (const file of expected.files) {
-    const path = resolveInside(resolvedRoot, file.path);
-    const info = await stat2(path);
+  const manifestBytes = await readFile3(join4(resolvedRoot, "dist", "runtime-manifest.json"));
+  const manifest = await parseRuntimeManifest(manifestBytes, resolvedRoot);
+  if (manifest.closure === void 0) {
+    throw new Error("Runtime release manifest is missing its materialized closure");
+  }
+  await verifyRuntimeFiles(resolvedRoot, manifest);
+  await verifyDependencyIdentities(resolvedRoot, manifest.dependencies);
+  const actualTree = await hashDirectoryTree(
+    resolveInside(resolvedRoot, dependencyTreePath),
+    dependencyTreePath
+  );
+  assertSameTree(manifest.closure.tree, actualTree, "materialized dependency closure");
+}
+async function verifyExpectedRuntime(root, expected, expectedBytes) {
+  const manifestPath = join4(root, "dist", "runtime-manifest.json");
+  const actualBytes = await readFile3(manifestPath);
+  if (!actualBytes.equals(expectedBytes)) {
+    throw new Error("Materialized runtime manifest does not match the expected closure");
+  }
+  const actual = await parseRuntimeManifest(actualBytes, root);
+  if (actual.closure === void 0 || expected.closure === void 0) {
+    throw new Error("Materialized runtime manifest is missing its closure");
+  }
+  await verifyRuntimeFiles(root, actual);
+  await verifyDependencyIdentities(root, actual.dependencies);
+  const actualTree = await hashDirectoryTree(
+    resolveInside(root, dependencyTreePath),
+    dependencyTreePath
+  );
+  assertSameTree(expected.closure.tree, actualTree, "materialized dependency closure");
+}
+async function verifyRuntimeFiles(root, manifest) {
+  for (const file of manifest.files) {
+    const path = resolveInside(root, file.path);
+    const info = await lstat2(path);
+    if (info.isSymbolicLink()) {
+      throw new Error(`Runtime artifact ${file.path} must not be a symbolic link`);
+    }
     if (!info.isFile() || info.size !== file.bytes) {
       throw new Error(`Runtime artifact ${file.path} has changed`);
     }
-    const hash = createHash2("sha256").update(await readFile3(path)).digest("hex");
+    const hash = createHash3("sha256").update(await readFile3(path)).digest("hex");
     if (hash !== file.sha256) {
       throw new Error(`Runtime artifact ${file.path} failed verification`);
     }
   }
-  for (const expectedTree of expected.trees) {
-    const treeRoot = resolveInside(resolvedRoot, expectedTree.path);
-    const actualTree = await hashDirectoryTree(treeRoot, expectedTree.path);
-    if (actualTree.files !== expectedTree.files || actualTree.bytes !== expectedTree.bytes || actualTree.sha256 !== expectedTree.sha256) {
-      throw new Error(`Runtime dependency tree ${expectedTree.path} failed verification`);
+}
+async function verifyDependencyIdentities(root, dependencies) {
+  const nodeModules = resolveInside(root, dependencyTreePath);
+  const modulesInfo = await lstat2(nodeModules);
+  if (!modulesInfo.isDirectory() || modulesInfo.isSymbolicLink()) {
+    throw new Error("Runtime dependency closure must be a regular directory");
+  }
+  for (const dependency of dependencies) {
+    const packageRoot = resolveInside(root, dependency.path);
+    const packageInfo = await lstat2(packageRoot);
+    if (!packageInfo.isDirectory() || packageInfo.isSymbolicLink()) {
+      throw new Error(`Runtime dependency ${dependency.name} must be a regular directory`);
+    }
+    const packageJsonPath = join4(packageRoot, "package.json");
+    const packageJsonInfo = await lstat2(packageJsonPath);
+    if (!packageJsonInfo.isFile() || packageJsonInfo.isSymbolicLink()) {
+      throw new Error(`Runtime dependency ${dependency.name} has an unsafe package.json`);
+    }
+    const identity = await readPackageMetadata(packageRoot);
+    if (identity.name !== dependency.name || identity.version !== dependency.version) {
+      throw new Error(`Runtime dependency ${dependency.name} has an unexpected identity`);
     }
   }
 }
+async function parseRuntimeManifest(bytes, root) {
+  let candidate;
+  try {
+    candidate = JSON.parse(bytes.toString("utf8"));
+  } catch {
+    throw new Error("Runtime manifest is not valid JSON");
+  }
+  await validateRuntimeManifest(candidate, root);
+  return candidate;
+}
+async function validateRuntimeManifest(candidate, root) {
+  if (!isRecord(candidate) || candidate.schemaVersion !== 4) {
+    throw new Error("Runtime manifest has an unsupported schema version");
+  }
+  if (!isRecord(candidate.package) || typeof candidate.package.name !== "string" || typeof candidate.package.version !== "string" || !isRecord(candidate.piRuntime) || candidate.piRuntime.mode !== "external" || !isRuntimeContract(candidate.runtime)) {
+    throw new Error("Runtime manifest has an invalid package identity");
+  }
+  const packageMetadata = await readPackageMetadata(root, true);
+  if (candidate.package.name !== packageMetadata.name || candidate.package.version !== packageMetadata.version || packageMetadata.runtime === void 0 || !sameRuntimeContract(candidate.runtime, packageMetadata.runtime) || packageMetadata.clientExport === void 0) {
+    throw new Error("Runtime manifest package identity does not match package.json");
+  }
+  if (!Array.isArray(candidate.files) || !Array.isArray(candidate.dependencies)) {
+    throw new Error("Runtime manifest has invalid artifact lists");
+  }
+  const filePaths = /* @__PURE__ */ new Set();
+  for (const file of candidate.files) {
+    if (!isRecord(file) || !isManifestPath(file.path) || !isValidSize(file.bytes) || !isSha256(file.sha256)) {
+      throw new Error("Runtime manifest contains an invalid artifact");
+    }
+    if (filePaths.has(file.path)) {
+      throw new Error(`Runtime manifest has duplicate path ${file.path}`);
+    }
+    filePaths.add(file.path);
+  }
+  for (const required of requiredRuntimeArtifacts) {
+    if (!filePaths.has(required)) {
+      throw new Error(`Runtime manifest is missing required artifact ${required}`);
+    }
+  }
+  const dependencyPaths = /* @__PURE__ */ new Set();
+  const dependencyNames = /* @__PURE__ */ new Set();
+  for (const dependency of candidate.dependencies) {
+    if (!isRecord(dependency) || !isManifestPath(dependency.path) || typeof dependency.name !== "string" || dependency.name.length === 0 || typeof dependency.version !== "string" || dependency.version.length === 0 || dependency.path !== `node_modules/${dependency.name}`) {
+      throw new Error("Runtime manifest contains an invalid dependency declaration");
+    }
+    if (dependencyPaths.has(dependency.path) || dependencyNames.has(dependency.name)) {
+      throw new Error(`Runtime manifest has duplicate dependency ${dependency.name}`);
+    }
+    dependencyPaths.add(dependency.path);
+    dependencyNames.add(dependency.name);
+  }
+  const expectedDependencies = packageMetadata.dependencies;
+  if (dependencyNames.size !== Object.keys(expectedDependencies).length || [...dependencyNames].some(
+    (name) => expectedDependencies[name] !== candidate.dependencies.find(
+      (dependency) => dependency.name === name
+    )?.version
+  )) {
+    throw new Error("Runtime manifest dependencies do not match package.json");
+  }
+  for (const filePath of filePaths) {
+    for (const dependencyPath of dependencyPaths) {
+      if (filePath === dependencyPath || filePath.startsWith(`${dependencyPath}/`) || dependencyPath.startsWith(`${filePath}/`)) {
+        throw new Error(`Runtime manifest has overlapping paths ${filePath} and ${dependencyPath}`);
+      }
+    }
+  }
+  if (candidate.closure !== void 0) {
+    if (!isRecord(candidate.closure) || !isSha256(candidate.closure.sourceManifestSha256) || !isTreeIntegrity(candidate.closure.tree) || candidate.closure.tree.path !== dependencyTreePath) {
+      throw new Error("Runtime manifest contains an invalid materialized closure");
+    }
+  }
+}
+async function readPackageMetadata(root, requireRuntimeContract = false) {
+  let candidate;
+  try {
+    candidate = JSON.parse(await readFile3(join4(root, "package.json"), "utf8"));
+  } catch {
+    throw new Error("Runtime package.json is not valid JSON");
+  }
+  if (!isRecord(candidate) || typeof candidate.name !== "string" || typeof candidate.version !== "string" || requireRuntimeContract && !isRuntimeContract(candidate.pifleet) || candidate.dependencies !== void 0 && !isRecord(candidate.dependencies) || isRecord(candidate.dependencies) && Object.values(candidate.dependencies).some((version) => typeof version !== "string")) {
+    throw new Error("Runtime package.json has invalid package metadata");
+  }
+  const clientExport = isRecord(candidate.exports) ? candidate.exports["./client"] : void 0;
+  return {
+    name: candidate.name,
+    version: candidate.version,
+    ...isRuntimeContract(candidate.pifleet) ? { runtime: candidate.pifleet } : {},
+    ...isRecord(clientExport) && clientExport.types === "./dist/client/index.d.ts" && clientExport.import === "./dist/client.mjs" ? {
+      clientExport: {
+        types: "./dist/client/index.d.ts",
+        import: "./dist/client.mjs"
+      }
+    } : {},
+    dependencies: isRecord(candidate.dependencies) ? candidate.dependencies : {}
+  };
+}
+function serializeManifest(manifest) {
+  return Buffer.from(`${JSON.stringify(manifest, null, 2)}
+`);
+}
+function assertSameTree(expected, actual, label) {
+  if (expected.path !== actual.path || expected.files !== actual.files || expected.bytes !== actual.bytes || expected.sha256 !== actual.sha256) {
+    throw new Error(`Runtime ${label} changed during materialization`);
+  }
+}
 function resolveInside(root, path) {
+  if (!isManifestPath(path)) throw new Error(`Runtime manifest contains an unsafe path ${path}`);
   const resolved = resolve2(root, path);
   if (!resolved.startsWith(`${root}${sep2}`)) {
     throw new Error(`Runtime manifest contains an unsafe path ${path}`);
   }
   return resolved;
 }
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function isRuntimeContract(value) {
+  return isRecord(value) && value.protocolVersion === 3 && value.journalSchemaVersion === 3 && value.clientExport === "./client";
+}
+function sameRuntimeContract(left, right) {
+  return left.protocolVersion === right.protocolVersion && left.journalSchemaVersion === right.journalSchemaVersion && left.clientExport === right.clientExport;
+}
+function isManifestPath(value) {
+  return typeof value === "string" && value.length > 0 && !value.includes("\\") && !value.startsWith("/") && posix.normalize(value) === value && value.split("/").every((part) => part.length > 0 && part !== "." && part !== "..");
+}
+function isValidSize(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function isSha256(value) {
+  return typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+}
+function isTreeIntegrity(value) {
+  return isRecord(value) && isManifestPath(value.path) && isValidSize(value.files) && isValidSize(value.bytes) && isSha256(value.sha256);
+}
+function isDestinationRace(error) {
+  const code = error.code;
+  return code === "EEXIST" || code === "ENOTEMPTY";
+}
 async function ensurePrivateDirectory(path) {
   await mkdir2(path, { recursive: true, mode: 448 });
   const info = await lstat2(path);
@@ -303,32 +816,9 @@ async function pathExists(path) {
 
 // src/platform/shared/paths.ts
 import { homedir as homedir2, tmpdir } from "node:os";
-import { join as join4, resolve as resolve3 } from "node:path";
+import { join as join5, resolve as resolve3 } from "node:path";
 function resolveApplicationRoot(env = process.env) {
-  return env.PIFLEET_APPLICATION_ROOT ?? (process.platform === "darwin" ? join4(homedir2(), "Library", "Application Support", "Pi Fleet", "runtime") : join4(env.XDG_DATA_HOME ?? join4(homedir2(), ".local", "share"), "pi-fleet"));
-}
-function resolveFleetPaths(env = process.env) {
-  const explicitRoot = env.PIFLEET_STATE_ROOT;
-  if (explicitRoot !== void 0) {
-    const root = resolve3(explicitRoot);
-    return {
-      runtimeRoot: root,
-      stateRoot: root,
-      socketPath: join4(root, "control.sock"),
-      databasePath: join4(root, "fleet.sqlite")
-    };
-  }
-  const runtimeRoot = join4(
-    env.XDG_RUNTIME_DIR ?? tmpdir(),
-    `pifleet-${process.getuid?.() ?? "user"}`
-  );
-  const stateRoot = process.platform === "darwin" ? join4(homedir2(), "Library", "Application Support", "Pi Fleet") : join4(env.XDG_STATE_HOME ?? join4(homedir2(), ".local", "state"), "pi-fleet");
-  return {
-    runtimeRoot,
-    stateRoot,
-    socketPath: join4(runtimeRoot, "control.sock"),
-    databasePath: join4(stateRoot, "fleet.sqlite")
-  };
+  return env.PIFLEET_APPLICATION_ROOT ?? (process.platform === "darwin" ? join5(homedir2(), "Library", "Application Support", "pi-fleet", "runtime") : join5(env.XDG_DATA_HOME ?? join5(homedir2(), ".local", "share"), "pi-fleet"));
 }
 
 // src/entry/installer.ts
@@ -338,25 +828,29 @@ var executor = {
   }
 };
 async function installRuntimeService() {
-  return installMaterializedService(resolveFleetPaths().stateRoot);
+  return installMaterializedService(process.env.PIFLEET_STATE_ROOT);
 }
 async function repairRuntimeService() {
   return installMaterializedService(process.env.PIFLEET_STATE_ROOT);
 }
 async function installMaterializedService(stateRoot) {
-  const sourceRoot = dirname2(dirname2(fileURLToPath(import.meta.url)));
+  const sourceRoot = dirname3(dirname3(fileURLToPath(import.meta.url)));
   const release = await materializeRuntime({
     sourceRoot,
     applicationRoot: resolveApplicationRoot()
   });
+  const pi = await resolveExternalPiInstallation({ env: process.env });
   return installUserService({
     platform: process.platform,
     definition: {
       nodePath: process.execPath,
-      runtimePath: join5(release, "bin", "pifleet-runtime.mjs"),
+      runtimePath: join6(release, "bin", "pifleet-runtime.mjs"),
+      piExecutablePath: pi.selectedPath,
+      piNodePath: pi.nodePath,
       ...stateRoot === void 0 ? {} : { stateRoot }
     },
-    executor
+    executor,
+    replaceExisting: false
   });
 }
 async function uninstallRuntimeService() {