feat(web-shell): add opt-in interactive browser terminal

docs/design/web-terminal-lifecycle.md

@@ -0,0 +1,20 @@
+# Web terminal lifecycle
+
+The browser terminal is a manually opened Web Shell surface. The host must add
+the terminal right-panel action and the daemon must advertise the
+`web_terminal` capability before the UI exposes the entry. WebSocket requests
+use the daemon's shared Host, Origin, authentication and workspace trust gates.
+
+Each terminal is owned by one active, trusted workspace runtime. The daemon
+resolves the client workspace selector against the live registry and supplies
+that runtime's cwd and effective environment to the PTY. A terminal id cannot
+be reclaimed through another workspace.
+
+Closing a terminal tab sends an explicit release control frame and kills the
+PTY. Hiding the panel, switching tabs or losing the WebSocket only detaches the
+client, so reconnect can replay the same session. A detached session is killed
+after the idle timeout even if its command is still running. Exited sessions
+replay both scrollback and exit state. Binary WebSocket frames contain UTF-8
+terminal input and output; NUL-prefixed text frames contain control messages.
+Reloading the page loses the in-memory terminal id, so the detached session is
+reclaimed after the idle timeout rather than restored into the new page.

docs/developers/qwen-serve-protocol.md

@@ -516,6 +516,7 @@ operator diagnostic snapshot documented below.
 | `browser_automation_mcp`            | ACP HTTP is enabled, `cdp_tunnel_over_ws` is active, no bearer token blocks `/cdp`, and `QWEN_CDP_MCP_COMMAND` names an external stdio MCP adapter. The main CLI package does not bundle a browser automation adapter; without this tag, Chrome extension side-panel chat may still work, but console/network/screenshot/click tools are not registered by default.                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `voice_transcribe`                  | the Voice WebSocket endpoint is mounted; a configured Voice model is still required for a successful transcription.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `realtime_voice`                    | the macOS WebShell daemon has Live Voice enabled and native Host integration active. `/live/status` reports readiness, but the capability is withdrawn until the feature is enabled.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `web_terminal`                      | ACP HTTP is enabled, so the authenticated Web Terminal endpoint is available.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 
 <!-- conditional-serve-features:end -->
 

packages/cli/src/serve/acp-http/index.ts

@@ -498,6 +498,8 @@ export interface MountAcpHttpOptions {
  */
 export interface ExtraWsRoute {
   path: string;
+  /** The route resolves its own workspace lifecycle instead of using primary. */
+  bypassPrimaryDrain?: boolean;
   onConnection: (ws: WebSocket, req: IncomingMessage) => void;
 }
 
@@ -1852,7 +1854,7 @@ export function mountAcpHttp(
         activeMount = resolvedMount;
       }
 
-      if (activeMount.draining) {
+      if (extraRoute?.bypassPrimaryDrain !== true && activeMount.draining) {
         logReject(`workspace-draining ${activeMount.routeLabel}`);
         socket.write(
           'HTTP/1.1 503 Service Unavailable\r\nRetry-After: 5\r\n\r\n',

packages/cli/src/serve/acp-http/workspace-qualified-acp.test.ts

@@ -293,6 +293,17 @@ describe('workspace-qualified ACP (/workspaces/:workspace/acp)', () => {
         HTTPS_PROXY: 'http://primary-proxy.example:8080',
       },
       workspaceRegistry,
+      extraWsRoutes: [
+        {
+          path: '/test-extra',
+          bypassPrimaryDrain: true,
+          onConnection: (ws) => {
+            ws.send('extra-ready');
+            ws.close(1000, 'done');
+          },
+        },
+        { path: '/test-primary-extra', onConnection: () => {} },
+      ],
       deviceFlowRegistry,
       cdpTunnelOverWs: true,
       cdpTunnelRegistry: cdpRegistry,
@@ -1745,6 +1756,41 @@ describe('workspace-qualified ACP (/workspaces/:workspace/acp)', () => {
     expect(response).toEqual({ status: 503, retryAfter: '5' });
   });
 
+  it('does not apply primary ACP drain to an extra WebSocket route', async () => {
+    handle!.beginWorkspaceDrain('primary-id');
+
+    const message = await new Promise<string>((resolve, reject) => {
+      const ws = new WebSocket(`ws://127.0.0.1:${port}/test-extra`, {
+        handshakeTimeout: 2000,
+      });
+      ws.on('message', (data: WebSocket.RawData) => resolve(data.toString()));
+      ws.on('error', reject);
+    });
+
+    expect(message).toBe('extra-ready');
+  });
+
+  it('keeps primary-scoped extra routes behind the primary drain gate', async () => {
+    handle!.beginWorkspaceDrain('primary-id');
+
+    const status = await new Promise<number | undefined>((resolve, reject) => {
+      const ws = new WebSocket(`ws://127.0.0.1:${port}/test-primary-extra`, {
+        handshakeTimeout: 2000,
+      });
+      ws.on('unexpected-response', (_req, res) => {
+        resolve(res.statusCode);
+        ws.terminate();
+      });
+      ws.on('open', () => {
+        ws.close();
+        reject(new Error('primary-scoped extra route should not open'));
+      });
+      ws.on('error', reject);
+    });
+
+    expect(status).toBe(503);
+  });
+
   it('rejects unowned and spoofed correlation frames during drain', async () => {
     const replies = await new Promise<Array<Record<string, unknown>>>(
       (resolve, reject) => {

packages/cli/src/serve/capabilities.ts

@@ -448,6 +448,7 @@ export const SERVE_CAPABILITY_REGISTRY = {
   // gate. `/live/status` remains the dynamic readiness surface for the Host,
   // permissions, self-checks, and provider reachability.
   realtime_voice: { since: 'v1' },
+  web_terminal: { since: 'v1' },
 } as const satisfies Record<string, ServeCapabilityDescriptor>;
 
 export type ServeFeature = keyof typeof SERVE_CAPABILITY_REGISTRY;
@@ -678,6 +679,7 @@ export const CONDITIONAL_SERVE_FEATURES: ReadonlyMap<
     (toggles) =>
       toggles.acpHttpEnabled === true && toggles.realtimeVoiceEnabled === true,
   ],
+  ['web_terminal', (toggles) => toggles.acpHttpEnabled === true],
 ]);
 
 export const SERVE_FEATURES = Object.freeze(