@xyagent/cli 0.0.1

package/src/tunnel_service.mjs

@@ -0,0 +1,699 @@
+import { spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+
+export function startTunnelRuntime({
+  localPort,
+  relayUrl,
+  cliPath,
+  tunnelID,
+  tunnelToken,
+  slug,
+  protocol,
+  targetBaseUrl,
+  logPath,
+  agentlinkHome,
+}) {
+  const startArgs = [
+    cliPath,
+    "tunnel",
+    "agent",
+    String(localPort),
+    "--relay",
+    relayUrl,
+    "--tunnel-id",
+    tunnelID,
+    "--tunnel-token",
+    tunnelToken,
+    "--slug",
+    slug,
+    "--tunnel-protocol",
+    protocol || "http",
+    "--target",
+    targetBaseUrl,
+  ];
+  const installContext = {
+    localPort,
+    relayUrl,
+    cliPath,
+    logPath,
+    agentlinkHome,
+    nodePath: process.execPath,
+    startArgs,
+  };
+
+  try {
+    if (process.platform === "darwin") {
+      return installTunnelServiceMac(installContext);
+    }
+    if (process.platform === "linux") {
+      if (isSystemdUserAvailable()) {
+        return installTunnelServiceLinux(installContext);
+      }
+      if (isSystemdSystemAvailable()) {
+        return installTunnelSystemServiceLinux(installContext);
+      }
+      return startDetachedTunnelProcess({ ...installContext, warning: "systemd user session unavailable; using detached process" });
+    }
+    if (process.platform === "win32") {
+      return installTunnelServiceWindows(installContext);
+    }
+    return startDetachedTunnelProcess({
+      ...installContext,
+      warning: `service manager not configured for platform ${process.platform}; using detached process`,
+    });
+  } catch (error) {
+    return startDetachedTunnelProcess({
+      ...installContext,
+      warning: `service install failed; using detached process (${String(error instanceof Error ? error.message : error)})`,
+    });
+  }
+}
+
+export function stopTunnelRuntime({ localPort, runtime, pid }) {
+  if (runtime?.mode === "service") {
+    return uninstallTunnelService(localPort, runtime);
+  }
+  if (pid && isPidAlive(pid)) {
+    safeKill(pid);
+  }
+  return {
+    mode: "process",
+    manager: "detached",
+    running: false,
+    target: null,
+    ref: null,
+  };
+}
+
+export function getTunnelRuntimeStatus({ localPort, runtime, pid }) {
+  if (runtime?.mode === "service") {
+    return getTunnelServiceStatus(localPort, runtime);
+  }
+  return {
+    mode: "process",
+    manager: "detached",
+    running: isPidAlive(pid),
+    pid: pid ?? null,
+    installed: false,
+    target: null,
+    ref: null,
+  };
+}
+
+function startDetachedTunnelProcess({ startArgs, logPath, warning }) {
+  fs.mkdirSync(path.dirname(logPath), { recursive: true });
+  const logFd = fs.openSync(logPath, "a");
+  const child = spawn(process.execPath, startArgs, {
+    detached: true,
+    stdio: ["ignore", logFd, logFd],
+    windowsHide: process.platform === "win32",
+  });
+  child.unref();
+  fs.closeSync(logFd);
+  return {
+    mode: "process",
+    manager: "detached",
+    running: true,
+    pid: child.pid ?? null,
+    target: null,
+    ref: null,
+    warning: warning || null,
+  };
+}
+
+function installTunnelServiceMac(installContext) {
+  const names = tunnelServiceNames(installContext.localPort);
+  const plistPath = resolveMacLaunchAgentPath(installContext.localPort);
+  const launchScriptPath = writeTunnelLaunchScript(installContext);
+  fs.mkdirSync(path.dirname(plistPath), { recursive: true });
+  const plist = [
+    "<?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>",
+    `  <key>Label</key><string>${names.label}</string>`,
+    "  <key>ProgramArguments</key>",
+    "  <array>",
+    `    <string>${escapeXmlText(launchScriptPath)}</string>`,
+    "  </array>",
+    "  <key>RunAtLoad</key><true/>",
+    "  <key>KeepAlive</key><true/>",
+    `  <key>WorkingDirectory</key><string>${escapeXmlText(installContext.agentlinkHome)}</string>`,
+    `  <key>StandardOutPath</key><string>${escapeXmlText(installContext.logPath)}</string>`,
+    `  <key>StandardErrorPath</key><string>${escapeXmlText(installContext.logPath)}</string>`,
+    "</dict>",
+    "</plist>",
+    "",
+  ].join("\n");
+  fs.writeFileSync(plistPath, plist, "utf8");
+
+  const uid = typeof process.getuid === "function" ? process.getuid() : null;
+  const domains = uid == null ? [] : [`gui/${uid}`, `user/${uid}`];
+  let selectedDomain = null;
+  for (const domain of domains) {
+    runCommand("launchctl", ["bootout", domain, plistPath]);
+    const bootstrap = runCommand("launchctl", ["bootstrap", domain, plistPath]);
+    if (bootstrap.status === 0) {
+      selectedDomain = domain;
+      runCommand("launchctl", ["enable", `${domain}/${names.label}`]);
+      runCommand("launchctl", ["kickstart", "-k", `${domain}/${names.label}`]);
+      break;
+    }
+  }
+  if (!selectedDomain) {
+    const fallback = runCommand("launchctl", ["load", "-w", plistPath]);
+    if (fallback.status !== 0) {
+      safeUnlink(plistPath);
+      safeUnlink(launchScriptPath);
+      throw new Error((fallback.stderr || fallback.stdout || "launchctl bootstrap failed").trim());
+    }
+    selectedDomain = "launchd";
+  }
+  const status = readMacLaunchdServiceStatus(uid, plistPath, names);
+  if (!status.running) {
+    throw new Error(status.lastExitCode ? `launchd last exit code: ${status.lastExitCode}` : "launchd service failed to stay running");
+  }
+  return {
+    mode: "service",
+    manager: "launchd",
+    running: true,
+    pid: status.pid ?? null,
+    target: plistPath,
+    ref: `${selectedDomain}/${names.label}`,
+    launchScriptPath,
+  };
+}
+
+function installTunnelServiceLinux(installContext) {
+  const names = tunnelServiceNames(installContext.localPort);
+  const unitPath = resolveLinuxUserUnitPath(installContext.localPort);
+  const launchScriptPath = writeTunnelLaunchScript(installContext);
+  fs.mkdirSync(path.dirname(unitPath), { recursive: true });
+  const unit = [
+    "[Unit]",
+    `Description=Agentlink tunnel ${installContext.localPort}`,
+    "After=network-online.target",
+    "Wants=network-online.target",
+    "",
+    "[Service]",
+    "Type=simple",
+    `Environment=\"HOME=${escapeSystemdValue(os.homedir())}\"`,
+    `Environment=\"AGENTLINK_HOME=${escapeSystemdValue(installContext.agentlinkHome)}\"`,
+    `WorkingDirectory=${escapeSystemdPath(installContext.agentlinkHome)}`,
+    `ExecStart=${escapeSystemdPath(launchScriptPath)}`,
+    "Restart=always",
+    "RestartSec=5",
+    `StandardOutput=append:${escapeSystemdPath(installContext.logPath)}`,
+    `StandardError=append:${escapeSystemdPath(installContext.logPath)}`,
+    "",
+    "[Install]",
+    "WantedBy=default.target",
+    "",
+  ].join("\n");
+  fs.writeFileSync(unitPath, unit, "utf8");
+
+  for (const [command, args] of [
+    ["systemctl", ["--user", "daemon-reload"]],
+    ["systemctl", ["--user", "enable", "--now", names.unit]],
+  ]) {
+    const result = runCommand(command, args);
+    if (result.status !== 0) {
+      runCommand("systemctl", ["--user", "disable", "--now", names.unit]);
+      safeUnlink(unitPath);
+      safeUnlink(launchScriptPath);
+      throw new Error((result.stderr || result.stdout || `${command} failed`).trim());
+    }
+  }
+
+  return {
+    mode: "service",
+    manager: "systemd-user",
+    running: true,
+    pid: null,
+    target: unitPath,
+    ref: names.unit,
+    launchScriptPath,
+  };
+}
+
+function installTunnelSystemServiceLinux(installContext) {
+  const names = tunnelServiceNames(installContext.localPort);
+  const unitPath = resolveLinuxSystemUnitPath(installContext.localPort);
+  const launchScriptPath = writeTunnelLaunchScript(installContext);
+  fs.mkdirSync(path.dirname(unitPath), { recursive: true });
+  const unit = [
+    "[Unit]",
+    `Description=Agentlink tunnel ${installContext.localPort}`,
+    "After=network-online.target",
+    "Wants=network-online.target",
+    "",
+    "[Service]",
+    "Type=simple",
+    "User=root",
+    `Environment=\"HOME=${escapeSystemdValue(os.homedir())}\"`,
+    `Environment=\"AGENTLINK_HOME=${escapeSystemdValue(installContext.agentlinkHome)}\"`,
+    `WorkingDirectory=${escapeSystemdPath(installContext.agentlinkHome)}`,
+    `ExecStart=${escapeSystemdPath(launchScriptPath)}`,
+    "Restart=always",
+    "RestartSec=5",
+    `StandardOutput=append:${escapeSystemdPath(installContext.logPath)}`,
+    `StandardError=append:${escapeSystemdPath(installContext.logPath)}`,
+    "",
+    "[Install]",
+    "WantedBy=multi-user.target",
+    "",
+  ].join("\n");
+  fs.writeFileSync(unitPath, unit, "utf8");
+
+  for (const [command, args] of [
+    ["systemctl", ["daemon-reload"]],
+    ["systemctl", ["enable", "--now", names.systemUnit]],
+  ]) {
+    const result = runCommand(command, args);
+    if (result.status !== 0) {
+      runCommand("systemctl", ["disable", "--now", names.systemUnit]);
+      safeUnlink(unitPath);
+      safeUnlink(launchScriptPath);
+      throw new Error((result.stderr || result.stdout || `${command} failed`).trim());
+    }
+  }
+
+  return {
+    mode: "service",
+    manager: "systemd-system",
+    running: true,
+    pid: null,
+    target: unitPath,
+    ref: names.systemUnit,
+    launchScriptPath,
+  };
+}
+
+function installTunnelServiceWindows(installContext) {
+  const names = tunnelServiceNames(installContext.localPort);
+  const launchScriptPath = writeTunnelLaunchScript(installContext);
+  const commandPath =
+    (process.env.ComSpec ?? "").trim() ||
+    path.join(process.env.SystemRoot ?? "C:\\Windows", "System32", "cmd.exe");
+  const commandArgs = `/d /c ${quoteWindowsCommandArg(launchScriptPath)}`;
+  const script = [
+    `$Action = New-ScheduledTaskAction -Execute '${commandPath.replaceAll("'", "''")}' -Argument '${commandArgs.replaceAll("'", "''")}'`,
+    "$Trigger = New-ScheduledTaskTrigger -AtLogOn",
+    "$Settings = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -RestartCount 999 -RestartInterval (New-TimeSpan -Minutes 1)",
+    `Register-ScheduledTask -TaskName '${names.task}' -Action $Action -Trigger $Trigger -Settings $Settings -Description 'Agentlink tunnel ${installContext.localPort}' -Force | Out-Null`,
+    `Start-ScheduledTask -TaskName '${names.task}'`,
+  ].join("; ");
+  const encoded = Buffer.from(script, "utf16le").toString("base64");
+  const result = runCommand("powershell.exe", ["-NoProfile", "-EncodedCommand", encoded]);
+  if (result.status !== 0) {
+    safeUnlink(launchScriptPath);
+    throw new Error((result.stderr || result.stdout || "scheduled task install failed").trim());
+  }
+  return {
+    mode: "service",
+    manager: "task-scheduler",
+    running: true,
+    pid: null,
+    target: names.task,
+    ref: names.task,
+    launchScriptPath,
+  };
+}
+
+function uninstallTunnelService(localPort, runtime) {
+  const names = tunnelServiceNames(localPort);
+  const launchScriptPath = runtime?.launchScriptPath || resolveTunnelLaunchScriptPath(localPort);
+  if (process.platform === "darwin") {
+    const plistPath = resolveMacLaunchAgentPath(localPort);
+    const uid = typeof process.getuid === "function" ? process.getuid() : null;
+    if (uid != null) {
+      runCommand("launchctl", ["bootout", `gui/${uid}`, plistPath]);
+      runCommand("launchctl", ["bootout", `user/${uid}`, plistPath]);
+    }
+    runCommand("launchctl", ["remove", names.label]);
+    safeUnlink(plistPath);
+    safeUnlink(launchScriptPath);
+    return {
+      mode: "service",
+      manager: "launchd",
+      running: false,
+      target: plistPath,
+      ref: names.label,
+    };
+  }
+  if (process.platform === "linux") {
+    if (runtime?.manager === "systemd-system") {
+      const unitPath = resolveLinuxSystemUnitPath(localPort);
+      runCommand("systemctl", ["disable", "--now", names.systemUnit]);
+      safeUnlink(unitPath);
+      safeUnlink(launchScriptPath);
+      runCommand("systemctl", ["daemon-reload"]);
+      return {
+        mode: "service",
+        manager: "systemd-system",
+        running: false,
+        target: unitPath,
+        ref: names.systemUnit,
+      };
+    }
+    const unitPath = resolveLinuxUserUnitPath(localPort);
+    runCommand("systemctl", ["--user", "disable", "--now", names.unit]);
+    safeUnlink(unitPath);
+    safeUnlink(launchScriptPath);
+    runCommand("systemctl", ["--user", "daemon-reload"]);
+    return {
+      mode: "service",
+      manager: "systemd-user",
+      running: false,
+      target: unitPath,
+      ref: names.unit,
+    };
+  }
+  if (process.platform === "win32") {
+    runCommand("powershell.exe", ["-NoProfile", "-Command", `Unregister-ScheduledTask -TaskName '${names.task}' -Confirm:$false -ErrorAction SilentlyContinue`]);
+    safeUnlink(launchScriptPath);
+    return {
+      mode: "service",
+      manager: "task-scheduler",
+      running: false,
+      target: names.task,
+      ref: names.task,
+    };
+  }
+  safeUnlink(launchScriptPath);
+  return {
+    mode: "service",
+    manager: runtime?.manager ?? process.platform,
+    running: false,
+    target: runtime?.target ?? null,
+    ref: runtime?.ref ?? null,
+  };
+}
+
+function getTunnelServiceStatus(localPort, runtime) {
+  const names = tunnelServiceNames(localPort);
+  if (process.platform === "darwin") {
+    const uid = typeof process.getuid === "function" ? process.getuid() : null;
+    const plistPath = resolveMacLaunchAgentPath(localPort);
+    const status = readMacLaunchdServiceStatus(uid, plistPath, names);
+    return {
+      mode: "service",
+      manager: "launchd",
+      running: Boolean(status.running),
+      pid: status.pid ?? null,
+      installed: Boolean(status.installed),
+      target: plistPath,
+      ref: status.ref,
+    };
+  }
+  if (process.platform === "linux") {
+    if (runtime?.manager === "systemd-system") {
+      const unitPath = resolveLinuxSystemUnitPath(localPort);
+      const active = runCommand("systemctl", ["is-active", names.systemUnit]);
+      return {
+        mode: "service",
+        manager: "systemd-system",
+        running: active.status === 0 && String(active.stdout ?? "").trim() === "active",
+        pid: null,
+        installed: fs.existsSync(unitPath),
+        target: unitPath,
+        ref: names.systemUnit,
+      };
+    }
+    const unitPath = resolveLinuxUserUnitPath(localPort);
+    const active = runCommand("systemctl", ["--user", "is-active", names.unit]);
+    return {
+      mode: "service",
+      manager: "systemd-user",
+      running: active.status === 0 && String(active.stdout ?? "").trim() === "active",
+      pid: null,
+      installed: fs.existsSync(unitPath),
+      target: unitPath,
+      ref: names.unit,
+    };
+  }
+  if (process.platform === "win32") {
+    const ps = [
+      `try {`,
+      `  $task = Get-ScheduledTask -TaskName '${names.task.replaceAll("'", "''")}' -ErrorAction Stop`,
+      `  $info = Get-ScheduledTaskInfo -TaskName '${names.task.replaceAll("'", "''")}'`,
+      `  [Console]::Out.Write((@{ installed = $true; running = ($info.State -eq 'Running'); state = [string]$info.State } | ConvertTo-Json -Compress))`,
+      `} catch {`,
+      `  [Console]::Out.Write((@{ installed = $false; running = $false; state = 'missing' } | ConvertTo-Json -Compress))`,
+      `}`,
+    ].join(" ");
+    const result = runCommand("powershell.exe", ["-NoProfile", "-Command", ps]);
+    let parsed = { installed: false, running: false };
+    try {
+      parsed = JSON.parse(String(result.stdout ?? "").trim() || "{}");
+    } catch {
+      parsed = { installed: false, running: false };
+    }
+    return {
+      mode: "service",
+      manager: "task-scheduler",
+      running: Boolean(parsed.running),
+      pid: null,
+      installed: Boolean(parsed.installed),
+      target: names.task,
+      ref: names.task,
+    };
+  }
+  return {
+    mode: "service",
+    manager: runtime?.manager ?? process.platform,
+    running: false,
+    pid: null,
+    installed: false,
+    target: runtime?.target ?? null,
+    ref: runtime?.ref ?? null,
+  };
+}
+
+function writeTunnelLaunchScript({ localPort, startArgs, nodePath, agentlinkHome }) {
+  const scriptPath = resolveTunnelLaunchScriptPath(localPort);
+  fs.mkdirSync(path.dirname(scriptPath), { recursive: true });
+  const capturedHome = os.homedir();
+  const capturedAgentlinkHome = agentlinkHome;
+  if (process.platform === "win32") {
+    const appData =
+      (process.env.APPDATA ?? "").trim() ||
+      path.join(capturedHome, "AppData", "Roaming");
+    const script = [
+      "@echo off",
+      `set "HOME=${capturedHome}"`,
+      `set "USERPROFILE=${capturedHome}"`,
+      `set "APPDATA=${appData}"`,
+      `set "AGENTLINK_HOME=${capturedAgentlinkHome}"`,
+      `"${nodePath}" ${startArgs.map((arg) => quoteWindowsCommandArg(arg)).join(" ")}`,
+      "",
+    ].join("\r\n");
+    fs.writeFileSync(scriptPath, script, { encoding: "utf8" });
+    return scriptPath;
+  }
+  const script = [
+    "#!/bin/sh",
+    "set -eu",
+    `export HOME='${escapePosixShellSingleQuoted(capturedHome)}'`,
+    `export AGENTLINK_HOME='${escapePosixShellSingleQuoted(capturedAgentlinkHome)}'`,
+    `exec '${escapePosixShellSingleQuoted(nodePath)}' ${startArgs.map((arg) => `'${escapePosixShellSingleQuoted(arg)}'`).join(" ")}`,
+    "",
+  ].join("\n");
+  fs.writeFileSync(scriptPath, script, { encoding: "utf8", mode: 0o755 });
+  return scriptPath;
+}
+
+function tunnelServiceNames(localPort) {
+  const suffix = String(localPort);
+  return {
+    label: `ai.agentlink.tunnel.${suffix}`,
+    unit: `agentlink-tunnel-${suffix}.service`,
+    systemUnit: `agentlink-tunnel-${suffix}.service`,
+    task: `Agentlink Tunnel ${suffix}`,
+  };
+}
+
+function resolveTunnelLaunchScriptPath(localPort) {
+  const ext = process.platform === "win32" ? "cmd" : "sh";
+  return path.join(resolveAgentlinkHome(), "tunnels", `launch-${localPort}.${ext}`);
+}
+
+function resolveMacLaunchAgentPath(localPort) {
+  return path.join(os.homedir(), "Library", "LaunchAgents", `${tunnelServiceNames(localPort).label}.plist`);
+}
+
+function resolveLinuxUserUnitPath(localPort) {
+  return path.join(os.homedir(), ".config", "systemd", "user", tunnelServiceNames(localPort).unit);
+}
+
+function resolveLinuxSystemUnitPath(localPort) {
+  return path.join("/etc", "systemd", "system", tunnelServiceNames(localPort).systemUnit);
+}
+
+function readMacLaunchdServiceStatus(uid, plistPath, names) {
+  const refs = uid == null ? [] : [`gui/${uid}/${names.label}`, `user/${uid}/${names.label}`];
+  for (const ref of refs) {
+    const result = runCommand("launchctl", ["print", ref]);
+    if (result.status !== 0) {
+      continue;
+    }
+    const output = `${result.stdout ?? ""}\n${result.stderr ?? ""}`;
+    const stateMatch = output.match(/state = ([^\n]+)/u);
+    const activeCountMatch = output.match(/active count = (\d+)/u);
+    const pidMatch = output.match(/\bpid = (\d+)/u);
+    const exitCodeMatch = output.match(/last exit code = (\d+)/u);
+    const state = stateMatch?.[1]?.trim() ?? "";
+    const activeCount = Number.parseInt(activeCountMatch?.[1] ?? "0", 10) || 0;
+    const pid = Number.parseInt(pidMatch?.[1] ?? "0", 10) || 0;
+    const lastExitCode = Number.parseInt(exitCodeMatch?.[1] ?? "0", 10) || 0;
+    return {
+      installed: true,
+      running: state.toLowerCase() === "running" || activeCount > 0 || (pid > 0 && isPidAlive(pid)),
+      pid: pid || null,
+      ref,
+      lastExitCode,
+    };
+  }
+  return {
+    installed: fs.existsSync(plistPath),
+    running: false,
+    pid: null,
+    ref: names.label,
+    lastExitCode: 0,
+  };
+}
+
+function isSystemdUserAvailable() {
+  if (process.platform !== "linux") {
+    return false;
+  }
+  const uid = typeof process.getuid === "function" ? process.getuid() : null;
+  if (uid === 0) {
+    return runCommand("systemctl", ["--user", "is-system-running"]).status === 0;
+  }
+  return runCommand("systemctl", ["--user", "--version"]).status === 0;
+}
+
+function isSystemdSystemAvailable() {
+  if (process.platform !== "linux") {
+    return false;
+  }
+  return runCommand("systemctl", ["--version"]).status === 0;
+}
+
+function runCommand(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    encoding: "utf8",
+    windowsHide: true,
+    ...options,
+  });
+  return {
+    status: result.status ?? 1,
+    stdout: String(result.stdout ?? ""),
+    stderr: String(result.stderr ?? ""),
+  };
+}
+
+function escapeXmlText(value) {
+  return String(value)
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;");
+}
+
+function escapeSystemdValue(value) {
+  return String(value ?? "").replaceAll("\"", "");
+}
+
+function escapeSystemdPath(value) {
+  return String(value ?? "").replaceAll(" ", "\\x20");
+}
+
+function escapePosixShellSingleQuoted(value) {
+  return String(value ?? "").replaceAll("'", `'\"'\"'`);
+}
+
+function quoteWindowsCommandArg(value) {
+  const text = String(value ?? "");
+  if (!/[\s"]/u.test(text)) {
+    return text;
+  }
+  return `"${text.replaceAll("\\", "\\\\").replaceAll("\"", "\\\"")}"`;
+}
+
+function resolveAgentlinkHome() {
+  const fromEnv = String(process.env.AGENTLINK_HOME ?? "").trim();
+  if (fromEnv) return fromEnv;
+  const home = String(process.env.HOME ?? process.env.USERPROFILE ?? "").trim() || os.homedir();
+  if (!home || home === "/") {
+    if (process.platform === "win32") {
+      const appData = String(process.env.APPDATA ?? "").trim();
+      if (appData) return path.join(appData, ".agentlink");
+      const userProfile = String(process.env.USERPROFILE ?? "").trim();
+      if (userProfile) return path.join(userProfile, ".agentlink");
+    }
+    let username = "";
+    try {
+      username = os.userInfo().username || "";
+    } catch {
+      username = "";
+    }
+    if (username) {
+      const bases = username === "root" ? ["/root"] : ["/home", "/Users"];
+      for (const base of bases) {
+        const candidate = username === "root"
+          ? path.join(base, ".agentlink")
+          : path.join(base, username, ".agentlink");
+        if (fs.existsSync(candidate)) return candidate;
+      }
+      if (username === "root") return "/root/.agentlink";
+      if (process.platform === "darwin") return path.join("/Users", username, ".agentlink");
+      return path.join("/home", username, ".agentlink");
+    }
+  }
+  return path.join(home, ".agentlink");
+}
+
+function safeUnlink(filePath) {
+  try {
+    fs.unlinkSync(filePath);
+  } catch {
+    // noop
+  }
+}
+
+function isPidAlive(pid) {
+  const normalized = Number(pid);
+  if (!Number.isFinite(normalized) || normalized <= 0) {
+    return false;
+  }
+  if (process.platform === "win32") {
+    const result = runCommand("tasklist", ["/FI", `PID eq ${normalized}`, "/NH"]);
+    return result.status === 0 && result.stdout.includes(String(normalized));
+  }
+  try {
+    process.kill(normalized, 0);
+    return true;
+  } catch (error) {
+    return Boolean(error && typeof error === "object" && error.code === "EPERM");
+  }
+}
+
+function safeKill(pid) {
+  const normalized = Number(pid);
+  if (!Number.isFinite(normalized) || normalized <= 0) {
+    return;
+  }
+  if (process.platform === "win32") {
+    runCommand("taskkill", ["/PID", String(normalized), "/T", "/F"]);
+    return;
+  }
+  try {
+    process.kill(normalized, "SIGTERM");
+  } catch {
+    // noop
+  }
+}