zcode-acp-server 0.22.0 → 0.24.0

package/dist/remote/config.js

@@ -1,31 +1,37 @@
 /**
- * Remote access configuration from environment variables.
+ * Remote access configuration: user config file first, env fallback.
  *
- * Remote access is opt-in via ZCODE_ACP_REMOTE=1 and REQUIRES a token — the
- * endpoint is expected to sit behind a public tunnel (Cloudflare Tunnel, frp),
- * so "loopback-only" is never a safe assumption here. A missing token disables
- * the feature with a warning instead of failing the bridge: the stdio link to
- * the editor must keep working no matter what.
+ * Remote access is opt-in and REQUIRES a token — the endpoint is expected to
+ * sit behind a public tunnel (Cloudflare Tunnel, frp), so "loopback-only" is
+ * never a safe assumption here. A missing token disables the feature with a
+ * warning instead of failing the bridge: the stdio link to the editor must
+ * keep working no matter what.
  *
- * Variables:
- *   ZCODE_ACP_REMOTE=1            enable the remote endpoint (gate)
- *   ZCODE_ACP_REMOTE_TOKEN=<s>    auth token (mandatory when enabled)
- *   ZCODE_ACP_HUB_PORT=8377       hub's fixed port (the one a tunnel maps)
- *   ZCODE_ACP_HUB_HOST=127.0.0.1  hub bind address (e.g. 0.0.0.0 for a
- *                                 containerized tunnel agent)
- *   ZCODE_ACP_REMOTE_PORT=8378    bridge endpoint start port (auto-increment
- *                                 when taken; loopback only)
- *   ZCODE_ACP_REMOTE_ORIGIN=serve registration origin override (ADR-0016: a
- *                                 REPL incubated by the hub in a visible
- *                                 terminal registers as "serve" so the
- *                                 per-workspace dedupe treats it as THE
- *                                 project's remote bridge)
- *   ZCODE_ACP_REMOTE_PIN_CWD=1    pin every session root to the process cwd
- *                                 (bridge-wide serveMode; ADR-0016: keeps
- *                                 ADR-0014's whitelist semantics for a
- *                                 hub-incubated REPL, whose bridge would
- *                                 otherwise trust a remote client's cwd)
+ * Sources, in priority order (per field):
+ *   1. ~/.config/zcode-acp/config.json `remote` section (XDG_CONFIG_HOME
+ *      aware) — the authoritative, launch-context-independent source. The
+ *      hub daemon is idle-exited and re-spawned by arbitrary bridges, so its
+ *      birth env rotates; user preference must not.
+ *   2. Environment variables (unchanged semantics — setups without a file
+ *      keep working, and env fills any field the file leaves unset):
+ *     ZCODE_ACP_REMOTE=1            enable the remote endpoint (gate)
+ *     ZCODE_ACP_REMOTE_TOKEN=<s>    auth token (mandatory when enabled)
+ *     ZCODE_ACP_HUB_PORT=8377       hub's fixed port (the one a tunnel maps)
+ *     ZCODE_ACP_HUB_HOST=127.0.0.1  hub bind address (e.g. 0.0.0.0 for a
+ *                                   containerized tunnel agent)
+ *     ZCODE_ACP_REMOTE_PORT=8378    bridge endpoint start port (auto-increment
+ *                                   when taken; loopback only)
+ *     ZCODE_ACP_HUB_TERMINAL=0      disable the visible-terminal incubation
+ *     ZCODE_ACP_HUB_TERMINAL_APP=<name>   terminal app for the TUI window
+ *     ZCODE_ACP_HUB_TERMINAL_COMMAND=<sh> shell command template ({script})
+ *   3. Built-in defaults.
+ *
+ * Process-role plumbing stays env-only by design (never file-configurable):
+ *   ZCODE_ACP_REMOTE_ORIGIN=serve  registration origin override (ADR-0016)
+ *   ZCODE_ACP_REMOTE_PIN_CWD=1     pin session roots to the process cwd
+ *   ZCODE_ACP_RESUME_SESSION=<id>  per-request boot-resume target (ADR-0017)
  */
+import { loadUserConfig } from "../config/user-config.js";
 import { warn } from "../utils.js";
 export const DEFAULT_HUB_PORT = 8377;
 export const DEFAULT_BRIDGE_PORT = 8378;
@@ -40,40 +46,68 @@ function parsePort(raw, fallback, envName) {
     }
     return port;
 }
