feat(serve): allow relocating session attachment storage via env var

docs/users/qwen-serve.md

@@ -711,6 +711,21 @@ Scope and limits:
 - Binary uploads (`POST /file/upload`) always create at `0600` regardless of this setting.
 - The daemon reads the variable at workspace-filesystem construction; restart the daemon after changing it.
 
+### Session attachment storage
+
+Session attachments (files and images uploaded by Web Shell through `POST /session/:id/attachments`) are stored by default under the workspace's runtime temp dir: `<runtimeBaseDir>/tmp/<projectHash>/attachments`, keyed per session as `session-<sessionId>`. Operators who want attachments to persist outside the runtime temp dir (e.g. on a dedicated volume) can override the root:
+
+| Env var                               | Values | Default | What it does                                                                                                                                                                                                |
+| ------------------------------------- | ------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `QWEN_SERVE_SESSION_ATTACHMENTS_ROOT` | path   | unset   | Stores session attachments under this directory instead of the default runtime temp dir. Accepts an absolute path, a path relative to the daemon's cwd, or `~` / `~/…` expanded against the home directory. |
+
+Scope and limits:
+
+- **One-way migration.** When the env is set, new attachments are written only under the configured root. Reads and removes that miss the configured root fall back to the default runtime temp dir, so attachments uploaded **before** the switch remain readable, and removable while the default fallback dir stays writable — a remove whose legacy copy cannot be unlinked (e.g. a read-only fallback volume) surfaces the error rather than reporting success. The reverse direction — removing the env after attachments were written to the configured root — makes those attachments unreachable; keep the variable stable for a given workspace.
+- **Per-session layout.** Files live under `<root>/<projectHash>/attachments/session-<sessionId>/` in both locations, where `<projectHash>` is the same workspace hash used by the default runtime temp dir; the fallback lookup uses the same session layout in the default dir. Two workspaces pointing at the same configured root stay isolated from each other.
+- **Delete cleanup.** When a session is deleted, its attachment directory is removed from both the configured root and the default fallback dir. Archiving a session keeps its attachments so they survive unarchive.
+- The daemon reads the variable at startup; restart the daemon after changing it. The directory must be writable by the daemon process.
+
 ## Multi-session & multi-workspace deployment
 
 Pass `--workspace` more than once to register several non-overlapping workspaces in one `qwen serve` process. The first path is primary. Each registered workspace owns an isolated runtime boundary, while the daemon-wide listener, authentication policy, and total-session limit are shared. Production attempts to preheat the primary ACP child for compatibility and retries on first use after failure; trusted secondaries start their own child on demand, and untrusted secondaries do not start ACP. Requests may select a registered workspace by canonical `cwd`; requests that omit `cwd` use the primary workspace. Use one daemon per user or security principal; workspace trust is an execution gate, not an ACL.

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

@@ -14802,6 +14802,86 @@ describe('createAcpSessionBridge', () => {
       await bridge.shutdown();
     });
 
