Merge branch 'main' into review-issue-48

src/cli.test.ts

@@ -2,7 +2,14 @@ import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
-import { commandWithVersionCheck, isCliEntrypoint } from "./cli.js";
+import {
+  commandWithVersionCheck,
+  doctorExitCode,
+  isCliEntrypoint,
+  launchdRuntimeDetails,
+  regularFileExists,
+  serviceBackendForPlatform,
+} from "./cli.js";
 
 const originalShell = process.env["SHELL"];
 
@@ -33,6 +40,42 @@ describe("commandWithVersionCheck", () => {
   });
 });
 
+describe("native-service doctor CLI contracts", () => {
+  it("uses native services only on supported platforms", () => {
+    expect(serviceBackendForPlatform("linux")).toEqual({ kind: "systemd", label: "systemd user services" });
+    expect(serviceBackendForPlatform("darwin")).toEqual({ kind: "launchd", label: "LaunchAgents" });
+    expect(serviceBackendForPlatform("win32")).toBeUndefined();
+  });
+
+  it("fails doctor for general, native-plan, or node-pty failures", () => {
+    expect(doctorExitCode(true, true, true)).toBe(0);
+    expect(doctorExitCode(false, true, true)).toBe(1);
+    expect(doctorExitCode(true, false, true)).toBe(1);
+    expect(doctorExitCode(true, true, false)).toBe(1);
+  });
+
+  it("accepts only regular files as bundled entrypoints", () => {
+    const dir = mkdtempSync(join(tmpdir(), "pi-web-entrypoint-test-"));
+    try {
+      const file = join(dir, "entrypoint.js");
+      writeFileSync(file, "export {};\n");
+      expect(regularFileExists(file)).toBe(true);
+      expect(regularFileExists(dir)).toBe(false);
+      expect(regularFileExists(join(dir, "missing.js"))).toBe(false);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("surfaces launchd last exit code 127 in service status", () => {
+    expect(launchdRuntimeDetails("state = exited\nlast exit code = 127\n")).toEqual({
+      state: "exited",
+      detail: "exited (last exit code 127)",
+      pid: undefined,
+    });
+  });
+});
+
 describe("isCliEntrypoint", () => {
   it("matches direct execution paths", () => {
     expect(isCliEntrypoint("/tmp/pi-web-cli.js", "/tmp/pi-web-cli.js")).toBe(true);

src/cli.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
-import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { homedir, userInfo } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
@@ -8,6 +8,37 @@ import { fileURLToPath } from "node:url";
 import { defaultPiWebConfigPath, defaultPiWebDataDir, examplePiWebConfig } from "./config.js";
 import { packageVersion, printPiWebVersionReport } from "./piWebVersionReport.js";
 import { checkNodePtyDarwinSpawnHelper, formatNodePtyDarwinSpawnHelperCheck } from "./server/diagnostics/nodePtySpawnHelper.js";
+import {
+  installNativeServiceCandidate,
+  nativeServiceInstallFailureNeedsPathAdvice,
+  type NativeServiceInstallCandidate,
+  type NativeServiceInstallFailure,
+} from "./nativeServices/serviceInstall.js";
+import {
+  nativeServiceManagerRefs,
+  productionNativeServiceIds,
+  type NativeServiceBackend,
+  type NativeServiceId,
+  type NativeServiceManagerRef,
+  type NativeServicePlan,
+  type NativeServiceShell,
+  type ProductionNativeServicePlanInput,
+} from "./nativeServices/servicePlan.js";
+import {
+  formatNativeServiceDoctorResult,
+  inferInstalledNativeServiceMode,
+  inspectInstalledDevelopmentServiceInput,
+  inspectInstalledProductionServiceContext,
+  runNativeServiceDoctor,
+  type InstalledNativeServiceDefinition,
+  type NativeServiceDoctorReport,
+  type NativeServiceDoctorTarget,
+} from "./nativeServices/serviceDoctor.js";
+import {
+  createNativeServiceAuthoritativeProbe,
+  nativeServicePrerequisiteShellCheck,
+} from "./nativeServices/serviceProbe.js";
+import { renderLaunchdPlist, renderSystemdUnit } from "./nativeServices/serviceRendering.js";
 
 const PI_WEB_PACKAGE_NAME = "@jmfederico/pi-web";
 
@@ -15,16 +46,10 @@ const systemdServiceDir = join(homedir(), ".config", "systemd", "user");
 const launchdServiceDir = join(homedir(), "Library", "LaunchAgents");
 const logDir = join(defaultPiWebDataDir(), "logs");
 
-const sessiondServiceName = "pi-web-sessiond.service";
-const webServiceName = "pi-web.service";
-const uiDevServiceName = "pi-web-ui-dev.service";
-
 type InstallMode = "production" | "dev";
-type ServiceBackendKind = "systemd" | "launchd";
-type ServiceId = "sessiond" | "web" | "uiDev";
+type ServiceId = NativeServiceId;
+type ServiceBackend = NativeServiceBackend;
 type Check = [string, string[]];
-type SupportedShell = "bash" | "zsh" | "fish";
-type RestartPolicy = "on-failure" | "never";
 
 interface InstallOptions {
   host: string;
@@ -33,44 +58,8 @@ interface InstallOptions {
   config?: string;
 }
 
-interface ServiceBackend {
-  kind: ServiceBackendKind;
-  label: string;
-}
-
-interface ServiceRef {
+interface ServiceRef extends NativeServiceManagerRef {
   id: ServiceId;
-  systemdName: string;
-  launchdLabel: string;
-  launchdPlistName: string;
-  logName: string;
-}
-
-interface ServiceDefinition extends ServiceRef {
-  description: string;
-  shellCommand: string;
-  restart: RestartPolicy;
-  environment: Record<string, string>;
-  after?: ServiceId[];
-  wants?: ServiceId[];
-  workingDirectory?: string;
-}
-
-interface ServiceShell {
-  name: SupportedShell;
-  executable: string;
-  detected?: string;
-  fallback: boolean;
-}
-
-interface ServiceExecutable {
-  command: string;
-  checks: Check[];
-}
-
-interface ServiceExecutables {
-  sessiond: ServiceExecutable;
-  web: ServiceExecutable;
 }
 
 type ServiceHealth = "running" | "stopped" | "not-installed" | "unknown";
@@ -85,30 +74,12 @@ interface ServiceRuntimeStatus {
 }
 
 const serviceRefs: Record<ServiceId, ServiceRef> = {
-  sessiond: {
-    id: "sessiond",
-    systemdName: sessiondServiceName,
-    launchdLabel: "com.pi-web.sessiond",
-    launchdPlistName: "com.pi-web.sessiond.plist",
-    logName: "sessiond.log",
-  },
-  web: {
-    id: "web",
-    systemdName: webServiceName,
-    launchdLabel: "com.pi-web.web",
-    launchdPlistName: "com.pi-web.web.plist",
-    logName: "web.log",
-  },
-  uiDev: {
-    id: "uiDev",
-    systemdName: uiDevServiceName,
-    launchdLabel: "com.pi-web.ui-dev",
-    launchdPlistName: "com.pi-web.ui-dev.plist",
-    logName: "ui-dev.log",
-  },
+  sessiond: { id: "sessiond", ...nativeServiceManagerRefs.sessiond },
+  web: { id: "web", ...nativeServiceManagerRefs.web },
+  uiDev: { id: "uiDev", ...nativeServiceManagerRefs.uiDev },
 };
 
-const productionServiceIds: ServiceId[] = ["sessiond", "web"];
+const productionServiceIds: ServiceId[] = [...productionNativeServiceIds];
 const startServiceOrder: ServiceId[] = ["sessiond", "web", "uiDev"];
 const stopServiceOrder: ServiceId[] = ["web", "uiDev", "sessiond"];
 // Restart web/UI before sessiond: when `pi-web restart` runs in a pi-web
@@ -123,12 +94,16 @@ function platformLabel(): string {
   return process.platform;
 }
 
-function currentServiceBackend(): ServiceBackend | undefined {
-  if (process.platform === "linux") return { kind: "systemd", label: "systemd user services" };
-  if (process.platform === "darwin") return { kind: "launchd", label: "LaunchAgents" };
+export function serviceBackendForPlatform(platform: NodeJS.Platform): ServiceBackend | undefined {
+  if (platform === "linux") return { kind: "systemd", label: "systemd user services" };
+  if (platform === "darwin") return { kind: "launchd", label: "LaunchAgents" };
   return undefined;
 }
 
+function currentServiceBackend(): ServiceBackend | undefined {
+  return serviceBackendForPlatform(process.platform);
+}
+
 function requireServiceBackend(command: string): ServiceBackend {
   const backend = currentServiceBackend();
   if (backend !== undefined) return backend;
@@ -236,23 +211,6 @@ function fishSingleQuote(value: string): string {
   return `'${value.replaceAll("\\", "\\\\").replaceAll("'", "\\'")}'`;
 }
 
-function systemdEscape(value: string): string {
-  return value.replaceAll("\\", "\\\\").replaceAll('"', '\\"');
-}
-
-function systemdQuotedValue(value: string): string {
-  return `"${systemdEscape(value)}"`;
-}
-
-function xmlEscape(value: string): string {
-  return value
-    .replaceAll("&", "&amp;")
-    .replaceAll("<", "&lt;")
-    .replaceAll(">", "&gt;")
-    .replaceAll('"', "&quot;")
-    .replaceAll("'", "&apos;");
-}
-
 function packageRootPath(): string {
   return dirname(dirname(fileURLToPath(import.meta.url)));
 }
@@ -261,15 +219,29 @@ function packageEntrypointPath(name: "server" | "sessiond"): string {
   return join(packageRootPath(), "dist", "server", name === "server" ? "index.js" : "sessiond.js");
 }
 
-function detectServiceShell(): ServiceShell {
+export function regularFileExists(path: string): boolean {
+  return existsSync(path) && statSync(path).isFile();
+}
+
+function detectServiceShell(): NativeServiceShell {
   const userShell = userInfo().shell ?? undefined;
   const envShell = process.env["SHELL"]?.trim();
   const detected = envShell === undefined || envShell === "" ? userShell : envShell;
   const name = basename(detected ?? "").replace(/^-/, "");
   if (name === "bash" || name === "zsh" || name === "fish") {
-    return { name, executable: detected ?? name, detected: detected ?? name, fallback: false };
+    return {
+      name,
+      executable: detected ?? name,
+      source: "detected",
+      detectedExecutable: detected ?? name,
+    };
   }
-  return { name: "bash", executable: "bash", ...(detected === undefined ? {} : { detected }), fallback: true };
+  return {
+    name: "bash",
+    executable: "bash",
+    source: "fallback",
+    detectedExecutable: detected ?? null,
+  };
 }
 
 function serviceShellCommand(command: string, cwd?: string): string[] {
@@ -277,76 +249,18 @@ function serviceShellCommand(command: string, cwd?: string): string[] {
   return ["/usr/bin/env", detectServiceShell().executable, "-lc", fullCommand];
 }
 
-function serviceShellExecPrefix(): string {
-  return `/usr/bin/env ${detectServiceShell().executable} -lc`;
-}
-
 function serviceShellQuote(value: string): string {
   return detectServiceShell().name === "fish" ? fishSingleQuote(value) : shellSingleQuote(value);
 }
 
-function systemdServiceShellQuote(value: string): string {
-  return serviceShellQuote(value.replaceAll("%", "%%").replaceAll("$", "$$"));
-}
-
-function checkSucceeds(command: string[]): boolean {
-  const [bin, ...args] = command;
-  return bin !== undefined && capture(bin, args).status === 0;
-}
-
-function serviceShellCanFindCommand(command: string, backend: ServiceBackend): boolean {
-  if (!checkSucceeds(serviceShellCommand(commandCheck(command)))) return false;
-  if (backend.kind === "systemd") return checkSucceeds(systemdUserServiceShellCommand(commandCheck(command)));
-  return true;
-}
-
-function readableFileCheck(path: string): string {
-  const quoted = serviceShellQuote(path);
-  return `test -r ${quoted} && printf '%s\\n' ${quoted}`;
-}
-
-function commandExecutable(command: string, backend: ServiceBackend): ServiceExecutable {
-  const shell = serviceShellLabel();
-  const checks: Check[] = [[`${shell} can find ${command}`, serviceShellCommand(commandCheck(command))]];
-  if (backend.kind === "systemd") {
-    checks.push([`systemd user ${shell} can find ${command}`, systemdUserServiceShellCommand(commandCheck(command))]);
-  }
-  return { command, checks };
-}
-
-function bundledExecutable(command: string, entrypointPath: string, backend: ServiceBackend): ServiceExecutable {
-  const shell = serviceShellLabel();
-  const check = readableFileCheck(entrypointPath);
-  const checks: Check[] = [[`${shell} can access bundled ${command} entrypoint`, serviceShellCommand(check)]];
-  if (backend.kind === "systemd") {
-    checks.push([`systemd user ${shell} can access bundled ${command} entrypoint`, systemdUserServiceShellCommand(check)]);
-  }
-  return { command: `node ${serviceShellQuote(entrypointPath)}`, checks };
-}
-
-function serviceExecutable(envName: "PI_WEB_SERVER_EXEC" | "PI_WEB_SESSIOND_EXEC", command: string, entrypointPath: string, backend: ServiceBackend): ServiceExecutable {
-  const configured = process.env[envName]?.trim();
-  if (configured !== undefined && configured !== "") return { command: configured, checks: [] };
-  if (serviceShellCanFindCommand(command, backend)) return commandExecutable(command, backend);
-  if (existsSync(entrypointPath)) return bundledExecutable(command, entrypointPath, backend);
-  return commandExecutable(command, backend);
-}
-
-function resolveServiceExecutables(backend: ServiceBackend): ServiceExecutables {
-  return {
-    sessiond: serviceExecutable("PI_WEB_SESSIOND_EXEC", "pi-web-sessiond", packageEntrypointPath("sessiond"), backend),
-    web: serviceExecutable("PI_WEB_SERVER_EXEC", "pi-web-server", packageEntrypointPath("server"), backend),
-  };
-}
-
 function describeServiceShell(): string {
   const shell = detectServiceShell();
-  if (shell.fallback) {
-    return shell.detected === undefined
+  if (shell.source === "fallback") {
+    return shell.detectedExecutable === null
       ? "could not detect a supported login shell; using bash"
-      : `detected ${shell.detected}; using bash because PI WEB currently supports bash, zsh, and fish`;
+      : `detected ${shell.detectedExecutable}; using bash because PI WEB currently supports bash, zsh, and fish`;
   }
-  return shell.detected === undefined ? shell.name : `${shell.name} (${shell.detected})`;
+  return shell.detectedExecutable === null ? shell.name : `${shell.name} (${shell.detectedExecutable})`;
 }
 
 function configEnvironment(options: InstallOptions, configPath: string): Record<string, string> {
@@ -385,28 +299,6 @@ function restartOrder(refs: ServiceRef[]): ServiceRef[] {
   return orderServiceRefs(refs, restartServiceOrder);
 }
 
-function productionServiceDefinitions(options: InstallOptions, configPath: string, executables: ServiceExecutables): ServiceDefinition[] {
-  const environment = configEnvironment(options, configPath);
-  return [
-    {
-      ...serviceRefs.sessiond,
-      description: "PI WEB session daemon",
-      shellCommand: `exec ${executables.sessiond.command}`,
-      restart: "on-failure",
-      environment,
-    },
-    {
-      ...serviceRefs.web,
-      description: "PI WEB server",
-      shellCommand: `exec ${executables.web.command}`,
-      restart: "on-failure",
-      environment,
-      after: ["sessiond"],
-      wants: ["sessiond"],
-    },
-  ];
-}
-
 function devRootPath(): string {
   return resolve(process.cwd());
 }
@@ -421,104 +313,21 @@ function validateDevCheckout(root: string): void {
   if (!isRecord(parsed) || parsed["name"] !== PI_WEB_PACKAGE_NAME) {
     throw new Error(`Development mode must be installed from a PI WEB checkout. ${packageJsonPath} is not ${PI_WEB_PACKAGE_NAME}.`);
   }
-
-  const scripts = parsed["scripts"];
-  if (!isRecord(scripts)) throw new Error(`Development mode requires npm scripts in ${packageJsonPath}.`);
-  const requiredScripts = ["start:sessiond", "dev:web", "dev:client"];
-  const missing = requiredScripts.filter((script) => typeof scripts[script] !== "string");
-  if (missing.length > 0) throw new Error(`Development mode requires missing npm scripts: ${missing.join(", ")}.`);
-}
-
-function devServiceDefinitions(options: InstallOptions, configPath: string, root: string): ServiceDefinition[] {
-  const environment = configEnvironment(options, configPath);
-  return [
-    {
-      ...serviceRefs.sessiond,
-      description: "PI WEB session daemon (dev)",
-      shellCommand: "exec npm run start:sessiond",
-      restart: "never",
-      environment,
-      workingDirectory: root,
-    },
-    {
-      ...serviceRefs.uiDev,
-      description: "PI WEB UI dev server",
-      shellCommand: `exec /usr/bin/env bash -c ${serviceShellQuote('trap "kill 0" EXIT; npm run dev:web & npm run dev:client & wait')}`,
-      restart: "never",
-      environment,
-      after: ["sessiond"],
-      wants: ["sessiond"],
-      workingDirectory: root,
-    },
-  ];
-}
-
-function dependencyLine(name: "After" | "Wants", ids: ServiceId[] | undefined): string {
-  if (ids === undefined || ids.length === 0) return "";
-  return `${name}=${ids.map((id) => serviceRefs[id].systemdName).join(" ")}\n`;
-}
-
-function environmentLines(environment: Record<string, string>): string {
-  return Object.entries(environment)
-    .map(([key, value]) => `Environment="${key}=${systemdEscape(value)}"\n`)
-    .join("");
-}
-
-function systemdUnit(service: ServiceDefinition): string {
-  const workingDirectory = service.workingDirectory === undefined ? "" : `WorkingDirectory=${systemdQuotedValue(service.workingDirectory)}\n`;
-  const restart = service.restart === "on-failure" ? "Restart=on-failure\nRestartSec=2\n" : "Restart=no\n";
-  return `[Unit]
-Description=${service.description}
-${dependencyLine("After", service.after)}${dependencyLine("Wants", service.wants)}
-[Service]
-Type=simple
-${workingDirectory}${environmentLines(service.environment)}ExecStart=${serviceShellExecPrefix()} ${systemdServiceShellQuote(service.shellCommand)}
-${restart}
-[Install]
-WantedBy=default.target
-`;
-}
-
-function plistString(key: string, value: string, indent = "  "): string {
-  return `${indent}<key>${xmlEscape(key)}</key>\n${indent}<string>${xmlEscape(value)}</string>\n`;
-}
-
-function plistProgramArguments(service: ServiceDefinition): string {
-  const args = ["/usr/bin/env", detectServiceShell().executable, "-lc", service.shellCommand];
-  return `  <key>ProgramArguments</key>\n  <array>\n${args.map((arg) => `    <string>${xmlEscape(arg)}</string>`).join("\n")}\n  </array>\n`;
-}
-
-function plistEnvironment(environment: Record<string, string>): string {
-  const entries = Object.entries(environment);
-  if (entries.length === 0) return "";
-  return `  <key>EnvironmentVariables</key>\n  <dict>\n${entries.map(([key, value]) => plistString(key, value, "    ")).join("")}  </dict>\n`;
 }
 
 function launchdLogPath(ref: ServiceRef): string {
   return join(logDir, ref.logName);
 }
 
-function launchdPlist(service: ServiceDefinition): string {
-  const workingDirectory = service.workingDirectory === undefined ? "" : plistString("WorkingDirectory", service.workingDirectory);
-  const keepAlive = service.restart === "on-failure" ? "  <key>KeepAlive</key>\n  <dict>\n    <key>SuccessfulExit</key>\n    <false/>\n  </dict>\n" : "";
-  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">
-<plist version="1.0">
-<dict>
-${plistString("Label", service.launchdLabel)}${plistProgramArguments(service)}${workingDirectory}${plistEnvironment(service.environment)}  <key>RunAtLoad</key>
-  <true/>
-${keepAlive}${plistString("StandardOutPath", launchdLogPath(service))}${plistString("StandardErrorPath", launchdLogPath(service))}</dict>
-</plist>
-`;
+function installConfigPath(options: InstallOptions): string {
+  return options.config === undefined ? defaultPiWebConfigPath() : resolve(options.config);
 }
 
-async function writeInitialConfig(options: InstallOptions): Promise<string> {
-  const configPath = options.config === undefined ? defaultPiWebConfigPath() : resolve(options.config);
+async function writeInitialConfig(options: InstallOptions, configPath: string): Promise<void> {
   await mkdir(dirname(configPath), { recursive: true });
   if (!existsSync(configPath)) {
     await writeFile(configPath, examplePiWebConfig({ host: options.host, port: Number(options.port) }));
   }
-  return configPath;
 }
 
 function systemdServicePath(ref: ServiceRef): string {
@@ -546,8 +355,8 @@ function installedServiceRefs(backend: ServiceBackend): ServiceRef[] {
   return installed.length === 0 ? productionServiceRefs() : installed;
 }
 
-async function installSystemdServices(services: ServiceDefinition[]): Promise<void> {
-  const selected = new Set<ServiceId>(services.map((service) => service.id));
+async function installSystemdServices(plan: NativeServicePlan): Promise<void> {
+  const selected = new Set<ServiceId>(plan.services.map((service) => service.id));
   const obsolete = stopOrder(allServiceRefs().filter((ref) => !selected.has(ref.id)));
 
   for (const ref of obsolete) {
@@ -556,11 +365,11 @@ async function installSystemdServices(services: ServiceDefinition[]): Promise<vo
   }
 
   await mkdir(systemdServiceDir, { recursive: true });
-  for (const service of services) {
-    await writeFile(systemdServicePath(service), systemdUnit(service));
+  for (const service of plan.services) {
+    await writeFile(join(systemdServiceDir, service.manager.systemdName), renderSystemdUnit(plan, service));
   }
 
-  const names = services.map((service) => service.systemdName);
+  const names = plan.services.map((service) => service.manager.systemdName);
   run("systemctl", ["--user", "daemon-reload"], { check: true });
   run("systemctl", ["--user", "enable", ...names], { check: true });
   run("systemctl", ["--user", "restart", ...names], { check: true });
@@ -592,8 +401,8 @@ function launchdStart(ref: ServiceRef): void {
   run("launchctl", ["kickstart", launchdServiceTarget(ref)], { check: true });
 }
 
-async function installLaunchdServices(services: ServiceDefinition[]): Promise<void> {
-  const selected = new Set<ServiceId>(services.map((service) => service.id));
+async function installLaunchdServices(plan: NativeServicePlan): Promise<void> {
+  const selected = new Set<ServiceId>(plan.services.map((service) => service.id));
 
   await mkdir(launchdServiceDir, { recursive: true });
   await mkdir(logDir, { recursive: true });
@@ -604,16 +413,21 @@ async function installLaunchdServices(services: ServiceDefinition[]): Promise<vo
     await rm(launchdPlistPath(ref), { force: true });
   }
 
-  for (const service of services) {
-    await writeFile(launchdPlistPath(service), launchdPlist(service));
+  for (const service of plan.services) {
+    const plistPath = join(launchdServiceDir, service.manager.launchdPlistName);
+    await writeFile(plistPath, renderLaunchdPlist(plan, service, logDir));
   }
 
-  for (const service of services) launchdStart(service);
+  for (const service of plan.services) launchdStart(serviceRefFromPlan(service.id, service.manager));
 }
 
-async function installNativeServices(backend: ServiceBackend, services: ServiceDefinition[]): Promise<void> {
-  if (backend.kind === "systemd") await installSystemdServices(services);
-  else await installLaunchdServices(services);
+async function installNativeServices(plan: NativeServicePlan): Promise<void> {
+  if (plan.backend.kind === "systemd") await installSystemdServices(plan);
+  else await installLaunchdServices(plan);
+}
+
+function serviceRefFromPlan(id: ServiceId, manager: NativeServiceManagerRef): ServiceRef {
+  return { id, ...manager };
 }
 
 async function uninstallSystemdServices(): Promise<void> {
@@ -705,6 +519,16 @@ function parseLaunchdField(output: string, field: string): string | undefined {
   return match?.[1]?.trim();
 }
 
+export function launchdRuntimeDetails(output: string): { state: string; detail: string; pid: string | undefined } {
+  const state = parseLaunchdField(output, "state") ?? "unknown";
+  const pid = parseLaunchdField(output, "pid");
+  const lastExitCode = parseLaunchdField(output, "last exit code");
+  const detail = state === "running"
+    ? "running"
+    : lastExitCode === undefined ? state : `${state} (last exit code ${lastExitCode})`;
+  return { state, detail, pid };
+}
+
 function launchdRuntimeStatus(backend: ServiceBackend, ref: ServiceRef): ServiceRuntimeStatus {
   const target = launchdServiceTarget(ref);
   const filePath = serviceFilePath(backend, ref);
@@ -715,10 +539,9 @@ function launchdRuntimeStatus(backend: ServiceBackend, ref: ServiceRef): Service
     return makeServiceRuntimeStatus(ref, "stopped", firstOutputLine(result.stderr, result.stdout) ?? "not loaded", target, filePath);
   }
 
-  const state = parseLaunchdField(result.stdout, "state") ?? "unknown";
-  const pid = parseLaunchdField(result.stdout, "pid");
-  const health: ServiceHealth = state === "running" ? "running" : state === "unknown" ? "unknown" : "stopped";
-  return makeServiceRuntimeStatus(ref, health, state === "running" ? "running" : state, target, filePath, pid);
+  const details = launchdRuntimeDetails(result.stdout);
+  const health: ServiceHealth = details.state === "running" ? "running" : details.state === "unknown" ? "unknown" : "stopped";
+  return makeServiceRuntimeStatus(ref, health, details.detail, target, filePath, details.pid);
 }
 
 function runtimeStatus(backend: ServiceBackend, ref: ServiceRef): ServiceRuntimeStatus {
@@ -747,40 +570,86 @@ function printServiceStatusReport(backend: ServiceBackend): boolean {
   return statuses.every((status) => status.health === "running");
 }
 
-function backendAvailabilityChecks(backend: ServiceBackend): Check[] {
-  if (backend.kind === "systemd") return [["systemctl --user", ["systemctl", "--user", "--version"]]];
-  return [[`launchctl ${launchdDomain()}`, ["launchctl", "print", launchdDomain()]]];
+function configuredServiceCommand(name: "PI_WEB_SERVER_EXEC" | "PI_WEB_SESSIOND_EXEC"): string | undefined {
+  const value = process.env[name];
+  return value === undefined || value.trim() === "" ? undefined : value;
 }
 
-function baseShellChecks(backend: ServiceBackend): Check[] {
-  const shell = serviceShellLabel();
-  const checks: Check[] = [[`${shell} can find node >= 22`, serviceShellCommand(nodeVersionCheck())]];
-  if (backend.kind === "systemd") checks.push([`systemd user ${shell} can find node >= 22`, systemdUserServiceShellCommand(nodeVersionCheck())]);
-  return checks;
+function productionNativeServicePlanInput(
+  backend: ServiceBackend,
+  shell: NativeServiceShell,
+  environment: Readonly<Record<string, string>>,
+): ProductionNativeServicePlanInput {
+  return {
+    backend,
+    shell,
+    environment,
+    executables: {
+      sessiond: {
+        configuredCommand: configuredServiceCommand("PI_WEB_SESSIOND_EXEC"),
+        namedCommand: "pi-web-sessiond",
+        bundledEntrypointPath: packageEntrypointPath("sessiond"),
+      },
+      web: {
+        configuredCommand: configuredServiceCommand("PI_WEB_SERVER_EXEC"),
+        namedCommand: "pi-web-server",
+        bundledEntrypointPath: packageEntrypointPath("server"),
+      },
+    },
+  };
 }
 
-function devInstallChecks(backend: ServiceBackend, root: string): Check[] {
-  const shell = serviceShellLabel();
-  const checks: Check[] = [
-    [`${shell} can find npm`, serviceShellCommand(commandCheck("npm"), root)],
-    [`${shell} can find bash`, serviceShellCommand(commandCheck("bash"), root)],
-  ];
-  if (backend.kind === "systemd") {
-    checks.push(
-      [`systemd user ${shell} can find npm`, systemdUserServiceShellCommand(commandCheck("npm"), root)],
-      [`systemd user ${shell} can find bash`, systemdUserServiceShellCommand(commandCheck("bash"), root)],
-    );
+function nativeServiceInstallCandidate(
+  options: InstallOptions,
+  backend: ServiceBackend,
+  configPath: string,
+  devRoot: string | undefined,
+): NativeServiceInstallCandidate {
+  const shell = detectServiceShell();
+  const environment = configEnvironment(options, configPath);
+  if (options.mode === "production") {
+    return {
+      mode: "production",
+      input: productionNativeServicePlanInput(backend, shell, environment),
+    };
   }
-  return checks;
+
+  const root = devRoot ?? devRootPath();
+  return {
+    mode: "development",
+    input: {
+      backend,
+      shell,
+      environment,
+      workingDirectory: root,
+      packageJsonPath: join(root, "package.json"),
+    },
+  };
 }
 
-function installPreflightChecks(backend: ServiceBackend, mode: InstallMode, executables: ServiceExecutables | undefined, devRoot: string | undefined): Check[] {
-  return [
-    ...backendAvailabilityChecks(backend),
-    ...baseShellChecks(backend),
-    ...(mode === "dev" && devRoot !== undefined ? devInstallChecks(backend, devRoot) : []),
-    ...(mode === "production" && executables !== undefined ? [...executables.web.checks, ...executables.sessiond.checks] : []),
-  ];
+function printNativeServiceInstallFailure(failure: NativeServiceInstallFailure): void {
+  if (failure.kind === "plan-resolution") {
+    for (const item of failure.failures) {
+      if (item.kind === "probe-infrastructure") {
+        console.log(`✗ Service-manager probe infrastructure failure (${item.reason}): ${item.message}`);
+      } else if (item.kind === "entrypoint-inspection-failure") {
+        console.log(`✗ Could not inspect bundled ${item.serviceId} entrypoint ${item.entrypointPath}: ${item.message}`);
+      } else {
+        console.log(`✗ ${item.namedCommand} is unavailable to the service manager, and bundled entrypoint ${item.bundledEntrypointPath} is missing.`);
+        if (item.namedCommandFailure !== null) console.log(`  ${item.namedCommandFailure}`);
+      }
+    }
+    return;
+  }
+
+  for (const item of failure.failures) {
+    if (item.kind === "probe-infrastructure") {
+      console.log(`✗ Service-manager probe infrastructure failure (${item.reason}): ${item.message}`);
+    } else {
+      console.log(`✗ ${item.prerequisite.description}`);
+      if (item.detail !== null && item.detail !== item.prerequisite.description) console.log(`  ${item.detail}`);
+    }
+  }
 }
 
 async function install(args: string[]): Promise<void> {
@@ -788,22 +657,26 @@ async function install(args: string[]): Promise<void> {
   const options = parseInstallOptions(args);
   const devRoot = options.mode === "dev" ? devRootPath() : undefined;
   if (devRoot !== undefined) validateDevCheckout(devRoot);
+  const configPath = installConfigPath(options);
+  const candidate = nativeServiceInstallCandidate(options, backend, configPath, devRoot);
 
-  const executables = options.mode === "production" ? resolveServiceExecutables(backend) : undefined;
   console.log(`Running PI WEB ${options.mode} install preflight checks...`);
   console.log(`Service backend: ${backend.label}`);
   console.log(`Service shell: ${describeServiceShell()}`);
-  if (!runChecks(installPreflightChecks(backend, options.mode, executables, devRoot))) {
-    printPathSetupAdvice();
-    throw new Error("Install preflight checks failed. Fix the failed checks above, then run `pi-web doctor` for more detail.");
+  const result = await installNativeServiceCandidate(candidate, {
+    probe: createNativeServiceAuthoritativeProbe(),
+    fileExists: regularFileExists,
+    writeInitialConfig: () => writeInitialConfig(options, configPath),
+    replaceServices: installNativeServices,
+  });
+  if (!result.ok) {
+    printNativeServiceInstallFailure(result.failure);
+    if (nativeServiceInstallFailureNeedsPathAdvice(result.failure)) printPathSetupAdvice();
+    throw new Error("Install preflight checks failed without changing config or services. Fix the failure above, then run `pi-web doctor` for more detail.");
+  }
+  for (const service of result.plan.services.filter((item) => item.strategy.kind === "configured-override")) {
+    console.log(`! ${service.description} uses a configured command override; preflight did not execute that arbitrary command.`);
   }
-
-  const configPath = await writeInitialConfig(options);
-  const services = options.mode === "dev"
-    ? devServiceDefinitions(options, configPath, devRoot ?? devRootPath())
-    : productionServiceDefinitions(options, configPath, executables ?? resolveServiceExecutables(backend));
-
-  await installNativeServices(backend, services);
 
   console.log(`\nPI WEB ${options.mode} services are installed and starting.`);
   console.log(`Config: ${configPath}`);
@@ -886,18 +759,6 @@ function serviceShellLabel(): string {
   return `${detectServiceShell().name} -lc`;
 }
 
-function systemdUserServiceShellCommand(command: string, cwd?: string): string[] {
-  return [
-    "systemd-run",
-    "--user",
-    "--wait",
-    "--collect",
-    "--pipe",
-    "--quiet",
-    ...serviceShellCommand(command, cwd),
-  ];
-}
-
 function commandCheck(command: string): string {
   return `command -v ${command}`;
 }
@@ -917,29 +778,13 @@ function nodeVersionCheck(): string {
   ].join(" && ");
 }
 
-function doctorChecks(): Check[] {
+function generalDoctorChecks(): Check[] {
   const shell = serviceShellLabel();
-  const backend = currentServiceBackend();
-  if (backend === undefined) {
-    return [
-      [`${shell} can find node >= 22`, serviceShellCommand(nodeVersionCheck())],
-      [`${shell} can find npm`, serviceShellCommand(commandWithVersionCheck("npm"))],
-      [`${shell} can find pi`, serviceShellCommand(commandWithVersionCheck("pi"))],
-    ];
-  }
-
-  const checks: Check[] = [
-    ...backendAvailabilityChecks(backend),
-    ...baseShellChecks(backend),
-    [`${shell} can find npm`, serviceShellCommand(commandWithVersionCheck("npm"))],
-    [`${shell} can find pi`, serviceShellCommand(commandWithVersionCheck("pi"))],
+  return [
+    [`Caller login ${shell} can find node >= 22`, serviceShellCommand(nodeVersionCheck())],
+    [`Caller login ${shell} can find npm`, serviceShellCommand(commandWithVersionCheck("npm"))],
+    [`Caller login ${shell} can find pi`, serviceShellCommand(commandWithVersionCheck("pi"))],
   ];
-  const executables = resolveServiceExecutables(backend);
-  checks.push(...executables.web.checks, ...executables.sessiond.checks);
-  if (backend.kind === "systemd") {
-    checks.push([`systemd user ${shell} can find pi`, systemdUserServiceShellCommand(commandWithVersionCheck("pi"))]);
-  }
-  return checks;
 }
 
 function runChecks(checks: Check[]): boolean {
@@ -966,10 +811,7 @@ function printCheckOutput(output: string): void {
 
 function optionalDoctorChecks(): Check[] {
   const shell = serviceShellLabel();
-  const backend = currentServiceBackend();
-  const checks: Check[] = [[`${shell} can find optional ripgrep (rg)`, serviceShellCommand(commandCheck("rg"))]];
-  if (backend?.kind === "systemd") checks.push([`systemd user ${shell} can find optional ripgrep (rg)`, systemdUserServiceShellCommand(commandCheck("rg"))]);
-  return checks;
+  return [[`Caller login ${shell} can find optional ripgrep (rg)`, serviceShellCommand(commandCheck("rg"))]];
 }
 
 function printOptionalDoctorChecks(): void {
@@ -989,8 +831,115 @@ function printOptionalDoctorChecks(): void {
   }
 }
 
-function printPathSetupAdvice(): void {
-  const shell = detectServiceShell();
+function installedServiceDefinitions(
+  backend: ServiceBackend,
+  ids: readonly ServiceId[],
+): InstalledNativeServiceDefinition[] {
+  return ids.map((id) => ({
+    id,
+    contents: readFileSync(serviceFilePath(backend, serviceRefs[id]), "utf8"),
+  }));
+}
+
+function nativeServiceDoctorTarget(backend: ServiceBackend): NativeServiceDoctorTarget {
+  const ids = installedServiceIds(backend);
+  const mode = inferInstalledNativeServiceMode(ids);
+  if (mode === "ambiguous") {
+    return {
+      kind: "inspection-failure",
+      message: `installed service IDs do not identify one mode (${[...ids].join(", ") || "none"}).`,
+    };
+  }
+  if (mode === "none") {
+    return {
+      kind: "prospective-production",
+      input: productionNativeServicePlanInput(backend, detectServiceShell(), {}),
+      reason: "no installed service strategy is available",
+    };
+  }
+  const expectedIds = mode === "production"
+    ? productionNativeServiceIds
+    : (["sessiond", "uiDev"] as const);
+  const missingId = expectedIds.find((id) => !ids.has(id));
+  if (missingId !== undefined) {
+    return {
+      kind: "inspection-failure",
+      message: `installed ${mode} service set is incomplete; ${missingId} is missing.`,
+    };
+  }
+
+  let definitions: InstalledNativeServiceDefinition[];
+  try {
+    definitions = installedServiceDefinitions(
+      backend,
+      expectedIds,
+    );
+  } catch (error: unknown) {
+    return {
+      kind: "inspection-failure",
+      message: error instanceof Error ? error.message : String(error),
+    };
+  }
+
+  if (mode === "development") {
+    const inspection = inspectInstalledDevelopmentServiceInput(backend, definitions);
+    return inspection.ok
+      ? { kind: "installed-development", input: inspection.value }
+      : { kind: "inspection-failure", message: inspection.message };
+  }
+
+  const inspection = inspectInstalledProductionServiceContext(backend, definitions);
+  return inspection.ok
+    ? {
+        kind: "prospective-production",
+        input: productionNativeServicePlanInput(backend, inspection.value.shell, inspection.value.environment),
+        reason: "installed executable strategy is not recorded",
+      }
+    : { kind: "inspection-failure", message: inspection.message };
+}
+
+async function printNativeServiceDoctorChecks(backend: ServiceBackend): Promise<NativeServiceDoctorReport> {
+  const result = await runNativeServiceDoctor(nativeServiceDoctorTarget(backend), {
+    probe: createNativeServiceAuthoritativeProbe(),
+    fileExists: regularFileExists,
+  });
+  const report = formatNativeServiceDoctorResult(result);
+  for (const line of report.lines) console.log(line);
+  printCallerContextComparisons(report);
+  return report;
+}
+
+function printCallerContextComparisons(report: NativeServiceDoctorReport): void {
+  if (report.plan === null || report.failedPrerequisites.length === 0) return;
+  const seen = new Set<string>();
+  for (const prerequisite of report.failedPrerequisites) {
+    if (seen.has(prerequisite.id)) continue;
+    seen.add(prerequisite.id);
+    const service = report.plan.services.find((candidate) => candidate.prerequisites.some((item) => item.id === prerequisite.id));
+    const command = nativeServicePrerequisiteShellCheck(report.plan.shell.name, prerequisite);
+    const result = captureServiceShell(report.plan.shell, command, service?.workingDirectory ?? null);
+    console.log(
+      `  Caller-invoked ${report.plan.shell.name} -lc ${result.status === 0 ? "satisfies" : "also does not satisfy"} ${prerequisite.description}; the service-manager result is authoritative.`,
+    );
+  }
+}
+
+function captureServiceShell(
+  shell: NativeServiceShell,
+  command: string,
+  workingDirectory: string | null,
+): { status: number; stdout: string; stderr: string } {
+  const fullCommand = workingDirectory === null
+    ? command
+    : `cd ${shellQuoteFor(shell.name, workingDirectory)} && ${command}`;
+  return capture("/usr/bin/env", [shell.executable, "-lc", fullCommand]);
+}
+
+function shellQuoteFor(shell: NativeServiceShell["name"], value: string): string {
+  return shell === "fish" ? fishSingleQuote(value) : shellSingleQuote(value);
+}
+
+function printPathSetupAdvice(shell: NativeServiceShell = detectServiceShell()): void {
   console.log("\nPATH setup advice:");
   if (shell.name === "bash") {
     console.log("  Detected bash. Put PATH setup for node/version managers/tools in ~/.bash_profile or ~/.profile.");
@@ -1005,21 +954,36 @@ function printPathSetupAdvice(): void {
   }
 }
 
+export function doctorExitCode(
+  generalReadinessOk: boolean,
+  nativeServicePlanOk: boolean,
+  nodePtySpawnHelperOk: boolean,
+): 0 | 1 {
+  return generalReadinessOk && nativeServicePlanOk && nodePtySpawnHelperOk ? 0 : 1;
+}
+
 async function doctor(): Promise<void> {
   const backend = currentServiceBackend();
   console.log(`Platform: ${platformLabel()}`);
   console.log(`Service backend: ${backend?.label ?? "manual run only"}`);
   console.log(`Service shell: ${describeServiceShell()}`);
   if (backend === undefined) {
-    console.log(`- Native user service checks skipped on ${platformLabel()}`);
+    console.log(`- Native user service plan checks skipped on ${platformLabel()}; no native-service drift is reported.`);
   }
   console.log("");
   await printPiWebVersionReport();
-  console.log("\nDoctor checks:");
-  const ok = runChecks(doctorChecks());
+
+  console.log("\nGeneral login-shell readiness (separate from native-service requirements):");
+  const generalReadinessOk = runChecks(generalDoctorChecks());
   printOptionalDoctorChecks();
   const nodePtySpawnHelperOk = printNodePtyDarwinSpawnHelperCheck();
 
+  let nativeServiceReport: NativeServiceDoctorReport | null = null;
+  if (backend !== undefined) {
+    console.log("\nNative service plan checks (service-manager context):");
+    nativeServiceReport = await printNativeServiceDoctorChecks(backend);
+  }
+
   if (supportsSystemdUserServices()) {
     const linger = isLingerEnabled();
     if (linger === true) {
@@ -1037,17 +1001,21 @@ async function doctor(): Promise<void> {
     console.log(`- systemd user lingering skipped on ${platformLabel()}`);
   }
 
-  if (!ok) {
-    console.log("\nIf a command works in your terminal but fails here, make sure your service shell login files set PATH the same way.");
-    if (backend?.kind === "systemd") console.log("If a bundled entrypoint is not accessible, reinstall or update the PI WEB package.");
-    printPathSetupAdvice();
+  const nativeServicePlanOk = nativeServiceReport?.ok ?? true;
+  const pathFailure = !generalReadinessOk || nativeServiceReport?.pathAdviceRecommended === true;
+  if (pathFailure) {
+    console.log("\nIf a command works in your terminal but fails in the service-manager check, compare the caller and manager contexts above.");
+    const adviceShell = nativeServiceReport?.pathAdviceRecommended === true && nativeServiceReport.adviceShell !== null
+      ? nativeServiceReport.adviceShell
+      : detectServiceShell();
+    printPathSetupAdvice(adviceShell);
   }
 
-  if (ok && backend === undefined) {
+  if (generalReadinessOk && backend === undefined) {
     console.log(`\n${manualRunAdvice()}`);
   }
 
-  if (!ok || !nodePtySpawnHelperOk) process.exitCode = 1;
+  if (doctorExitCode(generalReadinessOk, nativeServicePlanOk, nodePtySpawnHelperOk) !== 0) process.exitCode = 1;
 }
 
 function printNodePtyDarwinSpawnHelperCheck(): boolean {

src/client/src/api/clients.test.ts

@@ -13,6 +13,20 @@ const workspace: Workspace = {
   isGitWorktree: true,
 };
 
+function piWebStatusResponse() {
+  return {
+    packageName: "@jmfederico/pi-web",
+    generatedAt: "now",
+    components: {
+      web: { component: "web", label: "PI WEB", available: true, stale: false },
+      sessiond: { component: "sessiond", label: "PI WEB Session Daemon", available: true, stale: false },
+    },
+    release: { packageName: "@jmfederico/pi-web", updateAvailable: false },
+    commands: {},
+    messages: [],
+  };
+}
+
 const commandRun: TerminalCommandRun = {
   id: "run1",
   origin: "core",
@@ -32,17 +46,7 @@ afterEach(() => {
 
 describe("machine-scoped runtime API", () => {
   it("reads machine PI WEB status through the gateway route", async () => {
-    const fetchMock = stubJsonFetch({
-      packageName: "@jmfederico/pi-web",
-      generatedAt: "now",
-      components: {
-        web: { component: "web", label: "PI WEB", available: true, stale: false },
-        sessiond: { component: "sessiond", label: "PI WEB Session Daemon", available: true, stale: false },
-      },
-      release: { packageName: "@jmfederico/pi-web", updateAvailable: false },
-      commands: {},
-      messages: [],
-    });
+    const fetchMock = stubJsonFetch(piWebStatusResponse());
 
     await piWebApi.piWebStatus("remote a");
 
@@ -50,6 +54,26 @@ describe("machine-scoped runtime API", () => {
     expect(fetchCall(fetchMock, 0)[0]).toBe("/api/machines/remote%20a/pi-web/status");
   });
 
+  it("requests an uncached update check through the local status route", async () => {
+    const fetchMock = stubJsonFetch(piWebStatusResponse());
+
+    await piWebApi.checkForUpdates();
+
+    expect(fetchMock).toHaveBeenCalledOnce();
+    expect(fetchCall(fetchMock, 0)[0]).toBe("/api/pi-web/status?refresh=1");
+    expect(fetchCall(fetchMock, 0)[1]?.cache).toBe("no-store");
+  });
+
+  it("requests an uncached update check through the selected machine route", async () => {
+    const fetchMock = stubJsonFetch(piWebStatusResponse());
+
+    await piWebApi.checkForUpdates("remote a");
+
+    expect(fetchMock).toHaveBeenCalledOnce();
+    expect(fetchCall(fetchMock, 0)[0]).toBe("/api/machines/remote%20a/pi-web/status?refresh=1");
+    expect(fetchCall(fetchMock, 0)[1]?.cache).toBe("no-store");
+  });
+
   it("reads machine runtime through the gateway route", async () => {
     const fetchMock = stubJsonFetch({ machineId: "remote a", ok: true, checkedAt: "now", capabilities: [PI_WEB_CAPABILITIES.sessionsDeleteArchived] });
 

src/client/src/api/clients.ts

@@ -99,8 +99,13 @@ function sessionBulkMutationRef(session: SessionLookup): SessionBulkMutationRef
   return cwd === undefined || cwd === "" ? { id } : { id, cwd };
 }
 
+function piWebStatusUrl(machineId: string): string {
+  return machineId === "local" ? "/api/pi-web/status" : `${machinePrefix(machineId)}/pi-web/status`;
+}
+
 export const piWebApi = {
-  piWebStatus: (machineId = "local") => request(machineId === "local" ? "/api/pi-web/status" : `${machinePrefix(machineId)}/pi-web/status`, parsePiWebStatusResponse),
+  piWebStatus: (machineId = "local") => request(piWebStatusUrl(machineId), parsePiWebStatusResponse),
+  checkForUpdates: (machineId = "local") => request(`${piWebStatusUrl(machineId)}?refresh=1`, parsePiWebStatusResponse, { cache: "no-store" }),
   piWebRuntime: () => request("/api/pi-web/runtime", parsePiWebRuntimeResponse),
 };
 

src/client/src/api/federatedRouteContract.test.ts

@@ -28,6 +28,7 @@ describe("federated route contract", () => {
 
     await Promise.all([
       ignoreParseFailure(piWebApi.piWebStatus(machineId)),
+      ignoreParseFailure(piWebApi.checkForUpdates(machineId)),
       ignoreParseFailure(configApi.config(machineId)),
       ignoreParseFailure(configApi.saveConfig({ spawnSessions: true }, machineId)),
       ignoreParseFailure(pluginsApi.plugins(machineId)),

src/client/src/components/PiWebApp.ts

@@ -1,6 +1,6 @@
 import { LitElement, html } from "lit";
 import { customElement, query, state } from "lit/decorators.js";
-import { configApi, effectiveWorkspaceUploadFolder, piWebApi, sessionsApi, terminalsApi, workspacesApi, workspaceEffectiveUploadFolder, type Machine, type MachineHealth, type PiWebConfigValues, type PiWebShortcutConfig, type Project, type RealtimeEvent, type SessionCleanupExecuteResponse, type SessionCleanupPreviewResponse, type SessionCleanupRequest, type SessionInfo, type TerminalCommandRun, type TerminalUiEvent, type Workspace } from "../api";
+import { configApi, effectiveWorkspaceUploadFolder, sessionsApi, terminalsApi, workspacesApi, workspaceEffectiveUploadFolder, type Machine, type MachineHealth, type PiWebConfigValues, type PiWebShortcutConfig, type Project, type RealtimeEvent, type SessionCleanupExecuteResponse, type SessionCleanupPreviewResponse, type SessionCleanupRequest, type SessionInfo, type TerminalCommandRun, type TerminalUiEvent, type Workspace } from "../api";
 import type { AppAction } from "../actions";
 import { initialAppState, type AppState } from "../appState";
 import { isSessionActive } from "../../../shared/activity";
@@ -11,6 +11,7 @@ import { FileExplorerController } from "../controllers/fileExplorerController";
 import { GitController } from "../controllers/gitController";
 import { MachineController } from "../controllers/machineController";
 import { ProjectController } from "../controllers/projectController";
+import { PiWebStatusController } from "../controllers/piWebStatusController";
 import { SessionController } from "../controllers/sessionController";
 import { WorkspaceController, canDeleteWorkspace } from "../controllers/workspaceController";
 import { emptyMachineNavigationSnapshot, machineNavigationSnapshotFromState, routeFromMachineNavigationSnapshot, SessionStorageMachineNavigationMemory, type MachineNavigationSnapshot, type WorkspaceRouteSurface } from "../controllers/machineNavigationMemory";
@@ -132,6 +133,11 @@ export class PiWebApp extends LitElement {
     () => { this.updateUrl(); },
     this.projects,
   );
+  private readonly piWebStatusController = new PiWebStatusController(
+    () => this.state,
+    (patch) => { this.setState(patch); },
+    { onRefreshError: (machineId, error) => { console.warn(`Failed to refresh PI WEB status for ${machineId}`, error); } },
+  );
   private readonly files = new FileExplorerController(
     () => this.state,
     (patch) => { this.setState(patch); },
@@ -298,7 +304,7 @@ export class PiWebApp extends LitElement {
     this.clearScheduledPiWebStatusRefresh();
     this.piWebStatusDeferredTimer = window.setTimeout(() => {
       this.piWebStatusDeferredTimer = undefined;
-      void this.refreshPiWebStatus();
+      void this.piWebStatusController.refresh();
     }, delayMs);
   }
 
@@ -308,17 +314,6 @@ export class PiWebApp extends LitElement {
     this.piWebStatusDeferredTimer = undefined;
   }
 
-  private async refreshPiWebStatus(): Promise<void> {
-    const machineId = selectedMachineId(this.state);
-    try {
-      const piWebStatus = await piWebApi.piWebStatus(machineId);
-      if (selectedMachineId(this.state) === machineId) this.setState({ piWebStatus });
-    } catch (error) {
-      if (selectedMachineId(this.state) === machineId) this.setState({ piWebStatus: undefined });
-      console.warn(`Failed to refresh PI WEB status for ${machineId}`, error);
-    }
-  }
-
   private async refreshWorkspaceActivity(machineId = selectedMachineId(this.state)): Promise<void> {
     try {
       await this.activity.refresh(machineId);
@@ -1573,6 +1568,7 @@ export class PiWebApp extends LitElement {
       refreshFiles: () => this.files.refreshFiles(),
       refreshGit: () => this.git.refreshGit(),
       refreshAppData: () => this.refreshAppData(),
+      checkForPiWebUpdates: () => this.piWebStatusController.checkForUpdates(),
       reloadPage: () => { this.hardReloadApp(); },
       deleteWorkspace: (workspace) => this.deleteWorkspace(workspace),
       startSession: () => this.withChatScrollTransition(() => this.startSessionAndOpenChat()),

src/client/src/controllers/piWebStatusController.test.ts

@@ -0,0 +1,143 @@
+import { describe, expect, it, vi } from "vitest";
+import type { Machine, PiWebReleaseStatus, PiWebStatusResponse } from "../api";
+import { initialAppState, type AppState } from "../appState";
+import { PiWebStatusController, type PiWebStatusControllerDependencies } from "./piWebStatusController";
+
+type StatusApi = NonNullable<PiWebStatusControllerDependencies["api"]>;
+
+describe("PiWebStatusController", () => {
+  it("targets the selected machine and applies refreshed status", async () => {
+    const harness = createHarness("remote-a");
+    harness.piWebStatus.mockResolvedValue(status("remote"));
+
+    await harness.controller.refresh();
+
+    expect(harness.piWebStatus).toHaveBeenCalledWith("remote-a");
+    expect(harness.state().piWebStatus?.generatedAt).toBe("remote");
+  });
+
+  it("does not let an older periodic response overwrite a forced response", async () => {
+    const harness = createHarness();
+    const regular = createDeferred<PiWebStatusResponse>();
+    const forced = createDeferred<PiWebStatusResponse>();
+    harness.piWebStatus.mockReturnValue(regular.promise);
+    harness.checkForUpdates.mockReturnValue(forced.promise);
+
+    const regularRequest = harness.controller.refresh();
+    const forcedRequest = harness.controller.checkForUpdates();
+    forced.resolve(status("forced"));
+    await forcedRequest;
+    regular.resolve(status("regular"));
+    await regularRequest;
+
+    expect(harness.state().piWebStatus?.generatedAt).toBe("forced");
+  });
+
+  it("deduplicates forced checks and suppresses periodic refresh while one is pending", async () => {
+    const harness = createHarness();
+    const forced = createDeferred<PiWebStatusResponse>();
+    harness.checkForUpdates.mockReturnValue(forced.promise);
+
+    const first = harness.controller.checkForUpdates();
+    const second = harness.controller.checkForUpdates();
+    await harness.controller.refresh();
+
+    expect(second).toBe(first);
+    expect(harness.checkForUpdates).toHaveBeenCalledOnce();
+    expect(harness.piWebStatus).not.toHaveBeenCalled();
+
+    forced.resolve(status("forced"));
+    await first;
+  });
+
+  it("does not apply a response or error after the selected machine changes", async () => {
+    const harness = createHarness("remote-a");
+    const forced = createDeferred<PiWebStatusResponse>();
+    harness.checkForUpdates.mockReturnValue(forced.promise);
+
+    const request = harness.controller.checkForUpdates();
+    harness.selectMachine("remote-b");
+    forced.resolve(status("remote-a", { error: "registry unavailable" }));
+    await expect(request).resolves.toBeUndefined();
+
+    expect(harness.state().piWebStatus).toBeUndefined();
+  });
+
+  it.each([
+    [{ error: "registry unavailable" }, "PI WEB update check failed: registry unavailable"],
+    [{ skipped: true }, "PI WEB update check was skipped"],
+  ] as const)("applies status and rejects an unsuccessful manual check", async (release, message) => {
+    const harness = createHarness();
+    harness.checkForUpdates.mockResolvedValue(status("checked", release));
+
+    await expect(harness.controller.checkForUpdates()).rejects.toThrow(message);
+
+    expect(harness.state().piWebStatus?.generatedAt).toBe("checked");
+  });
+
+  it("clears current status and reports periodic refresh failures", async () => {
+    const harness = createHarness();
+    const error = new Error("offline");
+    harness.setStatus(status("old"));
+    harness.piWebStatus.mockRejectedValue(error);
+
+    await harness.controller.refresh();
+
+    expect(harness.state().piWebStatus).toBeUndefined();
+    expect(harness.onRefreshError).toHaveBeenCalledWith("local", error);
+  });
+});
+
+function createHarness(machineId = "local") {
+  let state: AppState = { ...initialAppState(), selectedMachine: machine(machineId) };
+  const piWebStatus = vi.fn<StatusApi["piWebStatus"]>();
+  const checkForUpdates = vi.fn<StatusApi["checkForUpdates"]>();
+  const onRefreshError = vi.fn<(machineId: string, error: unknown) => void>();
+  const controller = new PiWebStatusController(
+    () => state,
+    (patch) => { state = { ...state, ...patch }; },
+    { api: { piWebStatus, checkForUpdates }, onRefreshError },
+  );
+  return {
+    controller,
+    piWebStatus,
+    checkForUpdates,
+    onRefreshError,
+    state: () => state,
+    setStatus: (piWebStatusValue: PiWebStatusResponse) => { state = { ...state, piWebStatus: piWebStatusValue }; },
+    selectMachine: (id: string) => { state = { ...state, selectedMachine: machine(id) }; },
+  };
+}
+
+function machine(id: string): Machine {
+  return {
+    id,
+    name: id,
+    kind: id === "local" ? "local" : "remote",
+    ...(id === "local" ? {} : { baseUrl: `https://${id}.example.test` }),
+    createdAt: "now",
+    updatedAt: "now",
+  };
+}
+
+function status(generatedAt: string, release: Partial<PiWebReleaseStatus> = {}): PiWebStatusResponse {
+  return {
+    packageName: "@jmfederico/pi-web",
+    generatedAt,
+    components: {
+      web: { component: "web", label: "Web/UI", stale: false, available: true },
+      sessiond: { component: "sessiond", label: "Session daemon", stale: false, available: true },
+    },
+    release: { packageName: "@jmfederico/pi-web", updateAvailable: false, ...release },
+    commands: {},
+    messages: [],
+  };
+}
+
+function createDeferred<T>(): { promise: Promise<T>; resolve: (value: T) => void } {
+  let resolve: (value: T) => void = () => undefined;
+  const promise = new Promise<T>((innerResolve) => {
+    resolve = innerResolve;
+  });
+  return { promise, resolve };
+}

src/client/src/controllers/piWebStatusController.ts

@@ -0,0 +1,68 @@
+import { piWebApi, type PiWebStatusResponse } from "../api";
+import { selectedMachineId, type GetState, type SetState } from "./types";
+
+export interface PiWebStatusControllerDependencies {
+  api?: Pick<typeof piWebApi, "piWebStatus" | "checkForUpdates">;
+  onRefreshError?: (machineId: string, error: unknown) => void;
+}
+
+export class PiWebStatusController {
+  private readonly api: Pick<typeof piWebApi, "piWebStatus" | "checkForUpdates">;
+  private readonly onRefreshError: (machineId: string, error: unknown) => void;
+  private requestSequence = 0;
+  private pendingUpdateCheck: { machineId: string; requestSequence: number; promise: Promise<void> } | undefined;
+
+  constructor(
+    private readonly getState: GetState,
+    private readonly setState: SetState,
+    dependencies: PiWebStatusControllerDependencies = {},
+  ) {
+    this.api = dependencies.api ?? piWebApi;
+    this.onRefreshError = dependencies.onRefreshError ?? (() => undefined);
+  }
+
+  async refresh(): Promise<void> {
+    const machineId = selectedMachineId(this.getState());
+    if (this.pendingUpdateCheck?.machineId === machineId) return;
+    const requestSequence = ++this.requestSequence;
+    try {
+      const piWebStatus = await this.api.piWebStatus(machineId);
+      if (this.isCurrent(machineId, requestSequence)) this.setState({ piWebStatus });
+    } catch (error) {
+      if (!this.isCurrent(machineId, requestSequence)) return;
+      this.setState({ piWebStatus: undefined });
+      this.onRefreshError(machineId, error);
+    }
+  }
+
+  checkForUpdates(): Promise<void> {
+    const machineId = selectedMachineId(this.getState());
+    const existing = this.pendingUpdateCheck;
+    if (existing?.machineId === machineId) return existing.promise;
+
+    const requestSequence = ++this.requestSequence;
+    const promise = this.api.checkForUpdates(machineId)
+      .then((piWebStatus) => {
+        if (!this.isCurrent(machineId, requestSequence)) return;
+        this.setState({ piWebStatus });
+        throwForUnsuccessfulReleaseCheck(piWebStatus);
+      })
+      .catch((error: unknown) => {
+        if (this.isCurrent(machineId, requestSequence)) throw error;
+      })
+      .finally(() => {
+        if (this.pendingUpdateCheck?.requestSequence === requestSequence) this.pendingUpdateCheck = undefined;
+      });
+    this.pendingUpdateCheck = { machineId, requestSequence, promise };
+    return promise;
+  }
+
+  private isCurrent(machineId: string, requestSequence: number): boolean {
+    return selectedMachineId(this.getState()) === machineId && requestSequence === this.requestSequence;
+  }
+}
+
+function throwForUnsuccessfulReleaseCheck(status: PiWebStatusResponse): void {
+  if (status.release.error !== undefined) throw new Error(`PI WEB update check failed: ${status.release.error}`);
+  if (status.release.skipped === true) throw new Error("PI WEB update check was skipped because remote version checks are disabled by offline/version-check settings");
+}

src/client/src/plugins/types.ts

@@ -112,6 +112,7 @@ export interface PluginRuntimeContext {
   refreshFiles: () => void | Promise<void>;
   refreshGit: () => void | Promise<void>;
   refreshAppData: () => void | Promise<void>;
+  checkForPiWebUpdates?: () => void | Promise<void>;
   reloadPage: () => void;
   deleteWorkspace: (workspace?: Workspace) => void | Promise<void>;
   startSession: () => void | Promise<void>;

src/nativeServices/serviceDoctor.test.ts

@@ -0,0 +1,392 @@
+import { describe, expect, it } from "vitest";
+import {
+  formatNativeServiceDoctorResult,
+  inferInstalledNativeServiceMode,
+  inspectInstalledDevelopmentServiceInput,
+  inspectInstalledProductionServiceContext,
+  runNativeServiceDoctor,
+  type InstalledNativeServiceDefinition,
+  type NativeServiceDoctorTarget,
+} from "./serviceDoctor.js";
+import {
+  createDevelopmentNativeServicePlan,
+  type NativeServiceAuthoritativeProbe,
+  type NativeServicePlan,
+  type ProductionNativeServicePlanInput,
+} from "./servicePlan.js";
+import { renderLaunchdPlist, renderSystemdUnit } from "./serviceRendering.js";
+
+const shell = {
+  name: "zsh",
+  executable: "/bin/zsh",
+  source: "detected",
+  detectedExecutable: "/bin/zsh",
+} as const;
+
+function productionInput(configured = false): ProductionNativeServicePlanInput {
+  return {
+    backend: { kind: "systemd", label: "systemd user services" },
+    shell,
+    environment: { PI_WEB_CONFIG: "/home/user/config.json" },
+    executables: {
+      sessiond: {
+        configuredCommand: configured ? "custom sessiond --flag" : undefined,
+        namedCommand: "pi-web-sessiond",
+        bundledEntrypointPath: "/package/sessiond.js",
+      },
+      web: {
+        configuredCommand: configured ? "custom web --flag" : undefined,
+        namedCommand: "pi-web-server",
+        bundledEntrypointPath: "/package/server.js",
+      },
+    },
+  };
+}
+
+function probeWithStatus(status: "satisfied" | "unsatisfied"): NativeServiceAuthoritativeProbe {
+  return {
+    run: (request) => Promise.resolve({
+      kind: "completed",
+      outcomes: request.prerequisites.map((prerequisite) => ({
+        prerequisiteId: prerequisite.id,
+        status,
+        detail: status === "satisfied" ? null : `${prerequisite.id} missing in manager context`,
+      })),
+    }),
+  };
+}
+
+function developmentPlan(kind: "systemd" | "launchd"): NativeServicePlan {
+  return createDevelopmentNativeServicePlan({
+    backend: { kind, label: kind },
+    shell,
+    environment: { PI_WEB_CONFIG: "/home/user/config & dev.json" },
+    workingDirectory: "/checkout with space",
+    packageJsonPath: "/checkout with space/package.json",
+  });
+}
+
+function renderedDefinitions(plan: NativeServicePlan): InstalledNativeServiceDefinition[] {
+  return plan.services.map((service) => ({
+    id: service.id,
+    contents: plan.backend.kind === "systemd"
+      ? renderSystemdUnit(plan, service)
+      : renderLaunchdPlist(plan, service, "/tmp/logs"),
+  }));
+}
+
+describe("installed native-service mode and definition inspection", () => {
+  it("infers production, development, absent, and ambiguous service sets", () => {
+    expect(inferInstalledNativeServiceMode(new Set())).toBe("none");
+    expect(inferInstalledNativeServiceMode(new Set(["sessiond", "web"]))).toBe("production");
+    expect(inferInstalledNativeServiceMode(new Set(["sessiond", "uiDev"]))).toBe("development");
+    expect(inferInstalledNativeServiceMode(new Set(["web", "uiDev"]))).toBe("ambiguous");
+    expect(inferInstalledNativeServiceMode(new Set(["sessiond"]))).toBe("ambiguous");
+  });
+
+  it.each(["systemd", "launchd"] as const)("reconstructs POSIX development paths from %s definitions on every host", (kind) => {
+    const plan = developmentPlan(kind);
+    expect(inspectInstalledDevelopmentServiceInput(plan.backend, renderedDefinitions(plan))).toEqual({
+      ok: true,
+      value: {
+        backend: plan.backend,
+        shell,
+        environment: { PI_WEB_CONFIG: "/home/user/config & dev.json" },
+        workingDirectory: "/checkout with space",
+        packageJsonPath: "/checkout with space/package.json",
+      },
+    });
+  });
+
+  it("reconstructs escaped systemd paths, substitutions, and line controls exactly", () => {
+    const plan = createDevelopmentNativeServicePlan({
+      backend: { kind: "systemd", label: "systemd" },
+      shell: {
+        name: "zsh",
+        executable: "/shell $HOME/%h/zsh",
+        source: "detected",
+        detectedExecutable: "/shell $HOME/%h/zsh",
+      },
+      environment: { PI_WEB_CONFIG: "/config/%h\nnext" },
+      workingDirectory: "/checkout %h\nnext",
+      packageJsonPath: "/checkout %h\nnext/package.json",
+    });
+
+    expect(inspectInstalledDevelopmentServiceInput(plan.backend, renderedDefinitions(plan))).toEqual({
+      ok: true,
+      value: {
+        backend: plan.backend,
+        shell: plan.shell,
+        environment: plan.services[0]?.environment,
+        workingDirectory: "/checkout %h\nnext",
+        packageJsonPath: "/checkout %h\nnext/package.json",
+      },
+    });
+  });
+
+  it("interprets installed shell executable paths with POSIX semantics", () => {
+    const plan = developmentPlan("systemd");
+    const definitions = renderedDefinitions(plan).map((definition) => ({
+      ...definition,
+      contents: definition.contents.replace('"/bin/zsh"', '"/bin/not-zsh\\\\zsh"'),
+    }));
+
+    const inspection = inspectInstalledDevelopmentServiceInput(plan.backend, definitions);
+    expect(inspection.ok).toBe(false);
+    if (inspection.ok) throw new Error("Expected the POSIX shell basename inspection to fail");
+    expect(inspection.message).toContain("unsupported login shell");
+  });
+
+  it("inspects legacy systemd definitions without /usr/bin/env or quoted working directories", () => {
+    const plan = developmentPlan("systemd");
+    const definitions = renderedDefinitions(plan).map((definition) => ({
+      ...definition,
+      contents: definition.contents
+        .replace("ExecStart=/usr/bin/env ", "ExecStart=")
+        .replace("WorkingDirectory=/checkout\\x20with\\x20space", "WorkingDirectory=/checkout with space"),
+    }));
+
+    expect(inspectInstalledDevelopmentServiceInput(plan.backend, definitions)).toMatchObject({
+      ok: true,
+      value: { workingDirectory: "/checkout with space" },
+    });
+  });
+
+  it("rejects quoted systemd working directories that the manager treats as non-absolute", () => {
+    const plan = developmentPlan("systemd");
+    const definitions = renderedDefinitions(plan).map((definition) => ({
+      ...definition,
+      contents: definition.contents.replace(
+        "WorkingDirectory=/checkout\\x20with\\x20space",
+        'WorkingDirectory="/checkout with space"',
+      ),
+    }));
+
+    const inspection = inspectInstalledDevelopmentServiceInput(plan.backend, definitions);
+    expect(inspection.ok).toBe(false);
+    if (inspection.ok) throw new Error("Expected quoted working directory inspection to fail");
+    expect(inspection.message).toContain("invalid quoted working directory");
+  });
+
+  it("rejects unconsumed systemd environment syntax rather than checking a different context", () => {
+    const plan = developmentPlan("systemd");
+    const definitions = renderedDefinitions(plan).map((definition) => ({
+      ...definition,
+      contents: definition.contents.replace("[Service]\n", "[Service]\nEnvironment=PATH=/custom/bin\n"),
+    }));
+
+    const inspection = inspectInstalledDevelopmentServiceInput(plan.backend, definitions);
+    expect(inspection.ok).toBe(false);
+    if (inspection.ok) throw new Error("Expected systemd environment inspection to fail");
+    expect(inspection.message).toContain("environment entry");
+  });
+
+  it.each([
+    'Environment="PI_WEB_CONFIG=/config" "PATH=/broken"',
+    "EnvironmentFile=/tmp/pi-web.env",
+  ])("rejects noncanonical systemd environment context: %s", (directive) => {
+    const plan = developmentPlan("systemd");
+    const definitions = renderedDefinitions(plan).map((definition) => ({
+      ...definition,
+      contents: definition.contents.replace("[Service]\n", `[Service]\n${directive}\n`),
+    }));
+
+    expect(inspectInstalledDevelopmentServiceInput(plan.backend, definitions).ok).toBe(false);
+  });
+
+  it("rejects duplicate systemd ExecStart directives", () => {
+    const plan = developmentPlan("systemd");
+    const definitions = renderedDefinitions(plan).map((definition) => ({
+      ...definition,
+      contents: definition.contents.replace(
+        "Restart=no",
+        'ExecStart=/usr/bin/env "/bin/zsh" -lc "exec true"\nRestart=no',
+      ),
+    }));
+
+    const inspection = inspectInstalledDevelopmentServiceInput(plan.backend, definitions);
+    expect(inspection.ok).toBe(false);
+    if (inspection.ok) throw new Error("Expected duplicate ExecStart inspection to fail");
+    expect(inspection.message).toContain("exactly one recognized ExecStart");
+  });
+
+  it("rejects malformed launchd environment dictionaries rather than dropping entries", () => {
+    const plan = developmentPlan("launchd");
+    const definitions = renderedDefinitions(plan).map((definition) => ({
+      ...definition,
+      contents: definition.contents.replace(
+        "  </dict>\n  <key>RunAtLoad</key>",
+        "    <key>BROKEN</key>\n    <integer>1</integer>\n  </dict>\n  <key>RunAtLoad</key>",
+      ),
+    }));
+
+    const inspection = inspectInstalledDevelopmentServiceInput(plan.backend, definitions);
+    expect(inspection.ok).toBe(false);
+    if (inspection.ok) throw new Error("Expected launchd environment inspection to fail");
+    expect(inspection.message).toContain("environment dictionary");
+  });
+
+  it("rejects a modified development command rather than claiming to check the installed plan", () => {
+    const plan = developmentPlan("systemd");
+    const definitions = renderedDefinitions(plan);
+    const firstDefinition = definitions[0];
+    if (firstDefinition === undefined) throw new Error("Expected a rendered service definition");
+    definitions[0] = {
+      ...firstDefinition,
+      contents: firstDefinition.contents.replace("exec npm run start:sessiond", "exec npm run something-else"),
+    };
+
+    const inspection = inspectInstalledDevelopmentServiceInput(plan.backend, definitions);
+    expect(inspection.ok).toBe(false);
+    if (inspection.ok) throw new Error("Expected development inspection to fail");
+    expect(inspection.message).toContain("does not match the canonical development plan");
+  });
+
+  it("recovers production shell and environment while leaving executable strategy prospective", () => {
+    const plan = developmentPlan("launchd");
+    const firstService = plan.services[0];
+    if (firstService === undefined) throw new Error("Expected a development service");
+    const productionService = { ...firstService, workingDirectory: null };
+    const productionPlan: NativeServicePlan = { ...plan, mode: "production", services: [productionService] };
+    const productionLike = [{
+      id: "sessiond" as const,
+      contents: renderLaunchdPlist(productionPlan, productionService, "/tmp/logs"),
+    }];
+    expect(inspectInstalledProductionServiceContext(plan.backend, productionLike)).toEqual({
+      ok: true,
+      value: {
+        shell,
+        environment: { PI_WEB_CONFIG: "/home/user/config & dev.json" },
+      },
+    });
+  });
+});
+
+describe("native-service doctor planning and reporting", () => {
+  it("validates installed development requirements without production binary checks", async () => {
+    const plan = developmentPlan("launchd");
+    const inspected = inspectInstalledDevelopmentServiceInput(plan.backend, renderedDefinitions(plan));
+    if (!inspected.ok) throw new Error(inspected.message);
+
+    const result = await runNativeServiceDoctor(
+      { kind: "installed-development", input: inspected.value },
+      { probe: probeWithStatus("satisfied"), fileExists: () => false },
+    );
+    const report = formatNativeServiceDoctorResult(result);
+
+    expect(report.ok).toBe(true);
+    expect(report.lines).toContain("Installed development native-service plan:");
+    expect(report.plan?.services.flatMap((service) => service.prerequisites)).not.toEqual(
+      expect.arrayContaining([expect.objectContaining({ command: "pi-web-server" })]),
+    );
+  });
+
+  it("does not recommend PATH changes for checkout metadata failures", async () => {
+    const plan = developmentPlan("systemd");
+    const inspected = inspectInstalledDevelopmentServiceInput(plan.backend, renderedDefinitions(plan));
+    if (!inspected.ok) throw new Error(inspected.message);
+    const result = await runNativeServiceDoctor(
+      { kind: "installed-development", input: inspected.value },
+      {
+        probe: {
+          run: (request) => Promise.resolve({
+            kind: "completed",
+            outcomes: request.prerequisites.map((prerequisite) => ({
+              prerequisiteId: prerequisite.id,
+              status: prerequisite.kind === "package-scripts" ? "unsatisfied" as const : "satisfied" as const,
+              detail: prerequisite.kind === "package-scripts" ? "scripts missing" : null,
+            })),
+          }),
+        },
+        fileExists: () => true,
+      },
+    );
+    const report = formatNativeServiceDoctorResult(result);
+
+    expect(report).toMatchObject({ ok: false, failureKind: "requirements", pathAdviceRecommended: false });
+  });
+
+  it("labels a production check as prospective and reports manager-context requirements", async () => {
+    const target: NativeServiceDoctorTarget = {
+      kind: "prospective-production",
+      input: productionInput(),
+      reason: "installed executable strategy is not recorded",
+    };
+    const result = await runNativeServiceDoctor(target, {
+      probe: probeWithStatus("unsatisfied"),
+      fileExists: () => true,
+    });
+    const report = formatNativeServiceDoctorResult(result);
+
+    expect(report.ok).toBe(false);
+    expect(report.failureKind).toBe("requirements");
+    expect(report.lines[0]).toContain("Prospective production native-service plan");
+    expect(report.lines.join("\n")).toContain("Native service requirement failed");
+    expect(report.failedPrerequisites).toEqual(expect.arrayContaining([
+      expect.objectContaining({ kind: "node-version" }),
+      expect.objectContaining({ kind: "readable-file" }),
+    ]));
+  });
+
+  it("retains the installed production shell when resolution fails before a plan exists", async () => {
+    const result = await runNativeServiceDoctor(
+      { kind: "prospective-production", input: productionInput(), reason: "installed strategy is unknown" },
+      { probe: probeWithStatus("unsatisfied"), fileExists: () => false },
+    );
+    const report = formatNativeServiceDoctorResult(result);
+
+    expect(report).toMatchObject({
+      ok: false,
+      failureKind: "requirements",
+      plan: null,
+      adviceShell: shell,
+      pathAdviceRecommended: true,
+    });
+  });
+
+  it("preserves configured overrides as unverified and does not probe arbitrary commands", async () => {
+    let calls = 0;
+    const result = await runNativeServiceDoctor(
+      { kind: "prospective-production", input: productionInput(true), reason: "current configured overrides" },
+      {
+        probe: { run: () => { calls += 1; return Promise.resolve({ kind: "completed", outcomes: [] }); } },
+        fileExists: () => false,
+      },
+    );
+    const report = formatNativeServiceDoctorResult(result);
+
+    expect(calls).toBe(1);
+    expect(report.ok).toBe(true);
+    expect(report.lines.join("\n")).toContain("does not execute arbitrary configured commands");
+  });
+
+  it.each(["manager", "timeout", "malformed-output", "cleanup"] as const)(
+    "distinguishes %s infrastructure failures from PATH requirement drift",
+    async (reason) => {
+      const result = await runNativeServiceDoctor(
+        { kind: "prospective-production", input: productionInput(), reason: "no installed services" },
+        {
+          probe: { run: () => Promise.resolve({ kind: "infrastructure-failure", reason, message: `${reason} failure` }) },
+          fileExists: () => true,
+        },
+      );
+      const report = formatNativeServiceDoctorResult(result);
+
+      expect(report.ok).toBe(false);
+      expect(report.failureKind).toBe("infrastructure");
+      expect(report.lines.join("\n")).toContain(`infrastructure failure (${reason})`);
+      expect(report.lines.join("\n")).toContain("not proof of a PATH mismatch");
+    },
+  );
+
+  it("makes mixed or malformed installed definitions a failing inspection result", async () => {
+    const result = await runNativeServiceDoctor(
+      { kind: "inspection-failure", message: "production and development service IDs are both installed" },
+      { probe: probeWithStatus("satisfied"), fileExists: () => true },
+    );
+    const report = formatNativeServiceDoctorResult(result);
+
+    expect(report).toMatchObject({ ok: false, failureKind: "inspection" });
+    expect(report.lines.join("\n")).toContain("could not be inspected");
+  });
+});

src/nativeServices/serviceDoctor.ts

@@ -0,0 +1,591 @@
+import { posix as posixPath } from "node:path";
+import {
+  createDevelopmentNativeServicePlan,
+  nativeServicePrerequisiteNeedsPathAdvice,
+  resolveProductionNativeServicePlan,
+  validateNativeServicePlan,
+  type DevelopmentNativeServicePlanInput,
+  type NativeServiceBackend,
+  type NativeServiceId,
+  type NativeServicePlan,
+  type NativeServicePlanDependencies,
+  type NativeServicePlanFailure,
+  type NativeServicePlanValidationFailure,
+  type NativeServicePrerequisite,
+  type NativeServiceShell,
+  type ProductionNativeServicePlanInput,
+} from "./servicePlan.js";
+
+export type InstalledNativeServiceMode = "none" | "production" | "development" | "ambiguous";
+
+export interface InstalledNativeServiceDefinition {
+  id: NativeServiceId;
+  contents: string;
+}
+
+export interface InstalledNativeServiceContext {
+  shell: NativeServiceShell;
+  environment: Readonly<Record<string, string>>;
+}
+
+export type InstalledNativeServiceInspection<T> =
+  | { ok: true; value: T }
+  | { ok: false; message: string };
+
+export type NativeServiceDoctorTarget =
+  | {
+      kind: "installed-development";
+      input: DevelopmentNativeServicePlanInput;
+    }
+  | {
+      kind: "prospective-production";
+      input: ProductionNativeServicePlanInput;
+      reason: string;
+    }
+  | {
+      kind: "inspection-failure";
+      message: string;
+    };
+
+interface NativeServiceDoctorScope {
+  kind: "installed-development" | "prospective-production";
+  reason: string | null;
+  shell: NativeServiceShell;
+}
+
+export type NativeServiceDoctorResult =
+  | {
+      kind: "inspection-failure";
+      message: string;
+    }
+  | {
+      kind: "plan-resolution-failure";
+      scope: NativeServiceDoctorScope;
+      failures: readonly NativeServicePlanFailure[];
+    }
+  | {
+      kind: "plan-validation";
+      scope: NativeServiceDoctorScope;
+      plan: NativeServicePlan;
+      validation: { ok: true } | { ok: false; failures: readonly NativeServicePlanValidationFailure[] };
+    };
+
+export interface NativeServiceDoctorReport {
+  ok: boolean;
+  failureKind: "none" | "requirements" | "infrastructure" | "inspection";
+  lines: readonly string[];
+  plan: NativeServicePlan | null;
+  adviceShell: NativeServiceShell | null;
+  pathAdviceRecommended: boolean;
+  failedPrerequisites: readonly NativeServicePrerequisite[];
+}
+
+interface ParsedServiceDefinition {
+  id: NativeServiceId;
+  shell: NativeServiceShell;
+  environment: Readonly<Record<string, string>>;
+  workingDirectory: string | null;
+  shellCommand: string;
+}
+
+export function inferInstalledNativeServiceMode(serviceIds: ReadonlySet<NativeServiceId>): InstalledNativeServiceMode {
+  if (serviceIds.size === 0) return "none";
+  const hasProductionWeb = serviceIds.has("web");
+  const hasDevelopmentUi = serviceIds.has("uiDev");
+  if (hasProductionWeb && !hasDevelopmentUi) return "production";
+  if (hasDevelopmentUi && !hasProductionWeb) return "development";
+  return "ambiguous";
+}
+
+export function inspectInstalledProductionServiceContext(
+  backend: NativeServiceBackend,
+  definitions: readonly InstalledNativeServiceDefinition[],
+): InstalledNativeServiceInspection<InstalledNativeServiceContext> {
+  const parsed = parseConsistentDefinitions(backend, definitions);
+  if (!parsed.ok) return parsed;
+  const withWorkingDirectory = parsed.value.find((definition) => definition.workingDirectory !== null);
+  if (withWorkingDirectory !== undefined) {
+    return {
+      ok: false,
+      message: `Installed production service ${withWorkingDirectory.id} unexpectedly has working directory ${withWorkingDirectory.workingDirectory ?? ""}.`,
+    };
+  }
+  return {
+    ok: true,
+    value: {
+      shell: parsed.value[0]?.shell ?? impossibleMissingDefinition(),
+      environment: parsed.value[0]?.environment ?? impossibleMissingDefinition(),
+    },
+  };
+}
+
+export function inspectInstalledDevelopmentServiceInput(
+  backend: NativeServiceBackend,
+  definitions: readonly InstalledNativeServiceDefinition[],
+): InstalledNativeServiceInspection<DevelopmentNativeServicePlanInput> {
+  const parsed = parseConsistentDefinitions(backend, definitions);
+  if (!parsed.ok) return parsed;
+  const first = parsed.value[0] ?? impossibleMissingDefinition();
+  if (first.workingDirectory === null) {
+    return { ok: false, message: "Installed development services do not declare a working directory." };
+  }
+
+  const input: DevelopmentNativeServicePlanInput = {
+    backend,
+    shell: first.shell,
+    environment: first.environment,
+    workingDirectory: first.workingDirectory,
+    packageJsonPath: posixPath.join(first.workingDirectory, "package.json"),
+  };
+  const expectedPlan = createDevelopmentNativeServicePlan(input);
+  for (const definition of parsed.value) {
+    const expected = expectedPlan.services.find((service) => service.id === definition.id);
+    if (expected?.shellCommand !== definition.shellCommand) {
+      return {
+        ok: false,
+        message: `Installed ${definition.id} service command does not match the canonical development plan.`,
+      };
+    }
+  }
+  return { ok: true, value: input };
+}
+
+export async function runNativeServiceDoctor(
+  target: NativeServiceDoctorTarget,
+  dependencies: NativeServicePlanDependencies,
+): Promise<NativeServiceDoctorResult> {
+  if (target.kind === "inspection-failure") return target;
+
+  const scope: NativeServiceDoctorScope = target.kind === "installed-development"
+    ? { kind: target.kind, reason: null, shell: target.input.shell }
+    : { kind: target.kind, reason: target.reason, shell: target.input.shell };
+  let plan: NativeServicePlan;
+  if (target.kind === "installed-development") {
+    plan = createDevelopmentNativeServicePlan(target.input);
+  } else {
+    const resolution = await resolveProductionNativeServicePlan(target.input, dependencies);
+    if (!resolution.ok) {
+      return { kind: "plan-resolution-failure", scope, failures: resolution.failures };
+    }
+    plan = resolution.plan;
+  }
+
+  const validation = await validateNativeServicePlan(plan, dependencies.probe);
+  return { kind: "plan-validation", scope, plan, validation };
+}
+
+export function formatNativeServiceDoctorResult(result: NativeServiceDoctorResult): NativeServiceDoctorReport {
+  if (result.kind === "inspection-failure") {
+    return {
+      ok: false,
+      failureKind: "inspection",
+      lines: [
+        `✗ Installed native-service plan could not be inspected: ${result.message}`,
+        "  Run `pi-web install` or `pi-web install --dev` to replace mixed, partial, or outdated service definitions.",
+      ],
+      plan: null,
+      adviceShell: null,
+      pathAdviceRecommended: false,
+      failedPrerequisites: [],
+    };
+  }
+
+  const lines = [scopeHeading(result.scope)];
+  if (result.kind === "plan-resolution-failure") {
+    let infrastructure = false;
+    for (const failure of result.failures) {
+      if (failure.kind === "probe-infrastructure") {
+        infrastructure = true;
+        lines.push(`✗ Native service probe infrastructure failure (${failure.reason}): ${failure.message}`);
+      } else if (failure.kind === "entrypoint-inspection-failure") {
+        infrastructure = true;
+        lines.push(`✗ Could not inspect bundled ${failure.serviceId} entrypoint ${failure.entrypointPath}: ${failure.message}`);
+      } else {
+        lines.push(`✗ ${failure.namedCommand} is unavailable to the native service manager, and bundled entrypoint ${failure.bundledEntrypointPath} is missing.`);
+        if (failure.namedCommandFailure !== null) lines.push(`  ${failure.namedCommandFailure}`);
+      }
+    }
+    if (infrastructure) lines.push("  This infrastructure failure is not proof of a PATH mismatch.");
+    return {
+      ok: false,
+      failureKind: infrastructure ? "infrastructure" : "requirements",
+      lines,
+      plan: null,
+      adviceShell: result.scope.shell,
+      pathAdviceRecommended: !infrastructure
+        && result.failures.some((failure) => failure.kind === "executable-unavailable"),
+      failedPrerequisites: [],
+    };
+  }
+
+  const configuredOverrides = result.plan.services.filter((service) => service.strategy.kind === "configured-override");
+  for (const service of configuredOverrides) {
+    lines.push(`! ${service.description} uses a configured command override; doctor does not execute arbitrary configured commands.`);
+  }
+  if (result.validation.ok) {
+    lines.push("✓ All verifiable native-service plan requirements are satisfied in the service-manager context.");
+    return {
+      ok: true,
+      failureKind: "none",
+      lines,
+      plan: result.plan,
+      adviceShell: result.plan.shell,
+      pathAdviceRecommended: false,
+      failedPrerequisites: [],
+    };
+  }
+
+  const failedPrerequisites: NativeServicePrerequisite[] = [];
+  let infrastructure = false;
+  for (const failure of result.validation.failures) {
+    if (failure.kind === "probe-infrastructure") {
+      infrastructure = true;
+      lines.push(`✗ Native service probe infrastructure failure (${failure.reason}): ${failure.message}`);
+    } else {
+      failedPrerequisites.push(failure.prerequisite);
+      lines.push(`✗ Native service requirement failed: ${failure.prerequisite.description}`);
+      if (failure.detail !== null && failure.detail !== failure.prerequisite.description) lines.push(`  ${failure.detail}`);
+    }
+  }
+  if (infrastructure) lines.push("  This infrastructure failure is not proof of a PATH mismatch.");
+  return {
+    ok: false,
+    failureKind: infrastructure ? "infrastructure" : "requirements",
+    lines,
+    plan: result.plan,
+    adviceShell: result.plan.shell,
+    pathAdviceRecommended: !infrastructure
+      && failedPrerequisites.some(nativeServicePrerequisiteNeedsPathAdvice),
+    failedPrerequisites,
+  };
+}
+
+function scopeHeading(scope: NativeServiceDoctorScope): string {
+  if (scope.kind === "installed-development") return "Installed development native-service plan:";
+  return `Prospective production native-service plan (${scope.reason ?? "installed strategy is unknown"}):`;
+}
+
+function parseConsistentDefinitions(
+  backend: NativeServiceBackend,
+  definitions: readonly InstalledNativeServiceDefinition[],
+): InstalledNativeServiceInspection<readonly ParsedServiceDefinition[]> {
+  if (definitions.length === 0) return { ok: false, message: "No installed service definitions were provided." };
+
+  const parsed: ParsedServiceDefinition[] = [];
+  for (const definition of definitions) {
+    const result = backend.kind === "systemd"
+      ? parseSystemdDefinition(definition)
+      : parseLaunchdDefinition(definition);
+    if (!result.ok) return result;
+    parsed.push(result.value);
+  }
+
+  const first = parsed[0] ?? impossibleMissingDefinition();
+  for (const definition of parsed.slice(1)) {
+    if (definition.shell.executable !== first.shell.executable) {
+      return { ok: false, message: "Installed service definitions use different login shells." };
+    }
+    if (!recordsEqual(definition.environment, first.environment)) {
+      return { ok: false, message: "Installed service definitions use different environments." };
+    }
+    if (definition.workingDirectory !== first.workingDirectory) {
+      return { ok: false, message: "Installed service definitions use different working directories." };
+    }
+  }
+  return { ok: true, value: parsed };
+}
+
+interface ParsedSystemdDirective {
+  name: string;
+  value: string;
+}
+
+function systemdServiceDirectives(contents: string): ParsedSystemdDirective[] | undefined {
+  const allowed = new Set(["Type", "WorkingDirectory", "Environment", "ExecStart", "Restart", "RestartSec"]);
+  const directives: ParsedSystemdDirective[] = [];
+  let inServiceSection = false;
+  let foundServiceSection = false;
+  for (const line of contents.split(/\r?\n/u)) {
+    const trimmed = line.trim();
+    if (/^\[[^\]]+\]$/u.test(trimmed)) {
+      inServiceSection = trimmed === "[Service]";
+      foundServiceSection ||= inServiceSection;
+      continue;
+    }
+    if (!inServiceSection || trimmed === "" || trimmed.startsWith("#") || trimmed.startsWith(";")) continue;
+    const match = /^\s*([A-Za-z][A-Za-z0-9]*)=(.*)$/u.exec(line);
+    const name = match?.[1];
+    const value = match?.[2];
+    if (name === undefined || value === undefined || !allowed.has(name)) return undefined;
+    directives.push({ name, value });
+  }
+  return foundServiceSection ? directives : undefined;
+}
+
+function parseSystemdDefinition(
+  definition: InstalledNativeServiceDefinition,
+): InstalledNativeServiceInspection<ParsedServiceDefinition> {
+  const directives = systemdServiceDirectives(definition.contents);
+  if (directives === undefined) {
+    return { ok: false, message: `Installed ${definition.id} systemd unit has unrecognized service directives.` };
+  }
+  const execStarts = directives.filter((directive) => directive.name === "ExecStart");
+  const execStart = execStarts.length === 1
+    ? /^(?:\/usr\/bin\/env )?(.+?) -lc (.+)$/u.exec(execStarts[0]?.value ?? "")
+    : null;
+  if (execStart?.[1] === undefined || execStart[2] === undefined) {
+    return { ok: false, message: `Installed ${definition.id} systemd unit must have exactly one recognized ExecStart.` };
+  }
+  const shellExecutable = parseSystemdExecArgument(execStart[1]);
+  if (shellExecutable === undefined) {
+    return { ok: false, message: `Installed ${definition.id} systemd unit has an unrecognized login shell argument.` };
+  }
+  const shell = installedShell(shellExecutable);
+  if (!shell.ok) return shell;
+  const shellCommand = parseSystemdShellCommand(shell.value.name, execStart[2]);
+  if (shellCommand === undefined) {
+    return { ok: false, message: `Installed ${definition.id} systemd unit has an unrecognized shell command.` };
+  }
+
+  const environment: Record<string, string> = {};
+  for (const directive of directives.filter((item) => item.name === "Environment")) {
+    const rawValue = directive.value;
+    if (!/^"(?:\\.|[^"])*"$/u.test(rawValue)) {
+      return { ok: false, message: `Installed ${definition.id} systemd unit has an unrecognized environment entry.` };
+    }
+    const assignment = parseSystemdDirectiveValue(rawValue);
+    const separator = assignment?.indexOf("=") ?? -1;
+    const key = assignment?.slice(0, separator) ?? "";
+    if (separator <= 0 || Object.hasOwn(environment, key)) {
+      return { ok: false, message: `Installed ${definition.id} systemd unit has a malformed environment entry.` };
+    }
+    environment[key] = assignment?.slice(separator + 1) ?? "";
+  }
+
+  const workingDirectories = directives.filter((directive) => directive.name === "WorkingDirectory");
+  if (workingDirectories.length > 1) {
+    return { ok: false, message: `Installed ${definition.id} systemd unit has duplicate working directories.` };
+  }
+  const rawWorkingDirectory = workingDirectories[0]?.value;
+  if (rawWorkingDirectory?.startsWith('"') === true || rawWorkingDirectory?.startsWith("'") === true) {
+    return { ok: false, message: `Installed ${definition.id} systemd unit has an invalid quoted working directory.` };
+  }
+  const workingDirectory = rawWorkingDirectory === undefined
+    ? null
+    : parseSystemdDirectiveValue(rawWorkingDirectory);
+  if (workingDirectories.length === 1 && workingDirectory === undefined) {
+    return { ok: false, message: `Installed ${definition.id} systemd unit has a malformed working directory.` };
+  }
+
+  return {
+    ok: true,
+    value: { id: definition.id, shell: shell.value, environment, workingDirectory: workingDirectory ?? null, shellCommand },
+  };
+}
+
+function parseLaunchdDefinition(
+  definition: InstalledNativeServiceDefinition,
+): InstalledNativeServiceInspection<ParsedServiceDefinition> {
+  const argumentsMatches = [...definition.contents.matchAll(/<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/gu)];
+  const arguments_ = argumentsMatches.length === 1
+    ? parseXmlStringSequence(argumentsMatches[0]?.[1] ?? "")
+    : undefined;
+  if (arguments_?.length !== 4 || arguments_[0] !== "/usr/bin/env" || arguments_[2] !== "-lc") {
+    return { ok: false, message: `Installed ${definition.id} LaunchAgent has unrecognized ProgramArguments.` };
+  }
+  const shell = installedShell(arguments_[1] ?? "");
+  if (!shell.ok) return shell;
+
+  const environmentMatches = [...definition.contents.matchAll(/<key>EnvironmentVariables<\/key>\s*<dict>([\s\S]*?)<\/dict>/gu)];
+  const environmentKeyCount = [...definition.contents.matchAll(/<key>EnvironmentVariables<\/key>/gu)].length;
+  if (environmentMatches.length > 1 || environmentKeyCount !== environmentMatches.length) {
+    return { ok: false, message: `Installed ${definition.id} LaunchAgent has a malformed environment dictionary.` };
+  }
+  const environment = environmentMatches.length === 0
+    ? {}
+    : parseXmlStringDictionary(environmentMatches[0]?.[1] ?? "");
+  if (environment === undefined) {
+    return { ok: false, message: `Installed ${definition.id} LaunchAgent has a malformed environment dictionary.` };
+  }
+
+  const contentsWithoutEnvironment = environmentMatches[0]?.[0] === undefined
+    ? definition.contents
+    : definition.contents.replace(environmentMatches[0][0], "");
+  const workingDirectoryMatches = [...contentsWithoutEnvironment.matchAll(/<key>WorkingDirectory<\/key>\s*<string>([\s\S]*?)<\/string>/gu)];
+  const workingDirectoryKeyCount = [...contentsWithoutEnvironment.matchAll(/<key>WorkingDirectory<\/key>/gu)].length;
+  if (workingDirectoryMatches.length > 1 || workingDirectoryKeyCount !== workingDirectoryMatches.length) {
+    return { ok: false, message: `Installed ${definition.id} LaunchAgent has a malformed working directory.` };
+  }
+  const workingDirectory = workingDirectoryMatches[0]?.[1] === undefined
+    ? null
+    : xmlUnescapeStrict(workingDirectoryMatches[0][1]);
+  if (workingDirectoryMatches.length === 1 && workingDirectory === undefined) {
+    return { ok: false, message: `Installed ${definition.id} LaunchAgent has a malformed working directory.` };
+  }
+
+  return {
+    ok: true,
+    value: {
+      id: definition.id,
+      shell: shell.value,
+      environment,
+      workingDirectory: workingDirectory ?? null,
+      shellCommand: arguments_[3] ?? "",
+    },
+  };
+}
+
+function installedShell(executable: string): InstalledNativeServiceInspection<NativeServiceShell> {
+  const name = posixPath.basename(executable).replace(/^-/, "");
+  if (name !== "bash" && name !== "zsh" && name !== "fish") {
+    return { ok: false, message: `Installed service definition uses unsupported login shell ${executable}.` };
+  }
+  return {
+    ok: true,
+    value: { name, executable, source: "detected", detectedExecutable: executable },
+  };
+}
+
+function parseSystemdExecArgument(value: string): string | undefined {
+  const decoded = parseSystemdEscapedValue(value);
+  return decoded === undefined ? undefined : decodeSystemdSubstitutions(decoded, true);
+}
+
+function parseSystemdDirectiveValue(value: string): string | undefined {
+  const decoded = parseSystemdEscapedValue(value);
+  return decoded === undefined ? undefined : decodeSystemdSubstitutions(decoded, false);
+}
+
+function parseSystemdEscapedValue(value: string): string | undefined {
+  const quoted = value.startsWith('"') || value.endsWith('"');
+  if (quoted && (!value.startsWith('"') || !value.endsWith('"'))) return undefined;
+  return systemdUnescape(quoted ? value.slice(1, -1) : value);
+}
+
+function systemdUnescape(value: string): string | undefined {
+  let result = "";
+  for (let index = 0; index < value.length; index += 1) {
+    const character = value[index];
+    if (character !== "\\") {
+      result += character ?? "";
+      continue;
+    }
+
+    const escape = value[index + 1];
+    if (escape === undefined) return undefined;
+    const simpleEscapes: Readonly<Record<string, string>> = {
+      "\\": "\\",
+      '"': '"',
+      "'": "'",
+      a: "\u0007",
+      b: "\b",
+      e: "\u001b",
+      f: "\f",
+      n: "\n",
+      r: "\r",
+      s: " ",
+      t: "\t",
+      v: "\v",
+    };
+    const simple = simpleEscapes[escape];
+    if (simple !== undefined) {
+      result += simple;
+      index += 1;
+      continue;
+    }
+
+    const length = escape === "x" ? 2 : escape === "u" ? 4 : escape === "U" ? 8 : 0;
+    if (length === 0) return undefined;
+    const encoded = value.slice(index + 2, index + 2 + length);
+    if (encoded.length !== length || !new RegExp(`^[0-9a-fA-F]{${String(length)}}$`, "u").test(encoded)) return undefined;
+    const codePoint = Number.parseInt(encoded, 16);
+    if (codePoint === 0 || codePoint > 0x10ffff) return undefined;
+    result += String.fromCodePoint(codePoint);
+    index += length + 1;
+  }
+  return result;
+}
+
+function decodeSystemdSubstitutions(value: string, decodeDollars: boolean): string | undefined {
+  let result = "";
+  for (let index = 0; index < value.length; index += 1) {
+    const character = value[index];
+    if (character !== "%" && !(decodeDollars && character === "$")) {
+      result += character ?? "";
+      continue;
+    }
+    if (value[index + 1] !== character) return undefined;
+    result += character;
+    index += 1;
+  }
+  return result;
+}
+
+function parseSystemdShellCommand(shell: NativeServiceShell["name"], value: string): string | undefined {
+  if (value.startsWith('"') || value.endsWith('"')) return parseSystemdExecArgument(value);
+  if (!value.startsWith("'") || !value.endsWith("'")) return undefined;
+  const inner = value.slice(1, -1);
+  const unquoted = shell === "fish" ? fishSingleQuoteUnescape(inner) : inner.replaceAll("'\\''", "'");
+  return decodeSystemdSubstitutions(unquoted, true);
+}
+
+function fishSingleQuoteUnescape(value: string): string {
+  let result = "";
+  for (let index = 0; index < value.length; index += 1) {
+    const character = value[index];
+    if (character === "\\" && index + 1 < value.length) {
+      result += value[index + 1] ?? "";
+      index += 1;
+    } else {
+      result += character ?? "";
+    }
+  }
+  return result;
+}
+
+function parseXmlStringSequence(contents: string): string[] | undefined {
+  const values: string[] = [];
+  let cursor = 0;
+  for (const match of contents.matchAll(/<string>([\s\S]*?)<\/string>/gu)) {
+    if (contents.slice(cursor, match.index).trim() !== "") return undefined;
+    const value = xmlUnescapeStrict(match[1] ?? "");
+    if (value === undefined) return undefined;
+    values.push(value);
+    cursor = match.index + match[0].length;
+  }
+  return contents.slice(cursor).trim() === "" ? values : undefined;
+}
+
+function parseXmlStringDictionary(contents: string): Record<string, string> | undefined {
+  const values: Record<string, string> = {};
+  let cursor = 0;
+  for (const match of contents.matchAll(/<key>([\s\S]*?)<\/key>\s*<string>([\s\S]*?)<\/string>/gu)) {
+    if (contents.slice(cursor, match.index).trim() !== "") return undefined;
+    const key = xmlUnescapeStrict(match[1] ?? "");
+    const value = xmlUnescapeStrict(match[2] ?? "");
+    if (key === undefined || value === undefined || Object.hasOwn(values, key)) return undefined;
+    values[key] = value;
+    cursor = match.index + match[0].length;
+  }
+  return contents.slice(cursor).trim() === "" ? values : undefined;
+}
+
+function xmlUnescapeStrict(value: string): string | undefined {
+  if (/[<>]/u.test(value) || /&(?!(?:apos|quot|gt|lt|amp);)/u.test(value)) return undefined;
+  return value
+    .replaceAll("&apos;", "'")
+    .replaceAll("&quot;", '"')
+    .replaceAll("&gt;", ">")
+    .replaceAll("&lt;", "<")
+    .replaceAll("&amp;", "&");
+}
+
+function recordsEqual(left: Readonly<Record<string, string>>, right: Readonly<Record<string, string>>): boolean {
+  const leftEntries = Object.entries(left);
+  return leftEntries.length === Object.keys(right).length
+    && leftEntries.every(([key, value]) => right[key] === value);
+}
+
+function impossibleMissingDefinition(): never {
+  throw new Error("Expected at least one installed native service definition");
+}

src/nativeServices/serviceInstall.test.ts

@@ -0,0 +1,182 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  installNativeServiceCandidate,
+  nativeServiceInstallFailureNeedsPathAdvice,
+} from "./serviceInstall.js";
+import type {
+  NativeServiceAuthoritativeProbe,
+  NativeServicePlan,
+  NativeServiceProbeRequest,
+  ProductionNativeServicePlanInput,
+} from "./servicePlan.js";
+
+const productionInput: ProductionNativeServicePlanInput = {
+  backend: { kind: "systemd", label: "systemd user services" },
+  shell: {
+    name: "bash",
+    executable: "/bin/bash",
+    source: "detected",
+    detectedExecutable: "/bin/bash",
+  },
+  environment: { PI_WEB_CONFIG: "/home/user/config.json" },
+  executables: {
+    sessiond: {
+      configuredCommand: undefined,
+      namedCommand: "pi-web-sessiond",
+      bundledEntrypointPath: "/package/sessiond.js",
+    },
+    web: {
+      configuredCommand: undefined,
+      namedCommand: "pi-web-server",
+      bundledEntrypointPath: "/package/server.js",
+    },
+  },
+};
+
+function successfulProbe(events: string[]): NativeServiceAuthoritativeProbe {
+  return {
+    run: (request) => {
+      events.push(`probe:${request.purpose}`);
+      return Promise.resolve({
+        kind: "completed",
+        outcomes: request.prerequisites.map((prerequisite) => ({
+          prerequisiteId: prerequisite.id,
+          status: "satisfied" as const,
+          detail: null,
+        })),
+      });
+    },
+  };
+}
+
+describe("native service install orchestration", () => {
+  it("resolves and validates the complete plan before writing config or replacing services", async () => {
+    const events: string[] = [];
+    const writeInitialConfig = vi.fn(() => { events.push("write-config"); return Promise.resolve(); });
+    const replaceServices = vi.fn((plan: NativeServicePlan) => {
+      events.push(`replace:${plan.mode}`);
+      return Promise.resolve();
+    });
+
+    const result = await installNativeServiceCandidate(
+      { mode: "production", input: productionInput },
+      {
+        probe: successfulProbe(events),
+        fileExists: () => false,
+        writeInitialConfig,
+        replaceServices,
+      },
+    );
+
+    expect(result.ok).toBe(true);
+    expect(events).toEqual([
+      "probe:executable-selection",
+      "probe:plan-validation",
+      "write-config",
+      "replace:production",
+    ]);
+    expect(writeInitialConfig).toHaveBeenCalledOnce();
+    expect(replaceServices).toHaveBeenCalledWith(expect.objectContaining({ mode: "production" }));
+  });
+
+  it("validates manager and shell readiness without executing configured overrides", async () => {
+    const writeInitialConfig = vi.fn<() => Promise<void>>(() => Promise.resolve());
+    const replaceServices = vi.fn<() => Promise<void>>(() => Promise.resolve());
+    const requests: NativeServiceProbeRequest[] = [];
+    const configuredInput: ProductionNativeServicePlanInput = {
+      ...productionInput,
+      executables: {
+        sessiond: { ...productionInput.executables.sessiond, configuredCommand: "custom-sessiond --flag" },
+        web: { ...productionInput.executables.web, configuredCommand: "custom-web --flag" },
+      },
+    };
+
+    const result = await installNativeServiceCandidate(
+      { mode: "production", input: configuredInput },
+      {
+        probe: {
+          run: (request) => {
+            requests.push(request);
+            return Promise.resolve({ kind: "infrastructure-failure", reason: "manager", message: "manager unavailable" });
+          },
+        },
+        fileExists: () => false,
+        writeInitialConfig,
+        replaceServices,
+      },
+    );
+
+    expect(result).toMatchObject({ ok: false, failure: { kind: "plan-validation" } });
+    if (result.ok) throw new Error("Expected manager validation failure");
+    expect(nativeServiceInstallFailureNeedsPathAdvice(result.failure)).toBe(false);
+    expect(requests).toEqual([expect.objectContaining({ purpose: "plan-validation", prerequisites: [] })]);
+    expect(writeInitialConfig).not.toHaveBeenCalled();
+    expect(replaceServices).not.toHaveBeenCalled();
+  });
+
+  it("does not make durable changes when exact plan requirements are unsatisfied", async () => {
+    const writeInitialConfig = vi.fn<() => Promise<void>>(() => Promise.resolve());
+    const replaceServices = vi.fn<() => Promise<void>>(() => Promise.resolve());
+    const probe: NativeServiceAuthoritativeProbe = {
+      run: (request: NativeServiceProbeRequest) => Promise.resolve({
+        kind: "completed",
+        outcomes: request.prerequisites.map((prerequisite) => ({
+          prerequisiteId: prerequisite.id,
+          status: request.purpose === "plan-validation" ? "unsatisfied" : "satisfied",
+          detail: "not visible in the service manager environment",
+        })),
+      }),
+    };
+
+    const result = await installNativeServiceCandidate(
+      { mode: "production", input: productionInput },
+      { probe, fileExists: () => false, writeInitialConfig, replaceServices },
+    );
+
+    expect(result).toMatchObject({ ok: false, failure: { kind: "plan-validation" } });
+    if (result.ok || result.failure.kind !== "plan-validation") throw new Error("Expected validation failure");
+    expect(result.failure.failures).not.toHaveLength(0);
+    expect(result.failure.failures.every((failure) => failure.kind === "prerequisite-unsatisfied")).toBe(true);
+    expect(nativeServiceInstallFailureNeedsPathAdvice(result.failure)).toBe(true);
+    expect(writeInitialConfig).not.toHaveBeenCalled();
+    expect(replaceServices).not.toHaveBeenCalled();
+  });
+
+  it("does not mislabel probe infrastructure failures or write anything", async () => {
+    const writeInitialConfig = vi.fn<() => Promise<void>>(() => Promise.resolve());
+    const replaceServices = vi.fn<() => Promise<void>>(() => Promise.resolve());
+
+    const result = await installNativeServiceCandidate(
+      { mode: "production", input: productionInput },
+      {
+        probe: {
+          run: () => Promise.resolve({
+            kind: "infrastructure-failure",
+            reason: "timeout",
+            message: "service manager probe timed out",
+          }),
+        },
+        fileExists: () => true,
+        writeInitialConfig,
+        replaceServices,
+      },
+    );
+
+    expect(result).toEqual({
+      ok: false,
+      failure: {
+        kind: "plan-resolution",
+        failures: [{
+          kind: "probe-infrastructure",
+          serviceIds: ["sessiond", "web"],
+          reason: "timeout",
+          message: "service manager probe timed out",
+        }],
+      },
+    });
+    if (result.ok) throw new Error("Expected infrastructure failure");
+    expect(nativeServiceInstallFailureNeedsPathAdvice(result.failure)).toBe(false);
+    expect(writeInitialConfig).not.toHaveBeenCalled();
+    expect(replaceServices).not.toHaveBeenCalled();
+  });
+});

src/nativeServices/serviceInstall.ts

@@ -0,0 +1,71 @@
+import {
+  createDevelopmentNativeServicePlan,
+  nativeServicePrerequisiteNeedsPathAdvice,
+  resolveProductionNativeServicePlan,
+  validateNativeServicePlan,
+  type DevelopmentNativeServicePlanInput,
+  type NativeServiceAuthoritativeProbe,
+  type NativeServicePlan,
+  type NativeServicePlanDependencies,
+  type NativeServicePlanFailure,
+  type NativeServicePlanValidationFailure,
+  type ProductionNativeServicePlanInput,
+} from "./servicePlan.js";
+
+export type NativeServiceInstallCandidate =
+  | { mode: "production"; input: ProductionNativeServicePlanInput }
+  | { mode: "development"; input: DevelopmentNativeServicePlanInput };
+
+export interface NativeServiceInstallDependencies extends NativeServicePlanDependencies {
+  probe: NativeServiceAuthoritativeProbe;
+  writeInitialConfig(): Promise<void>;
+  replaceServices(plan: NativeServicePlan): Promise<void>;
+}
+
+export type NativeServiceInstallFailure =
+  | { kind: "plan-resolution"; failures: readonly NativeServicePlanFailure[] }
+  | { kind: "plan-validation"; failures: readonly NativeServicePlanValidationFailure[] };
+
+export type NativeServiceInstallResult =
+  | { ok: true; plan: NativeServicePlan }
+  | { ok: false; failure: NativeServiceInstallFailure };
+
+export function nativeServiceInstallFailureNeedsPathAdvice(failure: NativeServiceInstallFailure): boolean {
+  if (failure.kind === "plan-resolution") {
+    return failure.failures.every((item) => item.kind === "executable-unavailable")
+      && failure.failures.length > 0;
+  }
+  return failure.failures.some((item) =>
+    item.kind === "prerequisite-unsatisfied"
+    && nativeServicePrerequisiteNeedsPathAdvice(item.prerequisite));
+}
+
+/**
+ * Keeps preflight effects ahead of durable install effects. The authoritative
+ * probes may create bounded temporary artifacts, but they must clean those up
+ * before this function writes config or replaces existing services.
+ */
+export async function installNativeServiceCandidate(
+  candidate: NativeServiceInstallCandidate,
+  dependencies: NativeServiceInstallDependencies,
+): Promise<NativeServiceInstallResult> {
+  let plan: NativeServicePlan;
+  if (candidate.mode === "production") {
+    const resolution = await resolveProductionNativeServicePlan(candidate.input, dependencies);
+    if (!resolution.ok) {
+      return { ok: false, failure: { kind: "plan-resolution", failures: resolution.failures } };
+    }
+    plan = resolution.plan;
+  } else {
+    plan = createDevelopmentNativeServicePlan(candidate.input);
+  }
+
+  const validation = await validateNativeServicePlan(plan, dependencies.probe);
+  if (!validation.ok) {
+    return { ok: false, failure: { kind: "plan-validation", failures: validation.failures } };
+  }
+
+  await dependencies.writeInitialConfig();
+  await dependencies.replaceServices(plan);
+  return { ok: true, plan };
+}

src/nativeServices/servicePlan.test.ts

@@ -0,0 +1,373 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  createDevelopmentNativeServicePlan,
+  planValidationProbeRequests,
+  resolveProductionNativeServicePlan,
+  type NativeServiceAuthoritativeProbe,
+  type NativeServiceProbeRequest,
+  type NativeServiceProbeResult,
+  type ProductionNativeServicePlanInput,
+} from "./servicePlan.js";
+
+const backend = { kind: "systemd", label: "systemd user services" } as const;
+const shell = {
+  name: "zsh",
+  executable: "/bin/zsh",
+  source: "detected",
+  detectedExecutable: "/bin/zsh",
+} as const;
+
+function productionInput(): ProductionNativeServicePlanInput {
+  return {
+    backend,
+    shell,
+    environment: { PI_WEB_CONFIG: "/home/user/.config/pi-web/config.json" },
+    executables: {
+      sessiond: {
+        configuredCommand: undefined,
+        namedCommand: "pi-web-sessiond",
+        bundledEntrypointPath: "/package/dist/server/sessiond.js",
+      },
+      web: {
+        configuredCommand: undefined,
+        namedCommand: "pi-web-server",
+        bundledEntrypointPath: "/package/dist/server/index.js",
+      },
+    },
+  };
+}
+
+function completedProbe(status: "satisfied" | "unsatisfied", detail: string | null = null): NativeServiceAuthoritativeProbe {
+  return {
+    run: (request) => Promise.resolve({
+      kind: "completed",
+      outcomes: request.prerequisites.map((prerequisite) => ({ prerequisiteId: prerequisite.id, status, detail })),
+    }),
+  };
+}
+
+describe("production native service planning", () => {
+  it("selects named commands from one authoritative backend probe and carries their exact requirements", async () => {
+    const requests: NativeServiceProbeRequest[] = [];
+    const probe: NativeServiceAuthoritativeProbe = {
+      run: (request) => {
+        requests.push(request);
+        return Promise.resolve({
+          kind: "completed",
+          outcomes: request.prerequisites.map((prerequisite) => ({
+            prerequisiteId: prerequisite.id,
+            status: "satisfied",
+            detail: "/usr/local/bin/example",
+          })),
+        });
+      },
+    };
+
+    const resolution = await resolveProductionNativeServicePlan(productionInput(), {
+      probe,
+      fileExists: () => false,
+    });
+
+    expect(requests).toEqual([
+      {
+        purpose: "executable-selection",
+        backend,
+        shell,
+        environment: { PI_WEB_CONFIG: "/home/user/.config/pi-web/config.json" },
+        workingDirectory: null,
+        prerequisites: [
+          expect.objectContaining({ id: "sessiond.command.pi-web-sessiond", kind: "command-available", command: "pi-web-sessiond" }),
+          expect.objectContaining({ id: "web.command.pi-web-server", kind: "command-available", command: "pi-web-server" }),
+        ],
+      },
+    ]);
+    expect(resolution.ok).toBe(true);
+    if (!resolution.ok) throw new Error(JSON.stringify(resolution.failures));
+
+    expect(resolution.plan).toMatchObject({
+      mode: "production",
+      backend,
+      shell,
+      services: [
+        {
+          id: "sessiond",
+          manager: { systemdName: "pi-web-sessiond.service", launchdLabel: "com.pi-web.sessiond" },
+          shellCommand: "exec pi-web-sessiond",
+          strategy: { kind: "named-command", command: "pi-web-sessiond", selectedBy: "authoritative-backend-probe" },
+          environment: { PI_WEB_CONFIG: "/home/user/.config/pi-web/config.json" },
+          workingDirectory: null,
+          after: [],
+          wants: [],
+          prerequisites: [
+            { id: "sessiond.command.pi-web-sessiond", kind: "command-available", command: "pi-web-sessiond" },
+            { id: "sessiond.node", kind: "node-version", command: "node", minimumMajor: 22 },
+          ],
+        },
+        {
+          id: "web",
+          shellCommand: "exec pi-web-server",
+          strategy: { kind: "named-command", command: "pi-web-server" },
+          after: ["sessiond"],
+          wants: ["sessiond"],
+          prerequisites: [
+            { id: "web.command.pi-web-server", kind: "command-available", command: "pi-web-server" },
+            { id: "web.node", kind: "node-version", command: "node", minimumMajor: 22 },
+          ],
+        },
+      ],
+    });
+
+    expect(planValidationProbeRequests(resolution.plan)).toMatchObject([
+      {
+        purpose: "plan-validation",
+        backend,
+        shell,
+        workingDirectory: null,
+        prerequisites: [
+          { id: "sessiond.command.pi-web-sessiond" },
+          { id: "sessiond.node" },
+          { id: "web.command.pi-web-server" },
+          { id: "web.node" },
+        ],
+      },
+    ]);
+  });
+
+  it("preserves configured overrides verbatim and never probes or executes them", async () => {
+    const input = productionInput();
+    input.executables.sessiond.configuredCommand = "  /opt/pi web/run-sessiond --flag  ";
+    input.executables.web.configuredCommand = "custom-web --serve";
+    const run = vi.fn<(request: NativeServiceProbeRequest) => Promise<NativeServiceProbeResult>>();
+    const fileExists = vi.fn<(path: string) => boolean>();
+
+    const resolution = await resolveProductionNativeServicePlan(input, { probe: { run }, fileExists });
+
+    expect(run).not.toHaveBeenCalled();
+    expect(fileExists).not.toHaveBeenCalled();
+    expect(resolution.ok).toBe(true);
+    if (!resolution.ok) throw new Error(JSON.stringify(resolution.failures));
+    expect(resolution.plan.services).toMatchObject([
+      {
+        id: "sessiond",
+        shellCommand: "exec   /opt/pi web/run-sessiond --flag  ",
+        strategy: {
+          kind: "configured-override",
+          command: "  /opt/pi web/run-sessiond --flag  ",
+          verification: "unverified",
+        },
+        prerequisites: [],
+      },
+      {
+        id: "web",
+        shellCommand: "exec custom-web --serve",
+        strategy: { kind: "configured-override", command: "custom-web --serve", verification: "unverified" },
+        prerequisites: [],
+      },
+    ]);
+    expect(planValidationProbeRequests(resolution.plan)).toEqual([{
+      purpose: "plan-validation",
+      backend,
+      shell,
+      environment: { PI_WEB_CONFIG: "/home/user/.config/pi-web/config.json" },
+      workingDirectory: null,
+      prerequisites: [],
+    }]);
+  });
+
+  it("falls back per service to bundled entrypoints when named commands are unavailable", async () => {
+    const input = productionInput();
+    input.executables.sessiond.bundledEntrypointPath = "/package with space/sessiond's entry.js";
+    const fileExists = vi.fn<(path: string) => boolean>(() => true);
+
+    const resolution = await resolveProductionNativeServicePlan(input, {
+      probe: completedProbe("unsatisfied", "command not found"),
+      fileExists,
+    });
+
+    expect(fileExists).toHaveBeenCalledTimes(2);
+    expect(resolution.ok).toBe(true);
+    if (!resolution.ok) throw new Error(JSON.stringify(resolution.failures));
+    expect(resolution.plan.services[0]).toMatchObject({
+      shellCommand: "exec node '/package with space/sessiond'\\''s entry.js'",
+      strategy: {
+        kind: "bundled-entrypoint",
+        command: "node",
+        namedCommand: "pi-web-sessiond",
+        namedCommandFailure: "command not found",
+      },
+      prerequisites: [
+        { id: "sessiond.node", kind: "node-version", command: "node", minimumMajor: 22 },
+        { id: "sessiond.entrypoint", kind: "readable-file", path: "/package with space/sessiond's entry.js" },
+      ],
+    });
+  });
+
+  it("mixes configured, named, and bundled decisions without unrelated checks", async () => {
+    const input = productionInput();
+    input.executables.sessiond.configuredCommand = "custom-sessiond";
+    const requests: NativeServiceProbeRequest[] = [];
+
+    const resolution = await resolveProductionNativeServicePlan(input, {
+      probe: {
+        run: (request) => {
+          requests.push(request);
+          return Promise.resolve({
+            kind: "completed",
+            outcomes: [{ prerequisiteId: "web.command.pi-web-server", status: "unsatisfied", detail: null }],
+          });
+        },
+      },
+      fileExists: () => true,
+    });
+
+    expect(requests[0]?.prerequisites).toMatchObject([{ id: "web.command.pi-web-server", command: "pi-web-server" }]);
+    expect(resolution.ok).toBe(true);
+    if (resolution.ok) {
+      expect(resolution.plan.services.map((service) => service.strategy.kind)).toEqual(["configured-override", "bundled-entrypoint"]);
+    }
+  });
+
+  it("returns structured failures when neither production executable strategy is viable", async () => {
+    const resolution = await resolveProductionNativeServicePlan(productionInput(), {
+      probe: completedProbe("unsatisfied", "not found in service PATH"),
+      fileExists: () => false,
+    });
+
+    expect(resolution).toEqual({
+      ok: false,
+      failures: [
+        {
+          kind: "executable-unavailable",
+          serviceId: "sessiond",
+          namedCommand: "pi-web-sessiond",
+          namedCommandFailure: "not found in service PATH",
+          bundledEntrypointPath: "/package/dist/server/sessiond.js",
+        },
+        {
+          kind: "executable-unavailable",
+          serviceId: "web",
+          namedCommand: "pi-web-server",
+          namedCommandFailure: "not found in service PATH",
+          bundledEntrypointPath: "/package/dist/server/index.js",
+        },
+      ],
+    });
+  });
+
+  it("does not reinterpret probe infrastructure failures as missing commands", async () => {
+    const fileExists = vi.fn<(path: string) => boolean>(() => true);
+    const resolution = await resolveProductionNativeServicePlan(productionInput(), {
+      probe: {
+        run: () => Promise.resolve({ kind: "infrastructure-failure", reason: "cleanup", message: "launchd probe cleanup failed" }),
+      },
+      fileExists,
+    });
+
+    expect(fileExists).not.toHaveBeenCalled();
+    expect(resolution).toEqual({
+      ok: false,
+      failures: [{
+        kind: "probe-infrastructure",
+        serviceIds: ["sessiond", "web"],
+        reason: "cleanup",
+        message: "launchd probe cleanup failed",
+      }],
+    });
+  });
+
+  it("treats thrown and malformed probe results as infrastructure failures", async () => {
+    const thrown = await resolveProductionNativeServicePlan(productionInput(), {
+      probe: { run: () => Promise.reject(new Error("systemd-run failed")) },
+      fileExists: () => true,
+    });
+    expect(thrown).toMatchObject({
+      ok: false,
+      failures: [{ kind: "probe-infrastructure", reason: "manager", message: "systemd-run failed" }],
+    });
+
+    const malformed = await resolveProductionNativeServicePlan(productionInput(), {
+      probe: {
+        run: () => Promise.resolve({
+          kind: "completed",
+          outcomes: [{ prerequisiteId: "sessiond.command.pi-web-sessiond", status: "satisfied", detail: null }],
+        }),
+      },
+      fileExists: () => true,
+    });
+    expect(malformed).toMatchObject({
+      ok: false,
+      failures: [{ kind: "probe-infrastructure", reason: "malformed-output", message: "Authoritative probe returned no outcome for web.command.pi-web-server." }],
+    });
+  });
+});
+
+describe("development native service planning", () => {
+  it("plans only the exact checkout commands and prerequisites", () => {
+    const plan = createDevelopmentNativeServicePlan({
+      backend: { kind: "launchd", label: "LaunchAgents" },
+      shell: { name: "fish", executable: "/opt/homebrew/bin/fish", source: "detected", detectedExecutable: "/opt/homebrew/bin/fish" },
+      environment: { PI_WEB_CONFIG: "/tmp/config.json" },
+      workingDirectory: "/checkout with space",
+      packageJsonPath: "/checkout with space/package.json",
+    });
+
+    expect(plan).toMatchObject({
+      mode: "development",
+      backend: { kind: "launchd" },
+      shell: { name: "fish", executable: "/opt/homebrew/bin/fish" },
+      services: [
+        {
+          id: "sessiond",
+          shellCommand: "exec npm run start:sessiond",
+          strategy: { kind: "development-npm-script", script: "start:sessiond" },
+          restart: "never",
+          environment: { PI_WEB_CONFIG: "/tmp/config.json" },
+          workingDirectory: "/checkout with space",
+          prerequisites: [
+            { id: "sessiond.node", kind: "node-version", minimumMajor: 22 },
+            { id: "sessiond.command.npm", kind: "command-available", command: "npm" },
+            { id: "sessiond.package-scripts", kind: "package-scripts", scripts: ["start:sessiond"] },
+          ],
+        },
+        {
+          id: "uiDev",
+          shellCommand: "exec /usr/bin/env bash -c 'trap \"kill 0\" EXIT; npm run dev:web & npm run dev:client & wait'",
+          strategy: { kind: "development-npm-script-group", scripts: ["dev:web", "dev:client"], interpreter: "bash" },
+          restart: "never",
+          workingDirectory: "/checkout with space",
+          after: ["sessiond"],
+          wants: ["sessiond"],
+          prerequisites: [
+            { id: "uiDev.node", kind: "node-version", minimumMajor: 22 },
+            { id: "uiDev.command.npm", kind: "command-available", command: "npm" },
+            { id: "uiDev.command.bash", kind: "command-available", command: "bash" },
+            { id: "uiDev.package-scripts", kind: "package-scripts", scripts: ["dev:web", "dev:client"] },
+          ],
+        },
+      ],
+    });
+
+    const serviceCommandRequirements = plan.services.flatMap((service) => service.prerequisites)
+      .filter((prerequisite) => prerequisite.kind === "command-available")
+      .map((prerequisite) => prerequisite.command);
+    expect(serviceCommandRequirements).toEqual(["npm", "npm", "bash"]);
+    expect(serviceCommandRequirements).not.toContain("pi-web-server");
+    expect(serviceCommandRequirements).not.toContain("pi-web-sessiond");
+
+    expect(planValidationProbeRequests(plan)).toMatchObject([
+      {
+        backend: { kind: "launchd" },
+        workingDirectory: "/checkout with space",
+        prerequisites: [
+          { id: "sessiond.node" },
+          { id: "sessiond.command.npm" },
+          { id: "sessiond.package-scripts" },
+          { id: "uiDev.node" },
+          { id: "uiDev.command.npm" },
+          { id: "uiDev.command.bash" },
+          { id: "uiDev.package-scripts" },
+        ],
+      },
+    ]);
+  });
+});

src/nativeServices/servicePlan.ts

@@ -0,0 +1,623 @@
+export type NativeServiceBackendKind = "systemd" | "launchd";
+export type NativeServiceMode = "production" | "development";
+export type NativeServiceId = "sessiond" | "web" | "uiDev";
+export type ProductionNativeServiceId = Extract<NativeServiceId, "sessiond" | "web">;
+export type NativeServiceShellName = "bash" | "zsh" | "fish";
+export type NativeServiceRestartPolicy = "on-failure" | "never";
+export type NativeServiceProbeInfrastructureReason = "manager" | "timeout" | "malformed-output" | "cleanup";
+
+export interface NativeServiceBackend {
+  kind: NativeServiceBackendKind;
+  label: string;
+}
+
+export interface NativeServiceShell {
+  name: NativeServiceShellName;
+  executable: string;
+  source: "detected" | "fallback";
+  detectedExecutable: string | null;
+}
+
+export interface NativeServiceManagerRef {
+  systemdName: string;
+  launchdLabel: string;
+  launchdPlistName: string;
+  logName: string;
+}
+
+export type NativeServiceCommandStrategy =
+  | {
+      kind: "configured-override";
+      command: string;
+      verification: "unverified";
+    }
+  | {
+      kind: "named-command";
+      command: string;
+      selectedBy: "authoritative-backend-probe";
+    }
+  | {
+      kind: "bundled-entrypoint";
+      command: "node";
+      entrypointPath: string;
+      namedCommand: string;
+      namedCommandFailure: string | null;
+    }
+  | {
+      kind: "development-npm-script";
+      script: string;
+    }
+  | {
+      kind: "development-npm-script-group";
+      scripts: readonly string[];
+      interpreter: "bash";
+    };
+
+export type NativeServicePrerequisite =
+  | {
+      id: string;
+      kind: "command-available";
+      command: string;
+      description: string;
+    }
+  | {
+      id: string;
+      kind: "node-version";
+      command: "node";
+      minimumMajor: number;
+      description: string;
+    }
+  | {
+      id: string;
+      kind: "readable-file";
+      path: string;
+      description: string;
+    }
+  | {
+      id: string;
+      kind: "package-scripts";
+      packageJsonPath: string;
+      scripts: readonly string[];
+      description: string;
+    };
+
+export interface NativeServicePlanService {
+  id: NativeServiceId;
+  manager: NativeServiceManagerRef;
+  description: string;
+  shellCommand: string;
+  strategy: NativeServiceCommandStrategy;
+  restart: NativeServiceRestartPolicy;
+  environment: Readonly<Record<string, string>>;
+  workingDirectory: string | null;
+  after: readonly NativeServiceId[];
+  wants: readonly NativeServiceId[];
+  prerequisites: readonly NativeServicePrerequisite[];
+}
+
+export interface NativeServicePlan {
+  mode: NativeServiceMode;
+  backend: NativeServiceBackend;
+  shell: NativeServiceShell;
+  services: readonly NativeServicePlanService[];
+}
+
+export interface NativeServiceProbeRequest {
+  purpose: "executable-selection" | "plan-validation";
+  backend: NativeServiceBackend;
+  shell: NativeServiceShell;
+  environment: Readonly<Record<string, string>>;
+  workingDirectory: string | null;
+  prerequisites: readonly NativeServicePrerequisite[];
+}
+
+export interface NativeServicePrerequisiteOutcome {
+  prerequisiteId: string;
+  status: "satisfied" | "unsatisfied";
+  detail: string | null;
+}
+
+export type NativeServiceProbeResult =
+  | {
+      kind: "completed";
+      outcomes: readonly NativeServicePrerequisiteOutcome[];
+    }
+  | {
+      kind: "infrastructure-failure";
+      reason: NativeServiceProbeInfrastructureReason;
+      message: string;
+    };
+
+/**
+ * Runs requirements in the real native service-manager context represented by
+ * the request. Implementations must not treat the caller shell or a simulated
+ * `env -i` environment as authoritative. Timeouts, manager failures, malformed
+ * output, and cleanup failures are infrastructure failures; a missing command
+ * is a completed probe with an unsatisfied outcome.
+ */
+export interface NativeServiceAuthoritativeProbe {
+  run(request: NativeServiceProbeRequest): Promise<NativeServiceProbeResult>;
+}
+
+export interface ProductionNativeServiceExecutableInput {
+  configuredCommand: string | undefined;
+  namedCommand: string;
+  bundledEntrypointPath: string;
+}
+
+export interface ProductionNativeServicePlanInput {
+  backend: NativeServiceBackend;
+  shell: NativeServiceShell;
+  environment: Readonly<Record<string, string>>;
+  executables: Readonly<Record<ProductionNativeServiceId, ProductionNativeServiceExecutableInput>>;
+}
+
+export interface DevelopmentNativeServicePlanInput {
+  backend: NativeServiceBackend;
+  shell: NativeServiceShell;
+  environment: Readonly<Record<string, string>>;
+  workingDirectory: string;
+  packageJsonPath: string;
+}
+
+export interface NativeServicePlanDependencies {
+  probe: NativeServiceAuthoritativeProbe;
+  /** Returns true only when the path exists and is a regular file. */
+  fileExists(path: string): boolean;
+}
+
+export type NativeServicePlanFailure =
+  | {
+      kind: "probe-infrastructure";
+      serviceIds: readonly ProductionNativeServiceId[];
+      reason: NativeServiceProbeInfrastructureReason;
+      message: string;
+    }
+  | {
+      kind: "entrypoint-inspection-failure";
+      serviceId: ProductionNativeServiceId;
+      entrypointPath: string;
+      message: string;
+    }
+  | {
+      kind: "executable-unavailable";
+      serviceId: ProductionNativeServiceId;
+      namedCommand: string;
+      namedCommandFailure: string | null;
+      bundledEntrypointPath: string;
+    };
+
+export type NativeServicePlanResolution =
+  | { ok: true; plan: NativeServicePlan }
+  | { ok: false; failures: readonly NativeServicePlanFailure[] };
+
+export type NativeServicePlanValidationFailure =
+  | {
+      kind: "prerequisite-unsatisfied";
+      prerequisite: NativeServicePrerequisite;
+      detail: string | null;
+    }
+  | {
+      kind: "probe-infrastructure";
+      reason: NativeServiceProbeInfrastructureReason;
+      message: string;
+    };
+
+export type NativeServicePlanValidation =
+  | { ok: true }
+  | { ok: false; failures: readonly NativeServicePlanValidationFailure[] };
+
+export function nativeServicePrerequisiteNeedsPathAdvice(prerequisite: NativeServicePrerequisite): boolean {
+  return prerequisite.kind === "command-available" || prerequisite.kind === "node-version";
+}
+
+export const nativeServiceManagerRefs: Readonly<Record<NativeServiceId, NativeServiceManagerRef>> = {
+  sessiond: {
+    systemdName: "pi-web-sessiond.service",
+    launchdLabel: "com.pi-web.sessiond",
+    launchdPlistName: "com.pi-web.sessiond.plist",
+    logName: "sessiond.log",
+  },
+  web: {
+    systemdName: "pi-web.service",
+    launchdLabel: "com.pi-web.web",
+    launchdPlistName: "com.pi-web.web.plist",
+    logName: "web.log",
+  },
+  uiDev: {
+    systemdName: "pi-web-ui-dev.service",
+    launchdLabel: "com.pi-web.ui-dev",
+    launchdPlistName: "com.pi-web.ui-dev.plist",
+    logName: "ui-dev.log",
+  },
+};
+
+export const productionNativeServiceIds = ["sessiond", "web"] as const satisfies readonly ProductionNativeServiceId[];
+
+export async function resolveProductionNativeServicePlan(
+  input: ProductionNativeServicePlanInput,
+  dependencies: NativeServicePlanDependencies,
+): Promise<NativeServicePlanResolution> {
+  const configuredStrategies = new Map<ProductionNativeServiceId, NativeServiceCommandStrategy>();
+  const selectionRequirements: NativeServicePrerequisite[] = [];
+  const serviceIdsToProbe: ProductionNativeServiceId[] = [];
+
+  for (const serviceId of productionNativeServiceIds) {
+    const executable = input.executables[serviceId];
+    if (hasConfiguredCommand(executable.configuredCommand)) {
+      configuredStrategies.set(serviceId, {
+        kind: "configured-override",
+        command: executable.configuredCommand,
+        verification: "unverified",
+      });
+      continue;
+    }
+
+    serviceIdsToProbe.push(serviceId);
+    selectionRequirements.push(commandRequirement(serviceId, executable.namedCommand));
+  }
+
+  let outcomes = new Map<string, NativeServicePrerequisiteOutcome>();
+  if (selectionRequirements.length > 0) {
+    const probeResult = await runSelectionProbe(input, selectionRequirements, dependencies.probe);
+    if (probeResult.kind === "infrastructure-failure") {
+      return {
+        ok: false,
+        failures: [{ kind: "probe-infrastructure", serviceIds: serviceIdsToProbe, reason: probeResult.reason, message: probeResult.message }],
+      };
+    }
+
+    const parsedOutcomes = probeOutcomes(selectionRequirements, probeResult.outcomes);
+    if (parsedOutcomes.kind === "infrastructure-failure") {
+      return {
+        ok: false,
+        failures: [{ kind: "probe-infrastructure", serviceIds: serviceIdsToProbe, reason: parsedOutcomes.reason, message: parsedOutcomes.message }],
+      };
+    }
+    outcomes = parsedOutcomes.outcomes;
+  }
+
+  const strategies = new Map(configuredStrategies);
+  const failures: NativeServicePlanFailure[] = [];
+
+  for (const serviceId of serviceIdsToProbe) {
+    const executable = input.executables[serviceId];
+    const outcome = outcomes.get(commandRequirementId(serviceId, executable.namedCommand));
+    if (outcome?.status === "satisfied") {
+      strategies.set(serviceId, {
+        kind: "named-command",
+        command: executable.namedCommand,
+        selectedBy: "authoritative-backend-probe",
+      });
+      continue;
+    }
+
+    let entrypointExists: boolean;
+    try {
+      entrypointExists = dependencies.fileExists(executable.bundledEntrypointPath);
+    } catch (error: unknown) {
+      failures.push({
+        kind: "entrypoint-inspection-failure",
+        serviceId,
+        entrypointPath: executable.bundledEntrypointPath,
+        message: errorMessage(error),
+      });
+      continue;
+    }
+
+    if (entrypointExists) {
+      strategies.set(serviceId, {
+        kind: "bundled-entrypoint",
+        command: "node",
+        entrypointPath: executable.bundledEntrypointPath,
+        namedCommand: executable.namedCommand,
+        namedCommandFailure: outcome?.detail ?? null,
+      });
+      continue;
+    }
+
+    failures.push({
+      kind: "executable-unavailable",
+      serviceId,
+      namedCommand: executable.namedCommand,
+      namedCommandFailure: outcome?.detail ?? null,
+      bundledEntrypointPath: executable.bundledEntrypointPath,
+    });
+  }
+
+  if (failures.length > 0) return { ok: false, failures };
+
+  return {
+    ok: true,
+    plan: {
+      mode: "production",
+      backend: input.backend,
+      shell: input.shell,
+      services: productionNativeServiceIds.map((serviceId) => productionService(input, serviceId, requiredStrategy(strategies, serviceId))),
+    },
+  };
+}
+
+export function createDevelopmentNativeServicePlan(input: DevelopmentNativeServicePlanInput): NativeServicePlan {
+  const environment = copyEnvironment(input.environment);
+  const sessiondScripts = ["start:sessiond"] as const;
+  const uiDevScripts = ["dev:web", "dev:client"] as const;
+  const uiDevCommand = 'trap "kill 0" EXIT; npm run dev:web & npm run dev:client & wait';
+
+  return {
+    mode: "development",
+    backend: input.backend,
+    shell: input.shell,
+    services: [
+      {
+        id: "sessiond",
+        manager: nativeServiceManagerRefs.sessiond,
+        description: "PI WEB session daemon (dev)",
+        shellCommand: "exec npm run start:sessiond",
+        strategy: { kind: "development-npm-script", script: "start:sessiond" },
+        restart: "never",
+        environment,
+        workingDirectory: input.workingDirectory,
+        after: [],
+        wants: [],
+        prerequisites: [
+          nodeRequirement("sessiond"),
+          commandRequirement("sessiond", "npm"),
+          packageScriptsRequirement("sessiond", input.packageJsonPath, sessiondScripts),
+        ],
+      },
+      {
+        id: "uiDev",
+        manager: nativeServiceManagerRefs.uiDev,
+        description: "PI WEB UI dev server",
+        shellCommand: `exec /usr/bin/env bash -c ${shellSingleQuote(input.shell.name, uiDevCommand)}`,
+        strategy: { kind: "development-npm-script-group", scripts: uiDevScripts, interpreter: "bash" },
+        restart: "never",
+        environment,
+        workingDirectory: input.workingDirectory,
+        after: ["sessiond"],
+        wants: ["sessiond"],
+        prerequisites: [
+          nodeRequirement("uiDev"),
+          commandRequirement("uiDev", "npm"),
+          commandRequirement("uiDev", "bash"),
+          packageScriptsRequirement("uiDev", input.packageJsonPath, uiDevScripts),
+        ],
+      },
+    ],
+  };
+}
+
+export function planValidationProbeRequests(plan: NativeServicePlan): readonly NativeServiceProbeRequest[] {
+  const requests: (Omit<NativeServiceProbeRequest, "prerequisites"> & { prerequisites: NativeServicePrerequisite[] })[] = [];
+  for (const service of plan.services) {
+    const existing = requests.find((request) =>
+      request.workingDirectory === service.workingDirectory
+      && environmentsEqual(request.environment, service.environment));
+    if (existing === undefined) {
+      requests.push({
+        purpose: "plan-validation",
+        backend: plan.backend,
+        shell: plan.shell,
+        environment: service.environment,
+        workingDirectory: service.workingDirectory,
+        prerequisites: [...service.prerequisites],
+      });
+      continue;
+    }
+    existing.prerequisites.push(...service.prerequisites);
+  }
+  return requests;
+}
+
+export async function validateNativeServicePlan(
+  plan: NativeServicePlan,
+  probe: NativeServiceAuthoritativeProbe,
+): Promise<NativeServicePlanValidation> {
+  const failures: NativeServicePlanValidationFailure[] = [];
+  for (const request of planValidationProbeRequests(plan)) {
+    let result: NativeServiceProbeResult;
+    try {
+      result = await probe.run(request);
+    } catch (error: unknown) {
+      return {
+        ok: false,
+        failures: [{ kind: "probe-infrastructure", reason: "manager", message: errorMessage(error) }],
+      };
+    }
+    if (result.kind === "infrastructure-failure") {
+      return {
+        ok: false,
+        failures: [{ kind: "probe-infrastructure", reason: result.reason, message: result.message }],
+      };
+    }
+    const parsed = probeOutcomes(request.prerequisites, result.outcomes);
+    if (parsed.kind === "infrastructure-failure") {
+      return {
+        ok: false,
+        failures: [{ kind: "probe-infrastructure", reason: parsed.reason, message: parsed.message }],
+      };
+    }
+    for (const prerequisite of request.prerequisites) {
+      const outcome = parsed.outcomes.get(prerequisite.id);
+      if (outcome?.status === "unsatisfied") {
+        failures.push({ kind: "prerequisite-unsatisfied", prerequisite, detail: outcome.detail });
+      }
+    }
+  }
+  return failures.length === 0 ? { ok: true } : { ok: false, failures };
+}
+
+function productionService(
+  input: ProductionNativeServicePlanInput,
+  serviceId: ProductionNativeServiceId,
+  strategy: NativeServiceCommandStrategy,
+): NativeServicePlanService {
+  const isWeb = serviceId === "web";
+  return {
+    id: serviceId,
+    manager: nativeServiceManagerRefs[serviceId],
+    description: isWeb ? "PI WEB server" : "PI WEB session daemon",
+    shellCommand: `exec ${strategyCommand(input.shell, strategy)}`,
+    strategy,
+    restart: "on-failure",
+    environment: copyEnvironment(input.environment),
+    workingDirectory: null,
+    after: isWeb ? ["sessiond"] : [],
+    wants: isWeb ? ["sessiond"] : [],
+    prerequisites: strategyPrerequisites(serviceId, strategy),
+  };
+}
+
+function strategyCommand(shell: NativeServiceShell, strategy: NativeServiceCommandStrategy): string {
+  switch (strategy.kind) {
+    case "configured-override":
+    case "named-command":
+      return strategy.command;
+    case "bundled-entrypoint":
+      return `${strategy.command} ${shellSingleQuote(shell.name, strategy.entrypointPath)}`;
+    case "development-npm-script":
+      return `npm run ${strategy.script}`;
+    case "development-npm-script-group":
+      throw new Error("Development script groups define their complete service shell command");
+  }
+}
+
+function strategyPrerequisites(serviceId: ProductionNativeServiceId, strategy: NativeServiceCommandStrategy): readonly NativeServicePrerequisite[] {
+  switch (strategy.kind) {
+    case "configured-override":
+      return [];
+    case "named-command":
+      return [commandRequirement(serviceId, strategy.command), nodeRequirement(serviceId)];
+    case "bundled-entrypoint":
+      return [nodeRequirement(serviceId), readableFileRequirement(serviceId, strategy.entrypointPath)];
+    case "development-npm-script":
+    case "development-npm-script-group":
+      throw new Error(`Unexpected ${strategy.kind} strategy in a production plan`);
+  }
+}
+
+async function runSelectionProbe(
+  input: ProductionNativeServicePlanInput,
+  prerequisites: readonly NativeServicePrerequisite[],
+  probe: NativeServiceAuthoritativeProbe,
+): Promise<NativeServiceProbeResult> {
+  try {
+    return await probe.run({
+      purpose: "executable-selection",
+      backend: input.backend,
+      shell: input.shell,
+      environment: copyEnvironment(input.environment),
+      workingDirectory: null,
+      prerequisites,
+    });
+  } catch (error: unknown) {
+    return { kind: "infrastructure-failure", reason: "manager", message: errorMessage(error) };
+  }
+}
+
+function probeOutcomes(
+  prerequisites: readonly NativeServicePrerequisite[],
+  outcomes: readonly NativeServicePrerequisiteOutcome[],
+): { kind: "completed"; outcomes: Map<string, NativeServicePrerequisiteOutcome> } | { kind: "infrastructure-failure"; reason: "malformed-output"; message: string } {
+  const expectedIds = new Set(prerequisites.map((prerequisite) => prerequisite.id));
+  const byId = new Map<string, NativeServicePrerequisiteOutcome>();
+
+  for (const outcome of outcomes) {
+    if (!expectedIds.has(outcome.prerequisiteId)) {
+      return { kind: "infrastructure-failure", reason: "malformed-output", message: `Authoritative probe returned unexpected outcome ${outcome.prerequisiteId}.` };
+    }
+    if (byId.has(outcome.prerequisiteId)) {
+      return { kind: "infrastructure-failure", reason: "malformed-output", message: `Authoritative probe returned duplicate outcome ${outcome.prerequisiteId}.` };
+    }
+    byId.set(outcome.prerequisiteId, outcome);
+  }
+
+  const missing = prerequisites.find((prerequisite) => !byId.has(prerequisite.id));
+  if (missing !== undefined) {
+    return { kind: "infrastructure-failure", reason: "malformed-output", message: `Authoritative probe returned no outcome for ${missing.id}.` };
+  }
+  return { kind: "completed", outcomes: byId };
+}
+
+function requiredStrategy(
+  strategies: ReadonlyMap<ProductionNativeServiceId, NativeServiceCommandStrategy>,
+  serviceId: ProductionNativeServiceId,
+): NativeServiceCommandStrategy {
+  const strategy = strategies.get(serviceId);
+  if (strategy === undefined) throw new Error(`Missing executable strategy for ${serviceId}`);
+  return strategy;
+}
+
+function hasConfiguredCommand(command: string | undefined): command is string {
+  return command !== undefined && command.trim() !== "";
+}
+
+function commandRequirementId(serviceId: NativeServiceId, command: string): string {
+  return `${serviceId}.command.${command}`;
+}
+
+function commandRequirement(serviceId: NativeServiceId, command: string): NativeServicePrerequisite {
+  return {
+    id: commandRequirementId(serviceId, command),
+    kind: "command-available",
+    command,
+    description: `${command} resolves to an external executable for the service shell`,
+  };
+}
+
+function nodeRequirement(serviceId: NativeServiceId): NativeServicePrerequisite {
+  return {
+    id: `${serviceId}.node`,
+    kind: "node-version",
+    command: "node",
+    minimumMajor: 22,
+    description: "node >= 22 is available to the service shell",
+  };
+}
+
+function readableFileRequirement(serviceId: NativeServiceId, path: string): NativeServicePrerequisite {
+  return {
+    id: `${serviceId}.entrypoint`,
+    kind: "readable-file",
+    path,
+    description: `bundled entrypoint is a readable regular file: ${path}`,
+  };
+}
+
+function packageScriptsRequirement(
+  serviceId: NativeServiceId,
+  packageJsonPath: string,
+  scripts: readonly string[],
+): NativeServicePrerequisite {
+  return {
+    id: `${serviceId}.package-scripts`,
+    kind: "package-scripts",
+    packageJsonPath,
+    scripts,
+    description: `package.json defines scripts: ${scripts.join(", ")}`,
+  };
+}
+
+function shellSingleQuote(shell: NativeServiceShellName, value: string): string {
+  if (shell === "fish") return `'${value.replaceAll("\\", "\\\\").replaceAll("'", "\\'")}'`;
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+function copyEnvironment(environment: Readonly<Record<string, string>>): Readonly<Record<string, string>> {
+  return { ...environment };
+}
+
+function environmentsEqual(
+  left: Readonly<Record<string, string>>,
+  right: Readonly<Record<string, string>>,
+): boolean {
+  const leftEntries = Object.entries(left);
+  const rightEntries = Object.entries(right);
+  return leftEntries.length === rightEntries.length
+    && leftEntries.every(([key, value]) => right[key] === value);
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

src/nativeServices/serviceProbe.test.ts

@@ -0,0 +1,483 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  LaunchdNativeServiceProbe,
+  SpawnProbeCommandRunner,
+  SystemdNativeServiceProbe,
+  launchdProbePlist,
+  nativeServicePrerequisiteShellCheck,
+  systemdRunArguments,
+  type LaunchdProbeFileSystem,
+  type ProbeCommandResult,
+  type ProbeCommandRunner,
+} from "./serviceProbe.js";
+import type { NativeServiceProbeRequest } from "./servicePlan.js";
+
+function request(kind: "systemd" | "launchd" = "systemd"): NativeServiceProbeRequest {
+  return {
+    purpose: "plan-validation",
+    backend: { kind, label: kind },
+    shell: {
+      name: "zsh",
+      executable: "/bin/zsh",
+      source: "detected",
+      detectedExecutable: "/bin/zsh",
+    },
+    environment: { PI_WEB_CONFIG: "/home/user/config with space.json" },
+    workingDirectory: "/checkout with space",
+    prerequisites: [{
+      id: "sessiond.command.npm",
+      kind: "command-available",
+      command: "npm",
+      description: "npm is available",
+    }],
+  };
+}
+
+function completed(status = 0, stdout = "", stderr = ""): ProbeCommandResult {
+  return { kind: "completed", status, stdout, stderr };
+}
+
+function marker(id: string, status: "satisfied" | "unsatisfied"): string {
+  return `PI_WEB_PROBE_fixed\t${Buffer.from(id).toString("base64")}\t${status}\n`;
+}
+
+function queuedRunner(results: ProbeCommandResult[]): ProbeCommandRunner & { calls: { command: string; args: readonly string[]; timeoutMs: number }[] } {
+  const calls: { command: string; args: readonly string[]; timeoutMs: number }[] = [];
+  return {
+    calls,
+    run: (command, args, timeoutMs) => {
+      calls.push({ command, args, timeoutMs });
+      const result = results.shift();
+      if (result === undefined) throw new Error(`Unexpected command: ${command} ${args.join(" ")}`);
+      return Promise.resolve(result);
+    },
+  };
+}
+
+describe("systemd authoritative native-service probe", () => {
+  it("runs the exact shell, environment, and cwd in a transient user service", async () => {
+    const runner = queuedRunner([completed(0, `login banner\n${marker("sessiond.command.npm", "satisfied")}`)]);
+    const probe = new SystemdNativeServiceProbe({
+      commandRunner: runner,
+      createUniqueId: () => "fixed",
+      commandTimeoutMs: 3210,
+    });
+
+    await expect(probe.run(request())).resolves.toEqual({
+      kind: "completed",
+      outcomes: [{ prerequisiteId: "sessiond.command.npm", status: "satisfied", detail: null }],
+    });
+    expect(runner.calls).toHaveLength(1);
+    expect(runner.calls[0]).toMatchObject({ command: "systemd-run", timeoutMs: 3210 });
+    expect(runner.calls[0]?.args).toEqual([
+      "--user",
+      "--wait",
+      "--collect",
+      "--pipe",
+      "--quiet",
+      "--unit=pi-web-authoritative-probe-fixed.service",
+      "--property=RuntimeMaxSec=15s",
+      "--property=TimeoutStopSec=5s",
+      "--setenv=PI_WEB_CONFIG=/home/user/config with space.json",
+      "--working-directory=/checkout with space",
+      "/usr/bin/env",
+      "/bin/zsh",
+      "-lc",
+      expect.stringContaining("command -v 'npm'"),
+    ]);
+  });
+
+  it("reports requirement failures as completed and malformed output as infrastructure", async () => {
+    const unsatisfiedRunner = queuedRunner([completed(0, marker("sessiond.command.npm", "unsatisfied"))]);
+    const dependencies = { commandRunner: unsatisfiedRunner, createUniqueId: () => "fixed", commandTimeoutMs: 100 };
+    await expect(new SystemdNativeServiceProbe(dependencies).run(request())).resolves.toEqual({
+      kind: "completed",
+      outcomes: [{
+        prerequisiteId: "sessiond.command.npm",
+        status: "unsatisfied",
+        detail: "npm did not resolve to an external executable in the native service environment.",
+      }],
+    });
+
+    const malformedRunner = queuedRunner([completed(0, "no marker here")]);
+    await expect(new SystemdNativeServiceProbe({ ...dependencies, commandRunner: malformedRunner }).run(request())).resolves.toMatchObject({
+      kind: "infrastructure-failure",
+      reason: "malformed-output",
+    });
+  });
+
+  it("bounds a hung unit, cleans it up, and reports the timeout", async () => {
+    const runner = queuedRunner([
+      { kind: "timeout", stdout: "", stderr: "" },
+      completed(0),
+      completed(0, "not-found\n"),
+    ]);
+    const probe = new SystemdNativeServiceProbe({
+      commandRunner: runner,
+      createUniqueId: () => "fixed",
+      commandTimeoutMs: 100,
+    });
+
+    await expect(probe.run(request())).resolves.toMatchObject({
+      kind: "infrastructure-failure",
+      reason: "timeout",
+    });
+    expect(runner.calls.map(({ command }) => command)).toEqual(["systemd-run", "systemctl", "systemctl"]);
+  });
+
+  it("bounds a hung unit and distinguishes cleanup failure", async () => {
+    const runner = queuedRunner([
+      { kind: "timeout", stdout: "", stderr: "" },
+      completed(0),
+      completed(0, "loaded\n", "unit still loaded"),
+    ]);
+    const probe = new SystemdNativeServiceProbe({
+      commandRunner: runner,
+      createUniqueId: () => "fixed",
+      commandTimeoutMs: 100,
+    });
+
+    const result = await probe.run(request());
+    expect(result).toMatchObject({ kind: "infrastructure-failure", reason: "cleanup" });
+    expect(result.kind === "infrastructure-failure" && result.message).toContain("unit still loaded");
+    expect(runner.calls.map(({ command, args }) => [command, ...args.slice(0, 3)])).toEqual([
+      ["systemd-run", "--user", "--wait", "--collect"],
+      ["systemctl", "--user", "stop", "pi-web-authoritative-probe-fixed.service"],
+      ["systemctl", "--user", "show", "pi-web-authoritative-probe-fixed.service"],
+    ]);
+  });
+});
+
+describe("spawn probe command runner", () => {
+  it("bounds captured command output", async () => {
+    const runner = new SpawnProbeCommandRunner();
+    const result = await runner.run(
+      process.execPath,
+      ["-e", "process.stdout.write('x'.repeat(2 * 1024 * 1024))"],
+      5_000,
+    );
+
+    expect(result).toMatchObject({ kind: "output-limit" });
+    expect(result.stdout.length).toBeLessThanOrEqual(1024 * 1024);
+  });
+
+  it("settles a timeout without waiting for inherited pipes to close", async () => {
+    const runner = new SpawnProbeCommandRunner();
+    const childScript = [
+      "const { spawn } = require('node:child_process');",
+      "const child = spawn(process.execPath, ['-e', 'setTimeout(() => {}, 1000)'], { stdio: ['ignore', 'inherit', 'inherit'] });",
+      "child.unref();",
+    ].join(" ");
+    const startedAt = performance.now();
+
+    await expect(runner.run(process.execPath, ["-e", childScript], 20)).resolves.toMatchObject({ kind: "timeout" });
+    expect(performance.now() - startedAt).toBeLessThan(500);
+  });
+});
+
+describe("launchd authoritative native-service probe", () => {
+  it("bootstraps a uniquely labelled one-shot agent in gui/<uid> and always cleans it up", async () => {
+    const runner = queuedRunner([completed(0), completed(0)]);
+    const fileSystem = launchdFileSystem({
+      "/tmp/probe/result.log": marker("sessiond.command.npm", "satisfied"),
+    });
+    let now = 0;
+    const probe = new LaunchdNativeServiceProbe({
+      commandRunner: runner,
+      fileSystem,
+      uid: 501,
+      createUniqueId: () => "fixed",
+      now: () => now,
+      sleep: (milliseconds) => { now += milliseconds; return Promise.resolve(); },
+      probeTimeoutMs: 500,
+      pollIntervalMs: 10,
+      commandTimeoutMs: 100,
+    });
+
+    await expect(probe.run(request("launchd"))).resolves.toMatchObject({ kind: "completed" });
+    expect(runner.calls.map(({ command, args }) => [command, ...args])).toEqual([
+      ["launchctl", "bootstrap", "gui/501", "/tmp/probe/probe.plist"],
+      ["launchctl", "bootout", "gui/501/com.pi-web.authoritative-probe.501.fixed"],
+    ]);
+    expect(fileSystem.writeFile).toHaveBeenCalledWith(
+      "/tmp/probe/probe.plist",
+      expect.stringContaining("<string>/bin/zsh</string>"),
+      0o600,
+    );
+    expect(fileSystem.writeFile).toHaveBeenCalledWith(
+      "/tmp/probe/probe.plist",
+      expect.stringContaining("<key>WorkingDirectory</key>\n  <string>/checkout with space</string>"),
+      0o600,
+    );
+    expect(fileSystem.writeFile).toHaveBeenCalledWith(
+      "/tmp/probe/probe.plist",
+      expect.stringContaining("/bin/mv &apos;/tmp/probe/result.pending&apos; &apos;/tmp/probe/result.log&apos;"),
+      0o600,
+    );
+    expect(fileSystem.removeDirectory).toHaveBeenCalledWith("/tmp/probe");
+  });
+
+  it("times out deterministically, boots out the agent, and removes temporary files", async () => {
+    const runner = queuedRunner([completed(0), completed(0)]);
+    const fileSystem = launchdFileSystem({});
+    let now = 0;
+    const probe = new LaunchdNativeServiceProbe({
+      commandRunner: runner,
+      fileSystem,
+      uid: 502,
+      createUniqueId: () => "fixed",
+      now: () => now,
+      sleep: (milliseconds) => { now += milliseconds; return Promise.resolve(); },
+      probeTimeoutMs: 20,
+      pollIntervalMs: 10,
+      commandTimeoutMs: 100,
+    });
+
+    await expect(probe.run(request("launchd"))).resolves.toMatchObject({
+      kind: "infrastructure-failure",
+      reason: "timeout",
+    });
+    expect(runner.calls.at(-1)).toMatchObject({
+      command: "launchctl",
+      args: ["bootout", "gui/502/com.pi-web.authoritative-probe.502.fixed"],
+    });
+    expect(fileSystem.removeDirectory).toHaveBeenCalledWith("/tmp/probe");
+  });
+
+  it("bounds a stalled result-file read before cleaning up", async () => {
+    const runner = queuedRunner([completed(0), completed(0)]);
+    const fileSystem = launchdFileSystem({});
+    fileSystem.readOptionalFile.mockReturnValueOnce(new Promise(() => undefined));
+    const probe = new LaunchdNativeServiceProbe({
+      commandRunner: runner,
+      fileSystem,
+      uid: 502,
+      createUniqueId: () => "fixed",
+      now: () => 0,
+      sleep: () => Promise.resolve(),
+      probeTimeoutMs: 10,
+      pollIntervalMs: 1,
+      commandTimeoutMs: 100,
+    });
+
+    await expect(probe.run(request("launchd"))).resolves.toMatchObject({
+      kind: "infrastructure-failure",
+      reason: "timeout",
+    });
+    expect(runner.calls.map(({ args }) => args[0])).toEqual(["bootstrap", "bootout"]);
+    expect(fileSystem.removeDirectory).toHaveBeenCalledWith("/tmp/probe");
+  });
+
+  it("surfaces cleanup failure instead of returning an otherwise successful probe", async () => {
+    const runner = queuedRunner([completed(0), completed(1, "", "bootout denied")]);
+    const fileSystem = launchdFileSystem({
+      "/tmp/probe/result.log": marker("sessiond.command.npm", "satisfied"),
+    });
+    const probe = new LaunchdNativeServiceProbe({
+      commandRunner: runner,
+      fileSystem,
+      uid: 503,
+      createUniqueId: () => "fixed",
+      now: () => 0,
+      sleep: () => Promise.resolve(),
+      probeTimeoutMs: 20,
+      pollIntervalMs: 10,
+      commandTimeoutMs: 100,
+    });
+
+    const result = await probe.run(request("launchd"));
+    expect(result).toMatchObject({ kind: "infrastructure-failure", reason: "cleanup" });
+    expect(result.kind === "infrastructure-failure" && result.message).toContain("bootout denied");
+    expect(fileSystem.removeDirectory).toHaveBeenCalledWith("/tmp/probe");
+  });
+
+  it("boots out a label when bootstrap itself times out", async () => {
+    const runner = queuedRunner([
+      { kind: "timeout", stdout: "", stderr: "" },
+      completed(0),
+    ]);
+    const fileSystem = launchdFileSystem({});
+    const probe = new LaunchdNativeServiceProbe({
+      commandRunner: runner,
+      fileSystem,
+      uid: 504,
+      createUniqueId: () => "fixed",
+      now: () => 0,
+      sleep: () => Promise.resolve(),
+      probeTimeoutMs: 20,
+      pollIntervalMs: 10,
+      commandTimeoutMs: 100,
+    });
+
+    await expect(probe.run(request("launchd"))).resolves.toMatchObject({
+      kind: "infrastructure-failure",
+      reason: "timeout",
+    });
+    expect(runner.calls.map(({ args }) => args[0])).toEqual(["bootstrap", "bootout"]);
+    expect(fileSystem.removeDirectory).toHaveBeenCalledWith("/tmp/probe");
+  });
+
+  it("treats an explicit not-loaded bootout response as successful cleanup after bootstrap fails", async () => {
+    const runner = queuedRunner([
+      completed(1, "", "bootstrap denied"),
+      completed(3, "", "Could not find service in domain"),
+    ]);
+    const fileSystem = launchdFileSystem({});
+    const probe = new LaunchdNativeServiceProbe({
+      commandRunner: runner,
+      fileSystem,
+      uid: 504,
+      createUniqueId: () => "fixed",
+      now: () => 0,
+      sleep: () => Promise.resolve(),
+      probeTimeoutMs: 20,
+      pollIntervalMs: 10,
+      commandTimeoutMs: 100,
+    });
+
+    const result = await probe.run(request("launchd"));
+    expect(result).toMatchObject({ kind: "infrastructure-failure", reason: "manager" });
+    expect(result.kind === "infrastructure-failure" && result.message).toContain("bootstrap denied");
+    expect(runner.calls.map(({ args }) => args[0])).toEqual(["bootstrap", "bootout"]);
+    expect(fileSystem.removeDirectory).toHaveBeenCalledWith("/tmp/probe");
+  });
+
+  it("cleans a loaded label after malformed private result output", async () => {
+    const runner = queuedRunner([completed(0), completed(0)]);
+    const fileSystem = launchdFileSystem({ "/tmp/probe/result.log": "malformed result" });
+    const probe = new LaunchdNativeServiceProbe({
+      commandRunner: runner,
+      fileSystem,
+      uid: 505,
+      createUniqueId: () => "fixed",
+      now: () => 0,
+      sleep: () => Promise.resolve(),
+      probeTimeoutMs: 20,
+      pollIntervalMs: 10,
+      commandTimeoutMs: 100,
+    });
+
+    await expect(probe.run(request("launchd"))).resolves.toMatchObject({
+      kind: "infrastructure-failure",
+      reason: "malformed-output",
+    });
+    expect(runner.calls.at(-1)?.args[0]).toBe("bootout");
+    expect(fileSystem.removeDirectory).toHaveBeenCalledWith("/tmp/probe");
+  });
+
+  it("cleans a loaded label when the private result cannot be read", async () => {
+    const runner = queuedRunner([completed(0), completed(0)]);
+    const fileSystem = launchdFileSystem({});
+    fileSystem.readOptionalFile.mockRejectedValueOnce(new Error("read denied"));
+    const probe = new LaunchdNativeServiceProbe({
+      commandRunner: runner,
+      fileSystem,
+      uid: 506,
+      createUniqueId: () => "fixed",
+      now: () => 0,
+      sleep: () => Promise.resolve(),
+      probeTimeoutMs: 20,
+      pollIntervalMs: 10,
+      commandTimeoutMs: 100,
+    });
+
+    const result = await probe.run(request("launchd"));
+    expect(result).toMatchObject({ kind: "infrastructure-failure", reason: "manager" });
+    expect(result.kind === "infrastructure-failure" && result.message).toContain("Could not read launchd probe result");
+    expect(runner.calls.at(-1)?.args[0]).toBe("bootout");
+    expect(fileSystem.removeDirectory).toHaveBeenCalledWith("/tmp/probe");
+  });
+
+  it("reports temporary-file cleanup failures", async () => {
+    const runner = queuedRunner([
+      completed(1, "", "bootstrap denied"),
+      completed(3, "", "Could not find service in domain"),
+    ]);
+    const fileSystem = launchdFileSystem({});
+    fileSystem.removeDirectory.mockRejectedValueOnce(new Error("rm denied"));
+    const probe = new LaunchdNativeServiceProbe({
+      commandRunner: runner,
+      fileSystem,
+      uid: 506,
+      createUniqueId: () => "fixed",
+      now: () => 0,
+      sleep: () => Promise.resolve(),
+      probeTimeoutMs: 20,
+      pollIntervalMs: 10,
+      commandTimeoutMs: 100,
+    });
+
+    const result = await probe.run(request("launchd"));
+    expect(result).toMatchObject({ kind: "infrastructure-failure", reason: "cleanup" });
+    expect(result.kind === "infrastructure-failure" && result.message).toContain("rm denied");
+  });
+});
+
+describe("probe service definitions", () => {
+  it("requires external executables instead of accepting shell functions or aliases", () => {
+    const commandRequirement = request().prerequisites[0];
+    if (commandRequirement === undefined) throw new Error("Expected a command prerequisite");
+    const bashCheck = nativeServicePrerequisiteShellCheck("bash", commandRequirement);
+    expect(bashCheck).toContain("case \"$pi_web_probe_executable\" in */*)");
+    expect(bashCheck).toContain("test -f \"$pi_web_probe_executable\"");
+    expect(bashCheck).toContain("test -x \"$pi_web_probe_executable\"");
+
+    const fishCheck = nativeServicePrerequisiteShellCheck("fish", commandRequirement);
+    expect(fishCheck).toContain("string match -q '*/*'");
+    expect(fishCheck).toContain("test -f $pi_web_probe_executable[1]");
+    expect(fishCheck).toContain("test -x $pi_web_probe_executable[1]");
+  });
+
+  it("invokes the resolved external Node executable for version checks", () => {
+    const check = nativeServicePrerequisiteShellCheck("zsh", {
+      id: "sessiond.node",
+      kind: "node-version",
+      command: "node",
+      minimumMajor: 22,
+      description: "node >= 22",
+    });
+    expect(check).toContain("\"$pi_web_probe_executable\" '-e'");
+    expect(check).not.toContain("&& node -e");
+  });
+
+  it("requires bundled entrypoints to be readable regular files", () => {
+    const check = nativeServicePrerequisiteShellCheck("bash", {
+      id: "sessiond.entrypoint",
+      kind: "readable-file",
+      path: "/package/server.js",
+      description: "entrypoint",
+    });
+    expect(check).toBe("test -f '/package/server.js' && test -r '/package/server.js'");
+  });
+
+  it("renders backend inputs without inheriting the caller PATH", () => {
+    const probeRequest = request();
+    const systemdArguments = systemdRunArguments(probeRequest, "probe.service", "echo ok");
+    expect(systemdArguments.some((argument) => argument.includes("PATH="))).toBe(false);
+    const plist = launchdProbePlist(probeRequest, "com.example.probe", "echo ok", "/tmp/out", "/tmp/err");
+    expect(plist).not.toContain("<key>PATH</key>");
+    expect(plist).toContain("<key>PI_WEB_CONFIG</key>");
+    expect(plist).toContain("<key>HardResourceLimits</key>");
+  });
+
+  it("escapes manager-side substitutions in the systemd probe payload", () => {
+    const args = systemdRunArguments(request(), "probe.service", "test -r '/tmp/$HOME/%h'");
+    expect(args.at(-1)).toBe("test -r '/tmp/$$HOME/%h'");
+  });
+});
+
+function launchdFileSystem(contents: Record<string, string>): LaunchdProbeFileSystem & {
+  writeFile: ReturnType<typeof vi.fn<LaunchdProbeFileSystem["writeFile"]>>;
+  readOptionalFile: ReturnType<typeof vi.fn<LaunchdProbeFileSystem["readOptionalFile"]>>;
+  removeDirectory: ReturnType<typeof vi.fn<LaunchdProbeFileSystem["removeDirectory"]>>;
+} {
+  const writeFileMock = vi.fn<LaunchdProbeFileSystem["writeFile"]>(() => Promise.resolve());
+  const readOptionalFileMock = vi.fn<LaunchdProbeFileSystem["readOptionalFile"]>((path) => Promise.resolve(contents[path] ?? null));
+  const removeDirectoryMock = vi.fn<LaunchdProbeFileSystem["removeDirectory"]>(() => Promise.resolve());
+  return {
+    createTemporaryDirectory: () => Promise.resolve("/tmp/probe"),
+    writeFile: writeFileMock,
+    readOptionalFile: readOptionalFileMock,
+    removeDirectory: removeDirectoryMock,
+  };
+}

src/nativeServices/serviceProbe.ts

@@ -0,0 +1,591 @@
+import { spawn } from "node:child_process";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir, userInfo } from "node:os";
+import { posix as posixPath } from "node:path";
+import { performance } from "node:perf_hooks";
+import { randomUUID } from "node:crypto";
+import type {
+  NativeServiceAuthoritativeProbe,
+  NativeServicePrerequisite,
+  NativeServicePrerequisiteOutcome,
+  NativeServiceProbeRequest,
+  NativeServiceProbeResult,
+  NativeServiceShellName,
+} from "./servicePlan.js";
+
+export type ProbeCommandResult =
+  | { kind: "completed"; status: number; stdout: string; stderr: string }
+  | { kind: "timeout"; stdout: string; stderr: string }
+  | { kind: "spawn-failure"; message: string; stdout: string; stderr: string }
+  | { kind: "output-limit"; stdout: string; stderr: string };
+
+export interface ProbeCommandRunner {
+  run(command: string, args: readonly string[], timeoutMs: number): Promise<ProbeCommandResult>;
+}
+
+export interface LaunchdProbeFileSystem {
+  createTemporaryDirectory(prefix: string): Promise<string>;
+  writeFile(path: string, contents: string, mode: number): Promise<void>;
+  readOptionalFile(path: string): Promise<string | null>;
+  removeDirectory(path: string): Promise<void>;
+}
+
+interface CommonProbeDependencies {
+  commandRunner: ProbeCommandRunner;
+  createUniqueId(): string;
+  commandTimeoutMs: number;
+}
+
+export type SystemdProbeDependencies = CommonProbeDependencies;
+
+export interface LaunchdProbeDependencies extends CommonProbeDependencies {
+  fileSystem: LaunchdProbeFileSystem;
+  uid: number;
+  now(): number;
+  sleep(milliseconds: number): Promise<void>;
+  probeTimeoutMs: number;
+  pollIntervalMs: number;
+}
+
+const defaultCommandTimeoutMs = 15_000;
+const defaultProbeTimeoutMs = 15_000;
+const defaultPollIntervalMs = 50;
+const maxCapturedCommandOutputBytes = 1024 * 1024;
+const maxLaunchdProbeFileBytes = 1024 * 1024;
+
+export class SystemdNativeServiceProbe implements NativeServiceAuthoritativeProbe {
+  public constructor(private readonly dependencies: SystemdProbeDependencies) {}
+
+  public async run(request: NativeServiceProbeRequest): Promise<NativeServiceProbeResult> {
+    if (request.backend.kind !== "systemd") {
+      return infrastructureFailure("manager", `Systemd probe cannot validate the ${request.backend.kind} backend.`);
+    }
+
+    const uniqueId = safeUniqueId(this.dependencies.createUniqueId());
+    const unitName = `pi-web-authoritative-probe-${uniqueId}.service`;
+    const outputPrefix = `PI_WEB_PROBE_${uniqueId}`;
+    const command = prerequisiteProbeCommand(request.shell.name, request.prerequisites, outputPrefix);
+    const args = systemdRunArguments(request, unitName, command);
+    const result = await this.dependencies.commandRunner.run("systemd-run", args, this.dependencies.commandTimeoutMs);
+
+    if (result.kind === "timeout" || result.kind === "output-limit") {
+      const cleanupFailure = await this.cleanupTimedOutUnit(unitName);
+      if (cleanupFailure !== null) return cleanupFailure;
+      return result.kind === "timeout"
+        ? infrastructureFailure("timeout", `Timed out waiting for transient systemd unit ${unitName}.`)
+        : infrastructureFailure("manager", `Transient systemd probe ${unitName} exceeded the output limit.`);
+    }
+    if (result.kind === "spawn-failure") {
+      return infrastructureFailure("manager", `Could not start systemd-run: ${result.message}`);
+    }
+    if (result.status !== 0) {
+      return infrastructureFailure(
+        "manager",
+        `Transient systemd probe ${unitName} failed: ${firstOutput(result.stderr, result.stdout, `exit status ${String(result.status)}`)}`,
+      );
+    }
+    return parseProbeOutput(result.stdout, request.prerequisites, outputPrefix);
+  }
+
+  private async cleanupTimedOutUnit(unitName: string): Promise<NativeServiceProbeResult | null> {
+    const stop = await this.dependencies.commandRunner.run(
+      "systemctl",
+      ["--user", "stop", unitName],
+      this.dependencies.commandTimeoutMs,
+    );
+    const inspected = await this.dependencies.commandRunner.run(
+      "systemctl",
+      ["--user", "show", unitName, "--property=LoadState", "--value"],
+      this.dependencies.commandTimeoutMs,
+    );
+    if (inspected.kind === "completed" && inspected.status === 0 && inspected.stdout.trim() === "not-found") {
+      return null;
+    }
+    const details = [
+      `stop: ${commandFailureDetail(stop)}`,
+      `load state: ${commandFailureDetail(inspected)}`,
+    ].join("; ");
+    return infrastructureFailure("cleanup", `Could not confirm cleanup of timed-out transient systemd unit ${unitName}: ${details}`);
+  }
+}
+
+export class LaunchdNativeServiceProbe implements NativeServiceAuthoritativeProbe {
+  public constructor(private readonly dependencies: LaunchdProbeDependencies) {}
+
+  public async run(request: NativeServiceProbeRequest): Promise<NativeServiceProbeResult> {
+    if (request.backend.kind !== "launchd") {
+      return infrastructureFailure("manager", `Launchd probe cannot validate the ${request.backend.kind} backend.`);
+    }
+
+    const uniqueId = safeUniqueId(this.dependencies.createUniqueId());
+    const label = `com.pi-web.authoritative-probe.${String(this.dependencies.uid)}.${uniqueId}`;
+    const domain = `gui/${String(this.dependencies.uid)}`;
+    const target = `${domain}/${label}`;
+    const outputPrefix = `PI_WEB_PROBE_${uniqueId}`;
+    let directory: string | null = null;
+    let bootstrapState: "not-loaded" | "loaded" | "uncertain" = "not-loaded";
+    let result: NativeServiceProbeResult;
+
+    try {
+      directory = await this.dependencies.fileSystem.createTemporaryDirectory(
+        posixPath.join(tmpdir(), "pi-web-launchd-probe-"),
+      );
+      const plistPath = posixPath.join(directory, "probe.plist");
+      const stdoutPath = posixPath.join(directory, "stdout.log");
+      const stderrPath = posixPath.join(directory, "stderr.log");
+      const pendingResultPath = posixPath.join(directory, "result.pending");
+      const resultPath = posixPath.join(directory, "result.log");
+      const command = prerequisiteProbeCommand(
+        request.shell.name,
+        request.prerequisites,
+        outputPrefix,
+        { pendingPath: pendingResultPath, completedPath: resultPath },
+      );
+      await this.dependencies.fileSystem.writeFile(
+        plistPath,
+        launchdProbePlist(request, label, command, stdoutPath, stderrPath),
+        0o600,
+      );
+
+      const bootstrap = await this.dependencies.commandRunner.run(
+        "launchctl",
+        ["bootstrap", domain, plistPath],
+        this.dependencies.commandTimeoutMs,
+      );
+      if (bootstrap.kind !== "completed" || bootstrap.status !== 0) {
+        bootstrapState = bootstrap.kind === "spawn-failure" ? "not-loaded" : "uncertain";
+        result = commandInfrastructureFailure("bootstrap launchd probe", bootstrap);
+      } else {
+        bootstrapState = "loaded";
+        result = await this.waitForResult(target, resultPath, request.prerequisites, outputPrefix);
+      }
+    } catch (error: unknown) {
+      result = infrastructureFailure("manager", `Could not prepare launchd probe: ${errorMessage(error)}`);
+    }
+
+    const cleanupFailure = await this.cleanup(target, directory, bootstrapState);
+    return cleanupFailure ?? result;
+  }
+
+  private async waitForResult(
+    target: string,
+    resultPath: string,
+    prerequisites: readonly NativeServicePrerequisite[],
+    outputPrefix: string,
+  ): Promise<NativeServiceProbeResult> {
+    const deadline = this.dependencies.now() + this.dependencies.probeTimeoutMs;
+    while (this.dependencies.now() < deadline) {
+      const remainingMs = Math.max(0, deadline - this.dependencies.now());
+      const boundedRead = await readOptionalFileBounded(
+        this.dependencies.fileSystem,
+        resultPath,
+        remainingMs,
+      );
+      if (boundedRead.kind === "deadline") break;
+      if (boundedRead.kind === "read-failure") {
+        return infrastructureFailure("manager", `Could not read launchd probe result: ${errorMessage(boundedRead.error)}`);
+      }
+      if (boundedRead.output !== null) return parseProbeOutput(boundedRead.output, prerequisites, outputPrefix);
+      const pollDelayMs = Math.min(this.dependencies.pollIntervalMs, Math.max(0, deadline - this.dependencies.now()));
+      await this.dependencies.sleep(pollDelayMs);
+    }
+    return infrastructureFailure("timeout", `Timed out waiting for launchd probe ${target}.`);
+  }
+
+  private async cleanup(
+    target: string,
+    directory: string | null,
+    bootstrapState: "not-loaded" | "loaded" | "uncertain",
+  ): Promise<NativeServiceProbeResult | null> {
+    const failures: string[] = [];
+    const shouldBootout = bootstrapState !== "not-loaded";
+    if (shouldBootout) {
+      // A failed or timed-out bootstrap may still have loaded the unique label.
+      // Bootout is the only race-free cleanup; an explicit not-loaded response
+      // is success when bootstrap completion was uncertain.
+      const absenceIsSuccess = bootstrapState === "uncertain";
+      const bootout = await this.dependencies.commandRunner.run(
+        "launchctl",
+        ["bootout", target],
+        this.dependencies.commandTimeoutMs,
+      );
+      if (
+        (bootout.kind !== "completed" || bootout.status !== 0)
+        && !(absenceIsSuccess && launchdTargetNotLoaded(bootout))
+      ) {
+        failures.push(`bootout failed: ${commandFailureDetail(bootout)}`);
+      }
+    }
+    if (directory !== null) {
+      try {
+        await this.dependencies.fileSystem.removeDirectory(directory);
+      } catch (error: unknown) {
+        failures.push(`temporary-file removal failed: ${errorMessage(error)}`);
+      }
+    }
+    return failures.length === 0
+      ? null
+      : infrastructureFailure("cleanup", `Launchd probe cleanup failed for ${target}: ${failures.join("; ")}`);
+  }
+}
+
+export function createNativeServiceAuthoritativeProbe(): NativeServiceAuthoritativeProbe {
+  const commandRunner = new SpawnProbeCommandRunner();
+  const common: CommonProbeDependencies = {
+    commandRunner,
+    createUniqueId: randomUUID,
+    commandTimeoutMs: defaultCommandTimeoutMs,
+  };
+  const systemd = new SystemdNativeServiceProbe(common);
+  const launchd = new LaunchdNativeServiceProbe({
+    ...common,
+    fileSystem: nodeLaunchdProbeFileSystem,
+    uid: userInfo().uid,
+    now: performance.now.bind(performance),
+    sleep: (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
+    probeTimeoutMs: defaultProbeTimeoutMs,
+    pollIntervalMs: defaultPollIntervalMs,
+  });
+  return {
+    run: (request) => request.backend.kind === "systemd" ? systemd.run(request) : launchd.run(request),
+  };
+}
+
+export function systemdRunArguments(
+  request: NativeServiceProbeRequest,
+  unitName: string,
+  shellCommand: string,
+): readonly string[] {
+  return [
+    "--user",
+    "--wait",
+    "--collect",
+    "--pipe",
+    "--quiet",
+    `--unit=${unitName}`,
+    "--property=RuntimeMaxSec=15s",
+    "--property=TimeoutStopSec=5s",
+    ...Object.entries(request.environment).map(([key, value]) => `--setenv=${key}=${value}`),
+    ...(request.workingDirectory === null ? [] : [`--working-directory=${request.workingDirectory}`]),
+    "/usr/bin/env",
+    escapeSystemdCommandExpansion(request.shell.executable),
+    "-lc",
+    escapeSystemdCommandExpansion(shellCommand),
+  ];
+}
+
+function escapeSystemdCommandExpansion(value: string): string {
+  return value.replaceAll("$", () => "$$");
+}
+
+export function launchdProbePlist(
+  request: NativeServiceProbeRequest,
+  label: string,
+  shellCommand: string,
+  stdoutPath: string,
+  stderrPath: string,
+): string {
+  const argumentsXml = ["/usr/bin/env", request.shell.executable, "-lc", shellCommand]
+    .map((argument) => `    <string>${xmlEscape(argument)}</string>`)
+    .join("\n");
+  const environmentEntries = Object.entries(request.environment);
+  const environmentXml = environmentEntries.length === 0
+    ? ""
+    : `  <key>EnvironmentVariables</key>\n  <dict>\n${environmentEntries.map(([key, value]) => plistString(key, value, "    ")).join("")}  </dict>\n`;
+  const workingDirectoryXml = request.workingDirectory === null
+    ? ""
+    : plistString("WorkingDirectory", request.workingDirectory);
+  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">
+<plist version="1.0">
+<dict>
+${plistString("Label", label)}  <key>ProgramArguments</key>
+  <array>
+${argumentsXml}
+  </array>
+${workingDirectoryXml}${environmentXml}  <key>RunAtLoad</key>
+  <true/>
+  <key>HardResourceLimits</key>
+  <dict>
+    <key>FileSize</key>
+    <integer>${String(maxLaunchdProbeFileBytes)}</integer>
+  </dict>
+${plistString("StandardOutPath", stdoutPath)}${plistString("StandardErrorPath", stderrPath)}</dict>
+</plist>
+`;
+}
+
+export class SpawnProbeCommandRunner implements ProbeCommandRunner {
+  public run(command: string, args: readonly string[], timeoutMs: number): Promise<ProbeCommandResult> {
+    return new Promise((resolve) => {
+      const child = spawn(command, args, { stdio: ["ignore", "pipe", "pipe"] });
+      let stdout = "";
+      let stderr = "";
+      let capturedBytes = 0;
+      let spawnFailure: string | null = null;
+      let settled = false;
+
+      const finish = (result: ProbeCommandResult, terminate: boolean): void => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timeout);
+        if (terminate) {
+          child.kill("SIGKILL");
+          child.stdout.destroy();
+          child.stderr.destroy();
+          child.unref();
+        }
+        resolve(result);
+      };
+      const capture = (stream: "stdout" | "stderr", chunk: string): void => {
+        if (settled) return;
+        const bytes = Buffer.byteLength(chunk);
+        if (capturedBytes + bytes > maxCapturedCommandOutputBytes) {
+          finish({ kind: "output-limit", stdout, stderr }, true);
+          return;
+        }
+        capturedBytes += bytes;
+        if (stream === "stdout") stdout += chunk;
+        else stderr += chunk;
+      };
+
+      child.stdout.setEncoding("utf8");
+      child.stderr.setEncoding("utf8");
+      child.stdout.on("data", (chunk: string) => { capture("stdout", chunk); });
+      child.stderr.on("data", (chunk: string) => { capture("stderr", chunk); });
+      child.on("error", (error) => { spawnFailure = error.message; });
+      const timeout = setTimeout(() => {
+        finish({ kind: "timeout", stdout, stderr }, true);
+      }, timeoutMs);
+      child.on("close", (status) => {
+        if (spawnFailure !== null) {
+          finish({ kind: "spawn-failure", message: spawnFailure, stdout, stderr }, false);
+        } else {
+          finish({ kind: "completed", status: status ?? 1, stdout, stderr }, false);
+        }
+      });
+    });
+  }
+}
+
+const nodeLaunchdProbeFileSystem: LaunchdProbeFileSystem = {
+  createTemporaryDirectory: (prefix) => mkdtemp(prefix),
+  writeFile: (path, contents, mode) => writeFile(path, contents, { encoding: "utf8", mode }),
+  readOptionalFile: async (path) => {
+    try {
+      return await readFile(path, "utf8");
+    } catch (error: unknown) {
+      if (isNodeErrorWithCode(error, "ENOENT")) return null;
+      throw error;
+    }
+  },
+  removeDirectory: (path) => rm(path, { recursive: true, force: true }),
+};
+
+function readOptionalFileBounded(
+  fileSystem: LaunchdProbeFileSystem,
+  path: string,
+  timeoutMs: number,
+): Promise<
+  | { kind: "read"; output: string | null }
+  | { kind: "read-failure"; error: unknown }
+  | { kind: "deadline" }
+> {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (result:
+      | { kind: "read"; output: string | null }
+      | { kind: "read-failure"; error: unknown }
+      | { kind: "deadline" }): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      resolve(result);
+    };
+    const timeout = setTimeout(() => { finish({ kind: "deadline" }); }, timeoutMs);
+    void fileSystem.readOptionalFile(path).then(
+      (output) => { finish({ kind: "read", output }); },
+      (error: unknown) => { finish({ kind: "read-failure", error }); },
+    );
+  });
+}
+
+function prerequisiteProbeCommand(
+  shell: NativeServiceShellName,
+  prerequisites: readonly NativeServicePrerequisite[],
+  outputPrefix: string,
+  resultFiles?: { pendingPath: string; completedPath: string },
+): string {
+  const markerPath = resultFiles?.pendingPath;
+  const checks = prerequisites.map((prerequisite) => {
+    const check = nativeServicePrerequisiteShellCheck(shell, prerequisite);
+    const encodedId = Buffer.from(prerequisite.id, "utf8").toString("base64");
+    const satisfied = markerCommand(shell, outputPrefix, encodedId, "satisfied", markerPath);
+    const unsatisfied = markerCommand(shell, outputPrefix, encodedId, "unsatisfied", markerPath);
+    return `${check} >/dev/null 2>&1 && ${satisfied} || ${unsatisfied}`;
+  }).join("; ") || ":";
+  if (resultFiles === undefined) return checks;
+  const pending = shellQuote(shell, resultFiles.pendingPath);
+  const completed = shellQuote(shell, resultFiles.completedPath);
+  return `printf '%s' '' > ${pending}; ${checks}; /bin/mv ${pending} ${completed}`;
+}
+
+export function nativeServicePrerequisiteShellCheck(shell: NativeServiceShellName, prerequisite: NativeServicePrerequisite): string {
+  switch (prerequisite.kind) {
+    case "command-available":
+      return externalExecutableShellCheck(shell, prerequisite.command);
+    case "node-version": {
+      const script = `const major=Number(process.versions.node.split('.')[0]);process.exit(major>=${String(prerequisite.minimumMajor)}?0:1)`;
+      return externalExecutableShellCheck(shell, "node", ["-e", script]);
+    }
+    case "readable-file": {
+      const path = shellQuote(shell, prerequisite.path);
+      return `test -f ${path} && test -r ${path}`;
+    }
+    case "package-scripts": {
+      const script = "const p=require(process.argv[1]);const names=process.argv.slice(2);process.exit(names.every((name)=>typeof p.scripts?.[name]==='string')?0:1)";
+      return externalExecutableShellCheck(shell, "node", ["-e", script, prerequisite.packageJsonPath, ...prerequisite.scripts]);
+    }
+  }
+}
+
+function externalExecutableShellCheck(
+  shell: NativeServiceShellName,
+  command: string,
+  arguments_: readonly string[] = [],
+): string {
+  const quotedCommand = shellQuote(shell, command);
+  const quotedArguments = arguments_.map((argument) => shellQuote(shell, argument)).join(" ");
+  if (shell === "fish") {
+    const invocation = quotedArguments === "" ? "" : `; and $pi_web_probe_executable[1] ${quotedArguments}`;
+    return `set -l pi_web_probe_executable (command -v ${quotedCommand}); and test (count $pi_web_probe_executable) -eq 1; and string match -q '*/*' -- $pi_web_probe_executable[1]; and test -f $pi_web_probe_executable[1]; and test -x $pi_web_probe_executable[1]${invocation}`;
+  }
+  const invocation = quotedArguments === "" ? "" : ` && "$pi_web_probe_executable" ${quotedArguments}`;
+  return `pi_web_probe_executable=$(command -v ${quotedCommand}) && case "$pi_web_probe_executable" in */*) test -f "$pi_web_probe_executable" && test -x "$pi_web_probe_executable"${invocation};; *) false;; esac`;
+}
+
+function markerCommand(
+  shell: NativeServiceShellName,
+  outputPrefix: string,
+  encodedId: string,
+  status: "satisfied" | "unsatisfied",
+  outputPath?: string,
+): string {
+  const redirect = outputPath === undefined ? "" : ` >> ${shellQuote(shell, outputPath)}`;
+  return `printf '%s\\t%s\\t%s\\n' ${shellQuote(shell, outputPrefix)} ${shellQuote(shell, encodedId)} ${shellQuote(shell, status)}${redirect}`;
+}
+
+function parseProbeOutput(
+  stdout: string,
+  prerequisites: readonly NativeServicePrerequisite[],
+  outputPrefix: string,
+): NativeServiceProbeResult {
+  const expected = new Map(prerequisites.map((prerequisite) => [
+    Buffer.from(prerequisite.id, "utf8").toString("base64"),
+    prerequisite,
+  ]));
+  const outcomes = new Map<string, NativeServicePrerequisiteOutcome>();
+  for (const line of stdout.split(/\r?\n/u)) {
+    if (!line.startsWith(`${outputPrefix}\t`)) continue;
+    const fields = line.split("\t");
+    if (fields.length !== 3) {
+      return infrastructureFailure("malformed-output", "Authoritative probe returned a malformed result line.");
+    }
+    const encodedId = fields[1];
+    const status = fields[2];
+    const prerequisite = encodedId === undefined ? undefined : expected.get(encodedId);
+    if (prerequisite === undefined || (status !== "satisfied" && status !== "unsatisfied")) {
+      return infrastructureFailure("malformed-output", "Authoritative probe returned an unexpected result.");
+    }
+    if (outcomes.has(prerequisite.id)) {
+      return infrastructureFailure("malformed-output", `Authoritative probe returned duplicate outcome ${prerequisite.id}.`);
+    }
+    outcomes.set(prerequisite.id, {
+      prerequisiteId: prerequisite.id,
+      status,
+      detail: status === "satisfied" ? null : unsatisfiedDetail(prerequisite),
+    });
+  }
+  const missing = prerequisites.find((prerequisite) => !outcomes.has(prerequisite.id));
+  if (missing !== undefined) {
+    return infrastructureFailure("malformed-output", `Authoritative probe returned no outcome for ${missing.id}.`);
+  }
+  return { kind: "completed", outcomes: [...outcomes.values()] };
+}
+
+function unsatisfiedDetail(prerequisite: NativeServicePrerequisite): string {
+  switch (prerequisite.kind) {
+    case "command-available":
+      return `${prerequisite.command} did not resolve to an external executable in the native service environment.`;
+    case "node-version":
+      return `node >= ${String(prerequisite.minimumMajor)} was not available in the native service environment.`;
+    case "readable-file":
+      return `${prerequisite.path} was not a readable regular file in the native service environment.`;
+    case "package-scripts":
+      return `${prerequisite.packageJsonPath} did not provide scripts ${prerequisite.scripts.join(", ")} in the native service environment.`;
+  }
+}
+
+function shellQuote(shell: NativeServiceShellName, value: string): string {
+  return shell === "fish"
+    ? `'${value.replaceAll("\\", "\\\\").replaceAll("'", "\\'")}'`
+    : `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+function safeUniqueId(value: string): string {
+  const safe = value.toLowerCase().replaceAll(/[^a-z0-9-]/gu, "").slice(0, 48);
+  return safe === "" ? "probe" : safe;
+}
+
+function launchdTargetNotLoaded(result: ProbeCommandResult): boolean {
+  if (result.kind !== "completed" || result.status === 0) return false;
+  return /(?:could not find (?:specified )?service|service not found|no such process)/iu.test(`${result.stderr}\n${result.stdout}`);
+}
+
+function plistString(key: string, value: string, indent = "  "): string {
+  return `${indent}<key>${xmlEscape(key)}</key>\n${indent}<string>${xmlEscape(value)}</string>\n`;
+}
+
+function xmlEscape(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&apos;");
+}
+
+function commandInfrastructureFailure(action: string, result: ProbeCommandResult): NativeServiceProbeResult {
+  if (result.kind === "timeout") return infrastructureFailure("timeout", `Timed out while trying to ${action}.`);
+  return infrastructureFailure("manager", `Could not ${action}: ${commandFailureDetail(result)}`);
+}
+
+function commandFailureDetail(result: ProbeCommandResult): string {
+  if (result.kind === "timeout") return "command timed out";
+  if (result.kind === "spawn-failure") return result.message;
+  if (result.kind === "output-limit") return "command output exceeded the capture limit";
+  return firstOutput(result.stderr, result.stdout, `exit status ${String(result.status)}`);
+}
+
+function infrastructureFailure(
+  reason: "manager" | "timeout" | "malformed-output" | "cleanup",
+  message: string,
+): NativeServiceProbeResult {
+  return { kind: "infrastructure-failure", reason, message };
+}
+
+function firstOutput(...values: string[]): string {
+  for (const value of values) {
+    const line = value.trim().split(/\r?\n/u).find((candidate) => candidate.trim() !== "");
+    if (line !== undefined) return line.trim();
+  }
+  return "no output";
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function isNodeErrorWithCode(error: unknown, code: string): error is NodeJS.ErrnoException {
+  return error instanceof Error && "code" in error && error.code === code;
+}

src/nativeServices/serviceRendering.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from "vitest";
+import {
+  createDevelopmentNativeServicePlan,
+  type NativeServicePlan,
+  type NativeServicePlanService,
+} from "./servicePlan.js";
+import { renderLaunchdPlist, renderSystemdUnit } from "./serviceRendering.js";
+
+function developmentPlan(kind: "systemd" | "launchd"): NativeServicePlan {
+  return createDevelopmentNativeServicePlan({
+    backend: { kind, label: kind },
+    shell: {
+      name: "zsh",
+      executable: "/bin/zsh",
+      source: "detected",
+      detectedExecutable: "/bin/zsh",
+    },
+    environment: { PI_WEB_CONFIG: "/home/user/config with \"quote\".json" },
+    workingDirectory: "/checkout with space",
+    packageJsonPath: "/checkout with space/package.json",
+  });
+}
+
+function planService(plan: NativeServicePlan, index: number): NativeServicePlanService {
+  const service = plan.services[index];
+  if (service === undefined) throw new Error(`Missing service at index ${String(index)}`);
+  return service;
+}
+
+describe("native service rendering", () => {
+  it("renders systemd entirely from the canonical plan", () => {
+    const plan = developmentPlan("systemd");
+    const unit = renderSystemdUnit(plan, planService(plan, 1));
+
+    expect(unit).toContain("Description=PI WEB UI dev server");
+    expect(unit).toContain("After=pi-web-sessiond.service\nWants=pi-web-sessiond.service");
+    expect(unit).toContain("WorkingDirectory=/checkout\\x20with\\x20space");
+    expect(unit).toContain('Environment="PI_WEB_CONFIG=/home/user/config with \\"quote\\".json"');
+    expect(unit).toContain('ExecStart=/usr/bin/env "/bin/zsh" -lc "exec /usr/bin/env bash -c \'trap \\"kill 0\\" EXIT;');
+    expect(unit).toContain("Restart=no");
+  });
+
+  it("escapes systemd specifiers and line controls without changing directives", () => {
+    const plan = createDevelopmentNativeServicePlan({
+      backend: { kind: "systemd", label: "systemd" },
+      shell: {
+        name: "bash",
+        executable: "/shell $HOME/%h/bash",
+        source: "detected",
+        detectedExecutable: "/shell $HOME/%h/bash",
+      },
+      environment: { PI_WEB_CONFIG: "/config/%h\nEnvironment=INJECTED=yes" },
+      workingDirectory: "/checkout %h\nwith newline",
+      packageJsonPath: "/checkout/package.json",
+    });
+    const unit = renderSystemdUnit(plan, planService(plan, 0));
+
+    expect(unit).toContain("WorkingDirectory=/checkout\\x20%%h\\nwith\\x20newline");
+    expect(unit).toContain('Environment="PI_WEB_CONFIG=/config/%%h\\nEnvironment=INJECTED=yes"');
+    expect(unit).toContain('ExecStart=/usr/bin/env "/shell $$HOME/%%h/bash"');
+    expect(unit.match(/^Environment=/gmu)).toHaveLength(1);
+  });
+
+  it("renders launchd entirely from the canonical plan", () => {
+    const plan = developmentPlan("launchd");
+    const plist = renderLaunchdPlist(plan, planService(plan, 0), "/logs");
+
+    expect(plist).toContain("<string>com.pi-web.sessiond</string>");
+    expect(plist).toContain("<string>/bin/zsh</string>");
+    expect(plist).toContain("<string>exec npm run start:sessiond</string>");
+    expect(plist).toContain("<key>WorkingDirectory</key>\n  <string>/checkout with space</string>");
+    expect(plist).toContain("<key>PI_WEB_CONFIG</key>\n    <string>/home/user/config with &quot;quote&quot;.json</string>");
+    expect(plist.match(/<string>\/logs\/sessiond\.log<\/string>/gu)).toHaveLength(2);
+    expect(plist).not.toContain("<string>\\logs\\sessiond.log</string>");
+    expect(plist).not.toContain("<key>KeepAlive</key>");
+  });
+
+  it("rejects a service from a different plan", () => {
+    const first = developmentPlan("systemd");
+    const second = developmentPlan("systemd");
+    expect(() => renderSystemdUnit(first, planService(second, 0))).toThrow("not a member");
+  });
+});

src/nativeServices/serviceRendering.ts

@@ -0,0 +1,139 @@
+import { posix as posixPath } from "node:path";
+import type {
+  NativeServiceId,
+  NativeServicePlan,
+  NativeServicePlanService,
+} from "./servicePlan.js";
+
+export function renderSystemdUnit(
+  plan: NativeServicePlan,
+  service: NativeServicePlanService,
+): string {
+  assertPlanService(plan, service);
+  assertBackend(plan, "systemd");
+  const workingDirectory = service.workingDirectory === null
+    ? ""
+    : `WorkingDirectory=${systemdPathValue(service.workingDirectory)}\n`;
+  const restart = service.restart === "on-failure"
+    ? "Restart=on-failure\nRestartSec=2\n"
+    : "Restart=no\n";
+  return `[Unit]
+Description=${service.description}
+${systemdDependencyLine(plan, "After", service.after)}${systemdDependencyLine(plan, "Wants", service.wants)}[Service]
+Type=simple
+${workingDirectory}${systemdEnvironmentLines(service.environment)}ExecStart=/usr/bin/env ${systemdExecArgument(plan.shell.executable)} -lc ${systemdExecArgument(service.shellCommand)}
+${restart}
+[Install]
+WantedBy=default.target
+`;
+}
+
+export function renderLaunchdPlist(
+  plan: NativeServicePlan,
+  service: NativeServicePlanService,
+  logDirectory: string,
+): string {
+  assertPlanService(plan, service);
+  assertBackend(plan, "launchd");
+  const programArguments = ["/usr/bin/env", plan.shell.executable, "-lc", service.shellCommand];
+  const workingDirectory = service.workingDirectory === null
+    ? ""
+    : plistString("WorkingDirectory", service.workingDirectory);
+  const keepAlive = service.restart === "on-failure"
+    ? "  <key>KeepAlive</key>\n  <dict>\n    <key>SuccessfulExit</key>\n    <false/>\n  </dict>\n"
+    : "";
+  const logPath = posixPath.join(logDirectory, service.manager.logName);
+  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">
+<plist version="1.0">
+<dict>
+${plistString("Label", service.manager.launchdLabel)}${plistProgramArguments(programArguments)}${workingDirectory}${plistEnvironment(service.environment)}  <key>RunAtLoad</key>
+  <true/>
+${keepAlive}${plistString("StandardOutPath", logPath)}${plistString("StandardErrorPath", logPath)}</dict>
+</plist>
+`;
+}
+
+function assertPlanService(plan: NativeServicePlan, service: NativeServicePlanService): void {
+  if (!plan.services.includes(service)) {
+    throw new Error(`Cannot render ${service.id}; it is not a member of the supplied native service plan.`);
+  }
+}
+
+function assertBackend(plan: NativeServicePlan, expected: "systemd" | "launchd"): void {
+  if (plan.backend.kind !== expected) {
+    throw new Error(`Cannot render ${expected} service from a ${plan.backend.kind} native service plan.`);
+  }
+}
+
+function systemdDependencyLine(
+  plan: NativeServicePlan,
+  name: "After" | "Wants",
+  ids: readonly NativeServiceId[],
+): string {
+  if (ids.length === 0) return "";
+  const names = ids.map((id) => {
+    const dependency = plan.services.find((service) => service.id === id);
+    if (dependency === undefined) throw new Error(`Service ${id} is not present in the native service plan.`);
+    return dependency.manager.systemdName;
+  });
+  return `${name}=${names.join(" ")}\n`;
+}
+
+function systemdEnvironmentLines(environment: Readonly<Record<string, string>>): string {
+  return Object.entries(environment)
+    .map(([key, value]) => `Environment=${systemdQuotedDirectiveValue(`${key}=${value}`)}\n`)
+    .join("");
+}
+
+function systemdExecArgument(value: string): string {
+  return `"${systemdEscape(value.replaceAll("%", "%%").replaceAll("$", () => "$$"), false)}"`;
+}
+
+function systemdQuotedDirectiveValue(value: string): string {
+  return `"${systemdEscape(value.replaceAll("%", "%%"), false)}"`;
+}
+
+function systemdPathValue(value: string): string {
+  return systemdEscape(value.replaceAll("%", "%%"), true);
+}
+
+function systemdEscape(value: string, escapeSpaces: boolean): string {
+  let escaped = "";
+  for (const character of value) {
+    const code = character.codePointAt(0) ?? 0;
+    if (character === "\\") escaped += "\\\\";
+    else if (character === '"') escaped += escapeSpaces ? "\\x22" : '\\"';
+    else if (character === "'" && escapeSpaces) escaped += "\\x27";
+    else if (character === " " && escapeSpaces) escaped += "\\x20";
+    else if (character === "\n") escaped += "\\n";
+    else if (character === "\r") escaped += "\\r";
+    else if (character === "\t") escaped += "\\t";
+    else if (code < 0x20 || code === 0x7f) escaped += `\\x${code.toString(16).padStart(2, "0")}`;
+    else escaped += character;
+  }
+  return escaped;
+}
+
+function plistProgramArguments(arguments_: readonly string[]): string {
+  return `  <key>ProgramArguments</key>\n  <array>\n${arguments_.map((argument) => `    <string>${xmlEscape(argument)}</string>`).join("\n")}\n  </array>\n`;
+}
+
+function plistEnvironment(environment: Readonly<Record<string, string>>): string {
+  const entries = Object.entries(environment);
+  if (entries.length === 0) return "";
+  return `  <key>EnvironmentVariables</key>\n  <dict>\n${entries.map(([key, value]) => plistString(key, value, "    ")).join("")}  </dict>\n`;
+}
+
+function plistString(key: string, value: string, indent = "  "): string {
+  return `${indent}<key>${xmlEscape(key)}</key>\n${indent}<string>${xmlEscape(value)}</string>\n`;
+}
+
+function xmlEscape(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&apos;");
+}

src/plugin-api.ts

@@ -99,6 +99,8 @@ export interface PluginRuntimeContext {
   refreshFiles: () => void | Promise<void>;
   refreshGit: () => void | Promise<void>;
   refreshAppData: () => void | Promise<void>;
+  /** Force a fresh PI WEB release check on the selected machine. Optional for compatibility with older hosts. */
+  checkForPiWebUpdates?: () => void | Promise<void>;
   reloadPage: () => void;
   startSession: () => void | Promise<void>;
   archiveSession: () => void | Promise<void>;

src/server/app.piWebStatus.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it, vi } from "vitest";
+import type { PiWebStatusResponse } from "../shared/apiTypes.js";
+import { buildApp } from "./app.js";
+
+describe("PI WEB status routes", () => {
+  it("forces a fresh status load when refresh is requested", async () => {
+    const get = vi.fn(() => Promise.resolve(status("cached")));
+    const refresh = vi.fn(() => Promise.resolve(status("forced")));
+    const app = await buildApp({ piWebStatusCache: { get, refresh }, clientDist: false, logger: false });
+
+    try {
+      const cachedResponse = await app.inject({ method: "GET", url: "/api/pi-web/status" });
+      const forcedResponse = await app.inject({ method: "GET", url: "/api/pi-web/status?refresh=1" });
+
+      expect(cachedResponse.json<PiWebStatusResponse>().generatedAt).toBe("cached");
+      expect(forcedResponse.json<PiWebStatusResponse>().generatedAt).toBe("forced");
+      expect(get).toHaveBeenCalledOnce();
+      expect(refresh).toHaveBeenCalledOnce();
+      expect(refresh).toHaveBeenCalledWith({ force: true });
+    } finally {
+      await app.close();
+    }
+  });
+});
+
+function status(generatedAt: string): PiWebStatusResponse {
+  return {
+    packageName: "@jmfederico/pi-web",
+    generatedAt,
+    components: {
+      web: { component: "web", label: "Web/UI", stale: false, available: true },
+      sessiond: { component: "sessiond", label: "Session daemon", stale: false, available: true },
+    },
+    release: { packageName: "@jmfederico/pi-web", updateAvailable: false },
+    commands: {},
+    messages: [],
+  };
+}

src/server/app.plugins.test.ts

@@ -24,6 +24,11 @@ describe("buildApp PI WEB plugin routes", () => {
     expect(assetResponse.headers["content-type"]).toContain("application/javascript");
     expect(assetResponse.body).toBe("export default {};");
 
+    const svgResponse = await appTestContext.app.inject({ method: "GET", url: "/pi-web-plugins/fake/assets/icon.svg" });
+    expect(svgResponse.statusCode).toBe(200);
+    expect(svgResponse.headers["content-type"]).toContain("image/svg+xml");
+    expect(svgResponse.body).toContain("<svg");
+
     const missingResponse = await appTestContext.app.inject({ method: "GET", url: "/pi-web-plugins/fake/missing.js" });
     expect(missingResponse.statusCode).toBe(404);
   });

src/server/app.remoteProxy.test.ts

@@ -25,6 +25,23 @@ describe("buildApp remote machine proxy routes", () => {
     expect(request).toHaveBeenCalledWith("GET", "/api/projects?active=true", undefined);
   });
 
+  it("preserves the force-refresh query when proxying update checks", async () => {
+    const addResponse = await appTestContext.app.inject({ method: "POST", url: "/api/machines", payload: { name: "Remote", baseUrl: "https://remote.example.test/" } });
+    const remote = addResponse.json<{ id: string }>();
+    const request = vi.fn<MachineClient["request"]>(() => Promise.resolve({
+      statusCode: 200,
+      headers: { "content-type": "application/json" },
+      body: Readable.from([JSON.stringify({ ok: true })]),
+    }));
+    appTestContext.remoteClient = fakeRemoteClient({ request });
+
+    const response = await appTestContext.app.inject({ method: "GET", url: `/api/machines/${remote.id}/pi-web/status?refresh=1` });
+
+    expect(response.statusCode).toBe(200);
+    expect(response.json()).toEqual({ ok: true });
+    expect(request).toHaveBeenCalledWith("GET", "/api/pi-web/status?refresh=1", undefined);
+  });
+
   it("proxies remote Pi package routes and gives package mutations a longer timeout", async () => {
     const addResponse = await appTestContext.app.inject({ method: "POST", url: "/api/machines", payload: { name: "Remote", baseUrl: "https://remote.example.test/" } });
     const remote = addResponse.json<{ id: string }>();

src/server/app.testSupport.ts

@@ -100,7 +100,7 @@ export function registerAppTestHooks(): void {
       piWebPlugins: {
         manifest: () => Promise.resolve({ plugins: [{ id: "fake", module: "/pi-web-plugins/fake/plugin.js?v=1", source: "test", scope: "local", machineSpecific: false }] }),
         plugins: () => Promise.resolve({ plugins: [{ id: "fake", module: "/pi-web-plugins/fake/plugin.js?v=1", source: "test", scope: "local", machineSpecific: false, enabled: true }] }),
-        readAsset: (pluginId, assetPath) => Promise.resolve(pluginId === "fake" && assetPath === "plugin.js" ? { content: Buffer.from("export default {};"), contentType: "application/javascript; charset=utf-8" } : undefined),
+        readAsset: fakePiWebPluginAsset,
       },
       clientDist: false,
       logger: false,
@@ -123,6 +123,13 @@ export function registerAppTestHooks(): void {
   });
 }
 
+function fakePiWebPluginAsset(pluginId: string, assetPath: string): Promise<{ content: Buffer; contentType: string } | undefined> {
+  if (pluginId !== "fake") return Promise.resolve(undefined);
+  if (assetPath === "plugin.js") return Promise.resolve({ content: Buffer.from("export default {};"), contentType: "application/javascript; charset=utf-8" });
+  if (assetPath === "assets/icon.svg") return Promise.resolve({ content: Buffer.from('<svg xmlns="http://www.w3.org/2000/svg"></svg>'), contentType: "image/svg+xml" });
+  return Promise.resolve(undefined);
+}
+
 export interface CapturedSessionDaemonRequest {
   method: string;
   path: string;

src/server/app.ts

@@ -23,7 +23,7 @@ import { createFilePiWebConfigService, registerConfigRoutes, registerLocalMachin
 import { PiWebPluginService } from "./piWebPluginService.js";
 import { createDefaultPiPackageService, type PiPackageService } from "./piPackageService.js";
 import { registerPiPackageRoutes } from "./piPackageRoutes.js";
-import { createPiWebStatusCache } from "./piWebStatusCache.js";
+import { createPiWebStatusCache, type PiWebStatusCache } from "./piWebStatusCache.js";
 import { getPiWebRuntime, getPiWebStatus, getPiWebVersionStatus } from "./piWebStatus.js";
 import { MachineService } from "./machines/machineService.js";
 import { registerMachineRoutes } from "./machines/machineRoutes.js";
@@ -38,6 +38,7 @@ export interface AppDependencies {
   sessionDaemon?: SessionProxyDaemon;
   piWebPlugins?: Pick<PiWebPluginService, "manifest" | "plugins" | "readAsset">;
   piPackages?: PiPackageService;
+  piWebStatusCache?: PiWebStatusCache;
   config?: PiWebConfigService;
   clientDist?: string | false;
   logger?: FastifyServerOptions["logger"];
@@ -136,9 +137,10 @@ export async function buildApp(deps: AppDependencies = {}): Promise<FastifyInsta
   const piPackages = deps.piPackages ?? createDefaultPiPackageService();
   const configService = deps.config ?? createFilePiWebConfigService();
   const sessionDaemon = deps.sessionDaemon ?? new SessionDaemonClient();
-  const piWebStatusCache = createPiWebStatusCache(() => getPiWebStatus(sessionDaemon), {
-    onError: (error) => { app.log.warn({ err: error }, "failed to refresh PI WEB status cache"); },
-  });
+  const piWebStatusCache = deps.piWebStatusCache ?? createPiWebStatusCache(
+    ({ force }) => getPiWebStatus(sessionDaemon, { forceReleaseCheck: force }),
+    { onError: (error) => { app.log.warn({ err: error }, "failed to refresh PI WEB status cache"); } },
+  );
   const machines = deps.machines ?? new MachineService(undefined, {
     localRuntime: () => getPiWebRuntime(sessionDaemon),
   });
@@ -153,7 +155,9 @@ export async function buildApp(deps: AppDependencies = {}): Promise<FastifyInsta
     return reply.type(asset.contentType).send(asset.content);
   });
 
-  app.get("/api/pi-web/status", async () => piWebStatusCache.get());
+  app.get<{ Querystring: { refresh?: string } }>("/api/pi-web/status", async (request) => request.query.refresh === "1"
+    ? piWebStatusCache.refresh({ force: true })
+    : piWebStatusCache.get());
   app.get("/api/pi-web/version", async () => getPiWebVersionStatus(sessionDaemon));
   app.get("/api/pi-web/runtime", async () => getPiWebRuntime(sessionDaemon));
   app.get("/api/plugins", async () => piWebPlugins.plugins());

src/server/dockerControlAssets.test.ts

@@ -39,20 +39,24 @@ describe("Docker command assets", () => {
       execUtf8("sh", ["-n", dockerEntrypoint], process.env),
       execUtf8("sh", ["-n", join(repoRoot, "docker", "install.sh")], process.env),
       execUtf8("sh", ["-n", join(repoRoot, "docker", "internal", "dev", "compose")], process.env),
+      execUtf8("bash", ["-n", join(repoRoot, "docker", "internal", "dev", "sync-node-modules")], process.env),
       execUtf8("sh", ["-n", join(repoRoot, "docker", "internal", "host-profile.sh")], process.env),
     ]);
   });
 
   it("packages the canonical Docker command and internal support assets", async () => {
-    const [dockerfile, devDockerfile, runtimeCompose, devCompose, installer, devWrapper, dockerignore] = await Promise.all([
+    const [dockerfile, devDockerfile, runtimeCompose, devCompose, installer, devWrapper, dependencySync, dockerignore] = await Promise.all([
       readRepoFile("docker/Dockerfile"),
       readRepoFile("docker/Dockerfile.dev"),
       readRepoFile("docker/compose.yml"),
       readRepoFile("docker/compose.dev.yml"),
       readRepoFile("docker/install.sh"),
       readRepoFile("docker/internal/dev/compose"),
+      readRepoFile("docker/internal/dev/sync-node-modules"),
       readRepoFile("docker/.dockerignore"),
     ]);
+    const customImageHooksIndex = devDockerfile.indexOf("for script in /tmp/pi-web-custom-image.d/*.sh");
+    const dependencyGenerationIndex = devDockerfile.indexOf("/opt/pi-web-dev-dependencies/generation");
 
     expect(dockerfile).toContain("COPY pi-web-docker /usr/local/bin/pi-web-docker");
     expect(dockerfile).toContain("COPY internal/bin/hostexec /usr/local/bin/hostexec");
@@ -62,6 +66,12 @@ describe("Docker command assets", () => {
     expect(dockerfile).not.toContain("@earendil-works/pi-coding-agent@");
     expect(devDockerfile).toContain("COPY docker/pi-web-docker /usr/local/bin/pi-web-docker");
     expect(devDockerfile).toContain("COPY docker/internal/bin/hostexec /usr/local/bin/hostexec");
+    expect(devDockerfile).toContain("COPY --chmod=0755 docker/internal/dev/sync-node-modules /usr/local/sbin/pi-web-dev-sync-node-modules");
+    expect(devDockerfile).toContain("/opt/pi-web-dev-dependencies/node_modules");
+    // Hooks can mutate the dependency seed, so its cache generation must be finalized afterward.
+    expect(customImageHooksIndex).toBeGreaterThanOrEqual(0);
+    expect(dependencyGenerationIndex).toBeGreaterThan(customImageHooksIndex);
+    expect(dependencySync).toContain(".pi-web-dev-dependency-generation");
     expect(dockerignore).toContain("!pi-web-docker");
     expect(dockerignore).toContain("!internal/bin/hostexec");
     expect(installer).toContain("write_asset pi-web-docker 0755");
@@ -83,6 +93,8 @@ describe("Docker command assets", () => {
     expect(devCompose).toContain("PI_WEB_DOCKER_DEV_REPO_ROOT: ${PI_WEB_DOCKER_DEV_REPO_ROOT:?set by docker/pi-web-docker --dev}");
     expect(devCompose).toContain("PI_WEB_DOCKER_HELPER_IMAGE: ${PI_WEB_DEV_IMAGE:-pi-web:dev}");
     expect(devCompose).toContain("COMPOSE_PROJECT_NAME: ${COMPOSE_PROJECT_NAME:-pi-web-dev}");
+    expect(devCompose).toContain("/usr/local/sbin/pi-web-dev-sync-node-modules");
+    expect(devCompose.match(/volumes: \*pi-web-dev-volumes/g)).toHaveLength(3);
   });
 
   dockerCommandIt("fetches remote installer assets without clobbering the write target", async () => {
@@ -247,6 +259,84 @@ describe("Docker command assets", () => {
     expect(await readFile(helperLog, "utf8")).toBe("allow=1 args=ps\n");
   });
 
+  dockerCommandIt("refuses development updates when the checkout has uncommitted files", async () => {
+    const helperLog = join(tempDir, "dev-helper.log");
+    const devRoot = await createCleanDevGitRepoWithFakeHelper(helperLog);
+    const fakeDocker = await installFakeDocker();
+    await installFakeId(fakeDocker.binDir, 1234, 2345);
+    await writeFile(join(devRoot, "staged.txt"), "changed\n", "utf8");
+    await execUtf8("git", ["-C", devRoot, "add", "staged.txt"], cleanProcessEnv());
+    await writeFile(join(devRoot, "modified.txt"), "changed\n", "utf8");
+    await writeFile(join(devRoot, "untracked.txt"), "untracked\n", "utf8");
+
+    const result = await runDockerCommandAllowFailure(
+      ["--dev", "update"],
+      devHostEnv(fakeDocker, devRoot, join(tempDir, "home")),
+    );
+
+    expect(result.exitCode).not.toBe(0);
+    expect(result.stderr).toContain("refusing to update the Docker development stack because the checkout has uncommitted changes");
+    expect(result.stderr).toContain("staged.txt");
+    expect(result.stderr).toContain("modified.txt");
+    expect(result.stderr).toContain("?? untracked.txt");
+    expect(result.stderr).toContain("commit, stash, or remove these changes");
+    await expect(readFile(helperLog, "utf8")).rejects.toThrow();
+  });
+
+  dockerCommandIt("refuses dirty development updates before scheduling a detached helper", async () => {
+    const helperLog = join(tempDir, "dev-helper.log");
+    const devRoot = await createCleanDevGitRepoWithFakeHelper(helperLog);
+    const fakeDocker = await installFakeDocker();
+    await installFakeId(fakeDocker.binDir, 1234, 2345);
+    await writeFile(join(devRoot, "untracked.txt"), "untracked\n", "utf8");
+
+    const result = await runDockerCommandAllowFailure(["--dev", "update"], devRuntimeEnv(fakeDocker, devRoot));
+
+    expect(result.exitCode).not.toBe(0);
+    expect(result.stderr).toContain("checkout has uncommitted changes");
+    expect(result.stdout).not.toContain("Started detached PI WEB Docker helper");
+    await expect(readFile(fakeDocker.logPath, "utf8")).rejects.toThrow();
+    await expect(readFile(helperLog, "utf8")).rejects.toThrow();
+  });
+
+  dockerCommandIt("refuses development updates while a Git operation is in progress", async () => {
+    const helperLog = join(tempDir, "dev-helper.log");
+    const devRoot = await createCleanDevGitRepoWithFakeHelper(helperLog);
+    const fakeDocker = await installFakeDocker();
+    await installFakeId(fakeDocker.binDir, 1234, 2345);
+    const head = (await execUtf8("git", ["-C", devRoot, "rev-parse", "HEAD"], cleanProcessEnv())).stdout.trim();
+    await writeFile(join(devRoot, ".git", "MERGE_HEAD"), `${head}\n`, "utf8");
+
+    const result = await runDockerCommandAllowFailure(
+      ["--dev", "update"],
+      devHostEnv(fakeDocker, devRoot, join(tempDir, "home")),
+    );
+
+    expect(result.exitCode).not.toBe(0);
+    expect(result.stderr).toContain("while a Git merge is in progress");
+    expect(result.stderr).toContain("resolve or abort the Git merge");
+    await expect(readFile(helperLog, "utf8")).rejects.toThrow();
+  });
+
+  dockerCommandIt("allows clean development updates and dirty development starts", async () => {
+    const helperLog = join(tempDir, "dev-helper.log");
+    const devRoot = await createCleanDevGitRepoWithFakeHelper(helperLog);
+    const fakeDocker = await installFakeDocker();
+    await installFakeId(fakeDocker.binDir, 1234, 2345);
+    const env = devHostEnv(fakeDocker, devRoot, join(tempDir, "home"));
+
+    await runDockerCommand(["--dev", "update"], env);
+    await writeFile(join(devRoot, "in-progress-work.txt"), "dirty by design\n", "utf8");
+    await runDockerCommand(["--dev", "start"], env);
+
+    expect(await readFile(helperLog, "utf8")).toBe([
+      "allow=0 args=build --pull",
+      "allow=0 args=up -d --force-recreate --remove-orphans",
+      "allow=0 args=up -d --build",
+      "",
+    ].join("\n"));
+  });
+
   dockerCommandIt("starts development detached helpers as the generated dev user", async () => {
     const devRoot = await createDevGeneratedEnv({ uid: 1234, gid: 2345, dockerGid: 3456 });
     const fakeDocker = await installFakeDocker();
@@ -431,12 +521,31 @@ async function createDevRepoFixtureWithFakeHelper(logPath: string): Promise<stri
   await mkdir(dirname(helperPath), { recursive: true });
   await writeFile(helperPath, `#!/usr/bin/env sh
 set -eu
-printf 'allow=%s args=%s\n' "\${PI_WEB_DOCKER_ALLOW_ROOT:-}" "$*" >${shellSingleQuote(logPath)}
+printf 'allow=%s args=%s\n' "\${PI_WEB_DOCKER_ALLOW_ROOT:-}" "$*" >>${shellSingleQuote(logPath)}
 `, "utf8");
   await chmod(helperPath, 0o755);
   return devRoot;
 }
 
+async function createCleanDevGitRepoWithFakeHelper(logPath: string): Promise<string> {
+  const devRoot = await createDevRepoFixtureWithFakeHelper(logPath);
+  await Promise.all([
+    writeFile(join(devRoot, "staged.txt"), "clean\n", "utf8"),
+    writeFile(join(devRoot, "modified.txt"), "clean\n", "utf8"),
+  ]);
+  const env = cleanProcessEnv();
+  await execUtf8("git", ["init", "--quiet", devRoot], env);
+  await execUtf8("git", ["-C", devRoot, "add", "."], env);
+  await execUtf8("git", [
+    "-C", devRoot,
+    "-c", "user.name=PI WEB Test",
+    "-c", "[email protected]",
+    "-c", "core.hooksPath=/dev/null",
+    "commit", "--quiet", "--no-gpg-sign", "-m", "test fixture",
+  ], env);
+  return devRoot;
+}
+
 async function createDevGeneratedEnv(ids: { uid: number; gid: number; dockerGid: number }): Promise<string> {
   const devRoot = join(tempDir, "dev-runtime");
   await mkdir(join(devRoot, ".pi-web"), { recursive: true });

src/server/dockerDevDependencySync.test.ts

@@ -0,0 +1,102 @@
+import { execFile } from "node:child_process";
+import { mkdir, mkdtemp, readFile, readlink, rm, symlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const syncScript = join(repoRoot, "docker", "internal", "dev", "sync-node-modules");
+const dockerSyncIt = it.skipIf(process.platform === "win32");
+
+let tempDir = "";
+
+interface SyncFixture {
+  workspaceDir: string;
+  seedDir: string;
+  targetDir: string;
+}
+
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), "pi-web-docker-dependencies-test-"));
+});
+
+afterEach(async () => {
+  await rm(tempDir, { recursive: true, force: true });
+});
+
+describe("Docker development dependency synchronization", () => {
+  dockerSyncIt("replaces a stale dependency tree once per image generation", async () => {
+    const fixture = await createSyncFixture();
+
+    const first = await runSync(fixture);
+
+    expect(first.exitCode).toBe(0);
+    expect(first.stderr).toContain("Synchronizing PI WEB Docker dev dependencies");
+    expect(await readFile(join(fixture.targetDir, "fresh", "version.txt"), "utf8")).toBe("0.80.6\n");
+    expect(await readlink(join(fixture.targetDir, ".bin", "fresh"))).toBe("../fresh/version.txt");
+    expect(await readFile(join(fixture.targetDir, ".pi-web-dev-dependency-generation"), "utf8")).toBe("image-generation-2\n");
+    await expect(readFile(join(fixture.targetDir, "stale.txt"), "utf8")).rejects.toThrow();
+
+    await writeFile(join(fixture.targetDir, "keep-on-current-generation.txt"), "kept\n", "utf8");
+    const second = await runSync(fixture);
+
+    expect(second.exitCode).toBe(0);
+    expect(second.stderr).toContain("dependencies are current");
+    expect(await readFile(join(fixture.targetDir, "keep-on-current-generation.txt"), "utf8")).toBe("kept\n");
+  });
+
+  dockerSyncIt("fails without changing the volume when the image manifests are stale", async () => {
+    const fixture = await createSyncFixture();
+    await writeFile(join(fixture.workspaceDir, "package-lock.json"), '{"lockfileVersion":3,"changed":true}\n', "utf8");
+
+    const result = await runSync(fixture);
+
+    expect(result.exitCode).not.toBe(0);
+    expect(result.stderr).toContain("development image dependencies do not match the checkout");
+    expect(await readFile(join(fixture.targetDir, "stale.txt"), "utf8")).toBe("stale\n");
+  });
+});
+
+async function createSyncFixture(): Promise<SyncFixture> {
+  const workspaceDir = join(tempDir, "workspace");
+  const seedDir = join(tempDir, "seed");
+  const targetDir = join(workspaceDir, "node_modules");
+  const packageJson = '{"name":"dependency-sync-fixture","private":true}\n';
+  const packageLock = '{"name":"dependency-sync-fixture","lockfileVersion":3}\n';
+
+  await Promise.all([
+    mkdir(join(seedDir, "node_modules", "fresh"), { recursive: true }),
+    mkdir(join(seedDir, "node_modules", ".bin"), { recursive: true }),
+    mkdir(targetDir, { recursive: true }),
+  ]);
+  await Promise.all([
+    writeFile(join(workspaceDir, "package.json"), packageJson, "utf8"),
+    writeFile(join(workspaceDir, "package-lock.json"), packageLock, "utf8"),
+    writeFile(join(seedDir, "package.json"), packageJson, "utf8"),
+    writeFile(join(seedDir, "package-lock.json"), packageLock, "utf8"),
+    writeFile(join(seedDir, "generation"), "image-generation-2\n", "utf8"),
+    writeFile(join(seedDir, "node_modules", "fresh", "version.txt"), "0.80.6\n", "utf8"),
+    writeFile(join(targetDir, "stale.txt"), "stale\n", "utf8"),
+    writeFile(join(targetDir, ".pi-web-dev-dependency-generation"), "image-generation-1\n", "utf8"),
+  ]);
+  await symlink("../fresh/version.txt", join(seedDir, "node_modules", ".bin", "fresh"));
+
+  return { workspaceDir, seedDir, targetDir };
+}
+
+function runSync(fixture: SyncFixture): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+  return new Promise((resolvePromise) => {
+    execFile("bash", [syncScript], {
+      encoding: "utf8",
+      env: {
+        ...process.env,
+        PI_WEB_DEV_WORKSPACE_DIR: fixture.workspaceDir,
+        PI_WEB_DEV_DEPENDENCY_SEED_DIR: fixture.seedDir,
+      },
+    }, (error, stdout, stderr) => {
+      const exitCode = typeof error === "object" && error !== null && "code" in error && typeof error.code === "number" ? error.code : 0;
+      resolvePromise({ stdout, stderr, exitCode });
+    });
+  });
+}

src/server/piWebPluginService.test.ts

@@ -44,6 +44,44 @@ describe("PiWebPluginService", () => {
     expect(asset?.content.toString("utf8")).toContain("export default");
   });
 
+  it("preserves content types for extension-only asset names", async () => {
+    const pluginDir = join(tempDir, "plugins", "extension-only");
+    await writePlugin(pluginDir, {
+      packageJson: { piWeb: { plugins: [{ id: "extension-only", module: ".js" }] } },
+      files: {
+        ".js": "export default {};",
+        ".svg": '<svg xmlns="http://www.w3.org/2000/svg"></svg>',
+      },
+    });
+
+    const service = new PiWebPluginService({ roots: [{ path: join(tempDir, "plugins"), source: "test", scope: "local" }], packageProvider: false });
+
+    await expect(service.readAsset("extension-only", ".js")).resolves.toMatchObject({ contentType: "application/javascript; charset=utf-8" });
+    await expect(service.readAsset("extension-only", ".svg")).resolves.toMatchObject({ contentType: "image/svg+xml" });
+  });
+
+  it("serves nested SVG assets with a browser-compatible content type", async () => {
+    const pluginDir = join(tempDir, "plugins", "icons");
+    const svg = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"></svg>';
+    await writePlugin(pluginDir, {
+      packageJson: { piWeb: { plugins: [{ id: "icons", module: "pi-web-plugin.js" }] } },
+      files: {
+        "pi-web-plugin.js": "export default {};",
+        "assets/icon.svg": svg,
+        "assets/uppercase.SVG": svg,
+        "assets/data.bin": "unknown",
+      },
+    });
+
+    const service = new PiWebPluginService({ roots: [{ path: join(tempDir, "plugins"), source: "test", scope: "local" }], packageProvider: false });
+
+    const svgAsset = await service.readAsset("icons", "assets/icon.svg");
+    expect(svgAsset?.contentType).toBe("image/svg+xml");
+    expect(svgAsset?.content.toString("utf8")).toBe(svg);
+    await expect(service.readAsset("icons", "assets/uppercase.SVG")).resolves.toMatchObject({ contentType: "image/svg+xml" });
+    await expect(service.readAsset("icons", "assets/data.bin")).resolves.toMatchObject({ contentType: "application/octet-stream" });
+  });
+
   it("includes machine-specific preferences in plugin manifests", async () => {
     await writePlugin(join(tempDir, "plugins", "updates"), {
       packageJson: { piWeb: { plugins: [{ id: "updates", module: "pi-web-plugin.js", machineSpecific: true }] } },

src/server/piWebPluginService.ts

@@ -335,10 +335,12 @@ function isWithin(root: string, candidate: string): boolean {
 }
 
 function contentTypeFor(path: string): string {
-  if (path.endsWith(".js")) return "application/javascript; charset=utf-8";
-  if (path.endsWith(".json")) return "application/json; charset=utf-8";
-  if (path.endsWith(".css")) return "text/css; charset=utf-8";
-  if (path.endsWith(".html")) return "text/html; charset=utf-8";
+  const lowerPath = path.toLowerCase();
+  if (lowerPath.endsWith(".js")) return "application/javascript; charset=utf-8";
+  if (lowerPath.endsWith(".json")) return "application/json; charset=utf-8";
+  if (lowerPath.endsWith(".css")) return "text/css; charset=utf-8";
+  if (lowerPath.endsWith(".html")) return "text/html; charset=utf-8";
+  if (lowerPath.endsWith(".svg")) return "image/svg+xml";
   return "application/octet-stream";
 }
 

src/server/piWebReleaseLookupCache.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it, vi } from "vitest";
+import { createPiWebReleaseLookupCache } from "./piWebReleaseLookupCache.js";
+
+describe("createPiWebReleaseLookupCache", () => {
+  it("serves a fresh cached release lookup", async () => {
+    let now = 1_000;
+    const load = vi.fn(() => Promise.resolve("1.0.0"));
+    const cache = createPiWebReleaseLookupCache(load, { ttlMs: 100, now: () => now });
+
+    await expect(cache.get("0.9.0")).resolves.toMatchObject({ latestVersion: "1.0.0", checkedAtMs: 1_000 });
+    now = 1_050;
+    await expect(cache.get("0.9.1")).resolves.toMatchObject({ latestVersion: "1.0.0", checkedAtMs: 1_000 });
+
+    expect(load).toHaveBeenCalledOnce();
+    expect(load).toHaveBeenCalledWith("0.9.0");
+  });
+
+  it("bypasses a fresh lookup when forced", async () => {
+    let now = 1_000;
+    const load = vi.fn()
+      .mockResolvedValueOnce("1.0.0")
+      .mockResolvedValueOnce("1.1.0");
+    const cache = createPiWebReleaseLookupCache(load, { ttlMs: 100, now: () => now });
+
+    await cache.get("0.9.0");
+    now = 1_050;
+
+    await expect(cache.get("0.9.0", { force: true })).resolves.toMatchObject({ latestVersion: "1.1.0", checkedAtMs: 1_050 });
+    await expect(cache.get("0.9.0")).resolves.toMatchObject({ latestVersion: "1.1.0", checkedAtMs: 1_050 });
+    expect(load).toHaveBeenCalledTimes(2);
+  });
+
+  it.each(["forced-first", "regular-first"] as const)("does not let an older regular lookup replace a forced result when %s completes", async (completionOrder) => {
+    const regular = createDeferred<string>();
+    const forced = createDeferred<string>();
+    const load = vi.fn()
+      .mockImplementationOnce(() => regular.promise)
+      .mockImplementationOnce(() => forced.promise);
+    const cache = createPiWebReleaseLookupCache(load);
+
+    const regularLookup = cache.get("0.9.0");
+    const forcedLookup = cache.get("0.9.0", { force: true });
+    if (completionOrder === "forced-first") {
+      forced.resolve("2.0.0");
+      await expect(forcedLookup).resolves.toMatchObject({ latestVersion: "2.0.0" });
+      regular.resolve("1.0.0");
+      await expect(regularLookup).resolves.toMatchObject({ latestVersion: "1.0.0" });
+    } else {
+      regular.resolve("1.0.0");
+      await expect(regularLookup).resolves.toMatchObject({ latestVersion: "1.0.0" });
+      forced.resolve("2.0.0");
+      await expect(forcedLookup).resolves.toMatchObject({ latestVersion: "2.0.0" });
+    }
+
+    await expect(cache.get("0.9.0")).resolves.toMatchObject({ latestVersion: "2.0.0" });
+    expect(load).toHaveBeenCalledTimes(2);
+  });
+
+  it("makes regular callers join a pending forced lookup", async () => {
+    const forced = createDeferred<string>();
+    const load = vi.fn(() => forced.promise);
+    const cache = createPiWebReleaseLookupCache(load);
+
+    const forcedLookup = cache.get("0.9.0", { force: true });
+    const regularLookup = cache.get("0.9.0");
+
+    expect(regularLookup).toBe(forcedLookup);
+    forced.resolve("2.0.0");
+    await expect(regularLookup).resolves.toMatchObject({ latestVersion: "2.0.0" });
+    expect(load).toHaveBeenCalledOnce();
+  });
+});
+
+function createDeferred<T>(): { promise: Promise<T>; resolve: (value: T) => void } {
+  let resolve: (value: T) => void = () => undefined;
+  const promise = new Promise<T>((innerResolve) => {
+    resolve = innerResolve;
+  });
+  return { promise, resolve };
+}

src/server/piWebReleaseLookupCache.ts

@@ -0,0 +1,57 @@
+const DEFAULT_PI_WEB_RELEASE_LOOKUP_CACHE_TTL_MS = 6 * 60 * 60 * 1000;
+
+export interface PiWebReleaseLookup {
+  checkedAtMs: number;
+  latestVersion?: string;
+  error?: string;
+}
+
+export interface PiWebReleaseLookupCacheOptions {
+  ttlMs?: number;
+  now?: () => number;
+}
+
+export interface PiWebReleaseLookupOptions {
+  force?: boolean;
+}
+
+export interface PiWebReleaseLookupCache {
+  get(currentVersion: string, options?: PiWebReleaseLookupOptions): Promise<PiWebReleaseLookup>;
+}
+
+export function createPiWebReleaseLookupCache(
+  load: (currentVersion: string) => Promise<string>,
+  options: PiWebReleaseLookupCacheOptions = {},
+): PiWebReleaseLookupCache {
+  const ttlMs = options.ttlMs ?? DEFAULT_PI_WEB_RELEASE_LOOKUP_CACHE_TTL_MS;
+  const now = options.now ?? Date.now;
+  let cached: PiWebReleaseLookup | undefined;
+  let pending: { promise: Promise<PiWebReleaseLookup>; force: boolean; sequence: number } | undefined;
+  let loadSequence = 0;
+
+  return {
+    get(currentVersion: string, lookupOptions: PiWebReleaseLookupOptions = {}): Promise<PiWebReleaseLookup> {
+      const force = lookupOptions.force === true;
+      if (pending?.force === true) return pending.promise;
+
+      const checkedAtMs = now();
+      if (!force && cached !== undefined && checkedAtMs - cached.checkedAtMs < ttlMs) return Promise.resolve(cached);
+      if (!force && pending !== undefined) return pending.promise;
+
+      const sequence = ++loadSequence;
+      const promise = Promise.resolve()
+        .then(() => load(currentVersion))
+        .then((latestVersion): PiWebReleaseLookup => ({ checkedAtMs, latestVersion }))
+        .catch((error: unknown): PiWebReleaseLookup => ({ checkedAtMs, error: error instanceof Error ? error.message : String(error) }))
+        .then((lookup) => {
+          if (sequence === loadSequence) cached = lookup;
+          return lookup;
+        })
+        .finally(() => {
+          if (pending?.sequence === sequence) pending = undefined;
+        });
+      pending = { promise, force, sequence };
+      return promise;
+    },
+  };
+}

src/server/piWebStatus.test.ts

@@ -69,6 +69,33 @@ describe("PI WEB status", () => {
     expect(runtime.capabilities).toEqual(expect.arrayContaining([PI_WEB_CAPABILITIES.piPackagesManage, PI_WEB_CAPABILITIES.selectedMachineSettings]));
   });
 
+  it("bypasses cached npm release data for a forced check", async () => {
+    Reflect.deleteProperty(process.env, "PI_WEB_SKIP_VERSION_CHECK");
+    process.env["PI_WEB_DOCKER_RUNTIME"] = "1";
+    process.env["PI_WEB_DOCKER_MODE"] = "runtime";
+    const fetchMock = vi.spyOn(globalThis, "fetch")
+      .mockResolvedValueOnce(npmVersionResponse("1.202607.1"))
+      .mockResolvedValueOnce(npmVersionResponse("1.202607.2"));
+    const daemon = daemonWithComponent({
+      component: "sessiond",
+      label: "Session daemon",
+      runtimeVersion: "1.202607.0",
+      installedVersion: "1.202607.0",
+      stale: false,
+      available: true,
+      installation: { kind: "docker", dockerMode: "runtime" },
+    });
+
+    const first = await getPiWebStatus(daemon, { forceReleaseCheck: true });
+    const cached = await getPiWebStatus(daemon);
+    const forced = await getPiWebStatus(daemon, { forceReleaseCheck: true });
+
+    expect(first.release.latestVersion).toBe("1.202607.1");
+    expect(cached.release.latestVersion).toBe("1.202607.1");
+    expect(forced.release.latestVersion).toBe("1.202607.2");
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+
   it("reports stale session daemon versions as messages", async () => {
     process.env["PI_WEB_SKIP_VERSION_CHECK"] = "1";
     disableDockerRuntimeEnv();
@@ -82,7 +109,7 @@ describe("PI WEB status", () => {
       installation: { kind: "pi-package", source: "npm:@jmfederico/pi-web", scope: "user", path: "/tmp/pi-web" },
     });
 
-    const status = await getPiWebStatus(daemon);
+    const status = await getPiWebStatus(daemon, { forceReleaseCheck: true });
 
     expect(status.release.skipped).toBe(true);
     expect(status.components.sessiond.stale).toBe(true);
@@ -192,6 +219,10 @@ describe("PI WEB status", () => {
   });
 });
 
+function npmVersionResponse(version: string): Response {
+  return new Response(JSON.stringify({ version }), { status: 200, headers: { "content-type": "application/json" } });
+}
+
 function daemonWithComponent(component: PiWebComponentStatus): SessionDaemonClient {
   const daemon = new SessionDaemonClient();
   vi.spyOn(daemon, "request").mockResolvedValue({

src/server/piWebStatus.ts

@@ -11,11 +11,11 @@ import { effectivePiWebCapabilities, WEB_RUNTIME_CAPABILITIES } from "../shared/
 import { piWebDockerCommand } from "../docker/piWebDockerCommandPlan.js";
 import { parsePiWebComponentStatus, parsePiWebRuntimeComponent } from "../shared/piWebStatusParsing.js";
 import { SessionDaemonClient } from "../sessiond/sessionDaemonClient.js";
+import { createPiWebReleaseLookupCache, type PiWebReleaseLookup } from "./piWebReleaseLookupCache.js";
 
 const PI_WEB_PACKAGE_NAME = "@jmfederico/pi-web";
 const PI_WEB_NPM_SOURCE = `npm:${PI_WEB_PACKAGE_NAME}`;
 const DEFAULT_VERSION = "0.0.0-dev";
-const LATEST_RELEASE_CACHE_MS = 6 * 60 * 60 * 1000;
 const VERSION_CHECK_TIMEOUT_MS = 5000;
 
 type ServiceId = "sessiond" | "web" | "uiDev";
@@ -74,8 +74,11 @@ interface PiWebStatusDaemon {
   request(method: string, path: string, body?: unknown): Promise<{ statusCode: number; headers: Record<string, string>; body: string }>;
 }
 
-let latestReleaseCache: { checkedAtMs: number; latestVersion?: string; error?: string } | undefined;
+export interface PiWebStatusOptions {
+  forceReleaseCheck?: boolean;
+}
 
+const latestReleaseLookupCache = createPiWebReleaseLookupCache(fetchLatestNpmVersion);
 const runtimePackageInfo = readPackageInfoSync();
 
 export function getPiWebRuntimeComponent(component: PiWebServiceComponent, capabilities: readonly PiWebCapability[] = []): PiWebRuntimeComponent {
@@ -129,10 +132,10 @@ export async function getPiWebVersionStatus(daemon: PiWebStatusDaemon = new Sess
   };
 }
 
-export async function getPiWebStatus(daemon: PiWebStatusDaemon = new SessionDaemonClient()): Promise<PiWebStatusResponse> {
+export async function getPiWebStatus(daemon: PiWebStatusDaemon = new SessionDaemonClient(), options: PiWebStatusOptions = {}): Promise<PiWebStatusResponse> {
   const versionStatus = await getPiWebVersionStatus(daemon);
   const { web, sessiond } = versionStatus.components;
-  const release = await getLatestReleaseStatus(web.installedVersion ?? web.runtimeVersion ?? DEFAULT_VERSION);
+  const release = await getLatestReleaseStatus(web.installedVersion ?? web.runtimeVersion ?? DEFAULT_VERSION, options.forceReleaseCheck === true);
   const components = { web, sessiond };
   const commands = await commandsFor(components);
   const messages = buildMessages(components, release, commands);
@@ -375,25 +378,16 @@ function unavailableSessiond(error: string): PiWebComponentStatus {
   };
 }
 
-async function getLatestReleaseStatus(currentVersion: string): Promise<PiWebReleaseStatus> {
+async function getLatestReleaseStatus(currentVersion: string, force: boolean): Promise<PiWebReleaseStatus> {
   const checkedAtMs = Date.now();
   if (skipVersionCheck()) {
     return { packageName: PI_WEB_PACKAGE_NAME, updateAvailable: false, checkedAt: new Date(checkedAtMs).toISOString(), skipped: true };
   }
 
-  if (latestReleaseCache !== undefined && checkedAtMs - latestReleaseCache.checkedAtMs < LATEST_RELEASE_CACHE_MS) {
-    return releaseStatusFromCache(latestReleaseCache, currentVersion);
-  }
-
-  try {
-    latestReleaseCache = { checkedAtMs, latestVersion: await fetchLatestNpmVersion(currentVersion) };
-  } catch (error) {
-    latestReleaseCache = { checkedAtMs, error: error instanceof Error ? error.message : String(error) };
-  }
-  return releaseStatusFromCache(latestReleaseCache, currentVersion);
+  return releaseStatusFromCache(await latestReleaseLookupCache.get(currentVersion, { force }), currentVersion);
 }
 
-function releaseStatusFromCache(cache: { checkedAtMs: number; latestVersion?: string; error?: string }, currentVersion: string): PiWebReleaseStatus {
+function releaseStatusFromCache(cache: PiWebReleaseLookup, currentVersion: string): PiWebReleaseStatus {
   return {
     packageName: PI_WEB_PACKAGE_NAME,
     ...(cache.latestVersion === undefined ? {} : { latestVersion: cache.latestVersion }),

src/server/piWebStatusCache.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from "vitest";
 import type { PiWebStatusResponse } from "../shared/apiTypes.js";
-import { createPiWebStatusCache } from "./piWebStatusCache.js";
+import { createPiWebStatusCache, type PiWebStatusCacheLoadOptions } from "./piWebStatusCache.js";
 
 describe("createPiWebStatusCache", () => {
   it("serves cached status while it is fresh", async () => {
@@ -46,6 +46,45 @@ describe("createPiWebStatusCache", () => {
     expect(load).toHaveBeenCalledTimes(2);
   });
 
+  it.each(["forced-first", "regular-first"] as const)("does not let an older refresh replace a forced result when %s completes", async (completionOrder) => {
+    const regular = createDeferred<PiWebStatusResponse>();
+    const forced = createDeferred<PiWebStatusResponse>();
+    const load = vi.fn(({ force }: PiWebStatusCacheLoadOptions) => force ? forced.promise : regular.promise);
+    const cache = createPiWebStatusCache(load);
+
+    const regularRefresh = cache.refresh();
+    const forcedRefresh = cache.refresh({ force: true });
+    if (completionOrder === "forced-first") {
+      forced.resolve(status("forced"));
+      await expect(forcedRefresh).resolves.toMatchObject({ generatedAt: "forced" });
+      regular.resolve(status("regular"));
+      await expect(regularRefresh).resolves.toMatchObject({ generatedAt: "regular" });
+    } else {
+      regular.resolve(status("regular"));
+      await expect(regularRefresh).resolves.toMatchObject({ generatedAt: "regular" });
+      forced.resolve(status("forced"));
+      await expect(forcedRefresh).resolves.toMatchObject({ generatedAt: "forced" });
+    }
+
+    await expect(cache.get()).resolves.toMatchObject({ generatedAt: "forced" });
+    expect(load).toHaveBeenNthCalledWith(1, { force: false });
+    expect(load).toHaveBeenNthCalledWith(2, { force: true });
+  });
+
+  it("makes regular refreshes join a pending forced refresh", async () => {
+    const deferred = createDeferred<PiWebStatusResponse>();
+    const load = vi.fn(() => deferred.promise);
+    const cache = createPiWebStatusCache(load);
+
+    const forced = cache.refresh({ force: true });
+    const regular = cache.refresh();
+
+    expect(regular).toBe(forced);
+    deferred.resolve(status("forced"));
+    await forced;
+    expect(load).toHaveBeenCalledOnce();
+  });
+
   it("retains stale status and reports background refresh errors", async () => {
     let now = 1_000;
     const refreshError = new Error("refresh failed");

src/server/piWebStatusCache.ts

@@ -8,28 +8,42 @@ export interface PiWebStatusCacheOptions {
   onError?: (error: unknown) => void;
 }
 
-export interface PiWebStatusCache {
-  get(): Promise<PiWebStatusResponse>;
-  refresh(): Promise<PiWebStatusResponse>;
+export interface PiWebStatusCacheLoadOptions {
+  force: boolean;
 }
 
-export function createPiWebStatusCache(load: () => Promise<PiWebStatusResponse>, options: PiWebStatusCacheOptions = {}): PiWebStatusCache {
+export interface PiWebStatusCacheRefreshOptions {
+  force?: boolean;
+}
+
+export interface PiWebStatusCache {
+  get(): Promise<PiWebStatusResponse>;
+  refresh(options?: PiWebStatusCacheRefreshOptions): Promise<PiWebStatusResponse>;
+}
+
+export function createPiWebStatusCache(load: (options: PiWebStatusCacheLoadOptions) => Promise<PiWebStatusResponse>, options: PiWebStatusCacheOptions = {}): PiWebStatusCache {
   const ttlMs = options.ttlMs ?? DEFAULT_PI_WEB_STATUS_CACHE_TTL_MS;
   const now = options.now ?? Date.now;
   let cached: { status: PiWebStatusResponse; expiresAt: number } | undefined;
-  let pending: Promise<PiWebStatusResponse> | undefined;
+  let pending: { promise: Promise<PiWebStatusResponse>; force: boolean; sequence: number } | undefined;
+  let loadSequence = 0;
 
-  const refresh = (): Promise<PiWebStatusResponse> => {
-    pending ??= Promise.resolve()
-      .then(load)
+  const refresh = (refreshOptions: PiWebStatusCacheRefreshOptions = {}): Promise<PiWebStatusResponse> => {
+    const force = refreshOptions.force === true;
+    if (pending !== undefined && (!force || pending.force)) return pending.promise;
+
+    const sequence = ++loadSequence;
+    const promise = Promise.resolve()
+      .then(() => load({ force }))
       .then((status) => {
-        cached = { status, expiresAt: now() + ttlMs };
+        if (sequence === loadSequence) cached = { status, expiresAt: now() + ttlMs };
         return status;
       })
       .finally(() => {
-        pending = undefined;
+        if (pending?.sequence === sequence) pending = undefined;
       });
-    return pending;
+    pending = { promise, force, sequence };
+    return promise;
   };
 
   return {