@ours.network/cli 0.5.0 → 1.0.0

package/dist/{chunk-4IFFMMQO.js → chunk-QZIL3IT7.js}

@@ -2,7 +2,7 @@ import {
   attachClient,
   defaultConfigPath,
   resolveSelection
-} from "./chunk-6W3RHW3C.js";
+} from "./chunk-6K2JBKHI.js";
 
 // src/lifecycle.ts
 import { spawn as nodeSpawn } from "node:child_process";
@@ -54,7 +54,7 @@ async function inspectDaemon(config, deps = depsDefault) {
   try {
     client = await attachClient(config, { fetch: deps.fetch, leaseToken: "ours-cli-status" });
   } catch (error) {
-    if (error instanceof Error && error.name === "DaemonSelectionError" && /could not be reached/.test(error.message)) {
+    if (error instanceof Error && error.name === "DaemonUnavailableError") {
       return { state: "stopped", managed: false, info: null, ...base };
     }
     throw error;
@@ -87,7 +87,7 @@ function childEnvironment(selection) {
 async function serveDaemon(selection, managed = false) {
   if (selection.endpoint !== void 0) throw new Error("--endpoint selects a running daemon and cannot be used with daemon serve");
   Object.assign(process.env, childEnvironment(selection));
-  const { startDaemon } = await import("@ours.network/sdk/daemon");
+  const { startDaemon } = await import("./daemon-UUG6P6GK.js");
   const handle = await startDaemon();
   if (managed) {
     const response = await fetch(`http://127.0.0.1:${handle.port}/state-dir`);

package/dist/{chunk-YSHMCQ2B.js → chunk-SDNTPCKW.js}

@@ -42,14 +42,14 @@ var COMMAND_GROUPS = {
       "install-service": {
         kind: "daemon",
         handler: "install-service",
-        summary: "Install and enable the Linux user systemd service.",
-        effects: "Changes ~/.config/systemd/user/ours.service and runs systemctl --user. Requires --yes unless --dry-run is used; --force may replace only an existing unowned unit.",
+        summary: "Install and enable the per-user boot service (Linux systemd, macOS launchd).",
+        effects: "Changes ~/.config/systemd/user/ours.service and runs systemctl --user on Linux, or ~/Library/LaunchAgents and launchctl on macOS. Requires --yes unless --dry-run is used; --force may replace only an existing unowned unit.",
         example: "ours daemon install-service --dry-run --json"
       },
       "uninstall-service": {
         kind: "daemon",
         handler: "uninstall-service",
-        summary: "Disable and remove the Linux user systemd service owned by this CLI.",
+        summary: "Disable and remove the per-user boot service owned by this CLI.",
         effects: "Changes the user service manager. Requires --yes unless --dry-run is used and refuses to remove an unowned unit.",
         example: "ours daemon uninstall-service --dry-run --json"
       },

package/dist/chunk-TNNBVUKK.js

@@ -0,0 +1,241 @@
+import {
+  instanceNameFromStateDir,
+  labelForStateDir,
+  serviceDescription,
+  unitNameForStateDir
+} from "./chunk-UZQWSOUB.js";
+
+// src/service.ts
+import { execFile as nodeExecFile } from "node:child_process";
+import { promisify } from "node:util";
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+var execFile = promisify(nodeExecFile);
+var MARKER = "# Managed by @ours.network/cli";
+var PLIST_MARKER = "<!-- Managed by @ours.network/cli -->";
+var SERVICE_NAME = "ours.service";
+var defaultDeps = {
+  platform: process.platform,
+  run: async (command, args) => {
+    await execFile(command, args, { windowsHide: true });
+  },
+  uid: process.getuid?.()
+};
+function systemdEscapeArgument(value) {
+  if (/[\n\r]/.test(value)) throw new Error("service arguments must not contain newlines");
+  return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"').replaceAll("%", "%%")}"`;
+}
+function systemdUnescapeArgument(value) {
+  const trimmed = value.trim();
+  if (!trimmed.startsWith('"') || !trimmed.endsWith('"') || trimmed.length < 2) return void 0;
+  return trimmed.slice(1, -1).replaceAll("%%", "%").replaceAll('\\"', '"').replaceAll("\\\\", "\\");
+}
+function bakedStateDir(unit) {
+  for (const line of unit.split("\n")) {
+    if (!line.startsWith("Environment=OURS_STATE_DIR=")) continue;
+    return systemdUnescapeArgument(line.slice("Environment=OURS_STATE_DIR=".length));
+  }
+  return void 0;
+}
+function describeConflict(existing, serviceFile, stateDir, verb = "overwrite") {
+  if (!existing.managed) {
+    return {
+      kind: "unmanaged",
+      serviceFile,
+      message: verb === "remove" ? `${serviceFile} is not managed by @ours.network/cli; refusing to remove it` : `${serviceFile} is not managed by @ours.network/cli; refusing to overwrite it without --force`
+    };
+  }
+  const owner = existing.owner;
+  if (owner !== void 0 && owner !== stateDir) {
+    return {
+      kind: "other-state-dir",
+      serviceFile,
+      owner,
+      message: `${serviceFile} is the boot service for the daemon at ${owner}, not ${stateDir}; refusing to ${verb} it without --force`
+    };
+  }
+  return void 0;
+}
+function resolveStateDir(context) {
+  return resolve(context.stateDir ?? join(context.homeDir ?? homedir(), ".ours"));
+}
+function readSystemdUnit(previous) {
+  return { managed: previous.startsWith(MARKER), owner: bakedStateDir(previous) };
+}
+function createLinuxUserSystemdAdapter(deps = defaultDeps) {
+  if (deps.platform !== "linux") throw new Error(`service management is not supported on ${deps.platform}; use an external launcher for \`ours daemon serve\``);
+  return {
+    name: "systemd-user",
+    async install(context) {
+      const home = context.homeDir ?? homedir();
+      const stateDir = resolveStateDir(context);
+      const unitName = unitNameForStateDir(stateDir);
+      const serviceFile = join(home, ".config", "systemd", "user", unitName);
+      const unitConfig = context.configPath ? resolve(context.configPath) : void 0;
+      const args = [process.execPath, resolve(context.cliPath), "daemon", "serve"];
+      if (unitConfig) args.push("--config", unitConfig);
+      const environment = `Environment=OURS_STATE_DIR=${systemdEscapeArgument(stateDir)}
+`;
+      const unit = `${MARKER}
+[Unit]
+Description=${serviceDescription(instanceNameFromStateDir(stateDir).name)}
+After=network-online.target
+
+[Service]
+Type=simple
+ExecStart=${args.map(systemdEscapeArgument).join(" ")}
+${environment}Restart=on-failure
+RestartSec=2
+
+[Install]
+WantedBy=default.target
+`;
+      if (existsSync(serviceFile)) {
+        const previous = readFileSync(serviceFile, "utf8");
+        const conflict = describeConflict(readSystemdUnit(previous), serviceFile, stateDir);
+        if (conflict && !context.force) {
+          if (!context.dryRun) throw new Error(conflict.message);
+          return { adapter: this.name, action: "install", serviceFile, unitName, stateDir, configPath: unitConfig, commands: [], changed: false, dryRun: true, conflict };
+        }
+        if (previous === unit) return { adapter: this.name, action: "install", serviceFile, unitName, stateDir, configPath: unitConfig, commands: [], changed: false, dryRun: context.dryRun === true };
+      }
+      const commands = [["systemctl", "--user", "daemon-reload"], ["systemctl", "--user", "enable", "--now", unitName]];
+      if (!context.dryRun) {
+        mkdirSync(dirname(serviceFile), { recursive: true });
+        writeFileSync(serviceFile, unit, { mode: 420 });
+        for (const [command, ...args2] of commands) await deps.run(command, args2);
+      }
+      return { adapter: this.name, action: "install", serviceFile, unitName, stateDir, configPath: unitConfig, commands, changed: true, dryRun: context.dryRun === true };
+    },
+    async uninstall(context) {
+      const home = context.homeDir ?? homedir();
+      const stateDir = resolveStateDir(context);
+      const unitName = unitNameForStateDir(stateDir);
+      const serviceFile = join(home, ".config", "systemd", "user", unitName);
+      if (!existsSync(serviceFile)) return { adapter: this.name, action: "uninstall", serviceFile, unitName, stateDir, commands: [], changed: false, dryRun: context.dryRun === true };
+      const previous = readFileSync(serviceFile, "utf8");
+      const existing = readSystemdUnit(previous);
+      const conflict = describeConflict(existing, serviceFile, stateDir, "remove");
+      if (conflict && !(context.force && existing.managed)) {
+        if (!context.dryRun) throw new Error(conflict.message);
+        return { adapter: this.name, action: "uninstall", serviceFile, unitName, stateDir, commands: [], changed: false, dryRun: true, conflict };
+      }
+      const commands = [["systemctl", "--user", "disable", "--now", unitName], ["systemctl", "--user", "daemon-reload"]];
+      if (!context.dryRun) {
+        await deps.run(commands[0][0], commands[0].slice(1));
+        unlinkSync(serviceFile);
+        await deps.run(commands[1][0], commands[1].slice(1));
+      }
+      return { adapter: this.name, action: "uninstall", serviceFile, unitName, stateDir, commands, changed: true, dryRun: context.dryRun === true };
+    }
+  };
+}
+function xmlText(value) {
+  return String(value).replace(/[&<>"']/g, (character) => ({
+    "&": "&amp;",
+    "<": "&lt;",
+    ">": "&gt;",
+    '"': "&quot;",
+    "'": "&apos;"
+  })[character]);
+}
+function xmlUntext(value) {
+  return value.replaceAll("&lt;", "<").replaceAll("&gt;", ">").replaceAll("&quot;", '"').replaceAll("&apos;", "'").replaceAll("&amp;", "&");
+}
+function bakedStateDirFromPlist(plist) {
+  const match = /<key>OURS_STATE_DIR<\/key><string>([^<]*)<\/string>/.exec(plist);
+  return match ? xmlUntext(match[1]) : void 0;
+}
+function readLaunchdPlist(previous) {
+  const managed = previous.split("\n")[1] === PLIST_MARKER;
+  return { managed, owner: bakedStateDirFromPlist(previous) };
+}
+function createMacosUserLaunchdAdapter(deps = defaultDeps) {
+  if (deps.platform !== "darwin") throw new Error(`service management is not supported on ${deps.platform}; use an external launcher for \`ours daemon serve\``);
+  const domain = `gui/${deps.uid ?? process.getuid?.() ?? 0}`;
+  const plan = (context) => {
+    const home = context.homeDir ?? homedir();
+    const stateDir = resolveStateDir(context);
+    const unitName = labelForStateDir(stateDir);
+    return { stateDir, unitName, serviceFile: join(home, "Library", "LaunchAgents", `${unitName}.plist`) };
+  };
+  return {
+    name: "launchd-user",
+    async install(context) {
+      const { stateDir, unitName, serviceFile } = plan(context);
+      const unitConfig = context.configPath ? resolve(context.configPath) : void 0;
+      const args = [process.execPath, resolve(context.cliPath), "daemon", "serve"];
+      if (unitConfig) args.push("--config", unitConfig);
+      const unit = `<?xml version="1.0" encoding="UTF-8"?>
+${PLIST_MARKER}
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${xmlText(unitName)}</string>
+  <key>ProgramArguments</key>
+  <array>
+${args.map((argument) => `    <string>${xmlText(argument)}</string>`).join("\n")}
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>OURS_STATE_DIR</key><string>${xmlText(stateDir)}</string>
+  </dict>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+</dict>
+</plist>
+`;
+      if (existsSync(serviceFile)) {
+        const previous = readFileSync(serviceFile, "utf8");
+        const conflict = describeConflict(readLaunchdPlist(previous), serviceFile, stateDir);
+        if (conflict && !context.force) {
+          if (!context.dryRun) throw new Error(conflict.message);
+          return { adapter: this.name, action: "install", serviceFile, unitName, stateDir, configPath: unitConfig, commands: [], changed: false, dryRun: true, conflict };
+        }
+        if (previous === unit) return { adapter: this.name, action: "install", serviceFile, unitName, stateDir, configPath: unitConfig, commands: [], changed: false, dryRun: context.dryRun === true };
+      }
+      const commands = [["launchctl", "bootout", domain, serviceFile], ["launchctl", "bootstrap", domain, serviceFile]];
+      if (!context.dryRun) {
+        mkdirSync(dirname(serviceFile), { recursive: true });
+        writeFileSync(serviceFile, unit, { mode: 420 });
+        await deps.run(commands[0][0], commands[0].slice(1)).catch(() => {
+        });
+        await deps.run(commands[1][0], commands[1].slice(1));
+      }
+      return { adapter: this.name, action: "install", serviceFile, unitName, stateDir, configPath: unitConfig, commands, changed: true, dryRun: context.dryRun === true };
+    },
+    async uninstall(context) {
+      const { stateDir, unitName, serviceFile } = plan(context);
+      if (!existsSync(serviceFile)) return { adapter: this.name, action: "uninstall", serviceFile, unitName, stateDir, commands: [], changed: false, dryRun: context.dryRun === true };
+      const previous = readFileSync(serviceFile, "utf8");
+      const existing = readLaunchdPlist(previous);
+      const conflict = describeConflict(existing, serviceFile, stateDir, "remove");
+      if (conflict && !(context.force && existing.managed)) {
+        if (!context.dryRun) throw new Error(conflict.message);
+        return { adapter: this.name, action: "uninstall", serviceFile, unitName, stateDir, commands: [], changed: false, dryRun: true, conflict };
+      }
+      const commands = [["launchctl", "bootout", domain, serviceFile]];
+      if (!context.dryRun) {
+        await deps.run(commands[0][0], commands[0].slice(1)).catch(() => {
+        });
+        unlinkSync(serviceFile);
+      }
+      return { adapter: this.name, action: "uninstall", serviceFile, unitName, stateDir, commands, changed: true, dryRun: context.dryRun === true };
+    }
+  };
+}
+function createServiceAdapter(deps = defaultDeps) {
+  if (deps.platform === "linux") return createLinuxUserSystemdAdapter(deps);
+  if (deps.platform === "darwin") return createMacosUserLaunchdAdapter(deps);
+  throw new Error(`service management is not supported on ${deps.platform}; use an external launcher for \`ours daemon serve\``);
+}
+
+export {
+  SERVICE_NAME,
+  bakedStateDir,
+  createLinuxUserSystemdAdapter,
+  bakedStateDirFromPlist,
+  createMacosUserLaunchdAdapter,
+  createServiceAdapter
+};

package/dist/{chunk-3RLAHOPS.js → chunk-UZQWSOUB.js}

@@ -1,6 +1,7 @@
 // src/service-instance.ts
 import { basename, resolve } from "node:path";
 var DEFAULT_SYSTEMD_UNIT = "ours.service";
+var DEFAULT_LAUNCHD_LABEL = "solutions.adaptframework.ours";
 var INSTANCE_RE = /^[A-Za-z0-9](?:[A-Za-z0-9_-]{0,30}[A-Za-z0-9])?$/;
 function normalizeInstanceName(raw) {
   const s = typeof raw === "string" ? raw.trim() : "";
@@ -22,6 +23,11 @@ function systemdUnitName(instance = "") {
   if (!ok || !name) return DEFAULT_SYSTEMD_UNIT;
   return `ours-${name}.service`;
 }
+function launchdLabel(instance = "") {
+  const { ok, name } = normalizeInstanceName(instance);
+  if (!ok || !name) return DEFAULT_LAUNCHD_LABEL;
+  return `${DEFAULT_LAUNCHD_LABEL}.${name}`;
+}
 function serviceDescription(instance = "") {
   const { ok, name } = normalizeInstanceName(instance);
   return ok && name ? `ours daemon (instance "${name}")` : "ours shared daemon";
@@ -46,12 +52,20 @@ function unitNameForStateDir(stateDir) {
   if (!ok) throw new Error(reason);
   return systemdUnitName(name);
 }
+function labelForStateDir(stateDir) {
+  const { ok, name, reason } = instanceNameFromStateDir(stateDir);
+  if (!ok) throw new Error(reason);
+  return launchdLabel(name);
+}
 
 export {
   DEFAULT_SYSTEMD_UNIT,
+  DEFAULT_LAUNCHD_LABEL,
   normalizeInstanceName,
   systemdUnitName,
+  launchdLabel,
   serviceDescription,
   instanceNameFromStateDir,
-  unitNameForStateDir
+  unitNameForStateDir,
+  labelForStateDir
 };

package/dist/{chunk-VGWQD7CJ.js → chunk-ZFE47KH3.js}

@@ -13,7 +13,7 @@ import {
   IDENTITY_PREBIND_EXCEPTIONS,
   commandSpec,
   isCommandGroup
-} from "./chunk-YSHMCQ2B.js";
+} from "./chunk-SDNTPCKW.js";
 
 // src/help.ts
 var pad = (value, width = 32) => value.length >= width ? `${value} ` : value.padEnd(width);
@@ -126,7 +126,6 @@ function nativeConfigOptions(action) {
     ["--identity NAME", "Compatibility-only/ignored by config commands."],
     ["--broker-url URL", show ? "Compatibility-only/ignored by config show." : "Set the broker WebSocket URL."],
     ["--gc-interval-ms N", show ? "Compatibility-only/ignored by config show." : "Set a positive garbage-collection interval in milliseconds."],
-    ["--auto-start true|false", show ? "Compatibility-only/ignored by config show." : "Set automatic daemon startup (1/0 are also accepted)."],
     ["--api-visibility MODE", show ? "Compatibility-only/ignored by config show." : "Set owner, shared, or open API visibility."],
     ["--dry-run", show ? "Compatibility-only/ignored by config show." : "Return the merged redacted result without writing the file."],
     ["--json", "Write one JSON value to stdout."],

package/dist/commands.d.ts

@@ -64,14 +64,14 @@ export declare const COMMAND_GROUPS: {
             readonly 'install-service': {
                 readonly kind: "daemon";
                 readonly handler: "install-service";
-                readonly summary: "Install and enable the Linux user systemd service.";
-                readonly effects: "Changes ~/.config/systemd/user/ours.service and runs systemctl --user. Requires --yes unless --dry-run is used; --force may replace only an existing unowned unit.";
+                readonly summary: "Install and enable the per-user boot service (Linux systemd, macOS launchd).";
+                readonly effects: "Changes ~/.config/systemd/user/ours.service and runs systemctl --user on Linux, or ~/Library/LaunchAgents and launchctl on macOS. Requires --yes unless --dry-run is used; --force may replace only an existing unowned unit.";
                 readonly example: "ours daemon install-service --dry-run --json";
             };
             readonly 'uninstall-service': {
                 readonly kind: "daemon";
                 readonly handler: "uninstall-service";
-                readonly summary: "Disable and remove the Linux user systemd service owned by this CLI.";
+                readonly summary: "Disable and remove the per-user boot service owned by this CLI.";
                 readonly effects: "Changes the user service manager. Requires --yes unless --dry-run is used and refuses to remove an unowned unit.";
                 readonly example: "ours daemon uninstall-service --dry-run --json";
             };

package/dist/commands.js

@@ -4,7 +4,7 @@ import {
   IDENTITY_PREBIND_EXCEPTIONS,
   commandSpec,
   isCommandGroup
-} from "./chunk-YSHMCQ2B.js";
+} from "./chunk-SDNTPCKW.js";
 export {
   COMMAND_GROUPS,
   DESTRUCTIVE_OPERATIONS,

package/dist/config-command.js

@@ -1,8 +1,8 @@
 import {
   setupConfig,
   showConfig
-} from "./chunk-G2GHHOYX.js";
-import "./chunk-6W3RHW3C.js";
+} from "./chunk-DRQEV4SN.js";
+import "./chunk-6K2JBKHI.js";
 export {
   setupConfig,
   showConfig

package/dist/connection.js

@@ -3,7 +3,7 @@ import {
   defaultConfigPath,
   redactedSelection,
   resolveSelection
-} from "./chunk-6W3RHW3C.js";
+} from "./chunk-6K2JBKHI.js";
 export {
   attachClient,
   defaultConfigPath,

package/dist/daemon-UUG6P6GK.js

@@ -0,0 +1,250 @@
+import {
+  assertConfigNotDrifted,
+  loadConfig
+} from "./chunk-FXKFSNKS.js";
+
+// ../../src/internal/daemon.ts
+import * as fs2 from "node:fs";
+
+// ../../src/internal/state-root-lock.ts
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as net from "node:net";
+import { dirname, join, resolve } from "node:path";
+var SUPPORTED_PLATFORMS = /* @__PURE__ */ new Set(["linux", "darwin"]);
+var MAX_SOCKET_PATH_BYTES = 103;
+var MAX_ACQUIRE_ATTEMPTS = 8;
+var StateRootLockedError = class extends Error {
+  constructor(stateDir, ownerPid, owner) {
+    super(
+      `ours daemon state directory ${JSON.stringify(stateDir)} is already owned by ` + (ownerPid === null ? "another live process" : `pid ${ownerPid}`) + ". Stop that daemon through the ours CLI before starting another one for the same state directory."
+    );
+    this.stateDir = stateDir;
+    this.ownerPid = ownerPid;
+    this.owner = owner;
+    this.name = "StateRootLockedError";
+  }
+  code = "STATE_ROOT_LOCKED";
+};
+function fsCode(error) {
+  return error && typeof error === "object" && "code" in error ? String(error.code) : void 0;
+}
+function canonicalStateDir(input) {
+  let cursor = resolve(input);
+  const missing = [];
+  while (true) {
+    try {
+      const canonicalPrefix = fs.realpathSync.native(cursor);
+      return resolve(canonicalPrefix, ...missing.reverse());
+    } catch (error) {
+      if (fsCode(error) !== "ENOENT") throw error;
+      const parent = dirname(cursor);
+      if (parent === cursor) throw error;
+      missing.push(cursor.slice(parent.length + (parent.endsWith("/") ? 0 : 1)));
+      cursor = parent;
+    }
+  }
+}
+function ensurePrivateDirectory(path, uid) {
+  try {
+    fs.mkdirSync(path, { mode: 448 });
+  } catch (error) {
+    if (fsCode(error) !== "EEXIST") throw error;
+  }
+  const stat = fs.lstatSync(path);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) {
+    throw new Error(`daemon lock path ${JSON.stringify(path)} must be a real directory, not a symlink or file`);
+  }
+  if (stat.uid !== uid) {
+    throw new Error(`daemon lock path ${JSON.stringify(path)} is owned by uid ${stat.uid}, expected uid ${uid}`);
+  }
+  fs.chmodSync(path, 448);
+}
+function stateRootLockPath(stateDir) {
+  if (!SUPPORTED_PLATFORMS.has(process.platform)) {
+    throw new Error(
+      `the ours daemon state-root lock supports Linux and macOS only; platform ${JSON.stringify(process.platform)} has no verified Unix-domain-socket lock contract, so startup is refused`
+    );
+  }
+  const getuid = process.getuid;
+  if (typeof getuid !== "function") {
+    throw new Error("the ours daemon state-root lock requires a Unix uid; startup is refused");
+  }
+  const uid = getuid.call(process);
+  const base = `/tmp/ours-${uid}`;
+  const directory = join(base, "locks");
+  ensurePrivateDirectory(base, uid);
+  ensurePrivateDirectory(directory, uid);
+  const key = createHash("sha256").update(stateDir).digest("hex");
+  const socketPath = join(directory, `${key}.sock`);
+  if (Buffer.byteLength(socketPath) > MAX_SOCKET_PATH_BYTES) {
+    throw new Error(
+      `daemon lock socket path is ${Buffer.byteLength(socketPath)} bytes, exceeding the portable ${MAX_SOCKET_PATH_BYTES}-byte Linux/macOS contract: ${JSON.stringify(socketPath)}`
+    );
+  }
+  return { directory, socketPath };
+}
+function probeSocket(socketPath) {
+  return new Promise((resolveProbe) => {
+    const socket = net.createConnection(socketPath);
+    let data = "";
+    let settled = false;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      resolveProbe(result);
+    };
+    socket.setEncoding("utf8");
+    socket.setTimeout(1e3);
+    socket.on("data", (chunk) => {
+      data += chunk;
+    });
+    socket.once("end", () => {
+      try {
+        const parsed = JSON.parse(data);
+        const owner = Number.isInteger(parsed.pid) && typeof parsed.stateDir === "string" && typeof parsed.startedAt === "string" ? parsed : null;
+        finish({ kind: "live", owner });
+      } catch {
+        finish({ kind: "live", owner: null });
+      }
+    });
+    socket.once("timeout", () => finish({ kind: "ambiguous", error: new Error("timed out probing the live lock socket") }));
+    socket.once("error", (error) => {
+      const code = fsCode(error);
+      if (code === "ECONNREFUSED" || code === "ENOENT") finish({ kind: "stale" });
+      else finish({ kind: "ambiguous", error });
+    });
+  });
+}
+function listen(server, socketPath) {
+  return new Promise((resolveListen, reject) => {
+    const onError = (error) => reject(error);
+    server.once("error", onError);
+    server.listen(socketPath, () => {
+      server.off("error", onError);
+      resolveListen();
+    });
+  });
+}
+async function acquireStateRootLock(inputStateDir) {
+  const stateDir = canonicalStateDir(inputStateDir);
+  const { socketPath } = stateRootLockPath(stateDir);
+  const owner = { pid: process.pid, stateDir, startedAt: (/* @__PURE__ */ new Date()).toISOString() };
+  for (let attempt = 1; attempt <= MAX_ACQUIRE_ATTEMPTS; attempt++) {
+    const server = net.createServer((socket) => socket.end(`${JSON.stringify(owner)}
+`));
+    try {
+      await listen(server, socketPath);
+      server.unref();
+      let closed = false;
+      return {
+        stateDir,
+        socketPath,
+        owner,
+        close: async () => {
+          if (closed) return;
+          closed = true;
+          await new Promise((resolveClose) => server.close(() => resolveClose()));
+          try {
+            fs.unlinkSync(socketPath);
+          } catch (error) {
+            if (fsCode(error) !== "ENOENT") throw error;
+          }
+        }
+      };
+    } catch (error) {
+      try {
+        server.close();
+      } catch {
+      }
+      if (fsCode(error) !== "EADDRINUSE") throw error;
+      const probe = await probeSocket(socketPath);
+      if (probe.kind === "live") {
+        throw new StateRootLockedError(stateDir, probe.owner?.pid ?? null, probe.owner);
+      }
+      if (probe.kind === "ambiguous") {
+        throw new Error(
+          `could not prove whether daemon lock ${JSON.stringify(socketPath)} is live or stale; refusing to remove it: ${probe.error.message}`
+        );
+      }
+      try {
+        fs.unlinkSync(socketPath);
+      } catch (unlinkError) {
+        if (fsCode(unlinkError) !== "ENOENT") throw unlinkError;
+      }
+    }
+  }
+  throw new Error(`could not acquire daemon state-root lock for ${JSON.stringify(stateDir)} after ${MAX_ACQUIRE_ATTEMPTS} races`);
+}
+
+// ../../src/internal/daemon.ts
+var ENTRY_CONFIG = loadConfig();
+var heldLock = null;
+async function ensureLock() {
+  assertConfigNotDrifted();
+  if (heldLock) return { lock: heldLock, acquired: false };
+  const lock = await acquireStateRootLock(ENTRY_CONFIG.stateDir);
+  fs2.mkdirSync(lock.stateDir, { recursive: true, mode: 448 });
+  const actual = fs2.realpathSync.native(lock.stateDir);
+  if (actual !== lock.stateDir) {
+    await lock.close();
+    throw new Error(
+      `state directory canonical path changed during lock acquisition: locked ${JSON.stringify(lock.stateDir)}, created ${JSON.stringify(actual)}`
+    );
+  }
+  heldLock = lock;
+  return { lock, acquired: true };
+}
+async function releaseHeld(lock) {
+  if (heldLock !== lock) return;
+  heldLock = null;
+  await lock.close();
+}
+async function bootKernel() {
+  const { lock, acquired } = await ensureLock();
+  try {
+    const { bootWrapper } = await import("./boot-35BOHNSZ.js");
+    await bootWrapper();
+  } catch (error) {
+    if (acquired) await releaseHeld(lock);
+    throw error;
+  }
+}
+async function startDaemon(opts = {}) {
+  const { lock, acquired } = await ensureLock();
+  try {
+    const runtime = await import("./server-TDJBEWTU.js");
+    const { onRuntimeLoaded, ...daemonOptions } = opts;
+    onRuntimeLoaded?.();
+    const handle = await runtime.startDaemon({
+      ...daemonOptions,
+      // The server owns its existing signal behavior. This callback releases
+      // the lock after teardown and before its signal path exits the process.
+      onShutdown: async () => releaseHeld(lock)
+    });
+    let closed = false;
+    return {
+      port: handle.port,
+      close: async () => {
+        if (closed) return;
+        closed = true;
+        try {
+          await handle.close();
+        } finally {
+          await releaseHeld(lock);
+        }
+      }
+    };
+  } catch (error) {
+    if (acquired) await releaseHeld(lock);
+    throw error;
+  }
+}
+export {
+  StateRootLockedError,
+  bootKernel,
+  canonicalStateDir,
+  startDaemon,
+  stateRootLockPath
+};

package/dist/help.js

@@ -3,10 +3,10 @@ import {
   helpRequestPath,
   renderHelp,
   renderTopHelp
-} from "./chunk-VGWQD7CJ.js";
+} from "./chunk-ZFE47KH3.js";
 import "./chunk-QRNZFPNJ.js";
 import "./chunk-6NFATG6P.js";
-import "./chunk-YSHMCQ2B.js";
+import "./chunk-SDNTPCKW.js";
 export {
   helpHint,
   helpRequestPath,

package/dist/lifecycle.js

@@ -7,8 +7,8 @@ import {
   startDaemonManaged,
   stopDaemonManaged,
   writeManagedRecord
-} from "./chunk-4IFFMMQO.js";
-import "./chunk-6W3RHW3C.js";
+} from "./chunk-QZIL3IT7.js";
+import "./chunk-6K2JBKHI.js";
 export {
   DAEMON_LOG_FILE,
   MANAGED_PID_FILE,