fix: add structured error code to SessionNotFoundError for session-closing retry

docs/developers/qwen-serve-protocol.md

@@ -67,10 +67,14 @@ with status `400`.
 `SessionNotFoundError` for an unknown session id returns:
 
 ```json
-{ "error": "No session with id \"<sid>\"", "sessionId": "<sid>" }
+{
+  "error": "No session with id \"<sid>\"",
+  "sessionId": "<sid>",
+  "code": "session_not_found"
+}
 ```
 
-with status `404`.
+with status `404`. A concurrent close uses `code: "session_closing"`.
 
 `WorkspaceMismatchError` for a `POST /session` whose `cwd` doesn't canonicalize to a registered workspace returns `400` with:
 
@@ -2485,7 +2489,7 @@ curl -X DELETE http://127.0.0.1:4170/session/$SID
 # → 204 No Content
 ```
 
-Idempotent: returns `404` for unknown sessions (same `SessionNotFoundError` shape as other routes).
+Idempotent: returns `404` for unknown sessions. The error envelope uses `code: "session_not_found"`; a concurrent close may return `code: "session_closing"`, which clients may treat as the same successful terminal state for this route.
 
 > **`session_closed` event.** SSE subscribers receive a terminal `session_closed` event with `{ sessionId, reason: 'client_close', closedBy?: '<clientId>' }` before the stream ends. SDK reducers treat this identically to `session_died` (sets `alive: false`, clears `pendingPermissions`).
 

packages/acp-bridge/src/bridge.test.ts

@@ -4486,6 +4486,9 @@ describe('createAcpSessionBridge', () => {
     });
 
     await expect(refresh).rejects.toBeInstanceOf(SessionNotFoundError);
+    await expect(refresh).rejects.toMatchObject({
+      code: 'session_closing',
+    });
     closeResult.resolve({});
     await close;
     await bridge.shutdown();

packages/acp-bridge/src/bridge.ts

@@ -5100,6 +5100,7 @@ export function createAcpSessionBridge(opts: BridgeOptions): AcpSessionBridge {
         throw new SessionNotFoundError(
           req.sessionId,
           'The session is closing; retry after close completes',
+          'session_closing',
         );
       }
       const replayFields =
@@ -5114,12 +5115,16 @@ export function createAcpSessionBridge(opts: BridgeOptions): AcpSessionBridge {
         action === 'load'
           ? await resolveHistoryAnchorRecordId(existing, replayFields)
           : undefined;
-      if (
-        byId.get(req.sessionId) !== existing ||
-        isClosingOrAuthorizingClose(existing)
-      ) {
+      if (byId.get(req.sessionId) !== existing) {
         throw new SessionNotFoundError(req.sessionId);
       }
+      if (isClosingOrAuthorizingClose(existing)) {
+        throw new SessionNotFoundError(
+          req.sessionId,
+          'The session is closing; retry after close completes',
+          'session_closing',
+        );
+      }
       existing.attachCount++;
       const clientId = registerClient(existing, req.clientId);
       recordAttachRef(existing, clientId);
@@ -5617,6 +5622,7 @@ export function createAcpSessionBridge(opts: BridgeOptions): AcpSessionBridge {
           throw new SessionNotFoundError(
             req.sessionId,
             'The session is closing; retry after close completes',
+            'session_closing',
           );
         }
         // Self + any coalescers we accumulated while the restore was
@@ -5855,6 +5861,7 @@ export function createAcpSessionBridge(opts: BridgeOptions): AcpSessionBridge {
       throw new SessionNotFoundError(
         sessionId,
         'The session is already closing',
+        'session_closing',
       );
     }
     let originatorClientId: string | undefined;
@@ -6264,6 +6271,7 @@ export function createAcpSessionBridge(opts: BridgeOptions): AcpSessionBridge {
             throw new SessionNotFoundError(
               existing.sessionId,
               'The session is closing; retry after close completes',
+              'session_closing',
             );
           }
           // BRSCi: bump attach counter BEFORE any await so the
@@ -6531,6 +6539,7 @@ export function createAcpSessionBridge(opts: BridgeOptions): AcpSessionBridge {
           new SessionNotFoundError(
             sessionId,
             'The session is closing; retry after close completes',
+            'session_closing',
           ),
         );
       }
@@ -9427,7 +9436,11 @@ export function createAcpSessionBridge(opts: BridgeOptions): AcpSessionBridge {
       const entry = byId.get(sessionId);
       if (!entry) throw new SessionNotFoundError(sessionId);
       if (isClosingOrAuthorizingClose(entry)) {
-        throw new SessionNotFoundError(sessionId, 'The session is closing');
+        throw new SessionNotFoundError(
+          sessionId,
+          'The session is closing; retry after close completes',
+          'session_closing',
+        );
       }
       const info = channelInfoForEntry(entry);
       if (!info || info.isDying) throw new SessionNotFoundError(sessionId);

packages/acp-bridge/src/bridgeErrors.ts

@@ -57,10 +57,16 @@ function isNotCurrentlyGeneratingText(value: unknown): boolean {
 
 export class SessionNotFoundError extends Error {
   readonly sessionId: string;
-  constructor(sessionId: string, extra?: string) {
+  readonly code: 'session_not_found' | 'session_closing';
+  constructor(
+    sessionId: string,
+    extra?: string,
+    code: 'session_not_found' | 'session_closing' = 'session_not_found',
+  ) {
     super(`No session with id "${sessionId}"` + (extra ? `. ${extra}` : ''));
     this.name = 'SessionNotFoundError';
     this.sessionId = sessionId;
+    this.code = code;
   }
 }
 

packages/cli/src/serve/server/error-response.test.ts

@@ -6,6 +6,7 @@
 
 import type { Response } from 'express';
 import { describe, expect, it, vi } from 'vitest';
+import { SessionNotFoundError } from '@qwen-code/acp-bridge/bridgeErrors';
 import {
   SessionTranscriptChangedError,
   SessionWriterConflictError,
@@ -29,6 +30,26 @@ function responseMock(): {
 }
 
 describe('sendBridgeError session writer errors', () => {
+  it('serializes the structured session-closing code', () => {
+    const { response, status, json } = responseMock();
+
+    sendBridgeError(
+      response,
+      new SessionNotFoundError(
+        'session-1',
+        'The session is closing',
+        'session_closing',
+      ),
+    );
+
+    expect(status).toHaveBeenCalledWith(404);
+    expect(json).toHaveBeenCalledWith({
+      error: 'No session with id "session-1". The session is closing',
+      code: 'session_closing',
+      sessionId: 'session-1',
+    });
+  });
+
   it('maps sealed session maintenance to daemon_draining', () => {
     const { response, status, json } = responseMock();
 

packages/cli/src/serve/server/error-response.ts

@@ -390,7 +390,9 @@ export function sendBridgeError(
     return;
   }
   if (err instanceof SessionNotFoundError) {
-    res.status(404).json({ error: err.message, sessionId: err.sessionId });
+    res
+      .status(404)
+      .json({ error: err.message, code: err.code, sessionId: err.sessionId });
     return;
   }
   if (err instanceof SessionArchivedError) {

packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/DaemonSessionClient.java

@@ -434,7 +434,8 @@ private boolean isCurrentSessionNotFound(HttpSupport.Response response) {
             String responseSessionId = JsonSupport.optionalString(body, "sessionId");
             String code = JsonSupport.optionalString(body, "code");
             return session.getSessionId().equals(responseSessionId)
-                    && (code == null || "session_not_found".equals(code));
+                    && (code == null || "session_not_found".equals(code)
+                            || "session_closing".equals(code));
         } catch (DaemonProtocolException e) {
             return false;
         }

packages/sdk-java/qwencode/src/test/java/com/alibaba/qwen/code/daemon/DaemonSessionClientTest.java

@@ -1680,6 +1680,18 @@ void destroyAfterDetachOmitsRetiredClientIdAndAcceptsNotFound() {
         assertEquals(null, deleteClientId.get());
     }
 
+    @Test
+    void destroyAcceptsAlreadyClosingForCurrentSession() {
+        server.createContext("/session/session-1", exchange ->
+                sendJson(exchange, 404,
+                        "{\"error\":\"closing\",\"code\":\"session_closing\",\"sessionId\":\"session-1\"}"));
+
+        try (DaemonClient daemon = newClient()) {
+            DaemonSessionClient session = daemon.createSession();
+            session.destroySession();
+        }
+    }
+
     @Test
     void destroyDoesNotTreatGenericNotFoundAsAlreadyDeleted() {
         server.createContext("/session/session-1", exchange ->

packages/webui/src/daemon/session/DaemonSessionProvider.test.tsx

@@ -7409,8 +7409,8 @@ describe('DaemonSessionProvider', () => {
     const closingError = new DaemonHttpError(
       404,
       {
-        error:
-          'No session with id "session-b". The session is closing; retry after close completes',
+        code: 'session_closing',
+        error: 'No session with id "session-b". The session is closing',
         sessionId: 'session-b',
       },
       'POST /session/:id/load: No session with id "session-b". The session is closing; retry after close completes',
@@ -7570,6 +7570,7 @@ describe('DaemonSessionProvider', () => {
       new DaemonHttpError(
         404,
         {
+          code: 'session_closing',
           error:
             'No session with id "session-b". The session is closing; retry after close completes',
           sessionId: 'session-b',
@@ -7584,6 +7585,41 @@ describe('DaemonSessionProvider', () => {
     expect(sdkMocks.MockDaemonSessionClient.load).toHaveBeenCalledTimes(1);
   });
 
+  it('does not retry a missing session', async () => {
+    sdkMocks.sessions.push(createMockSession({ sessionId: 'session-a' }));
+    let actions: DaemonSessionActions | undefined;
+
+    function Harness() {
+      actions = useDaemonActions();
+      return null;
+    }
+
+    await renderWithProvider(<Harness />, {
+      autoConnect: true,
+      sessionId: 'session-a',
+    });
+    await act(async () => {
+      await flushPromises();
+    });
+    sdkMocks.MockDaemonSessionClient.load.mockClear();
+    sdkMocks.MockDaemonSessionClient.load.mockRejectedValueOnce(
+      new DaemonHttpError(
+        404,
+        {
+          code: 'session_not_found',
+          error: 'No session with id "session-b"',
+          sessionId: 'session-b',
+        },
+        'POST /session/:id/load: No session with id "session-b"',
+      ),
+    );
+
+    await expect(
+      requireActions(actions).loadSession('session-b'),
+    ).rejects.toThrow();
+    expect(sdkMocks.MockDaemonSessionClient.load).toHaveBeenCalledTimes(1);
+  });
+
   it('does not retry a closing session after a newer switch', async () => {
     sdkMocks.capabilities.mockResolvedValue({
       workspaceCwd: '/mock-workspace',
@@ -7611,6 +7647,7 @@ describe('DaemonSessionProvider', () => {
       new DaemonHttpError(
         404,
         {
+          code: 'session_closing',
           error:
             'No session with id "session-b". The session is closing; retry after close completes',
           sessionId: 'session-b',

packages/webui/src/daemon/session/DaemonSessionProvider.tsx

@@ -2764,7 +2764,10 @@ export function DaemonSessionProvider(props: DaemonSessionProviderProps) {
             autoReconnect &&
             loadingRequestedSession &&
             pendingLoad?.sessionId === restoreSessionId &&
-            isClosingSessionLoadError(error)
+            isClosingSessionLoadError(
+              error,
+              !capabilities?.features.includes(CLIENT_IDENTITY_FEATURE),
+            )
           ) {
             reconnectAttempt += 1;
             const reconnectConfig = reconnectConfigRef.current;
@@ -4729,13 +4732,18 @@ function isAuthFailureHttpError(error: unknown): boolean {
   return status !== undefined && AUTH_FAILURE_HTTP_STATUSES.has(status);
 }
 
-function isClosingSessionLoadError(error: unknown): boolean {
+function isClosingSessionLoadError(
+  error: unknown,
+  allowLegacyMessage = false,
+): boolean {
   if (!(error instanceof DaemonHttpError) || error.status !== 404) return false;
   const body = isRecord(error.body) ? error.body : undefined;
   return (
-    typeof body?.['error'] === 'string' &&
-    body['error'].endsWith(
-      'The session is closing; retry after close completes',
-    )
+    body?.['code'] === 'session_closing' ||
+    (allowLegacyMessage &&
+      typeof body?.['error'] === 'string' &&
+      body['error'].endsWith(
+        'The session is closing; retry after close completes',
+      ))
   );
 }