zcode-acp-server 0.30.0 → 0.31.0

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

@@ -83,14 +83,31 @@ export interface HubOptions {
      * dist/cli.js — an interactive TUI in a visible terminal for
      * session-create and session-resume ("tui"; resume carries the requested
      * session in ZCODE_ACP_RESUME_SESSION), a detached headless serve bridge
-     * for background queries ("serve").
+     * for background queries ("serve"). A "tui" attempt returns null when the
+     * launch fails; the caller then walks down the terminal preference list
+     * (terminalLaunches) and only spawns "serve" once every entry failed.
      */
     spawnServe?: (opts: {
         cwd: string;
         env: NodeJS.ProcessEnv;
         /** "tui" = visible terminal (session-create/-resume); "serve" = detached headless. */
         kind: "tui" | "serve";
-    }) => ChildProcess | Promise<ChildProcess>;
+        /** The resolved launch for a "tui" attempt (one list entry). */
+        launch?: TerminalLaunch;
+    }) => ChildProcess | null | Promise<ChildProcess | null>;
+    /**
+     * Override the ordered terminal preference list the create/resume
+     * incubation walks (tests inject fixed entries). Default: resolved LIVE
+     * per incubation from remoteTerminalPrefs (config file > env), so editing
+     * the file takes effect without a hub restart.
+     */
+    terminalLaunches?: TerminalLaunch[];
+    /**
+     * How long after startup the hub ignores newer-bridge stale votes (tests
+     * shrink to 0). Default STALE_VOTE_COOLDOWN_MS — the loop breaker so a
+     * same-age respawn can never be voted into a restart churn.
+     */
+    staleVoteCooldownMs?: number;
 }
 export interface HubHandle {
     port: number;
@@ -149,6 +166,17 @@ export declare function resolveTerminalLaunch(env: NodeJS.ProcessEnv, prefs?: Te
     launch: TerminalLaunch;
     warning?: string;
 };
+/**
+ * The ORDERED terminal preference list (ADR-0016 amendment): the hub walks
+ * it when a window fails — a launch that errors moves down the list at
+ * once, a window that never registers moves down at its registration
+ * timeout — and only the exhaustion of every entry falls back to headless.
+ * Resolution per entry mirrors resolveTerminalLaunch: the explicit command
+ * template (the universal escape hatch) replaces the whole list; otherwise
+ * a built-in launcher by normalized app name, else `open -a` passthrough.
+ * Disabled prefs resolve to [] (no visible-terminal attempts at all).
+ */
+export declare function resolveTerminalLaunches(prefs: TerminalPrefs): TerminalLaunch[];
 /**
  * The .command script body. The incubation env MUST be embedded as exports:
  * the script runs in a fresh shell spawned by the terminal app, which

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

@@ -124,6 +124,13 @@ function validSessions(raw) {
 /** How long POST /api/instances waits for the spawned bridge to register. */
 const SERVE_REGISTER_TIMEOUT_MS = 10_000;
 const SERVE_REGISTER_POLL_MS = 300;
+/**
+ * A freshly started hub ignores newer-bridge stale votes for this long —
+ * the loop breaker for a restart that re-spawned a hub of the same age
+ * (the vote would otherwise fire again immediately; at most one restart
+ * per cooldown window).
+ */
+const STALE_VOTE_COOLDOWN_MS = 60_000;
 /** Register-origin parser: only "serve" is special; anything else is "editor". */
 function parseOrigin(raw) {
     return raw === "serve" ? "serve" : "editor";
@@ -183,17 +190,32 @@ const TERMINAL_APP_LAUNCHERS = {
  * name passes through to `open -a` unchanged.
  */
 export function resolveTerminalLaunch(env, prefs = remoteTerminalPrefs(env)) {
+    const launches = resolveTerminalLaunches(prefs);
+    return { launch: launches[0] ?? { kind: "openApp", app: "Terminal" } };
+}
+/**
+ * The ORDERED terminal preference list (ADR-0016 amendment): the hub walks
+ * it when a window fails — a launch that errors moves down the list at
+ * once, a window that never registers moves down at its registration
+ * timeout — and only the exhaustion of every entry falls back to headless.
+ * Resolution per entry mirrors resolveTerminalLaunch: the explicit command
+ * template (the universal escape hatch) replaces the whole list; otherwise
+ * a built-in launcher by normalized app name, else `open -a` passthrough.
+ * Disabled prefs resolve to [] (no visible-terminal attempts at all).
+ */
+export function resolveTerminalLaunches(prefs) {
+    if (prefs.enabled === false)
+        return [];
     if (prefs.command)
-        return { launch: { kind: "shell", command: prefs.command } };
-    const raw = prefs.app ?? "";
-    const name = raw
-        .toLowerCase()
-        .replace(/\.app$/, "")
-        .replace(/\s+/g, "-");
-    const launcher = TERMINAL_APP_LAUNCHERS[name];
-    if (launcher)
-        return { launch: launcher };
-    return { launch: { kind: "openApp", app: raw || "Terminal" } };
+        return [{ kind: "shell", command: prefs.command }];
+    const names = prefs.terminals?.length ? prefs.terminals : prefs.app ? [prefs.app] : ["Terminal"];
+    return names.map((raw) => {
+        const name = raw
+            .toLowerCase()
+            .replace(/\.app$/, "")
+            .replace(/\s+/g, "-");
+        return TERMINAL_APP_LAUNCHERS[name] ?? { kind: "openApp", app: raw };
+    });
 }
 /**
  * The .command script body. The incubation env MUST be embedded as exports:
@@ -316,30 +338,22 @@ export function writeTuiScript(workspace, cliJs, env) {
 /**
  * Spawn session-create as a VISIBLE interactive TUI (ADR-0016): write a
  * throwaway .command script (`cd <project> && exec node cli.js`) and hand it
- * to a terminal (resolveTerminalLaunch) — the user gets a real terminal
- * window running the local CLI instead of an invisible daemon. The TUI's
- * bridge child inherits the remote ENV, so the incubation registers exactly
- * like a serve bridge; closing the window ends the bridge (its lifetime
- * follows the terminal, the ADR-0001 anchor). Returns null when a terminal
- * can't be used — platform, gated off via ZCODE_ACP_HUB_TERMINAL, or the
- * open failing (headless/SSH) — and the caller falls back to the detached
- * serve spawn.
+ * to ONE resolved terminal launch — the user gets a real terminal window
+ * running the local CLI instead of an invisible daemon. The TUI's bridge
+ * child inherits the remote ENV, so the incubation registers exactly like a
+ * serve bridge; closing the window ends the bridge (its lifetime follows
+ * the terminal, the ADR-0001 anchor). Returns null when the launch fails —
+ * platform without GUI support or the open erroring (pre-1.3 Ghostty,
+ * denied Automation permission) — and the CALLER walks down the terminal
+ * preference list, falling back to the detached serve spawn only after the
+ * list is exhausted.
  */
 async function spawnTerminalTui(opts) {
     if (process.platform !== "darwin")
         return null;
-    // Terminal prefs are read LIVE here (config file first, env fallback): the
-    // hub outlives the shells that configured it, and its birth env rotates
-    // between GUI editors and interactive shells — only the file is stable.
-    // Set remote.terminal.enabled=false in ~/.config/zcode-acp/config.json (or
-    // ZCODE_ACP_HUB_TERMINAL=0) to keep remote session-create headless.
-    if (!remoteTerminalPrefs(process.env).enabled)
-        return null;
     const cliJs = fileURLToPath(new URL("../cli.js", import.meta.url));
     const script = writeTuiScript(opts.cwd, cliJs, opts.env);
-    const { launch, warning } = resolveTerminalLaunch(process.env);
-    if (warning)
-        warn(`hub: ${warning}`);
+    const { launch } = opts;
     let argv;
     if (launch.kind === "shell") {
         const rendered = launch.command.includes("{script}")
@@ -413,11 +427,16 @@ async function spawnTerminalTui(opts) {
  * detached headless serve bridge otherwise (the ADR-0014 original — also the
  * fallback whenever the terminal window can't be opened).
  */
+/**
+ * One spawn attempt. "tui" = one resolved terminal launch (returns null when
+ * the launch fails — the caller walks the preference list); "serve" = the
+ * detached headless bridge (the documented no-GUI fallback, ADR-0014).
+ */
 async function defaultSpawnServe(opts) {
     if (opts.kind === "tui") {
-        const viaTerminal = await spawnTerminalTui(opts);
-        if (viaTerminal)
-            return viaTerminal;
+        if (!opts.launch)
+            return null;
+        return spawnTerminalTui(opts);
     }
     // dist/remote/hub-server.js → dist/cli.js (one level up).
     const cliJs = fileURLToPath(new URL("../cli.js", import.meta.url));
@@ -675,7 +694,7 @@ async function diskCodeIsNewer(paths, startedAt, runningFingerprint) {
  * EADDRINUSE when another hub already owns the port).
  */
 export function startHub(options) {
-    const { port, host, token, heartbeatTimeoutMs = HEARTBEAT_TIMEOUT_MS, idleExitMs = IDLE_EXIT_MS, pingIntervalMs = PING_INTERVAL_MS, tuiRegisterTimeoutMs = TUI_REGISTER_TIMEOUT_MS, onIdleExit, onRestart, codePaths = defaultCodePaths(), projectsDbPath, stayAliveCheck = () => remoteEnabledLive(), spawnServe = defaultSpawnServe, } = options;
+    const { port, host, token, heartbeatTimeoutMs = HEARTBEAT_TIMEOUT_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;
     /** Frozen at hub start — the anchor the /api/upgrade signals compare to. */
     const startedAt = Date.now();
     /**
@@ -790,26 +809,84 @@ export function startHub(options) {
             // (terminals otherwise name the tab after the process, "node").
             env.ZCODE_ACP_TAB_TITLE = tabTitle ?? path.basename(workspacePath);
         }
+        // Terminal preference list (ADR-0016 amendment): visible-terminal kinds
+        // walk it — a failed launch moves down at once, a window that never
+        // registers moves down at its timeout — and only the exhausted list
+        // falls back to the detached headless spawn. "serve" never pops a window.
+        const launches = kind === "serve"
+            ? []
+            : (terminalLaunches ?? resolveTerminalLaunches(remoteTerminalPrefs(process.env)));
+        let li = 0;
+        /**
+         * Try launches[li..] until one OPENS; advance li past every failure and
+         * leave it parked on the first opened attempt's successor. null = the
+         * remaining list failed/exhausted (caller falls back to headless).
+         */
+        const openNextTerminal = async () => {
+            while (li < launches.length) {
+                const attempt = launches[li];
+                li++;
+                try {
+                    const opened = await spawnServe({
+                        cwd: workspacePath,
+                        kind: "tui",
+                        env,
+                        launch: attempt,
+                    });
+                    if (opened) {
+                        opened.once("error", (e) => {
+                            spawnError = e;
+                        });
+                        spawnError = null;
+                        log(`hub: spawned terminal TUI via ${attempt.kind === "shell"
+                            ? "command template"
+                            : attempt.kind === "ghosttyScript"
+                                ? `Ghostty (${attempt.app})`
+                                : attempt.kind === "warpUri"
+                                    ? `Warp (${attempt.app})`
+                                    : `open -a ${attempt.app}`} for ${workspacePath} (pid ${opened.pid})`);
+                        return opened;
+                    }
+                    warn(`hub: terminal launch ${li}/${launches.length} failed to open — trying the next preference`);
+                }
+                catch (e) {
+                    warn(`hub: terminal launch threw: ${e instanceof Error ? e.message : String(e)}`);
+                }
+            }
+            return null;
+        };
         try {
-            // Resume shares session-create's visible-terminal surface (and its
-            // detached-serve fallback for headless machines); only a background
-            // listing spawns the headless form — it must never pop a window.
-            child = await spawnServe({
-                cwd: workspacePath,
-                kind: kind === "serve" ? "serve" : "tui",
-                env,
-            });
-            child.once("error", (e) => {
-                spawnError = e;
-            });
+            const opened = await openNextTerminal();
+            if (opened) {
+                child = opened;
+            }
+            else {
+                // Resume shares session-create's visible-terminal surface (and its
+                // detached-serve fallback for headless machines); only a background
+                // listing spawns the headless form — it must never pop a window.
+                const spawned = await spawnServe({
+                    cwd: workspacePath,
+                    kind: "serve",
+                    env,
+                });
+                if (!spawned)
+                    throw new Error("headless spawn returned null");
+                child = spawned;
+                child.once("error", (e) => {
+                    spawnError = e;
+                });
+            }
         }
         catch (e) {
             warn(`hub: serve spawn failed: ${e instanceof Error ? e.message : String(e)}`);
             throw new Error("serve bridge spawn failed");
         }
-        log(`hub: spawned ${kind === "resume" ? "resume TUI" : kind === "tui" ? "terminal TUI" : "serve bridge"} for ${workspacePath} (pid ${child.pid})`);
+        log(`hub: incubating ${kind === "resume" ? "resume TUI" : kind === "tui" ? "terminal TUI" : "serve bridge"} for ${workspacePath} (pid ${child.pid})`);
         const budget = kind === "serve" ? SERVE_REGISTER_TIMEOUT_MS : tuiRegisterTimeoutMs;
-        const deadline = Date.now() + budget;
+        let deadline = Date.now() + budget;
+        // One headless rescue per incubation — a second timeout means the rescue
+        // bridge also failed to register, and retrying again just burns time.
+        let rescued = false;
         // A visible-terminal incubation (create OR resume) runs NEXT TO the serve
         // bridge the listing already incubated, and several incubations can race
         // for one workspace: the poll matches only a registration that is neither
@@ -851,6 +928,46 @@ export function startHub(options) {
                         return { id: fallback.id, reused: true };
                     }
                 }
+                // Next terminal preference: the window opened but never registered —
+                // on a locked/display-asleep screen Ghostty's AppleScript tab opens
+                // fine but its surface init fails (error.OutOfMemory, ghostty
+                // #10712), leaving the tab dead on its error page (the fake child
+                // never exits, so the fast-fail above can't fire). Walk down the
+                // user's list with a fresh budget before giving up on windows.
+                if (kind !== "serve" && li < launches.length) {
+                    warn(`hub: terminal TUI for ${workspacePath} never registered — trying the next terminal preference`);
+                    const next = await openNextTerminal();
+                    if (next) {
+                        deadline = Date.now() + budget;
+                        continue;
+                    }
+                }
+                // Headless rescue (once, after the terminal list is exhausted):
+                // spawn the SAME incubation headlessly — the session-bind env rides
+                // along (create's pre-generated id, resume's target) and the nonce is
+                // unchanged, so this very loop matches the rescue bridge's
+                // registration and answers with a working session either way.
+                if (kind !== "serve" && !rescued) {
+                    rescued = true;
+                    warn(`hub: ${kind === "resume" ? "resume TUI" : "terminal TUI"} for ${workspacePath} ` +
+                        `never registered — rescuing the request with a headless serve bridge`);
+                    try {
+                        const rescuedChild = await spawnServe({ cwd: workspacePath, kind: "serve", env });
+                        if (!rescuedChild)
+                            throw new Error("rescue spawn returned null");
+                        child = rescuedChild;
+                        child.once("error", (e) => {
+                            spawnError = e;
+                        });
+                        spawnError = null;
+                    }
+                    catch (e) {
+                        warn(`hub: headless rescue spawn failed: ${e instanceof Error ? e.message : String(e)}`);
+                        throw new Error("serve bridge did not register in time");
+                    }
+                    deadline = Date.now() + budget;
+                    continue;
+                }
                 warn(`hub: serve bridge for ${workspacePath} never registered`);
                 throw new Error("serve bridge did not register in time");
             }
@@ -1490,34 +1607,33 @@ export function startHub(options) {
                 instances.delete(id);
                 idleSince = null; // re-arm the idle clock on membership change
             }
-            // Self-upgrade: a bridge running DIFFERENT code than this hub just
-            // registered, so this process is stale. Reply first (the bridge
-            // re-spawns the hub from its own dist when it sees `restarting`), then
-            // exit. Fingerprints are compared when both sides have one — content
-            // cannot lie the way a version frozen from package.json can (a hub
-            // born between a release merge and the dist rebuild). The lexical
-            // tie-break (bridge fp must sort HIGHER) gives coexisting dists on one
-            // machine a stable winner, so two differently-built bridges can never
-            // ping-pong the hub. Bridges without a fingerprint fall back to the
-            // legacy strictly-newer version check.
-            const bridgeFingerprint = typeof body.codeFingerprint === "string" && body.codeFingerprint
-                ? body.codeFingerprint
-                : null;
-            const fingerprintStale = bridgeFingerprint !== null &&
-                hubFingerprint !== null &&
-                bridgeFingerprint !== hubFingerprint &&
-                bridgeFingerprint > hubFingerprint;
-            const versionStale = bridgeFingerprint === null &&
-                hubFingerprint === null &&
-                typeof body.version === "string" &&
-                compareVersions(body.version, AGENT_INFO.version) > 0;
-            const stale = url.pathname === "/api/register" && (fingerprintStale || versionStale);
+            // Self-upgrade: a bridge with a strictly NEWER VERSION just registered,
+            // so this process is stale. Reply first (the bridge re-spawns the hub
+            // from its own dist when it sees `restarting`), then exit.
+            //
+            // Content fingerprints are deliberately NOT a vote signal: a hash has
+            // no ordering (a lexically-higher fingerprint can be OLDER code), and
+            // the hub's respawn source is not guaranteed to be the voting bridge's
+            // dist — differing fingerprints could only ever produce a
+            // non-converging restart loop (observed live: a coexisting dist voted
+            // every respawned hub stale, ~5s churn, all instances wiped).
+            // Fingerprint comparison belongs to /api/upgrade ONLY, where the
+            // comparison target is the DISK a respawn would load — self-negating
+            // by construction.
+            //
+            // Cooldown: a fresh hub ignores stale votes for the first minute. If
+            // the respawn race ever produces another same-age hub, this breaks the
+            // loop — at most one restart per STALE_VOTE_COOLDOWN_MS.
+            const newerVersion = typeof body.version === "string" && compareVersions(body.version, AGENT_INFO.version) > 0;
+            const cooledDown = Date.now() - startedAt > staleVoteCooldownMs;
+            const stale = url.pathname === "/api/register" && newerVersion && cooledDown;
             res.writeHead(200, { "Content-Type": "application/json" });
             res.end(JSON.stringify(stale ? { ok: true, restarting: true } : { ok: true }));
             if (stale) {
-                restartSoon(fingerprintStale
-                    ? `hub: bridge fingerprint ${bridgeFingerprint.slice(0, 12)} differs from hub ${hubFingerprint.slice(0, 12)} — restarting to upgrade`
-                    : `hub: bridge ${body.version} is newer than hub ${AGENT_INFO.version} — restarting to upgrade`);
+                restartSoon(`hub: bridge ${body.version} is newer than hub ${AGENT_INFO.version} — restarting to upgrade`);
+            }
+            else if (url.pathname === "/api/register" && newerVersion && !cooledDown) {
+                log("hub: newer-bridge vote ignored (restart cooldown after a recent restart)");
             }
             return;
         }