zcode-acp-server 0.74.0 → 0.76.0

package/dist/remote/hub-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hub-server.d.ts","sourceRoot":"","sources":["../../src/remote/hub-server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"hub-server.d.ts","sourceRoot":"","sources":["../../src/remote/hub-server.ts"],"names":[],"mappings":"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"}

package/dist/remote/hub-server.js

@@ -77,6 +77,19 @@ const PROBE_TIMEOUT_MS = 2_000;
  */
 const PROBE_GRACE_MS = 8_000;
 const MAX_BODY_BYTES = 1024 * 1024;
+/**
+ * Desktop Presence by recent request (amendment to ADR-0016): the desktop app
+ * polls GET /api/instances every 15s for its whole lifetime (DISCOVERY_REFRESH_MS
+ * in the app's runtime.rs), every call stamped with DESKTOP_CLIENT_HEADER. That
+ * poll is the one presence signal an IDLE desktop still emits: connection
+ * presence (`desktopPairs`) ends with the last proxied ACP connection, and a
+ * serve bridge self-exits once its last session closes — so a running desktop
+ * app with no open tab was invisible, and the next phone-originated
+ * create/resume opened a terminal window next to it. Three poll intervals of
+ * slack: the app schedules each poll AFTER the previous answer lands, so a
+ * slow hub stretches the gap past 15s.
+ */
+const DESKTOP_PRESENCE_TTL_MS = 45_000;
 /** Constant-time token compare (hash both to equal length first). */
 function tokenEquals(a, b) {
     const ha = createHash("sha256").update(a).digest();
@@ -924,12 +937,29 @@ export function initializeClientName(data) {
     const info = params?.clientInfo;
     return typeof info?.name === "string" ? info.name : "";
 }
+/**
+ * Desktop Presence request identity (amendment to ADR-0016): the desktop
+ * client stamps every hub HTTP call with its clientInfo name. Connection
+ * presence (`desktopPairs`) needs a proxied ACP connection to a bridge, so a
+ * cold hub (instances: 0, nothing to connect to) would open a terminal for
+ * the very FIRST session create — the request itself is the one presence
+ * signal that always exists. Every authorized stamped call also refreshes the
+ * recent-request presence (DESKTOP_PRESENCE_TTL_MS), which is what keeps an
+ * idle desktop — no open tab, no proxied connection — visible to the hub.
+ */
+const DESKTOP_CLIENT_HEADER = "x-zcode-client";
+function requestIsDesktopClient(req) {
+    const value = req.headers[DESKTOP_CLIENT_HEADER];
+    if (typeof value === "string")
+        return value === DESKTOP_CLIENT_NAME;
+    return Array.isArray(value) && value.includes(DESKTOP_CLIENT_NAME);
+}
 /**
  * Start the hub. Resolves once listening; rejects on bind failure (including
  * EADDRINUSE when another hub already owns the port).
  */
 export function startHub(options) {
-    const { port, host, token, webDir, heartbeatTimeoutMs = HEARTBEAT_TIMEOUT_MS, probeGraceMs = PROBE_GRACE_MS, idleExitMs = IDLE_EXIT_MS, pingIntervalMs = PING_INTERVAL_MS, tuiRegisterTimeoutMs = TUI_REGISTER_TIMEOUT_MS, onIdleExit, onRestart, codePaths = defaultCodePaths(), projectsDbPath, stayAliveCheck = () => remoteEnabledLive(), spawnServe = defaultSpawnServe, terminalLaunches, staleVoteCooldownMs = STALE_VOTE_COOLDOWN_MS, } = options;
+    const { port, host, token, webDir, heartbeatTimeoutMs = HEARTBEAT_TIMEOUT_MS, probeGraceMs = PROBE_GRACE_MS, idleExitMs = IDLE_EXIT_MS, pingIntervalMs = PING_INTERVAL_MS, tuiRegisterTimeoutMs = TUI_REGISTER_TIMEOUT_MS, desktopPresenceTtlMs = DESKTOP_PRESENCE_TTL_MS, onIdleExit, onRestart, codePaths = defaultCodePaths(), projectsDbPath, stayAliveCheck = () => remoteEnabledLive(), spawnServe = defaultSpawnServe, terminalLaunches, staleVoteCooldownMs = STALE_VOTE_COOLDOWN_MS, } = options;
     /** Frozen at hub start — the anchor the /api/upgrade signals compare to. */
     const startedAt = Date.now();
     /**
@@ -957,6 +987,27 @@ export function startHub(options) {
      * creates. Sessions that already have a window are never touched.
      */
     const desktopPairs = new Set();
+    /**
+     * Desktop Presence by recent request: when the last AUTHORIZED call stamped
+     * with the desktop identity landed (0 = never). Refreshed by handleHttp for
+     * every route — the 15s discovery poll is the steady source, but any
+     * stamped call counts.
+     */
+    let desktopSeenAt = 0;
+    /**
+     * The one incubation-time presence verdict (amendment to ADR-0016). Checked
+     * at the endpoint, once per request — a desktop client dropping mid-flight
+     * never opens a window retroactively.
+     */
+    const desktopPresence = (req) => {
+        if (desktopPairs.size > 0)
+            return "connection";
+        if (requestIsDesktopClient(req))
+            return "request";
+        if (desktopSeenAt > 0 && Date.now() - desktopSeenAt < desktopPresenceTtlMs)
+            return "recent";
+        return null;
+    };
     const timers = [];
     /**
      * Single-flight incubation per workspace (remote session-create,
@@ -990,7 +1041,7 @@ export function startHub(options) {
      * requested session (ADR-0017), "serve" the detached headless bridge
      * (background listing, ADR-0015).
      */
-    const incubateServe = async (workspacePath, kind, sessionId, tabTitle) => {
+    const incubateServe = async (workspacePath, kind, sessionId, tabTitle, desktop = null) => {
         // Async spawn failures (ENOENT — the dir vanished between the whitelist
         // check and the spawn) arrive as an 'error' event with exitCode still
         // null; without this flag the poll burns the full budget.
@@ -1082,20 +1133,23 @@ export function startHub(options) {
             // never churns when the bridge takes over the script's initial printf.
             env.ZCODE_ACP_TAB_TITLE = sessionTabTitle(tabTitle, workspacePath);
         }
-        // Desktop Presence (amendment to ADR-0016): while a desktop client is
-        // connected, session-create takes the headless serve form — the desktop
-        // app is the presenting surface, so a terminal window would re-render the
-        // same stream for nobody. Equivalent to the exhausted-terminal-list
-        // fallback: the launch list is empty, so openNextTerminal yields to the
-        // detached serve spawn at once. Checked once, here, at session-creation
-        // time (a desktop client dropping mid-flight never opens a window
-        // retroactively). Resume keeps its window (ADR-0017) and the listing was
-        // already headless; `ZCODE_ACP_HUB_TERMINAL=0` stays the static variant.
-        const desktopPresent = kind === "tui" && desktopPairs.size > 0;
+        // Desktop Presence (amendment to ADR-0016): while the desktop app is
+        // present — a proxied connection, the request's own identity header, or a
+        // stamped call within the presence TTL (see desktopPresence) —
+        // session-create AND resume incubate in the headless serve form: the
+        // desktop app is the presenting surface, so a terminal window would
+        // re-render the same stream for nobody (a resume's window was ADR-0017's
+        // mobile surface; a desktop-originated resume loads the session itself
+        // after attach). Equivalent to the exhausted-terminal-list fallback: the
+        // launch list is empty, so openNextTerminal yields to the detached serve
+        // spawn at once. The verdict was taken at the endpoint, once per request.
+        // The listing was already headless; `ZCODE_ACP_HUB_TERMINAL=0` stays the
+        // static variant.
+        const desktopPresent = (kind === "tui" || kind === "resume") && desktop !== null;
         if (desktopPresent) {
             // warn (not log): the daemon's stderr is null in production, so the
             // diary is the only place this state change is observable.
-            warn(`hub: desktop client connected — incubating ${workspacePath} headless (Desktop Presence)`);
+            warn(`hub: desktop app present (${desktop}) — incubating ${workspacePath} headless (Desktop Presence)`);
         }
         // Terminal preference list (ADR-0016 amendment): visible-terminal kinds
         // walk it — a failed launch moves down at once, a window that never
@@ -1272,14 +1326,14 @@ export function startHub(options) {
      * key carries the session id, so resumes of different sessions each get
      * their own window.
      */
-    const joinIncubation = (workspacePath, kind, sessionId, tabTitle) => {
+    const joinIncubation = (workspacePath, kind, sessionId, tabTitle, desktop = null) => {
         const mapKey = kind === "resume" ? `${workspacePath}\u0000resume\u0000${sessionId ?? ""}` : workspacePath;
         const inflight = serveIncubations.get(mapKey);
         if (inflight && (inflight.kind === kind || kind === "serve")) {
             log(`hub: joining the incubating serve bridge for ${workspacePath}`);
             return inflight.promise;
         }
-        const promise = incubateServe(workspacePath, kind, sessionId, tabTitle);
+        const promise = incubateServe(workspacePath, kind, sessionId, tabTitle, desktop);
         serveIncubations.set(mapKey, { kind, promise });
         // Drop the entry once settled (identity-checked — a newer incubation may
         // already have replaced it). The catch keeps the DERIVED promise handled;
@@ -1405,15 +1459,34 @@ export function startHub(options) {
         };
         socket.once("close", onClientGone);
         socket.once("error", onClientGone);
-        bridge.once("open", () => {
-            if (clientGone)
-                return; // terminated above; "open" can no longer fire
+        // Dial-phase guard: exactly one of open/fail settles the upgrade. The
+        // error path must stay attached AFTER the first emission (Bun's
+        // WebSocket reports one failed connect through two dispatch paths —
+        // once via the listener, once as an unhandled 'error' — observed live
+        // 2026-10-20: a corpse dial logged the warn AND threw an uncaught
+        // ErrorEvent), and must never fire into an upgraded socket.
+        let settled = false;
+        bridge.on("open", () => {
+            if (settled || clientGone)
+                return; // terminated above; "open" is moot
+            settled = true;
             socket.removeListener("close", onClientGone);
             socket.removeListener("error", onClientGone);
             wss.handleUpgrade(req, socket, head, (client) => startProxy(client, bridge));
         });
-        bridge.once("error", (e) => {
+        bridge.on("error", (e) => {
+            if (settled)
+                return;
+            settled = true;
             warn(`hub: dial bridge :${entry.port} failed: ${e.message}`);
+            // ECONNREFUSED on loopback means nothing is bound — the bridge process
+            // is gone (a busy-but-alive bridge's OS backlog still accepts). Prune
+            // now so the next client attempt reads "unknown instance" and falls
+            // back to re-incubation, instead of dialing a corpse until the
+            // heartbeat TTL expires. A wrong prune self-heals on the bridge's next
+            // heartbeat.
+            instances.delete(entry.id);
+            idleSince = null; // re-arm the idle clock on membership change
             rejectUpgrade(socket, 502, "Bridge Unreachable");
         });
     });
@@ -1430,6 +1503,13 @@ export function startHub(options) {
             res.end("ok");
             return;
         }
+        // Desktop Presence by recent request: every AUTHORIZED call the desktop
+        // client stamped refreshes the TTL (the 15s discovery poll in practice).
+        // Authorization first — a bare header must never suppress windows. The
+        // routes re-check authorization themselves; this extra compare only runs
+        // for stamped requests.
+        if (requestIsDesktopClient(req) && authorized(req, url, token))
+            desktopSeenAt = Date.now();
         if (url.pathname === "/api/instances" && req.method === "GET") {
             if (!authorized(req, url, token)) {
                 res.writeHead(401, { "Content-Type": "text/plain" });
@@ -1813,6 +1893,9 @@ export function startHub(options) {
         // reuses a live serve bridge: the App flow always runs the history
         // listing first, which incubates a headless serve instance, and reuse
         // would mean the window can never open (the pre-amendment behaviour).
+        // Desktop Presence inverts both rules (see desktopPresence below): no
+        // window is coming, so the workspace's live serve bridge hosts the session
+        // too, and only a workspace without one spawns — headless.
         // The hub waits for the bridge's heartbeat registration; the bridge lives
         // its own life afterwards (a terminal TUI until the window closes, a
         // serve bridge on its idle timer). Concurrent identical POSTs join one
@@ -1866,6 +1949,35 @@ export function startHub(options) {
                 res.end("session deleted");
                 return;
             }
+            // Desktop Presence (amendment to ADR-0016): the desktop app is the
+            // presenting surface, so no window opens — and with no window to be the
+            // feature, the pre-amendment reuse is right again: the workspace's live
+            // serve bridge (the listing's, an earlier create's, an open window's)
+            // hosts this session too. The client attaches and session/new-s or
+            // session/loads there, exactly as it already does after a headless
+            // rescue — one bridge and one backend process per project instead of
+            // one per session. A resume prefers the bridge that holds the session
+            // LIVE (any origin): two bridges must never load one conversation. Only
+            // a workspace with no live serve bridge still spawns, headless. An
+            // unhealthy-marked bridge is skipped (a dead one would fail the dial
+            // and only be pruned afterwards); a stalled-but-alive one costs a
+            // duplicate, the status quo before this reuse.
+            const desktop = desktopPresence(req);
+            if (desktop) {
+                const holder = resumeSid
+                    ? Array.from(instances.values()).find((e) => e.sessions.some((s) => s.sessionId === resumeSid))
+                    : undefined;
+                const live = holder ?? findServeInstances(workspacePath).find((e) => e.unhealthySince === undefined);
+                if (live) {
+                    // warn (not log): the diary is the only place this decision is
+                    // observable on the detached daemon (the phone's create that
+                    // deliberately did NOT open a window).
+                    warn(`hub: desktop app present (${desktop}) — ${resumeSid ? `resume ${resumeSid.slice(0, 8)}` : "create"} for ${workspacePath} reuses ${live.origin} bridge ${live.id}`);
+                    res.writeHead(200, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({ id: live.id, reused: true }));
+                    return;
+                }
+            }
             if (resumeSid) {
                 // Tab title, best-effort: the App browsed this conversation through
                 // the serve bridge's /sessions history, which is normally still live
@@ -1881,12 +1993,15 @@ export function startHub(options) {
                     tabTitle = sanitizeTabTitle(row?.title);
                 }
                 // Resume never reuses the live serve bridge: the window IS the
-                // feature, and the answer must be the NEW instance so the attaching
-                // client and the terminal share one bridge (and one backend process)
-                // for the session. A bogus id still opens the window — the TUI
-                // shows the load failure and falls back to a fresh session, the same
-                // honesty as a window that dies early (ADR-0016 §4).
-                const incubation = joinIncubation(workspacePath, "resume", resumeSid, tabTitle);
+                // feature for MOBILE-originated resumes (the attaching client and the
+                // terminal share one bridge and one backend process for the session;
+                // ADR-0017). Under Desktop Presence the reuse above already answered
+                // when a live bridge existed; what reaches here incubates headless
+                // (the client loads the session itself after attach). A bogus id
+                // still gets its honest spawn — the surface shows the load failure
+                // and falls back to a fresh session, the same honesty as a window
+                // that dies early (ADR-0016 §4).
+                const incubation = joinIncubation(workspacePath, "resume", resumeSid, tabTitle, desktop);
                 try {
                     const out = await incubation;
                     res.writeHead(200, { "Content-Type": "application/json" });
@@ -1899,15 +2014,18 @@ export function startHub(options) {
                 return;
             }
             // Session-create ALWAYS incubates a VISIBLE terminal TUI (ADR-0016 as
-            // amended): the App flow lists the project's history first, which
-            // incubates a headless serve bridge — reusing that instance (the
-            // original behaviour) meant a window could NEVER open once the project
-            // was browsed, and every create ran invisibly in the background. The
-            // answer is the NEW window's instance; concurrent identical POSTs join
-            // one incubation, and the detached headless serve spawn remains the
-            // fallback (no GUI / gated off / open failure). Clients that want a
-            // headless attach use the listing's instance id instead of this POST.
-            const incubation = joinIncubation(workspacePath, "tui");
+            // amended) — UNLESS Desktop Presence applies (see desktopPresence; a
+            // workspace with a live bridge was already answered above, so what
+            // reaches here under presence spawns headless). The App flow lists the
+            // project's history first, which incubates a headless serve bridge —
+            // reusing that instance (the original behaviour) meant a window could
+            // NEVER open once the project was browsed, and every create ran
+            // invisibly in the background. The answer is the NEW spawn's instance;
+            // concurrent identical POSTs join one incubation, and the detached
+            // headless serve spawn remains the fallback (no GUI / gated off / open
+            // failure). Clients that want a headless attach use the listing's
+            // instance id instead of this POST.
+            const incubation = joinIncubation(workspacePath, "tui", undefined, undefined, desktop);
             try {
                 const out = await incubation;
                 res.writeHead(200, { "Content-Type": "application/json" });