@seqyuan/annovibe 0.8.12

package/bin/pi-web.js

@@ -0,0 +1,825 @@
+#!/usr/bin/env node
+"use strict";
+
+process.title = "annovibe";
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { spawn, spawnSync } = require("child_process");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const path = require("path");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const fs = require("fs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const os = require("os");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const readline = require("readline");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { parseArgs } = require("util");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const bcrypt = require("bcryptjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const https = require("https");
+
+const pkgDir = path.join(__dirname, "..");
+const nextDir = path.join(pkgDir, ".next");
+const pkg = JSON.parse(fs.readFileSync(path.join(pkgDir, "package.json"), "utf8"));
+const VERSION = pkg.version;
+const PKG_NAME = pkg.name;
+const agentDir = process.env.PI_CODING_AGENT_DIR ?? path.join(os.homedir(), ".pi", "agent");
+const authFile = path.join(agentDir, "web-auth.json");
+const stateFile = path.join(agentDir, "annovibe.json");
+const legacyStateFile = path.join(agentDir, "pidex.json");
+const logFile = path.join(agentDir, "annovibe.log");
+const legacyLogFile = path.join(agentDir, "pidex.log");
+const STOP_TERM_TIMEOUT_MS = 6000;
+const STOP_KILL_TIMEOUT_MS = 2000;
+const PROCESS_TITLE = "annovibe";
+const NEXT_PROCESS_TITLE = "annovibe-next";
+
+// Resolve next's CLI entry
+let nextBin;
+try {
+  nextBin = require.resolve("next/dist/bin/next", { paths: [pkgDir] });
+} catch {
+  try {
+    const nextPkg = require.resolve("next/package.json", { paths: [pkgDir] });
+    nextBin = path.join(path.dirname(nextPkg), "dist", "bin", "next");
+  } catch {
+    nextBin = path.join(pkgDir, "node_modules", "next", "dist", "bin", "next");
+  }
+}
+
+const { values: cliArgs, positionals } = parseArgs({
+  options: {
+    port:     { type: "string", short: "p" },
+    hostname: { type: "string", short: "H" },
+    json:     { type: "boolean" },
+    follow:   { type: "boolean", short: "f" },
+    version:  { type: "boolean", short: "v" },
+    help:     { type: "boolean", short: "h" },
+  },
+  strict: false,
+  allowPositionals: true,
+});
+
+const port     = cliArgs.port     ?? process.env.PORT     ?? "30141";
+const hostname = cliArgs.hostname ?? process.env.HOSTNAME ?? null;
+
+// ── CLI commands ──
+
+function ensureAgentDir() {
+  if (!fs.existsSync(agentDir)) fs.mkdirSync(agentDir, { recursive: true });
+}
+
+function getCommandPath() {
+  return path.resolve(process.argv[1] || __filename);
+}
+
+function getUrl(host, listenPort) {
+  return `http://${host ?? "localhost"}:${listenPort}`;
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function setStableProcessTitle(title) {
+  process.title = title;
+  try {
+    Object.defineProperty(process, "title", {
+      configurable: true,
+      enumerable: true,
+      get: () => title,
+      set: () => {},
+    });
+  } catch {
+    const timer = setInterval(() => {
+      try { process.title = title; } catch { /* ignore */ }
+    }, 500);
+    timer.unref();
+  }
+}
+
+function readState() {
+  try {
+    const target = fs.existsSync(stateFile) ? stateFile : legacyStateFile;
+    if (!fs.existsSync(target)) return null;
+    return JSON.parse(fs.readFileSync(target, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function staleStateRemoved() {
+  const state = readState();
+  if (state && !isPidAlive(state.supervisorPid) && !isPidAlive(state.nextPid)) {
+    removeState();
+    return true;
+  }
+  return false;
+}
+
+function writeState(state) {
+  ensureAgentDir();
+  fs.writeFileSync(stateFile, JSON.stringify({ ...state, updatedAt: nowIso() }, null, 2));
+}
+
+function findListeningPids(listenPort) {
+  if (process.platform === "win32") return [];
+  const pids = new Set();
+  try {
+    const result = spawnSync("lsof", [`-tiTCP:${listenPort}`, "-sTCP:LISTEN"], { encoding: "utf8" });
+    result.stdout
+      .split(/\s+/)
+      .map((value) => Number(value))
+      .filter((pid) => Number.isInteger(pid) && pid > 0 && pid !== process.pid)
+      .forEach((pid) => pids.add(pid));
+  } catch {
+    // Fall through to ss.
+  }
+  if (pids.size === 0 && process.platform === "linux") {
+    try {
+      const result = spawnSync("ss", ["-H", "-ltnp", `sport = :${listenPort}`], { encoding: "utf8" });
+      const matches = result.stdout.matchAll(/pid=(\d+)/g);
+      for (const match of matches) {
+        const pid = Number(match[1]);
+        if (Number.isInteger(pid) && pid > 0 && pid !== process.pid) pids.add(pid);
+      }
+    } catch {
+      // Ignore lookup failures.
+    }
+  }
+  return [...pids];
+}
+
+function safeRealpath(targetPath) {
+  try {
+    return fs.realpathSync(targetPath);
+  } catch {
+    return targetPath;
+  }
+}
+
+function isPathInside(childPath, parentPath) {
+  const relative = path.relative(parentPath, childPath);
+  return relative === "" || (!!relative && !relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function readProcessCmdline(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return "";
+  if (process.platform === "linux") {
+    try {
+      return fs.readFileSync(`/proc/${pid}/cmdline`, "utf8").replace(/\0/g, " ").trim();
+    } catch {
+      // Fall through to ps.
+    }
+  }
+  try {
+    const result = spawnSync("ps", ["-p", String(pid), "-o", "command="], { encoding: "utf8" });
+    return result.status === 0 ? result.stdout.trim() : "";
+  } catch {
+    return "";
+  }
+}
+
+function readProcessCwd(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return "";
+  if (process.platform === "linux") {
+    try {
+      return fs.realpathSync(`/proc/${pid}/cwd`);
+    } catch {
+      return "";
+    }
+  }
+  if (process.platform === "darwin") {
+    try {
+      const result = spawnSync("lsof", ["-a", "-p", String(pid), "-d", "cwd", "-Fn"], { encoding: "utf8" });
+      if (result.status !== 0) return "";
+      const line = result.stdout.split(/\r?\n/).find((value) => value.startsWith("n"));
+      return line ? safeRealpath(line.slice(1)) : "";
+    } catch {
+      return "";
+    }
+  }
+  return "";
+}
+
+function getProcessSummary(pid) {
+  return {
+    pid,
+    cmdline: readProcessCmdline(pid),
+    cwd: readProcessCwd(pid),
+  };
+}
+
+function looksLikeAnnoVibeProcess(info) {
+  const cmdline = info.cmdline || "";
+  const cwd = info.cwd || "";
+  const realPkgDir = safeRealpath(pkgDir);
+  const realCwd = cwd ? safeRealpath(cwd) : "";
+  const inAnnoVibeDir = !!realCwd && isPathInside(realCwd, realPkgDir);
+  const commandMentionsAnnoVibe =
+    cmdline.includes("pi-web.js") ||
+    cmdline.includes("@seqyuan/annovibe") ||
+    cmdline.includes("@seqyuan/pidex") ||
+    cmdline.includes("/annovibe/") ||
+    cmdline.includes("/pidex/") ||
+    cmdline.includes("\\annovibe\\") ||
+    cmdline.includes("\\pidex\\") ||
+    cmdline.includes(PROCESS_TITLE);
+  const commandMentionsNext =
+    cmdline.includes("next-server") ||
+    cmdline.includes("next/dist/bin/next") ||
+    cmdline.includes("next start");
+
+  return commandMentionsAnnoVibe || (inAnnoVibeDir && commandMentionsNext);
+}
+
+async function stopVerifiedPortListeners(listenPort, quiet = false) {
+  const listeningPids = findListeningPids(listenPort);
+  if (listeningPids.length === 0) return { found: false, stopped: true, skipped: [] };
+
+  const verified = [];
+  const skipped = [];
+  for (const pid of listeningPids) {
+    const info = getProcessSummary(pid);
+    if (looksLikeAnnoVibeProcess(info)) {
+      verified.push(pid);
+    } else {
+      skipped.push(info);
+    }
+  }
+
+  if (skipped.length > 0) {
+    for (const info of skipped) {
+      const label = info.cmdline || "unknown command";
+      console.error(`annovibe stop: port ${listenPort} is used by pid ${info.pid}, but it does not look like annovibe; not stopping it.`);
+      console.error(`command: ${label}`);
+      if (info.cwd) console.error(`cwd: ${info.cwd}`);
+    }
+  }
+
+  if (verified.length === 0) {
+    return { found: true, stopped: skipped.length === 0, skipped };
+  }
+
+  let stopped = true;
+  for (const pid of verified) {
+    stopped = (await terminatePid(pid)) && stopped;
+  }
+  if (!quiet) {
+    console.log(stopped
+      ? `annovibe stop: stopped listener pid${verified.length === 1 ? "" : "s"} ${verified.join(", ")}`
+      : `annovibe stop: failed to stop listener pid${verified.length === 1 ? "" : "s"} ${verified.join(", ")}`);
+  }
+  return { found: true, stopped: stopped && skipped.length === 0, skipped };
+}
+
+function removeState() {
+  try { fs.rmSync(stateFile, { force: true }); } catch { /* ignore */ }
+  try { fs.rmSync(legacyStateFile, { force: true }); } catch { /* ignore */ }
+}
+
+function isPidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error && error.code === "EPERM";
+  }
+}
+
+function waitForPidExit(pid, timeoutMs) {
+  const startedAt = Date.now();
+  return new Promise((resolve) => {
+    const tick = () => {
+      if (!isPidAlive(pid)) {
+        resolve(true);
+        return;
+      }
+      if (Date.now() - startedAt >= timeoutMs) {
+        resolve(false);
+        return;
+      }
+      setTimeout(tick, 100);
+    };
+    tick();
+  });
+}
+
+async function terminatePid(pid, termTimeoutMs = STOP_TERM_TIMEOUT_MS, killTimeoutMs = STOP_KILL_TIMEOUT_MS) {
+  if (!isPidAlive(pid)) return true;
+  try {
+    process.kill(pid, "SIGTERM");
+  } catch {
+    return !isPidAlive(pid);
+  }
+  if (await waitForPidExit(pid, termTimeoutMs)) return true;
+  try {
+    process.kill(pid, "SIGKILL");
+  } catch {
+    return !isPidAlive(pid);
+  }
+  return waitForPidExit(pid, killTimeoutMs);
+}
+
+function renderState(state, json = false) {
+  const supervisorAlive = !!state && isPidAlive(state.supervisorPid);
+  const nextAlive = !!state && isPidAlive(state.nextPid);
+  const status = supervisorAlive ? "running" : nextAlive ? "orphaned" : "stopped";
+  const payload = {
+    running: supervisorAlive || nextAlive,
+    status,
+    version: state?.version ?? VERSION,
+    url: state?.url ?? getUrl(hostname, port),
+    port: state?.port ?? port,
+    hostname: state?.hostname ?? hostname,
+    supervisorPid: supervisorAlive ? state.supervisorPid : null,
+    nextPid: nextAlive ? state.nextPid : null,
+    startedAt: supervisorAlive ? state.startedAt ?? null : null,
+    logFile,
+    stateFile,
+  };
+  if (json) return JSON.stringify(payload, null, 2);
+  if (payload.status === "stopped") {
+    return [
+      "annovibe status: stopped",
+      `log: ${payload.logFile}`,
+      `state: ${payload.stateFile}`,
+    ].join("\n");
+  }
+  return [
+    "annovibe status: running",
+    `url: ${payload.url}`,
+    `version: ${payload.version}`,
+    `state: ${payload.status}`,
+    `supervisor pid: ${payload.supervisorPid ?? "not running"}`,
+    `next pid: ${payload.nextPid ?? "unknown"}`,
+    `started: ${payload.startedAt ?? "unknown"}`,
+    `log: ${payload.logFile}`,
+  ].join("\n");
+}
+
+function printRecentLogs(follow = false) {
+  ensureAgentDir();
+  const targetLogFile = fs.existsSync(logFile) ? logFile : legacyLogFile;
+  if (!fs.existsSync(targetLogFile)) {
+    console.log(`annovibe logs: no log file yet (${logFile})`);
+    return;
+  }
+  const content = fs.readFileSync(targetLogFile, "utf8");
+  const lines = content.split(/\r?\n/);
+  console.log(lines.slice(Math.max(0, lines.length - 200)).join("\n"));
+  if (!follow) return;
+  const tail = spawn(process.platform === "win32" ? "powershell.exe" : "tail", process.platform === "win32"
+    ? ["-NoProfile", "-Command", `Get-Content -Path ${JSON.stringify(targetLogFile)} -Wait -Tail 0`]
+    : ["-f", targetLogFile], { stdio: "inherit" });
+  tail.on("exit", (code) => process.exit(code ?? 0));
+}
+
+async function stopManagedServer(quiet = false) {
+  const state = readState();
+  if (!state) {
+    const portStop = await stopVerifiedPortListeners(port, quiet);
+    if (portStop.found) return portStop.stopped ? 0 : 1;
+    if (!quiet) console.log("annovibe stop: already stopped");
+    return 0;
+  }
+
+  const supervisorPid = state.supervisorPid;
+  const nextPid = state.nextPid;
+  let stopped = true;
+  if (isPidAlive(supervisorPid)) {
+    stopped = await terminatePid(supervisorPid);
+  }
+  if (nextPid && isPidAlive(nextPid)) {
+    stopped = (await terminatePid(nextPid)) && stopped;
+  }
+  if (stopped) {
+    removeState();
+    if (!quiet) console.log(`annovibe stop: stopped${supervisorPid ? ` pid ${supervisorPid}` : ""}`);
+    return 0;
+  }
+  if (!quiet) console.error(`annovibe stop: failed to stop pid ${supervisorPid}`);
+  return 1;
+}
+
+async function startManagedServer({ quiet = false } = {}) {
+  seedDefaults();
+  await maybeSetupAuth();
+  if (!fs.existsSync(nextDir)) {
+    console.error("Build artifacts not found. Please report this issue.");
+    return 1;
+  }
+  staleStateRemoved();
+  const existing = readState();
+  const existingSupervisorAlive = existing && isPidAlive(existing.supervisorPid);
+  const existingNextAlive = existing && isPidAlive(existing.nextPid);
+  if (existingSupervisorAlive) {
+    if (!quiet) {
+      console.log(`annovibe start: already running pid ${existing.supervisorPid}`);
+      console.log(`url: ${existing.url ?? getUrl(hostname, port)}`);
+      console.log(`log: ${logFile}`);
+    }
+    return 0;
+  }
+  if (existingNextAlive) {
+    if (!quiet) console.log(`annovibe start: recovering orphaned server pid ${existing.nextPid}`);
+    if (!(await terminatePid(existing.nextPid))) {
+      if (!quiet) console.error(`annovibe start: failed to stop orphaned server pid ${existing.nextPid}`);
+      return 1;
+    }
+    removeState();
+  }
+  ensureAgentDir();
+  const fd = fs.openSync(logFile, "a");
+  const child = spawn(process.execPath, [getCommandPath(), "__server", "--port", String(port), ...(hostname ? ["--hostname", hostname] : [])], {
+    cwd: pkgDir,
+    detached: true,
+    stdio: ["ignore", fd, fd],
+    env: {
+      ...process.env,
+      ANNOVIBE_MANAGED: "1",
+    },
+  });
+  fs.closeSync(fd);
+  if (!child.pid) {
+    throw new Error("failed to start annovibe server");
+  }
+  child.unref();
+  const state = {
+    schemaVersion: 1,
+    version: VERSION,
+    command: `${getCommandPath()} __server --port ${port}${hostname ? ` --hostname ${hostname}` : ""}`,
+    supervisorPid: child.pid,
+    nextPid: null,
+    port: String(port),
+    hostname,
+    url: getUrl(hostname, port),
+    logFile,
+    stateFile,
+    startedAt: nowIso(),
+  };
+  writeState(state);
+  if (!quiet) {
+    console.log(`annovibe start: pid ${child.pid}`);
+    console.log(`url: ${state.url}`);
+    console.log(`log: ${logFile}`);
+  }
+  return 0;
+}
+
+if (cliArgs.version) {
+  console.log(VERSION);
+  process.exit(0);
+}
+
+if (cliArgs.help) {
+  console.log(`annovibe v${VERSION} — Web UI for the pi coding agent
+
+Usage:
+  annovibe [options]
+  annovibe start          Start annovibe in background
+  annovibe restart        Stop then start annovibe in background
+  annovibe stop           Stop background annovibe
+  annovibe status [--json] Show background server status
+  annovibe logs [-f]      Show background server logs
+  annovibe passwd          Change password (or set if none)
+  annovibe passwd --reset   Remove password (disable auth)
+  annovibe update          Update to the latest version
+
+Options:
+  -p, --port <port>     Port to listen on (default: 30141, env: PORT)
+  -H, --hostname <host> Hostname to bind to (default: localhost)
+      --json            Print machine-readable status JSON
+  -f, --follow          Follow logs
+  -v, --version         Print version
+  -h, --help            Show this help
+
+Environment:
+  PORT                  Server port
+  ANNOVIBE_PASSWORD     Set password on first start
+  PI_CODING_AGENT_DIR   Custom pi agent data directory
+`);
+  process.exit(0);
+}
+
+const firstPos = positionals[0];
+if (firstPos === "status") {
+  const json = cliArgs.json;
+  staleStateRemoved();
+  const state = readState();
+  console.log(renderState(state, json));
+  process.exit(state && (isPidAlive(state.supervisorPid) || isPidAlive(state.nextPid)) ? 0 : 1);
+}
+
+if (firstPos === "logs") {
+  printRecentLogs(cliArgs.follow);
+  if (!cliArgs.follow) process.exit(0);
+  return;
+}
+
+if (firstPos === "stop") {
+  stopManagedServer()
+    .then((code) => process.exit(code))
+    .catch((error) => {
+      console.error(`annovibe stop: ${error instanceof Error ? error.message : String(error)}`);
+      process.exit(1);
+    });
+  return;
+}
+
+if (firstPos === "start") {
+  startManagedServer()
+    .then((code) => process.exit(code))
+    .catch((error) => {
+      console.error(`annovibe start: ${error instanceof Error ? error.message : String(error)}`);
+      process.exit(1);
+    });
+  return;
+}
+
+if (firstPos === "restart") {
+  stopManagedServer(true).then(async (code) => {
+    if (code !== 0) process.exit(code);
+    process.exit(await startManagedServer());
+  }).catch((error) => {
+    console.error(`annovibe restart: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+  });
+  return;
+}
+
+if (firstPos === "update") {
+  console.log(`\n  Updating ${PKG_NAME} to latest version...\n`);
+  const npmExecPath = process.env.npm_execpath;
+  const hasNpmExecPath = npmExecPath && fs.existsSync(npmExecPath);
+  const command = hasNpmExecPath ? process.execPath : (process.platform === "win32" ? "npm.cmd" : "npm");
+  const args = [
+    ...(hasNpmExecPath ? [npmExecPath] : []),
+    "install", "-g", `${PKG_NAME}@latest`,
+  ];
+  const child = spawn(command, args, { stdio: "inherit" });
+  child.on("exit", (code) => process.exit(code ?? 0));
+  return;
+}
+
+if (firstPos === "passwd") {
+  const reset = positionals[1] === "--reset";
+
+  if (reset) {
+    if (fs.existsSync(authFile)) {
+      fs.unlinkSync(authFile);
+      console.log("   🔓 Password removed. Auth disabled.\n");
+    } else {
+      console.log("   No password configured.\n");
+    }
+    process.exit(0);
+  }
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (prompt) => new Promise((res) => rl.question(prompt, res));
+  (async () => {
+    const exists = fs.existsSync(authFile);
+    if (exists) {
+      console.log("\n   Changing password...\n");
+      const oldPw = await ask("Current password: ");
+      try {
+        const cfg = JSON.parse(fs.readFileSync(authFile, "utf8"));
+        if (!bcrypt.compareSync(oldPw, cfg.passwordHash)) {
+          console.log("   ❌ Incorrect password.\n");
+          rl.close();
+          process.exit(1);
+        }
+      } catch { console.log("   ❌ Could not read auth file.\n"); rl.close(); process.exit(1); }
+    }
+    const pw1 = await ask("New password (empty to disable): ");
+    if (!pw1.trim()) {
+      if (fs.existsSync(authFile)) fs.unlinkSync(authFile);
+      console.log("   🔓 Auth disabled.\n");
+      rl.close();
+      process.exit(0);
+    }
+    const pw2 = await ask("Confirm new password: ");
+    if (pw1 !== pw2) {
+      console.log("   ❌ Passwords don't match.\n");
+      rl.close();
+      process.exit(1);
+    }
+    const hash = bcrypt.hashSync(pw1, 10);
+    const dir = path.dirname(authFile);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(authFile, JSON.stringify({ passwordHash: hash, enabled: true }, null, 2));
+    console.log(exists ? "   ✅ Password changed.\n" : "   ✅ Password set.\n");
+    rl.close();
+    process.exit(0);
+  })();
+  return;
+}
+
+// ── Version check (async, non-blocking) ──
+
+function checkVersion() {
+  const req = https.get(`https://registry.npmjs.org/${encodeURIComponent(PKG_NAME)}/latest`, { timeout: 5000 }, (res) => {
+    let data = "";
+    res.on("data", (chunk) => data += chunk);
+    res.on("end", () => {
+      try {
+        const json = JSON.parse(data);
+        const latest = json.version;
+        if (latest && latest !== VERSION) {
+          console.log(`\n   ⚡ Update available: ${VERSION} → ${latest}`);
+          console.log(`   Run: annovibe update\n`);
+        }
+      } catch { /* ignore */ }
+    });
+  });
+  req.on("error", () => {});
+  req.on("timeout", () => req.destroy());
+}
+
+// ── Normal startup ──
+
+function promptPassword() {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const ask = (prompt) => new Promise((res) => rl.question(prompt, res));
+    (async () => {
+      console.log("\n🔐 No password set. You can protect annovibe with a password.");
+      console.log("   Leave empty and press Enter to skip.\n");
+      const pw1 = await ask("Enter password: ");
+      if (!pw1.trim()) {
+        console.log("   Skipped — no password required.\n");
+        rl.close();
+        resolve(false);
+        return;
+      }
+      const pw2 = await ask("Confirm password: ");
+      if (pw1 !== pw2) {
+        console.log("   Passwords don't match. Skipping.\n");
+        rl.close();
+        resolve(false);
+        return;
+      }
+      const hash = bcrypt.hashSync(pw1, 10);
+      const dir = path.dirname(authFile);
+      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(authFile, JSON.stringify({ passwordHash: hash, enabled: true }, null, 2));
+      console.log("   ✅ Password set. Restart won't prompt.\n");
+      rl.close();
+      resolve(true);
+    })();
+  });
+}
+
+async function maybeSetupAuth() {
+  if (fs.existsSync(authFile)) return;
+  const password = process.env.ANNOVIBE_PASSWORD ?? process.env.PIDEX_PASSWORD;
+  if (password) {
+    const hash = bcrypt.hashSync(password, 10);
+    const dir = path.dirname(authFile);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(authFile, JSON.stringify({ passwordHash: hash, enabled: true }, null, 2));
+    console.log(`   🔐 Password set from ${process.env.ANNOVIBE_PASSWORD ? "ANNOVIBE_PASSWORD" : "PIDEX_PASSWORD"} env var.`);
+    return;
+  }
+  if (!process.stdin.isTTY) return;
+  await promptPassword();
+}
+
+function seedDefaults() {
+  const defaultSoulSrc = path.join(pkgDir, "lib", "default-soul.md");
+  const soulDest = path.join(agentDir, "soul.md");
+  if (!fs.existsSync(soulDest) && fs.existsSync(defaultSoulSrc)) {
+    const dir = path.dirname(soulDest);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    fs.copyFileSync(defaultSoulSrc, soulDest);
+    console.log("   🖖 Default soul.md seeded to ~/.pi/agent/soul.md");
+  }
+
+  const defaultHarnessSrc = path.join(pkgDir, "lib", "visualization-harness.md");
+  const harnessDest = path.join(agentDir, "harness.md");
+  if (!fs.existsSync(harnessDest) && fs.existsSync(defaultHarnessSrc)) {
+    const dir = path.dirname(harnessDest);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    fs.copyFileSync(defaultHarnessSrc, harnessDest);
+    console.log("   📊 Default harness.md seeded to ~/.pi/agent/harness.md");
+  }
+}
+
+// ── Start server ──
+function openBrowser(url) {
+  const isWindows = process.platform === "win32";
+  const isMac = process.platform === "darwin";
+  const openCmd = isWindows ? "start" : isMac ? "open" : "xdg-open";
+  const openChild = spawn(openCmd, [url], { shell: isWindows, stdio: "ignore", detached: true });
+  openChild.on("error", () => {});
+  openChild.unref();
+}
+
+async function runServerProcess() {
+  setStableProcessTitle(PROCESS_TITLE);
+  await maybeSetupAuth();
+  if (!fs.existsSync(nextDir)) {
+    console.error("Build artifacts not found. Please report this issue.");
+    process.exit(1);
+  }
+
+  checkVersion();
+
+  const url = getUrl(hostname, port);
+  const nextArgs = [getCommandPath(), "__next", "--port", String(port)];
+  if (hostname) nextArgs.push("--hostname", hostname);
+
+  const child = spawn(process.execPath, nextArgs, {
+    cwd: pkgDir,
+    stdio: ["ignore", "pipe", "pipe"],
+    env: {
+      ...process.env,
+      ANNOVIBE_SUPERVISOR_PID: String(process.pid),
+      ANNOVIBE_NEXT_WRAPPER: "1",
+    },
+  });
+
+  const writeCurrentState = (patch = {}) => {
+    const current = readState() ?? {};
+    writeState({
+      schemaVersion: 1,
+      version: VERSION,
+      command: `${getCommandPath()} __server --port ${port}${hostname ? ` --hostname ${hostname}` : ""}`,
+      supervisorPid: process.pid,
+      nextPid: child.pid ?? null,
+      port: String(port),
+      hostname,
+      url,
+      logFile,
+      stateFile,
+      startedAt: current.startedAt ?? nowIso(),
+      ...patch,
+    });
+  };
+
+  writeCurrentState();
+
+  let browserOpened = false;
+  child.stdout.on("data", (chunk) => {
+    const text = chunk.toString();
+    process.stdout.write(text);
+    if (!browserOpened && text.includes("Ready")) {
+      browserOpened = true;
+      openBrowser(url);
+      console.log(`\n   annovibe running at ${url}\n`);
+      writeCurrentState({ readyAt: nowIso() });
+    }
+  });
+  child.stderr.on("data", (chunk) => process.stderr.write(chunk));
+
+  const shutdown = async () => {
+    await terminatePid(child.pid);
+    removeState();
+    process.exit(0);
+  };
+  process.on("SIGTERM", () => { void shutdown(); });
+  process.on("SIGINT", () => { void shutdown(); });
+
+  child.on("exit", (code) => {
+    removeState();
+    process.exit(code ?? 0);
+  });
+}
+
+function runNextProcess() {
+  setStableProcessTitle(NEXT_PROCESS_TITLE);
+  if (!fs.existsSync(nextDir)) {
+    console.error("Build artifacts not found. Please report this issue.");
+    process.exit(1);
+  }
+
+  const nextArgs = ["start", "-p", String(port)];
+  if (hostname) nextArgs.push("-H", String(hostname));
+  process.argv = [process.execPath, nextBin, ...nextArgs];
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  require(nextBin);
+}
+
+if (firstPos === "__server") {
+  runServerProcess().catch((error) => {
+    console.error(`annovibe server: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+  });
+} else if (firstPos === "__next") {
+  try {
+    runNextProcess();
+  } catch (error) {
+    console.error(`annovibe next: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+  }
+} else {
+  startManagedServer()
+    .then((code) => process.exit(code))
+    .catch((error) => {
+      console.error(`annovibe start: ${error instanceof Error ? error.message : String(error)}`);
+      process.exit(1);
+    });
+}