Merge #780 feat(files): follow the agent into a worktree outside the session folder

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

test/file-browser-outside-worktree.test.ts

@@ -0,0 +1,312 @@
+/**
+ * @fileoverview The browser side of a worktree OUTSIDE the session folder (#765 follow-up).
+ *
+ * The server lists such a worktree with absolute paths and serves them as a second root. The
+ * browser has to route those paths to the workspace file routes (preview and edit), not to the
+ * attachment routes that serve an outside file read-only; the terminal has to open them in the
+ * preview, since the log viewer's `tail-file` stays confined to `workingDir`; and a root-relative
+ * markdown ref has to resolve from the top of the worktree. Real frontend code in a `vm` context.
+ */
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import vm from 'node:vm';
+import { JSDOM } from 'jsdom';
+import { describe, expect, it, vi } from 'vitest';
+
+const read = (name: string) => readFileSync(resolve(import.meta.dirname, '../src/web/public', name), 'utf8');
+
+const WORKING_DIR = '/base/myapp';
+const SIBLING = '/base/myapp-feature';
+const outsideSession = () => ({
+  workingDir: WORKING_DIR,
+  outsideWorktree: { name: 'myapp-feature', path: SIBLING, outside: true },
+});
+
+type Proto = {
+  _isExternalPreviewPath: (p: string, id: string) => boolean;
+  _isOutsideWorktreePath: (p: string, id: string) => boolean;
+};
+
+const loadRouting = (session: Record<string, unknown>) => {
+  const context = vm.createContext({
+    console,
+    CodemanApp: class CodemanApp {},
+    document: { addEventListener: vi.fn(), getElementById: () => null },
+    window: { addEventListener: vi.fn(), removeEventListener: vi.fn() },
+    localStorage: { getItem: () => null, setItem: () => {}, removeItem: () => {} },
+  });
+  vm.runInContext(
+    `${read('constants.js')}\n${read('terminal-ui.js')}\n${read('panels-ui.js')}\nglobalThis.__proto = CodemanApp.prototype;`,
+    context
+  );
+  const proto = (context as unknown as { __proto: Proto }).__proto;
+  const app = Object.assign(Object.create(proto), { sessions: new Map([['s1', session]]) }) as Proto;
+  return {
+    external: (p: string) => app._isExternalPreviewPath(p, 's1'),
+    outside: (p: string) => app._isOutsideWorktreePath(p, 's1'),
+  };
+};
+
+describe('preview routing for a worktree outside the session folder', () => {
+  it('keeps a path inside the outside worktree on the workspace routes', () => {
+    const app = loadRouting(outsideSession());
+    expect(app.external(`${SIBLING}/src/a.ts`)).toBe(false);
+    expect(app.external(SIBLING)).toBe(false);
+    expect(app.outside(`${SIBLING}/src/a.ts`)).toBe(true);
+  });
+
+  it('still sends every other outside path through the attachment routes', () => {
+    const app = loadRouting(outsideSession());
+    expect(app.external('/base/myapp-feature-2/src/a.ts')).toBe(true);
+    expect(app.external('/tmp/shot.png')).toBe(true);
+    expect(app.outside('/base/myapp-feature-2/src/a.ts')).toBe(false);
+    expect(app.outside('relative/a.ts')).toBe(false);
+  });
+
+  it('leaves workspace paths and an inside worktree as they were', () => {
+    const app = loadRouting({
+      workingDir: WORKING_DIR,
+      liveWorktree: { name: 'probe', path: `${WORKING_DIR}/.claude/worktrees/probe` },
+    });
+    expect(app.external(`${WORKING_DIR}/src/a.ts`)).toBe(false);
+    expect(app.outside(`${WORKING_DIR}/.claude/worktrees/probe/a.ts`)).toBe(false);
+    expect(app.external(`${SIBLING}/src/a.ts`)).toBe(true);
+  });
+
+  it('treats a sibling path as external once the agent has left the worktree', () => {
+    const app = loadRouting({ workingDir: WORKING_DIR });
+    expect(app.external(`${SIBLING}/src/a.ts`)).toBe(true);
+    expect(app.outside(`${SIBLING}/src/a.ts`)).toBe(false);
+  });
+});
+
+describe('terminal links into a worktree outside the session folder', () => {
+  type Link = { text: string; activate: (ev: unknown, text: string) => void };
+  type Provider = { provideLinks: (line: number, cb: (links: Link[] | undefined) => void) => void };
+
+  const makeApp = (line: string) => {
+    const CodemanApp = function CodemanApp(this: unknown) {};
+    const context = vm.createContext({
+      window: {},
+      document: {
+        body: { classList: { contains: () => false } },
+        activeElement: null,
+        addEventListener: vi.fn(),
+        getElementById: () => null,
+      },
+      CodemanApp,
+      console: { warn: vi.fn(), log: vi.fn(), debug: vi.fn() },
+      _crashDiag: { log: vi.fn() },
+      performance: { now: () => 0 },
+      requestAnimationFrame: () => 1,
+      setTimeout: () => 1,
+      MobileDetection: { isTouchDevice: () => false },
+      DEC_SYNC_STRIP_RE: /\x1b\[\?2026[hl]/g,
+      OSC52_STRIP_RE: /\x1b\]52;[^\x07\x1b]*(?:\x07|\x1b\\)/g,
+      TERMINAL_CHUNK_SIZE: 32 * 1024,
+    });
+    vm.runInContext(read('constants.js'), context, { filename: 'constants.js' });
+    vm.runInContext(read('terminal-ui.js'), context, { filename: 'terminal-ui.js' });
+    vm.runInContext(read('panels-ui.js'), context, { filename: 'panels-ui.js' });
+    const app = new (CodemanApp as unknown as new () => Record<string, any>)();
+    app.activeSessionId = 's1';
+    app.sessions = new Map([['s1', outsideSession()]]);
+    app.openFilePreview = vi.fn();
+    app.openLogViewerWindow = vi.fn();
+    const providers: Provider[] = [];
+    app.terminal = {
+      cols: 80,
+      registerLinkProvider: (p: Provider) => providers.push(p),
+      buffer: {
+        active: {
+          length: 1,
+          getLine: (row: number) =>
+            row === 0
+              ? { isWrapped: false, translateToString: (trim?: boolean) => (trim === false ? line.padEnd(80) : line) }
+              : undefined,
+        },
+      },
+    };
+    app.registerFilePathLinkProvider();
+    let links: Link[] = [];
+    providers[0].provideLinks(1, (found) => {
+      links = found || [];
+    });
+    return { app, link: links[0] };
+  };
+
+  it('opens a log in the outside worktree in the preview, since tail-file stays in the session folder', () => {
+    const { app, link } = makeApp(`tail -f ${SIBLING}/logs/server.log`);
+    link.activate({}, link.text);
+    expect(app.openFilePreview).toHaveBeenCalledWith(`${SIBLING}/logs/server.log`, 's1');
+    expect(app.openLogViewerWindow).not.toHaveBeenCalled();
+  });
+
+  it('keeps a log in the session folder in the log viewer', () => {
+    const { app, link } = makeApp(`tail -f ${WORKING_DIR}/logs/server.log`);
+    link.activate({}, link.text);
+    expect(app.openLogViewerWindow).toHaveBeenCalledWith(`${WORKING_DIR}/logs/server.log`, 's1');
+  });
+});
+
+describe('markdown in a worktree outside the session folder', () => {
+  const dom = new JSDOM('<!DOCTYPE html><html><body></body></html>', { url: 'http://localhost/' });
+  const { document } = dom.window;
+
+  it('resolves root-relative and relative refs from the worktree, not the session folder', () => {
+    const context = vm.createContext({
+      console,
+      CodemanApp: class CodemanApp {},
+      document,
+      window: { addEventListener: vi.fn(), removeEventListener: vi.fn() },
+      localStorage: { getItem: () => null, setItem: () => {}, removeItem: () => {} },
+    });
+    vm.runInContext(
+      `${read('constants.js')}\n${read('panels-ui.js')}\nglobalThis.__proto = CodemanApp.prototype;`,
+      context
+    );
+    const proto = (context as unknown as { __proto: Record<string, any> }).__proto;
+    const app = Object.assign(Object.create(proto), { sessions: new Map([['s1', outsideSession()]]) });
+    const root = document.createElement('div');
+    root.innerHTML = '<img src="/assets/root.png" alt="root"><img src="img/a.png" alt="rel">';
+
+    app._rebaseFilePreviewMarkdownRefs(root, { sessionId: 's1', filePath: `${SIBLING}/docs/README.md` });
+
+    const raw = (path: string) => `/api/sessions/s1/file-raw?path=${encodeURIComponent(path)}`;
+    const src = (alt: string) => root.querySelector(`img[alt="${alt}"]`)!.getAttribute('src');
+    expect(src('root')).toBe(raw(`${SIBLING}/assets/root.png`));
+    expect(src('rel')).toBe(raw(`${SIBLING}/docs/img/a.png`));
+  });
+});
+
+describe('the Files panel following an agent in a worktree outside the session folder', () => {
+  const OUTSIDE = { name: 'myapp-feature', path: SIBLING };
+  const update = (extra: Record<string, unknown>) => ({ id: 'sess-1', ...extra });
+
+  const panelElement = () => {
+    const classes = new Set<string>();
+    return {
+      innerHTML: '',
+      textContent: '',
+      title: '',
+      hidden: true,
+      value: '',
+      classList: {
+        toggle: (name: string, on: boolean) => (on ? classes.add(name) : classes.delete(name)),
+        contains: (name: string) => classes.has(name),
+      },
+      setAttribute: () => {},
+      querySelectorAll: () => [],
+    };
+  };
+
+  const loadPanel = () => {
+    const CodemanApp = function CodemanApp(this: unknown) {} as unknown as new () => Record<string, any>;
+    const context = vm.createContext({
+      CodemanApp,
+      console,
+      localStorage: { getItem: () => null, setItem: () => {}, removeItem: () => {} },
+      escapeHtml: (x: string) => String(x),
+      document: { getElementById: () => null, addEventListener: vi.fn() },
+      window: { addEventListener: vi.fn() },
+      setTimeout,
+      clearTimeout,
+      fetch: undefined as unknown,
+      CodemanBase: { url: (path: string) => path },
+    });
+    vm.runInContext(read('panels-ui.js'), context, { filename: 'panels-ui.js' });
+    const ids = [
+      'fileBrowserPanel',
+      'fileBrowserTree',
+      'fileBrowserStatus',
+      'fileBrowserHiddenBtn',
+      'fileBrowserSearch',
+      'fileBrowserRoot',
+      'fileBrowserRootLabel',
+      'fileBrowserRootName',
+      'fileBrowserRootSwitch',
+    ];
+    const elements = Object.fromEntries(ids.map((id) => [id, panelElement()]));
+    elements.fileBrowserPanel.classList.toggle('visible', true);
+    const app = new CodemanApp();
+    app.$ = (id: string) => elements[id] ?? null;
+    app.activeSessionId = 'sess-1';
+    app.fileBrowserData = null;
+    app.fileBrowserExpandedDirs = new Set<string>();
+    app.fileBrowserFilter = '';
+    app.fileBrowserShowHidden = false;
+    app.getFileIcon = () => '';
+    app.formatFileSize = () => '';
+
+    // A stand-in for the route. The agent is in the outside worktree when `outside` is set, and
+    // a listing then reports it only when the request asks for root=live-any.
+    const server = { outside: null as typeof OUTSIDE | null, requests: [] as string[] };
+    context.fetch = async (url: string) => {
+      server.requests.push(url);
+      const live = url.includes('root=live') && server.outside;
+      const data = {
+        root: live ? server.outside!.path : WORKING_DIR,
+        ...(live && { worktree: server.outside }),
+        tree: [],
+        totalFiles: 0,
+        totalDirectories: 0,
+        truncated: false,
+      };
+      return { ok: true, json: async () => ({ success: true, data }) };
+    };
+    return { app, elements, server };
+  };
+
+  it('reloads when an update carries only outsideWorktree and the listing reports none', async () => {
+    const { app, server } = loadPanel();
+    await app.loadFileBrowser('sess-1');
+    expect(server.requests).toHaveLength(1);
+    const reload = vi.spyOn(app, '_reloadFileBrowserKeepingQuery');
+
+    server.outside = OUTSIDE;
+    app._followFileBrowserWorktree(update({ outsideWorktree: { ...OUTSIDE, outside: true } }));
+    expect(reload).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not reload when the listing already reports that outside worktree', async () => {
+    const { app, server } = loadPanel();
+    server.outside = OUTSIDE;
+    await app.loadFileBrowser('sess-1');
+    const reload = vi.spyOn(app, '_reloadFileBrowserKeepingQuery');
+
+    app._followFileBrowserWorktree(update({ outsideWorktree: { ...OUTSIDE, outside: true } }));
+    expect(reload).not.toHaveBeenCalled();
+  });
+
+  it('keeps the session folder pinned while the agent stays in the outside worktree', async () => {
+    const { app, elements, server } = loadPanel();
+    server.outside = OUTSIDE;
+    await app.loadFileBrowser('sess-1');
+    await app.toggleFileBrowserRoot();
+    await vi.waitFor(() => expect(app._fileBrowserState.normalState?.phase).toBe('ready'));
+    expect(app._fileBrowserState.normalState.data.worktree).toBeUndefined();
+    const reload = vi.spyOn(app, '_reloadFileBrowserKeepingQuery');
+
+    app._followFileBrowserWorktree(update({ outsideWorktree: { ...OUTSIDE, outside: true } }));
+    expect(reload).not.toHaveBeenCalled();
+    expect(app._fileBrowserState.sessionRootPinned).toBe(true);
+    expect(elements.fileBrowserRoot.hidden).toBe(false);
+    expect(elements.fileBrowserRootLabel.textContent).toBe('Session folder');
+    expect(elements.fileBrowserRootSwitch.textContent).toBe('Back to worktree');
+  });
+
+  it('drops the pin and reloads once the agent leaves the outside worktree', async () => {
+    const { app, server } = loadPanel();
+    server.outside = OUTSIDE;
+    await app.loadFileBrowser('sess-1');
+    await app.toggleFileBrowserRoot();
+    await vi.waitFor(() => expect(app._fileBrowserState.normalState?.phase).toBe('ready'));
+    const reload = vi.spyOn(app, '_reloadFileBrowserKeepingQuery');
+
+    server.outside = null;
+    app._followFileBrowserWorktree(update({}));
+    expect(reload).toHaveBeenCalledTimes(1);
+    expect(app._fileBrowserState.sessionRootPinned).toBe(false);
+    expect(app._fileBrowserState.pinnedWorktree).toBeNull();
+  });
+});