+    it('reads attachments from the fallback root when the primary misses', async () => {
+      const mainRoot = await fsp.mkdtemp(
+        path.join(os.tmpdir(), 'qwen-bridge-main-'),
+      );
+      const fallbackRoot = await fsp.mkdtemp(
+        path.join(os.tmpdir(), 'qwen-bridge-fallback-'),
+      );
+      const bridge = makeBridge({
+        sessionAttachmentsRoot: mainRoot,
+        sessionAttachmentsFallbackRoot: fallbackRoot,
+        channelFactory: async () => makeChannel({}).channel,
+      });
+      try {
+        const session = await bridge.spawnOrAttach({ workspaceCwd: WS_A });
+        const sessionDir = `session-${encodeURIComponent(session.sessionId)}`;
+        await fsp.mkdir(path.join(fallbackRoot, sessionDir), {
+          recursive: true,
+        });
+        await fsp.writeFile(
+          path.join(fallbackRoot, sessionDir, 'notes.txt'),
+          'legacy attachment',
+        );
+
+        const read = await bridge.readSessionAttachment(
+          session.sessionId,
+          'notes.txt',
+          { clientId: session.clientId },
+        );
+        expect(read?.data.toString()).toBe('legacy attachment');
+        expect(read?.mimeType).toBe('text/plain');
+      } finally {
+        await bridge.shutdown();
+        await fsp.rm(mainRoot, { recursive: true, force: true });
+        await fsp.rm(fallbackRoot, { recursive: true, force: true });
+      }
+    });
+
+    it('deleteSessionAttachments clears both roots for a non-live session', async () => {
+      const mainRoot = await fsp.mkdtemp(
+        path.join(os.tmpdir(), 'qwen-bridge-main-'),
+      );
+      const fallbackRoot = await fsp.mkdtemp(
+        path.join(os.tmpdir(), 'qwen-bridge-fallback-'),
+      );
+      const bridge = makeBridge({
+        sessionAttachmentsRoot: mainRoot,
+        sessionAttachmentsFallbackRoot: fallbackRoot,
+        channelFactory: async () => makeChannel({}).channel,
+      });
+      try {
+        const sessionId = 'sess:unknown';
+        const sessionDir = `session-${encodeURIComponent(sessionId)}`;
+        await fsp.mkdir(path.join(mainRoot, sessionDir), { recursive: true });
+        await fsp.writeFile(
+          path.join(mainRoot, sessionDir, 'current.txt'),
+          'current',
+        );
+        await fsp.mkdir(path.join(fallbackRoot, sessionDir), {
+          recursive: true,
+        });
+        await fsp.writeFile(
+          path.join(fallbackRoot, sessionDir, 'notes.txt'),
+          'legacy',
+        );
+
+        await bridge.deleteSessionAttachments(sessionId);
+
+        await expect(
+          fsp.readdir(path.join(mainRoot, sessionDir)),
+        ).rejects.toMatchObject({ code: 'ENOENT' });
+        await expect(
+          fsp.readdir(path.join(fallbackRoot, sessionDir)),
+        ).rejects.toMatchObject({ code: 'ENOENT' });
+      } finally {
+        await bridge.shutdown();
+        await fsp.rm(mainRoot, { recursive: true, force: true });
+        await fsp.rm(fallbackRoot, { recursive: true, force: true });
+      }
+    });
+
     it('resolves text and binary file attachment references for ACP', async () => {
       const prompts: PromptRequest[] = [];
       const bridge = makeBridge({

packages/acp-bridge/src/bridge.ts

@@ -6415,6 +6415,7 @@ export function createAcpSessionBridge(opts: BridgeOptions): AcpSessionBridge {
       attachments: new SessionAttachmentStore(
         opts.sessionAttachmentsRoot,
         sessionId,
+        opts.sessionAttachmentsFallbackRoot,
       ),
       recordingDegraded: false,
       closing: false,
@@ -10315,6 +10316,7 @@ export function createAcpSessionBridge(opts: BridgeOptions): AcpSessionBridge {
             const branchAttachments = new SessionAttachmentStore(
               opts.sessionAttachmentsRoot,
               result.newSessionId,
+              opts.sessionAttachmentsFallbackRoot,
             );
             try {
               await branchAttachments.copyFrom(entry.attachments);
@@ -12242,7 +12244,11 @@ export function createAcpSessionBridge(opts: BridgeOptions): AcpSessionBridge {
     async deleteSessionAttachments(sessionId, options) {
       const store =
         byId.get(sessionId)?.attachments ??
-        new SessionAttachmentStore(opts.sessionAttachmentsRoot, sessionId);
+        new SessionAttachmentStore(
+          opts.sessionAttachmentsRoot,
+          sessionId,
+          opts.sessionAttachmentsFallbackRoot,
+        );
       await store.delete(options);
     },
 

packages/acp-bridge/src/bridgeOptions.ts

@@ -220,6 +220,14 @@ export interface BridgeOptions {
    * root. Direct embedded callers may omit it for process-local storage.
    */
   sessionAttachmentsRoot?: string;
+  /**
+   * Fallback root for reading session attachments stored before
+   * `sessionAttachmentsRoot` was reconfigured (e.g. the previous default
+   * directory). Writes always go to `sessionAttachmentsRoot`; reads and
+   * removes that miss there consult this root so existing attachments
+   * survive a root switch.
+   */
+  sessionAttachmentsFallbackRoot?: string;
   /**
    * `single` shares one session per workspace across HTTP
    * clients (live-collaboration default); `thread` gives each `spawnOrAttach`