@auroraflow/code 0.0.10 → 0.0.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@auroraflow/code",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "type": "module",
   "description": "Aurora launcher and sidecar for official Codex and Claude Code clients.",
   "repository": {

package/packages/cli/src/index.js

@@ -1,5 +1,6 @@
 import { ensureLayout, readAccount, readState, writeAccount, writeState } from "../../state/src/index.js";
 import { officialClientStatuses, runClient, updateOfficialClients } from "../../clients/src/index.js";
+import { ensureSidecarRunning, installSidecarService, sidecarServiceStatus, uninstallSidecarService } from "../../service/src/index.js";
 import { chooseClient, promptFields } from "../../../lib/prompt.js";
 
 export async function runAuroraCLI(argv = process.argv.slice(2)) {
@@ -34,11 +35,41 @@ export async function runAuroraCLI(argv = process.argv.slice(2)) {
       await updateOfficialClients();
       console.log(JSON.stringify({ officialClients: officialClientStatuses() }, null, 2));
       return;
+    case "sidecar":
+      await sidecarCommand(rest);
+      return;
     default:
       usage(1);
   }
 }
 
+async function sidecarCommand(args) {
+  const action = args[0] ?? "status";
+  switch (action) {
+    case "install":
+      await installSidecarService();
+      await ensureSidecarRunning();
+      console.log(JSON.stringify(await sidecarServiceStatus(), null, 2));
+      return;
+    case "uninstall":
+      await uninstallSidecarService();
+      console.log("Aurora sidecar service uninstalled.");
+      return;
+    case "restart":
+      await uninstallSidecarService();
+      await installSidecarService();
+      await ensureSidecarRunning();
+      console.log(JSON.stringify(await sidecarServiceStatus(), null, 2));
+      return;
+    case "status":
+      console.log(JSON.stringify(await sidecarServiceStatus(), null, 2));
+      return;
+    default:
+      console.error("Usage: aurora sidecar [install|uninstall|restart|status]");
+      process.exit(1);
+  }
+}
+
 export async function runAuroraClaude(argv = process.argv.slice(2)) {
   await ensureLayout();
   await runClient("claude", argv);
@@ -135,6 +166,7 @@ function usage(exitCode) {
   aurora codex [args...]
   aurora install-clients
   aurora update-clients
-  aurora status`);
+  aurora status
+  aurora sidecar [install|uninstall|restart|status]`);
   process.exit(exitCode);
 }

package/packages/clients/src/index.js

@@ -1,17 +1,13 @@
 import { spawn, spawnSync } from "node:child_process";
-import { randomBytes } from "node:crypto";
-import { closeSync, existsSync, openSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { mkdir, writeFile } from "node:fs/promises";
 import { delimiter, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { AURORA_SIDECAR_PORT } from "../../protocol/src/index.js";
-import { AURORA_HOME, CLAUDE_HOME, CODEX_HOME, readSidecarInfo, readState, writeSidecarInfo } from "../../state/src/index.js";
+import { CLAUDE_HOME, CODEX_HOME, readState } from "../../state/src/index.js";
+import { ensureSidecarRunning } from "../../service/src/index.js";
 
 const here = dirname(fileURLToPath(import.meta.url));
 const packageRoot = resolve(here, "..", "..", "..");
-const rootSidecarBin = join(packageRoot, "bin", "aurora-sidecar.js");
-const sidecarLogPath = join(AURORA_HOME, "log", "sidecar.log");
-let sidecarSupervisor = null;
 
 const OFFICIAL_CLIENTS = {
   claude: {
@@ -27,7 +23,7 @@ const OFFICIAL_CLIENTS = {
 };
 
 export async function createClientLaunchSpec(client, args = []) {
-  const sidecar = await ensureSidecar();
+  const sidecar = await ensureSidecarRunning();
   const state = await readState();
   const model = selectedModelAlias(state);
   const key = selectedKey(state);
@@ -144,53 +140,6 @@ function readOfficialClientVersion(bin) {
   }
 }
 
-async function ensureSidecar() {
-  try {
-    const info = await readSidecarInfo();
-    if (info?.port && info?.token && await pingSidecar(info)) return normalizedSidecarInfo(info);
-  } catch {
-    // Start below.
-  }
-  const token = `aurora-local-${randomBytes(24).toString("hex")}`;
-  const info = { port: AURORA_SIDECAR_PORT, token, baseURL: `http://127.0.0.1:${AURORA_SIDECAR_PORT}` };
-  await startManagedSidecar(info);
-  await waitForSidecar(info);
-  await writeSidecarInfo(info);
-  return info;
-}
-
-async function startManagedSidecar(info) {
-  if (sidecarSupervisor) return;
-  await mkdir(dirname(sidecarLogPath), { recursive: true });
-  const launch = () => {
-    const logFd = openSync(sidecarLogPath, "a");
-    const child = spawn(process.execPath, [
-      process.env.AURORA_SIDECAR_BIN || rootSidecarBin,
-      "--token",
-      info.token,
-      "--port",
-      String(info.port)
-    ], {
-      detached: true,
-      stdio: ["ignore", logFd, logFd],
-      env: process.env
-    });
-    closeSync(logFd);
-    sidecarSupervisor.child = child;
-    child.on("error", error => {
-      console.error(`Aurora sidecar failed to start: ${error.message}`);
-    });
-    child.on("exit", () => {
-      sidecarSupervisor.child = null;
-      setTimeout(launch, 1000);
-    });
-  };
-  sidecarSupervisor = {
-    child: null
-  };
-  launch();
-}
-
 async function writeCodexRuntimeFiles({ sidecar, model }) {
   await mkdir(CODEX_HOME, { recursive: true });
   const modelCatalogPath = join(CODEX_HOME, "model_catalog.json");
@@ -245,36 +194,6 @@ async function writeCodexModelCatalog(sidecar, modelCatalogPath) {
   await writeFile(join(CODEX_HOME, "models_cache.json"), `${JSON.stringify(cache, null, 2)}\n`, { mode: 0o600 });
 }
 
-async function waitForSidecar(info) {
-  const deadline = Date.now() + 2500;
-  while (Date.now() < deadline) {
-    if (await pingSidecar(info)) return;
-    await new Promise(resolve => setTimeout(resolve, 100));
-  }
-  throw new Error("Aurora sidecar did not become ready on 127.0.0.1:17878");
-}
-
-async function pingSidecar(info) {
-  try {
-    const normalized = normalizedSidecarInfo(info);
-    const response = await fetch(`${normalized.baseURL}/aurora/status`, {
-      headers: { authorization: `Bearer ${normalized.token}` },
-      signal: AbortSignal.timeout(500)
-    });
-    return response.ok;
-  } catch {
-    return false;
-  }
-}
-
-function normalizedSidecarInfo(info) {
-  return {
-    port: Number(info.port),
-    token: String(info.token),
-    baseURL: info.baseURL || `http://127.0.0.1:${Number(info.port)}`
-  };
-}
-
 function selectedModelAlias(state) {
   const model = state.selectedModel?.alias;
   if (!model) throw new Error("Aurora runtime model is not selected. Select a model in Aurora Desktop > 本机调用.");

package/packages/service/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@aurora/service",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js"
+  }
+}

package/packages/service/src/detached.js

@@ -0,0 +1,64 @@
+// Fallback backend: a detached, unref'd process.
+//
+// Used when no OS service manager is available (unknown platform, or Linux
+// without systemd --user). It cannot survive a reboot, but combined with the
+// sidecar's crash-only design (no process.exit on per-request errors) it stays
+// up for the whole login session, which is the best a no-service host allows.
+import { spawn } from "node:child_process";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { openSync, closeSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { AURORA_HOME } from "../../state/src/index.js";
+
+function pidPath() {
+  return join(AURORA_HOME, "sidecar.pid");
+}
+
+function alive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function install(spec) {
+  if (await isInstalled()) return;
+  await mkdir(dirname(spec.logPath), { recursive: true });
+  const logFd = openSync(spec.logPath, "a");
+  const child = spawn(spec.nodePath, [spec.scriptPath], {
+    detached: true,
+    stdio: ["ignore", logFd, logFd],
+    env: { ...process.env, AURORA_HOME: spec.auroraHome }
+  });
+  closeSync(logFd);
+  child.unref();
+  await writeFile(pidPath(), String(child.pid), { mode: 0o600 });
+}
+
+export async function uninstall() {
+  const pid = await readPid();
+  if (pid && alive(pid)) {
+    try {
+      process.kill(pid);
+    } catch {
+      // Already gone.
+    }
+  }
+  await rm(pidPath(), { force: true }).catch(() => {});
+}
+
+export async function isInstalled() {
+  const pid = await readPid();
+  return Boolean(pid && alive(pid));
+}
+
+async function readPid() {
+  try {
+    const pid = Number(await readFile(pidPath(), "utf8"));
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}

package/packages/service/src/index.js

@@ -0,0 +1,146 @@
+// Cross-platform supervision for the Aurora sidecar.
+//
+// "Always connectable" is delegated to the OS service manager rather than a
+// parent process: a launcher that spawns the sidecar dies with its terminal,
+// orphaning the daemon with no supervisor. Each platform uses its best
+// no-admin (npm-friendly) mechanism:
+//
+//   - macOS   → launchd LaunchAgent (~/Library/LaunchAgents)
+//   - Linux   → systemd --user unit (~/.config/systemd/user)
+//   - Windows → Scheduled Task at logon (schtasks, no UAC)
+//   - other / unavailable → detached supervised process (best effort)
+//
+// All backends run the SAME `bin/aurora-sidecar.js` with no secret in the
+// service definition — the sidecar reads its stable token from sidecar.json.
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { AURORA_LOCALHOST } from "../../protocol/src/index.js";
+import { AURORA_HOME, readSidecarInfo } from "../../state/src/index.js";
+import { ensureSidecarIdentity } from "../../sidecar/src/index.js";
+import * as launchd from "./launchd.js";
+import * as systemd from "./systemd.js";
+import * as schtasks from "./schtasks.js";
+import * as detached from "./detached.js";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const packageRoot = resolve(here, "..", "..", "..");
+
+export const SERVICE_LABEL = "com.auroraflow.sidecar";
+
+// serviceSpec is the platform-agnostic description every backend renders into
+// its own format. Absolute paths are resolved fresh each call so a node
+// upgrade (nvm/brew) self-heals on the next launch.
+export function serviceSpec() {
+  return {
+    label: SERVICE_LABEL,
+    nodePath: process.execPath,
+    scriptPath: join(packageRoot, "bin", "aurora-sidecar.js"),
+    logPath: join(AURORA_HOME, "log", "sidecar.log"),
+    auroraHome: AURORA_HOME
+  };
+}
+
+function backend() {
+  switch (process.platform) {
+    case "darwin":
+      return launchd;
+    case "linux":
+      return systemd;
+    case "win32":
+      return schtasks;
+    default:
+      return detached;
+  }
+}
+
+// ensureSidecarRunning is the single entry the launcher calls. It seeds the
+// stable identity, installs/repairs the OS service, then waits until the
+// sidecar answers. If the platform's service manager is unavailable, it falls
+// back to a detached process so the client still gets a working sidecar.
+export async function ensureSidecarRunning() {
+  const identity = await ensureSidecarIdentity();
+  if (await pingSidecar(identity)) return identity;
+  const spec = serviceSpec();
+  try {
+    await backend().install(spec);
+  } catch (error) {
+    if (backend() !== detached) {
+      console.error(`[aurora] ${process.platform} service manager unavailable (${error?.message || error}); using detached fallback.`);
+      await detached.install(spec);
+    } else {
+      throw error;
+    }
+  }
+  await waitForSidecar(identity);
+  return identity;
+}
+
+export async function installSidecarService() {
+  await ensureSidecarIdentity();
+  await backend().install(serviceSpec());
+}
+
+export async function uninstallSidecarService() {
+  await backend().uninstall(serviceSpec());
+  // Detached instances are not managed by the OS; stop any stray one too.
+  await detached.uninstall(serviceSpec()).catch(() => {});
+}
+
+export async function sidecarServiceStatus() {
+  const spec = serviceSpec();
+  let identity = null;
+  try {
+    identity = await readSidecarInfo();
+  } catch {
+    // Not seeded yet.
+  }
+  const installed = await backend().isInstalled(spec).catch(() => false);
+  const running = identity ? await pingSidecar(identity) : false;
+  return {
+    platform: process.platform,
+    backend: backendName(),
+    installed,
+    running,
+    port: identity?.port ?? null,
+    scriptPath: spec.scriptPath,
+    nodePath: spec.nodePath,
+    logPath: spec.logPath
+  };
+}
+
+function backendName() {
+  switch (process.platform) {
+    case "darwin":
+      return "launchd";
+    case "linux":
+      return "systemd";
+    case "win32":
+      return "schtasks";
+    default:
+      return "detached";
+  }
+}
+
+export async function pingSidecar(identity) {
+  try {
+    const port = Number(identity?.port);
+    const token = String(identity?.token ?? "");
+    if (!port || !token) return false;
+    const response = await fetch(`http://${AURORA_LOCALHOST}:${port}/aurora/status`, {
+      headers: { authorization: `Bearer ${token}` },
+      signal: AbortSignal.timeout(500)
+    });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+
+export async function waitForSidecar(identity, timeoutMs = 5000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await pingSidecar(identity)) return;
+    await new Promise(resolve => setTimeout(resolve, 100));
+  }
+  throw new Error(`Aurora sidecar did not become ready on ${AURORA_LOCALHOST}:${identity?.port}`);
+}

package/packages/service/src/launchd.js

@@ -0,0 +1,99 @@
+// macOS backend: launchd LaunchAgent.
+//
+// KeepAlive is the unconditional boolean: launchd's { Crashed: true } variant
+// does not reliably restart after a SIGKILL, which defeats the whole purpose.
+// Unconditional restart guarantees "always connectable"; the only cost is that
+// the rare single-instance "yield" exit (when another sidecar already owns the
+// port) gets relaunched every ~10s (launchd throttle) until the peer goes away,
+// which self-corrects. RunAtLoad + the LaunchAgents domain give login
+// auto-start without admin rights.
+import { execFile } from "node:child_process";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { promisify } from "node:util";
+
+const run = promisify(execFile);
+
+function plistPath(spec) {
+  return join(homedir(), "Library", "LaunchAgents", `${spec.label}.plist`);
+}
+
+function domainTarget() {
+  return `gui/${process.getuid()}`;
+}
+
+function serviceTarget(spec) {
+  return `${domainTarget()}/${spec.label}`;
+}
+
+function renderPlist(spec) {
+  const escape = value => String(value).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+  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>
+  <key>Label</key><string>${escape(spec.label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${escape(spec.nodePath)}</string>
+    <string>${escape(spec.scriptPath)}</string>
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>AURORA_HOME</key><string>${escape(spec.auroraHome)}</string>
+  </dict>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>ThrottleInterval</key><integer>1</integer>
+  <key>ProcessType</key><string>Background</string>
+  <key>StandardOutPath</key><string>${escape(spec.logPath)}</string>
+  <key>StandardErrorPath</key><string>${escape(spec.logPath)}</string>
+</dict>
+</plist>
+`;
+}
+
+export async function install(spec) {
+  const path = plistPath(spec);
+  const desired = renderPlist(spec);
+  await mkdir(dirname(path), { recursive: true });
+  await mkdir(dirname(spec.logPath), { recursive: true });
+  const current = existsSync(path) ? await readFile(path, "utf8") : null;
+  const loaded = await isLoaded(spec);
+  if (current === desired && loaded) {
+    // Already correct — make sure it is actually started, no-op if running.
+    await run("launchctl", ["kickstart", serviceTarget(spec)]).catch(() => {});
+    return;
+  }
+  await writeFile(path, desired, { mode: 0o644 });
+  // Reload cleanly: bootout the old definition (ignore if absent), bootstrap
+  // the new one, then kickstart to start immediately.
+  await run("launchctl", ["bootout", serviceTarget(spec)]).catch(() => {});
+  await run("launchctl", ["bootstrap", domainTarget(), path]);
+  await run("launchctl", ["enable", serviceTarget(spec)]).catch(() => {});
+  await run("launchctl", ["kickstart", "-k", serviceTarget(spec)]).catch(() => {});
+}
+
+export async function uninstall(spec) {
+  await run("launchctl", ["bootout", serviceTarget(spec)]).catch(() => {});
+  const path = plistPath(spec);
+  if (existsSync(path)) {
+    const { rm } = await import("node:fs/promises");
+    await rm(path, { force: true });
+  }
+}
+
+export async function isInstalled(spec) {
+  return existsSync(plistPath(spec));
+}
+
+async function isLoaded(spec) {
+  try {
+    await run("launchctl", ["print", serviceTarget(spec)]);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/packages/service/src/schtasks.js

@@ -0,0 +1,92 @@
+// Windows backend: Scheduled Task at logon (no admin / no UAC).
+//
+// A real Windows Service requires elevation, which an npm global install does
+// not have. A per-user Scheduled Task triggered at logon, with RestartOnFailure
+// and no execution time limit, is the standard no-admin always-on mechanism.
+//
+// Note: node.exe started by Task Scheduler may flash a console window. That is
+// cosmetic and does not affect connectivity; a windowless vbs shim can be added
+// later if needed.
+import { execFile } from "node:child_process";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { AURORA_HOME } from "../../state/src/index.js";
+
+const run = promisify(execFile);
+const TASK_NAME = "AuroraSidecar";
+
+function taskXmlPath() {
+  return join(AURORA_HOME, "aurora-sidecar-task.xml");
+}
+
+function renderTaskXml(spec) {
+  const escape = value => String(value)
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+  return `<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <Description>Aurora local sidecar</Description>
+  </RegistrationInfo>
+  <Triggers>
+    <LogonTrigger>
+      <Enabled>true</Enabled>
+    </LogonTrigger>
+  </Triggers>
+  <Principals>
+    <Principal id="Author">
+      <LogonType>InteractiveToken</LogonType>
+      <RunLevel>LeastPrivilege</RunLevel>
+    </Principal>
+  </Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <AllowHardTerminate>true</AllowHardTerminate>
+    <StartWhenAvailable>true</StartWhenAvailable>
+    <RunOnlyIfNetworkAvailable>false</RunOnlyIfNetworkAvailable>
+    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
+    <Enabled>true</Enabled>
+    <Hidden>false</Hidden>
+    <RestartOnFailure>
+      <Interval>PT1M</Interval>
+      <Count>999</Count>
+    </RestartOnFailure>
+  </Settings>
+  <Actions Context="Author">
+    <Exec>
+      <Command>"${escape(spec.nodePath)}"</Command>
+      <Arguments>"${escape(spec.scriptPath)}"</Arguments>
+    </Exec>
+  </Actions>
+</Task>
+`;
+}
+
+export async function install(spec) {
+  const path = taskXmlPath();
+  await mkdir(AURORA_HOME, { recursive: true });
+  // Task Scheduler XML must be UTF-16 with a BOM.
+  await writeFile(path, "" + renderTaskXml(spec), { encoding: "utf16le" });
+  // /f overwrites any existing definition, self-healing a drifted node path.
+  await run("schtasks", ["/create", "/tn", TASK_NAME, "/xml", path, "/f"]);
+  await run("schtasks", ["/run", "/tn", TASK_NAME]).catch(() => {});
+}
+
+export async function uninstall() {
+  await run("schtasks", ["/end", "/tn", TASK_NAME]).catch(() => {});
+  await run("schtasks", ["/delete", "/tn", TASK_NAME, "/f"]).catch(() => {});
+}
+
+export async function isInstalled() {
+  try {
+    await run("schtasks", ["/query", "/tn", TASK_NAME]);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/packages/service/src/systemd.js

@@ -0,0 +1,72 @@
+// Linux backend: systemd --user unit.
+//
+// Restart=on-failure (not always) so the single-instance clean "yield" exit
+// does not loop, while crashes restart after 1s. WantedBy=default.target gives
+// login auto-start without root. If systemctl --user is unavailable (no
+// systemd, containers, some WSL setups) install() throws and the dispatcher
+// falls back to a detached process.
+import { execFile } from "node:child_process";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { promisify } from "node:util";
+
+const run = promisify(execFile);
+
+function unitName(spec) {
+  // systemd unit names cannot contain dots beyond the type suffix.
+  return `${spec.label.replace(/\./g, "-")}.service`;
+}
+
+function unitPath(spec) {
+  return join(homedir(), ".config", "systemd", "user", unitName(spec));
+}
+
+function renderUnit(spec) {
+  return `[Unit]
+Description=Aurora local sidecar
+After=network.target
+
+[Service]
+Type=simple
+ExecStart=${spec.nodePath} ${spec.scriptPath}
+Environment=AURORA_HOME=${spec.auroraHome}
+Restart=on-failure
+RestartSec=1
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+export async function install(spec) {
+  // Probe availability first so an unsupported host triggers the fallback.
+  await run("systemctl", ["--user", "--version"]);
+  const path = unitPath(spec);
+  const desired = renderUnit(spec);
+  await mkdir(dirname(path), { recursive: true });
+  await mkdir(dirname(spec.logPath), { recursive: true });
+  const current = existsSync(path) ? await readFile(path, "utf8") : null;
+  if (current !== desired) {
+    await writeFile(path, desired, { mode: 0o644 });
+  }
+  await run("systemctl", ["--user", "daemon-reload"]);
+  await run("systemctl", ["--user", "enable", "--now", unitName(spec)]);
+  // Apply any unit change and ensure it is up.
+  await run("systemctl", ["--user", "restart", unitName(spec)]).catch(() => {});
+}
+
+export async function uninstall(spec) {
+  await run("systemctl", ["--user", "disable", "--now", unitName(spec)]).catch(() => {});
+  const path = unitPath(spec);
+  if (existsSync(path)) {
+    const { rm } = await import("node:fs/promises");
+    await rm(path, { force: true });
+  }
+  await run("systemctl", ["--user", "daemon-reload"]).catch(() => {});
+}
+
+export async function isInstalled(spec) {
+  return existsSync(unitPath(spec));
+}

package/packages/sidecar/src/index.js

@@ -1,38 +1,150 @@
 import { createServer } from "node:http";
+import { randomBytes } from "node:crypto";
 import { readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { AURORA_LOCALHOST, AURORA_SIDECAR_PORT, isRuntimePath, rewriteRuntimeModel, selectedKeyHeaders, toClientModelItem, toCodexModelInfo, trimSlash } from "../../protocol/src/index.js";
-import { CODEX_HOME, readState, writeSidecarInfo } from "../../state/src/index.js";
+import { CODEX_HOME, readSidecarInfo, readState, writeSidecarInfo } from "../../state/src/index.js";
 
 const CODEX_MODEL_CAPABILITIES_PATH = join(CODEX_HOME, "model_capabilities.json");
 
+// Header / idle timeouts for the upstream gateway connection. The stream body
+// has NO total timeout (long answers must not be cut), but a stalled gateway
+// (half-dead connection that stops sending bytes) is detected by the idle
+// timer and turned into a clean error so the client retries that one request
+// instead of spinning forever.
+const GATEWAY_HEADER_TIMEOUT_MS = 60000;
+const GATEWAY_IDLE_TIMEOUT_MS = 120000;
+
+// Keep the sidecar->gateway TLS connection warm. The expensive part of a cold
+// request is the ~1s TLS handshake to the gateway edge; undici pools the
+// connection but drops it after ~4s idle, so every think-pause re-handshakes
+// ("时快时慢"). A lightweight heartbeat under that idle window keeps one pooled
+// connection alive so real requests reuse a warm socket. It only runs within a
+// window after real activity, so an idle/abandoned sidecar stops chattering.
+const GATEWAY_KEEPALIVE_INTERVAL_MS = 3000;
+const GATEWAY_KEEPWARM_WINDOW_MS = 10 * 60 * 1000;
+let lastActivityAt = 0;
+
+function markActivity() {
+  lastActivityAt = Date.now();
+}
+
+// ensureSidecarIdentity generates the local token once and persists it so the
+// OS service, the launcher, and the running client all agree on a stable
+// token/port across restarts and node upgrades. Random-per-run tokens broke
+// reconnection when a long-lived service outlived the launcher that seeded it.
+export async function ensureSidecarIdentity() {
+  let existing = null;
+  try {
+    existing = await readSidecarInfo();
+  } catch {
+    // First run — generate below.
+  }
+  const port = Number(existing?.port) || AURORA_SIDECAR_PORT;
+  const token = existing?.token || `aurora-local-${randomBytes(24).toString("hex")}`;
+  const baseURL = `http://${AURORA_LOCALHOST}:${port}`;
+  await writeSidecarInfo({ port, token, baseURL });
+  return { port, token, baseURL };
+}
+
 export async function startSidecar(options = {}) {
-  const token = options.token || readArg("--token") || process.env.AURORA_SIDECAR_TOKEN || "aurora-local-dev";
-  const port = Number(options.port || readArg("--port") || process.env.AURORA_SIDECAR_PORT || AURORA_SIDECAR_PORT);
+  const tokenOverride = options.token || readArg("--token") || process.env.AURORA_SIDECAR_TOKEN;
+  const portOverride = options.port || readArg("--port") || process.env.AURORA_SIDECAR_PORT;
+  const identity = await ensureSidecarIdentity();
+  const token = tokenOverride || identity.token;
+  const port = Number(portOverride || identity.port);
   const server = createServer((request, response) => {
     handle(request, response, token).catch(error => {
+      // A streaming response has already flushed its headers, so a 500 here
+      // would throw ERR_HTTP_HEADERS_SENT and (via the global rejection
+      // handler) take the whole daemon down — that is exactly what produced
+      // the Claude Code "ConnectionRefused / retrying" spin. Only synthesize
+      // an error body when nothing has been sent yet; otherwise just close.
+      if (response.headersSent) {
+        response.end();
+        return;
+      }
       response.writeHead(500, { "content-type": "application/json" });
       response.end(JSON.stringify({ error: { type: "sidecar_error", message: error.message } }));
     });
   });
-  server.on("error", error => {
+  // Streaming requests can run for many minutes; the default 5-minute
+  // requestTimeout would cut long turns. Disable the whole-request timeout and
+  // keep only the header timeout that protects against a stuck client.
+  server.requestTimeout = 0;
+  server.headersTimeout = 60000;
+  server.keepAliveTimeout = 75000;
+  server.on("error", async error => {
+    if (error.code === "EADDRINUSE") {
+      // Single-instance: another sidecar already owns the port. If it is
+      // healthy, yield with a clean exit (service managers keep-alive only on
+      // crash, so exit 0 does not loop). If it is a dead bind, exit non-zero
+      // so the service manager retries shortly.
+      if (await pingLocalSidecar(port, token)) {
+        console.error(`Aurora sidecar: port ${port} already served by a healthy instance; yielding.`);
+        process.exit(0);
+      }
+      console.error(`Aurora sidecar: port ${port} busy but unhealthy; will retry.`);
+      process.exit(1);
+    }
     console.error(`Aurora sidecar listen error on ${AURORA_LOCALHOST}:${port}: ${error.message}`);
     process.exit(1);
   });
   server.listen(port, AURORA_LOCALHOST, async () => {
     await writeSidecarInfo({ port, token, baseURL: `http://${AURORA_LOCALHOST}:${port}` });
     console.error(`Aurora sidecar listening on http://${AURORA_LOCALHOST}:${port}`);
+    // Open the warm window and pre-warm the gateway connection so the very
+    // first client request reuses an established TLS socket.
+    markActivity();
+    startGatewayKeepAlive();
   });
 }
 
+function startGatewayKeepAlive() {
+  const beat = async () => {
+    if (Date.now() - lastActivityAt > GATEWAY_KEEPWARM_WINDOW_MS) return;
+    try {
+      const state = await readState();
+      const gatewayURL = trimSlash(state.gatewayURL ?? "https://auroramos.com");
+      // Same origin as proxyRuntime → same undici pool, so this keeps the edge
+      // TLS handshake amortized for real requests. The body MUST be drained:
+      // undici destroys (does not pool) a connection whose response body was
+      // left unconsumed, which silently defeats the warm-up. Result ignored.
+      const response = await fetch(gatewayURL, { signal: AbortSignal.timeout(GATEWAY_HEADER_TIMEOUT_MS) });
+      await response.text();
+    } catch {
+      // Best effort; a failed heartbeat just means the next real request pays
+      // a cold handshake, which is the pre-fix behaviour.
+    }
+  };
+  const timer = setInterval(beat, GATEWAY_KEEPALIVE_INTERVAL_MS);
+  timer.unref();
+  beat();
+}
+
+async function pingLocalSidecar(port, token) {
+  try {
+    const response = await fetch(`http://${AURORA_LOCALHOST}:${port}/aurora/status`, {
+      headers: { authorization: `Bearer ${token}` },
+      signal: AbortSignal.timeout(500)
+    });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+
+// The sidecar is a long-lived local proxy that Claude Code / Codex depend on
+// for every request. A single bad request (e.g. a mid-stream upstream drop)
+// must NOT kill the process: an orphaned sidecar with no live supervisor never
+// comes back, leaving the client stuck on ConnectionRefused. Log and keep
+// serving; the HTTP server stays healthy for the next request.
 process.on("uncaughtException", error => {
   console.error(`Aurora sidecar uncaught exception: ${error?.stack || error?.message || error}`);
-  process.exit(1);
 });
 
 process.on("unhandledRejection", reason => {
   console.error(`Aurora sidecar unhandled rejection: ${reason?.stack || reason?.message || reason}`);
-  process.exit(1);
 });
 
 async function handle(request, response, token) {
@@ -62,6 +174,7 @@ async function handle(request, response, token) {
 }
 
 async function proxyModels(response, incomingURL) {
+  markActivity();
   const state = await readState();
   const gatewayURL = trimSlash(state.gatewayURL ?? "https://auroramos.com");
   const clientVersion = incomingURL.searchParams.get("client_version");
@@ -87,24 +200,55 @@ async function proxyModels(response, incomingURL) {
 }
 
 async function proxyRuntime(request, response, path) {
+  markActivity();
   const state = await readState();
   const body = await readBody(request);
   const capabilitiesByAlias = await readCodexModelCapabilities();
   const gatewayURL = trimSlash(state.gatewayURL ?? "https://auroramos.com");
-  const upstream = await fetch(`${gatewayURL}${path}`, {
-    method: request.method,
-    headers: {
-      ...copyForwardHeaders(request.headers),
-      ...selectedKeyHeaders(state),
-      "content-type": request.headers["content-type"] ?? "application/json",
-      "accept-encoding": "identity"
-    },
-    body: rewriteRuntimeModel(body, state.selectedModel?.alias, capabilitiesByAlias)
-  });
+  // One controller drives both phases: a header timeout until the gateway
+  // responds, then an idle timer that aborts only after a gap with no bytes.
+  const controller = new AbortController();
+  let watchdog = setTimeout(() => controller.abort(new Error("gateway header timeout")), GATEWAY_HEADER_TIMEOUT_MS);
+  let upstream;
+  try {
+    upstream = await fetch(`${gatewayURL}${path}`, {
+      method: request.method,
+      headers: {
+        ...copyForwardHeaders(request.headers),
+        ...selectedKeyHeaders(state),
+        "content-type": request.headers["content-type"] ?? "application/json",
+        "accept-encoding": "identity"
+      },
+      body: rewriteRuntimeModel(body, state.selectedModel?.alias, capabilitiesByAlias),
+      signal: controller.signal
+    });
+  } catch (error) {
+    clearTimeout(watchdog);
+    // Gateway never produced response headers (refused / DNS / header timeout).
+    // Nothing has been sent to the client yet, so a clean 502 lets it retry.
+    writeJSON(response, 502, { error: { type: "gateway_unreachable", message: error?.message || String(error) } });
+    return;
+  }
   response.writeHead(upstream.status, responseHeaders(upstream.headers));
   if (upstream.body) {
-    for await (const chunk of upstream.body) response.write(chunk);
+    // Switch from header timeout to an idle timeout that resets on every chunk.
+    clearTimeout(watchdog);
+    watchdog = setTimeout(() => controller.abort(new Error("gateway idle timeout")), GATEWAY_IDLE_TIMEOUT_MS);
+    try {
+      for await (const chunk of upstream.body) {
+        watchdog.refresh();
+        response.write(chunk);
+      }
+    } catch (error) {
+      // Mid-stream gateway/upstream drop or idle-timeout abort. Headers are
+      // already flushed so we can't promote this to an error status — end the
+      // partial response and let the client retry that single request.
+      // Re-throwing here used to crash the daemon and trigger the
+      // ConnectionRefused spin.
+      console.error(`Aurora sidecar stream relay aborted: ${error?.message || error}`);
+    }
   }
+  clearTimeout(watchdog);
   response.end();
 }