test/file-browser-search.test.ts

@@ -387,7 +387,9 @@ describe('File Viewer server search', () => {
 
     await vi.advanceTimersByTimeAsync(1);
     expect(pending).toHaveLength(1);
-    expect(pending[0].url).toBe('/api/sessions/session%2FA/files?depth=5&showHidden=false&q=src%20%26%20docs&root=live');
+    expect(pending[0].url).toBe(
+      '/api/sessions/session%2FA/files?depth=5&showHidden=false&q=src%20%26%20docs&root=live-any'
+    );
   });
 
   it('is a safe no-op without a panel or session and can lazily adopt a later active owner', async () => {
@@ -399,7 +401,9 @@ describe('File Viewer server search', () => {
     app.activeSessionId = 'session/B';
     app.filterFileBrowser('after-session');
     await vi.advanceTimersByTimeAsync(250);
-    expect(pending[0].url).toBe('/api/sessions/session%2FB/files?depth=5&showHidden=false&q=after-session&root=live');
+    expect(pending[0].url).toBe(
+      '/api/sessions/session%2FB/files?depth=5&showHidden=false&q=after-session&root=live-any'
+    );
 
     pending[0].reply.resolve(response(successfulData()));
     await vi.advanceTimersByTimeAsync(0);
@@ -450,7 +454,7 @@ describe('File Viewer server search', () => {
     expect(pending).toHaveLength(0);
     await vi.advanceTimersByTimeAsync(1);
     expect(pending.map(({ url }) => url)).toEqual([
-      '/api/sessions/session%2FA/files?depth=5&showHidden=false&q=second%20query&root=live',
+      '/api/sessions/session%2FA/files?depth=5&showHidden=false&q=second%20query&root=live-any',
     ]);
   });
 
@@ -659,7 +663,7 @@ describe('File Viewer server search', () => {
     await vi.advanceTimersByTimeAsync(250);
 
     expect(pending).toHaveLength(1);
-    expect(pending[0].url.endsWith(`&q=${'x'.repeat(256)}&root=live`)).toBe(true);
+    expect(pending[0].url.endsWith(`&q=${'x'.repeat(256)}&root=live-any`)).toBe(true);
   });
 
   it('rejects 257 trimmed characters without a request', async () => {
@@ -786,7 +790,7 @@ describe('File Viewer server search', () => {
       expect(elements.fileBrowserTree.innerHTML).toContain('Loading files');
       expect(elements.fileBrowserTree.innerHTML).not.toContain('old-result.ts');
       expect(elements.fileBrowserTree.innerHTML).not.toContain('old-preference.ts');
-      expect(pending[1].url).toBe('/api/sessions/session%2FA/files?depth=5&showHidden=true&root=live');
+      expect(pending[1].url).toBe('/api/sessions/session%2FA/files?depth=5&showHidden=true&root=live-any');
 
       pending[1].reply.resolve(response(successfulTree('new-preference.ts')));
       await toggle;
@@ -794,7 +798,7 @@ describe('File Viewer server search', () => {
       expect(app._fileBrowserState.view).toBe('search-pending');
       expect(elements.fileBrowserTree.innerHTML).toContain('Searching');
       await vi.advanceTimersByTimeAsync(250);
-      expect(pending[2].url).toBe('/api/sessions/session%2FA/files?depth=5&showHidden=true&q=widget&root=live');
+      expect(pending[2].url).toBe('/api/sessions/session%2FA/files?depth=5&showHidden=true&q=widget&root=live-any');
       pending[2].reply.resolve(
         response(
           successfulData({
@@ -877,8 +881,8 @@ describe('File Viewer server search', () => {
       const firstToggle = app.toggleFileBrowserHidden();
       const secondToggle = app.toggleFileBrowserHidden();
       expect(pending.slice(1).map(({ url }) => url)).toEqual([
-        '/api/sessions/session%2FA/files?depth=5&showHidden=true&root=live',
-        '/api/sessions/session%2FA/files?depth=5&showHidden=false&root=live',
+        '/api/sessions/session%2FA/files?depth=5&showHidden=true&root=live-any',
+        '/api/sessions/session%2FA/files?depth=5&showHidden=false&root=live-any',
       ]);
 
       pending[1].reply.resolve(response(successfulTree('stale-hidden.ts')));
@@ -891,7 +895,7 @@ describe('File Viewer server search', () => {
       await vi.advanceTimersByTimeAsync(250);
 
       expect(pending).toHaveLength(4);
-      expect(pending[3].url).toBe('/api/sessions/session%2FA/files?depth=5&showHidden=false&q=widget&root=live');
+      expect(pending[3].url).toBe('/api/sessions/session%2FA/files?depth=5&showHidden=false&q=widget&root=live-any');
       expect(app.fileBrowserShowHidden).toBe(false);
     });
 
@@ -1674,7 +1678,9 @@ describe('File Viewer server search', () => {
       expect(immediateState.activeSessionId).toBe('session/B');
       expect(immediateState.ownerSessionId).toBe('session/B');
       expect(immediateState.resizeCalls).toBe(1);
-      expect(immediateState.fileUrls).toEqual(['/api/sessions/session%2FB/files?depth=5&showHidden=false&root=live']);
+      expect(immediateState.fileUrls).toEqual([
+        '/api/sessions/session%2FB/files?depth=5&showHidden=false&root=live-any',
+      ]);
 
       expect(filePending).toHaveLength(1);
       expect(app._fileBrowserState.ownerSessionId).toBe('session/B');
@@ -1755,7 +1761,9 @@ describe('File Viewer server search', () => {
       expect(elements.fileBrowserExpandBtn.innerHTML).toBe('\u229E');
       expect(elements.fileBrowserTree.querySelectorAll('.file-tree-item')).toHaveLength(0);
       expect(elements.fileBrowserTree.innerHTML).toContain('Loading files');
-      expect(pending.map(({ url }) => url)).toEqual(['/api/sessions/session%2FB/files?depth=5&showHidden=false&root=live']);
+      expect(pending.map(({ url }) => url)).toEqual([
+        '/api/sessions/session%2FB/files?depth=5&showHidden=false&root=live-any',
+      ]);
 
       await vi.advanceTimersByTimeAsync(250);
       expect(pending).toHaveLength(1);
@@ -1797,8 +1805,8 @@ describe('File Viewer server search', () => {
       await vi.advanceTimersByTimeAsync(250);
 
       expect(pending.map(({ url }) => url)).toEqual([
-        '/api/sessions/session%2FB/files?depth=5&showHidden=false&root=live',
-        '/api/sessions/session%2FB/files?depth=5&showHidden=false&q=during%20load&root=live',
+        '/api/sessions/session%2FB/files?depth=5&showHidden=false&root=live-any',
+        '/api/sessions/session%2FB/files?depth=5&showHidden=false&q=during%20load&root=live-any',
       ]);
       expect(pending.every(({ url }) => !url.includes('session%2FA'))).toBe(true);
     });
@@ -1815,9 +1823,9 @@ describe('File Viewer server search', () => {
 
       expect(secondA).not.toBe(firstA);
       expect(pending.map(({ url }) => url)).toEqual([
-        '/api/sessions/session%2FA/files?depth=5&showHidden=false&root=live',
-        '/api/sessions/session%2FB/files?depth=5&showHidden=false&root=live',
-        '/api/sessions/session%2FA/files?depth=5&showHidden=false&root=live',
+        '/api/sessions/session%2FA/files?depth=5&showHidden=false&root=live-any',
+        '/api/sessions/session%2FB/files?depth=5&showHidden=false&root=live-any',
+        '/api/sessions/session%2FA/files?depth=5&showHidden=false&root=live-any',
       ]);
 
       pending[0].reply.resolve(response(successfulTree('stale-A.ts')));

test/file-path-link-forms.test.ts

@@ -244,6 +244,7 @@ function loadApp() {
   app._registerExternalPreview = vi.fn(async () => ({ attachmentId: 'att-fixture' }));
   app.showToast = vi.fn();
   app._isExternalPreviewPath = (p: string) => p.startsWith('~/');
+  app._isOutsideWorktreePath = () => false;
   return app;
 }
 

test/file-preview-markdown.test.ts

@@ -146,6 +146,8 @@ function loadApp(prefs: Record<string, string> = {}) {
   app.$ = (id: string) => document.getElementById(id);
   app._resetFilePreviewEdit = () => {};
   app._isExternalPreviewPath = () => false;
+  app._isOutsideWorktreePath = () => false;
+  app.sessions = new Map();
   app.formatFileSize = (n: number) => `${n} B`;
   app.showToast = vi.fn();
   app.filePreviewContent = '';

test/live-worktree-outside.test.ts

@@ -0,0 +1,247 @@
+/**
+ * @fileoverview `findLiveWorktree()` for a worktree OUTSIDE the session's folder (#765 follow-up).
+ *
+ * Such a worktree becomes a second root the file routes serve, so what matters is what must NOT be
+ * followed: a folder the session's repository does not list, a forged `.git` file with no registry
+ * entry naming it back, another repository, the home folder or anything above it, a folder holding
+ * the session's folder, a Docker case workspace, and a folder the multi-user rule refuses. Runs
+ * against worktrees real git made, since the registry files are the thing being read.
+ */
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, relative as posixRelative } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { findLiveWorktree, findOutsideWorktree } from '../src/live-worktree.js';
+
+const git = (cwd: string, ...args: string[]): void => {
+  execFileSync('git', ['-c', 'user.name=t', '-c', 'user.email=t@t', ...args], { cwd, stdio: 'ignore' });
+};
+
+describe('findLiveWorktree outside the session folder', () => {
+  let base: string;
+  let repo: string;
+  let sibling: string;
+  /** Not the user's real home: the base folder must not count as "home or above". */
+  let home: string;
+
+  beforeEach(() => {
+    base = realpathSync(mkdtempSync(join(tmpdir(), 'outside-worktree-')));
+    home = join(base, 'home');
+    mkdirSync(home);
+    repo = join(base, 'myapp');
+    mkdirSync(repo);
+    git(repo, 'init', '-q');
+    writeFileSync(join(repo, 'README.md'), 'main');
+    git(repo, 'add', 'README.md');
+    git(repo, 'commit', '-q', '-m', 'init');
+    sibling = join(base, 'myapp-feature');
+    git(repo, 'worktree', 'add', '-q', sibling);
+    mkdirSync(join(sibling, 'src', 'deep'), { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(base, { recursive: true, force: true });
+  });
+
+  const expected = () => ({ name: 'myapp-feature', path: sibling, outside: true });
+
+  it('follows a sibling worktree of the session repository, from its root and from below it', async () => {
+    expect(await findLiveWorktree(repo, sibling, { home })).toEqual(expected());
+    expect(await findLiveWorktree(repo, join(sibling, 'src', 'deep'), { home })).toEqual(expected());
+  });
+
+  it('follows nothing outside the folder unless the caller passes the outside rules', async () => {
+    expect(await findLiveWorktree(repo, sibling)).toBeUndefined();
+  });
+
+  it('follows a worktree whose gitdir links are relative paths, whatever the git version', async () => {
+    // Hand-written, since git older than 2.48 cannot make this layout itself.
+    const relative = join(base, 'myapp-relative');
+    const entry = join(repo, '.git', 'worktrees', 'myapp-relative');
+    mkdirSync(relative);
+    mkdirSync(entry, { recursive: true });
+    writeFileSync(join(entry, 'gitdir'), `${posixRelative(entry, join(relative, '.git'))}\n`);
+    writeFileSync(join(relative, '.git'), `gitdir: ${posixRelative(relative, entry)}\n`);
+    expect(await findLiveWorktree(repo, relative, { home })).toEqual({
+      name: 'myapp-relative',
+      path: relative,
+      outside: true,
+    });
+  });
+
+  it('follows a worktree made with --relative-paths', async (ctx) => {
+    const relative = join(base, 'myapp-relative-git');
+    try {
+      git(repo, 'worktree', 'add', '-q', '--relative-paths', relative);
+    } catch {
+      ctx.skip(); // git older than 2.48 has no --relative-paths
+      return;
+    }
+    expect(await findLiveWorktree(repo, relative, { home })).toEqual({
+      name: 'myapp-relative-git',
+      path: relative,
+      outside: true,
+    });
+  });
+
+  it('follows the main worktree and other worktrees from a session started in a linked one', async () => {
+    const other = join(base, 'myapp-other');
+    git(repo, 'worktree', 'add', '-q', other);
+    expect(await findLiveWorktree(sibling, repo, { home })).toEqual({ name: 'myapp', path: repo, outside: true });
+    expect(await findLiveWorktree(sibling, other, { home })).toEqual({
+      name: 'myapp-other',
+      path: other,
+      outside: true,
+    });
+  });
+
+  it('answers with the real path when the pane reached the worktree through a symlink', async () => {
+    const link = join(base, 'link-to-feature');
+    symlinkSync(sibling, link);
+    expect(await findLiveWorktree(repo, join(link, 'src'), { home })).toEqual(expected());
+  });
+
+  it('refuses a folder in another repository, and one in no repository at all', async () => {
+    const otherRepo = join(base, 'other');
+    mkdirSync(otherRepo);
+    git(otherRepo, 'init', '-q');
+    expect(await findLiveWorktree(repo, otherRepo, { home })).toBeUndefined();
+    const plain = join(base, 'plain');
+    mkdirSync(plain);
+    expect(await findLiveWorktree(repo, plain, { home })).toBeUndefined();
+  });
+
+  it('refuses a worktree of ANOTHER repository, even one laid out the same way', async () => {
+    const otherRepo = join(base, 'other');
+    mkdirSync(otherRepo);
+    git(otherRepo, 'init', '-q');
+    writeFileSync(join(otherRepo, 'a'), 'a');
+    git(otherRepo, 'add', 'a');
+    git(otherRepo, 'commit', '-q', '-m', 'a');
+    const otherWorktree = join(base, 'other-feature');
+    git(otherRepo, 'worktree', 'add', '-q', otherWorktree);
+    expect(await findLiveWorktree(repo, otherWorktree, { home })).toBeUndefined();
+  });
+
+  it('refuses a forged .git file that the registry does not name back', async () => {
+    const forged = join(base, 'forged');
+    mkdirSync(forged);
+    // Points at the real registry entry of the sibling, whose `gitdir` names the sibling.
+    const entry = execFileSync('git', ['rev-parse', '--git-dir'], { cwd: sibling, encoding: 'utf8' }).trim();
+    writeFileSync(join(forged, '.git'), `gitdir: ${entry}\n`);
+    expect(await findLiveWorktree(repo, forged, { home })).toBeUndefined();
+  });
+
+  it('refuses a registry entry that names a .git symlink back', async () => {
+    const entry = execFileSync('git', ['rev-parse', '--git-dir'], { cwd: sibling, encoding: 'utf8' }).trim();
+    // The symlink leads to a copy of the original `gitdir` file, whose text is `<sibling>/.git`,
+    // so only the refusal of a symlink can stop it: followed, it would name the sibling back.
+    const copy = join(base, 'gitdir-copy');
+    writeFileSync(copy, readFileSync(join(entry, 'gitdir')));
+    rmSync(join(entry, 'gitdir'));
+    symlinkSync(copy, join(entry, 'gitdir'));
+    expect(await findLiveWorktree(repo, sibling, { home })).toBeUndefined();
+  });
+
+  it('refuses a .git file that is a symlink', async () => {
+    const text = execFileSync('cat', [join(sibling, '.git')], { encoding: 'utf8' });
+    const copy = join(base, 'dot-git-copy');
+    writeFileSync(copy, text);
+    rmSync(join(sibling, '.git'));
+    symlinkSync(copy, join(sibling, '.git'));
+    expect(await findLiveWorktree(repo, sibling, { home })).toBeUndefined();
+  });
+
+  it('refuses a folder whose .git is a symlink to the repository’s .git folder', async () => {
+    const fake = join(base, 'fake');
+    mkdirSync(fake);
+    symlinkSync(join(repo, '.git'), join(fake, '.git'));
+    // From a session in the main checkout.
+    expect(await findLiveWorktree(repo, fake, { home })).toBeUndefined();
+    // From a session in a linked worktree.
+    expect(await findLiveWorktree(sibling, fake, { home })).toBeUndefined();
+    // The real main worktree is still followed from the same session.
+    expect(await findLiveWorktree(sibling, repo, { home })).toEqual({ name: 'myapp', path: repo, outside: true });
+  });
+
+  it('follows nothing from a session started in a subfolder of its repository', async () => {
+    const sub = join(repo, 'sub');
+    mkdirSync(sub);
+    expect(await findLiveWorktree(sub, sibling, { home })).toBeUndefined();
+  });
+
+  it('refuses a worktree at or above the home folder', async () => {
+    expect(await findLiveWorktree(repo, sibling, { home: join(sibling, 'src') })).toBeUndefined();
+    expect(await findLiveWorktree(repo, sibling, { home: sibling })).toBeUndefined();
+  });
+
+  it('refuses a worktree that holds the session folder', async () => {
+    // A registry entry forged around the session's own folder: `base` holds `repo`. Both halves
+    // of the link are in place, so only the containment rule can refuse it.
+    const entry = join(repo, '.git', 'worktrees', 'around');
+    mkdirSync(entry, { recursive: true });
+    writeFileSync(join(entry, 'gitdir'), `${join(base, '.git')}\n`);
+    writeFileSync(join(base, '.git'), `gitdir: ${entry}\n`);
+    const elsewhereHome = realpathSync(mkdtempSync(join(tmpdir(), 'outside-worktree-home-')));
+    try {
+      expect(await findOutsideWorktree(repo, base, { home: elsewhereHome })).toBeUndefined();
+      // The same forged link around a folder that does NOT hold the session folder is followed,
+      // which shows the refusal above came from the containment rule.
+      const loose = join(base, 'loose');
+      mkdirSync(loose);
+      const looseEntry = join(repo, '.git', 'worktrees', 'loose');
+      mkdirSync(looseEntry, { recursive: true });
+      writeFileSync(join(looseEntry, 'gitdir'), `${join(loose, '.git')}\n`);
+      writeFileSync(join(loose, '.git'), `gitdir: ${looseEntry}\n`);
+      expect(await findOutsideWorktree(repo, loose, { home: elsewhereHome })).toEqual({
+        name: 'loose',
+        path: loose,
+        outside: true,
+      });
+    } finally {
+      rmSync(elsewhereHome, { recursive: true, force: true });
+    }
+  });
+
+  it('refuses a worktree at, inside or around a Docker case workspace', async () => {
+    const at = async () => [sibling];
+    const around = async () => [join(sibling, 'src')];
+    const above = async () => [base];
+    expect(await findLiveWorktree(repo, sibling, { home, dockerWorkspaces: at })).toBeUndefined();
+    expect(await findLiveWorktree(repo, sibling, { home, dockerWorkspaces: around })).toBeUndefined();
+    expect(await findLiveWorktree(repo, sibling, { home, dockerWorkspaces: above })).toBeUndefined();
+    const elsewhere = async () => [join(base, 'elsewhere')];
+    expect(await findLiveWorktree(repo, sibling, { home, dockerWorkspaces: elsewhere })).toEqual(expected());
+  });
+
+  it('follows nothing while the Docker case list cannot be read', async () => {
+    const unreadable = async (): Promise<string[]> => {
+      throw new Error('docker-cases.json mid-write');
+    };
+    expect(await findLiveWorktree(repo, sibling, { home, dockerWorkspaces: unreadable })).toBeUndefined();
+  });
+
+  it('lets allowRoot refuse the worktree, and passes it the real path', async () => {
+    const seen: string[] = [];
+    const refuse = (root: string) => {
+      seen.push(root);
+      return false;
+    };
+    expect(await findLiveWorktree(repo, sibling, { home, allowRoot: refuse })).toBeUndefined();
+    expect(seen).toEqual([sibling]);
+    expect(await findLiveWorktree(repo, sibling, { home, allowRoot: async () => true })).toEqual(expected());
+  });
+
+  it('treats an allowRoot that rejects as a refusal', async () => {
+    const reject = async () => {
+      throw new Error('settings unreadable');
+    };
+    expect(await findLiveWorktree(repo, sibling, { home, allowRoot: reject })).toBeUndefined();
+  });
+
+  it('clears when the pane comes back to the session folder', async () => {
+    expect(await findLiveWorktree(repo, repo, { home })).toBeUndefined();
+    expect(await findLiveWorktree(repo, join(repo, 'src'), { home })).toBeUndefined();
+  });
+});

test/pane-cwd-tracking.test.ts

@@ -29,13 +29,16 @@
  *
  * Port: ephemeral
  */
+import { execFileSync } from 'node:child_process';
 import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join, resolve } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import vm from 'node:vm';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { Session, rebasePath } from '../src/session.js';
 import { WebServer } from '../src/web/server.js';
+import { dataPath } from '../src/config/instance.js';
+import { createUser } from '../src/user-store.js';
 import type { SessionDocker, SessionRemote } from '../src/types.js';
 import type { MuxSession, TerminalMultiplexer } from '../src/mux-interface.js';
 import { TmuxManager, derivePaneCurrentPaths, parsePaneRows, type PaneRow } from '../src/tmux-manager.js';
@@ -314,9 +317,12 @@ describe('a pane read reaching the session record', () => {
       await vi.waitFor(() => expect(session.liveWorktree).toEqual({ name: 'probe', path: worktree }));
       // What the browser receives, and what the file routes read: never the confinement root.
       const state = (
-        web as unknown as { getSessionStateWithRespawn: (s: Session) => { liveWorktree?: unknown } }
+        web as unknown as {
+          getSessionStateWithRespawn: (s: Session) => { liveWorktree?: unknown; outsideWorktree?: unknown };
+        }
       ).getSessionStateWithRespawn(session);
       expect(state.liveWorktree).toEqual({ name: 'probe', path: worktree });
+      expect(state.outsideWorktree).toBeUndefined();
       expect(session.toState().workingDir).toBe(repo);
 
       const broadcasts = broadcast.mock.calls.length;
@@ -349,6 +355,174 @@ describe('a pane read reaching the session record', () => {
     });
   });
 
+  describe('liveWorktree outside the session folder (#765 follow-up)', () => {
+    let base: string;
+    let repo: string;
+    let sibling: string;
+
+    const git = (cwd: string, ...args: string[]): void => {
+      execFileSync('git', ['-c', 'user.name=t', '-c', 'user.email=t@t', ...args], { cwd, stdio: 'ignore' });
+    };
+
+    beforeEach(() => {
+      base = realpathSync(mkdtempSync(join(tmpdir(), 'pane-outside-worktree-')));
+      repo = join(base, 'myapp');
+      mkdirSync(repo);
+      git(repo, 'init', '-q');
+      writeFileSync(join(repo, 'README.md'), 'main');
+      git(repo, 'add', 'README.md');
+      git(repo, 'commit', '-q', '-m', 'init');
+      sibling = join(base, 'myapp-feature');
+      git(repo, 'worktree', 'add', '-q', sibling);
+    });
+
+    afterEach(() => {
+      rmSync(base, { recursive: true, force: true });
+    });
+
+    it('publishes a sibling worktree of the session repository as outside, and clears it on the way back', async () => {
+      const { mux, sessions, web } = build();
+      const session = localMuxSession({ workingDir: repo });
+      sessions.set(session.id, session);
+      (web as unknown as { broadcastSessionStateDebounced: (id: string) => void }).broadcastSessionStateDebounced =
+        vi.fn();
+      mux.getPaneExit = () => undefined;
+      let dir = sibling;
+      mux.getPaneCurrentPath = () => dir;
+      // A reading outside `workingDir` waits until the workspace's real path is known, so tick
+      // until it lands.
+      await vi.waitFor(() => {
+        mux.emit('paneExitsUpdated');
+        expect(session.liveWorktree).toEqual({ name: 'myapp-feature', path: sibling, outside: true });
+      });
+      expect(session.toState().workingDir).toBe(repo);
+      // On the wire an outside answer rides `outsideWorktree`; `liveWorktree` stays inside-only.
+      const state = session.toState();
+      expect(state.outsideWorktree).toEqual({ name: 'myapp-feature', path: sibling, outside: true });
+      expect(state.liveWorktree).toBeUndefined();
+
+      dir = repo;
+      mux.emit('paneExitsUpdated');
+      await vi.waitFor(() => expect(session.liveWorktree).toBeUndefined());
+    });
+
+    /**
+     * A session in `repo` whose pane sits in the sibling worktree, ticked until the lookup has
+     * answered. Returns the answer, so a test can tell "followed" from "refused".
+     */
+    const paneInSibling = async (sessionExtra: Record<string, unknown> = {}) => {
+      const { mux, sessions, web } = build();
+      const session = localMuxSession({ workingDir: repo, ...sessionExtra });
+      sessions.set(session.id, session);
+      (web as unknown as { broadcastSessionStateDebounced: (id: string) => void }).broadcastSessionStateDebounced =
+        vi.fn();
+      mux.getPaneExit = () => undefined;
+      mux.getPaneCurrentPath = () => sibling;
+      const lookup = vi.spyOn(session, 'setLiveWorktree');
+      // A reading outside `workingDir` waits until the workspace's real path is known, so tick
+      // until a lookup has run.
+      await vi.waitFor(() => {
+        mux.emit('paneExitsUpdated');
+        expect(lookup).toHaveBeenCalled();
+      });
+      // The lookup answers asynchronously; let the answer land before it is read.
+      await new Promise((resolve) => setTimeout(resolve, 50));
+      return session.liveWorktree;
+    };
+
+    /** Sets env vars for one test and restores them afterwards. */
+    const withEnv = async (env: Record<string, string>, run: () => Promise<void>): Promise<void> => {
+      const before = Object.fromEntries(Object.keys(env).map((key) => [key, process.env[key]]));
+      Object.assign(process.env, env);
+      try {
+        await run();
+      } finally {
+        for (const [key, value] of Object.entries(before)) {
+          if (value === undefined) delete process.env[key];
+          else process.env[key] = value;
+        }
+      }
+    };
+
+    it('follows nothing while attachment workspace confinement is on', async () => {
+      await withEnv({ CODEMAN_ATTACHMENT_CONFINE: '1' }, async () => {
+        expect(await paneInSibling()).toBeUndefined();
+      });
+      expect(await paneInSibling()).toEqual({ name: 'myapp-feature', path: sibling, outside: true });
+    });
+
+    it('follows nothing at a worktree that is itself a sensitive folder such as .ssh', async () => {
+      const keys = join(base, 'keys');
+      mkdirSync(keys);
+      const ssh = join(keys, '.ssh');
+      git(repo, 'worktree', 'add', '-q', '-b', 'keys-branch', ssh);
+      sibling = ssh;
+      expect(await paneInSibling()).toBeUndefined();
+    });
+
+    it('follows nothing at, inside or around an attachment blocked tree', async () => {
+      // Around the worktree: its parent folder is blocked.
+      await withEnv({ CODEMAN_ATTACHMENT_BLOCKED_PATHS: base }, async () => {
+        expect(await paneInSibling()).toBeUndefined();
+      });
+      // Inside the worktree: a blocked tree below its root.
+      mkdirSync(join(sibling, 'private'));
+      await withEnv({ CODEMAN_ATTACHMENT_BLOCKED_PATHS: join(sibling, 'private') }, async () => {
+        expect(await paneInSibling()).toBeUndefined();
+      });
+      // A blocked tree elsewhere changes nothing.
+      await withEnv({ CODEMAN_ATTACHMENT_BLOCKED_PATHS: join(base, 'elsewhere') }, async () => {
+        expect(await paneInSibling()).toEqual({ name: 'myapp-feature', path: sibling, outside: true });
+      });
+    });
+
+    it('follows nothing in a Docker case workspace, around or inside it', async () => {
+      const casesFile = dataPath('docker-cases.json');
+      mkdirSync(dirname(casesFile), { recursive: true });
+      try {
+        for (const hostWorkspacePath of [sibling, base, join(sibling, 'src')]) {
+          writeFileSync(casesFile, JSON.stringify([{ hostWorkspacePath }]));
+          expect(await paneInSibling()).toBeUndefined();
+        }
+        writeFileSync(casesFile, JSON.stringify([{ hostWorkspacePath: join(base, 'elsewhere') }]));
+        expect(await paneInSibling()).toEqual({ name: 'myapp-feature', path: sibling, outside: true });
+      } finally {
+        rmSync(casesFile, { force: true });
+      }
+    });
+
+    it('follows nothing while docker-cases.json cannot be parsed', async () => {
+      const casesFile = dataPath('docker-cases.json');
+      mkdirSync(dirname(casesFile), { recursive: true });
+      try {
+        // A read that lands while the writer is rewriting the file.
+        writeFileSync(casesFile, '[{"hostWorkspacePath": "/hom');
+        expect(await paneInSibling()).toBeUndefined();
+        writeFileSync(casesFile, '[]');
+        expect(await paneInSibling()).toEqual({ name: 'myapp-feature', path: sibling, outside: true });
+      } finally {
+        rmSync(casesFile, { force: true });
+      }
+    });
+
+    it('applies the owner folder rule in multi-user mode', async () => {
+      const spaces = join(base, 'spaces');
+      mkdirSync(spaces);
+      await createUser({ username: 'pane-admin', role: 'admin', password: 'correct horse battery' });
+      await createUser({ username: 'pane-user', role: 'user', password: 'correct horse battery' });
+      await withEnv({ CODEMAN_MULTIUSER: '1', CODEMAN_USER_SPACES_DIR: spaces }, async () => {
+        // A regular user's space does not hold the sibling, and neither does the session folder.
+        expect(await paneInSibling({ owner: 'pane-user' })).toBeUndefined();
+        // An admin may follow any worktree the repository lists.
+        expect(await paneInSibling({ owner: 'pane-admin' })).toEqual({
+          name: 'myapp-feature',
+          path: sibling,
+          outside: true,
+        });
+      });
+    });
+  });
+
   it('broadcasts a directory change once, and nothing on an unchanged tick', () => {
     const { mux, sessions } = build();
     const session = localMuxSession();
@@ -552,10 +726,14 @@ describe('confinement is unchanged by the live cwd', () => {
         __proto: {
           _resolveLinkedFilePath: (p: string, id: string) => string;
           _isExternalPreviewPath: (p: string, id: string) => boolean;
+          _isOutsideWorktreePath: (p: string, id: string) => boolean;
         };
       }
     ).__proto;
-    const app = { sessions: new Map([['s1', session]]) };
+    const app = {
+      sessions: new Map([['s1', session]]),
+      _isOutsideWorktreePath: proto._isOutsideWorktreePath,
+    };
     return {
       target: (p: string) => proto._resolveLinkedFilePath.call(app, p, 's1'),
       external: (p: string) => proto._isExternalPreviewPath.call(app, p, 's1'),
@@ -600,10 +778,14 @@ describe('a workspace reached through a symlink', () => {
         __proto: {
           _resolveLinkedFilePath: (p: string, id: string) => string;
           _isExternalPreviewPath: (p: string, id: string) => boolean;
+          _isOutsideWorktreePath: (p: string, id: string) => boolean;
         };
       }
     ).__proto;
-    const app = { sessions: new Map([['s1', session]]) };
+    const app = {
+      sessions: new Map([['s1', session]]),
+      _isOutsideWorktreePath: proto._isOutsideWorktreePath,
+    };
     return (p: string) => proto._isExternalPreviewPath.call(app, proto._resolveLinkedFilePath.call(app, p, 's1'), 's1');
   };
 

test/routes/file-routes-live-worktree.test.ts

@@ -81,6 +81,21 @@ describe('Files panel listing of a live worktree', () => {
     expect(data.tree[0].children[0].path).toBe(`${PREFIX}/src/worktree-only.ts`);
   });
 
+  it('lists an inside worktree for root=live-any, the root the Files panel sends', async () => {
+    const data = await list('&root=live-any');
+    expect(data.root).toBe(worktree);
+    expect(data.worktree).toEqual({ name: 'probe', path: worktree });
+    expect(names(data.tree)).toEqual(['src']);
+    expect(data.tree[0].path).toBe(`${PREFIX}/src`);
+    expect(data.tree[0].children[0].path).toBe(`${PREFIX}/src/worktree-only.ts`);
+  });
+
+  it('walks the session folder for root=live-any when a symlink replaced the worktree', async () => {
+    rmSync(worktree, { recursive: true });
+    symlinkSync(makeOutsideFolder(), worktree);
+    expectSessionFolderListing(await list('&root=live-any&showHidden=true'));
+  });
+
   it('does not need hidden files on, though the worktree lives under a dot folder', async () => {
     const data = await list('&root=live&showHidden=false');
     expect(data.totalFiles).toBe(1);

test/routes/file-routes-outside-worktree.test.ts

@@ -0,0 +1,299 @@
+/**
+ * @fileoverview The file routes for a worktree OUTSIDE the session's folder (#765 follow-up).
+ *
+ * A session's outside worktree is a second root: `GET .../files?root=live-any` lists it with
+ * ABSOLUTE paths (`root=live` keeps walking `workingDir`), and the read, raw, edit and download
+ * routes confine an absolute path inside it to it. What must not change: a relative path still resolves against `workingDir` only, a path that
+ * escapes the worktree through a symlink is refused, and a worktree folder replaced by a symlink is
+ * neither listed nor served. Real filesystem on purpose, since realpath is the thing under test.
+ */
+import { createHash } from 'node:crypto';
+import { mkdirSync, mkdtempSync, realpathSync, renameSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname } from 'node:path';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { createRouteTestHarness, type RouteTestHarness } from './_route-test-utils.js';
+import { registerFileRoutes } from '../../src/web/routes/file-routes.js';
+import { SETTINGS_PATH } from '../../src/web/route-helpers.js';
+
+// The converter would shell out to pdftoppm/LibreOffice; the route's own path check is under test.
+vi.mock('../../src/document-thumbnailer.js', () => ({
+  generateFirstPageThumbnail: vi.fn(async () => ({ content: Buffer.from('\x89PNG fake'), contentType: 'image/png' })),
+}));
+import { generateFirstPageThumbnail } from '../../src/document-thumbnailer.js';
+
+const sha256 = (text: string) => createHash('sha256').update(text).digest('hex');
+
+describe('file routes for a worktree outside the session folder', () => {
+  let harness: RouteTestHarness;
+  let base: string;
+  let repo: string;
+  let sibling: string;
+  let secret: string;
+
+  const sessionUrl = (rest: string) => `/api/sessions/${harness.ctx._sessionId}/${rest}`;
+  const list = async (query = '') => {
+    const res = await harness.app.inject({ method: 'GET', url: sessionUrl(`files?depth=5${query}`) });
+    expect(res.statusCode).toBe(200);
+    return res.json().data;
+  };
+  const readContent = (path: string) =>
+    harness.app.inject({ method: 'GET', url: sessionUrl(`file-content?path=${encodeURIComponent(path)}`) });
+
+  beforeEach(async () => {
+    harness = await createRouteTestHarness(registerFileRoutes);
+    base = realpathSync(mkdtempSync(join(tmpdir(), 'outside-worktree-route-')));
+    repo = join(base, 'myapp');
+    sibling = join(base, 'myapp-feature');
+    secret = join(base, 'secret');
+    mkdirSync(join(repo, 'src'), { recursive: true });
+    mkdirSync(join(sibling, 'src'), { recursive: true });
+    mkdirSync(secret);
+    writeFileSync(join(repo, 'src', 'main-only.ts'), 'main');
+    writeFileSync(join(sibling, 'src', 'feature-only.ts'), 'feature');
+    writeFileSync(join(secret, 'key.txt'), 'secret');
+    Object.assign(harness.ctx._session, {
+      workingDir: repo,
+      liveWorktree: { name: 'myapp-feature', path: sibling, outside: true },
+    });
+  });
+
+  afterEach(async () => {
+    await harness.app.close();
+    rmSync(base, { recursive: true, force: true });
+    rmSync(SETTINGS_PATH, { force: true });
+  });
+
+  describe('GET .../files', () => {
+    it('lists the worktree with absolute paths', async () => {
+      const data = await list('&root=live-any');
+      expect(data.root).toBe(sibling);
+      expect(data.worktree).toEqual({ name: 'myapp-feature', path: sibling, outside: true });
+      expect(data.tree[0].path).toBe(join(sibling, 'src'));
+      expect(data.tree[0].children[0].path).toBe(join(sibling, 'src', 'feature-only.ts'));
+    });
+
+    it('searches the worktree, matching on paths relative to it and answering absolute ones', async () => {
+      const data = await list(`&root=live-any&q=${encodeURIComponent('src/feature*')}`);
+      expect(data.matches.map((m: { path: string }) => m.path)).toEqual([join(sibling, 'src', 'feature-only.ts')]);
+    });
+
+    it('keeps walking the session folder, with relative paths, for root=live', async () => {
+      const data = await list('&root=live');
+      expect(data.root).toBe(repo);
+      expect(data.worktree).toBeUndefined();
+      expect(data.tree[0].children[0].path).toBe('src/main-only.ts');
+      expect(JSON.stringify(data.tree)).not.toContain('feature-only.ts');
+    });
+
+    it('keeps the session folder, with relative paths, without the parameter', async () => {
+      const data = await list();
+      expect(data.root).toBe(repo);
+      expect(data.worktree).toBeUndefined();
+      expect(data.tree[0].children[0].path).toBe('src/main-only.ts');
+    });
+
+    it('falls back to the session folder once a symlink has taken the worktree folder’s place', async () => {
+      renameSync(sibling, `${sibling}-moved`);
+      symlinkSync(secret, sibling);
+      const data = await list('&root=live-any');
+      expect(data.root).toBe(repo);
+      expect(JSON.stringify(data.tree)).not.toContain('key.txt');
+    });
+  });
+
+  describe('GET .../file-content', () => {
+    it('serves an absolute path inside the worktree', async () => {
+      const res = await readContent(join(sibling, 'src', 'feature-only.ts'));
+      expect(res.statusCode).toBe(200);
+      expect(JSON.stringify(res.json())).toContain('feature');
+    });
+
+    it('refuses a sensitive file in the worktree on file-content and file-raw, and serves its neighbours', async () => {
+      writeFileSync(join(sibling, '.env'), 'TOKEN=abc');
+      mkdirSync(join(sibling, '.aws'));
+      writeFileSync(join(sibling, '.aws', 'credentials'), 'aws_secret=abc');
+      writeFileSync(join(sibling, 'plain.ts'), 'plain');
+      for (const blocked of [join(sibling, '.env'), join(sibling, '.aws', 'credentials')]) {
+        const content = await readContent(blocked);
+        expect(content.json().success).toBe(false);
+        expect(content.body).not.toContain('abc');
+        const raw = await harness.app.inject({
+          method: 'GET',
+          url: sessionUrl(`file-raw?path=${encodeURIComponent(blocked)}`),
+        });
+        expect(raw.statusCode).not.toBe(200);
+        expect(raw.body).not.toContain('abc');
+      }
+      const plain = await readContent(join(sibling, 'plain.ts'));
+      expect(plain.json().success).toBe(true);
+      const plainRaw = await harness.app.inject({
+        method: 'GET',
+        url: sessionUrl(`file-raw?path=${encodeURIComponent(join(sibling, 'plain.ts'))}`),
+      });
+      expect(plainRaw.statusCode).toBe(200);
+      expect(plainRaw.body).toBe('plain');
+    });
+
+    it('still resolves a relative path against the session folder only', async () => {
+      expect((await readContent('src/main-only.ts')).statusCode).toBe(200);
+      const escaped = await readContent('../myapp-feature/src/feature-only.ts');
+      expect(JSON.stringify(escaped.json())).not.toContain('"feature"');
+      expect(escaped.json().success).toBe(false);
+    });
+
+    it('refuses a symlink in the worktree that leads out of it', async () => {
+      symlinkSync(join(secret, 'key.txt'), join(sibling, 'leak.txt'));
+      const res = await readContent(join(sibling, 'leak.txt'));
+      expect(res.json().success).toBe(false);
+      expect(JSON.stringify(res.json())).not.toContain('"secret"');
+    });
+
+    it('serves a symlink in the worktree that leads into the session folder', async () => {
+      symlinkSync(join(repo, 'src', 'main-only.ts'), join(sibling, 'main-link.ts'));
+      const res = await readContent(join(sibling, 'main-link.ts'));
+      expect(res.statusCode).toBe(200);
+      expect(res.json().success).toBe(true);
+    });
+
+    it('serves nothing from the folder once a symlink has taken its place', async () => {
+      renameSync(sibling, `${sibling}-moved`);
+      symlinkSync(secret, sibling);
+      const res = await readContent(join(sibling, 'key.txt'));
+      expect(res.json().success).toBe(false);
+    });
+
+    it('serves nothing outside the session folder once the worktree is not outside', async () => {
+      Object.assign(harness.ctx._session, { liveWorktree: { name: 'myapp-feature', path: sibling } });
+      const res = await readContent(join(sibling, 'src', 'feature-only.ts'));
+      expect(res.json().success).toBe(false);
+    });
+  });
+
+  describe('file-raw, download and edit', () => {
+    it('streams an absolute path inside the worktree from file-raw and download', async () => {
+      const target = join(sibling, 'src', 'feature-only.ts');
+      const raw = await harness.app.inject({
+        method: 'GET',
+        url: sessionUrl(`file-raw?path=${encodeURIComponent(target)}`),
+      });
+      expect(raw.statusCode).toBe(200);
+      expect(raw.body).toBe('feature');
+      const download = await harness.app.inject({
+        method: 'GET',
+        url: `/api/download?sessionId=${harness.ctx._sessionId}&path=${encodeURIComponent(target)}`,
+      });
+      expect(download.statusCode).toBe(200);
+      expect(download.body).toBe('feature');
+    });
+
+    it('edits a file inside the worktree in place', async () => {
+      const target = join(sibling, 'notes.md');
+      writeFileSync(target, 'before\n');
+      const res = await harness.app.inject({
+        method: 'PUT',
+        url: sessionUrl('file-content'),
+        payload: { path: target, content: 'after\n', baseHash: sha256('before\n') },
+      });
+      expect(res.statusCode).toBe(200);
+      expect(readFileSync(target, 'utf8')).toBe('after\n');
+    });
+
+    it('refuses to edit through a symlink that leads out of the worktree', async () => {
+      symlinkSync(join(secret, 'key.txt'), join(sibling, 'leak.md'));
+      const res = await harness.app.inject({
+        method: 'PUT',
+        url: sessionUrl('file-content'),
+        payload: { path: join(sibling, 'leak.md'), content: 'pwned', baseHash: sha256('secret') },
+      });
+      expect(res.statusCode).toBe(404);
+      expect(readFileSync(join(secret, 'key.txt'), 'utf8')).toBe('secret');
+    });
+  });
+
+  describe('file-preview and file-thumbnail', () => {
+    const preview = (path: string) =>
+      harness.app.inject({ method: 'GET', url: sessionUrl(`file-preview?path=${encodeURIComponent(path)}`) });
+    const thumbnail = (path: string) =>
+      harness.app.inject({ method: 'GET', url: sessionUrl(`file-thumbnail?path=${encodeURIComponent(path)}`) });
+
+    beforeEach(() => {
+      vi.mocked(generateFirstPageThumbnail).mockClear();
+      writeFileSync(join(sibling, 'doc.pdf'), '%PDF-1.4 fake');
+      writeFileSync(join(sibling, 'pic.png'), 'png');
+    });
+
+    it('answers file-preview for an absolute path inside the worktree', async () => {
+      const res = await preview(join(sibling, 'doc.pdf'));
+      expect(res.statusCode).toBeGreaterThanOrEqual(300);
+      expect(res.statusCode).toBeLessThan(400);
+      expect(res.headers.location).toContain('/file-raw?path=');
+    });
+
+    it('serves file-thumbnail for an absolute path inside the worktree', async () => {
+      const res = await thumbnail(join(sibling, 'pic.png'));
+      expect(res.statusCode).toBe(200);
+      expect(res.headers['content-type']).toContain('image/png');
+      expect(generateFirstPageThumbnail).toHaveBeenCalled();
+    });
+
+    it('refuses both once a symlink has taken the worktree folder’s place', async () => {
+      writeFileSync(join(secret, 'doc.pdf'), '%PDF-1.4 fake');
+      writeFileSync(join(secret, 'pic.png'), 'png');
+      renameSync(sibling, `${sibling}-moved`);
+      symlinkSync(secret, sibling);
+      expect((await preview(join(sibling, 'doc.pdf'))).statusCode).toBe(404);
+      expect((await thumbnail(join(sibling, 'pic.png'))).statusCode).toBe(404);
+      expect(generateFirstPageThumbnail).not.toHaveBeenCalled();
+    });
+  });
+  describe('the attachment guard, judged again on every request', () => {
+    const target = () => join(sibling, 'src', 'feature-only.ts');
+    const writeSettings = (settings: Record<string, unknown>) => {
+      mkdirSync(dirname(SETTINGS_PATH), { recursive: true });
+      writeFileSync(SETTINGS_PATH, JSON.stringify(settings));
+    };
+    const get = (route: string) =>
+      harness.app.inject({ method: 'GET', url: sessionUrl(`${route}?path=${encodeURIComponent(target())}`) });
+
+    it('serves the worktree while no guard rule applies', async () => {
+      writeSettings({});
+      expect((await get('file-raw')).statusCode).toBe(200);
+    });
+
+    it.each([
+      ['workspace confinement is turned on', () => ({ attachmentConfineToWorkspace: true })],
+      ['the worktree’s parent folder is blocked', () => ({ attachmentBlockedPaths: [base] })],
+    ])('stops serving it once %s', async (_label, settings) => {
+      writeSettings(settings());
+
+      const content = await get('file-content');
+      expect(content.json().success).toBe(false);
+      expect(content.body).not.toContain('feature');
+      expect((await get('file-raw')).statusCode).toBe(404);
+
+      const before = readFileSync(target(), 'utf8');
+      const put = await harness.app.inject({
+        method: 'PUT',
+        url: sessionUrl('file-content'),
+        payload: { path: target(), content: 'changed', baseHash: sha256(before) },
+      });
+      expect(put.statusCode).toBe(404);
+      expect(readFileSync(target(), 'utf8')).toBe(before);
+
+      const download = await harness.app.inject({
+        method: 'GET',
+        url: `/api/download?sessionId=${harness.ctx._sessionId}&path=${encodeURIComponent(target())}`,
+      });
+      expect(download.statusCode).toBe(404);
+
+      // The listing walks the session folder, and keeps reporting the worktree so the panel settles.
+      const data = await list('&root=live-any');
+      expect(data.root).toBe(repo);
+      expect(data.tree[0].children[0].path).toBe('src/main-only.ts');
+      expect(data.worktree).toEqual({ name: 'myapp-feature', path: sibling, outside: true });
+    });
+  });
+});

test/routes/html-view-routes.test.ts

@@ -34,6 +34,9 @@ describe('html-view routes', () => {
     writeFileSync(join(root, 'outside.txt'), 'outside');
     symlinkSync(join(root, 'outside.txt'), join(workspace, 'escape.txt'));
 
+    mkdirSync(join(root, 'sibling-feature'));
+    writeFileSync(join(root, 'sibling-feature', 'report.html'), '<p>feature</p>');
+
     harness = await createRouteTestHarness(registerHtmlViewRoutes);
     sid = harness.ctx._sessionId as string;
     (harness.ctx.sessions.get(sid) as { workingDir: string }).workingDir = workspace;
@@ -270,6 +273,64 @@ describe('html-view routes', () => {
     });
   });
 
+  describe('in a worktree outside the workspace (#765 follow-up)', () => {
+    let sibling: string;
+    const saved = {
+      confine: process.env.CODEMAN_ATTACHMENT_CONFINE,
+      blocked: process.env.CODEMAN_ATTACHMENT_BLOCKED_PATHS,
+    };
+
+    beforeEach(() => {
+      sibling = realpathSync(join(root, 'sibling-feature'));
+      Object.assign(harness.ctx.sessions.get(sid) as object, {
+        liveWorktree: { name: 'sibling-feature', path: sibling, outside: true },
+      });
+    });
+
+    afterEach(() => {
+      for (const [key, value] of [
+        ['CODEMAN_ATTACHMENT_CONFINE', saved.confine],
+        ['CODEMAN_ATTACHMENT_BLOCKED_PATHS', saved.blocked],
+      ] as const) {
+        if (value === undefined) delete process.env[key];
+        else process.env[key] = value;
+      }
+    });
+
+    it('renders a page from the worktree, minted as outside the workspace', async () => {
+      const res = await open(join(sibling, 'report.html'));
+      expect(res.statusCode).toBe(200);
+      const url = JSON.parse(res.body).data.url as string;
+      const page = await harness.app.inject({ method: 'GET', url });
+      expect(page.statusCode).toBe(200);
+      expect(page.body).toBe('<p>feature</p>');
+      // Minted as outside the workspace, so the serve route's per-request confinement check covers it.
+      expect(htmlViewCapabilities.resolve(capabilityFromHtmlViewPath(url) as string)?.outsideWorkspace).toBe(true);
+    });
+
+    it('answers to the attachment guard: confinement on, or a blocked tree', async () => {
+      const res = await open(join(sibling, 'report.html'));
+      const url = JSON.parse(res.body).data.url as string;
+
+      process.env.CODEMAN_ATTACHMENT_CONFINE = '1';
+      expect((await open(join(sibling, 'report.html'))).statusCode).toBe(403);
+      // A page minted before confinement was switched on stops serving too.
+      expect((await harness.app.inject({ method: 'GET', url })).statusCode).toBe(404);
+      delete process.env.CODEMAN_ATTACHMENT_CONFINE;
+
+      process.env.CODEMAN_ATTACHMENT_BLOCKED_PATHS = sibling;
+      expect((await open(join(sibling, 'report.html'))).statusCode).toBe(403);
+    });
+
+    it('leaves a path outside both roots as it was', async () => {
+      mkdirSync(join(root, 'reports'));
+      writeFileSync(join(root, 'reports', 'report.html'), '<p>report</p>');
+      expect((await open(join(root, 'reports', 'report.html'))).statusCode).toBe(200);
+      process.env.CODEMAN_ATTACHMENT_CONFINE = '1';
+      expect((await open(join(root, 'reports', 'report.html'))).statusCode).toBe(403);
+    });
+  });
+
   it('refuses an HTML file inside a hidden directory, in or out of the workspace', async () => {
     mkdirSync(join(workspace, '.cache'));
     writeFileSync(join(workspace, '.cache', 'r.html'), '<p>r</p>');

test/terminal-cell-wrapped-paths.test.ts

@@ -251,6 +251,7 @@ describe('terminal link provider with cell-wrapped paths', () => {
       _openTerminalUrl: proto._openTerminalUrl,
       _resolveLinkedFilePath: proto._resolveLinkedFilePath,
       _isExternalPreviewPath: () => false,
+      _isOutsideWorktreePath: () => false,
       registerFilePathLinkProvider: proto.registerFilePathLinkProvider,
     };
     app.registerFilePathLinkProvider.call(app);

test/terminal-link-provider-target.test.ts

@@ -83,6 +83,7 @@ function makeApp() {
   app.openFilePreview = vi.fn();
   app.openLogViewerWindow = vi.fn();
   app._isExternalPreviewPath = () => false;
+  app._isOutsideWorktreePath = () => false;
   return app;
 }
 

test/terminal-touch-tap.test.ts

@@ -964,6 +964,7 @@ describe('terminal link tap', () => {
     app.openFilePreview = vi.fn();
     app.openLogViewerWindow = vi.fn();
     app._isExternalPreviewPath = () => false;
+    app._isOutsideWorktreePath = () => false;
     windowRef.open = vi.fn();
     app.registerFilePathLinkProvider();
     return { app, windowRef, sent };
@@ -1421,6 +1422,7 @@ describe('terminal wrapped-line handling', () => {
     app.openFilePreview = vi.fn();
     app.openLogViewerWindow = vi.fn();
     app._isExternalPreviewPath = () => false;
+    app._isOutsideWorktreePath = () => false;
     windowRef.open = vi.fn();
     app.registerFilePathLinkProvider();
     return { app, windowRef, select: app.terminal.select as ReturnType<typeof vi.fn> };