magpie-agent-console 0.1.0 → 1.1.0

package/index.mjs

@@ -1,244 +1,537 @@
-// Agent Console v1.0 — magpie 插件入口（§9.1）
-// 职责：确保后台 daemon（独立 Node 进程）在运行并复用；不在宿主里跑业务。
-// 模块加载即执行一次「确保 daemon」（沿用旧版防白屏做法）；
-// magpie 回调 server(input, options) 传入不同 port 时重启 daemon 迁移端口。
-
-import { spawn, execFile } from "node:child_process";
-import { readFileSync, existsSync, openSync, closeSync, statSync } from "node:fs";
-import { mkdir, readFile } from "node:fs/promises";
+// Agent Console — Magpie plugin entry (loaded by Magpie's Bun plugin host).
+//
+// Lifecycle and token handoff (design after the PR #535 review):
+// - Importing this module has no side effects: no port, no process, no file writes.
+// - When Magpie calls server(input, options): generate two random secrets for this host — the gate key (written to
+//   page/session.js) and the daemon token (handed to the daemon page only via the # fragment of the gate's 302, never written to any static file) —
+//   and bind a tiny "gate" (lib/gate.mjs) on 127.0.0.1:<port> (default 3488). Only after a successful bind is
+//   page/session.js written atomically; the plugin page (sandbox iframe) reads it from the page directory Magpie serves. If the bind fails (port in use)
+//   it retries every 2 seconds in the background; server() itself returns immediately and never blocks the plugin host from loading.
+// - The daemon is started only when the plugin page navigates to the gate's /open?k=<key> ("start on page open"): a non-detached child,
+//   stdin is a lifeline pipe and it gets --parent-pid; later /open calls reuse the same child.
+// - The daemon exits by itself when the host exits (stdin closes or the parent disappears) or after an idle timeout (60 minutes);
+//   stop() closes the gate, ends the daemon and deletes session.js.
+// - Note: Magpie's plugin host treats the return value of server() as an OpenCode hooks object and never calls stop();
+//   the host calls process.exit() after Magpie closes its stdin. So what really runs is the synchronous exit safety net:
+//   close the daemon's lifeline pipe and delete the session.js this host wrote.
+// - No SIGINT/SIGTERM handlers (they would swallow the host's default termination behavior).
+
+import { execFile, spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import {
+  appendFileSync,
+  closeSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import http from "node:http";
 import { homedir } from "node:os";
-import { join, dirname } from "node:path";
+import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import http from "node:http";
+import { createGate } from "./lib/gate.mjs";
+import { NODE_TOO_OLD_MESSAGE, requireNode } from "./lib/pathscan.mjs";
 
 const here = dirname(fileURLToPath(import.meta.url));
-const pkg = JSON.parse(readFileSync(join(here, "package.json"), "utf8"));
-const VERSION = String(pkg.version || "0.0.0");
-
-const dataRoot = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
-const dataDir = join(dataRoot, "magpie", "agent-console");
-const daemonJsonPath = join(dataDir, "daemon.json");
 const DEFAULT_PORT = 3488;
+// Longest wait for the daemon's ready line (Windows cold start + antivirus scanning can be slow)
+const READY_TIMEOUT_MS = 15000;
+const BIND_RETRY_MS = 2000;
+const SESSION_BEAT_MS = 4000;
+// A port still busy after this many tries (~10 s) is worth a log line (see bindLoop)
+const BUSY_LOG_AFTER = 5;
+function bindDelayMs() {
+  const v = Number(process.env.AGENT_CONSOLE_BIND_DELAY_MS);
+  return Number.isFinite(v) && v >= 0 ? v : 1200;
+}
+
+// Paths are computed again inside server(): tests change environment variables after import
+function paths() {
+  const dataRoot = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+  const dataDir = join(dataRoot, "magpie", "agent-console");
+  return {
+    dataRoot,
+    dataDir,
+    logsDir: join(dataDir, "logs"),
+    spawnLog: join(dataDir, "logs", "daemon-spawn.log"),
+    daemonJson: join(dataDir, "daemon.json"),
+    // pid of the host that wrote page/session.js (kept out of the page directory, which any page can read)
+    sessionOwner: join(dataDir, "session-owner.json"),
+    pageDir: process.env.AGENT_CONSOLE_PAGE_DIR || join(here, "page"),
+  };
+}
 
-function envPort() {
-  const p = Number(process.env.AGENT_CONSOLE_PORT || "");
-  return Number.isInteger(p) && p >= 1 && p <= 65535 ? p : DEFAULT_PORT;
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+// ESRCH = gone; EPERM = exists but we may not signal it (common on Windows), counts as alive
 function pidAlive(pid) {
   try {
     process.kill(pid, 0);
     return true;
+  } catch (error) {
+    return error?.code === "EPERM";
+  }
+}
+
+// A failed log write (directory deleted, disk full) must never make the host's flow throw
+function makeLogger(p) {
+  return (message) => {
+    try {
+      mkdirSync(p.logsDir, { recursive: true });
+      appendFileSync(p.spawnLog, `[${new Date().toISOString()}] ${message}\n`);
+    } catch {}
+  };
+}
+
+function readDaemonInfo(p) {
+  try {
+    return JSON.parse(readFileSync(p.daemonJson, "utf8"));
   } catch {
-    return false;
+    return null;
   }
 }
 
 function ping(port, token) {
-  return new Promise((res) => {
-    const req = http.get(
-      { host: "127.0.0.1", port, path: "/api/ping", headers: { "x-agent-console": token }, timeout: 2000 },
-      (r) => {
-        let b = "";
-        r.on("data", (c) => (b += c));
-        r.on("end", () => {
+  return new Promise((resolve) => {
+    const request = http.get(
+      {
+        host: "127.0.0.1",
+        port,
+        path: "/api/ping",
+        headers: { "x-agent-console": token },
+        timeout: 1500,
+      },
+      (response) => {
+        let body = "";
+        response.on("data", (chunk) => {
+          body += chunk;
+        });
+        response.on("end", () => {
           try {
-            res(JSON.parse(b));
+            resolve(JSON.parse(body));
           } catch {
-            res(null);
+            resolve(null);
           }
         });
-      }
+      },
     );
-    req.on("error", () => res(null));
-    req.on("timeout", () => {
-      req.destroy();
-      res(null);
+    request.on("error", () => resolve(null));
+    request.on("timeout", () => {
+      request.destroy();
+      resolve(null);
     });
   });
 }
 
-function sleep(ms) {
-  return new Promise((r) => setTimeout(r, ms));
-}
-
-function findNode() {
-  return new Promise((res) => {
-    execFile("where.exe", ["node"], { windowsHide: true, timeout: 4000 }, (e, out) => {
-      if (e) return res(process.execPath);
-      const hits = String(out)
-        .split(/\r?\n/)
-        .map((s) => s.trim())
-        .filter(Boolean);
-      res(hits.find((h) => /node\.exe$/i.test(h)) || hits[0] || process.execPath);
-    });
-  });
+async function killPid(pid) {
+  if (process.platform === "win32") {
+    await new Promise((resolve) =>
+      execFile("taskkill", ["/PID", String(pid), "/T", "/F"], { windowsHide: true }, () => resolve()),
+    );
+    return;
+  }
+  try {
+    process.kill(pid, "SIGTERM");
+  } catch {}
+  for (let i = 0; i < 20 && pidAlive(pid); i++) await sleep(100);
+  if (pidAlive(pid)) {
+    try {
+      process.kill(pid, "SIGKILL");
+    } catch {}
+  }
 }
 
-async function shutdownViaWs(port, token) {
+// The 0.1.0 daemon was detached and may still hold 3488 after an upgrade.
+// Only after it answered a ping with the token from daemon.json (confirming it really is our daemon, guarding against pid reuse)
+// do we first shut it down gracefully via WS app.shutdown, then force-kill it if it's still there.
+async function shutdownLegacy(info, log) {
+  if (!info?.pid || !info?.port || !info?.token || !pidAlive(info.pid)) return;
+  const answer = await ping(info.port, info.token);
+  if (!answer?.ok || answer.pid !== info.pid) return;
+  log(`stopping legacy daemon pid ${info.pid} on port ${info.port}`);
   try {
     const { WebSocket } = await import("ws");
-    await new Promise((res) => {
-      const ws = new WebSocket(`ws://127.0.0.1:${port}/ws`);
-      const t = setTimeout(() => {
-        try {
-          ws.terminate();
-        } catch {}
-        res();
+    await new Promise((resolve) => {
+      const socket = new WebSocket(`ws://127.0.0.1:${info.port}/ws`);
+      const timer = setTimeout(() => {
+        socket.terminate();
+        resolve();
       }, 3000);
-      ws.on("open", () => {
-        ws.send(JSON.stringify({ t: "hello", token, v: 1 }));
-      });
-      ws.on("message", (d) => {
-        let m;
+      socket.on("open", () => socket.send(JSON.stringify({ t: "hello", token: info.token, v: 1 })));
+      socket.on("message", (data) => {
+        let message;
         try {
-          m = JSON.parse(String(d));
+          message = JSON.parse(String(data));
         } catch {
           return;
         }
-        if (m.t === "hello.ok") {
-          ws.send(JSON.stringify({ t: "req", id: 1, m: "app.shutdown", p: {} }));
+        if (message.t === "hello.ok") {
+          socket.send(JSON.stringify({ t: "req", id: 1, m: "app.shutdown", p: {} }));
         }
-        if (m.t === "res" && m.id === 1) {
-          clearTimeout(t);
-          ws.close();
-          res();
+        if (message.t === "res" && message.id === 1) {
+          clearTimeout(timer);
+          socket.close();
+          resolve();
         }
       });
-      ws.on("error", () => {
-        clearTimeout(t);
-        res();
-      });
-      ws.on("close", () => {
-        clearTimeout(t);
-        res();
+      socket.on("error", () => {
+        clearTimeout(timer);
+        resolve();
       });
     });
   } catch {}
+  for (let i = 0; i < 30 && pidAlive(info.pid); i++) await sleep(100);
+  if (pidAlive(info.pid)) await killPid(info.pid);
 }
 
-async function killPid(pid) {
-  if (process.platform === "win32") {
-    await new Promise((res) => {
-      execFile("taskkill", ["/PID", String(pid), "/T", "/F"], { windowsHide: true, timeout: 5000 }, () => res());
-    });
-  } else {
-    try {
-      process.kill(pid, "SIGTERM");
-    } catch {}
-    await sleep(1500);
-    try {
-      process.kill(pid, "SIGKILL");
-    } catch {}
-  }
-}
-
-async function shutdownDaemon(info) {
-  if (info?.port && info?.token) await shutdownViaWs(info.port, info.token);
-  for (let i = 0; i < 12 && pidAlive(info.pid); i++) await sleep(250);
-  if (pidAlive(info.pid)) await killPid(info.pid);
+// session.js is a script file holding only the gate port (a number) and the gate key (hex); "<" is still escaped just in case.
+// Any page that knows Magpie's page path can read it with <script src>, so the daemon token must never go here.
+// ts: when it was written. beat: whether this host keeps refreshing it (every SESSION_BEAT_MS, from the first page open on).
+// A host that is killed hard (Magpie restarting it, Windows) can't delete its session.js:
+// - boot.js treats a beating file whose ts stopped moving as stale, and after a lost connection (ac_lost) takes only a file written
+//   after the loss, so it waits for the new host's file instead of opening a dead gate;
+// - a file that never beat (the page was never opened) says nothing by its age, so the next host deletes it at startup when the
+//   host that wrote it is gone (removeDeadSession), before Magpie serves the page.
+function writeSession(pageDir, port, key, beat = false) {
+  mkdirSync(pageDir, { recursive: true });
+  const json = JSON.stringify({ v: 2, port, key, ts: Date.now(), beat }).replace(/</g, "\\u003c");
+  const temp = join(pageDir, `.session-${process.pid}-${randomBytes(4).toString("hex")}.tmp`);
+  writeFileSync(temp, `globalThis.AgentConsoleSession = ${json};\n`, { mode: 0o600 });
+  renameSync(temp, join(pageDir, "session.js"));
 }
 
-async function startDaemon(port) {
-  const node = await findNode();
-  await mkdir(join(dataDir, "logs"), { recursive: true });
-  const logFd = openSync(join(dataDir, "logs", "daemon-spawn.log"), "a");
+// At host startup (synchronously, so before Magpie serves the page that made it start this host): a session.js left by a host
+// that is no longer running points at a dead gate; delete it so boot.js waits for this host's file.
+// session-owner.json holds the writer's pid; a live writer (another host, e.g. Magpie's own while a `magpie` CLI command runs) is left alone.
+function removeDeadSession(p) {
+  const sessionPath = join(p.pageDir, "session.js");
+  let owner;
   try {
-    const child = spawn(
-      node,
-      [join(here, "daemon", "dist", "main.js"), "--port", String(port), "--data", dataRoot],
-      { detached: true, stdio: ["ignore", logFd, logFd], windowsHide: true }
-    );
-    child.unref();
-    return child;
-  } finally {
-    closeSync(logFd);
+    owner = JSON.parse(readFileSync(p.sessionOwner, "utf8"));
+  } catch {
+    return;
   }
+  if (!owner || !Number.isInteger(owner.pid) || owner.pid === process.pid || pidAlive(owner.pid)) return;
+  try {
+    const cur = readFileSync(sessionPath, "utf8");
+    if (typeof owner.key === "string" && owner.key && !cur.includes(owner.key)) return;
+    unlinkSync(sessionPath);
+  } catch {}
 }
 
-function readDaemonJson() {
+function writeSessionOwner(p, key) {
   try {
-    return JSON.parse(readFileSync(daemonJsonPath, "utf8"));
-  } catch {
-    return null;
-  }
+    mkdirSync(p.dataDir, { recursive: true });
+    // Only the first 16 hex chars of the gate key: enough to recognise the file, useless for opening the gate
+    writeFileSync(p.sessionOwner, JSON.stringify({ pid: process.pid, key: key.slice(0, 16) }), { mode: 0o600 });
+  } catch {}
 }
 
-function buildStamp() {
+function removeSession(pageDir, key) {
+  const sessionPath = join(pageDir, "session.js");
   try {
-    return String(statSync(join(here, "daemon", "dist", "main.js")).mtimeMs);
-  } catch {
-    return "0";
-  }
+    // Another host may already have written its own session.js; delete only ours
+    if (readFileSync(sessionPath, "utf8").includes(key)) unlinkSync(sessionPath);
+  } catch {}
 }
 
-async function ensureDaemon(port) {
-  const stamp = buildStamp();
-  // a. 已有 daemon.json 且进程活着：按端口与版本决定复用或重启
-  const info = readDaemonJson();
-  if (info?.pid && pidAlive(info.pid)) {
-    const alive = await ping(info.port ?? port, info.token);
-    if (alive?.ok) {
-      if (info.port === port && alive.version === VERSION && alive.buildStamp === stamp) {
-        return { ok: true, reused: true, port };
+// Synchronous safety net when the host process exits (Magpie never calls stop(); this is the only cleanup that runs on a normal exit).
+// The daemon also exits by itself when stdin closes / the parent disappears; this only speeds it up;
+// on Windows child.kill() is a hard kill that leaves the daemon no time to end the Agent processes it started, so we only close the pipe.
+// Also delete the session.js this host wrote so no stale key is left behind.
+const liveChildren = new Set();
+const liveSessions = new Map(); // pageDir -> key
+let exitHookInstalled = false;
+function installExitHook() {
+  if (exitHookInstalled) return;
+  exitHookInstalled = true;
+  process.once("exit", () => {
+    for (const [pageDir, key] of liveSessions) removeSession(pageDir, key);
+    for (const child of liveChildren) {
+      try {
+        child.stdin?.destroy();
+      } catch {}
+      if (process.platform !== "win32") {
+        try {
+          child.kill("SIGTERM");
+        } catch {}
       }
-      // 版本不同或端口不同：关掉重启
-      await shutdownDaemon(info);
-    } else {
-      // 进程活着但 ping 不通：直接杀（可能是别的进程复用了 pid，taskkill 只杀该 pid 树）
-      await killPid(info.pid);
     }
+  });
+}
+
+function createHost(port) {
+  const p = paths();
+  const log = makeLogger(p);
+  // Gate key: written to session.js; even if leaked it only buys one navigation to the daemon
+  const key = randomBytes(32).toString("hex");
+  // Daemon token: given to the daemon only via an environment variable, and to the page via the 302's # fragment
+  const token = randomBytes(32).toString("hex");
+  let stopped = false;
+  let child = null;
+  let childPort = null;
+  let starting = null;
+  let legacyChecked = false;
+  let wakeBindLoop = null;
+  let beat = null;
+  let bound = false;
+  removeDeadSession(p);
+
+  // From the first page open on, session.js is rewritten every SESSION_BEAT_MS (only while it is still ours), so a page that lost
+  // its connection can tell this live host's file from a dead host's. Before that there is nothing to tell apart: no writes.
+  function startBeat() {
+    if (beat || stopped || !bound) return;
+    const refresh = () => {
+      if (stopped) return;
+      try {
+        const cur = readFileSync(join(p.pageDir, "session.js"), "utf8");
+        if (cur.includes(key)) writeSession(p.pageDir, port, key, true);
+      } catch { /* deleted or unreadable: leave it */ }
+    };
+    refresh();
+    beat = setInterval(refresh, SESSION_BEAT_MS);
+    beat.unref?.();
+  }
+
+  async function checkLegacyOnce() {
+    if (legacyChecked) return;
+    legacyChecked = true;
+    const info = readDaemonInfo(p);
+    if (info && (!child || info.pid !== child.pid)) await shutdownLegacy(info, log);
+  }
+
+  async function spawnDaemon() {
+    await checkLegacyOnce();
+    if (stopped) throw new Error("plugin host stopped");
+    mkdirSync(p.logsDir, { recursive: true });
+    let node;
+    try {
+      // Inside Magpie process.execPath is Bun; the daemon and node-pty need real Node
+      node = requireNode();
+    } catch (error) {
+      log(`cannot spawn daemon: ${error.message} (PATH=${process.env.PATH ?? ""})`);
+      throw error;
+    }
+    log(`spawning daemon with ${node}`);
+    const stderrFd = openSync(p.spawnLog, "a");
+    let spawned;
+    try {
+      spawned = spawn(
+        node,
+        [
+          join(here, "daemon", "dist", "main.js"),
+          "--port",
+          "0",
+          "--data",
+          p.dataRoot,
+          "--parent-pid",
+          String(process.pid),
+        ],
+        {
+          // The token goes through an environment variable, not the command line (command lines are visible to other users on the machine)
+          env: { ...process.env, AGENT_CONSOLE_TOKEN: token },
+          stdio: ["pipe", "pipe", stderrFd],
+          windowsHide: true,
+        },
+      );
+    } finally {
+      closeSync(stderrFd);
+    }
+    child = spawned;
+    childPort = null;
+    liveChildren.add(spawned);
+    installExitHook();
+
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      let stdoutBuffer = "";
+      const finish = (error, port) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        if (error) {
+          // Failed start: clear the state so the next /open starts it again
+          try {
+            spawned.kill();
+          } catch {}
+          if (child === spawned) {
+            child = null;
+            childPort = null;
+          }
+          reject(error);
+        } else {
+          resolve(port);
+        }
+      };
+      const timer = setTimeout(() => finish(new Error("daemon ready timeout")), READY_TIMEOUT_MS);
+
+      // A spawn failure (ENOENT etc.) must not crash the Bun plugin host: log it and fail this /open
+      spawned.on("error", (spawnError) => {
+        log(`spawn error: ${spawnError}`);
+        finish(spawnError);
+      });
+      spawned.stdin.on("error", () => {});
+      // Keep reading stdout into the log so the pipe never fills up; the ready line may span chunks, so buffer and parse by line
+      spawned.stdout.on("data", (chunk) => {
+        const text = String(chunk);
+        try {
+          appendFileSync(p.spawnLog, text);
+        } catch {}
+        stdoutBuffer += text;
+        const lines = stdoutBuffer.split(/\r?\n/);
+        stdoutBuffer = lines.pop() ?? "";
+        for (const line of lines) {
+          let ready;
+          try {
+            ready = JSON.parse(line);
+          } catch {
+            continue;
+          }
+          if (ready?.agentConsoleReady && Number.isInteger(ready.port) && ready.port > 0) {
+            if (child === spawned) childPort = ready.port;
+            finish(null, ready.port);
+          }
+        }
+      });
+      spawned.once("exit", (code, signal) => {
+        log(`daemon pid ${spawned.pid} exited (code ${code}, signal ${signal})`);
+        liveChildren.delete(spawned);
+        if (child === spawned) {
+          child = null;
+          childPort = null;
+        }
+        const error = new Error(`daemon exited before ready (code ${code})`);
+        // The daemon uses exit code 3 for a Node version that's too old
+        if (code === 3) error.userMessage = NODE_TOO_OLD_MESSAGE;
+        finish(error);
+      });
+    });
   }
 
-  // b. 启动新 daemon
-  const child = await startDaemon(port);
-  for (let i = 0; i < 40; i++) {
-    await sleep(250);
-    const info2 = readDaemonJson();
-    if (info2?.token) {
-      const p = await ping(port, info2.token);
-      if (p?.ok) return { ok: true, reused: false, port, pid: info2.pid };
+  // Called on every gate /open: reuse the child if it's alive, start one only if not; concurrent calls share one start
+  async function ensureDaemon() {
+    if (stopped) throw new Error("plugin host stopped");
+    if (child && child.exitCode === null && child.signalCode === null && childPort) {
+      return { port: childPort };
+    }
+    if (!starting) {
+      starting = spawnDaemon().finally(() => {
+        starting = null;
+      });
     }
-    if (child.exitCode !== null) break;
+    return { port: await starting };
+  }
+
+  // The gate calls this only for an /open with the right key
+  const gate = createGate({
+    port, key, token,
+    ensureDaemon: () => {
+      startBeat();
+      return ensureDaemon();
+    },
+  });
+
+  function waitForRetry() {
+    return new Promise((resolve) => {
+      const timer = setTimeout(resolve, BIND_RETRY_MS);
+      wakeBindLoop = () => {
+        clearTimeout(timer);
+        resolve();
+      };
+    });
   }
-  return { ok: false, reason: `daemon 启动超时（端口 ${port}）` };
-}
-
-let ensuring = null;
-function ensure(port) {
-  if (!ensuring) {
-    ensuring = ensureDaemon(port)
-      .then((r) => {
-        if (!r.ok) console.error("[agent-console] daemon 启动失败：" + r.reason);
-        return r;
-      })
-      .catch((e) => {
-        console.error("[agent-console] daemon 启动异常：" + String(e));
-        return { ok: false, reason: String(e) };
-      })
-      .finally(() => {
-        ensuring = null;
+
+  async function bindLoop() {
+    const loggedCodes = new Set();
+    let busyTries = 0;
+    // B16: every `magpie` CLI command starts a short-lived plugin host that calls server() too. Waiting a moment before binding
+    // means such a host usually exits before it takes the gate or writes session.js, and a port held by the long-lived host
+    // (EADDRINUSE) is only logged once it has stayed busy for a while, not once per CLI command.
+    const delay = bindDelayMs();
+    if (delay > 0) {
+      await new Promise((resolve) => {
+        const timer = setTimeout(resolve, delay);
+        wakeBindLoop = () => { clearTimeout(timer); resolve(); };
       });
+    }
+    while (!stopped) {
+      try {
+        await gate.listen();
+      } catch (error) {
+        const code = error?.code || String(error);
+        if (code === "EADDRINUSE") busyTries++;
+        const quiet = code === "EADDRINUSE" && busyTries < BUSY_LOG_AFTER;
+        if (!quiet && !loggedCodes.has(code)) {
+          loggedCodes.add(code);
+          log(`gate port ${port} bind failed (${code}); retrying every ${BIND_RETRY_MS / 1000}s`);
+        }
+        // Port in use: if a detached 0.1.0 daemon is holding it, confirm its identity and shut it down
+        if (code === "EADDRINUSE" && !legacyChecked) {
+          const info = readDaemonInfo(p);
+          if (info?.port === port) await checkLegacyOnce();
+        }
+        if (stopped) return;
+        await waitForRetry();
+        continue;
+      }
+      // stop() may be called while listen is in progress: close immediately and don't write session.js
+      if (stopped) {
+        await gate.close();
+        return;
+      }
+      try {
+        writeSession(p.pageDir, port, key, false);
+        writeSessionOwner(p, key);
+        bound = true;
+        liveSessions.set(p.pageDir, key);
+        installExitHook();
+        log(`gate listening on 127.0.0.1:${port}; session.js written`);
+      } catch (error) {
+        log(`writing session.js failed: ${error}`);
+      }
+      return;
+    }
   }
-  return ensuring;
-}
 
-// 模块加载即确保 daemon（防白屏：带路页跳转前服务就要在）
-const bootPort = envPort();
-void ensure(bootPort);
+  const binding = bindLoop().catch((error) => log(`gate failed: ${error}`));
 
-// magpie OpenCode v1 契约：server(input, options)
-async function server(_input, options) {
-  const port = Number(options?.port || "") || bootPort;
-  if (port !== bootPort) {
-    await ensure(port); // 端口迁移：ensureDaemon 会按 daemon.json 判断重启
+  async function stopDaemon() {
+    const current = child;
+    if (!current) return;
+    // Close the lifeline first so the daemon exits gracefully (ending the Agent processes it started); force-kill after a timeout
+    try {
+      current.stdin.end();
+    } catch {}
+    for (let i = 0; i < 30 && current.exitCode === null && current.signalCode === null; i++) await sleep(100);
+    if (current.exitCode === null && current.signalCode === null && current.pid) {
+      await killPid(current.pid);
+    }
   }
-  return {
-    async stop() {
-      const info = readDaemonJson();
-      if (info?.pid && pidAlive(info.pid)) await shutdownDaemon(info);
-    },
-  };
+
+  async function stop() {
+    stopped = true;
+    if (beat) clearInterval(beat);
+    wakeBindLoop?.();
+    await binding;
+    await gate.close();
+    if (starting) await starting.catch(() => {});
+    await stopDaemon();
+    removeSession(p.pageDir, key);
+    if (liveSessions.get(p.pageDir) === key) liveSessions.delete(p.pageDir);
+  }
+
+  return { stop };
+}
+
+async function server(_input, options) {
+  const requested = Number(options?.port) || Number(process.env.AGENT_CONSOLE_PORT) || DEFAULT_PORT;
+  const port = Number.isInteger(requested) && requested > 0 && requested <= 65535 ? requested : DEFAULT_PORT;
+  return createHost(port);
 }
 
 export default { id: "agent-console", server };