+/** Shared file>env merge for token/ports/host (already validated by the loader). */
+function mergeCommon(env) {
+    const file = loadUserConfig(env).remote ?? {};
+    return {
+        token: file.token ?? (env.ZCODE_ACP_REMOTE_TOKEN ?? "").trim(),
+        hubPort: file.hubPort ?? parsePort(env.ZCODE_ACP_HUB_PORT, DEFAULT_HUB_PORT, "ZCODE_ACP_HUB_PORT"),
+        hubHost: file.hubHost ?? ((env.ZCODE_ACP_HUB_HOST ?? "").trim() || DEFAULT_HUB_HOST),
+        bridgePort: file.bridgePort ??
+            parsePort(env.ZCODE_ACP_REMOTE_PORT, DEFAULT_BRIDGE_PORT, "ZCODE_ACP_REMOTE_PORT"),
+    };
+}
 /** Parse remote config; null = disabled (or misconfigured → warned). */
 export function parseRemoteConfig(env = process.env) {
-    const gate = (env.ZCODE_ACP_REMOTE ?? "").trim().toLowerCase();
-    if (!["1", "true", "yes", "on"].includes(gate))
+    const file = loadUserConfig(env).remote ?? {};
+    // Gate: the file is authoritative when it says anything; env decides only
+    // when the file is silent (an explicit `enabled: false` wins over env =1).
+    const enabled = file.enabled !== undefined
+        ? file.enabled
+        : ["1", "true", "yes", "on"].includes((env.ZCODE_ACP_REMOTE ?? "").trim().toLowerCase());
+    if (!enabled)
         return null;
-    const token = (env.ZCODE_ACP_REMOTE_TOKEN ?? "").trim();
+    const { token, hubPort, hubHost, bridgePort } = mergeCommon(env);
     if (!token) {
-        warn("remote: ZCODE_ACP_REMOTE is enabled but ZCODE_ACP_REMOTE_TOKEN is missing — " +
+        warn("remote: enabled but no token (config file or ZCODE_ACP_REMOTE_TOKEN) — " +
             "remote access disabled (stdio unaffected)");
         return null;
     }
     return {
         token,
-        hubPort: parsePort(env.ZCODE_ACP_HUB_PORT, DEFAULT_HUB_PORT, "ZCODE_ACP_HUB_PORT"),
-        hubHost: (env.ZCODE_ACP_HUB_HOST ?? "").trim() || DEFAULT_HUB_HOST,
-        bridgePort: parsePort(env.ZCODE_ACP_REMOTE_PORT, DEFAULT_BRIDGE_PORT, "ZCODE_ACP_REMOTE_PORT"),
+        hubPort,
+        hubHost,
+        bridgePort,
         origin: (env.ZCODE_ACP_REMOTE_ORIGIN ?? "").trim() === "serve" ? "serve" : "editor",
         pinCwd: (env.ZCODE_ACP_REMOTE_PIN_CWD ?? "").trim() === "1",
     };
 }
 /** Parse hub-side config for the standalone hub entry (`zcode-acp hub`). */
 export function parseHubConfig(env = process.env) {
-    const token = (env.ZCODE_ACP_REMOTE_TOKEN ?? "").trim();
+    const { token, hubPort, hubHost, bridgePort } = mergeCommon(env);
     if (!token) {
-        warn("hub: ZCODE_ACP_REMOTE_TOKEN is required — refusing to start without auth");
+        warn("hub: no token (config file or ZCODE_ACP_REMOTE_TOKEN) — refusing to start without auth");
         return null;
     }
     return {
         token,
-        hubPort: parsePort(env.ZCODE_ACP_HUB_PORT, DEFAULT_HUB_PORT, "ZCODE_ACP_HUB_PORT"),
-        hubHost: (env.ZCODE_ACP_HUB_HOST ?? "").trim() || DEFAULT_HUB_HOST,
-        bridgePort: parsePort(env.ZCODE_ACP_REMOTE_PORT, DEFAULT_BRIDGE_PORT, "ZCODE_ACP_REMOTE_PORT"),
+        hubPort,
+        hubHost,
+        bridgePort,
         origin: "editor",
         pinCwd: false,
     };
 }
+/**
+ * Terminal incubation preferences for the hub (ADR-0016), merged file > env.
+ * Read LIVE by the hub at every incubation so editing the file takes effect
+ * without a hub restart — the hub outlives the shells that configured it.
+ */
+export function remoteTerminalPrefs(env = process.env) {
+    const file = loadUserConfig(env).remote?.terminal ?? {};
+    const app = file.app ?? ((env.ZCODE_ACP_HUB_TERMINAL_APP ?? "").trim() || undefined);
+    const command = file.command ?? ((env.ZCODE_ACP_HUB_TERMINAL_COMMAND ?? "").trim() || undefined);
+    const enabled = file.enabled ?? !["0", "false", "off"].includes((env.ZCODE_ACP_HUB_TERMINAL ?? "").trim().toLowerCase());
+    return { enabled, ...(app ? { app } : {}), ...(command ? { command } : {}) };
+}
 //# sourceMappingURL=config.js.map

package/dist/remote/config.js.map

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

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

@@ -23,6 +23,7 @@
  * next bridge re-spawns it on demand.
  */
 import { type ChildProcess } from "node:child_process";
+import type { TerminalPrefs } from "../config/user-config.js";
 export interface HubOptions {
     port: number;
     host: string;
@@ -93,17 +94,27 @@ export type TerminalLaunch =
     kind: "openAppArgs";
     app: string;
     args: string[];
+}
+/** Warp: refuses `.command` files and its CLI is agent-only, but its URI
+ * scheme EXECUTES a script handed to action/new_tab's path param
+ * (app/src/uri/mod.rs → open_file; verified on 0.2026.09.02): the hub opens
+ * `<scheme>://action/new_tab?path=<script>` and Warp runs it as a new tab
+ * in its default mode. Preview uses the warppreview:// scheme. */
+ | {
+    kind: "warpUri";
+    app: string;
+    scheme: string;
 };
 /**
- * Pick how to open the TUI script. The hub is a background daemon — its env
- * carries no terminal and macOS has no default-terminal setting — so nothing
- * is detected. Priority: the explicit command template (the universal escape
- * hatch) → a built-in launcher by app name (aliases are case- and
- * `.app`-suffix-insensitive) → plain Terminal.app. Warp gets a special warning
- * because it accepts the open but cannot run the script; any other unmatched
+ * Pick how to open the TUI script. Preferences arrive pre-merged from
+ * `remoteTerminalPrefs` (config file first, env fallback — see config.ts);
+ * only the app-name normalization lives here. Priority: the explicit command
+ * template (the universal escape hatch) → a built-in launcher by app name
+ * (aliases are case- and `.app`-suffix-insensitive) → plain Terminal.app
+ * (macOS has no default-terminal setting to detect). Any other unmatched
  * name passes through to `open -a` unchanged.
  */
-export declare function resolveTerminalLaunch(env: NodeJS.ProcessEnv): {
+export declare function resolveTerminalLaunch(env: NodeJS.ProcessEnv, prefs?: TerminalPrefs): {
     launch: TerminalLaunch;
     warning?: string;
 };
@@ -118,6 +129,14 @@ export declare function resolveTerminalLaunch(env: NodeJS.ProcessEnv): {
 export declare function terminalTuiScript(cwd: string, cliJs: string, env: NodeJS.ProcessEnv): string;
 /** Reset the quota cache (test helper). */
 export declare function resetQuotaCacheForTest(): void;
+/**
+ * Tab-title sanitizer: the value is printf'd into the terminal as an OSC
+ * payload, so control characters (an ESC inside a model-generated summary
+ * would inject terminal sequences) become spaces, whitespace collapses, and
+ * the length caps at what a tab can usefully show. Empty/non-string →
+ * undefined (the caller falls back to the project name).
+ */
+export declare function sanitizeTabTitle(v: unknown): string | undefined;
 /**
  * Start the hub. Resolves once listening; rejects on bind failure (including
  * EADDRINUSE when another hub already owns the port).

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":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAS,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AA2B9D,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,kFAAkF;IAClF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gFAAgF;IAChF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB;;;;OAIG;IACH,SAAS,CAAC,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACrD;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE;QAClB,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;QACvB,sFAAsF;QACtF,IAAI,EAAE,KAAK,GAAG,OAAO,CAAC;KACvB,KAAK,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAwID,sEAAsE;AACtE,MAAM,MAAM,cAAc;AACxB;uEACuE;AACrE;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE;AACpC,6EAA6E;GAC3E;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE;AAClC;kEACkE;GAChE;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AA0BzD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG;IAC7D,MAAM,EAAE,cAAc,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAkBA;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CAY5F;AAgJD,2CAA2C;AAC3C,wBAAgB,sBAAsB,IAAI,IAAI,CAG7C;AA4JD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,UAAU,GAAG;IAAE,UAAU,CAAC,EAAE,MAAM,IAAI,CAAA;CAAE,GAAG,OAAO,CAAC,SAAS,CAAC,CAw0B9F"}
+{"version":3,"file":"hub-server.d.ts","sourceRoot":"","sources":["../../src/remote/hub-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAS,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAwB9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAM9D,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,kFAAkF;IAClF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gFAAgF;IAChF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB;;;;OAIG;IACH,SAAS,CAAC,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACrD;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE;QAClB,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;QACvB,sFAAsF;QACtF,IAAI,EAAE,KAAK,GAAG,OAAO,CAAC;KACvB,KAAK,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAsID,sEAAsE;AACtE,MAAM,MAAM,cAAc;AACxB;uEACuE;AACrE;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE;AACpC,6EAA6E;GAC3E;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE;AAClC;kEACkE;GAChE;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE;AACtD;;;;kEAIkE;GAChE;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AA2BrD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,MAAM,CAAC,UAAU,EACtB,KAAK,GAAE,aAAwC,GAC9C;IACD,MAAM,EAAE,cAAc,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAUA;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CAqB5F;AA6JD,2CAA2C;AAC3C,wBAAgB,sBAAsB,IAAI,IAAI,CAG7C;AAmCD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAQ/D;AAyID;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,UAAU,GAAG;IAAE,UAAU,CAAC,EAAE,MAAM,IAAI,CAAA;CAAE,GAAG,OAAO,CAAC,SAAS,CAAC,CA22B9F"}

package/dist/remote/hub-server.js

@@ -35,7 +35,9 @@ import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { WebSocket, WebSocketServer } from "ws";
 import { AGENT_INFO, compareVersions, log, warn } from "../utils.js";
+import { remoteTerminalPrefs } from "./config.js";
 import { accountUsageStats } from "../handlers/account.js";
+import { BOOT_RESUME_TRIGGER } from "../handlers/session.js";
 import { listKnownWorkspaces } from "../tasks-index.js";
 const HEARTBEAT_TIMEOUT_MS = 30_000;
 const IDLE_EXIT_MS = 10 * 60_000;
@@ -128,8 +130,6 @@ function parseOrigin(raw) {
 const TUI_REGISTER_TIMEOUT_MS = 20_000;
 /** `open -a <terminal>` must answer fast or the incubation falls back. */
 const TERMINAL_OPEN_TIMEOUT_MS = 3_000;
-/** Set ZCODE_ACP_HUB_TERMINAL=0 to keep remote session-create headless. */
-const TERMINAL_GATE_ENV = "ZCODE_ACP_HUB_TERMINAL";
 /** Single-quote for sh: ' → '\'' . */
 function shQuote(s) {
     return `'${s.replace(/'/g, "'\\''")}'`;
@@ -141,11 +141,9 @@ function shQuote(s) {
  * WezTerm's `start --` runs an alternative program (wezterm.org/cli/start.html);
  * kitty takes the program as normal positional arguments
  * (sw.kovidgoyal.net/kitty/invocation); Alacritty and Ghostty support the
- * common `-e` flag. The script does its own `cd`, so no per-app cwd flags.
- * Warp is deliberately ABSENT — it cannot execute `.command` files (#1917)
- * and has no programmatic command execution at all (URI scheme opens dirs
- * only; still an open request in #3959/#9083). Hyper is absent for the same
- * reason (#3677).
+ * common `-e` flag; Warp rides its new_tab URI action (see warpUri above).
+ * The script does its own `cd`, so no per-app cwd flags. Hyper is absent — no
+ * programmatic command execution at all (vercel/hyper#3677).
  */
 const TERMINAL_APP_LAUNCHERS = {
     terminal: { kind: "openApp", app: "Terminal" },
@@ -156,34 +154,30 @@ const TERMINAL_APP_LAUNCHERS = {
     kitty: { kind: "openAppArgs", app: "kitty", args: [] },
     alacritty: { kind: "openAppArgs", app: "Alacritty", args: ["-e"] },
     ghostty: { kind: "openAppArgs", app: "Ghostty", args: ["-e"] },
+    warp: { kind: "warpUri", app: "Warp", scheme: "warp" },
+    "warp-preview": { kind: "warpUri", app: "Warp Preview", scheme: "warppreview" },
+    warp_preview: { kind: "warpUri", app: "Warp Preview", scheme: "warppreview" },
 };
 /**
- * Pick how to open the TUI script. The hub is a background daemon — its env
- * carries no terminal and macOS has no default-terminal setting — so nothing
- * is detected. Priority: the explicit command template (the universal escape
- * hatch) → a built-in launcher by app name (aliases are case- and
- * `.app`-suffix-insensitive) → plain Terminal.app. Warp gets a special warning
- * because it accepts the open but cannot run the script; any other unmatched
+ * Pick how to open the TUI script. Preferences arrive pre-merged from
+ * `remoteTerminalPrefs` (config file first, env fallback — see config.ts);
+ * only the app-name normalization lives here. Priority: the explicit command
+ * template (the universal escape hatch) → a built-in launcher by app name
+ * (aliases are case- and `.app`-suffix-insensitive) → plain Terminal.app
+ * (macOS has no default-terminal setting to detect). Any other unmatched
  * name passes through to `open -a` unchanged.
  */
-export function resolveTerminalLaunch(env) {
-    const command = (env.ZCODE_ACP_HUB_TERMINAL_COMMAND ?? "").trim();
-    if (command)
-        return { launch: { kind: "shell", command } };
-    const raw = (env.ZCODE_ACP_HUB_TERMINAL_APP ?? "").trim();
-    const name = raw.toLowerCase().replace(/\.app$/, "");
+export function resolveTerminalLaunch(env, prefs = remoteTerminalPrefs(env)) {
+    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 };
-    if (name === "warp") {
-        return {
-            launch: { kind: "openApp", app: raw || "Warp" },
-            warning: "Warp cannot execute .command scripts (warpdotdev/warp#1917) and has no " +
-                "programmatic command execution (warpdotdev/warp#3959, #9083) — the window " +
-                "will idle and session-create falls back to a headless bridge after the " +
-                "register timeout; set ZCODE_ACP_HUB_TERMINAL_COMMAND to drive Warp another way",
-        };
-    }
     return { launch: { kind: "openApp", app: raw || "Terminal" } };
 }
 /**
@@ -196,13 +190,22 @@ export function resolveTerminalLaunch(env) {
  */
 export function terminalTuiScript(cwd, cliJs, env) {
     const exports = Object.keys(env)
-        .filter((k) => k.startsWith("ZCODE_ACP_"))
+        // DSH_TUI_AUTOPROMPT is the one non-ZCODE_ACP_* passenger: the boot-resume
+        // banner handshake (martty reads it at its own process start).
+        .filter((k) => k.startsWith("ZCODE_ACP_") || k === "DSH_TUI_AUTOPROMPT")
         .map((k) => `export ${k}=${shQuote(String(env[k]))}`);
     return [
         "#!/bin/sh",
         `# Hub-incubated TUI session (ADR-0016): closing this window ends the bridge.`,
         `cd ${shQuote(cwd)} || exit 1`,
         ...exports,
+        // OSC 0 names the tab after the conversation — without it terminals show
+        // the running process ("node"). printf reads the \033/\007 escapes from
+        // the format string; %s keeps the value itself shell-safe. martty never
+        // sets a terminal title, so this survives until the window closes.
+        ...(env.ZCODE_ACP_TAB_TITLE !== undefined
+            ? [`printf '\\033]0;%s\\007' "$ZCODE_ACP_TAB_TITLE"`]
+            : []),
         `exec ${shQuote(process.execPath)} ${shQuote(cliJs)}`,
         "",
     ].join("\n");
@@ -222,8 +225,12 @@ export function terminalTuiScript(cwd, cliJs, env) {
 async function spawnTerminalTui(opts) {
     if (process.platform !== "darwin")
         return null;
-    const gate = (process.env[TERMINAL_GATE_ENV] ?? "").trim().toLowerCase();
-    if (["0", "false", "off"].includes(gate))
+    // 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 = path.join(mkdtempSync(path.join(tmpdir(), "zcode-acp-term-")), "tui.command");
@@ -242,6 +249,16 @@ async function spawnTerminalTui(opts) {
     else if (launch.kind === "openApp") {
         argv = ["open", "-a", launch.app, script];
     }
+    else if (launch.kind === "warpUri") {
+        // new_tab = Warp's default open mode (like Cmd+T: a tab in the focused
+        // window; Warp opens a window first if none exists).
+        argv = [
+            "open",
+            "-a",
+            launch.app,
+            `${launch.scheme}://action/new_tab?path=${encodeURIComponent(script)}`,
+        ];
+    }
     else {
         argv = ["open", "-na", launch.app, "--args", ...launch.args, "/bin/sh", script];
     }
@@ -371,6 +388,36 @@ const MAX_SESSION_LIST_BYTES = 4 * 1024 * 1024;
  * gives its own query 15s).
  */
 const SESSION_LIST_TIMEOUT_MS = 12_000;
+/** Best-effort budget for the resume tab-title lookup — the window must
+ *  never wait on a slow bridge (the 12s list budget is for listings, not
+ *  for cosmetics). */
+const TITLE_LOOKUP_BUDGET_MS = 2_000;
+/**
+ * Tab-title sanitizer: the value is printf'd into the terminal as an OSC
+ * payload, so control characters (an ESC inside a model-generated summary
+ * would inject terminal sequences) become spaces, whitespace collapses, and
+ * the length caps at what a tab can usefully show. Empty/non-string →
+ * undefined (the caller falls back to the project name).
+ */
+export function sanitizeTabTitle(v) {
+    if (typeof v !== "string")
+        return undefined;
+    const clean = v
+        .replace(/[\p{Cc}]/gu, " ")
+        .replace(/\s+/g, " ")
+        .trim()
+        .slice(0, 80);
+    return clean.length > 0 ? clean : undefined;
+}
+/** Resolve with undefined after `ms` — for best-effort lookups that must not
+ *  stall their caller; the losing promise settles into the void (its own
+ *  rejection is the caller's `.catch`, never unhandled). */
+function withTimeout(p, ms) {
+    const timeout = new Promise((resolve) => {
+        setTimeout(() => resolve(undefined), ms).unref?.();
+    });
+    return Promise.race([p, timeout]);
+}
 /**
  * Fetch a bridge's GET /sessions payload (ADR-0015), forwarding the
  * pagination query ("?limit=..&before=.."). Resolves with the parsed JSON;
@@ -527,7 +574,7 @@ export function startHub(options) {
      * requested session (ADR-0017), "serve" the detached headless bridge
      * (background listing, ADR-0015).
      */
-    const incubateServe = async (workspacePath, kind, sessionId) => {
+    const incubateServe = async (workspacePath, kind, sessionId, tabTitle) => {
         // 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.
@@ -562,6 +609,19 @@ export function startHub(options) {
             // TUI boots into it. The detached serve fallback ignores it; the
             // client attaches to the serve bridge and session/loads there instead.
             env.ZCODE_ACP_RESUME_SESSION = sessionId;
+            // Banner handshake (see BOOT_RESUME_TRIGGER): martty auto-submits this
+            // text at boot, which drops its welcome banner and reveals the
+            // boot-replayed history without waiting for the user's first message.
+            // Must ride the env verbatim — martty reads it once at process start.
+            env.DSH_TUI_AUTOPROMPT = BOOT_RESUME_TRIGGER;
+        }
+        if (kind !== "serve") {
+            // Tab title (both visible-terminal kinds): a resume carries the
+            // conversation's title when the hub resolved it; session-create and a
+            // failed lookup fall back to the project name. Rides the env —
+            // terminalTuiScript turns it into an OSC 0 before exec'ing the CLI
+            // (terminals otherwise name the tab after the process, "node").
+            env.ZCODE_ACP_TAB_TITLE = tabTitle ?? path.basename(workspacePath);
         }
         try {
             // Resume shares session-create's visible-terminal surface (and its
@@ -624,14 +684,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) => {
+    const joinIncubation = (workspacePath, kind, sessionId, tabTitle) => {
         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);
+        const promise = incubateServe(workspacePath, kind, sessionId, tabTitle);
         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;
@@ -969,13 +1029,26 @@ export function startHub(options) {
                 return;
             }
             if (resumeSid) {
+                // Tab title, best-effort: the App browsed this conversation through
+                // the serve bridge's /sessions history, which is normally still live
+                // and still holds the title. Every miss (no live instance, id beyond
+                // the page, slow fetch) falls back to the project name inside
+                // incubateServe — the window must never wait on this lookup.
+                let tabTitle;
+                const titleSource = findServeInstance(workspacePath);
+                if (titleSource) {
+                    const row = await withTimeout(fetchBridgeSessions(titleSource.port, "?limit=200")
+                        .then((payload) => (payload.sessions ?? []).find((s) => s.sessionId === resumeSid))
+                        .catch(() => undefined), TITLE_LOOKUP_BUDGET_MS);
+                    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);
+                const incubation = joinIncubation(workspacePath, "resume", resumeSid, tabTitle);
                 try {
                     const out = await incubation;
                     res.writeHead(200, { "Content-Type": "application/json" });